@mcpose/audit 2.0.2 → 3.0.0

package/src/__tests__/sensitivity.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { createSensitivityResolver } from '../sensitivity.js';
+import type { Identity } from 'mcpose';
+
+const identity: Identity = {
+  sub: 'u1',
+  type: 'human',
+  roles: [],
+  claims: {},
+  resolvedAt: new Date().toISOString(),
+  source: 'jwt',
+};
+
+describe('createSensitivityResolver', () => {
+  it('returns the mapped tier for a known tool', () => {
+    const resolve = createSensitivityResolver({
+      transfer_funds: 'high',
+      get_balance: 'low',
+    });
+    expect(resolve('transfer_funds', identity, {})).toBe('high');
+    expect(resolve('get_balance', identity, {})).toBe('low');
+  });
+
+  it('returns high for an unknown tool', () => {
+    const resolve = createSensitivityResolver({ get_balance: 'low' });
+    expect(resolve('unknown_tool', identity, {})).toBe('high');
+  });
+
+  it('override fn takes precedence over the static map', () => {
+    const resolve = createSensitivityResolver(
+      { get_balance: 'low' },
+      (_tool, _identity, args) => (args.pii ? 'high' : 'low'),
+    );
+    expect(resolve('get_balance', identity, { pii: true })).toBe('high');
+    expect(resolve('get_balance', identity, {})).toBe('low');
+  });
+
+  it('override receives the map tier and can fall back to it', () => {
+    const resolve = createSensitivityResolver(
+      { get_balance: 'medium' },
+      (_tool, _identity, _args, mapTier) => mapTier,
+    );
+    expect(resolve('get_balance', identity, {})).toBe('medium');
+    // Unknown tool: mapTier is already defaulted to high.
+    expect(resolve('unknown_tool', identity, {})).toBe('high');
+  });
+
+  it('resolves prototype-inherited tool names to high (attacker-controlled names)', () => {
+    const resolve = createSensitivityResolver({ get_balance: 'low' });
+    // These exist on Object.prototype — a naive map lookup returns a
+    // truthy Function, bypassing the unknown⇒high default.
+    for (const tool of [
+      'toString',
+      'constructor',
+      'valueOf',
+      'hasOwnProperty',
+      '__proto__',
+    ]) {
+      expect(resolve(tool, identity, {})).toBe('high');
+    }
+  });
+
+  it('treats a garbage tier from the map or override as high (fail closed)', () => {
+    const badMap = createSensitivityResolver({
+      typo_tool: 'pubic' as never,
+    });
+    expect(badMap('typo_tool', identity, {})).toBe('high');
+
+    const badOverride = createSensitivityResolver({}, () => undefined as never);
+    expect(badOverride('anything', identity, {})).toBe('high');
+  });
+});

