@mcpose/audit 2.0.3 → 3.1.0

package/src/sensitivity.ts

@@ -0,0 +1,33 @@
+import type {
+  SensitivityTier,
+  SensitivityResolverFn,
+  SensitivityOverrideFn,
+} from './types.js';
+
+const TIERS: ReadonlySet<string> = new Set(['low', 'medium', 'high']);
+
+function validTier(value: unknown): SensitivityTier {
+  // Fail CLOSED: anything that is not a known tier resolves to 'high'
+  // (encrypt). Guards against typos in the map and misbehaving overrides.
+  return TIERS.has(value as string) ? (value as SensitivityTier) : 'high';
+}
+
+/**
+ * Builds a resolver from a static tool→tier map, with an optional dynamic
+ * override that receives the map's resolution as its fourth argument.
+ *
+ * Unknown tools resolve to `'high'` (encrypt by default). The lookup uses
+ * `Object.hasOwn`, so prototype-inherited keys (a tool named `toString` or
+ * `constructor` — tool names are attacker-controlled) cannot bypass that
+ * default.
+ */
+export function createSensitivityResolver(
+  map: Record<string, SensitivityTier>,
+  override?: SensitivityOverrideFn,
+): SensitivityResolverFn {
+  return (tool, identity, args) => {
+    const mapTier = validTier(Object.hasOwn(map, tool) ? map[tool] : undefined);
+    if (override) return validTier(override(tool, identity, args, mapTier));
+    return mapTier;
+  };
+}

package/src/signingKey.ts

@@ -0,0 +1,35 @@
+import { createHmac } from 'node:crypto';
+import type { SigningKeyProvider } from './types.js';
+
+// keyId derivation label. v1 used bare SHA256(secret), which let anyone
+// holding a manifest brute-force a low-entropy secret offline from the
+// published keyId. HMAC with a domain label is not invertible into a
+// dictionary check any faster than attacking the signature itself, and
+// keeps keyId stable per secret. See ADR-0004.
+const DOMAIN_KEYID = 'mcpose/v2/keyid';
+
+/**
+ * In-process HMAC-SHA256 signing provider.
+ *
+ * The secret must be high-entropy (>= 32 random bytes). `keyId` is PUBLIC —
+ * it is published in every ReplayManifest — so it must never be used as key
+ * material (ADR-0003), and a guessable secret is offline-attackable from
+ * any published manifest.
+ */
+export function createDefaultSigningKeyProvider(
+  secret: Buffer | string,
+): SigningKeyProvider {
+  // The secret is handed to createHmac as given. Normalizing a string to a
+  // Buffer first was a no-op: createHmac encodes a string key as utf8, byte
+  // for byte what Buffer.from produces, so no input could tell the two
+  // apart. The equivalence is pinned by a test (#110).
+  const keyId = createHmac('sha256', secret).update(DOMAIN_KEYID).digest('hex');
+
+  return {
+    algorithm: 'HMAC-SHA256',
+    keyId,
+    async sign(data: Buffer): Promise<Buffer> {
+      return createHmac('sha256', secret).update(data).digest();
+    },
+  };
+}

package/src/subjectKeyStore.ts

