Skip to main content
Version: 🚧 Canary

🍪 Cookie Utilities

The Nodeblocks SDK provides helpers for cookie-based authentication and Set-Cookie option resolution. These utilities integrate with the authentication service when authMode is 'cookie'.

🎯 Overview​

Cookie utilities live under the utils namespace and are used at cookie-setting time (login, refresh, logout) and at compose/request time (branching between cookie and bearer auth handlers).

import { utils } from '@nodeblocks/backend-sdk';

const {
  DEFAULT_COOKIE_OPTS,
  withCookieOptDefaults,
  isCookieMode,
  whenCookieAuth,
} = utils;

The module exports five symbols: CookieOptions, DEFAULT_COOKIE_OPTS, withCookieOptDefaults, isCookieMode, and whenCookieAuth.

For service-level configuration (authMode, token sign options), see Authentication Service.

📋 Types and Defaults​

CookieOptions​

TypeScript interface for cookie configuration:

interface CookieOptions {
  domain?: string;
  httpOnly?: boolean;
  maxAge?: number;
  path?: string;
  sameSite?: 'strict' | 'lax' | 'none';
  secure?: boolean;
}

Secure defaults applied before user overrides:

const DEFAULT_COOKIE_OPTS: CookieOptions = {
  httpOnly: true,
  path: '/',
  sameSite: 'strict',
  secure: true,
};

🔧 Set-Cookie Option Resolution​

withCookieOptDefaults​

Resolves final Set-Cookie options for an access or refresh token cookie.

import { utils } from '@nodeblocks/backend-sdk';

const { withCookieOptDefaults } = utils;

const accessCookieOpts = withCookieOptDefaults(context, 'access');
const refreshCookieOpts = withCookieOptDefaults(context, 'refresh');

Parameters:

  • context: ServiceContext — request/service context with configuration
  • tokenType: 'access' | 'refresh' — selects which token sign options to read for maxAge

Merge order (low → high precedence):

  1. DEFAULT_COOKIE_OPTS
  2. User cookieOpts from context.cookieOpts or context.configuration.cookieOpts
  3. Computed maxAge from the matching token's expiresIn (accessTokenSignOptions or refreshTokenSignOptions), converted via deriveCookieMaxAge

When a token expiresIn is configured, the computed maxAge overrides any maxAge the user set in cookieOpts.

Important: Call this helper only at cookie-setting time (e.g. setResponseCookie, logout). Compose-time predicates must read raw authMode / cookieOpts configuration — never a value that has passed through this helper.

🔀 Auth Mode Branching​

isCookieMode​

Predicate for compose-time / request-time checks:

import { utils } from '@nodeblocks/backend-sdk';

const { isCookieMode } = utils;

isCookieMode('cookie');  // true
isCookieMode('bearer');  // false

Equivalent to value === 'cookie'.

whenCookieAuth​

Runs a cookie handler when cookie auth is active; otherwise runs a bearer handler (defaults to pass-through).

import { utils } from '@nodeblocks/backend-sdk';

const { getBearerTokenInfo, getCookieTokenInfo, whenCookieAuth } = utils;

const authenticate = whenCookieAuth(
  getCookieTokenInfo,
  getBearerTokenInfo
);

// Use `authenticate` as an async route handler, or compose it with
// subsequent handler steps.
const handler = authenticate;

Cookie mode detection: Reads context.authMode or context.configuration.authMode at request time.

Default bearer handler: When no bearer handler is supplied, the default pass-through returns ok(payload) unchanged.

Parameters:

  • cookieFn: Handler to run when cookie auth is active
  • bearerFn: Optional handler for bearer mode (default: pass-through)

📐 Best Practices​

// ✅ Good: resolve when setting cookies
response.cookie('accessToken', token, withCookieOptDefaults(context, 'access'));

// ❌ Avoid: using withCookieOptDefaults for auth-mode predicates
const isCookie = withCookieOptDefaults(context, 'access'); // wrong helper

2. Branch auth handlers with whenCookieAuth​

// ✅ Good: single pipeline, mode-aware auth
const authHandler = whenCookieAuth(getCookieTokenInfo, getBearerTokenInfo);

See Authentication Utilities for token validation helpers used by cookie and bearer paths.

🔗 See Also​