Skip to main content

Cookie Plugin

Provides comprehensive cookie parsing and management. Automatically parses incoming cookies and provides convenient methods for setting and clearing cookies on responses.

Quick Start​

import { Server } from 'balda-js';

const server = new Server({
  plugins: {
    cookie: {
      secret: 'your-secret-key'
    }
  }
});

Configuration​

cookie: {
  secret: 'your-secret-key',     // Required for signed cookies
  parse: true,                   // Enable cookie parsing (default: true)
  sign: false,                   // Enable cookie signing (default: false)
  defaults: {
    path: '/',                   // Cookie path (default: '/')
    httpOnly: true,              // HttpOnly flag (default: true)
    secure: false,               // Secure flag (default: false)
    sameSite: 'Lax'             // SameSite attribute (default: 'Lax')
  }
}

Production Configuration​

cookie: {
  secret: process.env.COOKIE_SECRET,
  sign: true,
  defaults: {
    httpOnly: true,
    secure: true,            // HTTPS only
    sameSite: 'Strict',
    domain: '.myapp.com'
  }
}

Usage​

Setting Cookies​

@controller('/auth')
export class AuthController {
  @post('/login')
  async login(req: Request, res: Response) {
    const user = await validateUser(req.body.username, req.body.password);

    if (user) {
      // Set cookie
      res.cookie('sessionId', user.sessionId, {
        maxAge: 24 * 60 * 60 * 1000, // 24 hours
        httpOnly: true,
        secure: true
      });

      res.json({ message: 'Login successful' });
    }
  }

  @post('/logout')
  async logout(req: Request, res: Response) {
    // Clear cookie
    res.clearCookie('sessionId');
    res.json({ message: 'Logout successful' });
  }
}

Reading Cookies​

@get('/profile')
async getProfile(req: Request, res: Response) {
  const sessionId = req.cookies.sessionId;
  const theme = req.cookies.theme || 'light';

  if (!sessionId) {
    return res.unauthorized({ error: 'No session found' });
  }

  const user = await getUserBySession(sessionId);
  res.json({ user, theme });
}

Setting Multiple Cookies​

@post('/preferences')
async setPreferences(req: Request, res: Response) {
  const { theme, language, timezone } = req.body;

  res
    .cookie('theme', theme, { maxAge: 365 * 24 * 60 * 60 * 1000 })
    .cookie('language', language, { maxAge: 365 * 24 * 60 * 60 * 1000 })
    .cookie('timezone', timezone, { maxAge: 365 * 24 * 60 * 60 * 1000 })
    .json({ message: 'Preferences updated' });
}

maxAge​

Cookie expiration in milliseconds:

res.cookie('name', 'value', {
  maxAge: 24 * 60 * 60 * 1000  // 24 hours
});

httpOnly​

Prevent JavaScript access (recommended for security):

res.cookie('sessionId', value, {
  httpOnly: true  // Cannot be accessed via JavaScript
});

secure​

Only send over HTTPS:

res.cookie('sessionId', value, {
  secure: true  // HTTPS only
});

sameSite​

CSRF protection:

res.cookie('name', value, {
  sameSite: 'Strict'  // or 'Lax' or 'None'
});

domain​

Cookie domain:

res.cookie('name', value, {
  domain: '.myapp.com'  // Works for all subdomains
});

path​

Cookie path:

res.cookie('name', value, {
  path: '/api'  // Only sent to /api routes
});

Signed Cookies​

Enable signing for tamper-proof cookies:

// Configuration
cookie: {
  secret: 'your-secret-key',
  sign: true
}

// Set signed cookie
res.cookie('userId', user.id, {
  signed: true,
  httpOnly: true
});

// Read signed cookie
const userId = req.signedCookies.userId;

Security Best Practices​

Session Cookies​

res.cookie('sessionId', sessionId, {
  httpOnly: true,        // Prevent XSS
  secure: true,          // HTTPS only
  sameSite: 'Strict',   // Prevent CSRF
  maxAge: 24 * 60 * 60 * 1000
});

Authentication Tokens​

res.cookie('authToken', token, {
  httpOnly: true,
  secure: true,
  sameSite: 'Strict',
  signed: true          // Prevent tampering
});

User Preferences​

res.cookie('theme', 'dark', {
  httpOnly: false,       // Allow JavaScript access
  secure: true,
  sameSite: 'Lax',
  maxAge: 365 * 24 * 60 * 60 * 1000  // 1 year
});

Environment-Based Configuration​

const isProduction = process.env.NODE_ENV === 'production';

const server = new Server({
  plugins: {
    cookie: {
      secret: process.env.COOKIE_SECRET,
      sign: isProduction,
      defaults: {
        httpOnly: true,
        secure: isProduction,
        sameSite: isProduction ? 'Strict' : 'Lax'
      }
    }
  }
});

Common Patterns​

Session Management​

cookie: {
  secret: process.env.SESSION_SECRET,
  sign: true,
  defaults: {
    httpOnly: true,
    secure: true,
    sameSite: 'Strict',
    maxAge: 24 * 60 * 60 * 1000
  }
}

Remember Me​

res.cookie('rememberMe', token, {
  httpOnly: true,
  secure: true,
  sameSite: 'Strict',
  maxAge: 30 * 24 * 60 * 60 * 1000  // 30 days
});

Analytics Tracking​

res.cookie('tracking', trackingId, {
  httpOnly: false,
  secure: true,
  sameSite: 'Lax',
  maxAge: 365 * 24 * 60 * 60 * 1000
});