@mcp-audit-gateway/core 0.1.0

package/src/attestation/audit-log.ts

@@ -0,0 +1,126 @@
+import { appendFile, stat, rename, open } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import type { AuditRecord } from "../types.js";
+import type { Signer } from "./signer.js";
+
+export function hashRecord(record: AuditRecord): string {
+  const json = JSON.stringify(record);
+  return createHash("sha256").update(json).digest("hex");
+}
+
+export class AuditLog {
+  private currentSize = 0;
+  private lastHash: string = "genesis";
+  private writeQueue: Promise<void> = Promise.resolve();
+
+  constructor(
+    private path: string,
+    private signer: Signer,
+    private rotateAfterBytes: number,
+  ) {}
+
+  async record(
+    method: string,
+    opts: {
+      toolName?: string;
+      namespace?: string;
+      upstream?: string;
+      principal?: string;
+      durationMs: number;
+      success: boolean;
+      errorCode?: number;
+    },
+  ): Promise<AuditRecord> {
+    return new Promise((resolve, reject) => {
+      this.writeQueue = this.writeQueue.then(async () => {
+        try {
+          const result = await this.writeRecord(method, opts);
+          resolve(result);
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+  }
+
+  private async writeRecord(
+    method: string,
+    opts: {
+      toolName?: string;
+      namespace?: string;
+      upstream?: string;
+      principal?: string;
+      durationMs: number;
+      success: boolean;
+      errorCode?: number;
+    },
+  ): Promise<AuditRecord> {
+    const record: AuditRecord = {
+      id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      method,
+      ...opts,
+      previousHash: this.lastHash,
+    };
+
+    record.attestation = await this.signer.sign(record);
+    const line = JSON.stringify(record) + "\n";
+
+    await appendFile(this.path, line);
+    this.currentSize += Buffer.byteLength(line);
+
+    this.lastHash = hashRecord(record);
+
+    if (this.currentSize >= this.rotateAfterBytes) {
+      await this.rotate();
+    }
+
+    return record;
+  }
+
+  private async rotate(): Promise<void> {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const rotatedPath = this.path.replace(/\.jsonl$/, `-${ts}.jsonl`);
+    try {
+      await rename(this.path, rotatedPath);
+      this.currentSize = 0;
+      this.lastHash = "genesis";
+    } catch {}
+  }
+
+  async init(): Promise<void> {
+    let s;
+    try {
+      s = await stat(this.path);
+    } catch {
+      this.currentSize = 0;
+      return;
+    }
+
+    this.currentSize = s.size;
+
+    if (s.size > 0) {
+      const tailSize = Math.min(s.size, 8192);
+      const fh = await open(this.path, "r");
+      try {
+        const buf = Buffer.alloc(tailSize);
+        await fh.read(buf, 0, tailSize, s.size - tailSize);
+        const tail = buf.toString("utf-8");
+        const lines = tail.trimEnd().split("\n");
+        for (let i = lines.length - 1; i >= 0; i--) {
+          try {
+            const record: AuditRecord = JSON.parse(lines[i]);
+            this.lastHash = hashRecord(record);
+            return;
+          } catch {
+            process.stderr.write(
+              `[audit-log] warning: corrupt record in tail, skipping\n`,
+            );
+          }
+        }
+      } finally {
+        await fh.close();
+      }
+    }
+  }
+}

package/src/attestation/bugfix.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { writeFile, unlink, readFile } from "node:fs/promises";
+import { HmacSigner } from "./signer.js";
+import { AuditLog, hashRecord } from "./audit-log.js";
+import { verifyAuditLog } from "./verify.js";
+import type { AuditRecord } from "../types.js";
+
+const TEST_LOG = "/tmp/bugfix-audit.jsonl";
+const SECRET = "d".repeat(64);
+
+describe("Bug fix: pipe injection in canonicalization", () => {
+  const signer = new HmacSigner(SECRET);
+
+  it("different records with pipe chars produce different signatures", async () => {
+    const record1: AuditRecord = {
+      id: "uuid-1",
+      timestamp: "2026-08-16T10:00:00Z",
+      method: "tools/call",
+      toolName: "db/read|admin",
+      namespace: "db",
+      upstream: "evil",
+      principal: "alice",
+      durationMs: 50,
+      success: true,
+    };
+
+    const record2: AuditRecord = {
+      id: "uuid-1",
+      timestamp: "2026-08-16T10:00:00Z",
+      method: "tools/call",
+      toolName: "db/read",
+      namespace: "admin",
+      upstream: "db",
+      principal: "evil|alice",
+      durationMs: 50,
+      success: true,
+    };
+
+    const sig1 = await signer.sign(record1);
+    const sig2 = await signer.sign(record2);
+    expect(sig1).not.toBe(sig2);
+  });
+});
+
+describe("Bug fix: hash chain survives restart", () => {
+  const signer = new HmacSigner(SECRET);
+
+  beforeEach(async () => { try { await unlink(TEST_LOG); } catch {} });
+  afterEach(async () => { try { await unlink(TEST_LOG); } catch {} });
+
+  it("restores lastHash from existing log on init", async () => {
+    const log1 = new AuditLog(TEST_LOG, signer, 100 * 1024 * 1024);
+    await log1.init();
+    await log1.record("tools/call", { toolName: "test/a", durationMs: 10, success: true });
+    await log1.record("tools/call", { toolName: "test/b", durationMs: 10, success: true });
+
+    const log2 = new AuditLog(TEST_LOG, signer, 100 * 1024 * 1024);
+    await log2.init();
+    await log2.record("tools/call", { toolName: "test/c", durationMs: 10, success: true });
+
+    const result = await verifyAuditLog(TEST_LOG, signer, { verifyChain: true });
+    expect(result.total).toBe(3);
+    expect(result.valid).toBe(3);
+    expect(result.invalid).toBe(0);
+  });
+});
+
+describe("Bug fix: concurrent writes maintain chain integrity", () => {
+  const signer = new HmacSigner(SECRET);
+
+  beforeEach(async () => { try { await unlink(TEST_LOG); } catch {} });
+  afterEach(async () => { try { await unlink(TEST_LOG); } catch {} });
+
+  it("serializes concurrent writes correctly", async () => {
+    const log = new AuditLog(TEST_LOG, signer, 100 * 1024 * 1024);
+    await log.init();
+
+    await log.record("tools/call", { toolName: "test/setup", durationMs: 10, success: true });
+
+    const concurrent = Array.from({ length: 10 }, (_, i) =>
+      log.record("tools/call", { toolName: `test/tool_${i}`, durationMs: i, success: true })
+    );
+    await Promise.all(concurrent);
+
+    const content = await readFile(TEST_LOG, "utf-8");
+    const records: AuditRecord[] = content.trimEnd().split("\n").map((l) => JSON.parse(l));
+    expect(records).toHaveLength(11);
+
+    const previousHashes = records.map((r) => r.previousHash);
+    const unique = new Set(previousHashes);
+    expect(unique.size).toBe(11);
+
+    for (let i = 1; i < records.length; i++) {
+      const expected = hashRecord(records[i - 1]);
+      expect(records[i].previousHash).toBe(expected);
+    }
+  });
+});
+
+describe("Bug fix: glob matcher prefix/suffix overlap", () => {
+  it("does not match when prefix and suffix overlap", async () => {
+    const { PolicyEngine } = await import("../policy/engine.js");
+    const engine = new PolicyEngine("allow", []);
+    const match = (engine as any).globMatch.bind(engine);
+
+    expect(match("ab*ab", "ab")).toBe(false);
+    expect(match("admin*admin", "admin")).toBe(false);
+    expect(match("ab*ab", "abab")).toBe(true);
+    expect(match("ab*ab", "abXab")).toBe(true);
+    expect(match("*/write_*", "fs/write_file")).toBe(true);
+    expect(match("agent:readonly-*", "agent:readonly-bot")).toBe(true);
+  });
+});

package/src/attestation/chain.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { unlink, readFile } from "node:fs/promises";
+import { HmacSigner } from "./signer.js";
+import { AuditLog, hashRecord } from "./audit-log.js";
+import { verifyChain } from "./verify.js";
+import type { AuditRecord } from "../types.js";
+
+const TEST_LOG = "/tmp/test-chain-audit.jsonl";
+const SECRET = "c".repeat(64);
+
+async function readRecords(path: string): Promise<AuditRecord[]> {
+  const content = await readFile(path, "utf-8");
+  return content
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line) => JSON.parse(line));
+}
+
+describe("hash chain integrity", () => {
+  const signer = new HmacSigner(SECRET);
+
+  beforeEach(async () => {
+    try {
+      await unlink(TEST_LOG);
+    } catch {}
+  });
+
+  afterEach(async () => {
+    try {
+      await unlink(TEST_LOG);
+    } catch {}
+  });
+
+  it("valid chain passes verification", async () => {
+    const log = new AuditLog(TEST_LOG, signer, 100 * 1024 * 1024);
+    await log.init();
+
+    await log.record("tools/call", {
+      toolName: "test/tool_a",
+      namespace: "test",
+      upstream: "test-server",
+      principal: "agent:bot",
+      durationMs: 100,
+      success: true,
+    });
+
+    await log.record("tools/call", {
+      toolName: "test/tool_b",
+      namespace: "test",
+      upstream: "test-server",
+      principal: "agent:bot",
+      durationMs: 50,
+      success: true,
+    });
+
+    await log.record("tools/call", {
+      toolName: "test/tool_c",
+      namespace: "test",
+      upstream: "test-server",
+      principal: "agent:bot",
+      durationMs: 75,
+      success: true,
+    });
+
+    const records = await readRecords(TEST_LOG);
+    const result = await verifyChain(records);
+
+    expect(result.valid).toBe(true);
+    expect(result.total).toBe(3);
+    expect(result.errors).toHaveLength(0);
+
+    // Verify first record has genesis
+    expect(records[0].previousHash).toBe("genesis");
+
+    // Verify second record references hash of first
+    expect(records[1].previousHash).toBe(hashRecord(records[0]));
+
+    // Verify third record references hash of second
+    expect(records[2].previousHash).toBe(hashRecord(records[1]));
+  });
+
+  it("detects deleted record", async () => {
+    const log = new AuditLog(TEST_LOG, signer, 100 * 1024 * 1024);
+    await log.init();
+
+    await log.record("tools/call", {
+      toolName: "test/tool_a",
+      durationMs: 100,
+      success: true,
+    });
+
+    await log.record("tools/call", {
+      toolName: "test/tool_b",
+      durationMs: 50,
+      success: true,
+    });
+
+    await log.record("tools/call", {
+      toolName: "test/tool_c",
+      durationMs: 75,
+      success: true,
+    });
+
+    const records = await readRecords(TEST_LOG);
+    // Remove the middle record
+    const tampered = [records[0], records[2]];
+
+    const result = await verifyChain(tampered);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors[0].reason).toBe(
+      "previousHash does not match hash of prior record",
+    );
+  });
+
+  it("detects reordered records", async () => {
+    const log = new AuditLog(TEST_LOG, signer, 100 * 1024 * 1024);
+    await log.init();
+
+    await log.record("tools/call", {
+      toolName: "test/tool_a",
+      durationMs: 100,
+      success: true,
+    });
+
+    await log.record("tools/call", {
+      toolName: "test/tool_b",
+      durationMs: 50,
+      success: true,
+    });
+
+    await log.record("tools/call", {
+      toolName: "test/tool_c",
+      durationMs: 75,
+      success: true,
+    });
+
+    const records = await readRecords(TEST_LOG);
+    // Swap the second and third records
+    const reordered = [records[0], records[2], records[1]];
+
+    const result = await verifyChain(reordered);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors[0].reason).toBe(
+      "previousHash does not match hash of prior record",
+    );
+  });
+
+  it("detects inserted record (previousHash won't match)", async () => {
+    const log = new AuditLog(TEST_LOG, signer, 100 * 1024 * 1024);
+    await log.init();
+
+    await log.record("tools/call", {
+      toolName: "test/tool_a",
+      durationMs: 100,
+      success: true,
+    });
+
+    await log.record("tools/call", {
+      toolName: "test/tool_b",
+      durationMs: 50,
+      success: true,
+    });
+
+    const records = await readRecords(TEST_LOG);
+
+    // Insert a fake record between the two
+    const inserted: AuditRecord = {
+      id: "fake-inserted-id",
+      timestamp: new Date().toISOString(),
+      method: "tools/call",
+      toolName: "test/malicious_tool",
+      durationMs: 1,
+      success: true,
+      previousHash: hashRecord(records[0]),
+    };
+
+    const tampered = [records[0], inserted, records[1]];
+
+    const result = await verifyChain(tampered);
+    expect(result.valid).toBe(false);
+    // The record after the inserted one will fail because its previousHash
+    // was computed against the original record[0], not the inserted record
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors.some((e) => e.reason === "previousHash does not match hash of prior record")).toBe(true);
+  });
+});

