@intx/inference 0.1.2

package/src/audit-collector.ts

@@ -0,0 +1,172 @@
+// Audit collector: accumulates tool invocation records for persistence.
+//
+// The collector correlates three data sources into complete AuditRecord
+// objects:
+//   1. tool.start events — tool name and arguments (allowed calls only)
+//   2. AuthzDecision via onDecision — governance decision
+//   3. tool.done events — result and completion metadata
+//
+// Correlation is by callId. For blocked calls, no tool.start is emitted;
+// the collector creates the record from the buffered decision and the
+// tool.done event alone.
+//
+// Wiring: the caller must connect onDecision to the authz extension's
+// onDecision callback, and onEvent to the reactor's event stream. The
+// types alone do not enforce this — it is a composition-layer concern.
+
+import type { AuditRecord, AuditAuthz } from "@intx/types/audit";
+import type { InferenceEvent } from "@intx/types/runtime";
+import { getLogger } from "@intx/log";
+import type { AuthzDecision } from "./authz-extension";
+
+const logger = getLogger(["interchange", "audit-collector"]);
+
+type PendingRecord = {
+  callId: string;
+  tool: string;
+  arguments: Record<string, unknown>;
+  authz: AuditAuthz | null;
+};
+
+export type AuditCollector = {
+  onEvent(event: InferenceEvent): void;
+  onDecision(decision: AuthzDecision): void;
+  flush(): AuditRecord[];
+  pending(): number;
+};
+
+function coerceContent(content: unknown): string | Record<string, unknown> {
+  if (typeof content === "string") return content;
+  if (typeof content === "object" && content !== null) {
+    // content is a non-null object — compatible with Record<string, unknown>
+    // but TypeScript can't verify the index signature without a cast.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- non-null object is structurally compatible with Record<string, unknown> but TS won't widen
+    return content as Record<string, unknown>;
+  }
+  throw new Error(`Unexpected tool result content type: ${typeof content}`);
+}
+
+function mapGrant(g: AuthzDecision["matchingGrants"][number]) {
+  return {
+    id: g.id,
+    resource: g.resource,
+    action: g.action,
+    effect: g.effect,
+    origin: g.origin,
+    specificity: g.specificity,
+  };
+}
+
+function decisionToAuthz(d: AuthzDecision): AuditAuthz {
+  return {
+    effect: d.effect,
+    resolvedBy: d.resolvedBy ? mapGrant(d.resolvedBy) : null,
+    matchingGrants: d.matchingGrants.map(mapGrant),
+    blocked: d.blocked,
+    ...(d.blockReason !== undefined ? { blockReason: d.blockReason } : {}),
+  };
+}
+
+export function createAuditCollector(sessionId: string): AuditCollector {
+  const decisions = new Map<string, AuthzDecision>();
+  const pendingRecords = new Map<string, PendingRecord>();
+  const completed: AuditRecord[] = [];
+
+  function onDecision(decision: AuthzDecision): void {
+    decisions.set(decision.callId, decision);
+  }
+
+  function onEvent(event: InferenceEvent): void {
+    if (event.type === "tool.start") {
+      const call = event.data.call;
+      const decision = decisions.get(call.id);
+      decisions.delete(call.id);
+
+      pendingRecords.set(call.id, {
+        callId: call.id,
+        tool: call.name,
+        arguments: call.arguments,
+        authz: decision ? decisionToAuthz(decision) : null,
+      });
+      return;
+    }
+
+    if (event.type === "tool.done") {
+      const result = event.data.result;
+      const pending = pendingRecords.get(result.callId);
+
+      if (pending) {
+        pendingRecords.delete(result.callId);
+        completed.push({
+          callId: pending.callId,
+          tool: pending.tool,
+          arguments: pending.arguments,
+          authz: pending.authz,
+          result: {
+            content: coerceContent(result.content),
+            isError: result.isError === true,
+          },
+          timestamp: new Date().toISOString(),
+          sessionId,
+          seq: event.seq,
+        });
+        return;
+      }
+
+      // Blocked call: no tool.start was emitted. Build the record from
+      // the buffered decision and the tool.done event.
+      const decision = decisions.get(result.callId);
+      if (decision === undefined) {
+        // Orphaned tool.done: no tool.start or authz decision was recorded.
+        // Emit a degraded record rather than crashing the session — the audit
+        // system is observational infrastructure and must not veto execution.
+
+        logger.warn`Orphaned tool.done for callId "${result.callId}": no tool.start or authz decision was recorded`;
+        completed.push({
+          callId: result.callId,
+          tool: "$orphaned",
+          arguments: {},
+          authz: null,
+          result: {
+            content: coerceContent(result.content),
+            isError: result.isError === true,
+          },
+          timestamp: new Date().toISOString(),
+          sessionId,
+          seq: event.seq,
+        });
+        return;
+      }
+      decisions.delete(result.callId);
+
+      completed.push({
+        callId: result.callId,
+        tool: decision.tool,
+        arguments: {},
+        authz: decisionToAuthz(decision),
+        result: {
+          content: coerceContent(result.content),
+          isError: result.isError === true,
+        },
+        timestamp: new Date().toISOString(),
+        sessionId,
+        seq: event.seq,
+      });
+    }
+  }
+
+  function flush(): AuditRecord[] {
+    return completed.splice(0);
+  }
+
+  function pendingCount(): number {
+    return pendingRecords.size + decisions.size;
+  }
+
+  return {
+    onEvent,
+    onDecision,
+    flush,
+    pending: pendingCount,
+  };
+}

