create-ailk 0.14.0 → 0.16.0

package/templates/apps/api/src/__tests__/support/hub-sign-in-fake-db.ts

@@ -0,0 +1,362 @@
+/**
+ * An in-memory stand-in for the handful of Prisma delegates the hub sign-in
+ * flow touches (#7894): `spoke`, `oAuthClient`, `oAuthAuthorization`,
+ * `verification` and `user`. Test-only.
+ *
+ * It lets the suites drive the REAL store, service, routes and preHandler end
+ * to end — a code minted by one call is consumed (once) by the next — while
+ * the Prisma client itself, the external boundary, stays faked. Every delegate
+ * method answers only the `where` shapes the production code uses; an
+ * unexpected shape throws, so a code change that adds a query is a failing
+ * test and not a silent miss.
+ *
+ * Install it on the shared `__mocks__/prisma.ts` double:
+ *
+ *   jest.mock("../../lib/prisma.js");
+ *   const fake = installHubSignInFakeDb(jest.mocked(prisma));
+ */
+import { randomUUID } from "node:crypto";
+
+import { hashSpokeKey, mintSpokeKey } from "../../lib/spoke-store.js";
+import {
+  HUB_CALLBACK_PATH,
+  mintClientSecret,
+  sha256Hex,
+} from "../../lib/hub-sign-in-store.js";
+
+type Row = Record<string, unknown>;
+type Where = Record<string, unknown>;
+
+export interface FakeUser {
+  id: string;
+  name: string | null;
+  email: string;
+  emailVerified: boolean;
+  createdAt: Date;
+}
+
+export interface FakeSpoke {
+  id: string;
+  workspaceId: string;
+  name: string;
+  credentialHash: string;
+  revokedAt: Date | null;
+}
+
+export interface FakeClient {
+  id: string;
+  clientId: string;
+  clientSecret: string;
+  redirectUris: string[];
+  enabled: boolean;
+}
+
+export interface FakeVerification {
+  id: string;
+  identifier: string;
+  value: string;
+  expiresAt: Date;
+}
+
+export interface FakeAuthorization {
+  id: string;
+  userId: string;
+  clientId: string;
+  scopes: string[];
+  accessToken: string;
+  expiresAt: Date;
+  revokedAt: Date | null;
+}
+
+export interface FakeHubDb {
+  users: Map<string, FakeUser>;
+  spokes: Map<string, FakeSpoke>;
+  clients: Map<string, FakeClient>;
+  verifications: FakeVerification[];
+  authorizations: FakeAuthorization[];
+  /** Every `prisma.session.*` call — the token route must make none. */
+  sessionCalls: string[];
+}
+
+/** A seeded spoke with a registered sign-in client. */
+export interface SeededSpoke {
+  spoke: FakeSpoke;
+  client: FakeClient;
+  /** The spoke key, in clear (the test sends it). */
+  key: string;
+  /** The client secret, in clear. */
+  secret: string;
+  redirectUri: string;
+  /** `Authorization: Basic …` for the token and revoke routes. */
+  basic: string;
+}
+
+function eq(row: object, where: Where): boolean {
+  return Object.entries(where).every(([key, expected]) => {
+    if (expected !== null && typeof expected === "object") {
+      throw new Error(`fake db: unsupported where clause on "${key}"`);
+    }
+    return (row as Record<string, unknown>)[key] === expected;
+  });
+}
+
+function pickWhere(where: Where, allowed: string[]): void {
+  for (const key of Object.keys(where)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`fake db: unexpected where key "${key}"`);
+    }
+  }
+}
+
+type DelegateMock = {
+  mockImplementation: (fn: (arg: never) => unknown) => void;
+};
+
+function impl(mock: unknown, fn: (arg: never) => unknown): void {
+  (mock as DelegateMock).mockImplementation(fn);
+}
+
+export function installHubSignInFakeDb(db: {
+  spoke: { findUnique: unknown };
+  oAuthClient: { findUnique: unknown; upsert: unknown; updateMany: unknown };
+  oAuthAuthorization: {
+    findUnique: unknown;
+    upsert: unknown;
+    updateMany: unknown;
+  };
+  verification: { create: unknown; findFirst: unknown; deleteMany: unknown };
+  user: { findUnique: unknown };
+  session: { findUnique: unknown; create: unknown };
+}): FakeHubDb {
+  const state: FakeHubDb = {
+    users: new Map(),
+    spokes: new Map(),
+    clients: new Map(),
+    verifications: [],
+    authorizations: [],
+    sessionCalls: [],
+  };
+
+  impl(
+    db.user.findUnique,
+    async ({ where }: { where: Where }) =>
+      state.users.get(String(where.id)) ?? null,
+  );
+
+  impl(db.spoke.findUnique, async ({ where }: { where: Where }) => {
+    pickWhere(where, ["id", "credentialHash"]);
+    for (const spoke of state.spokes.values()) {
+      if (eq(spoke, where)) return spoke;
+    }
+    return null;
+  });
+
+  impl(db.oAuthClient.findUnique, async ({ where }: { where: Where }) => {
+    pickWhere(where, ["clientId"]);
+    return state.clients.get(String(where.clientId)) ?? null;
+  });
+
+  impl(
+    db.oAuthClient.upsert,
+    async (args: {
+      where: Where;
+      create: Omit<FakeClient, "id">;
+      update: Partial<FakeClient>;
+    }) => {
+      const clientId = String(args.where.clientId);
+      const existing = state.clients.get(clientId);
+      const next: FakeClient = existing
+        ? { ...existing, ...args.update }
+        : { id: `oauthc_${randomUUID()}`, ...args.create };
+      state.clients.set(clientId, next);
+      return next;
+    },
+  );
+
+  impl(
+    db.oAuthClient.updateMany,
+    async ({ where, data }: { where: Where; data: Row }) => {
+      pickWhere(where, ["clientId"]);
+      const client = state.clients.get(String(where.clientId));
+      if (!client) return { count: 0 };
+      Object.assign(client, data);
+      return { count: 1 };
+    },
+  );
+
+  impl(
+    db.verification.create,
+    async ({ data }: { data: Omit<FakeVerification, "id"> }) => {
+    const row: FakeVerification = { id: `verify_${randomUUID()}`, ...data };
+    state.verifications.push(row);
+    return row;
+  });
+
+  impl(db.verification.findFirst, async ({ where }: { where: Where }) => {
+    pickWhere(where, ["identifier"]);
+    return (
+      state.verifications.find((v) => v.identifier === where.identifier) ?? null
+    );
+  });
+
+  impl(db.verification.deleteMany, async ({ where }: { where: Where }) => {
+    const before = state.verifications.length;
+    if (typeof where.id === "string") {
+      state.verifications = state.verifications.filter(
+        (v) => v.id !== where.id,
+      );
+    } else {
+      const startsWith = (where.identifier as { startsWith: string })
+        .startsWith;
+      const lte = (where.expiresAt as { lte: Date }).lte;
+      state.verifications = state.verifications.filter(
+        (v) => !(v.identifier.startsWith(startsWith) && v.expiresAt <= lte),
+      );
+    }
+    return { count: before - state.verifications.length };
+  });
+
+  impl(
+    db.oAuthAuthorization.upsert,
+    async (args: {
+      where: { userId_clientId: { userId: string; clientId: string } };
+      create: Omit<FakeAuthorization, "id" | "revokedAt">;
+      update: Partial<FakeAuthorization>;
+    }) => {
+      const { userId, clientId } = args.where.userId_clientId;
+      const existing = state.authorizations.find(
+        (a) => a.userId === userId && a.clientId === clientId,
+      );
+      if (existing) {
+        Object.assign(existing, args.update);
+        return existing;
+      }
+      const row: FakeAuthorization = {
+        id: `oautha_${randomUUID()}`,
+        revokedAt: null,
+        ...args.create,
+      };
+      state.authorizations.push(row);
+      return row;
+    },
+  );
+
+  impl(
+    db.oAuthAuthorization.updateMany,
+    async ({ where, data }: { where: Where; data: Row }) => {
+      // Two production shapes: the revoke route (a client's credential by
+      // digest) and the web app's password reset (every live grant of a user).
+      const matches = state.authorizations.filter((a) => {
+        if ("accessToken" in where && a.accessToken !== where.accessToken)
+          return false;
+        if ("clientId" in where && a.clientId !== where.clientId) return false;
+        if ("userId" in where && a.userId !== where.userId) return false;
+        if ("revokedAt" in where && a.revokedAt !== where.revokedAt)
+          return false;
+        return true;
+      });
+      for (const row of matches) Object.assign(row, data);
+      return { count: matches.length };
+    },
+  );
+
+  impl(
+    db.oAuthAuthorization.findUnique,
+    async ({ where }: { where: Where }) => {
+      pickWhere(where, ["accessToken"]);
+      const row = state.authorizations.find(
+        (a) => a.accessToken === where.accessToken,
+      );
+      if (!row) return null;
+      const client = [...state.clients.values()].find(
+        (c) => c.id === row.clientId,
+      );
+      const user = state.users.get(row.userId);
+      if (!client || !user) return null;
+      return {
+        userId: row.userId,
+        expiresAt: row.expiresAt,
+        revokedAt: row.revokedAt,
+        client: { clientId: client.clientId, enabled: client.enabled },
+        user: { emailVerified: user.emailVerified },
+      };
+    },
+  );
+
+  impl(db.session.findUnique, async () => {
+    state.sessionCalls.push("findUnique");
+    return null;
+  });
+  impl(db.session.create, async () => {
+    state.sessionCalls.push("create");
+    throw new Error("fake db: a hub sign-in must never create a Session");
+  });
+
+  return state;
+}
+
+let counter = 0;
+
+export function seedUser(
+  state: FakeHubDb,
+  overrides: Partial<FakeUser> = {},
+): FakeUser {
+  counter += 1;
+  const user: FakeUser = {
+    id: `user_${counter}`,
+    name: "Pat Person",
+    email: `pat${counter}@example.com`,
+    emailVerified: true,
+    createdAt: new Date("2026-10-01T00:00:00.000Z"),
+    ...overrides,
+  };
+  state.users.set(user.id, user);
+  return user;
+}
+
+export function seedSpoke(
+  state: FakeHubDb,
+  host = "spoke.example.com",
+): SeededSpoke {
+  counter += 1;
+  const key = mintSpokeKey();
+  const spoke: FakeSpoke = {
+    id: `spoke_${counter}`,
+    workspaceId: `wksp_${counter}`,
+    name: `Spoke ${counter}`,
+    credentialHash: hashSpokeKey(key),
+    revokedAt: null,
+  };
+  state.spokes.set(spoke.id, spoke);
+
+  const secret = mintClientSecret();
+  const redirectUri = `https://${host}${HUB_CALLBACK_PATH}`;
+  const client: FakeClient = {
+    id: `oauthc_${counter}`,
+    clientId: spoke.id,
+    clientSecret: sha256Hex(secret),
+    redirectUris: [redirectUri],
+    enabled: true,
+  };
+  state.clients.set(client.clientId, client);
+
+  return {
+    spoke,
+    client,
+    key,
+    secret,
+    redirectUri,
+    basic: `Basic ${Buffer.from(`${spoke.id}:${secret}`).toString("base64")}`,
+  };
+}
+
+/** A PKCE pair: the verifier a spoke generates and the S256 challenge of it. */
+export function pkcePair(): { verifier: string; challenge: string } {
+  const verifier = Buffer.from(randomUUID() + randomUUID())
+    .toString("base64url")
+    .slice(0, 64);
+  const challenge = Buffer.from(sha256Hex(verifier), "hex").toString(
+    "base64url",
+  );
+  return { verifier, challenge };
+}

