@oxyhq/core 5.1.0 → 5.2.0

package/dist/cjs/AuthManager.js

@@ -397,11 +397,33 @@ class AuthManager {
             this.currentUser = session.user;
         }
         this.currentAuthMethod = method;
-        const decodedAuthuser = session.accessToken
-            ? AuthManager.decodeAuthuserFromAccessToken(session.accessToken)
+        // Register this primary session in the device's first-party multi-account
+        // refresh-cookie set (web only). Every web primary commit funnels through
+        // here (FedCM, central `/sso` return, credentials), but only a same-apex
+        // `/fedcm/exchange` plants an `oxy_rt_<authuser>` slot as a side effect — the
+        // cross-origin/credential-less restores (`/sso/exchange`, the IdP
+        // `/auth/silent` postMessage) cannot set an `api.oxy.so` cookie. WITHOUT this
+        // call those primaries never join the device set, so `refresh-all` returns no
+        // accounts and account-switch persistence has no foundation. The shared
+        // `POST /auth/session` primitive plants/reuses this user's slot where the
+        // cookies ARE visible, re-plants the rotated access token, and returns the
+        // AUTHORITATIVE `authuser` slot (the one actually written) — preferred over the
+        // JWT-decoded guess, which may not correspond to a real cookie. No-op on native
+        // (returns `null`); best-effort on transient failure.
+        const establishedAuthuser = await this.oxyServices.establishDeviceRefreshSlot();
+        // The slot mint rotated the access token; pick it up so the registry and the
+        // refresh authority track the cookie just written. Falls back to the original
+        // session token when the slot was a no-op (native) or failed.
+        const rotatedToken = (establishedAuthuser !== null ? this.oxyServices.getAccessToken() : null) ??
+            session.accessToken;
+        if (rotatedToken) {
+            this._lastKnownAccessToken = rotatedToken;
+        }
+        const decodedAuthuser = rotatedToken
+            ? AuthManager.decodeAuthuserFromAccessToken(rotatedToken)
             : null;
