@bajustone/fortress 1.0.0-rc.1

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

@@ -0,0 +1,140 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+/**
+ * Pipeline CSRF check (H5) regression tests.
+ *
+ * Cover the matrix:
+ * - Safe methods always pass.
+ * - Bearer / API-key flows skip even when unsafe.
+ * - Cookie-authenticated POST with no CSRF header → 403.
+ * - Cookie-authenticated POST with valid CSRF header → passes.
+ * - `Sec-Fetch-Site: cross-site` → 403 regardless of header.
+ * - Opt-out via `csrf: { enabled: false }` disables the check.
+ */
+
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { assertSuccess } from '../types';
+
+interface LoginResult { accessToken: string; refreshToken: string }
+
+async function setup(csrf?: { enabled?: boolean }): Promise<{ fortress: Awaited<ReturnType<typeof createFortress>>; login: LoginResult }> {
+  const fortress = createFortress({
+    database: createTestAdapter(),
+    jwt: { key: 'x'.repeat(32) },
+    cookies: { secure: false },
+    csrf,
+  });
+  await fortress.auth.createUser({ email: 'csrf@test.com', name: 'C', password: 'pass-test-12345' });
+  const login = await fortress.auth.login('csrf@test.com', 'pass-test-12345');
+  assertSuccess(login);
+  return { fortress, login: { accessToken: login.accessToken!, refreshToken: login.refreshToken! } };
+}
+
+describe('pipeline CSRF check (H5)', () => {
+  let fortress: Awaited<ReturnType<typeof createFortress>>;
+  let login: LoginResult;
+
+  beforeEach(async () => {
+    ({ fortress, login } = await setup());
+  });
+
+  it('safe methods pass without CSRF header', async () => {
+    const res = await fortress.handleRequest(new Request('http://localhost/auth/me', {
+      headers: { cookie: `${fortress.cookies.accessName}=${login.accessToken}` },
+    }));
+    expect(res.status).toBe(200);
+  });
+
+  it('bearer POST passes without CSRF header', async () => {
+    const res = await fortress.handleRequest(new Request('http://localhost/auth/logout', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'authorization': `Bearer ${login.accessToken}`,
+      },
+      body: JSON.stringify({ refreshToken: login.refreshToken }),
+    }));
+    // Logout uses security:['none'] but cookie absence + bearer header
+    // means no cookie auth ambient credential — CSRF skipped.
+    expect(res.status).toBe(200);
+  });
+
+  it('rejects cross-site pre-authentication state changes without a cookie', async () => {
+    const res = await fortress.handleRequest(new Request('http://localhost/auth/login', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'sec-fetch-site': 'cross-site',
+      },
+      body: JSON.stringify({ identifier: 'csrf@example.com', password: 'password-123456' }),
+    }));
+    expect(res.status).toBe(403);
+  });
+
+  it('cookie POST without CSRF header is rejected (403)', async () => {
+    const res = await fortress.handleRequest(new Request('http://localhost/auth/logout', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'cookie': `${fortress.cookies.accessName}=${login.accessToken}`,
+      },
+      body: JSON.stringify({ refreshToken: login.refreshToken }),
+    }));
+    expect(res.status).toBe(403);
+  });
+
+  it('cookie POST with custom CSRF header passes', async () => {
+    const res = await fortress.handleRequest(new Request('http://localhost/auth/logout', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'cookie': `${fortress.cookies.accessName}=${login.accessToken}`,
+        'x-fortress-csrf': '1',
+      },
+      body: JSON.stringify({ refreshToken: login.refreshToken }),
+    }));
+    expect(res.status).toBe(200);
+  });
+
+  it('sec-fetch-site: cross-site is rejected even with the header', async () => {
+    const res = await fortress.handleRequest(new Request('http://localhost/auth/logout', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'cookie': `${fortress.cookies.accessName}=${login.accessToken}`,
+        'x-fortress-csrf': '1',
+        'sec-fetch-site': 'cross-site',
+      },
+      body: JSON.stringify({ refreshToken: login.refreshToken }),
+    }));
+    expect(res.status).toBe(403);
+  });
+
+  it('refresh-cookie-only request (expired access) is still CSRF-checked', async () => {
+    // A session whose access cookie has expired still carries the refresh
+    // cookie. Such a request has ambient credentials and must not slip the
+    // check by virtue of the access cookie being absent.
+    const res = await fortress.handleRequest(new Request('http://localhost/auth/logout', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'cookie': `${fortress.cookies.refreshName}=${login.refreshToken}`,
+      },
+      body: JSON.stringify({ refreshToken: login.refreshToken }),
+    }));
+    expect(res.status).toBe(403);
+  });
+
+  it('opting out via csrf.enabled=false disables the check', async () => {
+    const optedOut = await setup({ enabled: false });
+    const res = await optedOut.fortress.handleRequest(new Request('http://localhost/auth/logout', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'cookie': `${optedOut.fortress.cookies.accessName}=${optedOut.login.accessToken}`,
+      },
+      body: JSON.stringify({ refreshToken: optedOut.login.refreshToken }),
+    }));
+    expect(res.status).toBe(200);
+  });
+});