package/templates/apps/api/src/bin/spokes.ts

@@ -21,10 +21,24 @@
  *   list
  *       Every spoke: id, name, workspace, key prefix, created, revoked. Never
  *       the digest.
+ *   sign-in-client --id <spoke_id> --redirect-uri <url>
+ *       Register (or rotate) the spoke's sign-in client (#7894 D3): the hub
+ *       signs that spoke's visitors in, and the callback is the ONE registered
+ *       URL — `https:` (or `http:` on a loopback host), path exactly
+ *       `/api/hub-session/callback`, no query, fragment or userinfo. Prints the
+ *       client id and secret ONCE; re-running rotates the secret. Refuses an
+ *       unknown or revoked spoke.
+ *   sign-in-client --id <spoke_id> --disable
+ *       Switch that spoke's sign-in client off: its codes and credentials stop
+ *       at once.
  *
  * A key rotates by registering a second spoke for the workspace, deploying
  * its key, then revoking the first. There is no HTTP route for any of this.
  */
+import {
+  disableSignInClient,
+  registerSignInClient,
+} from "../lib/hub-sign-in-store.js";
 import { prisma } from "../lib/prisma.js";
 import {
   listSpokes,
@@ -36,12 +50,15 @@ const USAGE = [
   "usage: spokes register --workspace <wksp_id> --name <label>",
   "       spokes revoke --id <spoke_id>",
   "       spokes list",
+  "       spokes sign-in-client --id <spoke_id> --redirect-uri <url> | --disable",
 ].join("\n");
 
 type Flags = {
   workspace?: string | undefined;
   name?: string | undefined;
   id?: string | undefined;
+  redirectUri?: string | undefined;
+  disable?: boolean | undefined;
 };
 
 /** Minimal `--flag value` parser — no external dependency for a 3-flag CLI. */
@@ -53,7 +70,11 @@ function parseFlags(argv: string[]): Flags {
     if (flag === "--workspace") out.workspace = value;
     else if (flag === "--name") out.name = value;
     else if (flag === "--id") out.id = value;
-    else continue;
+    else if (flag === "--redirect-uri") out.redirectUri = value;
+    else if (flag === "--disable") {
+      out.disable = true;
+      continue; // a bare flag: it takes no value
+    } else continue;
     i += 1;
   }
   return out;
@@ -96,6 +117,45 @@ async function runRevoke(flags: Flags): Promise<void> {
   console.log(`[spokes] revoked spoke="${flags.id}"`);
 }
 
+async function runSignInClient(flags: Flags): Promise<void> {
+  if (!flags.id || (!flags.disable && !flags.redirectUri)) {
+    console.error(`[spokes] ${USAGE}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (flags.disable) {
+    const disabled = await disableSignInClient(flags.id);
+    if (!disabled) {
+      console.error(`[spokes] no sign-in client for spoke "${flags.id}"`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`[spokes] disabled the sign-in client of spoke="${flags.id}"`);
+    return;
+  }
+  const result = await registerSignInClient({
+    spokeId: flags.id,
+    redirectUri: flags.redirectUri ?? "",
+  });
+  if (!result.ok) {
+    const why = {
+      "invalid-redirect-uri":
+        "the redirect URI must be https (or http on localhost / 127.0.0.1), its path exactly /api/hub-session/callback, with no query, fragment or userinfo",
+      "spoke-not-found": `no spoke "${flags.id}"`,
+      "spoke-revoked": `spoke "${flags.id}" is revoked`,
+    }[result.reason];
+    console.error(`[spokes] ${result.reason}: ${why}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`[spokes] sign-in client ready for spoke="${result.spokeId}"`);
+  console.log(`AILK_HUB_CLIENT_ID=${result.spokeId}`);
+  console.log(`AILK_HUB_CLIENT_SECRET=${result.secret}`);
+  console.log(
+    "[spokes] This secret will not be shown again. Set both as the spoke's AILK_HUB_CLIENT_ID / AILK_HUB_CLIENT_SECRET now. Re-running rotates the secret.",
+  );
+}
+
 async function runList(): Promise<void> {
   const spokes = await listSpokes();
   if (spokes.length === 0) {
@@ -122,6 +182,7 @@ async function main(): Promise<void> {
   if (command === "register") return runRegister(flags);
   if (command === "revoke") return runRevoke(flags);
   if (command === "list") return runList();
+  if (command === "sign-in-client") return runSignInClient(flags);
   console.error(`[spokes] ${USAGE}`);
   process.exitCode = 1;
 }

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

@@ -119,3 +119,78 @@ describe('AILK_HUB_REQUIRE_SPOKE_KEY (#7532 D7, #7633 D2)', () => {
     expect(config).toMatchObject({ AILK_HUB_REQUIRE_SPOKE_KEY: mode });
   });
 });
+
+/**
+ * `AILK_SPOKE_FLOW_SEED` — whether a hub lets a spoke key write its own
+ * workspace's flow definitions (#7876 D3, AC-3). Off unless set: unset, empty
+ * or blank is `false`; `true`/`1` is `true`; `false`/`0` is `false` —
+ * case-insensitively, after trimming. Any other value refuses the boot with a
+ * message naming the variable, never the value. `true` warns once at boot.
+ */
+describe('AILK_SPOKE_FLOW_SEED (#7876 D3)', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+    delete process.env.AILK_SPOKE_FLOW_SEED;
+    delete process.env.AILK_HUB_REQUIRE_SPOKE_KEY;
+    process.env.DATABASE_URL = 'postgresql://test:test@localhost/test';
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    jest.restoreAllMocks();
+  });
+
+  function seedWarnings(): unknown[][] {
+    return mockLoggerWarn.mock.calls.filter((call) =>
+      JSON.stringify(call).includes('AILK_SPOKE_FLOW_SEED'),
+    );
+  }
+
+  it.each([
+    [undefined, false],
+    ['', false],
+    ['  ', false],
+    ['false', false],
+    ['0', false],
+    ['true', true],
+    ['TRUE', true],
+    ['1', true],
+    [' True ', true],
+    ['yes', null],
+  ])('parseSpokeFlowSeed(%j) is %j', (raw, expected) => {
+    const { parseSpokeFlowSeed } = require('../index');
+    expect(parseSpokeFlowSeed(raw)).toBe(expected);
+  });
+
+  it('is off by default and warns nothing', () => {
+    const { config } = require('../index');
+    expect(config).toMatchObject({ AILK_SPOKE_FLOW_SEED: false });
+    expect(seedWarnings()).toHaveLength(0);
+  });
+
+  it('on warns once at boot', () => {
+    process.env.AILK_SPOKE_FLOW_SEED = 'true';
+    const { config } = require('../index');
+    expect(config).toMatchObject({ AILK_SPOKE_FLOW_SEED: true });
+    expect(seedWarnings()).toHaveLength(1);
+  });
+
+  it('"yes" refuses the boot, naming the variable and never the value', () => {
+    process.env.AILK_SPOKE_FLOW_SEED = 'yes';
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called');
+    });
+    const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    expect(() => require('../index')).toThrow('Process exit called');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    const logged = JSON.stringify([mockLoggerError.mock.calls, consoleSpy.mock.calls]);
+    expect(logged).toContain('AILK_SPOKE_FLOW_SEED must be true, 1, false, 0 or unset');
+    expect(logged).not.toContain('yes');
+  });
+});

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

