@bajustone/fortress 1.0.0-rc.1

package/src/core/http/protect.test.ts

@@ -0,0 +1,220 @@
+import type { EndpointDefinition } from '../endpoint';
+import type { FortressPlugin } from '../plugin';
+import type { ProtectedRouteContext } from './protect';
+import { describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { buildRouteManifest } from '../manifest/route-manifest';
+import { endpoint, id, int, obj, str } from '../schema-builder';
+import { protect } from './protect';
+
+/** Compile-time assertion that two types are identical. */
+type Expect<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+const secret = 'test-secret-minimum-32-bytes-long!!';
+
+function testEndpoint(): EndpointDefinition {
+  return {
+    method: 'POST',
+    path: '/host/things/:id',
+    handler: 'createHostThing',
+    meta: { summary: 'Create host thing', security: ['none'] },
+    input: {
+      body: obj({ name: str() }, 'name'),
+      bodySchema: obj({ name: str() }, 'name'),
+      query: obj({ draft: str() }),
+      querySchema: obj({ draft: str() }),
+      params: obj({ id: id() }, 'id'),
+      paramsSchema: obj({ id: id() }, 'id'),
+    },
+    responses: { 201: { description: 'Created', schema: obj({ ok: str() }, 'ok') } },
+  };
+}
+
+describe('protect()', () => {
+  it('runs plugin middleware, validates/coerces input, and calls the host handler', async () => {
+    const calls: string[] = [];
+    const ep = testEndpoint();
+    const plugin: FortressPlugin = {
+      name: 'host-routes',
+      routes: { createHostThing: ep },
+      middleware: [
+        {
+          path: '/host/things/:id',
+          position: 'before-auth',
+          handler: async (_ctx, _request, next) => {
+            calls.push('before-auth');
+            await next();
+          },
+        },
+        {
+          path: '/host/things/:id',
+          position: 'after-auth',
+          handler: async (_ctx, _request, next) => {
+            calls.push('after-auth');
+            await next();
+          },
+        },
+        {
+          path: '/host/things/:id',
+          position: 'after-rbac',
+          handler: async (_ctx, _request, next) => {
+            calls.push('after-rbac');
+            await next();
+          },
+        },
+      ],
+    };
+    const fortress = createFortress({
+      database: createTestAdapter(),
+      jwt: { key: secret },
+      csrf: { enabled: false },
+      plugins: [plugin],
+    });
+
+    const handler = protect(fortress, 'createHostThing', (ctx) => {
+      expect(ctx.manifest.classification).toBe('public');
+      expect(ctx.input).toEqual({ name: 'alpha', draft: 'true', id: '123' });
+      expect(ctx.params).toEqual({ id: '123' });
+      return { ok: 'yes' };
+    });
+
+    const res = await handler(new Request('http://localhost/host/things/123?draft=true', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'alpha' }),
+    }));
+
+    expect(res.status).toBe(201);
+    expect(await res.json()).toEqual({ ok: 'yes' });
+    expect(calls).toEqual(['before-auth', 'after-auth', 'after-rbac']);
+  });
+
+  it('authenticates JWTs and enforces RBAC for permission-only host handlers', async () => {
+    const ep = {
+      method: 'GET',
+      path: '/reports/:id',
+      handler: 'readReport',
+      meta: {
+        summary: 'Read report',
+        permission: { resource: 'report', action: 'read' },
+      },
+      input: {
+        params: obj({ id: id() }, 'id'),
+        paramsSchema: obj({ id: id() }, 'id'),
+      },
+      responses: { 200: { description: 'OK' } },
+    } as EndpointDefinition;
+    const checked: unknown[] = [];
+    const fortress = {
+      endpoints: [ep],
+      config: { plugins: [], csrf: { enabled: false }, database: createTestAdapter() },
+      cookies: { accessName: 'fortress_access', refreshName: 'fortress_refresh' },
+      get manifest() { return buildRouteManifest(this as any); },
+      auth: {
+        verifyToken: async () => ({
+          sub: '7',
+          subjectType: 'USER',
+          name: 'User',
+          groups: [],
+          iss: 'test',
+          iat: 1,
+          exp: 2,
+        }),
+      },
+      iam: {
+        checkPermission: async (...args: unknown[]) => {
+          checked.push(args);
+          return true;
+        },
+      },
+      extractAccessToken: (request: Request) => request.headers.get('authorization')?.replace('Bearer ', '') ?? null,
+      serializeAuthCookies: () => [],
+      logger: undefined,
+    };
+
+    const handler = protect(fortress as any, ep, ctx => ({ subject: ctx.subject, input: ctx.input }));
+    const res = await handler(new Request('http://localhost/reports/42', {
+      headers: { Authorization: 'Bearer token' },
+    }));
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      subject: { type: 'USER', id: '7' },
+      input: { id: '42' },
+    });
+    expect(checked).toHaveLength(1);
+    expect(checked[0]).toEqual([{ type: 'USER', id: '7' }, 'report', 'read', { credentialScopes: undefined }]);
+  });
+
+  it('attaches auth cookies for token-shaped handler results', async () => {
+    const ep = testEndpoint();
+    const fortress = createFortress({
+      database: createTestAdapter(),
+      jwt: { key: secret },
+      csrf: { enabled: false },
+      plugins: [{ name: 'host-routes', routes: { createHostThing: ep } }],
+      cookies: { secure: false },
+    });
+
+    const handler = protect(fortress, ep, () => ({ accessToken: 'access', refreshToken: 'refresh' }));
+    const res = await handler(new Request('http://localhost/host/things/1', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'alpha' }),
+    }));
+
+    expect(res.headers.getSetCookie().length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('exposes ctx.respond for typed non-success status returns', async () => {
+    const ep = testEndpoint();
+    const fortress = createFortress({
+      database: createTestAdapter(),
+      jwt: { key: secret },
+      csrf: { enabled: false },
+      plugins: [{ name: 'host-routes', routes: { createHostThing: ep } }],
+      cookies: { secure: false },
+    });
+
+    const handler = protect(fortress, ep, (ctx) => {
+      return ctx.respond(404, { code: 'NOT_FOUND', message: 'no thing', statusCode: 404 } as any);
+    });
+
+    const res = await handler(new Request('http://localhost/host/things/1', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'alpha' }),
+    }));
+
+    expect(res.status).toBe(404);
+    expect(await res.json()).toEqual({ code: 'NOT_FOUND', message: 'no thing', statusCode: 404 });
+  });
+
+  it('narrows ctx.body to non-optional T when a body schema is declared (type-level)', () => {
+    const withBody = endpoint('POST', '/things')
+      .body(obj({ name: str() }, 'name'))
+      .response(201, 'Created', obj({ ok: str() }, 'ok'))
+      .handler('createThing')
+      .build();
+    const noBody = endpoint('GET', '/things/:id')
+      .params(obj({ id: int() }, 'id'))
+      .response(200, 'OK', obj({ ok: str() }, 'ok'))
+      .handler('getThing')
+      .build();
+
+    type WithBodyCtx = ProtectedRouteContext<typeof withBody>;
+    type NoBodyCtx = ProtectedRouteContext<typeof noBody>;
+
+    // Declared body schema → non-optional `{ name: string }` (no `| undefined`).
+    const _bodyNonOptional: Expect<WithBodyCtx['body'], { name: string }> = true;
+    // No body schema → loose `unknown`.
+    const _bodyLoose: Expect<NoBodyCtx['body'], unknown> = true;
+
+    // Touch the runtime values so they aren't flagged as type-only.
+    expect(withBody.handler).toBe('createThing');
+    expect(noBody.handler).toBe('getThing');
+    expect(_bodyNonOptional).toBe(true);
+    expect(_bodyLoose).toBe(true);
+  });
+});

