@checkstack/ai-backend 0.1.0

package/src/hardening/handler-authz.test.ts

@@ -0,0 +1,282 @@
+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 "../propose-apply/service";
+import type { AiToolCallStore } from "../propose-apply/store";
+import type { AiToolCallRow } from "../schema";
+
+/**
+ * HARDENING: handler-side authorization holds when the MODEL MISBEHAVES
+ * (plan §1.5, §16 matrix #8/#11/#14, risk "Model calls a tool the principal
+ * can't use").
+ *
+ * The LLM is an untrusted caller that happens to be good at picking arguments.
+ * These named assertions prove the server refuses a model that "picks" a tool
+ * the principal is NOT allowed (or passes bad args) — the refusal is
+ * server-side, not a UI hint, and the underlying execute / dryRun is NEVER
+ * reached. This complements the per-transport tests (`mcp/server.test.ts` #8,
+ * `chat/agent-loop.test.ts` #14): here we assert the SHARED authorization spine
+ * (`resolver` + `propose-apply` service) directly, so the invariant holds for
+ * any future transport built on the same registry. Pure (no DB, no DOM).
+ */
+
+// These hardening tests reject at the authz / schema gate BEFORE the dry-run, so
+// the RPC client is never used; a throwing stub satisfies the required arg and
+// proves it is never reached.
+const rpcClient = {
+  forPlugin: () => {
+    throw new Error("authz gate must reject before any RPC call");
+  },
+} as unknown as RpcClient;
+
+/** A read tool whose execute must NEVER run for an unauthorized principal. */
+function readTool(
+  name: string,
+  rule: string,
+  onExecute: () => void,
+): RegisteredAiTool {
+  return {
+    name,
+    description: name,
+    effect: "read",
+    input: z.object({ q: z.string() }),
+    requiredAccessRules: [rule],
+    execute: () => {
+      onExecute();
+      return Promise.resolve({ ok: true });
+    },
+  };
+}
+
+/** A mutating tool whose dryRun must NEVER run for an unauthorized principal. */
+function mutateTool(
+  name: string,
+  rule: string,
+  hooks: { onDryRun: () => void; onExecute: () => void },
+): RegisteredAiTool {
+  return {
+    name,
+    description: name,
+    effect: "mutate",
+    input: z.object({ amount: z.number().int().positive() }),
+    requiredAccessRules: [rule],
+    dryRun: ({ input }) => {
+      hooks.onDryRun();
+      return Promise.resolve({ summary: "would mutate", payload: input });
+    },
+    execute: ({ input }) => {
+      hooks.onExecute();
+      return Promise.resolve(input);
+    },
+  };
+}
+
+/** Minimal in-memory store: enough for the propose path to be exercised. */
+function memStore(): AiToolCallStore {
+  let n = 0;
+  const rows = new Map<string, AiToolCallRow>();
+  const base = (over: Partial<AiToolCallRow>): AiToolCallRow => ({
+    id: `row-${++n}`,
+    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: new Date(),
+    ...over,
+  });
+  return {
+    async recordExecuted(args) {
+      const row = base({ ...args, conversationId: args.conversationId ?? null, effect: "read", status: "executed" });
+      rows.set(row.id, row);
+      return row;
+    },
+    async recordFailed(args) {
+      const row = base({ ...args, conversationId: args.conversationId ?? null, status: "failed" });
+      rows.set(row.id, row);
+      return row;
+    },
+    async createProposal(args) {
+      const nonce = "nonce-fixed";
+      const row = base({
+        ...args,
+        conversationId: args.conversationId ?? null,
+        proposalNonce: nonce,
+        proposalExpiresAt: new Date(Date.now() + 600_000),
+        proposedPayload: args.proposedPayload ?? null,
+        resultSnapshot: args.resultSnapshot ?? null,
+        proposedAt: new Date(),
+      });
+      rows.set(row.id, row);
+      return { row, nonce };
+    },
+    async getProposal(id) {
+      return rows.get(id);
+    },
+    async consumeProposal({ rowId }) {
+      const row = rows.get(rowId);
+      if (!row || row.status !== "proposed") return undefined;
+      const applied = { ...row, status: "applied" as const, appliedAt: new Date() };
+      rows.set(rowId, applied);
+      return applied;
+    },
+    async expireStaleProposals() {
+      return 0;
+    },
+  };
+}
+
+const limited: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["incident.incident.read"],
+};
+
+describe("HARDENING: a misbehaving model cannot escape the resolver gate", () => {
+  test("isAllowed refuses a tool whose rule the principal lacks", () => {
+    const registry = createAiToolRegistry();
+    let ran = false;
+    const adminTool = readTool("ai.secrets", "ai.tools.manage", () => {
+      ran = true;
+    });
+    registry.register(adminTool);
+    const resolver = createAiToolResolver({ registry });
+
+    expect(resolver.isAllowed({ principal: limited, tool: adminTool })).toBe(false);
+    // resolveTools never even surfaces it to the model.
+    expect(resolver.resolveTools(limited)).toEqual([]);
+    expect(ran).toBe(false);
+  });
+
+  test("a service principal (no access rules) is refused every tool", () => {
+    const registry = createAiToolRegistry();
+    const tool = readTool("incident.list", "incident.incident.read", () => {});
+    registry.register(tool);
+    const resolver = createAiToolResolver({ registry });
+    const service: AuthUser = { type: "service", pluginId: "svc" };
+    expect(resolver.isAllowed({ principal: service, tool })).toBe(false);
+  });
+});
+
+describe("HARDENING: propose refuses a model-picked out-of-scope tool BEFORE dryRun", () => {
+  test("an unauthorized mutating tool is refused server-side; dryRun never runs", async () => {
+    const registry = createAiToolRegistry();
+    let dryRan = false;
+    let executed = false;
+    const tool = mutateTool("billing.refund", "billing.billing.manage", {
+      onDryRun: () => {
+        dryRan = true;
+      },
+      onExecute: () => {
+        executed = true;
+      },
+    });
+    registry.register(tool);
+    const resolver = createAiToolResolver({ registry });
+    const service = createProposeApplyService({
+      registry,
+      resolver,
+      store: memStore(),
+    });
+
+    await expect(
+      service.propose({
+        principal: limited, // lacks billing.billing.manage
+        toolName: "billing.refund",
+        input: { amount: 100 },
+        transport: "chat",
+        rpcClient,
+      }),
+    ).rejects.toMatchObject({ code: "forbidden" });
+
+    // The dry-run (and therefore any mutation) was never reached.
+    expect(dryRan).toBe(false);
+    expect(executed).toBe(false);
+  });
+});
+
+describe("HARDENING: bad model-supplied args are rejected (no execution on garbage)", () => {
+  test("propose rejects args that fail the tool's own zod schema", async () => {
+    const registry = createAiToolRegistry();
+    let dryRan = false;
+    const tool = mutateTool("incident.escalate", "incident.incident.read", {
+      onDryRun: () => {
+        dryRan = true;
+      },
+      onExecute: () => {},
+    });
+    registry.register(tool);
+    const resolver = createAiToolResolver({ registry });
+    const service = createProposeApplyService({
+      registry,
+      resolver,
+      store: memStore(),
+    });
+
+    // The principal IS authorized (same rule), but the model passed bad args:
+    // `amount` must be a positive integer. The schema validation gate refuses
+    // it WITHOUT running the dry-run.
+    await expect(
+      service.propose({
+        principal: limited,
+        toolName: "incident.escalate",
+        input: { amount: -5 },
+        transport: "chat",
+        rpcClient,
+      }),
+    ).rejects.toBeInstanceOf(ProposeApplyError);
+    expect(dryRan).toBe(false);
+  });
+});
+
+describe("HARDENING: scope-narrowing can never WIDEN the surfaced toolset", () => {
+  // The resolver predicate is the same one autoAuthMiddleware applies. A
+  // scope-narrowed principal carries a SMALLER accessRules set; intersection can
+  // only ever shrink the visible tools — never add one the principal lacks.
+  test("narrowing the principal's rules monotonically shrinks the visible tools", () => {
+    const registry = createAiToolRegistry();
+    registry.register(readTool("incident.list", "incident.incident.read", () => {}));
+    registry.register(readTool("hc.status", "healthcheck.config.read", () => {}));
+    registry.register(readTool("ai.secrets", "ai.tools.manage", () => {}));
+    const resolver = createAiToolResolver({ registry });
+
+    const wide: AuthUser = {
+      type: "user",
+      id: "u1",
+      accessRules: ["incident.incident.read", "healthcheck.config.read"],
+    };
+    const narrowed: AuthUser = {
+      type: "user",
+      id: "u1",
+      accessRules: ["incident.incident.read"], // a token granted only this
+    };
+
+    const wideNames = new Set(resolver.resolveTools(wide).map((t) => t.name));
+    const narrowNames = new Set(resolver.resolveTools(narrowed).map((t) => t.name));
+
+    // Narrowed is a strict subset — never a superset.
+    for (const name of narrowNames) expect(wideNames.has(name)).toBe(true);
+    expect(narrowNames.has("hc.status")).toBe(false);
+    expect(narrowNames.has("ai.secrets")).toBe(false);
+    // And the narrowing never invented a tool outside the wide set.
+    expect([...narrowNames].every((n) => wideNames.has(n))).toBe(true);
+  });
+});

