@kya-os/cli 2.0.0 → 2.0.2

package/node_modules/@kya-os/contracts/parity-vectors/delegation-conformance.json

@@ -0,0 +1,265 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "Delegation chain conformance vectors",
+  "description": "Cascading-revocation, chain-integrity, per-hop attenuation, and multi-hop delegation chains (E3.5 / issue #2904). `core` = full reference semantics (mcp-i-core cascading-revocation + delegation-graph, contracts areChildConstraintsValid). `edge` = reduced-profile kya-os-engine verdict: single-hop is evaluated; multi-hop fails closed to Block(PolicyDenied) unless a higher-priority reason (Revoked/Expired) fires first.",
+  "version": "1.0.0",
+  "vectors": [
+    {
+      "id": "cascade-revoke-ancestor-revokes-leaf",
+      "category": "cascading-revocation",
+      "profiles": ["core", "edge"],
+      "description": "Two-hop chain whose root delegation is revoked while the leaf's own credential is clean. Core: leaf invalid via ancestor cascade. Edge: the engine sees only the leaf's top-level credentialStatus (clean) and cannot observe the ancestor revocation, so it fails closed on the multi-hop chain (PolicyDenied) rather than over-permitting.",
+      "input": {
+        "chain": [
+          {
+            "id": "cr-root",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:*"],
+            "credentialStatusId": "https://status.example/revocation/v1#5"
+          },
+          {
+            "id": "cr-leaf",
+            "parentId": "cr-root",
+            "issuerDid": "did:web:agent.example",
+            "subjectDid": "did:key:zSubLeaf",
+            "grantedScopes": ["read:email"],
+            "credentialStatusId": "https://status.example/revocation/v1#9"
+          }
+        ],
+        "requestedScope": "read:email",
+        "revokedStatusIds": ["https://status.example/revocation/v1#5"],
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "core": {
+          "valid": false,
+          "failureReason": "cascaded-revocation",
+          "revokedAncestor": "cr-root"
+        },
+        "edge": {
+          "mode": "fail-closed",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "PolicyDenied",
+              "detail": "multi-hop delegation chain (len=2) not evaluated by reduced edge profile; Layer-2 policy authoritative"
+            }
+          }
+        }
+      },
+      "note": "The leaf's own credentialStatus (#9) is NOT revoked, so the engine's Stage 3 does not fire Block(Revoked); the multi-hop guard yields PolicyDenied. If the leaf's own status WERE revoked, Stage 3's Revoked (priority 0) would outrank PolicyDenied — covered by the cross-runtime matrix, not here."
+    },
+    {
+      "id": "chain-integrity-broken-issuer-linkage",
+      "category": "chain-integrity",
+      "profiles": ["core", "edge"],
+      "description": "Two-hop chain where the leaf's issuer is NOT the root's subject (forged intermediate). Core: invalid-chain via delegation-graph linkage check. Edge: fails closed on the multi-hop chain.",
+      "input": {
+        "chain": [
+          {
+            "id": "ci-root",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:*"]
+          },
+          {
+            "id": "ci-leaf",
+            "parentId": "ci-root",
+            "issuerDid": "did:web:evil.example",
+            "subjectDid": "did:key:zSubLeaf",
+            "grantedScopes": ["read:email"]
+          }
+        ],
+        "requestedScope": "read:email",
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "core": {
+          "valid": false,
+          "failureReason": "invalid-chain"
+        },
+        "edge": {
+          "mode": "fail-closed",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "PolicyDenied",
+              "detail": "multi-hop delegation chain (len=2) not evaluated by reduced edge profile; Layer-2 policy authoritative"
+            }
+          }
+        }
+      },
+      "note": "delegation-graph.validateChain requires child.issuerDid === parent.subjectDid (delegation-graph.ts:243). did:web:evil.example breaks the linkage. The flat engine carries no per-hop issuer/subject, so it cannot detect this — fail-closed is the safe reduced-profile behavior."
+    },
+    {
+      "id": "attenuation-child-exceeds-parent-scope",
+      "category": "per-hop-attenuation",
+      "profiles": ["core", "edge"],
+      "description": "Two-hop chain where the child grants MORE than the parent (parent read:* via prefix, child write:billing). Core: attenuation-violation via areChildConstraintsValid. Edge: fails closed. This is the canonical over-permit case the reduced profile closes.",
+      "input": {
+        "chain": [
+          {
+            "id": "at-root",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:*"],
+            "constraints": {
+              "crisp": {
+                "scopes": [{ "resource": "read:", "matcher": "prefix" }]
+              }
+            }
+          },
+          {
+            "id": "at-leaf",
+            "parentId": "at-root",
+            "issuerDid": "did:web:agent.example",
+            "subjectDid": "did:key:zSubLeaf",
+            "grantedScopes": ["write:billing"],
+            "constraints": {
+              "crisp": {
+                "scopes": [{ "resource": "write:billing", "matcher": "exact" }]
+              }
+            }
+          }
+        ],
+        "requestedScope": "write:billing",
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "core": {
+          "valid": false,
+          "failureReason": "attenuation-violation"
+        },
+        "edge": {
+          "mode": "fail-closed",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "PolicyDenied",
+              "detail": "multi-hop delegation chain (len=2) not evaluated by reduced edge profile; Layer-2 policy authoritative"
+            }
+          }
+        }
+      },
+      "note": "Today the flat engine would flatten grants to [read:*, write:billing] and scope_satisfies('write:billing', ...) === true → silent Permit. areChildConstraintsValid rejects the widening (write:billing does not start with read:). Fail-closed converts the silent over-permit into Block(PolicyDenied)."
+    },
+    {
+      "id": "multihop-valid-chain-still-fail-closed",
+      "category": "multi-hop-valid",
+      "profiles": ["core", "edge"],
+      "description": "A WELL-FORMED two-hop chain: valid linkage, no revocation, child scopes within parent, request within leaf grant. Core: valid. Edge: STILL fails closed — the reduced profile does not certify multi-hop even when the chain is valid; the over-permit risk is structural, not data-dependent.",
+      "input": {
+        "chain": [
+          {
+            "id": "hp-root",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:email"],
+            "credentialStatusId": "https://status.example/revocation/v1#20",
+            "constraints": {
+              "crisp": {
+                "scopes": [{ "resource": "read:email", "matcher": "exact" }]
+              }
+            }
+          },
+          {
+            "id": "hp-leaf",
+            "parentId": "hp-root",
+            "issuerDid": "did:web:agent.example",
+            "subjectDid": "did:key:zSubLeaf",
+            "grantedScopes": ["read:email"],
+            "credentialStatusId": "https://status.example/revocation/v1#21",
+            "constraints": {
+              "crisp": {
+                "scopes": [{ "resource": "read:email", "matcher": "exact" }]
+              }
+            }
+          }
+        ],
+        "requestedScope": "read:email",
+        "revokedStatusIds": [],
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "core": {
+          "valid": true
+        },
+        "edge": {
+          "mode": "fail-closed",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "PolicyDenied",
+              "detail": "multi-hop delegation chain (len=2) not evaluated by reduced edge profile; Layer-2 policy authoritative"
+            }
+          }
+        }
+      },
+      "note": "Deliberate negative-of-convenience: proves the edge profile fails closed even on a VALID multi-hop chain. This is the honest cost of the reduced profile — Layer-2 tenant policy must opt these back in. Prevents a future maintainer from 'optimizing' the guard to permit valid-looking chains."
+    },
+    {
+      "id": "singlehop-scope-permit",
+      "category": "scope-match",
+      "profiles": ["edge"],
+      "description": "Single-hop delegation whose granted scope covers the requested scope. Edge: evaluated → Permit (regression guard that the multi-hop guard does NOT change the len<=1 path).",
+      "input": {
+        "chain": [
+          {
+            "id": "sh-permit",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:email"]
+          }
+        ],
+        "requestedScope": "read:email",
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "edge": {
+          "mode": "evaluated",
+          "decision": { "kind": "Permit" }
+        }
+      },
+      "note": "Single-hop is within the engine's competence: it flattens the one step's grants and matches requestedScope. No core counterpart — for single-hop scope the engine is the reference."
+    },
+    {
+      "id": "singlehop-scope-out-of-scope",
+      "category": "scope-match",
+      "profiles": ["edge"],
+      "description": "Single-hop delegation whose granted scope does NOT cover the requested scope. Edge: evaluated → Block(OutOfScope). Proves the guard leaves the genuine single-hop scope rejection intact.",
+      "input": {
+        "chain": [
+          {
+            "id": "sh-oos",
+            "parentId": null,
+            "issuerDid": "did:web:org.example",
+            "subjectDid": "did:web:agent.example",
+            "grantedScopes": ["read:email"]
+          }
+        ],
+        "requestedScope": "write:billing",
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "edge": {
+          "mode": "evaluated",
+          "decision": {
+            "kind": "Block",
+            "reason": {
+              "kind": "OutOfScope",
+              "requested": "write:billing",
+              "granted": ["read:email"]
+            }
+          }
+        }
+      },
+      "note": "Single-hop OutOfScope stays a genuine evaluated rejection (not fail-closed). granted is the flattened single-step grant set."
+    }
+  ]
+}

