@kya-os/mcp 1.6.1 → 1.9.0

package/dist/utils/safe-fetch.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SSRF-hardened outbound fetch (safe-fetch) — the policy orchestrator.
+ *
+ * `resolveCard` — and, later, JWKS + status-list resolution — follows URLs an attacker can
+ * influence across four discovery surfaces, so every outbound request goes through this
+ * guard. `createSafeFetch` returns a fetcher structurally compatible with the card's
+ * `FetchLike` ({ ok, status, json }) that enforces, fail-closed:
+ *
+ *   - https-only (no http:, file:, data:, …);
+ *   - the connection IP is a PUBLIC UNICAST address (RFC1918, loopback, link-local incl. the
+ *     169.254.169.254 cloud-metadata endpoint, IPv6 ULA/link-local, NAT64/6to4/Teredo transition
+ *     ranges are denied — see `./ip-classifier`). Each HOP is resolved ONCE and its connection is
+ *     PINNED to that validated address, closing the DNS-rebinding (TOCTOU) window within the hop; a
+ *     same-origin redirect to a different host triggers a fresh resolve-and-pin cycle for that hop;
+ *   - cross-origin redirects are blocked (manual handling; a 3xx to a different origin is
+ *     rejected, same-origin redirects are followed up to a small cap);
+ *   - a response size cap and an AbortSignal-backed timeout bound resource use.
+ *
+ * The two Node transports live in `./safe-fetch-transports`; the seam vocabulary in
+ * `./safe-fetch-types`; the address policy in `./ip-classifier`. This module owns only the
+ * hop-by-hop POLICY (scheme, resolve-and-pin, redirect, size cap, timeout, first-party escape
+ * hatch) and re-exports the transports + classifier + types so the public surface is one import.
+ *
+ * First-party escape hatch: `allowOrigins` / `firstPartyOrigin` list origins a caller owns. A
+ * request whose origin equals a configured one is fetched plain (origin-equality is not
+ * attacker-routable); every other origin still takes the guarded path, fail-closed.
+ *
+ * All I/O is injected via pluggable seams (`lookup`, `transport`) so the policy is unit tested
+ * with mocked DNS + transport. No crypto here — no mcp-i-core dependency leaks in.
+ */
+import type { SafeFetch, SafeFetchOptions } from './safe-fetch-types.js';
+export * from './safe-fetch-types.js';
+export { isBlockedAddress } from './ip-classifier.js';
+export { defaultLookup, fetchTransport, nodeHttpsTransport, selectDefaultTransport, } from './safe-fetch-transports.js';
+/**
+ * Build an SSRF-hardened fetcher. The returned function is structurally compatible with the
+ * card's `FetchLike`: `(url) => Promise<{ ok, status, json }>`.
+ */
+export declare function createSafeFetch(options?: SafeFetchOptions): SafeFetch;
+//# sourceMappingURL=safe-fetch.d.ts.map

package/dist/utils/safe-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fetch.d.ts","sourceRoot":"","sources":["../../src/utils/safe-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH,OAAO,KAAK,EAIV,SAAS,EACT,gBAAgB,EAGjB,MAAM,uBAAuB,CAAC;AAG/B,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AA6EpC;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAuBzE"}

package/dist/utils/safe-fetch.js

