@proof-holdings/delegation-verifier 0.1.0 → 0.1.1

package/dist/keyset.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The key-set rules, free of I/O: how a fetched JWKS is merged into what the verifier already
+ * knows, and which key — if any — may verify a token of a given family.
+ *
+ * Kept apart from `jwks.ts` (fetch, cache, cooldowns) because these are the rules every verifier
+ * must agree on — the JS, Python, Go and PHP SDKs port them function for function, and the shared
+ * fixtures in `sdks/shared/fixtures/jwks_rotation/` pin the outcome of each one.
+ *
+ * Four properties are load-bearing:
+ *
+ *   - One response is never trusted for long. Anything that would outlive the next fetch — a key
+ *     being remembered, a window narrowing, a tombstone — takes effect only when a second fetch, at
+ *     least five minutes after the first sighting, says the same. A key verifies from its first
+ *     sighting (an emergency key must work at once), but until it is confirmed the next document
+ *     replaces or drops it, exactly as before rotation existed. Otherwise one poisoned response
+ *     could plant a key the verifier keeps for as long as that key's own members claim, or revoke
+ *     or re-date an honest key fleet-wide.
+ *   - A fetch is MERGED, never swapped in. A CONFIRMED registry key that disappears keeps its
+ *     last-known state, never gets new key material, and its window may narrow (by the rule above)
+ *     but never widen — a document that widens one is refused whole, whatever key material it
+ *     serves under that kid.
+ *   - An applied tombstone is sticky until every token the key signed is dead.
+ *   - "Registry live" is a property of the merged set (some key carries `proof_purpose`). Until
+ *     then the set is in tolerant mode and behaves exactly as it did before rotation existed. An
+ *     unconfirmed key counts too: it is gone with the next document that omits it.
+ */
+import type { JwksEventType } from './types.js';
+export declare const KEY_FAMILIES: readonly ["proof", "delegation", "status-list"];
+export type KeyFamily = (typeof KEY_FAMILIES)[number];
+/** Clock skew tolerated on each edge of a key's `[not_before, not_after]` window. */
+export declare const KEY_WINDOW_SKEW_SECONDS = 300;
+/** Minimum spacing between the two fetches that confirm a key, a narrowed window or a tombstone. */
+export declare const CONFIRM_SPACING_MS: number;
+/** An applied tombstone is kept until `revoked_at` plus this. */
+export declare const TOMBSTONE_RETENTION_SECONDS: number;
+/** Both clocks at one instant: monotonic for in-process intervals, wall for anything persisted. */
+export interface KeySetClockReading {
+    monotonicMs: number;
+    wallMs: number;
+}
+export interface KeyRecord {
+    kid?: string;
+    /** The JWK as last accepted, with any narrowing of its window applied. */
+    jwk: Record<string, unknown>;
+    /** Identity of the key material: a protected kid keeps its first material, an unprotected one takes the latest. */
+    fingerprint: string;
+    /** `alg`, `use` and `key_ops` — the members that decide whether the key may verify at all. */
+    usage: string;
+    hasPurposeMember: boolean;
+    purpose?: KeyFamily;
+    legacy: boolean;
+    notBefore?: number;
+    notAfter?: number;
+    maxTokenLifetime?: number;
+    vanished: boolean;
+    /** When this exact description of the key was first served. */
+    firstSeen: KeySetClockReading;
+    /** Served unchanged by two fetches at least `CONFIRM_SPACING_MS` apart. */
+    confirmed: boolean;
+    /** A narrower window served for a confirmed key, applied once a later fetch confirms it. */
+    pendingWindow?: PendingWindow;
+}
+export interface PendingWindow {
+    notBefore: number;
+    notAfter: number;
+    firstSeen: KeySetClockReading;
+}
+export interface PendingTombstone {
+    kid: string;
+    revokedAt: number;
+    firstSeen: KeySetClockReading;
+}
+export interface AppliedTombstone {
+    kid: string;
+    revokedAt: number;
+}
+export interface KeySetState {
+    keys: Map<string, KeyRecord>;
+    /** Keys served without a `kid` — tolerant mode only ever needs them. */
+    anonymous: KeyRecord[];
+    pending: Map<string, PendingTombstone>;
+    applied: Map<string, AppliedTombstone>;
+    fetchedAt: KeySetClockReading | null;
+    /** A persisted `fetched_at` lay in the future: its age is unknown, so it counts as stale. */
+    fetchedAtUntrusted: boolean;
+}
+export type KeySetEventType = Exclude<JwksEventType, 'store_error'>;
+export interface KeySetEvent {
+    type: KeySetEventType;
+    kid?: string;
+    message: string;
+}
+export interface MergeResult {
+    state: KeySetState;
+    events: KeySetEvent[];
+    /** False when the document was refused whole; `state` is then the unchanged input. */
+    accepted: boolean;
+}
+export type KeySelection = {
+    kind: 'candidates';
+    records: KeyRecord[];
+} | {
+    kind: 'revoked';
+    kid: string;
+} | {
+    kind: 'wrong_purpose';
+    kid: string;
+} | {
+    kind: 'unknown';
+};
+export type KeyPolicyViolation = 'outside_key_window' | 'token_lifetime_exceeded';
+export declare function emptyKeySetState(): KeySetState;
+export declare function parseKeyRecord(jwk: Record<string, unknown>, firstSeen: KeySetClockReading): KeyRecord;
+export declare function isRegistryLive(state: KeySetState): boolean;
+/**
+ * Merge one fetched JWKS body (already known to be an object with a `keys` array) into `state`.
+ * Pure: returns a new state and the events the caller should report.
+ */
+export declare function mergeFetchedDocument(state: KeySetState, body: Record<string, unknown>, now: KeySetClockReading): MergeResult;
+/**
+ * Which keys may verify a token of `family` carrying `kid`. Checks the applied tombstone and the
+ * key's purpose; the signature and the window are the caller's next steps, in that order.
+ */
+export declare function selectKeys(state: KeySetState, kid: string | undefined, family: KeyFamily): KeySelection;
+/** The window and lifetime rules for a key whose signature has verified. */
+export declare function checkKeyPolicy(record: KeyRecord, token: {
+    iat: unknown;
+    exp: unknown;
+}, registryLive: boolean): KeyPolicyViolation | null;
+/**
+ * Fold the tombstones of a persisted state into a set this process has already fetched. The
+ * fetched keys are newer than disk, but a tombstone is not something a later fetch can restore:
+ * dropping the persisted one would silently un-revoke a key until two more fetches agreed again.
+ */
+export declare function withPersistedTombstones(state: KeySetState, persisted: KeySetState): KeySetState;
+/**
+ * The part of a cached set that may answer after a refetch FAILED: confirmed keys only. An
+ * unconfirmed key is trusted until the next document, and a failing fetch must not stretch that to
+ * `maxJwksAgeMs` — otherwise one poisoned response followed by an outage would keep its key, and
+ * the registry mode it switched on, for a day.
+ */
+export declare function withConfirmedKeysOnly(state: KeySetState): KeySetState;
+/** Drop every applied and pending tombstone — the documented manual reset. */
+export declare function withoutTombstones(state: KeySetState): KeySetState;
+/**
+ * Persisted form. Every timestamp is wall-clock milliseconds: a monotonic reading means nothing
+ * to another process.
+ */
+export declare function serializeKeySetState(state: KeySetState): string;
+/**
+ * Rebuild a persisted state, or null when the blob is not one. A `fetched_at` in the future marks
+ * the set stale; a pending tombstone first seen in the future is dropped.
+ */
+export declare function deserializeKeySetState(raw: string, now: KeySetClockReading): KeySetState | null;
+//# sourceMappingURL=keyset.d.ts.map

