@checkstack/ai-backend 0.1.0

package/src/registry-wiring.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { access, definePluginMetadata, proc } from "@checkstack/common";
+import { AiToolEffectSchema } from "@checkstack/ai-common";
+import type { AnyContractProcedure } from "@orpc/contract";
+import { createAiToolRegistry } from "./tool-registry";
+import { createRegistryExtensionPoints } from "./registry-wiring";
+import type { RegisteredAiTool } from "./tool-registry";
+
+const sourcePluginMetadata = definePluginMetadata({ pluginId: "incident" });
+const incidentRead = access("incident", "read", "View incidents");
+const listIncidents = proc({
+  operationType: "query",
+  userType: "authenticated",
+  access: [incidentRead],
+}).input(z.object({ status: z.string().optional() })) as AnyContractProcedure;
+
+function handAuthoredTool(): RegisteredAiTool {
+  return {
+    // Unqualified name — the extension point must qualify it with the plugin id.
+    name: "propose",
+    description: "Propose an automation from natural language.",
+    effect: "mutate",
+    input: z.object({ prompt: z.string() }),
+    requiredAccessRules: ["automation.automation.manage"],
+    execute: () => Promise.resolve({}),
+  };
+}
+
+describe("createRegistryExtensionPoints (end-to-end registration)", () => {
+  test("registerTool qualifies an unqualified name with the plugin id", () => {
+    const registry = createAiToolRegistry();
+    const { toolExtensionPoint } = createRegistryExtensionPoints({ registry });
+
+    toolExtensionPoint.registerTool(
+      handAuthoredTool(),
+      definePluginMetadata({ pluginId: "automation" }),
+    );
+
+    expect(registry.hasTool("automation.propose")).toBe(true);
+    expect(registry.getTool("automation.propose")?.effect).toBe("mutate");
+  });
+
+  test("registerTool leaves an already-qualified name unchanged", () => {
+    const registry = createAiToolRegistry();
+    const { toolExtensionPoint } = createRegistryExtensionPoints({ registry });
+
+    toolExtensionPoint.registerTool(
+      { ...handAuthoredTool(), name: "automation.propose" },
+      definePluginMetadata({ pluginId: "different" }),
+    );
+
+    expect(registry.hasTool("automation.propose")).toBe(true);
+    expect(registry.hasTool("different.automation.propose")).toBe(false);
+  });
+
+  test("expose builds and registers a projected tool from a contract procedure", () => {
+    const registry = createAiToolRegistry();
+    const { projectionExtensionPoint } = createRegistryExtensionPoints({
+      registry,
+    });
+
+    projectionExtensionPoint.expose({
+      procedure: listIncidents,
+      sourcePluginMetadata,
+      procedureKey: "listIncidents",
+      name: "incident.list",
+      description: "List incidents.",
+      effect: "read",
+      execute: () => Promise.resolve({}),
+    });
+
+    const tool = registry.getTool("incident.list");
+    expect(tool).toBeDefined();
+    // Access rules read verbatim from the source procedure, qualified.
+    expect(tool?.requiredAccessRules).toEqual(["incident.incident.read"]);
+    expect(tool?.effect).toBe("read");
+  });
+
+  test("both paths populate the SAME registry (one spine, two paths)", () => {
+    const registry = createAiToolRegistry();
+    const { toolExtensionPoint, projectionExtensionPoint } =
+      createRegistryExtensionPoints({ registry });
+
+    toolExtensionPoint.registerTool(
+      handAuthoredTool(),
+      definePluginMetadata({ pluginId: "automation" }),
+    );
+    projectionExtensionPoint.expose({
+      procedure: listIncidents,
+      sourcePluginMetadata,
+      procedureKey: "listIncidents",
+      name: "incident.list",
+      description: "List incidents.",
+      effect: "read",
+      execute: () => Promise.resolve({}),
+    });
+
+    expect(registry.getTools().map((t) => t.name).sort()).toEqual([
+      "automation.propose",
+      "incident.list",
+    ]);
+  });
+
+  // §4.2 belt-and-suspenders: every registered tool carries a VALID effect.
+  // This is already guaranteed by the `AiToolEffect` type at compile time, but
+  // the runtime assertion documents the invariant the permission-mode gating
+  // keys on - an effect outside `read | mutate | destructive` would slip the
+  // 3-tier disposition logic.
+  test("every registered tool has a valid effect", () => {
+    const registry = createAiToolRegistry();
+    const { toolExtensionPoint, projectionExtensionPoint } =
+      createRegistryExtensionPoints({ registry });
+    toolExtensionPoint.registerTool(
+      handAuthoredTool(),
+      definePluginMetadata({ pluginId: "automation" }),
+    );
+    projectionExtensionPoint.expose({
+      procedure: listIncidents,
+      sourcePluginMetadata,
+      procedureKey: "listIncidents",
+      name: "incident.list",
+      description: "List incidents.",
+      effect: "read",
+      execute: () => Promise.resolve({}),
+    });
+    for (const tool of registry.getTools()) {
+      expect(AiToolEffectSchema.safeParse(tool.effect).success).toBe(true);
+    }
+  });
+});