package/src/hardening/no-secret-leak.test.ts

@@ -0,0 +1,303 @@
+import { describe, expect, test, mock } from "bun:test";
+import { z } from "zod";
+import { isSecretSchema, toJsonSchema } from "@checkstack/backend-api";
+import {
+  AiChatIntegrationSchema,
+  AiConversationSchema,
+  AiMessageSchema,
+  AiProposalSchema,
+  AiToolDescriptorSchema,
+} from "@checkstack/ai-common";
+import { OpenAiCompatibleConnectionSchema } from "../openai-provider";
+import { serializeTool, serializeTools } from "../serializer";
+import type { RegisteredAiTool } from "../tool-registry";
+import { createAiConversationStore } from "../chat/conversation-store";
+import { REDACTED } from "../chat/scrub-content";
+
+/**
+ * NO-SECRET-LEAK DTO hardening (matrix #16, plan §16, risk "Integration API key
+ * leaks").
+ *
+ * The single most security-sensitive guarantee of the AI platform: a provider
+ * credential (the OpenAI-compatible `apiKey`, or ANY `x-secret` field) must
+ * NEVER cross an AI-facing wire. This suite asserts that property structurally
+ * across EVERY AI-surface DTO the plan enumerates:
+ *
+ *   - the MCP / OpenAI tool descriptor (and its JSON Schema),
+ *   - the `listTools` introspection output,
+ *   - the chat-integration picker DTO (`listChatIntegrations`),
+ *   - chat message + conversation records,
+ *   - the `ai_tool_calls` propose/apply proposal DTO,
+ *   - and chat-message persistence (secrets masked before they hit Postgres).
+ *
+ * These are pure schema/serialization assertions (no DB, no DOM), so they run in
+ * the default root `bun test`.
+ */
+
+/** A canary secret value. If it appears in ANY DTO, the test fails loudly. */
+const SECRET = "sk-canary-DO-NOT-LEAK-0123456789abcdef";
+
+/** Recursively assert the canary secret appears nowhere in a value. */
+function assertNoSecret(value: unknown, where: string): void {
+  expect(JSON.stringify(value) ?? "", `${where} must not contain the secret`).not.toContain(
+    SECRET,
+  );
+}
+
+describe("no-secret-leak: the connection schema marks apiKey x-secret", () => {
+  test("apiKey is x-secret; baseUrl / defaultModel are not", () => {
+    const shape = OpenAiCompatibleConnectionSchema.shape;
+    expect(isSecretSchema(shape.apiKey)).toBe(true);
+    expect(isSecretSchema(shape.baseUrl)).toBe(false);
+    expect(isSecretSchema(shape.defaultModel)).toBe(false);
+  });
+
+  test("the emitted JSON Schema flags apiKey x-secret (so the platform redacts it)", () => {
+    const json = toJsonSchema(OpenAiCompatibleConnectionSchema) as {
+      properties?: Record<string, { "x-secret"?: boolean }>;
+    };
+    expect(json.properties?.apiKey?.["x-secret"]).toBe(true);
+    expect(json.properties?.baseUrl?.["x-secret"]).toBeUndefined();
+  });
+});
+
+describe("no-secret-leak: tool descriptors never carry a credential", () => {
+  // A tool whose INPUT schema happens to declare a secret field (worst case):
+  // the descriptor must still never serialize a secret VALUE, and it carries no
+  // executor closure that could close over the credential.
+  const credentialTool: RegisteredAiTool = {
+    name: "evil.echo",
+    description: "A tool whose schema references a secret-ish field.",
+    effect: "read",
+    input: z.object({ q: z.string() }),
+    requiredAccessRules: ["incident.incident.read"],
+    execute: () => Promise.resolve({ ok: true }),
+  };
+
+  test("serializeTool returns only JSON Schema + metadata (no executor, no secret value)", () => {
+    const descriptor = serializeTool({ tool: credentialTool });
+    // Structural: the descriptor parses as the wire DTO (which has no executor).
+    const parsed = AiToolDescriptorSchema.parse(descriptor);
+    expect(parsed.name).toBe("evil.echo");
+    expect("execute" in descriptor).toBe(false);
+    assertNoSecret(descriptor, "tool descriptor");
+  });
+
+  test("serializeTools (listTools / MCP tools-list) leaks no secret", () => {
+    const descriptors = serializeTools({ tools: [credentialTool] });
+    assertNoSecret(descriptors, "listTools output");
+  });
+});
+
+describe("no-secret-leak: chat-integration picker exposes model UX only", () => {
+  test("AiChatIntegration DTO has no apiKey field and round-trips without one", () => {
+    // The DTO shape itself cannot carry a credential: there is no key for it.
+    expect(Object.keys(AiChatIntegrationSchema.shape)).not.toContain("apiKey");
+    const dto = AiChatIntegrationSchema.parse({
+      connectionId: "ai.openai-compatible.c1",
+      name: "OpenAI",
+      defaultModel: "gpt-4o-mini",
+      availableModels: ["gpt-4o-mini", "gpt-4o"],
+    });
+    assertNoSecret(dto, "listChatIntegrations DTO");
+  });
+
+  test("an UNKNOWN extra key (a hand-crafted apiKey) is stripped by the schema", () => {
+    // Even if a buggy handler tried to spread the raw connection, parsing the
+    // DTO drops keys outside the schema — the credential cannot ride along.
+    const raw = {
+      connectionId: "c1",
+      name: "OpenAI",
+      defaultModel: "gpt-4o-mini",
+      apiKey: SECRET,
+    };
+    const dto = AiChatIntegrationSchema.parse(raw);
+    expect("apiKey" in dto).toBe(false);
+    assertNoSecret(dto, "stripped listChatIntegrations DTO");
+  });
+});
+
+describe("no-secret-leak: conversation + message + proposal DTOs", () => {
+  test("AiConversation DTO carries no secret", () => {
+    const dto = AiConversationSchema.parse({
+      id: "c1",
+      title: "Investigate prod",
+      integrationId: "ai.openai-compatible.c1",
+      model: "gpt-4o-mini",
+      permissionMode: "approve",
+      createdAt: "2026-06-02T00:00:00Z",
+      updatedAt: "2026-06-02T00:00:00Z",
+    });
+    expect(Object.keys(dto)).not.toContain("apiKey");
+    assertNoSecret(dto, "conversation DTO");
+  });
+
+  test("AiMessage DTO carries no secret", () => {
+    const dto = AiMessageSchema.parse({
+      id: "m1",
+      conversationId: "c1",
+      role: "assistant",
+      content: { text: "here is the plan" },
+      toolCalls: [{ toolName: "incident.list", args: {} }],
+      createdAt: "2026-06-02T00:00:00Z",
+    });
+    assertNoSecret(dto, "message DTO");
+  });
+
+  test("AiProposal DTO (the ai_tool_calls proposal row surface) carries no secret", () => {
+    const dto = AiProposalSchema.parse({
+      token: "propose:row-1.abcdef",
+      summary: "Create an automation",
+      payload: { trigger: "incident.opened", actions: [] },
+      toolCallId: "row-1",
+      expiresAt: "2026-06-02T00:10:00Z",
+    });
+    assertNoSecret(dto, "proposal DTO");
+  });
+});
+
+describe("no-secret-leak: the credential is structurally unreachable from AI DTOs", () => {
+  // The credential lives ONLY on the integration connection (an x-secret field
+  // the integration platform stores in the Secrets Vault and redacts). No AI
+  // DTO has a field that can carry it: the chat-integration picker exposes model
+  // UX metadata only, and the agent loop only ever forwards tool RESULTS (which
+  // the source read procedures already redact) into a message — never the
+  // connection. We assert the negative across the full DTO set with a single
+  // worst-case payload that embeds the canary in every plausible position.
+  test("a worst-case object embedding the secret never validates into any AI DTO with the secret intact", () => {
+    // Each schema either lacks a field to hold the secret (stripped on parse) or
+    // would carry it only inside a free-form content/payload bag. Parsing the
+    // strict-shaped DTOs drops the credential.
+    const conv = AiConversationSchema.parse({
+      id: "c1",
+      title: SECRET, // a title is user-controlled, but it is never the credential
+      integrationId: "ai.openai-compatible.c1",
+      model: "gpt-4o-mini",
+      permissionMode: "approve",
+      createdAt: "2026-06-02T00:00:00Z",
+      updatedAt: "2026-06-02T00:00:00Z",
+    });
+    // The conversation DTO has no credential field; a coincidental title is the
+    // user's own text, not the provider key. The integration picker (the only
+    // DTO derived FROM the connection) cannot carry it:
+    const picker = AiChatIntegrationSchema.parse({
+      connectionId: "ai.openai-compatible.c1",
+      name: "OpenAI",
+      defaultModel: "gpt-4o-mini",
+      apiKey: SECRET, // hand-crafted extra key
+      availableModels: ["gpt-4o-mini"],
+    });
+    expect("apiKey" in picker).toBe(false);
+    assertNoSecret(picker, "listChatIntegrations DTO (credential-derived surface)");
+    // Sanity: the conversation title carries the user's literal input verbatim,
+    // proving the schema does not silently scrub arbitrary strings — the leak
+    // guarantee is that the credential has NO field to ride on, not blanket
+    // string scrubbing.
+    expect(conv.title).toBe(SECRET);
+  });
+
+  test("the canary is detectable (the guard has teeth — assertions are not vacuous)", () => {
+    // If a DTO ever DID carry the credential, assertNoSecret would catch it.
+    expect(() => assertNoSecret({ leaked: SECRET }, "teeth-check")).toThrow();
+  });
+});
+
+describe("no-secret-leak: the message WRITE PATH enforces the guarantee (canary)", () => {
+  /**
+   * The free-form `ai_messages.content` bag could, in principle, hold a secret
+   * if a buggy/malicious tool result smuggled one in. The guarantee is no longer
+   * merely architectural: `appendMessage` scrubs credential-shaped keys/values
+   * BEFORE the row hits Postgres. We assert the canary is stripped on write by
+   * capturing what the store passes to `db.insert(...).values(...)`.
+   */
+  function captureStore() {
+    const captured: Array<Record<string, unknown>> = [];
+    const returning = mock(() => Promise.resolve([{ id: "m1" }]));
+    const values = mock((v: Record<string, unknown>) => {
+      captured.push(v);
+      return { returning };
+    });
+    const updateWhere = mock(() => Promise.resolve([]));
+    const set = mock(() => ({ where: updateWhere }));
+    const db = {
+      insert: mock(() => ({ values })),
+      update: mock(() => ({ set })),
+    };
+    return { store: createAiConversationStore({ db: db as never }), captured };
+  }
+
+  test("a credential injected into message content is STRIPPED on write (not persisted)", async () => {
+    const { store, captured } = captureStore();
+    await store.appendMessage({
+      conversationId: "c1",
+      role: "tool",
+      // Worst case: a tool result that leaked the integration apiKey + a raw key.
+      content: {
+        text: "tool ran",
+        result: { apiKey: SECRET, headers: { authorization: `Bearer ${SECRET}` } },
+        rawSecretValue: SECRET,
+      },
+    });
+    const inserted = captured[0];
+    // What would be written to Postgres carries NO secret anywhere.
+    assertNoSecret(inserted, "persisted message content");
+    const content = inserted?.content as Record<string, unknown>;
+    const result = content.result as Record<string, unknown>;
+    expect(result.apiKey).toBe(REDACTED);
+    expect(content.rawSecretValue).toBe(REDACTED);
+    // Non-secret structure survives.
+    expect(content.text).toBe("tool ran");
+  });
+
+  test("a credential inside the REPLAY modelMessages is STRIPPED on write", async () => {
+    const { store, captured } = captureStore();
+    await store.appendMessage({
+      conversationId: "c1",
+      role: "assistant",
+      content: { text: "done" },
+      modelMessages: [
+        {
+          role: "tool",
+          content: [
+            {
+              type: "tool-result",
+              toolCallId: "tc1",
+              toolName: "x.read",
+              output: { type: "json", value: { apiKey: SECRET } },
+            },
+          ],
+        },
+      ],
+    });
+    const inserted = captured[0];
+    assertNoSecret(inserted, "persisted replay modelMessages");
+  });
+
+  test("a credential in the denormalized toolCalls column is STRIPPED on write", async () => {
+    const { store, captured } = captureStore();
+    await store.appendMessage({
+      conversationId: "c1",
+      role: "assistant",
+      content: { text: "calling" },
+      // The render-time denormalized tool calls bag is scrubbed too, so a
+      // credential smuggled into a tool's args/result can never persist here.
+      toolCalls: [
+        {
+          toolName: "x.read",
+          args: { authorization: `Bearer ${SECRET}`, q: "open" },
+          result: { apiKey: SECRET },
+        },
+      ],
+    });
+    const inserted = captured[0];
+    assertNoSecret(inserted, "persisted toolCalls column");
+    const toolCalls = inserted?.toolCalls as Array<Record<string, unknown>>;
+    const args = toolCalls[0]?.args as Record<string, unknown>;
+    const result = toolCalls[0]?.result as Record<string, unknown>;
+    expect(args.authorization).toBe(REDACTED);
+    expect(result.apiKey).toBe(REDACTED);
+    // Non-secret args survive so the call still renders.
+    expect(args.q).toBe("open");
+    expect(toolCalls[0]?.toolName).toBe("x.read");
+  });
+});

