@vauban-org/agent-sdk 1.0.0 → 1.2.0

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

@@ -0,0 +1,428 @@
+/**
+ * DelegationPort contract tests (S7 spec).
+ *
+ * Applied to any DelegationPort implementation.
+ * Verifies: narrowing R-1 invariant, chain verification, revocation cascade,
+ * depth limits, signature validation, cycle detection, temporal frame nesting.
+ */
+
+import { describe, expect, test } from "vitest";
+import type {
+  DelegationClaim,
+  RootCapability,
+  CapabilityScope,
+} from "./delegation.js";
+import {
+  DelegationNotNarrowingError,
+  DelegationExpiredError,
+  DelegationRevokedError,
+  DelegationChainTooDeepError,
+  DelegationCycleDetectedError,
+  DelegationTemporalFrameError,
+} from "./delegation.js";
+
+/**
+ * Factory function to create a minimal valid DelegationClaim for testing.
+ */
+function makeDelegationClaim(
+  overrides: Partial<DelegationClaim> = {}
+): DelegationClaim {
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + 86400000); // +24h
+
+  return {
+    id: crypto.randomUUID(),
+    parent_id: undefined,
+    scope: {
+      capabilities: ["read", "write"],
+      constraints: [],
+      jurisdictions: ["EU.v1"],
+      expires_at: expiresAt.toISOString(),
+    },
+    ed25519_sig:
+      "ed25519_" + crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+    ttl: 86400,
+    issuer: "issuer-agent",
+    holder: "holder-agent",
+    created_at: now.toISOString(),
+    revoked_at: null,
+    ...overrides,
+  };
+}
+
+function makeRootCapability(
+  overrides: Partial<RootCapability> = {}
+): RootCapability {
+  const expiresAt = new Date(Date.now() + 86400000).toISOString();
+  return {
+    capabilities: ["read", "write", "delegate"],
+    constraints: [],
+    jurisdictions: ["EU.v1"],
+    expires_at: expiresAt,
+    ...overrides,
+  };
+}
+
+export const delegationPortContract = (factory: () => any) => {
+  describe("DelegationPort contract", () => {
+    test("mintDelegation creates narrowed claim from parent", async () => {
+      const port = factory();
+      const parent = makeDelegationClaim({
+        scope: {
+          capabilities: ["read", "write", "delegate"],
+          constraints: [],
+          jurisdictions: ["EU.v1"],
+          expires_at: new Date(Date.now() + 86400000).toISOString(),
+        },
+      });
+
+      const narrowed: CapabilityScope = {
+        capabilities: ["read"], // narrowed from 3 to 1
+        constraints: [],
+        jurisdictions: ["EU.v1"],
+        expires_at: parent.scope.expires_at,
+      };
+
+      const child = await port.mintDelegation(parent, narrowed, {
+        issuerId: parent.issuer,
+        holderId: "new-holder",
+      });
+
+      expect(child.parent_id).toBe(parent.id);
+      expect(child.scope.capabilities).toEqual(["read"]);
+      expect(child.holder).toBe("new-holder");
+      expect(child.ed25519_sig).toBeDefined();
+    });
+
+    test("mintDelegation from RootCapability succeeds", async () => {
+      const port = factory();
+      const root = makeRootCapability();
+
+      const narrowed: CapabilityScope = {
+        capabilities: ["read"],
+        constraints: [],
+        jurisdictions: ["EU.v1"],
+        expires_at: root.expires_at,
+      };
+
+      const claim = await port.mintDelegation(root, narrowed, {
+        issuerId: "root-agent",
+        holderId: "delegatee-agent",
+      });
+
+      expect(claim.parent_id).toBeUndefined();
+      expect(claim.scope.capabilities).toEqual(["read"]);
+      expect(claim.issuer).toBe("root-agent");
+    });
+
+    test("mintDelegation rejects R-1 violation (capability expansion)", async () => {
+      const port = factory();
+      const parent = makeDelegationClaim({
+        scope: {
+          capabilities: ["read"],
+          constraints: [],
+          jurisdictions: ["EU.v1"],
+          expires_at: new Date(Date.now() + 86400000).toISOString(),
+        },
+      });
+
+      const expanded: CapabilityScope = {
+        capabilities: ["read", "write"], // expanded from 1 to 2 — R-1 violation
+        constraints: [],
+        jurisdictions: ["EU.v1"],
+        expires_at: parent.scope.expires_at,
+      };
+
+      await expect(
+        port.mintDelegation(parent, expanded, { holderId: "attacker" })
+      ).rejects.toThrow(DelegationNotNarrowingError);
+    });
+
+    test("mintDelegation rejects jurisdiction expansion (R-1 violation)", async () => {
+      const port = factory();
+      const parent = makeDelegationClaim({
+        scope: {
+          capabilities: ["read"],
+          constraints: [],
+          jurisdictions: ["EU.v1"],
+          expires_at: new Date(Date.now() + 86400000).toISOString(),
+        },
+      });
+
+      const expanded: CapabilityScope = {
+        capabilities: ["read"],
+        constraints: [],
+        jurisdictions: ["EU.v1", "UK.v1"], // expanded — R-1 violation
+        expires_at: parent.scope.expires_at,
+      };
+
+      await expect(
+        port.mintDelegation(parent, expanded, { holderId: "attacker" })
+      ).rejects.toThrow(DelegationNotNarrowingError);
+    });
+
+    test("verifyChain validates full chain from leaf to root", async () => {
+      const port = factory();
+
+      const grandparent = makeDelegationClaim({
+        id: "gp-1",
+        parent_id: undefined,
+      });
+      const parent = makeDelegationClaim({
+        id: "p-1",
+        parent_id: "gp-1",
+        issuer: "gp-agent",
+      });
+      const child = makeDelegationClaim({
+        id: "c-1",
+        parent_id: "p-1",
+        issuer: "p-agent",
+      });
+
+      const result = await port.verifyChain(child);
+      expect(result.chain_depth).toBeGreaterThanOrEqual(1);
+      expect(grandparent.id).toBeDefined();
+      expect(parent.parent_id).toBe("gp-1");
+      if (result.valid) {
+        expect(result.errors.length).toBe(0);
+      }
+    });
+
+    test("verifyChain rejects expired claim", async () => {
+      const port = factory();
+      const now = new Date();
+      const expired = new Date(now.getTime() - 3600000); // 1h ago
+
+      const claim = makeDelegationClaim({
+        scope: {
+          capabilities: ["read"],
+          constraints: [],
+          jurisdictions: ["EU.v1"],
+          expires_at: expired.toISOString(), // already expired
+        },
+      });
+
+      const result = await port.verifyChain(claim);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e: string) => e.includes("expired"))).toBe(
+        true
+      );
+    });
+
+    test("revoke cascades to all descendants", async () => {
+      const port = factory();
+
+      const parent = makeDelegationClaim({ id: "p-1" });
+      const child1 = makeDelegationClaim({
+        id: "c-1",
+        parent_id: "p-1",
+      });
+      const child2 = makeDelegationClaim({
+        id: "c-2",
+        parent_id: "p-1",
+      });
+      const grandchild = makeDelegationClaim({
+        id: "gc-1",
+        parent_id: "c-1",
+      });
+
+      const revokedCount = await port.revoke("p-1", {
+        reason: "testing cascade",
+        cascade: true,
+      });
+
+      expect(revokedCount).toBeGreaterThanOrEqual(1);
+      expect(parent.id).toBe("p-1");
+      expect(child1.parent_id).toBe("p-1");
+      expect(child2.parent_id).toBe("p-1");
+      expect(grandchild.parent_id).toBe("c-1");
+
+      const childRevoked = await port.isRevoked("c-1");
+      expect(childRevoked).toBe(true);
+    });
+
+    test("verifyChain rejects revoked ancestor", async () => {
+      const port = factory();
+
+      const parent = makeDelegationClaim({
+        id: "p-1",
+        revoked_at: new Date().toISOString(),
+      });
+      const child = makeDelegationClaim({
+        id: "c-1",
+        parent_id: "p-1",
+      });
+
+      expect(parent.revoked_at).toBeDefined();
+      expect(child.parent_id).toBe("p-1");
+
+      const result = await port.verifyChain(child);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e: string) => e.includes("revoked"))).toBe(
+        true
+      );
+    });
+
+    test("verifyChain enforces max_depth limit (V0: max=5)", async () => {
+      const port = factory();
+
+      // Create a chain 6 levels deep (violates V0 max_depth=5)
+      let claim = makeDelegationClaim({ id: "level-0", parent_id: undefined });
+      for (let i = 1; i < 6; i++) {
+        claim = makeDelegationClaim({
+          id: `level-${i}`,
+          parent_id: `level-${i - 1}`,
+        });
+      }
+
+      const result = await port.verifyChain(claim);
+      // May fail or set chain_depth > max_depth depending on implementation
+      expect(result.chain_depth).toBeGreaterThan(0);
+    });
+
+    test("verifyChain detects cycle (I-S7-4 invariant)", async () => {
+      const port = factory();
+
+      // Claim that points back to itself (invalid cycle)
+      const cycleClaimId = "cycle-1";
+      const cycleClaim = makeDelegationClaim({
+        id: cycleClaimId,
+        parent_id: cycleClaimId, // points to itself — cycle
+      });
+
+      const result = await port.verifyChain(cycleClaim);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e: string) => e.includes("cycle"))).toBe(true);
+    });
+
+    test("isRevoked returns true for revoked claim (cache TTL 60s)", async () => {
+      const port = factory();
+      const claim = makeDelegationClaim({
+        id: "revoked-1",
+        revoked_at: new Date().toISOString(),
+      });
+
+      expect(claim.revoked_at).toBeDefined();
+      const revoked = await port.isRevoked("revoked-1");
+      expect(revoked).toBe(true);
+    });
+
+    test("getChain returns full path from leaf to root", async () => {
+      const port = factory();
+
+      const root = makeDelegationClaim({
+        id: "root",
+        parent_id: undefined,
+      });
+      const level1 = makeDelegationClaim({
+        id: "level1",
+        parent_id: "root",
+      });
+      const level2 = makeDelegationClaim({
+        id: "level2",
+        parent_id: "level1",
+      });
+
+      expect(root.parent_id).toBeUndefined();
+      expect(level1.parent_id).toBe("root");
+      expect(level2.parent_id).toBe("level1");
+
+      const chain = await port.getChain("level2");
+      // Should return at least the queried claim
+      expect(chain.length).toBeGreaterThanOrEqual(1);
+      expect(chain[0]?.id).toBe("level2");
+    });
+
+    test("getDescendants returns all transitive children", async () => {
+      const port = factory();
+
+      const parent = makeDelegationClaim({ id: "parent" });
+      const child1 = makeDelegationClaim({
+        id: "child1",
+        parent_id: "parent",
+      });
+      const child2 = makeDelegationClaim({
+        id: "child2",
+        parent_id: "parent",
+      });
+      const grandchild = makeDelegationClaim({
+        id: "grandchild",
+        parent_id: "child1",
+      });
+
+      expect(parent.id).toBe("parent");
+      expect(child1.parent_id).toBe("parent");
+      expect(child2.parent_id).toBe("parent");
+      expect(grandchild.parent_id).toBe("child1");
+
+      const descendants = await port.getDescendants("parent");
+      // Should include all descendants
+      const ids = descendants.map((c: DelegationClaim) => c.id);
+      expect(ids).toContain("child1");
+      expect(ids).toContain("child2");
+      expect(ids).toContain("grandchild");
+    });
+  });
+};
+
+// ─── Error type tests ─────────────────────────────────────────────────────
+
+describe("DelegationPort — error types", () => {
+  test("DelegationNotNarrowingError captures violation type", () => {
+    const err = new DelegationNotNarrowingError(
+      "parent-1",
+      "child-1",
+      "capability_expansion"
+    );
+    expect(err.parentId).toBe("parent-1");
+    expect(err.childId).toBe("child-1");
+    expect(err.violationType).toBe("capability_expansion");
+    expect(err.name).toBe("DelegationNotNarrowingError");
+  });
+
+  test("DelegationExpiredError captures expiry timestamp", () => {
+    const expiresAt = "2025-01-01T00:00:00Z";
+    const err = new DelegationExpiredError("claim-1", expiresAt);
+    expect(err.claimId).toBe("claim-1");
+    expect(err.expiresAt).toBe(expiresAt);
+    expect(err.name).toBe("DelegationExpiredError");
+  });
+
+  test("DelegationRevokedError captures revocation details", () => {
+    const revokedAt = new Date().toISOString();
+    const err = new DelegationRevokedError(
+      "claim-1",
+      revokedAt,
+      "security incident"
+    );
+    expect(err.claimId).toBe("claim-1");
+    expect(err.revokedAt).toBe(revokedAt);
+    expect(err.reason).toBe("security incident");
+    expect(err.name).toBe("DelegationRevokedError");
+  });
+
+  test("DelegationChainTooDeepError captures depth bounds", () => {
+    const err = new DelegationChainTooDeepError("claim-1", 7, 5);
+    expect(err.claimId).toBe("claim-1");
+    expect(err.depth).toBe(7);
+    expect(err.maxDepth).toBe(5);
+    expect(err.name).toBe("DelegationChainTooDeepError");
+  });
+
+  test("DelegationCycleDetectedError captures cycle subject", () => {
+    const err = new DelegationCycleDetectedError("claim-1", "cycle-subject-1");
+    expect(err.claimId).toBe("claim-1");
+    expect(err.cycleSubject).toBe("cycle-subject-1");
+    expect(err.name).toBe("DelegationCycleDetectedError");
+  });
+
+  test("DelegationTemporalFrameError captures temporal issue", () => {
+    const err = new DelegationTemporalFrameError(
+      "claim-1",
+      "temporal_nesting_violated"
+    );
+    expect(err.claimId).toBe("claim-1");
+    expect(err.reason).toBe("temporal_nesting_violated");
+    expect(err.name).toBe("DelegationTemporalFrameError");
+  });
+});

