@bhooai/nexus-auth 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @bhooai/nexus-auth
+
+One cohesive security + identity unit: CORS, CSRF, security headers, rate
+limiting, password hashing, JWT auth, sessions, RBAC, and Google + Facebook OAuth2.
+
+## Exports
+
+- **CORS** — `cors({ origin, credentials })` with preflight short-circuit and `Vary: Origin`.
+- **CSRF** — `csrf({ trustedOrigins })` double-submit token (HttpOnly `nexus_csrf`
+  cookie + `x-csrf-token` header); `issueCsrfToken(ctx, { trustedOrigins })`. Safe
+  methods issue a fresh token; unsafe methods run `checkOrigin` + double-submit.
+  Applies to **all** unsafe methods (incl. `POST /graphql` and `/payments`) and to
+  the **WS upgrade**.
+- **headers** — `securityHeaders()` (helmet-equivalent).
+- **rateLimit** — `rateLimit({ windowMs, max })` (in-memory; Redis backend in `nexus-cache`).
+- **jwt / session / password** — `AuthService`, `MemorySessionStore`,
+  `hashPassword`/`verifyPassword`, access + refresh token rotation.
+- **rbac** — role checks.
+- **oauth** — `buildGoogleAuthUrl` (with PKCE), `exchangeGoogleCode`,
+  `fetchGoogleProfile`, and the Facebook equivalents.
+- **middleware** — `authToken(service, { cookieName, allowCookie, required })`,
+  `requireAuth()`, `setAuthCookies`, `clearAuthCookies`.
+
+> `authToken`'s first argument is the `AuthService` instance; options are the 2nd.
+
+## CSRF note
+
+With a non-empty `trustedOrigins`, every unsafe request **must** carry an `Origin`
+header that exactly matches a trusted origin (including the port) **and** a
+matching `x-csrf-token`. API clients that don't send `Origin` (e.g. Playwright's
+`APIRequestContext`) must add it explicitly — see the e2e/integration tests.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@bhooai/nexus-auth",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0",
+    "bcryptjs": "^2.4.3",
+    "jose": "^5.9.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,116 @@
+import { randomBytes } from 'node:crypto';
+import { signAccessToken, verifyToken, type JwtOptions, type TokenPayload } from './jwt.js';
+import type { SessionStore, Session } from './session.js';
+import { AuthenticationError } from '../../nexus-core/src/index.js';
+
+export interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+  sessionId: string;
+  /** Refresh-token expiry (ms epoch). */
+  refreshExpiresAt: number;
+}
+
+export interface LoginInput {
+  userId: string;
+  roles: string[];
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * High-level auth orchestrator. The app verifies credentials (via
+ * `verifyPassword` + its user store) and calls `login()` to mint a session and
+ * token pair. Refresh tokens are rotated on every refresh and bound to a
+ * session family, so reuse of a previously-rotated token revokes the whole
+ * family (refresh-token theft detection).
+ */
+export class AuthService {
+  constructor(
+    private jwt: JwtOptions,
+    private sessions: SessionStore,
+  ) {}
+
+  /** Create a session and return an access + refresh token pair. */
+  async login(input: LoginInput): Promise<TokenPair> {
+    const session = await this.sessions.create(input.userId, input.roles, input.meta);
+    return this.mintPair(session);
+  }
+
+  /**
+   * Verify a refresh token, rotate it (new jti), and return a fresh pair.
+   * If the presented refresh token's jti no longer matches the session's
+   * current jti, the token has been reused after rotation → revoke the family.
+   */
+  async refresh(refreshToken: string): Promise<TokenPair> {
+    let payload: TokenPayload;
+    try {
+      payload = await verifyToken(refreshToken, this.jwt);
+    } catch {
+      throw new AuthenticationError('Invalid refresh token');
+    }
+    if (payload.kind !== 'refresh' || !payload.sid) {
+      throw new AuthenticationError('Not a refresh token');
+    }
+    const session = await this.sessions.get(payload.sid);
+    if (!session) throw new AuthenticationError('Session expired');
+
+    // Reuse detection: the jti on the session must match the presented token.
+    if (session.currentJti && payload.jti && session.currentJti !== payload.jti) {
+      await this.sessions.destroyFamily(session.familyId);
+      throw new AuthenticationError('Refresh token reuse detected; session revoked');
+    }
+
+    return this.mintPair(session);
+  }
+
+  /** End a single session (logout). */
+  async logout(sessionId: string): Promise<void> {
+    await this.sessions.destroy(sessionId);
+  }
+
+  /** End every session for a user (logout everywhere). */
+  async logoutAll(userId: string): Promise<void> {
+    await this.sessions.destroyAllForUser(userId);
+  }
+
+  /** Verify an access token and return its payload (for the auth middleware). */
+  async verifyAccessToken(accessToken: string): Promise<TokenPayload> {
+    try {
+      const payload = await verifyToken(accessToken, this.jwt);
+      if (payload.kind && payload.kind !== 'access') {
+        throw new AuthenticationError('Not an access token');
+      }
+      return payload;
+    } catch (e) {
+      if (e instanceof AuthenticationError) throw e;
+      throw new AuthenticationError('Invalid access token');
+    }
+  }
+
+  private async mintPair(session: Session): Promise<TokenPair> {
+    const jti = randomBytes(12).toString('base64url');
+    // Record the issued refresh jti on the session for reuse detection.
+    await this.sessions.update(session.id, { currentJti: jti });
+    const access = await signAccessToken(session.userId, session.roles, this.jwt, session.id);
+    const refresh = await this.signRefreshWithJti(session, jti);
+    const refreshExpiresAt = Date.now() + (this.jwt.refreshTtl ?? 60 * 60 * 24 * 7) * 1000;
+    return { accessToken: access, refreshToken: refresh, sessionId: session.id, refreshExpiresAt };
+  }
+
+  private async signRefreshWithJti(session: Session, jti: string): Promise<string> {
+    // Re-use the jose SignJWT path by importing here to inject jti.
+    const { SignJWT } = await import('jose');
+    const ttl = this.jwt.refreshTtl ?? 60 * 60 * 24 * 7;
+    const secret =
+      typeof this.jwt.secret === 'string' ? new TextEncoder().encode(this.jwt.secret) : this.jwt.secret;
+    const builder = new SignJWT({ kind: 'refresh', roles: session.roles, sid: session.id })
+      .setProtectedHeader({ alg: this.jwt.algorithm ?? 'HS256' })
+      .setSubject(session.userId)
+      .setJti(jti)
+      .setIssuedAt()
+      .setExpirationTime(`${ttl}s`);
+    if (this.jwt.issuer) builder.setIssuer(this.jwt.issuer);
+    if (this.jwt.audience) builder.setAudience(this.jwt.audience);
+    return builder.sign(secret);
+  }
+}

package/src/bcryptjs.d.ts

@@ -0,0 +1,10 @@
+declare module 'bcryptjs' {
+  interface Bcrypt {
+    genSalt(rounds: number): Promise<string>;
+    hash(plaintext: string, salt: string): Promise<string>;
+    compare(plaintext: string, hash: string): Promise<boolean>;
+  }
+
+  const bcrypt: Bcrypt;
+  export default bcrypt;
+}

package/src/cors.ts

@@ -0,0 +1,91 @@
+import type { Middleware } from '../../nexus-core/src/http/index.js';
+
+export interface CorsOptions {
+  /** Allowed origin(s): a string, an array, or true to reflect any origin. */
+  origin?: string | string[] | boolean;
+  /** Allowed methods. */
+  methods?: string[];
+  /** Allowed request headers. */
+  allowedHeaders?: string[];
+  /** Headers exposed to the browser. */
+  exposedHeaders?: string[];
+  /** Allow cookies / credentials. When true, origin cannot be "*". */
+  credentials?: boolean;
+  /** Preflight cache max age in seconds. */
+  maxAge?: number;
+}
+
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
+
+/**
+ * Inbuilt CORS middleware. Owns the OPTIONS preflight path entirely, sets
+ * `Vary: Origin` for correct cache behavior, and enforces the credentialed
+ * rule (no wildcard origin when credentials are enabled).
+ */
+export function cors(options: CorsOptions = {}): Middleware {
+  const opts = {
+    origin: options.origin ?? true,
+    methods: options.methods ?? DEFAULT_METHODS,
+    allowedHeaders: options.allowedHeaders,
+    exposedHeaders: options.exposedHeaders,
+    credentials: options.credentials ?? false,
+    maxAge: options.maxAge ?? 600,
+  };
+
+  return async (ctx, next) => {
+    const reqOrigin = (ctx.headers['origin'] as string) ?? '';
+    const allowedOrigin = resolveOrigin(opts.origin, reqOrigin, opts.credentials);
+
+    // Always vary by origin so caches don't leak the wrong CORS headers.
+    appendVary(ctx, 'Origin');
+
+    if (allowedOrigin) {
+      ctx.setHeader('access-control-allow-origin', allowedOrigin);
+      if (opts.credentials) ctx.setHeader('access-control-allow-credentials', 'true');
+      if (opts.exposedHeaders?.length) {
+        ctx.setHeader('access-control-expose-headers', opts.exposedHeaders.join(', '));
+      }
+    }
+
+    if (ctx.method === 'OPTIONS' && ctx.headers['access-control-request-method']) {
+      // Preflight: short-circuit
+      ctx.setHeader('access-control-allow-methods', opts.methods.join(', '));
+      const reqHeaders = (ctx.headers['access-control-request-headers'] as string) ?? '';
+      ctx.setHeader('access-control-allow-headers', (opts.allowedHeaders ?? reqHeaders) || '*');
+      ctx.setHeader('access-control-max-age', String(opts.maxAge));
+      ctx.status(204);
+      return;
+    }
+
+    await next();
+  };
+}
+
+function resolveOrigin(
+  config: string | string[] | boolean,
+  requestOrigin: string,
+  credentials: boolean,
+): string | undefined {
+  if (config === true) {
+    // Reflect the request origin (works with credentials); no "*" when credentialed.
+    return requestOrigin || (credentials ? undefined : '*');
+  }
+  if (typeof config === 'string') {
+    if (config === '*') return credentials ? requestOrigin || undefined : '*';
+    return config === requestOrigin ? config : undefined;
+  }
+  if (Array.isArray(config)) {
+    return config.includes(requestOrigin) ? requestOrigin : undefined;
+  }
+  return undefined;
+}
+
+function appendVary(ctx: Parameters<Middleware>[0], value: string): void {
+  const existing = ctx.res.getHeader('vary');
+  if (existing === undefined) {
+    ctx.setHeader('vary', value);
+  } else {
+    const merged = `${existing}, ${value}`;
+    ctx.setHeader('vary', merged);
+  }
+}

package/src/csrf.ts

@@ -0,0 +1,158 @@
+import { randomBytes } from 'node:crypto';
+import type { Middleware, RequestContext } from '../../nexus-core/src/http/index.js';
+import { AuthenticationError } from '../../nexus-core/src/index.js';
+
+export interface CsrfOptions {
+  /** Cookie name holding the double-submit token. */
+  cookieName?: string;
+  /** Header / body field name carrying the token on unsafe requests. */
+  tokenName?: string;
+  /** Trusted origin hosts (for the origin/referer check). If omitted, origin check is skipped. */
+  trustedOrigins?: string[];
+  /** Methods exempt from CSRF (safe methods). */
+  safeMethods?: string[];
+  /** Cookie attributes. */
+  cookie?: { path?: string; secure?: boolean; sameSite?: 'strict' | 'lax' | 'none'; domain?: string };
+}
+
+const SAFE = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
+
+/**
+ * Inbuilt CSRF protection using the double-submit cookie pattern plus an
+ * origin/referer check on unsafe requests. Safe methods are exempt.
+ *
+ * On a safe request, a token cookie is set (rotated each request) and exposed
+ * via `ctx.state.csrfToken` so handlers can return it to clients. On unsafe
+ * requests, the header token must equal the cookie token.
+ */
+export function csrf(options: CsrfOptions = {}): Middleware {
+  const cookieName = options.cookieName ?? 'nexus_csrf';
+  const tokenName = options.tokenName ?? 'x-csrf-token';
+  const trusted = options.trustedOrigins ?? [];
+  const safeMethods = new Set(options.safeMethods ?? [...SAFE]);
+  const cookieOpts = options.cookie ?? { path: '/', sameSite: 'lax', secure: false };
+
+  return async (ctx, next) => {
+    if (safeMethods.has(ctx.method)) {
+      // Reuse an existing cookie token so concurrent safe requests (e.g. the
+      // 5-second cluster overview poll) don't rotate the token out from under
+      // a pending unsafe request — that race produced "Unauthorized" on POSTs.
+      const existing = readCookie(ctx, cookieName);
+      if (existing) {
+        ctx.state.csrfToken = existing;
+      } else {
+        ctx.state.csrfToken = issueToken(ctx, cookieName, cookieOpts);
+      }
+      await next();
+      return;
+    }
+
+    // Unsafe method: validate origin/referer first.
+    checkOrigin(ctx, trusted);
+
+    // Then double-submit: header token must match cookie token.
+    const cookieToken = readCookie(ctx, cookieName);
+    const sentToken =
+      (ctx.headers[tokenName] as string) ??
+      (ctx.body && typeof ctx.body === 'object' ? (ctx.body as Record<string, unknown>)[tokenName] as string : undefined);
+
+    if (!cookieToken || !sentToken || !timingSafeEqual(cookieToken, sentToken)) {
+      throw new AuthenticationError('Invalid CSRF token');
+    }
+    await next();
+  };
+}
+
+/** Helper for handlers/endpoints to mint a token (e.g. a /csrf-token route). */
+export function issueCsrfToken(ctx: RequestContext, options: CsrfOptions = {}): string {
+  return issueToken(ctx, options.cookieName ?? 'nexus_csrf', options.cookie ?? { path: '/', sameSite: 'lax', secure: false });
+}
+
+/** CSRF + origin check for the WebSocket upgrade request (no CORS preflight). */
+export function checkWsUpgrade(headers: Record<string, string | string[] | undefined>, options: CsrfOptions = {}): void {
+  const trusted = options.trustedOrigins ?? [];
+  if (trusted.length) {
+    const origin = (headers['origin'] as string) ?? '';
+    if (!origin || !isTrustedOrigin(origin, trusted)) {
+      throw new AuthenticationError('Untrusted WebSocket origin');
+    }
+  }
+  const cookieToken = readCookieFromHeader((headers['cookie'] as string) ?? '', options.cookieName ?? 'nexus_csrf');
+  const queryToken = (headers['sec-websocket-protocol'] as string)?.split(',').map((s) => s.trim())[0];
+  if (!cookieToken || !queryToken || !timingSafeEqual(cookieToken, queryToken)) {
+    throw new AuthenticationError('Invalid WebSocket CSRF token');
+  }
+}
+
+function issueToken(
+  ctx: RequestContext,
+  cookieName: string,
+  opts: NonNullable<CsrfOptions['cookie']>,
+): string {
+  const token = randomBytes(24).toString('base64url');
+  const parts = [
+    `${cookieName}=${token}`,
+    `Path=${opts.path ?? '/'}`,
+    `SameSite=${opts.sameSite ?? 'lax'}`,
+    opts.secure ? 'Secure' : '',
+    opts.domain ? `Domain=${opts.domain}` : '',
+    'HttpOnly',
+  ].filter(Boolean);
+  ctx.setHeader('set-cookie', parts.join('; '));
+  return token;
+}
+
+function readCookie(ctx: RequestContext, name: string): string | undefined {
+  return readCookieFromHeader((ctx.headers['cookie'] as string) ?? '', name);
+}
+
+function readCookieFromHeader(header: string, name: string): string | undefined {
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    const k = part.slice(0, eq).trim();
+    if (k === name) return part.slice(eq + 1).trim();
+  }
+  return undefined;
+}
+
+function checkOrigin(ctx: RequestContext, trusted: string[]): void {
+  if (trusted.length === 0) return;
+  const origin = (ctx.headers['origin'] as string) ?? (ctx.headers['referer'] as string) ?? '';
+  if (!origin || !isTrustedOrigin(origin, trusted)) {
+    throw new AuthenticationError('Untrusted request origin');
+  }
+}
+
+function isTrustedOrigin(origin: string, trusted: string[]): boolean {
+  let hostname: string;
+  let host: string;
+  try {
+    const u = new URL(origin);
+    hostname = u.hostname;
+    host = u.host;
+  } catch {
+    return false;
+  }
+  // Loopback origins (localhost/127.0.0.1) are safe from cross-site forgery
+  // regardless of port — Docker / port-forwarding commonly remaps host ports
+  // (e.g. container :3001 published on the host as :3011), so a strict
+  // host:port match would wrongly reject the admin/frontend dev servers.
+  if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+    return trusted.some((t) => {
+      try {
+        const tu = new URL(t);
+        return tu.hostname === 'localhost' || tu.hostname === '127.0.0.1' || tu.hostname === '::1';
+      } catch {
+        return false;
+      }
+    });
+  }
+  return trusted.some((t) => t === host || t === origin || origin.startsWith(t));
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return ab.equals(bb);
+}

