@telecrypt-io/storage 0.5.28 → 0.5.29

package/dist/core/oidc.js

@@ -6,10 +6,9 @@
  * this module under Node is safe; the CLI uses the device-code functions,
  * which are plain fetch calls.
  */
-import { createClient } from "matrix-js-sdk";
 import { generateScope, isValidDeviceAccessTokenResponse, normalizeBearerTokenResponseTokenType, validateBearerTokenResponse, validateDeviceAuthorizationResponse, validateRegistrationResponse, OAuthGrantType, OAuth2, } from "matrix-js-sdk/lib/oauth/index.js";
 import { StorageError } from "./errors.js";
-import { raceWithAbort, readBoundedResponseBody } from "./http.js";
+import { cancelResponseBody, raceWithAbort, readResponseBody, ResponseBodyReadError, } from "./http.js";
 import { validateCanonicalMatrixUserId, validateMatrixDeviceId, } from "./constants.js";
 const AUTHORIZATION_CONTEXT_PREFIX = "telecrypt:oauth2:pkce:v1:";
 const AUTHORIZATION_CONTEXT_VERSION = 1;
@@ -22,8 +21,6 @@ const MAX_AUTHORIZATION_CONTEXT_LENGTH = 64 * 1024;
 const PKCE_VERIFIER_PATTERN = /^[A-Za-z0-9._~-]{43,128}$/;
 const DEVICE_ID_PATTERN = /^[A-Za-z0-9._~-]{1,128}$/;
 const STATE_PATTERN = /^[A-Za-z0-9._~-]{32,128}$/;
-const MAX_OAUTH_ERROR_BODY_BYTES = 16 * 1024;
-const MAX_OAUTH_SUCCESS_BODY_BYTES = 32 * 1024;
 const OIDC_REQUEST_TIMEOUT_MS = 30_000;
 const OIDC_REFRESH_TIMEOUT_MS = 30_000;
 const OIDC_CLEANUP_TIMEOUT_MS = 30_000;
@@ -85,6 +82,225 @@ class OidcValidationError extends StorageError {
         this.name = "OidcValidationError";
     }
 }