package/src/registry-wiring.ts

@@ -0,0 +1,68 @@
+import type { PluginMetadata } from "@checkstack/common";
+import type {
+  AiToolExtensionPoint,
+  AiToolProjectionExtensionPoint,
+} from "./extension-points";
+import { buildProjectedTool } from "./projection";
+import type { AiToolRegistry } from "./tool-registry";
+
+/**
+ * Build the two extension-point implementations that feed a tool {@link
+ * AiToolRegistry}. Factored out of the plugin `register()` so the exact
+ * production wiring (name qualification for hand-authored tools, `expose`
+ * building a projected tool from a contract procedure) is unit-testable
+ * end-to-end without standing up a full plugin environment.
+ *
+ * Both paths are the ONLY way a tool reaches the registry:
+ * - `registerTool` qualifies a hand-authored composite tool's name with the
+ *   registering plugin id (unless already qualified).
+ * - `expose` builds a projected tool from an oRPC contract procedure via
+ *   {@link buildProjectedTool} and registers it.
+ */
+/**
+ * Routing metadata for a projected read tool, accumulated as plugins `expose`
+ * their own read procedures. The MCP transport and the chat read-loop re-enter
+ * the live router using `{ pluginId, procedureKey }`, so ai-backend collects this
+ * AFTER all plugins have registered (in `afterPluginsReady`) - it does not need
+ * to know which plugins exist or import their `*-common`.
+ */
+export interface ExposedProjectionRoute {
+  toolName: string;
+  pluginId: string;
+  procedureKey: string;
+}
+
+export function createRegistryExtensionPoints({
+  registry,
+}: {
+  registry: AiToolRegistry;
+}): {
+  toolExtensionPoint: AiToolExtensionPoint;
+  projectionExtensionPoint: AiToolProjectionExtensionPoint;
+  /** Routing for every projection exposed via the point (populated lazily). */
+  exposedProjections: ExposedProjectionRoute[];
+} {
+  const toolExtensionPoint: AiToolExtensionPoint = {
+    registerTool: (tool, metadata: PluginMetadata) => {
+      const qualifiedName = tool.name.includes(".")
+        ? tool.name
+        : `${metadata.pluginId}.${tool.name}`;
+      registry.register({ ...tool, name: qualifiedName });
+    },
+  };
+
+  const exposedProjections: ExposedProjectionRoute[] = [];
+  const projectionExtensionPoint: AiToolProjectionExtensionPoint = {
+    expose: (input) => {
+      const tool = buildProjectedTool(input);
+      registry.register(tool);
+      exposedProjections.push({
+        toolName: tool.name,
+        pluginId: input.sourcePluginMetadata.pluginId,
+        procedureKey: input.procedureKey,
+      });
+    },
+  };
+
+  return { toolExtensionPoint, projectionExtensionPoint, exposedProjections };
+}

