@bajustone/fortress 1.0.0-rc.1

package/src/core/auth/post-auth-gate.ts

@@ -0,0 +1,228 @@
+import type { DatabaseAdapter } from '../../adapters/database';
+import type { FortressConfig } from '../config';
+import type { StoredContinuation } from '../internal-adapter';
+import type { FortressPlugin, PostAuthGateDecision } from '../plugin';
+import type { AuthChallenge, FortressUser, PendingReason, RequestMeta } from '../types';
+import { Errors } from '../errors';
+import { generateRefreshToken, hashToken } from './refresh-token';
+
+/** Default lifetime of a pending-auth continuation (five minutes). */
+export const AUTH_CONTINUATION_TTL_SECONDS = 300;
+
+export interface PostAuthGateHold {
+  challenge: AuthChallenge;
+  pluginData?: Record<string, unknown>;
+}
+
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_COOLDOWN_SECONDS = 1;
+
+/** Persist a short-lived, hashed continuation and return only its raw bearer token. */
+export async function mintAuthContinuation(
+  db: DatabaseAdapter,
+  userId: string,
+  reason: PendingReason,
+  ttlSeconds: number = AUTH_CONTINUATION_TTL_SECONDS,
+  policy: { maxAttempts?: number; cooldownSeconds?: number } = {},
+): Promise<AuthChallenge> {
+  const { raw, hash } = await generateRefreshToken();
+  const now = new Date();
+  await db.create({
+    model: 'auth_continuation',
+    data: {
+      userId,
+      tokenHash: hash,
+      reason,
+      expiresAt: new Date(now.getTime() + ttlSeconds * 1000),
+      consumedAt: null,
+      failedAttempts: 0,
+      lastFailedAt: null,
+      invalidatedAt: null,
+      maxAttempts: Math.max(1, policy.maxAttempts ?? DEFAULT_MAX_ATTEMPTS),
+      cooldownSeconds: Math.max(0, policy.cooldownSeconds ?? DEFAULT_COOLDOWN_SECONDS),
+      createdAt: now,
+    },
+  });
+  return { reason, continuationToken: raw };
+}
+
+function assertUsableContinuation(record: StoredContinuation | null): StoredContinuation {
+  if (!record || record.consumedAt || record.invalidatedAt || record.expiresAt <= new Date())
+    throw Errors.unauthorized('Invalid or expired auth continuation');
+  return record;
+}
+
+/** Inspect a continuation without consuming it, for a factor plugin's credential check. */
+export async function peekAuthContinuation(
+  db: DatabaseAdapter,
+  continuationToken: string,
+): Promise<StoredContinuation> {
+  const tokenHash = await hashToken(continuationToken);
+  const record = await db.findOne<StoredContinuation>({
+    model: 'auth_continuation',
+    where: [{ field: 'tokenHash', operator: '=', value: tokenHash }],
+  });
+  return assertUsableContinuation(record);
+}
+
+/** Atomically claim a continuation exactly once. */
+export async function consumeAuthContinuation(
+  db: DatabaseAdapter,
+  continuationToken: string,
+  verify?: (tx: DatabaseAdapter, continuation: StoredContinuation) => Promise<void>,
+): Promise<StoredContinuation> {
+  const tokenHash = await hashToken(continuationToken);
+  const consumedAt = new Date();
+
+  const outcome = await db.transaction(async (tx): Promise<
+    | { ok: true; continuation: StoredContinuation }
+    | { ok: false; error: unknown }
+  > => {
+    const existing = await tx.findOne<StoredContinuation>({
+      model: 'auth_continuation',
+      where: [{ field: 'tokenHash', operator: '=', value: tokenHash }],
+    });
+    const usable = assertUsableContinuation(existing);
+    const maxAttempts = usable.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const failedAttempts = usable.failedAttempts ?? 0;
+    if (failedAttempts >= maxAttempts)
+      throw Errors.unauthorized('Invalid or expired auth continuation');
+
+    const cooldownSeconds = usable.cooldownSeconds ?? DEFAULT_COOLDOWN_SECONDS;
+    if (cooldownSeconds > 0) {
+      const cutoff = new Date(consumedAt.getTime() - cooldownSeconds * 1000);
+      const recent = await tx.findOne<StoredContinuation>({
+        model: 'auth_continuation',
+        where: [
+          { field: 'userId', operator: '=', value: usable.userId },
+          { field: 'reason', operator: '=', value: usable.reason },
+          { field: 'lastFailedAt', operator: 'gt', value: cutoff },
+        ],
+      });
+      if (recent)
+        throw Errors.unauthorized('Too many authentication attempts; try again shortly');
+    }
+
+    const record = await tx.update<StoredContinuation>({
+      model: 'auth_continuation',
+      where: [
+        { field: 'tokenHash', operator: '=', value: tokenHash },
+        { field: 'consumedAt', operator: 'isNull', value: null },
+        { field: 'invalidatedAt', operator: 'isNull', value: null },
+        { field: 'expiresAt', operator: 'gt', value: consumedAt },
+        { field: 'failedAttempts', operator: 'lt', value: maxAttempts },
+      ],
+      data: { consumedAt },
+    });
+    if (!record)
+      throw Errors.unauthorized('Invalid or expired auth continuation');
+
+    try {
+      // The row claim serializes concurrent guesses. On rejection, convert the
+      // error to data so the transaction can durably release the claim and
+      // increment the counter before the original error is re-thrown outside.
+      await verify?.(tx, record);
+      return { ok: true, continuation: record };
+    }
+    catch (error) {
+      const nextFailedAttempts = (record.failedAttempts ?? 0) + 1;
+      const released = await tx.update<StoredContinuation>({
+        model: 'auth_continuation',
+        where: [
+          { field: 'tokenHash', operator: '=', value: tokenHash },
+          { field: 'consumedAt', operator: '=', value: consumedAt },
+        ],
+        data: {
+          consumedAt: null,
+          failedAttempts: nextFailedAttempts,
+          lastFailedAt: consumedAt,
+          ...(nextFailedAttempts >= maxAttempts ? { invalidatedAt: consumedAt } : {}),
+        },
+      });
+      if (!released)
+        throw Errors.unauthorized('Invalid or expired auth continuation');
+      return { ok: false, error };
+    }
+  });
+
+  if (!outcome.ok)
+    throw outcome.error;
+  return outcome.continuation;
+}
+
+/** Run post-credential gates in registration order and mint the first hold. */
+export async function runPostAuthGates(
+  plugins: readonly FortressPlugin[],
+  db: DatabaseAdapter,
+  config: FortressConfig,
+  user: FortressUser,
+  meta: RequestMeta | undefined,
+  completedReasons: readonly PendingReason[] = [],
+): Promise<PostAuthGateHold | null> {
+  const providers = plugins.flatMap(plugin => plugin.hooks?.postAuthGate ? [plugin.hooks.postAuthGate] : []);
+  const duplicateReason = providers.find((provider, index) =>
+    providers.findIndex(candidate => candidate.reason === provider.reason) !== index,
+  );
+  if (duplicateReason)
+    throw Errors.badRequest(`Duplicate post-auth gate reason: '${duplicateReason.reason}'`);
+
+  const resumeReason = completedReasons.at(-1);
+  const resumeIndex = resumeReason == null
+    ? -1
+    : providers.findIndex(provider => provider.reason === resumeReason);
+  if (resumeReason != null && resumeIndex < 0)
+    throw Errors.unauthorized('No auth gate can resume this continuation');
+
+  const satisfiedReasons = providers.slice(0, resumeIndex + 1).map(provider => provider.reason);
+  for (const provider of providers.slice(resumeIndex + 1)) {
+    const decision: PostAuthGateDecision | void = await provider.evaluate({
+      db,
+      config,
+      meta,
+      user,
+      completedReasons: satisfiedReasons,
+    });
+    if (!decision)
+      continue;
+
+    return {
+      challenge: await mintAuthContinuation(db, user.id, provider.reason, AUTH_CONTINUATION_TTL_SECONDS, {
+        maxAttempts: provider.maxAttempts,
+        cooldownSeconds: provider.cooldownSeconds,
+      }),
+      pluginData: decision.pluginData,
+    };
+  }
+  return null;
+}
+
+/** Dispatch completion proof to the provider that created this continuation. */
+export async function verifyAuthContinuation(
+  plugins: readonly FortressPlugin[],
+  db: DatabaseAdapter,
+  config: FortressConfig,
+  user: FortressUser,
+  continuation: StoredContinuation,
+  completion: unknown,
+  meta?: RequestMeta,
+): Promise<Record<string, unknown> | void> {
+  const providers = plugins.flatMap((plugin) => {
+    const provider = plugin.hooks?.postAuthGate;
+    return provider?.reason === continuation.reason ? [provider] : [];
+  });
+  if (providers.length !== 1)
+    throw Errors.unauthorized('No unique auth gate can complete this continuation');
+  const [provider] = providers;
+
+  return provider.verify({
+    db,
+    config,
+    meta,
+    user,
+    continuation: {
+      id: continuation.id,
+      reason: continuation.reason,
+      expiresAt: continuation.expiresAt,
+    },
+  }, completion);
+}

