@kya-os/mcp 1.7.0 → 1.9.0

package/dist/card/builder.js

@@ -0,0 +1,147 @@
+/**
+ * KYA-OS Entity Card — fluent BUILDER (the 10-minute adoption path).
+ *
+ * `card({ did, entityType, name })` opens a fluent chain that accumulates declared facts and
+ * `.build()`s them into an `EntityCard` — a thin, ergonomic front over {@link buildCard} that
+ * hides the card shape behind readable, self-documenting calls:
+ *
+ *   card({ did, entityType: 'agent', name: 'Acme Pay' })
+ *     .capability('search')                              // L1 bare-string capability
+ *     .attestedCapability('payments.transfer', vc)       // L2 attested capability (VC-backed)
+ *     .accountableTo('did:web:acme.example', { via: 'vc_root>del_123' })
+ *     .build();
+ *
+ * Claim-minimal like `buildCard`: it asserts only identity + type + declared capabilities +
+ * accountability locators; trust-bearing claims are PROVEN by the referenced credentials, not
+ * minted here. The infrastructure coordinates it can ALSO carry — `.usesProof()` (proof profile),
+ * `.cimd()`, `.revocation()`, `.didDocument()`, `.publicKey()` — are self-descriptive pointers, not
+ * credential-proven claims, so the ergonomic path can emit a card that plugs into the proof / CIMD /
+ * revocation machinery. `conformanceLevel` is intentionally never set — a verifier RECOMPUTES it.
+ * Pure, no I/O, no crypto: no runtime (`mcp-i-core`) dependency leaks in.
+ */
+import { buildCard } from './build.js';
+import { PROOF_PROFILE_ID } from './schema.js';
+/** The single proof profile a KYA-OS card advertises (holder-of-key, per-request `_meta`). */
+const KYA_OS_PROOF_PROFILE = PROOF_PROFILE_ID;
+/**
+ * A fluent accumulator over one card's declared facts. Mutable + chainable (each method returns
+ * `this`); `.build()` projects the accumulated facts through {@link buildCard}. Prefer the `card()`
+ * factory over `new CardBuilder(...)`.
+ */
+export class CardBuilder {
+    identity;
+    entityType;
+    name;
+    capabilities = [];
+    attestations = [];
+    responsibleParty;
+    principal;
+    delegationRef;
+    proofProfile;
+    cimdBinding;
+    revocationEntry;
+    didDocumentUrl;
+    publicKeyJwk;
+    constructor(init) {
+        this.identity = { did: init.did };
+        if (init.kid !== undefined)
+            this.identity.kid = init.kid;
+        if (init.createdAt !== undefined)
+            this.identity.createdAt = init.createdAt;
+        this.entityType = init.entityType;
+        this.name = init.name;
+    }
+    /** Declare an L1 bare-string capability (self-asserted; a verifier floors it at L1). */
+    capability(name) {
+        this.capabilities.push(name);
+        return this;
+    }
+    /**
+     * Declare an L2 capability backed by an attestation VC. Repeated calls for the SAME capability
+     * name accumulate onto its `attestations[]` (one capability, several proofs) rather than
+     * duplicating the entry.
+     */
+    attestedCapability(name, vc) {
+        const existing = this.findAttested(name);
+        if (existing)
+            existing.attestations.push({ vc });
+        else
+            this.capabilities.push({ name, attestations: [{ vc }] });
+        return this;
+    }
+    /**
+     * Attach a standalone attestation (e.g. a KYC/KYB `IdentityVerification` VC on the responsible
+     * party) that is not tied to a single capability.
+     */
+    attestation(attestation) {
+        this.attestations.push(attestation);
+        return this;
+    }
+    /**
+     * Declare the accountability edge: `responsibleParty` is the ultimately-accountable root (a
+     * KYC-able org), `opts.via` the compact `delegationRef` chain locator, and `opts.principal` the
+     * immediate human delegator. A verifier RECOMPUTES this edge (delegationRef → responsibleParty).
+     */
+    accountableTo(responsibleParty, opts = {}) {
+        this.responsibleParty = responsibleParty;
+        if (opts.via !== undefined)
+            this.delegationRef = opts.via;
+        if (opts.principal !== undefined)
+            this.principal = opts.principal;
+        return this;
+    }
+    /**
+     * Advertise the per-request holder-of-key proof profile (`org.kya-os/proof@1`). This only NAMES
+     * the profile — the proof itself is never on the static card; it rides per-request `_meta`.
+     */
+    usesProof() {
+        this.proofProfile = KYA_OS_PROOF_PROFILE;
+        return this;
+    }
+    /** Bind the L1 CIMD on-ramp coordinates (`client_id` ⇄ `did:web`, `jwks_uri` ⇄ DID keys). */
+    cimd(binding) {
+        this.cimdBinding = binding;
+        return this;
+    }
+    /** Attach the W3C Bitstring Status List revocation entry (the post-issuance kill switch). */
+    revocation(entry) {
+        this.revocationEntry = entry;
+        return this;
+    }
+    /** Record the entity's DID document URL (where the `KyaOsEntityCard` service entry lives). */
+    didDocument(url) {
+        this.didDocumentUrl = url;
+        return this;
+    }
+    /** Inline the entity's Ed25519 public JWK (the card's self-contained verification key). */
+    publicKey(jwk) {
+        this.publicKeyJwk = jwk;
+        return this;
+    }
+    /** Project the accumulated facts into an `EntityCard` (via {@link buildCard}). */
+    build() {
+        return buildCard(this.identity, {
+            entityType: this.entityType,
+            name: this.name,
+            ...(this.capabilities.length > 0 ? { capabilities: this.capabilities } : {}),
+            ...(this.attestations.length > 0 ? { attestations: this.attestations } : {}),
+            ...(this.responsibleParty !== undefined ? { responsibleParty: this.responsibleParty } : {}),
+            ...(this.principal !== undefined ? { principal: this.principal } : {}),
+            ...(this.delegationRef !== undefined ? { delegationRef: this.delegationRef } : {}),
+            ...(this.proofProfile !== undefined ? { proofProfile: this.proofProfile } : {}),
+            ...(this.cimdBinding !== undefined ? { cimd: this.cimdBinding } : {}),
+            ...(this.revocationEntry !== undefined ? { revocation: this.revocationEntry } : {}),
+            ...(this.didDocumentUrl !== undefined ? { didDocument: this.didDocumentUrl } : {}),
+            ...(this.publicKeyJwk !== undefined ? { publicKeyJwk: this.publicKeyJwk } : {}),
+        });
+    }
+    /** Find an already-declared attested capability by name (for attestation accumulation). */
+    findAttested(name) {
+        return this.capabilities.find((c) => typeof c !== 'string' && c.name === name);
+    }
+}
+/** Open a fluent card-building chain (the ergonomic entry point). */
+export function card(init) {
+    return new CardBuilder(init);
+}
+//# sourceMappingURL=builder.js.map

