@proof-holdings/delegation-verifier 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,7 @@
 # @proof-holdings/delegation-verifier
 
 Verify a **Proof of Delegation**: a signed statement that the controller of a domain authorized
-a specific agent artifact — an npm package, a container, an endpoint — for a set of capability
-scopes.
+a specific agent artifact — an npm package, a container, an endpoint.
 
 You do not need an account with anyone to use this. It runs against public surfaces only, and
 it has **no built-in trust list**: you name the issuers you accept.
@@ -18,8 +17,8 @@ Zero runtime dependencies. Node ≥ 18 (or any runtime with WebCrypto, `fetch` a
 
 A verified delegation says exactly one thing:
 
-> The controller of `principal` authorized `delegate` for these scopes, and the issuer checked
-> that control when it signed.
+> The controller of `principal` authorized `delegate`, and the issuer checked that control when
+> it signed.
 
 It is **not** a statement that the artifact is safe, audited, maintained, or endorsed, and it is
 not a review of the business behind the domain. Do not render it as a generic "verified" badge.
@@ -41,7 +40,6 @@ const result = await verifyPublishedDelegation(serverCard, {
   // The artifact YOU resolved — the package you are installing, the endpoint you are calling.
   delegate: { type: 'purl', value: 'pkg:npm/postmark-mcp' },
   expectedPrincipal: 'postmarkapp.com',
-  requiredScopes: ['send-email'],
 });
 
 if (result.valid) {
@@ -85,21 +83,29 @@ presented as *"X says it authorized this"*, never as *verified*.
 1. **Trust policy** — the token's `iss` must be one you named. No trust list, no verification.
 2. **Signature** — RS256/ES256 against the issuer's JWKS. The algorithm is chosen by the
    verifier, never read from the token, so `alg: none` and HMAC forgeries die before any key is
-   fetched. Key sets are cached; an unknown `kid` triggers at most one refetch per 30s.
+   fetched. Key sets are cached; an unknown `kid` triggers at most one refetch per 30s. The
+   signing key's purpose, window and tombstone are checked here too — see
+   [Key rotation](#key-rotation-and-the-key-set-cache).
 3. **Claims** — `token_type`, schema version, `exp`/`iat` (5s tolerance by default), and the
    required claim set.
 4. **Principal** — pinned to the domain you expect, when you supply one. See above: without it
    the answer says who *claims* the artifact, not that the right party did.
 5. **Delegate** — canonicalized and compared byte-for-byte with the identity you resolved.
-6. **Status** — two channels, both authenticated:
+6. **Status** — two channels, both authenticated, asked in order:
    - the IETF Token Status List the token points at (`status.status_list`), whose uri is
      refused unless it belongs to your trusted issuer, and whose signature is checked against
-     the same key set;
-   - the issuer's status endpoint, which is the only thing that can report the **cascade**: a
-     delegation is worth no more than the domain control proof beneath it, and a revoked domain
-     proof does not flip the delegation's own status-list bit.
-
-   Status checking is **fail-closed**: if either channel cannot answer, the result is
+     the same key set. A readable `valid`, `revoked` or `suspended` slot is the answer, and the
+     check stops there. An issuer whose validity cascades folds a revoked or suspended domain
+     control proof beneath the delegation into this same slot (proof.holdings does);
+   - the issuer's status endpoint, asked only when the list gives no answer: the token carries
+     no status-list claim, or the list cannot be read, is not the trusted issuer's, or holds no
+     valid/revoked/suspended value for the token's slot. One thing
+     only the endpoint can report is an **expiry** inherited from the domain control proof, which
+     a list slot never encodes. A delegation whose own slot and own `exp` both read fine is
+     therefore not re-checked for it — an accepted residual, explained in
+     [Why the status endpoint is not always called](#why-the-status-endpoint-is-not-always-called-and-what-that-leaves-uncovered).
+
+   Status checking is **fail-closed**: if neither channel gives an answer, the result is
    `status_unavailable`, not "valid". Pass `statusCheck: 'skip'` to check signature and claims
    only — the result then carries `statusChecked: false`, which means *revocation was not
    checked*, never *not revoked*.
@@ -121,6 +127,56 @@ than before.
 `POST <statusEndpoint>` with `{"proof_token": "<jwt>"}` answering JSON with at least
 `{"valid": boolean}` and optionally `{"reason": "revoked" | "suspended" | ...}`.
 
+## Key rotation and the key-set cache
+
+An issuer's JWKS may carry several keys at once. Beside the standard members, a key may declare
+`proof_purpose` (`proof`, `delegation` or `status-list`), a window (`not_before`, `not_after`,
+`max_token_lifetime` — integer seconds) or `proof_legacy: true`; revoked keys are listed in a
+top-level `proof_tombstones: [{ "kid", "revoked_at" }]`. A key set without these members verifies
+exactly as before. Once any key carries `proof_purpose`:
+
+- a delegation must be signed by a `delegation` key or a legacy one (`wrong_key_purpose`);
+- its `iat` must lie in the key's window, ± 5 minutes (`outside_key_window`), and its `exp` no later
+  than `iat + max_token_lifetime` (`token_lifetime_exceeded`) — legacy keys skip both;
+- a token without `kid` is tried against legacy keys only.
+
+The status list's own signing key is held to the same rules as a `status-list` key; a list signed by
+a key that fails them counts as unreadable, exactly like a list that could not be fetched.
+
+**One response is never trusted for long.** A new key verifies from its first sighting, so an
+emergency key works at once. But the verifier only *remembers* a key carrying `proof_purpose` or
+`proof_legacy` — keeps it after it disappears from the JWKS, refuses new key material under its
+`kid`, refuses whole a document that widens its window — once two fetches at least 5 minutes apart
+served it unchanged; until then the next document replaces or drops it. A narrower window and a
+tombstone wait for the same confirmation: a tombstone applies only when a fetch at least 5 minutes
+after its first sighting still carries it (a fetch in between that drops it starts over;
+`refreshJwks` forces the second fetch), and once applied it stays until `revoked_at` + 365 days or
+`clearTombstones()`, whatever later documents say.
+
+The key set is refetched every 10 minutes. When a refetch fails, the cache's confirmed keys keep
+answering until it is `maxJwksAgeMs` old, then the answer is `jwks_stale`; an applied tombstone
+answers `key_revoked` at any age. A failed refetch of a cached set is retried at most once per 30s.
+The cache lives in the process, keyed by `jwksUri`.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `maxJwksAgeMs` | 24 h | How old the cache may be when a refetch fails. Above 25 days, non-integer or ≤ 0 is `invalid_options`. |
+| `keySetStore` | none | `{ load(jwksUri), save(jwksUri, state) }`, sync or async, opaque string state. Persists the key set — tombstones included — across restarts and cold starts. A failing store never fails a verification. |
+| `onJwksEvent` | ignored | Receives `{ type, jwksUri, kid?, message }`: `tombstone_pending`, `tombstone_applied`, `tombstone_for_live_key`, `window_narrowing_pending`, `window_narrowing_applied`, `window_widening_rejected`, `key_material_changed`, `kid_vanished`, `store_error`. |
+| `timeoutMs` | 5000 | Bounds each network request and each `keySetStore` call. |
+
+Exported alongside `verifyDelegation`:
+
+- `refreshJwks({ jwksUri, fetch?, timeoutMs?, keySetStore?, onJwksEvent? })` — refetch now,
+  ignoring the TTL and cooldowns; resolves `{ ok: true }` or `{ ok: false, message }`. The method a
+  `jwks_stale` result's `refreshHint` names.
+- `clearTombstones({ jwksUri?, keySetStore? })` — the manual reset: forgets applied and pending
+  tombstones for one key set (and its persisted copy), or for every set in memory.
+- `getJwksDiagnostics(jwksUri)` — cache age, whether the registry is live, vanished keys, pending and
+  applied tombstones; `null` for a key set this process has never used.
+- `DEFAULT_MAX_JWKS_AGE_MS`, `MAX_JWKS_AGE_CAP_MS` — to validate your own configuration against the
+  same bounds.
+
 ## Failure reasons
 
 Every failure carries an `outcome: 'invalid' | 'unconfirmed'` beside `reason` —
@@ -132,18 +188,22 @@ because they occur in practice).
 
 | `reason` | `outcome` | Meaning |
 | --- | --- | --- |
-| `invalid_options` | `invalid` | The call is wrong — usually a missing or uncanonicalizable `delegate`. |
+| `invalid_options` | `invalid` | The call is wrong — usually a missing or uncanonicalizable `delegate`, or the `requiredScopes` option, removed in 0.2.0 with the `scope` claim (refused rather than ignored, so no caller reads a valid answer as "my scopes were granted"). |
 | `no_trust_policy` | `invalid` | `trustedIssuers` was empty. There is no default. |
 | `malformed_token` | `invalid` | Not a decodable JWT. |
 | `untrusted_issuer` | `invalid` | Signed by someone you did not name. |
 | `unsupported_algorithm` | `invalid` | The token asked for an algorithm this verifier does not accept. |
 | `unknown_key` / `bad_signature` | `invalid` | No matching key, or the signature does not hold. |
-| `jwks_unavailable` | `unconfirmed` | Could not read the key set — "I could not check", not "it is bad". |
-| `not_a_delegation` / `unsupported_schema` | `invalid` | Wrong token type or a schema major this version does not understand. |
+| `jwks_unavailable` | `unconfirmed` | Could not read the key set, or could not refetch it for an unknown `kid` — "I could not check", not "it is bad". |
+| `jwks_stale` | `unconfirmed` | A refetch failed and the cached key set is older than `maxJwksAgeMs`. Carries `cacheAgeSeconds` (null when unknown) and `refreshHint: { jwksUri, method: 'refreshJwks' }`. |
+| `key_revoked` | `invalid` | The issuer revoked the signing key (an applied JWKS tombstone). Carries `pullHint: { issuerOrigin, handle }` — where to ask for a re-signed token. The handle is read from a token whose signature was not checked: an address to ask, not a verified identity. |
+| `wrong_key_purpose` | `invalid` | The signing key belongs to another key family than a delegation. |
+| `outside_key_window` | `invalid` | The token's `iat` lies outside the signing key's window (5 minutes of skew allowed). |
+| `token_lifetime_exceeded` | `invalid` | `exp` lies beyond `iat` plus the signing key's `max_token_lifetime`. |
+| `not_a_delegation` / `unsupported_version` | `invalid` | Wrong token type, or a `delegation_schema_version` major other than 2 (a 1.x token, which still carries `scope`, is refused before any network call). |
 | `expired` / `not_yet_valid` / `malformed_claims` | `invalid` | Claim-level rejections. |
 | `principal_mismatch` | `invalid` | Issued by a different domain than you expected. |
 | `delegate_mismatch` | `invalid` | **Attests a different artifact than the one you resolved.** |
-| `scope_not_granted` | `invalid` | Does not grant a scope you required. |
 | `status_uri_untrusted` | `unconfirmed` | The status-list uri in the token is not the issuer's. Not fetched. |
 | `status_unavailable` | `unconfirmed` | Revocation could not be checked. Fail closed. |
 | `revoked` / `suspended` | `invalid` | Withdrawn, or reversibly paused. |
@@ -160,17 +220,19 @@ that token's validity in it. An issuer that keeps a side-channel revocation reas
 published list is not honoring the channel it chose to publish — a fact about that issuer, not
 something a generic verifier can special-case.
 
-The endpoint still fires for the cases the bit structurally cannot answer: a token with no
-status-list claim at all, `unknown_delegation` ("no record of this handle" is distinguishable
-from "a record that is dead" only by a live call), and — for issuers whose validity cascades
-through something else, like a domain control proof underneath a delegation — an EXPIRY driven by
-that something else, which a status-list bit never encodes (only revoked/suspended are, by the
-same draft's own vocabulary). For proof.holdings specifically, that cascade-expiry gap is bounded,
-not eliminated: a delegation can no longer be minted longer than its underlying control proof, and
-a control cannot be re-issued shorter than an outstanding delegation without capping the
-reissue to cover it — but a control shortened before that guarantee existed, or a reissue that hit
-its own rare fail-open path, can still leave a delegation whose list bit and own `exp` claim both
-read fine while its issuer would answer `expired`. This is a known, accepted trade-off — not
+The endpoint is asked only when the list gives no answer: the token carries no status-list claim,
+or the list cannot be read, is not the trusted issuer's, or holds no valid/revoked/suspended value
+for the token's slot. It is the only channel that can report two things the bit structurally
+cannot — `unknown_delegation` ("no record of this handle" is distinguishable from "a record that
+is dead" only by a live call) and, for issuers whose validity cascades through something else, like
+a domain control proof underneath a delegation, an EXPIRY driven by that something else, which a
+status-list bit never encodes (only revoked/suspended are, by the same draft's own vocabulary) —
+so when the list does answer, neither is checked. For proof.holdings specifically, that
+cascade-expiry gap is bounded, not eliminated: a delegation can no longer be minted longer than its
+underlying control proof, and a control cannot be re-issued shorter than an outstanding delegation
+without capping the reissue to cover it — but a control shortened before that guarantee existed, or a
+reissue that hit its own rare fail-open path, can still leave a delegation whose list bit and own
+`exp` claim both read fine while its issuer would answer `expired`. This is a known, accepted trade-off — not
 silently assumed away.
 
 ### One thing a failure reason is not

package/dist/delegate.d.ts

@@ -15,8 +15,6 @@ import type { DelegateInput, DelegateType } from './types.js';
 export declare const DELEGATE_TYPES: readonly DelegateType[];
 /** Cap on the CANONICAL delegate string. */
 export declare const DELEGATE_MAX_LENGTH = 512;
-export declare const DELEGATION_SCOPE_MAX_ENTRIES = 32;
-export declare const DELEGATION_SCOPE_TOKEN_MAX_LENGTH = 64;
 export declare class DelegateIdentifierError extends Error {
     constructor(message: string);
 }
@@ -26,9 +24,4 @@ export declare class DelegateIdentifierError extends Error {
  * cannot be canonicalized is a bug in the CALL, not evidence about the token.
  */
 export declare function canonicalizeDelegate(input: DelegateInput): string;
-/**
- * Validate and canonicalize a scope list: every entry a lowercase kebab-case token,
- * deduplicated, sorted. Throws `DelegateIdentifierError` on any rejection.
- */
-export declare function canonicalizeScopes(scopes: string[]): string[];
 //# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAA6B,CAAC;AAEhF,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAC/C,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAQpD,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAIjE;AAqGD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAyB7D"}
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAA6B,CAAC;AAEhF,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAKvC,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAIjE"}

package/dist/delegate.js

@@ -14,10 +14,6 @@
 export const DELEGATE_TYPES = ['url', 'purl'];
 /** Cap on the CANONICAL delegate string. */
 export const DELEGATE_MAX_LENGTH = 512;
-export const DELEGATION_SCOPE_MAX_ENTRIES = 32;
-export const DELEGATION_SCOPE_TOKEN_MAX_LENGTH = 64;
-/** Lowercase kebab-case: `send-email`, `read-profile-v2`. */
-const SCOPE_TOKEN_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 /** `pkg:type/[namespace/]name` — structure only; per-type case rules applied after. */
 const PURL_RE = /^pkg:([a-z0-9.+-]+)\/(.+)$/i;
 export class DelegateIdentifierError extends Error {
@@ -116,10 +112,11 @@ function canonicalizeUrl(value) {
         throw new DelegateIdentifierError('delegate URL must not carry a fragment');
     }
     // URL() already lowercases the host and strips an explicit default port; pathname keeps its
-    // case. Trailing slash is canonicalized away except at the root, where it is always '/'.
+    // case. Trailing slash is canonicalized away except at the root, where it is always '/' — a
+    // path of slashes only collapses to that root, so the result is idempotent.
     let pathname = parsed.pathname;
     if (pathname.length > 1 && pathname.endsWith('/')) {
-        pathname = pathname.replace(/\/+$/, '');
+        pathname = pathname.replace(/\/+$/, '') || '/';
     }
     return enforceLength(`https://${parsed.host}${pathname}`);
 }
@@ -129,28 +126,4 @@ function enforceLength(canonical) {
     }
     return canonical;
 }
-/**
- * Validate and canonicalize a scope list: every entry a lowercase kebab-case token,
- * deduplicated, sorted. Throws `DelegateIdentifierError` on any rejection.
- */
-export function canonicalizeScopes(scopes) {
-    if (!Array.isArray(scopes) || scopes.length === 0) {
-        throw new DelegateIdentifierError('scope must contain at least one entry');
-    }
-    if (scopes.length > DELEGATION_SCOPE_MAX_ENTRIES) {
-        throw new DelegateIdentifierError(`too many scope entries (max ${DELEGATION_SCOPE_MAX_ENTRIES})`);
-    }
-    for (const token of scopes) {
-        if (typeof token !== 'string' || token.length === 0) {
-            throw new DelegateIdentifierError('scope entries must be non-empty strings');
-        }
-        if (token.length > DELEGATION_SCOPE_TOKEN_MAX_LENGTH) {
-            throw new DelegateIdentifierError(`scope entry is too long (max ${DELEGATION_SCOPE_TOKEN_MAX_LENGTH} characters)`);
-        }
-        if (!SCOPE_TOKEN_RE.test(token)) {
-            throw new DelegateIdentifierError(`invalid scope entry "${token}" — lowercase kebab-case tokens only (e.g. send-email)`);
-        }
-    }
-    return [...new Set(scopes)].sort();
-}
 //# sourceMappingURL=delegate.js.map

package/dist/delegate.js.map

@@ -1 +1 @@
-{"version":3,"file":"delegate.js","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,CAAC,MAAM,cAAc,GAA4B,CAAC,KAAK,EAAE,MAAM,CAAU,CAAC;AAEhF,4CAA4C;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEvC,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,CAAC;AAC/C,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAEpD,6DAA6D;AAC7D,MAAM,cAAc,GAAG,+BAA+B,CAAC;AAEvD,uFAAuF;AACvF,MAAM,OAAO,GAAG,6BAA6B,CAAC;AAE9C,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAoB;IACvD,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAChE,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9D,MAAM,IAAI,uBAAuB,CAAC,0BAA0B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpF,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,uBAAuB,CAAC,4BAA4B,CAAC,CAAC;IAC1E,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,uBAAuB,CAAC,sCAAsC,CAAC,CAAC;IAC9F,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,uBAAuB,CAAC,+CAA+C,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,uBAAuB,CAAC,2CAA2C,CAAC,CAAC;IACjF,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,uBAAuB,CAAC,mDAAmD,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAEpB,0FAA0F;IAC1F,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,uBAAuB,CAC/B,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,uBAAuB,CAAC,2CAA2C,CAAC,CAAC;IACjF,CAAC;IAED,2FAA2F;IAC3F,4FAA4F;IAC5F,wDAAwD;IACxD,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACnB,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpE,CAAC;SAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvF,CAAC;SAAM,CAAC;QACN,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,aAAa,CAAC,OAAO,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,IAAY;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,SAAS;QAC9B,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG;YAAE,SAAS,CAAC,eAAe;QAC7D,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,uBAAuB,CAAC,4BAA4B,CAAC,CAAC;IAE1E,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,uBAAuB,CAAC,uCAAuC,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,uBAAuB,CAAC,6BAA6B,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACvC,MAAM,IAAI,uBAAuB,CAAC,yCAAyC,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,IAAI,uBAAuB,CAAC,4CAA4C,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,uBAAuB,CAAC,wCAAwC,CAAC,CAAC;IAC9E,CAAC;IAED,4FAA4F;IAC5F,yFAAyF;IACzF,IAAI,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC/B,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,aAAa,CAAC,WAAW,MAAM,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,aAAa,CAAC,SAAiB;IACtC,IAAI,SAAS,CAAC,MAAM,GAAG,mBAAmB,EAAE,CAAC;QAC3C,MAAM,IAAI,uBAAuB,CAAC,6BAA6B,mBAAmB,cAAc,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAgB;IACjD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,uBAAuB,CAAC,uCAAuC,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,4BAA4B,EAAE,CAAC;QACjD,MAAM,IAAI,uBAAuB,CAAC,+BAA+B,4BAA4B,GAAG,CAAC,CAAC;IACpG,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,uBAAuB,CAAC,yCAAyC,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,iCAAiC,EAAE,CAAC;YACrD,MAAM,IAAI,uBAAuB,CAC/B,gCAAgC,iCAAiC,cAAc,CAChF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,uBAAuB,CAC/B,wBAAwB,KAAK,wDAAwD,CACtF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACrC,CAAC"}
+{"version":3,"file":"delegate.js","sourceRoot":"","sources":["../src/delegate.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * @proof-holdings/delegation-verifier — issuer-agnostic verification of Proof of Delegation.
  *
- * A delegation says: the domain in `principal` authorized the artifact in `delegate` for these
- * capability scopes, and the issuer checked that domain's control at issuance. It says nothing
+ * A delegation says: the domain in `principal` authorized the artifact in `delegate`, and the
+ * issuer checked that domain's control at issuance. It says nothing
  * about whether the artifact is safe, audited, or any good.
  *
  * ```ts
@@ -28,10 +28,10 @@ export type { FoundPublication } from './publication.js';
  */
 export { parseDelegationPointer, pointerRecordName, POINTER_VERSION, POINTER_RECORD_PREFIX, } from './publication.js';
 export type { PointerParseResult, PointerRejection } from './publication.js';
-export { canonicalizeDelegate, canonicalizeScopes, DelegateIdentifierError, DELEGATE_TYPES, DELEGATE_MAX_LENGTH, } from './delegate.js';
-export { resetJwksCache, SUPPORTED_ALGORITHMS } from './jwks.js';
-export type { SupportedAlgorithm } from './jwks.js';
+export { canonicalizeDelegate, DelegateIdentifierError, DELEGATE_TYPES, DELEGATE_MAX_LENGTH, } from './delegate.js';
+export { clearTombstones, DEFAULT_MAX_JWKS_AGE_MS, getJwksDiagnostics, MAX_JWKS_AGE_CAP_MS, refreshJwks, resetJwksCache, SUPPORTED_ALGORITHMS, } from './jwks.js';
+export type { JwksDiagnostics, SupportedAlgorithm } from './jwks.js';
 export { readStatusSlot } from './status.js';
 export { classifyFailureReason } from './types.js';
-export type { DelegateInput, DelegateType, FailureOutcome, FailureReason, FetchLike, TrustedIssuer, VerificationFailure, VerificationResult, VerificationSuccess, VerifiedDelegation, VerifyOptions, } from './types.js';
+export type { DelegateInput, DelegateType, FailureOutcome, FailureReason, FetchLike, JwksEvent, JwksEventType, KeySetStore, TrustedIssuer, VerificationFailure, VerificationResult, VerificationSuccess, VerifiedDelegation, VerifyOptions, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,EACnB,wBAAwB,EACxB,+BAA+B,GAChC,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD;;;;;GAKG;AACH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,aAAa,EACb,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,EACnB,wBAAwB,EACxB,+BAA+B,GAChC,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD;;;;;GAKG;AACH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,aAAa,EACb,SAAS,EACT,SAAS,EACT,aAAa,EACb,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,8 +1,8 @@
 /**
  * @proof-holdings/delegation-verifier — issuer-agnostic verification of Proof of Delegation.
  *
- * A delegation says: the domain in `principal` authorized the artifact in `delegate` for these
- * capability scopes, and the issuer checked that domain's control at issuance. It says nothing
+ * A delegation says: the domain in `principal` authorized the artifact in `delegate`, and the
+ * issuer checked that domain's control at issuance. It says nothing
  * about whether the artifact is safe, audited, or any good.
  *
  * ```ts
@@ -26,8 +26,8 @@ export { verifyPublishedDelegation, extractDelegationPublications, DELEGATION_ME
  * and hands the TXT values in.
  */
 export { parseDelegationPointer, pointerRecordName, POINTER_VERSION, POINTER_RECORD_PREFIX, } from './publication.js';
-export { canonicalizeDelegate, canonicalizeScopes, DelegateIdentifierError, DELEGATE_TYPES, DELEGATE_MAX_LENGTH, } from './delegate.js';
-export { resetJwksCache, SUPPORTED_ALGORITHMS } from './jwks.js';
+export { canonicalizeDelegate, DelegateIdentifierError, DELEGATE_TYPES, DELEGATE_MAX_LENGTH, } from './delegate.js';
+export { clearTombstones, DEFAULT_MAX_JWKS_AGE_MS, getJwksDiagnostics, MAX_JWKS_AGE_CAP_MS, refreshJwks, resetJwksCache, SUPPORTED_ALGORITHMS, } from './jwks.js';
 export { readStatusSlot } from './status.js';
 export { classifyFailureReason } from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,EACnB,wBAAwB,EACxB,+BAA+B,GAChC,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,EACnB,wBAAwB,EACxB,+BAA+B,GAChC,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/jwks.d.ts

@@ -1,47 +1,148 @@
 /**
- * JWKS retrieval and key cache.
+ * JWKS retrieval and key cache — the I/O half. The rules a fetched key set is held to (merge,
+ * tombstones, purpose, window) live in `keyset.ts`; this file decides WHEN to fetch and what to
+ * answer when a fetch fails.
  *
- * Three behaviours here are load-bearing rather than tidy, all learned from the hand-rolled Go
- * verifier that shipped before this package:
+ * Behaviours that are load-bearing rather than tidy, the first three learned from the hand-rolled
+ * Go verifier that shipped before this package:
  *
  *   - The algorithm is chosen from THIS list, never from the token's own header. A token that
  *     asks for `none` or for an HMAC is refused before any key is looked up.
- *   - An unknown `kid` is indistinguishable from a rotated key, so a miss triggers at most one
- *     refetch per cooldown window. Without it every junk-kid token costs one outbound request
- *     and a busy verifier trips the issuer's rate limit — failing its GOOD tokens too.
+ *   - An unknown `kid` is indistinguishable from a rotated (or emergency) key, so a miss triggers
+ *     at most one refetch per cooldown window. Without it every junk-kid token costs one outbound
+ *     request and a busy verifier trips the issuer's rate limit — failing its GOOD tokens too.
  *   - Concurrent misses share ONE in-flight fetch per key set, with the cache re-checked after
  *     it resolves. Serialising is what makes the cooldown hold under concurrency.
+ *   - A failed refetch does not discard a cached key set. Under `maxJwksAgeMs` its CONFIRMED keys
+ *     keep answering (a kid they do not cover is `jwks_unavailable`: it may be new); over it the answer
+ *     is `jwks_stale` — except for an applied tombstone, which is `key_revoked` at any age. A set
+ *     that was never fetched has no cache to fall back on, so its failure stays `jwks_unavailable`
+ *     and is retried on every call.
+ *   - Age is measured on a monotonic clock in-process. Only what is persisted uses wall clock.
  */
-import type { FetchLike } from './types.js';
+import type { KeyFamily, KeyPolicyViolation, KeyRecord } from './keyset.js';
+import type { FetchLike, JwksEvent, KeySetStore } from './types.js';
 export declare const SUPPORTED_ALGORITHMS: readonly ["RS256", "ES256"];
 export type SupportedAlgorithm = (typeof SUPPORTED_ALGORITHMS)[number];
-/** How long a `kid` miss suppresses further refetches of the same key set. */
+/** How long a `kid` miss — or a failed refetch of a cached set — suppresses further fetches. */
 export declare const KEY_MISS_COOLDOWN_MS = 30000;
 /** How long a successfully fetched key set is reused without refetching. */
 export declare const KEY_SET_TTL_MS: number;
+/** Default `maxJwksAgeMs`. */
+export declare const DEFAULT_MAX_JWKS_AGE_MS: number;
+/** Largest accepted `maxJwksAgeMs` — below the issuer's ~30-day lead on its next key. */
+export declare const MAX_JWKS_AGE_CAP_MS: number;
 /**
  * A key set is kilobytes. Anything larger is not a JWKS, and the request is driven by input the
  * verifier does not control, so it is capped rather than streamed to completion.
  */
 export declare const MAX_REMOTE_BODY_BYTES: number;
-/** Test seam — drops every cached key set. */
+export interface JwksClock {
+    monotonicMs(): number;
+    wallMs(): number;
+}
+/** Test seam — replaces both clocks; `null` restores the system clocks. Not exported publicly. */
+export declare function setJwksClockForTests(replacement: JwksClock | null): void;
+/** The per-call knobs that shape key-set handling. */
+export interface KeySetOptions {
+    maxJwksAgeMs: number;
+    keySetStore?: KeySetStore;
+    onJwksEvent?: (event: JwksEvent) => void;
+}
+/** Test seam — drops every cached key set, tombstones included. */
 export declare function resetJwksCache(): void;
 export declare class JwksUnavailableError extends Error {
     constructor(message: string);
 }
 export declare function isSupportedAlgorithm(alg: unknown): alg is SupportedAlgorithm;
+export interface KeyCandidate {
+    key: CryptoKey;
+    record: KeyRecord;
+}
+export type KeyResolution = {
+    kind: 'keys';
+    candidates: KeyCandidate[];
+    registryLive: boolean;
+} | {
+    kind: 'revoked';
+    kid: string;
+} | {
+    kind: 'wrong_purpose';
+    kid: string;
+} | {
+    kind: 'unknown';
+} | {
+    kind: 'stale';
+    cacheAgeSeconds: number | null;
+} | {
+    kind: 'unavailable';
+    message: string;
+};
 /**
- * Candidate verification keys for `kid`, fetching the key set at most once per cooldown.
- * Returns an empty array when the key is genuinely unknown; throws `JwksUnavailableError`
- * when the key set could not be read at all ("I could not check" is not "the token is bad").
+ * The keys that may verify a token of `family` carrying `kid` — or why none may. Fetches the key
+ * set when it is older than the TTL, or once per cooldown when `kid` is unknown.
  */
-export declare function getVerificationKeys(params: {
+export declare function resolveVerificationKeys(params: {
     jwksUri: string;
     kid?: string;
     alg: SupportedAlgorithm;
+    family: KeyFamily;
     fetch: FetchLike;
     timeoutMs: number;
-}): Promise<CryptoKey[]>;
+} & KeySetOptions): Promise<KeyResolution>;
 /** Verify a JWS signature against one candidate key. */
 export declare function verifySignature(key: CryptoKey, alg: SupportedAlgorithm, signingInput: string, signature: Uint8Array): Promise<boolean>;
+/**
+ * Signature first, then the window and lifetime of the key that verified it — so a forged token
+ * is reported as `bad_signature`, not as a policy violation of a key it never came from.
+ */
+export declare function verifyWithCandidates(resolution: Extract<KeyResolution, {
+    kind: 'keys';
+}>, alg: SupportedAlgorithm, signingInput: string, signature: Uint8Array, token: {
+    iat: unknown;
+    exp: unknown;
+}): Promise<'ok' | 'bad_signature' | KeyPolicyViolation>;
+/**
+ * Refetch a key set now, ignoring the TTL and cooldowns — the method a `jwks_stale` answer names.
+ * Resolves with the outcome rather than throwing.
+ */
+export declare function refreshJwks(params: {
+    jwksUri: string;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    keySetStore?: KeySetStore;
+    onJwksEvent?: (event: JwksEvent) => void;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+}>;
+/**
+ * Forget every applied and pending tombstone — the documented manual reset. With `jwksUri`, only
+ * that key set (and, given a `keySetStore`, its persisted copy); without, every set in memory.
+ */
+export declare function clearTombstones(params?: {
+    jwksUri?: string;
+    keySetStore?: KeySetStore;
+}): Promise<void>;
+export interface JwksDiagnostics {
+    jwksUri: string;
+    /** Age of the cached set in seconds; null when never fetched or the persisted age is unknown. */
+    cacheAgeSeconds: number | null;
+    registryLive: boolean;
+    /** Confirmed registry kids no longer served before their retention ended — kept with last-known state. */
+    vanishedKids: string[];
+    pendingTombstones: Array<{
+        kid: string;
+        revokedAt: number;
+        pendingForSeconds: number;
+    }>;
+    appliedTombstones: Array<{
+        kid: string;
+        revokedAt: number;
+    }>;
+}
+/** What the verifier currently holds for one key set, or null if it has never been used. */
+export declare function getJwksDiagnostics(jwksUri: string): JwksDiagnostics | null;
 //# sourceMappingURL=jwks.d.ts.map

package/dist/jwks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,oBAAoB,6BAA8B,CAAC;AAChE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,4EAA4E;AAC5E,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAa,CAAC;AAchD,8CAA8C;AAC9C,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAkBD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,kBAAkB,CAE5E;AA8ED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,kBAAkB,CAAC;IACxB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAmDvB;AAED,wDAAwD;AACxD,wBAAsB,eAAe,CACnC,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,kBAAkB,EACvB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAYlB"}
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"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"}