@oxyhq/core 5.1.1 → 5.2.1

package/dist/esm/AuthManager.js

@@ -393,11 +393,33 @@ export 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,
@@ -407,7 +429,7 @@ export class AuthManager {
                     name: session.user.name,
                     avatar: session.user.avatar ?? null,
                 },
-                accessToken: session.accessToken,
+                accessToken: rotatedToken,
                 expiresAt: session.expiresAt,
             });
             this.activeAuthuser = authuser;

package/dist/esm/OxyServices.base.js

@@ -8,6 +8,9 @@ import { handleHttpError } from './utils/errorUtils.js';
 import { HttpService } from './HttpService.js';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors.js';
 import { resolveCentralAuthUrl } from './utils/authWebUrl.js';
+import { isWeb } from './utils/platform.js';
+import { registrableApex } from './utils/fapiAutoDetect.js';
+import { logger } from './utils/loggerUtils.js';
 /**
  * Base class for OxyServices with core infrastructure
  */
@@ -250,6 +253,74 @@ export 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 (!isWeb()) {
+            return null;
+        }
+        if (typeof window !== 'undefined' && window.location?.hostname) {
+            const pageApex = registrableApex(window.location.hostname);
+            let apiApex = null;
+            try {
+                apiApex = 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) {
+            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/esm/i18n/locales/ar-SA.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "قائمة الحساب",
         "manage": "إدارة حساب Oxy الخاص بك",
+        "viewProfile": "عرض الملف الشخصي",
         "addAnother": "إضافة حساب آخر",
         "signOutAll": "تسجيل الخروج من جميع الحسابات",
         "open": "قائمة الحساب",

package/dist/esm/i18n/locales/ca-ES.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Menú del compte",
         "manage": "Gestiona el teu compte d'Oxy",
+        "viewProfile": "Mostra el perfil",
         "addAnother": "Afegeix un altre compte",
         "signOutAll": "Tanca la sessió de tots els comptes",
         "open": "Menú del compte",

package/dist/esm/i18n/locales/de-DE.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Kontomenü",
         "manage": "Ihr Oxy-Konto verwalten",
+        "viewProfile": "Profil ansehen",
         "addAnother": "Weiteres Konto hinzufügen",
         "signOutAll": "Von allen Konten abmelden",
         "open": "Kontomenü",

package/dist/esm/i18n/locales/en-US.json

@@ -1555,6 +1555,7 @@
     "accountMenu": {
         "label": "Account menu",
         "manage": "Manage your Oxy Account",
+        "viewProfile": "View profile",
         "addAnother": "Add another account",
         "signOutAll": "Sign out of all accounts",
         "open": "Account menu",

package/dist/esm/i18n/locales/es-ES.json

@@ -1555,6 +1555,7 @@
     "accountMenu": {
         "label": "Menú de cuenta",
         "manage": "Gestiona tu cuenta de Oxy",
+        "viewProfile": "Ver perfil",
         "addAnother": "Añadir otra cuenta",
         "signOutAll": "Cerrar sesión en todas las cuentas",
         "open": "Menú de cuenta",

package/dist/esm/i18n/locales/fr-FR.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Menu du compte",
         "manage": "Gérer votre compte Oxy",
+        "viewProfile": "Voir le profil",
         "addAnother": "Ajouter un autre compte",
         "signOutAll": "Se déconnecter de tous les comptes",
         "open": "Menu du compte",

package/dist/esm/i18n/locales/it-IT.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Menu account",
         "manage": "Gestisci il tuo account Oxy",
+        "viewProfile": "Visualizza profilo",
         "addAnother": "Aggiungi un altro account",
         "signOutAll": "Esci da tutti gli account",
         "open": "Menu account",

package/dist/esm/i18n/locales/ja-JP.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "アカウントメニュー",
         "manage": "Oxy アカウントを管理",
+        "viewProfile": "プロフィールを表示",
         "addAnother": "別のアカウントを追加",
         "signOutAll": "すべてのアカウントからログアウト",
         "open": "アカウントメニュー",

package/dist/esm/i18n/locales/ko-KR.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "계정 메뉴",
         "manage": "Oxy 계정 관리",
+        "viewProfile": "프로필 보기",
         "addAnother": "다른 계정 추가",
         "signOutAll": "모든 계정에서 로그아웃",
         "open": "계정 메뉴",

package/dist/esm/i18n/locales/locales/ar-SA.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "قائمة الحساب",
     "manage": "إدارة حساب Oxy الخاص بك",
+    "viewProfile": "عرض الملف الشخصي",
     "addAnother": "إضافة حساب آخر",
     "signOutAll": "تسجيل الخروج من جميع الحسابات",
     "open": "قائمة الحساب",

package/dist/esm/i18n/locales/locales/ca-ES.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menú del compte",
     "manage": "Gestiona el teu compte d'Oxy",
+    "viewProfile": "Mostra el perfil",
     "addAnother": "Afegeix un altre compte",
     "signOutAll": "Tanca la sessió de tots els comptes",
     "open": "Menú del compte",

package/dist/esm/i18n/locales/locales/de-DE.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Kontomenü",
     "manage": "Ihr Oxy-Konto verwalten",
+    "viewProfile": "Profil ansehen",
     "addAnother": "Weiteres Konto hinzufügen",
     "signOutAll": "Von allen Konten abmelden",
     "open": "Kontomenü",

package/dist/esm/i18n/locales/locales/en-US.json

@@ -1555,6 +1555,7 @@
   "accountMenu": {
     "label": "Account menu",
     "manage": "Manage your Oxy Account",
+    "viewProfile": "View profile",
     "addAnother": "Add another account",
     "signOutAll": "Sign out of all accounts",
     "open": "Account menu",

package/dist/esm/i18n/locales/locales/es-ES.json

@@ -1555,6 +1555,7 @@
   "accountMenu": {
     "label": "Menú de cuenta",
     "manage": "Gestiona tu cuenta de Oxy",
+    "viewProfile": "Ver perfil",
     "addAnother": "Añadir otra cuenta",
     "signOutAll": "Cerrar sesión en todas las cuentas",
     "open": "Menú de cuenta",

package/dist/esm/i18n/locales/locales/fr-FR.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu du compte",
     "manage": "Gérer votre compte Oxy",
+    "viewProfile": "Voir le profil",
     "addAnother": "Ajouter un autre compte",
     "signOutAll": "Se déconnecter de tous les comptes",
     "open": "Menu du compte",

package/dist/esm/i18n/locales/locales/it-IT.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu account",
     "manage": "Gestisci il tuo account Oxy",
+    "viewProfile": "Visualizza profilo",
     "addAnother": "Aggiungi un altro account",
     "signOutAll": "Esci da tutti gli account",
     "open": "Menu account",

package/dist/esm/i18n/locales/locales/ja-JP.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "アカウントメニュー",
     "manage": "Oxy アカウントを管理",
+    "viewProfile": "プロフィールを表示",
     "addAnother": "別のアカウントを追加",
     "signOutAll": "すべてのアカウントからログアウト",
     "open": "アカウントメニュー",

package/dist/esm/i18n/locales/locales/ko-KR.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "계정 메뉴",
     "manage": "Oxy 계정 관리",
+    "viewProfile": "프로필 보기",
     "addAnother": "다른 계정 추가",
     "signOutAll": "모든 계정에서 로그아웃",
     "open": "계정 메뉴",

package/dist/esm/i18n/locales/locales/pt-PT.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu da conta",
     "manage": "Gerir a sua conta Oxy",
+    "viewProfile": "Ver perfil",
     "addAnother": "Adicionar outra conta",
     "signOutAll": "Terminar sessão em todas as contas",
     "open": "Menu da conta",

package/dist/esm/i18n/locales/locales/zh-CN.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "账户菜单",
     "manage": "管理您的 Oxy 账户",
+    "viewProfile": "查看个人资料",
     "addAnother": "添加其他账户",
     "signOutAll": "退出所有账户",
     "open": "账户菜单",

package/dist/esm/i18n/locales/pt-PT.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Menu da conta",
         "manage": "Gerir a sua conta Oxy",
+        "viewProfile": "Ver perfil",
         "addAnother": "Adicionar outra conta",
         "signOutAll": "Terminar sessão em todas as contas",
         "open": "Menu da conta",

package/dist/esm/i18n/locales/zh-CN.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "账户菜单",
         "manage": "管理您的 Oxy 账户",
+        "viewProfile": "查看个人资料",
         "addAnother": "添加其他账户",
         "signOutAll": "退出所有账户",
         "open": "账户菜单",

package/dist/esm/index.js

@@ -127,7 +127,7 @@ export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './uti
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn.js';
 export { generateSsoState } from './mixins/OxyServices.sso.js';
 // SSO bounce — per-origin sessionStorage keys, bounce URL builder, predicates
-export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, allowSsoBounce, } from './utils/ssoBounce.js';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoSignedOutKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, silentRestoreSuppressed, allowSsoBounce, } from './utils/ssoBounce.js';
 export { runColdBoot } from './utils/coldBoot.js';
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every

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

@@ -1,6 +1,4 @@
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
-import { isWeb } from '../utils/platform.js';
-import { logger } from '../utils/loggerUtils.js';
 import { CACHE_TIMES } from './mixinHelpers.js';
 export function OxyServicesAccountsMixin(Base) {
     return class extends Base {
@@ -91,29 +89,16 @@ export 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 (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) {
-                        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/esm/mixins/OxyServices.assets.js

@@ -8,6 +8,19 @@ import { extractErrorStatus } from '../utils/errorUtils.js';
  * `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}$/;
 export function OxyServicesAssetsMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -210,6 +223,69 @@ export 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) {
+                    logger.warn('getServiceAssetMetadataBySha256: chunk failed, continuing with remaining chunks', {
+                        method: 'getServiceAssetMetadataBySha256',
+                        chunkSize: chunk.length,
+                        status: extractErrorStatus(error),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    return [];
+                }
+            }));
+            return settled.flat();
+        }
         /**
          * Upload raw file data
          */

package/dist/esm/utils/cache.js

@@ -198,6 +198,8 @@ export function registerCacheForCleanup(cache) {
                 cache.cleanup();
             }
         }, 60000); // Every minute
+        // Never block process/worker exit on a housekeeping timer.
+        cleanupInterval.unref?.();
     }
 }
 /**

package/dist/esm/utils/ssoBounce.js

@@ -65,6 +65,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). */
 export function ssoStateKey(origin) {
     return `${STATE_KEY_PREFIX}${origin}`;
@@ -114,6 +115,36 @@ export function ssoAttemptedKey(origin) {
 export 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.
+ */
+export function ssoSignedOutKey(origin) {
+    return `${SIGNED_OUT_KEY_PREFIX}${origin}`;
+}
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *
@@ -244,6 +275,32 @@ export function guardActive(storage, origin, now = Date.now()) {
     }
     return now - ts < 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.
+ */
+export 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).