package/src/auth.test.ts

@@ -0,0 +1,117 @@
+// Credential-sentinel substitution. Adapters declare which credential
+// shape they want by placing one of the exported sentinel strings as
+// the header value; `injectCredentials` walks the header map and
+// rewrites exact-match values with material derived from
+// `InferenceSource.apiKey`. The harness uses this in place of the
+// previous per-header hardcoded branches so adding a new provider
+// requires no harness change.
+
+import { describe, expect, test } from "bun:test";
+
+import type { InferenceSource } from "@intx/types/runtime";
+
+import {
+  BEARER_CREDENTIAL_SENTINEL,
+  CREDENTIAL_SENTINEL,
+  injectCredentials,
+} from "./auth";
+
+const SOURCE: InferenceSource = {
+  id: "test:model",
+  provider: "test",
+  baseURL: "https://test.invalid",
+  apiKey: "sk-test-secret",
+  model: "test-model",
+};
+
+describe("injectCredentials", () => {
+  test("replaces CREDENTIAL_SENTINEL with apiKey verbatim", () => {
+    const out = injectCredentials(
+      {
+        "x-api-key": CREDENTIAL_SENTINEL,
+        "content-type": "application/json",
+      },
+      SOURCE,
+    );
+    expect(out["x-api-key"]).toBe("sk-test-secret");
+    expect(out["content-type"]).toBe("application/json");
+  });
+
+  test("replaces BEARER_CREDENTIAL_SENTINEL with Bearer-prefixed apiKey", () => {
+    const out = injectCredentials(
+      {
+        authorization: BEARER_CREDENTIAL_SENTINEL,
+        "content-type": "application/json",
+      },
+      SOURCE,
+    );
+    expect(out["authorization"]).toBe("Bearer sk-test-secret");
+    expect(out["content-type"]).toBe("application/json");
+  });
+
+  test("non-sentinel values pass through unchanged", () => {
+    const out = injectCredentials(
+      {
+        "content-type": "application/json",
+        "anthropic-version": "2023-06-01",
+        "user-agent": "test",
+      },
+      SOURCE,
+    );
+    expect(out["content-type"]).toBe("application/json");
+    expect(out["anthropic-version"]).toBe("2023-06-01");
+    expect(out["user-agent"]).toBe("test");
+  });
+
+  test("replaces sentinels regardless of header name (new providers need no harness change)", () => {
+    // The whole point of sentinel-based replacement: a brand-new
+    // provider that uses, say, `x-goog-api-key` works without
+    // touching this function. The exact header name is irrelevant
+    // to the substitution logic.
+    const out = injectCredentials(
+      { "x-goog-api-key": CREDENTIAL_SENTINEL },
+      SOURCE,
+    );
+    expect(out["x-goog-api-key"]).toBe("sk-test-secret");
+  });
+
+  test("substring matches are not replaced (exact match only)", () => {
+    // A header value that *contains* the sentinel literal as a
+    // substring -- but isn't exactly equal to it -- is left alone.
+    // Partial replacement would be surprising and no legitimate
+    // adapter constructs composite values around the sentinel.
+    const wrapped = `prefix ${CREDENTIAL_SENTINEL} suffix`;
+    const out = injectCredentials({ "x-weird-header": wrapped }, SOURCE);
+    expect(out["x-weird-header"]).toBe(wrapped);
+  });
+
+  test("returns a new object and does not mutate the input", () => {
+    const input: Record<string, string> = {
+      "x-api-key": CREDENTIAL_SENTINEL,
+    };
+    const out = injectCredentials(input, SOURCE);
+    expect(input["x-api-key"]).toBe(CREDENTIAL_SENTINEL);
+    expect(out["x-api-key"]).toBe("sk-test-secret");
+    expect(out).not.toBe(input);
+  });
+
+  test("handles multiple sentinels of mixed shapes in one request", () => {
+    // Pathological but well-defined: an adapter that wants both
+    // a verbatim credential header and a Bearer header (some
+    // vendors do this for legacy + modern endpoints) gets both
+    // replacements applied in one pass.
+    const out = injectCredentials(
+      {
+        "x-api-key": CREDENTIAL_SENTINEL,
+        authorization: BEARER_CREDENTIAL_SENTINEL,
+      },
+      SOURCE,
+    );
+    expect(out["x-api-key"]).toBe("sk-test-secret");
+    expect(out["authorization"]).toBe("Bearer sk-test-secret");
+  });
+
+  test("empty headers in, empty headers out", () => {
+    expect(injectCredentials({}, SOURCE)).toEqual({});
+  });
+});