@@ -0,0 +1,188 @@
+/**
+ * SSRF-hardened outbound fetch (safe-fetch) — the policy orchestrator.
+ *
+ * `resolveCard` — and, later, JWKS + status-list resolution — follows URLs an attacker can
+ * influence across four discovery surfaces, so every outbound request goes through this
+ * guard. `createSafeFetch` returns a fetcher structurally compatible with the card's
+ * `FetchLike` ({ ok, status, json }) that enforces, fail-closed:
+ *
+ *   - https-only (no http:, file:, data:, …);
+ *   - the connection IP is a PUBLIC UNICAST address (RFC1918, loopback, link-local incl. the
+ *     169.254.169.254 cloud-metadata endpoint, IPv6 ULA/link-local, NAT64/6to4/Teredo transition
+ *     ranges are denied — see `./ip-classifier`). Each HOP is resolved ONCE and its connection is
+ *     PINNED to that validated address, closing the DNS-rebinding (TOCTOU) window within the hop; a
+ *     same-origin redirect to a different host triggers a fresh resolve-and-pin cycle for that hop;
+ *   - cross-origin redirects are blocked (manual handling; a 3xx to a different origin is
+ *     rejected, same-origin redirects are followed up to a small cap);
+ *   - a response size cap and an AbortSignal-backed timeout bound resource use.
+ *
+ * The two Node transports live in `./safe-fetch-transports`; the seam vocabulary in
+ * `./safe-fetch-types`; the address policy in `./ip-classifier`. This module owns only the
+ * hop-by-hop POLICY (scheme, resolve-and-pin, redirect, size cap, timeout, first-party escape
+ * hatch) and re-exports the transports + classifier + types so the public surface is one import.
+ *
+ * First-party escape hatch: `allowOrigins` / `firstPartyOrigin` list origins a caller owns. A
+ * request whose origin equals a configured one is fetched plain (origin-equality is not
+ * attacker-routable); every other origin still takes the guarded path, fail-closed.
+ *
+ * All I/O is injected via pluggable seams (`lookup`, `transport`) so the policy is unit tested
+ * with mocked DNS + transport. No crypto here — no mcp-i-core dependency leaks in.
+ */
+import { isBlockedAddress } from './ip-classifier.js';
+import { defaultLookup, fetchTransport, selectDefaultTransport, } from './safe-fetch-transports.js';
+// Re-export the full public surface so a consumer needs only `./safe-fetch` (barrels unchanged).
+export * from './safe-fetch-types.js';
+export { isBlockedAddress } from './ip-classifier.js';
+export { defaultLookup, fetchTransport, nodeHttpsTransport, selectDefaultTransport, } from './safe-fetch-transports.js';
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_BYTES = 1_048_576;
+const DEFAULT_MAX_REDIRECTS = 3;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Parse + require https; returns the normalized href. */
+function assertHttpsUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`safe-fetch: invalid URL "${raw}"`);
+    }
+    if (url.protocol !== 'https:') {
+        throw new Error(`safe-fetch: only https is allowed (got "${url.protocol}")`);
+    }
+    return url.href;
+}
+/** Resolve the host ONCE, reject if ANY resolved address is non-public, and pin the first. */
+async function resolveAndPin(hostname, lookup) {
+    const addresses = await lookup(hostname);
+    const [first] = addresses;
+    if (!first) {
+        throw new Error(`safe-fetch: DNS lookup for "${hostname}" returned no addresses`);
+    }
+    for (const candidate of addresses) {
+        if (isBlockedAddress(candidate.address)) {
+            throw new Error(`safe-fetch: refusing non-public address ${candidate.address} for host "${hostname}"`);
+        }
+    }
+    return first;
+}
+/** Resolve a 3xx into the next URL, rejecting cross-origin / non-https / missing-Location. */
+function nextRedirectUrl(currentUrl, raw) {
+    const location = raw.headers.get('location');
+    if (!location) {
+        throw new Error(`safe-fetch: ${raw.status} redirect without a Location header`);
+    }
+    let target;
+    try {
+        target = new URL(location, currentUrl);
+    }
+    catch {
+        // Keep the module's fail-closed convention: a malformed Location surfaces a `safe-fetch:`-
+        // prefixed error rather than a raw TypeError leaking out of the URL constructor.
+        throw new Error(`safe-fetch: redirect location is not a valid URL "${location}"`);
+    }
+    if (target.protocol !== 'https:') {
+        throw new Error(`safe-fetch: redirect to non-https target "${target.protocol}" blocked`);
+    }
+    const origin = new URL(currentUrl).origin;
+    if (target.origin !== origin) {
+        throw new Error(`safe-fetch: cross-origin redirect blocked (${origin} → ${target.origin})`);
+    }
+    return target.href;
+}
+/** Enforce the size cap and project a RawResponse into the FetchLike-compatible shape. */
+async function finalize(raw, maxBytes) {
+    const declared = Number(raw.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        throw new Error(`safe-fetch: declared content-length ${declared} exceeds cap ${maxBytes}`);
+    }
+    const body = await raw.text();
+    if (Buffer.byteLength(body, 'utf8') > maxBytes) {
+        throw new Error(`safe-fetch: response body exceeds size cap ${maxBytes}`);
+    }
+    return {
+        ok: raw.status >= 200 && raw.status < 300,
+        status: raw.status,
+        json: () => Promise.resolve(JSON.parse(body)),
+    };
+}
+/**
+ * Build an SSRF-hardened fetcher. The returned function is structurally compatible with the
+ * card's `FetchLike`: `(url) => Promise<{ ok, status, json }>`.
+ */
+export function createSafeFetch(options = {}) {
+    const cfg = {
+        lookup: options.lookup ?? defaultLookup,
+        transport: options.transport ?? selectDefaultTransport(),
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+        trustedOrigins: normalizeTrustedOrigins(options),
+    };
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    return async function safeFetch(initialUrl) {
+        let url = assertHttpsUrl(initialUrl);
+        for (let hop = 0;; hop++) {
+            const raw = await requestOnce(url, cfg);
+            if (!REDIRECT_STATUSES.has(raw.status)) {
+                return finalize(raw, cfg.maxBytes);
+            }
+            if (hop >= maxRedirects) {
+                throw new Error(`safe-fetch: too many redirects (> ${maxRedirects})`);
+            }
+            url = nextRedirectUrl(url, raw);
+        }
+    };
+}
+/**
+ * Perform ONE hop. First-party origins skip the resolve-and-pin SSRF screen (origin-equality is
+ * not attacker-routable) and are fetched plain by name; every other origin is resolved, screened,
+ * and pinned before the configured transport runs. Both branches are timeout-bounded.
+ */
+async function requestOnce(url, cfg) {
+    const { hostname, origin } = new URL(url);
+    if (cfg.trustedOrigins.has(origin)) {
+        return withTimeout(hostname, cfg.timeoutMs, (signal) => fetchTransport(url, { signal, hostname, pinnedAddress: '', family: 4, maxBytes: cfg.maxBytes }));
+    }
+    const pinned = await resolveAndPin(hostname, cfg.lookup);
+    return withTimeout(hostname, cfg.timeoutMs, (signal) => cfg.transport(url, {
+        signal,
+        hostname,
+        pinnedAddress: pinned.address,
+        family: pinned.family,
+        maxBytes: cfg.maxBytes,
+    }));
+}
+/** Run a transport call under an AbortSignal that fires after `timeoutMs`. */
+async function withTimeout(hostname, timeoutMs, run) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`safe-fetch: request to ${hostname} timed out after ${timeoutMs}ms`)), timeoutMs);
+    try {
+        return await run(controller.signal);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Build the set of first-party origins that bypass the SSRF screen. Each `allowOrigins` /
+ * `firstPartyOrigin` entry MUST parse as an https origin — fail-closed (throw) otherwise.
+ */
+function normalizeTrustedOrigins(options) {
+    const raw = [...(options.allowOrigins ?? []), ...(options.firstPartyOrigin ? [options.firstPartyOrigin] : [])];
+    const origins = new Set();
+    for (const entry of raw) {
+        let url;
+        try {
+            url = new URL(entry);
+        }
+        catch {
+            throw new Error(`safe-fetch: invalid first-party origin "${entry}"`);
+        }
+        if (url.protocol !== 'https:') {
+            throw new Error(`safe-fetch: first-party origin must be https (got "${entry}")`);
+        }
+        origins.add(url.origin);
+    }
+    return origins;
+}
+//# sourceMappingURL=safe-fetch.js.map

package/dist/utils/safe-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fetch.js","sourceRoot":"","sources":["../../src/utils/safe-fetch.ts"],"names":[],"mappings":"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"}

package/dist/utils/statuslist-purpose.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared fail-closed status-list `statusPurpose` check — the SINGLE source of truth for the
+ * invariant both the card revocation reader (`src/card/revocation.ts`) and the delegation status
+ * manager (`src/delegation/statuslist-manager.ts`) enforce, so the two readers cannot drift.
+ */
+/**
+ * Fail CLOSED unless the resolved status list's `statusPurpose` is present AND equals `wanted`. A
+ * list of a DIFFERENT kind (e.g. a `suspension` list read as `revocation`) must not be accepted —
+ * its clear bit would otherwise report "not revoked" from the wrong list, a fail-open bypass.
+ */
+export declare function assertStatusPurpose(listPurpose: unknown, wanted: string): void;
+//# sourceMappingURL=statuslist-purpose.d.ts.map

package/dist/utils/statuslist-purpose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statuslist-purpose.d.ts","sourceRoot":"","sources":["../../src/utils/statuslist-purpose.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAO9E"}

package/dist/utils/statuslist-purpose.js

@@ -0,0 +1,19 @@
+/**
+ * Shared fail-closed status-list `statusPurpose` check — the SINGLE source of truth for the
+ * invariant both the card revocation reader (`src/card/revocation.ts`) and the delegation status
+ * manager (`src/delegation/statuslist-manager.ts`) enforce, so the two readers cannot drift.
+ */
+/**
+ * Fail CLOSED unless the resolved status list's `statusPurpose` is present AND equals `wanted`. A
+ * list of a DIFFERENT kind (e.g. a `suspension` list read as `revocation`) must not be accepted —
+ * its clear bit would otherwise report "not revoked" from the wrong list, a fail-open bypass.
+ */
+export function assertStatusPurpose(listPurpose, wanted) {
+    if (typeof listPurpose !== 'string') {
+        throw new Error(`status list has no statusPurpose (expected "${wanted}") — fail-closed`);
+    }
+    if (listPurpose !== wanted) {
+        throw new Error(`status list statusPurpose mismatch: "${listPurpose}" ≠ "${wanted}"`);
+    }
+}
+//# sourceMappingURL=statuslist-purpose.js.map

package/dist/utils/statuslist-purpose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statuslist-purpose.js","sourceRoot":"","sources":["../../src/utils/statuslist-purpose.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAoB,EAAE,MAAc;IACtE,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,+CAA+C,MAAM,kBAAkB,CAAC,CAAC;IAC3F,CAAC;IACD,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,wCAAwC,WAAW,QAAQ,MAAM,GAAG,CAAC,CAAC;IACxF,CAAC;AACH,CAAC"}

package/dist/utils/url.d.ts

@@ -0,0 +1,2 @@
+export declare function stripTrailingSlashes(value: string): string;
+//# sourceMappingURL=url.d.ts.map

package/dist/utils/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM1D"}

package/dist/utils/url.js

@@ -0,0 +1,8 @@
+export function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47) {
+        end--;
+    }
+    return value.slice(0, end);
+}
+//# sourceMappingURL=url.js.map