package/src/core/auth/refresh-token.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+
+import { deriveRefreshTokenSuccessor, generateRefreshToken, generateTokenFamily, hashRefreshFingerprint, hashToken } from './refresh-token';
+
+describe('refresh-token', () => {
+  describe('generateRefreshToken', () => {
+    it('generates a raw token and its hash', async () => {
+      const { raw, hash } = await generateRefreshToken();
+      expect(raw).toBeTruthy();
+      expect(hash).toBeTruthy();
+      expect(raw).not.toBe(hash);
+    });
+
+    it('generates unique tokens each time', async () => {
+      const t1 = await generateRefreshToken();
+      const t2 = await generateRefreshToken();
+      expect(t1.raw).not.toBe(t2.raw);
+      expect(t1.hash).not.toBe(t2.hash);
+    });
+
+    it('raw token is base64url encoded (no +, /, =)', async () => {
+      const { raw } = await generateRefreshToken();
+      expect(raw).not.toMatch(/[+/=]/);
+    });
+
+    it('hash is a hex string', async () => {
+      const { hash } = await generateRefreshToken();
+      expect(hash).toMatch(/^[0-9a-f]{64}$/); // SHA256 = 64 hex chars
+    });
+  });
+
+  describe('hashToken', () => {
+    it('produces consistent hash for the same input', async () => {
+      const hash1 = await hashToken('same-token');
+      const hash2 = await hashToken('same-token');
+      expect(hash1).toBe(hash2);
+    });
+
+    it('produces different hash for different input', async () => {
+      const hash1 = await hashToken('token-a');
+      const hash2 = await hashToken('token-b');
+      expect(hash1).not.toBe(hash2);
+    });
+
+    it('hash of generated token matches the returned hash', async () => {
+      const { raw, hash } = await generateRefreshToken();
+      const recomputed = await hashToken(raw);
+      expect(recomputed).toBe(hash);
+    });
+  });
+
+  describe('deriveRefreshTokenSuccessor', () => {
+    it('recomputes the same successor without storing its raw value', async () => {
+      const first = await deriveRefreshTokenSuccessor('old-token', 'secret-a');
+      const retry = await deriveRefreshTokenSuccessor('old-token', 'secret-a');
+      const otherKey = await deriveRefreshTokenSuccessor('old-token', 'secret-b');
+
+      expect(retry).toEqual(first);
+      expect(otherKey.raw).not.toBe(first.raw);
+      expect(await hashToken(first.raw)).toBe(first.hash);
+    });
+  });
+
+  describe('hashRefreshFingerprint', () => {
+    it('is keyed and binds both User-Agent and source IP', async () => {
+      const first = await hashRefreshFingerprint('Browser/1', '203.0.113.1', 'secret-a');
+      expect(await hashRefreshFingerprint('Browser/1', '203.0.113.1', 'secret-a')).toBe(first);
+      expect(await hashRefreshFingerprint('Browser/1', '203.0.113.2', 'secret-a')).not.toBe(first);
+      expect(await hashRefreshFingerprint('Browser/1', '203.0.113.1', 'secret-b')).not.toBe(first);
+      expect(first).not.toBe(await hashToken('Browser/1'));
+    });
+  });
+
+  describe('generateTokenFamily', () => {
+    it('generates a non-empty string', () => {
+      const family = generateTokenFamily();
+      expect(family).toBeTruthy();
+    });
+
+    it('generates unique families', () => {
+      const f1 = generateTokenFamily();
+      const f2 = generateTokenFamily();
+      expect(f1).not.toBe(f2);
+    });
+  });
+});