package/dist/card/builder.js.map

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

package/dist/card/cimd.d.ts

@@ -0,0 +1,92 @@
+/**
+ * KYA-OS Entity Card — CIMD L1 on-ramp bind.
+ *
+ * CIMD (draft-ietf-oauth-client-id-metadata-document, the MCP default since 2025-11-25) is
+ * the L1 on-ramp with zero new infra: the OAuth `client_id` IS the entity's `did:web` in its
+ * HTTPS form, and the `jwks_uri` the AS validates `private_key_jwt` against IS a mechanical
+ * projection of the DID document's keys — so OAuth client-authentication becomes a DID-key
+ * proof, and the access token the AS mints can be sender-constrained (RFC 9449 `cnf.jkt`) to
+ * the exact key the per-request holder-of-key proof later carries (closing L1 → L3).
+ *
+ *   - `bindClientId` / `didFromClientId` — the W3C `did:web` ⇄ HTTPS bijection
+ *     (`did:web:host:a:b` ⇄ `https://host/a/b`, the authority colon percent-encoded for ports).
+ *   - `didKeyedJwks`        — DID-document `verificationMethod[]` Ed25519 → an OKP JWK set
+ *     (`kid` preserved), stripping any private `d` and skipping non-Ed25519 methods.
+ *   - `toClientMetadata`    — PROJECT the card into the CIMD doc served at the `client_id` URL
+ *     (`token_endpoint_auth_method: private_key_jwt`, `_meta['org.kya-os/did']` = the DID).
+ *   - `cardFromClientMetadata` — DERIVE the L1 card from a CIMD doc (a pure-CIMD client with
+ *     no DID still onboards: a `did:web` is minted from its `client_id`).
+ *   - `verifyCimdBind`      — the anti-substitution graft, FAIL-CLOSED: origin-equality
+ *     (`did:web` host === `client_id` origin === `jwks_uri` origin) AND a reciprocal
+ *     `alsoKnownAs` bind, so a hostile CIMD pointing `jwks_uri` at someone else's keys (or
+ *     claiming a victim's DID) fails closed.
+ *
+ * Pure + deterministic — no I/O, no crypto. All key material is projected, never minted, so
+ * no runtime (mcp-i-core) dependency leaks into `@kya-os/mcp`.
+ */
+import type { CimdBinding, Ed25519PublicJwk, EntityCard } from './schema.js';
+/** CIMD `token_endpoint_auth_method` — `private_key_jwt` IS the DID-key proof. */
+export declare const PRIVATE_KEY_JWT = "private_key_jwt";
+/** Reverse-DNS `_meta` key carrying the entity's DID inside a CIMD document. */
+export declare const KYA_OS_DID_META_KEY = "org.kya-os/did";
+/** A CIMD (client_id metadata document) projected from / parsed into an EntityCard. */
+export interface ClientMetadata {
+    client_id: string;
+    client_name: string;
+    token_endpoint_auth_method: typeof PRIVATE_KEY_JWT;
+    jwks_uri: string;
+    _meta: Record<typeof KYA_OS_DID_META_KEY, string>;
+}
+/** A JSON Web Key Set — the DID-keyed JWKS served at a CIMD `jwks_uri`. */
+export interface Jwks {
+    keys: Ed25519PublicJwk[];
+}
+/** The fail-closed result of `verifyCimdBind` — `ok` iff there are no `reasons`. */
+export interface CimdBindResult {
+    ok: boolean;
+    reasons: string[];
+}
+/**
+ * Bind a `did:web` to its OAuth `client_id` (the W3C HTTPS form):
+ *   `did:web:host:a:b`        → `https://host/a/b`
+ *   `did:web:host%3A3000:a`   → `https://host:3000/a`   (authority colon percent-decoded)
+ *   `did:web:host`            → `https://host`
+ */
+export declare function bindClientId(did: string): string;
+/**
+ * The inverse of `bindClientId`: an HTTPS `client_id` → its `did:web` (authority colon
+ * percent-encoded for ports). `https://host/a/b` → `did:web:host:a:b`. https-only,
+ * fail-closed.
+ */
+export declare function didFromClientId(clientId: string): string;
+/**
+ * Project a DID document's `verificationMethod[]` into the JWKS the AS validates
+ * `private_key_jwt` against. Only Ed25519 (`OKP`) keys are projected; `kid` is preserved
+ * (the JWK's own `kid`, else the verification method `id`); any private `d` is stripped.
+ */
+export declare function didKeyedJwks(didDoc: unknown): Jwks;
+/**
+ * Project a card into the CIMD document served at its `client_id` URL. The
+ * `token_endpoint_auth_method` is `private_key_jwt` — so the AS validating it against
+ * `jwks_uri` is verifying a DID-key signature.
+ */
+export declare function toClientMetadata(card: EntityCard, opts: {
+    jwksUri: string;
+}): ClientMetadata;
+/**
+ * Derive the L1 card from a CIMD document. The DID is read from `_meta['org.kya-os/did']`
+ * when present, else MINTED from the `client_id` (a pure-CIMD client still onboards). The
+ * card is `entityType: 'client'` and carries the CIMD coordinates when a `jwks_uri` is given.
+ * Fail-closed: the result is validated through `parseCard`.
+ */
+export declare function cardFromClientMetadata(meta: unknown): EntityCard;
+/**
+ * Verify a CIMD binding against the entity's DID document, FAIL-CLOSED. Enforces:
+ *   1. origin-equality — `did:web` host === `client_id` origin === `jwks_uri` origin
+ *      (a hostile CIMD pointing `jwks_uri` at another origin's keys fails here);
+ *   2. a reciprocal `alsoKnownAs` bind — the DID document lists the `client_id` URL, so a
+ *      CIMD cannot unilaterally claim a DID it does not control.
+ * `ok` is true iff there are no `reasons`.
+ */
+export declare function verifyCimdBind(cimd: CimdBinding, didDoc: unknown): CimdBindResult;
+//# sourceMappingURL=cimd.d.ts.map

