@oxyhq/core 19.1.2 → 20.1.0

package/dist/cjs/mixins/OxyServices.utility.js

@@ -136,18 +136,41 @@ function OxyServicesUtilityMixin(Base) {
          * Uses server-side session validation for security (not just JWT decode).
          *
          * **Design note — jwtDecode vs jwt.verify:**
-         * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
-         * verification) for user tokens. This is by design, NOT a security gap:
-         * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
-         * - Security comes from API-based session validation (`validateSession()`)
-         *   which checks the session server-side on every request
-         * - Service tokens (type: 'service') DO use cryptographic HMAC verification
-         *   via the `jwtSecret` option, since they are stateless. Service tokens
-         *   are additionally checked for `aud`, `iss`, and `type` claims to prevent
+         * This middleware uses `jwtDecode()` (decode-only, NO signature check) for
+         * user tokens, because third-party apps mounting `oxy.auth()` do not hold
+         * the Oxy signing secret. **Every claim in a user token is therefore
+         * attacker-controlled and proves nothing on its own.** The identity comes
+         * from somewhere else entirely:
+         * - A user token MUST carry a `sessionId`. That session is validated
+         *   server-side on every request via `validateSession()`, and the user id
+         *   is read off the VALIDATED SESSION — never off the token. A token whose
+         *   `userId` claim disagrees with the session is refused
+         *   (`SESSION_USER_MISMATCH`); a token with no `sessionId` at all is
+         *   refused outright (`SESSION_REQUIRED`). There is no local-claims path.
+         * - Service tokens (type: 'service') ARE stateless, so they use
+         *   cryptographic HMAC verification via the `jwtSecret` option, and are
+         *   additionally checked for `aud`, `iss`, and `type` claims to prevent
          *   cross-token-type confusion attacks.
          * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
          *   direct access to `SERVICE_TOKEN_SECRET` / `ACCESS_TOKEN_SECRET`.
          *
+         * **Why session-less user tokens are refused rather than trusted:**
+         * every user access token the Oxy API issues carries a `sessionId` (see
+         * `packages/api/src/utils/sessionUtils.ts`, `generateSessionTokens` — the
+         * only mint site for user tokens, including the OAuth code exchange). So
+         * refusing session-less user tokens costs nothing legitimate, while
+         * accepting them let anyone authenticate as anyone by hand-rolling a JWT
+         * with a `userId` claim and a garbage signature.
+         *
+         * **Why the claimed user id is cross-checked against the session:**
+         * `GET /session/validate/:sessionId` is UNAUTHENTICATED and does not bind
+         * the bearer token — it returns whoever owns the session id it was handed.
+         * Trusting the token's `userId` claim after a successful validation would
+         * therefore let a caller holding ANY live session id (their own, for
+         * instance) pair it with a forged `userId` and be trusted as that user.
+         * `authSocket()` has always cross-checked this; the HTTP middleware now
+         * does too.
+         *
          * **Service-token delegation (X-Oxy-User-Id):**
          * When a service token is accompanied by `X-Oxy-User-Id`, the SDK calls
          * `verifyServiceActingAs(appId, userId)` to confirm an explicit delegation
@@ -410,8 +433,10 @@ function OxyServicesUtilityMixin(Base) {
                         }
                         return next();
                     }