package/dist/utils/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;IACvB,OAAO,GAAG,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QACnD,GAAG,EAAE,CAAC;IACR,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@kya-os/mcp",
-  "version": "1.6.1",
+  "version": "1.9.0",
   "description": "Reference implementation of the KYA-OS protocol for Model Context Protocol servers: delegation, proof, and session primitives",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -11,6 +12,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./card": {
+      "types": "./dist/card/index.d.ts",
+      "default": "./dist/card/index.js"
+    },
     "./delegation": {
       "types": "./dist/delegation/index.d.ts",
       "default": "./dist/delegation/index.js"
@@ -51,6 +56,10 @@
       "types": "./dist/authz/index.d.ts",
       "default": "./dist/authz/index.js"
     },
+    "./cheqd": {
+      "types": "./dist/integrations/cheqd/index.d.ts",
+      "default": "./dist/integrations/cheqd/index.js"
+    },
     "./schemas/*.json": "./schemas/*.json",
     "./package.json": "./package.json"
   },
@@ -64,9 +73,15 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
+    "test:e2e:cheqd:testnet": "vitest run src/integrations/cheqd/__tests__/registrar.live.test.ts",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
+    "conformance": "tsx conformance/bin.ts",
+    "conformance:generate": "tsx conformance/generate-vectors.ts",
+    "conformance:generate:card": "tsx conformance/card-vectors.ts",
+    "conformance:verify:crosslang": "python3 conformance/verify.py",
+    "conformance:typecheck": "tsc --noEmit -p conformance/tsconfig.json",
     "lint": "eslint src --ext .ts",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build && npm run test",