package/src/hooks.ts

@@ -0,0 +1,33 @@
+import { createHook } from "@checkstack/backend-api";
+import type { AiToolEffect } from "@checkstack/ai-common";
+
+/**
+ * Status reached by a tool call when the {@link aiHooks.toolCalled} hook fires.
+ */
+export type AiToolCalledStatus = "proposed" | "applied" | "executed" | "failed";
+
+/**
+ * Payload for the {@link aiHooks.toolCalled} event.
+ *
+ * Deliberately carries NO arguments and NO result body — only metadata. The
+ * audit row (`ai_tool_calls`) stores a SHA-256 `argsHash`, never the raw args,
+ * because they may carry PII or secrets (§10). Subscribers (notifications,
+ * anomaly-context, etc.) react to the fact of a call, not its contents.
+ */
+export interface AiToolCalledPayload {
+  principalKind: "user" | "application";
+  principalId: string;
+  transport: "chat" | "mcp" | "automation";
+  toolName: string;
+  effect: AiToolEffect;
+  status: AiToolCalledStatus;
+}
+
+/**
+ * AI platform hooks. Emitted on the shared event bus so subscribers on every
+ * pod receive them (cluster-wide), independent of which pod ran the tool.
+ */
+export const aiHooks = {
+  /** Emitted for every tool invocation (propose / apply / read). */
+  toolCalled: createHook<AiToolCalledPayload>("ai.toolCalled"),
+};