package/src/core/http/protect.ts

@@ -0,0 +1,394 @@
+/**
+ * Host-owned route protection.
+ *
+ * Lets adapters and framework-less hosts run the same Fortress security
+ * pipeline used by `fortress.handleRequest()` around handlers they register
+ * themselves: plugin middleware, CSRF, principal resolution, RBAC,
+ * validation, and auth-cookie attachment.
+ */
+
+import type {
+  EndpointDefinition,
+  InferEndpointBody,
+  InferEndpointCallInput,
+  InferEndpointParams,
+  InferEndpointQuery,
+  InferEndpointResponses,
+} from '../endpoint';
+import type { Fortress } from '../fortress';
+import type { RouteManifestEntry } from '../manifest/route-manifest';
+import type { Subject, TokenClaims } from '../types';
+import { Errors, FortressError } from '../errors';
+import { coerceBySchema, validateRequest } from '../validation';
+import { enforceCsrf, resolveCsrfConfig } from './csrf';
+import { errorToResponse, withCookies } from './error-response';
+import { enforceFortressPermission } from './fortress-rbac';
+import { buildRouteTable, matchRoute } from './match';
+import { runPluginMiddleware } from './plugin-middleware';
+import { tryPluginPrincipal } from './principal';
+
+/**
+ * What you point `protect()` at: an `EndpointDefinition` (preferred — its
+ * phantom `<TBody, TQuery, TParams, TResponses>` types flow into the
+ * `ProtectedRouteContext`) or a handler name from `fortress.endpoints`
+ * (looser typing, falls back to `Record<string, unknown>` / `unknown`).
+ */
+
+export type ProtectedRouteTarget<E extends EndpointDefinition<any, any, any, any> = EndpointDefinition>
+  = string | E;
+
+/**
+ * Widen `{}` (the `EndpointDefinition` default for an unspecified input slot)
+ * back to `Record<string, unknown>` so adapter callers that pass a string
+ * target — or an untyped `EndpointDefinition` — keep the loose ergonomics
+ * they had before generics existed. A real declared schema produces a
+ * narrow object type, which passes through unchanged.
+ */
+type WidenObj<T> = [keyof T] extends [never] ? Record<string, unknown> : T;
+
+export interface ProtectOptions {
+  /**
+   * Canonical path to use for plugin middleware / CSRF matching when the
+   * host-owned route is mounted at a path different from the endpoint path.
+   * Defaults to the incoming request pathname.
+   */
+  path?: string;
+  /** Override HTTP method for manifest lookup. Defaults to request.method. */
+  method?: string;
+  /** Explicit params for host paths that do not match the endpoint path. */
+  params?: Record<string, string>;
+  /** Attach auth cookies when the handler returns `{ accessToken, refreshToken? }`. Default `true`. */
+  attachAuthCookies?: boolean;
+}
+
+/**
+ * Per-request context handed to the host callback. When `target` is a
+ * typed `EndpointDefinition`, `body` / `query` / `params` / `input` are
+ * inferred from its phantom generics; when `target` is a handler name
+ * string, they fall back to `Record<string, unknown>` / `unknown`.
+ */
+export interface ProtectedRouteContext<
+
+  E extends EndpointDefinition<any, any, any, any> = EndpointDefinition,
+> {
+  request: Request;
+  /** The resolved endpoint definition (typed when the target was typed). */
+  endpoint: E;
+  manifest: RouteManifestEntry;
+  subject?: Subject;
+  userId?: string;
+  claims?: TokenClaims;
+  scopes?: string[] | null;
+  params: WidenObj<InferEndpointParams<E>>;
+  query: WidenObj<InferEndpointQuery<E>>;
+  /**
+   * Parsed request body.
+   *
+   * When the endpoint declares a body schema, the handler only runs after
+   * that body passes Standard Schema validation, so `body` is narrowed to a
+   * non-optional `T` — use it directly without `!` or reaching for
+   * `ctx.input`. Endpoints with no declared body schema fall back to the
+   * loose `unknown` (which still admits `undefined`), matching the
+   * pre-generics ergonomics for string / untyped targets.
+   */
+  body: [keyof InferEndpointBody<E>] extends [never]
+    ? unknown
+    : InferEndpointBody<E>;
+  /**
+   * Merged `{ ...body, ...query, ...params }` input after URL coercion.
+   * Typed as the same intersection the `fortress.call.*` proxy uses.
+   */
+  input: [keyof InferEndpointCallInput<E>] extends [never]
+    ? Record<string, unknown>
+    : InferEndpointCallInput<E>;
+  /**
+   * Build a typed JSON response for a status declared on the endpoint.
+   *
+   * When `target` was a typed `EndpointDefinition`, `status` is narrowed
+   * to the response codes that endpoint actually declares and `body` is
+   * narrowed to that response's schema output. Use this instead of
+   * hand-rolling `new Response(JSON.stringify(...), { status })` for
+   * non-2xx returns:
+   *
+   * ```ts
+   * protectedRoute(fortress, getSchool, async (ctx) => {
+   *   const school = await loadSchool(ctx.params.id);
+   *   if (!school)
+   *     return ctx.respond(404, { code: 'NOT_FOUND', message: 'School not found', statusCode: 404 });
+   *   return { data: school };  // 2xx success returned as a plain object
+   * });
+   * ```
+   *
+   * For string-target / untyped endpoints, both arguments fall back to
+   * `number` / `unknown`, matching the loose ergonomics elsewhere in the
+   * context.
+   */
+  respond: [keyof InferEndpointResponses<E>] extends [never]
+    ? (status: number, body: unknown) => Response
+    : <S extends keyof InferEndpointResponses<E> & number>(
+        status: S,
+        body: InferEndpointResponses<E>[S],
+      ) => Response;
+}
+
+export type ProtectedRouteHandler<
+
+  E extends EndpointDefinition<any, any, any, any> = EndpointDefinition,
+  TResult = unknown,
+> = (
+  ctx: ProtectedRouteContext<E>,
+) => TResult | Response | Promise<TResult | Response>;
+
+function targetLabel(target: ProtectedRouteTarget): string {
+  return typeof target === 'string' ? target : `${target.method} ${target.path}`;
+}
+
+function routeKey(route: Pick<EndpointDefinition, 'method' | 'path'>): string {
+  return `${route.method.toUpperCase()} ${route.path}`;
+}
+
+function findEndpoint(fortress: Fortress, target: ProtectedRouteTarget, method?: string): EndpointDefinition {
+  if (typeof target !== 'string') {
+    return target;
+  }
+
+  const matches = fortress.endpoints.filter(endpoint => endpoint.handler === target);
+  if (matches.length === 0)
+    throw Errors.notFound(`No endpoint found for handler '${target}'`);
+
+  if (method) {
+    const byMethod = matches.find(endpoint => endpoint.method.toUpperCase() === method.toUpperCase());
+    if (byMethod)
+      return byMethod;
+  }
+
+  if (matches.length > 1) {
+    throw Errors.badRequest(
+      `Handler '${target}' maps to multiple endpoints; pass the EndpointDefinition or ProtectOptions.method.`,
+    );
+  }
+
+  return matches[0];
+}
+
+function findManifestEntry(fortress: Fortress, endpoint: EndpointDefinition): RouteManifestEntry {
+  const key = routeKey(endpoint);
+  const entry = fortress.manifest.find(route => `${route.method.toUpperCase()} ${route.path}` === key);
+  if (!entry)
+    throw Errors.notFound(`No route manifest entry found for ${key}`);
+  return entry;
+}
+
+function rewriteRequestPath(request: Request, pathname: string): Request {
+  const current = new URL(request.url);
+  if (current.pathname === pathname)
+    return request;
+  const rewritten = new URL(request.url);
+  rewritten.pathname = pathname;
+  return new Request(rewritten, request);
+}
+
+async function parseJsonBody(request: Request): Promise<unknown> {
+  if (request.method === 'GET' || request.method === 'HEAD')
+    return undefined;
+  if (!(request.headers.get('content-type') ?? '').includes('json'))
+    return undefined;
+  return request.clone().json().catch(() => undefined);
+}
+
+function objectOrEmpty(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function successStatus(endpoint: EndpointDefinition): number {
+  const status = Object.keys(endpoint.responses ?? {})
+    .map(Number)
+    .find(code => code >= 200 && code < 300);
+  return status ?? 200;
+}
+
+function jsonResponse(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body ?? { ok: true }), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+function maybeAttachAuthCookies(fortress: Fortress, result: Response | unknown, response: Response): Response {
+  if (result instanceof Response)
+    return response;
+  const obj = result as { accessToken?: unknown; refreshToken?: unknown } | undefined;
+  if (typeof obj?.accessToken !== 'string')
+    return response;
+  return withCookies(response, fortress.serializeAuthCookies({
+    accessToken: obj.accessToken,
+    refreshToken: typeof obj.refreshToken === 'string' ? obj.refreshToken : null,
+  }));
+}
+
+/**
+ * Build a web-standard protected route handler for a host-owned route.
+ * Adapter-specific helpers wrap this function for Hono, Express, and
+ * SvelteKit ergonomics.
+ *
+ * Two overloads:
+ *
+ * - **Typed target** — pass an `EndpointDefinition` (e.g. the value produced
+ *   by `endpoint(...).build()`). Its `<TBody, TQuery, TParams, TResponses>`
+ *   phantoms flow into `ctx.body` / `ctx.query` / `ctx.params` / `ctx.input`.
+ * - **String target** — pass a unique `handler` name. Inputs fall back to
+ *   `Record<string, unknown>` / `unknown`, matching pre-0.2.x behaviour.
+ *
+ * The runtime is identical in both forms; this is purely typing.
+ */
+export function protect<
+
+  E extends EndpointDefinition<any, any, any, any>,
+  TResult = unknown,
+>(
+  fortress: Fortress,
+  target: E,
+  handler: ProtectedRouteHandler<E, TResult>,
+  options?: ProtectOptions,
+): (request: Request) => Promise<Response>;
+export function protect<TResult = unknown>(
+  fortress: Fortress,
+  target: string,
+  handler: ProtectedRouteHandler<EndpointDefinition, TResult>,
+  options?: ProtectOptions,
+): (request: Request) => Promise<Response>;
+export function protect(
+  fortress: Fortress,
+  target: ProtectedRouteTarget,
+
+  handler: ProtectedRouteHandler<any, unknown>,
+  options: ProtectOptions = {},
+): (request: Request) => Promise<Response> {
+  const endpoint = findEndpoint(fortress, target, options.method);
+  const manifest = findManifestEntry(fortress, endpoint);
+  const endpointRouteTable = buildRouteTable([endpoint]);
+  const csrfConfig = resolveCsrfConfig(fortress.config.csrf);
+  const plugins = fortress.config.plugins ?? [];
+
+  return async function protectedRequestHandler(request: Request): Promise<Response> {
+    let response: Response | undefined;
+    try {
+      const url = new URL(request.url);
+      const pipelinePath = options.path ?? url.pathname;
+      const pipelineRequest = rewriteRequestPath(request, pipelinePath);
+
+      await runPluginMiddleware(plugins, fortress.config, 'before-auth', { request: pipelineRequest });
+      enforceCsrf(pipelineRequest, pipelinePath, csrfConfig, fortress.cookies);
+
+      let subject: Subject | undefined;
+      let userId: string | undefined;
+      let claims: TokenClaims | undefined;
+      let scopes: string[] | null | undefined;
+      const selfManagedBearer = endpoint.meta?.bearerKind === 'oauth';
+
+      if (!selfManagedBearer) {
+        const pluginResolved = await tryPluginPrincipal(fortress, pipelineRequest);
+        if (pluginResolved) {
+          subject = pluginResolved.subject;
+          claims = pluginResolved.claims;
+          scopes = pluginResolved.scopes;
+        }
+      }
+
+      const requiresBearer = !selfManagedBearer
+        && ((endpoint.meta?.security?.includes('bearer') ?? false) || !!endpoint.meta?.permission);
+      if (!subject && requiresBearer) {
+        const token = fortress.extractAccessToken(pipelineRequest);
+        if (!token)
+          throw Errors.unauthorized('Missing access token');
+        try {
+          claims = await fortress.auth.verifyToken(token);
+          subject = { type: claims.subjectType, id: claims.sub };
+        }
+        catch (err) {
+          if (err instanceof FortressError)
+            throw err;
+          throw Errors.unauthorized('Invalid access token');
+        }
+      }
+
+      if (subject?.type === 'USER')
+        userId = subject.id;
+
+      await runPluginMiddleware(plugins, fortress.config, 'after-auth', {
+        request: pipelineRequest,
+        fortressSubject: subject,
+        fortressUserId: userId,
+        fortressClaims: claims,
+        fortressScopes: scopes,
+      });
+
+      if (!selfManagedBearer) {
+        await enforceFortressPermission(endpoint, subject, {
+          checkPermission: (subj, resource, action, credentialScopes): Promise<boolean> =>
+            fortress.iam.checkPermission(subj, resource, action, { credentialScopes }),
+        }, scopes);
+      }
+
+      await runPluginMiddleware(plugins, fortress.config, 'after-rbac', {
+        request: pipelineRequest,
+        fortressSubject: subject,
+        fortressUserId: userId,
+        fortressClaims: claims,
+        fortressScopes: scopes,
+      });
+
+      const body = await parseJsonBody(request);
+      const rawQuery = Object.fromEntries(url.searchParams);
+      const match = matchRoute(endpointRouteTable, endpoint.method, options.path ?? url.pathname);
+      const rawParams = options.params ?? match?.params ?? {};
+      const query = coerceBySchema(endpoint.input?.query, rawQuery) ?? rawQuery;
+      const params = coerceBySchema(endpoint.input?.params, rawParams) ?? rawParams;
+      await validateRequest(endpoint.input, { body, query, params });
+
+      const input = { ...objectOrEmpty(body), ...query, ...params };
+      const result = await handler({
+        request,
+        endpoint,
+        manifest,
+        subject,
+        userId,
+        claims,
+        scopes,
+        params,
+        query,
+        body,
+        input,
+        respond: (status: number, responseBody: unknown) => jsonResponse(responseBody, status),
+        // Cast: the runtime values are untyped records; the generic context
+        // type narrows them for the caller, but the impl signature uses the
+        // loose `ProtectedRouteContext<EndpointDefinition>`.
+      } as ProtectedRouteContext);
+
+      response = result instanceof Response ? result : jsonResponse(result, successStatus(endpoint));
+      if (options.attachAuthCookies ?? true)
+        response = maybeAttachAuthCookies(fortress, result, response);
+      return response;
+    }
+    catch (err) {
+      response = errorToResponse(err, fortress.logger);
+      return response;
+    }
+  };
+}
+
+/** Resolve an endpoint eagerly; useful for adapter wrappers and diagnostics. */
+export function resolveProtectedEndpoint(
+  fortress: Fortress,
+  target: ProtectedRouteTarget,
+  method?: string,
+): EndpointDefinition {
+  return findEndpoint(fortress, target, method);
+}
+
+/** Human-readable name for errors/logs. */
+export function describeProtectedTarget(target: ProtectedRouteTarget): string {
+  return targetLabel(target);
+}

package/src/core/http/token-extraction.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { resolveCookieConfig } from '../config';
+import { extractAccessToken, extractRefreshToken } from './token-extraction';
+
+const cookies = resolveCookieConfig({ secure: false }); // dev defaults: fortress_access / fortress_refresh
+
+function req(headers: Record<string, string>): Request {
+  return new Request('http://localhost/', { headers });
+}
+
+describe('extractAccessToken', () => {
+  it('reads the access token from the configured cookie first', () => {
+    const r = req({ cookie: 'fortress_access=cookie-token' });
+    expect(extractAccessToken(r, cookies)).toBe('cookie-token');
+  });
+
+  it('falls back to Authorization: Bearer when no cookie', () => {
+    const r = req({ authorization: 'Bearer header-token' });
+    expect(extractAccessToken(r, cookies)).toBe('header-token');
+  });
+
+  it('accepts the case-insensitive Bearer authentication scheme', () => {
+    const r = req({ authorization: 'bearer lowercase-token' });
+    expect(extractAccessToken(r, cookies)).toBe('lowercase-token');
+  });
+
+  it('prefers Authorization header over cookie (P3.7 — cookie-shadow fix)', () => {
+    const r = req({
+      cookie: 'fortress_access=cookie-token',
+      authorization: 'Bearer header-token',
+    });
+    expect(extractAccessToken(r, cookies)).toBe('header-token');
+  });
+
+  it('returns null when neither source has a token', () => {
+    expect(extractAccessToken(req({}), cookies)).toBeNull();
+  });
+
+  it('ignores non-Bearer Authorization headers', () => {
+    const r = req({ authorization: 'Basic dXNlcjpwYXNz' });
+    expect(extractAccessToken(r, cookies)).toBeNull();
+  });
+});
+
+describe('extractRefreshToken', () => {
+  it('reads the refresh token from the cookie jar', () => {
+    const r = req({ cookie: 'fortress_refresh=rtoken' });
+    expect(extractRefreshToken(r, cookies)).toBe('rtoken');
+  });
+
+  it('returns null when no refresh cookie present', () => {
+    expect(extractRefreshToken(req({}), cookies)).toBeNull();
+  });
+
+  it('does NOT fall back to Authorization header', () => {
+    const r = req({ authorization: 'Bearer some-token' });
+    expect(extractRefreshToken(r, cookies)).toBeNull();
+  });
+});