create-ailk 0.11.4 → 0.12.0

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

@@ -0,0 +1,96 @@
+/**
+ * @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).
+ *
+ * `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.
+ */
+
+// 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(),
+  },
+}));
+
+describe('AILK_HUB_REQUIRE_SPOKE_KEY (#7532 D7)', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+    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();
+  });
+
+  it.each(['true', 'TRUE', '1', ' True '])('%j parses on', (raw) => {
+    process.env.AILK_HUB_REQUIRE_SPOKE_KEY = raw;
+    const { config } = require('../index');
+    expect(config.AILK_HUB_REQUIRE_SPOKE_KEY).toBe(true);
+  });
+
+  it.each([undefined, '', '  ', 'false', 'FALSE', '0'])('%j parses off', (raw) => {
+    if (raw !== undefined) process.env.AILK_HUB_REQUIRE_SPOKE_KEY = raw;
+    const { config } = require('../index');
+    expect(config.AILK_HUB_REQUIRE_SPOKE_KEY).toBe(false);
+  });
+
+  it('any other value refuses the boot, naming the variable and never the value', () => {
+    process.env.AILK_HUB_REQUIRE_SPOKE_KEY = 'yes-sentinel-value';
+    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_HUB_REQUIRE_SPOKE_KEY');
+    expect(logged).not.toContain('yes-sentinel-value');
+  });
+
+  it('on with DATABASE_URL unset refuses the boot', () => {
+    process.env.AILK_HUB_REQUIRE_SPOKE_KEY = 'true';
+    delete process.env.DATABASE_URL;
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called');
+    });
+    jest.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    expect(() => require('../index')).toThrow('Process exit called');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(JSON.stringify(mockLoggerError.mock.calls)).toContain(
+      'AILK_HUB_REQUIRE_SPOKE_KEY',
+    );
+  });
+
+  it('off with DATABASE_URL unset still boots database-less, as today', () => {
+    delete process.env.DATABASE_URL;
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called');
+    });
+
+    const { config } = require('../index');
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(config.AILK_HUB_REQUIRE_SPOKE_KEY).toBe(false);
+  });
+});

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

@@ -102,6 +102,23 @@ export interface Config {
   // nothing (§ D2 row 1) — the same fail-closed posture STRIPE_WEBHOOK_SECRET
   // unset already has.
   CAL_WEBHOOK_SECRET?: string;
+
+  // Per-workspace scheduling connections (#7533 D2) — the AES-256-GCM key
+  // services/scheduling/connections.ts encrypts each connection's provider
+  // credential and webhook secret under. Canonical standard base64 of exactly
+  // 32 random bytes (`openssl rand -base64 32`), checked at startup by
+  // resolveSchedulingCredentialKey() below; a refused value stops the API.
+  // Optional: unset (or empty) means connections cannot be written, and the
+  // 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;
 }
 
 /** Why an AILK_TRUSTED_ORIGINS entry was refused (#7395 D2). */
@@ -201,6 +218,47 @@ export function resolveTrustedOrigins(env: {
   return { origins: Object.freeze([...new Set(origins)]), refused, primaryUnusable };
 }
 
+/** Why a SCHEDULING_CREDENTIAL_KEY value was refused (#7533 D2). */
+export type SchedulingCredentialKeyRefusal = 'not-canonical-base64' | 'length';
+
+/**
+ * The scheduling-connection key (#7533 D2, SEC-7533-6). Pure;
+ * `validateConfig()` calls it once.
+ *
+ * Accepts only CANONICAL standard base64 — `Buffer.from(v, 'base64')
+ * .toString('base64') === v` — of exactly 32 bytes. Base64 decoding silently
+ * skips characters outside its alphabet, so without the round-trip a
+ * base64url value, or a passphrase that happens to decode to 32 bytes, would
+ * be taken as a key. `''` and unset are both `unset`. A refusal carries the
+ * reason kind only, never any part of the value.
+ */
+export function resolveSchedulingCredentialKey(
+  raw: string | undefined,
+):
+  | { kind: 'unset' }
+  | { kind: 'ok'; key: Buffer }
+  | { kind: 'refused'; reason: SchedulingCredentialKeyRefusal } {
+  if (raw === undefined || raw === '') return { kind: 'unset' };
+  const key = Buffer.from(raw, 'base64');
+  if (key.toString('base64') !== raw) {
+    return { kind: 'refused', reason: 'not-canonical-base64' };
+  }
+  if (key.length !== 32) return { kind: 'refused', reason: 'length' };
+  return { kind: 'ok', key };
+}
+
+/**
+ * `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.
+ */
+export function parseHubRequireSpokeKey(raw: string | undefined): boolean | null {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value === 'true' || value === '1') return true;
+  if (value === '' || value === 'false' || value === '0') return false;
+  return null;
+}
+
 /** Enabled modules whose state lives in the database (see validateConfig). */
 const DATABASE_MODULES = [
   'commerce',
@@ -267,6 +325,40 @@ function validateConfig(): Config {
     );
   }
 
