@request-seal/core 0.1.0 → 0.3.0

package/dist/discovery/body.js

@@ -1,16 +1,18 @@
 import { remainingMs } from "../context.js";
 import { decodeJson } from "../json.js";
 import { PublicKey } from "../public_key.js";
-import { resolveAlgorithm, algorithms, selection, } from "../crypto/algorithm.js";
+import { resolveAlgorithm, assertedJose, joseId, selection, } from "../crypto/algorithm.js";
 import { digest } from "../crypto/subtle.js";
 import { encodeBase64Url } from "../bytes.js";
 import { ok } from "../result.js";
 import { isDiscoverySource, keyIdValid, sourceOrigin, sourceUrl, } from "./source.js";
 import { ensure, unwrap, failure, clockSeconds, inspectable, systemClock, list, } from "./support.js";
 const resolutions = new WeakSet(), sets = new WeakSet();
+/** Check the private brand of a discovery resolution. */
 export function isResolution(v) {
     return !!v && typeof v === "object" && resolutions.has(v);
 }
+/** Check the private brand of a discovery key set. */
 export function isKeySet(v) {
     return !!v && typeof v === "object" && sets.has(v);
 }
@@ -45,6 +47,7 @@ export function keySet(data) {
         proof: data.proof,
     });
 }
+/** Resolve an eligible key by identifier, allowed algorithms, and current time. */
 export async function lookup(set, kid, allowed, now = systemClock(), transient = false) {
     try {
         ensure(isKeySet(set), "invalid_options");
@@ -56,7 +59,8 @@ export async function lookup(set, kid, allowed, now = systemClock(), transient =
             isResolution(entry) &&
             now < entry.expiresAt &&
             !set.source.revoked.includes(entry.thumbprint), "unknown_key");
-        const algorithm = choices.find((a) => (entry.assertedAlgorithm === null || entry.assertedAlgorithm === a) &&
+        const algorithm = choices.find((a) => (entry.assertedAlgorithm === null ||
+            entry.assertedAlgorithm === joseId(a)) &&
             entry.key.bind(a).ok);
         ensure(algorithm, "unknown_key");
         return ok(resolution({ ...entry, algorithm, revision: set.revision }));
@@ -122,14 +126,34 @@ export async function bodyKeys(doc, source, now, location = source.location, con
             !Array.isArray(input) &&
             Object.keys(input).length <= 32, "invalid_key_set");
         const j = input, asserted = j.alg;
+        // Leaked private members are a publisher blunder the whole set rejects
+        // loudly, before any skip decision: skipping must never hide them.
+        ensure(!["d", "p", "q", "dp", "dq", "qi", "oth", "k"].some((k) => Object.hasOwn(j, k)), "invalid_key_set");
+        // A key whose alg names an algorithm this verifier does not use — an
+        // encryption key, or a signing name outside both registries — cannot
+        // satisfy any signature policy: skip it and keep the rest of the set.
+        if (typeof asserted === "string" && assertedJose(asserted) === undefined)
+            continue;
         ensure(asserted === undefined ||
             asserted === null ||
-            (typeof asserted === "string" &&
-                unwrap(algorithms(), "invalid_key_set").includes(asserted)), "invalid_key_set");
+            typeof asserted === "string", "invalid_key_set");
+        // RFC 7517 sources assert standard JOSE names; either spelling normalizes
+        // once, here, to the JOSE name, which exists for every registry entry.
+        const normalized = typeof asserted === "string" ? assertedJose(asserted) : undefined;
         const imported = Object.assign(Object.create(null), j);
-        if (typeof asserted === "string")
-            imported.alg = unwrap(resolveAlgorithm(asserted), "invalid_key_set").jose;
-        const key = unwrap(await PublicKey.import(imported), "invalid_key_set");
+        if (normalized !== undefined)
+            imported.alg = normalized;
+        const attempt = await PublicKey.import(imported);
+        if (!attempt.ok) {
+            // A well-formed key this verifier cannot import for signature work (an
+            // unknown kty or curve, RFC 7517 Section 5) is skipped like an
+            // out-of-registry alg; other import failures stay set rejections.
+            if (attempt.error.kind !== "crypto" || attempt.error.reason !== "invalid_key")
+                ensure(false, "invalid_key_set");
+            ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
+            continue;
+        }
+        const key = attempt.value;
         ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
         const thumbprint = unwrap(await key.thumbprint(), "invalid_key_set");
         ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
@@ -140,14 +164,15 @@ export async function bodyKeys(doc, source, now, location = source.location, con
             j.kid === thumbprint, "invalid_key_set");
         const nbf = Object.hasOwn(j, "nbf") ? keyTime(j.nbf) : null, exp = Object.hasOwn(j, "exp") ? keyTime(j.exp) : null;
         const publicJwk = unwrap(key.jwk(), "invalid_key_set");
-        const algorithm = (asserted ??
-            (publicJwk.kty === "OKP"
+        const algorithm = normalized === undefined
+            ? (publicJwk.kty === "OKP"
                 ? "ed25519"
                 : publicJwk.kty === "EC"
                     ? publicJwk.crv === "P-256"
                         ? "ecdsa-p256-sha256"
                         : "ecdsa-p384-sha384"
-                    : "rsa-pss-sha512"));
+                    : "rsa-pss-sha512")
+            : { jws: normalized };
         if (key.bind(algorithm).ok &&
             (nbf === null || now >= nbf) &&
             (exp === null || now < exp) &&
@@ -158,7 +183,7 @@ export async function bodyKeys(doc, source, now, location = source.location, con
                 keyId: kid,
                 thumbprint,
                 algorithm,
-                assertedAlgorithm: (asserted ?? null),
+                assertedAlgorithm: normalized ?? null,
                 origin: sourceOrigin(sourceUrl(location)),
                 sourceType: source.type,
                 location,

package/dist/discovery/cache.d.ts

@@ -1,17 +1,36 @@
 import { type Result } from "../result.ts";
 import { type Context } from "../context.ts";
 import { type DiscoverySource } from "./source.ts";
-import { type KeySet, type Resolution } from "./body.ts";
+import { type KeySet, type NotModified, type Resolution } from "./body.ts";
+/** A caller-owned discovery transport callback. With `validators`, an unchanged source answers 304 and the callback returns a `NotModified` outcome instead of a key set (RFC 9111 Section 4.3.4). */
 export type DiscoveryFetch = (source: DiscoverySource, options: {
     clock: () => number;
     context: Context;
-}) => Promise<Result<KeySet>>;
+    validators?: Readonly<{
+        etag: string;
+        lifetime: number;
+    }>;
+}) => Promise<Result<KeySet | NotModified>>;
+/** A caller-owned bounded cache of discovery key sets and failures. */
 export type DiscoveryCache = Readonly<{
+    /** Refresh a source from an explicit snapshot or configured fetch callback. */
     refresh: (source: unknown, snapshot?: unknown) => Promise<Result<KeySet>>;
+    /** Resolve an eligible key through the bounded discovery cache. */
     resolve: (source: unknown, keyId: unknown, options?: unknown) => Promise<Result<Resolution>>;
+    /** Remove a key by thumbprint from a cached source. */
     remove: (source: unknown, thumbprint: unknown) => Result<true>;
+    /** Invalidate a source's cached key set. */
     invalidate: (source: unknown) => Result<true>;
+    /** Close this capability and release its retained state. */
     close: () => Result<true>;
 }>;
+/**
+ * Internal to the resolver bridge, not exported from the package: resolve with the
+ * cache's own clock for fetching, storing, negative caching, and entry freshness, and
+ * decide the key's freshness on `decision`.
+ */
+export declare function resolveOnClock(cache: DiscoveryCache, s: unknown, kid: unknown, input: unknown, decision: () => number): Promise<Result<Resolution>>;
+/** Check the private brand of a discovery cache. */
 export declare function isDiscoveryCache(v: unknown): v is DiscoveryCache;
+/** Validate cache options and create a branded discovery cache. */
 export declare function createCache(input?: unknown): Result<DiscoveryCache>;

package/dist/discovery/cache.js

@@ -6,9 +6,20 @@ import { algorithmList, isKeySet, keySet, lookup, } from "./body.js";
 import { algorithms } from "../crypto/algorithm.js";
 import { ensure, unwrap, failure, options, clockValue, systemClock, inspectable, } from "./support.js";
 const caches = new WeakSet();
+const decided = new WeakMap();
+/**
+ * Internal to the resolver bridge, not exported from the package: resolve with the
+ * cache's own clock for fetching, storing, negative caching, and entry freshness, and
+ * decide the key's freshness on `decision`.
+ */
+export function resolveOnClock(cache, s, kid, input, decision) {
+    return decided.get(cache)(s, kid, input, decision);
+}
+/** Check the private brand of a discovery cache. */
 export function isDiscoveryCache(v) {
     return !!v && typeof v === "object" && caches.has(v);
 }
+/** Validate cache options and create a branded discovery cache. */
 export function createCache(input = {}) {
     try {
         const a = options(input, ["clock", "maxSources", "maxInFlight", "fetch"]);
@@ -47,6 +58,31 @@ export function createCache(input = {}) {
         }
         function store(e, result, clock, snapshot = false) {
             const now = clockValue(clock);
+            if (result.ok && "notModified" in result.value && result.value.notModified === true) {
+                // RFC 9111 Section 4.3.4: the stored representation stays; the 304's
+                // own freshness directives and validator replace the stored ones. The
+                // set never claims freshness beyond its earliest still-live key.
+                const current = e.set;
+                if (!current ||
+                    sourceIdentity(current.source) !== sourceIdentity(e.source))
+                    return err(discoveryError("source_unavailable"));
+                const fresh = result.value;
+                const set = filter(current, e);
+                const earliest = Object.values(set.keys).reduce((bound, key) => Math.min(bound, key.expiresAt), Infinity);
+                const merged = keySet({
+                    ...set,
+                    etag: fresh.etag,
+                    fetchedAt: fresh.fetchedAt,
+                    expiresAt: Math.min(fresh.expiresAt, earliest),
+                });
+                e.fetchedAtHighWater = Math.max(e.fetchedAtHighWater ?? merged.fetchedAt, merged.fetchedAt);
+                delete e.failureUntil;
+                if (merged.expiresAt > now)
+                    e.set = merged;
+                else
+                    delete e.set;
+                return ok(merged);
+            }
             if (result.ok) {
                 ensure(isKeySet(result.value) &&
                     sourceIdentity(result.value.source) === sourceIdentity(e.source), "source_unavailable");
@@ -82,13 +118,36 @@ export function createCache(input = {}) {
                     signal: controller.signal,
                 }), "invalid_options");
                 const generation = e.generation;
+                // A stored validator makes the revalidation conditional: an unchanged
+                // source answers 304 and its key set stays put. A CIMD document is not
+                // the key set itself — its 304 says nothing about the nested JWKS it
+                // names — so CIMD sources always revalidate unconditionally.
+                let validators;
+                const stored = e.set;
+                if (stored && stored.etag !== null && e.source.type !== "cimd") {
+                    const now = clockValue(clock);
+                    // A 304 keeps the stored keys, so it can only renew a set whose
+                    // every key is still inside its own expiry; any dead key forces a
+                    // full fetch.
+                    const alive = Object.keys(stored.keys).length > 0 &&
+                        Object.values(stored.keys).every((key) => now < key.expiresAt);
+                    if (alive)
+                        validators = Object.freeze({
+                            etag: stored.etag,
+                            lifetime: Math.max(stored.expiresAt - stored.fetchedAt, 0),
+                        });
+                }
                 flight = {
                     controller,
                     waiters: 0,
                     work: Promise.resolve().then(async () => {
                         let result;
                         try {
-                            const r = await run(c, () => fetcher(e.source, { clock, context: c }));
+                            const r = await run(c, () => fetcher(e.source, {
+                                clock,
+                                context: c,
+                                ...(validators ? { validators } : {}),
+                            }));
                             result =
                                 !r.ok && r.error.kind !== "discovery"
                                     ? err(discoveryError(r.error.reason === "deadline_exceeded"
@@ -134,6 +193,48 @@ export function createCache(input = {}) {
                 }
             }
         }
+        async function resolveWith(s, kid, input, decision) {
+            try {
+                ensure(isDiscoverySource(s), "invalid_source");
+                const a = options(input, ["algorithms", "clock", "context", "timeoutMs"]);
+                const choices = algorithmList(Object.hasOwn(a, "algorithms")
+                    ? a.algorithms
+                    : unwrap(algorithms(), "invalid_options"));
+                ensure(keyIdValid(s, kid), "unknown_key");
+                ensure(s.keyId === "directory" || !s.revoked.includes(kid), "revoked_key");
+                // With a decision clock (the resolver bridge), the cache's own clock fetches, stores,
+                // and judges entry freshness; the decision clock judges only the key returned.
+                const selectedClock = decision === undefined && Object.hasOwn(a, "clock") ? a.clock : clockFn;
+                const now = clockValue(selectedClock);
+                const decisionNow = decision === undefined ? now : clockValue(decision);
+                ensure(!Object.hasOwn(a, "context") || isContext(a.context), "invalid_options");
+                let context = a.context;
+                if (Object.hasOwn(a, "timeoutMs")) {
+                    ensure(Number.isSafeInteger(a.timeoutMs) &&
+                        a.timeoutMs >= 1 &&
+                        a.timeoutMs <= 300000, "invalid_options");
+                    context = unwrap(withDeadline({
+                        timeoutMs: Math.min(a.timeoutMs, s.timeoutMs),
+                        ...(context ? { parent: context } : {}),
+                    }), "invalid_options");
+                }
+                ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
+                const e = enroll(s);
+                ensure(e.source.keyId === "directory" ||
+                    (!e.removed.has(kid) && !e.source.revoked.includes(kid)), "revoked_key");
+                if (e.set && now < e.set.expiresAt)
+                    return await lookup(e.set, kid, choices, decisionNow);
+                ensure(e.failureUntil === undefined || now >= e.failureUntil, "source_unavailable");
+                const fetched = await load(e, selectedClock, context);
+                if (!fetched.ok)
+                    return fetched;
+                ensure(e.source.keyId === "directory" || !e.removed.has(kid), "revoked_key");
+                return await lookup(filter(fetched.value, e), kid, choices, decision === undefined ? clockValue(selectedClock) : clockValue(decision), fetched.value.expiresAt === fetched.value.fetchedAt);
+            }
+            catch (e) {
+                return failure(e, "source_unavailable");
+            }
+        }
         const out = {
             async refresh(s, snapshot) {
                 try {
@@ -149,44 +250,8 @@ export function createCache(input = {}) {
                     return failure(e, "source_unavailable");
                 }
             },
-            async resolve(s, kid, input = {}) {
-                try {
-                    ensure(isDiscoverySource(s), "invalid_source");
-                    const a = options(input, ["algorithms", "clock", "context", "timeoutMs"]);
-                    const choices = algorithmList(Object.hasOwn(a, "algorithms")
-                        ? a.algorithms
-                        : unwrap(algorithms(), "invalid_options"));
-                    ensure(keyIdValid(s, kid), "unknown_key");
-                    ensure(s.keyId === "directory" || !s.revoked.includes(kid), "revoked_key");
-                    const selectedClock = Object.hasOwn(a, "clock") ? a.clock : clockFn;
-                    const now = clockValue(selectedClock);
-                    ensure(!Object.hasOwn(a, "context") || isContext(a.context), "invalid_options");
-                    let context = a.context;
-                    if (Object.hasOwn(a, "timeoutMs")) {
-                        ensure(Number.isSafeInteger(a.timeoutMs) &&
-                            a.timeoutMs >= 1 &&
-                            a.timeoutMs <= 300000, "invalid_options");
-                        context = unwrap(withDeadline({
-                            timeoutMs: Math.min(a.timeoutMs, s.timeoutMs),
-                            ...(context ? { parent: context } : {}),
-                        }), "invalid_options");
-                    }
-                    ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
-                    const e = enroll(s);
-                    ensure(e.source.keyId === "directory" ||
-                        (!e.removed.has(kid) && !e.source.revoked.includes(kid)), "revoked_key");
-                    if (e.set && now < e.set.expiresAt)
-                        return await lookup(e.set, kid, choices, now);
-                    ensure(e.failureUntil === undefined || now >= e.failureUntil, "source_unavailable");
-                    const fetched = await load(e, selectedClock, context);
-                    if (!fetched.ok)
-                        return fetched;
-                    ensure(e.source.keyId === "directory" || !e.removed.has(kid), "revoked_key");
-                    return await lookup(filter(fetched.value, e), kid, choices, clockValue(selectedClock), fetched.value.expiresAt === fetched.value.fetchedAt);
-                }
-                catch (e) {
-                    return failure(e, "source_unavailable");
-                }
+            resolve(s, kid, input = {}) {
+                return resolveWith(s, kid, input);
             },
             remove(s, kid) {
                 try {
@@ -227,6 +292,7 @@ export function createCache(input = {}) {
             },
         };
         caches.add(out);
+        decided.set(out, (src, kid, input, decision) => resolveWith(src, kid, input, decision));
         return ok(inspectable(out, { kind: "DiscoveryCache" }));
     }
     catch (e) {

package/dist/discovery/headers.d.ts

@@ -1,9 +1,12 @@
 import { type FieldOccurrence as Field } from "../message/index.ts";
 import type { DiscoverySource } from "./source.ts";
+/** Ordered discovery response header names and string or byte values. */
 export type Headers = readonly (readonly [string, string | Uint8Array])[];
 export declare function fields(headers: unknown): readonly Field[];
 export declare function values(fs: readonly Field[], name: string): string[];
 export declare function header(fs: readonly Field[], name: string): string | null;
 export declare function httpDate(input: string | null, now: number): number | null;
 export declare function expiry(fs: readonly Field[], source: DiscoverySource, now: number): number;
+/** RFC 9111 Section 4.3.4: whether a response carries freshness directives of its own. */
+export declare function hasFreshness(fs: readonly Field[]): boolean;
 export declare function mediaType(fs: readonly Field[], type: DiscoverySource["type"]): void;

package/dist/discovery/headers.js

@@ -85,6 +85,25 @@ export function expiry(fs, source, now) {
         .toLowerCase()
         .split(",")
         .map((v) => v.trim());
+    return expiryFromControls(fs, source, now, controls);
+}
+/** RFC 9111 Section 4.3.4: whether a response carries freshness directives of its own. */
+export function hasFreshness(fs) {
+    if (header(fs, "expires") !== null)
+        return true;
+    const controls = values(fs, "cache-control")
+        .join(",")
+        .toLowerCase()
+        .split(",")
+        .map((v) => v.trim());
+    // Only freshness-changing names count: max-age, no-cache, no-store. A
+    // directive like `public` leaves the stored lifetime in force.
+    return controls.some((v) => {
+        const name = v.split("=", 1)[0].trim();
+        return name === "no-store" || name === "no-cache" || name === "max-age";
+    });
+}
+function expiryFromControls(fs, source, now, controls) {
     const ages = controls
         .filter((v) => v.startsWith("max-age="))
         .map((v) => v.slice(8).replace(/^"+|"+$/g, ""));
@@ -102,8 +121,15 @@ export function expiry(fs, source, now) {
     }
     const age = header(fs, "age") ?? "0";
     ensure(/^[0-9]{1,10}$/.test(age), "invalid_response");
+    // RFC 9111 Sections 5.2.2.3 and 5.2.2.4: no-store and no-cache also arrive
+    // qualified, as in no-cache="content-type" (and the RFC 7234 quoted form whose
+    // member can itself contain commas). Match the directive name before any "=",
+    // so every spelling still forces revalidation.
     return (now +
-        (controls.some((v) => v === "no-store" || v === "no-cache")
+        (controls.some((v) => {
+            const name = v.split("=", 1)[0].trim();
+            return name === "no-store" || name === "no-cache";
+        })
             ? 0
             : Math.max(Math.min(ttl, source.maxTtl) - Math.max(Number(age), now - date, 0), 0)));
 }

package/dist/discovery/index.d.ts

@@ -1,17 +1,29 @@
 import { type Result } from "../result.ts";
 import { fromSnapshot } from "./snapshot.ts";
 import { type Resolution } from "./body.ts";
+/** A discovery-backed signature key resolver. @inline */
 export type KeyResolver = (request: unknown) => Promise<Result<Readonly<{
     algorithm: Resolution["algorithm"];
     key: Resolution["key"];
 }>>>;
+/** Create a resolver over a branded key set or caller-owned discovery cache. */
 declare function resolver(input: unknown, opts: unknown): Result<KeyResolver>;
+/** Snapshot resolution and explicit discovery operations. */
 export declare const Discovery: Readonly<{
+    /**
+     * Create a resolver over a branded key set or caller-owned discovery cache.
+     * Options are `algorithms` and an optional `clock` (integer Unix seconds); pass the
+     * policy's freshness clock so key freshness and signature freshness agree. Without
+     * `clock`, a key set uses system time and a cache uses its own clock. With a cache,
+     * `clock` decides only the returned key's freshness; the cache keeps its own clock for
+     * fetching and storing.
+     */
     resolver: typeof resolver & {
+        /** Parse a caller-supplied discovery snapshot without fetching it. */
         fromSnapshot: typeof fromSnapshot;
     };
 }>;
 export { DiscoverySource, isDiscoverySource, directoryId } from "./source.ts";
-export { isKeySet, isResolution, type KeySet, type Resolution, } from "./body.ts";
+export { isKeySet, isResolution, type KeySet, type NotModified, type Resolution, } from "./body.ts";
 export { createCache, isDiscoveryCache, type DiscoveryCache, type DiscoveryFetch, } from "./cache.ts";
 export type { Headers } from "./snapshot.ts";

package/dist/discovery/index.js

@@ -2,13 +2,17 @@ import { ok } from "../result.js";
 import { snapshotOptions } from "../brand.js";
 import { isKeySet, algorithmList } from "./body.js";
 import { isDiscoverySource } from "./source.js";
-import { isDiscoveryCache } from "./cache.js";
+import { isDiscoveryCache, resolveOnClock } from "./cache.js";
 import { fromSnapshot } from "./snapshot.js";
-import { ensure, unwrap, failure } from "./support.js";
+import { ensure, unwrap, failure, clockValue } from "./support.js";
+/** Create a resolver over a branded key set or caller-owned discovery cache. */
 function resolver(input, opts) {
     try {
-        const a = unwrap(snapshotOptions(opts, ["algorithms"]), "invalid_options");
+        const a = unwrap(snapshotOptions(opts, ["algorithms", "clock"]), "invalid_options");
         const allowed = algorithmList(a.algorithms);
+        // An explicit clock, usually the policy's freshness clock; system time otherwise.
+        const clock = Object.hasOwn(a, "clock") ? a.clock : undefined;
+        ensure(clock === undefined || typeof clock === "function", "invalid_options");
         let set, cache, source;
         if (isKeySet(input))
             set = input;
@@ -24,9 +28,15 @@ function resolver(input, opts) {
                     typeof request === "object" &&
                     Object.hasOwn(request, "keyid"), "unknown_key");
                 const kid = request.keyid;
+                // A clock decides key freshness only: a throwing or invalid clock is
+                // invalid_options on both paths, and a cache still fetches and stores on its own clock.
                 const result = set
-                    ? await set.lookup(kid, allowed)
-                    : await cache.resolve(source, kid, { algorithms: allowed });
+                    ? clock === undefined
+                        ? await set.lookup(kid, allowed)
+                        : await set.lookup(kid, allowed, clockValue(clock))
+                    : clock === undefined
+                        ? await cache.resolve(source, kid, { algorithms: allowed })
+                        : await resolveOnClock(cache, source, kid, { algorithms: allowed }, clock);
                 return result.ok
                     ? ok(Object.freeze({
                         algorithm: result.value.algorithm,
@@ -44,8 +54,22 @@ function resolver(input, opts) {
         return failure(e, "invalid_options");
     }
 }
-const Resolver = Object.freeze(Object.assign(resolver, { fromSnapshot }));
-export const Discovery = Object.freeze({ resolver: Resolver });
+const Resolver = Object.freeze(Object.assign(resolver, {
+    /** Parse a caller-supplied discovery snapshot without fetching it. */
+    fromSnapshot
+}));
+/** Snapshot resolution and explicit discovery operations. */
+export const Discovery = Object.freeze({
+    /**
+     * Create a resolver over a branded key set or caller-owned discovery cache.
+     * Options are `algorithms` and an optional `clock` (integer Unix seconds); pass the
+     * policy's freshness clock so key freshness and signature freshness agree. Without
+     * `clock`, a key set uses system time and a cache uses its own clock. With a cache,
+     * `clock` decides only the returned key's freshness; the cache keeps its own clock for
+     * fetching and storing.
+     */
+    resolver: Resolver
+});
 export { DiscoverySource, isDiscoverySource, directoryId } from "./source.js";
 export { isKeySet, isResolution, } from "./body.js";
 export { createCache, isDiscoveryCache, } from "./cache.js";

package/dist/discovery/node-connection.d.ts

@@ -3,5 +3,5 @@ export declare function checkPeer(observed: {
     address: string | undefined;
     port: number | undefined;
 }, address: string, port: number, permittedAddresses: readonly string[]): void;
-/** A connected peer denial terminates the address loop. */
+/** Peer and trust-store denials terminate the address loop unchanged. */
 export declare function allowConnectionRetry(error: unknown): void;

package/dist/discovery/node-connection.js

@@ -5,8 +5,8 @@ export function checkPeer(observed, address, port, permittedAddresses) {
     ensure(sameAddress(observed.address, address) && observed.port === port &&
         unwrap(addressAllowed(observed.address, permittedAddresses), "address_denied"), "address_denied");
 }
-/** A connected peer denial terminates the address loop. */
+/** Peer and trust-store denials terminate the address loop unchanged. */
 export function allowConnectionRetry(error) {
-    if (error && typeof error === "object" && "reason" in error && error.reason === "address_denied")
+    if (error && typeof error === "object" && "reason" in error && (error.reason === "address_denied" || error.reason === "transport_unavailable"))
         throw error;
 }

package/dist/discovery/node-trust.d.ts

@@ -0,0 +1,2 @@
+/** Classify OS trust permission failures without changing other errors. */
+export declare function systemCertificateError(error: unknown): never;

package/dist/discovery/node-trust.js

@@ -0,0 +1,9 @@
+import { discoveryError } from '../errors/types.js';
+/** Classify OS trust permission failures without changing other errors. */
+export function systemCertificateError(error) {
+    const deno = globalThis.Deno;
+    const PermissionError = deno?.errors?.NotCapable;
+    if (PermissionError && error instanceof PermissionError)
+        throw discoveryError('transport_unavailable');
+    throw error;
+}

package/dist/discovery/node.d.ts

@@ -1,15 +1,23 @@
 import { type Result } from "../result.ts";
-import { type KeySet } from "./body.ts";
+import { type KeySet, type NotModified } from "./body.ts";
 export type DiscoverySource = import("./source.ts").DiscoverySource;
+/** Fetch a discovery key set with bounded HTTPS, address, and redirect policies, unconditionally. A `validators` option is accepted and ignored, so this function wires directly as a cache's fetch callback; use `fetchWithValidators` for conditional revalidation. */
 export declare function fetch(source: unknown, input?: unknown): Promise<Result<KeySet>>;
+/** Conditionally fetch a discovery key set (RFC 9111 Section 4.3.4): send `If-None-Match` with the stored validator, and an unchanged source answers 304 as a `NotModified` outcome instead of a key set. `storedLifetime` seconds persist when the 304 carries no freshness directives of its own. */
+export declare function fetchWithValidators(source: unknown, etag: unknown, storedLifetime: unknown, input?: unknown): Promise<Result<KeySet | NotModified>>;
+/** Discovery resolution with the explicit Node HTTPS transport. */
 export declare const Discovery: Readonly<{
     resolver: ((input: unknown, opts: unknown) => Result<import("./index.ts").KeyResolver>) & {
         fromSnapshot: typeof import("./snapshot.ts").fromSnapshot;
     };
+    /** Fetch a discovery key set through the bounded Node HTTPS transport. */
     fetch: typeof fetch;
+    /** Conditionally fetch a discovery key set (RFC 9111 Section 4.3.4). */
+    fetchWithValidators: typeof fetchWithValidators;
 }>;
 /** Node source creation fails closed when the OS trust store is unavailable or empty. */
 export declare const DiscoverySource: Readonly<{
     directoryId: typeof import("./source.ts").directoryId;
+    /** Create a discovery source after validating Node transport options. */
     create(input: unknown): Result<import("./source.ts").DiscoverySource>;
 }>;