package/src/auth.ts

@@ -0,0 +1,61 @@
+import type { InferenceSource } from "@intx/types/runtime";
+
+// Sentinel placeholder strings adapters use in their built request
+// headers to declare which credential the harness should fill at send
+// time. The harness scans every header value and replaces exact-match
+// sentinels with material derived from `InferenceSource.apiKey`. Adapters
+// never see the API key.
+//
+// Each new provider adds a new header name + sentinel choice in its
+// `buildRequest`; the harness needs no per-provider knowledge. The
+// alternative pattern -- a switch in the harness keyed on header name
+// -- was abandoned because the constraint ("how does this provider
+// want its credential delivered") lives with the adapter, not with the
+// harness, and growing a hardcoded branch per provider violates the
+// constraint-ownership rule.
+//
+// The sentinel strings deliberately contain angle brackets and a
+// keyword prefix that would never appear in a legitimate header value:
+// matching is exact, but defense-in-depth ensures a literal echo from
+// an upstream system can't accidentally trigger replacement.
+
+/**
+ * Sentinel for headers that carry the API key verbatim (no prefix).
+ * Used by providers like Anthropic (`x-api-key`) and Google
+ * (`x-goog-api-key`) that accept the raw credential.
+ */
+export const CREDENTIAL_SENTINEL = "<inject:credential>";
+
+/**
+ * Sentinel for headers that carry a Bearer-prefixed API key. Used by
+ * providers that follow the `Authorization: Bearer <token>` convention
+ * (OpenAI, OpenAI-compatible).
+ */
+export const BEARER_CREDENTIAL_SENTINEL = "<inject:bearer-credential>";
+
+/**
+ * Replace credential sentinels in a header map with material derived
+ * from the inference source. Returns a new object; the input is not
+ * mutated. Non-sentinel header values pass through unchanged.
+ *
+ * A header value that contains a sentinel as a substring but is not
+ * exactly equal to it is left alone -- partial replacement would be
+ * surprising, and no legitimate adapter constructs sentinel-bearing
+ * composite values.
+ */
+export function injectCredentials(
+  headers: Record<string, string>,
+  source: InferenceSource,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === CREDENTIAL_SENTINEL) {
+      result[name] = source.apiKey;
+    } else if (value === BEARER_CREDENTIAL_SENTINEL) {
+      result[name] = `Bearer ${source.apiKey}`;
+    } else {
+      result[name] = value;
+    }
+  }
+  return result;
+}

package/src/authz-extension.test.ts

