@shelbyb/daywalker-sdk 0.2.0 → 0.4.0

package/dist/client.js

@@ -1,5 +1,5 @@
 import { resolveConfig } from "./config.js";
-import { loadSigningKey, signRequest, verifyJwtLease, maskSecret, redactSecrets, } from "./crypto/index.js";
+import { loadSigningKey, signRequest, verifyJwtLease, maskSecret, redactSecrets, sha256Base64Url, } from "./crypto/index.js";
 import { DaywalkerAuthError, DaywalkerError, DaywalkerRateLimitError, } from "./types.js";
 function parseRetryAfter(headerValue) {
     if (!headerValue)
@@ -23,10 +23,158 @@ function generateNonce() {
         bin += String.fromCharCode(b);
     return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
+/** Validation results kept in memory; the least recently used are evicted past this. */
+export const MAX_VALIDATION_CACHE_ENTRIES = 1000;
+/** Longest 429 `Retry-After` waited out by default (`retry.maxRetryAfterMs`); longer ones return the 429. */
+export const MAX_RETRY_AFTER_MS = 60_000;
+/** Methods retried after a network error or timeout by default: repeating them can't change server state. */
+const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function isPlainJsonValue(value) {
+    if (Array.isArray(value))
+        return true;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+async function prepareBody(raw, signing) {
+    if (raw === undefined || raw === null)
+        return { bytes: null, send: null, replayable: true };
+    if (typeof raw === "string")
+        return { bytes: raw, send: raw, replayable: true };
+    if (raw instanceof Uint8Array)
+        return { bytes: raw, send: raw, replayable: true };
+    if (raw instanceof ArrayBuffer || ArrayBuffer.isView(raw)) {
+        const bytes = raw instanceof ArrayBuffer ? new Uint8Array(raw) : new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+        return { bytes, send: bytes, replayable: true };
+    }
+    if (raw instanceof URLSearchParams) {
+        const str = raw.toString();
+        return { bytes: str, send: str, contentType: "application/x-www-form-urlencoded;charset=UTF-8", replayable: true };
+    }
+    if (typeof Blob !== "undefined" && raw instanceof Blob) {
+        if (!signing)
+            return { bytes: null, send: raw, replayable: true };
+        const bytes = new Uint8Array(await raw.arrayBuffer());
+        return { bytes, send: bytes, contentType: raw.type || undefined, replayable: true };
+    }
+    const isFormData = typeof FormData !== "undefined" && raw instanceof FormData;
+    const isStream = typeof ReadableStream !== "undefined" && raw instanceof ReadableStream;
+    if (isFormData || isStream) {
+        if (signing) {
+            throw new DaywalkerError(`${isFormData ? "FormData" : "ReadableStream"} bodies can't be signed: their exact bytes aren't known up front, so no Content-Digest can be computed. Serialize the body to a string or Uint8Array first.`);
+        }
+        return { bytes: null, send: raw, replayable: !isStream };
+    }
+    if (typeof raw === "object" && isPlainJsonValue(raw)) {
+        const json = JSON.stringify(raw);
+        return { bytes: json, send: json, contentType: "application/json", replayable: true };
+    }
+    throw new DaywalkerError(`Unsupported fetch() body (${Object.prototype.toString.call(raw)}): pass a plain object or array (sent as JSON), a string, Uint8Array, ArrayBuffer, URLSearchParams or Blob`);
+}
+/** Resolves after `ms`, or rejects with the signal's reason as soon as it aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * The signal for one attempt: the caller's signal combined with a `timeoutMs` timer, via `AbortSignal.any`
+ * (Node >= 20.3) or a manual fallback. `cleanup()` clears the timer once response headers arrive.
+ */
+function attemptSignal(caller, timeoutMs) {
+    const signals = caller ? [caller] : [];
+    let timer;
+    if (timeoutMs > 0) {
+        const timeout = new AbortController();
+        timer = setTimeout(() => timeout.abort(new DOMException(`Request to Daywalker Auth timed out after ${timeoutMs}ms`, "TimeoutError")), timeoutMs);
+        signals.push(timeout.signal);
+    }
+    const clear = () => clearTimeout(timer);
+    if (signals.length <= 1)
+        return { signal: signals[0], cleanup: clear };
+    if (typeof AbortSignal.any === "function")
+        return { signal: AbortSignal.any(signals), cleanup: clear };
+    const combined = new AbortController();
+    const onAbort = (e) => combined.abort(e.target.reason);
+    for (const s of signals) {
+        if (s.aborted)
+            combined.abort(s.reason);
+        else
+            s.addEventListener("abort", onAbort, { once: true });
+    }
+    return {
+        signal: combined.signal,
+        cleanup: () => {
+            clear();
+            for (const s of signals)
+                s.removeEventListener("abort", onAbort);
+        },
+    };
+}
+/** Reads a response body, giving up (and cancelling it) after `timeoutMs` so a trickling body can't hang us. */
+async function readText(res, timeoutMs) {
+    if (!(timeoutMs > 0))
+        return res.text();
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            res.body?.cancel().catch(() => { });
+            reject(new DOMException(`Reading the Daywalker Auth response timed out after ${timeoutMs}ms`, "TimeoutError"));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([res.text(), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function isRedirect(res) {
+    return res.type === "opaqueredirect" || REDIRECT_STATUSES.has(res.status);
+}
+function redirectError(what, res) {
+    res.body?.cancel().catch(() => { });
+    return new DaywalkerError(`Daywalker Auth answered ${what} with a redirect (HTTP ${res.status}); refusing to follow it with credentials`, res.status || undefined, "UNEXPECTED_REDIRECT");
+}
+function isRateLimitWindow(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const w = value;
+    return ["limit", "remaining", "reset"].every((k) => typeof w[k] === "number" && Number.isFinite(w[k]));
+}
+/** Why a `valid: true` answer can't be trusted as a validation result, or null when its shape is sane. */
+function malformedValidation(json, payloadData) {
+    for (const src of [json, payloadData]) {
+        for (const k of ["serviceSlug", "tenantId", "tokenId", "tokenName", "userId", "stage"]) {
+            if (src[k] !== undefined && src[k] !== null && typeof src[k] !== "string")
+                return `${k} is not a string`;
+        }
+        for (const k of ["rateLimit", "rateLimitHourly"]) {
+            if (src[k] !== undefined && src[k] !== null && !isRateLimitWindow(src[k]))
+                return `${k} is not a rate limit window`;
+        }
+    }
+    return null;
+}
+/** Results are handed out as copies, so a caller mutating one can't alter what other callers get from the cache. */
+function cloneResult(result) {
+    return typeof structuredClone === "function" ? structuredClone(result) : JSON.parse(JSON.stringify(result));
+}
 export class Daywalker {
     _config;
     _rawConfig;
     _signingKeyPromise;
+    _previousSigningKeyPromise;
     _cache = new Map();
     _inflight = new Map();
     constructor(config = {}) {
@@ -62,41 +210,66 @@ export class Daywalker {
         }
         return this._signingKeyPromise;
     }
+    async getLoadedPreviousSigningKey() {
+        const raw = this._config.previousSigningKey;
+        if (!raw)
+            return null;
+        if (!this._previousSigningKeyPromise) {
+            this._previousSigningKeyPromise = loadSigningKey(raw);
+        }
+        return this._previousSigningKeyPromise;
+    }
     /**
-     * Signs and executes requests with automatic retry and exponential backoff on 429 responses.
+     * Signs and executes a request to Daywalker Auth (same origin as `authUrl` only).
+     * - Redirects are never followed: a 3xx throws a DaywalkerError (code UNEXPECTED_REDIRECT), so the API key,
+     *   signature and body never reach another URL and no redirect target's answer is trusted.
+     * - Each attempt times out after `timeoutMs` (default 5000ms) of waiting for response headers; the caller's
+     *   `signal` aborts immediately, including during backoff, and is never retried.
+     * - 429s are retried with exponential backoff, honoring `Retry-After` up to `retry.maxRetryAfterMs`. Network
+     *   errors and timeouts are retried only for GET / HEAD / OPTIONS, with an `idempotencyKey`, or when
+     *   `retry.retryNetworkErrors` is true. Options merge as defaults < `config.retry` < `init.retry`.
+     * - An explicit `Authorization` header is sent as given; otherwise `Bearer <apiKey>` is added. The signature
+     *   covers method, path, query, authority and Content-Digest, never Authorization.
      */
     async fetch(path, init) {
         const authUrl = this._config.authUrl;
         const url = new URL(path, authUrl);
+        // Absolute URLs to other hosts would otherwise receive the API key and a valid signature.
+        const authOrigin = new URL(authUrl).origin;
+        if (url.origin !== authOrigin) {
+            throw new DaywalkerError(`Refusing to send Daywalker credentials to ${url.origin}; fetch() only targets ${authOrigin}`);
+        }
         const method = (init?.method ?? (init?.body !== undefined ? "POST" : "GET")).toUpperCase();
         const doFetch = this._rawConfig.fetch ?? globalThis.fetch;
-        const retryOpts = {
-            maxRetries: init?.retry?.maxRetries ?? this._config.maxRetries ?? 3,
-            initialDelayMs: init?.retry?.initialDelayMs ?? 500,
-            maxDelayMs: init?.retry?.maxDelayMs ?? 30_000,
-            backoffFactor: init?.retry?.backoffFactor ?? 2,
-            jitter: init?.retry?.jitter ?? true,
-            ...init?.retry,
-        };
-        const rawBody = init?.body;
-        let bodyString = null;
-        if (rawBody !== undefined && rawBody !== null) {
-            if (typeof rawBody === "string") {
-                bodyString = rawBody;
-            }
-            else if (rawBody instanceof Uint8Array) {
-                bodyString = rawBody;
-            }
-            else if (typeof rawBody === "object") {
-                bodyString = JSON.stringify(rawBody);
-            }
+        const { retry: _retry, timeoutMs: _timeoutMs, idempotencyKey, body: rawBody, signal: callerSignal, ...requestInit } = init ?? {};
+        const retryOpts = { ...this._config.retry };
+        for (const [k, v] of Object.entries(init?.retry ?? {})) {
+            if (v !== undefined)
+                retryOpts[k] = v;
         }
+        const maxRetries = retryOpts.maxRetries ?? 3;
+        const initialDelayMs = retryOpts.initialDelayMs ?? 500;
+        const maxDelayMs = retryOpts.maxDelayMs ?? 30_000;
+        const backoffFactor = retryOpts.backoffFactor ?? 2;
+        const jitter = retryOpts.jitter ?? true;
+        const maxRetryAfterMs = retryOpts.maxRetryAfterMs ?? MAX_RETRY_AFTER_MS;
+        const retryNetworkErrors = retryOpts.retryNetworkErrors ?? (IDEMPOTENT_METHODS.has(method) || Boolean(idempotencyKey));
+        const timeoutMs = init?.timeoutMs ?? this._config.timeoutMs;
+        const backoff = (n) => {
+            let delayMs = initialDelayMs * Math.pow(backoffFactor, n - 1);
+            if (jitter)
+                delayMs = delayMs * (0.8 + Math.random() * 0.4);
+            return Math.min(delayMs, maxDelayMs);
+        };
+        callerSignal?.throwIfAborted();
         const signingKey = await this.getLoadedSigningKey();
+        const body = await prepareBody(rawBody, Boolean(signingKey));
         let attempt = 0;
         while (true) {
+            callerSignal?.throwIfAborted();
             const headers = new Headers(init?.headers);
-            if (rawBody !== undefined && !headers.has("content-type") && typeof rawBody === "object" && !(rawBody instanceof Uint8Array)) {
-                headers.set("content-type", "application/json");
+            if (body.contentType && !headers.has("content-type")) {
+                headers.set("content-type", body.contentType);
             }
             if (!headers.has("accept")) {
                 headers.set("accept", "application/json");
@@ -104,15 +277,18 @@ export class Daywalker {
             if (this._config.apiKey && !headers.has("authorization")) {
                 headers.set("authorization", `Bearer ${this._config.apiKey}`);
             }
+            if (idempotencyKey && !headers.has("idempotency-key")) {
+                headers.set("idempotency-key", idempotencyKey);
+            }
             if (signingKey) {
+                // apiKey is left out so the signer can't replace an explicit Authorization header.
                 const signedHeaders = await signRequest({
                     method,
-                    path: url.pathname,
+                    path: url.pathname + url.search,
                     authority: url.host,
-                    body: bodyString,
+                    body: body.bytes,
                     key: signingKey,
                     keyid: this._config.keyId ?? undefined,
-                    apiKey: this._config.apiKey ?? undefined,
                     nonce: generateNonce(),
                 });
                 for (const [k, v] of Object.entries(signedHeaders)) {
@@ -121,45 +297,80 @@ export class Daywalker {
                     }
                 }
             }
+            const { signal, cleanup } = attemptSignal(callerSignal, timeoutMs);
             const reqInit = {
-                ...init,
+                ...requestInit,
                 method,
                 headers,
-                body: bodyString ?? undefined,
+                body: body.send ?? undefined,
+                redirect: requestInit.redirect === "error" ? "error" : "manual",
+                signal,
             };
             let res;
             try {
                 res = await doFetch(url.toString(), reqInit);
             }
             catch (err) {
-                if (attempt < (retryOpts.maxRetries ?? 3)) {
+                if (callerSignal?.aborted)
+                    throw err;
+                if (retryNetworkErrors && body.replayable && attempt < maxRetries) {
                     attempt++;
-                    const delay = (retryOpts.initialDelayMs ?? 500) * Math.pow(retryOpts.backoffFactor ?? 2, attempt - 1);
-                    await new Promise((r) => setTimeout(r, delay));
+                    await sleep(backoff(attempt), callerSignal);
                     continue;
                 }
                 throw err;
             }
-            if (res.status === 429 && attempt < (retryOpts.maxRetries ?? 3)) {
-                attempt++;
+            finally {
+                cleanup();
+            }
+            if (isRedirect(res)) {
+                throw redirectError(url.pathname, res);
+            }
+            if (res.status === 429 && body.replayable && attempt < maxRetries) {
                 const retryAfterSec = parseRetryAfter(res.headers.get("retry-after"));
-                let delayMs = (retryOpts.initialDelayMs ?? 500) * Math.pow(retryOpts.backoffFactor ?? 2, attempt - 1);
-                if (retryOpts.jitter) {
-                    delayMs = delayMs * (0.8 + Math.random() * 0.4);
-                }
+                let delayMs = backoff(attempt + 1);
                 if (retryAfterSec !== undefined) {
+                    // Retrying sooner than the server asked is pointless; waiting longer than this is the caller's call.
+                    if (retryAfterSec * 1000 > maxRetryAfterMs)
+                        return res;
                     delayMs = Math.max(delayMs, retryAfterSec * 1000);
                 }
-                delayMs = Math.min(delayMs, retryOpts.maxDelayMs ?? 30_000);
-                await new Promise((r) => setTimeout(r, delayMs));
+                attempt++;
+                res.body?.cancel().catch(() => { });
+                await sleep(delayMs, callerSignal);
                 continue;
             }
             return res;
         }
     }
+    _cacheGet(key) {
+        const entry = this._cache.get(key);
+        if (!entry)
+            return undefined;
+        this._cache.delete(key);
+        if (entry.expiresAt <= Date.now())
+            return undefined;
+        this._cache.set(key, entry); // most recently used goes last
+        return entry.result;
+    }
+    _cacheSet(key, result, ttlMs, notAfterMs = Infinity) {
+        const expiresAt = Math.min(Date.now() + ttlMs, notAfterMs);
+        if (expiresAt <= Date.now())
+            return;
+        this._cache.delete(key);
+        this._cache.set(key, { result, expiresAt });
+        while (this._cache.size > MAX_VALIDATION_CACHE_ENTRIES) {
+            this._cache.delete(this._cache.keys().next().value);
+        }
+    }
     /**
-     * Validates incoming bearer tokens with memory caching and discriminated union return.
+     * Validates an incoming bearer token with memory caching and discriminated union return.
      * Supports zero-egress offline verification for JWT token leases when Daywalker's public key is configured.
+     * A missing token is always rejected (401); it never falls back to this service's own API key —
+     * use `validateServiceKey()` for that.
+     * Online validation fails closed: only a 2xx JSON answer with `valid: true` and a sane shape is accepted.
+     * Outages (network errors, timeouts, 5xx, malformed answers) return status 503 with error NETWORK_ERROR or
+     * SERVICE_UNAVAILABLE and are never cached. Each call gets its own copy of the (cached) result.
      */
     async validateToken(tokenOrOptions, options) {
         let token;
@@ -173,7 +384,7 @@ export class Daywalker {
             offlineOnly = options?.offlineOnly ?? false;
         }
         else {
-            token = tokenOrOptions?.token ?? this._config.apiKey ?? undefined;
+            token = tokenOrOptions?.token ?? undefined;
             serviceSlug = (tokenOrOptions?.serviceSlug ?? this._config.serviceSlug ?? "").toLowerCase();
             forceRefresh = tokenOrOptions?.forceRefresh ?? false;
             offlineOnly = tokenOrOptions?.offlineOnly ?? false;
@@ -181,15 +392,16 @@ export class Daywalker {
         if (!token) {
             return {
                 ok: false,
-                error: "CONFIGURATION_ERROR",
-                status: 400,
+                error: "INVALID_TOKEN",
+                status: 401,
                 message: "Missing token to validate",
             };
         }
-        const cacheKey = `${serviceSlug || "default"}:${token}`;
-        const cached = this._cache.get(cacheKey);
-        if (!forceRefresh && cached && cached.expiresAt > Date.now()) {
-            return cached.result;
+        // Keyed by a hash so raw tokens are never held as cache keys.
+        const cacheKey = `${serviceSlug || "default"}:${await sha256Base64Url(token)}`;
+        const cached = forceRefresh ? undefined : this._cacheGet(cacheKey);
+        if (cached) {
+            return cloneResult(cached);
         }
         // Check for offline JWT lease verification
         if (this._config.daywalkerPublicKey && token.split(".").length === 3) {
@@ -197,6 +409,7 @@ export class Daywalker {
                 token,
                 publicKey: this._config.daywalkerPublicKey,
                 expectedServiceSlug: serviceSlug || undefined,
+                expectedIssuer: this._config.leaseIssuer ?? undefined,
             });
             if (jwtResult.valid && jwtResult.payload) {
                 const payload = jwtResult.payload;
@@ -220,9 +433,10 @@ export class Daywalker {
                     },
                 };
                 if (this._config.cacheTtlMs > 0) {
-                    this._cache.set(cacheKey, { result, expiresAt: Date.now() + this._config.cacheTtlMs });
+                    // Never cache a lease past its own expiry.
+                    this._cacheSet(cacheKey, result, this._config.cacheTtlMs, payload.exp * 1000);
                 }
-                return result;
+                return cloneResult(result);
             }
             else if (offlineOnly) {
                 return {
@@ -245,21 +459,28 @@ export class Daywalker {
         const inflightKey = `${cacheKey}`;
         const pending = this._inflight.get(inflightKey);
         if (pending)
-            return pending;
+            return pending.then(cloneResult);
         const run = this._validateOnline(token, serviceSlug, cacheKey).finally(() => {
             this._inflight.delete(inflightKey);
         });
         this._inflight.set(inflightKey, run);
-        return run;
+        return run.then(cloneResult);
     }
     async _validateOnline(token, serviceSlug, cacheKey) {
         const negTtl = this._config.negativeCacheTtlMs;
         const fail = (result) => {
-            if (negTtl > 0 && result.error !== "RATE_LIMITED" && result.error !== "NETWORK_ERROR") {
-                this._cache.set(cacheKey, { result, expiresAt: Date.now() + negTtl });
+            if (negTtl > 0 && result.error !== "RATE_LIMITED" && result.error !== "NETWORK_ERROR" && result.error !== "SERVICE_UNAVAILABLE") {
+                this._cacheSet(cacheKey, result, negTtl);
             }
             return result;
         };
+        // Says nothing about the token, so never cached.
+        const unavailable = (message) => ({
+            ok: false,
+            error: "SERVICE_UNAVAILABLE",
+            status: 503,
+            message: redactSecrets(message),
+        });
         try {
             const validateBody = { token };
             if (serviceSlug) {
@@ -268,10 +489,42 @@ export class Daywalker {
             const res = await this.fetch("/api/v1/tokens/validate", {
                 method: "POST",
                 body: validateBody,
+                // Validation is read-only, so repeating it after a lost response is safe.
+                retry: { retryNetworkErrors: this._config.retry.retryNetworkErrors ?? true },
             });
-            const json = (await res.json().catch(() => ({})));
-            if (res.status === 200 && json.valid !== false) {
-                const payloadData = (typeof json.data === "object" && json.data ? json.data : json);
+            // A body that times out is an outage (thrown to NETWORK_ERROR below), never an empty answer.
+            const text = await readText(res, this._config.timeoutMs);
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = undefined;
+            }
+            const json = (parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {});
+            const isObject = json === parsed;
+            if (res.status === 429) {
+                const retryAfter = parseRetryAfter(res.headers.get("retry-after")) ?? (typeof json.retryAfter === "number" ? json.retryAfter : undefined);
+                return {
+                    ok: false,
+                    error: "RATE_LIMITED",
+                    status: 429,
+                    message: redactSecrets((typeof json.message === "string" && json.message) || "Rate limit exceeded"),
+                    retryAfter,
+                };
+            }
+            if (res.status >= 500) {
+                return unavailable(`Daywalker Auth is unavailable (HTTP ${res.status})`);
+            }
+            if (res.ok && isObject && json.valid === true) {
+                const payloadData = (json.data === undefined ? json : json.data);
+                if (!payloadData || typeof payloadData !== "object" || Array.isArray(payloadData)) {
+                    return unavailable("Daywalker Auth returned a malformed validation result (data is not an object)");
+                }
+                const problem = malformedValidation(json, payloadData);
+                if (problem) {
+                    return unavailable(`Daywalker Auth returned a malformed validation result (${problem})`);
+                }
                 const data = {
                     serviceSlug: json.serviceSlug || serviceSlug,
                     tenantId: (payloadData.tenantId || payloadData.userId || json.tenantId || json.userId || ""),
@@ -288,22 +541,16 @@ export class Daywalker {
                     data,
                 };
                 if (this._config.cacheTtlMs > 0) {
-                    this._cache.set(cacheKey, { result, expiresAt: Date.now() + this._config.cacheTtlMs });
+                    this._cacheSet(cacheKey, result, this._config.cacheTtlMs);
                 }
                 return result;
             }
-            if (res.status === 429) {
-                const retryAfter = parseRetryAfter(res.headers.get("retry-after")) ?? json.retryAfter;
-                return {
-                    ok: false,
-                    error: "RATE_LIMITED",
-                    status: 429,
-                    message: redactSecrets(json.message || "Rate limit exceeded"),
-                    retryAfter,
-                };
+            // A 2xx is only a token verdict when it says so; anything else (HTML, `{}`, a captive portal) fails closed.
+            if (res.ok && !(isObject && (json.valid === false || typeof json.error === "string"))) {
+                return unavailable(`Daywalker Auth returned no validation result (HTTP ${res.status})`);
             }
             let error = "INVALID_TOKEN";
-            const errMsg = (json.message || json.error || "");
+            const errMsg = String((typeof json.message === "string" && json.message) || (typeof json.error === "string" && json.error) || "");
             if (json.error === "EXPIRED" || /expired/i.test(errMsg)) {
                 error = "EXPIRED";
             }
@@ -313,7 +560,8 @@ export class Daywalker {
             return fail({
                 ok: false,
                 error,
-                status: res.status,
+                // `{ valid: false }` may come with a 200; never hand adapters a success status for a rejection.
+                status: res.ok ? 401 : res.status,
                 message: redactSecrets(errMsg || `Validation failed with HTTP ${res.status}`),
             });
         }
@@ -326,6 +574,21 @@ export class Daywalker {
             };
         }
     }
+    /**
+     * Service health check: validates this service's own configured API key (DAYWALKER_API_KEY).
+     * Never use this to authenticate an incoming request.
+     */
+    async validateServiceKey(options) {
+        if (!this._config.apiKey) {
+            return {
+                ok: false,
+                error: "CONFIGURATION_ERROR",
+                status: 500,
+                message: "DAYWALKER_API_KEY is not set",
+            };
+        }
+        return this.validateToken(this._config.apiKey, options);
+    }
     /**
      * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
      */
@@ -355,19 +618,52 @@ export class Daywalker {
     }
     /**
      * Fetches Daywalker's public JWKS (GET /.well-known/jwks.json) for offline lease verification.
+     * Uses the configured `fetch`, sends no credentials, never follows redirects and times out after `timeoutMs`.
      */
     async fetchJwks() {
-        const res = await globalThis.fetch(`${this._config.authUrl.replace(/\/+$/, "")}/.well-known/jwks.json`, { headers: { Accept: "application/json" } });
+        const doFetch = this._rawConfig.fetch ?? globalThis.fetch;
+        const { signal, cleanup } = attemptSignal(undefined, this._config.timeoutMs);
+        let res;
+        try {
+            res = await doFetch(`${this._config.authUrl.replace(/\/+$/, "")}/.well-known/jwks.json`, {
+                headers: { Accept: "application/json" },
+                redirect: "manual",
+                signal,
+            });
+        }
+        finally {
+            cleanup();
+        }
+        if (isRedirect(res))
+            throw redirectError("/.well-known/jwks.json", res);
         if (!res.ok)
             throw new DaywalkerError(`Could not fetch JWKS (HTTP ${res.status})`, res.status);
-        return (await res.json());
+        let json = null;
+        try {
+            json = JSON.parse(await readText(res, this._config.timeoutMs));
+        }
+        catch (err) {
+            if (err.name === "TimeoutError")
+                throw err;
+        }
+        if (!json || typeof json !== "object" || !Array.isArray(json.keys)) {
+            throw new DaywalkerError("JWKS response is not a JWK Set");
+        }
+        return { keys: json.keys };
     }
     /**
-     * The public JWK(s) configured for this service.
+     * The public JWK(s) configured for this service: the current signing key, then the previous one
+     * (`previousSigningKey`) during a rotation, so requests from instances still on the old key keep verifying.
      */
     async keys() {
         const key = await this.getLoadedSigningKey();
-        return { keys: key ? [key.publicJwk] : [] };
+        const keys = key ? [key.publicJwk] : [];
+        // A broken previous key must not take the current one offline; selfCheck() reports it.
+        const previous = await this.getLoadedPreviousSigningKey().catch(() => null);
+        if (previous && !keys.some((k) => k.kid === previous.publicJwk.kid)) {
+            keys.push(previous.publicJwk);
+        }
+        return { keys };
     }
     /**
      * Check configuration and verify signature readiness.
@@ -381,6 +677,9 @@ export class Daywalker {
         if (!signingKey) {
             problems.push("DAYWALKER_SIGNING_KEY is not set: requests will be sent without RFC 9421 signature");
         }
+        await this.getLoadedPreviousSigningKey().catch((err) => {
+            problems.push(`Previous signing key load error: ${err.message}`);
+        });
         const keyId = signingKey?.publicJwk.kid ?? null;
         const offlineVerificationReady = Boolean(this._config.daywalkerPublicKey);
         return {

package/dist/config.d.ts

@@ -1,22 +1,34 @@
-import type { DaywalkerConfig, PublicJwk, SigningKey } from "./types.js";
+import type { DaywalkerConfig, PublicJwk, PublicJwks, RetryOptions, SigningKey } from "./types.js";
 export interface ResolvedConfig {
     apiKey: string | null;
     signingKey: string | SigningKey | null;
+    /** Never signs; `keys()` publishes its public JWK alongside the current key during rotation. */
     previousSigningKey: string | SigningKey | null;
     keyId: string | null;
     serviceSlug: string | null;
     domain: string | null;
     domainSource: string | null;
-    daywalkerPublicKey: string | PublicJwk | null;
+    daywalkerPublicKey: string | PublicJwk | PublicJwks | null;
+    leaseIssuer: string | null;
     authUrl: string;
     cacheTtlMs: number;
     negativeCacheTtlMs: number;
     maxRetries: number;
+    /** `config.retry` with undefined fields dropped; per-request `init.retry` is layered on top. */
+    retry: RetryOptions;
+    timeoutMs: number;
     problems: string[];
 }
+/** Default per-attempt timeout for requests to Daywalker Auth. */
+export declare const DEFAULT_TIMEOUT_MS = 5000;
 /**
  * A public hostname from a URL or bare host, or null for anything that can't be fetched over
  * the internet (localhost, 0.0.0.0, IP addresses, single labels).
  */
 export declare function publicHostname(value: string | undefined | null): string | null;
+/**
+ * Throws unless `value` is an https: URL (http: is allowed only for localhost / 127.0.0.1 / [::1]),
+ * so API keys, SDK keys and write keys never travel in cleartext.
+ */
+export declare function assertSecureUrl(name: string, value: string): void;
 export declare function resolveConfig(options?: DaywalkerConfig): ResolvedConfig;