@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/src/ports/privacy.contract.test.ts

@@ -0,0 +1,413 @@
+/**
+ * PrivacyPort contract tests — validate V0 noop stub interface compliance.
+ *
+ * Tests verify:
+ * - applyMask returns input unchanged (identity function V0)
+ * - verifyZkProof always returns {valid: false, reason: 'noop_v0'}
+ * - commitToSmt returns deterministic mock root with correct structure
+ * - NoopPrivacyAdapter satisfies the PrivacyPort interface
+ * - All operations handle various context and commitment types
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  NoopPrivacyAdapter,
+  type RevelationMask,
+  type ZkProofInput,
+  type PrivacyContext,
+  type Commitment,
+} from "./privacy";
+
+describe("PrivacyPort contract", () => {
+  describe("applyMask", () => {
+    it("returns input payload unchanged (V0 identity function)", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const payload = { secret: "hidden", public: "visible", count: 42 };
+      const mask: RevelationMask = {
+        public_fields: ["public"],
+        private_fields: ["secret"],
+      };
+      const ctx: PrivacyContext = { user_id: "user-1", tenant_id: "tenant-a" };
+
+      const result = await adapter.applyMask(payload, mask, ctx);
+
+      expect(result).toEqual(payload);
+      expect(result).toBe(payload); // same reference (identity)
+    });
+
+    it("handles complex nested objects unchanged", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const payload = {
+        user: {
+          id: "u1",
+          nested: {
+            secret: "data",
+            array: [1, 2, 3],
+          },
+        },
+      };
+      const mask: RevelationMask = {
+        public_fields: ["user.id"],
+        private_fields: ["user.nested.secret"],
+      };
+      const ctx: PrivacyContext = {};
+
+      const result = await adapter.applyMask(payload, mask, ctx);
+
+      expect(result).toEqual(payload);
+    });
+
+    it("accepts conditional revelation masks", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const payload = { data: "value" };
+      const mask: RevelationMask = {
+        public_fields: ["id"],
+        private_fields: ["secret"],
+        conditional: [
+          {
+            field: "email",
+            condition: "user_role == 'admin'",
+          },
+        ],
+      };
+      const ctx: PrivacyContext = { role: "admin" };
+
+      const result = await adapter.applyMask(payload, mask, ctx);
+
+      expect(result).toEqual(payload);
+    });
+
+    it("handles various payload types (string, number, array, null)", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const mask: RevelationMask = {
+        public_fields: [],
+        private_fields: [],
+      };
+      const ctx: PrivacyContext = {};
+
+      const testCases = [
+        "string payload",
+        42,
+        3.14,
+        true,
+        [1, 2, 3],
+        null,
+        undefined,
+      ];
+
+      for (const payload of testCases) {
+        const result = await adapter.applyMask(payload, mask, ctx);
+        expect(result).toEqual(payload);
+      }
+    });
+
+    it("context parameters are accepted and ignored (V0)", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const payload = { data: "test" };
+      const mask: RevelationMask = {
+        public_fields: [],
+        private_fields: [],
+      };
+
+      const contexts = [
+        { user_id: "u1" },
+        { tenant_id: "t1", jurisdiction: "FR.v1" },
+        { role: "admin", user_id: "u2", metadata: { custom: "value" } },
+        {},
+      ];
+
+      for (const ctx of contexts) {
+        const result = await adapter.applyMask(payload, mask, ctx);
+        expect(result).toEqual(payload);
+      }
+    });
+  });
+
+  describe("verifyZkProof", () => {
+    it("always returns invalid with 'noop_v0' reason", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const proof: ZkProofInput = {
+        proof_data: { some: "proof" },
+        public_inputs: { value: 42 },
+      };
+      const ctx: PrivacyContext = {};
+
+      const result = await adapter.verifyZkProof(proof, ctx);
+
+      expect(result.valid).toBe(false);
+      expect(result.reason).toBe("noop_v0");
+      expect(result.confidence).toBe(0);
+    });
+
+    it("handles various proof schemes (V0 ignores)", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const schemes = ["stwo", "starknet_stone", "groth16", "plonk"];
+
+      for (const scheme of schemes) {
+        const proof: ZkProofInput = {
+          proof_data: { scheme_data: "test" },
+          public_inputs: {},
+          scheme,
+        };
+        const result = await adapter.verifyZkProof(proof, {});
+
+        expect(result.valid).toBe(false);
+        expect(result.reason).toBe("noop_v0");
+      }
+    });
+
+    it("accepts empty public inputs", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const proof: ZkProofInput = {
+        proof_data: "opaque_bytes",
+        public_inputs: {},
+      };
+
+      const result = await adapter.verifyZkProof(proof, {});
+
+      expect(result.valid).toBe(false);
+      expect(result.reason).toBe("noop_v0");
+    });
+
+    it("context parameters are accepted and ignored (V0)", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const proof: ZkProofInput = {
+        proof_data: "test",
+        public_inputs: { x: 1 },
+      };
+
+      const contexts = [
+        { user_id: "u1" },
+        { tenant_id: "t1", jurisdiction: "EU.v1" },
+        { role: "operator" },
+      ];
+
+      for (const ctx of contexts) {
+        const result = await adapter.verifyZkProof(proof, ctx);
+        expect(result.valid).toBe(false);
+      }
+    });
+  });
+
+  describe("commitToSmt", () => {
+    it("returns mock SMT root with correct structure", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const commitment: Commitment = { value: "test_value" };
+      const ctx: PrivacyContext = {};
+
+      const result = await adapter.commitToSmt(commitment, ctx);
+
+      expect(result.smt_root).toBeDefined();
+      expect(result.smt_root).toMatch(/^0x[0-9a-f]+$/);
+      expect(result.leaf_index).toBe(0);
+      expect(result.version).toBe(0);
+    });
+
+    it("returns deterministic root for same commitment", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const commitment: Commitment = { value: "deterministic" };
+      const ctx: PrivacyContext = {};
+
+      const result1 = await adapter.commitToSmt(commitment, ctx);
+      const result2 = await adapter.commitToSmt(commitment, ctx);
+
+      expect(result1.smt_root).toBe(result2.smt_root);
+    });
+
+    it("returns different root for different commitments", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const ctx: PrivacyContext = {};
+
+      const result1 = await adapter.commitToSmt({ value: "value1" }, ctx);
+      const result2 = await adapter.commitToSmt({ value: "value2" }, ctx);
+
+      expect(result1.smt_root).not.toBe(result2.smt_root);
+    });
+
+    it("respects explicit leaf_index from commitment", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const commitment: Commitment = { value: "test", index: 42 };
+      const ctx: PrivacyContext = {};
+
+      const result = await adapter.commitToSmt(commitment, ctx);
+
+      expect(result.leaf_index).toBe(42);
+    });
+
+    it("defaults leaf_index to 0 when not specified", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const commitment: Commitment = { value: "test" };
+      const ctx: PrivacyContext = {};
+
+      const result = await adapter.commitToSmt(commitment, ctx);
+
+      expect(result.leaf_index).toBe(0);
+    });
+
+    it("accepts optional salt in commitment", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const commitment: Commitment = {
+        value: "secret",
+        salt: "random_salt_123",
+        index: 5,
+      };
+      const ctx: PrivacyContext = {};
+
+      const result = await adapter.commitToSmt(commitment, ctx);
+
+      expect(result.smt_root).toBeDefined();
+      expect(result.leaf_index).toBe(5);
+      expect(result.version).toBe(0);
+    });
+
+    it("handles various commitment value types", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const ctx: PrivacyContext = {};
+
+      const values = [
+        "string value",
+        42,
+        3.14,
+        true,
+        { nested: "object" },
+        [1, 2, 3],
+      ];
+
+      for (const value of values) {
+        const result = await adapter.commitToSmt({ value }, ctx);
+        expect(result.smt_root).toBeDefined();
+        expect(result.version).toBe(0);
+      }
+    });
+
+    it("context parameters are accepted and ignored (V0)", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const commitment: Commitment = { value: "test" };
+
+      const contexts = [
+        { user_id: "u1", tenant_id: "t1" },
+        { jurisdiction: "CH.v1" },
+        { metadata: { custom: true } },
+      ];
+
+      for (const ctx of contexts) {
+        const result = await adapter.commitToSmt(commitment, ctx);
+        expect(result.smt_root).toBeDefined();
+      }
+    });
+  });
+
+  describe("NoopPrivacyAdapter interface compliance", () => {
+    it("satisfies PrivacyPort contract", () => {
+      const adapter = new NoopPrivacyAdapter();
+
+      expect(typeof adapter.applyMask).toBe("function");
+      expect(typeof adapter.verifyZkProof).toBe("function");
+      expect(typeof adapter.commitToSmt).toBe("function");
+    });
+
+    it("all async methods return Promise", async () => {
+      const adapter = new NoopPrivacyAdapter();
+
+      const maskResult = adapter.applyMask(
+        {},
+        { public_fields: [], private_fields: [] },
+        {}
+      );
+      const proofResult = adapter.verifyZkProof(
+        { proof_data: "x", public_inputs: {} },
+        {}
+      );
+      const smtResult = adapter.commitToSmt({ value: "x" }, {});
+
+      expect(maskResult).toBeInstanceOf(Promise);
+      expect(proofResult).toBeInstanceOf(Promise);
+      expect(smtResult).toBeInstanceOf(Promise);
+
+      await maskResult;
+      await proofResult;
+      await smtResult;
+    });
+
+    it("methods work together in realistic flow", async () => {
+      const adapter = new NoopPrivacyAdapter();
+      const ctx: PrivacyContext = { user_id: "user-1", role: "admin" };
+
+      // Simulate a privacy-respecting workflow (V0: all no-ops)
+      const payload = { secret: "data", public: "info" };
+      const mask: RevelationMask = {
+        public_fields: ["public"],
+        private_fields: ["secret"],
+      };
+
+      const masked = await adapter.applyMask(payload, mask, ctx);
+      expect(masked).toEqual(payload);
+
+      const commitment: Commitment = { value: masked };
+      const smtResult = await adapter.commitToSmt(commitment, ctx);
+      expect(smtResult.smt_root).toBeDefined();
+      expect(smtResult.version).toBe(0);
+
+      const proof: ZkProofInput = {
+        proof_data: { root: smtResult.smt_root },
+        public_inputs: { commitment_hash: "hash" },
+      };
+      const verified = await adapter.verifyZkProof(proof, ctx);
+      expect(verified.valid).toBe(false);
+      expect(verified.reason).toBe("noop_v0");
+    });
+  });
+
+  describe("V0 noop semantics validation", () => {
+    it("demonstrates V0 identity semantics: applyMask is identity", async () => {
+      const adapter = new NoopPrivacyAdapter();
+
+      // V0 guarantee: f(x) = x for any x
+      const testValues = [
+        { a: 1, b: "secret" },
+        "plain text",
+        [1, 2, 3, "secret"],
+        { deeply: { nested: { secret: "data" } } },
+      ];
+
+      for (const value of testValues) {
+        const result = await adapter.applyMask(
+          value,
+          { public_fields: ["a"], private_fields: ["secret"] },
+          {}
+        );
+        expect(result).toBe(value); // exact same object
+      }
+    });
+
+    it("demonstrates V0 proof rejection: verifyZkProof always fails", async () => {
+      const adapter = new NoopPrivacyAdapter();
+
+      // V0 guarantee: verifyZkProof always returns invalid
+      const proofs = [
+        { proof_data: "valid_proof", public_inputs: {} },
+        { proof_data: null, public_inputs: { x: 1 } },
+        { proof_data: { complex: "structure" }, public_inputs: [] },
+      ];
+
+      for (const proof of proofs) {
+        const result = await adapter.verifyZkProof(proof as ZkProofInput, {});
+        expect(result.valid).toBe(false);
+        expect(result.reason).toBe("noop_v0");
+        expect(result.confidence).toBe(0);
+      }
+    });
+
+    it("demonstrates V0 mock SMT: deterministic but no crypto", async () => {
+      const adapter = new NoopPrivacyAdapter();
+
+      // V0 guarantee: deterministic + version 0
+      const c1 = await adapter.commitToSmt({ value: "test" }, {});
+      const c2 = await adapter.commitToSmt({ value: "test" }, {});
+
+      expect(c1.smt_root).toBe(c2.smt_root);
+      expect(c1.version).toBe(0);
+      expect(c2.version).toBe(0);
+    });
+  });
+});

package/src/ports/privacy.ts

@@ -0,0 +1,207 @@
+/**
+ * PrivacyPort — V0 noop stub for Vauban Privacy Protocol (VPP) integration.
+ *
+ * Implements S0 port #10 (PrivacyPort): placeholder interface for privacy-preserving
+ * operations. Phase 2+ will implement full Stwo+ML-KEM+viewing-key+SMT+cross-domain
+ * functionality per draft-vauban-privacy-protocol-00 (target IETF submission 2026-06-29,
+ * sprint-490 active 78%).
+ *
+ * V0 design: all operations return identity or noop stubs. Enables code to pass type
+ * checks while VPP integration is deferred. No Side effects, no cryptographic guarantees.
+ *
+ * Reference: S0 § cross-spec invariants X-1 (isolation), X-3 (crypto-shredding);
+ * VPP Phase roadmap: draft-vauban-privacy-protocol-00 + integration plan TBD.
+ */
+
+// ─── Privacy revelation mask types ────────────────────────────────────────────
+
+/**
+ * RevelationMask — declarative specification of which fields should be exposed
+ * during a privacy-respecting operation.
+ */
+export interface RevelationMask {
+  readonly public_fields: string[]; // fields always visible
+  readonly private_fields: string[]; // fields always hidden
+  readonly conditional?: Array<{
+    readonly field: string;
+    readonly condition: string; // e.g., "user_role == 'admin'"
+  }>;
+}
+
+// ─── Zero-knowledge proof types ────────────────────────────────────────────────
+
+export interface ZkProofInput {
+  readonly proof_data: unknown; // opaque proof bytes / object
+  readonly public_inputs: unknown; // public circuit inputs
+  readonly scheme?: string; // e.g., "stwo", "starknet_stone"
+}
+
+export interface VerifyResult {
+  readonly valid: boolean;
+  readonly reason?: string; // why invalid (e.g., 'noop_v0', 'invalid_proof')
+  readonly confidence?: number; // 0-1 confidence score (V0 always 0)
+}
+
+// ─── Sparse merkle tree commitment types ───────────────────────────────────────
+
+export interface Commitment {
+  readonly value: unknown; // commitment hash or object
+  readonly salt?: string; // optional salt for hiding value
+  readonly index?: number; // position in tree
+}
+
+export interface SmtResult {
+  readonly smt_root: string; // hex-encoded root hash (V0: deterministic mock)
+  readonly leaf_index: number; // position of committed value
+  readonly version: number; // SMT version/epoch (V0: 0)
+  readonly proof?: unknown; // merkle path (V0: omitted)
+}
+
+// ─── Privacy context ──────────────────────────────────────────────────────────
+
+export interface PrivacyContext {
+  readonly user_id?: string;
+  readonly tenant_id?: string;
+  readonly role?: string; // 'user', 'admin', 'operator'
+  readonly jurisdiction?: string; // e.g., 'FR.v1', 'EU.v1'
+  readonly metadata?: Record<string, unknown>;
+}
+
+// ─── PrivacyPort interface ────────────────────────────────────────────────────
+
+/**
+ * PrivacyPort — V0 noop stub.
+ *
+ * All methods return identity values or noop results. Replaced by full VPP
+ * implementation in Phase 2 (Stwo+ML-KEM+viewing-key+SMT+cross-domain).
+ *
+ * Usage:
+ *   const priv = new NoopPrivacyAdapter();
+ *   const revealed = await priv.applyMask(data, mask, ctx); // data unchanged V0
+ *   const vk = await priv.verifyZkProof(proof, ctx); // {valid: false, reason: 'noop_v0'}
+ */
+export interface PrivacyPort {
+  /**
+   * Apply a revelation mask to payload (V0: returns payload unchanged).
+   *
+   * Phase 2+: will implement field-level hiding via ZK commitments or viewing keys.
+   *
+   * @param payload input object or data structure
+   * @param mask specification of which fields are public/private/conditional
+   * @param ctx privacy context (user, tenant, role, jurisdiction)
+   * @returns masked payload (V0: unchanged)
+   */
+  applyMask(
+    payload: unknown,
+    mask: RevelationMask,
+    ctx: PrivacyContext
+  ): Promise<unknown>;
+
+  /**
+   * Verify a zero-knowledge proof (V0: always returns invalid with 'noop_v0' reason).
+   *
+   * Phase 2+: will implement Stwo proof verification against public inputs.
+   *
+   * @param proof ZK proof object (scheme TBD, likely Stwo)
+   * @param ctx privacy context
+   * @returns { valid: false, reason: 'noop_v0' } in V0
+   */
+  verifyZkProof(
+    proof: ZkProofInput,
+    ctx: PrivacyContext
+  ): Promise<VerifyResult>;
+
+  /**
+   * Commit value to sparse merkle tree (V0: returns deterministic mock root).
+   *
+   * Phase 2+: will implement full SMT with Poseidon hashing and viewing keys.
+   *
+   * @param commitment value or hash to commit
+   * @param ctx privacy context
+   * @returns mock SMT root (V0: deterministic, no cryptographic guarantee)
+   */
+  commitToSmt(commitment: Commitment, ctx: PrivacyContext): Promise<SmtResult>;
+}
+
+// ─── Noop implementation (V0 stub) ────────────────────────────────────────────
+
+/**
+ * NoopPrivacyAdapter — V0 stub implementation of PrivacyPort.
+ *
+ * All methods return identity values or noop results. Enables type-safe code
+ * while VPP integration is deferred to Phase 2.
+ *
+ * Documentation: "V0 stub — replaced by VPP integration in Phase 2
+ * (Stwo+ML-KEM+viewing key+SMT+cross-domain)."
+ *
+ * Usage:
+ *   const adapter = new NoopPrivacyAdapter();
+ *   const data = { secret: 'hidden', public: 'visible' };
+ *   const masked = await adapter.applyMask(data, mask, ctx);
+ *   // masked === data (unchanged in V0)
+ */
+export class NoopPrivacyAdapter implements PrivacyPort {
+  async applyMask(
+    payload: unknown,
+    _mask: RevelationMask,
+    _ctx: PrivacyContext
+  ): Promise<unknown> {
+    // V0: identity function — return input unchanged
+    return payload;
+  }
+
+  async verifyZkProof(
+    _proof: ZkProofInput,
+    _ctx: PrivacyContext
+  ): Promise<VerifyResult> {
+    // V0: always invalid with noop marker
+    return {
+      valid: false,
+      reason: "noop_v0",
+      confidence: 0,
+    };
+  }
+
+  async commitToSmt(
+    commitment: Commitment,
+    _ctx: PrivacyContext
+  ): Promise<SmtResult> {
+    // V0: return deterministic mock root based on commitment value
+    // In real Phase 2+, would compute Poseidon hash and maintain SMT state
+    const mockRoot = this.computeMockRoot(commitment);
+    return {
+      smt_root: mockRoot,
+      leaf_index: commitment.index ?? 0,
+      version: 0, // V0 version
+    };
+  }
+
+  /**
+   * Compute a deterministic mock SMT root (V0 only).
+   * Purely for testing — no cryptographic guarantee.
+   */
+  private computeMockRoot(commitment: Commitment): string {
+    // Simple deterministic hash for V0: stringify commitment and hash
+    const str = JSON.stringify(commitment);
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      hash = (hash << 5) - hash + str.charCodeAt(i);
+      hash = hash & hash; // keep it as 32-bit int
+    }
+    return "0x" + Math.abs(hash).toString(16).padStart(64, "0");
+  }
+}
+
+// ─── Informational warning (not thrown) ─────────────────────────────────────
+
+/**
+ * PrivacyNoopWarning — logged when V0 noop operations are used.
+ * Not thrown as an exception (non-blocking), but logged for observability.
+ */
+export class PrivacyNoopWarning extends Error {
+  constructor(message: string, public readonly operation: string) {
+    super(message);
+    this.name = "PrivacyNoopWarning";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}