@@ -0,0 +1,269 @@
+import { describe, test, expect } from "bun:test";
+
+import {
+  createAuthzExtension,
+  type AuthzCallResult,
+  type AuthzDecision,
+} from "./authz-extension";
+
+import type { ToolCall, ReactorState, TokenUsage } from "@intx/types/runtime";
+
+function emptyUsage(): TokenUsage {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, thinking: 0 };
+}
+
+function makeState(): ReactorState {
+  return {
+    sessionId: "test",
+    turns: [],
+    activeForks: [],
+    pendingOperations: [],
+    activeGates: [],
+    tokenUsage: emptyUsage(),
+    lastCycleUsage: null,
+    lastCycleSource: null,
+  };
+}
+
+function makeCall(name = "bash"): ToolCall {
+  return { id: "call-1", name, arguments: {} };
+}
+
+function getDecision(decisions: AuthzDecision[]): AuthzDecision {
+  const d = decisions[0];
+  if (d === undefined) throw new Error("no decisions recorded");
+  return d;
+}
+
+function allowResult(): AuthzCallResult {
+  return {
+    effect: "allow",
+    matchingGrants: [
+      {
+        id: "grant-1",
+        resource: "tool:bash",
+        action: "invoke",
+        effect: "allow",
+        origin: "creator",
+        specificity: 1009,
+      },
+    ],
+    resolvedBy: {
+      id: "grant-1",
+      resource: "tool:bash",
+      action: "invoke",
+      effect: "allow",
+      origin: "creator",
+      specificity: 1009,
+    },
+  };
+}
+
+function denyResult(): AuthzCallResult {
+  return {
+    effect: "deny",
+    matchingGrants: [
+      {
+        id: "grant-2",
+        resource: "tool:bash",
+        action: "invoke",
+        effect: "deny",
+        origin: "system",
+        specificity: 1009,
+      },
+    ],
+    resolvedBy: {
+      id: "grant-2",
+      resource: "tool:bash",
+      action: "invoke",
+      effect: "deny",
+      origin: "system",
+      specificity: 1009,
+    },
+  };
+}
+
+describe("createAuthzExtension", () => {
+  const signal = new AbortController().signal;
+
+  test("allow effect returns undefined and calls onDecision", async () => {
+    const decisions: AuthzDecision[] = [];
+
+    const ext = createAuthzExtension({
+      authorize: async () => allowResult(),
+      onDecision: (d) => decisions.push(d),
+    });
+
+    const result = await ext.beforeTool(makeCall(), makeState(), signal);
+
+    expect(result).toBeUndefined();
+    const d = getDecision(decisions);
+    expect(d.callId).toBe("call-1");
+    expect(d.effect).toBe("allow");
+    expect(d.blocked).toBe(false);
+    expect(d.blockReason).toBeUndefined();
+    expect(d.tool).toBe("bash");
+    expect(d.resource).toBe("tool:bash");
+    expect(d.action).toBe("invoke");
+  });
+
+  test("deny effect returns block reason and calls onDecision", async () => {
+    const decisions: AuthzDecision[] = [];
+
+    const ext = createAuthzExtension({
+      authorize: async () => denyResult(),
+      onDecision: (d) => decisions.push(d),
+    });
+
+    const result = await ext.beforeTool(makeCall(), makeState(), signal);
+
+    expect(result).toBe("Denied by policy: tool:bash/invoke");
+    const d = getDecision(decisions);
+    expect(d.effect).toBe("deny");
+    expect(d.blocked).toBe(true);
+    expect(d.blockReason).toBe("Denied by policy: tool:bash/invoke");
+    expect(d.resolvedBy).toBeDefined();
+    if (d.resolvedBy === null) throw new Error("expected resolvedBy");
+    expect(d.resolvedBy.id).toBe("grant-2");
+  });
+
+  test("ask effect blocks with approval message", async () => {
+    const decisions: AuthzDecision[] = [];
+
+    const ext = createAuthzExtension({
+      authorize: async () => ({
+        effect: "ask" as const,
+        matchingGrants: [],
+        resolvedBy: null,
+      }),
+      onDecision: (d) => decisions.push(d),
+    });
+
+    const result = await ext.beforeTool(makeCall(), makeState(), signal);
+
+    expect(result).toBe("Requires approval: tool:bash/invoke");
+    const d = getDecision(decisions);
+    expect(d.effect).toBe("ask");
+    expect(d.blocked).toBe(true);
+  });
+
+  test("null effect (no matching grants) blocks fail-closed", async () => {
+    const decisions: AuthzDecision[] = [];
+
+    const ext = createAuthzExtension({
+      authorize: async () => ({
+        effect: null,
+        matchingGrants: [],
+        resolvedBy: null,
+      }),
+      onDecision: (d) => decisions.push(d),
+    });
+
+    const result = await ext.beforeTool(makeCall(), makeState(), signal);
+
+    expect(result).toBe("No matching grants for tool:bash/invoke");
+    const d = getDecision(decisions);
+    expect(d.effect).toBeNull();
+    expect(d.blocked).toBe(true);
+  });
+
+  test("authorize throwing calls onDecision with error and rethrows", async () => {
+    const decisions: AuthzDecision[] = [];
+
+    const ext = createAuthzExtension({
+      authorize: async () => {
+        throw new Error("DB connection failed");
+      },
+      onDecision: (d) => decisions.push(d),
+    });
+
+    let thrown: Error | undefined;
+    try {
+      await ext.beforeTool(makeCall(), makeState(), signal);
+    } catch (cause) {
+      thrown = cause instanceof Error ? cause : new Error(String(cause));
+    }
+    expect(thrown?.message).toBe("DB connection failed");
+
+    const d = getDecision(decisions);
+    expect(d.callId).toBe("call-1");
+    expect(d.blocked).toBe(true);
+    expect(d.error).toBe("DB connection failed");
+    expect(d.blockReason).toBe("Authorization failed: DB connection failed");
+    expect(d.effect).toBeNull();
+  });
+
+  test("onDecision is optional", async () => {
+    const ext = createAuthzExtension({
+      authorize: async () => allowResult(),
+    });
+
+    const result = await ext.beforeTool(makeCall(), makeState(), signal);
+    expect(result).toBeUndefined();
+  });
+
+  test("resource format uses tool:{name}", async () => {
+    let capturedResource = "";
+
+    const ext = createAuthzExtension({
+      authorize: async (resource) => {
+        capturedResource = resource;
+        return allowResult();
+      },
+    });
+
+    await ext.beforeTool(makeCall("stripe_charge"), makeState(), signal);
+    expect(capturedResource).toBe("tool:stripe_charge");
+  });
+
+  test("matchingGrants are passed through to decision", async () => {
+    const decisions: AuthzDecision[] = [];
+    const expectedGrants = denyResult().matchingGrants;
+
+    const ext = createAuthzExtension({
+      authorize: async () => denyResult(),
+      onDecision: (d) => decisions.push(d),
+    });
+
+    await ext.beforeTool(makeCall(), makeState(), signal);
+
+    const d = getDecision(decisions);
+    expect(d.matchingGrants.length).toBe(expectedGrants.length);
+    const firstGrant = d.matchingGrants[0];
+    const expectedFirst = expectedGrants[0];
+    if (firstGrant === undefined || expectedFirst === undefined)
+      throw new Error("expected at least one grant");
+    expect(firstGrant.id).toBe(expectedFirst.id);
+  });
+
+  test("onDecision throwing does not affect allow decision", async () => {
+    const ext = createAuthzExtension({
+      authorize: async () => allowResult(),
+      onDecision: () => {
+        throw new Error("audit log failed");
+      },
+    });
+
+    const result = await ext.beforeTool(makeCall(), makeState(), signal);
+    expect(result).toBeUndefined();
+  });
+
+  test("onDecision throwing does not mask authorize error", async () => {
+    const ext = createAuthzExtension({
+      authorize: async () => {
+        throw new Error("DB connection failed");
+      },
+      onDecision: () => {
+        throw new Error("audit log failed");
+      },
+    });
+
+    let thrown: Error | undefined;
+    try {
+      await ext.beforeTool(makeCall(), makeState(), signal);
+    } catch (cause) {
+      thrown = cause instanceof Error ? cause : new Error(String(cause));
+    }
+    expect(thrown?.message).toBe("DB connection failed");
+  });
+});