package/src/core/auth/refresh-token.ts

@@ -0,0 +1,105 @@
+/**
+ * Refresh token utilities.
+ * Tokens are 32 bytes of cryptographic randomness, base64url encoded.
+ * Only the SHA256 hash is stored — the raw token is never persisted.
+ */
+
+/**
+ * Generate a new refresh token and its SHA256 hash.
+ */
+export async function generateRefreshToken(): Promise<{ raw: string; hash: string }> {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const raw = base64UrlEncode(bytes);
+  const hash = await hashToken(raw);
+  return { raw, hash };
+}
+
+/**
+ * Derive a rotation successor without persisting its raw value. A
+ * domain-separated HKDF subkey derived from the configured root secret keys
+ * the rotation HMAC, so the JWT signing key is never used directly for a
+ * second primitive. A grace-window retry can recompute the exact successor
+ * and confirm it against `successorTokenHash`.
+ */
+export async function deriveRefreshTokenSuccessor(
+  rawToken: string,
+  secret: string,
+): Promise<{ raw: string; hash: string }> {
+  const encoder = new TextEncoder();
+  const key = await deriveRefreshHmacKey(secret, 'rotation-successor-hmac');
+  const digest = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    encoder.encode(`fortress-refresh-successor\0${rawToken}`),
+  );
+  const raw = base64UrlEncode(new Uint8Array(digest));
+  return { raw, hash: await hashToken(raw) };
+}
+
+/**
+ * Keyed refresh-client consistency signal. It binds both User-Agent and the
+ * observed source IP without storing a reversible fingerprint in the DB.
+ * This remains optional defense-in-depth rather than proof of device identity.
+ */
+export async function hashRefreshFingerprint(
+  userAgent: string,
+  ipAddress: string | undefined,
+  secret: string,
+): Promise<string> {
+  const encoder = new TextEncoder();
+  const key = await deriveRefreshHmacKey(secret, 'client-fingerprint-hmac');
+  const digest = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    encoder.encode(`${userAgent}\0${ipAddress ?? ''}`),
+  );
+  return hexEncode(new Uint8Array(digest));
+}
+
+async function deriveRefreshHmacKey(secret: string, info: string): Promise<CryptoKey> {
+  const encoder = new TextEncoder();
+  const rootKey = await crypto.subtle.importKey('raw', encoder.encode(secret), 'HKDF', false, ['deriveKey']);
+  return crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: encoder.encode('fortress-refresh-token-kdf-v1'),
+      info: encoder.encode(info),
+    },
+    rootKey,
+    { name: 'HMAC', hash: 'SHA-256', length: 256 },
+    false,
+    ['sign'],
+  );
+}
+
+/**
+ * Generate a random token family ID for rotation tracking.
+ */
+export function generateTokenFamily(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+
+/**
+ * SHA256 hash a raw token. Used for storage and lookup.
+ */
+export async function hashToken(raw: string): Promise<string> {
+  const data = new TextEncoder().encode(raw);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  return hexEncode(new Uint8Array(hashBuffer));
+}
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
+  return btoa(binString)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '');
+}
+
+function hexEncode(bytes: Uint8Array): string {
+  return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+}