package/node_modules/@kya-os/contracts/parity-vectors/did-key.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "did:key resolution test vectors",
+  "description": "Test vectors for did:key resolution parity between TypeScript and Rust",
+  "version": "1.0.0",
+  "vectors": [
+    {
+      "id": "valid-ed25519-1",
+      "description": "Valid Ed25519 did:key",
+      "input": {
+        "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+      },
+      "expected": {
+        "success": true,
+        "keyType": "Ed25519",
+        "publicKeyHex": "8520f0098930a754748b7ddcb43ef75a0dbf3a0d26381af4eba4a98eaa9b4e6a",
+        "keyId": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+      }
+    },
+    {
+      "id": "valid-ed25519-2",
+      "description": "Another valid Ed25519 did:key",
+      "input": {
+        "did": "did:key:z6MkfrNzYH9ygZbUjWKFW3BrN5SvXqWMQGQwYVaR8GGJqWLb"
+      },
+      "expected": {
+        "success": true,
+        "keyType": "Ed25519"
+      }
+    },
+    {
+      "id": "invalid-empty",
+      "description": "Empty DID string",
+      "input": {
+        "did": ""
+      },
+      "expected": {
+        "success": false,
+        "errorType": "InvalidFormat"
+      }
+    },
+    {
+      "id": "invalid-not-did-key",
+      "description": "Wrong DID method (did:web instead of did:key)",
+      "input": {
+        "did": "did:web:example.com"
+      },
+      "expected": {
+        "success": false,
+        "errorType": "InvalidPrefix"
+      }
+    },
+    {
+      "id": "invalid-multibase-prefix",
+      "description": "Invalid multibase prefix (not z)",
+      "input": {
+        "did": "did:key:f6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+      },
+      "expected": {
+        "success": false,
+        "errorType": "InvalidMultibase"
+      }
+    },
+    {
+      "id": "invalid-base58",
+      "description": "Invalid base58 encoding (contains 0, O, I, l)",
+      "input": {
+        "did": "did:key:z6Mk0OIl"
+      },
+      "expected": {
+        "success": false,
+        "errorType": "InvalidBase58"
+      }
+    },
+    {
+      "id": "unsupported-curve-p256",
+      "description": "Unsupported curve (P-256)",
+      "input": {
+        "did": "did:key:zDnaeucDGfNLZfcPeDpQWAcfJMCvzNjrB5F9Xut7VH8fFYnDW"
+      },
+      "expected": {
+        "success": false,
+        "errorType": "UnsupportedKeyType"
+      }
+    },
+    {
+      "id": "unsupported-curve-secp256k1",
+      "description": "Unsupported curve (secp256k1)",
+      "input": {
+        "did": "did:key:zQ3shNFbC9Wk5yXnNMEsNz1hL5NPcUHbBYC8TmUHxAHhVWFqe"
+      },
+      "expected": {
+        "success": false,
+        "errorType": "UnsupportedKeyType"
+      }
+    },
+    {
+      "id": "invalid-key-length",
+      "description": "Invalid key length (too short)",
+      "input": {
+        "did": "did:key:z6MkTest"
+      },
+      "expected": {
+        "success": false,
+        "errorType": "InvalidKeyLength"
+      }
+    },
+    {
+      "id": "valid-key-id-validation",
+      "description": "Validate key ID format",
+      "input": {
+        "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+        "keyId": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+      },
+      "expected": {
+        "success": true,
+        "keyIdValid": true
+      }
+    },
+    {
+      "id": "invalid-key-id-mismatch",
+      "description": "Key ID does not match DID",
+      "input": {
+        "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+        "keyId": "did:key:z6MkfrNzYH9ygZbUjWKFW3BrN5SvXqWMQGQwYVaR8GGJqWLb#z6MkfrNzYH9ygZbUjWKFW3BrN5SvXqWMQGQwYVaR8GGJqWLb"
+      },
+      "expected": {
+        "success": false,
+        "keyIdValid": false,
+        "errorType": "KeyIdMismatch"
+      }
+    }
+  ]
+}

package/node_modules/@kya-os/contracts/parity-vectors/index.ts

@@ -0,0 +1,253 @@
+/**
+ * Test Vector Loader
+ *
+ * This module provides functions to load parity test vectors.
+ * These vectors ensure TypeScript and Rust implementations produce identical results.
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+
+// Types for test vectors
+export interface TestVector<TInput, TExpected> {
+  id: string;
+  description: string;
+  input: TInput;
+  expected: TExpected;
+  note?: string;
+}
+
+export interface TestVectorFile<TInput, TExpected> {
+  $schema?: string;
+  name: string;
+  description: string;
+  version: string;
+  vectors: TestVector<TInput, TExpected>[];
+}
+
+// did:key vector types
+export interface DidKeyInput {
+  did: string;
+  keyId?: string;
+}
+
+export interface DidKeyExpected {
+  success: boolean;
+  keyType?: string;
+  publicKeyHex?: string;
+  keyId?: string;
+  keyIdValid?: boolean;
+  errorType?: string;
+}
+
+// Scope matching vector types
+export interface ScopeMatchingInput {
+  requested: string;
+  granted: string[];
+  notBefore?: number | null;
+  notAfter?: number | null;
+  currentTime?: number;
+}
+
+export interface ScopeMatchingExpected {
+  permitted: boolean;
+  matchType?: "exact" | "wildcard" | "prefix" | "fullAccess" | "none";
+  matchedBy?: string | null;
+  error?: boolean;
+  errorType?: string;
+}
+
+export interface ScopeMatchingVectorFile
+  extends TestVectorFile<ScopeMatchingInput, ScopeMatchingExpected> {
+  timeBoundaryVectors?: TestVector<ScopeMatchingInput, ScopeMatchingExpected>[];
+}
+
+// VC-JWT vector types
+export interface VcJwtInput {
+  jwt: string;
+  publicKeyHex?: string;
+}
+
+export interface VcJwtExpected {
+  success: boolean;
+  header?: {
+    alg: string;
+    typ?: string | null;
+  };
+  payload?: Record<string, unknown>;
+  issuer?: string;
+  verified?: boolean;
+  errorType?: string;
+  errorMessage?: string;
+}
+
+export interface VcJwtVectorFile
+  extends TestVectorFile<VcJwtInput, VcJwtExpected> {
+  signatureVerificationVectors?: TestVector<VcJwtInput, VcJwtExpected>[];
+}
+
+/**
+ * Load test vectors from JSON file
+ */
+function loadVectors<T>(filename: string): T {
+  const filepath = join(__dirname, filename);
+  const content = readFileSync(filepath, "utf-8");
+  return JSON.parse(content) as T;
+}
+
+/**
+ * Load did:key resolution test vectors
+ */
+export function loadDidKeyVectors(): TestVectorFile<
+  DidKeyInput,
+  DidKeyExpected
+> {
+  return loadVectors<TestVectorFile<DidKeyInput, DidKeyExpected>>(
+    "did-key.json"
+  );
+}
+
+/**
+ * Load scope matching test vectors
+ */
+export function loadScopeMatchingVectors(): ScopeMatchingVectorFile {
+  return loadVectors<ScopeMatchingVectorFile>("scope-matching.json");
+}
+
+/**
+ * Load VC-JWT verification test vectors
+ */
+export function loadVcJwtVectors(): VcJwtVectorFile {
+  return loadVectors<VcJwtVectorFile>("vc-jwt.json");
+}
+
+// ============================================================================
+// Delegation chain conformance vectors (E3.5 / issue #2904)
+//
+// These vectors codify the reference delegation semantics defined in E3.1
+// (mcp-i-core: cascading-revocation, delegation-graph) plus the CRISP per-hop
+// attenuation primitive (contracts: areChildConstraintsValid), so the TS cores
+// and the reduced-profile Rust edge engine verify against one shared corpus.
+//
+// Each vector carries TWO expected outcomes:
+//   - `core`: the full reference semantics a complete verifier must produce.
+//   - `edge`: the reduced-profile kya-os-engine (WASM/WASI) verdict. The edge
+//     engine formally verifies single-hop delegation only; multi-hop chains
+//     fail closed (see issue #2904 "reduced edge profile").
+// `profiles` lists which profiles must satisfy the vector directly; `category`
+// selects which reference primitive owns the vector's `core` assertion.
+// ============================================================================
+
+/** Selects which reference primitive owns a vector's `core` assertion. */
+export type DelegationCategory =
+  | "cascading-revocation"
+  | "chain-integrity"
+  | "per-hop-attenuation"
+  | "multi-hop-valid"
+  | "scope-match";
+
+export type DelegationProfile = "core" | "edge";
+
+/** Minimal CRISP constraint shape the attenuation primitive consumes. */
+export interface DelegationConstraintsInput {
+  notBefore?: number;
+  notAfter?: number;
+  scopes?: string[];
+  crisp?: {
+    budget?: { unit: "USD" | "ops" | "points"; cap: number };
+    scopes: Array<{ resource: string; matcher: "exact" | "prefix" | "regex" }>;
+  };
+}
+
+/** One hop in a delegation chain (root→leaf order). */
+export interface DelegationHopInput {
+  /** Delegation id (unique within the chain). */
+  id: string;
+  /** Parent delegation id, or null for the root hop. */
+  parentId: string | null;
+  /** Issuer (delegator) DID. */
+  issuerDid: string;
+  /** Subject (delegatee) DID. */
+  subjectDid: string;
+  /** Flat granted scopes — what the reduced-profile engine's DelegationStep carries. */
+  grantedScopes: string[];
+  /** StatusList2021 pointer "<statusListUrl>#<index>" for revocation, if any. */
+  credentialStatusId?: string;
+  /** CRISP constraints — required for per-hop-attenuation vectors. */
+  constraints?: DelegationConstraintsInput;
+}
+
+export interface DelegationChainInput {
+  /** The delegation chain, root→leaf. length===1 ⇒ single-hop; >1 ⇒ multi-hop. */
+  chain: DelegationHopInput[];
+  /** Scope the leaf agent requests (the engine derives this from payload.aud). */
+  requestedScope: string;
+  /** credentialStatusIds that are currently revoked (drives the cascade check). */
+  revokedStatusIds?: string[];
+  /** Evaluation time (Unix seconds) for time-bounded checks. */
+  currentTime?: number;
+}
+
+/** Full reference-semantics outcome (the TS cores). */
+export interface DelegationCoreExpected {
+  valid: boolean;
+  failureReason?:
+    | "cascaded-revocation"
+    | "direct-revocation"
+    | "invalid-chain"
+    | "attenuation-violation";
+  /** For cascaded revocation: the revoked ancestor's id. */
+  revokedAncestor?: string;
+}
+
+/** Canonical engine Decision wire shape (kya-os-engine types.rs). */
+export type EngineDecision =
+  | { kind: "Permit" }
+  | { kind: "Block"; reason: { kind: string; [k: string]: unknown } };
+
+/** Reduced-profile edge verdict (kya-os-engine). */
+export interface DelegationEdgeExpected {
+  /**
+   * 'evaluated'   — single-hop / L1: the engine computes the real verdict.
+   * 'fail-closed' — multi-hop: the engine refuses (Block PolicyDenied) unless a
+   *                 higher-priority reason (Revoked/Expired) fires first.
+   */
+  mode: "evaluated" | "fail-closed";
+  decision: EngineDecision;
+}
+
+export interface DelegationExpected {
+  /** Omitted for edge-only vectors (single-hop scope-match), where the engine is itself the reference. */
+  core?: DelegationCoreExpected;
+  edge: DelegationEdgeExpected;
+}
+
+export interface DelegationVector
+  extends TestVector<DelegationChainInput, DelegationExpected> {
+  category: DelegationCategory;
+  profiles: DelegationProfile[];
+}
+
+export interface DelegationVectorFile
+  extends TestVectorFile<DelegationChainInput, DelegationExpected> {
+  vectors: DelegationVector[];
+}
+
+/**
+ * Load delegation chain conformance test vectors
+ */
+export function loadDelegationVectors(): DelegationVectorFile {
+  return loadVectors<DelegationVectorFile>("delegation-conformance.json");
+}
+
+/**
+ * Get all test vectors as a combined object
+ */
+export function loadAllVectors() {
+  return {
+    didKey: loadDidKeyVectors(),
+    scopeMatching: loadScopeMatchingVectors(),
+    vcJwt: loadVcJwtVectors(),
+    delegation: loadDelegationVectors(),
+  };
+}