@@ -122,6 +122,11 @@ export interface Config {
   // 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;
+  // Whether a registered spoke key may write flow definitions into its own
+  // workspace through `PUT /v1/flows/:slug/definition` (#7876 D3). Off unless
+  // the hub's operator turns it on; warned at boot when on. Parsed by
+  // parseSpokeFlowSeed() below; read by routes/flows/index.ts.
+  AILK_SPOKE_FLOW_SEED: boolean;
 }
 
 /** `AILK_HUB_REQUIRE_SPOKE_KEY`'s three states (#7633 D2). */
@@ -267,6 +272,19 @@ export function parseHubRequireSpokeKey(raw: string | undefined): HubSpokeKeyMod
   return null;
 }
 
+/**
+ * `AILK_SPOKE_FLOW_SEED` (#7876 D3): unset, empty or blank → `false`;
+ * `true`/`1` → `true`; `false`/`0` → `false` — case-insensitive, after
+ * trimming. `null` for any other value, which `validateConfig()` refuses at
+ * boot.
+ */
+export function parseSpokeFlowSeed(raw: string | undefined): boolean | null {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value === '' || value === 'false' || value === '0') return false;
+  if (value === 'true' || value === '1') return true;
+  return null;
+}
+
 /** Enabled modules whose state lives in the database (see validateConfig). */
 const DATABASE_MODULES = [
   'commerce',
@@ -374,6 +392,22 @@ function validateConfig(): Config {
     );
   }
 
+  // Flow seeding is a write a spoke key could not do before (#7876 D3): a
+  // typo must never read as either state, and turning it on is never silent.
+  // The message names the variable, never its value.
+  const spokeFlowSeed = parseSpokeFlowSeed(process.env.AILK_SPOKE_FLOW_SEED);
+  if (spokeFlowSeed === null) {
+    const message = '❌ AILK_SPOKE_FLOW_SEED must be true, 1, false, 0 or unset';
+    logger.error(message);
+    console.error(message);
+    process.exit(1);
+  }
+  if (spokeFlowSeed) {
+    logger.warn(
+      "AILK_SPOKE_FLOW_SEED=true — a registered spoke key may write its own workspace's flow definitions",
+    );
+  }
+
   return {
     NODE_ENV: nodeEnv,
     PORT: parseInt(process.env.PORT || '3002', 10),
@@ -446,6 +480,7 @@ function validateConfig(): Config {
       SCHEDULING_CREDENTIAL_KEY: schedulingKey.key,
     }),
     AILK_HUB_REQUIRE_SPOKE_KEY: hubRequireSpokeKey,
+    AILK_SPOKE_FLOW_SEED: spokeFlowSeed,
   };
 }