@@ -75,13 +90,17 @@
     "example:inspector": "npx @modelcontextprotocol/inspector npx tsx examples/node-server/server.ts --stdio",
     "example:verify-proof": "npx tsx examples/verify-proof/verify.ts",
     "example:anti-mitm": "npx tsx examples/verify-proof/anti-mitm-demo.ts",
+    "example:entity-card": "npx tsx examples/entity-card/walkthrough.ts",
+    "example:entity-card:server": "npx tsx examples/entity-card/server.ts",
+    "example:embedded-agent": "npx tsx examples/embedded-agent/walkthrough.ts",
     "example:authz-inspector": "npx @modelcontextprotocol/inspector npx tsx examples/authz-inspector/src/stdio.ts",
     "example:authz-inspector:http": "npx tsx examples/authz-inspector/src/inspector-http.ts",
     "example:authz-inspector:http:server": "npx tsx examples/authz-inspector/src/http.ts",
-    "example:authz-inspector:stdio:server": "npx tsx examples/authz-inspector/src/stdio.ts"
+    "example:authz-inspector:stdio:server": "npx tsx examples/authz-inspector/src/stdio.ts",
+    "example:cheqd-dlr": "npx tsx examples/cheqd-dlr/operator-flow.ts"
   },
   "dependencies": {
-    "jose": "^5.6.3",
+    "jose": "^6.2.3",
     "json-canonicalize": "^2.0.0",
     "zod": "^4.3.6"
   },
