@proof-holdings/delegation-verifier 0.1.0

package/dist/publication.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Verifying the delegation a card publishes.
+ *
+ * The carrier layout itself lives in `carriers.ts` (kept crypto-free so it can be read without
+ * pulling in the verification machinery); this module is the part that decides.
+ */
+import type { VerificationResult, VerifyOptions } from './types.js';
+export { DELEGATION_META_KEY, DELEGATION_EXTENSION_URI, REGISTRY_PUBLISHER_PROVIDED_KEY, extractDelegationPublications, parseDelegationPointer, pointerRecordName, POINTER_VERSION, POINTER_RECORD_PREFIX, } from './carriers.js';
+export type { FoundPublication, PointerParseResult, PointerRejection } from './carriers.js';
+/**
+ * Verify the delegation an MCP server card or A2A agent card publishes.
+ *
+ * `options.delegate` still means what it means everywhere else: the artifact identity YOU
+ * resolved — the npm package you are about to install, the endpoint you are about to call —
+ * NOT a field read out of this card. A card that describes itself is not evidence about
+ * itself.
+ */
+export declare function verifyPublishedDelegation(card: unknown, options: VerifyOptions): Promise<VerificationResult>;
+//# sourceMappingURL=publication.d.ts.map

package/dist/publication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publication.d.ts","sourceRoot":"","sources":["../src/publication.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGpE,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,+BAA+B,EAC/B,6BAA6B,EAC7B,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE5F;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAmB7B"}

package/dist/publication.js

@@ -0,0 +1,39 @@
+/**
+ * Verifying the delegation a card publishes.
+ *
+ * The carrier layout itself lives in `carriers.ts` (kept crypto-free so it can be read without
+ * pulling in the verification machinery); this module is the part that decides.
+ */
+import { collectPublishedTokens } from './carriers.js';
+import { classifyFailureReason } from './types.js';
+import { verifyDelegation } from './verify.js';
+export { DELEGATION_META_KEY, DELEGATION_EXTENSION_URI, REGISTRY_PUBLISHER_PROVIDED_KEY, extractDelegationPublications, parseDelegationPointer, pointerRecordName, POINTER_VERSION, POINTER_RECORD_PREFIX, } from './carriers.js';
+/**
+ * Verify the delegation an MCP server card or A2A agent card publishes.
+ *
+ * `options.delegate` still means what it means everywhere else: the artifact identity YOU
+ * resolved — the npm package you are about to install, the endpoint you are about to call —
+ * NOT a field read out of this card. A card that describes itself is not evidence about
+ * itself.
+ */
+export async function verifyPublishedDelegation(card, options) {
+    const tokens = collectPublishedTokens(card);
+    if (tokens.length === 0) {
+        return {
+            valid: false,
+            reason: 'no_publication',
+            outcome: classifyFailureReason('no_publication'),
+            message: 'card carries no delegation publication in any sanctioned location',
+        };
+    }
+    if (tokens.length > 1) {
+        return {
+            valid: false,
+            reason: 'multiple_publications',
+            outcome: classifyFailureReason('multiple_publications'),
+            message: `card publishes ${tokens.length} different delegation tokens — refusing to guess which one it means`,
+        };
+    }
+    return verifyDelegation(tokens[0], options);
+}
+//# sourceMappingURL=publication.js.map

package/dist/publication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publication.js","sourceRoot":"","sources":["../src/publication.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,+BAA+B,EAC/B,6BAA6B,EAC7B,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAGvB;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,IAAa,EACb,OAAsB;IAEtB,MAAM,MAAM,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,gBAAgB;YACxB,OAAO,EAAE,qBAAqB,CAAC,gBAAgB,CAAC;YAChD,OAAO,EAAE,mEAAmE;SAC7E,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,uBAAuB;YAC/B,OAAO,EAAE,qBAAqB,CAAC,uBAAuB,CAAC;YACvD,OAAO,EAAE,kBAAkB,MAAM,CAAC,MAAM,qEAAqE;SAC9G,CAAC;IACJ,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC"}

