create-ailk 0.12.1 → 0.13.0

package/templates/apps/web/lib/relay.ts

@@ -0,0 +1,279 @@
+/**
+ * The same-origin relay (#7644, spec docs/specs/7644-the-browser-talks-only-to-spec.md).
+ *
+ * A visitor's browser posts lead capture, newsletter signup, flow submits and
+ * booking calls to THIS site's own address — `resolveSubmitUrl` leaves a
+ * root-relative action alone in a build of this app (next.config.mjs sets
+ * `NEXT_PUBLIC_AILK_SAME_ORIGIN_RELAY`). `app/v1/[...path]/route.ts` hands
+ * every `/v1/...` request here, and this module forwards it server-side to
+ * the hub through `@working-theory/api-client`'s `relayToApi`, which attaches
+ * the site's own `AILK_SPOKE_KEY` when it has one. A browser never holds the
+ * key and never calls the hub, so a hub can refuse callers it does not know
+ * (#7633) without taking any site's forms down. A single-site install takes
+ * the same path with no key.
+ *
+ * What it guarantees:
+ *
+ *   - ONLY THE LIST (D2). `RELAY_ROUTES` is the fixed set of (method, path)
+ *     pairs a browser form calls; an exact, case-sensitive match on the
+ *     pathname or a 404 with no hub call. Adding a route is a reviewed change
+ *     to this list, its test and apps/web/.env.example.
+ *   - NO CROSS-SITE POST (D4). `Sec-Fetch-Site` other than `same-origin`, or
+ *     an `Origin` whose host is not this site's own, is refused with 403
+ *     before the hub is called. A POST must be JSON, which no cross-origin
+ *     browser can send without a preflight this route never answers.
+ *   - THE VISITOR, UNCHANGED (D3). `x-forwarded-for` as received (else
+ *     `x-real-ip`) and `user-agent` reach the hub, so per-visitor rate limits
+ *     still count each visitor (#7615's rule; `flow.actions.ts`).
+ *   - AN ALLOW-LIST OF HEADERS (D3). Nothing else from the incoming request is
+ *     forwarded: no `authorization`, no client-sent `x-ailk-*`, no `host`, and
+ *     a `cookie` only on the one session route.
+ *
+ * NO SECRET IS LOGGED. A failure logs `{ path, outcome }` and nothing else.
+ */
+import { relayToApi, visitorForwardHeaders } from "@working-theory/api-client";
+
+type RelayMethod = "GET" | "POST";
+
+/** One relayed (method, path) pair. */
+export interface RelayRoute {
+  readonly method: RelayMethod;
+  readonly path: string;
+}
+
+function route(method: RelayMethod, path: string): RelayRoute {
+  return Object.freeze({ method, path });
+}
+
+/**
+ * The fixed list (D2). The scheduling and commerce paths are plain strings:
+ * on a hub without those modules the hub's own 404 passes through.
+ */
+/**
+ * The one session route: a site-admin, cookie-authenticated write. It is
+ * forwarded with the visitor's `cookie` and `Origin` (the hub still checks
+ * that `Origin` against its trusted list), mirroring `forwardedCookieInit` in
+ * lib/server-api.ts. Every other entry is a visitor route.
+ */
+const SESSION_ROUTE = route("POST", "/v1/commerce/invoices");
+
+export const RELAY_ROUTES: readonly RelayRoute[] = Object.freeze([
+  route("POST", "/v1/leads/submit"),
+  route("POST", "/v1/leads/subscribe"),
+  route("POST", "/v1/leads/callback"),
+  route("GET", "/v1/schedule/availability"),
+  route("POST", "/v1/schedule/book"),
+  SESSION_ROUTE,
+]);
+
+/** Fastify's default `bodyLimit`; the hub sets none (NFR4). */
+const RELAY_BODY_LIMIT = 1_048_576;
+
+/** Set on every forwarded call; an incoming request carrying it is a loop. */
+const RELAYED_HEADER = "x-ailk-relayed";
+
+/** Set on every answer: never cached, never content-sniffed by the browser. */
+const BASE_RESPONSE_HEADERS = {
+  "cache-control": "no-store",
+  "x-content-type-options": "nosniff",
+} as const;
+
+function refusal(status: number, code: string, message: string): Response {
+  return Response.json(
+    { ok: false, error: { code, message } },
+    { status, headers: BASE_RESPONSE_HEADERS },
+  );
+}
+
+/**
+ * True when the site has an API address to forward to. `getApiBase()` falls
+ * back to `http://localhost:3001` for local development; a production site
+ * with no address set must not send its visitors' calls (and its key) there.
+ */
+function hubConfigured(): boolean {
+  if (process.env.NODE_ENV !== "production") return true;
+  return Boolean(
+    process.env.AILK_API_URL ||
+      process.env.NEXT_PUBLIC_AILK_API_URL ||
+      process.env.NEXT_PUBLIC_API_URL,
+  );
+}
+
+/**
+ * The host the browser addressed: the first `x-forwarded-host`, else `host`.
+ * The site's edge must overwrite `x-forwarded-host`, never pass a client's on.
+ */
+function ownHost(request: Request): string {
+  const forwarded = request.headers.get("x-forwarded-host")?.split(",")[0];
+  if (forwarded) return forwarded.trim();
+  return request.headers.get("host") ?? new URL(request.url).host;
+}
+
+/**
+ * True when the request is a cross-site browser call (D4 step 3). A request
+ * with neither `Sec-Fetch-Site` nor `Origin` is a non-browser caller and is
+ * admitted: it can forge either header anyway.
+ */
+function isCrossSite(request: Request): boolean {
+  const fetchSite = request.headers.get("sec-fetch-site");
+  if (fetchSite !== null && fetchSite !== "same-origin") return true;
+
+  const origin = request.headers.get("origin");
+  if (origin === null) return false;
+  try {
+    const originUrl = new URL(origin);
+    // Parsing the own host under the Origin's scheme normalises a default
+    // port and letter case, so `spoke.example:443` equals `spoke.example`.
+    const own = new URL(`${originUrl.protocol}//${ownHost(request)}`);
+    return originUrl.host !== own.host;
+  } catch {
+    // `null`, or anything that is not a URL.
+    return true;
+  }
+}
+
+function isJson(contentType: string | null): boolean {
+  return (
+    contentType?.split(";")[0]?.trim().toLowerCase() === "application/json"
+  );
+}
+
+/**
+ * The body as text, or `null` once it passes `limit` bytes. Read as a stream
+ * so an oversized body is refused without buffering all of it.
+ */
+async function readCapped(
+  request: Request,
+  limit: number,
+): Promise<string | null> {
+  const declared = Number(request.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > limit) return null;
+  if (!request.body) return "";
+
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+
+/** The outbound headers, built from an allow-list (D3). Never a spread of the incoming set. */
+function relayHeaders(
+  request: Request,
+  entry: RelayRoute,
+): Record<string, string> {
+  const incoming = request.headers;
+  const out: Record<string, string> = { [RELAYED_HEADER]: "1" };
+
+  const contentType = incoming.get("content-type");
+  if (entry.method === "POST" && contentType) out["content-type"] = contentType;
+
+  const userAgent = incoming.get("user-agent");
+  if (userAgent) out["user-agent"] = userAgent;
+
+  const visitorIp =
+    incoming.get("x-forwarded-for") ?? incoming.get("x-real-ip");
+  if (visitorIp) out["x-forwarded-for"] = visitorIp;
+
+  if (entry === SESSION_ROUTE) {
+    const cookie = incoming.get("cookie");
+    if (cookie) out.cookie = cookie;
+    const origin = incoming.get("origin");
+    if (origin) out.origin = origin;
+  } else {
+    Object.assign(
+      out,
+      visitorForwardHeaders(incoming, process.env.AILK_VISITOR_FORWARD_KEY),
+    );
+  }
+  return out;
+}
+
+/** Answer one `/v1/...` request to this site: refuse it, or forward it to the hub. */
+export async function handleRelay(request: Request): Promise<Response> {
+  if (request.headers.has(RELAYED_HEADER)) {
+    return refusal(508, "relay_loop", "Request already relayed");
+  }
+
+  const url = new URL(request.url);
+  const entry = RELAY_ROUTES.find(
+    (r) => r.method === request.method && r.path === url.pathname,
+  );
+  if (!entry) return refusal(404, "not_found", "Not found");
+
+  if (isCrossSite(request)) {
+    return refusal(403, "cross_site", "Cross-site request refused");
+  }
+
+  let body: string | undefined;
+  if (entry.method === "POST") {
+    if (!isJson(request.headers.get("content-type"))) {
+      return refusal(415, "unsupported_media_type", "Expected application/json");
+    }
+    const text = await readCapped(request, RELAY_BODY_LIMIT);
+    if (text === null) {
+      return refusal(413, "payload_too_large", "Request body too large");
+    }
+    body = text;
+  }
+
+  if (!hubConfigured()) {
+    console.error("[relay] hub call failed", {
+      path: entry.path,
+      outcome: "no-api-address",
+    });
+    return refusal(502, "relay_unreachable", "The site could not reach its API");
+  }
+
+  try {
+    const result = await relayToApi(
+      entry.method === "GET" ? `${entry.path}${url.search}` : entry.path,
+      {
+        method: entry.method,
+        headers: relayHeaders(request, entry),
+        ...(body !== undefined ? { body } : {}),
+      },
+    );
+    // Only a JSON answer keeps its content-type; anything else (an HTML error
+    // page from a proxy in front of the hub) is served as plain text, so it
+    // can never render as markup on this site's origin.
+    const headers: Record<string, string> = {
+      ...BASE_RESPONSE_HEADERS,
+      "content-type":
+        result.contentType && isJson(result.contentType)
+          ? result.contentType
+          : "text/plain; charset=utf-8",
+    };
+    if (result.retryAfter) headers["retry-after"] = result.retryAfter;
+    // A null-body status (204, 304) cannot carry even an empty string.
+    return new Response(result.body === "" ? null : result.body, {
+      status: result.status,
+      headers,
+    });
+  } catch (err) {
+    // The error's name only (TypeError for a refused redirect or a network
+    // failure, TimeoutError for a hub that never answered) — never its
+    // message, which can quote a request detail.
+    console.error("[relay] hub call failed", {
+      path: entry.path,
+      outcome: "unreachable",
+      error: err instanceof Error ? err.name : "unknown",
+    });
+    return refusal(502, "relay_unreachable", "The site could not reach its API");
+  }
+}

package/templates/apps/web/middleware.ts

@@ -12,9 +12,10 @@
 // Locale list: read once at module load from project.yaml via readLocales() (S1).
 // Static assets and internal Next.js paths are excluded via the matcher below.
 //
-// /api/* and /og are route handlers outside app/[locale] (#6864). They skip
-// next-intl — whose as-needed rewrite would send them to /en/api/… and /en/og,
-// which do not exist — but still get the security headers. They are exempted
+// /api/*, /og and /v1/* are route handlers outside app/[locale] (#6864; /v1
+// is the same-origin relay, #7644). They skip next-intl — whose as-needed
+// rewrite would send them to /en/api/…, /en/og and /en/v1/…, which do not
+// exist — but still get the security headers. They are exempted
 // here rather than in the matcher, because this middleware is the only place
 // the security headers are stamped.
 //
@@ -57,7 +58,7 @@ const intlMiddleware = createMiddleware({
 
 // Top-level app/ route directories that live outside [locale]. Kept in step
 // with app/ by the drift test in __tests__/i18n/middleware.test.ts.
-export const NON_LOCALE_ROUTE_PREFIXES = ["/api", "/og"] as const;
+export const NON_LOCALE_ROUTE_PREFIXES = ["/api", "/og", "/v1"] as const;
 
 // Segment-bound: /og and /og/x are exempt; /ogden and /og-image are not.
 export function isNonLocaleRoute(pathname: string): boolean {

package/templates/apps/web/next.config.mjs

@@ -148,6 +148,12 @@ const nextConfig = {
     // Default locale baked at build time — consumed by the sitemap route for
     // x-default URL composition and bare-path default-locale serving.
     NEXT_PUBLIC_DEFAULT_LOCALE: defaultLocaleAtBuild,
+    // This site serves the same-origin relay (app/v1/[...path]/route.ts,
+    // #7644), so @working-theory/ui's resolveSubmitUrl leaves a form's
+    // root-relative action on this site's own address instead of rewriting it
+    // onto the hub's. Part of the source, not an operator setting: a build
+    // that carries the relay always carries the flag, and no other build does.
+    NEXT_PUBLIC_AILK_SAME_ORIGIN_RELAY: "1",
   },
   async headers() {
     if (!STEALTH) return [];

package/templates/database/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @working-theory/database
 
+## 0.35.0
+
+### Minor Changes
+
+- [#7671](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/7671) [`25d4a69`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/25d4a699cefaac7cf9c73dafa802696ebdc995e8) Thanks [@claudio-planck](https://github.com/claudio-planck)! - The agent seat, step A ([#3591](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/3591), PR-A of docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md).
+
+  - `@working-theory/database` — a new `auth` model, `Agent`, and its enum `AgentPermissionLevel` (`member`): a stored delegate of one person, bound to one workspace, keeping only the SHA-256 digest of its key. The migration `20261005120000_agents` is purely additive: one table, its indexes, the ADR-0031 `agent_` primary-key CHECK and format CHECKs on every reference column. Deleting the organization, the workspace or the person's membership deletes the agent; deleting the membership of the person last shown its key clears `key_issued_to_membership_id`.
+  - `@working-theory/ids` — registers the `agent_` prefix and exports `zAgentId`.
+
+### Patch Changes
+
+- Updated dependencies [[`589b167`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/589b167dcd5acb83cb37b46bd5cdb0a57a80df1a), [`25d4a69`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/25d4a699cefaac7cf9c73dafa802696ebdc995e8), [`0fb0f37`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/0fb0f3727db9ad32776b88f39ec8b0943671bcad), [`a6833f9`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/a6833f940da064c36f3150a4af614c9fd8b38628)]:
+  - @working-theory/validation@0.35.0
+  - @working-theory/ids@0.10.0
+
 ## 0.34.1
 
 ### Patch Changes

package/templates/database/__tests__/agents.db.test.ts

@@ -0,0 +1,235 @@
+/**
+ * @file agents.db.test.ts
+ *
+ * LIVE-DATABASE proof of the agents table (#3591, spec
+ * docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md D1; AC-1 and AC-2's
+ * cascade legs). Requires DATABASE_URL pointing at a Postgres with the
+ * migrations applied — the whole suite SKIPS when DATABASE_URL is unset,
+ * keeping the workspace Jest run DB-free (the repo convention; the
+ * `apps/api Route Tests (Postgres)` workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `spoke-registry.db.test.ts` does. What it
+ * proves that a mock cannot:
+ *   1. The six format CHECKs reject a malformed id.
+ *   2. `credential_hash` is unique.
+ *   3. Deleting the responsible person's membership, the workspace or the
+ *      organization deletes the agent — so a re-invited person's new
+ *      membership cannot revive it.
+ *   4. Deleting the membership of the person last shown the key sets
+ *      `key_issued_to_membership_id` null and keeps the agent.
+ *   5. Deleting the creator's user row leaves the agent (no relation).
+ */
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+const AGENT_ID = /^agent_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+describeDb("the agents table (#3591, live DB)", () => {
+  let db: Client;
+  let organizationId: string;
+  let workspaceId: string;
+  let ownerUserId: string;
+  let personUserId: string;
+  let ownerMembershipId: string;
+  let personMembershipId: string;
+  let hashSeq = 0;
+
+  /** A fresh 64-character digest per insert, so the unique key never collides by accident. */
+  function nextHash(): string {
+    hashSeq += 1;
+    return hashSeq.toString(16).padStart(64, "0");
+  }
+
+  async function insertUser(tag: string): Promise<string> {
+    return (
+      await db.query<{ id: string }>(
+        `INSERT INTO "users" ("email", "updated_at") VALUES ($1, now()) RETURNING "id"`,
+        [`agents3591-${tag}@example.test`],
+      )
+    ).rows[0]!.id;
+  }
+
+  async function insertOrganization(slug: string): Promise<string> {
+    return (
+      await db.query<{ id: string }>(
+        `INSERT INTO "organizations" ("name", "slug", "updated_at")
+         VALUES ($1, $1, now()) RETURNING "id"`,
+        [`agents3591-${slug}`],
+      )
+    ).rows[0]!.id;
+  }
+
+  async function insertWorkspace(orgId: string, slug: string): Promise<string> {
+    return (
+      await db.query<{ id: string }>(
+        `INSERT INTO "workspaces" ("organization_id", "name", "slug", "updated_at")
+         VALUES ($1, $2, $2, now()) RETURNING "id"`,
+        [orgId, slug],
+      )
+    ).rows[0]!.id;
+  }
+
+  async function insertMembership(orgId: string, userId: string, role: string): Promise<string> {
+    return (
+      await db.query<{ id: string }>(
+        `INSERT INTO "memberships" ("organization_id", "user_id", "role")
+         VALUES ($1, $2, $3::"Role") RETURNING "id"`,
+        [orgId, userId, role],
+      )
+    ).rows[0]!.id;
+  }
+
+  type AgentColumns = {
+    id?: string;
+    organization_id: string;
+    workspace_id: string;
+    responsible_membership_id: string;
+    created_by_user_id: string;
+    key_issued_to_membership_id: string | null;
+    credential_hash: string;
+  };
+
+  function defaults(): AgentColumns {
+    return {
+      organization_id: organizationId,
+      workspace_id: workspaceId,
+      responsible_membership_id: personMembershipId,
+      created_by_user_id: ownerUserId,
+      key_issued_to_membership_id: ownerMembershipId,
+      credential_hash: nextHash(),
+    };
+  }
+
+  /** Insert one agent; the database mints its id unless one is given. */
+  async function insertAgent(overrides: Partial<AgentColumns> = {}): Promise<string> {
+    const row = { ...defaults(), ...overrides };
+    const columns = Object.keys(row);
+    const values = Object.values(row);
+    const { rows } = await db.query<{ id: string }>(
+      `INSERT INTO "agents" (${columns.map((c) => `"${c}"`).join(", ")}, "name", "credential_prefix", "updated_at")
+       VALUES (${columns.map((_, i) => `$${i + 1}`).join(", ")}, 'inbox helper', 'ailk_agt_abcdefgh', now())
+       RETURNING "id"`,
+      values,
+    );
+    return rows[0]!.id;
+  }
+
+  async function agentRow(id: string): Promise<{ key_issued_to_membership_id: string | null } | undefined> {
+    return (
+      await db.query<{ key_issued_to_membership_id: string | null }>(
+        `SELECT "key_issued_to_membership_id" FROM "agents" WHERE "id" = $1`,
+        [id],
+      )
+    ).rows[0];
+  }
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    organizationId = await insertOrganization("org");
+    workspaceId = await insertWorkspace(organizationId, "agents3591-ws");
+    ownerUserId = await insertUser("owner");
+    personUserId = await insertUser("person");
+    ownerMembershipId = await insertMembership(organizationId, ownerUserId, "owner");
+    personMembershipId = await insertMembership(organizationId, personUserId, "member");
+  });
+
+  afterAll(async () => {
+    await db.query(`DELETE FROM "organizations" WHERE "slug" LIKE 'agents3591-%'`);
+    await db.query(`DELETE FROM "users" WHERE "email" LIKE 'agents3591-%'`);
+    await db.end();
+  });
+
+  describe("format CHECKs (ADR-0031)", () => {
+    it("an agent takes a database-minted agent_ id, a member ceiling and is enabled", async () => {
+      const id = await insertAgent();
+      expect(id).toMatch(AGENT_ID);
+      const { rows } = await db.query<{ permission_level: string; enabled: boolean }>(
+        `SELECT "permission_level", "enabled" FROM "agents" WHERE "id" = $1`,
+        [id],
+      );
+      expect(rows[0]).toEqual({ permission_level: "member", enabled: true });
+    });
+
+    it.each([
+      ["id", "agents_id_format"],
+      ["organization_id", "agents_organization_id_format"],
+      ["workspace_id", "agents_workspace_id_format"],
+      ["responsible_membership_id", "agents_responsible_membership_id_format"],
+      ["key_issued_to_membership_id", "agents_key_issued_to_membership_id_format"],
+      ["created_by_user_id", "agents_created_by_user_id_format"],
+    ] as const)("REJECTS a malformed %s", async (column, constraint) => {
+      // The format CHECK fires before any foreign key.
+      await expect(insertAgent({ [column]: "bad" })).rejects.toThrow(new RegExp(constraint));
+    });
+
+    it("refuses a ceiling outside the enum", async () => {
+      const id = await insertAgent();
+      await expect(
+        db.query(`UPDATE "agents" SET "permission_level" = 'owner' WHERE "id" = $1`, [id]),
+      ).rejects.toThrow(/AgentPermissionLevel/);
+    });
+  });
+
+  it("a credential digest is unique", async () => {
+    const hash = nextHash();
+    await insertAgent({ credential_hash: hash });
+    await expect(insertAgent({ credential_hash: hash })).rejects.toThrow(
+      /agents_credential_hash_key/,
+    );
+  });
+
+  describe("cascades (D1 — leaving stops the agent)", () => {
+    it("deleting the person's membership deletes their agent, and a re-invite does not revive it", async () => {
+      const user = await insertUser("leaver");
+      const membership = await insertMembership(organizationId, user, "member");
+      const agent = await insertAgent({ responsible_membership_id: membership });
+
+      await db.query(`DELETE FROM "memberships" WHERE "id" = $1`, [membership]);
+      expect(await agentRow(agent)).toBeUndefined();
+
+      const reinvited = await insertMembership(organizationId, user, "member");
+      expect(reinvited).not.toBe(membership);
+      expect(await agentRow(agent)).toBeUndefined();
+    });
+
+    it("deleting the workspace deletes its agents", async () => {
+      const doomed = await insertWorkspace(organizationId, "agents3591-doomed");
+      const agent = await insertAgent({ workspace_id: doomed });
+      await db.query(`DELETE FROM "workspaces" WHERE "id" = $1`, [doomed]);
+      expect(await agentRow(agent)).toBeUndefined();
+    });
+
+    it("deleting the organization deletes its agents", async () => {
+      const org = await insertOrganization("doomed-org");
+      const ws = await insertWorkspace(org, "agents3591-doomed-org-ws");
+      const user = await insertUser("doomed-org-person");
+      const membership = await insertMembership(org, user, "owner");
+      const agent = await insertAgent({
+        organization_id: org,
+        workspace_id: ws,
+        responsible_membership_id: membership,
+        key_issued_to_membership_id: membership,
+      });
+      await db.query(`DELETE FROM "organizations" WHERE "id" = $1`, [org]);
+      expect(await agentRow(agent)).toBeUndefined();
+    });
+
+    it("deleting the key-holder's membership keeps the agent and clears key_issued_to_membership_id", async () => {
+      const admin = await insertUser("departing-admin");
+      const adminMembership = await insertMembership(organizationId, admin, "admin");
+      const agent = await insertAgent({ key_issued_to_membership_id: adminMembership });
+
+      await db.query(`DELETE FROM "memberships" WHERE "id" = $1`, [adminMembership]);
+      expect(await agentRow(agent)).toEqual({ key_issued_to_membership_id: null });
+    });
+
+    it("deleting the creator's user row leaves the agent (created_by_user_id has no relation)", async () => {
+      const creator = await insertUser("creator");
+      const agent = await insertAgent({ created_by_user_id: creator, key_issued_to_membership_id: null });
+      await db.query(`DELETE FROM "users" WHERE "id" = $1`, [creator]);
+      expect(await agentRow(agent)).toEqual({ key_issued_to_membership_id: null });
+    });
+  });
+});

package/templates/database/auth/schema.prisma

@@ -82,6 +82,8 @@ model Organization {
   memberships Membership[]
   invitations Invitation[]
   workspaces  Workspace[]
+  // #3591 — the agents (delegates) of this organization's members.
+  agents      Agent[]
 
   @@unique([billingProvider, billingCustomerId])
   @@map("organizations")
@@ -102,6 +104,8 @@ model Workspace {
   organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
   // #7532 — the hub's spoke registry rows bound to this workspace.
   spokes       Spoke[]
+  // #3591 — the agents bound to this workspace.
+  agents       Agent[]
 
   @@unique([organizationId, slug])
   @@index([organizationId])
@@ -137,6 +141,59 @@ model Spoke {
   @@map("spokes")
 }
 
+/// AgentPermissionLevel — an agent's ceiling (#3591, spec
+/// docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md D1, D5). The agent
+/// acts with the LOWER of its person's `Role` and this. One value in v1;
+/// raising the ceiling later is a new value here and in
+/// `@working-theory/validation`'s `AGENT_PERMISSION_LEVELS`.
+enum AgentPermissionLevel {
+  member
+}
+
+/// Agent — a stored delegate of ONE person, bound to ONE workspace (#3591,
+/// spec docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md D1, D2).
+///
+/// The agent signs in with a key (`ailk_agt_…`, shown once) and passes the
+/// same tenant guard a browser session does, through its person's live
+/// `Membership` (`responsibleMembershipId`). Removing that membership deletes
+/// the agent (the FK below), so a re-invite cannot revive it.
+///
+/// Only the key's SHA-256 digest is stored (`credentialHash`) plus a short
+/// recognisable `credentialPrefix`; the key itself never is.
+/// `keyIssuedToMembershipId` is the owner or admin who created or last
+/// re-keyed the agent — the only person who has seen its key. Removing that
+/// membership sets the column null and the guard refuses the agent until it
+/// is re-keyed. `createdByUserId` is a plain column with no relation, so
+/// deleting the creator does not delete the agents they made for others.
+/// `apps/api/src/lib/agent-store.ts` is the only file that names
+/// `prisma.agent`.
+model Agent {
+  id                      String               @id @default(dbgenerated("('agent_'::text || (uuidv7())::text)")) @db.Text
+  organizationId          String               @map("organization_id")
+  workspaceId             String               @map("workspace_id")
+  responsibleMembershipId String               @map("responsible_membership_id")
+  name                    String               @db.VarChar(80)
+  permissionLevel         AgentPermissionLevel @default(member) @map("permission_level")
+  enabled                 Boolean              @default(true)
+  credentialHash          String               @unique @map("credential_hash") @db.Char(64)
+  credentialPrefix        String               @map("credential_prefix") @db.VarChar(24)
+  lastActiveAt            DateTime?            @map("last_active_at")
+  createdByUserId         String               @map("created_by_user_id")
+  keyIssuedToMembershipId String?              @map("key_issued_to_membership_id")
+  createdAt               DateTime             @default(now()) @map("created_at")
+  updatedAt               DateTime             @updatedAt @map("updated_at")
+
+  organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  workspace    Workspace    @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+  responsible  Membership   @relation("AgentResponsible", fields: [responsibleMembershipId], references: [id], onDelete: Cascade)
+  keyIssuedTo  Membership?  @relation("AgentKeyIssuedTo", fields: [keyIssuedToMembershipId], references: [id], onDelete: SetNull)
+
+  @@index([organizationId])
+  @@index([workspaceId])
+  @@index([responsibleMembershipId])
+  @@map("agents")
+}
+
 /// Membership — User ↔ Organization with a Role. Managed by the Better Auth
 /// organization plugin (modelName "membership"). Org-level: grants visibility
 /// into every workspace of the organization.
@@ -149,6 +206,10 @@ model Membership {
 
   organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
   user         User         @relation(fields: [userId], references: [id], onDelete: Cascade)
+  // #3591 — the agents this person is responsible for, and the agents whose
+  // current key this person was the one shown.
+  agents          Agent[] @relation("AgentResponsible")
+  agentKeysIssued Agent[] @relation("AgentKeyIssuedTo")
 
   @@unique([organizationId, userId])
   @@index([userId])