package/src/resolver.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import type { AuthUser } from "@checkstack/backend-api";
+import { createAiToolRegistry, type RegisteredAiTool } from "./tool-registry";
+import { createAiToolResolver, principalSatisfiesRules } from "./resolver";
+
+function tool(
+  name: string,
+  requiredAccessRules: string[],
+): RegisteredAiTool {
+  return {
+    name,
+    description: name,
+    effect: "read",
+    input: z.object({}),
+    requiredAccessRules,
+    execute: () => Promise.resolve({}),
+  };
+}
+
+function userWith(accessRules: string[]): AuthUser {
+  return { type: "user", id: "u1", accessRules };
+}
+
+describe("createAiToolResolver.resolveTools", () => {
+  test("a principal lacking automation.manage never sees automation.propose", () => {
+    const registry = createAiToolRegistry();
+    registry.register(
+      tool("automation.propose", ["automation.automation.manage"]),
+    );
+    registry.register(tool("incident.list", ["incident.incident.read"]));
+    const resolver = createAiToolResolver({ registry });
+
+    const principal = userWith(["incident.incident.read"]);
+    const names = resolver.resolveTools(principal).map((t) => t.name);
+
+    expect(names).toEqual(["incident.list"]);
+    expect(names).not.toContain("automation.propose");
+  });
+
+  test("an admin (accessRules ['*']) sees all tools", () => {
+    const registry = createAiToolRegistry();
+    registry.register(
+      tool("automation.propose", ["automation.automation.manage"]),
+    );
+    registry.register(tool("incident.list", ["incident.incident.read"]));
+    const resolver = createAiToolResolver({ registry });
+
+    const names = resolver
+      .resolveTools(userWith(["*"]))
+      .map((t) => t.name)
+      .sort();
+
+    expect(names).toEqual(["automation.propose", "incident.list"]);
+  });
+
+  test("a service principal (no access rules) sees no tools", () => {
+    const registry = createAiToolRegistry();
+    registry.register(tool("incident.list", ["incident.incident.read"]));
+    const resolver = createAiToolResolver({ registry });
+
+    const service: AuthUser = { type: "service", pluginId: "automation" };
+    expect(resolver.resolveTools(service)).toEqual([]);
+  });
+
+  test("a tool requiring MULTIPLE rules needs ALL of them", () => {
+    const registry = createAiToolRegistry();
+    registry.register(
+      tool("multi", ["incident.incident.read", "catalog.system.read"]),
+    );
+    const resolver = createAiToolResolver({ registry });
+
+    expect(
+      resolver.resolveTools(userWith(["incident.incident.read"])),
+    ).toEqual([]);
+    expect(
+      resolver
+        .resolveTools(
+          userWith(["incident.incident.read", "catalog.system.read"]),
+        )
+        .map((t) => t.name),
+    ).toEqual(["multi"]);
+  });
+});
+
+describe("isAllowed mirrors autoAuthMiddleware's global-rule check", () => {
+  // Replicates the EXACT predicate autoAuthMiddleware applies to global rules
+  // (rpc.ts:258-260): rules.includes("*") || rules.includes(qualifiedId).
+  function middlewareWouldAllow(
+    rules: string[],
+    requiredAccessRules: string[],
+  ): boolean {
+    return requiredAccessRules.every(
+      (rule) => rules.includes("*") || rules.includes(rule),
+    );
+  }
+
+  const ruleUniverse = ["a.read", "b.read", "c.manage"];
+  const principalSets: string[][] = [
+    [],
+    ["*"],
+    ["a.read"],
+    ["a.read", "b.read"],
+    ["c.manage"],
+    ["a.read", "b.read", "c.manage"],
+  ];
+  const toolRuleSets: string[][] = [
+    [],
+    ["a.read"],
+    ["a.read", "b.read"],
+    ["c.manage"],
+    ["a.read", "c.manage"],
+    ruleUniverse,
+  ];
+
+  test("isAllowed == middleware decision for the full matrix", () => {
+    const registry = createAiToolRegistry();
+    const resolver = createAiToolResolver({ registry });
+
+    for (const rules of principalSets) {
+      for (const required of toolRuleSets) {
+        const principal = userWith(rules);
+        const t = tool("t", required);
+        const expected = middlewareWouldAllow(rules, required);
+        expect(resolver.isAllowed({ principal, tool: t })).toBe(expected);
+        expect(
+          principalSatisfiesRules({
+            principalAccessRules: rules,
+            requiredAccessRules: required,
+          }),
+        ).toBe(expected);
+      }
+    }
+  });
+
+  test("narrowing can never widen: a subset principal allows a subset of tools", () => {
+    const registry = createAiToolRegistry();
+    registry.register(tool("t1", ["a.read"]));
+    registry.register(tool("t2", ["b.read"]));
+    registry.register(tool("t3", ["c.manage"]));
+    const resolver = createAiToolResolver({ registry });
+
+    const full = userWith(["a.read", "b.read", "c.manage"]);
+    const narrowed = userWith(["a.read"]); // a narrowed token: strict subset
+
+    const fullNames = new Set(resolver.resolveTools(full).map((t) => t.name));
+    const narrowedNames = resolver.resolveTools(narrowed).map((t) => t.name);
+
+    // Every tool the narrowed principal sees is also seen by the full
+    // principal — narrowing only ever removes tools.
+    for (const name of narrowedNames) {
+      expect(fullNames.has(name)).toBe(true);
+    }
+    expect(narrowedNames).toEqual(["t1"]);
+  });
+});

package/src/resolver.ts