-                    const userId = decoded.userId || decoded.id;
-                    if (!userId) {
+                    // The CLAIMED user id. Never trusted as an identity — it is only ever
+                    // compared against the id the validated session resolves to.
+                    const claimedUserId = readStringClaim(decoded.userId) ?? readStringClaim(decoded.id);
+                    if (!claimedUserId) {
                         if (optional) {
                             req.userId = null;
                             req.user = null;
@@ -445,111 +470,129 @@ function OxyServicesUtilityMixin(Base) {
                             return onError(error);
                         return res.status(401).json(error);
                     }
-                    // Validate token against the Oxy API for session-based verification
-                    // This ensures the session hasn't been revoked server-side
-                    if (decoded.sessionId) {
-                        try {
-                            const validationResult = await oxyInstance.validateSession(decoded.sessionId, {
-                                useHeaderValidation: true,
-                            });
-                            if (!validationResult || !validationResult.valid) {
-                                if (optional) {
-                                    req.userId = null;
-                                    req.user = null;
-                                    return next();
-                                }
-                                const error = {
-                                    error: 'INVALID_SESSION',
-                                    message: 'Session invalid or expired',
-                                    code: 'INVALID_SESSION',
-                                    status: 401
-                                };
-                                if (onError)
-                                    return onError(error);
-                                return res.status(401).json(error);
-                            }
-                            // Use validated user data from session validation (already has full user)
-                            req.userId = userId;
-                            req.accessToken = token;
-                            req.sessionId = decoded.sessionId;
-                            if (loadUser && validationResult.user) {
-                                // Session validation already returns full user data
-                                req.user = validationResult.user;
-                            }
-                            else {
-                                req.user = { id: userId };
-                            }
-                            if (debug) {
-                                logger_1.logger.debug(`[oxy.auth] OK user=${userId} session=${decoded.sessionId}`, {
-                                    component: 'auth',
-                                    method: 'auth',
-                                });
-                            }
+                    // A server-validated session is MANDATORY for a user token. The JWT
+                    // signature is not verified on this path, so a bare decoded token
+                    // proves nothing: without the session round-trip a forged token could
+                    // claim any user id. Mirrors `authSocket()`, which has always
+                    // required this.
+                    const sessionId = readStringClaim(decoded.sessionId);
+                    if (!sessionId) {
+                        if (optional) {
+                            req.userId = null;
+                            req.user = null;
                             return next();
                         }
-                        catch (validationError) {
-                            if (debug) {
-                                logger_1.logger.debug('[oxy.auth] Session validation failed', {
-                                    component: 'auth',
-                                    method: 'auth',
-                                }, validationError);
-                            }
+                        const error = {
+                            error: 'SESSION_REQUIRED',
+                            message: 'Access token is not bound to a session',
+                            code: 'SESSION_REQUIRED',
+                            status: 401
+                        };
+                        if (onError)
+                            return onError(error);
+                        return res.status(401).json(error);
+                    }
+                    // Validate the token against the Oxy API. This proves the session is
+                    // real and unrevoked, AND yields the identity it belongs to.
+                    try {
+                        const validationResult = await oxyInstance.validateSession(sessionId, {
+                            useHeaderValidation: true,
+                        });
+                        if (!validationResult || !validationResult.valid || !validationResult.user) {
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
                                 return next();
                             }
                             const error = {
-                                error: 'SESSION_VALIDATION_ERROR',
-                                message: 'Session validation failed',
-                                code: 'SESSION_VALIDATION_ERROR',
+                                error: 'INVALID_SESSION',
+                                message: 'Session invalid or expired',
+                                code: 'INVALID_SESSION',
                                 status: 401
                             };
                             if (onError)
                                 return onError(error);
                             return res.status(401).json(error);
                         }
-                    }
-                    // Non-session token: use local validation only (userId from JWT)
-                    req.userId = userId;
-                    req.accessToken = token;
-                    req.user = { id: userId };
-                    // If loadUser requested with non-session token, fetch from API
-                    if (loadUser) {
-                        try {
-                            // Temporarily set token to make the API call
-                            const prevToken = oxyInstance.getAccessToken();
-                            oxyInstance.setTokens(token);
-                            const fullUser = await oxyInstance.getCurrentUser();
-                            // Restore previous token
-                            if (prevToken) {
-                                oxyInstance.setTokens(prevToken);
-                            }
-                            else {
-                                oxyInstance.clearTokens();
+                        // The session — not the token — is the source of truth for identity.
+                        const validatedUserId = getUserIdentityId(validationResult.user);
+                        if (!validatedUserId) {
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
                             }
-                            if (fullUser) {
-                                req.user = fullUser;
+                            const error = {
+                                error: 'INVALID_SESSION',
+                                message: 'Session did not resolve to a usable identity',
+                                code: 'INVALID_SESSION',
+                                status: 401
+                            };
+                            if (onError)
+                                return onError(error);
+                            return res.status(401).json(error);
+                        }
+                        if (validatedUserId !== claimedUserId) {
+                            // Session-id/claim confusion: the caller presented a live session
+                            // that belongs to somebody else. Worth a warning — it has no
+                            // benign cause. Ids only; never the token or the payload.
+                            logger_1.logger.warn('[oxy.auth] Token rejected — claimed user does not own the session', {
+                                component: 'auth',
+                                method: 'auth',
+                                claimedUserId,
+                                validatedUserId,
+                            });
+                            if (optional) {
+                                req.userId = null;
+                                req.user = null;
+                                return next();
                             }
+                            const error = {
+                                error: 'SESSION_USER_MISMATCH',
+                                message: 'Token user does not match the session',
+                                code: 'SESSION_USER_MISMATCH',
+                                status: 401
+                            };
+                            if (onError)
+                                return onError(error);
+                            return res.status(401).json(error);
                         }
-                        catch (loadUserError) {
-                            // Loading the full user is best-effort here; the basic { id }
-                            // object is already attached. Log so misconfigured deployments
-                            // can be diagnosed instead of silently failing.
-                            logger_1.logger.warn('[oxy.auth] loadUser fallback — could not fetch full profile', {
+                        req.userId = validatedUserId;
+                        req.accessToken = token;
+                        req.sessionId = sessionId;
+                        // Session validation already returned the full user, so `loadUser`
+                        // costs no extra round-trip.
+                        req.user = loadUser ? validationResult.user : { id: validatedUserId };
+                        if (debug) {
+                            logger_1.logger.debug(`[oxy.auth] OK user=${validatedUserId} session=${sessionId}`, {
                                 component: 'auth',
-                                method: 'auth.loadUser',
-                                userId,
-                            }, loadUserError);
+                                method: 'auth',
+                            });
                         }
+                        return next();
                     }
-                    if (debug) {
-                        logger_1.logger.debug(`[oxy.auth] OK user=${userId} (no session)`, {
-                            component: 'auth',
-                            method: 'auth',
-                        });
+                    catch (validationError) {
+                        if (debug) {
+                            logger_1.logger.debug('[oxy.auth] Session validation failed', {
+                                component: 'auth',
+                                method: 'auth',
+                            }, validationError);
+                        }
+                        if (optional) {
+                            req.userId = null;
+                            req.user = null;
+                            return next();
+                        }
+                        const error = {
+                            error: 'SESSION_VALIDATION_ERROR',
+                            message: 'Session validation failed',
+                            code: 'SESSION_VALIDATION_ERROR',
+                            status: 401
+                        };
+                        if (onError)
+                            return onError(error);
+                        return res.status(401).json(error);
                     }
-                    next();
                 }
                 catch (error) {
                     const handled = oxyInstance.handleError(error);
@@ -618,7 +661,7 @@ function OxyServicesUtilityMixin(Base) {
                         }
                         return next(new Error('Invalid token'));
                     }
-                    const claimedUserId = decoded.userId || decoded.id;
+                    const claimedUserId = readStringClaim(decoded.userId) ?? readStringClaim(decoded.id);
                     if (!claimedUserId) {
                         return next(new Error('Invalid token payload'));
                     }
@@ -629,12 +672,13 @@ function OxyServicesUtilityMixin(Base) {
                     // A server-validated session is mandatory. A bare decoded JWT proves
                     // nothing — the signature is not verified here, so without a session
                     // round-trip a forged token could claim any user id.
-                    if (!decoded.sessionId) {
+                    const sessionId = readStringClaim(decoded.sessionId);
+                    if (!sessionId) {
                         return next(new Error('Session required'));
                     }
                     let userId = claimedUserId;
                     try {
-                        const result = await oxyInstance.validateSession(decoded.sessionId, {
+                        const result = await oxyInstance.validateSession(sessionId, {
                             useHeaderValidation: true,
                         });
                         if (!result || !result.valid || !result.user) {
@@ -664,9 +708,9 @@ function OxyServicesUtilityMixin(Base) {
                     // reads from `socket.user.id`.
                     socket.data = socket.data || {};
                     socket.data.userId = userId;
-                    socket.data.sessionId = decoded.sessionId || null;
+                    socket.data.sessionId = sessionId;
                     socket.data.token = token;
-                    socket.user = { id: userId, userId, sessionId: decoded.sessionId };
+                    socket.user = { id: userId, userId, sessionId };
                     if (debug) {
                         logger_1.logger.debug(`[oxy.authSocket] OK user=${userId}`, {
                             component: 'auth',
@@ -810,12 +854,16 @@ async function verifyServiceTokenSignature(token, secret) {
     }
 }
 /**
- * Verify that a decoded service-token payload carries the expected `aud`,
- * `iss`, and `type` claims. Throws `ServiceTokenClaimError` on mismatch.
- * This is the defence against the H4 vulnerability where a recovery / 2FA /
- * access token signed by the same shared secret could be replayed as a
- * service token because no claim binding existed.
+ * Read a JWT claim that is only usable as a non-empty string.
+ *
+ * A decoded payload is attacker-controlled JSON: a claim the type declares as
+ * `string` can arrive as a number, an object, or `null`. Narrowing here keeps
+ * those values out of URL construction and identity comparison, so an
+ * unexpected shape becomes a 401 rather than a stringified surprise.
  */
+function readStringClaim(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
 /**
  * Resolve the canonical user id from a validated session's user object.
  *
@@ -828,6 +876,13 @@ function getUserIdentityId(user) {
         ?? user._id;
     return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
 }
+/**
+ * Verify that a decoded service-token payload carries the expected `aud`,
+ * `iss`, and `type` claims. Throws `ServiceTokenClaimError` on mismatch.
+ * This is the defence against the H4 vulnerability where a recovery / 2FA /
+ * access token signed by the same shared secret could be replayed as a
+ * service token because no claim binding existed.
+ */
 function verifyServiceTokenClaims(decoded, expected) {
     if (decoded.type !== 'service') {
         throw new ServiceTokenClaimError(`Service token has unexpected type '${String(decoded.type)}'`);

package/dist/cjs/mixins/index.js

@@ -20,6 +20,7 @@ const OxyServices_reputation_1 = require("./OxyServices.reputation");
 const OxyServices_assets_1 = require("./OxyServices.assets");
 const OxyServices_accounts_1 = require("./OxyServices.accounts");
 const OxyServices_connectedApps_1 = require("./OxyServices.connectedApps");
+const OxyServices_store_1 = require("./OxyServices.store");
 const OxyServices_location_1 = require("./OxyServices.location");
 const OxyServices_analytics_1 = require("./OxyServices.analytics");
 const OxyServices_devices_1 = require("./OxyServices.devices");
@@ -31,6 +32,7 @@ const OxyServices_contacts_1 = require("./OxyServices.contacts");
 const OxyServices_notifications_1 = require("./OxyServices.notifications");
 const OxyServices_appData_1 = require("./OxyServices.appData");
 const OxyServices_civic_1 = require("./OxyServices.civic");
+const OxyServices_chains_1 = require("./OxyServices.chains");
 const OxyServices_nodes_1 = require("./OxyServices.nodes");
 const OxyServices_links_1 = require("./OxyServices.links");
 const OxyServices_followGraph_1 = require("./OxyServices.followGraph");
@@ -70,6 +72,10 @@ const MIXIN_PIPELINE = [
     // OAuth-consent surface (public app identity + connected-app grants). Kept
     // separate from account ownership.
     OxyServices_connectedApps_1.OxyServicesConnectedAppsMixin,
+    // The app store: the public storefront, the reviews on it, and the listing a
+    // publisher edits. A module OVER the platform — turn it off and OAuth still
+    // works — so it is its own surface rather than more of `accounts`.
+    OxyServices_store_1.OxyServicesStoreMixin,
     OxyServices_location_1.OxyServicesLocationMixin,
     OxyServices_analytics_1.OxyServicesAnalyticsMixin,
     OxyServices_devices_1.OxyServicesDevicesMixin,
@@ -84,6 +90,7 @@ const MIXIN_PIPELINE = [
     OxyServices_appData_1.OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServices_civic_1.OxyServicesCivicMixin,
+    OxyServices_chains_1.OxyServicesChainsMixin,
     // User nodes / decentralization (Fase 5): register/read/revoke/manage the
     // caller's personal data node + ingest hint.
     OxyServices_nodes_1.OxyServicesNodesMixin,

package/dist/cjs/server/rateLimit.js

@@ -7,6 +7,7 @@ exports.createOxyRateLimit = createOxyRateLimit;
 const node_crypto_1 = require("node:crypto");
 const node_net_1 = require("node:net");
 const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
+const auth_1 = require("./auth");
 /**
  * Built-in exemptions. A media app's cover-art/avatar fan-out and HLS
  * sub-requests must not consume the coarse global budget; health probes from
@@ -119,11 +120,12 @@ function hashAnonymousIp(ip) {
 /**
  * Resolve the trusted authenticated rate-limit key.
  *
- * `oxy.auth({ optional: true })` preserves legacy non-session user tokens by
- * decoding their JWT claims locally. Those claims are not cryptographically
- * verified and therefore MUST NOT influence abuse-control buckets. Only use
- * identities that came from a server-validated session or a verified service
- * token/delegation.
+ * Only identities that came from a server-validated session or a verified
+ * service token/delegation may pick a bucket. `req.sessionId` is the marker
+ * for the former: `oxy.auth()` sets it only after `validateSession()` came
+ * back valid, so requiring it here means an identity written by some OTHER
+ * middleware — which this package cannot vouch for — shares the anonymous
+ * per-IP bucket rather than getting the authenticated quota.
  */
 function resolveTrustedAuthenticatedKey(req) {
     const userId = req.userId ?? req.user?.id ?? req.user?._id;
@@ -159,7 +161,14 @@ function createOxyRateLimit(oxy, options = {}) {
     const { authenticatedMax = 5000, anonymousMax = 600, windowMs = 15 * 60 * 1000, store, exempt, message = 'Too many requests, please try again later.', auth, } = options;
     // Idempotent optional-auth resolver. Reuses the SAME session resolution as
     // every protected route, so the limiter keys by the real user identity.
-    const resolveSession = oxy.auth({ ...auth, optional: true });
+    //
+    // `createOptionalOxyAuth` — NOT the raw `oxy.auth({ optional: true })` —
+    // because only the former skips resolution when a preceding middleware has
+    // already resolved a user. The raw middleware writes `req.userId = null` on
+    // every request it cannot authenticate, and because it mutates the shared
+    // `req` that erasure is visible to every handler downstream of the limiter,
+    // not just to the bucket calculation.
+    const resolveSession = (0, auth_1.createOptionalOxyAuth)(oxy, { auth });
     const skip = (req) => isBuiltInExempt(req) || (exempt ? exempt(req) : false);
     const limiter = (0, express_rate_limit_1.default)({
         windowMs,

package/dist/cjs/session/accountProjection.js

@@ -19,6 +19,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSwitchTargetAccount = isSwitchTargetAccount;
+exports.canSwitchIntoAccount = canSwitchIntoAccount;
 exports.projectSwitchableAccounts = projectSwitchableAccounts;
 exports.switchableAccountIds = switchableAccountIds;
 const contracts_1 = require("@oxyhq/contracts");
@@ -53,6 +54,30 @@ const userHandle_1 = require("../utils/userHandle");
 function isSwitchTargetAccount(node) {
     return node.relationship === 'self' || (0, contracts_1.isActAsEligibleKind)(node.kind);
 }
+/**
+ * Whether the caller may switch INTO this account — the server-side
+ * `account:act_as` gate plus the structural {@link isSwitchTargetAccount} rule.
+ *
+ * `relationship: 'self'` always passes (returning to the caller's own personal
+ * account). Every other ground requires a switch-eligible kind AND
+ * `account:act_as` in the resolved membership permissions. When permissions are
+ * absent but the relationship is `owner`, the owner baseline is assumed — the
+ * API always resolves effective permissions for owned accounts, but test
+ * fixtures and stale rows may omit the membership blob.
+ */
+function canSwitchIntoAccount(node) {
+    if (node.relationship === 'self') {
+        return true;
+    }
+    if (!isSwitchTargetAccount(node)) {
+        return false;
+    }
+    const permissions = node.callerMembership?.permissions;
+    if (permissions) {
+        return permissions.includes('account:act_as');
+    }
+    return node.relationship === 'owner';
+}
 /**
  * Pure union of device sign-ins and account-graph nodes into the flat
  * {@link SwitchableAccount}[] every switcher renders.
@@ -62,9 +87,9 @@ function isSwitchTargetAccount(node) {
  * and a graph node is deduped into ONE device row enriched with the graph
  * metadata (relationship / kind / parent / membership).
  *
- * Graph nodes that are not switch targets — a `channel`, which nobody may act
- * as — are omitted. {@link isSwitchTargetAccount} is the rule; see the filter
- * below.
+ * Graph nodes the caller cannot switch into — a `channel`, or a managed account
+ * whose membership lacks `account:act_as` — are omitted.
+ * {@link canSwitchIntoAccount} is the rule; see the filter below.
  */
 function projectSwitchableAccounts(input) {
     const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
@@ -144,7 +169,7 @@ function projectSwitchableAccounts(input) {
         // An account already on the device skipped this check via the branch above,
         // and correctly: whatever its kind, the caller is signed into it, so
         // switching is a local activation that asks the server for nothing.
-        if (!isSwitchTargetAccount(node)) {
+        if (!canSwitchIntoAccount(node)) {
             continue;
         }
         remember(toRow(node.account, {
@@ -166,7 +191,7 @@ function projectSwitchableAccounts(input) {
  * document, but including their ids lets the caller pass one id set and lets the
  * projection prefer freshly-fetched profiles uniformly.
  *
- * Applies the SAME {@link isSwitchTargetAccount} filter as
+ * Applies the SAME {@link canSwitchIntoAccount} filter as
  * {@link projectSwitchableAccounts} to graph nodes, so this never fetches a
  * profile for a row the projection will drop — and, just as importantly, never
  * SKIPS one the projection will keep, which would leave that row unrendered
@@ -180,7 +205,7 @@ function switchableAccountIds(state, graph) {
         }
     }
     for (const node of graph) {
-        if (node.accountId && isSwitchTargetAccount(node)) {
+        if (node.accountId && canSwitchIntoAccount(node)) {
             ids.add(node.accountId);
         }
     }

package/dist/cjs/utils/errorUtils.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorCodes = void 0;
+exports.isHttpRequestError = isHttpRequestError;
+exports.parseHttpErrorBody = parseHttpErrorBody;
 exports.createApiError = createApiError;
 exports.handleHttpError = handleHttpError;
 exports.getErrorCodeFromStatus = getErrorCodeFromStatus;
@@ -37,6 +39,63 @@ exports.ErrorCodes = {
     NETWORK_ERROR: 'NETWORK_ERROR',
     CONNECTION_FAILED: 'CONNECTION_FAILED'
 };
+/**
+ * Narrow a caught value to {@link HttpRequestError}.
+ *
+ * Returns `false` for a plain {@link ApiError} object (those are objects, not
+ * `Error`s) — run an arbitrary thrown value through {@link handleHttpError}
+ * first if you need one normalized.
+ */
+function isHttpRequestError(value) {
+    if (!(value instanceof Error)) {
+        return false;
+    }
+    return typeof value.status === 'number';
+}
+const isPlainRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const nonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+/**
+ * Extract `message` / `code` / `details` from a parsed HTTP error response body.
+ *
+ * Handles every error envelope in use across the Oxy ecosystem:
+ *
+ * - `{ error: { code, message, details? } }` — nested envelope (CrowdSource and
+ *   other Oxy services). Never stringify the nested object: `new Error(obj)`
+ *   yields the literal message `"[object Object]"`.
+ * - `{ error: '<CODE>', message, details? }` — oxy-api's canonical shape
+ *   (`ApiError.toJSON`), where the top-level `error` field IS the code.
+ * - `{ error: '<CODE>', error_description }` — RFC 6749 §5.2 / RFC 6750 §3, the
+ *   OAuth token and userinfo endpoints. `error_description` is the human text
+ *   and `error` is the machine code, so both survive.
+ * - `{ message, code }` — e.g. the API's CSRF rejections.
+ * - `{ error: '<human message>' }` — legacy hand-rolled routes. With no sibling
+ *   `message`/`error_description` the string is the message, not a code: a bare
+ *   `error` string is not machine-readable enough to promote to `code`.
+ *
+ * Anything else — a non-object body (`null`, `[]`, `"str"`, `42`), or an object
+ * carrying none of these fields — yields an empty result, leaving the caller on
+ * its status-based fallback message. Total function: never throws.
+ */
+function parseHttpErrorBody(body) {
+    if (!isPlainRecord(body)) {
+        return {};
+    }
+    const nested = isPlainRecord(body.error) ? body.error : undefined;
+    const errorString = nonEmptyString(body.error);
+    // A sibling that proves the top-level `error` is a CODE rather than prose.
+    const siblingMessage = nonEmptyString(body.message) ?? nonEmptyString(body.error_description);
+    return {
+        message: siblingMessage ?? (nested ? nonEmptyString(nested.message) : errorString),
+        code: (nested ? nonEmptyString(nested.code) : undefined) ??
+            nonEmptyString(body.code) ??
+            (siblingMessage ? errorString : undefined),
+        details: isPlainRecord(body.details)
+            ? body.details
+            : nested && isPlainRecord(nested.details)
+                ? nested.details
+                : undefined,
+    };
+}
 /**
  * Create a standardized API error
  */
@@ -81,7 +140,12 @@ function handleHttpError(error) {
         const fetchError = error;
         const status = fetchError.response?.status || fetchError.status;
         if (status) {
-            return createApiError(fetchError.message || `HTTP ${status} error`, getErrorCodeFromStatus(status), status);
+            // `details` is carried through when present: a body may ship structured
+            // detail without a machine-readable `code` (which is what routes the
+            // error to the already-an-ApiError branch above), and dropping it here
+            // would make it unreachable to every caller that rethrows via
+            // `OxyServices.handleError`.
+            return createApiError(fetchError.message || `HTTP ${status} error`, getErrorCodeFromStatus(status), status, isPlainRecord(fetchError.details) ? fetchError.details : undefined);
         }
     }
     // Handle standard errors