package/src/__tests__/signingKey.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { createHash, createHmac } from 'node:crypto';
+import { createDefaultSigningKeyProvider } from '../signingKey.js';
+
+describe('createDefaultSigningKeyProvider', () => {
+  it('has correct shape', () => {
+    const provider = createDefaultSigningKeyProvider('secret');
+    expect(provider.algorithm).toBe('HMAC-SHA256');
+    expect(typeof provider.keyId).toBe('string');
+    expect(provider.keyId.length).toBeGreaterThan(0);
+    expect(typeof provider.sign).toBe('function');
+  });
+
+  it('derives keyId as HMAC(secret, mcpose/v2/keyid), never bare SHA256(secret)', () => {
+    // v1 published SHA256(secret) as keyId, enabling offline brute-force of
+    // low-entropy secrets from any manifest. Pin the v2 formula and the label.
+    const provider = createDefaultSigningKeyProvider('secret');
+    expect(provider.keyId).toBe(
+      createHmac('sha256', Buffer.from('secret'))
+        .update('mcpose/v2/keyid')
+        .digest('hex'),
+    );
+    expect(provider.keyId).not.toBe(
+      createHash('sha256').update('secret').digest('hex'),
+    );
+  });
+
+  it('sign returns a non-empty buffer', async () => {
+    const provider = createDefaultSigningKeyProvider('secret');
+    const sig = await provider.sign(Buffer.from('hello'));
+    expect(sig).toBeInstanceOf(Buffer);
+    expect(sig.length).toBeGreaterThan(0);
+  });
+
+  it('same secret + same data → same signature (deterministic)', async () => {
+    const p1 = createDefaultSigningKeyProvider('secret');
+    const p2 = createDefaultSigningKeyProvider('secret');
+    const data = Buffer.from('test-data');
+    const [s1, s2] = await Promise.all([p1.sign(data), p2.sign(data)]);
+    expect(s1.toString('hex')).toBe(s2.toString('hex'));
+  });
+
+  it('different secrets → different signatures', async () => {
+    const p1 = createDefaultSigningKeyProvider('secret-a');
+    const p2 = createDefaultSigningKeyProvider('secret-b');
+    const data = Buffer.from('test-data');
+    const [s1, s2] = await Promise.all([p1.sign(data), p2.sign(data)]);
+    expect(s1.toString('hex')).not.toBe(s2.toString('hex'));
+  });
+
+  it('accepts a Buffer secret and keys it identically to its utf8 string form', async () => {
+    // Pins why the provider hands the secret to createHmac as given rather
+    // than normalizing a string to a Buffer first: createHmac encodes a
+    // string key as utf8 itself, so the conversion was unobservable and its
+    // mutants unkillable (#110). A non-ASCII secret makes the encoding
+    // load-bearing rather than incidental.
+    const text = 'sécret';
+    const fromString = createDefaultSigningKeyProvider(text);
+    const fromBuffer = createDefaultSigningKeyProvider(Buffer.from(text));
+
+    expect(fromBuffer.keyId).toBe(fromString.keyId);
+    expect(fromBuffer.keyId).toBe(
+      createHmac('sha256', Buffer.from(text, 'utf8'))
+        .update('mcpose/v2/keyid')
+        .digest('hex'),
+    );
+
+    const data = Buffer.from('data');
+    const [fromBufferSig, fromStringSig] = await Promise.all([
+      fromBuffer.sign(data),
+      fromString.sign(data),
+    ]);
+    expect(fromBufferSig).toBeInstanceOf(Buffer);
+    expect(fromBufferSig.toString('hex')).toBe(fromStringSig.toString('hex'));
+  });
+});

package/src/chain.ts

