create-ailk 0.11.0 → 0.11.2

package/templates/apps/api/src/__tests__/cors.test.ts

@@ -44,7 +44,7 @@ const DRAFT_PATCH_URL = "/v1/project-listings/drafts/listing_abc123";
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any avoids pulling in the full FastifyInstance type here
 type App = any;
 
-const ENV_KEYS = ["FRONTEND_URL", "NODE_ENV"] as const;
+const ENV_KEYS = ["FRONTEND_URL", "AILK_TRUSTED_ORIGINS", "NODE_ENV"] as const;
 
 /**
  * Build a server whose `config` was resolved from `env`. Restores the prior
@@ -52,6 +52,7 @@ const ENV_KEYS = ["FRONTEND_URL", "NODE_ENV"] as const;
  */
 async function buildWith(env: {
   FRONTEND_URL?: string;
+  AILK_TRUSTED_ORIGINS?: string;
   NODE_ENV: string;
 }): Promise<App> {
   for (const key of ENV_KEYS) {
@@ -147,18 +148,19 @@ describe("CORS preflight (#5397)", () => {
     // ACT
     const response = await preflight(app, FOREIGN_ORIGIN, "PATCH");
 
-    // ASSERT — with a STRING `origin` option, @fastify/cors echoes the
-    // configured origin rather than the requester's
-    // (`getAccessControlAllowOriginHeader`), and the refusal is the browser's:
-    // it blocks any response whose allow-origin is not its own origin. So the
-    // contract to pin is that the foreign origin is never named back, and the
-    // wildcard never appears — `credentials: true` with `*` would let any site
-    // read credentialed responses (the security-review M1 posture server.ts
-    // already documents). Widening `methods` must not widen WHO may use them.
+    // ASSERT — the refusal is the browser's: it blocks any response whose
+    // allow-origin is not its own origin. So the contract to pin is that the
+    // foreign origin is never named back, and the wildcard never appears —
+    // `credentials: true` with `*` would let any site read credentialed
+    // responses (the security-review M1 posture server.ts already documents).
+    // Widening `methods` must not widen WHO may use them. With the ARRAY
+    // `origin` option (#7395 D4), @fastify/cors writes no allow-origin header
+    // at all for an unlisted origin (D6.4); before #7395 it echoed the one
+    // configured string.
     const allowOrigin = response.headers["access-control-allow-origin"];
     expect(allowOrigin).not.toBe(FOREIGN_ORIGIN);
     expect(allowOrigin).not.toBe("*");
-    expect(allowOrigin).toBe(FRONTEND_URL);
+    expect(allowOrigin).toBeUndefined();
   });
 
   it("advertises every method the registered route table actually serves", async () => {
@@ -193,3 +195,82 @@ describe("CORS preflight (#5397)", () => {
     }
   });
 });
+
+// ── #7395 — the trusted-origin allowlist (AC-4) ──────────────────────────────
+//
+// One deployment serves the hub site, its Admin app and every spoke, so CORS
+// answers for each origin the operator listed in FRONTEND_URL or
+// AILK_TRUSTED_ORIGINS, and for no other — in development as in production,
+// since the reflect-any dev arm is gone (D4). A credentialed GET, not only a
+// preflight, carries the header, so a hand-written OPTIONS route cannot pass.
+
+describe("CORS trusted-origin allowlist (#7395)", () => {
+  const HUB = "https://hub.example";
+  const SPOKE_A = "https://spoke-a.example";
+  const priorEnv = new Map<string, string | undefined>(
+    ENV_KEYS.map((key) => [key, process.env[key]]),
+  );
+  let app: App;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+    for (const [key, value] of priorEnv) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    jest.resetModules();
+  });
+
+  describe.each(["production", "development"])("NODE_ENV=%s", (nodeEnv) => {
+    beforeEach(async () => {
+      app = await buildWith({
+        FRONTEND_URL: HUB,
+        AILK_TRUSTED_ORIGINS: SPOKE_A,
+        NODE_ENV: nodeEnv,
+      });
+    });
+
+    it("allows a PATCH preflight from a listed spoke, with credentials and Vary: Origin", async () => {
+      const response = await preflight(app, SPOKE_A, "PATCH");
+
+      expect(response.headers["access-control-allow-origin"]).toBe(SPOKE_A);
+      expect(response.headers["access-control-allow-credentials"]).toBe(
+        "true",
+      );
+      expect(String(response.headers["vary"] ?? "")).toMatch(/\bOrigin\b/i);
+      expect(allowedMethods(response)).toContain("PATCH");
+    });
+
+    it("names a listed spoke on a credentialed GET, not only on a preflight", async () => {
+      const response = await app.inject({
+        method: "GET",
+        url: "/health",
+        headers: { origin: SPOKE_A, cookie: "better-auth.session_token=x" },
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers["access-control-allow-origin"]).toBe(SPOKE_A);
+      expect(response.headers["access-control-allow-credentials"]).toBe(
+        "true",
+      );
+    });
+
+    it("still allows the primary FRONTEND_URL origin", async () => {
+      const response = await preflight(app, HUB, "PATCH");
+
+      expect(response.headers["access-control-allow-origin"]).toBe(HUB);
+    });
+
+    it("writes no allow-origin header for an unlisted origin", async () => {
+      const response = await preflight(app, FOREIGN_ORIGIN, "PATCH");
+
+      expect(response.headers["access-control-allow-origin"]).toBeUndefined();
+    });
+  });
+});

