@oxyhq/core 5.1.1 → 5.2.0

package/dist/types/OxyServices.base.d.ts

@@ -142,6 +142,44 @@ export declare class OxyServicesBase {
      * Get the raw access token (for constructing anchor URLs when needed)
      */
     getAccessToken(): string | null;
+    /**
+     * 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.
+     */
+    establishDeviceRefreshSlot(): Promise<number | 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/types/index.d.ts

@@ -62,7 +62,7 @@ export { RecoveryPhraseService } from './crypto/recoveryPhrase';
 export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
 export { DeviceManager } from './utils/deviceManager';
 export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
-export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceSession, DeviceSessionsResponse, DeviceSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
+export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceSession, DeviceSessionsResponse, DeviceSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 export { TopicType, TopicSource } from './models/Topic';
 export type { TopicData, TopicTranslation } from './models/Topic';
@@ -93,7 +93,7 @@ export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './uti
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
 export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';
 export { generateSsoState } from './mixins/OxyServices.sso';
-export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, allowSsoBounce, } from './utils/ssoBounce';
+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';
 export type { SsoBounceGate } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';

package/dist/types/mixins/OxyServices.accounts.d.ts

@@ -684,6 +684,7 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.analytics.d.ts

@@ -54,6 +54,7 @@ export declare function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBa
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.appData.d.ts

@@ -90,6 +90,7 @@ export declare function OxyServicesAppDataMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.assets.d.ts

@@ -1,4 +1,4 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, ServiceAssetMetadata } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -90,6 +90,40 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          * rate), mirroring the sibling service/POST methods which never cache.
          */
         getServiceAssetMetadataByIds(ids: string[]): Promise<ServiceAssetMetadata[]>;
+        /**
+         * 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.
+         */
+        getServiceAssetMetadataBySha256(sha256s: string[]): Promise<ServiceAssetMetadataBySha[]>;
         /**
          * Upload raw file data
          */
@@ -175,6 +209,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -569,6 +569,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.civic.d.ts