@@ -0,0 +1,317 @@
+import { createHash, createHmac } from 'node:crypto';
+import type { AuditEvent, MerkleProof } from './types.js';
+
+// ── Canonical serialization ────────────────────────────────────────────────────
+//
+// v1 hashed `JSON.stringify` output, which made object-key insertion order
+// load-bearing: an independently written verifier that reconstructed the
+// fields in a different order failed on every chainHash. v2 hashes a
+// canonical form instead — lexicographically sorted keys at every depth —
+// so only the field SET matters. See ADR-0004.
+
+/**
+ * Canonical JSON: object keys sorted lexicographically at every depth,
+ * `undefined`-valued keys skipped. Throws on values with no canonical JSON
+ * form (BigInt, function, symbol, circular references).
+ *
+ * Use for data the audit layer controls (chain preimages, manifest
+ * payloads). For arbitrary caller payloads use {@link stableStringify}.
+ */
+export function canonicalJson(value: unknown): string {
+  return serialize(value, new Set(), { strict: true });
+}
+
+/**
+ * Total variant of {@link canonicalJson} for arbitrary caller payloads:
+ * never throws. Circular references become `"[Circular]"`, BigInt becomes
+ * its decimal string. Used for `inputHash`/`outputHash`, so two
+ * semantically identical payloads hash identically regardless of the
+ * client's JSON key order.
+ */
+export function stableStringify(value: unknown): string {
+  return serialize(value, new Set(), { strict: false });
+}
+
+function serialize(
+  value: unknown,
+  seen: Set<object>,
+  opts: { strict: boolean },
+): string {
+  if (value === null || value === undefined) return 'null';
+
+  switch (typeof value) {
+    case 'string':
+    case 'number':
+    case 'boolean':
+      return JSON.stringify(value);
+    case 'bigint':
+      if (opts.strict) {
+        throw new TypeError('canonicalJson: BigInt has no canonical JSON form');
+      }
+      return JSON.stringify(value.toString());
+    case 'function':
+    case 'symbol':
+      if (opts.strict) {
+        throw new TypeError(
+          `canonicalJson: ${typeof value} has no canonical JSON form`,
+        );
+      }
+      return 'null';
+  }
+
+  const obj = value;
+  if (seen.has(obj)) {
+    if (opts.strict) {
+      throw new TypeError('canonicalJson: circular reference');
+    }
+    return '"[Circular]"';
+  }
+  seen.add(obj);
+  try {
+    if (Array.isArray(obj)) {
+      return `[${obj.map((item) => serialize(item, seen, opts)).join(',')}]`;
+    }
+    if (typeof (obj as { toJSON?: unknown }).toJSON === 'function') {
+      return serialize((obj as { toJSON: () => unknown }).toJSON(), seen, opts);
+    }
+    const entries = Object.entries(obj)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => `${JSON.stringify(k)}:${serialize(v, seen, opts)}`);
+    return `{${entries.join(',')}}`;
+  } finally {
+    seen.delete(obj);
+  }
+}
+
+// ── Hash primitives ────────────────────────────────────────────────────────────
+
+export function sha256hex(data: string | Buffer): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+function hmacSha256hex(data: string | Buffer, key: Buffer): string {
+  return createHmac('sha256', key).update(data).digest('hex');
+}
+
+// ── HMAC chain ─────────────────────────────────────────────────────────────────
+
+const DOMAIN_CHAIN_HASH = 'mcpose/v2/chain';
+
+/**
+ * The exact fields of an audit event that the chain covers, extracted from
+ * the event. Used by both the producer (middleware) and any verifier
+ * ({@link verifyAuditChain}) so the two cannot drift.
+ *
+ * NOT covered (bound only via inputHash/outputHash): the raw/encrypted
+ * payloads.
+ */
+export function chainPreimageFields(
+  event: Omit<AuditEvent, 'chainHash'> | AuditEvent,
+): Record<string, unknown> {
+  return {
+    id: event.id,
+    startedAt: event.startedAt,
+    endedAt: event.endedAt,
+    ...(event.sessionId === undefined ? {} : { sessionId: event.sessionId }),
+    ...(event.delegatedFrom === undefined
+      ? {}
+      : { delegatedFrom: event.delegatedFrom }),
+    // Required on every event, so it is a plain always-present field rather
+    // than an omission-guarded optional one (ADR-0019). Under the omission
+    // pattern an event with no proxy and one whose proxy was stripped hashed
+    // identically, so removing recorded provenance was undetectable.
+    proxy: event.proxy,
+    ...(event.kind === undefined ? {} : { kind: event.kind }),
+    // Optional, omitted when absent (ADR-0012), so a default-mode event keeps
+    // the preimage it had before erasable mode existed. Covering it is what
+    // stops a stored event being reinterpreted under the other hash scheme:
+    // adding or stripping the marker breaks verification at that index
+    // (ADR-0018).
+    ...(event.erasable === undefined ? {} : { erasable: event.erasable }),
+    identity: event.identity,
+    tool: event.tool,
+    duration_ms: event.duration_ms,
+    outcome: event.outcome,
+    // Required on every event, so it is a plain always-present field rather
+    // than an omission-guarded optional one (ADR-0015).
+    sensitivityTier: event.sensitivityTier,
+    ...(event.rejectionReason === undefined
+      ? {}
+      : { rejectionReason: event.rejectionReason }),
+    ...(event.error === undefined ? {} : { error: event.error }),
+    inputHash: event.inputHash,
+    outputHash: event.outputHash,
+    replayManifestPosition: event.replayManifestPosition,
+  };
+}
+
+/**
+ * `HMAC-SHA256(chainKey, canonicalJson({domain, prevChainHash, event}))`.
+ * Domain-separated and canonically framed: neither field order nor
+ * string-concatenation ambiguity can affect the hash. The entry is
+ * serialized without its own chainHash. First entry uses `prevChainHash: ''`.
+ */
+export function computeChainHash(
+  entryWithoutChainHash: Record<string, unknown>,
+  prevChainHash: string,
+  chainKey: Buffer,
+): string {
+  const preimage = canonicalJson({
+    domain: DOMAIN_CHAIN_HASH,
+    prevChainHash,
+    event: entryWithoutChainHash,
+  });
+  return hmacSha256hex(preimage, chainKey);
+}
+
+// ── Merkle tree ────────────────────────────────────────────────────────────────
+//
+// Leaves and internal nodes are domain-separated so an internal node can
+// never be replayed as a leaf (second-preimage hardening). Odd layers
+// duplicate the last node; ambiguity from that padding is neutralized by
+// the signed `eventCount` in the manifest payload.
+
+const LEAF_TAG = 'mcpose/v2/leaf\0';
+const NODE_TAG = 'mcpose/v2/node\0';
+
+function leafHash(chainHash: string): string {
+  return sha256hex(LEAF_TAG + chainHash);
+}
+
+function nodeHash(left: string, right: string): string {
+  return sha256hex(NODE_TAG + left + right);
+}
+
+function nextLayer(layer: string[]): string[] {
+  const next: string[] = [];
+  for (let i = 0; i < layer.length; i += 2) {
+    // `i < layer.length` guarantees `left`; a missing right sibling means an
+    // odd layer, whose last node is duplicated (ADR-0004) — same padding as
+    // `computeMerkleProof` and `computeMerkleRootAndProofs`.
+    const left = layer[i]!;
+    const right = layer[i + 1] ?? left;
+    next.push(nodeHash(left, right));
+  }
+  return next;
+}
+
+/** Merkle root over the events' `chainHash` values. Empty → `sha256('')`. */
+export function computeMerkleRoot(hashes: string[]): string {
+  if (hashes.length === 0) return sha256hex('');
+  let layer = hashes.map(leafHash);
+  while (layer.length > 1) {
+    layer = nextLayer(layer);
+  }
+  // `hashes` is non-empty here and the loop exits only at length 1.
+  return layer[0]!;
+}
+
+export function computeMerkleProof(
+  hashes: string[],
+  index: number,
+): MerkleProof {
+  if (!Number.isInteger(index) || index < 0 || index >= hashes.length) {
+    throw new RangeError(
+      `computeMerkleProof: index ${index} out of range for ${hashes.length} leaves`,
+    );
+  }
+
+  const siblings: string[] = [];
+  const directions: ('left' | 'right')[] = [];
+
+  let layer = hashes.map(leafHash);
+  let idx = index;
+
+  while (layer.length > 1) {
+    const siblingIdx = idx % 2 === 0 ? idx + 1 : idx - 1;
+    // A sibling past the end means an odd layer whose last node is
+    // duplicated, and `idx` is then that last node — same padding as
+    // `nextLayer`, which must stay identical. `idx` is always in range.
+    siblings.push(layer[siblingIdx] ?? layer[idx]!);
+    directions.push(idx % 2 === 0 ? 'right' : 'left');
+    layer = nextLayer(layer);
+    idx = Math.floor(idx / 2);
+  }
+
+  return { index, siblings, directions };
+}
+
+function proofFromLayers(index: number, layers: string[][]): MerkleProof {
+  const siblings: string[] = [];
+  const directions: ('left' | 'right')[] = [];
+  let idx = index;
+
+  for (let level = 0; level < layers.length - 1; level++) {
+    const layer = layers[level]!;
+    const siblingIdx = idx % 2 === 0 ? idx + 1 : idx - 1;
+    siblings.push(layer[siblingIdx] ?? layer[idx]!);
+    directions.push(idx % 2 === 0 ? 'right' : 'left');
+    idx = Math.floor(idx / 2);
+  }
+
+  return { index, siblings, directions };
+}
+
+/** Build a manifest root and every proof from the same set of tree layers. */
+export function computeMerkleRootAndProofs(hashes: string[]): {
+  merkleRoot: string;
+  merkleProofs: MerkleProof[];
+} {
+  if (hashes.length === 0) {
+    return { merkleRoot: sha256hex(''), merkleProofs: [] };
+  }
+
+  const layers = [hashes.map(leafHash)];
+  while (layers[layers.length - 1]!.length > 1) {
+    layers.push(nextLayer(layers[layers.length - 1]!));
+  }
+
+  return {
+    merkleRoot: layers[layers.length - 1]![0]!,
+    merkleProofs: hashes.map((_, index) => proofFromLayers(index, layers)),
+  };
+}
+
+/**
+ * Verifies a Merkle proof for an event's `chainHash` (the raw chain hash —
+ * the leaf tag is applied internally).
+ *
+ * Rejects malformed proofs: `siblings`/`directions` length mismatch,
+ * directions inconsistent with `proof.index` (each level's direction is
+ * fully determined by the index), or an index that the path cannot
+ * represent (`index >= 2 ** siblings.length`, which leaves high bits
+ * unconsumed after traversal).
+ */
+export function verifyMerkleProof(
+  leafChainHash: string,
+  proof: MerkleProof,
+  root: string,
+): boolean {
+  if (
+    !Number.isSafeInteger(proof.index) ||
+    proof.index < 0 ||
+    proof.siblings.length !== proof.directions.length
+  ) {
+    return false;
+  }
+
+  let current = leafHash(leafChainHash);
+  let idx = proof.index;
+  for (let i = 0; i < proof.siblings.length; i++) {
+    const expectedDir = idx % 2 === 0 ? 'right' : 'left';
+    if (proof.directions[i] !== expectedDir) return false;
+    const sibling = proof.siblings[i];
+    // A hole in a caller-supplied `siblings` array is a malformed proof.
+    if (sibling === undefined) return false;
+    current =
+      expectedDir === 'right'
+        ? nodeHash(current, sibling)
+        : nodeHash(sibling, current);
+    idx = Math.floor(idx / 2);
+  }
+  // Bits left over mean the claimed position lies outside a tree of this
+  // depth: a two-leaf proof for position 0 must not also verify at 2 or 4.
+  if (idx !== 0) return false;
+  return current === root;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export type {
+  SensitivityTier,
+  SensitivityResolverFn,
+  SensitivityOverrideFn,
+  SigningKeyProvider,
+  SubjectKeyStore,
+  SubjectKeyTombstone,
+  AuditEventBase,
+  LowAuditEvent,
+  MediumAuditEvent,
+  HighAuditEvent,
+  AuditEvent,
+  MerkleProof,
+  ReplayManifest,
+  AuditOptions,
+  AuditMiddlewareHandle,
+} from './types.js';
+
+export { createSensitivityResolver } from './sensitivity.js';
+export { createDefaultSigningKeyProvider } from './signingKey.js';
+export { createInMemorySubjectKeyStore } from './subjectKeyStore.js';
+export { createAuditMiddleware } from './middleware.js';
+export {
+  computeMerkleRoot,
+  computeMerkleProof,
+  verifyMerkleProof,
+  canonicalJson,
+  stableStringify,
+} from './chain.js';
+export type { ChainVerification } from './verify.js';
+export { verifyAuditChain, verifyManifestSignature } from './verify.js';