package/dist/status.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Revocation status of a delegation, over two channels that answer different questions.
+ *
+ *   1. **Token Status List** (IETF draft-ietf-oauth-status-list). The token carries its own
+ *      slot — `status.status_list.{idx, uri}` — and the signed list at that uri says whether
+ *      the slot is valid (0), revoked (1) or suspended (2). This is the standard, cacheable,
+ *      herd-private channel, and — since `h-status-list-cascade-fold` — it is AUTHORITATIVE
+ *      for the delegation, including the domain control proof cascade underneath it: a
+ *      revoked or suspended control folds into this same bit, so `checkDelegationStatus`
+ *      trusts a `valid`/`revoked`/`suspended` list read and does not also ask the endpoint
+ *      (`h-delegation-verifier-status-fallthrough-gate`).
+ *   2. **The issuer's status endpoint.** Stays the only channel for three things the bit
+ *      cannot express: `unknown_delegation` ("no record of this handle" is distinguishable
+ *      from "we have a record and it is dead" only by a live call), a token carrying no
+ *      status-list claim at all, and cascade-derived EXPIRY — the control's own `expires_at`
+ *      is never packed into the bit (only revoked/suspended are), so a delegation whose
+ *      effective lifetime is capped by an expired control, while its own list bit and its own
+ *      `exp` claim both still read fine, is only visible through this endpoint.
+ *
+ *      `h-fix-control-proof-reissue-shorter` closes the write side of that expiry gap going
+ *      forward — a delegation can no longer be minted longer than its control, and reissuing a
+ *      control shorter than an outstanding delegation now caps the reissue instead of leaving
+ *      the delegation to outlive it — but two bounded residuals remain, both deliberately
+ *      accepted there rather than fixed here: a control shortened before that task shipped
+ *      (measured zero on staging, unmeasured in production), and that task's own fail-open
+ *      when its registry-budget guard cannot run. A verifier package cannot special-case any
+ *      one issuer's guarantees, so this residual is disclosed, not silently assumed away — see
+ *      the package README's Failure reasons section.
+ *
+ * Both channels are authenticated: the status list is a signed JWT checked against the same
+ * key set as the delegation, and the uri inside the token is refused unless it belongs to the
+ * trusted issuer — it arrives INSIDE the artifact being verified, so treating it as an address
+ * to fetch would hand an attacker both the status authority and an SSRF primitive.
+ */
+import type { FetchLike, TrustedIssuer } from './types.js';
+export type StatusOutcome = {
+    state: 'valid';
+} | {
+    state: 'revoked';
+    message: string;
+} | {
+    state: 'suspended';
+    message: string;
+}
+/** The issuer's clock says this delegation is over — distinct from withdrawn. */
+ | {
+    state: 'expired';
+    message: string;
+}
+/** The issuer has no record of the delegation at all. */
+ | {
+    state: 'unknown';
+    message: string;
+} | {
+    state: 'untrusted_uri';
+    message: string;
+} | {
+    state: 'unavailable';
+    message: string;
+};
+export declare function allowedStatusOrigins(issuer: TrustedIssuer): string[];
+/**
+ * Read one 2-bit slot out of a decoded status list. Lowest index in the least significant
+ * bits, `bits` statuses per byte — the draft's byte order.
+ */
+export declare function readStatusSlot(bytes: Uint8Array, index: number, bits: number): number | null;
+interface StatusListClaim {
+    idx: number;
+    uri: string;
+}
+export declare function readStatusListClaim(claims: Record<string, unknown>): StatusListClaim | null;
+/**
+ * Combined status. A negative answer from EITHER channel is decisive; `unavailable` from
+ * either one is reported so the caller can fail closed.
+ */
+export declare function checkDelegationStatus(params: {
+    token: string;
+    claims: Record<string, unknown>;
+    issuer: TrustedIssuer;
+    fetch: FetchLike;
+    timeoutMs: number;
+    now: Date;
+    clockToleranceSeconds: number;
+}): Promise<StatusOutcome>;
+export {};
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,MAAM,aAAa,GACrB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAClB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACzC,iFAAiF;GAC/E;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACvC,yDAAyD;GACvD;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAM9C,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,EAAE,CAWpE;AASD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS5F;AAED,UAAU,eAAe;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,GAAG,IAAI,CAS3F;AA+ND;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,IAAI,CAAC;IACV,qBAAqB,EAAE,MAAM,CAAC;CAC/B,GAAG,OAAO,CAAC,aAAa,CAAC,CA0BzB"}

package/dist/status.js