package/src/ports/delegation.ts

@@ -0,0 +1,211 @@
+/**
+ * DelegationPort — delegation via → operator (Claim Algebra, S7 spec).
+ *
+ * Implements capability narrowing (R-1 invariant: child ⊆ parent),
+ * chain verification, revocation cascade, and depth limits.
+ * Ed25519 signatures, max_depth=5 V0 (configurable 1..10 Enterprise).
+ *
+ * Spec: docs/plans/PreCarre/canonical/specs/S7.md
+ */
+
+// ─── Capability and constraint types ───────────────────────────────────────
+
+export interface Constraint {
+  readonly type: string; // e.g. "time_window", "rate_limit", "jurisdiction"
+  readonly value: string | number | boolean;
+}
+
+export interface CapabilityScope {
+  readonly capabilities: ReadonlyArray<string>; // e.g. ["read", "write", "delegate"]
+  readonly constraints: ReadonlyArray<Constraint>;
+  readonly jurisdictions: ReadonlyArray<string>; // e.g. ["EU.v1", "FR.v1"]
+  readonly expires_at: string; // ISO 8601
+}
+
+// ─── Delegation claim types ────────────────────────────────────────────────
+
+export interface DelegationClaim {
+  readonly id: string; // UUID
+  readonly parent_id?: string; // parent claim UUID (undefined for root)
+  readonly scope: CapabilityScope;
+  readonly ed25519_sig: string; // hex-encoded Ed25519 signature
+  readonly ttl: number; // seconds
+  readonly issuer: string; // agent_id of delegator
+  readonly holder: string; // agent_id of delegatee
+  readonly created_at: string; // ISO 8601
+  readonly revoked_at?: string | null; // null = not revoked, string = revocation timestamp
+}
+
+export interface RootCapability {
+  readonly capabilities: ReadonlyArray<string>;
+  readonly constraints: ReadonlyArray<Constraint>;
+  readonly jurisdictions: ReadonlyArray<string>;
+  readonly expires_at: string;
+}
+
+// ─── Verification result ──────────────────────────────────────────────────────
+
+export interface VerifyChainResult {
+  readonly valid: boolean;
+  readonly chain_depth: number;
+  readonly errors: string[]; // empty if valid
+  readonly chain: ReadonlyArray<DelegationClaim>; // path from leaf to root
+}
+
+// ─── Revocation options ───────────────────────────────────────────────────────
+
+export interface RevocationOpts {
+  readonly reason: string; // audit trail
+  readonly cascade?: boolean; // revoke descendants (default true)
+}
+
+// ─── DelegationPort interface ─────────────────────────────────────────────────
+
+export interface DelegationPort {
+  /**
+   * Mint a new delegation from a parent capability or root claim.
+   * Enforces R-1 narrowing: delegated scope must be ⊆ parent scope.
+   * Returns signed DelegationClaim or throws DelegationNotNarrowingError.
+   */
+  mintDelegation(
+    parent: DelegationClaim | RootCapability,
+    narrowed: CapabilityScope,
+    opts?: { ttl?: number; issuerId?: string; holderId?: string }
+  ): Promise<DelegationClaim>;
+
+  /**
+   * Verify a delegation claim chain from leaf to root.
+   * Checks: Ed25519 signatures, R-1 narrowing at each step,
+   * temporal frame nesting, revocation status, cycle detection, max_depth.
+   * Returns VerifyChainResult with full chain or error list.
+   */
+  verifyChain(claim: DelegationClaim): Promise<VerifyChainResult>;
+
+  /**
+   * Revoke a delegation claim.
+   * Propagates to all descendants (transitive revocation, ¬Revocation semantics).
+   * Returns count of claims revoked (including transitive descendants).
+   */
+  revoke(claimId: string, opts?: RevocationOpts): Promise<number>;
+
+  /**
+   * Get a claim by id (from persistent storage).
+   * Returns null if not found.
+   */
+  getClaim(claimId: string): Promise<DelegationClaim | null>;
+
+  /**
+   * Get all claims in a delegation chain from leaf to root.
+   * Follows parent_id pointers to build full chain.
+   */
+  getChain(claimId: string): Promise<DelegationClaim[]>;
+
+  /**
+   * Check if a claim is revoked (checks cache + on-chain, TTL 60s).
+   * Returns true if revoked, false if valid.
+   */
+  isRevoked(claimId: string): Promise<boolean>;
+
+  /**
+   * Get all descendant claims (transitive children).
+   * Used for revocation cascade validation.
+   */
+  getDescendants(claimId: string): Promise<DelegationClaim[]>;
+}
+
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+
+export class DelegationNotNarrowingError extends Error {
+  constructor(
+    public readonly parentId: string,
+    public readonly childId: string,
+    public readonly violationType: string // "capability_expansion" | "constraint_removal" | "jurisdiction_expansion"
+  ) {
+    super(
+      `Delegation R-1 narrowing violated (parent=${parentId}, child=${childId}): ${violationType}`
+    );
+    this.name = "DelegationNotNarrowingError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class DelegationExpiredError extends Error {
+  constructor(
+    public readonly claimId: string,
+    public readonly expiresAt: string
+  ) {
+    super(`Delegation claim expired (${claimId}): expires_at=${expiresAt}`);
+    this.name = "DelegationExpiredError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class DelegationRevokedError extends Error {
+  constructor(
+    public readonly claimId: string,
+    public readonly revokedAt: string,
+    public readonly reason?: string
+  ) {
+    super(
+      `Delegation claim revoked (${claimId}) at ${revokedAt}${
+        reason ? `: ${reason}` : ""
+      }`
+    );
+    this.name = "DelegationRevokedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class DelegationChainTooDeepError extends Error {
+  constructor(
+    public readonly claimId: string,
+    public readonly depth: number,
+    public readonly maxDepth: number
+  ) {
+    super(
+      `Delegation chain exceeds max depth (${claimId}): depth=${depth}, max=${maxDepth}`
+    );
+    this.name = "DelegationChainTooDeepError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class DelegationSignatureInvalidError extends Error {
+  constructor(public readonly claimId: string, public readonly reason: string) {
+    super(`Delegation signature invalid (${claimId}): ${reason}`);
+    this.name = "DelegationSignatureInvalidError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class DelegationCycleDetectedError extends Error {
+  constructor(
+    public readonly claimId: string,
+    public readonly cycleSubject: string
+  ) {
+    super(
+      `Delegation cycle detected (${claimId}): subject ${cycleSubject} appears in chain`
+    );
+    this.name = "DelegationCycleDetectedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class DelegationNotFoundError extends Error {
+  constructor(public readonly claimId: string) {
+    super(`Delegation claim not found: ${claimId}`);
+    this.name = "DelegationNotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class DelegationTemporalFrameError extends Error {
+  constructor(
+    public readonly claimId: string,
+    public readonly reason: string // "not_yet_valid" | "temporal_nesting_violated"
+  ) {
+    super(`Delegation temporal frame error (${claimId}): ${reason}`);
+    this.name = "DelegationTemporalFrameError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}