@@ -98,13 +117,14 @@
     "@kya-os/consent": "^0.1.37",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@types/express": "^5.0.6",
-    "@types/node": "^20.14.9",
+    "@types/node": "^26.0.1",
     "@typescript-eslint/eslint-plugin": "^8.57.0",
     "@typescript-eslint/parser": "^8.57.0",
     "@vitest/coverage-v8": "^2.0.0",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "eslint": "^10.0.3",
     "express": "^5.2.1",
+    "tsx": "^4.22.4",
     "typescript": "^5.5.3",
     "typescript-eslint": "^8.57.0",
     "vitest": "^2.0.0"

package/schemas/README.md

@@ -8,7 +8,8 @@ This directory contains JSON Schema definitions for the core KYA-OS (Model Conte
 |--------|-------------|
 | [handshake-request.json](./handshake-request.json) | Client-initiated session establishment request |
 | [handshake-response.json](./handshake-response.json) | Server response with session context |
-| [delegation-credential.json](./delegation-credential.json) | W3C Verifiable Credential for delegations |
+| [delegation-credential.json](./delegation-credential.json) | W3C Verifiable Credential for delegations (legacy VC 1.0 shape) |
+| [card-delegation-credential.json](./card-delegation-credential.json) | W3C VC 2.0 + ZCAP-LD delegation profile (Entity Card) |
 | [detached-proof.json](./detached-proof.json) | Cryptographic proof for tool request/response |
 | [well-known-kyaos.json](./well-known-kyaos.json) | Service discovery document |
 

package/schemas/card-delegation-credential.json

@@ -0,0 +1,239 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.kya-os.org/v1/protocol/delegation/credential/v1.1.0",
+  "title": "KYA-OS Delegation Credential (W3C VC 2.0 + ZCAP-LD profile)",
+  "description": "A W3C Verifiable Credential 2.0 whose credentialSubject IS an attenuated ZCAP-LD capability. One credential per delegation HOP; a chain runs root -> ... -> leaf. CRISP attenuation is enforced on resolve, fail-closed: a child's allowedAction MUST be a subset of its parent's; caveats are monotone-narrowing (child MaxAmount <= parent, child ValidUntil <= parent, and a parent caveat may never be silently dropped); the parent's delegate (invoker/controller) MUST be the child's issuer; child.parentCapability MUST reference the parent capability id; the invocationTarget is constant along the chain; depth <= 10; and the ROOT's parentCapability equals its invocationTarget with issuer/invocationTarget = the resource owner / resource. responsibleParty is recomputed as the issuer of the root credential; the leaf invoker is asserted equal to the per-request proof key. This schema is a re-profile of the prior draft, not a new artifact.",
+  "type": "object",
+  "required": ["@context", "type", "issuer", "credentialSubject"],
+  "properties": {
+    "@context": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string", "format": "uri" },
+          { "type": "object" }
+        ]
+      },
+      "minItems": 2,
+      "description": "JSON-LD context. MUST include the W3C VC 2.0 context 'https://www.w3.org/ns/credentials/v2' as the first element, the ZCAP-LD context 'https://w3id.org/security/zcap/v1', and the KYA-OS delegation namespace 'https://kya-os.org/ns/delegation/v1'."
+    },
+    "id": {
+      "type": "string",
+      "format": "uri",
+      "description": "Unique credential identifier (URN or URL)."
+    },
+    "type": {
+      "type": "array",
+      "items": { "type": "string" },
+      "contains": { "const": "VerifiableCredential" },
+      "minItems": 2,
+      "description": "Credential types. MUST include 'VerifiableCredential' and 'DelegationCredential'."
+    },
+    "issuer": {
+      "oneOf": [
+        { "type": "string", "pattern": "^did:.+$" },
+        {
+          "type": "object",
+          "required": ["id"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^did:.+$" }
+          }
+        }
+      ],
+      "description": "Delegator DID (or an issuer object carrying id). For the ROOT credential this is the resource owner and the recomputed responsibleParty."
+    },
+    "validFrom": {
+      "type": "string",
+      "format": "date-time",
+      "description": "VC 2.0 validity start (replaces the legacy issuanceDate)."
+    },
+    "validUntil": {
+      "type": "string",
+      "format": "date-time",
+      "description": "VC 2.0 validity end (replaces the legacy expirationDate). A child's validUntil MUST be no later than its parent's (monotone-narrowing)."
+    },
+    "credentialSubject": {
+      "$ref": "#/$defs/ZcapCapability"
+    },
+    "credentialStatus": {
+      "$ref": "#/$defs/CredentialStatus"
+    },
+    "proof": {
+      "$ref": "#/$defs/Proof"
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "ZcapCapability": {
+      "type": "object",
+      "description": "The attenuated ZCAP-LD capability carried as the VC credentialSubject.",
+      "required": ["id", "parentCapability", "invocationTarget", "allowedAction"],
+      "anyOf": [
+        { "required": ["controller"] },
+        { "required": ["invoker"] }
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Capability identifier, typically a 'urn:zcap:*' URN. A child's parentCapability MUST reference this value."
+        },
+        "controller": {
+          "type": "string",
+          "pattern": "^did:.+$",
+          "description": "The delegate DID that controls this capability (synonym of invoker)."
+        },
+        "invoker": {
+          "type": "string",
+          "pattern": "^did:.+$",
+          "description": "The delegate DID authorized to invoke this capability. For the leaf hop this is asserted equal to the per-request proof key (proof.did)."
+        },
+        "parentCapability": {
+          "type": "string",
+          "description": "The parent capability id. For the ROOT hop this MUST equal invocationTarget (the resource itself)."
+        },
+        "invocationTarget": {
+          "type": "string",
+          "description": "The resource DID/URI this capability authorizes. Constant along the whole chain."
+        },
+        "allowedAction": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Permitted action strings. A child's allowedAction MUST be a subset of its parent's (no escalation)."
+        },
+        "caveats": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Caveat" },
+          "description": "Monotone-narrowing constraints accumulated down the chain."
+        }
+      },
+      "additionalProperties": true
+    },
+    "Caveat": {
+      "type": "object",
+      "description": "A monotone-narrowing constraint. A child MUST carry, for every parent caveat, a caveat of the same type that is at least as narrow; unknown caveat types MUST be replicated verbatim (fail-closed).",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Caveat type, e.g. 'ValidUntil' or 'MaxAmount'."
+        },
+        "date": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ValidUntil caveat: the expiry; a child's date MUST be <= its parent's."
+        },
+        "limit": {
+          "type": "string",
+          "description": "MaxAmount caveat: a decimal cap; a child's limit MUST be <= its parent's for the same currency."
+        },
+        "currency": {
+          "type": "string",
+          "description": "MaxAmount caveat: the ISO currency code (e.g. 'USD')."
+        }
+      },
+      "additionalProperties": true
+    },
+    "CredentialStatus": {
+      "type": "object",
+      "description": "W3C Bitstring Status List v1.0 entry (the StatusList2021Entry successor), evaluated through the injected RevocationChecker seam; a revoked ancestor cascades to invalidate the subtree.",
+      "required": ["type", "statusListIndex", "statusListCredential"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uri",
+          "description": "Status entry identifier."
+        },
+        "type": {
+          "type": "string",
+          "const": "BitstringStatusListEntry"
+        },
+        "statusPurpose": {
+          "type": "string",
+          "enum": ["revocation", "suspension"]
+        },
+        "statusListIndex": {
+          "type": "string",
+          "pattern": "^[0-9]+$",
+          "description": "Index in the status-list bitstring."
+        },
+        "statusListCredential": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL of the Bitstring Status List credential."
+        }
+      }
+    },
+    "Proof": {
+      "type": "object",
+      "description": "Data Integrity proof over the credential.",
+      "required": ["type", "cryptosuite"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "DataIntegrityProof"
+        },
+        "cryptosuite": {
+          "type": "string",
+          "const": "eddsa-jcs-2022"
+        },
+        "created": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "verificationMethod": {
+          "type": "string",
+          "description": "DID URL of the verification key."
+        },
+        "proofPurpose": {
+          "type": "string",
+          "description": "Purpose of the proof (e.g., 'assertionMethod')."
+        },
+        "proofValue": {
+          "type": "string",
+          "description": "Multibase-encoded signature value."
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "examples": [
+    {
+      "@context": [
+        "https://www.w3.org/ns/credentials/v2",
+        "https://w3id.org/security/zcap/v1",
+        "https://kya-os.org/ns/delegation/v1"
+      ],
+      "id": "urn:uuid:12345678-1234-1234-1234-123456789abc",
+      "type": ["VerifiableCredential", "DelegationCredential"],
+      "issuer": "did:web:agent-a.example",
+      "validFrom": "2026-03-12T00:00:00Z",
+      "validUntil": "2026-06-01T00:00:00Z",
+      "credentialSubject": {
+        "id": "urn:zcap:del_123",
+        "invoker": "did:web:agent-b.example",
+        "parentCapability": "urn:zcap:root",
+        "invocationTarget": "did:web:api.example:payments",
+        "allowedAction": ["payments.transfer"],
+        "caveats": [
+          { "type": "ValidUntil", "date": "2026-06-01T00:00:00Z" },
+          { "type": "MaxAmount", "limit": "500.00", "currency": "USD" }
+        ]
+      },
+      "credentialStatus": {
+        "id": "https://issuer.example/status/1#94567",
+        "type": "BitstringStatusListEntry",
+        "statusPurpose": "revocation",
+        "statusListIndex": "94567",
+        "statusListCredential": "https://issuer.example/status/1"
+      },
+      "proof": {
+        "type": "DataIntegrityProof",
+        "cryptosuite": "eddsa-jcs-2022",
+        "created": "2026-03-12T00:00:01Z",
+        "verificationMethod": "did:web:agent-a.example#key-1",
+        "proofPurpose": "assertionMethod",
+        "proofValue": "z3FXQ..."
+      }
+    }
+  ]
+}