Cookies

The IAM service uses three cookies. It sets two of them session and iat, and reads one that it does not own, canary_id, which is set by the bot-detector. Every cookie the service writes is httpOnly, secure, and sameSite: strict. No cookie is ever accessible to client side JavaScript.

The session cookie carries the raw refresh token. The iat cookie carries the millisecond timestamp of when the credentials were last issued. Together, they let the client send refresh requests without storing sensitive values in localStorage or sessionStorage. The canary_id cookie is a device fingerprint created by the bot-detector and is consumed by the IAM service during signup, login, OAuth, and anomaly detection flows.

Cookie Conventions

session Cookie

The session cookie is the most security-critical cookie in the system. It contains the raw, unhashed refresh token. The server stores only a SHA-256 hash of this value in the refresh_tokens table. Anyone who possesses the raw cookie value can request a new access token.

Options

When It Is Set

The session cookie is written in every flow that issues a new refresh token:

In every case, the pattern is the same:

makeCookie(res, 'session', newRefresh.raw, {
  httpOnly: true,
  sameSite: 'strict',
  secure: true,
  domain: jwt.refresh_tokens.domain,
  path: '/',
  expires: newRefresh.expiresAt
})

When It Is Cleared

The session cookie is cleared in two scenarios:

iat Cookie

The iat (issued-at) cookie records the moment when the most recent token pair (access + refresh) was issued. The value is Date.now().toString(), a millisecond Unix timestamp as a string.

Options

Purpose

The iat cookie helps upstream services determine how recently credentials were issued without decoding the access token JWT. A BFF can read the iat value to decide whether a proactive rotation is needed before the access token expires.

When It Is Set

The iat cookie is always set alongside the session cookie. Every flow listed in the session cookie table above also sets iat:

makeCookie(res, 'iat', Date.now().toString(), {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  path: '/',
  expires: newRefresh.expiresAt
})

When It Is Cleared

The iat cookie is cleared alongside session during logout and session expiry. The clearCookie call uses the same httpOnly, sameSite, secure, and path options. For logout specifically, the domain is explicitly set to jwt.refresh_tokens.domain in the clear call to ensure the deletion reaches the correct scope.

canary_id Cookie - Read-Only

The IAM service reads but never writes the canary_id cookie. This cookie is set by the bot-detector middleware, which runs before the IAM service's routes.

How the IAM Service Uses It

makeCookie Helper

All cookie operations go through the makeCookie utility function. It wraps res.cookie() with automatic prefix enforcement for security-hardened cookie names.

function makeCookie(
  res: Response,
  name: string,
  value: string,
  options: CookieOptions
): void

Prefix Enforcement

The function checks the cookie name for two standard security prefixes and enforces the corresponding browser requirements:

Currently, the IAM service uses plain cookie names (session, iat) without a prefix. The prefix enforcement exists for forward compatibility if the service adopts __Host-session or __Secure-session naming in the future. The enforcement logic runs on every call, so switching to prefixed names requires only changing the name string; the security constraints apply automatically.

Cookie Middleware

cookieParser

The service mounts cookieParser() as Express middleware. It runs after express.json() and before any route handler:

httpLogger, helmet, headers, validateIp, hmacAuth?, json, cookieParser, routes

cookieParser parses the Cookie header and populates req.cookies as a key-value object. Every route handler downstream can access req.cookies.session, req.cookies.iat, and req.cookies.canary_id directly.

requireRefreshToken

A middleware guard that checks for the session cookie before allowing the request to proceed. If req.cookies.session is missing or empty, the middleware returns 401 immediately. Used on routes that consume the refresh token:

• POST /auth/user/refresh-session rotation
• POST /auth/logout logout

acceptCookieOnly

A stricter middleware guard for endpoints where the cookie should be the only input. It rejects requests that include a body, query parameters, or a Content-Type header. Exported from @riavzon/auth as acceptCookieOnly.

The acceptCookieOnly middleware performs these checks:

Cookie Lifecycle Summary

The diagram below shows when each cookie is created and destroyed across the authentication lifecycle:

Every creation event sets both session and iat together. They are always written as a pair, with the same expiry. The canary_id cookie is independent of the IAM session lifecycle; it persists across login/logout cycles and is managed entirely by the bot-detector.

Security Properties