@@ -0,0 +1,38 @@
+import { randomBytes } from 'node:crypto';
+import type { SubjectKeyStore } from './types.js';
+
+/**
+ * Reference {@link SubjectKeyStore}, backed by a `Map` in this process.
+ *
+ * NOT DURABLE, and not for production. The keys live only in this process's
+ * heap, so a restart erases every subject at once and a second proxy instance
+ * cannot decrypt what the first recorded. Both are silent failures: the chain
+ * still verifies, and the loss shows up only when someone tries to read a
+ * payload back.
+ *
+ * A real deployment needs a durable, access-controlled store — a KMS, an HSM,
+ * or an encrypted table whose read path is audited — because in erasable mode
+ * this store IS the confidentiality of every high-tier payload it holds a key
+ * for (ADR-0018).
+ */
+export function createInMemorySubjectKeyStore(): SubjectKeyStore {
+  const keys = new Map<string, Buffer>();
+
+  return {
+    async getOrCreate(subjectId: string): Promise<Buffer> {
+      const existing = keys.get(subjectId);
+      if (existing !== undefined) return existing;
+      // 256-bit, random rather than derived: a key recomputable from the
+      // signing secret could not be destroyed, which is the whole point.
+      const created = randomBytes(32);
+      keys.set(subjectId, created);
+      return created;
+    },
+    async destroy(subjectId: string) {
+      keys.delete(subjectId);
+      // Idempotent: an unknown subject still gets a tombstone, so a repeated
+      // erasure request produces evidence rather than an error.
+      return { destroyedAt: new Date().toISOString() };
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,287 @@
+import type {
+  Identity,
+  PromptMiddleware,
+  ProxyIdentity,
+  RejectionReason,
+  ToolMiddleware,
+} from 'mcpose';
+
+// ── Sensitivity ────────────────────────────────────────────────────────────────
+
+export type SensitivityTier = 'low' | 'medium' | 'high';
+
+export type SensitivityResolverFn = (
+  tool: string,
+  identity: Identity,
+  args: Record<string, unknown>,
+) => SensitivityTier;
+
+/**
+ * Override passed to `createSensitivityResolver`. Receives the static map's
+ * resolution as `mapTier` (already defaulted to `'high'` for unknown tools)
+ * so it can fall back: `(tool, id, args, mapTier) => mapTier`.
+ */
+export type SensitivityOverrideFn = (
+  tool: string,
+  identity: Identity,
+  args: Record<string, unknown>,
+  mapTier: SensitivityTier,
+) => SensitivityTier;
+
+// ── Signing ────────────────────────────────────────────────────────────────────
+
+export interface SigningKeyProvider {
+  sign(data: Buffer): Promise<Buffer>;
+  keyId: string;
+  algorithm: 'HMAC-SHA256';
+}
+
+// ── Cryptographic erasure ──────────────────────────────────────────────────────
+
+/** Evidence that a subject's key was destroyed, returned by `destroy`. */
+export interface SubjectKeyTombstone {
+  /** ISO timestamp of the destruction. */
+  destroyedAt: string;
+}
+
+/**
+ * Custody of the per-subject keys that make erasable mode erasable (ADR-0018).
+ *
+ * Supplying one to `AuditOptions.keyStore` switches the audit layer into
+ * erasable mode: per-event encryption keys and the keyed payload hashes then
+ * derive from the stored subject key rather than from the signing secret, so
+ * `destroy(subjectId)` makes that subject's recorded payloads permanently
+ * unreadable and unconfirmable. The chain and the manifest are untouched.
+ *
+ * These keys are private key material with the same handling rules as the
+ * signing secret: they must never be logged, exported, or written into an
+ * event, a manifest, or telemetry. An implementation that stores them in the
+ * clear voids the encryption guarantee for every subject in it.
+ */
+export interface SubjectKeyStore {
+  /**
+   * The subject's 256-bit key, created at random on first use. Called before
+   * every audited call in erasable mode, so it must not be memoized in a way
+   * that outlives `destroy`: a subject that calls again after erasure gets a
+   * fresh key, and the old events stay dead.
+   *
+   * A rejection fails the audited call (the pre-call failure stage) rather
+   * than letting it run unaudited.
+   */
+  getOrCreate(subjectId: string): Promise<Buffer>;
+  /**
+   * Permanently removes the subject's key and returns the tombstone that
+   * evidences the erasure. Idempotent: destroying an unknown subject still
+   * returns a tombstone, because "this subject holds no key" is the state the
+   * caller asked for either way.
+   */
+  destroy(subjectId: string): Promise<SubjectKeyTombstone>;
+}
+
+// ── Audit events ───────────────────────────────────────────────────────────────
+
+export interface AuditEventBase {
+  /** Equals the ProxyContext requestId. */
+  id: string;
+  /** ISO timestamp captured before the upstream call started. */
+  startedAt: string;
+  /** ISO timestamp captured after the upstream call settled. */
+  endedAt: string;
+  sessionId?: string;
+  identity: Identity;
+  delegatedFrom?: Identity[];
+  /**
+   * The proxy instance that recorded this event, from `ProxyContext.proxy`.
+   * Provenance, not a principal — never part of `delegatedFrom` (ADR-0012).
+   *
+   * Required, and covered by the chain unconditionally (ADR-0019). While it
+   * was omitted when absent, an event with no `proxy` and an event whose
+   * `proxy` was stripped produced the same preimage, so deleting recorded
+   * provenance was not chain-detectable.
+   */
+  proxy: ProxyIdentity;
+  /**
+   * Present ONLY on events recorded for a prompt call (`prompts/get`), where
+   * `tool` holds the prompt name. An absent `kind` means a tool call, so
+   * every event recorded before prompts were audited keeps its meaning and
+   * its chain preimage (additive within v2, ADR-0012 and ADR-0014).
+   */
+  kind?: 'prompt';
+  /**
+   * Present ONLY on events recorded in erasable mode, where the per-event
+   * encryption key and the keyed `inputHash`/`outputHash` derive from a
+   * destroyable subject key instead of the signing secret (ADR-0018).
+   *
+   * Optional and covered by the chain under the ADR-0012 omission rule,
+   * exactly as `kind` is: an absent marker means default mode with plain
+   * `sha256` hashes, so events recorded before erasable mode existed keep
+   * their preimage, and a stored event cannot be silently reinterpreted
+   * under the wrong hash scheme.
+   */
+  erasable?: true;
+  tool: string;
+  duration_ms: number;
+  outcome: 'success' | 'rejected' | 'error';
+  /** Present when outcome is 'rejected' (from the MCP error's data field). */
+  rejectionReason?: RejectionReason;
+  /**
+   * Present when outcome is 'error': what the upstream call threw, or a fixed
+   * message when the call failed without throwing -- `{ name: 'ToolError' }`
+   * for a tool result that carried `isError: true` in-band, and
+   * `{ name: 'InvalidToolResult' }` when the call resolved to a value that is
+   * not the shape its `kind` expects.
+   */
+  error?: { name: string; message: string };
+  inputHash: string;
+  outputHash: string;
+  chainHash: string;
+  replayManifestPosition: number;
+}
+
+export type LowAuditEvent = AuditEventBase & {
+  sensitivityTier: 'low';
+  inputRaw: Record<string, unknown>;
+  outputRaw: unknown;
+};
+
+export type MediumAuditEvent = AuditEventBase & {
+  sensitivityTier: 'medium';
+  inputRaw: Record<string, unknown>;
+  outputRaw: unknown;
+};
+
+export type HighAuditEvent = AuditEventBase & {
+  sensitivityTier: 'high';
+  inputEncrypted: string;
+  outputEncrypted: string;
+};
+
+export type AuditEvent = LowAuditEvent | MediumAuditEvent | HighAuditEvent;
+
+// ── Merkle + ReplayManifest ────────────────────────────────────────────────────
+
+export interface MerkleProof {
+  index: number;
+  siblings: string[];
+  directions: ('left' | 'right')[];
+}
+
+export interface ReplayManifest {
+  sessionId: string;
+  identity: Identity;
+  /**
+   * The proxy instance that produced this session's trail, captured when
+   * the session was first seen. Covered by the signature like every other
+   * field (ADR-0004, ADR-0012).
+   *
+   * Required, and included in the signing payload unconditionally
+   * (ADR-0019), so stripping it from a stored manifest fails the signature
+   * rather than rebuilding a payload that verifies.
+   */
+  proxy: ProxyIdentity;
+  startedAt: string;
+  closedAt: string;
+  eventCount: number;
+  merkleRoot: string;
+  merkleProofs: MerkleProof[];
+  signedBy: string;
+  /**
+   * HMAC over the canonical serialization of the ENTIRE manifest (every
+   * field above, domain-separated) — not just the Merkle root. Verify with
+   * `verifyManifestSignature`, which accepts only this exact lowercase hex
+   * string: a respelling (uppercase, an appended character) does not verify.
+   */
+  signature: string;
+}
+
+// ── Audit options + handle ─────────────────────────────────────────────────────
+
+export interface AuditOptions {
+  signingKey: SigningKeyProvider;
+  sensitivityResolver: SensitivityResolverFn;
+  /**
+   * Supply a store to run in ERASABLE mode (ADR-0018). Omit it and the audit
+   * layer behaves exactly as it always has, byte for byte: same preimages,
+   * same ciphertexts, same plain `sha256` payload hashes, no `erasable`
+   * marker on any event.
+   *
+   * With a store, the erasure unit is the data subject — the resolved
+   * `identity.sub` of each event, with anonymous events sharing the
+   * `anonymousIdentity()` bucket — and `destroy(sub)` renders that subject's
+   * recorded payloads permanently undecryptable and unconfirmable. Chain and
+   * manifest verification are unaffected, because payloads are bound to the
+   * chain only through their hashes.
+   *
+   * Key custody becomes your responsibility: see the README's erasable-mode
+   * section before choosing a store.
+   */
+  keyStore?: SubjectKeyStore;
+  onEvent: (event: AuditEvent) => void | Promise<void>;
+  /**
+   * Called with the finished ReplayManifest when the host calls closeSession().
+   *
+   * Why this exists: ToolMiddleware is a pure per-request function with no
+   * lifecycle hooks. Sessions are owned by the HTTP transport, not by
+   * middleware. There is no in-band way for middleware to observe session close.
+   * This callback gives consumers a push-based way to receive the manifest
+   * exactly when the host signals the session has ended — mirroring how audit
+   * substrates in financial systems work: the host controls the flush boundary;
+   * the audit layer reacts.
+   */
+  onManifest?: (manifest: ReplayManifest) => void | Promise<void>;
+  /**
+   * Record events for rejected calls (hidden tools etc.).
+   * @default true
+   */
+  includeRejections?: boolean;
+  /**
+   * How long `closeSession` waits for calls already admitted to the session
+   * to append and persist their events before it seals the manifest. Past
+   * the deadline the manifest covers what has landed, and each straggler is
+   * reported through `onAuditError` with its tool and requestId. `Infinity`
+   * waits without bound. Any other value (NaN, a negative number) is
+   * rejected at construction, because it would leave the drain with no
+   * deadline at all.
+   * @default 30_000
+   */
+  closeDrainTimeoutMs?: number;
+  /**
+   * Called when the audit layer itself fails (event serialization, a
+   * throwing onEvent sink). The audit layer NEVER throws into the tool-call
+   * path; failures are reported here instead. If this hook itself throws or
+   * returns a rejected promise, the failure is contained and never reaches
+   * the caller either.
+   * @default console.error
+   */
+  onAuditError?: (
+    err: unknown,
+    info: { tool: string; requestId: string; sessionId?: string },
+  ) => unknown;
+}
+
+export interface AuditMiddlewareHandle {
+  middleware: ToolMiddleware;
+  /**
+   * Audits `prompts/get` calls. Wire it into
+   * `ProxyOptions.promptMiddleware`; it shares the session chain with
+   * `middleware`, so tool and prompt events interleave in one trail.
+   * Prompt events carry `kind: 'prompt'` (ADR-0014).
+   */
+  promptMiddleware: PromptMiddleware;
+  /**
+   * Signal that a session has ended. Waits for every call already admitted
+   * to the session to append and persist its event, then computes the
+   * Merkle tree over all audit events for the session, signs the full
+   * manifest, fires onManifest, and returns the ReplayManifest. A call still
+   * inside its handler at teardown therefore lands in the manifest rather
+   * than orphaned at position 0. Concurrent calls for the same session share
+   * one close. Returns undefined if the session had no events or is unknown.
+   *
+   * A rejection from the signing provider or from onManifest is retryable:
+   * the sealed session is retained, and calling closeSession again with the
+   * same id resumes where it stopped. A retry signs the same payload and
+   * delivers the same manifest, never a second signed artifact. The state
+   * is released only once onManifest has settled successfully.
+   */
+  closeSession(sessionId: string): Promise<ReplayManifest | undefined>;
+}

package/src/verify.ts

@@ -0,0 +1,92 @@
+import { timingSafeEqual } from 'node:crypto';
+import type {
+  AuditEvent,
+  ReplayManifest,
+  SigningKeyProvider,
+} from './types.js';
+import { chainPreimageFields, computeChainHash } from './chain.js';
+import { manifestSigningPayload } from './middleware.js';
+
+const DOMAIN_CHAIN = Buffer.from('mcpose/v2/chain');
+
+export type ChainVerification =
+  { valid: true } | { valid: false; index: number; reason: string };
+
+/**
+ * Canonical hex: lowercase, even length, hex digits only, non-empty. This
+ * is what the producer writes (`digest('hex')`), and the exact string a
+ * third-party verifier compares.
+ */
+const CANONICAL_HEX = /^(?:[0-9a-f]{2})+$/;
+
+/**
+ * Compares a stored hex string against the recomputed value in constant
+ * time. The stored string must be canonical first: Node's hex decoder drops
+ * a trailing odd nibble and stops at the first non-hex character, so
+ * `sig + '0'`, `sig + 'z'` and `SIG` all decode to the stored bytes and would
+ * otherwise verify. The verifiers authenticate the stored string itself, not
+ * just its decoding, so two implementations agree on one artifact (#281).
+ */
+function hexEqual(storedHex: string, expectedHex: string): boolean {
+  if (!CANONICAL_HEX.test(storedHex)) return false;
+  const a = Buffer.from(storedHex, 'hex');
+  const b = Buffer.from(expectedHex, 'hex');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+/**
+ * KEYED chain verification: recomputes every event's chainHash from its
+ * preimage fields with the chain key derived through the signing oracle.
+ * Unlike the keyless `assertAuditChainIntegrity` in @mcpose/testing, this
+ * detects key-inconsistent forgeries — a rewritten event, a renumbered
+ * suffix, or a chain built under a different secret.
+ *
+ * An empty event list is invalid: truncation-to-zero must not verify.
+ */
+export async function verifyAuditChain(
+  events: readonly AuditEvent[],
+  signingKey: SigningKeyProvider,
+): Promise<ChainVerification> {
+  if (events.length === 0) {
+    return { valid: false, index: 0, reason: 'empty event list' };
+  }
+
+  const chainKey = await signingKey.sign(DOMAIN_CHAIN);
+  let prevChainHash = '';
+
+  for (const [i, event] of events.entries()) {
+    if (event.replayManifestPosition !== i) {
+      return {
+        valid: false,
+        index: i,
+        reason: `replayManifestPosition ${event.replayManifestPosition}, expected ${i}`,
+      };
+    }
+    const expected = computeChainHash(
+      chainPreimageFields(event),
+      prevChainHash,
+      chainKey,
+    );
+    if (!hexEqual(event.chainHash, expected)) {
+      return { valid: false, index: i, reason: 'chainHash mismatch' };
+    }
+    prevChainHash = event.chainHash;
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Recomputes the manifest's signature (which covers every manifest field,
+ * not just the Merkle root) and compares it in constant time.
+ */
+export async function verifyManifestSignature(
+  manifest: ReplayManifest,
+  signingKey: SigningKeyProvider,
+): Promise<boolean> {
+  const { signature, ...unsigned } = manifest;
+  const expected = await signingKey.sign(
+    Buffer.from(manifestSigningPayload(unsigned)),
+  );
+  return hexEqual(signature, expected.toString('hex'));
+}