package/src/attestation/keygen.ts

@@ -0,0 +1,18 @@
+import { writeFile } from "node:fs/promises";
+
+export async function generateKeyPair(outputDir: string): Promise<{
+  publicKeyPath: string;
+  privateKeyPath: string;
+}> {
+  const ed = await import("@noble/ed25519");
+  const privateKey = ed.utils.randomPrivateKey();
+  const publicKey = await ed.getPublicKeyAsync(privateKey);
+
+  const privateKeyPath = `${outputDir}/gateway.key`;
+  const publicKeyPath = `${outputDir}/gateway.pub`;
+
+  await writeFile(privateKeyPath, Buffer.from(privateKey), { mode: 0o600 });
+  await writeFile(publicKeyPath, Buffer.from(publicKey), { mode: 0o644 });
+
+  return { publicKeyPath, privateKeyPath };
+}

package/src/attestation/signer.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import { HmacSigner, Ed25519Signer } from "./signer.js";
+import type { AuditRecord } from "../types.js";
+
+const mockRecord: AuditRecord = {
+  id: "test-uuid-001",
+  timestamp: "2026-08-16T10:00:00.000Z",
+  method: "tools/call",
+  toolName: "github/create_pr",
+  namespace: "github",
+  upstream: "github-server",
+  principal: "agent:dev-bot",
+  durationMs: 234,
+  success: true,
+};
+
+describe("HmacSigner", () => {
+  const secret = "a".repeat(64);
+  const signer = new HmacSigner(secret);
+
+  it("produces a hex signature", async () => {
+    const sig = await signer.sign(mockRecord);
+    expect(sig).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("verifies a valid signature", async () => {
+    const sig = await signer.sign(mockRecord);
+    const valid = await signer.verify(mockRecord, sig);
+    expect(valid).toBe(true);
+  });
+
+  it("rejects a tampered record", async () => {
+    const sig = await signer.sign(mockRecord);
+    const tampered = { ...mockRecord, durationMs: 999 };
+    const valid = await signer.verify(tampered, sig);
+    expect(valid).toBe(false);
+  });
+
+  it("rejects a wrong signature", async () => {
+    const valid = await signer.verify(mockRecord, "bad".repeat(21) + "b");
+    expect(valid).toBe(false);
+  });
+});
+
+describe("Ed25519Signer", () => {
+  it("signs and verifies a record", async () => {
+    const signer = new Ed25519Signer();
+    await signer.init();
+
+    const sig = await signer.sign(mockRecord);
+    expect(sig.length).toBeGreaterThan(100);
+
+    const valid = await signer.verify(mockRecord, sig);
+    expect(valid).toBe(true);
+  });
+
+  it("rejects a tampered record", async () => {
+    const signer = new Ed25519Signer();
+    await signer.init();
+
+    const sig = await signer.sign(mockRecord);
+    const tampered = { ...mockRecord, success: false };
+    const valid = await signer.verify(tampered, sig);
+    expect(valid).toBe(false);
+  });
+
+  it("exposes the public key for external verification", async () => {
+    const signer = new Ed25519Signer();
+    await signer.init();
+
+    const pubKey = signer.getPublicKey();
+    expect(pubKey).not.toBeNull();
+    expect(pubKey!.length).toBe(32);
+  });
+});

package/src/attestation/signer.ts

@@ -0,0 +1,105 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import type { AttestationConfig, AuditRecord } from "../types.js";
+
+export interface Signer {
+  sign(record: AuditRecord): Promise<string>;
+  verify(record: AuditRecord, signature: string): Promise<boolean>;
+}
+
+export class HmacSigner implements Signer {
+  private secret: Buffer;
+
+  constructor(secret: string) {
+    this.secret = Buffer.from(secret, "hex");
+  }
+
+  async sign(record: AuditRecord): Promise<string> {
+    const payload = this.canonicalize(record);
+    const hmac = createHmac("sha256", this.secret);
+    hmac.update(payload);
+    return hmac.digest("hex");
+  }
+
+  async verify(record: AuditRecord, signature: string): Promise<boolean> {
+    const expected = await this.sign(record);
+    const expectedBuf = Buffer.from(expected, "hex");
+    const signatureBuf = Buffer.from(signature, "hex");
+    if (expectedBuf.length !== signatureBuf.length) return false;
+    return timingSafeEqual(expectedBuf, signatureBuf);
+  }
+
+  private canonicalize(record: AuditRecord): string {
+    return canonicalizeRecord(record);
+  }
+}
+
+export class Ed25519Signer implements Signer {
+  private privateKey: Uint8Array | null = null;
+  private publicKey: Uint8Array | null = null;
+
+  constructor(private keyPath?: string) {}
+
+  async init(): Promise<void> {
+    const ed = await import("@noble/ed25519");
+    if (this.keyPath) {
+      const { readFile } = await import("node:fs/promises");
+      const keyData = await readFile(this.keyPath);
+      this.privateKey = new Uint8Array(keyData);
+    } else {
+      this.privateKey = ed.utils.randomPrivateKey();
+    }
+    this.publicKey = await ed.getPublicKeyAsync(this.privateKey);
+  }
+
+  async sign(record: AuditRecord): Promise<string> {
+    if (!this.privateKey) await this.init();
+    const ed = await import("@noble/ed25519");
+    const payload = new TextEncoder().encode(this.canonicalize(record));
+    const sig = await ed.signAsync(payload, this.privateKey!);
+    return Buffer.from(sig).toString("hex");
+  }
+
+  async verify(record: AuditRecord, signature: string): Promise<boolean> {
+    if (!this.publicKey) await this.init();
+    const ed = await import("@noble/ed25519");
+    const payload = new TextEncoder().encode(this.canonicalize(record));
+    const sig = Buffer.from(signature, "hex");
+    return ed.verifyAsync(sig, payload, this.publicKey!);
+  }
+
+  getPublicKey(): Uint8Array | null {
+    return this.publicKey;
+  }
+
+  private canonicalize(record: AuditRecord): string {
+    return canonicalizeRecord(record);
+  }
+}
+
+function canonicalizeRecord(record: AuditRecord): string {
+  const ordered: [string, string | number | boolean | null][] = [
+    ["id", record.id],
+    ["timestamp", record.timestamp],
+    ["method", record.method],
+    ["toolName", record.toolName ?? null],
+    ["namespace", record.namespace ?? null],
+    ["upstream", record.upstream ?? null],
+    ["principal", record.principal ?? null],
+    ["durationMs", record.durationMs],
+    ["success", record.success],
+    ["errorCode", record.errorCode ?? null],
+    ["previousHash", record.previousHash ?? null],
+  ];
+  return JSON.stringify(ordered);
+}
+
+export function createSigner(config: AttestationConfig): Signer {
+  if (!config.enabled) {
+    return { sign: async () => "", verify: async () => true };
+  }
+  if (config.algorithm === "hmac-sha256") {
+    const secret = config.secret ?? randomBytes(32).toString("hex");
+    return new HmacSigner(secret);
+  }
+  return new Ed25519Signer(config.keyPath);
+}