@shelbyb/daywalker-sdk 0.5.0 → 0.7.0

package/dist/client.js

@@ -1,5 +1,8 @@
 import { parseServiceSlugs, resolveConfig } from "./config.js";
-import { loadSigningKey, signRequest, verifyJwtLease, leaseServices, maskSecret, redactSecrets, sha256Base64Url, } from "./crypto/index.js";
+import { API_KEY_PATTERN, SAFE_IDENTIFIER_PATTERN, SERVICE_SLUG_PATTERN } from "./crypto/signatures.js";
+import { parseStoredSigningKey } from "./keystore/index.js";
+import { loadSigningKey, loadPublicKey, signRequest, verifyJwtLease, leaseServices, maskSecret, redactSecrets, sha256Base64Url, generateDpopKey, createDpopProof, verifyDpopProof, importSigningKey, generateSigningKey, registerPublicKey, revokeSigningKey, keySlotFor, randomInstanceId, calculateJwkThumbprint, base64UrlToBytes, utf8ToString, } from "./crypto/index.js";
+import { webcrypto } from "./crypto/webcrypto.js";
 import { DaywalkerAuthError, DaywalkerError, DaywalkerRateLimitError, } from "./types.js";
 function parseRetryAfter(headerValue) {
     if (!headerValue)
@@ -17,7 +20,7 @@ function parseRetryAfter(headerValue) {
 }
 function generateNonce() {
     const bytes = new Uint8Array(16);
-    globalThis.crypto.getRandomValues(bytes);
+    webcrypto.getRandomValues(bytes);
     let bin = "";
     for (const b of bytes)
         bin += String.fromCharCode(b);
@@ -121,10 +124,43 @@ function attemptSignal(caller, timeoutMs) {
         },
     };
 }
-/** Reads a response body, giving up (and cancelling it) after `timeoutMs` so a trickling body can't hang us. */
+/**
+ * Reads a response body as text, giving up (and cancelling it) after `timeoutMs` so a trickling body can't
+ * hang us, and refusing bodies over `MAX_RESPONSE_BYTES` so a huge one can't exhaust memory.
+ */
 async function readText(res, timeoutMs) {
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+        res.body?.cancel().catch(() => { });
+        throw new DaywalkerError(`Daywalker Auth response is too large (${declared} bytes)`);
+    }
+    const read = async () => {
+        if (!res.body)
+            return res.text();
+        const reader = res.body.getReader();
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > MAX_RESPONSE_BYTES) {
+                reader.cancel().catch(() => { });
+                throw new DaywalkerError(`Daywalker Auth response is larger than ${MAX_RESPONSE_BYTES} bytes`);
+            }
+            chunks.push(value);
+        }
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const c of chunks) {
+            bytes.set(c, offset);
+            offset += c.byteLength;
+        }
+        return utf8ToString(bytes);
+    };
     if (!(timeoutMs > 0))
-        return res.text();
+        return read();
     let timer;
     const timeout = new Promise((_resolve, reject) => {
         timer = setTimeout(() => {
@@ -133,12 +169,25 @@ async function readText(res, timeoutMs) {
         }, timeoutMs);
     });
     try {
-        return await Promise.race([res.text(), timeout]);
+        return await Promise.race([read(), timeout]);
     }
     finally {
         clearTimeout(timer);
     }
 }
+/** A JSON object from a response body (bounded, with a timeout), or `{}` when it isn't one. */
+async function readJsonObject(res, timeoutMs) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readText(res, timeoutMs));
+    }
+    catch (err) {
+        if (err.name === "TimeoutError" || err instanceof DaywalkerError)
+            throw err;
+        return {};
+    }
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
 function isRedirect(res) {
     return res.type === "opaqueredirect" || REDIRECT_STATUSES.has(res.status);
 }
@@ -146,6 +195,38 @@ 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");
 }