package/src/core/auth/timing-safe.ts

@@ -0,0 +1,23 @@
+/**
+ * Constant-time equality for secret-derived strings.
+ *
+ * `===` on two strings short-circuits at the first mismatched byte, which —
+ * combined with a remote attacker's ability to time HTTP responses — leaks
+ * one bit per request about how far into the secret the comparison got.
+ * The standard mitigation is to compare every byte regardless of mismatch.
+ *
+ * Both arms of OAuth's hot paths (client-secret check, access-token /
+ * authorization-code lookup) hash the inbound value with SHA-256 before
+ * comparing, so both operands here are 64-character lowercase hex. The
+ * length check is therefore a no-op in practice but preserved for safety.
+ *
+ * @see RFC 9700 §2.1.1, OWASP ASVS V2.4
+ */
+export function timingSafeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length)
+    return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++)
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/src/core/config.ts

@@ -0,0 +1,212 @@
+import type { DatabaseAdapter } from '../adapters/database';
+import type { JwtKeyMaterial } from './auth/jwt';
+import type { PasswordPolicyConfig } from './auth/password-policy';
+import type { EndpointDefinition } from './endpoint';
+import type { CsrfConfig } from './http/csrf';
+import type { FortressLogger } from './observability/logger';
+import type { TelemetryProvider } from './observability/types';
+import type { FortressPlugin } from './plugin';
+
+/** Pluggable password hashing contract — implement to swap fortress's default Argon2id WASM hasher. */
+export interface PasswordHasher {
+  hash: (password: string) => Promise<string>;
+  verify: (hash: string, password: string) => Promise<boolean>;
+}
+
+/**
+ * Cookie configuration consumed by `fortress.handleRequest` and any framework
+ * adapter that wants to serialize auth tokens to `Set-Cookie` headers.
+ *
+ * Defaults are environment-independent and production-safe: `__Host-`
+ * prefixed names, `httpOnly`, `secure`, `sameSite: 'lax'`, `path: '/'`.
+ * Plain-HTTP local development must explicitly set `secure: false`, which
+ * also selects non-`__Host-` default names.
+ */
+export interface CookieConfig {
+  /** Override the access-token cookie name. Default: `__Host-fortress_access` when host-prefix constraints permit. */
+  accessName?: string;
+  /** Override the refresh-token cookie name. Default: `__Host-fortress_refresh` when host-prefix constraints permit. */
+  refreshName?: string;
+  /** SameSite attribute. Default: `'lax'`. */
+  sameSite?: 'lax' | 'strict' | 'none';
+  /** Force the `Secure` attribute on or off. Default: `true` in every environment. */
+  secure?: boolean;
+  /** Optional `Domain` attribute. Defaults to host-only when omitted. */
+  domain?: string;
+  /** `Path` attribute. Default: `'/'`. */
+  path?: string;
+}
+
+/** Opt-in refresh-session controls. Omitted fields preserve existing behavior. */
+export interface SessionConfig {
+  /** Accept the immediately previous refresh token for this many seconds. */
+  refreshGraceSeconds?: number;
+  /** Reject a session after this many seconds without refresh activity. */
+  idleTimeoutSeconds?: number;
+  /** Reject a refresh family after this many seconds, regardless of activity. */
+  absoluteTimeoutSeconds?: number;
+  /** Maximum active refresh families per user; oldest sessions are revoked first. */
+  maxSessionsPerUser?: number;
+}
+
+/** Top-level fortress configuration accepted by {@link createFortress}. */
+export interface FortressConfig {
+  jwt: {
+    /**
+     * Signing/verification key material. Today: an HS256 shared secret
+     * (string) or a rotation array of shared secrets (first signs, all
+     * verify). See {@link JwtKeyMaterial} for the planned expansion to
+     * asymmetric keys / JWKS.
+     */
+    key: JwtKeyMaterial;
+    issuer?: string;
+    /** Optional audience included in and required for access tokens. */
+    audience?: string | string[];
+    accessTokenExpirySeconds?: number;
+    refreshTokenExpirySeconds?: number;
+    /**
+     * Compare a domain-separated keyed fingerprint of User-Agent + source IP
+     * across refreshes. This is an anomaly signal, not proof of device identity;
+     * enable hard rejection only where client IP stability is acceptable.
+     */
+    validateRefreshFingerprint?: boolean | 'warn';
+    /** Optional session rotation/cap controls. No caps or grace apply when omitted. */
+    session?: SessionConfig;
+  };
+  rbac?: {
+    evaluationMode?: 'allow-only' | 'deny-overrides';
+    resourceFile?: string;
+    cache?: {
+      ttlSeconds?: number;
+      maxEntries?: number;
+    };
+  };
+  database: DatabaseAdapter;
+  passwordHasher?: PasswordHasher;
+  passwordPolicy?: PasswordPolicyConfig;
+  /**
+   * Impersonation hardening (RFC 8693 `act` tokens). All fields optional;
+   * defaults to a 1-hour ceiling on caller-supplied `expirySeconds`.
+   */
+  impersonation?: {
+    /**
+     * Hard ceiling on the impersonation access-token lifetime in seconds.
+     * `auth.impersonate({ expirySeconds })` is clamped to this. Default: 3600.
+     */
+    maxTtlSeconds?: number;
+  };
+  plugins?: readonly FortressPlugin[];
+  /**
+   * Host-application endpoint definitions to register with the manifest,
+   * OpenAPI generation, and `protect()` / adapter `protectedRoute()` helpers
+   * without authoring a plugin. Fortress tracks them internally under the
+   * reserved name `__host`.
+   *
+   * Top-level `routes` are metadata-only: adapters leave them to the host
+   * router and they do not add `fortress.call.*` entries because no handler
+   * methods are registered. If you need Fortress-mounted routes or typed
+   * in-process callables for custom routes, declare a real plugin with both
+   * `routes` and matching `methods`.
+   *
+   * Keyed by handler name, matching {@link FortressPlugin.routes}:
+   *
+   * ```ts
+   * createFortress({
+   *   database, jwt, cookies,
+   *   routes: appEndpoints,
+   * });
+   * ```
+   *
+   * The name `__host` is reserved — declaring a plugin called `__host`
+   * alongside `routes` is a configuration error.
+   */
+  routes?: Record<string, EndpointDefinition>;
+  /** Auth-cookie naming and attributes used by `fortress.handleRequest` and framework adapters. */
+  cookies?: CookieConfig;
+  /**
+   * Pipeline CSRF protection (H5). Defaults to `{ enabled: true }`.
+   * Bearer/API-key requests are exempt automatically — only cookie-auth
+   * traffic is checked. See {@link CsrfConfig}.
+   */
+  csrf?: CsrfConfig;
+  /**
+   * Optional pluggable logger. Accepts any object that conforms structurally
+   * to {@link FortressLogger} — a `pino()` instance, Fastify's `app.log`,
+   * or a hand-rolled `console` wrapper. Defaults to a silent no-op so
+   * Fortress never writes to stderr unless the caller opts in.
+   */
+  logger?: FortressLogger;
+  /**
+   * Optional telemetry provider (tracer + meter). Wire this to the
+   * OpenTelemetry adapter with `createOtelTelemetry` from the
+   * `@bajustone/fortress/otel` sub-path, or provide any custom
+   * implementation. Defaults to a zero-alloc no-op provider.
+   */
+  observability?: TelemetryProvider;
+}
+
+/** Validated cookie attributes resolved independently of `NODE_ENV`. */
+export interface ResolvedCookieConfig {
+  accessName: string;
+  refreshName: string;
+  sameSite: 'lax' | 'strict' | 'none';
+  secure: boolean;
+  domain?: string;
+  path: string;
+}
+
+/**
+ * Resolve a {@link CookieConfig} with secure, environment-independent defaults.
+ * Plain-HTTP localhost development must explicitly pass `secure: false`; this
+ * disables the `__Host-` default names because that prefix requires Secure.
+ */
+export function resolveCookieConfig(config?: CookieConfig): ResolvedCookieConfig {
+  // P3.7: default to `Secure` unless the caller explicitly opts out. Many
+  // production runtimes do not set NODE_ENV to 'production' (containers,
+  // serverless, Kubernetes Jobs), so falling back to NODE_ENV would leave
+  // cookies unprotected. Local HTTP development must now opt out
+  // explicitly via `cookies: { secure: false }`.
+  const secure = config?.secure ?? true;
+  const domain = config?.domain?.trim() || undefined;
+  // __Host- prefix requires Secure + Path=/ + no Domain (RFC 6265bis).
+  const canHostPrefix = secure && !domain && (config?.path ?? '/') === '/';
+  const defaultAccess = canHostPrefix ? '__Host-fortress_access' : 'fortress_access';
+  const defaultRefresh = canHostPrefix ? '__Host-fortress_refresh' : 'fortress_refresh';
+  const accessName = config?.accessName ?? defaultAccess;
+  const refreshName = config?.refreshName ?? defaultRefresh;
+  const sameSite = config?.sameSite ?? 'lax';
+  const path = config?.path ?? '/';
+
+  if (sameSite === 'none' && !secure)
+    throw new Error('Cookie SameSite=None requires Secure');
+
+  for (const name of [accessName, refreshName]) {
+    if (name.startsWith('__Secure-') && !secure)
+      throw new Error(`Cookie ${name} uses the __Secure- prefix but Secure is disabled`);
+    if (name.startsWith('__Host-') && (!secure || domain !== undefined || path !== '/')) {
+      throw new Error(`Cookie ${name} uses the __Host- prefix but requires Secure, Path=/, and no Domain`);
+    }
+  }
+
+  return {
+    accessName,
+    refreshName,
+    sameSite,
+    secure,
+    domain,
+    path,
+  };
+}
+
+/** Default JWT and RBAC settings applied when {@link FortressConfig} omits them. */
+export const DEFAULT_CONFIG = {
+  jwt: {
+    issuer: 'fortress',
+    accessTokenExpirySeconds: 900,
+    refreshTokenExpirySeconds: 604800,
+  },
+  rbac: {
+    evaluationMode: 'allow-only' as const,
+    resourceFile: './fortress.resources.json',
+  },
+} as const;