+const DIAGNOSTIC_SECRET_FIELD = /^(?:access[_-]?token|refresh[_-]?token|id[_-]?token|client[_-]?id|client[_-]?secret|user[_-]?id|device[_-]?id|authorization(?:[_-]?code)?|device[_-]?code|user[_-]?code|code[_-]?verifier|token|credential[s]?|private[_-]?key|(?:[A-Za-z0-9]+[_-])?(?:encryption|signing|password|secret|api[_-]?key|recovery[_-]?key|cookie|session)(?:[_-]?token|[_-]?key)?)$/iu;
+const DIAGNOSTIC_EMAIL = /[A-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Z0-9-]+(?:\.[A-Z0-9-]+)+/giu;
+const DIAGNOSTIC_MXID = /@[A-Z0-9._=+\-/]+:[A-Z0-9.-]+/giu;
+const DIAGNOSTIC_ULID = /\b[0-9A-HJKMNP-TV-Z]{26}\b/giu;
+/** Keep provider diagnostics useful without allowing credentials, customer
+ * identifiers, or control characters from an untrusted response to cross the
+ * SDK boundary. */
+export function sanitizeDiagnosticText(value) {
+    const quotedValue = `"(?:\\\\.|[^"\\\\])*"|'(?:\\\\.|[^'\\\\])*'|[^\\s,};\\]]+`;
+    return value
+        .replace(/(Bearer\s+)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s"',}]+)/giu, "$1<redacted>")
+        .replace(new RegExp(`(["'])([^"']+)\\1(\\s*[:=]\\s*)(${quotedValue})`, "giu"), (whole, quote, key, separator) => DIAGNOSTIC_SECRET_FIELD.test(key.replace(/\\(["'])/gu, "$1"))
+        ? `${quote}${key}${quote}${separator}"<redacted>"`
+        : whole)
+        .replace(new RegExp(`\\b([A-Za-z][A-Za-z0-9_-]*)\\b(\\s*[:=]\\s*)(${quotedValue})`, "giu"), (whole, key, separator) => DIAGNOSTIC_SECRET_FIELD.test(key) ? `${key}${separator}"<redacted>"` : whole)
+        .replace(DIAGNOSTIC_EMAIL, "<redacted>")
+        .replace(DIAGNOSTIC_MXID, "<redacted>")
+        .replace(DIAGNOSTIC_ULID, "<redacted>")
+        .replace(/[\r\n\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu, " ")
+        .trim();
+}
+class OidcResponseError extends Error {
+    status;
+    constructor(operation, status, body, cause) {
+        const detail = sanitizeDiagnosticText(body);
+        super(`OIDC ${operation} provider response (${status})${detail === "" ? "" : `: ${detail}`}`, cause === undefined ? undefined : { cause });
+        this.name = "OidcResponseError";
+        this.status = status;
+    }
+}
+function diagnosticKey(key) {
+    return String(key);
+}
+function diagnosticDisplayKey(key) {
+    return sanitizeDiagnosticText(diagnosticKey(key)) || "<empty property>";
+}
+function diagnosticPropertyIsSecret(key) {
+    return DIAGNOSTIC_SECRET_FIELD.test(diagnosticKey(key));
+}
+function readDiagnosticProperties(value, seen) {
+    const properties = [];
+    const failures = [];
+    let keys;
+    try {
+        keys = Reflect.ownKeys(value);
+    }
+    catch (error) {
+        failures.push(`own properties unavailable: ${diagnosticFailureText(error, seen)}`);
+        return { properties, failures };
+    }
+    for (const key of keys) {
+        let descriptor;
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(value, key);
+        }
+        catch (error) {
+            failures.push(`${diagnosticDisplayKey(key)} unavailable: ${diagnosticPropertyIsSecret(key) ? "<redacted>" : diagnosticFailureText(error, seen)}`);
+            continue;
+        }
+        if (!descriptor)
+            continue;
+        try {
+            if ("value" in descriptor) {
+                properties.push({ key, value: descriptor.value });
+            }
+            else if (typeof descriptor.get === "function") {
+                properties.push({ key, value: Reflect.get(value, key) });
+            }
+            else {
+                failures.push(`${diagnosticDisplayKey(key)} unavailable: ${diagnosticPropertyIsSecret(key) ? "<redacted>" : "accessor has no getter"}`);
+            }
+        }
+        catch (error) {
+            failures.push(`${diagnosticDisplayKey(key)} unavailable: ${diagnosticPropertyIsSecret(key) ? "<redacted>" : diagnosticFailureText(error, seen)}`);
+        }
+    }
+    return { properties, failures };
+}
+function diagnosticObjectText(value, seen) {
+    const inspection = readDiagnosticProperties(value, seen);
+    const parts = inspection.failures.slice();
+    for (const property of inspection.properties) {
+        const key = diagnosticDisplayKey(property.key);
+        parts.push(`${key}: ${diagnosticPropertyIsSecret(property.key) ? "<redacted>" : diagnosticValueText(property.value, seen)}`);
+    }
+    if (parts.length === 0) {
+        return "object { }";
+    }
+    return `object { ${parts.join(", ")} }`;
+}
+function diagnosticValueText(value, seen) {
+    if (value !== null && (typeof value === "object" || typeof value === "function")) {
+        if (seen.has(value))
+            return "[cyclic diagnostic]";
+        seen.add(value);
+    }
+    if (value instanceof AggregateError) {
+        const parts = [`${sanitizeDiagnosticText(value.name)}: ${sanitizeDiagnosticText(value.message)}`];
+        if (typeof value.stack === "string")
+            parts.push(`stack: ${sanitizeDiagnosticText(value.stack)}`);
+        try {
+            parts.push(`children: ${value.errors.map((child) => diagnosticValueText(child, seen)).join(", ")}`);
+        }
+        catch (error) {
+            parts.push(`children unavailable: ${diagnosticFailureText(error, seen)}`);
+        }
+        const inspection = readDiagnosticProperties(value, seen);
+        for (const property of inspection.properties) {
+            if (["name", "message", "stack", "cause", "errors"].includes(diagnosticKey(property.key)))
+                continue;
+            const key = diagnosticDisplayKey(property.key);
+            parts.push(`${key}: ${diagnosticPropertyIsSecret(property.key) ? "<redacted>" : diagnosticValueText(property.value, seen)}`);
+        }
+        parts.push(...inspection.failures);
+        return parts.join("; ");
+    }
+    if (value instanceof Error) {
+        const parts = [`${sanitizeDiagnosticText(value.name)}: ${sanitizeDiagnosticText(value.message)}`];
+        if (typeof value.stack === "string")
+            parts.push(`stack: ${sanitizeDiagnosticText(value.stack)}`);
+        try {
+            if (value.cause !== undefined)
+                parts.push(`cause: ${diagnosticValueText(value.cause, seen)}`);
+        }
+        catch (error) {
+            parts.push(`cause unavailable: ${diagnosticFailureText(error, seen)}`);
+        }
+        const inspection = readDiagnosticProperties(value, seen);
+        for (const property of inspection.properties) {
+            if (["name", "message", "stack", "cause", "bytes"].includes(diagnosticKey(property.key)))
+                continue;
+            const key = diagnosticDisplayKey(property.key);
+            parts.push(`${key}: ${diagnosticPropertyIsSecret(property.key) ? "<redacted>" : diagnosticValueText(property.value, seen)}`);
+        }
+        parts.push(...inspection.failures);
+        return parts.join("; ");
+    }
+    if (value !== null && (typeof value === "object" || typeof value === "function")) {
+        return diagnosticObjectText(value, seen);
+    }
+    try {
+        return sanitizeDiagnosticText(String(value));
+    }
+    catch {
+        return "unknown failure";
+    }
+}
+function diagnosticFailureText(error, seen) {
+    try {
+        return diagnosticValueText(error, seen);
+    }
+    catch {
+        return "unknown property failure";
+    }
+}
+/** Copy a transport error's useful details across the SDK boundary after the
+ * same secret/control-character sanitization used for provider responses. */
+export function diagnosticCause(error, seen = new WeakSet()) {
+    if (error !== null && (typeof error === "object" || typeof error === "function")) {
+        if (seen.has(error))
+            return new Error("[cyclic diagnostic]");
+        seen.add(error);
+    }
+    if (error instanceof AggregateError) {
+        let children = [];
+        try {
+            if (Array.isArray(error.errors))
+                children = error.errors;
+        }
+        catch {
+            children = [];
+        }
+        const copy = new AggregateError(children.map((child) => diagnosticCause(child, seen)), diagnosticValueText(error, new WeakSet()));
+        copy.name = sanitizeDiagnosticText(error.name) || "AggregateError";
+        if (typeof error.stack === "string")
+            copy.stack = sanitizeDiagnosticText(error.stack);
+        let cause;
+        try {
+            cause = error.cause;
+        }
+        catch {
+            cause = undefined;
+        }
+        if (cause !== undefined) {
+            Object.defineProperty(copy, "cause", {
+                configurable: true,
+                enumerable: false,
+                value: diagnosticCause(cause, seen),
+                writable: true,
+            });
+        }
+        return copy;
+    }
+    if (error instanceof Error) {
+        const copy = new Error(diagnosticValueText(error, new WeakSet()));
+        copy.name = sanitizeDiagnosticText(error.name) || "Error";
+        if (typeof error.stack === "string")
+            copy.stack = sanitizeDiagnosticText(error.stack);
+        let cause;
+        try {
+            cause = error.cause;
+        }
+        catch {
+            cause = undefined;
+        }
+        if (cause !== undefined) {
+            Object.defineProperty(copy, "cause", {
+                configurable: true,
+                enumerable: false,
+                value: diagnosticCause(cause, seen),
+                writable: true,
+            });
+        }
+        return copy;
+    }
+    const copy = new Error(diagnosticValueText(error, new WeakSet()));
+    copy.name = "ThrownObject";
+    return copy;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -139,8 +355,8 @@ function parseSafeRedirectUri(value, name) {
     try {
         parsed = new URL(text);
     }
-    catch {
-        throw new StorageError(`OIDC authorization context has an invalid ${name}`);
+    catch (error) {
+        throw new StorageError(`OIDC authorization context has an invalid ${name}`, { cause: error });
     }
     const isRootWithoutSlash = parsed.pathname === "/" && parsed.toString() === `${text}/`;
     if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
@@ -200,24 +416,32 @@ function validateRegistrationMetadata(metadata) {
     });
     return { clientUri, redirectUris };
 }
-async function readBoundedResponseText(response, maxBytes = MAX_OAUTH_ERROR_BODY_BYTES, signal) {
-    const body = await readBoundedResponseBody(response, maxBytes, signal);
-    return { text: new TextDecoder().decode(body.bytes), truncated: body.truncated };
-}
-async function readBoundedJsonResponse(response, operation, signal) {
-    const maxBytes = response.ok ? MAX_OAUTH_SUCCESS_BODY_BYTES : MAX_OAUTH_ERROR_BODY_BYTES;
-    const body = await readBoundedResponseText(response, maxBytes, signal);
-    if (body.truncated) {
-        throw new StorageError(`OIDC ${operation} returned an oversized response`);
+async function readResponseText(response, signal, operation = "OIDC response") {
+    try {
+        const body = await readResponseBody(response, signal);
+        return { text: new TextDecoder().decode(body.bytes) };
     }
+    catch (error) {
+        if (!(error instanceof ResponseBodyReadError))
+            throw error;
+        const partial = sanitizeDiagnosticText(new TextDecoder().decode(error.bytes));
+        throw new StorageError(`${operation} response body could not be read${partial === "" ? "" : `: ${partial}`}`, {
+            cause: new OidcResponseError(operation, response.status, partial, error.cause),
+        });
+    }
+}
+async function readJsonResponse(response, operation, signal) {
+    const body = await readResponseText(response, signal, operation);
     try {
-        return JSON.parse(body.text);
+        return { value: JSON.parse(body.text), text: body.text };
     }
-    catch {
-        throw new StorageError(`OIDC ${operation} returned an invalid response`);
+    catch (error) {
+        throw new StorageError(`OIDC ${operation} returned an invalid response`, {
+            cause: new OidcResponseError(operation, response.status, body.text, error),
+        });
     }
 }
-function assertNoRedirect(response, endpoint, operation) {
+async function assertNoRedirect(response, endpoint, operation) {
     // OAuth request bodies contain bearer credentials, refresh tokens, or
     // authorization codes. Redirects must never be followed with those bodies.
     // `redirect: "manual"` makes this a local rejection rather than a network
@@ -226,8 +450,9 @@ function assertNoRedirect(response, endpoint, operation) {
         response.type === "opaqueredirect" ||
         (response.url !== "" && response.url !== endpoint) ||
         response.redirected) {
-        void response.body?.cancel().catch(() => undefined);
-        throw new StorageError(`OIDC ${operation} rejected an untrusted redirect`);
+        const failure = new StorageError(`OIDC ${operation} rejected an untrusted redirect`);
+        await cancelResponseBody(response, `OIDC ${operation} redirect`, failure);
+        throw failure;
     }
 }
 function exactEndpoint(value, name) {
@@ -247,14 +472,13 @@ function parseSafeOAuthError(body) {
     return { code: parsed.error };
 }
 function formatTokenRefreshFailure(status, body) {
-    if (body.truncated) {
-        return `OIDC token refresh failed (${status}): provider error response was too large`;
-    }
     const oauthError = parseSafeOAuthError(body.text);
     if (!oauthError) {
-        return `OIDC token refresh failed (${status}): provider returned an invalid OAuth error response`;
+        return new StorageError(`OIDC token refresh failed (${status}): provider returned an invalid OAuth error response`, { cause: new OidcResponseError("token refresh", status, body.text) });
     }
-    return `OIDC token refresh failed (${status}): OAuth error ${oauthError.code}`;
+    return new StorageError(`OIDC token refresh failed (${status}): OAuth error ${oauthError.code}`, {
+        cause: new OidcResponseError("token refresh", status, body.text),
+    });
 }
 function providerErrorStatus(error) {
     if (!isRecord(error) || typeof error.httpStatus !== "number")
@@ -264,12 +488,29 @@ function providerErrorStatus(error) {
         : undefined;
 }
 function formatProviderFailure(operation, error) {
-    if (error instanceof OidcRequestTimeoutError)
-        return error.message;
-    if (error instanceof OidcRequestCancelledError)
-        return error.message;
+    if (error instanceof StorageError)
+        return error;
+    if (error instanceof OidcRequestTimeoutError) {
+        return new StorageError(error.message, { cause: diagnosticCause(error) });
+    }
+    if (error instanceof OidcRequestCancelledError) {
+        return new StorageError(error.message, { cause: diagnosticCause(error) });
+    }
     const status = providerErrorStatus(error);
-    return `OIDC ${operation} failed${status === undefined ? "" : ` (${status})`}`;
+    return new StorageError(`OIDC ${operation} failed${status === undefined ? "" : ` (${status})`}`, { cause: diagnosticCause(error) });
+}
+function providerResponseFailure(operation, response, body, message) {
+    return new StorageError(message, {
+        cause: new OidcResponseError(operation, response.status, body),
+    });
+}
+function responseValidationFailure(operation, response, body, error) {
+    const message = error instanceof Error
+        ? sanitizeDiagnosticText(error.message) || `OIDC ${operation} returned an invalid response`
+        : `OIDC ${operation} returned an invalid response`;
+    return new StorageError(message, {
+        cause: new OidcResponseError(operation, response.status, body, diagnosticCause(error)),
+    });
 }
 function ensureOidcNotCancelled(signal, operation) {
     if (signal?.aborted)
@@ -291,15 +532,22 @@ async function requestWithTimeout(input, init, operation, consume, timeoutMs = O
             signal.addEventListener("abort", abort, { once: true });
     }
     try {
-        const response = await raceWithAbort(fetch(input, { ...init, signal: controller.signal }), controller.signal, () => undefined, () => timedOut
+        const response = await raceWithAbort(fetch(input, { ...init, signal: controller.signal }), controller.signal, () => timedOut
             ? new OidcRequestTimeoutError(operation)
             : new OidcRequestCancelledError(operation));
         return await consume(response, controller.signal);
     }
     catch (error) {
-        if (timedOut)
+        if (error instanceof AggregateError)
+            throw error;
+        if (timedOut) {
+            if (error instanceof OidcRequestTimeoutError)
+                throw error;
             throw new OidcRequestTimeoutError(operation);
+        }
         if (signals.some((signal) => signal.aborted)) {
+            if (error instanceof OidcRequestCancelledError)
+                throw error;
             throw new OidcRequestCancelledError(operation);
         }
         throw error;
@@ -327,50 +575,14 @@ function abortableDelay(milliseconds, signal) {
         signal?.addEventListener("abort", abort, { once: true });
     });
 }
-function requestUrl(input) {
-    if (typeof input === "string")
-        return new URL(input).toString();
-    if (input instanceof URL)
-        return input.toString();
-    return input.url;
-}
-/**
- * MatrixClient's OAuth helpers use the SDK HTTP layer for discovery and
- * whoami. Supply a bounded/manual-redirect fetch implementation so those
- * calls have the same body and credential boundary as the direct OAuth calls.
- */
-function boundedMatrixFetch(operation, externalSignal) {
-    return async (input, init) => {
-        const endpoint = requestUrl(input);
-        return requestWithTimeout(input, { ...init, redirect: "manual" }, operation, async (response, requestSignal) => {
-            assertNoRedirect(response, endpoint, operation);
-            const maxBytes = response.ok ? MAX_OAUTH_SUCCESS_BODY_BYTES : MAX_OAUTH_ERROR_BODY_BYTES;
-            const body = await readBoundedResponseText(response, maxBytes, requestSignal);
-            if (body.truncated) {
-                if (response.ok) {
-                    throw new StorageError(`OIDC ${operation} returned an oversized response`);
-                }
-                return new Response(null, {
-                    status: response.status,
-                    statusText: response.statusText,
-                });
-            }
-            return new Response(body.text, {
-                status: response.status,
-                statusText: response.statusText,
-                headers: response.headers,
-            });
-        }, OIDC_REQUEST_TIMEOUT_MS, externalSignal);
-    };
-}
 function parseHttpUrl(value, name) {
     const text = requireBoundedString(value, name, MAX_OIDC_URL_LENGTH);
     let parsed;
     try {
         parsed = new URL(text);
     }
-    catch {
-        throw new StorageError(`OIDC authorization context has an invalid ${name}`);
+    catch (error) {
+        throw new StorageError(`OIDC authorization context has an invalid ${name}`, { cause: error });
     }
     const isRootWithoutSlash = parsed.pathname === "/" && parsed.toString() === `${text}/`;
     if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
@@ -394,6 +606,10 @@ function matrixAuthMetadataEndpoint(homeserver) {
     const basePath = homeserver.pathname.replace(/\/+$/u, "");
     return new URL(`${basePath}/_matrix/client/v1/auth_metadata`, homeserver.origin).toString();
 }
+function matrixWhoAmIEndpoint(homeserver) {
+    const basePath = homeserver.pathname.replace(/\/+$/u, "");
+    return new URL(`${basePath}/_matrix/client/v3/account/whoami`, homeserver.origin).toString();
+}
 function validateTokenEndpointMetadata(metadata) {
     const issuer = parseHttpUrl(metadata.issuer, "issuer");
     const tokenEndpoint = parseHttpUrl(metadata.token_endpoint, "token endpoint");
@@ -504,8 +720,8 @@ function validateDeviceAuthorizationSession(value) {
     try {
         validateDeviceAuthorizationResponse(value);
     }
-    catch {
-        throw new StorageError("OIDC device authorization returned an invalid response");
+    catch (error) {
+        throw new StorageError("OIDC device authorization returned an invalid response", { cause: error });
     }
     const session = value;
     requireBoundedString(session.device_code, "device code", MAX_OIDC_CODE_LENGTH);
@@ -547,8 +763,8 @@ function validateTokenBounds(value, operation) {
         if (value.scope !== undefined)
             requireScope(value.scope, "scope");
     }
-    catch {
-        throw new StorageError(`OIDC ${operation} returned an invalid token response`);
+    catch (error) {
+        throw new StorageError(`OIDC ${operation} returned an invalid token response`, { cause: error });
     }
     if (value.expires_in !== undefined &&
         (!Number.isInteger(value.expires_in) || value.expires_in < 0 || value.expires_in > 86400)) {
@@ -618,22 +834,21 @@ export async function discoverOidcIssuer(homeserverBaseUrl, signal) {
     try {
         const homeserver = parseHttpUrl(homeserverBaseUrl, "homeserver URL");
         const endpoint = matrixAuthMetadataEndpoint(homeserver);
-        const { response, body } = await requestWithTimeout(endpoint, { method: "GET", headers: { Accept: "application/json" }, redirect: "manual" }, "discovery", async (response, requestSignal) => {
-            assertNoRedirect(response, endpoint, "discovery");
+        const { response, body, responseText } = await requestWithTimeout(endpoint, { method: "GET", headers: { Accept: "application/json" }, redirect: "manual" }, "discovery", async (response, requestSignal) => {
+            await assertNoRedirect(response, endpoint, "discovery");
             if (!response.ok) {
-                // Discovery only consumes metadata on success. Drain a bounded
-                // error body without parsing or surfacing provider-controlled text;
-                // the status remains the only caller-visible diagnostic.
-                await readBoundedResponseBody(response, MAX_OAUTH_ERROR_BODY_BYTES, requestSignal);
-                return { response, body: undefined };
+                const body = await readResponseText(response, requestSignal, "discovery");
+                return { response, body: undefined, responseText: body.text };
             }
+            const body = await readJsonResponse(response, "discovery", requestSignal);
             return {
                 response,
-                body: await readBoundedJsonResponse(response, "discovery", requestSignal),
+                body: body.value,
+                responseText: body.text,
             };
         }, OIDC_REQUEST_TIMEOUT_MS, signal);
         if (!response.ok) {
-            const failure = new StorageError("OIDC discovery failed");
+            const failure = providerResponseFailure("discovery", response, responseText ?? "", `OIDC discovery failed (${response.status})`);
             failure.httpStatus = response.status;
             throw failure;
         }
@@ -641,7 +856,9 @@ export async function discoverOidcIssuer(homeserverBaseUrl, signal) {
         return validateTrustedAuthMetadata(body);
     }
     catch (err) {
-        throw new StorageError(formatProviderFailure("discovery", err));
+        if (err instanceof AggregateError)
+            throw err;
+        throw formatProviderFailure("discovery", err);
     }
 }
 /**
@@ -677,26 +894,38 @@ export async function registerClient(authMetadata, metadata, signal) {
             policy_uri: metadata.policyUri,
         };
         const endpoint = exactEndpoint(safeAuthMetadata.registration_endpoint, "registration endpoint");
-        const { response, body } = await requestWithTimeout(endpoint, {
+        const { response, body, responseText } = await requestWithTimeout(endpoint, {
             method: "POST",
             headers: { Accept: "application/json", "Content-Type": "application/json" },
             body: JSON.stringify(registration),
             redirect: "manual",
         }, "dynamic client registration", async (response, requestSignal) => {
-            assertNoRedirect(response, endpoint, "dynamic client registration");
+            await assertNoRedirect(response, endpoint, "dynamic client registration");
+            const body = await readJsonResponse(response, "dynamic client registration", requestSignal);
             return {
                 response,
-                body: await readBoundedJsonResponse(response, "dynamic client registration", requestSignal),
+                body: body.value,
+                responseText: body.text,
             };
         }, OIDC_REQUEST_TIMEOUT_MS, signal);
-        if (!response.ok || !validateRegistrationResponse(body)) {
-            throw new StorageError("OIDC dynamic client registration failed");
+        if (!response.ok) {
+            throw providerResponseFailure("dynamic client registration", response, responseText ?? "", "OIDC dynamic client registration failed");
+        }
+        if (!validateRegistrationResponse(body)) {
+            throw providerResponseFailure("dynamic client registration", response, responseText ?? "", "OIDC dynamic client registration returned an invalid response");
         }
         ensureOidcNotCancelled(signal, "dynamic client registration");
-        return requireClientId(body.client_id);
+        try {
+            return requireClientId(body.client_id);
+        }
+        catch (error) {
+            throw responseValidationFailure("dynamic client registration", response, responseText ?? "", error);
+        }
     }
     catch (err) {
-        throw new StorageError(formatProviderFailure("dynamic client registration", err));
+        if (err instanceof AggregateError)
+            throw err;
+        throw formatProviderFailure("dynamic client registration", err);
     }
 }
 // ---------------------------------------------------------------------------
@@ -721,21 +950,30 @@ export async function startDeviceCodeLogin(authMetadata, clientId, deviceId, sig
         if (!endpoint)
             throw new StorageError("OIDC device authorization is not supported");
         const trustedEndpoint = exactEndpoint(endpoint, "device authorization endpoint");
-        const { response, body } = await requestWithTimeout(trustedEndpoint, {
+        const { response, body, responseText } = await requestWithTimeout(trustedEndpoint, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body: new URLSearchParams({ client_id: safeClientId, scope }).toString(),
             redirect: "manual",
         }, "device authorization", async (response, requestSignal) => {
-            assertNoRedirect(response, trustedEndpoint, "device authorization");
+            await assertNoRedirect(response, trustedEndpoint, "device authorization");
+            const body = await readJsonResponse(response, "device authorization", requestSignal);
             return {
                 response,
-                body: await readBoundedJsonResponse(response, "device authorization", requestSignal),
+                body: body.value,
+                responseText: body.text,
             };
         }, OIDC_REQUEST_TIMEOUT_MS, signal);
-        if (!response.ok)
-            throw new StorageError("OIDC device authorization failed");
-        const session = validateDeviceAuthorizationSession(body);
+        if (!response.ok) {
+            throw providerResponseFailure("device authorization", response, responseText ?? "", "OIDC device authorization failed");
+        }
+        let session;
+        try {
+            session = validateDeviceAuthorizationSession(body);
+        }
+        catch (error) {
+            throw responseValidationFailure("device authorization", response, responseText ?? "", error);
+        }
         ensureOidcNotCancelled(signal, "device authorization");
         // Keep the requested device binding attached to this in-memory session
         // without changing the RFC response shape or serializing it into logs.
@@ -743,7 +981,9 @@ export async function startDeviceCodeLogin(authMetadata, clientId, deviceId, sig
         return session;
     }
     catch (err) {
-        throw new StorageError(formatProviderFailure("device authorization", err));
+        if (err instanceof AggregateError)
+            throw err;
+        throw formatProviderFailure("device authorization", err);
     }
 }
 /**
@@ -776,7 +1016,7 @@ export async function waitForDeviceCodeLogin(authMetadata, clientId, session, si
                 ensureOidcNotCancelled(signal, "device authorization");
                 return { error: "expired" };
             }
-            const { response, body } = await requestWithTimeout(endpoint, {
+            const { response, body, responseText } = await requestWithTimeout(endpoint, {
                 method: "POST",
                 headers: { "Content-Type": "application/x-www-form-urlencoded" },
                 body: new URLSearchParams({
@@ -786,21 +1026,36 @@ export async function waitForDeviceCodeLogin(authMetadata, clientId, session, si
                 }).toString(),
                 redirect: "manual",
             }, "device authorization", async (response, requestSignal) => {
-                assertNoRedirect(response, endpoint, "device authorization");
+                await assertNoRedirect(response, endpoint, "device authorization");
+                const body = await readJsonResponse(response, "device authorization", requestSignal);
                 return {
                     response,
-                    body: await readBoundedJsonResponse(response, "device authorization", requestSignal),
+                    body: body.value,
+                    responseText: body.text,
                 };
             }, Math.min(OIDC_REQUEST_TIMEOUT_MS, remaining), signal);
-            if (response.ok && isValidDeviceAccessTokenResponse(body)) {
-                const tokenResponse = validateDeviceAccessTokenResponse(body);
-                if (!requestedDeviceId ||
-                    typeof tokenResponse.scope !== "string" ||
-                    !scopeMatchesDevice(tokenResponse.scope, requestedDeviceId)) {
-                    throw new OidcValidationError("OIDC device authorization returned an unexpected granted scope");
+            if (!response.ok && !isRecord(body)) {
+                throw providerResponseFailure("device authorization", response, responseText ?? "", "OIDC device authorization returned an invalid response");
+            }
+            if (response.ok) {
+                if (!isValidDeviceAccessTokenResponse(body)) {
+                    throw providerResponseFailure("device authorization", response, responseText ?? "", "OIDC device authorization returned an invalid response");
+                }
+                try {
+                    const tokenResponse = validateDeviceAccessTokenResponse(body);
+                    if (!requestedDeviceId ||
+                        typeof tokenResponse.scope !== "string" ||
+                        !scopeMatchesDevice(tokenResponse.scope, requestedDeviceId)) {
+                        throw new OidcValidationError("OIDC device authorization returned an unexpected granted scope");
+                    }
+                    ensureOidcNotCancelled(signal, "device authorization");
+                    return tokenResponse;
+                }
+                catch (error) {
+                    if (error instanceof OidcRequestCancelledError)
+                        throw error;
+                    throw responseValidationFailure("device authorization", response, responseText ?? "", error);
                 }
-                ensureOidcNotCancelled(signal, "device authorization");
-                return tokenResponse;
             }
             const error = isRecord(body) && typeof body.error === "string" ? body.error : undefined;
             switch (error) {
@@ -815,7 +1070,7 @@ export async function waitForDeviceCodeLogin(authMetadata, clientId, session, si
                     return { error: SAFE_OAUTH_ERROR_CODES.has(error) ? error : "provider_error" };
                 default:
                     ensureOidcNotCancelled(signal, "device authorization");
-                    return { error: "provider_error" };
+                    throw providerResponseFailure("device authorization", response, responseText ?? "", "OIDC device authorization returned an unknown provider error");
             }
             await abortableDelay(Math.min(interval, Math.max(0, expiration - Date.now())), signal);
         } while (Date.now() < expiration);
@@ -823,9 +1078,9 @@ export async function waitForDeviceCodeLogin(authMetadata, clientId, session, si
         return { error: "expired" };
     }
     catch (err) {
-        if (err instanceof OidcValidationError)
+        if (err instanceof OidcValidationError || err instanceof AggregateError)
             throw err;
-        throw new StorageError(formatProviderFailure("device authorization", err));
+        throw formatProviderFailure("device authorization", err);
     }
 }
 export function isDeviceAccessTokenError(result) {
@@ -862,8 +1117,8 @@ export async function beginAuthorizationCodeFlow(opts) {
     try {
         generated = new URL(url);
     }
-    catch {
-        throw new StorageError("OIDC authorization URL is invalid");
+    catch (error) {
+        throw new StorageError("OIDC authorization URL is invalid", { cause: error });
     }
     const expectedEndpoint = parseHttpUrl(authMetadata.authorization_endpoint, "authorization endpoint");
     const stateValues = generated.searchParams.getAll("state");
@@ -900,24 +1155,35 @@ export async function completeAuthorizationCodeFlow(code, state, signal) {
     const serialized = store.getItem(key);
     if (!serialized)
         throw new StorageError("OIDC authorization context is missing or expired");
+    let context;
+    let validationError;
     if (serialized.length > MAX_AUTHORIZATION_CONTEXT_LENGTH) {
-        store.removeItem(key);
-        throw new StorageError("OIDC authorization context is too large");
+        validationError = new StorageError("OIDC authorization context is too large");
     }
-    let context;
+    else {
+        try {
+            context = parseAuthorizationContext(JSON.parse(serialized), state);
+        }
+        catch (error) {
+            validationError = error instanceof StorageError
+                ? error
+                : new StorageError("OIDC authorization context is missing or invalid", { cause: error });
+        }
+    }
+    // Consume the state before any network exchange. A retry must not replay
+    // the authorization code, even if validation fails. Preserve a validation
+    // failure when storage cleanup fails as well.
     try {
-        context = parseAuthorizationContext(JSON.parse(serialized), state);
+        store.removeItem(key);
     }
     catch (error) {
-        if (error instanceof StorageError)
-            throw error;
-        throw new StorageError("OIDC authorization context is missing or invalid");
-    }
-    finally {
-        // Consume the state before any network exchange. A retry must not replay
-        // the authorization code, even if the exchange fails.
-        store.removeItem(key);
+        if (validationError !== undefined) {
+            throw new AggregateError([validationError, error], "OIDC authorization context validation and cleanup failed", { cause: validationError });
+        }
+        throw error;
     }
+    if (validationError !== undefined)
+        throw validationError;
     try {
         requireBoundedString(code, "authorization code", MAX_OIDC_CODE_LENGTH);
         const endpoint = exactEndpoint(context.authMetadata.token_endpoint, "token endpoint");
@@ -928,26 +1194,37 @@ export async function completeAuthorizationCodeFlow(code, state, signal) {
             redirect_uri: context.redirectUri,
             code,
         });
-        const { response, body } = await requestWithTimeout(endpoint, {
+        const { response, body, responseText } = await requestWithTimeout(endpoint, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
             body: params.toString(),
             redirect: "manual",
         }, "authorization code exchange", async (response, requestSignal) => {
-            assertNoRedirect(response, endpoint, "authorization code exchange");
+            await assertNoRedirect(response, endpoint, "authorization code exchange");
+            const body = await readJsonResponse(response, "authorization code exchange", requestSignal);
             return {
                 response,
-                body: await readBoundedJsonResponse(response, "authorization code exchange", requestSignal),
+                body: body.value,
+                responseText: body.text,
             };
         }, OIDC_REQUEST_TIMEOUT_MS, signal);
-        if (!response.ok)
-            throw new StorageError("OIDC authorization code exchange failed");
-        validateBearerTokenResponse(body);
-        validateTokenBounds(body, "authorization code exchange");
-        const normalized = normalizeBearerTokenResponseTokenType(body);
-        const grantedScope = normalized.scope;
-        if (typeof grantedScope !== "string" || !scopeMatchesDevice(grantedScope, context.deviceId)) {
-            throw new StorageError("OIDC authorization code exchange returned an unexpected granted scope");
+        if (!response.ok) {
+            throw providerResponseFailure("authorization code exchange", response, responseText ?? "", "OIDC authorization code exchange failed");
+        }
+        let normalized;
+        let grantedScope;
+        try {
+            validateBearerTokenResponse(body);
+            validateTokenBounds(body, "authorization code exchange");
+            normalized = normalizeBearerTokenResponseTokenType(body);
+            const normalizedScope = normalized.scope;
+            if (typeof normalizedScope !== "string" || !scopeMatchesDevice(normalizedScope, context.deviceId)) {
+                throw new StorageError("OIDC authorization code exchange returned an unexpected granted scope");
+            }
+            grantedScope = normalizedScope;
+        }
+        catch (error) {
+            throw responseValidationFailure("authorization code exchange", response, responseText ?? "", error);
         }
         const tokenResponse = {
             ...normalized,
@@ -961,9 +1238,9 @@ export async function completeAuthorizationCodeFlow(code, state, signal) {
         };
     }
     catch (err) {
-        if (err instanceof StorageError)
+        if (err instanceof StorageError || err instanceof AggregateError)
             throw err;
-        throw new StorageError(formatProviderFailure("authorization code exchange", err));
+        throw formatProviderFailure("authorization code exchange", err);
     }
 }
 // ---------------------------------------------------------------------------
@@ -1029,8 +1306,8 @@ function validateMatrixUserId(userId, serverName) {
     try {
         return validateCanonicalMatrixUserId(userId, serverName);
     }
-    catch {
-        throw new StorageError("OIDC identity confirmation returned an invalid or foreign user ID");
+    catch (error) {
+        throw new StorageError("OIDC identity confirmation returned an invalid or foreign user ID", { cause: error });
     }
 }
 /** Confirms {userId, deviceId} for a freshly-obtained access token via
@@ -1040,35 +1317,50 @@ function validateMatrixUserId(userId, serverName) {
 export async function whoAmI(homeserverUrl, accessToken, serverName, signal) {
     try {
         const homeserver = parseHttpUrl(homeserverUrl, "homeserver URL");
-        const baseUrl = homeserver.toString();
         requireBoundedString(accessToken, "access token", MAX_OIDC_TOKEN_LENGTH);
-        const client = createClient({
-            baseUrl,
-            accessToken,
-            localTimeoutMs: OIDC_REQUEST_TIMEOUT_MS,
-            fetchFn: boundedMatrixFetch("identity confirmation", signal),
-        });
-        const res = await client.whoami();
-        const userId = validateMatrixUserId(res?.user_id, serverName);
-        if (res.device_id !== undefined && res.device_id !== null) {
+        const endpoint = matrixWhoAmIEndpoint(homeserver);
+        const { response, body, responseText } = await requestWithTimeout(endpoint, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" },
+            redirect: "manual",
+        }, "identity confirmation", async (response, requestSignal) => {
+            await assertNoRedirect(response, endpoint, "identity confirmation");
+            if (!response.ok) {
+                const body = await readResponseText(response, requestSignal, "identity confirmation");
+                return { response, body: undefined, responseText: body.text };
+            }
+            const body = await readJsonResponse(response, "identity confirmation", requestSignal);
+            return { response, body: body.value, responseText: body.text };
+        }, OIDC_REQUEST_TIMEOUT_MS, signal);
+        if (!response.ok) {
+            throw providerResponseFailure("identity confirmation", response, responseText ?? "", `OIDC identity confirmation failed (${response.status})`);
+        }
+        if (!isRecord(body)) {
+            throw responseValidationFailure("identity confirmation", response, responseText ?? "", new StorageError("OIDC identity confirmation returned an invalid response"));
+        }
+        const userId = validateMatrixUserId(body.user_id, serverName);
+        let deviceId = null;
+        if (body.device_id !== undefined && body.device_id !== null) {
             try {
-                validateMatrixDeviceId(res.device_id);
+                deviceId = validateMatrixDeviceId(body.device_id);
             }
-            catch {
-                throw new StorageError("OIDC identity confirmation returned an invalid device ID");
+            catch (error) {
+                throw new StorageError("OIDC identity confirmation returned an invalid device ID", { cause: error });
             }
         }
         if (signal?.aborted)
             throw new OidcRequestCancelledError("identity confirmation");
-        return { userId, deviceId: res.device_id ?? null };
+        return { userId, deviceId };
     }
     catch (err) {
+        if (err instanceof AggregateError)
+            throw err;
         if (signal?.aborted) {
             throw new StorageError("OIDC identity confirmation cancelled");
         }
         if (err instanceof StorageError)
             throw err;
-        throw new StorageError(formatProviderFailure("identity confirmation", err));
+        throw formatProviderFailure("identity confirmation", err);
     }
 }
 /**
@@ -1076,9 +1368,8 @@ export async function whoAmI(homeserverUrl, accessToken, serverName, signal) {
  * POST to the token endpoint. A public client (`token_endpoint_auth_method:
  * "none"`, what `registerClient` above registers) authenticates a refresh
  * with just `client_id` in the body, no secret. This narrow request remains
- * local because Matrix 42's `OAuth2.performRefreshTokenGrant` parses every
- * non-success body with unbounded `response.json()`; this path bounds the
- * body and exposes only an allowlisted OAuth error code.
+ * local because Matrix 42's `OAuth2.performRefreshTokenGrant` exposes
+ * provider-controlled response details directly.
  */
 async function refreshOidcToken(tokenEndpoint, clientId, refreshToken, expectedDeviceId, signal) {
     const endpoint = exactEndpoint(tokenEndpoint, "token endpoint");
@@ -1102,35 +1393,43 @@ async function refreshOidcToken(tokenEndpoint, clientId, refreshToken, expectedD
             }).toString(),
             signal: controller.signal,
             redirect: "manual",
-        }), controller.signal, () => undefined, () => signal?.aborted
-            ? new StorageError("OIDC token refresh cancelled")
-            : new StorageError("OIDC token refresh timed out"));
-        assertNoRedirect(res, endpoint, "token refresh");
+        }), controller.signal, () => signal?.aborted
+            ? new StorageError("OIDC token refresh cancelled", {
+                cause: new OidcRequestCancelledError("token refresh"),
+            })
+            : new StorageError("OIDC token refresh timed out", {
+                cause: new OidcRequestTimeoutError("token refresh"),
+            }));
+        await assertNoRedirect(res, endpoint, "token refresh");
         if (!res.ok) {
             let body;
             try {
-                body = await readBoundedResponseText(res, MAX_OAUTH_ERROR_BODY_BYTES, controller.signal);
+                body = await readResponseText(res, controller.signal, "token refresh");
             }
             catch (error) {
                 if (signal?.aborted || controller.signal.aborted)
                     throw error;
-                body = { text: "", truncated: false };
+                throw new StorageError("OIDC token refresh error response could not be read", {
+                    cause: diagnosticCause(error),
+                });
             }
-            throw new StorageError(formatTokenRefreshFailure(res.status, body));
-        }
-        const body = await readBoundedResponseText(res, MAX_OAUTH_SUCCESS_BODY_BYTES, controller.signal);
-        if (body.truncated) {
-            throw new StorageError("OIDC token refresh returned an oversized response");
+            throw formatTokenRefreshFailure(res.status, body);
         }
+        const body = await readResponseText(res, controller.signal, "token refresh");
+        const invalidResponse = (message, cause) => new StorageError(message, {
+            cause: new OidcResponseError("token refresh", res.status, body.text, cause),
+        });
         let data;
         try {
             data = JSON.parse(body.text);
         }
-        catch {
-            throw new StorageError("OIDC token refresh returned an invalid response");
+        catch (error) {
+            throw new StorageError("OIDC token refresh returned an invalid response", {
+                cause: new OidcResponseError("token refresh", res.status, body.text, error),
+            });
         }
         if (!data || typeof data !== "object") {
-            throw new StorageError("OIDC token refresh returned an invalid response");
+            throw invalidResponse("OIDC token refresh returned an invalid response");
         }
         const record = data;
         const accessToken = record.access_token;
@@ -1141,42 +1440,42 @@ async function refreshOidcToken(tokenEndpoint, clientId, refreshToken, expectedD
             accessToken.trim() === "" ||
             accessToken.length > MAX_OIDC_TOKEN_LENGTH ||
             /[\s\u0000-\u001f\u007f]/.test(accessToken)) {
-            throw new StorageError("OIDC token refresh returned no access token");
+            throw invalidResponse("OIDC token refresh returned no access token");
         }
         const tokenType = record.token_type;
         if (typeof tokenType !== "string" || tokenType.toLowerCase() !== "bearer") {
-            throw new StorageError("OIDC token refresh returned an invalid token type");
+            throw invalidResponse("OIDC token refresh returned an invalid token type");
         }
         if (nextRefreshToken !== undefined &&
             (typeof nextRefreshToken !== "string" ||
                 nextRefreshToken.trim() === "" ||
                 nextRefreshToken.length > MAX_OIDC_TOKEN_LENGTH ||
                 /[\s\u0000-\u001f\u007f]/.test(nextRefreshToken))) {
-            throw new StorageError("OIDC token refresh returned an invalid refresh token");
+            throw invalidResponse("OIDC token refresh returned an invalid refresh token");
         }
         if (grantedScope !== undefined) {
             if (typeof grantedScope !== "string") {
-                throw new StorageError("OIDC token refresh returned an invalid scope");
+                throw invalidResponse("OIDC token refresh returned an invalid scope");
             }
             try {
                 requireScope(grantedScope, "scope");
             }
-            catch {
-                throw new StorageError("OIDC token refresh returned an invalid scope");
+            catch (error) {
+                throw invalidResponse("OIDC token refresh returned an invalid scope", { cause: error });
             }
             if (!scopeMatchesDevice(grantedScope, expectedDeviceId)) {
-                throw new StorageError("OIDC token refresh returned an unexpected granted scope");
+                throw invalidResponse("OIDC token refresh returned an unexpected granted scope");
             }
         }
         else {
-            throw new StorageError("OIDC token refresh returned no device-bound scope");
+            throw invalidResponse("OIDC token refresh returned no device-bound scope");
         }
         if (expiresIn !== undefined &&
             (typeof expiresIn !== "number" ||
                 !Number.isInteger(expiresIn) ||
                 expiresIn < 0 ||
                 expiresIn > 86400)) {
-            throw new StorageError("OIDC token refresh returned an invalid expiry");
+            throw invalidResponse("OIDC token refresh returned an invalid expiry");
         }
         ensureOidcNotCancelled(signal, "token refresh");
         return {
@@ -1190,15 +1489,15 @@ async function refreshOidcToken(tokenEndpoint, clientId, refreshToken, expectedD
         };
     }
     catch (error) {
-        if (error instanceof StorageError)
+        if (error instanceof StorageError || error instanceof AggregateError)
             throw error;
         if (signal?.aborted) {
-            throw new StorageError("OIDC token refresh cancelled");
+            throw new StorageError("OIDC token refresh cancelled", { cause: diagnosticCause(error) });
         }
         if (controller.signal.aborted) {
-            throw new StorageError("OIDC token refresh timed out");
+            throw new StorageError("OIDC token refresh timed out", { cause: diagnosticCause(error) });
         }
-        throw new StorageError("OIDC token refresh failed");
+        throw new StorageError("OIDC token refresh failed", { cause: diagnosticCause(error) });
     }
     finally {
         clearTimeout(timeout);
@@ -1210,27 +1509,30 @@ async function revokeOidcToken(revocationEndpoint, clientId, token, tokenTypeHin
     const endpoint = exactEndpoint(revocationEndpoint, "revocation endpoint");
     const safeClientId = requireClientId(clientId);
     const safeToken = requireBoundedString(token, "token", MAX_OIDC_TOKEN_LENGTH);
-    const { response } = await requestWithTimeout(endpoint, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: new URLSearchParams({
-            client_id: safeClientId,
-            token: safeToken,
-            token_type_hint: tokenTypeHint,
-        }).toString(),
-        redirect: "manual",
-    }, "token revocation", async (res, requestSignal) => {
-        assertNoRedirect(res, endpoint, "token revocation");
-        if (!res.ok) {
-            await readBoundedResponseText(res, MAX_OAUTH_ERROR_BODY_BYTES, requestSignal);
-        }
-        else {
-            await readBoundedResponseText(res, MAX_OAUTH_SUCCESS_BODY_BYTES, requestSignal);
+    try {
+        const { response, responseText } = await requestWithTimeout(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                client_id: safeClientId,
+                token: safeToken,
+                token_type_hint: tokenTypeHint,
+            }).toString(),
+            redirect: "manual",
+        }, "token revocation", async (res, requestSignal) => {
+            await assertNoRedirect(res, endpoint, "token revocation");
+            const body = await readResponseText(res, requestSignal, "token revocation");
+            return { response: res, responseText: body.text };
+        }, OIDC_REQUEST_TIMEOUT_MS, signal);
+        if (!response.ok) {
+            throw providerResponseFailure("token revocation", response, responseText ?? "", "OIDC token revocation failed");
         }
-        return { response: res };
-    }, OIDC_REQUEST_TIMEOUT_MS, signal);
-    if (!response.ok)
-        throw new StorageError("OIDC token revocation failed");
+    }
+    catch (error) {
+        if (error instanceof StorageError || error instanceof AggregateError)
+            throw error;
+        throw formatProviderFailure("token revocation", error);
+    }
 }
 async function persistOidcTokens(onPersist, tokens, externalSignal) {
     if (externalSignal?.aborted)
@@ -1250,7 +1552,7 @@ async function persistOidcTokens(onPersist, tokens, externalSignal) {
         // Promise.resolve().then() also observes synchronous callback throws and
         // lets raceWithAbort attach a rejection handler before a late adapter
         // rejection can become unhandled after the bounded call has settled.
-        await raceWithAbort(Promise.resolve().then(() => onPersist(tokens, controller.signal)), controller.signal, () => undefined, () => timedOut
+        await raceWithAbort(Promise.resolve().then(() => onPersist(tokens, controller.signal)), controller.signal, () => timedOut
             ? new OidcRequestTimeoutError("token persistence")
             : new OidcRequestCancelledError("token persistence"));
         // The persistence promise and the caller signal can settle in either
@@ -1295,26 +1597,42 @@ export function buildTokenRefreshFunction(metadata, clientId, onPersist, expecte
         try {
             await persistOidcTokens(onPersist, { accessToken: tokens.accessToken, refreshToken: tokens.refreshToken }, signal);
         }
-        catch {
+        catch (persistenceError) {
             if (revocationEndpoint) {
                 // Cleanup must remain possible even when the caller's signal is
                 // already aborted. Use a separate bounded signal so persistence
                 // failure cannot strand freshly-issued tokens merely because the
                 // original request was cancelled.
                 const cleanup = createOidcCleanupSignal();
+                const cleanupFailures = [];
                 try {
-                    await revokeOidcToken(revocationEndpoint, safeClientId, tokens.accessToken, "access_token", cleanup.signal);
+                    try {
+                        await revokeOidcToken(revocationEndpoint, safeClientId, tokens.accessToken, "access_token", cleanup.signal);
+                    }
+                    catch (error) {
+                        cleanupFailures.push(error);
+                    }
                     if (tokens.refreshToken) {
-                        await revokeOidcToken(revocationEndpoint, safeClientId, tokens.refreshToken, "refresh_token", cleanup.signal);
+                        try {
+                            await revokeOidcToken(revocationEndpoint, safeClientId, tokens.refreshToken, "refresh_token", cleanup.signal);
+                        }
+                        catch (error) {
+                            cleanupFailures.push(error);
+                        }
                     }
                 }
-                catch {
+                finally {
                     cleanup.close();
-                    throw new StorageError("OIDC token persistence failed and session cleanup was incomplete");
                 }
-                cleanup.close();
+                if (cleanupFailures.length > 0) {
+                    throw new StorageError("OIDC token persistence failed and session cleanup was incomplete", {
+                        cause: new AggregateError([persistenceError, ...cleanupFailures], "OIDC token persistence and session cleanup failed"),
+                    });
+                }
             }
-            throw new StorageError("OIDC token persistence failed; discard the refreshed session");
+            throw new StorageError("OIDC token persistence failed; discard the refreshed session", {
+                cause: persistenceError,
+            });
         }
         ensureOidcNotCancelled(signal, "token refresh");
         return tokens;