package/dist/keyset.d.ts.map

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

package/dist/keyset.js

@@ -0,0 +1,505 @@
+/**
+ * The key-set rules, free of I/O: how a fetched JWKS is merged into what the verifier already
+ * knows, and which key — if any — may verify a token of a given family.
+ *
+ * Kept apart from `jwks.ts` (fetch, cache, cooldowns) because these are the rules every verifier
+ * must agree on — the JS, Python, Go and PHP SDKs port them function for function, and the shared
+ * fixtures in `sdks/shared/fixtures/jwks_rotation/` pin the outcome of each one.
+ *
+ * Four properties are load-bearing:
+ *
+ *   - One response is never trusted for long. Anything that would outlive the next fetch — a key
+ *     being remembered, a window narrowing, a tombstone — takes effect only when a second fetch, at
+ *     least five minutes after the first sighting, says the same. A key verifies from its first
+ *     sighting (an emergency key must work at once), but until it is confirmed the next document
+ *     replaces or drops it, exactly as before rotation existed. Otherwise one poisoned response
+ *     could plant a key the verifier keeps for as long as that key's own members claim, or revoke
+ *     or re-date an honest key fleet-wide.
+ *   - A fetch is MERGED, never swapped in. A CONFIRMED registry key that disappears keeps its
+ *     last-known state, never gets new key material, and its window may narrow (by the rule above)
+ *     but never widen — a document that widens one is refused whole, whatever key material it
+ *     serves under that kid.
+ *   - An applied tombstone is sticky until every token the key signed is dead.
+ *   - "Registry live" is a property of the merged set (some key carries `proof_purpose`). Until
+ *     then the set is in tolerant mode and behaves exactly as it did before rotation existed. An
+ *     unconfirmed key counts too: it is gone with the next document that omits it.
+ */
+import { isRecord } from './jwt.js';
+export const KEY_FAMILIES = ['proof', 'delegation', 'status-list'];
+/** Clock skew tolerated on each edge of a key's `[not_before, not_after]` window. */
+export const KEY_WINDOW_SKEW_SECONDS = 300;
+/** Minimum spacing between the two fetches that confirm a key, a narrowed window or a tombstone. */
+export const CONFIRM_SPACING_MS = 5 * 60_000;
+/** An applied tombstone is kept until `revoked_at` plus this. */
+export const TOMBSTONE_RETENTION_SECONDS = 365 * 86_400;
+export function emptyKeySetState() {
+    return {
+        keys: new Map(),
+        anonymous: [],
+        pending: new Map(),
+        applied: new Map(),
+        fetchedAt: null,
+        fetchedAtUntrusted: false,
+    };
+}
+function isWholeNumber(value) {
+    return typeof value === 'number' && Number.isInteger(value);
+}
+function isKeyFamily(value) {
+    return typeof value === 'string' && KEY_FAMILIES.includes(value);
+}
+const MATERIAL_MEMBERS = ['kty', 'crv', 'x', 'y', 'n', 'e'];
+function fingerprintOf(jwk) {
+    return JSON.stringify(MATERIAL_MEMBERS.map((member) => jwk[member] ?? null));
+}
+function usageOf(jwk) {
+    return JSON.stringify([jwk.alg ?? null, jwk.use ?? null, jwk.key_ops ?? null]);
+}
+export function parseKeyRecord(jwk, firstSeen) {
+    const record = {
+        jwk,
+        fingerprint: fingerprintOf(jwk),
+        usage: usageOf(jwk),
+        hasPurposeMember: jwk.proof_purpose !== undefined,
+        legacy: jwk.proof_legacy === true,
+        vanished: false,
+        firstSeen,
+        confirmed: false,
+    };
+    if (typeof jwk.kid === 'string' && jwk.kid.length > 0)
+        record.kid = jwk.kid;
+    if (isKeyFamily(jwk.proof_purpose))
+        record.purpose = jwk.proof_purpose;
+    if (isWholeNumber(jwk.not_before))
+        record.notBefore = jwk.not_before;
+    if (isWholeNumber(jwk.not_after))
+        record.notAfter = jwk.not_after;
+    if (isWholeNumber(jwk.max_token_lifetime))
+        record.maxTokenLifetime = jwk.max_token_lifetime;
+    return record;
+}
+function hasWindow(record) {
+    return record.notBefore !== undefined && record.notAfter !== undefined && record.maxTokenLifetime !== undefined;
+}
+/**
+ * A key the issuer's registry describes — it carries `proof_purpose` or `proof_legacy` — AND that
+ * two fetches at least `CONFIRM_SPACING_MS` apart served unchanged. The ONE predicate behind every
+ * rule that outlives a fetch: material lock, no widening, pending narrowing, retained when it
+ * vanishes. Window members alone do not make a registry key: without a purpose such a key cannot
+ * verify anything once the registry is live, so it keeps tolerant semantics.
+ */
+function isProtectedRecord(record) {
+    return record.confirmed && (record.hasPurposeMember || record.legacy);
+}
+/**
+ * Whether two records describe the same key: material, usage, purpose, legacy marker and window.
+ * Usage counts because the record kept is the one first seen: a poisoned first sighting marked
+ * `use: "enc"` must be replaced by the honest description, not confirmed by it.
+ */
+function describesSameKey(a, b) {
+    return (a.fingerprint === b.fingerprint &&
+        a.usage === b.usage &&
+        a.hasPurposeMember === b.hasPurposeMember &&
+        a.purpose === b.purpose &&
+        a.legacy === b.legacy &&
+        a.notBefore === b.notBefore &&
+        a.notAfter === b.notAfter &&
+        a.maxTokenLifetime === b.maxTokenLifetime);
+}
+function spacingElapsed(since, now) {
+    return now.monotonicMs - since.monotonicMs >= CONFIRM_SPACING_MS;
+}
+export function isRegistryLive(state) {
+    for (const record of state.keys.values())
+        if (record.hasPurposeMember)
+            return true;
+    return state.anonymous.some((record) => record.hasPurposeMember);
+}
+function wallSeconds(reading) {
+    return Math.floor(reading.wallMs / 1000);
+}
+/** Whether a kid may still be signing: legacy, window unknown, or not yet past `not_after`. */
+function isLiveKey(record, nowSeconds) {
+    if (record.legacy || !hasWindow(record))
+        return true;
+    return nowSeconds <= record.notAfter + KEY_WINDOW_SKEW_SECONDS;
+}
+function parseTombstones(value) {
+    if (!Array.isArray(value))
+        return [];
+    const tombstones = [];
+    for (const entry of value) {
+        if (!isRecord(entry))
+            continue;
+        if (typeof entry.kid !== 'string' || entry.kid.length === 0)
+            continue;
+        if (!isWholeNumber(entry.revoked_at))
+            continue;
+        tombstones.push({ kid: entry.kid, revokedAt: entry.revoked_at });
+    }
+    return tombstones;
+}
+function cloneState(state) {
+    return {
+        keys: new Map([...state.keys].map(([kid, record]) => [kid, { ...record }])),
+        anonymous: state.anonymous.map((record) => ({ ...record })),
+        pending: new Map(state.pending),
+        applied: new Map(state.applied),
+        fetchedAt: state.fetchedAt,
+        fetchedAtUntrusted: state.fetchedAtUntrusted,
+    };
+}
+/**
+ * Merge one fetched JWKS body (already known to be an object with a `keys` array) into `state`.
+ * Pure: returns a new state and the events the caller should report.
+ */
+export function mergeFetchedDocument(state, body, now) {
+    const nowSeconds = wallSeconds(now);
+    const candidates = Array.isArray(body.keys) ? body.keys.filter(isRecord) : [];
+    const served = new Map();
+    const anonymous = [];
+    for (const jwk of candidates) {
+        const record = parseKeyRecord(jwk, now);
+        if (record.kid)
+            served.set(record.kid, record);
+        else
+            anonymous.push(record);
+    }
+    // Widening is checked before anything is touched: such a document is refused whole.
+    for (const [kid, incoming] of served) {
+        const known = state.keys.get(kid);
+        if (!known || !isProtectedRecord(known) || !hasWindow(known) || !hasWindow(incoming))
+            continue;
+        if (incoming.notBefore < known.notBefore || incoming.notAfter > known.notAfter) {
+            return {
+                state,
+                accepted: false,
+                events: [
+                    {
+                        type: 'window_widening_rejected',
+                        kid,
+                        message: `JWKS refused: it widens the window of confirmed key "${kid}"`,
+                    },
+                ],
+            };
+        }
+    }
+    const next = cloneState(state);
+    const events = [];
+    const tombstones = parseTombstones(body.proof_tombstones);
+    const tombstonedNow = new Set(tombstones.map((tombstone) => tombstone.kid));
+    for (const [kid, incoming] of served) {
+        const known = next.keys.get(kid);
+        // Not protected yet: the latest document describes the key, exactly as before rotation
+        // existed. Serving the same description again, far enough apart, confirms it.
+        if (!known || !isProtectedRecord(known)) {
+            if (known && describesSameKey(known, incoming)) {
+                if (!known.confirmed && spacingElapsed(known.firstSeen, now))
+                    known.confirmed = true;
+            }
+            else {
+                next.keys.set(kid, incoming);
+            }
+            continue;
+        }
+        known.vanished = false;
+        if (known.fingerprint !== incoming.fingerprint) {
+            delete known.pendingWindow;
+            events.push({
+                type: 'key_material_changed',
+                kid,
+                message: `JWKS serves different key material for confirmed key "${kid}"; the first-seen key is kept`,
+            });
+            continue;
+        }
+        if (!hasWindow(known) || !hasWindow(incoming))
+            continue;
+        if (incoming.notBefore === known.notBefore && incoming.notAfter === known.notAfter) {
+            delete known.pendingWindow;
+            continue;
+        }
+        const pending = known.pendingWindow;
+        if (!pending || pending.notBefore !== incoming.notBefore || pending.notAfter !== incoming.notAfter) {
+            known.pendingWindow = { notBefore: incoming.notBefore, notAfter: incoming.notAfter, firstSeen: now };
+            events.push({
+                type: 'window_narrowing_pending',
+                kid,
+                message: `JWKS narrows the window of confirmed key "${kid}"; applied only if a fetch at least 5 minutes later serves the same window`,
+            });
+            continue;
+        }
+        if (!spacingElapsed(pending.firstSeen, now))
+            continue;
+        known.notBefore = pending.notBefore;
+        known.notAfter = pending.notAfter;
+        known.jwk = { ...known.jwk, not_before: pending.notBefore, not_after: pending.notAfter };
+        delete known.pendingWindow;
+        events.push({
+            type: 'window_narrowing_applied',
+            kid,
+            message: `narrowed window of key "${kid}" confirmed by a second fetch and applied`,
+        });
+    }
+    for (const [kid, known] of [...next.keys]) {
+        if (served.has(kid))
+            continue;
+        if (!isProtectedRecord(known)) {
+            next.keys.delete(kid);
+            continue;
+        }
+        if (hasWindow(known)) {
+            if (nowSeconds > known.notAfter + known.maxTokenLifetime + KEY_WINDOW_SKEW_SECONDS) {
+                next.keys.delete(kid);
+                continue;
+            }
+        }
+        else if (!known.legacy) {
+            next.keys.delete(kid);
+            continue;
+        }
+        // A narrowing is confirmed by consecutive documents serving it; one that omits the kid breaks the run.
+        delete known.pendingWindow;
+        if (!known.vanished && !tombstonedNow.has(kid)) {
+            known.vanished = true;
+            events.push({
+                type: 'kid_vanished',
+                kid,
+                message: `key "${kid}" is no longer served before its retention ended; its last-known state is kept`,
+            });
+        }
+    }
+    next.anonymous = anonymous;
+    for (const [kid] of next.pending) {
+        if (!tombstonedNow.has(kid))
+            next.pending.delete(kid);
+    }
+    for (const tombstone of tombstones) {
+        if (next.applied.has(tombstone.kid))
+            continue;
+        const pending = next.pending.get(tombstone.kid);
+        if (pending) {
+            if (spacingElapsed(pending.firstSeen, now)) {
+                next.pending.delete(tombstone.kid);
+                next.applied.set(tombstone.kid, { kid: tombstone.kid, revokedAt: pending.revokedAt });
+                events.push({
+                    type: 'tombstone_applied',
+                    kid: tombstone.kid,
+                    message: `tombstone for key "${tombstone.kid}" confirmed by a second fetch and applied`,
+                });
+            }
+            continue;
+        }
+        next.pending.set(tombstone.kid, { kid: tombstone.kid, revokedAt: tombstone.revokedAt, firstSeen: now });
+        events.push({
+            type: 'tombstone_pending',
+            kid: tombstone.kid,
+            message: `tombstone for key "${tombstone.kid}" seen; applied only if a fetch at least 5 minutes later still carries it`,
+        });
+        // "Last seen live" is read from what the verifier knew BEFORE this document, which may itself
+        // have dropped the key.
+        const known = state.keys.get(tombstone.kid);
+        if (known && isLiveKey(known, nowSeconds)) {
+            events.push({
+                type: 'tombstone_for_live_key',
+                kid: tombstone.kid,
+                message: `ANOMALY: tombstone names key "${tombstone.kid}", which was last seen live`,
+            });
+        }
+    }
+    for (const [kid, applied] of [...next.applied]) {
+        if (nowSeconds > applied.revokedAt + TOMBSTONE_RETENTION_SECONDS)
+            next.applied.delete(kid);
+    }
+    next.fetchedAt = now;
+    next.fetchedAtUntrusted = false;
+    return { state: next, events, accepted: true };
+}
+/**
+ * Which keys may verify a token of `family` carrying `kid`. Checks the applied tombstone and the
+ * key's purpose; the signature and the window are the caller's next steps, in that order.
+ */
+export function selectKeys(state, kid, family) {
+    const registryLive = isRegistryLive(state);
+    if (kid !== undefined) {
+        if (state.applied.has(kid))
+            return { kind: 'revoked', kid };
+        const record = state.keys.get(kid);
+        if (!record)
+            return { kind: 'unknown' };
+        if (record.legacy || !registryLive)
+            return { kind: 'candidates', records: [record] };
+        if (record.purpose !== family)
+            return { kind: 'wrong_purpose', kid };
+        return { kind: 'candidates', records: [record] };
+    }
+    // No `kid`: once the registry is live only a key marked legacy may answer — trying every key
+    // would let a token borrow any family's key and skip the purpose check.
+    const all = [...state.anonymous, ...state.keys.values()].filter((record) => !(record.kid && state.applied.has(record.kid)));
+    const records = registryLive ? all.filter((record) => record.legacy) : all;
+    return records.length > 0 ? { kind: 'candidates', records } : { kind: 'unknown' };
+}
+/** The window and lifetime rules for a key whose signature has verified. */
+export function checkKeyPolicy(record, token, registryLive) {
+    if (!registryLive || record.legacy)
+        return null;
+    if (!hasWindow(record))
+        return 'outside_key_window';
+    if (!isWholeNumber(token.iat))
+        return 'outside_key_window';
+    if (token.iat < record.notBefore - KEY_WINDOW_SKEW_SECONDS)
+        return 'outside_key_window';
+    if (token.iat > record.notAfter + KEY_WINDOW_SKEW_SECONDS)
+        return 'outside_key_window';
+    if (typeof token.exp !== 'number' || token.exp > token.iat + record.maxTokenLifetime) {
+        return 'token_lifetime_exceeded';
+    }
+    return null;
+}
+/**
+ * Fold the tombstones of a persisted state into a set this process has already fetched. The
+ * fetched keys are newer than disk, but a tombstone is not something a later fetch can restore:
+ * dropping the persisted one would silently un-revoke a key until two more fetches agreed again.
+ */
+export function withPersistedTombstones(state, persisted) {
+    const next = cloneState(state);
+    for (const [kid, applied] of persisted.applied) {
+        if (!next.applied.has(kid))
+            next.applied.set(kid, applied);
+    }
+    for (const [kid, pending] of persisted.pending) {
+        if (!next.applied.has(kid) && !next.pending.has(kid))
+            next.pending.set(kid, pending);
+    }
+    return next;
+}
+/**
+ * The part of a cached set that may answer after a refetch FAILED: confirmed keys only. An
+ * unconfirmed key is trusted until the next document, and a failing fetch must not stretch that to
+ * `maxJwksAgeMs` — otherwise one poisoned response followed by an outage would keep its key, and
+ * the registry mode it switched on, for a day.
+ */
+export function withConfirmedKeysOnly(state) {
+    const next = cloneState(state);
+    for (const [kid, record] of [...next.keys]) {
+        if (!record.confirmed)
+            next.keys.delete(kid);
+    }
+    next.anonymous = [];
+    return next;
+}
+/** Drop every applied and pending tombstone — the documented manual reset. */
+export function withoutTombstones(state) {
+    const next = cloneState(state);
+    next.applied.clear();
+    next.pending.clear();
+    return next;
+}
+const PERSISTED_VERSION = 1;
+/**
+ * Persisted form. Every timestamp is wall-clock milliseconds: a monotonic reading means nothing
+ * to another process.
+ */
+export function serializeKeySetState(state) {
+    return JSON.stringify({
+        v: PERSISTED_VERSION,
+        fetched_at_wall_ms: state.fetchedAt && !state.fetchedAtUntrusted ? state.fetchedAt.wallMs : null,
+        keys: [...state.keys.values()].map((record) => ({
+            jwk: record.jwk,
+            vanished: record.vanished,
+            confirmed: record.confirmed,
+            first_seen_wall_ms: record.firstSeen.wallMs,
+            ...(record.pendingWindow
+                ? {
+                    pending_window: {
+                        not_before: record.pendingWindow.notBefore,
+                        not_after: record.pendingWindow.notAfter,
+                        first_seen_wall_ms: record.pendingWindow.firstSeen.wallMs,
+                    },
+                }
+                : {}),
+        })),
+        anonymous: state.anonymous.map((record) => record.jwk),
+        pending: [...state.pending.values()].map((pending) => ({
+            kid: pending.kid,
+            revoked_at: pending.revokedAt,
+            first_seen_wall_ms: pending.firstSeen.wallMs,
+        })),
+        applied: [...state.applied.values()].map((applied) => ({ kid: applied.kid, revoked_at: applied.revokedAt })),
+    });
+}
+function fromWall(wallMs, now) {
+    return { wallMs, monotonicMs: now.monotonicMs - (now.wallMs - wallMs) };
+}
+/**
+ * Rebuild a persisted state, or null when the blob is not one. A `fetched_at` in the future marks
+ * the set stale; a pending tombstone first seen in the future is dropped.
+ */
+export function deserializeKeySetState(raw, now) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed) || parsed.v !== PERSISTED_VERSION)
+        return null;
+    const state = emptyKeySetState();
+    if (Array.isArray(parsed.keys)) {
+        for (const entry of parsed.keys) {
+            if (!isRecord(entry) || !isRecord(entry.jwk))
+                continue;
+            // A first sighting persisted in the future cannot be timed: the key starts over as unconfirmed.
+            const firstSeenWall = entry.first_seen_wall_ms;
+            const firstSeen = isWholeNumber(firstSeenWall) && firstSeenWall <= now.wallMs ? fromWall(firstSeenWall, now) : null;
+            const record = parseKeyRecord(entry.jwk, firstSeen ?? now);
+            if (!record.kid)
+                continue;
+            record.vanished = entry.vanished === true;
+            record.confirmed = firstSeen !== null && entry.confirmed === true;
+            const pendingWindow = entry.pending_window;
+            if (isRecord(pendingWindow) &&
+                isWholeNumber(pendingWindow.not_before) &&
+                isWholeNumber(pendingWindow.not_after) &&
+                isWholeNumber(pendingWindow.first_seen_wall_ms) &&
+                pendingWindow.first_seen_wall_ms <= now.wallMs) {
+                record.pendingWindow = {
+                    notBefore: pendingWindow.not_before,
+                    notAfter: pendingWindow.not_after,
+                    firstSeen: fromWall(pendingWindow.first_seen_wall_ms, now),
+                };
+            }
+            state.keys.set(record.kid, record);
+        }
+    }
+    if (Array.isArray(parsed.anonymous)) {
+        state.anonymous = parsed.anonymous.filter(isRecord).map((jwk) => parseKeyRecord(jwk, now));
+    }
+    for (const applied of parseTombstones(parsed.applied))
+        state.applied.set(applied.kid, applied);
+    if (Array.isArray(parsed.pending)) {
+        for (const entry of parsed.pending) {
+            if (!isRecord(entry) || typeof entry.kid !== 'string' || !isWholeNumber(entry.revoked_at))
+                continue;
+            if (!isWholeNumber(entry.first_seen_wall_ms) || entry.first_seen_wall_ms > now.wallMs)
+                continue;
+            state.pending.set(entry.kid, {
+                kid: entry.kid,
+                revokedAt: entry.revoked_at,
+                firstSeen: fromWall(entry.first_seen_wall_ms, now),
+            });
+        }
+    }
+    const fetchedAtWall = parsed.fetched_at_wall_ms;
+    if (isWholeNumber(fetchedAtWall)) {
+        if (fetchedAtWall > now.wallMs) {
+            state.fetchedAt = now;
+            state.fetchedAtUntrusted = true;
+        }
+        else {
+            state.fetchedAt = fromWall(fetchedAtWall, now);
+        }
+    }
+    return state;
+}
+//# sourceMappingURL=keyset.js.map