create-ailk 0.12.0 → 0.13.0

package/templates/apps/api/src/__tests__/factories/in-memory-prisma.ts

@@ -0,0 +1,321 @@
+/**
+ * @file in-memory-prisma.ts
+ *
+ * An in-memory, where-clause-honouring Prisma double, shared by the route
+ * suites that register every tenant-guarded route plugin behind the real auth
+ * and tenant preHandlers (`routes/workspaces/__tests__/member-operates.test.ts`,
+ * #7636, and `agent-guard-parity.test.ts`, #3591).
+ *
+ * Every delegate call is recorded on `__calls` and the store is exposed on
+ * `__db`, so a refusal can be shown to read nothing. A relation filter the
+ * double does not model throws, so scoping that rides on one can never pass
+ * for the wrong reason.
+ *
+ * Usage — the factory must run inside the hoisted `jest.mock` callback:
+ *
+ *   jest.mock("../../../lib/prisma.js", () =>
+ *     jest
+ *       .requireActual<typeof import("../../../__tests__/factories/in-memory-prisma")>(
+ *         "../../../__tests__/factories/in-memory-prisma",
+ *       )
+ *       .createInMemoryPrisma(),
+ *   );
+ */
+export function createInMemoryPrisma(): { prisma: Record<string, unknown> } {
+  type Row = Record<string, unknown>;
+  type Where = Record<string, unknown>;
+  const db: Record<string, Row[]> = {};
+  const calls: Array<{ model: string; op: string }> = [];
+  const OPS = new Set([
+    "in",
+    "notIn",
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "not",
+    "equals",
+    "startsWith",
+    "endsWith",
+    "contains",
+    "has",
+    "hasSome",
+    "mode",
+    "path",
+  ]);
+  const isPlain = (v: unknown): v is Record<string, unknown> =>
+    v !== null &&
+    typeof v === "object" &&
+    !Array.isArray(v) &&
+    !(v instanceof Date);
+  const norm = (v: unknown) => (v instanceof Date ? v.getTime() : (v ?? null));
+  const eq = (a: unknown, b: unknown) => norm(a) === norm(b);
+  const cmp = (a: unknown, b: unknown) => {
+    const x = norm(a) as number;
+    const y = norm(b) as number;
+    return x < y ? -1 : x > y ? 1 : 0;
+  };
+  const table = (model: string) => (db[model] ??= []);
+
+  function matchCond(value: unknown, cond: unknown): boolean {
+    if (cond === undefined) return true;
+    if (!isPlain(cond)) return eq(value, cond);
+    const keys = Object.keys(cond);
+    if (!keys.every((k) => OPS.has(k))) {
+      // A nested filter is matched against a nested value. A relation filter
+      // this double does not model fails loudly, so scoping that rides on
+      // one can never pass for the wrong reason.
+      if (
+        keys.some((k) =>
+          ["some", "none", "every", "is", "isNot"].includes(k),
+        ) ||
+        !isPlain(value)
+      ) {
+        throw new Error(
+          `in-memory prisma: unmodelled filter ${JSON.stringify(keys)}`,
+        );
+      }
+      return matches(value, cond);
+    }
+    if ("path" in cond) {
+      const path = cond.path as string[];
+      let nested: unknown = value;
+      for (const p of path) nested = isPlain(nested) ? nested[p] : undefined;
+      const { path: _p, ...rest } = cond;
+      return matchCond(nested, rest);
+    }
+    for (const [op, arg] of Object.entries(cond)) {
+      switch (op) {
+        case "in":
+          if (!(arg as unknown[]).some((v) => eq(value, v))) return false;
+          break;
+        case "notIn":
+          if ((arg as unknown[]).some((v) => eq(value, v))) return false;
+          break;
+        case "lt":
+          if (value == null || cmp(value, arg) >= 0) return false;
+          break;
+        case "lte":
+          if (value == null || cmp(value, arg) > 0) return false;
+          break;
+        case "gt":
+          if (value == null || cmp(value, arg) <= 0) return false;
+          break;
+        case "gte":
+          if (value == null || cmp(value, arg) < 0) return false;
+          break;
+        case "not":
+          if (matchCond(value, arg)) return false;
+          break;
+        case "equals":
+          if (!eq(value, arg)) return false;
+          break;
+        case "startsWith":
+          if (typeof value !== "string" || !value.startsWith(arg as string))
+            return false;
+          break;
+        case "endsWith":
+          if (typeof value !== "string" || !value.endsWith(arg as string))
+            return false;
+          break;
+        case "contains":
+          if (typeof value !== "string" || !value.includes(arg as string))
+            return false;
+          break;
+        case "has":
+          if (!Array.isArray(value) || !value.includes(arg)) return false;
+          break;
+        case "hasSome":
+          if (
+            !Array.isArray(value) ||
+            !(arg as unknown[]).some((v) => value.includes(v))
+          ) {
+            return false;
+          }
+          break;
+        default:
+          break;
+      }
+    }
+    return true;
+  }
+
+  function matches(row: Row, where: Where | undefined): boolean {
+    for (const [key, cond] of Object.entries(where ?? {})) {
+      if (key === "AND") {
+        const all = Array.isArray(cond) ? cond : [cond];
+        if (!all.every((w) => matches(row, w as Where))) return false;
+      } else if (key === "OR") {
+        if (!(cond as Where[]).some((w) => matches(row, w))) return false;
+      } else if (key === "NOT") {
+        const all = Array.isArray(cond) ? cond : [cond];
+        if (all.some((w) => matches(row, w as Where))) return false;
+      } else if (
+        !(key in row) &&
+        isPlain(cond) &&
+        !Object.keys(cond).every((k) => OPS.has(k))
+      ) {
+        if (!matches(row, cond)) return false;
+      } else if (!matchCond(row[key], cond)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  function pick(value: unknown, select: unknown): unknown {
+    if (!isPlain(select) || value == null) return value;
+    if (Array.isArray(value)) return value.map((v) => pick(v, select));
+    if (!isPlain(value)) return value;
+    const out: Row = {};
+    for (const [key, spec] of Object.entries(select)) {
+      if (spec === true) out[key] = value[key];
+      else if (isPlain(spec) && key in value) {
+        out[key] = pick(value[key], (spec as Row).select ?? spec);
+      }
+    }
+    return out;
+  }
+
+  function sorted(rows: Row[], orderBy: unknown): Row[] {
+    if (!orderBy) return rows;
+    const orders = (Array.isArray(orderBy) ? orderBy : [orderBy]) as Array<
+      Record<string, string>
+    >;
+    return [...rows].sort((a, b) => {
+      for (const ord of orders) {
+        const [field, dir] = Object.entries(ord)[0] as [string, string];
+        const c = cmp(a[field], b[field]);
+        if (c !== 0) return dir === "desc" ? -c : c;
+      }
+      return 0;
+    });
+  }
+
+  let seq = 0;
+  function apply(row: Row, data: Row): Row {
+    for (const [key, value] of Object.entries(data)) {
+      if (isPlain(value) && "increment" in value) {
+        row[key] = ((row[key] as number) ?? 0) + (value.increment as number);
+      } else if (isPlain(value) && "set" in value) {
+        row[key] = value.set;
+      } else {
+        row[key] = value;
+      }
+    }
+    row["updatedAt"] = new Date();
+    return row;
+  }
+
+  function delegate(model: string) {
+    const log = (op: string) => calls.push({ model, op });
+    const findMany = (args: Row = {}) => {
+      let rows = sorted(
+        table(model).filter((r) => matches(r, args.where as Where)),
+        args.orderBy,
+      );
+      if (typeof args.skip === "number") rows = rows.slice(args.skip);
+      if (typeof args.take === "number") rows = rows.slice(0, args.take);
+      return rows.map(
+        (r) => pick({ ...r }, args.select ?? args.include) as Row,
+      );
+    };
+    const create = (args: Row) => {
+      const data = args.data as Row;
+      const row: Row = {
+        // A registry-shaped id, so an `isId` boundary check accepts it.
+        id: `${model === "user" ? "user" : model}_00000000-0000-7000-8000-${String(++seq).padStart(12, "0")}`,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...data,
+      };
+      table(model).push(row);
+      return pick({ ...row }, args.select);
+    };
+    return {
+      findMany: jest.fn(
+        async (args: Row = {}) => (log("findMany"), findMany(args)),
+      ),
+      findFirst: jest.fn(
+        async (args: Row = {}) => (log("findFirst"), findMany(args)[0] ?? null),
+      ),
+      findUnique: jest.fn(
+        async (args: Row = {}) => (
+          log("findUnique"),
+          findMany(args)[0] ?? null
+        ),
+      ),
+      findUniqueOrThrow: jest.fn(async (args: Row = {}) => {
+        log("findUniqueOrThrow");
+        const row = findMany(args)[0];
+        if (!row) throw new Error(`${model} not found`);
+        return row;
+      }),
+      count: jest.fn(
+        async (args: Row = {}) => (
+          log("count"),
+          findMany({ where: args.where }).length
+        ),
+      ),
+      create: jest.fn(async (args: Row) => (log("create"), create(args))),
+      update: jest.fn(async (args: Row) => {
+        log("update");
+        const row = table(model).find((r) => matches(r, args.where as Where));
+        if (!row) throw new Error(`${model} not found`);
+        return pick({ ...apply(row, args.data as Row) }, args.select);
+      }),
+      updateMany: jest.fn(async (args: Row) => {
+        log("updateMany");
+        const rows = table(model).filter((r) =>
+          matches(r, args.where as Where),
+        );
+        for (const row of rows) apply(row, args.data as Row);
+        return { count: rows.length };
+      }),
+      upsert: jest.fn(async (args: Row) => {
+        log("upsert");
+        const row = table(model).find((r) => matches(r, args.where as Where));
+        if (row)
+          return pick({ ...apply(row, args.update as Row) }, args.select);
+        return create({ data: args.create, select: args.select });
+      }),
+      deleteMany: jest.fn(async (args: Row = {}) => {
+        log("deleteMany");
+        const before = table(model).length;
+        db[model] = table(model).filter(
+          (r) => !matches(r, args.where as Where),
+        );
+        return { count: before - table(model).length };
+      }),
+      groupBy: jest.fn(async () => (log("groupBy"), [])),
+      aggregate: jest.fn(
+        async () => (
+          log("aggregate"),
+          { _count: {}, _sum: {}, _max: {}, _min: {} }
+        ),
+      ),
+    };
+  }
+
+  const delegates: Record<string, ReturnType<typeof delegate>> = {};
+  const prisma: Record<string, unknown> = new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (prop === "__db") return db;
+        if (prop === "__calls") return calls;
+        if (prop === "$transaction") {
+          return async (arg: unknown) =>
+            typeof arg === "function"
+              ? (arg as (tx: unknown) => unknown)(prisma)
+              : Promise.all(arg as Promise<unknown>[]);
+        }
+        if (prop === "$queryRaw" || prop === "$executeRaw")
+          return async () => [];
+        if (typeof prop !== "string" || prop === "then") return undefined;
+        return (delegates[prop] ??= delegate(prop));
+      },
+    },
+  );
+  return { prisma };
+}