package/templates/apps/api/src/__tests__/server.test.ts

@@ -474,7 +474,8 @@ describe("#6216 D11 — a lead_… path segment is truncated to 8 characters, cs
 //
 // POST /v1/checkout/sessions admits a caller without X-Internal-Auth when
 // OSS_API_INTERNAL_SECRET is unset, and with FRONTEND_URL unset its redirect
-// lock answers 500 while the CORS/cookie origin checks pin to localhost. Both
+// lock answers 500 while CORS and cookie writes trust only AILK_TRUSTED_ORIGINS
+// (#7395 D5; before #7395 they pinned to localhost). Both
 // are optional by design (OSS standalone compat), so startup must never fail
 // on them — but a production boot says so, once per variable. Each case rebuilds the module graph because `config/index.ts`
 // snapshots NODE_ENV at import time.
@@ -545,6 +546,9 @@ describe("#6889 — production startup warns on an unset FRONTEND_URL or OSS_API
     });
     expect(naming(messages, "FRONTEND_URL")).toHaveLength(1);
     expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(0);
+    // #7395 D5 — nothing is pinned to localhost any more; an unset
+    // FRONTEND_URL in production trusts only AILK_TRUSTED_ORIGINS.
+    expect(naming(messages, "FRONTEND_URL")[0]).not.toContain("localhost:3000");
   });
 
   it("warns exactly once naming OSS_API_INTERNAL_SECRET when it is unset in production", async () => {

package/templates/apps/api/src/__tests__/trusted-origins.server.test.ts

@@ -0,0 +1,135 @@
+/**
+ * @file trusted-origins.server.test.ts
+ * @description A spoke's cookie-forwarded write through the REAL server (#7395 AC-8).
+ *
+ * The defect #7395 reports: a spoke renders `/account` against the hub API and
+ * forwards the visitor's cookie with the browser's own `Origin`, and every
+ * write came back 401 because the auth preHandler compared that `Origin` with
+ * `===` against the one `FRONTEND_URL`. The unit suites build the plugin
+ * options themselves, so only a boot through `build()` sees what `server.ts`
+ * actually wires — `trustedOrigins: [config.FRONTEND_URL]` would pass every
+ * one of them and still refuse the spoke here.
+ *
+ * Each case rebuilds the module graph (`jest.resetModules()`) because
+ * `config/index.ts` resolves the allowlist at import time.
+ */
+
+// Mocked for the same reasons cors.test.ts gives: rate-limit wants a live
+// store, and @working-theory/email pulls an ESM-only transitive dep.
+jest.mock("@fastify/rate-limit", () => jest.fn().mockResolvedValue(undefined));
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted; the DB boundary, mirrors auth.cookie-path.test.ts
+jest.mock("../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    apiToken: {
+      findUnique: jest.fn(),
+      create: jest.fn(),
+      update: jest.fn().mockResolvedValue(undefined),
+    },
+  },
+}));
+
+const HUB = "https://hub.example";
+const SPOKE_A = "https://spoke-a.example";
+const ATTACKER = "https://attacker.example.net";
+const COOKIE = "better-auth.session_token=sess_tok_spoke.signature";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any avoids pulling in the full FastifyInstance type here
+type App = any;
+
+const ENV_KEYS = [
+  "FRONTEND_URL",
+  "AILK_TRUSTED_ORIGINS",
+  "NODE_ENV",
+  "DATABASE_URL",
+  // Cleared so a production boot never trips config's database-module exit.
+  "AILK_ENABLED_MODULES",
+] as const;
+
+describe("#7395 — a listed spoke's cookie write through build()", () => {
+  const priorEnv = new Map<string, string | undefined>(
+    ENV_KEYS.map((key) => [key, process.env[key]]),
+  );
+  let app: App;
+  let prisma: {
+    session: { findUnique: jest.Mock };
+    apiToken: { create: jest.Mock };
+  };
+
+  beforeEach(async () => {
+    process.env.FRONTEND_URL = HUB;
+    process.env.AILK_TRUSTED_ORIGINS = SPOKE_A;
+    process.env.NODE_ENV = "production";
+    process.env.DATABASE_URL = "postgresql://test:test@localhost/test";
+    delete process.env.AILK_ENABLED_MODULES;
+    jest.resetModules();
+
+    prisma = (require("../lib/prisma.js") as { prisma: typeof prisma }).prisma;
+    prisma.session.findUnique.mockResolvedValue({
+      id: "ses_1",
+      userId: "usr_spoke_visitor",
+      expiresAt: new Date(Date.now() + 60_000),
+      activeOrganizationId: null,
+      activeWorkspaceId: null,
+    });
+    prisma.apiToken.create.mockResolvedValue({
+      id: "tok_1",
+      name: "spoke",
+      tokenPrefix: "ailk_abc",
+      clientType: "cli",
+      scopes: [],
+      expiresAt: null,
+      createdAt: new Date(),
+    });
+
+    const { build } = require("../server") as typeof import("../server");
+    app = await build();
+  });
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+    for (const [key, value] of priorEnv) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+    jest.resetModules();
+  });
+
+  function postToken(origin: string) {
+    return app.inject({
+      method: "POST",
+      url: "/v1/auth/tokens",
+      headers: { cookie: COOKIE, origin },
+      payload: { name: "spoke" },
+    });
+  }
+
+  it("lets a cookie write from the listed spoke past the auth preHandler", async () => {
+    const res = await postToken(SPOKE_A);
+
+    expect(res.statusCode).not.toBe(401);
+    expect(res.json()).not.toEqual({ error: "unauthorized" });
+    // The handler ran as the session's user: the token was minted for them.
+    expect(res.statusCode).toBe(201);
+    expect(prisma.apiToken.create).toHaveBeenCalledTimes(1);
+    expect(prisma.apiToken.create.mock.calls[0][0].data.userId).toBe(
+      "usr_spoke_visitor",
+    );
+  });
+
+  it("refuses the same cookie write from an unlisted origin with 401", async () => {
+    const res = await postToken(ATTACKER);
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json()).toEqual({ error: "unauthorized" });
+    expect(prisma.apiToken.create).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/api/src/config/__tests__/trusted-origins.test.ts

@@ -0,0 +1,238 @@
+/**
+ * @file trusted-origins.test.ts
+ * @description The trusted browser-origin allowlist (#7395 AC-2).
+ *
+ * `resolveTrustedOrigins` is the one derivation CORS, the cookie-forwarded
+ * write check and the checkout redirect lock all read (spec D2/D4). It takes
+ * `FRONTEND_URL` (lenient, as today) plus the opt-in `AILK_TRUSTED_ORIGINS`
+ * (strict: an entry must already be written exactly as a browser serialises
+ * an `Origin` header). A refused entry stops the process at startup (D3), and
+ * the refusal log names the entry's position and reason, never its text.
+ */
+
+// Mock dotenv so a developer's local .env never leaks into the config module.
+jest.mock('dotenv', () => ({
+  config: jest.fn(),
+}));
+
+const mockLoggerError = jest.fn();
+const mockLoggerWarn = jest.fn();
+jest.mock('@working-theory/observability', () => ({
+  logger: {
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    warn: (...args: unknown[]) => mockLoggerWarn(...args),
+    info: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+import { resolveTrustedOrigins } from '../index';
+
+describe('resolveTrustedOrigins (#7395 D2)', () => {
+  it('normalises the primary, trims and de-duplicates the extras, and keeps first-seen order', () => {
+    const result = resolveTrustedOrigins({
+      FRONTEND_URL: 'https://hub.example/',
+      AILK_TRUSTED_ORIGINS:
+        ' https://admin.hub.example,https://spoke-a.example,,https://hub.example',
+      NODE_ENV: 'production',
+    });
+
+    expect(result.origins).toEqual([
+      'https://hub.example',
+      'https://admin.hub.example',
+      'https://spoke-a.example',
+    ]);
+    expect(result.refused).toEqual([]);
+    expect(result.primaryUnusable).toBe(false);
+    expect(Object.isFrozen(result.origins)).toBe(true);
+  });
+
+  it.each([
+    ['*', 'wildcard'],
+    ['https://*.example.com', 'wildcard'],
+    ['null', 'unparseable'],
+    ['https://a.example/', 'not-canonical'],
+    ['https://a.example/app', 'not-canonical'],
+    ['HTTPS://A.EXAMPLE', 'not-canonical'],
+    ['https://a.example:443', 'not-canonical'],
+    ['ftp://a.example', 'scheme'],
+    ['not a url', 'unparseable'],
+    ['https://user:pw@a.example', 'not-canonical'],
+    ['https://bücher.example', 'not-canonical'],
+    ['https://a.example.', 'trailing-dot'],
+    ['http://a.example', 'scheme'],
+  ])('refuses the extra %j in production (%s)', (entry, reason) => {
+    const result = resolveTrustedOrigins({
+      FRONTEND_URL: 'https://hub.example',
+      AILK_TRUSTED_ORIGINS: `https://ok.example,${entry}`,
+      NODE_ENV: 'production',
+    });
+
+    expect(result.refused).toEqual([{ position: 2, reason }]);
+    expect(result.origins).toEqual(['https://hub.example', 'https://ok.example']);
+  });
+
+  it('accepts a plain-http extra outside production', () => {
+    const result = resolveTrustedOrigins({
+      FRONTEND_URL: 'http://localhost:3000',
+      AILK_TRUSTED_ORIGINS: 'http://a.example',
+      NODE_ENV: 'development',
+    });
+
+    expect(result.refused).toEqual([]);
+    expect(result.origins).toEqual(['http://localhost:3000', 'http://a.example']);
+  });
+
+  it('carries no raw entry text in its result', () => {
+    const result = resolveTrustedOrigins({
+      FRONTEND_URL: 'https://hub.example',
+      AILK_TRUSTED_ORIGINS: 'https://user:pw@a.example',
+      NODE_ENV: 'production',
+    });
+
+    expect(JSON.stringify(result)).not.toContain('pw');
+  });
+
+  it.each([
+    'https://*',
+    // WHATWG decodes `%2A` in a host, so this parses to origin https://*.example.com.
+    'https://%2A.example.com',
+    'https://a.example,https://b.example',
+    'not a url',
+    'mailto:ops@example.com',
+  ])(
+    'a FRONTEND_URL of %j contributes no origin and is reported unusable',
+    (frontendUrl) => {
+      const result = resolveTrustedOrigins({
+        FRONTEND_URL: frontendUrl,
+        AILK_TRUSTED_ORIGINS: 'https://spoke-a.example',
+        NODE_ENV: 'production',
+      });
+
+      expect(result.origins).toEqual(['https://spoke-a.example']);
+      expect(result.primaryUnusable).toBe(true);
+      expect(result.refused).toEqual([]);
+    },
+  );
+
+  it('keeps a plain-http primary in production, as today', () => {
+    const result = resolveTrustedOrigins({
+      FRONTEND_URL: 'http://site.example',
+      NODE_ENV: 'production',
+    });
+
+    expect(result.origins).toEqual(['http://site.example']);
+    expect(result.primaryUnusable).toBe(false);
+  });
+
+  it('defaults an unset primary to http://localhost:3000 outside production', () => {
+    const result = resolveTrustedOrigins({ NODE_ENV: 'development' });
+
+    expect(result.origins).toEqual(['http://localhost:3000']);
+    expect(result.primaryUnusable).toBe(false);
+  });
+
+  it('trusts nothing for an unset primary in production, without reporting it unusable', () => {
+    const result = resolveTrustedOrigins({ NODE_ENV: 'production' });
+
+    expect(result.origins).toEqual([]);
+    expect(result.primaryUnusable).toBe(false);
+  });
+
+  it('trusts only the extras for an unset primary in production', () => {
+    const result = resolveTrustedOrigins({
+      AILK_TRUSTED_ORIGINS: 'https://hub.example',
+      NODE_ENV: 'production',
+    });
+
+    expect(result.origins).toEqual(['https://hub.example']);
+  });
+});
+
+describe('config.TRUSTED_ORIGINS at startup (#7395 D3/D5)', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+    // Cleared so a production boot never trips config's database-module exit.
+    delete process.env.AILK_ENABLED_MODULES;
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    jest.restoreAllMocks();
+  });
+
+  it('exposes the resolved, frozen list on config', () => {
+    process.env.FRONTEND_URL = 'https://hub.example/';
+    process.env.AILK_TRUSTED_ORIGINS = 'https://spoke-a.example';
+
+    const { config } = require('../index');
+
+    expect(config.TRUSTED_ORIGINS).toEqual(['https://hub.example', 'https://spoke-a.example']);
+    expect(Object.isFrozen(config.TRUSTED_ORIGINS)).toBe(true);
+    expect(config.AILK_TRUSTED_ORIGINS).toBe('https://spoke-a.example');
+    // FRONTEND_URL keeps its job as the primary site's address (D7).
+    expect(config.FRONTEND_URL).toBe('https://hub.example/');
+  });
+
+  it.each(['production', 'development'])(
+    'exits with a refused entry in %s, logging its position and reason but never its text',
+    (nodeEnv) => {
+      process.env.NODE_ENV = nodeEnv;
+      process.env.FRONTEND_URL = 'https://hub.example';
+      process.env.AILK_TRUSTED_ORIGINS = 'https://spoke-a.example,https://user:pw@a.example';
+      const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('Process exit called');
+      });
+      const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+
+      expect(() => require('../index')).toThrow('Process exit called');
+      expect(exitSpy).toHaveBeenCalledWith(1);
+      expect(mockLoggerError).toHaveBeenCalledTimes(1);
+
+      const logged = JSON.stringify([mockLoggerError.mock.calls, consoleError.mock.calls]);
+      expect(logged).toContain('AILK_TRUSTED_ORIGINS');
+      expect(logged).toContain('"position":2');
+      expect(logged).toContain('"reason":"not-canonical"');
+      expect(logged).not.toContain('pw');
+      expect(logged).not.toContain('a.example');
+      // The same line also reaches console.error, which survives a worker
+      // transport dropping the last line before exit (spec § 9 SA-08).
+      expect(consoleError).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  it.each(['production', 'development'])(
+    'logs, without exiting or echoing it, a FRONTEND_URL that is set but unusable (%s)',
+    (nodeEnv) => {
+      process.env.NODE_ENV = nodeEnv;
+      process.env.FRONTEND_URL = 'https://secret-token*@hub.example';
+      delete process.env.AILK_TRUSTED_ORIGINS;
+      const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('Process exit called');
+      });
+
+      const { config } = require('../index');
+
+      expect(exitSpy).not.toHaveBeenCalled();
+      expect(config.TRUSTED_ORIGINS).toEqual([]);
+      expect(mockLoggerError).toHaveBeenCalledTimes(1);
+      const logged = JSON.stringify(mockLoggerError.mock.calls);
+      expect(logged).toContain('FRONTEND_URL is set but');
+      expect(logged).not.toContain('secret-token');
+    },
+  );
+
+  it('logs no error for a usable FRONTEND_URL and no extras', () => {
+    process.env.FRONTEND_URL = 'https://hub.example';
+    delete process.env.AILK_TRUSTED_ORIGINS;
+
+    const { config } = require('../index');
+
+    expect(config.TRUSTED_ORIGINS).toEqual(['https://hub.example']);
+    expect(mockLoggerError).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/api/src/config/index.ts

@@ -17,6 +17,16 @@ export interface Config {
   PORT: number;
   FRONTEND_URL: string;
 
+  // The browser origins this API trusts (#7395) — the one list CORS, the
+  // cookie-forwarded write check (middleware/auth.ts) and the checkout
+  // redirect lock (routes/checkout/sessions.ts) all read. Resolved once, at
+  // startup, by resolveTrustedOrigins() below from FRONTEND_URL's origin plus
+  // the opt-in AILK_TRUSTED_ORIGINS (a comma-separated list of exact origins,
+  // for a hub that serves its Admin app and spoke sites). Frozen; no request
+  // input can add to it, and no entry can be `*` or a wildcard host.
+  TRUSTED_ORIGINS: readonly string[];
+  AILK_TRUSTED_ORIGINS?: string;
+
   // Local Database (for auth: User, Session, ApiToken, etc.). Required in
   // production; unset elsewhere starts the API database-less (#6482).
   DATABASE_URL?: string;
@@ -94,6 +104,103 @@ export interface Config {
   CAL_WEBHOOK_SECRET?: string;
 }
 
+/** Why an AILK_TRUSTED_ORIGINS entry was refused (#7395 D2). */
+export type TrustedOriginRefusal =
+  | 'wildcard'
+  | 'unparseable'
+  | 'scheme'
+  | 'not-canonical'
+  | 'trailing-dot';
+
+/** The zero-config development origin (`apps/web`'s `pnpm dev`). */
+const DEV_FRONTEND_ORIGIN = 'http://localhost:3000';
+
+/** `FRONTEND_URL`'s origin, or null when it is unusable as one (#7395 D2). */
+function primaryOrigin(raw: string): string | null {
+  // A comma means a list was put in the wrong variable:
+  // new URL('https://a.example,https://b.example').origin is 'https://a.example,https'.
+  if (raw.includes('*') || raw.includes(',')) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return null;
+  // WHATWG decodes a percent-encoded host: `https://%2A.example.com` has origin
+  // `https://*.example.com`, which the raw-string check above cannot see.
+  if (parsed.origin.includes('*')) return null;
+  return parsed.origin;
+}
+
+/** Why one AILK_TRUSTED_ORIGINS entry is refused, or null when it is an exact origin. */
+function refuseExtra(entry: string, nodeEnv: Config['NODE_ENV']): TrustedOriginRefusal | null {
+  // WHATWG parses `https://*.example.com` and keeps it as its own origin, so
+  // the wildcard is refused by name, before the parse (spec § 1.3).
+  if (entry.includes('*')) return 'wildcard';
+  let parsed: URL;
+  try {
+    parsed = new URL(entry);
+  } catch {
+    return 'unparseable';
+  }
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && nodeEnv !== 'production')) {
+    return 'scheme';
+  }
+  // Written exactly as a browser serialises an Origin header: lower-case
+  // punycode host, no default port, path, trailing slash or userinfo.
+  if (entry !== parsed.origin) return 'not-canonical';
+  // `https://a.example.` is a different origin from `https://a.example`.
+  if (parsed.hostname.endsWith('.')) return 'trailing-dot';
+  return null;
+}
+
+/**
+ * The trusted browser-origin allowlist (#7395 D2). Pure; `validateConfig()`
+ * calls it once.
+ *
+ * - `FRONTEND_URL` is normalised to its origin, as the checkout lock always
+ *   did; unset outside production it is the dev default. Unset in production,
+ *   or unusable (unparseable, not http(s), or containing `*` or `,`), it
+ *   contributes nothing, and `primaryUnusable` reports the latter.
+ * - `AILK_TRUSTED_ORIGINS` entries must already be exact origins, https-only in
+ *   production. A refused entry is reported by 1-based position and reason —
+ *   never its text, which may carry userinfo or a misplaced secret.
+ *
+ * The result is de-duplicated in first-seen order and frozen.
+ */
+export function resolveTrustedOrigins(env: {
+  FRONTEND_URL?: string | undefined;
+  AILK_TRUSTED_ORIGINS?: string | undefined;
+  NODE_ENV: Config['NODE_ENV'];
+}): {
+  origins: readonly string[];
+  refused: { position: number; reason: TrustedOriginRefusal }[];
+  primaryUnusable: boolean;
+} {
+  const origins: string[] = [];
+  const refused: { position: number; reason: TrustedOriginRefusal }[] = [];
+  let primaryUnusable = false;
+
+  if (env.FRONTEND_URL) {
+    const primary = primaryOrigin(env.FRONTEND_URL);
+    if (primary === null) primaryUnusable = true;
+    else origins.push(primary);
+  } else if (env.NODE_ENV !== 'production') {
+    origins.push(DEV_FRONTEND_ORIGIN);
+  }
+
+  (env.AILK_TRUSTED_ORIGINS ?? '').split(',').forEach((piece, index) => {
+    const entry = piece.trim();
+    if (!entry) return;
+    const reason = refuseExtra(entry, env.NODE_ENV);
+    if (reason !== null) refused.push({ position: index + 1, reason });
+    else origins.push(entry);
+  });
+
+  return { origins: Object.freeze([...new Set(origins)]), refused, primaryUnusable };
+}
+
 /** Enabled modules whose state lives in the database (see validateConfig). */
 const DATABASE_MODULES = [
   'commerce',
@@ -135,10 +242,39 @@ function validateConfig(): Config {
     );
   }
 
+  // #7395 D3 — a refused AILK_TRUSTED_ORIGINS entry stops the API in every
+  // environment: the variable is opt-in, and an entry dropped silently would
+  // resurface as the very 401 it was added to fix. Position and reason only,
+  // never the entry's text. console.error too, because pino-pretty's worker
+  // transport can drop the last line written before exit.
+  const trusted = resolveTrustedOrigins({
+    FRONTEND_URL: process.env.FRONTEND_URL,
+    AILK_TRUSTED_ORIGINS: process.env.AILK_TRUSTED_ORIGINS,
+    NODE_ENV: nodeEnv,
+  });
+  if (trusted.refused.length > 0) {
+    const message =
+      '❌ AILK_TRUSTED_ORIGINS has entries that are not exact http(s) origins (https only in production; no `*`, path, trailing slash or userinfo)';
+    logger.error({ refused: trusted.refused }, message);
+    console.error(message, JSON.stringify({ refused: trusted.refused }));
+    process.exit(1);
+  }
+  // #7395 D5 — a set-but-unusable FRONTEND_URL predates this list, so it is
+  // logged rather than fatal. The value is never echoed.
+  if (trusted.primaryUnusable) {
+    logger.error(
+      "FRONTEND_URL is set but is not an absolute http(s) URL without '*' or ',' — it is not a trusted origin",
+    );
+  }
+
   return {
     NODE_ENV: nodeEnv,
     PORT: parseInt(process.env.PORT || '3002', 10),
     FRONTEND_URL: process.env.FRONTEND_URL || 'http://localhost:3000',
+    TRUSTED_ORIGINS: trusted.origins,
+    ...(process.env.AILK_TRUSTED_ORIGINS !== undefined && {
+      AILK_TRUSTED_ORIGINS: process.env.AILK_TRUSTED_ORIGINS,
+    }),
 
     ...(process.env.DATABASE_URL !== undefined && {
       DATABASE_URL: process.env.DATABASE_URL,