@kya-os/mcp 1.7.0 → 1.9.0

package/dist/card/resolve.d.ts

@@ -0,0 +1,97 @@
+/**
+ * KYA-OS Entity Card — RESOLVE (discovery).
+ *
+ * Discover another entity's card — the conventional, UNAUTHENTICATED half. Discovery
+ * precedes the proof: you need the card's DID (the proof audience) before you can mint a
+ * proof against it.
+ *
+ * The card's canonical home is the `KyaOsEntityCard` service entry on the entity's
+ * `did:web` DID document, NOT a bespoke `/.well-known` file. `resolveCard` is multi-surface:
+ *   - a `did:web` (or `{ did }`) resolves in TWO steps — `did.json` → the `KyaOsEntityCard`
+ *     service entry → `card.json`;
+ *   - `{ cardUrl }` fetches a `card.json` directly (the lazy-fetch target of a `cardRef`);
+ *   - `{ serverMeta }` reads a server.json / catalog `_meta['org.kya-os/card']` entry — a
+ *     `{ 'org.kya-os/cardRef' }` and a `did:web` inline summary DEREFERENCE the entity's canonical
+ *     `card.json` (the summary is a discovery INDEX, its `id` names the DID, never trusted as an
+ *     authoritative card); a `did:key` summary has no web home to dereference, so it is parsed
+ *     directly — fail-closed because the summary carries the `revocation` kill switch and
+ *     `delegationRef` (see `resolveFromServerMeta`);
+ *   - `{ a2a }` follows an A2A AgentExtension's `params.cardUrl`;
+ *   - `{ agentFacts }` two-steps from a NANDA AgentFacts `id` (a `did:web`).
+ *
+ * EVERY outbound fetch goes through the injected `SafeFetch` seam (SSRF-hardened, https-only,
+ * private-range-denied — see `src/utils/safe-fetch.ts`), because resolution now follows
+ * attacker-influenced URLs across four discovery surfaces.
+ */
+import type { SafeFetch } from '../utils/safe-fetch.js';
+import { type EntityCard } from './schema.js';
+/** DID-document `service[].type` string that anchors the card (we own only this string). */
+export declare const KYA_OS_CARD_SERVICE_TYPE = "KyaOsEntityCard";
+/** DID-document `service[].id` fragment for the card service entry. */
+export declare const KYA_OS_CARD_SERVICE_ID = "#kya-os-card";
+/** Reverse-DNS `_meta` key carrying the card (inline summary or a `cardRef`) on MCP surfaces. */
+export declare const KYA_OS_CARD_META_KEY = "org.kya-os/card";
+/** Reverse-DNS key whose value is a lazy-fetch `card.json` URL inside `org.kya-os/card`. */
+export declare const KYA_OS_CARD_REF_KEY = "org.kya-os/cardRef";
+/**
+ * Bare-domain (org-root) card convention. A path-form `did:web:host:a:b` anchors its card at
+ * `/a/b/card.json`, but a BARE `did:web:host` (an org root — e.g. the default trusted issuer
+ * `did:web:example.com`) has no path segment, so its card lives at this well-known path. Defined
+ * ONCE here so `didWebToCardUrl` (emit) and the summary-derive resolve path agree on one URL —
+ * closing the emit/resolve asymmetry that previously locked bare org roots out of the helpers.
+ */
+export declare const KYA_OS_CARD_WELL_KNOWN_PATH = ".well-known/kya-os-card.json";
+/** A non-DID reference form `resolveCard` accepts in addition to a bare `did:web` string. */
+export type CardRef = {
+    did: string;
+} | {
+    cardUrl: string;
+} | {
+    serverMeta: unknown;
+} | {
+    a2a: unknown;
+} | {
+    agentFacts: unknown;
+};
+export type ResolveCardInput = string | CardRef;
+export interface ResolveCardDeps {
+    /** SSRF-hardened fetch seam — every outbound request is routed through it. */
+    fetch: SafeFetch;
+}
+/**
+ * Discover an entity's card from any supported reference form. A `did:web` resolves in two
+ * steps (`did.json` → `KyaOsEntityCard` service → `card.json`); the reference forms short-cut
+ * to the `card.json` URL (or an inline summary). `did:key` has no domain anchor, so a
+ * `did:key` card must be supplied directly (e.g. via `parseCard`), never resolved.
+ *
+ * THROW CONTRACT (fail-closed — deliberately UNLIKE the DID-METHOD resolvers, which return
+ * null so a failed method can be retried): every failure path REJECTS with a reasoned `Error`
+ * (message prefixed `resolveCard:`, or a `ZodError` from `parseCard` on an invalid card body).
+ * `resolveCard` NEVER resolves to `null`/`undefined`. Rationale: this is a security-relevant
+ * verify surface — a silently-null card would let an integrator mistake "couldn't resolve" for
+ * "no card = allow" (fail-open). Integrators MUST wrap the call and treat a throw as a hard
+ * deny. See CONTRIBUTING.md → Code Style for why this surface is scoped out of the null-on-
+ * failure resolver rule.
+ */
+export declare function resolveCard(input: ResolveCardInput, deps: ResolveCardDeps): Promise<EntityCard>;
+/**
+ * Map a `did:web` to its per-entity card URL:
+ *   did:web:host:a:b → https://host/a/b/card.json
+ *   did:web:host     → https://host/.well-known/kya-os-card.json  (the bare org-root convention)
+ *
+ * A bare `did:web:host` (an org root, incl. the default trusted issuer) resolves to the
+ * well-known card path so the trust anchors can publish their own card via the shipped helpers,
+ * and the emit projections agree with the summary-derive resolve path on this one URL. A
+ * non-`did:web` DID (e.g. `did:key`) has no web home, so this throws with actionable guidance:
+ * emit it onto the inline summary + AgentFacts surfaces, or supply an explicit `serviceEndpoint`.
+ */
+export declare function didWebToCardUrl(did: string): string;
+/**
+ * Map a `did:web` to its DID document URL (W3C did:web):
+ *   did:web:host:a:b → https://host/a/b/did.json
+ *   did:web:host     → https://host/.well-known/did.json
+ */
+export declare function didWebToDidDocUrl(did: string): string;
+/** Validate + parse an unknown value into an EntityCard (throws a ZodError on mismatch). */
+export declare function parseCard(value: unknown): EntityCard;
+//# sourceMappingURL=resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/card/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAKhE,4FAA4F;AAC5F,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAC1D,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AACrD,iGAAiG;AACjG,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AACtD,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,uBAAuB,CAAC;AACxD;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,iCAAiC,CAAC;AAE1E,6FAA6F;AAC7F,MAAM,MAAM,OAAO,GACf;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GACf;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACnB;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,GACvB;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,GAChB;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5B,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,KAAK,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,UAAU,CAAC,CASrB;AAmID;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAEpD"}

