@mikeargento/bitgraph 1.1.0

package/src/__tests__/constructor.test.ts

@@ -0,0 +1,340 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+import { describe, test } from "node:test";
+import * as assert from "node:assert/strict";
+import { getPublicKeyAsync, signAsync } from "@noble/ed25519";
+import { Constructor } from "../constructor.js";
+import type { HostCapabilities } from "../host.js";
+
+// ---------------------------------------------------------------------------
+// Test helper: build a mock host backed by a real Ed25519 key pair
+// ---------------------------------------------------------------------------
+
+interface KeyMaterial {
+  privateKey: Uint8Array;
+  publicKeyBytes: Uint8Array;
+  publicKeyB64: string;
+}
+
+async function makeKeys(): Promise<KeyMaterial> {
+  const privateKey = crypto.getRandomValues(new Uint8Array(32));
+  const publicKeyBytes = await getPublicKeyAsync(privateKey);
+  const publicKeyB64 = Buffer.from(publicKeyBytes).toString("base64");
+  return { privateKey, publicKeyBytes, publicKeyB64 };
+}
+
+/** Minimal stub host — all required capabilities, no optional ones. */
+function baseHost(km: KeyMaterial): HostCapabilities {
+  return {
+    enforcementTier: "stub" as const,
+    getMeasurement: async () => "test-measurement-cafebabe",
+    getFreshNonce: async () => crypto.getRandomValues(new Uint8Array(16)),
+    sign: async (data: Uint8Array) => signAsync(data, km.privateKey),
+    getPublicKey: async () => km.publicKeyBytes,
+  };
+}
+
+/** Stub host that also exposes a monotonic counter. */
+function hostWithCounter(km: KeyMaterial): HostCapabilities {
+  let c = 0;
+  return {
+    enforcementTier: "stub" as const,
+    getMeasurement: async () => "test-measurement-cafebabe",
+    getFreshNonce: async () => crypto.getRandomValues(new Uint8Array(16)),
+    sign: async (data: Uint8Array) => signAsync(data, km.privateKey),
+    getPublicKey: async () => km.publicKeyBytes,
+    nextCounter: async () => String(++c),
+  };
+}
+
+/** Stub host that also exposes a secure clock. */
+function hostWithTime(km: KeyMaterial, timeMs: number): HostCapabilities {
+  return {
+    enforcementTier: "stub" as const,
+    getMeasurement: async () => "test-measurement-cafebabe",
+    getFreshNonce: async () => crypto.getRandomValues(new Uint8Array(16)),
+    sign: async (data: Uint8Array) => signAsync(data, km.privateKey),
+    getPublicKey: async () => km.publicKeyBytes,
+    secureTime: async () => timeMs,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Constructor.initialize
+// ---------------------------------------------------------------------------
+
+describe("Constructor.initialize", () => {
+  test("succeeds with a minimal host", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    assert.ok(ctor instanceof Constructor);
+  });
+
+  test("fails when getMeasurement() rejects", async () => {
+    const km = await makeKeys();
+    const host: HostCapabilities = {
+      ...baseHost(km),
+      getMeasurement: async () => { throw new Error("measurement unavailable"); },
+    };
+    await assert.rejects(
+      Constructor.initialize({ host }),
+      /preflight failed/,
+    );
+  });
+
+  test("fails when getPublicKey() rejects", async () => {
+    const km = await makeKeys();
+    const host: HostCapabilities = {
+      ...baseHost(km),
+      getPublicKey: async () => { throw new Error("key unavailable"); },
+    };
+    await assert.rejects(
+      Constructor.initialize({ host }),
+      /preflight failed/,
+    );
+  });
+
+  test("rejects requireCounter policy when host has no nextCounter", async () => {
+    const km = await makeKeys();
+    await assert.rejects(
+      Constructor.initialize({ host: baseHost(km), policy: { requireCounter: true } }),
+      /nextCounter/,
+    );
+  });
+
+  test("rejects requireTime policy when host has no secureTime", async () => {
+    const km = await makeKeys();
+    await assert.rejects(
+      Constructor.initialize({ host: baseHost(km), policy: { requireTime: true } }),
+      /secureTime/,
+    );
+  });
+
+  test("accepts requireCounter policy when host has nextCounter", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({
+      host: hostWithCounter(km),
+      policy: { requireCounter: true },
+    });
+    assert.ok(ctor instanceof Constructor);
+  });
+
+  test("accepts requireTime policy when host has secureTime", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({
+      host: hostWithTime(km, Date.now()),
+      policy: { requireTime: true },
+    });
+    assert.ok(ctor instanceof Constructor);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Constructor.commit
+// ---------------------------------------------------------------------------
+
+describe("Constructor.commit", () => {
+  test("returns a structurally valid BitGraphProof", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const bytes = new TextEncoder().encode("hello bitgraph");
+    const proof = await ctor.commit({ bytes });
+
+    assert.equal(proof.version, "bitgraph/1");
+    assert.equal(proof.artifact.hashAlg, "sha256");
+    assert.ok(typeof proof.artifact.digestB64 === "string" && proof.artifact.digestB64.length > 0);
+    assert.ok(typeof proof.commit.nonceB64 === "string" && proof.commit.nonceB64.length > 0);
+    assert.equal(proof.signer.publicKeyB64, km.publicKeyB64);
+    assert.ok(typeof proof.signer.signatureB64 === "string" && proof.signer.signatureB64.length > 0);
+    assert.equal(proof.environment.enforcement, "stub");
+    assert.equal(proof.environment.measurement, "test-measurement-cafebabe");
+  });
+
+  test("works with empty bytes", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const proof = await ctor.commit({ bytes: new Uint8Array(0) });
+    assert.equal(proof.version, "bitgraph/1");
+    assert.ok(proof.artifact.digestB64.length > 0);
+  });
+
+  test("works with large bytes (100 KB)", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    // crypto.getRandomValues is limited to 65536 bytes; use fill instead
+    const bytes = new Uint8Array(100_000).fill(0xab);
+    const proof = await ctor.commit({ bytes });
+    assert.equal(proof.version, "bitgraph/1");
+  });
+
+  test("includes metadata when provided (outside signature)", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const proof = await ctor.commit({
+      bytes: new Uint8Array([1, 2, 3]),
+      metadata: { source: "test-suite" },
+    });
+    assert.deepEqual(proof.metadata, { source: "test-suite" });
+  });
+
+  test("omits metadata field when not provided", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const proof = await ctor.commit({ bytes: new Uint8Array([1]) });
+    assert.equal(proof.metadata, undefined);
+  });
+
+  test("includes counter when host provides nextCounter", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: hostWithCounter(km) });
+    const proof = await ctor.commit({ bytes: new Uint8Array([1]) });
+    assert.ok(typeof proof.commit.counter === "string");
+    assert.equal(proof.commit.counter, "1");
+  });
+
+  test("counter increments across commits", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: hostWithCounter(km) });
+    const p1 = await ctor.commit({ bytes: new Uint8Array([1]) });
+    const p2 = await ctor.commit({ bytes: new Uint8Array([2]) });
+    assert.equal(p1.commit.counter, "1");
+    assert.equal(p2.commit.counter, "2");
+  });
+
+  test("includes time when host provides secureTime", async () => {
+    const km = await makeKeys();
+    const fixedTime = 1_700_000_000_000;
+    const ctor = await Constructor.initialize({ host: hostWithTime(km, fixedTime) });
+    const proof = await ctor.commit({ bytes: new Uint8Array([1]) });
+    assert.equal(proof.commit.time, fixedTime);
+  });
+
+  test("includes prevB64 when provided", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const prevHash = Buffer.alloc(32).toString("base64");
+    const proof = await ctor.commit({
+      bytes: new Uint8Array([1]),
+      prevProofHashB64: prevHash,
+    });
+    assert.equal(proof.commit.prevB64, prevHash);
+  });
+
+  test("includes epochId when Constructor was initialized with one", async () => {
+    const km = await makeKeys();
+    const epochId = "epoch-abc-123";
+    const ctor = await Constructor.initialize({ host: baseHost(km), epochId });
+    const proof = await ctor.commit({ bytes: new Uint8Array([1]) });
+    assert.equal(proof.commit.epochId, epochId);
+  });
+
+  test("omits epochId when not provided at initialization", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const proof = await ctor.commit({ bytes: new Uint8Array([1]) });
+    assert.equal(proof.commit.epochId, undefined);
+  });
+
+  test("each commit has a unique nonce", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const p1 = await ctor.commit({ bytes: new Uint8Array([1]) });
+    const p2 = await ctor.commit({ bytes: new Uint8Array([1]) });
+    assert.notEqual(p1.commit.nonceB64, p2.commit.nonceB64);
+  });
+
+  test("fail-closed: throws when sign() rejects (no partial proof)", async () => {
+    const km = await makeKeys();
+    const badSignHost: HostCapabilities = {
+      enforcementTier: "stub" as const,
+      getMeasurement: async () => "meas",
+      getFreshNonce: async () => crypto.getRandomValues(new Uint8Array(16)),
+      sign: async () => { throw new Error("HSM offline"); },
+      getPublicKey: async () => km.publicKeyBytes,
+    };
+    const ctor = await Constructor.initialize({ host: badSignHost });
+    await assert.rejects(
+      ctor.commit({ bytes: new Uint8Array([1]) }),
+      /host\.sign\(\) rejected/,
+    );
+  });
+
+  test("throws when nonce is too short", async () => {
+    const km = await makeKeys();
+    const shortNonceHost: HostCapabilities = {
+      ...baseHost(km),
+      getFreshNonce: async () => new Uint8Array(8), // < 16 bytes required
+    };
+    const ctor = await Constructor.initialize({ host: shortNonceHost });
+    await assert.rejects(
+      ctor.commit({ bytes: new Uint8Array([1]) }),
+      /insufficient length/,
+    );
+  });
+
+  test("two commits to same bytes produce different proofs (nonce)", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const bytes = new Uint8Array([42, 43, 44]);
+    const p1 = await ctor.commit({ bytes });
+    const p2 = await ctor.commit({ bytes });
+    assert.equal(p1.artifact.digestB64, p2.artifact.digestB64); // same digest
+    assert.notEqual(p1.signer.signatureB64, p2.signer.signatureB64); // different signature
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Constructor.commitDigest
+// ---------------------------------------------------------------------------
+
+describe("Constructor.commitDigest", () => {
+  test("returns a valid proof given a correct 32-byte base64 digest", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    // SHA-256 of empty bytes
+    const digest = Buffer.alloc(32, 0xab).toString("base64");
+    const proof = await ctor.commitDigest({ digestB64: digest });
+    assert.equal(proof.version, "bitgraph/1");
+    assert.equal(proof.artifact.digestB64, digest);
+  });
+
+  test("throws for invalid base64", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    await assert.rejects(
+      ctor.commitDigest({ digestB64: "not-valid-base64!!!" }),
+      /base64/i,
+    );
+  });
+
+  test("throws when digest decodes to != 32 bytes", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    // 16 bytes, valid base64, but not 32 bytes
+    const shortDigest = Buffer.alloc(16).toString("base64");
+    await assert.rejects(
+      ctor.commitDigest({ digestB64: shortDigest }),
+      /32/,
+    );
+  });
+
+  test("throws for empty string digest", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    await assert.rejects(
+      ctor.commitDigest({ digestB64: "" }),
+      /non-empty|base64/i,
+    );
+  });
+
+  test("includes metadata when provided", async () => {
+    const km = await makeKeys();
+    const ctor = await Constructor.initialize({ host: baseHost(km) });
+    const digest = Buffer.alloc(32, 0x77).toString("base64");
+    const proof = await ctor.commitDigest({
+      digestB64: digest,
+      metadata: { mode: "digest-only" },
+    });
+    assert.deepEqual(proof.metadata, { mode: "digest-only" });
+  });
+});