@@ -492,6 +492,7 @@ export declare function OxyServicesCivicMixin<T extends typeof OxyServicesBase>(
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.connectedApps.d.ts

@@ -147,6 +147,7 @@ export declare function OxyServicesConnectedAppsMixin<T extends typeof OxyServic
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.contacts.d.ts

@@ -82,6 +82,7 @@ export declare function OxyServicesContactsMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.devices.d.ts

@@ -84,6 +84,7 @@ export declare function OxyServicesDevicesMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.features.d.ts

@@ -232,6 +232,7 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.fedcm.d.ts

@@ -286,6 +286,7 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.identity.d.ts

@@ -234,6 +234,7 @@ export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.language.d.ts

@@ -69,6 +69,7 @@ export declare function OxyServicesLanguageMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.links.d.ts

@@ -86,6 +86,7 @@ export declare function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.location.d.ts

@@ -52,6 +52,7 @@ export declare function OxyServicesLocationMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.nodes.d.ts

@@ -180,6 +180,7 @@ export declare function OxyServicesNodesMixin<T extends typeof OxyServicesBase>(
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.payment.d.ts

@@ -99,6 +99,7 @@ export declare function OxyServicesPaymentMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.privacy.d.ts

@@ -128,6 +128,7 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.redirect.d.ts

@@ -71,6 +71,7 @@ export declare function OxyServicesRedirectAuthMixin<T extends typeof OxyService
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.reputation.d.ts

@@ -417,6 +417,7 @@ export declare function OxyServicesReputationMixin<T extends typeof OxyServicesB
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.security.d.ts

@@ -66,6 +66,7 @@ export declare function OxyServicesSecurityMixin<T extends typeof OxyServicesBas
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.silent.d.ts

@@ -109,6 +109,7 @@ export declare function OxyServicesSilentAuthMixin<T extends typeof OxyServicesB
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.sso.d.ts

@@ -94,6 +94,7 @@ export declare function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Ba
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.topics.d.ts

@@ -92,6 +92,7 @@ export declare function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.user.d.ts

@@ -386,6 +386,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -257,6 +257,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
         getCurrentUserId(): string | null;
         hasValidToken(): boolean;
         getAccessToken(): string | null;
+        establishDeviceRefreshSlot(): Promise<number | null>;
         getAccessTokenExpiry(): number | null;
         waitForAuth(timeoutMs?: number): Promise<boolean>;
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {

package/dist/types/models/interfaces.d.ts

@@ -465,6 +465,29 @@ export interface ServiceAssetMetadata {
     size: number;
     status: 'active' | 'trash';
 }
+/**
+ * Reverse-lookup asset metadata returned by `POST /assets/service/by-sha256`.
+ *
+ * Resolves a content-addressed `sha256` digest back to the live Oxy asset that
+ * holds those bytes: its file `id`, MIME type, byte `size`, storage `status`,
+ * and — for active, public, CDN-reachable assets only — a public `url`
+ * (`cloud.oxy.so`). This is the inverse of {@link ServiceAssetMetadata}: it lets
+ * a `files:read`-scoped service-to-server caller (e.g. Mention's MTN materializer
+ * / node-blob sync) turn a record's `blob.sha256` into a servable asset.
+ *
+ * `url` is omitted for private/unlisted assets (and for public assets whose
+ * bytes are not yet CDN-reachable) — those must be streamed through the origin.
+ * Unknown or deleted hashes are omitted from the response (never error the whole
+ * batch), so the result may be shorter than the requested hash list.
+ */
+export interface ServiceAssetMetadataBySha {
+    sha256: string;
+    id: string;
+    mime: string;
+    size: number;
+    status: 'active' | 'trash';
+    url?: string;
+}
 /**
  * Account storage usage (server-side usage, not local AsyncStorage)
  */

package/dist/types/utils/ssoBounce.d.ts

@@ -94,6 +94,34 @@ export declare function ssoAttemptedKey(origin: string): string;
  * IdP, while a truly first-time anonymous visitor is never force-bounced.
  */
 export declare function ssoPriorSessionKey(origin: string): string;
+/**
+ * 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 declare function ssoSignedOutKey(origin: string): string;
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *
@@ -174,6 +202,25 @@ export declare function isCentralIdPOrigin(origin: string): boolean;
  *   `Date.now()`.
  */
 export declare function guardActive(storage: Pick<Storage, 'getItem'>, origin: string, now?: number): boolean;
+/**
+ * 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 declare function silentRestoreSuppressed(storage: Pick<Storage, 'getItem'>, origin: string): boolean;
 /**
  * Inputs to the smart {@link allowSsoBounce} gate.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "5.1.1",
+  "version": "5.2.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/AuthManager.ts

@@ -509,11 +509,35 @@ export class AuthManager {
 
     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,
@@ -523,7 +547,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/src/OxyServices.base.ts

@@ -9,6 +9,9 @@ import { handleHttpError } from './utils/errorUtils';
 import { HttpService, type AuthRefreshReason, type RequestOptions } from './HttpService';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 import { resolveCentralAuthUrl } from './utils/authWebUrl';
+import { isWeb } from './utils/platform';
+import { registrableApex } from './utils/fapiAutoDetect';
+import { logger } from './utils/loggerUtils';
 
 export interface OxyConfig extends OxyConfigBase {
   cloudURL?: string;
@@ -310,6 +313,82 @@ export class OxyServicesBase {
     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.
+   */
+  public async establishDeviceRefreshSlot(): Promise<number | null> {
+    if (!isWeb()) {
+      return null;
+    }
+    if (typeof window !== 'undefined' && window.location?.hostname) {
+      const pageApex = registrableApex(window.location.hostname);
+      let apiApex: string | null = 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<{ accessToken?: string; authuser?: number }>(
+        '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,