@kya-os/contracts 1.8.0 → 1.9.0

package/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(),
+  };
+}

package/parity-vectors/scope-matching.json

@@ -0,0 +1,330 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "Scope matching test vectors",
+  "description": "Test vectors for delegation scope matching parity between TypeScript and Rust",
+  "version": "1.0.0",
+  "vectors": [
+    {
+      "id": "exact-match",
+      "description": "Exact scope match",
+      "input": {
+        "requested": "read:email",
+        "granted": ["read:email"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "exact",
+        "matchedBy": "read:email"
+      }
+    },
+    {
+      "id": "exact-no-match",
+      "description": "Exact scope does not match",
+      "input": {
+        "requested": "write:email",
+        "granted": ["read:email"]
+      },
+      "expected": {
+        "permitted": false,
+        "matchType": "none",
+        "matchedBy": null
+      }
+    },
+    {
+      "id": "full-access",
+      "description": "Full access wildcard matches anything",
+      "input": {
+        "requested": "any:thing:at:all",
+        "granted": ["*"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "fullAccess",
+        "matchedBy": "*"
+      }
+    },
+    {
+      "id": "wildcard-action",
+      "description": "Wildcard action matches any action in resource",
+      "input": {
+        "requested": "read:email",
+        "granted": ["read:*"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "wildcard",
+        "matchedBy": "read:*"
+      }
+    },
+    {
+      "id": "wildcard-resource",
+      "description": "Wildcard resource matches any resource for action",
+      "input": {
+        "requested": "read:email",
+        "granted": ["*:email"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "wildcard",
+        "matchedBy": "*:email"
+      }
+    },
+    {
+      "id": "wildcard-depth-mismatch",
+      "description": "Wildcard does not match different depth",
+      "input": {
+        "requested": "read:email:inbox",
+        "granted": ["read:*"]
+      },
+      "expected": {
+        "permitted": false,
+        "matchType": "none",
+        "matchedBy": null
+      }
+    },
+    {
+      "id": "prefix-match-three-segments",
+      "description": "Prefix match with trailing wildcard (3 segments)",
+      "input": {
+        "requested": "read:email:inbox",
+        "granted": ["read:email:*"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "prefix",
+        "matchedBy": "read:email:*"
+      }
+    },
+    {
+      "id": "prefix-match-four-segments",
+      "description": "Prefix match with trailing wildcard (4 segments)",
+      "input": {
+        "requested": "read:email:inbox:unread",
+        "granted": ["read:email:inbox:*"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "prefix",
+        "matchedBy": "read:email:inbox:*"
+      }
+    },
+    {
+      "id": "deep-prefix-one-level",
+      "description": "Deep prefix wildcard matches one level below",
+      "input": {
+        "requested": "read:email",
+        "granted": ["read:**"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "prefix",
+        "matchedBy": "read:**"
+      }
+    },
+    {
+      "id": "deep-prefix-two-levels",
+      "description": "Deep prefix wildcard matches two levels below",
+      "input": {
+        "requested": "read:email:inbox",
+        "granted": ["read:**"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "prefix",
+        "matchedBy": "read:**"
+      }
+    },
+    {
+      "id": "deep-prefix-many-levels",
+      "description": "Deep prefix wildcard matches many levels below",
+      "input": {
+        "requested": "read:email:inbox:unread:important",
+        "granted": ["read:**"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "prefix",
+        "matchedBy": "read:**"
+      }
+    },
+    {
+      "id": "deep-prefix-no-self-match",
+      "description": "Deep prefix wildcard does NOT match same level (strictly below)",
+      "input": {
+        "requested": "read",
+        "granted": ["read:**"]
+      },
+      "expected": {
+        "permitted": false,
+        "matchType": "none",
+        "matchedBy": null
+      }
+    },
+    {
+      "id": "deep-prefix-wrong-prefix",
+      "description": "Deep prefix wildcard does not match wrong prefix",
+      "input": {
+        "requested": "write:email",
+        "granted": ["read:**"]
+      },
+      "expected": {
+        "permitted": false,
+        "matchType": "none",
+        "matchedBy": null
+      }
+    },
+    {
+      "id": "multiple-scopes-first-match",
+      "description": "Multiple granted scopes, first match wins",
+      "input": {
+        "requested": "read:email",
+        "granted": ["write:calendar", "read:email"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "exact",
+        "matchedBy": "read:email"
+      }
+    },
+    {
+      "id": "multiple-scopes-full-access-wins",
+      "description": "Full access wins when present",
+      "input": {
+        "requested": "read:email",
+        "granted": ["write:calendar", "*"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "fullAccess",
+        "matchedBy": "*"
+      }
+    },
+    {
+      "id": "empty-scope-error",
+      "description": "Empty scope should error",
+      "input": {
+        "requested": "",
+        "granted": ["read:email"]
+      },
+      "expected": {
+        "permitted": false,
+        "error": true,
+        "errorType": "EmptyScope"
+      }
+    },
+    {
+      "id": "wildcard-middle-segment",
+      "description": "Wildcard in middle segment",
+      "input": {
+        "requested": "read:email:inbox",
+        "granted": ["read:*:inbox"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "wildcard",
+        "matchedBy": "read:*:inbox"
+      }
+    },
+    {
+      "id": "wildcard-first-segment",
+      "description": "Wildcard in first segment",
+      "input": {
+        "requested": "read:email:inbox",
+        "granted": ["*:email:inbox"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "wildcard",
+        "matchedBy": "*:email:inbox"
+      }
+    },
+    {
+      "id": "empty-granted-no-match",
+      "description": "No granted scopes means no match",
+      "input": {
+        "requested": "read:email",
+        "granted": []
+      },
+      "expected": {
+        "permitted": false,
+        "matchType": "none",
+        "matchedBy": null
+      }
+    },
+    {
+      "id": "single-segment-scope",
+      "description": "Single segment scope exact match",
+      "input": {
+        "requested": "admin",
+        "granted": ["admin"]
+      },
+      "expected": {
+        "permitted": true,
+        "matchType": "exact",
+        "matchedBy": "admin"
+      }
+    }
+  ],
+  "timeBoundaryVectors": [
+    {
+      "id": "valid-time-window",
+      "description": "Current time within valid window",
+      "input": {
+        "requested": "read:email",
+        "granted": ["read:email"],
+        "notBefore": 1704067200,
+        "notAfter": 1767225600,
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "permitted": true
+      }
+    },
+    {
+      "id": "expired-delegation",
+      "description": "Current time after notAfter",
+      "input": {
+        "requested": "read:email",
+        "granted": ["read:email"],
+        "notBefore": null,
+        "notAfter": 1704067200,
+        "currentTime": 1735689600
+      },
+      "expected": {
+        "permitted": false,
+        "error": true,
+        "errorType": "Expired"
+      }
+    },
+    {
+      "id": "not-yet-valid",
+      "description": "Current time before notBefore",
+      "input": {
+        "requested": "read:email",
+        "granted": ["read:email"],
+        "notBefore": 1735689600,
+        "notAfter": null,
+        "currentTime": 1704067200
+      },
+      "expected": {
+        "permitted": false,
+        "error": true,
+        "errorType": "NotYetValid"
+      }
+    },
+    {
+      "id": "skip-time-check",
+      "description": "Time check skipped when currentTime is 0",
+      "input": {
+        "requested": "read:email",
+        "granted": ["read:email"],
+        "notBefore": 9999999999,
+        "notAfter": 1,
+        "currentTime": 0
+      },
+      "expected": {
+        "permitted": true
+      }
+    }
+  ]
+}