+/**
+ * A failed client credentials grant or refresh as a validation result. Missing configuration is a 500;
+ * anything else (invalid_client, access_denied, an outage) is a 503, since it says nothing about the
+ * caller's token. Never cached.
+ */
+function credentialFailure(err) {
+    if (err.code === "CONFIGURATION_ERROR") {
+        return { ok: false, error: "CONFIGURATION_ERROR", status: 500, message: err.message };
+    }
+    return {
+        ok: false,
+        error: "SERVICE_UNAVAILABLE",
+        status: 503,
+        message: redactSecrets(`Could not obtain an OAuth access token${err.code ? ` (${err.code})` : ""}: ${err.message}`),
+    };
+}
+/** The payload of a JWT this client was just issued over TLS; not verified, only read. */
+function decodeJwtClaims(jwt) {
+    try {
+        const claims = JSON.parse(utf8ToString(base64UrlToBytes(jwt.split(".")[1] ?? "")));
+        return claims && typeof claims === "object" ? claims : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The `code` (else `error`) of a JSON error answer, read from a copy so the caller still gets the body. */
+async function errorCode(res) {
+    const json = (await res.clone().json().catch(() => null));
+    const code = json?.code ?? json?.error;
+    return typeof code === "string" ? code : undefined;
+}
 function isRateLimitWindow(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -173,54 +254,431 @@ function malformedValidation(json, payloadData) {
 function cloneResult(result) {
     return typeof structuredClone === "function" ? structuredClone(result) : JSON.parse(JSON.stringify(result));
 }
+const DEFAULT_ISSUER = "https://auth.daywalker.dev";
+const TOKEN_PATH = "/api/v1/oauth/token";
+/**
+ * Longest a successful validation is cached (5 minutes), whatever `cacheTtlMs` says, so a revoked token
+ * can't stay accepted for long.
+ */
+export const MAX_CACHE_TTL_MS = 300_000;
+/** Longest incoming token accepted (characters); longer input is refused without calling Daywalker. */
+export const MAX_TOKEN_LENGTH = 8_192;
+/** Printable ASCII with no whitespace, quotes, commas or separators: anything else is not a token. */
+const TOKEN_PATTERN = /^[A-Za-z0-9._~+/=-]+$/;
+/** Access tokens are used for at most this long (seconds), whatever the token endpoint says. */
+const MAX_ACCESS_TOKEN_LIFETIME_SECONDS = 3_600;
+/** Largest response body read from Daywalker Auth. */
+const MAX_RESPONSE_BYTES = 1_048_576;
+/** How long a fetched JWKS (`jwks: "auto"`) is used before it is refetched. */
+export const JWKS_CACHE_TTL_MS = 600_000;
+/**
+ * Least time between two JWKS fetches, whatever triggers them (an unknown `kid`, an expired set, a failed
+ * fetch), so a flood of tokens naming made-up `kid`s costs at most one request to Daywalker per interval.
+ */
+export const JWKS_REFETCH_COOLDOWN_MS = 30_000;
+/** Keys looked at in a fetched JWKS; the rest are ignored. */
+const MAX_JWKS_KEYS = 16;
+/** An Ed25519 public key: 32 bytes, unpadded base64url. */
+const ED25519_X_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * The keys of a fetched JWKS that can verify Daywalker access tokens: Ed25519 signing keys for EdDSA with a
+ * `kid`, copied to fresh objects with nothing else on them. Anything else (RSA, EC, `alg: "none"`, private
+ * key material, encryption keys) is dropped.
+ */
+function usableJwks(keys) {
+    if (!Array.isArray(keys))
+        return [];
+    const out = [];
+    for (const k of keys.slice(0, MAX_JWKS_KEYS)) {
+        if (!k || typeof k !== "object")
+            continue;
+        const j = k;
+        if (j.kty !== "OKP" || j.crv !== "Ed25519" || typeof j.x !== "string" || !ED25519_X_PATTERN.test(j.x))
+            continue;
+        if ((j.alg !== undefined && j.alg !== "EdDSA") || (j.use !== undefined && j.use !== "sig") || j.d !== undefined)
+            continue;
+        if (typeof j.kid !== "string" || j.kid === "" || j.kid.length > 256)
+            continue;
+        out.push({ kty: "OKP", crv: "Ed25519", x: j.x, kid: j.kid, use: "sig", alg: "EdDSA" });
+    }
+    return out;
+}
+/** The `kid` a JWT's (unverified) header names, used only to pick a key; undefined when there is none. */
+function jwtKid(token) {
+    try {
+        const header = JSON.parse(utf8ToString(base64UrlToBytes(token.split(".")[0] ?? "")));
+        return header && typeof header === "object" && typeof header.kid === "string" ? header.kid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A copy of `value` that can't be changed: nested objects and arrays are frozen too. */
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}
+/** A local key as a signer; its private key never leaves the closure. */
+function localSigner(key, keyId, source) {
+    const privateKey = key.privateKey;
+    return Object.freeze({
+        signer: Object.freeze({
+            keyId,
+            sign: async (data) => new Uint8Array(await webcrypto.sign("Ed25519", privateKey, data)),
+            publicJwk: key.publicJwk,
+        }),
+        publicJwk: key.publicJwk,
+        source,
+    });
+}
 export class Daywalker {
-    _config;
-    _rawConfig;
-    _signingKeyPromise;
-    _previousSigningKeyPromise;
-    _cache = new Map();
-    _inflight = new Map();
+    #config;
+    /** The secret-free, frozen view handed out by `config`. */
+    #publicConfig;
+    #fetch;
+    #publicOrigin;
+    #dpopReplayStore;
+    /** `config.signer` and `config.keyStore`, captured (methods bound) at construction so later edits can't swap them. */
+    #externalSigner;
+    #keyStore;
+    #signerPromise = null;
+    /** Ephemeral mode: this process's key slot, its current key, the rotation in flight, and when to retry one. */
+    #ephemeralSlot;
+    #ephemeral = null;
+    #ephemeralRotation = null;
+    #ephemeralRetryAt = 0;
+    /** Bumped whenever the ephemeral key is replaced; tokens requested under an older generation are stale. */
+    #keyGeneration = 0;
+    #closed = false;
+    #signingKeyPromise;
+    #previousSigningKeyPromise;
+    #cache = new Map();
+    #inflight = new Map();
+    /** The last JWKS fetched with usable keys (`jwks: "auto"`), kept when a later fetch fails. */
+    #jwks = null;
+    #jwksFlight = null;
+    #jwksAttemptAt = -Infinity;
     constructor(config = {}) {
-        this._rawConfig = config;
-        this._config = resolveConfig(config);
+        // Everything is read once: changing the caller's config object later has no effect.
+        const resolved = resolveConfig(config);
+        resolved.cacheTtlMs = Math.max(0, Math.min(Number.isFinite(resolved.cacheTtlMs) ? resolved.cacheTtlMs : 0, MAX_CACHE_TTL_MS));
+        resolved.negativeCacheTtlMs = Math.max(0, Math.min(Number.isFinite(resolved.negativeCacheTtlMs) ? resolved.negativeCacheTtlMs : 0, MAX_CACHE_TTL_MS));
+        // Copies, so freezing never touches objects the caller still owns.
+        const copyKey = (k) => (k && typeof k === "object" ? { ...k, publicJwk: { ...k.publicJwk } } : k);
+        resolved.signingKey = copyKey(resolved.signingKey);
+        resolved.previousSigningKey = copyKey(resolved.previousSigningKey);
+        if (resolved.daywalkerPublicKey && typeof resolved.daywalkerPublicKey === "object") {
+            resolved.daywalkerPublicKey = JSON.parse(JSON.stringify(resolved.daywalkerPublicKey));
+        }
+        this.#config = deepFreeze(resolved);
+        this.#publicConfig = deepFreeze({
+            ...resolved,
+            serviceSlugs: [...resolved.serviceSlugs],
+            retry: { ...resolved.retry },
+            problems: [...resolved.problems],
+            apiKey: resolved.apiKey ? "[configured]" : null,
+            signingKey: resolved.signingKey ? "[configured]" : null,
+            previousSigningKey: resolved.previousSigningKey ? "[configured]" : null,
+        });
+        const doFetch = config.fetch ?? globalThis.fetch;
+        if (typeof doFetch !== "function")
+            throw new DaywalkerError("No fetch implementation available: pass config.fetch");
+        this.#fetch = doFetch;
+        this.#publicOrigin = resolved.publicOrigin;
+        this.#dpopReplayStore = config.dpopReplayStore;
+        const signer = config.signer;
+        if (signer) {
+            if (typeof signer.sign !== "function" || typeof signer.keyId !== "string" || !SAFE_IDENTIFIER_PATTERN.test(signer.keyId)) {
+                throw new DaywalkerError("config.signer needs a sign() function and a keyId of 1-128 safe characters");
+            }
+            this.#externalSigner = Object.freeze({
+                keyId: signer.keyId,
+                sign: signer.sign.bind(signer),
+                publicJwk: signer.publicJwk ? Object.freeze({ ...signer.publicJwk }) : undefined,
+            });
+        }
+        else {
+            this.#externalSigner = null;
+        }
+        const store = config.keyStore;
+        if (store && typeof store.load !== "function")
+            throw new DaywalkerError("config.keyStore needs a load() function");
+        if (store && resolved.ephemeralKey)
+            throw new DaywalkerError("Use either keyStore or ephemeralKey, not both");
+        this.#ephemeralSlot = resolved.ephemeralKey ? (resolved.ephemeralKey.instanceId ?? randomInstanceId()) : null;
+        this.#keyStore = store
+            ? Object.freeze({
+                load: store.load.bind(store),
+                saveIfAbsent: typeof store.saveIfAbsent === "function" ? store.saveIfAbsent.bind(store) : undefined,
+            })
+            : null;
+        // Instances of this class (not subclasses, which may still add fields) can't gain or change properties.
+        if (new.target === Daywalker)
+            Object.freeze(this);
     }
+    /** The resolved configuration, frozen, with the API key and private keys shown as "[configured]". */
     get config() {
-        return this._config;
+        return this.#publicConfig;
     }
     toJSON() {
         return {
-            serviceSlug: this._config.serviceSlug,
-            domain: this._config.domain,
-            authUrl: this._config.authUrl,
-            keyId: this._config.keyId,
-            apiKey: maskSecret(this._config.apiKey),
-            signingKey: this._config.signingKey ? "[configured]" : null,
-            daywalkerPublicKey: this._config.daywalkerPublicKey ? "[configured]" : null,
+            serviceSlug: this.#config.serviceSlug,
+            domain: this.#config.domain,
+            authUrl: this.#config.authUrl,
+            keyId: this.#config.keyId,
+            apiKey: maskSecret(this.#config.apiKey),
+            signingKey: this.#config.signingKey ? "[configured]" : null,
+            daywalkerPublicKey: this.#config.daywalkerPublicKey ? "[configured]" : null,
+            jwks: this.#config.jwks,
         };
     }
     // Node.js custom inspect masking
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toJSON();
     }
-    async getLoadedSigningKey() {
-        if (!this._config.signingKey)
+    async #getLoadedSigningKey() {
+        if (!this.#config.signingKey)
             return null;
-        if (typeof this._config.signingKey !== "string" && "privateKey" in this._config.signingKey) {
-            return this._config.signingKey;
+        if (typeof this.#config.signingKey !== "string" && "privateKey" in this.#config.signingKey) {
+            return this.#config.signingKey;
         }
-        if (!this._signingKeyPromise) {
-            this._signingKeyPromise = loadSigningKey(this._config.signingKey);
+        if (!this.#signingKeyPromise) {
+            this.#signingKeyPromise = loadSigningKey(this.#config.signingKey);
         }
-        return this._signingKeyPromise;
+        return this.#signingKeyPromise;
     }
-    async getLoadedPreviousSigningKey() {
-        const raw = this._config.previousSigningKey;
+    /**
+     * What signs this client's requests, resolved once: `config.signer` (KMS / HSM), else `signingKey`
+     * (DAYWALKER_SIGNING_KEY), else the key in `keyStore`, provisioned on first use. Null when none is set up.
+     * A failure isn't remembered, so the next request tries again.
+     */
+    #getSigner() {
+        if (this.#closed)
+            return Promise.reject(new DaywalkerError("This Daywalker client was closed", undefined, "CLIENT_CLOSED"));
+        if (this.#config.ephemeralKey && !this.#externalSigner && !this.#config.signingKey)
+            return this.#ephemeralSigner();
+        if (!this.#signerPromise) {
+            this.#signerPromise = this.#resolveSigner().catch((err) => {
+                this.#signerPromise = null;
+                throw err;
+            });
+        }
+        return this.#signerPromise;
+    }
+    async #resolveSigner() {
+        const external = this.#externalSigner;
+        if (external) {
+            if (external.publicJwk) {
+                // Prove once that the signer's key is the one claimed, before any request depends on it.
+                const { publicKey } = await loadPublicKey(external.publicJwk);
+                const challenge = webcrypto.getRandomValues(new Uint8Array(32));
+                const signature = await external.sign(challenge);
+                if (!(signature instanceof Uint8Array) || !(await webcrypto.verify("Ed25519", publicKey, signature, challenge))) {
+                    throw new DaywalkerAuthError("config.signer does not sign with the key in its publicJwk", 500, "CONFIGURATION_ERROR");
+                }
+            }
+            return Object.freeze({ signer: external, publicJwk: external.publicJwk, source: "signer" });
+        }
+        const local = await this.#getLoadedSigningKey();
+        if (local)
+            return localSigner(local, this.#config.keyId ?? local.publicJwk.kid, "signingKey");
+        if (this.#keyStore) {
+            const key = await this.#provisionFromStore(this.#keyStore);
+            return localSigner(key, key.publicJwk.kid, "keyStore");
+        }
+        return null;
+    }
+    async #loadStored(store) {
+        const raw = await store.load();
+        return raw === null || raw === undefined ? null : parseStoredSigningKey(raw);
+    }
+    /** Imports a stored key (non-extractable) after checking it belongs to this service and matches its keyId. */
+    async #useStored(stored) {
+        if (this.#config.domain && stored.domain !== this.#config.domain) {
+            throw new DaywalkerAuthError(`The stored signing key is registered for ${stored.domain}, but this service is ${this.#config.domain}. Remove it from the key store to provision one for ${this.#config.domain}.`, 500, "CONFIGURATION_ERROR");
+        }
+        const key = await importSigningKey(stored.privateKeyPkcs8Base64);
+        if (key.publicJwk.kid !== stored.keyId) {
+            throw new DaywalkerAuthError("The stored signing key does not match its keyId (corrupted or tampered with)", 500, "CONFIGURATION_ERROR");
+        }
+        return key;
+    }
+    /**
+     * Auto-provisioning. Loads the key from the store; when there is none, generates one, registers it for this
+     * service's domain (`POST /api/v1/keys/register`, with the API key) and saves it with `saveIfAbsent`. Only
+     * registered keys are ever stored, so a key planted in the store is never registered by this process. If
+     * another instance saved first, its key is used and the one registered here is reported for revocation.
+     */
+    async #provisionFromStore(store) {
+        const existing = await this.#loadStored(store);
+        if (existing)
+            return this.#useStored(existing);
+        if (!store.saveIfAbsent) {
+            throw new DaywalkerAuthError("The key store is read-only and holds no signing key: provision one with `npx daywalker init`", 500, "CONFIGURATION_ERROR");
+        }
+        if (!this.#config.apiKey) {
+            throw new DaywalkerAuthError("DAYWALKER_API_KEY is needed to register a signing key on first use", 500, "CONFIGURATION_ERROR");
+        }
+        const domain = this.#config.domain;
+        if (!domain) {
+            throw new DaywalkerAuthError("No public domain detected to register a signing key for: set DAYWALKER_DOMAIN", 500, "CONFIGURATION_ERROR");
+        }
+        const generated = await generateSigningKey();
+        // Another instance may have finished while we generated: prefer its key over registering a second one.
+        const raced = await this.#loadStored(store);
+        if (raced)
+            return this.#useStored(raced);
+        // Its own slot, so registering it never demotes a key another instance is already using.
+        await this.#register(generated.publicJwk, { instanceId: keySlotFor(generated.publicJwk.kid) });
+        const record = {
+            version: 1,
+            keyId: generated.publicJwk.kid,
+            domain,
+            privateKeyPkcs8Base64: generated.privateKeyPkcs8Base64,
+            createdAt: Math.floor(Date.now() / 1000),
+        };
+        if (await store.saveIfAbsent(record))
+            return this.#useStored(record);
+        const winner = await this.#loadStored(store);
+        if (!winner)
+            throw new DaywalkerAuthError("The key store refused the signing key but holds none", 500, "CONFIGURATION_ERROR");
+        // Another instance stored its key first: ours was registered but will never be used, so revoke it.
+        const revoked = await revokeSigningKey({ authUrl: this.#config.authUrl, apiKey: this.#config.apiKey, keyId: record.keyId, fetchFn: this.#fetch });
+        if (!revoked.ok) {
+            console.warn(`[daywalker] Unused signing key ${record.keyId} (${domain}) could not be revoked (${revoked.status} ${revoked.error}); revoke it with \`npx daywalker revoke ${record.keyId}\`.`);
+        }
+        return this.#useStored(winner);
+    }
+    /**
+     * Ephemeral mode: the current in-memory key, replaced in the same slot once a quarter of its lifetime is left.
+     * While the old key is still good for more than a minute, requests keep using it and the replacement registers
+     * in the background (Daywalker keeps the old one valid for 10 more minutes). A failed replacement is retried
+     * at most every 30 seconds.
+     */
+    async #ephemeralSigner() {
+        const now = Math.floor(Date.now() / 1000);
+        const ttl = this.#config.ephemeralKey.ttlSeconds;
+        const current = this.#ephemeral;
+        if (current && current.expiresAt - now > ttl / 4)
+            return current.signer;
+        const usable = current && current.expiresAt - now > 60;
+        if (usable && Date.now() < this.#ephemeralRetryAt)
+            return current.signer;
+        if (!this.#ephemeralRotation) {
+            this.#ephemeralRotation = this.#rotateEphemeral()
+                .catch((err) => {
+                this.#ephemeralRetryAt = Date.now() + 30_000;
+                throw err;
+            })
+                .finally(() => {
+                this.#ephemeralRotation = null;
+            });
+        }
+        if (usable) {
+            this.#ephemeralRotation.catch(() => { });
+            return current.signer;
+        }
+        return this.#ephemeralRotation;
+    }
+    /** Generates a non-extractable key in memory and registers it in this process's slot with a lifetime. */
+    async #rotateEphemeral() {
+        if (!this.#config.apiKey) {
+            throw new DaywalkerAuthError("DAYWALKER_API_KEY is needed to register an ephemeral signing key", 500, "CONFIGURATION_ERROR");
+        }
+        if (!this.#config.domain) {
+            throw new DaywalkerAuthError("No public domain detected to register a signing key for: set DAYWALKER_DOMAIN", 500, "CONFIGURATION_ERROR");
+        }
+        const ttl = this.#config.ephemeralKey.ttlSeconds;
+        const pair = (await webcrypto.generateKey({ name: "Ed25519" }, false, ["sign", "verify"]));
+        const { x } = (await webcrypto.exportKey("jwk", pair.publicKey));
+        const kid = await calculateJwkThumbprint({ crv: "Ed25519", kty: "OKP", x });
+        const publicJwk = { kty: "OKP", crv: "Ed25519", x, kid, use: "sig", alg: "EdDSA" };
+        const registration = await this.#register(publicJwk, { instanceId: this.#ephemeralSlot, ttlSeconds: ttl });
+        if (this.#closed) {
+            // close() ran while this registered: don't leave the key behind.
+            await revokeSigningKey({ authUrl: this.#config.authUrl, apiKey: this.#config.apiKey, keyId: kid, fetchFn: this.#fetch });
+            throw new DaywalkerError("This Daywalker client was closed", undefined, "CLIENT_CLOSED");
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const expiresAt = Math.min(registration.key?.expiresAt ?? Infinity, now + ttl);
+        const signer = localSigner({ privateKey: pair.privateKey, publicJwk }, kid, "ephemeral");
+        const replaced = this.#ephemeral !== null;
+        this.#ephemeral = { signer, keyId: kid, expiresAt };
+        // OAuth sessions are tied to the key that started them: tokens from before this point are now stale, even a
+        // grant still in flight, so the next accessToken() starts a session with the new key.
+        if (replaced)
+            this.#keyGeneration++;
+        return signer;
+    }
+    /**
+     * Shuts the client down: revokes its ephemeral signing key (which also ends the OAuth sessions it started)
+     * and forgets its tokens. Afterwards every call that needs Daywalker fails with CLIENT_CLOSED. Safe to call
+     * twice. Keys from `signingKey`, `keyStore` or `signer` are long-lived and are left alone.
+     */
+    async close() {
+        if (this.#closed)
+            return { revoked: [], failed: [] };
+        this.#closed = true;
+        await this.#ephemeralRotation?.catch(() => { });
+        const current = this.#ephemeral;
+        this.#ephemeral = null;
+        this.#tokens = null;
+        if (!current || !this.#config.apiKey)
+            return { revoked: [], failed: [] };
+        const result = await revokeSigningKey({ authUrl: this.#config.authUrl, apiKey: this.#config.apiKey, keyId: current.keyId, fetchFn: this.#fetch });
+        return result.ok ? { revoked: [current.keyId], failed: [] } : { revoked: [], failed: [current.keyId] };
+    }
+    /**
+     * Registers a public key with Daywalker for this service's domain. Failures become errors the validation
+     * paths map to 503 (an outage, or credentials Daywalker refuses), with Daywalker's code in the message and
+     * what to do about a full domain.
+     */
+    async #register(publicJwk, options) {
+        const registration = await registerPublicKey({
+            authUrl: this.#config.authUrl,
+            apiKey: this.#config.apiKey,
+            domain: this.#config.domain,
+            serviceSlug: this.#config.serviceSlugs.length > 0 ? this.#config.serviceSlugs.join(",") : undefined,
+            publicJwk,
+            instanceId: options.instanceId,
+            ttlSeconds: options.ttlSeconds,
+            fetchFn: this.#fetch,
+        });
+        if (registration.ok)
+            return registration;
+        const hint = registration.code === "KEY_LIMIT_REACHED"
+            ? " The domain has 20 live keys: list them with `npx daywalker keys` and revoke unused ones with `npx daywalker revoke <keyId>`."
+            : "";
+        const message = `Registering the signing key failed (${registration.status || "network"}${registration.code ? ` ${registration.code}` : ""}): ${registration.error ?? "unknown error"}.${hint}`;
+        if (registration.status === 0 || registration.status >= 500)
+            throw new DaywalkerError(message, registration.status || undefined);
+        throw new DaywalkerAuthError(message, 503, "KEY_REGISTRATION_FAILED");
+    }
+    /**
+     * Resolves the signing key now instead of on the first request: loads it, or provisions and registers it
+     * (see `keyStore`). Call it at startup to fail fast. Returns where the key came from and its id.
+     */
+    async provisionSigningKey() {
+        const active = await this.#getSigner();
+        return active ? { source: active.source, keyId: active.signer.keyId } : null;
+    }
+    #dpopKey = null;
+    /** The client's DPoP key, generated on first use. Issued tokens are bound to it for this client's life. */
+    #getDpopKey() {
+        return (this.#dpopKey ??= generateDpopKey());
+    }
+    async #getLoadedPreviousSigningKey() {
+        const raw = this.#config.previousSigningKey;
         if (!raw)
             return null;
-        if (!this._previousSigningKeyPromise) {
-            this._previousSigningKeyPromise = loadSigningKey(raw);
+        if (!this.#previousSigningKeyPromise) {
+            this.#previousSigningKeyPromise = loadSigningKey(raw);
         }
-        return this._previousSigningKeyPromise;
+        return this.#previousSigningKeyPromise;
     }
     /**
      * Signs and executes a request to Daywalker Auth (same origin as `authUrl` only).
@@ -231,21 +689,24 @@ export class Daywalker {
      * - 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.
+     * - An explicit `Authorization` header is sent as given; otherwise `DPoP <access token>` from the OAuth
+     *   client credentials flow (`accessToken()`) is added, with a DPoP proof bound to it. The API key is never
+     *   sent here: it only authenticates the client credentials grant. An answer of 401 ACCESS_TOKEN_EXPIRED
+     *   refreshes the token and retries once. The signature covers method, path, query, authority and
+     *   Content-Digest, never Authorization.
      */
     async fetch(path, init) {
-        const authUrl = this._config.authUrl;
+        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.
+        // Absolute URLs to other hosts would otherwise receive an access token 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 doFetch = this.#fetch;
         const { retry: _retry, timeoutMs: _timeoutMs, idempotencyKey, body: rawBody, signal: callerSignal, ...requestInit } = init ?? {};
-        const retryOpts = { ...this._config.retry };
+        const retryOpts = { ...this.#config.retry };
         for (const [k, v] of Object.entries(init?.retry ?? {})) {
             if (v !== undefined)
                 retryOpts[k] = v;
@@ -257,7 +718,7 @@ export class Daywalker {
         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 timeoutMs = init?.timeoutMs ?? this.#config.timeoutMs;
         const backoff = (n) => {
             let delayMs = initialDelayMs * Math.pow(backoffFactor, n - 1);
             if (jitter)
@@ -265,8 +726,12 @@ export class Daywalker {
             return Math.min(delayMs, maxDelayMs);
         };
         callerSignal?.throwIfAborted();
-        const signingKey = await this.getLoadedSigningKey();
-        const body = await prepareBody(rawBody, Boolean(signingKey));
+        const active = await this.#getSigner();
+        const body = await prepareBody(rawBody, Boolean(active));
+        // The token endpoint authenticates itself (see _tokenRequest); everything else gets an OAuth access token.
+        const isTokenEndpoint = url.pathname === TOKEN_PATH;
+        const autoAuth = !isTokenEndpoint && !new Headers(init?.headers).has("authorization");
+        let refreshedExpired = false;
         let attempt = 0;
         while (true) {
             callerSignal?.throwIfAborted();
@@ -277,21 +742,27 @@ export class Daywalker {
             if (!headers.has("accept")) {
                 headers.set("accept", "application/json");
             }
-            if (this._config.apiKey && !headers.has("authorization")) {
-                headers.set("authorization", `Bearer ${this._config.apiKey}`);
+            if (autoAuth) {
+                headers.set("authorization", `DPoP ${await this.accessToken()}`);
             }
             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.
+            // DPoP (RFC 9449) is mandatory on the token endpoint and when presenting a DPoP access token.
+            const auth = headers.get("authorization") ?? "";
+            const isDpopAuth = /^dpop\s+/i.test(auth);
+            if ((autoAuth || !headers.has("dpop")) && (isTokenEndpoint || isDpopAuth)) {
+                const accessToken = isDpopAuth ? auth.replace(/^dpop\s+/i, "") : undefined;
+                headers.set("dpop", await createDpopProof(await this.#getDpopKey(), { method, url: url.toString(), accessToken }));
+            }
+            if (active) {
+                // Signing never touches Authorization, so an explicit header is kept as given.
                 const signedHeaders = await signRequest({
                     method,
                     path: url.pathname + url.search,
                     authority: url.host,
                     body: body.bytes,
-                    key: signingKey,
-                    keyid: this._config.keyId ?? undefined,
+                    signer: active.signer,
                     nonce: generateNonce(),
                 });
                 for (const [k, v] of Object.entries(signedHeaders)) {
@@ -307,6 +778,8 @@ export class Daywalker {
                 headers,
                 body: body.send ?? undefined,
                 redirect: requestInit.redirect === "error" ? "error" : "manual",
+                // Never served from or stored in an HTTP cache (Next.js patches fetch to cache by default).
+                cache: "no-store",
                 signal,
             };
             let res;
@@ -329,6 +802,14 @@ export class Daywalker {
             if (isRedirect(res)) {
                 throw redirectError(url.pathname, res);
             }
+            if (res.status === 401 && autoAuth && !refreshedExpired && body.replayable && (await errorCode(res)) === "ACCESS_TOKEN_EXPIRED") {
+                // The server's clock says the token expired before ours did: refresh it and try once more.
+                refreshedExpired = true;
+                if (this.#tokens)
+                    this.#tokens = { ...this.#tokens, expiresAt: 0 };
+                res.body?.cancel().catch(() => { });
+                continue;
+            }
             if (res.status === 429 && body.replayable && attempt < maxRetries) {
                 const retryAfterSec = parseRetryAfter(res.headers.get("retry-after"));
                 let delayMs = backoff(attempt + 1);
@@ -346,100 +827,139 @@ export class Daywalker {
             return res;
         }
     }
-    _cacheGet(key) {
-        const entry = this._cache.get(key);
+    #cacheGet(key) {
+        const entry = this.#cache.get(key);
         if (!entry)
             return undefined;
-        this._cache.delete(key);
+        this.#cache.delete(key);
         if (entry.expiresAt <= Date.now())
             return undefined;
-        this._cache.set(key, entry); // most recently used goes last
-        return entry.result;
+        this.#cache.set(key, entry); // most recently used goes last
+        return entry;
     }
-    _cacheSet(key, result, ttlMs, notAfterMs = Infinity) {
+    #cacheSet(key, result, ttlMs, notAfterMs = Infinity, jkt) {
         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);
+        this.#cache.delete(key);
+        // Frozen, so nothing holding the entry can change what later callers get.
+        this.#cache.set(key, Object.freeze({ result: deepFreeze(cloneResult(result)), expiresAt, jkt }));
+        while (this.#cache.size > MAX_VALIDATION_CACHE_ENTRIES) {
+            this.#cache.delete(this.#cache.keys().next().value);
         }
     }
     /**
-     * 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.
+     * Checks the DPoP proof a DPoP-bound (`cnf.jkt`) access token must come with. Run on every request, cached
+     * token or not: a proof is single-use, so a copied token is worthless without the client's private key.
      */
-    async validateToken(tokenOrOptions, options) {
-        let token;
-        let serviceSlug;
-        let forceRefresh = false;
-        let offlineOnly = false;
-        if (typeof tokenOrOptions === "string") {
-            token = tokenOrOptions;
-            serviceSlug = (options?.serviceSlug ?? this._config.serviceSlug ?? "").toLowerCase();
-            forceRefresh = options?.forceRefresh ?? false;
-            offlineOnly = options?.offlineOnly ?? false;
-        }
-        else {
-            token = tokenOrOptions?.token ?? undefined;
-            serviceSlug = (tokenOrOptions?.serviceSlug ?? this._config.serviceSlug ?? "").toLowerCase();
-            forceRefresh = tokenOrOptions?.forceRefresh ?? false;
-            offlineOnly = tokenOrOptions?.offlineOnly ?? false;
-        }
-        if (!token) {
+    async #checkDpop(token, jkt, dpop) {
+        if (!dpop || typeof dpop.proof !== "string" || dpop.proof === "") {
             return {
                 ok: false,
-                error: "INVALID_TOKEN",
+                error: "DPOP_REQUIRED",
                 status: 401,
-                message: "Missing token to validate",
+                message: "This access token is DPoP-bound: present it as `Authorization: DPoP <token>` with a DPoP proof",
             };
         }
+        let url = dpop.url;
+        if (this.#publicOrigin) {
+            try {
+                const u = new URL(dpop.url);
+                url = `${this.#publicOrigin}${u.pathname}${u.search}`;
+            }
+            catch {
+                url = "";
+            }
+        }
+        const res = await verifyDpopProof({
+            proof: dpop.proof,
+            method: String(dpop.method ?? ""),
+            url,
+            accessToken: token,
+            expectedJkt: jkt,
+            replayStore: this.#dpopReplayStore,
+        });
+        return res.valid ? null : { ok: false, error: "INVALID_DPOP_PROOF", status: 401, message: res.error ?? "Invalid DPoP proof" };
+    }
+    /**
+     * Validates an incoming token with memory caching and a discriminated union result.
+     * - Access tokens (JWTs) are verified offline when Daywalker's public key is configured. A DPoP-bound
+     *   token (`cnf.jkt`) is only accepted with a valid DPoP proof (`options.dpop`; the adapters pass it).
+     * - Other tokens are validated online with `POST /api/v1/tokens/validate`, authenticated with this
+     *   service's own DPoP-bound access token. The answer must name the expected service.
+     * - A missing, oversized or malformed token is rejected (401) without calling Daywalker. A token is never
+     *   replaced by this service's own credentials: use `validateServiceCredentials()` 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) {
+        const opts = typeof tokenOrOptions === "string" ? { ...options, token: tokenOrOptions } : { ...(tokenOrOptions ?? {}) };
+        const token = opts.token;
+        const forceRefresh = opts.forceRefresh === true;
+        const offlineOnly = opts.offlineOnly === true;
+        if (token === undefined || token === null || token === "") {
+            return { ok: false, error: "INVALID_TOKEN", status: 401, message: "Missing token to validate" };
+        }
+        if (typeof token !== "string" || token.length > MAX_TOKEN_LENGTH || !TOKEN_PATTERN.test(token)) {
+            // Never forwarded, hashed or cached: it can't be a Daywalker token.
+            return { ok: false, error: "INVALID_TOKEN", status: 401, message: "Malformed token" };
+        }
+        const serviceSlug = String(opts.serviceSlug ?? this.#config.serviceSlug ?? "").toLowerCase();
+        if (serviceSlug && !SERVICE_SLUG_PATTERN.test(serviceSlug)) {
+            return { ok: false, error: "CONFIGURATION_ERROR", status: 500, message: "serviceSlug is not a valid Daywalker service slug" };
+        }
         // 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);
+        const cached = forceRefresh ? undefined : this.#cacheGet(cacheKey);
         if (cached) {
-            return cloneResult(cached);
+            if (cached.jkt) {
+                const failure = await this.#checkDpop(token, cached.jkt, opts.dpop);
+                if (failure)
+                    return failure;
+            }
+            return cloneResult(cached.result);
         }
-        // Check for offline JWT lease verification
-        if (this._config.daywalkerPublicKey && token.split(".").length === 3) {
+        // Offline verification of Daywalker access tokens: against the fetched JWKS with `jwks: "auto"`, else
+        // (or while no key set can be obtained) against the configured public key.
+        const isJwt = token.split(".").length === 3;
+        const offlineKey = isJwt ? ((this.#config.jwks === "auto" ? await this.#jwksFor(jwtKid(token)) : null) ?? this.#config.daywalkerPublicKey) : null;
+        if (offlineKey) {
             const jwtResult = await verifyJwtLease({
                 token,
-                publicKey: this._config.daywalkerPublicKey,
+                publicKey: offlineKey,
                 expectedServiceSlug: serviceSlug || undefined,
-                expectedIssuer: this._config.leaseIssuer ?? undefined,
+                expectedIssuer: this.#config.leaseIssuer ?? DEFAULT_ISSUER,
             });
             if (jwtResult.valid && jwtResult.payload) {
                 const payload = jwtResult.payload;
+                const cnf = payload.cnf;
+                const jkt = typeof cnf?.jkt === "string" ? cnf.jkt : undefined;
+                if (jkt) {
+                    const failure = await this.#checkDpop(token, jkt, opts.dpop);
+                    if (failure)
+                        return failure;
+                }
+                const user = payload.user && typeof payload.user === "object" ? payload.user : {};
+                const userId = typeof user.id === "string" ? user.id : typeof payload.sub === "string" ? payload.sub : undefined;
+                const services = leaseServices(payload);
                 const result = {
                     ok: true,
                     data: {
-                        serviceSlug: serviceSlug || (payload.serviceSlug || payload.service || ""),
-                        tenantId: (payload.tenantId || payload.sub || ""),
-                        rateLimit: payload.rateLimit ?? {
-                            limit: 1000,
-                            remaining: 999,
-                            reset: Math.floor(Date.now() / 1000) + 60,
-                        },
-                        rateLimitHourly: payload.rateLimitHourly,
-                        tokenId: (payload.tokenId || payload.sub),
-                        tokenName: payload.tokenName,
-                        userId: payload.userId,
-                        stage: payload.stage,
-                        offlineVerified: true,
+                        // Claims first: the verified fields below can't be overridden by a claim of the same name.
                         ...payload,
-                        // Every service the lease covers: its `services` claim, else its audience.
-                        services: leaseServices(payload),
+                        serviceSlug: serviceSlug || services[0] || "",
+                        tenantId: userId ?? "",
+                        userId,
+                        tokenId: typeof payload.jti === "string" ? payload.jti : undefined,
+                        rateLimit: { limit: 0, remaining: 0, reset: 0 },
+                        offlineVerified: true,
+                        services,
                     },
                 };
-                if (this._config.cacheTtlMs > 0) {
-                    // Never cache a lease past its own expiry.
-                    this._cacheSet(cacheKey, result, this._config.cacheTtlMs, payload.exp * 1000);
+                if (this.#config.cacheTtlMs > 0) {
+                    // Never cache a token past its own expiry.
+                    this.#cacheSet(cacheKey, result, this.#config.cacheTtlMs, payload.exp * 1000, jkt);
                 }
                 return cloneResult(result);
             }
@@ -452,30 +972,39 @@ export class Daywalker {
                 };
             }
         }
+        else if (offlineOnly && isJwt && this.#config.jwks === "auto") {
+            // Fail closed: no key set, no offline verdict.
+            return {
+                ok: false,
+                error: "SERVICE_UNAVAILABLE",
+                status: 503,
+                message: "Offline verification failed: Daywalker's JWKS could not be fetched",
+            };
+        }
         else if (offlineOnly) {
             return {
                 ok: false,
                 error: "CONFIGURATION_ERROR",
                 status: 500,
-                message: "Offline verification requires DAYWALKER_PUBLIC_KEY and a valid JWT token lease",
+                message: "Offline verification requires DAYWALKER_PUBLIC_KEY or DAYWALKER_JWKS=auto and a Daywalker access token (JWT)",
             };
         }
         // Online verification, deduplicated across concurrent callers
         const inflightKey = `${cacheKey}`;
-        const pending = this._inflight.get(inflightKey);
+        const pending = this.#inflight.get(inflightKey);
         if (pending)
             return pending.then(cloneResult);
-        const run = this._validateOnline(token, serviceSlug, cacheKey).finally(() => {
-            this._inflight.delete(inflightKey);
+        const run = this.#validateOnline(token, serviceSlug, cacheKey).finally(() => {
+            this.#inflight.delete(inflightKey);
         });
-        this._inflight.set(inflightKey, run);
+        this.#inflight.set(inflightKey, run);
         return run.then(cloneResult);
     }
-    async _validateOnline(token, serviceSlug, cacheKey) {
-        const negTtl = this._config.negativeCacheTtlMs;
+    async #validateOnline(token, serviceSlug, cacheKey) {
+        const negTtl = this.#config.negativeCacheTtlMs;
         const fail = (result) => {
             if (negTtl > 0 && result.error !== "RATE_LIMITED" && result.error !== "NETWORK_ERROR" && result.error !== "SERVICE_UNAVAILABLE") {
-                this._cacheSet(cacheKey, result, negTtl);
+                this.#cacheSet(cacheKey, result, negTtl);
             }
             return result;
         };
@@ -487,18 +1016,15 @@ export class Daywalker {
             message: redactSecrets(message),
         });
         try {
-            const validateBody = { token };
-            if (serviceSlug) {
-                validateBody.serviceSlug = serviceSlug;
-            }
+            // No service slug is sent: the caller is identified by its credentials, not by naming a service
             const res = await this.fetch("/api/v1/tokens/validate", {
                 method: "POST",
-                body: validateBody,
+                body: { token },
                 // Validation is read-only, so repeating it after a lost response is safe.
-                retry: { retryNetworkErrors: this._config.retry.retryNetworkErrors ?? true },
+                retry: { retryNetworkErrors: this.#config.retry.retryNetworkErrors ?? true },
             });
-            // 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);
+            // A body that times out or is too large is an outage (thrown to NETWORK_ERROR below), never an answer.
+            const text = await readText(res, this.#config.timeoutMs);
             let parsed;
             try {
                 parsed = JSON.parse(text);
@@ -530,8 +1056,26 @@ export class Daywalker {
                 if (problem) {
                     return unavailable(`Daywalker Auth returned a malformed validation result (${problem})`);
                 }
+                const servedSlug = (payloadData.serviceSlug ?? json.serviceSlug)?.toLowerCase();
+                const reported = (payloadData.services ?? json.services);
+                const services = Array.from(new Set((reported ?? (servedSlug ? [servedSlug] : [])).map((s) => s.toLowerCase())));
+                if (services.length === 0 && !servedSlug) {
+                    return unavailable("Daywalker Auth returned a malformed validation result (no service named)");
+                }
+                // The token was validated for whichever service it shares with our credentials: make sure that
+                // includes this one, so a token for a sibling service is never accepted here.
+                if (serviceSlug && servedSlug !== serviceSlug && !services.includes(serviceSlug)) {
+                    return fail({
+                        ok: false,
+                        error: "SERVICE_NOT_GRANTED",
+                        status: 403,
+                        message: `This token is not valid for ${serviceSlug}`,
+                    });
+                }
                 const data = {
-                    serviceSlug: json.serviceSlug || serviceSlug,
+                    // Server fields first: the normalized fields below always win.
+                    ...payloadData,
+                    serviceSlug: serviceSlug || servedSlug || services[0],
                     tenantId: (payloadData.tenantId || payloadData.userId || json.tenantId || json.userId || ""),
                     rateLimit: (payloadData.rateLimit || json.rateLimit || { limit: 0, remaining: 0, reset: 0 }),
                     rateLimitHourly: (payloadData.rateLimitHourly || json.rateLimitHourly),
@@ -539,15 +1083,12 @@ export class Daywalker {
                     tokenName: (payloadData.tokenName || json.tokenName),
                     userId: (payloadData.userId || json.userId),
                     stage: (payloadData.stage || json.stage),
-                    ...payloadData,
-                    services: (payloadData.services ?? json.services) ?? [json.serviceSlug || serviceSlug],
-                };
-                const result = {
-                    ok: true,
-                    data,
+                    offlineVerified: false,
+                    services: services.length > 0 ? services : [servedSlug],
                 };
-                if (this._config.cacheTtlMs > 0) {
-                    this._cacheSet(cacheKey, result, this._config.cacheTtlMs);
+                const result = { ok: true, data };
+                if (this.#config.cacheTtlMs > 0) {
+                    this.#cacheSet(cacheKey, result, this.#config.cacheTtlMs);
                 }
                 return result;
             }
@@ -556,7 +1097,7 @@ export class Daywalker {
                 return unavailable(`Daywalker Auth returned no validation result (HTTP ${res.status})`);
             }
             let error = "INVALID_TOKEN";
-            const errMsg = String((typeof json.message === "string" && json.message) || (typeof json.error === "string" && json.error) || "");
+            const errMsg = String((typeof json.message === "string" && json.message) || (typeof json.error === "string" && json.error) || "").slice(0, 500);
             if (json.error === "EXPIRED" || /expired/i.test(errMsg)) {
                 error = "EXPIRED";
             }
@@ -572,6 +1113,9 @@ export class Daywalker {
             });
         }
         catch (err) {
+            // This service couldn't get its own access token: says nothing about the caller's token.
+            if (err instanceof DaywalkerAuthError)
+                return credentialFailure(err);
             return {
                 ok: false,
                 error: "NETWORK_ERROR",
@@ -581,19 +1125,58 @@ 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.
+     * Service health check: runs this service's OAuth client credentials flow (`accessToken()`) and checks
+     * that the granted services include `serviceSlug` (default: the configured one; with none configured, at
+     * least one service must be granted). Never use this to authenticate an incoming request. `forceRefresh`
+     * starts a new client credentials grant.
      */
-    async validateServiceKey(options) {
-        if (!this._config.apiKey) {
+    async validateServiceCredentials(options) {
+        const serviceSlug = String(options?.serviceSlug ?? this.#config.serviceSlug ?? "").toLowerCase();
+        if (serviceSlug && !SERVICE_SLUG_PATTERN.test(serviceSlug)) {
+            return { ok: false, error: "CONFIGURATION_ERROR", status: 500, message: "serviceSlug is not a valid Daywalker service slug" };
+        }
+        let tokens;
+        try {
+            if (options?.forceRefresh === true)
+                await this.getTokens();
+            else
+                await this.accessToken();
+            tokens = this.#tokens;
+        }
+        catch (err) {
+            if (err instanceof DaywalkerAuthError)
+                return credentialFailure(err);
             return {
                 ok: false,
-                error: "CONFIGURATION_ERROR",
-                status: 500,
-                message: "DAYWALKER_API_KEY is not set",
+                error: "NETWORK_ERROR",
+                status: 503,
+                message: redactSecrets(`Could not reach Daywalker Auth: ${err.message}`),
+            };
+        }
+        if (serviceSlug ? !tokens.services.includes(serviceSlug) : tokens.services.length === 0) {
+            return {
+                ok: false,
+                error: "SERVICE_NOT_GRANTED",
+                status: 403,
+                message: serviceSlug
+                    ? `The OAuth client credentials don't cover ${serviceSlug} (granted: ${tokens.services.join(", ") || "none"})`
+                    : "The OAuth client credentials were granted no service",
             };
         }
-        return this.validateToken(this._config.apiKey, options);
+        const claims = decodeJwtClaims(tokens.accessToken);
+        const user = claims.user && typeof claims.user === "object" ? claims.user : {};
+        const userId = typeof user.id === "string" ? user.id : typeof claims.sub === "string" ? claims.sub : undefined;
+        return {
+            ok: true,
+            data: {
+                serviceSlug: serviceSlug || tokens.services[0],
+                tenantId: userId ?? "",
+                userId,
+                rateLimit: { limit: 0, remaining: 0, reset: 0 },
+                services: [...tokens.services],
+                expiresAt: tokens.expiresAt,
+            },
+        };
     }
     /**
      * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
@@ -608,44 +1191,154 @@ export class Daywalker {
         }
         return result.data;
     }
+    #tokens = null;
+    /** The key generation that was current when `#tokens` was requested. */
+    #tokenGeneration = 0;
+    #tokenFlight = null;
+    /**
+     * POST /api/v1/oauth/token. The client credentials grant is the one request that carries the API key
+     * (`Authorization: Bearer`, next to the RFC 9421 signature); a refresh is authenticated by its refresh
+     * token and DPoP proof alone. The answer is checked before it is trusted: it must be a DPoP-bound token
+     * pair of sane shape, and its lifetime is capped so a bad `expires_at` can't keep a token alive.
+     */
+    async #tokenRequest(body) {
+        const headers = {};
+        if (body.grant_type === "client_credentials") {
+            if (!this.#config.apiKey) {
+                throw new DaywalkerAuthError("DAYWALKER_API_KEY is not set: it is the client credential for the OAuth token endpoint", 500, "CONFIGURATION_ERROR");
+            }
+            if (!API_KEY_PATTERN.test(this.#config.apiKey)) {
+                throw new DaywalkerAuthError("DAYWALKER_API_KEY contains characters an API key can't have", 500, "CONFIGURATION_ERROR");
+            }
+            headers.authorization = `Bearer ${this.#config.apiKey}`;
+        }
+        const res = await this.fetch(TOKEN_PATH, { method: "POST", body, headers });
+        const json = await readJsonObject(res, this.#config.timeoutMs);
+        const str = (v) => (typeof v === "string" ? v.slice(0, 500) : undefined);
+        if (res.status !== 200) {
+            throw new DaywalkerAuthError(redactSecrets(str(json.message) ?? str(json.error) ?? `Token request failed with HTTP ${res.status}`), res.status, str(json.code) ?? str(json.error));
+        }
+        const malformed = (why) => new DaywalkerAuthError(`Daywalker Auth returned a malformed token response (${why})`, 502, "SERVICE_UNAVAILABLE");
+        const isToken = (v) => typeof v === "string" && v.length <= MAX_TOKEN_LENGTH && TOKEN_PATTERN.test(v);
+        if (!isToken(json.access_token) || !isToken(json.refresh_token))
+            throw malformed("tokens missing or not tokens");
+        // Every token Daywalker issues is sender-constrained; an unbound (bearer) token is refused, not used.
+        if (typeof json.token_type !== "string" || json.token_type.toLowerCase() !== "dpop")
+            throw malformed("token_type is not DPoP");
+        const now = Math.floor(Date.now() / 1000);
+        const expiresIn = Math.floor(Number(json.expires_in));
+        if (!Number.isFinite(expiresIn) || expiresIn <= 0)
+            throw malformed("expires_in is not a positive number");
+        const lifetime = Math.min(expiresIn, MAX_ACCESS_TOKEN_LIFETIME_SECONDS);
+        const expiresAtClaim = Number(json.expires_at);
+        // Earliest of what the server says and what expires_in allows (a past expires_at means already expired).
+        const expiresAt = Number.isFinite(expiresAtClaim) && json.expires_at !== undefined ? Math.min(Math.floor(expiresAtClaim), now + lifetime) : now + lifetime;
+        const services = Array.isArray(json.services)
+            ? Array.from(new Set(json.services.filter((x) => typeof x === "string" && SERVICE_SLUG_PATTERN.test(x.toLowerCase())).map((x) => x.toLowerCase())))
+            : [];
+        const refreshExpiresIn = Math.max(0, Math.floor(Number(json.refresh_expires_in) || 0));
+        return deepFreeze({
+            accessToken: json.access_token,
+            refreshToken: json.refresh_token,
+            tokenType: "DPoP",
+            expiresAt,
+            expiresIn: lifetime,
+            refreshExpiresIn,
+            scope: services.join(" "),
+            services,
+            jwksUri: typeof json.jwks_uri === "string" && json.jwks_uri.startsWith(`${this.#config.authUrl}/`) ? json.jwks_uri : undefined,
+        });
+    }
     /**
-     * Exchanges an RFC 9421 signed request for a short-lived EdDSA JWT lease (POST /api/v1/leases/issue).
-     * The lease lists every service slug the API key covers (`services`, also the JWT's `services` and `aud`
-     * claims), so one set of credentials serves all of them. Pass `{ services: [...] }` to narrow it.
+     * Client credentials grant (RFC 6749 §4.4): the signed request (API key + registered Ed25519 key) is
+     * exchanged for a short-lived access token JWT and a rotating refresh token. By default the grant is
+     * narrowed to the configured service slug(s) (least privilege); with none configured it covers every
+     * service the credentials do. The tokens are remembered for `accessToken()`. The result is frozen.
      */
-    async issueLease(options) {
-        const opts = typeof options === "number" ? { ttlSeconds: options } : (options ?? {});
-        const services = opts.services ? parseServiceSlugs(opts.services) : undefined;
-        if (opts.services && (!services || services.length === 0)) {
-            throw new DaywalkerAuthError("issueLease: services must list at least one service slug", 400, "INVALID_REQUEST");
-        }
-        const res = await this.fetch("/api/v1/leases/issue", {
-            method: "POST",
-            body: { ...(opts.ttlSeconds ? { ttlSeconds: opts.ttlSeconds } : {}), ...(services ? { services } : {}) },
+    async getTokens(options = {}) {
+        const scope = options.scope ? parseServiceSlugs(options.scope) : this.#config.serviceSlugs.length > 0 ? [...this.#config.serviceSlugs] : undefined;
+        if (options.scope && (!scope || scope.length === 0)) {
+            throw new DaywalkerAuthError("getTokens: scope must list at least one service slug", 400, "INVALID_REQUEST");
+        }
+        if (scope && !scope.every((slug) => SERVICE_SLUG_PATTERN.test(slug))) {
+            throw new DaywalkerAuthError("getTokens: scope must list Daywalker service slugs", 400, "INVALID_REQUEST");
+        }
+        if (options.expiresIn !== undefined && (!Number.isInteger(options.expiresIn) || options.expiresIn < 300 || options.expiresIn > 900)) {
+            throw new DaywalkerAuthError("getTokens: expiresIn must be a whole number of seconds from 300 to 900", 400, "INVALID_REQUEST");
+        }
+        const generation = this.#keyGeneration;
+        const tokens = await this.#tokenRequest({
+            grant_type: "client_credentials",
+            ...(scope ? { scope: scope.join(" ") } : {}),
+            ...(options.expiresIn ? { expires_in: options.expiresIn } : {}),
         });
-        const json = (await res.json().catch(() => ({})));
-        if (res.status !== 201 && res.status !== 200) {
-            throw new DaywalkerAuthError(redactSecrets(String(json.message || json.error || `Lease issue failed with HTTP ${res.status}`)), res.status, json.error);
+        this.#tokens = tokens;
+        this.#tokenGeneration = generation;
+        return tokens;
+    }
+    /**
+     * Refresh token rotation: trades the refresh token for a NEW access token and a NEW refresh token; the
+     * old refresh token stops working. Presenting an old one again revokes the whole session, so refreshes
+     * are serialized per client and the new refresh token must replace the stored one.
+     */
+    async refreshTokens(refreshToken) {
+        const token = refreshToken ?? this.#tokens?.refreshToken;
+        if (!token)
+            throw new DaywalkerAuthError("refreshTokens: no refresh token (call getTokens() first)", 400, "INVALID_REQUEST");
+        if (typeof token !== "string" || token.length > MAX_TOKEN_LENGTH || !TOKEN_PATTERN.test(token)) {
+            throw new DaywalkerAuthError("refreshTokens: malformed refresh token", 400, "INVALID_REQUEST");
         }
-        if (typeof json.lease !== "string") {
-            throw new DaywalkerAuthError("Daywalker Auth returned a malformed lease response (no lease)", res.status, "SERVICE_UNAVAILABLE");
+        const generation = this.#keyGeneration;
+        const tokens = await this.#tokenRequest({ grant_type: "refresh_token", refresh_token: token });
+        this.#tokens = tokens;
+        this.#tokenGeneration = generation;
+        return tokens;
+    }
+    /**
+     * A valid access token, refreshing (or re-authenticating with the client credentials once the session
+     * ended) when it is within 30 seconds of expiry. Concurrent callers share one request, so the single-use
+     * refresh token is never presented twice.
+     */
+    async accessToken() {
+        // Tokens from before the signing key was replaced belong to the old key's session: start a new one.
+        const current = this.#tokenGeneration === this.#keyGeneration ? this.#tokens : null;
+        if (current && current.expiresAt - 30 > Math.floor(Date.now() / 1000))
+            return current.accessToken;
+        if (!this.#tokenFlight) {
+            this.#tokenFlight = (async () => {
+                if (current) {
+                    try {
+                        return await this.refreshTokens();
+                    }
+                    catch (err) {
+                        if (!(err instanceof DaywalkerAuthError) || err.status !== 400)
+                            throw err;
+                        // invalid_grant: the session ended or was revoked; start a new one
+                    }
+                }
+                return this.getTokens();
+            })().finally(() => {
+                this.#tokenFlight = null;
+            });
         }
-        // Servers from before multi-service tokens don't list services; their lease covers the one configured slug.
-        const listed = Array.isArray(json.services) ? json.services.filter((s) => typeof s === "string") : [];
-        return { ...json, lease: json.lease, services: listed.length > 0 ? listed : this._config.serviceSlug ? [this._config.serviceSlug] : [] };
+        return (await this.#tokenFlight).accessToken;
     }
     /**
      * 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 doFetch = this._rawConfig.fetch ?? globalThis.fetch;
-        const { signal, cleanup } = attemptSignal(undefined, this._config.timeoutMs);
+    fetchJwks() {
+        return this.#fetchJwks();
+    }
+    async #fetchJwks() {
+        const doFetch = this.#fetch;
+        const { signal, cleanup } = attemptSignal(undefined, this.#config.timeoutMs);
         let res;
         try {
-            res = await doFetch(`${this._config.authUrl.replace(/\/+$/, "")}/.well-known/jwks.json`, {
+            res = await doFetch(`${this.#config.authUrl.replace(/\/+$/, "")}/.well-known/jwks.json`, {
                 headers: { Accept: "application/json" },
                 redirect: "manual",
+                cache: "no-store",
                 signal,
             });
         }
@@ -658,7 +1351,7 @@ export class Daywalker {
             throw new DaywalkerError(`Could not fetch JWKS (HTTP ${res.status})`, res.status);
         let json = null;
         try {
-            json = JSON.parse(await readText(res, this._config.timeoutMs));
+            json = JSON.parse(await readText(res, this.#config.timeoutMs));
         }
         catch (err) {
             if (err.name === "TimeoutError")
@@ -669,49 +1362,124 @@ export class Daywalker {
         }
         return { keys: json.keys };
     }
+    /**
+     * The key set to verify a token naming `kid` with (`jwks: "auto"`), or null when none could be obtained.
+     * The set is refetched once it is older than `JWKS_CACHE_TTL_MS`, or when it has no key with this `kid`
+     * (Daywalker rotated its key), but never sooner than `JWKS_REFETCH_COOLDOWN_MS` after the last attempt.
+     * Concurrent callers share one fetch. A failed fetch, or one with no usable key, keeps the previous set.
+     * Only `${authUrl}/.well-known/jwks.json` is ever fetched: a `jwks_uri` from anywhere is not followed.
+     */
+    async #jwksFor(kid) {
+        const current = this.#jwks;
+        const stale = !current || Date.now() - current.fetchedAt >= JWKS_CACHE_TTL_MS;
+        const unknownKid = Boolean(current && kid !== undefined && !current.set.keys.some((k) => k.kid === kid));
+        if ((stale || unknownKid) && (this.#jwksFlight || Date.now() - this.#jwksAttemptAt >= JWKS_REFETCH_COOLDOWN_MS)) {
+            await this.#refreshJwks();
+        }
+        return this.#jwks?.set ?? null;
+    }
+    #refreshJwks() {
+        if (!this.#jwksFlight) {
+            this.#jwksAttemptAt = Date.now();
+            this.#jwksFlight = this.#fetchJwks()
+                .then(({ keys }) => {
+                const usable = usableJwks(keys);
+                if (usable.length > 0)
+                    this.#jwks = { set: deepFreeze({ keys: usable }), fetchedAt: Date.now() };
+            }, () => {
+                // Keep the last good set; the cooldown spaces out the next attempt.
+            })
+                .finally(() => {
+                this.#jwksFlight = null;
+            });
+        }
+        return this.#jwksFlight;
+    }
     /**
      * 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();
-        const keys = key ? [key.publicJwk] : [];
+        const active = await this.#getSigner();
+        const keys = active?.publicJwk ? [active.publicJwk] : [];
         // A broken previous key must not take the current one offline; selfCheck() reports it.
-        const previous = await this.getLoadedPreviousSigningKey().catch(() => null);
+        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.
+     * Check configuration and verify signature readiness. Never provisions or registers a key: with a
+     * `keyStore` it only reads what is stored and reports what first use would need.
      */
     async selfCheck() {
-        const problems = [...this._config.problems];
-        const signingKey = await this.getLoadedSigningKey().catch((err) => {
-            problems.push(`Signing key load error: ${err.message}`);
-            return null;
-        });
-        if (!signingKey) {
-            problems.push("DAYWALKER_SIGNING_KEY is not set: requests will be sent without RFC 9421 signature");
+        const problems = [...this.#config.problems];
+        let keyId = null;
+        let signing = false;
+        if (this.#externalSigner) {
+            signing = true;
+            keyId = this.#externalSigner.keyId;
+        }
+        else if (this.#config.signingKey) {
+            const signingKey = await this.#getLoadedSigningKey().catch((err) => {
+                problems.push(`Signing key load error: ${err.message}`);
+                return null;
+            });
+            signing = Boolean(signingKey);
+            keyId = this.#config.keyId ?? signingKey?.publicJwk.kid ?? null;
+        }
+        else if (this.#config.ephemeralKey) {
+            signing = Boolean(this.#config.domain);
+            keyId = this.#ephemeral?.keyId ?? null;
+            if (!this.#config.domain)
+                problems.push("No public domain detected: set DAYWALKER_DOMAIN so the ephemeral signing key can be registered");
+        }
+        else if (this.#keyStore) {
+            const store = this.#keyStore;
+            try {
+                const stored = await this.#loadStored(store);
+                if (stored) {
+                    await this.#useStored(stored);
+                    keyId = stored.keyId;
+                    signing = true;
+                }
+                else if (!store.saveIfAbsent) {
+                    problems.push("The key store is read-only and holds no signing key: provision one with `npx daywalker init`");
+                }
+                else if (!this.#config.domain) {
+                    problems.push("No public domain detected: set DAYWALKER_DOMAIN so a signing key can be registered on first use");
+                }
+                else {
+                    signing = true; // provisioned and registered on first use
+                }
+            }
+            catch (err) {
+                problems.push(`Key store error: ${err.message}`);
+            }
+        }
+        else {
+            problems.push("No signing key: set DAYWALKER_SIGNING_KEY (npx daywalker init), a keyStore for auto-provisioning, or a signer");
         }
-        await this.getLoadedPreviousSigningKey().catch((err) => {
+        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 {
             ok: problems.length === 0,
-            serviceSlug: this._config.serviceSlug,
-            serviceSlugs: this._config.serviceSlugs,
-            domain: this._config.domain,
-            signing: Boolean(signingKey),
+            serviceSlug: this.#config.serviceSlug,
+            serviceSlugs: this.#config.serviceSlugs,
+            domain: this.#config.domain,
+            signing,
             keyId,
-            offlineVerificationReady,
+            offlineVerificationReady: Boolean(this.#config.daywalkerPublicKey) || this.#config.jwks === "auto",
             problems,
         };
     }
 }
+// Methods can't be replaced on the class or (by assignment) on an instance, so code elsewhere in the process
+// can't swap validateToken() for one that always says yes.
+Object.freeze(Daywalker.prototype);
+Object.freeze(Daywalker);
 /**
  * Factory function for creating instantiable Daywalker client instances.
  */
@@ -742,4 +1510,9 @@ export const daywalker = new Proxy((() => getDefaultInstance()), {
         }
         return getDefaultInstance();
     },
+    // The shared default client can't be patched through the proxy either.
+    set: () => false,
+    defineProperty: () => false,
+    deleteProperty: () => false,
+    setPrototypeOf: () => false,
 });