package/src/core/http/csrf.ts

@@ -0,0 +1,173 @@
+/**
+ * Pipeline-level CSRF protection.
+ *
+ * Activated by default for unsafe HTTP methods (`POST/PUT/PATCH/DELETE`)
+ * when the request authenticated via a Fortress auth cookie. Bearer-only
+ * and API-key requests are CSRF-immune by construction (no ambient
+ * credential the browser would auto-attach) and are skipped.
+ *
+ * The check is intentionally narrow:
+ *
+ * 1. Reject when `Sec-Fetch-Site: cross-site`. Modern browsers send this
+ *    header on every fetch — its presence + value is a reliable signal.
+ * 2. Reject when the required custom header (`X-Fortress-CSRF` by default)
+ *    is absent. Custom-header CSRF leverages the browser preflight rule:
+ *    a cross-origin request can't set the header without an explicit
+ *    server-side CORS allowance.
+ *
+ * Closes H5 — before this, `mountFortress` / `createSvelteKitHandle`
+ * dispatched straight to `handleRequest` with no CSRF check. This check now
+ * runs inside `handleRequest`, so every Fortress-managed route is covered
+ * regardless of adapter (Hono, Express, SvelteKit). The SvelteKit adapter's
+ * user-route silent token refresh — the one remaining Fortress state-change
+ * outside this pipeline — is independently gated to safe HTTP methods.
+ */
+
+import type { ResolvedCookieConfig } from '../config';
+import { Errors } from '../errors';
+import { parseCookieHeader } from './cookie-serialize';
+
+/** Resolved CSRF configuration. */
+export interface ResolvedCsrfConfig {
+  enabled: boolean;
+  headerName: string;
+  skipPaths: string[];
+  rejectSameSite: boolean;
+}
+
+/** User-facing CSRF configuration (all fields optional). */
+export interface CsrfConfig {
+  /**
+   * Set to `false` to disable the pipeline CSRF check entirely. Useful for
+   * pure bearer-only API deployments where no Fortress route is reachable
+   * with ambient credentials. Default: `true`.
+   */
+  enabled?: boolean;
+  /** Required header name. Default: `'X-Fortress-CSRF'`. */
+  headerName?: string;
+  /**
+   * Exact-path allow-list of routes the check should skip. Matched at
+   * segment boundaries (i.e. `'/foo'` matches `/foo` and `/foo/bar` but
+   * not `/foobar`).
+   */
+  skipPaths?: string[];
+  /**
+   * Additionally reject `Sec-Fetch-Site: same-site` requests. Single-host
+   * deployments (web app + Fortress on the same origin) can opt in to the
+   * stricter posture; multi-host (`api.example.com` + `app.example.com`)
+   * deployments leave this `false` so the legit app traffic passes.
+   * Default: `false`.
+   */
+  rejectSameSite?: boolean;
+}
+
+/** Resolve user-facing CSRF config against defaults. */
+export function resolveCsrfConfig(config?: CsrfConfig): ResolvedCsrfConfig {
+  return {
+    enabled: config?.enabled ?? true,
+    headerName: config?.headerName ?? 'X-Fortress-CSRF',
+    skipPaths: config?.skipPaths ?? [],
+    rejectSameSite: config?.rejectSameSite ?? false,
+  };
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/**
+ * Test whether `path` falls under any of the configured skip paths,
+ * matched at segment boundaries (so `/foo` doesn't accidentally skip
+ * `/foobar`).
+ */
+function matchesSkipPath(path: string, skipPaths: string[]): boolean {
+  for (const skip of skipPaths) {
+    if (path === skip)
+      return true;
+    if (path.startsWith(`${skip}/`))
+      return true;
+  }
+  return false;
+}
+
+/**
+ * Detect whether the request authenticated through a Fortress auth
+ * cookie. We treat cookie-based auth as "browser ambient credentials
+ * exist" — the only condition under which a cross-site request can use
+ * the user's session.
+ */
+function isCookieAuthenticated(
+  request: Request,
+  cookies: ResolvedCookieConfig,
+): boolean {
+  const jar = parseCookieHeader(request.headers.get('cookie'));
+  // Either cookie counts as ambient credentials. A session whose access
+  // cookie has expired still carries a valid refresh cookie, and adapters
+  // can silently rotate it — so a refresh-only request is just as
+  // CSRF-exposed as an access-cookie request.
+  const hasCookie = (name: string): boolean =>
+    typeof jar[name] === 'string' && jar[name].length > 0;
+  return hasCookie(cookies.accessName) || hasCookie(cookies.refreshName);
+}
+
+/**
+ * Enforce CSRF on unsafe, cookie-authenticated requests. Throws
+ * {@link FortressError} (403) when the request is rejected. Returns
+ * silently when the request is safe or the check is bypassed.
+ */
+export function enforceCsrf(
+  request: Request,
+  pathname: string,
+  csrf: ResolvedCsrfConfig,
+  cookies: ResolvedCookieConfig,
+): void {
+  if (!csrf.enabled)
+    return;
+
+  // GET/HEAD/OPTIONS are safe-by-method per RFC 9110.
+  if (SAFE_METHODS.has(request.method.toUpperCase()))
+    return;
+
+  if (matchesSkipPath(pathname, csrf.skipPaths))
+    return;
+
+  const fetchSite = request.headers.get('sec-fetch-site');
+  const cookieAuthenticated = isCookieAuthenticated(request, cookies);
+
+  // Pre-authentication endpoints still need login-CSRF protection: a hostile
+  // site can otherwise submit its own credentials and bind the victim's
+  // browser to the attacker's account. Browser cross-site signals are checked
+  // even before an auth cookie exists; non-browser bearer/API-key clients do
+  // not send these ambient-browser headers and remain unaffected.
+  if (!cookieAuthenticated) {
+    // Explicit credentials are not ambient browser authority and therefore
+    // are not vulnerable to CSRF, even when sent cross-origin intentionally.
+    if (request.headers.has('authorization') || request.headers.has('x-api-key'))
+      return;
+    if (fetchSite === 'cross-site')
+      throw Errors.forbidden('CSRF: cross-site request rejected');
+    const origin = request.headers.get('origin');
+    if (origin) {
+      try {
+        if (new URL(origin).origin !== new URL(request.url).origin)
+          throw Errors.forbidden('CSRF: cross-origin request rejected');
+      }
+      catch (error) {
+        if (error instanceof Error && 'code' in error)
+          throw error;
+        throw Errors.forbidden('CSRF: invalid Origin header');
+      }
+    }
+    return;
+  }
+
+  // Cookie-authenticated browser requests additionally require the custom
+  // header, which forces a CORS preflight for cross-origin JavaScript.
+
+  if (fetchSite === 'cross-site')
+    throw Errors.forbidden('CSRF: cross-site request rejected');
+  if (csrf.rejectSameSite && fetchSite === 'same-site')
+    throw Errors.forbidden('CSRF: same-site request rejected');
+
+  const tokenHeader = request.headers.get(csrf.headerName);
+  if (!tokenHeader)
+    throw Errors.forbidden(`CSRF: missing ${csrf.headerName} header`);
+}