@@ -0,0 +1,78 @@
+import type { AuthUser } from "@checkstack/backend-api";
+import type { RegisteredAiTool } from "./tool-registry";
+import type { AiToolRegistry } from "./tool-registry";
+
+/**
+ * Resolves the subset of registered tools a principal may see / call.
+ *
+ * The predicate is intentionally IDENTICAL to the global-rule check
+ * `autoAuthMiddleware` applies (rpc.ts:258-260): a tool is allowed iff EVERY
+ * `requiredAccessRules` entry is satisfied by the principal's `accessRules`,
+ * with the `"*"` admin escape. This guarantees the resolver can never surface a
+ * tool the handler would then reject for a global rule, and — crucially — can
+ * never WIDEN a principal: a scope-narrowed principal carries a smaller
+ * `accessRules` set, and the intersection only ever shrinks the visible tools.
+ *
+ * Team reach is NOT pre-filtered here. Instance (team-scoped) rules are
+ * enforced per-call handler-side via the existing S2S `checkResourceTeamAccess`,
+ * so the resolver filters by the access-rule VOCABULARY only and the surfaced
+ * tool set matches exactly what the principal could invoke in the UI.
+ */
+export interface AiToolResolver {
+  resolveTools(principal: AuthUser): RegisteredAiTool[];
+  isAllowed(args: { principal: AuthUser; tool: RegisteredAiTool }): boolean;
+}
+
+/**
+ * Pure predicate mirroring the middleware's global-rule check. Exported so
+ * tests can assert it equals `autoAuthMiddleware`'s behaviour for an arbitrary
+ * (rules, requiredAccessRules) matrix.
+ */
+export function principalSatisfiesRules({
+  principalAccessRules,
+  requiredAccessRules,
+}: {
+  principalAccessRules: readonly string[];
+  requiredAccessRules: readonly string[];
+}): boolean {
+  return requiredAccessRules.every(
+    (rule) =>
+      principalAccessRules.includes("*") ||
+      principalAccessRules.includes(rule),
+  );
+}
+
+/**
+ * Single-tool authorization gate. Services bypass the registry entirely (they
+ * are trusted S2S callers and never drive the model); a service principal has
+ * no access-rule set, so it is never granted a tool here.
+ */
+export function isToolAllowed({
+  principal,
+  tool,
+}: {
+  principal: AuthUser;
+  tool: RegisteredAiTool;
+}): boolean {
+  const principalAccessRules =
+    "accessRules" in principal ? (principal.accessRules ?? []) : [];
+  return principalSatisfiesRules({
+    principalAccessRules,
+    requiredAccessRules: tool.requiredAccessRules,
+  });
+}
+
+export function createAiToolResolver({
+  registry,
+}: {
+  registry: AiToolRegistry;
+}): AiToolResolver {
+  return {
+    isAllowed: isToolAllowed,
+    resolveTools(principal: AuthUser): RegisteredAiTool[] {
+      return registry
+        .getTools()
+        .filter((tool) => isToolAllowed({ principal, tool }));
+    },
+  };
+}

package/src/router.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { coerceConversationModel } from "./router";
+import type { ChatIntegrationLister } from "./router";
+
+function lister(
+  integrations: Array<{
+    connectionId: string;
+    name: string;
+    defaultModel: string;
+    availableModels?: string[];
+  }>,
+): ChatIntegrationLister {
+  return { list: () => Promise.resolve(integrations) };
+}
+
+const conn = {
+  connectionId: "ai.openai-compatible.c1",
+  name: "OpenAI",
+  defaultModel: "gpt-4o-mini",
+  availableModels: ["gpt-4o-mini", "gpt-4o"],
+};
+
+describe("coerceConversationModel (P4 review item 1 — server-side model control)", () => {
+  test("honours an allowlisted model", async () => {
+    const model = await coerceConversationModel({
+      integrations: lister([conn]),
+      integrationId: conn.connectionId,
+      model: "gpt-4o",
+    });
+    expect(model).toBe("gpt-4o");
+  });
+
+  test("coerces an out-of-allowlist model to defaultModel (untrusted wire input)", async () => {
+    const model = await coerceConversationModel({
+      integrations: lister([conn]),
+      integrationId: conn.connectionId,
+      model: "evil-model",
+    });
+    expect(model).toBe("gpt-4o-mini");
+  });
+
+  test("an empty allowlist allows any model (free-text providers)", async () => {
+    const free = { ...conn, availableModels: undefined };
+    const model = await coerceConversationModel({
+      integrations: lister([free]),
+      integrationId: free.connectionId,
+      model: "llama3",
+    });
+    expect(model).toBe("llama3");
+  });
+
+  test("returns undefined when no model is requested", async () => {
+    const model = await coerceConversationModel({
+      integrations: lister([conn]),
+      integrationId: conn.connectionId,
+      model: undefined,
+    });
+    expect(model).toBeUndefined();
+  });
+
+  test("drops the model when the integration cannot be resolved (no validation possible)", async () => {
+    const model = await coerceConversationModel({
+      integrations: lister([conn]),
+      integrationId: "unknown.connection",
+      model: "gpt-4o",
+    });
+    expect(model).toBeUndefined();
+  });
+
+  test("drops the model when no integration id is given", async () => {
+    const model = await coerceConversationModel({
+      integrations: lister([conn]),
+      integrationId: undefined,
+      model: "gpt-4o",
+    });
+    expect(model).toBeUndefined();
+  });
+});