@checkstack/ai-backend 0.1.0

package/src/projection.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type {
+  AccessRule,
+  PluginMetadata,
+  ProcedureMetadata,
+} from "@checkstack/common";
+import { isContractProcedure } from "@orpc/contract";
+import type { AnyContractProcedure } from "@orpc/contract";
+import type { AuthUser } from "@checkstack/backend-api";
+import type { AiToolEffect } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "./tool-registry";
+
+/**
+ * Subset of a contract procedure's `~orpc` def that the projection reads. The
+ * full def is typed by oRPC; we only narrow what we touch so the projection
+ * never depends on undocumented internals.
+ */
+interface ProjectableProcedureDef {
+  meta?: Partial<ProcedureMetadata>;
+  inputSchema?: z.ZodType<unknown>;
+}
+
+/**
+ * Input to {@link buildProjectedTool}. The `procedure` is an existing oRPC
+ * contract procedure whose access rules and input schema are read verbatim —
+ * nothing is duplicated (decision 2a).
+ */
+export interface ProjectToolInput<TInput = unknown, TOutput = unknown> {
+  /** The contract procedure to project. */
+  procedure: AnyContractProcedure;
+  /**
+   * Plugin metadata that OWNS `procedure`. Used to qualify the procedure's
+   * (unqualified) access rules into the same `<plugin>.<resource>.<level>` IDs
+   * `autoAuthMiddleware` enforces. For a plugin projecting another plugin's
+   * procedure this MUST be the source plugin's metadata, otherwise the gate
+   * would check a wrong rule id.
+   */
+  sourcePluginMetadata: PluginMetadata;
+  /** Model-facing description (procedures often lack good model prose). */
+  description: string;
+  /** Effect classification — REQUIRED, never inferred from operationType. */
+  effect: AiToolEffect;
+  /** Optional override of the derived tool name (else `<sourcePlugin>.<key>`). */
+  name?: string;
+  /**
+   * Procedure key (e.g. "listIncidents"); used to derive the tool name when
+   * `name` is not given.
+   */
+  procedureKey: string;
+  /** The executor — invokes the underlying procedure for the principal. */
+  execute(args: { input: TInput; principal: AuthUser }): Promise<TOutput>;
+  /** Optional dry-run for mutate / destructive projections (Phase 3). */
+  dryRun?: RegisteredAiTool<TInput, TOutput>["dryRun"];
+}
+
+/**
+ * The `execute` a plugin supplies when EXPOSING a read-only projection. A
+ * projected read tool is never run via its own `execute`: the MCP transport and
+ * the chat read-loop re-enter the live router AS the principal using the tool's
+ * `{ pluginId, procedureKey }` routing (so handler-side authz holds). This is a
+ * fail-closed safety net if a transport ever forgot to route - it rejects rather
+ * than silently running as a trusted service principal.
+ */
+export function deferredProjectionExecute(): Promise<never> {
+  return Promise.reject(
+    new Error(
+      "Projected read tool execution is routed by the transport (MCP / chat), " +
+        "not run via its own execute.",
+    ),
+  );
+}
+
+/**
+ * Build a {@link RegisteredAiTool} from an existing oRPC contract procedure.
+ *
+ * - `requiredAccessRules` is the procedure's `~orpc.meta.access` rules,
+ *   qualified against the source plugin id — exactly the IDs the resolver and
+ *   `autoAuthMiddleware` compare against `principal.accessRules`.
+ * - `input` is the procedure's `~orpc.inputSchema`; a procedure with no input
+ *   projects to an empty-object schema.
+ * - `effect` is mandatory: this throws if it is omitted (a `mutation`
+ *   operationType is NOT the same as a destructive effect).
+ */
+export function buildProjectedTool<TInput = unknown, TOutput = unknown>(
+  input: ProjectToolInput<TInput, TOutput>,
+): RegisteredAiTool<TInput, TOutput> {
+  const {
+    procedure,
+    sourcePluginMetadata,
+    description,
+    effect,
+    name,
+    procedureKey,
+    execute,
+    dryRun,
+  } = input;
+
+  if (!isContractProcedure(procedure)) {
+    throw new Error(
+      `Cannot project ${procedureKey}: value is not an oRPC contract procedure.`,
+    );
+  }
+  // `effect` is required by the type, but guard the runtime path for JS callers.
+  if (effect === undefined) {
+    throw new Error(
+      `Cannot project ${procedureKey}: 'effect' is required and is never inferred from the operation type.`,
+    );
+  }
+
+  const def = (procedure as { "~orpc": ProjectableProcedureDef })["~orpc"];
+  const accessRules: AccessRule[] = def.meta?.access ?? [];
+  const requiredAccessRules = accessRules.map((rule) =>
+    qualifyAccessRuleId(sourcePluginMetadata, rule),
+  );
+
+  const inputSchema: z.ZodType<TInput> =
+    (def.inputSchema as z.ZodType<TInput> | undefined) ??
+    (z.object({}) as unknown as z.ZodType<TInput>);
+
+  const toolName = name ?? `${sourcePluginMetadata.pluginId}.${procedureKey}`;
+
+  return {
+    name: toolName,
+    description,
+    effect,
+    input: inputSchema,
+    requiredAccessRules,
+    dryRun,
+    execute,
+  };
+}