package/dist/card/cimd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cimd.d.ts","sourceRoot":"","sources":["../../src/card/cimd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK7E,kFAAkF;AAClF,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAIpD,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B,EAAE,OAAO,eAAe,CAAC;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,OAAO,mBAAmB,EAAE,MAAM,CAAC,CAAC;CACnD;AAED,2EAA2E;AAC3E,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,gBAAgB,EAAE,CAAC;CAC1B;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAaxD;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CASlD;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAQ5F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAiBhE;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAG,cAAc,CAqBjF"}

package/dist/card/cimd.js

@@ -0,0 +1,225 @@
+/**
+ * KYA-OS Entity Card — CIMD L1 on-ramp bind.
+ *
+ * CIMD (draft-ietf-oauth-client-id-metadata-document, the MCP default since 2025-11-25) is
+ * the L1 on-ramp with zero new infra: the OAuth `client_id` IS the entity's `did:web` in its
+ * HTTPS form, and the `jwks_uri` the AS validates `private_key_jwt` against IS a mechanical
+ * projection of the DID document's keys — so OAuth client-authentication becomes a DID-key
+ * proof, and the access token the AS mints can be sender-constrained (RFC 9449 `cnf.jkt`) to
+ * the exact key the per-request holder-of-key proof later carries (closing L1 → L3).
+ *
+ *   - `bindClientId` / `didFromClientId` — the W3C `did:web` ⇄ HTTPS bijection
+ *     (`did:web:host:a:b` ⇄ `https://host/a/b`, the authority colon percent-encoded for ports).
+ *   - `didKeyedJwks`        — DID-document `verificationMethod[]` Ed25519 → an OKP JWK set
+ *     (`kid` preserved), stripping any private `d` and skipping non-Ed25519 methods.
+ *   - `toClientMetadata`    — PROJECT the card into the CIMD doc served at the `client_id` URL
+ *     (`token_endpoint_auth_method: private_key_jwt`, `_meta['org.kya-os/did']` = the DID).
+ *   - `cardFromClientMetadata` — DERIVE the L1 card from a CIMD doc (a pure-CIMD client with
+ *     no DID still onboards: a `did:web` is minted from its `client_id`).
+ *   - `verifyCimdBind`      — the anti-substitution graft, FAIL-CLOSED: origin-equality
+ *     (`did:web` host === `client_id` origin === `jwks_uri` origin) AND a reciprocal
+ *     `alsoKnownAs` bind, so a hostile CIMD pointing `jwks_uri` at someone else's keys (or
+ *     claiming a victim's DID) fails closed.
+ *
+ * Pure + deterministic — no I/O, no crypto. All key material is projected, never minted, so
+ * no runtime (mcp-i-core) dependency leaks into `@kya-os/mcp`.
+ */
+import { isRecord } from '../utils/guards.js';
+import { parseCard } from './resolve.js';
+/** The OAuth `client_id` metadata-document prefix this module transforms. */
+const DID_WEB_PREFIX = 'did:web:';
+/** CIMD `token_endpoint_auth_method` — `private_key_jwt` IS the DID-key proof. */
+export const PRIVATE_KEY_JWT = 'private_key_jwt';
+/** Reverse-DNS `_meta` key carrying the entity's DID inside a CIMD document. */
+export const KYA_OS_DID_META_KEY = 'org.kya-os/did';
+// ── client_id ⇄ did:web bijection ─────────────────────────────────────────────
+/**
+ * Bind a `did:web` to its OAuth `client_id` (the W3C HTTPS form):
+ *   `did:web:host:a:b`        → `https://host/a/b`
+ *   `did:web:host%3A3000:a`   → `https://host:3000/a`   (authority colon percent-decoded)
+ *   `did:web:host`            → `https://host`
+ */
+export function bindClientId(did) {
+    if (!did.startsWith(DID_WEB_PREFIX)) {
+        throw new Error(`bindClientId: only did:web has an HTTPS client_id form (got "${did}")`);
+    }
+    const [authority, ...segments] = didWebSegments(did);
+    if (!authority)
+        throw new Error(`bindClientId: did:web "${did}" has no host authority`);
+    const path = segments.length ? `/${segments.join('/')}` : '';
+    return `https://${authority}${path}`;
+}
+/**
+ * The inverse of `bindClientId`: an HTTPS `client_id` → its `did:web` (authority colon
+ * percent-encoded for ports). `https://host/a/b` → `did:web:host:a:b`. https-only,
+ * fail-closed.
+ */
+export function didFromClientId(clientId) {
+    let url;
+    try {
+        url = new URL(clientId);
+    }
+    catch {
+        throw new Error(`didFromClientId: client_id is not a valid URL ("${clientId}")`);
+    }
+    if (url.protocol !== 'https:') {
+        throw new Error(`didFromClientId: client_id must be https (got "${url.protocol}")`);
+    }
+    const authority = encodeURIComponent(url.host);
+    const segments = url.pathname.split('/').filter((s) => s.length > 0).map(encodeURIComponent);
+    return `${DID_WEB_PREFIX}${[authority, ...segments].join(':')}`;
+}
+// ── DID-keyed JWKS ─────────────────────────────────────────────────────────────
+/**
+ * Project a DID document's `verificationMethod[]` into the JWKS the AS validates
+ * `private_key_jwt` against. Only Ed25519 (`OKP`) keys are projected; `kid` is preserved
+ * (the JWK's own `kid`, else the verification method `id`); any private `d` is stripped.
+ */
+export function didKeyedJwks(didDoc) {
+    const vms = isRecord(didDoc) && Array.isArray(didDoc.verificationMethod) ? didDoc.verificationMethod : [];
+    const keys = [];
+    for (const vm of vms) {
+        const jwk = vmToOkpJwk(vm);
+        if (jwk)
+            keys.push(jwk);
+    }
+    return { keys };
+}
+// ── CIMD document projection / derivation ──────────────────────────────────────
+/**
+ * Project a card into the CIMD document served at its `client_id` URL. The
+ * `token_endpoint_auth_method` is `private_key_jwt` — so the AS validating it against
+ * `jwks_uri` is verifying a DID-key signature.
+ */
+export function toClientMetadata(card, opts) {
+    return {
+        client_id: bindClientId(card.id),
+        client_name: card.name,
+        token_endpoint_auth_method: PRIVATE_KEY_JWT,
+        jwks_uri: opts.jwksUri,
+        _meta: { [KYA_OS_DID_META_KEY]: card.id },
+    };
+}
+/**
+ * Derive the L1 card from a CIMD document. The DID is read from `_meta['org.kya-os/did']`
+ * when present, else MINTED from the `client_id` (a pure-CIMD client still onboards). The
+ * card is `entityType: 'client'` and carries the CIMD coordinates when a `jwks_uri` is given.
+ * Fail-closed: the result is validated through `parseCard`.
+ */
+export function cardFromClientMetadata(meta) {
+    if (!isRecord(meta)) {
+        throw new Error('cardFromClientMetadata: client metadata must be an object');
+    }
+    const clientId = meta.client_id;
+    if (typeof clientId !== 'string') {
+        throw new Error('cardFromClientMetadata: missing string client_id');
+    }
+    const did = didFromMeta(meta, clientId);
+    const jwksUri = typeof meta.jwks_uri === 'string' ? meta.jwks_uri : undefined;
+    const card = {
+        id: did,
+        entityType: 'client',
+        name: typeof meta.client_name === 'string' && meta.client_name.length > 0 ? meta.client_name : did,
+    };
+    if (jwksUri !== undefined)
+        card.cimd = { clientId, jwksUri };
+    return parseCard(card);
+}
+// ── Anti-substitution bind (FAIL-CLOSED) ───────────────────────────────────────
+/**
+ * Verify a CIMD binding against the entity's DID document, FAIL-CLOSED. Enforces:
+ *   1. origin-equality — `did:web` host === `client_id` origin === `jwks_uri` origin
+ *      (a hostile CIMD pointing `jwks_uri` at another origin's keys fails here);
+ *   2. a reciprocal `alsoKnownAs` bind — the DID document lists the `client_id` URL, so a
+ *      CIMD cannot unilaterally claim a DID it does not control.
+ * `ok` is true iff there are no `reasons`.
+ */
+export function verifyCimdBind(cimd, didDoc) {
+    const reasons = [];
+    const doc = isRecord(didDoc) ? didDoc : {};
+    const did = typeof doc.id === 'string' ? doc.id : '';
+    const didOrigin = safeDidOrigin(did, reasons);
+    const clientOrigin = safeOrigin(cimd.clientId, 'client_id', reasons);
+    const jwksOrigin = safeOrigin(cimd.jwksUri, 'jwks_uri', reasons);
+    if (didOrigin && clientOrigin && didOrigin !== clientOrigin) {
+        reasons.push(`origin mismatch: did:web (${didOrigin}) !== client_id (${clientOrigin})`);
+    }
+    if (clientOrigin && jwksOrigin && clientOrigin !== jwksOrigin) {
+        reasons.push(`origin mismatch: client_id (${clientOrigin}) !== jwks_uri (${jwksOrigin})`);
+    }
+    if (!aliasListed(doc.alsoKnownAs, cimd.clientId)) {
+        reasons.push(`DID document alsoKnownAs does not list client_id "${cimd.clientId}" (no reciprocal bind)`);
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+// ── Internals ──────────────────────────────────────────────────────────────────
+/** Split a `did:web` into its percent-decoded `:`-separated segments (authority, then path). */
+function didWebSegments(did) {
+    return did.slice(DID_WEB_PREFIX.length).split(':').map(decodeURIComponent);
+}
+/** The DID for a derived card: a declared `_meta['org.kya-os/did']`, else minted from client_id. */
+function didFromMeta(meta, clientId) {
+    const block = isRecord(meta._meta) ? meta._meta : undefined;
+    const declared = block?.[KYA_OS_DID_META_KEY];
+    return typeof declared === 'string' ? declared : didFromClientId(clientId);
+}
+/** Project one verification method to a public OKP JWK (Ed25519 only; `d` stripped), or null. */
+function vmToOkpJwk(vm) {
+    if (!isRecord(vm))
+        return null;
+    const jwk = vm.publicKeyJwk;
+    if (!isRecord(jwk) || jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.x !== 'string') {
+        return null;
+    }
+    const okp = { kty: 'OKP', crv: 'Ed25519', x: jwk.x };
+    const kid = typeof jwk.kid === 'string' ? jwk.kid : typeof vm.id === 'string' ? vm.id : undefined;
+    if (kid !== undefined)
+        okp.kid = kid;
+    return okp;
+}
+/** The HTTPS origin of a `did:web`'s `client_id` form, or null (recording a reason). */
+function safeDidOrigin(did, reasons) {
+    if (!did.startsWith(DID_WEB_PREFIX)) {
+        reasons.push(`DID document id is not a did:web ("${did}")`);
+        return null;
+    }
+    try {
+        return new URL(bindClientId(did)).origin;
+    }
+    catch {
+        reasons.push(`DID document id has no resolvable origin ("${did}")`);
+        return null;
+    }
+}
+/** The HTTPS origin of a URL, or null (recording a reason); non-https fails closed. */
+function safeOrigin(url, label, reasons) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        reasons.push(`${label} is not a valid URL ("${url}")`);
+        return null;
+    }
+    if (parsed.protocol !== 'https:') {
+        reasons.push(`${label} must be https (got "${parsed.protocol}")`);
+        return null;
+    }
+    return parsed.origin;
+}
+/** Whether the DID document's `alsoKnownAs` reciprocally lists the `client_id` URL. */
+function aliasListed(alsoKnownAs, clientId) {
+    if (!Array.isArray(alsoKnownAs))
+        return false;
+    return alsoKnownAs.some((aka) => typeof aka === 'string' && sameUrl(aka, clientId));
+}
+/** Normalized URL equality (tolerant of trailing-slash differences), fail-closed on invalid. */
+function sameUrl(a, b) {
+    try {
+        return new URL(a).href === new URL(b).href;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=cimd.js.map

package/dist/card/cimd.js.map

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

package/dist/card/delegation.d.ts

@@ -0,0 +1,145 @@
+/**
+ * KYA-OS Entity Card — DELEGATION (W3C VC 2.0 + ZCAP-LD profile, CRISP attenuation).
+ *
+ * A DelegationCredential is a W3C VC 2.0 whose `credentialSubject` IS an attenuated ZCAP-LD
+ * capability (`@context` carries `w3id.org/security/zcap/v1` + the KYA-OS delegation namespace).
+ * One credential per HOP; a delegation CHAIN runs `root → … → leaf`. We PROFILE, not fork.
+ *
+ * CRISP attenuation is enforced structurally on resolve and is FAIL-CLOSED — any broadening hop
+ * invalidates the whole chain: child `allowedAction` ⊆ parent; caveats monotone-narrowing (child
+ * `MaxAmount`/`ValidUntil` ≤ parent, no parent caveat silently dropped, unknown caveats replicated
+ * verbatim); top-level `validUntil` narrowing; CONTINUITY (the parent's delegate `invoker` MUST be
+ * the child's `issuer` — you only re-delegate what was delegated to YOUR key — and
+ * `child.parentCapability` references the parent `id`); a constant `invocationTarget`; depth ≤
+ * {@link MAX_DELEGATION_DEPTH}; ROOT `parentCapability` = the resource, `issuer`/`invocationTarget`
+ * = (optional) resource owner / resource. THE JOIN (recomputed, asserted nowhere):
+ * {@link responsiblePartyOf} = `issuer(rootVC)`, {@link leafInvokerOf} = the leaf delegate a verifier
+ * asserts equals `proof.did`. Revocation reuses the injected {@link RevocationChecker} seam from
+ * `./revocation` (no status-list churn reaches callers; NO `mcp-i-core` runtime dep). Per-hop
+ * signature verification is a SEPARATE injected concern; this module owns the CRISP + continuity recompute.
+ */
+import { z } from 'zod';
+import { type BitstringStatusListEntry } from './schema.js';
+import { type RevocationChecker } from './revocation.js';
+export declare const DELEGATION_CONTEXT_V2 = "https://www.w3.org/ns/credentials/v2";
+export declare const ZCAP_CONTEXT = "https://w3id.org/security/zcap/v1";
+export declare const KYA_OS_DELEGATION_CONTEXT = "https://kya-os.org/ns/delegation/v1";
+export declare const DELEGATION_CREDENTIAL_TYPE = "DelegationCredential";
+export declare const MAX_DELEGATION_DEPTH = 10;
+/** A monotone-narrowing constraint: `{type:'ValidUntil',date}` or `{type:'MaxAmount',limit,currency}`.
+ *  The flat shape keeps typing clean; unknown caveat types are compared verbatim (fail-closed). */
+export declare const CaveatSchema: z.ZodObject<{
+    type: z.ZodString;
+    date: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodString>;
+    currency: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** The attenuated ZCAP capability carried as the VC `credentialSubject`. */
+export declare const ZcapCapabilitySchema: z.ZodObject<{
+    id: z.ZodString;
+    controller: z.ZodOptional<z.ZodString>;
+    invoker: z.ZodOptional<z.ZodString>;
+    parentCapability: z.ZodString;
+    invocationTarget: z.ZodString;
+    allowedAction: z.ZodArray<z.ZodString>;
+    caveats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        date: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+/** W3C Bitstring Status List v1.0 `credentialStatus` entry (the StatusList2021 successor). */
+export declare const DelegationCredentialStatusSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"BitstringStatusListEntry">;
+    statusPurpose: z.ZodOptional<z.ZodString>;
+    statusListIndex: z.ZodString;
+    statusListCredential: z.ZodString;
+}, z.core.$strip>;
+/** Data Integrity proof, `eddsa-jcs-2022` cryptosuite (verified by a separate injected seam). */
+export declare const DataIntegrityProofSchema: z.ZodObject<{
+    type: z.ZodLiteral<"DataIntegrityProof">;
+    cryptosuite: z.ZodLiteral<"eddsa-jcs-2022">;
+}, z.core.$loose>;
+export declare const DelegationCredentialSchema: z.ZodObject<{
+    '@context': z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    id: z.ZodOptional<z.ZodString>;
+    type: z.ZodArray<z.ZodString>;
+    issuer: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$loose>]>;
+    validFrom: z.ZodOptional<z.ZodString>;
+    validUntil: z.ZodOptional<z.ZodString>;
+    credentialSubject: z.ZodObject<{
+        id: z.ZodString;
+        controller: z.ZodOptional<z.ZodString>;
+        invoker: z.ZodOptional<z.ZodString>;
+        parentCapability: z.ZodString;
+        invocationTarget: z.ZodString;
+        allowedAction: z.ZodArray<z.ZodString>;
+        caveats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            date: z.ZodOptional<z.ZodString>;
+            limit: z.ZodOptional<z.ZodString>;
+            currency: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>;
+    credentialStatus: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"BitstringStatusListEntry">;
+        statusPurpose: z.ZodOptional<z.ZodString>;
+        statusListIndex: z.ZodString;
+        statusListCredential: z.ZodString;
+    }, z.core.$strip>>;
+    proof: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"DataIntegrityProof">;
+        cryptosuite: z.ZodLiteral<"eddsa-jcs-2022">;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type Caveat = z.infer<typeof CaveatSchema>;
+export type ZcapCapability = z.infer<typeof ZcapCapabilitySchema>;
+export type DelegationCredentialStatus = z.infer<typeof DelegationCredentialStatusSchema>;
+export type DelegationCredential = z.infer<typeof DelegationCredentialSchema>;
+export type DelegationChain = readonly DelegationCredential[];
+/** The issuer (delegator) DID, whether `issuer` is a bare string or an `{id}` object. */
+export declare function issuerDid(vc: DelegationCredential): string;
+/** The delegate DID granted this capability (`invoker`, falling back to `controller`). */
+export declare function invokerDid(vc: DelegationCredential): string | undefined;
+/** `responsibleParty` = the issuer of the ROOT VC (ultimately accountable). */
+export declare function responsiblePartyOf(chain: DelegationChain): string | undefined;
+/** The LEAF invoker — a verifier asserts this equals `proof.did`. */
+export declare function leafInvokerOf(chain: DelegationChain): string | undefined;
+/** Project a hop's `credentialStatus` onto the revocation-seam entry shape (if present). */
+export declare function statusEntryOf(vc: DelegationCredential): BitstringStatusListEntry | undefined;
+/** Reasons the `child` FAILS to attenuate its `parent` (empty ⇒ valid hop): action subset, caveat
+ *  monotonicity, `validUntil` narrowing, invoker→issuer continuity, `parentCapability` linkage,
+ *  constant `invocationTarget`. */
+export declare function attenuates(parent: DelegationCredential, child: DelegationCredential): string[];
+export interface DelegationChainContext {
+    resourceOwner?: string;
+    resource?: string;
+    maxDepth?: number;
+    /** Injectable clock (epoch ms) for the wall-clock expiry gate; default `Date.now` (deterministic tests inject it). */
+    now?: () => number;
+}
+export interface DelegationChainResult {
+    ok: boolean;
+    reasons: string[];
+    responsibleParty?: string;
+    leafInvoker?: string;
+    invocationTarget?: string;
+    allowedAction: string[];
+    depth: number;
+}
+/** Structurally validate a chain (CRISP + continuity), fail-closed. Signature + revocation
+ *  are separate injected concerns (see {@link evaluateDelegationChain}). */
+export declare function validateDelegationChain(chain: DelegationChain, ctx?: DelegationChainContext): DelegationChainResult;
+export interface DelegationChainEvaluation extends DelegationChainResult {
+    fresh: boolean;
+}
+/** Validate structure AND revocation: run {@link validateDelegationChain}, then (only if it passes —
+ *  fail-closed) cascade the injected {@link RevocationChecker} root→leaf via
+ *  {@link evaluateRevocationChain}. A revoked ancestor invalidates the subtree. */
+export declare function evaluateDelegationChain(chain: DelegationChain, check: RevocationChecker, ctx?: DelegationChainContext): Promise<DelegationChainEvaluation>;
+//# sourceMappingURL=delegation.d.ts.map

package/dist/card/delegation.d.ts.map

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