Implementation methods for Cookie and Session management in Koa

Koa's Cookie and Session management are foundational features for building web applications. Koa core provides Cookie operations, while Session needs to be implemented through middleware.

1. Cookie Operations:

Koa core has built-in Cookie functionality, operated through the ctx.cookies object.

Setting Cookie:

javascript
app.use(async (ctx) => {
  // Basic setting
  ctx.cookies.set('name', 'value');
  
  // Setting with options
  ctx.cookies.set('username', 'john', {
    maxAge: 3600000,        // Expiration (milliseconds)
    expires: new Date('2025-12-31'), // Expiration date
    path: '/',              // Path
    domain: '.example.com', // Domain
    secure: true,           // HTTPS only
    httpOnly: true,         // HTTP only, prevent XSS
    sameSite: 'strict',     // CSRF protection
    signed: true            // Signed cookie
  });
  
  ctx.body = 'Cookie set';
});

Getting Cookie:

javascript
app.use(async (ctx) => {
  const username = ctx.cookies.get('username');
  ctx.body = `Hello ${username}`;
});

Deleting Cookie:

javascript
app.use(async (ctx) => {
  ctx.cookies.set('username', null, { 
    maxAge: 0,
    path: '/' 
  });
  ctx.body = 'Cookie deleted';
});

2. Session Management:

Use koa-session middleware to implement Session functionality.

Install:

bash
npm install koa-session

Basic configuration:

javascript
const session = require('koa-session');

const sessionConfig = {
  key: 'koa.sess',          // Cookie name
  maxAge: 86400000,         // Expiration (milliseconds)
  autoCommit: true,         // Auto commit
  overwrite: true,          // Overwrite
  httpOnly: true,           // HTTP only
  signed: true,             // Signed
  rolling: false,           // Update expiration on each request
  renew: false,             // Auto renew when near expiration
  secure: false,            // HTTPS only
  sameSite: null,           // SameSite policy
};

app.keys = ['your-secret-key']; // Must set for signing
app.use(session(sessionConfig, app));

Session usage:

javascript
// Set Session
app.use(async (ctx) => {
  if (ctx.path === '/login') {
    ctx.session.user = {
      id: 1,
      name: 'John',
      role: 'admin'
    };
    ctx.body = 'Logged in';
  }
});

// Get Session
app.use(async (ctx) => {
  if (ctx.path === '/profile') {
    const user = ctx.session.user;
    if (user) {
      ctx.body = `Welcome ${user.name}`;
    } else {
      ctx.throw(401, 'Not logged in');
    }
  }
});

// Delete Session
app.use(async (ctx) => {
  if (ctx.path === '/logout') {
    ctx.session = null;
    ctx.body = 'Logged out';
  }
});

3. Redis Session Storage:

For production, it's recommended to use Redis for Session storage.

Install:

bash
npm install koa-session koa-redis

Configure Redis Session:

javascript
const session = require('koa-session');
const RedisStore = require('koa-redis');

const redisStore = RedisStore({
  host: 'localhost',
  port: 6379,
  password: 'your-password',
  db: 0
});

const sessionConfig = {
  store: redisStore,
  key: 'koa.sess',
  maxAge: 86400000,
  httpOnly: true,
  signed: true
};

app.keys = ['your-secret-key'];
app.use(session(sessionConfig, app));

4. Authentication middleware example:

javascript
// Authentication middleware
async function authMiddleware(ctx, next) {
  if (!ctx.session.user) {
    ctx.throw(401, 'Unauthorized');
  }
  await next();
}

// Use authentication middleware
router.get('/protected', authMiddleware, async (ctx) => {
  ctx.body = `Welcome ${ctx.session.user.name}`;
});

5. JWT Token Authentication:

Use jsonwebtoken and koa-jwt to implement JWT authentication.

Install:

bash
npm install jsonwebtoken koa-jwt

Generate Token:

javascript
const jwt = require('jsonwebtoken');

app.use(async (ctx) => {
  if (ctx.path === '/login') {
    const { username, password } = ctx.request.body;
    
    // Verify user
    const user = await authenticateUser(username, password);
    
    // Generate Token
    const token = jwt.sign(
      { id: user.id, name: user.name },
      'your-secret-key',
      { expiresIn: '24h' }
    );
    
    ctx.body = { token };
  }
});

Verify Token:

javascript
const jwt = require('koa-jwt');

app.use(jwt({
  secret: 'your-secret-key'
}).unless({
  path: [/^\/public/, '/login', '/register']
}));

// Access user info
app.use(async (ctx) => {
  ctx.body = ctx.state.user;
});

6. Complete authentication flow example:

javascript
const Koa = require('koa');
const Router = require('@koa/router');
const session = require('koa-session');
const jwt = require('jsonwebtoken');
const koaJwt = require('koa-jwt');

const app = new Koa();
const router = new Router();

// Session configuration
app.keys = ['secret-key'];
app.use(session({
  key: 'koa.sess',
  maxAge: 86400000
}, app));

// JWT middleware
app.use(koaJwt({
  secret: 'jwt-secret'
}).unless({
  path: [/^\/api\/auth/]
}));

// Login route
router.post('/api/auth/login', async (ctx) => {
  const { username, password } = ctx.request.body;
  
  // Verify user
  const user = await User.findOne({ username });
  if (!user || !await user.comparePassword(password)) {
    ctx.throw(401, 'Invalid credentials');
  }
  
  // Set Session
  ctx.session.user = {
    id: user.id,
    name: user.name
  };
  
  // Generate JWT Token
  const token = jwt.sign(
    { id: user.id, name: user.name },
    'jwt-secret',
    { expiresIn: '24h' }
  );
  
  ctx.body = {
    token,
    user: {
      id: user.id,
      name: user.name
    }
  };
});

// Protected route
router.get('/api/user/profile', async (ctx) => {
  ctx.body = ctx.state.user;
});

// Logout route
router.post('/api/auth/logout', async (ctx) => {
  ctx.session = null;
  ctx.body = { message: 'Logged out' };
});

app.use(router.routes());

7. Security best practices:

1. Cookie security:

   • Always set httpOnly: true to prevent XSS
   • Use secure: true for HTTPS only in production
   • Set sameSite: 'strict' to prevent CSRF
   • Use signed cookies to prevent tampering

2. Session security:

   • Use strong random keys
   • Set reasonable expiration time
   • Use Redis storage in production
   • Clear session on logout

3. JWT security:

   • Use strong secrets
   • Set reasonable expiration time
   • Use HTTPS for transmission
   • Implement token refresh mechanism

4. Other security measures:

   • Limit login attempts
   • Implement password strength validation
   • Log authentication events
   • Regularly update secrets