package/templates/apps/api/src/__tests__/schedule-forwarded-rate-limit.test.ts

@@ -0,0 +1,117 @@
+/**
+ * @file schedule-forwarded-rate-limit.test.ts
+ * @description #7633 (conductor amendment, the relay's security review) — a
+ * site's relayed schedule calls are limited per visitor end to end, through
+ * the real `build()`, the schedule scope's own limiter and the REAL
+ * `@fastify/rate-limit` global ceiling: the schedule scope's twin of
+ * `leads-forwarded-rate-limit.test.ts` (#7394 AC-7).
+ *
+ * Once browsers post through a site's same-origin relay (#7644), every
+ * visitor's `GET /v1/schedule/availability` and `POST /v1/schedule/book`
+ * reaches the hub from the site's server. With the hub-issued forwarding key,
+ * each visitor gets the scope's own per-visitor budget, and the key as a
+ * whole a ceiling of 60 a minute — well below the lead routes' 300, because a
+ * booking is a real booking.
+ *
+ * `DATABASE_URL` is unset and the `scheduling` module is enabled for the
+ * file's duration. Whatever each route answers past the limiter (a 400 or a
+ * 503) is not this file's subject: the limiter runs on `onRequest`, before
+ * any handler.
+ */
+
+import { __resetBuckets } from "../middleware/rate-limit";
+import { build } from "../server";
+
+jest.mock("@fastify/cors", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+const KEY = "0123456789abcdef".repeat(4); // gitleaks:allow — test fixture, not a credential (#7394)
+const SPOKE_HOST = "198.51.100.7";
+
+/** A distinct, valid visitor IP per index. */
+function visitor(i: number): string {
+  return `203.0.${Math.floor(i / 250)}.${(i % 250) + 1}`;
+}
+
+function headersFor(visitorIp: string, withKey: boolean): Record<string, string> {
+  return {
+    "x-forwarded-for": SPOKE_HOST,
+    "x-ailk-visitor-ip": visitorIp,
+    ...(withKey && { "x-ailk-visitor-forward-key": KEY }),
+  };
+}
+
+const ROUTES = [
+  { method: "GET", url: "/v1/schedule/availability?calLink=acme%2Fintro" },
+  { method: "POST", url: "/v1/schedule/book", payload: {} },
+] as const;
+
+describe.each(ROUTES)("$method $url for a keyed site, against the real limiters (#7633)", (route) => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any matches server.test.ts
+  let app: any;
+  const prior = {
+    keys: process.env.AILK_VISITOR_FORWARD_KEYS,
+    modules: process.env.AILK_ENABLED_MODULES,
+    databaseUrl: process.env.DATABASE_URL,
+  };
+
+  async function statuses(count: number, visitorFor: (i: number) => string, withKey: boolean): Promise<number[]> {
+    const codes: number[] = [];
+    for (let i = 0; i < count; i++) {
+      const res = await app.inject({ ...route, headers: headersFor(visitorFor(i), withKey) });
+      codes.push(res.statusCode);
+    }
+    return codes;
+  }
+
+  beforeEach(async () => {
+    __resetBuckets();
+    process.env.AILK_VISITOR_FORWARD_KEYS = KEY;
+    process.env.AILK_ENABLED_MODULES = "scheduling";
+    delete process.env.DATABASE_URL;
+    app = await build();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+    app = undefined;
+  });
+
+  afterAll(() => {
+    for (const [name, value] of [
+      ["AILK_VISITOR_FORWARD_KEYS", prior.keys],
+      ["AILK_ENABLED_MODULES", prior.modules],
+      ["DATABASE_URL", prior.databaseUrl],
+    ] as const) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  it("two visitors behind one forwarding key are counted separately: the first's eleventh call is 429, the second's first is not", async () => {
+    const first = await statuses(11, () => "203.0.113.1", true);
+    expect(first.slice(0, 10).every((code) => code !== 429)).toBe(true);
+    expect(first[10]).toBe(429);
+
+    const second = await statuses(1, () => "203.0.113.2", true);
+    expect(second[0]).not.toBe(429);
+  });
+
+  it("without the key, distinct visitors behind one host share the host's budget: the eleventh call is 429", async () => {
+    const codes = await statuses(11, visitor, false);
+    expect(codes.slice(0, 10).every((code) => code !== 429)).toBe(true);
+    expect(codes[10]).toBe(429);
+  });
+
+  it("the key's own ceiling is 60 a minute across all of its visitors: the sixty-first is 429", async () => {
+    const codes = await statuses(61, visitor, true);
+    expect(codes.slice(0, 60).every((code) => code !== 429)).toBe(true);
+    expect(codes[60]).toBe(429);
+  });
+});

package/templates/apps/api/src/config/__tests__/hub-require-spoke-key.test.ts

@@ -1,12 +1,15 @@
 /**
  * @file hub-require-spoke-key.test.ts
- * @description `AILK_HUB_REQUIRE_SPOKE_KEY` — the hub's strict-mode flag
- * (#7532, spec docs/specs/7532-a-spoke-s-public-reads-spec.md D7, AC-5).
+ * @description `AILK_HUB_REQUIRE_SPOKE_KEY` — the hub's spoke-key mode
+ * (#7532 D7; three-state since #7633, spec
+ * docs/specs/7633-expected-a-keyless-public-read-spec.md D2, AC-5).
  *
- * `true`/`1` turn it on; unset, empty, `false` and `0` leave it off —
- * case-insensitively, after trimming. Any other value refuses the boot with a
- * message naming the variable, never the value. On with no `DATABASE_URL`
- * refuses the boot too: strict mode with no registry would refuse every call.
+ * Unset, empty or blank is `"auto"` (refuse a keyless call once the registry
+ * holds a row); `true`/`1` is `"on"`; `false`/`0` is `"off"`, the emergency
+ * opt-out, which warns at boot — case-insensitively, after trimming. Any other
+ * value refuses the boot with a message naming the variable, never the value.
+ * `"on"` with no `DATABASE_URL` refuses the boot too: it would refuse every
+ * call. `"auto"` and `"off"` boot without a database.
  */
 
 // Mock dotenv so a developer's local .env never leaks into the config module.
@@ -25,7 +28,7 @@ jest.mock('@working-theory/observability', () => ({
   },
 }));
 
-describe('AILK_HUB_REQUIRE_SPOKE_KEY (#7532 D7)', () => {
+describe('AILK_HUB_REQUIRE_SPOKE_KEY (#7532 D7, #7633 D2)', () => {
   const originalEnv = process.env;
 
   beforeEach(() => {
@@ -41,16 +44,34 @@ describe('AILK_HUB_REQUIRE_SPOKE_KEY (#7532 D7)', () => {
     jest.restoreAllMocks();
   });
 
-  it.each(['true', 'TRUE', '1', ' True '])('%j parses on', (raw) => {
+  /** The boot warnings that name this variable. */
+  function hubWarnings(): unknown[][] {
+    return mockLoggerWarn.mock.calls.filter((call) =>
+      JSON.stringify(call).includes('AILK_HUB_REQUIRE_SPOKE_KEY'),
+    );
+  }
+
+  it.each([undefined, '', '  '])('%j parses "auto" — the default — and warns nothing', (raw) => {
+    if (raw !== undefined) process.env.AILK_HUB_REQUIRE_SPOKE_KEY = raw;
+    const { config } = require('../index');
+    expect(config).toMatchObject({ AILK_HUB_REQUIRE_SPOKE_KEY: 'auto' });
+    expect(hubWarnings()).toHaveLength(0);
+  });
+
+  it.each(['true', 'TRUE', '1', ' True '])('%j parses "on" and warns nothing', (raw) => {
     process.env.AILK_HUB_REQUIRE_SPOKE_KEY = raw;
     const { config } = require('../index');
-    expect(config.AILK_HUB_REQUIRE_SPOKE_KEY).toBe(true);
+    expect(config).toMatchObject({ AILK_HUB_REQUIRE_SPOKE_KEY: 'on' });
+    expect(hubWarnings()).toHaveLength(0);
   });
 
-  it.each([undefined, '', '  ', 'false', 'FALSE', '0'])('%j parses off', (raw) => {
-    if (raw !== undefined) process.env.AILK_HUB_REQUIRE_SPOKE_KEY = raw;
+  it.each(['false', 'FALSE', '0'])('%j parses "off" — the emergency opt-out — and warns once at boot', (raw) => {
+    process.env.AILK_HUB_REQUIRE_SPOKE_KEY = raw;
     const { config } = require('../index');
-    expect(config.AILK_HUB_REQUIRE_SPOKE_KEY).toBe(false);
+    expect(config).toMatchObject({ AILK_HUB_REQUIRE_SPOKE_KEY: 'off' });
+    const warnings = hubWarnings();
+    expect(warnings).toHaveLength(1);
+    expect(JSON.stringify(warnings)).toContain('AILK_HUB_REQUIRE_SPOKE_KEY=false');
   });
 
   it('any other value refuses the boot, naming the variable and never the value', () => {
@@ -83,7 +104,11 @@ describe('AILK_HUB_REQUIRE_SPOKE_KEY (#7532 D7)', () => {
     );
   });
 
-  it('off with DATABASE_URL unset still boots database-less, as today', () => {
+  it.each([
+    ['auto', undefined],
+    ['off', 'false'],
+  ])('"%s" with DATABASE_URL unset still boots database-less', (mode, raw) => {
+    if (raw !== undefined) process.env.AILK_HUB_REQUIRE_SPOKE_KEY = raw;
     delete process.env.DATABASE_URL;
     const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
       throw new Error('Process exit called');
@@ -91,6 +116,6 @@ describe('AILK_HUB_REQUIRE_SPOKE_KEY (#7532 D7)', () => {
 
     const { config } = require('../index');
     expect(exitSpy).not.toHaveBeenCalled();
-    expect(config.AILK_HUB_REQUIRE_SPOKE_KEY).toBe(false);
+    expect(config).toMatchObject({ AILK_HUB_REQUIRE_SPOKE_KEY: mode });
   });
 });

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

@@ -112,15 +112,21 @@ export interface Config {
   // env-configured CAL_API_KEY path works exactly as before. Held decoded,
   // never as the raw string, and never logged.
   SCHEDULING_CREDENTIAL_KEY?: Buffer;
-  // Hub strict mode (#7532 D7). A hub serving several spokes sets it so a
-  // request to a spoke-aware public surface (meeting types, the three lead
-  // writes, booking, the public content reads) that carries no
-  // `x-ailk-spoke-key` resolves to nothing. Off (the default) keeps today's
-  // header-less resolution, byte for byte. Parsed by parseHubRequireSpokeKey()
-  // below; read by services/public-site-resolver.ts.
-  AILK_HUB_REQUIRE_SPOKE_KEY: boolean;
+  // What a hub does with a request to a spoke-aware public surface (meeting
+  // types, the three lead writes, booking, availability, event meta, the
+  // public content reads) that carries no `x-ailk-spoke-key` (#7532 D7,
+  // #7633 D2). `"auto"` (unset, the default) refuses it once the spoke
+  // registry holds a row, and keeps the keyless answer on a deployment with
+  // no spoke; `"on"` always refuses it; `"off"` never does — an emergency
+  // opt-out, warned at boot. A mode, never a boolean: every value is a truthy
+  // string, so no reader may test it by truthiness. Parsed by
+  // parseHubRequireSpokeKey() below; read by services/public-site-resolver.ts.
+  AILK_HUB_REQUIRE_SPOKE_KEY: HubSpokeKeyMode;
 }
 
+/** `AILK_HUB_REQUIRE_SPOKE_KEY`'s three states (#7633 D2). */
+export type HubSpokeKeyMode = 'auto' | 'on' | 'off';
+
 /** Why an AILK_TRUSTED_ORIGINS entry was refused (#7395 D2). */
 export type TrustedOriginRefusal =
   | 'wildcard'
@@ -248,14 +254,16 @@ export function resolveSchedulingCredentialKey(
 }
 
 /**
- * `AILK_HUB_REQUIRE_SPOKE_KEY` (#7532 D7): `true`/`1` → on; unset, empty,
- * `false`, `0` → off — case-insensitive, after trimming. `null` for any other
- * value, which `validateConfig()` refuses at boot.
+ * `AILK_HUB_REQUIRE_SPOKE_KEY` (#7532 D7, #7633 D2): unset, empty or blank →
+ * `"auto"`; `true`/`1` → `"on"`; `false`/`0` → `"off"` — case-insensitive,
+ * after trimming. `null` for any other value, which `validateConfig()`
+ * refuses at boot.
  */
-export function parseHubRequireSpokeKey(raw: string | undefined): boolean | null {
+export function parseHubRequireSpokeKey(raw: string | undefined): HubSpokeKeyMode | null {
   const value = (raw ?? '').trim().toLowerCase();
-  if (value === 'true' || value === '1') return true;
-  if (value === '' || value === 'false' || value === '0') return false;
+  if (value === '') return 'auto';
+  if (value === 'true' || value === '1') return 'on';
+  if (value === 'false' || value === '0') return 'off';
   return null;
 }
 
@@ -338,11 +346,11 @@ function validateConfig(): Config {
     process.exit(1);
   }
 
-  // #7532 D7 — the hub strict-mode flag. An unparseable value stops the API:
-  // the variable is opt-in, and a typo read as "off" would silently leave the
-  // hub open to header-less callers. The message names the variable, never
-  // its value. On with no DATABASE_URL stops it too: strict mode with no
-  // registry to look a key up in would refuse every call.
+  // #7532 D7, #7633 D2 — the hub's spoke-key mode. An unparseable value stops
+  // the API: a typo read as "off" would silently leave the hub open to
+  // header-less callers. The message names the variable, never its value.
+  // "on" with no DATABASE_URL stops it too: with no registry to look a key up
+  // in it would refuse every call. "auto" and "off" boot without a database.
   const hubRequireSpokeKey = parseHubRequireSpokeKey(process.env.AILK_HUB_REQUIRE_SPOKE_KEY);
   if (hubRequireSpokeKey === null) {
     const message =
@@ -351,13 +359,20 @@ function validateConfig(): Config {
     console.error(message);
     process.exit(1);
   }
-  if (hubRequireSpokeKey && !process.env.DATABASE_URL) {
+  if (hubRequireSpokeKey === 'on' && !process.env.DATABASE_URL) {
     const message =
       '❌ AILK_HUB_REQUIRE_SPOKE_KEY is on but DATABASE_URL is not set — the spoke registry lives in the database';
     logger.error(message);
     console.error(message);
     process.exit(1);
   }
+  // The emergency opt-out is never silent: it reopens keyless access on every
+  // spoke-aware surface of a hub (#7633 D2, D6).
+  if (hubRequireSpokeKey === 'off') {
+    logger.warn(
+      'AILK_HUB_REQUIRE_SPOKE_KEY=false — a public request with no spoke key is accepted even when spokes are registered',
+    );
+  }
 
   return {
     NODE_ENV: nodeEnv,
@@ -430,7 +445,7 @@ function validateConfig(): Config {
     ...(schedulingKey.kind === 'ok' && {
       SCHEDULING_CREDENTIAL_KEY: schedulingKey.key,
     }),
-    AILK_HUB_REQUIRE_SPOKE_KEY: hubRequireSpokeKey === true,
+    AILK_HUB_REQUIRE_SPOKE_KEY: hubRequireSpokeKey,
   };
 }
 

package/templates/apps/api/src/lib/__mocks__/prisma-client.js

@@ -8,6 +8,9 @@ const MockPrismaClient = jest.fn().mockImplementation((options) => ({
   user: {},
   apiToken: {},
   userData: {},
+  // #7633 D8 — the public resolver's "is this a hub" read. An empty registry,
+  // so a suite that reaches this stub keeps today's keyless answer.
+  spoke: { findFirst: jest.fn(async () => null) },
 }));
 
 // #4663 D6 — flow-engine.ts imports the real `Prisma` runtime namespace (a

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -67,6 +67,8 @@ export const prisma = {
   user: {
     findUnique: jest.fn(),
     findFirst: jest.fn(),
+    // #3591 — `lib/agent-store.ts`'s list names each agent's creator by id.
+    findMany: jest.fn(),
     update: jest.fn(),
     create: jest.fn(),
   },
@@ -387,6 +389,18 @@ export const prisma = {
     findUnique: jest.fn(),
     createMany: jest.fn(),
   },
+  // ── #3591 — agents (auth) ────────────────────────────────────────────────
+  // Every call lives in `lib/agent-store.ts`: `findUnique` by credential
+  // digest (the auth preHandler's one lookup) or by id; `update` — the
+  // best-effort `lastActiveAt` bump; `create`/`updateMany`/`findMany` — the
+  // management functions, each scoped by the caller's organization id.
+  agent: {
+    findUnique: jest.fn(),
+    findMany: jest.fn(),
+    create: jest.fn(),
+    update: jest.fn(),
+    updateMany: jest.fn(),
+  },
   // ── Content namespace (UsageEvent, UsagePeriod — FEAT-047 P1.S1/#3709) ──
   usageEvent: {
     create: jest.fn(),