@@ -0,0 +1,321 @@
+/**
+ * Revocation status of a delegation, over two channels that answer different questions.
+ *
+ *   1. **Token Status List** (IETF draft-ietf-oauth-status-list). The token carries its own
+ *      slot — `status.status_list.{idx, uri}` — and the signed list at that uri says whether
+ *      the slot is valid (0), revoked (1) or suspended (2). This is the standard, cacheable,
+ *      herd-private channel, and — since `h-status-list-cascade-fold` — it is AUTHORITATIVE
+ *      for the delegation, including the domain control proof cascade underneath it: a
+ *      revoked or suspended control folds into this same bit, so `checkDelegationStatus`
+ *      trusts a `valid`/`revoked`/`suspended` list read and does not also ask the endpoint
+ *      (`h-delegation-verifier-status-fallthrough-gate`).
+ *   2. **The issuer's status endpoint.** Stays the only channel for three things the bit
+ *      cannot express: `unknown_delegation` ("no record of this handle" is distinguishable
+ *      from "we have a record and it is dead" only by a live call), a token carrying no
+ *      status-list claim at all, and cascade-derived EXPIRY — the control's own `expires_at`
+ *      is never packed into the bit (only revoked/suspended are), so a delegation whose
+ *      effective lifetime is capped by an expired control, while its own list bit and its own
+ *      `exp` claim both still read fine, is only visible through this endpoint.
+ *
+ *      `h-fix-control-proof-reissue-shorter` closes the write side of that expiry gap going
+ *      forward — a delegation can no longer be minted longer than its control, and reissuing a
+ *      control shorter than an outstanding delegation now caps the reissue instead of leaving
+ *      the delegation to outlive it — but two bounded residuals remain, both deliberately
+ *      accepted there rather than fixed here: a control shortened before that task shipped
+ *      (measured zero on staging, unmeasured in production), and that task's own fail-open
+ *      when its registry-budget guard cannot run. A verifier package cannot special-case any
+ *      one issuer's guarantees, so this residual is disclosed, not silently assumed away — see
+ *      the package README's Failure reasons section.
+ *
+ * Both channels are authenticated: the status list is a signed JWT checked against the same
+ * key set as the delegation, and the uri inside the token is refused unless it belongs to the
+ * trusted issuer — it arrives INSIDE the artifact being verified, so treating it as an address
+ * to fetch would hand an attacker both the status authority and an SSRF primitive.
+ */
+import { base64UrlToBytes, isRecord, parseJwt } from './jwt.js';
+import { getVerificationKeys, isSupportedAlgorithm, MAX_REMOTE_BODY_BYTES, verifySignature } from './jwks.js';
+const STATUS_VALID = 0;
+const STATUS_REVOKED = 1;
+const STATUS_SUSPENDED = 2;
+export function allowedStatusOrigins(issuer) {
+    const origins = new Set();
+    for (const candidate of [issuer.jwksUri, issuer.statusEndpoint, ...(issuer.statusListOrigins ?? [])]) {
+        if (!candidate)
+            continue;
+        try {
+            origins.add(new URL(candidate).origin);
+        }
+        catch {
+            // A malformed policy entry contributes no origin; the caller's own validation reports it.
+        }
+    }
+    return [...origins];
+}
+/** Inflate a zlib-wrapped DEFLATE payload without pulling in a compression dependency. */
+async function inflate(bytes) {
+    const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream('deflate'));
+    const buffer = await new Response(stream).arrayBuffer();
+    return new Uint8Array(buffer);
+}
+/**
+ * Read one 2-bit slot out of a decoded status list. Lowest index in the least significant
+ * bits, `bits` statuses per byte — the draft's byte order.
+ */
+export function readStatusSlot(bytes, index, bits) {
+    if (!Number.isInteger(index) || index < 0)
+        return null;
+    if (bits !== 1 && bits !== 2 && bits !== 4 && bits !== 8)
+        return null;
+    const perByte = 8 / bits;
+    const byteIndex = Math.floor(index / perByte);
+    if (byteIndex >= bytes.length)
+        return null;
+    const shift = (index % perByte) * bits;
+    const mask = (1 << bits) - 1;
+    return (bytes[byteIndex] >> shift) & mask;
+}
+export function readStatusListClaim(claims) {
+    const status = claims.status;
+    if (!isRecord(status))
+        return null;
+    const statusList = status.status_list;
+    if (!isRecord(statusList))
+        return null;
+    const { idx, uri } = statusList;
+    if (typeof idx !== 'number' || !Number.isInteger(idx) || idx < 0)
+        return null;
+    if (typeof uri !== 'string' || uri.length === 0)
+        return null;
+    return { idx, uri };
+}
+async function checkStatusList(params) {
+    const { claim, issuer } = params;
+    let uri;
+    try {
+        uri = new URL(claim.uri);
+    }
+    catch {
+        return { state: 'untrusted_uri', message: 'status list uri is not a valid URL' };
+    }
+    if (!allowedStatusOrigins(issuer).includes(uri.origin)) {
+        return {
+            state: 'untrusted_uri',
+            message: `status list uri origin ${uri.origin} is not an origin of trusted issuer "${issuer.issuer}"`,
+        };
+    }
+    let response;
+    try {
+        response = await params.fetch(uri.toString(), {
+            signal: AbortSignal.timeout(params.timeoutMs),
+            headers: { accept: 'application/statuslist+jwt, application/jwt, text/plain' },
+            // The origin guard above is only worth as much as the hop it guards: with the default
+            // `follow`, ANY open redirect on the issuer's origin would carry this fetch off it —
+            // the token controls the path — handing back both the status authority and an SSRF
+            // primitive against the verifying gateway's network.
+            redirect: 'error',
+        });
+    }
+    catch (error) {
+        return {
+            state: 'unavailable',
+            message: `status list fetch failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!response.ok) {
+        return { state: 'unavailable', message: `status list fetch failed with HTTP ${response.status}` };
+    }
+    const declaredLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_REMOTE_BODY_BYTES) {
+        return { state: 'unavailable', message: 'status list response is too large' };
+    }
+    const listToken = (await response.text()).trim();
+    if (listToken.length > MAX_REMOTE_BODY_BYTES) {
+        return { state: 'unavailable', message: 'status list response is too large' };
+    }
+    const parsed = parseJwt(listToken);
+    if (!parsed)
+        return { state: 'unavailable', message: 'status list is not a JWT' };
+    const alg = parsed.header.alg;
+    if (!isSupportedAlgorithm(alg)) {
+        return { state: 'unavailable', message: `status list uses unsupported algorithm ${String(alg)}` };
+    }
+    // The draft mandates this `typ`, and it is the one header that separates a status list from
+    // every other JWT the issuer signs with the SAME key — without it, any such token with a
+    // matching `sub` could stand in as a status authority.
+    if (parsed.header.typ !== 'statuslist+jwt') {
+        return {
+            state: 'unavailable',
+            message: `status list must carry typ "statuslist+jwt", got ${JSON.stringify(parsed.header.typ)}`,
+        };
+    }
+    let keys;
+    try {
+        keys = await getVerificationKeys({
+            jwksUri: issuer.jwksUri,
+            kid: typeof parsed.header.kid === 'string' ? parsed.header.kid : undefined,
+            alg,
+            fetch: params.fetch,
+            timeoutMs: params.timeoutMs,
+        });
+    }
+    catch (error) {
+        return {
+            state: 'unavailable',
+            message: `status list signing key unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (keys.length === 0) {
+        return { state: 'unavailable', message: 'status list is signed by an unknown key' };
+    }
+    let signatureOk = false;
+    for (const key of keys) {
+        if (await verifySignature(key, alg, parsed.signingInput, parsed.signature)) {
+            signatureOk = true;
+            break;
+        }
+    }
+    if (!signatureOk) {
+        return { state: 'unavailable', message: 'status list signature is invalid' };
+    }
+    // The list must say it is the list we asked for, or a valid list from the same issuer could
+    // be replayed in place of another one.
+    if (parsed.payload.sub !== claim.uri) {
+        return { state: 'unavailable', message: 'status list `sub` does not match the uri it was fetched from' };
+    }
+    // A freshness channel with no expiry is not one: an `exp`-less list would be honoured
+    // forever, so its absence is treated as "cannot answer" rather than fail-open.
+    const nowSeconds = Math.floor(params.now.getTime() / 1000);
+    const exp = parsed.payload.exp;
+    if (typeof exp !== 'number') {
+        return { state: 'unavailable', message: 'status list carries no exp' };
+    }
+    if (nowSeconds > exp + params.clockToleranceSeconds) {
+        return { state: 'unavailable', message: 'status list has expired' };
+    }
+    const statusList = parsed.payload.status_list;
+    if (!isRecord(statusList) || typeof statusList.lst !== 'string') {
+        return { state: 'unavailable', message: 'status list payload has no `lst`' };
+    }
+    const bits = typeof statusList.bits === 'number' ? statusList.bits : 2;
+    let decoded;
+    try {
+        decoded = await inflate(base64UrlToBytes(statusList.lst));
+    }
+    catch (error) {
+        return {
+            state: 'unavailable',
+            message: `status list payload could not be decompressed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const slot = readStatusSlot(decoded, claim.idx, bits);
+    if (slot === null) {
+        // A slot beyond the list is not "valid" — the issuer has no answer for this token.
+        return { state: 'unavailable', message: `status list has no slot ${claim.idx}` };
+    }
+    if (slot === STATUS_REVOKED)
+        return { state: 'revoked', message: 'the issuer status list marks this delegation revoked' };
+    if (slot === STATUS_SUSPENDED) {
+        return { state: 'suspended', message: 'the issuer status list marks this delegation suspended' };
+    }
+    if (slot !== STATUS_VALID) {
+        return { state: 'unavailable', message: `status list slot carries unknown status ${slot}` };
+    }
+    return { state: 'valid' };
+}
+/**
+ * Ask the issuer's status endpoint about this exact token. Contract:
+ * `POST` `{"proof_token": "<jwt>"}` → JSON with at least `{"valid": boolean}` and optionally
+ * `{"reason": "revoked" | "suspended" | "expired" | ...}`.
+ */
+async function checkStatusEndpoint(params) {
+    const endpoint = params.issuer.statusEndpoint;
+    if (!endpoint) {
+        return {
+            state: 'unavailable',
+            message: `trusted issuer "${params.issuer.issuer}" declares no statusEndpoint, so the control-proof cascade cannot be checked`,
+        };
+    }
+    let response;
+    try {
+        response = await params.fetch(endpoint, {
+            method: 'POST',
+            signal: AbortSignal.timeout(params.timeoutMs),
+            headers: { 'content-type': 'application/json', accept: 'application/json' },
+            body: JSON.stringify({ proof_token: params.token }),
+            redirect: 'error',
+        });
+    }
+    catch (error) {
+        return {
+            state: 'unavailable',
+            message: `status endpoint request failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!response.ok) {
+        return { state: 'unavailable', message: `status endpoint answered HTTP ${response.status}` };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        return { state: 'unavailable', message: 'status endpoint answered with a non-JSON body' };
+    }
+    if (!isRecord(body) || typeof body.valid !== 'boolean') {
+        return { state: 'unavailable', message: 'status endpoint answer carries no `valid` boolean' };
+    }
+    if (body.valid)
+        return { state: 'valid' };
+    // `valid: false` is not automatically "withdrawn". An issuer answers it for things that mean
+    // "I could not check" too — proof.holdings itself answers `status_unavailable` on a registry
+    // read failure. Reporting those as `revoked` would make a database blip at the issuer look
+    // like a permanent withdrawal to every gateway that asked, so only reasons that actually
+    // name a withdrawal are treated as one; anything unrecognised fails closed as unavailable.
+    const reason = typeof body.reason === 'string' ? body.reason : '';
+    switch (reason) {
+        case 'revoked':
+            return { state: 'revoked', message: 'the issuer reports this delegation revoked' };
+        case 'suspended':
+            return { state: 'suspended', message: 'the issuer reports this delegation suspended' };
+        case 'expired':
+            return { state: 'expired', message: 'the issuer reports this delegation expired' };
+        case 'unknown_delegation':
+            return { state: 'unknown', message: 'the issuer has no record of this delegation' };
+        default:
+            return {
+                state: 'unavailable',
+                message: `the issuer answered invalid without a recognised reason (${reason || 'none'})`,
+            };
+    }
+}
+/**
+ * Combined status. A negative answer from EITHER channel is decisive; `unavailable` from
+ * either one is reported so the caller can fail closed.
+ */
+export async function checkDelegationStatus(params) {
+    const claim = readStatusListClaim(params.claims);
+    if (claim) {
+        const listOutcome = await checkStatusList({
+            claim,
+            issuer: params.issuer,
+            fetch: params.fetch,
+            timeoutMs: params.timeoutMs,
+            now: params.now,
+            clockToleranceSeconds: params.clockToleranceSeconds,
+        });
+        // Authoritative for `valid`/`revoked`/`suspended` — the fold (h-status-list-cascade-fold)
+        // makes those three the issuer's whole answer for this delegation's own bit.
+        // `unavailable`/`untrusted_uri` mean "could not read the list", not an answer from it, and
+        // still fall through to the endpoint below.
+        if (listOutcome.state !== 'unavailable' && listOutcome.state !== 'untrusted_uri') {
+            return listOutcome;
+        }
+    }
+    return checkStatusEndpoint({
+        token: params.token,
+        issuer: params.issuer,
+        fetch: params.fetch,
+        timeoutMs: params.timeoutMs,
+    });
+}
+//# sourceMappingURL=status.js.map

package/dist/status.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Public types of the Proof of Delegation reference verifier.
+ *
+ * The library verifies a delegation token — an attestation that the domain in `principal`
+ * authorized the artifact in `delegate` for a set of capability scopes. It attests NOTHING
+ * about the artifact's quality, safety or the business behind it, and it is not a statement
+ * that anyone "verified" the server.
+ *
+ * Two design rules separate this from an SDK, and both are load-bearing:
+ *
+ *   1. There is NO default trust list. `trustedIssuers` is supplied by the caller on every
+ *      call — a verifier that trusts an issuer because the library shipped with its name
+ *      hard-coded is a client for that issuer, not a verifier.
+ *   2. `delegate` is REQUIRED. The token is a bearer artifact: anyone can copy a genuine
+ *      token into their own package. The comparison that defeats that is against the artifact
+ *      identity the CALLER resolved independently — never against what the card says about
+ *      itself.
+ */
+/** A typed artifact identifier, canonicalized before comparison. */
+export type DelegateType = 'url' | 'purl';
+export interface DelegateInput {
+    type: DelegateType;
+    /** e.g. `pkg:npm/postmark-mcp` or `https://api.example.com/mcp` */
+    value: string;
+}
+/**
+ * One entry of the caller's trust policy.
+ *
+ * `statusEndpoint` is what lets the verifier see a revocation that a status list cannot show.
+ * An issuer's status list carries one bit per proof, so it reports the delegation's OWN
+ * revocation — but a delegation is only worth the domain control proof underneath it, and
+ * that cascade is resolved by the issuer, not encoded in the delegation's own bit. The
+ * endpoint contract is deliberately minimal: `POST` with `{"proof_token": "<jwt>"}` and a
+ * JSON answer carrying at least `{"valid": boolean}` (optionally `reason`).
+ */
+export interface TrustedIssuer {
+    /** Exact value the token's `iss` claim must equal. */
+    issuer: string;
+    /** Absolute https URL of the issuer's JWKS. */
+    jwksUri: string;
+    /** Absolute https URL of the issuer's public token-status endpoint. */
+    statusEndpoint?: string;
+    /**
+     * Extra origins this issuer may serve its status list from. The origins of `jwksUri` and
+     * `statusEndpoint` are always allowed; anything else must be listed here or the status-list
+     * uri inside the token is refused WITHOUT being fetched.
+     */
+    statusListOrigins?: string[];
+}
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface VerifyOptions {
+    /** REQUIRED, no default. An empty list fails closed with `no_trust_policy`. */
+    trustedIssuers: TrustedIssuer[];
+    /** REQUIRED. The artifact identity the caller resolved independently. */
+    delegate: DelegateInput;
+    /**
+     * The domain you expect to have authorized this artifact. Optional in the type, but omitting
+     * it downgrades the answer — see `VerificationSuccess.principalChecked`. Compared after
+     * trimming and lowercasing.
+     */
+    expectedPrincipal?: string;
+    /**
+     * Scopes the delegation must grant. Compared as EXACT strings against the token's own
+     * `scope` (trimmed only): scope grammar belongs to the issuer, and imposing one issuer's
+     * rules here would make another issuer's grants unaskable.
+     */
+    requiredScopes?: string[];
+    /**
+     * `required` (default) — the delegation's status list is checked, and the issuer's status
+     * endpoint is asked too whenever the list cannot answer on its own (see `status.ts` for
+     * exactly when); anything unreachable fails closed with `status_unavailable`. There is no
+     * option to tolerate a transient `status_unavailable` — a caller wanting a grace window
+     * around a flaky issuer must implement that itself (e.g. retry, or branch on `outcome:
+     * 'unconfirmed'`); this library does not offer a built-in one.
+     * `skip` — signature and claims only; the result carries `statusChecked: false`, which a
+     * caller must treat as "revocation not checked", never as "not revoked".
+     */
+    statusCheck?: 'required' | 'skip';
+    /** Seconds of leeway on `exp`/`iat`. Default 5. */
+    clockToleranceSeconds?: number;
+    /** Verification time; defaults to now. */
+    now?: Date;
+    /** Injected fetch (tests, proxies, non-Node runtimes). Defaults to global fetch. */
+    fetch?: FetchLike;
+    /** Per-request network timeout in ms. Default 5000. */
+    timeoutMs?: number;
+}
+export type FailureReason = 
+/** The call itself is wrong (missing `delegate`, malformed trust entry). */
+'invalid_options'
+/** `trustedIssuers` was empty — the library has no default trust. */
+ | 'no_trust_policy' | 'malformed_token' | 'untrusted_issuer' | 'unsupported_algorithm' | 'unknown_key' | 'bad_signature' | 'jwks_unavailable' | 'not_a_delegation' | 'unsupported_schema' | 'expired' | 'not_yet_valid' | 'malformed_claims' | 'principal_mismatch'
+/** The token attests some OTHER artifact than the one the caller resolved. */
+ | 'delegate_mismatch' | 'scope_not_granted'
+/** The status-list uri in the token does not belong to the trusted issuer. */
+ | 'status_uri_untrusted' | 'status_unavailable' | 'revoked' | 'suspended'
+/** The issuer has no record of this delegation — distinct from "it could not answer". */
+ | 'unknown_delegation'
+/** Card carries no delegation publication. */
+ | 'no_publication'
+/** Card carries several publications — ambiguous, refused rather than guessed. */
+ | 'multiple_publications';
+export type FailureOutcome = 'invalid' | 'unconfirmed';
+/**
+ * Whether a `FailureReason` means "checked, and it's bad" (`invalid`) or "could not check"
+ * (`unconfirmed`). The three status-channel reasons that mean the revocation check itself
+ * failed are `unconfirmed`; every other reason is a completed check with a negative verdict,
+ * including a call-shape error — `verifyDelegation` always receives a well-formed
+ * `VerifyOptions` in practice, so those are `invalid` for exhaustiveness, not because they
+ * occur.
+ */
+export declare function classifyFailureReason(reason: FailureReason): FailureOutcome;
+export interface VerifiedDelegation {
+    issuer: string;
+    /** The domain that authorized the artifact. */
+    principal: string;
+    /** Canonical artifact identifier, byte-equal to what the caller resolved. */
+    delegate: string;
+    scope: string[];
+    /** Public handle of the domain control proof underneath this delegation. */
+    controlProof: string;
+    /** Public handle of the delegation itself (`ph_dlg_*` for proof.holdings). */
+    delegationId: string;
+    issuedAt: Date;
+    expiresAt: Date;
+}
+export interface VerificationSuccess {
+    valid: true;
+    /** False only when `statusCheck: 'skip'` was requested. */
+    statusChecked: boolean;
+    /**
+     * False when no `expectedPrincipal` was supplied — and then `valid: true` means LESS than it
+     * looks like. An issuer binds `delegate` to nothing: the domain in `principal` is whatever
+     * the requester proved control of, and the artifact is free-text they chose. So anyone who
+     * can verify `evil.example` can mint a genuine, signature-valid delegation naming SOMEONE
+     * ELSE's package. The required `delegate` argument defeats a COPIED token; only pinning
+     * `principal` defeats a token minted by the wrong party.
+     *
+     * A caller that already knows whose artifact this is (an agent installing `postmark-mcp`
+     * knows it expects `postmarkapp.com`) must pass `expectedPrincipal`. A caller that is
+     * discovering who claims an artifact may legitimately leave it off — and must then present
+     * the answer as "X says it authorized this", never as "verified".
+     */
+    principalChecked: boolean;
+    delegation: VerifiedDelegation;
+}
+export interface VerificationFailure {
+    valid: false;
+    reason: FailureReason;
+    /** `classifyFailureReason(reason)` — set for every failure, never left for the caller to derive. */
+    outcome: FailureOutcome;
+    message: string;
+}
+export type VerificationResult = VerificationSuccess | VerificationFailure;
+//# sourceMappingURL=types.d.ts.map