@request-seal/core 0.2.0 → 0.3.0

package/dist/discovery/cache.js

@@ -6,6 +6,15 @@ 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);
@@ -49,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");
@@ -84,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"
@@ -136,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 {
@@ -151,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 {
@@ -229,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

@@ -7,4 +7,6 @@ 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

@@ -10,13 +10,20 @@ export type KeyResolver = (request: unknown) => Promise<Result<Readonly<{
 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. */
+    /**
+     * 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,14 +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;
@@ -25,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,
@@ -51,7 +60,14 @@ const Resolver = Object.freeze(Object.assign(resolver, {
 }));
 /** Snapshot resolution and explicit discovery operations. */
 export const Discovery = Object.freeze({
-    /** Create a resolver over a branded key set or caller-owned discovery cache. */
+    /**
+     * 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";

package/dist/discovery/node.d.ts

@@ -1,8 +1,10 @@
 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. */
+/** 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>) & {
@@ -10,6 +12,8 @@ export declare const Discovery: Readonly<{
     };
     /** 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<{

package/dist/discovery/node.js

@@ -3,15 +3,16 @@ import { promises as dns } from "node:dns";
 import { isIP } from "node:net";
 import * as tls from "node:tls";
 import { connect, checkServerIdentity } from "node:tls";
-import { err } from "../result.js";
+import { X509Certificate } from "node:crypto";
+import { err, ok } from "../result.js";
 import { withDeadline, isContext, run, remainingMs, } from "../context.js";
-import { discoveryError, custodyError } from "../errors/types.js";
+import { discoveryError } from "../errors/types.js";
 import { encodeBase64 } from "../bytes.js";
 import { Discovery as CoreDiscovery } from "./index.js";
 import { sourceUrl, normalizedHost, sourceAuthority, sourceOrigin, isDiscoverySource, DiscoverySource as CoreSource, } from "./source.js";
 import { addressAllowed } from "./address.js";
 import { ensure, unwrap, failure, options, clockValue, systemClock, sslError, list, } from "./support.js";
-import { fields, header, expiry, mediaType } from "./headers.js";
+import { fields, header, expiry, hasFreshness, mediaType } from "./headers.js";
 import { bodyDocument } from "./body.js";
 import { fromResource } from "./snapshot.js";
 import { decodeBody } from "./gzip.js";
@@ -42,6 +43,10 @@ async function resolve(host, context, servers) {
             ]);
             if (found.some((r) => r.status === "rejected" && r.reason?.code === "ETIMEOUT"))
                 throw discoveryError("deadline_exceeded");
+            // An authoritative NXDOMAIN on every query is a configuration error:
+            // the configured domain does not exist, so retrying cannot help.
+            if (found.every((r) => r.status === "rejected" && r.reason?.code === "ENOTFOUND"))
+                throw discoveryError("domain_not_found");
             answers = found.flatMap((r, i) => r.status === "fulfilled"
                 ? r.value.map((address) => ({ address, family: i === 0 ? 4 : 6 }))
                 : []);
@@ -54,7 +59,13 @@ async function resolve(host, context, servers) {
         try {
             answers = await lookup(host, { all: true });
         }
-        catch {
+        catch (error) {
+            // getaddrinfo's authoritative name-not-found is the same configuration
+            // error; any other resolver trouble may succeed on a later retry.
+            if (error &&
+                typeof error === "object" &&
+                error.code === "ENOTFOUND")
+                throw discoveryError("domain_not_found");
             throw discoveryError("resolution_failed");
         }
     }
@@ -66,6 +77,12 @@ async function resolve(host, context, servers) {
     ensure(addresses.length >= 1 && addresses.length <= 64, "resolution_failed");
     return addresses;
 }
+/**
+ * The OS trust store, or undefined when this runtime provides no usable one: Node before
+ * 22.15.0 (and Deno 2.5.6) lack `tls.getCACertificates`, and a host can return an empty
+ * store. Bundled roots are never a fallback (ADR 0007); callers get
+ * `discovery/transport_unavailable`, the same refusal as a denied store.
+ */
 function systemCertificates() {
     if (typeof tls.getCACertificates !== "function")
         return undefined;
@@ -77,6 +94,27 @@ function systemCertificates() {
         systemCertificateError(error);
     }
 }
+/**
+ * Check that the peer certificate names the host. An IP literal is matched against the
+ * certificate's iPAddress names by OpenSSL (`X509Certificate.checkIP`), never against DNS
+ * names or the subject. Node 22.23.1's `tls.checkServerIdentity` IDNA-normalizes the host
+ * before testing for an IP, and `domainToASCII("::1")` is "", so every IPv6 literal fails
+ * there with ERR_TLS_CERT_ALTNAME_INVALID; DNS hosts keep `tls.checkServerIdentity`.
+ */
+function checkHostIdentity(host, cert) {
+    if (!isIP(host))
+        return checkServerIdentity(host, cert);
+    try {
+        if (new X509Certificate(cert.raw).checkIP(host) !== undefined)
+            return undefined;
+    }
+    catch {
+        // A certificate OpenSSL cannot parse names no address.
+    }
+    return Object.assign(new Error("certificate does not name the IP address"), {
+        code: "ERR_TLS_CERT_ALTNAME_INVALID",
+    });
+}
 function tlsSocket(ip, url, source, context) {
     remaining(context);
     const host = normalizedHost(url), roots = source.cacerts;
@@ -86,7 +124,7 @@ function tlsSocket(ip, url, source, context) {
             encodeBase64(der) +
             "\n-----END CERTIFICATE-----");
     if (!ca)
-        throw custodyError("unsupported_format");
+        throw discoveryError("transport_unavailable");
     return new Promise((done, fail) => {
         const socket = connect(Object.assign(Object.create(null), {
             host: ip,
@@ -96,7 +134,7 @@ function tlsSocket(ip, url, source, context) {
             minVersion: "TLSv1.2",
             ALPNProtocols: ["http/1.1"],
             ca,
-            checkServerIdentity: (_name, cert) => checkServerIdentity(host, cert),
+            checkServerIdentity: (_name, cert) => checkHostIdentity(host, cert),
             lookup: () => {
                 throw discoveryError("address_denied");
             },
@@ -146,7 +184,7 @@ async function connected(url, source, context, servers) {
     }
     throw last;
 }
-async function get(url, source, context, servers) {
+async function get(url, source, context, servers, etag) {
     const socket = await connected(url, source, context, servers);
     // HTTPS receives only an already connected, peer-checked TLS socket. No proxy,
     // pooled connection or late DNS lookup participates in this private agent.
@@ -176,6 +214,7 @@ async function get(url, source, context, servers) {
                         : "application/json, application/jwk-set+json",
                     "Accept-Encoding": "gzip",
                     Connection: "close",
+                    ...(typeof etag === "string" ? { "If-None-Match": etag } : {}),
                 },
                 lookup: () => {
                     throw discoveryError("address_denied");
@@ -252,7 +291,14 @@ async function get(url, source, context, servers) {
                 }
             };
             socket.prependListener("data", onWire);
-            req.on("information", info => reject(discoveryError("unexpected_status", info.statusCode)));
+            // RFC 9110 Section 15.2: interim responses are provisional and precede
+            // the final status. Five are skipped, the reference bound; a sixth
+            // names a misbehaving publisher and rejects as a malformed response.
+            let interims = 0;
+            req.on("information", (info) => {
+                if (++interims > 5)
+                    reject(discoveryError("invalid_response"));
+            });
             req.on("upgrade", (res, upgraded) => {
                 reject(discoveryError("unexpected_status", res.statusCode));
                 upgraded.destroy();
@@ -354,8 +400,8 @@ function redirectUrl(current, location) {
         throw discoveryError("redirect_denied");
     }
 }
-async function resource(url, source, context, servers, hops = 0) {
-    const { status, fs, encoded } = await get(url, source, context, servers);
+async function resource(url, source, context, servers, hops = 0, etag) {
+    const { status, fs, encoded } = await get(url, source, context, servers, etag);
     if ([301, 302, 303, 307, 308].includes(status)) {
         ensure(source.maxRedirects > 0, "redirect_denied");
         ensure(hops < source.maxRedirects, "redirect_limit");
@@ -364,8 +410,15 @@ async function resource(url, source, context, servers, hops = 0) {
         const target = redirectUrl(url, location);
         ensure(source.redirectScope === "any_https" ||
             sourceOrigin(target) === sourceOrigin(sourceUrl(source.location)), "redirect_denied");
-        return resource(target, source, context, servers, hops + 1);
+        // A validator never crosses a redirect: the target is a different
+        // resource representation.
+        return resource(target, source, context, servers, hops + 1, undefined);
     }
+    // RFC 9111 Section 15.4.5: 304 is valid only as the answer to the
+    // conditional this client sent; an unsolicited 304 falls through to the
+    // unexpected-status rejection below.
+    if (status === 304 && typeof etag === "string")
+        return { notModified: true, fields: fs, location: url.href };
     if (status !== 200)
         throw discoveryError("unexpected_status", status);
     mediaType(fs, source.type);
@@ -375,13 +428,37 @@ async function resource(url, source, context, servers, hops = 0) {
     remaining(context);
     return { fields: fs, encoded, decoded, location: url.href };
 }
-/** Fetch a discovery key set with bounded HTTPS, address, and redirect policies. */
+/** 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 async function fetch(source, input = {}) {
+    const r = await conditional(source, input, undefined);
+    // No validator was sent, so a 304 cannot occur; keep the total anyway.
+    if (r.ok && "notModified" in r.value && r.value.notModified === true)
+        return err(discoveryError("invalid_response"));
+    return r;
+}
+/** 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 async function fetchWithValidators(source, etag, storedLifetime, input = {}) {
+    try {
+        ensure(typeof etag === "string" &&
+            etag.length >= 1 &&
+            etag.length <= 512 &&
+            Number.isSafeInteger(storedLifetime) &&
+            storedLifetime >= 0, "invalid_options");
+    }
+    catch (e) {
+        return failure(e);
+    }
+    return conditional(source, input, {
+        etag: etag,
+        lifetime: storedLifetime,
+    });
+}
+async function conditional(source, input, validator) {
     try {
         ensure(isDiscoverySource(source), "invalid_source");
         if (source.cacerts === "os" && !systemCertificates())
-            return err(custodyError("unsupported_format"));
-        const a = options(input, ["timeoutMs", "clock", "context", "dnsServers"]);
+            return err(discoveryError("transport_unavailable"));
+        const a = options(input, ["timeoutMs", "clock", "context", "dnsServers", "validators"]);
         const timeout = Object.hasOwn(a, "timeoutMs")
             ? a.timeoutMs
             : source.timeoutMs;
@@ -418,15 +495,38 @@ export async function fetch(source, input = {}) {
         }), "invalid_options");
         const result = await run(context, async () => {
             try {
-                const outer = await resource(sourceUrl(source.location), source, context, servers);
+                const outer = await resource(sourceUrl(source.location), source, context, servers, 0, validator?.etag);
                 const now = clockValue(clock);
+                if ("notModified" in outer) {
+                    // RFC 9111 Sections 3.2 and 4.3.4: a 304's own directives
+                    // recalculate freshness; without them the stored representation's
+                    // lifetime persists. A different strong validator identifies a
+                    // different representation, so it cannot renew this one.
+                    const updated = header(outer.fields, "etag");
+                    ensure(updated === null || updated.length <= 512, "invalid_response");
+                    ensure(updated === null || updated === validator.etag, "invalid_response");
+                    const fresh = Object.freeze({
+                        notModified: true,
+                        etag: validator.etag,
+                        fetchedAt: now,
+                        expiresAt: hasFreshness(outer.fields)
+                            ? expiry(outer.fields, source, now)
+                            : now + validator.lifetime,
+                    });
+                    return ok(fresh);
+                }
                 if (source.type === "cimd") {
                     const doc = bodyDocument(outer.decoded, source);
                     ensure(doc.client_id === source.location, "client_id_mismatch");
                     ensure(!(Object.hasOwn(doc, "jwks") && Object.hasOwn(doc, "jwks_uri")), "ambiguous_key_source");
                     if (Object.hasOwn(doc, "jwks_uri")) {
                         const url = sourceUrl(doc.jwks_uri);
-                        ensure(sourceOrigin(url) === sourceOrigin(sourceUrl(source.location)), "redirect_denied");
+                        ensure(
+                        // Compare against the origin that served this document, not the
+                        // configured one: a permissive redirect scope can legitimately
+                        // move the document to a mirror, and its jwks_uri names that
+                        // mirror.
+                        sourceOrigin(url) === sourceOrigin(sourceUrl(outer.location)), "redirect_denied");
                         // The subresource has JWKS media/body ceilings, original CIMD provenance.
                         const nestedSource = unwrap(DiscoverySource.create({
                             ...source,
@@ -434,6 +534,10 @@ export async function fetch(source, input = {}) {
                             location: url.href,
                         }), "invalid_source");
                         const nested = await resource(url, nestedSource, context, servers);
+                        // The nested subresource is always fetched unconditionally, so a
+                        // 304 cannot occur here; keep the rejection total anyway.
+                        if ("notModified" in nested)
+                            throw discoveryError("unexpected_status");
                         const result = await fromResource(source, nested.decoded, nested.encoded, now, nested.fields, nested.location, expiry(outer.fields, source, now), true, context);
                         remaining(context);
                         return result;
@@ -458,7 +562,9 @@ export async function fetch(source, input = {}) {
 /** Discovery resolution with the explicit Node HTTPS transport. */
 export const Discovery = Object.freeze({ ...CoreDiscovery,
     /** Fetch a discovery key set through the bounded Node HTTPS transport. */
-    fetch });
+    fetch,
+    /** Conditionally fetch a discovery key set (RFC 9111 Section 4.3.4). */
+    fetchWithValidators });
 /** Node source creation fails closed when the OS trust store is unavailable or empty. */
 export const DiscoverySource = Object.freeze({
     ...CoreSource,
@@ -467,7 +573,7 @@ export const DiscoverySource = Object.freeze({
         try {
             const result = CoreSource.create(input);
             if (result.ok && result.value.cacerts === "os" && !systemCertificates())
-                return err(custodyError("unsupported_format"));
+                return err(discoveryError("transport_unavailable"));
             return result;
         }
         catch (error) {

package/dist/discovery/proof.js

@@ -4,7 +4,7 @@ import { Message, Body, TransportFacts, } from "../message/index.js";
 import { SignatureBase } from "../signature-base/index.js";
 import { Crypto } from "../crypto/index.js";
 import { digest } from "../crypto/subtle.js";
-import { algorithms } from "../crypto/algorithm.js";
+import { algorithms, joseId } from "../crypto/algorithm.js";
 import { encodeBase64 } from "../bytes.js";
 import { sourceAuthority, sourceUrl, thumbprintId } from "./source.js";
 import { ensure, unwrap } from "./support.js";
@@ -145,7 +145,7 @@ export async function possessionProof(source, keys, location, fs, encoded, now,
         for (const algorithm of unwrap(algorithms(), "directory_signature_invalid")) {
             ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
             if ((entry.assertedAlgorithm === null ||
-                entry.assertedAlgorithm === algorithm) &&
+                entry.assertedAlgorithm === joseId(algorithm)) &&
                 entry.key.bind(algorithm).ok &&
                 (!p.has("alg") || textParam(p, "alg") === algorithm)) {
                 if ((await Crypto.verify(algorithm, entry.key, sig.value.value, base)).ok) {

package/dist/discovery/snapshot.js

@@ -57,6 +57,8 @@ export async function fromResource(source, decoded, encoded, now, fs, location,
         }
         const bodyRevision = await revision(decoded);
         ensure(!context || remainingMs(context) > 0, "deadline_exceeded");
+        const storedEtag = header(fs, "etag");
+        ensure(storedEtag === null || storedEtag.length <= 512, "invalid_response");
         return ok(keySet({
             source,
             origin: sourceOrigin(sourceUrl(location)),
@@ -65,6 +67,7 @@ export async function fromResource(source, decoded, encoded, now, fs, location,
             expiresAt,
             revision: bodyRevision,
             proof: proven.proof,
+            etag: storedEtag,
         }));
     }
     catch (e) {