package/src/propose-apply/args-hash.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { hashToolArgs } from "./args-hash";
+
+describe("hashToolArgs", () => {
+  test("is stable across key order (canonical JSON)", () => {
+    const a = hashToolArgs({ b: 2, a: 1, nested: { y: 1, x: 2 } });
+    const b = hashToolArgs({ a: 1, nested: { x: 2, y: 1 }, b: 2 });
+    expect(a).toBe(b);
+  });
+
+  test("preserves array order significance", () => {
+    expect(hashToolArgs([1, 2, 3])).not.toBe(hashToolArgs([3, 2, 1]));
+  });
+
+  test("produces a 64-char hex SHA-256 digest", () => {
+    expect(hashToolArgs({ x: 1 })).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("different content hashes differently", () => {
+    expect(hashToolArgs({ x: 1 })).not.toBe(hashToolArgs({ x: 2 }));
+  });
+
+  test("ignores undefined properties (treated as absent)", () => {
+    expect(hashToolArgs({ x: 1, y: undefined })).toBe(hashToolArgs({ x: 1 }));
+  });
+});

package/src/propose-apply/args-hash.ts

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Deterministically serialize a value to canonical JSON: object keys are sorted
+ * recursively so two semantically-equal argument objects hash identically
+ * regardless of key order. Arrays preserve order (order is significant).
+ */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+  return `{${entries.join(",")}}`;
+}
+
+/**
+ * SHA-256 of the canonical-JSON form of the tool arguments. The audit row
+ * stores ONLY this hash, never the raw args, because args may carry PII or
+ * secrets (§10). Identical args always hash identically; key order is
+ * irrelevant.
+ */
+export function hashToolArgs(args: unknown): string {
+  return createHash("sha256").update(canonicalJson(args)).digest("hex");
+}

package/src/propose-apply/service.test.ts

@@ -0,0 +1,423 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createAiToolRegistry } from "../tool-registry";
+import type { RegisteredAiTool } from "../tool-registry";
+import { createAiToolResolver } from "../resolver";
+import {
+  createProposeApplyService,
+  ProposeApplyError,
+} from "./service";
+import { generateProposalNonce } from "./token";
+import type { AiToolCallStore } from "./store";
+import type { AiToolCallRow } from "../schema";
+
+/**
+ * In-memory `AiToolCallStore` that faithfully mimics the atomic single-use
+ * consume: only one caller can flip a row from `proposed` to `applied`. This
+ * lets the lifecycle / single-use / expiry / authz logic be tested without a
+ * real Postgres connection (the SQL atomicity itself is expressed by the
+ * `WHERE status='proposed'` clause in the real store).
+ */
+function createFakeStore(now: () => Date): AiToolCallStore & {
+  rows: Map<string, AiToolCallRow>;
+} {
+  const rows = new Map<string, AiToolCallRow>();
+  let counter = 0;
+
+  const baseRow = (over: Partial<AiToolCallRow>): AiToolCallRow => ({
+    id: `row-${++counter}`,
+    principalKind: "user",
+    principalId: "u1",
+    transport: "chat",
+    conversationId: null,
+    toolName: "x",
+    effect: "mutate",
+    argsHash: "h",
+    status: "proposed",
+    proposalNonce: null,
+    proposalExpiresAt: null,
+    resultSnapshot: null,
+    proposedPayload: null,
+    error: null,
+    proposedAt: null,
+    appliedAt: null,
+    appliedByKind: null,
+    appliedById: null,
+    createdAt: now(),
+    ...over,
+  });
+
+  return {
+    rows,
+    async recordExecuted(args) {
+      const row = baseRow({
+        ...args,
+        conversationId: args.conversationId ?? null,
+        effect: "read",
+        status: "executed",
+        resultSnapshot: args.resultSnapshot ?? null,
+      });
+      rows.set(row.id, row);
+      return row;
+    },
+    async recordFailed(args) {
+      const row = baseRow({
+        ...args,
+        conversationId: args.conversationId ?? null,
+        status: "failed",
+      });
+      rows.set(row.id, row);
+      return row;
+    },
+    async createProposal(args) {
+      const nonce = generateProposalNonce();
+      const row = baseRow({
+        principalKind: args.principal.kind,
+        principalId: args.principal.id,
+        transport: args.transport,
+        conversationId: args.conversationId ?? null,
+        toolName: args.toolName,
+        effect: args.effect,
+        argsHash: args.argsHash,
+        status: "proposed",
+        proposalNonce: nonce,
+        proposalExpiresAt: new Date((args.now ?? now()).getTime() + 600_000),
+        proposedPayload: args.proposedPayload,
+        resultSnapshot: args.resultSnapshot ?? null,
+        proposedAt: args.now ?? now(),
+      });
+      rows.set(row.id, row);
+      return { row, nonce };
+    },
+    async consumeProposal({ rowId, applier, now: at = now() }) {
+      const row = rows.get(rowId);
+      if (!row) return undefined;
+      // Atomic single-use: only a still-`proposed`, non-expired row wins.
+      if (row.status !== "proposed") return undefined;
+      if (row.proposalExpiresAt && row.proposalExpiresAt.getTime() <= at.getTime()) {
+        return undefined;
+      }
+      const updated: AiToolCallRow = {
+        ...row,
+        status: "applied",
+        appliedAt: at,
+        appliedByKind: applier.kind,
+        appliedById: applier.id,
+      };
+      rows.set(rowId, updated);
+      return updated;
+    },
+    async getProposal(rowId) {
+      return rows.get(rowId);
+    },
+    async expireStaleProposals(at = now()) {
+      let n = 0;
+      for (const [id, row] of rows) {
+        if (
+          row.status === "proposed" &&
+          row.proposalExpiresAt &&
+          row.proposalExpiresAt.getTime() < at.getTime()
+        ) {
+          rows.set(id, { ...row, status: "expired" });
+          n += 1;
+        }
+      }
+      return n;
+    },
+  };
+}
+
+const ManageInput = z.object({ value: z.string() });
+
+function mutatingTool(
+  over?: Partial<RegisteredAiTool>,
+): RegisteredAiTool<{ value: string }, { created: string }> {
+  let executed = 0;
+  const tool: RegisteredAiTool<{ value: string }, { created: string }> = {
+    name: "demo.mutate",
+    description: "demo mutating tool",
+    effect: "mutate",
+    input: ManageInput,
+    requiredAccessRules: ["demo.demo.manage"],
+    dryRun: async ({ input }) => ({
+      summary: `Would create ${input.value}`,
+      payload: { value: input.value },
+    }),
+    execute: async ({ input }) => {
+      executed += 1;
+      return { created: input.value };
+    },
+    ...(over as Partial<RegisteredAiTool<{ value: string }, { created: string }>>),
+  };
+  Object.defineProperty(tool, "_executed", { get: () => executed });
+  return tool;
+}
+
+const allowed: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["demo.demo.manage"],
+};
+const notAllowed: AuthUser = {
+  type: "user",
+  id: "u2",
+  accessRules: ["other.read"],
+};
+
+// The demo tool's dryRun/execute ignore the RPC client, so a never-called stub
+// satisfies the user-scoped `rpcClient` arg threaded through propose/apply.
+const rpcClient = {
+  forPlugin: () => {
+    throw new Error("demo tool must not call the RPC client");
+  },
+} as unknown as RpcClient;
+
+function setup(tool: RegisteredAiTool, clock = () => new Date()) {
+  const registry = createAiToolRegistry();
+  registry.register(tool);
+  const resolver = createAiToolResolver({ registry });
+  const store = createFakeStore(clock);
+  const real = createProposeApplyService({ registry, resolver, store });
+  // Auto-inject the user-scoped `rpcClient` stub on every propose/apply so the
+  // individual tests below stay focused on lifecycle/authz (the demo tool
+  // ignores the client). This mirrors how the transports build the per-turn,
+  // user-scoped client and hand it to the service.
+  const service = {
+    ...real,
+    propose: (args: Omit<Parameters<typeof real.propose>[0], "rpcClient">) =>
+      real.propose({ ...args, rpcClient }),
+    apply: (args: Omit<Parameters<typeof real.apply>[0], "rpcClient">) =>
+      real.apply({ ...args, rpcClient }),
+  };
+  return { registry, resolver, store, service };
+}
+
+describe("propose/apply lifecycle (matrix #11)", () => {
+  test("a valid token applies exactly once; a second apply is rejected", async () => {
+    const tool = mutatingTool();
+    const { service } = setup(tool);
+
+    const proposal = await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "alpha" },
+      transport: "chat",
+    });
+    expect(proposal.token.startsWith("propose:")).toBe(true);
+
+    const first = await service.apply({ principal: allowed, token: proposal.token });
+    expect(first.result).toEqual({ created: "alpha" });
+
+    // Single-use: the second apply must be rejected (atomic consume lost).
+    await expect(
+      service.apply({ principal: allowed, token: proposal.token }),
+    ).rejects.toMatchObject({ code: "consumed" });
+  });
+
+  test("an expired token is rejected", async () => {
+    let current = new Date("2026-06-01T00:00:00Z");
+    const tool = mutatingTool();
+    const { service } = setup(tool, () => current);
+
+    const proposal = await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "beta" },
+      transport: "chat",
+    });
+
+    // Advance the clock past the 10-minute TTL.
+    current = new Date(current.getTime() + 11 * 60_000);
+    await expect(
+      service.apply({ principal: allowed, token: proposal.token }),
+    ).rejects.toMatchObject({ code: "expired" });
+  });
+
+  test("a tampered nonce is rejected (constant-time compare)", async () => {
+    const tool = mutatingTool();
+    const { service } = setup(tool);
+    const proposal = await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "gamma" },
+      transport: "chat",
+    });
+    // Replace the nonce with a same-length but different value.
+    const [head, nonce] = proposal.token.split(".");
+    const tampered = `${head}.${"f".repeat(nonce.length)}`;
+    await expect(
+      service.apply({ principal: allowed, token: tampered }),
+    ).rejects.toMatchObject({ code: "invalid_token" });
+  });
+
+  test("a malformed token is rejected", async () => {
+    const { service } = setup(mutatingTool());
+    await expect(
+      service.apply({ principal: allowed, token: "not-a-token" }),
+    ).rejects.toMatchObject({ code: "invalid_token" });
+  });
+});
+
+describe("propose/apply authorization (matrix #11 / decision 5)", () => {
+  test("propose is refused for a principal lacking the rule", async () => {
+    const { service } = setup(mutatingTool());
+    await expect(
+      service.propose({
+        principal: notAllowed,
+        toolName: "demo.mutate",
+        input: { value: "x" },
+        transport: "chat",
+      }),
+    ).rejects.toMatchObject({ code: "forbidden" });
+  });
+
+  test("apply re-checks authz: a rule lost after propose blocks apply", async () => {
+    const tool = mutatingTool();
+    const { service } = setup(tool);
+    const proposal = await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "x" },
+      transport: "chat",
+    });
+    // The SAME user, but their rules have since been revoked.
+    const revoked: AuthUser = { type: "user", id: "u1", accessRules: [] };
+    await expect(
+      service.apply({ principal: revoked, token: proposal.token }),
+    ).rejects.toMatchObject({ code: "forbidden" });
+  });
+
+  test("a read tool is not proposable", async () => {
+    const read = mutatingTool({ effect: "read", dryRun: undefined });
+    const { service } = setup(read);
+    await expect(
+      service.propose({
+        principal: allowed,
+        toolName: "demo.mutate",
+        input: { value: "x" },
+        transport: "chat",
+      }),
+    ).rejects.toMatchObject({ code: "not_proposable" });
+  });
+
+  test("a service principal can never propose", async () => {
+    const { service } = setup(mutatingTool());
+    await expect(
+      service.propose({
+        principal: { type: "service", pluginId: "x" },
+        toolName: "demo.mutate",
+        input: { value: "x" },
+        transport: "chat",
+      }),
+    ).rejects.toBeInstanceOf(ProposeApplyError);
+  });
+});
+
+describe("propose does NOT mutate (matrix #12)", () => {
+  test("propose runs dryRun and never calls execute", async () => {
+    const tool = mutatingTool();
+    const { service } = setup(tool);
+    await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "x" },
+      transport: "chat",
+    });
+    expect((tool as unknown as { _executed: number })._executed).toBe(0);
+  });
+});
+
+describe("audit rows (matrix #13)", () => {
+  test("propose writes a proposed row; apply transitions it to applied", async () => {
+    const tool = mutatingTool();
+    const { service, store } = setup(tool);
+    const proposal = await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "x" },
+      transport: "chat",
+    });
+    const proposedRow = store.rows.get(proposal.toolCallId);
+    expect(proposedRow?.status).toBe("proposed");
+    // The audit row stores a SHA-256 of the args, never the raw args. (The
+    // separate `proposedPayload` holds the VALIDATED apply payload by design —
+    // it is what `apply` commits — but the inbound args themselves are only
+    // ever represented as the hash.)
+    expect(proposedRow?.argsHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(proposedRow).not.toHaveProperty("args");
+    expect(proposedRow).not.toHaveProperty("rawArgs");
+
+    await service.apply({ principal: allowed, token: proposal.token });
+    expect(store.rows.get(proposal.toolCallId)?.status).toBe("applied");
+  });
+
+  test("apply records WHO applied, not the proposer (P3 review item 1)", async () => {
+    const tool = mutatingTool();
+    const { service, store } = setup(tool);
+    // Proposed by u1.
+    const proposal = await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "x" },
+      transport: "chat",
+    });
+    // Applied by a DIFFERENT principal that also holds the rule. The invariant
+    // (single-use 256-bit token + live authz re-check) holds, so the apply is
+    // recorded, attributed to the real applier — not rejected.
+    const otherApplier: AuthUser = {
+      type: "user",
+      id: "u-applier",
+      accessRules: ["demo.demo.manage"],
+    };
+    await service.apply({ principal: otherApplier, token: proposal.token });
+    const applied = store.rows.get(proposal.toolCallId);
+    expect(applied?.status).toBe("applied");
+    expect(applied?.principalKind).toBe("user");
+    expect(applied?.principalId).toBe("u1"); // proposer preserved
+    expect(applied?.appliedByKind).toBe("user");
+    expect(applied?.appliedById).toBe("u-applier"); // real applier recorded
+  });
+
+  test("apply re-parses the stored payload against the tool schema (P3 review item 2)", async () => {
+    // A tool whose input schema would reject the stored payload at apply time
+    // (simulating an evolved schema): execute must never run.
+    const tool = mutatingTool();
+    const { service, store } = setup(tool);
+    const proposal = await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "x" },
+      transport: "chat",
+    });
+    // Corrupt the server-stored payload so it no longer matches the schema.
+    const row = store.rows.get(proposal.toolCallId);
+    if (row) {
+      store.rows.set(proposal.toolCallId, {
+        ...row,
+        proposedPayload: { value: 42 } as unknown as Record<string, unknown>,
+      });
+    }
+    await expect(
+      service.apply({ principal: allowed, token: proposal.token }),
+    ).rejects.toMatchObject({ code: "execute_failed" });
+    // execute never ran.
+    expect((tool as unknown as { _executed: number })._executed).toBe(0);
+  });
+
+  test("expireStaleProposals flips expired rows to expired status", async () => {
+    let current = new Date("2026-06-01T00:00:00Z");
+    const tool = mutatingTool();
+    const { service, store } = setup(tool, () => current);
+    const proposal = await service.propose({
+      principal: allowed,
+      toolName: "demo.mutate",
+      input: { value: "x" },
+      transport: "chat",
+    });
+    current = new Date(current.getTime() + 11 * 60_000);
+    const n = await store.expireStaleProposals(current);
+    expect(n).toBe(1);
+    expect(store.rows.get(proposal.toolCallId)?.status).toBe("expired");
+  });
+});