+  // #7533 D2 — a set-but-refused SCHEDULING_CREDENTIAL_KEY stops the API in
+  // every environment, as a refused AILK_TRUSTED_ORIGINS entry does: a key
+  // taken in some other shape would encrypt every connection under a value
+  // the operator did not mean. The reason kind only, never the value.
+  const schedulingKey = resolveSchedulingCredentialKey(process.env.SCHEDULING_CREDENTIAL_KEY);
+  if (schedulingKey.kind === 'refused') {
+    const message =
+      '❌ SCHEDULING_CREDENTIAL_KEY must be canonical standard base64 of exactly 32 bytes (openssl rand -base64 32)';
+    logger.error({ reason: schedulingKey.reason }, message);
+    console.error(message, JSON.stringify({ reason: schedulingKey.reason }));
+    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.
+  const hubRequireSpokeKey = parseHubRequireSpokeKey(process.env.AILK_HUB_REQUIRE_SPOKE_KEY);
+  if (hubRequireSpokeKey === null) {
+    const message =
+      '❌ AILK_HUB_REQUIRE_SPOKE_KEY must be true, 1, false, 0 or unset';
+    logger.error(message);
+    console.error(message);
+    process.exit(1);
+  }
+  if (hubRequireSpokeKey && !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);
+  }
+
   return {
     NODE_ENV: nodeEnv,
     PORT: parseInt(process.env.PORT || '3002', 10),
@@ -334,6 +426,11 @@ function validateConfig(): Config {
     ...(process.env.CAL_WEBHOOK_SECRET !== undefined && {
       CAL_WEBHOOK_SECRET: process.env.CAL_WEBHOOK_SECRET,
     }),
+
+    ...(schedulingKey.kind === 'ok' && {
+      SCHEDULING_CREDENTIAL_KEY: schedulingKey.key,
+    }),
+    AILK_HUB_REQUIRE_SPOKE_KEY: hubRequireSpokeKey === true,
   };
 }
 

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

