create-ailk 0.24.0 → 0.26.0

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

@@ -1,613 +0,0 @@
-/**
- * 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.
- *
- * GRANTS (#7864, spec docs/specs/7864-agent-key-grants-spec.md D2–D4). An
- * agent's row carries the permissions an owner or admin granted it one by one
- * — only the five `AGENT_GRANTABLE_PERMISSIONS`. `setServedAgentGrants` is
- * the column's only writer, and refuses a grant its person's own role does
- * not hold; the tenant guards apply the same rule on every request, so a
- * grant stored before a demotion is held to the person's current role.
- *
- * Nothing caches a row: a switch-off, a re-key, a grant change or a removed
- * membership takes effect on the next request.
- */
-import { createHash, randomBytes } from "node:crypto";
-
-import type { Id } from "@working-theory/ids";
-import {
-  AGENT_GRANTABLE_PERMISSIONS,
-  can,
-  type AgentGrantablePermission,
-  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 grants stored on the row (#7864 D3). The tenant guards keep only
-   * those its person's role also holds (`agentTenant`).
-   */
-  grants: readonly string[];
-}
-
-/**
- * A stored grant set in `AGENT_GRANTABLE_PERMISSIONS` order, without
- * duplicates and without anything outside the five.
- */
-function orderedGrants(
-  grants: readonly string[],
-): AgentGrantablePermission[] {
-  return AGENT_GRANTABLE_PERMISSIONS.filter((p) => grants.includes(p));
-}
-
-// ── The auth preHandler's three functions ────────────────────────────────────
-
-export interface AgentKeyRow {
-  id: string;
-  workspaceId: string;
-  organizationId: string;
-  permissionLevel: AgentPermissionLevel;
-  /** `undefined` only from a test double; the auth preHandler reads it as none. */
-  grants: string[] | undefined;
-  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,
-      grants: 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;
-}
-
-interface SetAgentGrantsParams {
-  organizationId: string;
-  agentId: string;
-  grants: readonly AgentGrantablePermission[];
-}
-
-/**
- * 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);
-  });
-}
-
-/** A grant set the agent's person's own role does not wholly hold. */
-export type AgentGrantExceedsPerson = { ok: false; reason: "exceeds-person" };
-export type ServedAgentGrants = ServedAgent & {
-  /** The grants stored before this write, in D1 order — for the audit row. */
-  previous: AgentGrantablePermission[];
-};
-
-/**
- * Replace an agent's grants with `grants` (#7864 D4) and answer with its list
- * row. One transaction: the agent is read by id inside the caller's
- * organization, with its responsible person's role; any requested grant that
- * role does not hold refuses the whole set (`exceeds-person`) and writes
- * nothing. An agent of another organization, or none, is `not-found`.
- */
-export async function setServedAgentGrants(
-  params: SetAgentGrantsParams,
-): Promise<ServedAgentGrants | AgentNotFound | AgentGrantExceedsPerson> {
-  return prisma.$transaction(async (tx) => {
-    const current = await tx.agent.findUnique({
-      where: agentScope(params),
-      select: {
-        organizationId: true,
-        grants: true,
-        responsible: { select: { role: true } },
-      },
-    });
-    if (!current || current.organizationId !== params.organizationId) {
-      return { ok: false, reason: "not-found" } as const;
-    }
-    const grants = orderedGrants(params.grants);
-    if (!grants.every((grant) => can(current.responsible.role, grant))) {
-      return { ok: false, reason: "exceeds-person" } as const;
-    }
-    const { count } = await tx.agent.updateMany({
-      where: agentScope(params),
-      data: { grants },
-    });
-    if (count !== 1) return { ok: false, reason: "not-found" } as const;
-    const [agent] = await readAgentListRows(
-      { id: params.agentId, organizationId: params.organizationId },
-      tx,
-    );
-    return agent
-      ? ({
-          ok: true,
-          agent,
-          previous: orderedGrants(current.grants),
-        } 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;
-  /** The stored grants (#7864 D4), in `AGENT_GRANTABLE_PERMISSIONS` order. */
-  grants: AgentGrantablePermission[];
-  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,
-      grants: 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,
-    grants: orderedGrants(r.grants),
-    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,
-    },
-  };
-}