-        const authuser = decodedAuthuser ?? 0;
-        if (session.accessToken && session.sessionId) {
+        const authuser = establishedAuthuser ?? decodedAuthuser ?? 0;
+        if (rotatedToken && session.sessionId) {
             this.accounts.set(authuser, {
                 authuser,
                 sessionId: session.sessionId,
@@ -411,7 +433,7 @@ class AuthManager {
                     name: session.user.name,
                     avatar: session.user.avatar ?? null,
                 },
-                accessToken: session.accessToken,
+                accessToken: rotatedToken,
                 expiresAt: session.expiresAt,
             });
             this.activeAuthuser = authuser;

package/dist/cjs/OxyServices.base.js

@@ -11,6 +11,9 @@ const errorUtils_1 = require("./utils/errorUtils");
 const HttpService_1 = require("./HttpService");
 const OxyServices_errors_1 = require("./OxyServices.errors");
 const authWebUrl_1 = require("./utils/authWebUrl");
+const platform_1 = require("./utils/platform");
+const fapiAutoDetect_1 = require("./utils/fapiAutoDetect");
+const loggerUtils_1 = require("./utils/loggerUtils");
 /**
  * Base class for OxyServices with core infrastructure
  */
@@ -253,6 +256,74 @@ class OxyServicesBase {
     getAccessToken() {
         return this.httpService.getAccessToken();
     }
+    /**
+     * Register the CURRENTLY-ACTIVE session in the device's first-party
+     * multi-account refresh-cookie set by calling `POST /auth/session`.
+     *
+     * This is the single, shared primitive every web primary-session commit and the
+     * account switch use to plant their `oxy_rt_<authuser>` slot. It MUST be a
+     * dedicated call to `/auth/session` rather than relying on whichever endpoint
+     * established the session: that endpoint is frequently OUTSIDE the cookie's
+     * `Path=/auth` scope (`/accounts/:id/switch`) or is a cross-origin/credential-
+     * less restore (`/sso/exchange`, the IdP `/auth/silent` postMessage) that cannot
+     * set an `api.oxy.so` cookie at all. `/auth/session` runs where the device's
+     * existing slots ARE visible, so the server resolves this user's slot (reusing an
+     * existing one or allocating a new one) without clobbering a sibling account,
+     * mints a fresh access token bound to the same session, and returns the resolved
+     * `authuser`.
+     *
+     * Behaviour:
+     * - Requires a planted bearer (the caller must have already installed the
+     *   session's access token); `/auth/session` derives the session from it.
+     * - On success re-plants the rotated access token (so the active token matches
+     *   the freshly-rotated cookie) and returns the device `authuser` slot.
+     * - WEB-ONLY: on native there are no first-party refresh cookies → returns
+     *   `null`.
+     * - FIRST-PARTY-ONLY: the cookie is host-only on the API host with
+     *   `SameSite=Lax`, so it only sticks when the page is SAME-SITE (same
+     *   registrable apex) as the API. On a cross-apex RP (`mention.earth` calling
+     *   `api.oxy.so`) the browser rejects the `Set-Cookie` as a third-party cookie,
+     *   so a returned slot would be a phantom never enumerated by `refresh-all`.
+     *   Those RPs durably restore via the per-apex `/auth/silent` iframe + `/sso`
+     *   bounce, NOT this device set → returns `null` without calling the API.
+     * - BEST-EFFORT: a failure (e.g. transient network) never throws — the session
+     *   stays active in-memory; only its reload durability via the device set is at
+     *   risk. The caller treats `null` as "not registered in the device set".
+     *
+     * @returns The resolved device `authuser` slot, or `null` on native / cross-apex
+     *   / failure.
+     */
+    async establishDeviceRefreshSlot() {
+        if (!(0, platform_1.isWeb)()) {
+            return null;
+        }
+        if (typeof window !== 'undefined' && window.location?.hostname) {
+            const pageApex = (0, fapiAutoDetect_1.registrableApex)(window.location.hostname);
+            let apiApex = null;
+            try {
+                apiApex = (0, fapiAutoDetect_1.registrableApex)(new URL(this.getBaseURL()).hostname);
+            }
+            catch {
+                apiApex = null;
+            }
+            if (!pageApex || !apiApex || pageApex !== apiApex) {
+                return null;
+            }
+        }
+        try {
+            const established = await this.makeRequest('POST', '/auth/session', undefined, { cache: false });
+            // `/auth/session` mints a fresh access token off the same session; re-plant
+            // it so the active token matches the rotated cookie.
+            if (established?.accessToken) {
+                this.setTokens(established.accessToken);
+            }
+            return typeof established?.authuser === 'number' ? established.authuser : null;
+        }
+        catch (error) {
+            loggerUtils_1.logger.warn('[OxyServices] Failed to establish device refresh cookie via POST /auth/session; the session is active in-session but may not survive a reload as part of the device account set', { component: 'OxyServices', method: 'establishDeviceRefreshSlot' }, error);
+            return null;
+        }
+    }
     /**
      * Decode the current access token and return its `exp` claim in SECONDS since
      * the Unix epoch (the raw JWT `exp` unit), or `null` when there is no token,

package/dist/cjs/index.js

@@ -21,7 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.isRTLLocale = exports.normalizeLanguageCode = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.RecoveryPhraseService = exports.SignatureService = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.verifyPublicCardAttestation = exports.parseAttestPayload = exports.parseIdPayload = exports.buildUserDid = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.OxyAppDataIdentifierError = exports.ServiceCredentialMismatchError = exports.createCrossDomainAuth = exports.CrossDomainAuth = exports.createAuthManager = exports.AuthManager = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyServices = void 0;
 exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.translate = exports.createDebugLogger = exports.debugError = exports.debugWarn = exports.debugLog = exports.isDev = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isAndroid = void 0;
 exports.ssoPriorSessionKey = exports.ssoAttemptedKey = exports.ssoNoSessionKey = exports.ssoDestKey = exports.ssoGuardKey = exports.ssoStateKey = exports.SSO_GUARD_TTL_MS = exports.SSO_CALLBACK_PATH = exports.generateSsoState = exports.consumeSsoReturn = exports.parseSsoReturnFragment = exports.resolveCentralAuthUrl = exports.CENTRAL_IDP_APEX = exports.CENTRAL_AUTH_URL = exports.registrableApex = exports.autoDetectAuthWebUrl = exports.getAccountColor = exports.mergeAccountsFromRefreshAll = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = void 0;
-exports.packageInfo = exports.runColdBoot = exports.allowSsoBounce = exports.guardActive = exports.isCentralIdPOrigin = exports.buildSsoBounceUrl = exports.getSsoCallbackBootstrapScript = exports.ssoNavigate = exports.ssoCallbackBootstrapKey = void 0;
+exports.packageInfo = exports.runColdBoot = exports.allowSsoBounce = exports.silentRestoreSuppressed = exports.guardActive = exports.isCentralIdPOrigin = exports.buildSsoBounceUrl = exports.getSsoCallbackBootstrapScript = exports.ssoNavigate = exports.ssoCallbackBootstrapKey = exports.ssoSignedOutKey = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -284,12 +284,14 @@ Object.defineProperty(exports, "ssoDestKey", { enumerable: true, get: function (
 Object.defineProperty(exports, "ssoNoSessionKey", { enumerable: true, get: function () { return ssoBounce_1.ssoNoSessionKey; } });
 Object.defineProperty(exports, "ssoAttemptedKey", { enumerable: true, get: function () { return ssoBounce_1.ssoAttemptedKey; } });
 Object.defineProperty(exports, "ssoPriorSessionKey", { enumerable: true, get: function () { return ssoBounce_1.ssoPriorSessionKey; } });
+Object.defineProperty(exports, "ssoSignedOutKey", { enumerable: true, get: function () { return ssoBounce_1.ssoSignedOutKey; } });
 Object.defineProperty(exports, "ssoCallbackBootstrapKey", { enumerable: true, get: function () { return ssoBounce_1.ssoCallbackBootstrapKey; } });
 Object.defineProperty(exports, "ssoNavigate", { enumerable: true, get: function () { return ssoBounce_1.ssoNavigate; } });
 Object.defineProperty(exports, "getSsoCallbackBootstrapScript", { enumerable: true, get: function () { return ssoBounce_1.getSsoCallbackBootstrapScript; } });
 Object.defineProperty(exports, "buildSsoBounceUrl", { enumerable: true, get: function () { return ssoBounce_1.buildSsoBounceUrl; } });
 Object.defineProperty(exports, "isCentralIdPOrigin", { enumerable: true, get: function () { return ssoBounce_1.isCentralIdPOrigin; } });
 Object.defineProperty(exports, "guardActive", { enumerable: true, get: function () { return ssoBounce_1.guardActive; } });
+Object.defineProperty(exports, "silentRestoreSuppressed", { enumerable: true, get: function () { return ssoBounce_1.silentRestoreSuppressed; } });
 Object.defineProperty(exports, "allowSsoBounce", { enumerable: true, get: function () { return ssoBounce_1.allowSsoBounce; } });
 var coldBoot_1 = require("./utils/coldBoot");
 Object.defineProperty(exports, "runColdBoot", { enumerable: true, get: function () { return coldBoot_1.runColdBoot; } });

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

@@ -2,8 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OxyServicesAccountsMixin = OxyServicesAccountsMixin;
 const userIdentity_1 = require("../utils/userIdentity");
-const platform_1 = require("../utils/platform");
-const loggerUtils_1 = require("../utils/loggerUtils");
 const mixinHelpers_1 = require("./mixinHelpers");
 function OxyServicesAccountsMixin(Base) {
     return class extends Base {
@@ -94,29 +92,16 @@ function OxyServicesAccountsMixin(Base) {
                 }
                 // Register the switched session in the device's multi-account set by
                 // establishing its first-party refresh cookie. This MUST be a separate
-                // call to `POST /auth/session`: the switch route is at `/accounts/*`,
-                // outside the `oxy_rt_<authuser>` cookie's `Path=/auth` scope, so it can
-                // never read the device's existing slots and would overwrite slot 0
-                // (destroying the operator's own session). `/auth/session` runs where the
-                // cookies ARE visible, so the server allocates a NEW slot that coexists
-                // with the operator's and returns its `authuser`. Web-only; best-effort.
-                let authuser = res.authuser;
-                if ((0, platform_1.isWeb)()) {
-                    try {
-                        const established = await this.makeRequest('POST', '/auth/session', undefined, { cache: false });
-                        if (typeof established?.authuser === 'number') {
-                            authuser = established.authuser;
-                        }
-                        // /auth/session mints a fresh access token off the same session;
-                        // re-plant it so the active token matches the rotated cookie.
-                        if (established?.accessToken) {
-                            this.setTokens(established.accessToken);
-                        }
-                    }
-                    catch (error) {
-                        loggerUtils_1.logger.warn('[OxyServices] Failed to establish device refresh cookie after account switch; the switch is active in-session but may not survive a reload', { component: 'OxyServices', method: 'switchToAccount' }, error);
-                    }
-                }
+                // call to `POST /auth/session` (the shared `establishDeviceRefreshSlot`
+                // primitive): the switch route is at `/accounts/*`, outside the
+                // `oxy_rt_<authuser>` cookie's `Path=/auth` scope, so it can never read
+                // the device's existing slots and would overwrite slot 0 (destroying the
+                // operator's own session). `/auth/session` runs where the cookies ARE
+                // visible, so the server allocates a NEW slot that coexists with the
+                // operator's and returns its `authuser`. Web-only; best-effort (the helper
+                // re-plants the rotated access token and returns `null` on native/failure).
+                const establishedAuthuser = await this.establishDeviceRefreshSlot();
+                const authuser = establishedAuthuser ?? res.authuser;
                 // Identity changed → drop the entire GET response cache so no entry
                 // personalised for the previous identity is reused. Cache keys are
                 // identity-scoped, so a different identity could not READ the old

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

@@ -11,6 +11,19 @@ const errorUtils_1 = require("../utils/errorUtils");
  * `getUsersByIds`'s `USERS_BY_IDS_CHUNK_SIZE`.
  */
 const SERVICE_ASSET_METADATA_CHUNK_SIZE = 100;
+/**
+ * Maximum number of content hashes sent per `POST /assets/service/by-sha256`
+ * request. Matches the server-side cap (the route rejects empty or > 100 hash
+ * arrays with a 400); larger inputs are chunked and merged. Same ceiling as
+ * {@link SERVICE_ASSET_METADATA_CHUNK_SIZE} for the forward id lookup.
+ */
+const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
+/**
+ * Lowercase hex SHA-256 digest matcher (exactly 64 hex chars). The reverse
+ * lookup drops non-conforming hashes client-side so a single malformed value
+ * never 400s an otherwise-valid chunk on the server.
+ */
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
 function OxyServicesAssetsMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -213,6 +226,69 @@ function OxyServicesAssetsMixin(Base) {
             }));
             return settled.flat();
         }