@@ -43,3 +43,41 @@ function enabledModules(): Set<string> {
 export function isModuleEnabled(moduleName: string): boolean {
   return enabledModules().has(moduleName);
 }
+
+/**
+ * The recognized optional-module keys, sorted — the vocabulary the root index
+ * may report (#7501). Filtering to this list is what keeps the anonymous
+ * `GET /` from echoing whatever text an operator typed into
+ * `AILK_ENABLED_MODULES`. `docs` is deliberately absent: no apps/api route
+ * registers under it, so reporting it would break "modules this process
+ * registered routes for".
+ */
+export const OPTIONAL_MODULES = [
+  "commerce",
+  "content-write",
+  "multi-tenant",
+  "scheduling",
+  "signal-collectors",
+  "workspace",
+] as const;
+
+/**
+ * The optional modules whose routes this process registers, sorted. Called
+ * once at build time by `server.ts`, so the answer matches what registered
+ * even if the env changes afterwards.
+ *
+ * `content-write` counts only alongside a tenancy module (`workspace` or
+ * `multi-tenant`) — the exact predicate `server.ts` registers the editor's
+ * content routes under. That gate stays a literal there (the
+ * slice-registration lint reads `isModuleEnabled("X")` guards by text), so the
+ * predicate is repeated here and `root-modules.test.ts` asserts they agree.
+ */
+export function servedModules(): string[] {
+  return OPTIONAL_MODULES.filter((name) => {
+    if (!isModuleEnabled(name)) return false;
+    if (name === "content-write") {
+      return isModuleEnabled("workspace") || isModuleEnabled("multi-tenant");
+    }
+    return true;
+  });
+}

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

@@ -161,6 +161,11 @@ export const prisma = {
     upsert: jest.fn(),
     deleteMany: jest.fn(),
   },
+  // `findUnique` — the public meetings read (`lib/public-meetings-config.ts`),
+  // which a spoke's meeting-types read and booking gate reach (#7532 D3/D4).
+  workspaceMeetings: {
+    findUnique: jest.fn(),
+  },
   // ── Inbox namespace (Lead, Subscriber, Callback) ─────────────────────────
   lead: {
     create: jest.fn(),
@@ -355,6 +360,33 @@ export const prisma = {
     findMany: jest.fn(),
     updateMany: jest.fn(),
   },
+  // ── Config namespace (SchedulingConnection — #7533) ─────────────────────
+  // Every call lives in services/scheduling/connections.ts: `findUnique` by
+  // `workspaceId` (the provider read + the summary) or by `webhookToken` (the
+  // per-connection webhook); `upsert` keyed on the tenant's workspace (the
+  // connect/replace write); `deleteMany` keyed the same way (the revoke).
+  schedulingConnection: {
+    findUnique: jest.fn(),
+    upsert: jest.fn(),
+    deleteMany: jest.fn(),
+  },
+  // ── #7532 — the hub's spoke registry (auth) and the booking origin (inbox) ─
+  // `spoke.findUnique` — the resolver's one lookup by credential digest;
+  // `create`/`updateMany`/`findMany` — the operator CLI's register, revoke and
+  // list (`lib/spoke-store.ts`). `appointmentOrigin.createMany` — the bind's
+  // ON CONFLICT DO NOTHING insert; `findUnique` — the origin read the bind and
+  // the webhook make (`services/scheduling/appointments.ts`).
+  spoke: {
+    findUnique: jest.fn(),
+    findFirst: jest.fn(),
+    findMany: jest.fn(),
+    create: jest.fn(),
+    updateMany: jest.fn(),
+  },
+  appointmentOrigin: {
+    findUnique: jest.fn(),
+    createMany: jest.fn(),
+  },
   // ── Content namespace (UsageEvent, UsagePeriod — FEAT-047 P1.S1/#3709) ──
   usageEvent: {
     create: jest.fn(),
@@ -385,6 +417,9 @@ export const prisma = {
   // `mockTransaction` helper models commit/rollback so atomicity is asserted,
   // not assumed.
   $transaction: jest.fn(),
+  // `$executeRaw` — the per-booking `pg_advisory_xact_lock` (#7532 D5),
+  // taken inside `$transaction`. Suites on that path arm both.
+  $executeRaw: jest.fn(),
   $connect: jest.fn(),
   $disconnect: jest.fn(),
 };

package/templates/apps/api/src/lib/__tests__/spoke-store.test.ts

@@ -0,0 +1,152 @@
+/**
+ * @file spoke-store.test.ts
+ *
+ * The hub's spoke registry boundary (#7532, spec
+ * docs/specs/7532-a-spoke-s-public-reads-spec.md D2, D7, AC-5): minting a key,
+ * its digest, the one lookup the resolver makes, and the three operator
+ * functions the `spokes` CLI calls.
+ *
+ * External dependency boundary mocked:
+ *   - @working-theory/database (via the prisma singleton; __mocks__/prisma.ts)
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../prisma.js");
+
+import { createHash } from "node:crypto";
+
+import { prisma } from "../prisma.js";
+import {
+  SPOKE_KEY_PREFIX,
+  findSpokeByKeyHash,
+  hashSpokeKey,
+  listSpokes,
+  mintSpokeKey,
+  registerSpoke,
+  revokeSpoke,
+} from "../spoke-store.js";
+
+const db = jest.mocked(prisma);
+
+const W1 = "wksp_00000000-0000-7000-8000-0000000000b1";
+const S1 = "spoke_00000000-0000-7000-8000-0000000000c1";
+
+beforeEach(() => {
+  jest.resetAllMocks();
+});
+
+describe("mintSpokeKey / hashSpokeKey (D2)", () => {
+  it("mints `ailk_spk_` + 32 random bytes in base64url — 52 characters", () => {
+    const key = mintSpokeKey();
+    expect(key.startsWith(SPOKE_KEY_PREFIX)).toBe(true);
+    expect(key).toHaveLength(52);
+    expect(key.slice(SPOKE_KEY_PREFIX.length)).toMatch(/^[A-Za-z0-9_-]{43}$/);
+  });
+
+  it("never mints the same key twice", () => {
+    const keys = new Set(Array.from({ length: 50 }, () => mintSpokeKey()));
+    expect(keys.size).toBe(50);
+  });
+
+  it("digests the TRIMMED key to lowercase hex SHA-256", () => {
+    const key = mintSpokeKey();
+    const expected = createHash("sha256").update(key).digest("hex");
+    expect(hashSpokeKey(key)).toBe(expected);
+    expect(hashSpokeKey(`  ${key}\t`)).toBe(expected);
+    expect(hashSpokeKey(key)).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+describe("findSpokeByKeyHash (D3 step 5)", () => {
+  it("is one findUnique by digest, selecting only what the resolver needs", async () => {
+    const row = { id: S1, workspaceId: W1, revokedAt: null };
+    db.spoke.findUnique.mockResolvedValue(row as never);
+    const digest = "a".repeat(64);
+
+    await expect(findSpokeByKeyHash(digest)).resolves.toEqual(row);
+    expect(db.spoke.findUnique).toHaveBeenCalledTimes(1);
+    expect(db.spoke.findUnique).toHaveBeenCalledWith({
+      where: { credentialHash: digest },
+      select: { id: true, workspaceId: true, revokedAt: true },
+    });
+  });
+
+  it("answers null when no row carries the digest", async () => {
+    db.spoke.findUnique.mockResolvedValue(null);
+    await expect(findSpokeByKeyHash("b".repeat(64))).resolves.toBeNull();
+  });
+});
+
+describe("registerSpoke (D7, AC-5)", () => {
+  it("stores the key's digest and a 17-character prefix, never the key", async () => {
+    db.workspace.findUnique.mockResolvedValue({ id: W1 } as never);
+    db.spoke.create.mockImplementation((async (args: {
+      data: Record<string, unknown>;
+    }) => ({ id: S1, createdAt: new Date(), ...args.data })) as never);
+
+    const result = await registerSpoke({ workspaceId: W1, name: "acme" });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const createArg = db.spoke.create.mock.calls[0]![0] as {
+      data: Record<string, unknown>;
+    };
+    expect(createArg.data["credentialHash"]).toMatch(/^[0-9a-f]{64}$/);
+    expect(createArg.data["credentialHash"]).toBe(hashSpokeKey(result.key));
+    expect(createArg.data["credentialPrefix"]).toBe(result.key.slice(0, 17));
+    expect(createArg.data["workspaceId"]).toBe(W1);
+    expect(createArg.data["name"]).toBe("acme");
+    // No create argument equals the returned key.
+    expect(JSON.stringify(createArg)).not.toContain(result.key);
+    expect(result.spoke.id).toBe(S1);
+  });
+
+  it("refuses a workspace that does not exist, creating nothing", async () => {
+    db.workspace.findUnique.mockResolvedValue(null);
+
+    await expect(
+      registerSpoke({ workspaceId: W1, name: "acme" }),
+    ).resolves.toEqual({ ok: false, reason: "workspace-not-found" });
+    expect(db.spoke.create).not.toHaveBeenCalled();
+  });
+});
+
+describe("revokeSpoke (D7, AC-5)", () => {
+  it("sets revokedAt on that one unrevoked row only", async () => {
+    db.spoke.updateMany.mockResolvedValue({ count: 1 });
+
+    await expect(revokeSpoke(S1)).resolves.toBe(true);
+    const arg = db.spoke.updateMany.mock.calls[0]![0] as {
+      where: unknown;
+      data: { revokedAt: unknown };
+    };
+    expect(arg.where).toEqual({ id: S1, revokedAt: null });
+    expect(arg.data.revokedAt).toBeInstanceOf(Date);
+  });
+
+  it("reports false when no unrevoked row matched", async () => {
+    db.spoke.updateMany.mockResolvedValue({ count: 0 });
+    await expect(revokeSpoke(S1)).resolves.toBe(false);
+  });
+});
+
+describe("listSpokes (D7, AC-5)", () => {
+  it("never selects the credential digest", async () => {
+    db.spoke.findMany.mockResolvedValue([]);
+
+    await listSpokes();
+
+    const arg = db.spoke.findMany.mock.calls[0]![0] as {
+      select: Record<string, boolean>;
+    };
+    expect(arg.select).not.toHaveProperty("credentialHash");
+    expect(arg.select).toEqual({
+      id: true,
+      name: true,
+      workspaceId: true,
+      credentialPrefix: true,
+      createdAt: true,
+      revokedAt: true,
+    });
+  });
+});

package/templates/apps/api/src/lib/spoke-store.ts

@@ -0,0 +1,131 @@
+/**
+ * The hub's spoke registry — its ONE data-access boundary (#7532, spec
+ * docs/specs/7532-a-spoke-s-public-reads-spec.md D1, D2, D7).
+ *
+ * A spoke is a separately deployed site that calls this API server-to-server,
+ * bound to exactly one workspace. It authenticates with a hub-minted key sent
+ * in `x-ailk-spoke-key`. This file is the only one that names `prisma.spoke`.
+ *
+ * THE KEY IS NEVER STORED. The row keeps the lowercase hex SHA-256 of the
+ * trimmed key (`credentialHash`) and its first 17 characters
+ * (`credentialPrefix`: `ailk_spk_` plus 8 random ones) so an operator can
+ * recognise a key in a list. A fast digest is enough: the key carries 256
+ * bits of entropy, so a lookup by its unique digest leaks nothing usable.
+ *
+ * WHAT A KEY PROVES. It identifies a deployed SITE, not a person: every
+ * anonymous visitor of that site, and every agent using its `apps/mcp`, acts
+ * through it. It grants what the site's anonymous visitors can already do on
+ * the hub — read that workspace's enabled meeting types and public content,
+ * and write leads and bookings into it.
+ *
+ * Two kinds of caller, kept apart:
+ *   - the public resolver (`services/public-site-resolver.ts`) calls
+ *     `hashSpokeKey` and `findSpokeByKeyHash` only;
+ *   - the operator CLI (`bin/spokes.ts`) calls `registerSpoke`, `revokeSpoke`
+ *     and `listSpokes`. No route imports them.
+ *
+ * Nothing caches a row: a revocation takes effect on the next request (NFR4).
+ */
+import { createHash, randomBytes } from "node:crypto";
+
+import { prisma } from "./prisma.js";
+
+/** Every spoke key starts with this, so a leaked one is recognisable. */
+export const SPOKE_KEY_PREFIX = "ailk_spk_";
+
+/** How much of the key the row keeps for recognition: the prefix + 8 characters. */
+const CREDENTIAL_PREFIX_LENGTH = SPOKE_KEY_PREFIX.length + 8;
+
+/** A new key: `ailk_spk_` + 32 random bytes in base64url (52 characters). */
+export function mintSpokeKey(): string {
+  return `${SPOKE_KEY_PREFIX}${randomBytes(32).toString("base64url")}`;
+}
+
+/** The stored digest of a key: lowercase hex SHA-256 of the TRIMMED value. */
+export function hashSpokeKey(key: string): string {
+  return createHash("sha256").update(key.trim()).digest("hex");
+}
+
+export interface SpokeLookupRow {
+  id: string;
+  workspaceId: string;
+  revokedAt: Date | null;
+}
+
+/** The one read the resolver makes: a `findUnique` by digest. */
+export async function findSpokeByKeyHash(
+  credentialHash: string,
+): Promise<SpokeLookupRow | null> {
+  return prisma.spoke.findUnique({
+    where: { credentialHash },
+    select: { id: true, workspaceId: true, revokedAt: true },
+  });
+}
+
+// ── Operator functions — `bin/spokes.ts` only ────────────────────────────────
+
+export interface SpokeListRow {
+  id: string;
+  name: string;
+  workspaceId: string;
+  credentialPrefix: string;
+  createdAt: Date;
+  revokedAt: Date | null;
+}
+
+const SPOKE_LIST_SELECT = {
+  id: true,
+  name: true,
+  workspaceId: true,
+  credentialPrefix: true,
+  createdAt: true,
+  revokedAt: true,
+} as const;
+
+export type RegisterSpokeResult =
+  | { ok: true; spoke: SpokeListRow; key: string }
+  | { ok: false; reason: "workspace-not-found" };
+
+/**
+ * Register a spoke bound to one existing workspace. The returned `key` is the
+ * only copy that will ever exist: the caller prints it once.
+ */
+export async function registerSpoke(params: {
+  workspaceId: string;
+  name: string;
+}): Promise<RegisterSpokeResult> {
+  const workspace = await prisma.workspace.findUnique({
+    where: { id: params.workspaceId },
+    select: { id: true },
+  });
+  if (!workspace) return { ok: false, reason: "workspace-not-found" };
+
+  const key = mintSpokeKey();
+  const spoke = await prisma.spoke.create({
+    data: {
+      workspaceId: params.workspaceId,
+      name: params.name,
+      credentialHash: hashSpokeKey(key),
+      credentialPrefix: key.slice(0, CREDENTIAL_PREFIX_LENGTH),
+    },
+    select: SPOKE_LIST_SELECT,
+  });
+  return { ok: true, spoke, key };
+}
+
+/** Revoke one spoke. `false` when no unrevoked spoke has that id. */
+export async function revokeSpoke(id: string): Promise<boolean> {
+  const { count } = await prisma.spoke.updateMany({
+    where: { id, revokedAt: null },
+    data: { revokedAt: new Date() },
+  });
+  return count === 1;
+}
+
+/** Every spoke, newest first. Never selects the credential digest. */
+export async function listSpokes(): Promise<SpokeListRow[]> {
+  return prisma.spoke.findMany({
+    select: SPOKE_LIST_SELECT,
+    orderBy: { createdAt: "desc" },
+  });
+}