create-ailk 0.12.1 → 0.14.0

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

@@ -0,0 +1,521 @@
+/**
+ * The agents table — its ONE data-access boundary (#3591, spec
+ * docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md D1, D2, D12).
+ *
+ * An agent is a stored delegate of ONE person (its responsible `Membership`),
+ * bound to ONE workspace. It authenticates with a key sent as
+ * `Authorization: Bearer ailk_agt_…` and passes the same tenant guard a
+ * browser session does, through its person's live membership. This file is
+ * the only one that names `prisma.agent`.
+ *
+ * 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_agt_` plus 8 random ones) so an owner 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 —
+ * the spoke-key shape (`./spoke-store.ts`).
+ *
+ * NO READ TAKES A SCOPE OF ITS OWN. Every read is keyed by a key's digest, an
+ * agent id, or an organization id the CALLER passes from a granted
+ * `TenantContext`. `createAgent` derives the organization from the target
+ * workspace's own row and the membership from the organization's compound
+ * key, in one transaction, so a row's three references always agree
+ * (SEC-3591-15).
+ *
+ * Two kinds of caller, kept apart:
+ *   - the auth preHandler (`middleware/auth.ts`) calls `hashAgentKey`,
+ *     `findAgentByKeyHash` and `touchAgentLastActive` only;
+ *   - the management routes (`routes/workspaces/agents.ts`) call the rest.
+ *
+ * Nothing caches a row: a switch-off, a re-key or a removed membership takes
+ * effect on the next request.
+ */
+import { createHash, randomBytes } from "node:crypto";
+
+import type { Id } from "@working-theory/ids";
+import type { AgentPermissionLevel } from "@working-theory/validation";
+
+import { prisma } from "./prisma.js";
+
+/** Every agent key starts with this, so a leaked one is recognisable. */
+export const AGENT_KEY_PREFIX = "ailk_agt_";
+
+/** How much of the key the row keeps for recognition: the prefix + 8 characters. */
+const CREDENTIAL_PREFIX_LENGTH = AGENT_KEY_PREFIX.length + 8;
+
+/** A new key: `ailk_agt_` + 32 random bytes in base64url (52 characters). */
+export function mintAgentKey(): string {
+  return `${AGENT_KEY_PREFIX}${randomBytes(32).toString("base64url")}`;
+}
+
+/** The stored digest of a key: lowercase hex SHA-256 of the TRIMMED value. */
+export function hashAgentKey(key: string): string {
+  return createHash("sha256").update(key.trim()).digest("hex");
+}
+
+/** The digest and recognisable prefix a fresh key is stored as. */
+function credentialFor(key: string) {
+  return {
+    credentialHash: hashAgentKey(key),
+    credentialPrefix: key.slice(0, CREDENTIAL_PREFIX_LENGTH),
+  };
+}
+
+/**
+ * What the tenant guards need to know about an authenticated agent — set by
+ * the auth preHandler as `request.agent`. Never carries the key.
+ */
+export interface AgentGrant {
+  agentId: Id<"agent">;
+  workspaceId: Id<"workspace">;
+  organizationId: Id<"organization">;
+  responsibleMembershipId: Id<"membership">;
+  permissionLevel: AgentPermissionLevel;
+}
+
+// ── The auth preHandler's three functions ────────────────────────────────────
+
+export interface AgentKeyRow {
+  id: string;
+  workspaceId: string;
+  organizationId: string;
+  permissionLevel: AgentPermissionLevel;
+  enabled: boolean;
+  keyIssuedToMembershipId: string | null;
+  lastActiveAt: Date | null;
+  responsible: { id: string; userId: string };
+}
+
+/** The one read the auth preHandler makes: a `findUnique` by digest. */
+export async function findAgentByKeyHash(
+  credentialHash: string,
+): Promise<AgentKeyRow | null> {
+  return prisma.agent.findUnique({
+    where: { credentialHash },
+    select: {
+      id: true,
+      workspaceId: true,
+      organizationId: true,
+      permissionLevel: true,
+      enabled: true,
+      keyIssuedToMembershipId: true,
+      lastActiveAt: true,
+      responsible: { select: { id: true, userId: true } },
+    },
+  });
+}
+
+/** Stamp the agent's `lastActiveAt` — best effort; the caller swallows a failure. */
+export async function touchAgentLastActive(
+  agentId: string,
+  at: Date,
+): Promise<void> {
+  await prisma.agent.update({
+    where: { id: agentId },
+    data: { lastActiveAt: at },
+    select: { id: true },
+  });
+}
+
+// ── The management functions — scoped by the caller's organization ───────────
+
+/** An agent as the management functions hand it back. Never the digest. */
+export interface AgentRow {
+  id: string;
+  name: string;
+  organizationId: string;
+  workspaceId: string;
+  responsibleMembershipId: string;
+  permissionLevel: AgentPermissionLevel;
+  enabled: boolean;
+  lastActiveAt: Date | null;
+  createdAt: Date;
+  credentialPrefix: string;
+  createdByUserId: string;
+  keyIssuedToMembershipId: string | null;
+}
+
+const AGENT_ROW_SELECT = {
+  id: true,
+  name: true,
+  organizationId: true,
+  workspaceId: true,
+  responsibleMembershipId: true,
+  permissionLevel: true,
+  enabled: true,
+  lastActiveAt: true,
+  createdAt: true,
+  credentialPrefix: true,
+  createdByUserId: true,
+  keyIssuedToMembershipId: true,
+} as const;
+
+/** One body for every miss, so no caller can tell "absent" from "not yours". */
+export type AgentNotFound = { ok: false; reason: "not-found" };
+export type AgentWithKey = { ok: true; agent: AgentRow; key: string };
+
+/** The client a management write runs on: the singleton, or a transaction's. */
+type AgentDb = Pick<
+  typeof prisma,
+  "agent" | "membership" | "workspace" | "user"
+>;
+
+interface CreateAgentParams {
+  organizationId: string;
+  workspaceId: string;
+  responsibleUserId: string;
+  createdByUserId: string;
+  name: string;
+}
+
+interface ReplaceAgentKeyParams {
+  organizationId: string;
+  agentId: string;
+  issuedByUserId: string;
+}
+
+interface SetAgentEnabledParams {
+  organizationId: string;
+  agentId: string;
+  enabled: boolean;
+}
+
+/**
+ * Add an agent for `responsibleUserId`, bound to `workspaceId`. The returned
+ * `key` is the only copy that will ever exist: the caller shows it once.
+ *
+ * `organizationId` is the caller's granted `tenant.organizationId`. The
+ * workspace row must belong to it, and the responsible person and the
+ * creator must each hold a `Membership` in it — every miss is the same
+ * `not-found`. The creator's membership becomes `keyIssuedToMembershipId`:
+ * they are the one person who has seen the key.
+ */
+export async function createAgent(
+  params: CreateAgentParams,
+): Promise<AgentWithKey | AgentNotFound> {
+  return prisma.$transaction((tx) => createAgentIn(tx, params));
+}
+
+/**
+ * Replace an agent's key. The old key is refused on its next request; the
+ * agent's id, name, person and history are kept. `issuedByUserId` — the
+ * owner or admin re-keying it — becomes the one person who has seen the key.
+ */
+export async function replaceAgentKey(
+  params: ReplaceAgentKeyParams,
+): Promise<AgentWithKey | AgentNotFound> {
+  return prisma.$transaction(async (tx) => {
+    const key = await replaceAgentKeyIn(tx, params);
+    if (key === null) return { ok: false, reason: "not-found" } as const;
+    const agent = await tx.agent.findUnique({
+      where: { id: params.agentId },
+      select: AGENT_ROW_SELECT,
+    });
+    return agent
+      ? ({ ok: true, agent, key } as const)
+      : ({ ok: false, reason: "not-found" } as const);
+  });
+}
+
+/** Switch an agent off or back on. `null` when the organization has no such agent. */
+export async function setAgentEnabled(
+  params: SetAgentEnabledParams,
+): Promise<AgentRow | null> {
+  if (!(await setAgentEnabledIn(prisma, params))) return null;
+  return prisma.agent.findUnique({
+    where: { id: params.agentId },
+    select: AGENT_ROW_SELECT,
+  });
+}
+
+// ── The management routes' writes — each returns the row it serves ──────────
+//
+// The route builds its response, and its audit row, from what these return.
+// Each runs the write and the list-row read in ONE transaction, so a write
+// that committed always comes back with its row: a re-key can never answer
+// an error after the old key is already dead, nor leave a change the route
+// could not record.
+
+/** A management write's result in the list-row shape spec D11 serves. */
+export type ServedAgent = { ok: true; agent: AgentListRow };
+export type ServedAgentWithKey = { ok: true; agent: AgentListRow; key: string };
+
+/** `createAgent`, answering with the list row. */
+export async function createServedAgent(
+  params: CreateAgentParams,
+): Promise<ServedAgentWithKey | AgentNotFound> {
+  return prisma.$transaction(async (tx) => {
+    const created = await createAgentIn(tx, params);
+    if (!created.ok) return created;
+    return servedWith(tx, params.organizationId, created.agent.id, created.key);
+  });
+}
+
+/** `replaceAgentKey`, answering with the list row. */
+export async function replaceServedAgentKey(
+  params: ReplaceAgentKeyParams,
+): Promise<ServedAgentWithKey | AgentNotFound> {
+  return prisma.$transaction(async (tx) => {
+    const key = await replaceAgentKeyIn(tx, params);
+    if (key === null) return { ok: false, reason: "not-found" } as const;
+    return servedWith(tx, params.organizationId, params.agentId, key);
+  });
+}
+
+/** `setAgentEnabled`, answering with the list row. */
+export async function setServedAgentEnabled(
+  params: SetAgentEnabledParams,
+): Promise<ServedAgent | AgentNotFound> {
+  return prisma.$transaction(async (tx) => {
+    if (!(await setAgentEnabledIn(tx, params))) {
+      return { ok: false, reason: "not-found" } as const;
+    }
+    const [agent] = await readAgentListRows(
+      { id: params.agentId, organizationId: params.organizationId },
+      tx,
+    );
+    return agent
+      ? ({ ok: true, agent } as const)
+      : ({ ok: false, reason: "not-found" } as const);
+  });
+}
+
+/** The list row of a just-written agent, read on the write's own client. */
+async function servedWith(
+  db: AgentDb,
+  organizationId: string,
+  agentId: string,
+  key: string,
+): Promise<ServedAgentWithKey | AgentNotFound> {
+  const [agent] = await readAgentListRows({ id: agentId, organizationId }, db);
+  return agent
+    ? ({ ok: true, agent, key } as const)
+    : ({ ok: false, reason: "not-found" } as const);
+}
+
+// ── The writes themselves, on a caller's client ──────────────────────────────
+
+async function createAgentIn(
+  db: AgentDb,
+  params: CreateAgentParams,
+): Promise<AgentWithKey | AgentNotFound> {
+  const workspace = await db.workspace.findUnique({
+    where: { id: params.workspaceId },
+    select: { id: true, organizationId: true },
+  });
+  if (!workspace || workspace.organizationId !== params.organizationId) {
+    return { ok: false, reason: "not-found" } as const;
+  }
+
+  const responsible = await db.membership.findUnique({
+    where: {
+      organizationId_userId: {
+        organizationId: workspace.organizationId,
+        userId: params.responsibleUserId,
+      },
+    },
+    select: { id: true },
+  });
+  const issuer = await db.membership.findUnique({
+    where: {
+      organizationId_userId: {
+        organizationId: workspace.organizationId,
+        userId: params.createdByUserId,
+      },
+    },
+    select: { id: true },
+  });
+  if (!responsible || !issuer) {
+    return { ok: false, reason: "not-found" } as const;
+  }
+
+  const key = mintAgentKey();
+  const agent = await db.agent.create({
+    data: {
+      organizationId: workspace.organizationId,
+      workspaceId: workspace.id,
+      responsibleMembershipId: responsible.id,
+      keyIssuedToMembershipId: issuer.id,
+      createdByUserId: params.createdByUserId,
+      name: params.name,
+      ...credentialFor(key),
+    },
+    select: AGENT_ROW_SELECT,
+  });
+  return { ok: true, agent, key } as const;
+}
+
+/** The new key, or `null` when the scope has no such agent or no such issuer. */
+async function replaceAgentKeyIn(
+  db: AgentDb,
+  params: ReplaceAgentKeyParams,
+): Promise<string | null> {
+  const issuer = await db.membership.findUnique({
+    where: {
+      organizationId_userId: {
+        organizationId: params.organizationId,
+        userId: params.issuedByUserId,
+      },
+    },
+    select: { id: true },
+  });
+  if (!issuer) return null;
+
+  const key = mintAgentKey();
+  const { count } = await db.agent.updateMany({
+    where: agentScope(params),
+    data: { ...credentialFor(key), keyIssuedToMembershipId: issuer.id },
+  });
+  return count === 1 ? key : null;
+}
+
+async function setAgentEnabledIn(
+  db: AgentDb,
+  params: SetAgentEnabledParams,
+): Promise<boolean> {
+  const { count } = await db.agent.updateMany({
+    where: agentScope(params),
+    data: { enabled: params.enabled },
+  });
+  return count === 1;
+}
+
+/** One agent, by id, inside the caller's organization — whichever workspace it is bound to. */
+function agentScope(params: { organizationId: string; agentId: string }) {
+  return { id: params.agentId, organizationId: params.organizationId };
+}
+
+/** One row of the organization's agent list (the shape spec D11 serves). */
+export interface AgentListRow {
+  id: string;
+  name: string;
+  workspaceId: string;
+  responsible: { userId: string; name: string | null; email: string };
+  permissionLevel: AgentPermissionLevel;
+  enabled: boolean;
+  lastActiveAt: Date | null;
+  createdAt: Date;
+  keyPrefix: string;
+  createdBy: { userId: string; name: string | null };
+  keyIssuedTo: { userId: string; name: string | null } | null;
+}
+
+/**
+ * Every agent of the organization, newest first — or, with `userId`, only
+ * that person's. Never selects the digest.
+ */
+export async function listAgentsForOrganization(
+  organizationId: string,
+  userId?: string,
+): Promise<AgentListRow[]> {
+  return readAgentListRows(
+    userId ? { organizationId, responsible: { userId } } : { organizationId },
+  );
+}
+
+/**
+ * The list read. Every `where` carries the caller's `organizationId`.
+ * `createdBy` is named by a second read because `createdByUserId` carries no
+ * relation (D1).
+ */
+async function readAgentListRows(
+  where:
+    | { organizationId: string; responsible?: { userId: string } }
+    | { id: string; organizationId: string },
+  db: AgentDb = prisma,
+): Promise<AgentListRow[]> {
+  const rows = await db.agent.findMany({
+    where,
+    select: {
+      id: true,
+      name: true,
+      workspaceId: true,
+      permissionLevel: true,
+      enabled: true,
+      lastActiveAt: true,
+      createdAt: true,
+      credentialPrefix: true,
+      createdByUserId: true,
+      responsible: {
+        select: { userId: true, user: { select: { name: true, email: true } } },
+      },
+      keyIssuedTo: {
+        select: { userId: true, user: { select: { name: true } } },
+      },
+    },
+    orderBy: { createdAt: "desc" },
+  });
+
+  const creatorIds = [...new Set(rows.map((r) => r.createdByUserId))];
+  const creators =
+    creatorIds.length === 0
+      ? []
+      : await db.user.findMany({
+          where: { id: { in: creatorIds } },
+          select: { id: true, name: true },
+        });
+  const creatorName = new Map(creators.map((u) => [u.id, u.name]));
+
+  return rows.map((r) => ({
+    id: r.id,
+    name: r.name,
+    workspaceId: r.workspaceId,
+    responsible: {
+      userId: r.responsible.userId,
+      name: r.responsible.user.name,
+      email: r.responsible.user.email,
+    },
+    permissionLevel: r.permissionLevel,
+    enabled: r.enabled,
+    lastActiveAt: r.lastActiveAt,
+    createdAt: r.createdAt,
+    keyPrefix: r.credentialPrefix,
+    createdBy: {
+      userId: r.createdByUserId,
+      name: creatorName.get(r.createdByUserId) ?? null,
+    },
+    keyIssuedTo: r.keyIssuedTo
+      ? { userId: r.keyIssuedTo.userId, name: r.keyIssuedTo.user.name }
+      : null,
+  }));
+}
+
+/** What an agent needs to scope its calls and copy its person on a reply. */
+export interface AgentContext {
+  agent: {
+    id: string;
+    name: string;
+    workspaceId: string;
+    permissionLevel: AgentPermissionLevel;
+  };
+  responsible: { name: string | null; email: string };
+}
+
+/** The agent's own context, by its id (taken from `request.agent`, never the wire). */
+export async function findAgentContext(
+  agentId: string,
+): Promise<AgentContext | null> {
+  const row = await prisma.agent.findUnique({
+    where: { id: agentId },
+    select: {
+      id: true,
+      name: true,
+      workspaceId: true,
+      permissionLevel: true,
+      responsible: { select: { user: { select: { name: true, email: true } } } },
+    },
+  });
+  if (!row) return null;
+  return {
+    agent: {
+      id: row.id,
+      name: row.name,
+      workspaceId: row.workspaceId,
+      permissionLevel: row.permissionLevel,
+    },
+    responsible: {
+      name: row.responsible.user.name,
+      email: row.responsible.user.email,
+    },
+  };
+}

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

@@ -20,11 +20,12 @@
  *
  * Two kinds of caller, kept apart:
  *   - the public resolver (`services/public-site-resolver.ts`) calls
- *     `hashSpokeKey` and `findSpokeByKeyHash` only;
+ *     `hashSpokeKey`, `findSpokeByKeyHash` and `hasRegisteredSpoke` 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).
+ * Nothing here caches a row: a revocation takes effect on the next request
+ * (NFR4). The resolver holds `hasRegisteredSpoke`'s answer itself (#7633 D3).
  */
 import { createHash, randomBytes } from "node:crypto";
 
@@ -62,6 +63,16 @@ export async function findSpokeByKeyHash(
   });
 }
 
+/**
+ * Whether this deployment is a hub: its registry holds at least one spoke,
+ * revoked or not (#7633 D1). Reads every time; the resolver holds the
+ * answer (D3).
+ */
+export async function hasRegisteredSpoke(): Promise<boolean> {
+  const row = await prisma.spoke.findFirst({ select: { id: true } });
+  return Boolean(row);
+}
+
 // ── Operator functions — `bin/spokes.ts` only ────────────────────────────────
 
 export interface SpokeListRow {