+        /**
+         * Reverse content-address lookup: resolve many content `sha256` digests to
+         * the servable Oxy asset holding each, in one round-trip per chunk via
+         * `POST /assets/service/by-sha256` (body `{ sha256s }`).
+         *
+         * This is the INVERSE of {@link getServiceAssetMetadataByIds}: given a
+         * record's `blob.sha256`, it returns the asset's `id`, `mime`, byte `size`,
+         * `status`, and — for active, public, CDN-reachable assets only — a public
+         * `url` (`cloud.oxy.so`). Built for server-to-server callers (e.g. Mention's
+         * MTN materializer / node-blob sync) that hold a content hash and need to
+         * map it back to a servable asset. Hashes are lowercased, validated against
+         * a 64-char hex pattern (malformed entries dropped client-side), and
+         * deduplicated before being split into chunks of
+         * {@link SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE} (the server-side cap). The
+         * server omits unknown/deleted hashes from each chunk's `data`, so the
+         * merged result may be shorter than the requested list and the caller is
+         * expected to map by `sha256`.
+         *
+         * **Service-token auth (required).** `/assets/service/by-sha256` is guarded
+         * by `serviceAuthMiddleware` + the `files:read` scope and is called via
+         * `makeServiceRequest` (`Authorization: Bearer <serviceToken>`, `cache:false`).
+         * The calling client MUST be service-configured (`configureServiceAuth`)
+         * before invoking; a plain user-session request is rejected by the route's
+         * service-auth guard.
+         *
+         * Resilience: chunks are independent. A failed chunk is logged and skipped —
+         * every entry that resolved is still returned. An empty input (or one whose
+         * every value is malformed) resolves immediately with `[]` and performs no
+         * network call.
+         *
+         * Not cached at the SDK layer: it's a POST keyed on a multi-hash body (low
+         * hit rate), mirroring the sibling service/POST methods which never cache.
+         */
+        async getServiceAssetMetadataBySha256(sha256s) {
+            const uniqueShas = Array.from(new Set(sha256s
+                .filter((sha) => typeof sha === 'string')
+                .map((sha) => sha.trim().toLowerCase())
+                .filter((sha) => SHA256_HEX_PATTERN.test(sha))));
+            if (uniqueShas.length === 0) {
+                return [];
+            }
+            const chunks = [];
+            for (let i = 0; i < uniqueShas.length; i += SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE) {
+                chunks.push(uniqueShas.slice(i, i + SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE));
+            }
+            // Run chunks concurrently; a single chunk failure must not sink the rest.
+            const settled = await Promise.all(chunks.map(async (chunk) => {
+                try {
+                    const entries = await this.makeServiceRequest('POST', '/assets/service/by-sha256', { sha256s: chunk });
+                    return Array.isArray(entries) ? entries : [];
+                }
+                catch (error) {
+                    loggerUtils_1.logger.warn('getServiceAssetMetadataBySha256: chunk failed, continuing with remaining chunks', {
+                        method: 'getServiceAssetMetadataBySha256',
+                        chunkSize: chunk.length,
+                        status: (0, errorUtils_1.extractErrorStatus)(error),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    return [];
+                }
+            }));
+            return settled.flat();
+        }
         /**
          * Upload raw file data
          */

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

@@ -233,16 +233,28 @@ function OxyServicesUserMixin(Base) {
          * by `id`); each is run through `normalizeUserIdentity`, matching
          * `getUserById`.
          *
-         * **Service-token auth (required).** `/users/by-ids` is a server-to-server
-         * bulk fetch of PUBLIC user data and is called via `makeServiceRequest`,
-         * which attaches `Authorization: Bearer <serviceToken>`. oxy-api's CSRF
-         * middleware skips bearer-authenticated requests, so the calling client
-         * MUST be service-configured (`configureServiceAuth(apiKey, apiSecret)`)
-         * before invoking this method; otherwise `getServiceToken()` throws because
-         * no credentials are available. (A plain user-session request fails here:
-         * server-to-server there is no cookie jar, so the auto-attached
-         * `X-CSRF-Token` has no matching cookie and oxy-api rejects the POST with
-         * 403 "CSRF token missing".)
+         * **Dual-mode auth.** `/users/by-ids` is `optionalUserOrServiceAuth` on
+         * oxy-api: it accepts a service token, a user session, or an anonymous
+         * caller, and returns the SAME public `{ data: PublicUserProfile[] }`
+         * payload (canonical `name.displayName` + `_count`) in every case — no
+         * viewer-specific fields. This method picks the path automatically:
+         * - **Service-configured host (backend):** when `configureServiceAuth(apiKey,
+         *   apiSecret)` has been called, the chunk is fetched via `makeServiceRequest`
+         *   (attaches `Authorization: Bearer <serviceToken>`). This is the
+         *   server-to-server feed/notification hydration path (e.g. Mention's
+         *   `PostHydrationService`) and is unchanged.
+         * - **Plain client (browser / React Native with a user session):** when no
+         *   service credentials are configured, the chunk is fetched via
+         *   `makeRequest`, which attaches the configured user bearer. oxy-api's CSRF
+         *   middleware skips bearer-authenticated writes, and `makeRequest` only
+         *   fetches a CSRF token for cookie-only (no-bearer) state-changing requests,
+         *   so the user-bearer POST is sent without CSRF and succeeds. Previously
+         *   this method always used the service path, so every client-side caller
+         *   silently received `[]` because `getServiceToken()` had no credentials.
+         *
+         * Both paths run results through `normalizeUserIdentity` and unwrap the
+         * API's `{ data }` envelope identically (`makeServiceRequest` is literally
+         * `makeRequest` plus a bearer service header).
          *
          * Resilience: chunks are independent. A failed chunk is logged and skipped
          * — the method returns every user that resolved successfully rather than
@@ -261,15 +273,22 @@ function OxyServicesUserMixin(Base) {
             for (let i = 0; i < uniqueIds.length; i += USERS_BY_IDS_CHUNK_SIZE) {
                 chunks.push(uniqueIds.slice(i, i + USERS_BY_IDS_CHUNK_SIZE));
             }
+            // A backend that called configureServiceAuth() uses the bearer-service
+            // path; any other caller (browser / RN with a user session) uses the
+            // user-bearer path. See the method doc for why the user path is CSRF-safe.
+            const useServiceAuth = Boolean(this._serviceApiKey && this._serviceApiSecret);
             // Run chunks concurrently; a single chunk failure must not sink the rest.
             const settled = await Promise.all(chunks.map(async (chunk) => {
                 try {
-                    const users = await this.makeServiceRequest('POST', '/users/by-ids', { ids: chunk });
+                    const users = useServiceAuth
+                        ? await this.makeServiceRequest('POST', '/users/by-ids', { ids: chunk })
+                        : await this.makeRequest('POST', '/users/by-ids', { ids: chunk }, { cache: false });
                     return Array.isArray(users) ? users.map((user) => (0, userIdentity_1.normalizeUserIdentity)(user)) : [];
                 }
                 catch (error) {
                     loggerUtils_1.logger.warn('getUsersByIds: chunk failed, continuing with remaining chunks', {
                         method: 'getUsersByIds',
+                        mode: useServiceAuth ? 'service' : 'user',
                         chunkSize: chunk.length,
                         status: (0, errorUtils_1.extractErrorStatus)(error),
                         error: error instanceof Error ? error.message : String(error),

package/dist/cjs/utils/ssoBounce.js

@@ -50,12 +50,14 @@ exports.ssoDestKey = ssoDestKey;
 exports.ssoNoSessionKey = ssoNoSessionKey;
 exports.ssoAttemptedKey = ssoAttemptedKey;
 exports.ssoPriorSessionKey = ssoPriorSessionKey;
+exports.ssoSignedOutKey = ssoSignedOutKey;
 exports.ssoCallbackBootstrapKey = ssoCallbackBootstrapKey;
 exports.getSsoCallbackBootstrapScript = getSsoCallbackBootstrapScript;
 exports.ssoNavigate = ssoNavigate;
 exports.buildSsoBounceUrl = buildSsoBounceUrl;
 exports.isCentralIdPOrigin = isCentralIdPOrigin;
 exports.guardActive = guardActive;
+exports.silentRestoreSuppressed = silentRestoreSuppressed;
 exports.allowSsoBounce = allowSsoBounce;
 const authWebUrl_1 = require("./authWebUrl");
 /**
@@ -81,6 +83,7 @@ const NO_SESSION_KEY_PREFIX = 'oxy_sso_no_session:';
 const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
 const CALLBACK_BOOTSTRAP_KEY_PREFIX = 'oxy_sso_callback_bootstrap:';
 const PRIOR_SESSION_KEY_PREFIX = 'oxy_sso_prior_session:';
+const SIGNED_OUT_KEY_PREFIX = 'oxy_signed_out:';
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 function ssoStateKey(origin) {
     return `${STATE_KEY_PREFIX}${origin}`;
@@ -130,6 +133,36 @@ function ssoAttemptedKey(origin) {
 function ssoPriorSessionKey(origin) {
     return `${PRIOR_SESSION_KEY_PREFIX}${origin}`;
 }
+/**
+ * Per-origin DURABLE "the user DELIBERATELY signed out on this device/origin"
+ * flag.
+ *
+ * Like {@link ssoPriorSessionKey} this lives in DURABLE storage (web
+ * `localStorage`; services uses its own `storageKeyPrefix`-scoped key), NOT the
+ * per-tab `sessionStorage` the loop-breaker keys use — it must survive a reload.
+ *
+ * It exists purely to suppress AUTOMATIC silent restore after a deliberate
+ * sign-out: a still-live IdP session (the central `fedcm_session` / the FedCM
+ * credential association) would otherwise let `fedcm-silent` / the per-apex
+ * `/auth/silent` iframe re-mint a session on the very next cold boot, so a user
+ * who pressed "Sign out" gets silently signed back in on reload. With this flag
+ * set, those silent cold-boot steps are skipped while the Gmail-style
+ * returning-account fast-path is otherwise preserved.
+ *
+ * Lifecycle (mirrors the existing gate machinery — set on a definitive event,
+ * cleared on its inverse):
+ *   - SET on EXPLICIT full sign-out (alongside clearing the prior-session hint
+ *     and the SSO bounce state).
+ *   - CLEARED on ANY deliberate sign-in (password, FedCM, account switch, device
+ *     claim) so a real sign-in fully re-enables silent restore — there is no
+ *     "stuck signed out" state.
+ *
+ * NOTE: this gates only AUTOMATIC/silent restore. An INTERACTIVE sign-in always
+ * clears it first, so the user can always sign back in.
+ */
+function ssoSignedOutKey(origin) {
+    return `${SIGNED_OUT_KEY_PREFIX}${origin}`;
+}
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *
@@ -260,6 +293,32 @@ function guardActive(storage, origin, now = Date.now()) {
     }
     return now - ts < exports.SSO_GUARD_TTL_MS;
 }
+/**
+ * Whether AUTOMATIC silent restore is SUPPRESSED for this origin because the
+ * user deliberately signed out (the durable {@link ssoSignedOutKey} flag).
+ *
+ * When `true`, the silent cold-boot steps that can re-mint a session from a
+ * still-live IdP session WITHOUT user intent — `fedcm-silent` and the per-apex
+ * `/auth/silent` iframe — MUST be skipped, so a user who pressed "Sign out" is
+ * not silently signed back in on the next reload. Interactive sign-in clears the
+ * flag, so this never blocks a deliberate re-sign-in.
+ *
+ * Defensive: a `getItem` that throws (locked/disabled storage) is treated as NOT
+ * suppressed, so the gate fails toward the normal restore behaviour rather than
+ * wedging the user out.
+ *
+ * @param storage - The DURABLE storage to read (web `localStorage`; injected for
+ *   testability).
+ * @param origin - The page origin whose signed-out flag to evaluate.
+ */
+function silentRestoreSuppressed(storage, origin) {
+    try {
+        return storage.getItem(ssoSignedOutKey(origin)) === '1';
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Decide whether the terminal `/sso` establish-bounce is ALLOWED for this
  * visitor (the smart `enabled` gate for the `sso-bounce` cold-boot step).