package/src/__tests__/hello-world.test.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+
+import { describe, test } from "node:test";
+import * as assert from "node:assert/strict";
+
+describe("hello world", () => {
+  test("passes", () => {
+    assert.strictEqual("hello world", "hello world");
+  });
+});

package/src/__tests__/policy-enforcement.test.ts

@@ -0,0 +1,226 @@
+// Copyright (c) Mike Argento. All rights reserved. See LICENSE.
+// End-to-end test for the BitGraph policy enforcement pipeline.
+
+import { test, describe } from "node:test";
+import * as assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { Constructor } from "../constructor.js";
+import { canonicalize } from "../index.js";
+import { hashPolicy, createPolicyBinding } from "../policy.js";
+import { sha256 } from "@noble/hashes/sha256";
+
+// Inline stub host for test isolation — dynamic import avoids tsc dist conflicts
+async function createTestHost(statePath: string) {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const mod = await import("bitgraph-stub" as string) as any;
+  const StubHost = mod.StubHost ?? mod.default?.StubHost;
+  return StubHost.createPersistent({
+    statePath,
+    measurement: "test",
+    enableTime: true,
+    enableCounter: true,
+  });
+}
+
+const TEST_POLICY = `# Policy: Test Policy
+version: 2.0
+
+## Allowed Tools
+- search
+- read_file
+
+## Limits
+- max_actions: 100
+- rate_limit: 10/min
+`;
+
+const TEST_POLICY_REVOKED = `# Policy: Test Policy Revoked
+version: 3.0
+
+## Allowed Tools
+- search
+
+## Limits
+- max_actions: 50
+`;
+
+describe("Policy Enforcement Pipeline", () => {
+  test("policy binding is created from markdown", () => {
+    const binding = createPolicyBinding(TEST_POLICY);
+    assert.ok(binding.digestB64, "should have digestB64");
+    assert.equal(binding.name, "Test Policy");
+    assert.equal(binding.version, "2.0");
+  });
+
+  test("policy committed as slot 0 with binding in proof", async () => {
+    const testDir = join(tmpdir(), `bitgraph-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+
+    const stub = await createTestHost(join(testDir, "state.json"));
+
+    const constructor = await Constructor.initialize({
+      host: stub.host,
+      policy: { requireCounter: true, requireTime: true },
+    });
+
+    const binding = createPolicyBinding(TEST_POLICY);
+    const policyDigest = hashPolicy(TEST_POLICY);
+
+    const policyProof = await constructor.commitDigest({
+      digestB64: policyDigest,
+      metadata: { kind: "policy-commitment", policyName: binding.name },
+      policy: binding,
+    });
+
+    assert.ok(policyProof, "should return a proof");
+    assert.equal(policyProof.commit.counter, "1");
+    assert.ok(policyProof.policy, "proof should have policy field");
+    assert.equal(policyProof.policy!.digestB64, policyDigest);
+    assert.equal(policyProof.policy!.name, "Test Policy");
+
+    const proofHash = Buffer.from(sha256(canonicalize(policyProof))).toString("base64");
+    binding.authorProofDigestB64 = proofHash;
+    assert.ok(binding.authorProofDigestB64);
+  });
+
+  test("action proofs carry the policy binding", async () => {
+    const testDir = join(tmpdir(), `bitgraph-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+
+    const stub = await createTestHost(join(testDir, "state.json"));
+
+    const constructor = await Constructor.initialize({
+      host: stub.host,
+      policy: { requireCounter: true, requireTime: true },
+    });
+
+    const binding = createPolicyBinding(TEST_POLICY);
+    const policyDigest = hashPolicy(TEST_POLICY);
+
+    const policyProof = await constructor.commitDigest({
+      digestB64: policyDigest,
+      metadata: { kind: "policy-commitment" },
+      policy: binding,
+    });
+
+    const proofHash = Buffer.from(sha256(canonicalize(policyProof))).toString("base64");
+    binding.authorProofDigestB64 = proofHash;
+
+    const actionDigest = Buffer.from(sha256(new TextEncoder().encode("search:query"))).toString("base64");
+    const actionProof = await constructor.commitDigest({
+      digestB64: actionDigest,
+      metadata: { kind: "tool-execution", tool: "search" },
+      prevProofHashB64: proofHash,
+      policy: binding,
+    });
+
+    assert.ok(actionProof.policy, "action proof should have policy");
+    assert.equal(actionProof.policy!.digestB64, policyDigest);
+    assert.equal(actionProof.policy!.authorProofDigestB64, proofHash);
+    assert.equal(actionProof.commit.counter, "2");
+  });
+
+  test("policy revocation updates binding", async () => {
+    const testDir = join(tmpdir(), `bitgraph-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+
+    const stub = await createTestHost(join(testDir, "state.json"));
+
+    const constructor = await Constructor.initialize({
+      host: stub.host,
+      policy: { requireCounter: true, requireTime: true },
+    });
+
+    // Slot 0: original policy
+    const originalBinding = createPolicyBinding(TEST_POLICY);
+    const originalDigest = hashPolicy(TEST_POLICY);
+
+    const slot0Proof = await constructor.commitDigest({
+      digestB64: originalDigest,
+      metadata: { kind: "policy-commitment" },
+      policy: originalBinding,
+    });
+    const slot0Hash = Buffer.from(sha256(canonicalize(slot0Proof))).toString("base64");
+    originalBinding.authorProofDigestB64 = slot0Hash;
+
+    // Action under original policy
+    const action1 = await constructor.commitDigest({
+      digestB64: Buffer.from(sha256(new TextEncoder().encode("action1"))).toString("base64"),
+      metadata: { kind: "tool-execution", tool: "read_file" },
+      prevProofHashB64: slot0Hash,
+      policy: originalBinding,
+    });
+    assert.equal(action1.policy!.digestB64, originalDigest);
+
+    // Revoke: commit new policy
+    const revokedBinding = createPolicyBinding(TEST_POLICY_REVOKED);
+    const revokedDigest = hashPolicy(TEST_POLICY_REVOKED);
+
+    const action1Hash = Buffer.from(sha256(canonicalize(action1))).toString("base64");
+    const revokeProof = await constructor.commitDigest({
+      digestB64: revokedDigest,
+      metadata: { kind: "policy-change", removed: ["read_file"] },
+      prevProofHashB64: action1Hash,
+      policy: revokedBinding,
+    });
+    const revokeHash = Buffer.from(sha256(canonicalize(revokeProof))).toString("base64");
+    revokedBinding.authorProofDigestB64 = revokeHash;
+
+    // Action under new (revoked) policy
+    const action2 = await constructor.commitDigest({
+      digestB64: Buffer.from(sha256(new TextEncoder().encode("action2"))).toString("base64"),
+      metadata: { kind: "tool-execution", tool: "search" },
+      prevProofHashB64: revokeHash,
+      policy: revokedBinding,
+    });
+
+    assert.equal(action2.policy!.digestB64, revokedDigest);
+    assert.equal(action2.policy!.authorProofDigestB64, revokeHash);
+    assert.notEqual(action2.policy!.digestB64, originalDigest);
+  });
+
+  test("causal ordering: policy counter < action counter", async () => {
+    const testDir = join(tmpdir(), `bitgraph-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+
+    const stub = await createTestHost(join(testDir, "state.json"));
+
+    const constructor = await Constructor.initialize({
+      host: stub.host,
+      policy: { requireCounter: true, requireTime: true },
+    });
+
+    const binding = createPolicyBinding(TEST_POLICY);
+
+    const policyProof = await constructor.commitDigest({
+      digestB64: hashPolicy(TEST_POLICY),
+      metadata: { kind: "policy-commitment" },
+      policy: binding,
+    });
+    const policyCounter = BigInt(policyProof.commit.counter ?? "0");
+
+    const proofHash = Buffer.from(sha256(canonicalize(policyProof))).toString("base64");
+    binding.authorProofDigestB64 = proofHash;
+
+    for (let i = 1; i <= 3; i++) {
+      const actionProof = await constructor.commitDigest({
+        digestB64: Buffer.from(sha256(new TextEncoder().encode(`action-${i}`))).toString("base64"),
+        metadata: { kind: "tool-execution", tool: "search" },
+        policy: binding,
+      });
+      const actionCounter = BigInt(actionProof.commit.counter ?? "0");
+      assert.ok(actionCounter > policyCounter, `action ${i} counter (${actionCounter}) > policy counter (${policyCounter})`);
+    }
+  });
+
+  test("hashPolicy produces consistent digest", () => {
+    const digest1 = hashPolicy(TEST_POLICY);
+    const digest2 = hashPolicy(TEST_POLICY);
+    assert.equal(digest1, digest2);
+
+    const digest3 = hashPolicy(TEST_POLICY_REVOKED);
+    assert.notEqual(digest1, digest3);
+  });
+});