@oxyhq/core 5.5.0 → 6.0.0

package/dist/types/session/SessionClient.d.ts

@@ -16,6 +16,16 @@ export interface SessionClientHost {
 }
 export interface SessionClientOptions {
     transport?: TokenTransport;
+    /**
+     * Invoked when an APPLIED state has zero accounts — i.e. a device
+     * signout-all removed the last account from this device set. Providers use
+     * this to clear the persisted {@link AuthStateStore} so a reload does not
+     * try to restore a session that no longer exists on the device.
+     *
+     * Only fires when a state is actually applied (revision advanced), never on
+     * a stale/rejected push. Exceptions thrown by the callback are isolated.
+     */
+    onUnauthenticated?: () => void;
     /**
      * Statically-injected `socket.io-client` factory (its `io` export).
      * `@oxyhq/services` and `@oxyhq/auth` list `socket.io-client` as a real
@@ -60,6 +70,21 @@ export declare class SessionClient {
         all: true;
     }): Promise<void>;
     addCurrentAccount(): Promise<void>;
+    /**
+     * Register the just-signed-in account into the device set AND make it the
+     * ACTIVE account — the explicit user-intent activation a sign-in UI performs.
+     *
+     * `addCurrentAccount` alone honors the server's `activate:'if-empty'` policy
+     * (a new account does NOT steal focus from an already-active one), which is
+     * correct for a background/silent add but wrong right after a deliberate
+     * sign-in. This adds, then switches to the target so the UI lands on the
+     * account the user just authenticated.
+     *
+     * @param accountId - The signed-in account id (e.g. `session.user.id`). When
+     *   omitted, falls back to the host's current-account ref. If neither
+     *   resolves, the add still applies and no switch is performed.
+     */
+    registerAndActivate(accountId?: string): Promise<void>;
     start(): Promise<void>;
     stop(): void;
     private connectSocket;

package/dist/types/session/authStateStore.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Persisted auth state — ONE shape, web + native.
+ *
+ * The device-first session model (auth-centralization wave 1) persists the
+ * rotating refresh-token family head per ORIGIN so a reload restores the
+ * session locally without a redirect. This module is the storage seam: a tiny
+ * `load / save / clear` interface plus platform factories, so the cold boot
+ * (`coldBootV2`) and the unified refresh handler (`refresh.ts`) never touch a
+ * platform storage API directly.
+ *
+ * Platform-agnostic — the native factory takes an INJECTED key/value store
+ * (`@oxyhq/services` passes a SecureStore-backed adapter) so `@oxyhq/core`
+ * never imports `expo-secure-store`. The web factory is self-contained
+ * (`localStorage`) and degrades to in-memory when storage is unavailable
+ * (sandboxed iframe `SecurityError`, private-mode quota, SSR).
+ *
+ * ESM-safe (no `require()`).
+ */
+/**
+ * The persisted session credential set for a single origin.
+ *
+ * `refreshToken` is the rotating single-use family head; `sessionId` + `userId`
+ * identify the owning device session and account. `deviceToken` is the opaque,
+ * add-only device attribution token (mirrored to the shared keychain on native
+ * so every Oxy app on one phone shares one DeviceSession).
+ *
+ * `accessToken` + `expiresAt` are OPTIONAL warm-boot fields. Persisting them
+ * lets the cold boot plant a still-valid access token on the very first paint
+ * WITHOUT a blocking `/auth/refresh-token` round-trip — the proactive scheduler
+ * then rotates it in the background. They are a strict optimization: the store
+ * is fully functional (via `refreshToken`) when they are absent or stale, and
+ * the access token is short-lived, so persisting it adds no exposure the
+ * already-persisted refresh token does not (see the plan's XSS risk note — the
+ * refresh token is the dominant secret either way).
+ */
+export interface PersistedAuthState {
+    sessionId: string;
+    refreshToken: string;
+    userId: string;
+    deviceToken?: string;
+    /** Optional warm-boot access token (short-lived; see interface docs). */
+    accessToken?: string;
+    /** Optional warm-boot access-token expiry, ISO-8601. */
+    expiresAt?: string;
+}
+/**
+ * The storage seam consumed by the cold boot and the refresh handler. Async
+ * throughout so one interface fits both synchronous web `localStorage` and
+ * asynchronous native SecureStore/AsyncStorage.
+ *
+ * Two lifetimes:
+ *  - The SESSION credential blob (`load`/`save`/`clear`) is per-sign-in and is
+ *    wiped on `clear()` (sign-out).
+ *  - The DEVICE token (`loadDeviceToken`/`saveDeviceToken`/`clearDeviceToken`)
+ *    is long-lived device attribution that SURVIVES `clear()`: a signed-out
+ *    browser is still the same device, and a later in-app (cross-apex,
+ *    cookie-less) login sends this token so the new session joins the SAME
+ *    server-side DeviceSession. Only an explicit device signout-all
+ *    (`clearDeviceToken`) removes it.
+ */
+export interface AuthStateStore {
+    load(): Promise<PersistedAuthState | null>;
+    save(state: PersistedAuthState): Promise<void>;
+    clear(): Promise<void>;
+    loadDeviceToken(): Promise<string | null>;
+    saveDeviceToken(token: string): Promise<void>;
+    clearDeviceToken(): Promise<void>;
+}
+/**
+ * The minimal async key/value surface a native store must provide. Matches
+ * both `expo-secure-store` (wrapped) and `@react-native-async-storage`.
+ */
+export interface NativeKeyValueStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * Versioned storage key. The `.v1` suffix lets a future shape change ship a
+ * `.v2` key without reading a stale/incompatible `.v1` blob. Distinct from the
+ * `oxy_shared_*` keychain keys in `KeyManager`, so it never collides.
+ */
+export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
+/**
+ * Storage key for the long-lived device-attribution token. Separate from
+ * {@link AUTH_STATE_STORAGE_KEY} because it must OUTLIVE a session `clear()`
+ * (sign-out) — the device is unchanged across sign-ins.
+ */
+export declare const DEVICE_TOKEN_STORAGE_KEY = "oxy.device.v1";
+/**
+ * A process-lifetime, in-memory {@link AuthStateStore}. Used directly for
+ * tests/SSR and as the degraded fallback of the web store when `localStorage`
+ * is unreachable. Not durable across reloads — that is acceptable for the
+ * fallback because the alternative (throwing) would break cold boot entirely.
+ */
+export declare function createMemoryAuthStateStore(): AuthStateStore;
+/**
+ * A `localStorage`-backed {@link AuthStateStore} under the versioned
+ * {@link AUTH_STATE_STORAGE_KEY}.
+ *
+ * Resilience:
+ *  - If `localStorage` is unreachable (sandboxed-iframe `SecurityError`, SSR),
+ *    the whole store degrades to an in-memory {@link createMemoryAuthStateStore}
+ *    for this page's lifetime — never throws on construction.
+ *  - Individual `getItem`/`setItem`/`removeItem` are each wrapped: a read that
+ *    throws yields `null`; a write that throws (quota, private mode) is
+ *    swallowed. The persisted-refresh lane treats a failed persist as "no
+ *    durable state" (falls back to the bootstrap hop) rather than crashing.
+ */
+export declare function createWebAuthStateStore(): AuthStateStore;
+/**
+ * A native {@link AuthStateStore} over an injected async key/value store.
+ *
+ * `@oxyhq/core` never imports `expo-secure-store`; `@oxyhq/services` constructs
+ * the SecureStore-backed adapter and passes it here. Every operation is wrapped
+ * so a storage exception degrades gracefully (read → `null`, write → swallowed)
+ * exactly like the web store.
+ */
+export declare function createNativeAuthStateStore(storage: NativeKeyValueStorage): AuthStateStore;

package/dist/types/session/refresh.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Unified token refresh — THE single refresh implementation for web + native.
+ *
+ * Before device-first, refresh was duplicated: `@oxyhq/auth`'s
+ * `session/tokenRefresh.ts` (per-apex `/auth/silent` iframe) and
+ * `@oxyhq/services`'s `inSessionTokenRefresh.ts` (native shared-key). This
+ * module replaces both with ONE persisted-refresh-token rotation shared by
+ * every consumer:
+ *
+ *  - `refreshPersistedSession` — arm 1 rotates the stored refresh-token family
+ *    (`POST /auth/refresh-token`), planting + persisting the rotated pair; arm 2
+ *    (native only) re-mints via the shared-keychain identity when there is no
+ *    live refresh token. It is used BOTH reactively (wrapped as the
+ *    `AuthRefreshHandler` installed on `HttpService`) AND proactively (the
+ *    cold-boot `stored-tokens` step calls it directly).
+ *  - `createAuthRefreshHandler` / `installAuthRefreshHandler` wire arm 1+2 into
+ *    `HttpService.setAuthRefreshHandler`, keeping that layer's single-flight
+ *    dedup + cooldown (this module does NOT reimplement them).
+ *  - `startTokenRefreshScheduler` — a proactive scheduler (lifted from the
+ *    better of the two prior duplicates, `@oxyhq/auth`'s `tokenRefresh.ts`),
+ *    decoupled from any React / auth-sdk type: refreshes ~60s before `exp`,
+ *    re-arms on token change + web tab-focus, `.unref?.()`s its timer in Node.
+ *
+ * Framework-free; no module-level mutable state.
+ */
+import type { OxyServices } from '../OxyServices';
+import type { AuthRefreshHandler } from '../HttpService';
+import type { AuthStateStore } from './authStateStore';
+/**
+ * Lead time (ms) before access-token expiry at which the proactive scheduler
+ * refreshes. Mirrors `HttpService`'s per-request `TOKEN_REFRESH_LEAD_SECONDS`
+ * (60s) so the scheduled refresh and the request-time preflight refresh use
+ * the same window — the scheduler just fires it during idle/background.
+ */
+export declare const TOKEN_REFRESH_LEAD_MS = 60000;
+export interface RefreshDeps {
+    oxy: OxyServices;
+    store: AuthStateStore;
+    /**
+     * Whether to fall back to the native shared-keychain re-mint (arm 2) when
+     * there is no live refresh token / arm 1 is revoked. Defaults to `isNative()`
+     * — web has no shared keychain. Exposed for tests.
+     */
+    allowSharedKeyFallback?: boolean;
+}
+/**
+ * Rotate the persisted session and return the fresh access token, or `null`
+ * when no arm could produce one.
+ *
+ * Arm 1 (`POST /auth/refresh-token`): if the store holds a refresh token, rotate
+ * it — on success plant + persist the rotated pair; on a REVOKED error clear the
+ * store; on a transient error leave the store and return `null`.
+ *
+ * Arm 2 (native shared-keychain): when there is no refresh token or arm 1 was
+ * revoked, re-mint via `signInWithSharedIdentity` (which plants tokens). The
+ * shared keychain — not the per-origin store — is the durable native credential,
+ * so this arm does not write the store.
+ */
+export declare function refreshPersistedSession(deps: RefreshDeps): Promise<string | null>;
+/**
+ * Build the reactive `AuthRefreshHandler` (arm 1 + arm 2). Install it via
+ * {@link installAuthRefreshHandler} or directly on
+ * `oxy.httpService.setAuthRefreshHandler`. `HttpService` owns single-flight
+ * dedup + cooldown, so the timer, the request-time preflight, and a 401 all
+ * collapse to one network attempt.
+ */
+export declare function createAuthRefreshHandler(deps: RefreshDeps): AuthRefreshHandler;
+/**
+ * Install the unified refresh handler on the owner client's `HttpService`.
+ * Returns a disposer that removes it.
+ */
+export declare function installAuthRefreshHandler(deps: RefreshDeps): () => void;
+/** Handle returned by {@link startTokenRefreshScheduler}; `dispose()` tears it down. */
+export interface TokenRefreshSchedulerHandle {
+    dispose(): void;
+}
+/**
+ * Start the proactive refresh scheduler against `oxy`.
+ *
+ * Schedules a single timer to fire {@link TOKEN_REFRESH_LEAD_MS} before the
+ * current access token's `exp`, calling
+ * `oxy.httpService.refreshAccessToken('preflight')` (which runs the installed
+ * handler; deduped + cooldown-guarded). After every attempt it reschedules
+ * from the possibly-rotated token. It also reschedules whenever the token
+ * changes (a sign-out that clears the token cancels the timer) and, on web
+ * tab-focus, refreshes immediately if already inside the lead window (a
+ * long-hidden tab throttles timers, so the token can be expired on return).
+ *
+ * No-ops cleanly when there is no token or an opaque/no-`exp` token — the
+ * reactive 401 path stays the only refresh trigger in that case. The timer is
+ * `.unref?.()`-ed so it never keeps a Node/Jest event loop alive.
+ */
+export declare function startTokenRefreshScheduler(oxy: OxyServices): TokenRefreshSchedulerHandle;

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

@@ -2,7 +2,6 @@
  * Shared account types and pure helper functions.
  * Used by both @oxyhq/services (React Native) and @oxyhq/auth (Web) account stores.
  */
-import type { RefreshAllAccount } from '../models/interfaces';
 export interface QuickAccount {
     sessionId: string;
     userId?: string;
@@ -94,19 +93,6 @@ export declare const createQuickAccount: (sessionId: string, userData: {
     } | string;
     avatar?: string | null;
 }, existingAccount?: QuickAccount, getFileDownloadUrl?: (fileId: string, variant: string) => string) => QuickAccount;
-/**
- * Merge a fresh `/auth/refresh-all` snapshot into an existing QuickAccount
- * list, preserving any cached fields (`avatarUrl`) for slots that didn't
- * change. The fresh response is canonical: the resulting list contains EXACTLY
- * the slots present in `fresh`, sorted by `authuser` ascending. Stale stored
- * accounts that no longer appear in `fresh` are dropped (the server already
- * authoritatively cleared the corresponding cookie).
- *
- * @param stored Previously persisted QuickAccount list (any order).
- * @param fresh Server's authoritative refresh-all response.
- * @returns Canonical merged list, sorted by `authuser` asc.
- */
-export declare const mergeAccountsFromRefreshAll: (stored: QuickAccount[] | undefined, fresh: RefreshAllAccount[]) => QuickAccount[];
 /**
  * Return the account's preferred Bloom color preset, or `null` if it has no
  * preference. Centralises the `color ?? null` normalisation so consumers can

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

@@ -12,9 +12,11 @@
  * `window`/`location`, and has no side effects. It is the single source of
  * truth for the central IdP origin so call sites never hardcode the literal.
  *
- * Note: this is distinct from `autoDetectAuthWebUrl` (per-apex `auth.<rp-apex>`
- * derivation). The central-SSO path deliberately does NOT auto-detect per-apex
- * IdPs — it is central only. An explicitly-configured `authWebUrl` still wins.
+ * LEGACY(old-sdk): the client resolver (`resolveCentralAuthUrl`) was removed in
+ * the device-first cutover; `CENTRAL_IDP_APEX` / `CENTRAL_AUTH_URL` survive ONLY
+ * because the lista-B IdP worker imports them to brand assertions. Deletable
+ * once Homiio/Allo/Alia/Syra are bumped off the old SDK AND CloudWatch
+ * `/oxy/ecs` shows the `/sso*` + `/fedcm/*` routes quiet — F-final sweep.
  */
 /**
  * The registrable apex (eTLD+1) of the Oxy ecosystem's central Identity
@@ -29,14 +31,6 @@ export declare const CENTRAL_IDP_APEX = "oxy.so";
 /**
  * The canonical central Identity Provider origin for the Oxy ecosystem.
  * No trailing slash. Derived from {@link CENTRAL_IDP_APEX} so the apex and the
- * full origin never drift apart.
+ * full origin never drift apart. The IdP worker imports it to brand assertions.
  */
 export declare const CENTRAL_AUTH_URL = "https://auth.oxy.so";
-/**
- * Resolve the central IdP origin, honouring an explicit override.
- *
- * @param explicit - A caller-supplied auth web URL, or `undefined`/empty to use
- *   the central default. An explicit non-empty value always wins.
- * @returns The explicit value when provided, otherwise {@link CENTRAL_AUTH_URL}.
- */
-export declare function resolveCentralAuthUrl(explicit?: string): string;

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

@@ -1,46 +1,24 @@
 /**
- * Auto-detect the FAPI (IdP) URL from the current browser hostname.
- *
- * This is the canonical cross-domain IdP-resolution primitive for the Oxy
- * ecosystem. Both candidate cross-domain SSO designs derive `auth.<rp-apex>`
- * through this helper; do not fork it.
- *
- * Clerk-style multi-domain SSO depends on the IdP being reachable on a
- * subdomain of the RP's own apex (e.g. `auth.mention.earth` CNAMEd to the
- * central Oxy IdP). That way every FedCM endpoint, the session cookie,
- * and any redirect target are same-site with the RP — the only way
- * to get first-party cookies in Safari ITP and Firefox Total Cookie
- * Protection.
- *
- * This helper computes `https://auth.<rp-apex>` from
- * `window.location.hostname` so a consuming app doesn't have to pass
- * `authWebUrl` explicitly. Returns `undefined` for environments where
- * auto-detection would be wrong:
- *
- *   - SSR / non-browser (no `window`).
- *   - `localhost`, `127.0.0.1`, IPv4/IPv6 literals.
- *   - Hostnames with fewer than two labels.
- *   - Hostnames where a registrable domain cannot be determined from the
- *     Public Suffix List, including private hosted suffixes such as
- *     `github.io`, `pages.dev`, and `netlify.app`.
- *
- * When the page is already loaded ON the IdP itself (`auth.<anything>`),
- * the helper returns the current origin so the SDK keeps everything
- * same-origin instead of hopping to a different IdP host.
- *
- * The IdP backend independently derives `iss`, `provider_urls`, and the
- * `fedcm.json` icon URLs from the request host
- * (`packages/auth/server/index.ts`), so an honest CNAME pair is all that
- * is required for end-to-end FedCM correctness — no per-RP config.
+ * Registrable-apex (eTLD+1) host kernel.
+ *
+ * The client FAPI auto-detection helper (`autoDetectAuthWebUrl`) was removed in
+ * the device-first cutover — the SDK no longer derives a per-apex `auth.<rp>`
+ * IdP host. What survives is the pure registrable-domain kernel, still used by
+ * the api SSO surface, `fedcm.service`, `deviceAuth` (same-apex trust checks),
+ * and the IdP worker (all lista B / server-side). `@oxyhq/core/server`
+ * re-exports it for the api.
+ *
+ * LEGACY(old-sdk): `registrableApex` survives ONLY for the lista-B server/IdP
+ * SSO surface. Deletable once Homiio/Allo/Alia/Syra are bumped off the old SDK
+ * AND CloudWatch `/oxy/ecs` shows the `/sso*` + `/fedcm/*` routes quiet — the
+ * F-final sweep should remove this file then.
  */
 /**
  * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
  * Suffix List, including private hosted suffixes.
  *
- * This is the pure host-handling kernel shared by {@link autoDetectAuthWebUrl}
- * and the IdP worker — it performs NO protocol handling, NO `auth.` prefixing,
- * and builds NO URL. It only answers "what is the registrable domain of this
- * host, or is that undefinable?".
+ * Performs NO protocol handling and builds NO URL — it only answers "what is
+ * the registrable domain of this host, or is that undefinable?".
  *
  * Returns `null` (apex undefinable) for:
  *   - empty input;
@@ -53,4 +31,3 @@
  * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.
  */
 export declare function registrableApex(hostname: string): string | null;
-export declare function autoDetectAuthWebUrl(location?: Pick<Location, 'hostname' | 'protocol'> | undefined): string | undefined;

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

@@ -33,3 +33,17 @@ export declare function isAndroid(): boolean;
  * This allows lazy detection in environments where react-native is available
  */
 export declare function setPlatformOS(os: PlatformOS): void;
+/**
+ * True only in a real web browser (a DOM is present), false on React Native
+ * and Node/SSR.
+ *
+ * Native defines a global `window` but no `document`, so the DOM probe — not a
+ * bare `window` check — is the reliable discriminator. This is the single
+ * source of truth consumed by `@oxyhq/services` and `@oxyhq/auth` (both dropped
+ * their local copies), so every consumer shares the exact same predicate.
+ *
+ * NOTE: this is a live runtime probe (not the cached `getPlatformOS()` verdict)
+ * because it must reflect the actual DOM availability at call time in the
+ * consumer's bundle.
+ */
+export declare function isWebBrowser(): boolean;