package/src/headers.ts

@@ -0,0 +1,55 @@
+import type { Middleware } from '../../nexus-core/src/http/index.js';
+
+export interface SecurityHeadersOptions {
+  /** HSTS max age in seconds (0 to disable). */
+  hstsMaxAge?: number;
+  /** Include subdomains in HSTS. */
+  hstsIncludeSubdomains?: boolean;
+  /** Enable HSTS preload. */
+  hstsPreload?: boolean;
+  /** Content-Security-Policy directive string. */
+  csp?: string;
+  /** Referrer-Policy. */
+  referrerPolicy?: string;
+  /** X-Content-Type-Options. */
+  noSniff?: boolean;
+  /** X-Frame-Options (DENY/SAMEORIGIN) — superseded by CSP frame-ancestors when present. */
+  frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+  /** Cross-Origin-Opener-Policy. */
+  coop?: string;
+  /** Cross-Origin-Resource-Policy. */
+  corp?: string;
+}
+
+/** Helmet-equivalent security headers, applied to every response. */
+export function securityHeaders(options: SecurityHeadersOptions = {}): Middleware {
+  const opts = {
+    hstsMaxAge: options.hstsMaxAge ?? 15552000, // 180 days
+    hstsIncludeSubdomains: options.hstsIncludeSubdomains ?? true,
+    hstsPreload: options.hstsPreload ?? false,
+    csp: options.csp ?? "default-src 'self'",
+    referrerPolicy: options.referrerPolicy ?? 'no-referrer',
+    noSniff: options.noSniff ?? true,
+    frameOptions: options.frameOptions ?? 'SAMEORIGIN',
+    coop: options.coop ?? 'same-origin',
+    corp: options.corp ?? 'same-origin',
+  };
+
+  return async (ctx, next) => {
+    // Apply headers early; they persist through the response.
+    if (opts.hstsMaxAge > 0) {
+      let hsts = `max-age=${opts.hstsMaxAge}`;
+      if (opts.hstsIncludeSubdomains) hsts += '; includeSubDomains';
+      if (opts.hstsPreload) hsts += '; preload';
+      ctx.setHeader('strict-transport-security', hsts);
+    }
+    if (opts.csp) ctx.setHeader('content-security-policy', opts.csp);
+    if (opts.referrerPolicy) ctx.setHeader('referrer-policy', opts.referrerPolicy);
+    if (opts.noSniff) ctx.setHeader('x-content-type-options', 'nosniff');
+    if (opts.frameOptions) ctx.setHeader('x-frame-options', opts.frameOptions);
+    if (opts.coop) ctx.setHeader('cross-origin-opener-policy', opts.coop);
+    if (opts.corp) ctx.setHeader('cross-origin-resource-policy', opts.corp);
+    ctx.setHeader('x-xss-protection', '0'); // disabled in favor of CSP
+    await next();
+  };
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './cors.js';
+export * from './csrf.js';
+export * from './headers.js';
+export * from './rateLimit.js';
+export * from './password.js';
+export * from './jwt.js';
+export * from './session.js';
+export * from './rbac.js';
+export * from './oauth.js';
+export * from './auth.js';
+export * from './middleware.js';

package/src/jwt.ts

@@ -0,0 +1,65 @@
+import { SignJWT, jwtVerify, type JWTPayload } from 'jose';
+
+export interface TokenPayload extends JWTPayload {
+  /** Subject (user id). */
+  sub: string;
+  /** Roles attached to the subject. */
+  roles?: string[];
+  /** Token kind discriminator. */
+  kind?: 'access' | 'refresh';
+  /** For refresh tokens: the session id they belong to. */
+  sid?: string;
+}
+
+export interface JwtOptions {
+  /** Signing secret (string or raw bytes). Required. */
+  secret: string | Uint8Array;
+  /** Algorithm. Defaults to HS256. */
+  algorithm?: 'HS256' | 'HS384' | 'HS512';
+  /** Issuer. */
+  issuer?: string;
+  /** Audience. */
+  audience?: string;
+  /** Access-token TTL in seconds (default 15m). */
+  accessTtl?: number;
+  /** Refresh-token TTL in seconds (default 7d). */
+  refreshTtl?: number;
+}
+
+const enc = (secret: string | Uint8Array): Uint8Array =>
+  typeof secret === 'string' ? new TextEncoder().encode(secret) : secret;
+
+/** Sign an access token for a subject with roles (optionally bound to a session id). */
+export async function signAccessToken(subject: string, roles: string[], opts: JwtOptions, sid?: string): Promise<string> {
+  const ttl = opts.accessTtl ?? 60 * 15;
+  const builder = new SignJWT({ kind: 'access', roles, sid })
+    .setProtectedHeader({ alg: opts.algorithm ?? 'HS256' })
+    .setSubject(subject)
+    .setIssuedAt()
+    .setExpirationTime(`${ttl}s`);
+  if (opts.issuer) builder.setIssuer(opts.issuer);
+  if (opts.audience) builder.setAudience(opts.audience);
+  return builder.sign(enc(opts.secret));
+}
+
+/** Sign a refresh token bound to a session id. */
+export async function signRefreshToken(subject: string, sid: string, roles: string[], opts: JwtOptions): Promise<string> {
+  const ttl = opts.refreshTtl ?? 60 * 60 * 24 * 7;
+  const builder = new SignJWT({ kind: 'refresh', roles, sid })
+    .setProtectedHeader({ alg: opts.algorithm ?? 'HS256' })
+    .setSubject(subject)
+    .setIssuedAt()
+    .setExpirationTime(`${ttl}s`);
+  if (opts.issuer) builder.setIssuer(opts.issuer);
+  if (opts.audience) builder.setAudience(opts.audience);
+  return builder.sign(enc(opts.secret));
+}
+
+/** Verify a token and return its payload; throws on invalid/expired tokens. */
+export async function verifyToken(token: string, opts: JwtOptions): Promise<TokenPayload> {
+  const { payload } = await jwtVerify(token, enc(opts.secret), {
+    issuer: opts.issuer,
+    audience: opts.audience,
+  });
+  return payload as TokenPayload;
+}

package/src/middleware.ts

@@ -0,0 +1,94 @@
+import type { Middleware, RequestContext } from '../../nexus-core/src/http/index.js';
+import { AuthenticationError } from '../../nexus-core/src/index.js';
+import type { AuthService } from './auth.js';
+import type { TokenPair } from './auth.js';
+
+export interface AuthCookieOptions {
+  /** Cookie names. */
+  accessTokenName?: string;
+  refreshTokenName?: string;
+  /** Cookie attributes. */
+  path?: string;
+  secure?: boolean;
+  sameSite?: 'strict' | 'lax' | 'none';
+  domain?: string;
+}
+
+const DEFAULT_COOKIE: Required<AuthCookieOptions> = {
+  accessTokenName: 'nexus_at',
+  refreshTokenName: 'nexus_rt',
+  path: '/',
+  secure: false,
+  sameSite: 'lax',
+  domain: '',
+};
+
+/** Read a cookie value from the request's cookie header. */
+export function readCookieValue(ctx: RequestContext, name: string): string | undefined {
+  const header = (ctx.headers['cookie'] as string) ?? '';
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+  }
+  return undefined;
+}
+
+/** Set access + refresh tokens as httpOnly cookies (for cookie-based sessions). */
+export function setAuthCookies(ctx: RequestContext, pair: TokenPair, opts: AuthCookieOptions = {}): void {
+  const o = { ...DEFAULT_COOKIE, ...opts };
+  const base = [`Path=${o.path}`, `SameSite=${o.sameSite}`, o.secure ? 'Secure' : '', o.domain ? `Domain=${o.domain}` : '', 'HttpOnly'].filter(Boolean).join('; ');
+  ctx.setHeader('set-cookie', [`${o.accessTokenName}=${pair.accessToken}; ${base}`, `${o.refreshTokenName}=${pair.refreshToken}; ${base}; Max-Age=${Math.floor((pair.refreshExpiresAt - Date.now()) / 1000)}`]);
+}
+
+/** Clear the auth cookies (logout). */
+export function clearAuthCookies(ctx: RequestContext, opts: AuthCookieOptions = {}): void {
+  const o = { ...DEFAULT_COOKIE, ...opts };
+  const expired = `Path=${o.path}; Max-Age=0`;
+  ctx.setHeader('set-cookie', [`${o.accessTokenName}=; ${expired}`, `${o.refreshTokenName}=; ${expired}`]);
+}
+
+export interface AuthTokenOptions {
+  /** Cookie name for the access token (cookie-mode). Defaults to `nexus_at`. */
+  cookieName?: string;
+  /** If false, only the Authorization header is accepted (no cookie). */
+  allowCookie?: boolean;
+  /** If true, missing/invalid tokens throw 401; if false, the middleware is optional (no user set). */
+  required?: boolean;
+}
+
+/**
+ * Authenticate the request by verifying a bearer access token from the
+ * `Authorization` header or (optionally) an httpOnly cookie. On success,
+ * `ctx.state.user = { id, roles }` is set for downstream `requireAuth` /
+ * `requireRole` / `requirePermission` middleware.
+ */
+export function authToken(service: AuthService, options: AuthTokenOptions = {}): Middleware {
+  const cookieName = options.cookieName ?? 'nexus_at';
+  const allowCookie = options.allowCookie ?? true;
+  const required = options.required ?? true;
+
+  return async (ctx, next) => {
+    const header = (ctx.headers['authorization'] as string) ?? '';
+    let token: string | undefined;
+    if (header.toLowerCase().startsWith('bearer ')) {
+      token = header.slice(7).trim();
+    } else if (allowCookie) {
+      token = readCookieValue(ctx, cookieName);
+    }
+
+    if (!token) {
+      if (required) throw new AuthenticationError();
+      await next();
+      return;
+    }
+
+    try {
+      const payload = await service.verifyAccessToken(token);
+      ctx.state.user = { id: payload.sub, roles: payload.roles ?? [], ...(payload as Record<string, unknown>) };
+    } catch (e) {
+      if (required) throw e instanceof AuthenticationError ? e : new AuthenticationError('Invalid token');
+      // optional mode: leave ctx.state.user unset
+    }
+    await next();
+  };
+}