package/dist/card/resolve.js

@@ -0,0 +1,223 @@
+/**
+ * KYA-OS Entity Card — RESOLVE (discovery).
+ *
+ * Discover another entity's card — the conventional, UNAUTHENTICATED half. Discovery
+ * precedes the proof: you need the card's DID (the proof audience) before you can mint a
+ * proof against it.
+ *
+ * The card's canonical home is the `KyaOsEntityCard` service entry on the entity's
+ * `did:web` DID document, NOT a bespoke `/.well-known` file. `resolveCard` is multi-surface:
+ *   - a `did:web` (or `{ did }`) resolves in TWO steps — `did.json` → the `KyaOsEntityCard`
+ *     service entry → `card.json`;
+ *   - `{ cardUrl }` fetches a `card.json` directly (the lazy-fetch target of a `cardRef`);
+ *   - `{ serverMeta }` reads a server.json / catalog `_meta['org.kya-os/card']` entry — a
+ *     `{ 'org.kya-os/cardRef' }` and a `did:web` inline summary DEREFERENCE the entity's canonical
+ *     `card.json` (the summary is a discovery INDEX, its `id` names the DID, never trusted as an
+ *     authoritative card); a `did:key` summary has no web home to dereference, so it is parsed
+ *     directly — fail-closed because the summary carries the `revocation` kill switch and
+ *     `delegationRef` (see `resolveFromServerMeta`);
+ *   - `{ a2a }` follows an A2A AgentExtension's `params.cardUrl`;
+ *   - `{ agentFacts }` two-steps from a NANDA AgentFacts `id` (a `did:web`).
+ *
+ * EVERY outbound fetch goes through the injected `SafeFetch` seam (SSRF-hardened, https-only,
+ * private-range-denied — see `src/utils/safe-fetch.ts`), because resolution now follows
+ * attacker-influenced URLs across four discovery surfaces.
+ */
+import { isRecord } from '../utils/guards.js';
+import { EntityCardSchema } from './schema.js';
+// ── Canonical discovery constants (co-located in the lowest module so `emit.ts`, which
+//    builds these surfaces, can depend on `resolve.ts` one-way without an import cycle) ──
+/** DID-document `service[].type` string that anchors the card (we own only this string). */
+export const KYA_OS_CARD_SERVICE_TYPE = 'KyaOsEntityCard';
+/** DID-document `service[].id` fragment for the card service entry. */
+export const KYA_OS_CARD_SERVICE_ID = '#kya-os-card';
+/** Reverse-DNS `_meta` key carrying the card (inline summary or a `cardRef`) on MCP surfaces. */
+export const KYA_OS_CARD_META_KEY = 'org.kya-os/card';
+/** Reverse-DNS key whose value is a lazy-fetch `card.json` URL inside `org.kya-os/card`. */
+export const KYA_OS_CARD_REF_KEY = 'org.kya-os/cardRef';
+/**
+ * Bare-domain (org-root) card convention. A path-form `did:web:host:a:b` anchors its card at
+ * `/a/b/card.json`, but a BARE `did:web:host` (an org root — e.g. the default trusted issuer
+ * `did:web:example.com`) has no path segment, so its card lives at this well-known path. Defined
+ * ONCE here so `didWebToCardUrl` (emit) and the summary-derive resolve path agree on one URL —
+ * closing the emit/resolve asymmetry that previously locked bare org roots out of the helpers.
+ */
+export const KYA_OS_CARD_WELL_KNOWN_PATH = '.well-known/kya-os-card.json';
+/**
+ * Discover an entity's card from any supported reference form. A `did:web` resolves in two
+ * steps (`did.json` → `KyaOsEntityCard` service → `card.json`); the reference forms short-cut
+ * to the `card.json` URL (or an inline summary). `did:key` has no domain anchor, so a
+ * `did:key` card must be supplied directly (e.g. via `parseCard`), never resolved.
+ *
+ * THROW CONTRACT (fail-closed — deliberately UNLIKE the DID-METHOD resolvers, which return
+ * null so a failed method can be retried): every failure path REJECTS with a reasoned `Error`
+ * (message prefixed `resolveCard:`, or a `ZodError` from `parseCard` on an invalid card body).
+ * `resolveCard` NEVER resolves to `null`/`undefined`. Rationale: this is a security-relevant
+ * verify surface — a silently-null card would let an integrator mistake "couldn't resolve" for
+ * "no card = allow" (fail-open). Integrators MUST wrap the call and treat a throw as a hard
+ * deny. See CONTRIBUTING.md → Code Style for why this surface is scoped out of the null-on-
+ * failure resolver rule.
+ */
+export async function resolveCard(input, deps) {
+    const { fetch } = deps;
+    if (typeof input === 'string')
+        return resolveDidWeb(input, fetch);
+    if ('did' in input)
+        return resolveDidWeb(input.did, fetch);
+    if ('cardUrl' in input)
+        return fetchCard(input.cardUrl, fetch);
+    if ('serverMeta' in input)
+        return resolveFromServerMeta(input.serverMeta, fetch);
+    if ('a2a' in input)
+        return fetchCard(cardUrlFromA2A(input.a2a), fetch);
+    if ('agentFacts' in input)
+        return resolveDidWeb(didFromAgentFacts(input.agentFacts), fetch);
+    throw new Error('resolveCard: unrecognized reference form');
+}
+/** Two-step `did:web` resolution: `did.json` → `KyaOsEntityCard` service → `card.json`. */
+async function resolveDidWeb(did, fetch) {
+    if (!did.startsWith('did:web:')) {
+        throw new Error(`resolveCard: only did:web is resolvable (got "${did}"); supply a did:key card directly`);
+    }
+    const didDoc = await fetchJson(didWebToDidDocUrl(did), fetch);
+    return fetchCard(cardEndpointFromDidDoc(didDoc, did), fetch, did);
+}
+/**
+ * Read a server.json / catalog `_meta` block and resolve it fail-closed. An explicit
+ * `org.kya-os/cardRef` is a lazy-fetch URL; an inline summary is a discovery INDEX handled by
+ * `resolveInlineSummary` (dereference for `did:web`, parse-in-place for `did:key`).
+ */
+async function resolveFromServerMeta(serverMeta, fetch) {
+    const entry = isRecord(serverMeta) ? serverMeta[KYA_OS_CARD_META_KEY] : undefined;
+    if (entry === undefined) {
+        throw new Error(`resolveCard: serverMeta has no "${KYA_OS_CARD_META_KEY}" entry`);
+    }
+    const ref = isRecord(entry) ? entry[KYA_OS_CARD_REF_KEY] : undefined;
+    if (typeof ref === 'string')
+        return fetchCard(ref, fetch);
+    return resolveInlineSummary(entry, fetch);
+}
+/**
+ * Resolve an inline `_meta` summary fail-closed. A `did:web` summary is a discovery INDEX: its
+ * `id` names the DID, so we DEREFERENCE the canonical `card.json` and never trust the (claim-
+ * minimal) summary as a first-class card — landing back on the one authoritative source that
+ * carries `revocation`/`delegationRef`/`attestations`, so a revoked card cannot fail open. A
+ * `did:key` id has NO web home to dereference, so the summary is parsed directly; this stays
+ * fail-closed because the summary now carries the `revocation` kill switch and `delegationRef`
+ * (the projection is self-verifiable), so `verifyCard`'s status-list checker is still consulted
+ * and a revoked `did:key` card verifies `ok:false`.
+ *
+ * SECURITY (§12.6): the `did:key` branch trusts the *presented* summary — a `did:key` has no
+ * origin-served `card.json` to dereference, so an intermediary that strips `revocation` from an
+ * unsigned `did:key` summary can hide a revocation. `did:web` is REQUIRED for revocable Entities.
+ */
+async function resolveInlineSummary(entry, fetch) {
+    const id = isRecord(entry) ? entry.id : undefined;
+    if (typeof id !== 'string') {
+        throw new Error(`resolveCard: inline "${KYA_OS_CARD_META_KEY}" summary has no string id (DID)`);
+    }
+    if (id.startsWith('did:web:'))
+        return fetchCard(didWebToCardUrl(id), fetch, id);
+    return parseCard(entry);
+}
+/** Locate the `KyaOsEntityCard` service entry's endpoint on a DID document (fail-closed). */
+function cardEndpointFromDidDoc(didDoc, did) {
+    const services = isRecord(didDoc) && Array.isArray(didDoc.service) ? didDoc.service : [];
+    for (const svc of services) {
+        if (isRecord(svc) &&
+            svc.type === KYA_OS_CARD_SERVICE_TYPE &&
+            typeof svc.serviceEndpoint === 'string') {
+            return svc.serviceEndpoint;
+        }
+    }
+    throw new Error(`resolveCard: DID document for "${did}" has no ${KYA_OS_CARD_SERVICE_TYPE} service entry`);
+}
+/** Pull the `card.json` URL out of an A2A AgentExtension's `params.cardUrl` (fail-closed). */
+function cardUrlFromA2A(a2a) {
+    const params = isRecord(a2a) ? a2a.params : undefined;
+    const cardUrl = isRecord(params) ? params.cardUrl : undefined;
+    if (typeof cardUrl !== 'string') {
+        throw new Error('resolveCard: A2A extension has no string params.cardUrl');
+    }
+    return cardUrl;
+}
+/** Pull the agent DID out of a NANDA AgentFacts document's `id` (fail-closed). */
+function didFromAgentFacts(agentFacts) {
+    const id = isRecord(agentFacts) ? agentFacts.id : undefined;
+    if (typeof id !== 'string') {
+        throw new Error('resolveCard: AgentFacts has no string id (DID)');
+    }
+    return id;
+}
+/** GET a URL through the SafeFetch seam and return its parsed JSON (throws on non-2xx). */
+async function fetchJson(url, fetch) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`resolveCard: GET ${url} → ${res.status}`);
+    return res.json();
+}
+/**
+ * GET a `card.json` URL and validate it into an `EntityCard`. When `expectedDid` is supplied — every
+ * DID-anchored resolve path (`did:web` two-step, inline `did:web` summary, AgentFacts) — BIND the
+ * fetched card to it: its `id` MUST equal that DID (normalized), else FAIL CLOSED. This closes the
+ * cross-origin confusion where a DID document's `KyaOsEntityCard` service entry points at a card for
+ * a DIFFERENT DID (or a compromised third-party endpoint), which would otherwise attribute another
+ * entity's claims/capabilities to the resolved DID. The `{ cardUrl }` and A2A paths carry no
+ * independent DID to bind against, so they pass no `expectedDid` (the URL itself is the trust root).
+ */
+async function fetchCard(url, fetch, expectedDid) {
+    const card = parseCard(await fetchJson(url, fetch));
+    if (expectedDid !== undefined && normalizeDid(card.id) !== normalizeDid(expectedDid)) {
+        throw new Error(`resolveCard: resolved card id "${card.id}" ≠ requested DID "${expectedDid}" (identity mismatch) — fail-closed`);
+    }
+    return card;
+}
+/** Decompose a `did:web` into its host + slash-joined path segments. */
+function parseDidWeb(did) {
+    const parts = did.slice('did:web:'.length).split(':').map(decodeURIComponent);
+    return { host: parts[0] ?? '', path: parts.slice(1).join('/') };
+}
+/**
+ * Canonicalize a DID for identity comparison. For `did:web` the DNS host is case-INsensitive and the
+ * segments are percent-decoded (reusing {@link parseDidWeb}), so `did:web:Example.com` binds to
+ * `did:web:example.com`; other DID methods (e.g. `did:key`, case-sensitive base58) compare verbatim.
+ */
+function normalizeDid(did) {
+    if (!did.startsWith('did:web:'))
+        return did;
+    const { host, path } = parseDidWeb(did);
+    const base = `did:web:${host.toLowerCase()}`;
+    return path ? `${base}:${path.split('/').join(':')}` : base;
+}
+/**
+ * Map a `did:web` to its per-entity card URL:
+ *   did:web:host:a:b → https://host/a/b/card.json
+ *   did:web:host     → https://host/.well-known/kya-os-card.json  (the bare org-root convention)
+ *
+ * A bare `did:web:host` (an org root, incl. the default trusted issuer) resolves to the
+ * well-known card path so the trust anchors can publish their own card via the shipped helpers,
+ * and the emit projections agree with the summary-derive resolve path on this one URL. A
+ * non-`did:web` DID (e.g. `did:key`) has no web home, so this throws with actionable guidance:
+ * emit it onto the inline summary + AgentFacts surfaces, or supply an explicit `serviceEndpoint`.
+ */
+export function didWebToCardUrl(did) {
+    if (!did.startsWith('did:web:')) {
+        throw new Error(`didWebToCardUrl: only a did:web has a web card URL (got "${did}"); a did:key card has no web home — emit it onto the inline summary + AgentFacts surfaces, or supply an explicit serviceEndpoint`);
+    }
+    const { host, path } = parseDidWeb(did);
+    return path ? `https://${host}/${path}/card.json` : `https://${host}/${KYA_OS_CARD_WELL_KNOWN_PATH}`;
+}
+/**
+ * Map a `did:web` to its DID document URL (W3C did:web):
+ *   did:web:host:a:b → https://host/a/b/did.json
+ *   did:web:host     → https://host/.well-known/did.json
+ */
+export function didWebToDidDocUrl(did) {
+    const { host, path } = parseDidWeb(did);
+    return path ? `https://${host}/${path}/did.json` : `https://${host}/.well-known/did.json`;
+}
+/** Validate + parse an unknown value into an EntityCard (throws a ZodError on mismatch). */
+export function parseCard(value) {
+    return EntityCardSchema.parse(value);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/card/resolve.js.map

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

package/dist/card/revocation.d.ts

@@ -0,0 +1,96 @@
+/**
+ * KYA-OS Entity Card — REVOCATION seam (W3C Bitstring Status List v1.0).
+ *
+ * Capability + delegation credentials are revocable, so a verifier must be able to ask "is
+ * THIS credential still live?" without the question's shape leaking into callers. This module
+ * ships that question as a pluggable seam — `RevocationChecker` — so the VC-2.0 / status-list
+ * churn stays behind one interface (the same injected-seam discipline `verifyCard` already
+ * uses for its capability / attestation / accountability verifiers; NO `mcp-i-core` runtime
+ * dependency leaks into `@kya-os/mcp`).
+ *
+ * `createRevocationChecker` is the DEFAULT implementation over W3C Bitstring Status List v1.0
+ * (`BitstringStatusListEntry` — the StatusList2021 SUCCESSOR). It resolves the entry's
+ * `statusListCredential` through the injected, SSRF-hardened {@link SafeFetch} seam, inflates
+ * the multibase / GZIP `encodedList` bitstring, and reads the bit at `statusListIndex`.
+ *
+ * FAIL-CLOSED is the invariant: an unreachable status list, a malformed credential, a
+ * mismatched `statusPurpose`, or an out-of-range index all resolve to `{ revoked: true }` —
+ * the absence of proof-of-liveness is treated as revoked, never as "probably fine".
+ *
+ * Each verdict also reports `fresh`: `true` only when read from a LIVE, in-validity-window
+ * status list. A stale (past `validUntil`) or not-yet-valid list still yields a readable bit
+ * but `fresh: false`. {@link evaluateRevocationChain} walks a delegation chain root→leaf and
+ * fail-closes (cascading: a revoked parent invalidates the whole subtree) on the first
+ * revoked/unresolvable hop, threading `fresh` through every hop. The caller decides the gate:
+ * L2 accepts a non-revoked chain (cached / offline-verifiable); L3 additionally requires
+ * `fresh` (a live status check). NOT wired into `verifyCard` here — a later step injects it.
+ */
+import type { SafeFetch } from '../utils/safe-fetch.js';
+import type { BitstringStatusListEntry } from './schema.js';
+/** The `statusPurpose` this checker evaluates by default (revocation, not suspension). */
+export declare const STATUS_PURPOSE_REVOCATION = "revocation";
+/**
+ * Inflate a GZIP `encodedList` payload to the raw status bitstring. The seam that keeps this
+ * verifier ISOMORPHIC: the default is Node-only (`node:zlib`), but a Workers / Deno / browser
+ * deployment injects a `DecompressionStream`-based impl so the bundle never pulls `node:zlib`.
+ * MAY be sync or async; MUST reject (throw / reject) on non-inflatable input (fail-closed).
+ */
+export type Decompress = (bytes: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+/** Verdict for ONE status entry. */
+export interface RevocationStatus {
+    /** True iff the status bit is set OR the status could not be proven clear (fail-closed). */
+    revoked: boolean;
+    /** True iff read from a LIVE, in-validity-window status list (drives the L2/L3 gate). */
+    fresh: boolean;
+}
+/**
+ * The injected revocation seam: resolve a `BitstringStatusListEntry` to a {@link RevocationStatus}.
+ * A runtime supplies an implementation (the default is {@link createRevocationChecker}); a
+ * caller may inject a cache-backed or offline variant. Implementations MUST fail closed.
+ */
+export type RevocationChecker = (entry: BitstringStatusListEntry) => Promise<RevocationStatus>;
+/** Result of a cascading root→leaf chain walk. */
+export interface RevocationChainResult {
+    /** True iff EVERY hop is non-revoked (fail-closed: any revoked/unresolvable hop ⇒ false). */
+    ok: boolean;
+    /** True iff EVERY checked hop was read from a live, in-window status list. */
+    fresh: boolean;
+    /** Fail-closed reasons (empty ⇒ ok). */
+    reasons: string[];
+}
+/** Dependencies for the default Bitstring Status List v1.0 checker. */
+export interface RevocationCheckerDeps {
+    /** SSRF-hardened fetch seam used to resolve the `statusListCredential`. */
+    fetch: SafeFetch;
+    /** Injectable clock returning epoch MILLISECONDS (deterministic freshness tests). */
+    now?: () => number;
+    /** `statusPurpose` to honour; default {@link STATUS_PURPOSE_REVOCATION}. */
+    statusPurpose?: string;
+    /**
+     * Injectable GZIP inflation seam ({@link Decompress}). DEFAULT = `node:zlib` `gunzipSync` bounded
+     * to the 16 MiB {@link MAX_STATUS_LIST_BYTES} `maxOutputLength` cap (so a decompression bomb
+     * THROWS mid-inflation ⇒ fail-closed, never allocating the whole payload). Non-Node runtimes
+     * inject a `DecompressionStream`-based impl; when they do, the default is never referenced so a
+     * bundler tree-shakes `node:zlib` out of the graph. An injected impl SHOULD bound its own output
+     * — {@link decodeStatusList} still applies the cap as a post-inflation backstop regardless.
+     */
+    decompress?: Decompress;
+}
+/**
+ * Build the default `RevocationChecker` over W3C Bitstring Status List v1.0. Every outbound
+ * request rides the injected {@link SafeFetch}; any failure on the path (unreachable, non-2xx,
+ * malformed, wrong purpose, out-of-range index) resolves {@link FAIL_CLOSED}.
+ */
+export declare function createRevocationChecker(deps: RevocationCheckerDeps): RevocationChecker;
+/**
+ * Walk a delegation/capability chain root→leaf and fail-close on the first revoked or
+ * unresolvable hop (cascading — a revoked ancestor invalidates the subtree, so the walk
+ * short-circuits). `fresh` is the AND of every checked hop's liveness.
+ *
+ * An empty set of status entries is trivially `ok` (nothing is revoked — an offline/L2-acceptable
+ * verdict) but is NOT `fresh`: freshness is a LIVE-check signal, and zero checks obtained no live
+ * signal. An L3 liveness gate that requires `fresh` therefore cannot be satisfied by a chain that
+ * simply omits all `credentialStatus` entries — it must consult at least one live status list.
+ */
+export declare function evaluateRevocationChain(entries: readonly BitstringStatusListEntry[], check: RevocationChecker): Promise<RevocationChainResult>;
+//# sourceMappingURL=revocation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"revocation.d.ts","sourceRoot":"","sources":["../../src/card/revocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE5D,0FAA0F;AAC1F,eAAO,MAAM,yBAAyB,eAAe,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAcjF,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,4FAA4F;IAC5F,OAAO,EAAE,OAAO,CAAC;IACjB,yFAAyF;IACzF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,wBAAwB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/F,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,EAAE,EAAE,OAAO,CAAC;IACZ,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,KAAK,EAAE,SAAS,CAAC;IACjB,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAKD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CAetF;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,SAAS,wBAAwB,EAAE,EAC5C,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,qBAAqB,CAAC,CAiBhC"}

package/dist/card/revocation.js

@@ -0,0 +1,190 @@
+/**
+ * KYA-OS Entity Card — REVOCATION seam (W3C Bitstring Status List v1.0).
+ *
+ * Capability + delegation credentials are revocable, so a verifier must be able to ask "is
+ * THIS credential still live?" without the question's shape leaking into callers. This module
+ * ships that question as a pluggable seam — `RevocationChecker` — so the VC-2.0 / status-list
+ * churn stays behind one interface (the same injected-seam discipline `verifyCard` already
+ * uses for its capability / attestation / accountability verifiers; NO `mcp-i-core` runtime
+ * dependency leaks into `@kya-os/mcp`).
+ *
+ * `createRevocationChecker` is the DEFAULT implementation over W3C Bitstring Status List v1.0
+ * (`BitstringStatusListEntry` — the StatusList2021 SUCCESSOR). It resolves the entry's
+ * `statusListCredential` through the injected, SSRF-hardened {@link SafeFetch} seam, inflates
+ * the multibase / GZIP `encodedList` bitstring, and reads the bit at `statusListIndex`.
+ *
+ * FAIL-CLOSED is the invariant: an unreachable status list, a malformed credential, a
+ * mismatched `statusPurpose`, or an out-of-range index all resolve to `{ revoked: true }` —
+ * the absence of proof-of-liveness is treated as revoked, never as "probably fine".
+ *
+ * Each verdict also reports `fresh`: `true` only when read from a LIVE, in-validity-window
+ * status list. A stale (past `validUntil`) or not-yet-valid list still yields a readable bit
+ * but `fresh: false`. {@link evaluateRevocationChain} walks a delegation chain root→leaf and
+ * fail-closes (cascading: a revoked parent invalidates the whole subtree) on the first
+ * revoked/unresolvable hop, threading `fresh` through every hop. The caller decides the gate:
+ * L2 accepts a non-revoked chain (cached / offline-verifiable); L3 additionally requires
+ * `fresh` (a live status check). NOT wired into `verifyCard` here — a later step injects it.
+ */
+import { base64urlDecodeToBytes } from '../utils/base64.js';
+import { isRecord } from '../utils/guards.js';
+import { assertStatusPurpose } from '../utils/statuslist-purpose.js';
+/** The `statusPurpose` this checker evaluates by default (revocation, not suspension). */
+export const STATUS_PURPOSE_REVOCATION = 'revocation';
+/** Multibase prefix for an unpadded base64url payload (W3C Bitstring Status List `encodedList`). */
+const MULTIBASE_BASE64URL = 'u';
+/**
+ * Hard ceiling on the INFLATED status bitstring (16 MiB ⇒ ~134M entries — far beyond any
+ * herd-privacy list). A status bitstring is fixed-size, so a generous fixed cap costs nothing
+ * legitimate while stopping a decompression bomb: without it, the ~786 KB of GZIP that fits
+ * inside SafeFetch's 1 MiB body cap inflates to ~800 MB, blocking the event loop on a synchronous
+ * `gunzipSync`. Exceeding the cap makes `gunzipSync` throw, which the checker converts to
+ * FAIL_CLOSED — preserving the module's uniform fail-closed posture. */
+const MAX_STATUS_LIST_BYTES = 16 * 1024 * 1024;
+/** Fail-closed verdict: status indeterminate ⇒ treat as revoked AND not fresh. */
+const FAIL_CLOSED = { revoked: true, fresh: false };
+/**
+ * Build the default `RevocationChecker` over W3C Bitstring Status List v1.0. Every outbound
+ * request rides the injected {@link SafeFetch}; any failure on the path (unreachable, non-2xx,
+ * malformed, wrong purpose, out-of-range index) resolves {@link FAIL_CLOSED}.
+ */
+export function createRevocationChecker(deps) {
+    const clock = deps.now ?? (() => Date.now());
+    const wantedPurpose = deps.statusPurpose ?? STATUS_PURPOSE_REVOCATION;
+    const decompress = deps.decompress ?? defaultNodeGunzip;
+    return async function check(entry) {
+        try {
+            const credential = await fetchStatusList(entry.statusListCredential, deps.fetch);
+            assertStatusPurpose(statusListSubject(credential).statusPurpose, wantedPurpose);
+            const bits = await decodeStatusList(credential, decompress);
+            const revoked = readBit(bits, parseIndex(entry.statusListIndex));
+            return { revoked, fresh: isLive(credential, clock()) };
+        }
+        catch {
+            return FAIL_CLOSED;
+        }
+    };
+}
+/**
+ * Walk a delegation/capability chain root→leaf and fail-close on the first revoked or
+ * unresolvable hop (cascading — a revoked ancestor invalidates the subtree, so the walk
+ * short-circuits). `fresh` is the AND of every checked hop's liveness.
+ *
+ * An empty set of status entries is trivially `ok` (nothing is revoked — an offline/L2-acceptable
+ * verdict) but is NOT `fresh`: freshness is a LIVE-check signal, and zero checks obtained no live
+ * signal. An L3 liveness gate that requires `fresh` therefore cannot be satisfied by a chain that
+ * simply omits all `credentialStatus` entries — it must consult at least one live status list.
+ */
+export async function evaluateRevocationChain(entries, check) {
+    let fresh = entries.length > 0; // no entries ⇒ no live signal ⇒ not fresh (fail-closed for L3)
+    for (const [hop, entry] of entries.entries()) {
+        const status = await check(entry);
+        fresh = fresh && status.fresh;
+        if (status.revoked) {
+            return {
+                ok: false,
+                fresh: false,
+                reasons: [
+                    `revocation: hop ${hop} (${entry.statusListCredential}#${entry.statusListIndex}) ` +
+                        'is revoked or unresolvable — fail-closed, subtree invalidated',
+                ],
+            };
+        }
+    }
+    return { ok: true, fresh, reasons: [] };
+}
+// ── Internals ──────────────────────────────────────────────────────────────────
+/** GET the status-list credential through SafeFetch (throws on non-2xx / non-object body). */
+async function fetchStatusList(url, fetch) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`revocation: status-list GET ${url} → ${res.status}`);
+    const body = await res.json();
+    if (!isRecord(body))
+        throw new Error('revocation: status-list credential is not an object');
+    return body;
+}
+/** The `credentialSubject` of a status-list credential (throws if absent). */
+function statusListSubject(credential) {
+    const subject = credential.credentialSubject;
+    if (!isRecord(subject))
+        throw new Error('revocation: status-list has no credentialSubject');
+    return subject;
+}
+/**
+ * DEFAULT {@link Decompress}: `node:zlib` `gunzipSync` bounded to {@link MAX_STATUS_LIST_BYTES}
+ * so an oversized inflation THROWS mid-stream (fail-closed) instead of allocating the whole bomb.
+ * Pulled in via a DYNAMIC `import('node:zlib')` — only when no `decompress` was injected — so a
+ * Workers / Deno / browser bundle that supplies its own seam keeps `node:zlib` out of the graph.
+ */
+async function defaultNodeGunzip(bytes) {
+    const { gunzipSync } = await import('node:zlib');
+    return new Uint8Array(gunzipSync(bytes, { maxOutputLength: MAX_STATUS_LIST_BYTES }));
+}
+/**
+ * Inflate the multibase / GZIP `encodedList` into the raw status bitstring bytes through the
+ * injected {@link Decompress} seam. The 16 MiB cap is re-checked here as a POST-inflation backstop:
+ * the default gunzip caps mid-stream, but an injected (edge) decompressor that does not bound its
+ * own output is still fail-closed against an oversized bitstring at this seam.
+ */
+async function decodeStatusList(credential, decompress) {
+    const encoded = statusListSubject(credential).encodedList;
+    if (typeof encoded !== 'string' || encoded.length === 0) {
+        throw new Error('revocation: status-list has no encodedList');
+    }
+    const base64url = encoded[0] === MULTIBASE_BASE64URL ? encoded.slice(1) : encoded;
+    const inflated = await decompress(base64urlDecodeToBytes(base64url));
+    if (inflated.length > MAX_STATUS_LIST_BYTES) {
+        throw new Error(`revocation: status list too large: ${inflated.length} bytes exceeds ${MAX_STATUS_LIST_BYTES}`);
+    }
+    return inflated instanceof Uint8Array ? inflated : new Uint8Array(inflated);
+}
+/**
+ * Parse the decimal `statusListIndex` (a non-negative integer expressed as a string), fail-closed.
+ * MUST be canonical decimal only: `Number()` alone would coerce whitespace (`" "` → 0), hex
+ * (`"0x2A"` → 42), octal, `"+42"`, and `"1e1"` → 10 — silently reading a DIFFERENT (often clear) bit
+ * than the credential names, so a revoked credential could read as live. Reject anything that is not
+ * `[0-9]+`.
+ */
+function parseIndex(raw) {
+    if (!/^[0-9]+$/.test(raw)) {
+        throw new Error(`revocation: statusListIndex must be a canonical non-negative decimal (got "${raw}")`);
+    }
+    const index = Number(raw);
+    if (!Number.isSafeInteger(index) || index < 0) {
+        throw new Error(`revocation: statusListIndex out of range "${raw}"`);
+    }
+    return index;
+}
+/**
+ * Read the status bit at `index` — MSB-first within each byte (W3C Bitstring encoding).
+ * Uses FULL-PRECISION arithmetic (`Math.floor(index / 8)`, `index % 8`) rather than the 32-bit
+ * bitwise ops `>>>`/`&`, which coerce their operand to uint32 first: an index ≥ 2^32 would
+ * silently wrap onto a low byte (e.g. 2^32+5 ⇒ byte 0, bit 5) and read the WRONG — often clear —
+ * bit, turning an out-of-range index that MUST fail-closed into a fail-OPEN "not revoked". With
+ * full-precision arithmetic an out-of-range byte offset indexes past the bitstring, yielding
+ * `undefined` ⇒ throw ⇒ FAIL_CLOSED. */
+function readBit(bits, index) {
+    const byte = bits[Math.floor(index / 8)];
+    if (byte === undefined) {
+        throw new Error(`revocation: statusListIndex ${index} is out of range for the status list`);
+    }
+    return (byte & (0x80 >> (index % 8))) !== 0;
+}
+/** True iff `nowMs` falls inside the credential's `[validFrom, validUntil]` window (if declared). */
+function isLive(credential, nowMs) {
+    const validUntil = parseDate(credential.validUntil ?? credential.expirationDate);
+    if (validUntil !== undefined && validUntil < nowMs)
+        return false; // stale → cached-OK at L2 only
+    const validFrom = parseDate(credential.validFrom ?? credential.issuanceDate);
+    if (validFrom !== undefined && validFrom > nowMs)
+        return false; // not yet valid
+    return true;
+}
+/** Parse an ISO-8601 date string to epoch ms, or `undefined` when absent / unparseable. */
+function parseDate(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? undefined : ms;
+}
+//# sourceMappingURL=revocation.js.map

package/dist/card/revocation.js.map

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