@oxyhq/core 5.2.0 → 5.3.0

package/dist/esm/session/projectSessionState.js

@@ -0,0 +1,69 @@
+/**
+ * Pure projection helpers: `DeviceSessionState` (the device-scoped
+ * multi-account session-sync state produced by `SessionClient`) -> the
+ * shapes consumers (`@oxyhq/services`, `@oxyhq/auth`) render today
+ * (`ClientSession[]`, an active session id, an active `User`).
+ *
+ * No I/O. The caller fetches profiles via
+ * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
+ * from the result before calling `deviceStateToClientSessions` /
+ * `activeUserOf`.
+ */
+/**
+ * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
+ *
+ * `DeviceSessionState` carries no per-account `expiresAt` / `lastActive` —
+ * both are set to `state.updatedAt` (converted to an ISO-8601 string; the
+ * wire value is an epoch-ms number) as a provisional value.
+ *
+ * `usersById` is accepted for signature symmetry with `activeUserOf` even
+ * though `ClientSession` only stores `userId` — a session is still
+ * projected for an account whose id is absent from `usersById` (no
+ * placeholder user is fabricated).
+ */
+export function deviceStateToClientSessions(state, usersById) {
+    const provisionalTimestamp = new Date(state.updatedAt).toISOString();
+    return state.accounts.map((account) => ({
+        sessionId: account.sessionId,
+        deviceId: state.deviceId,
+        // provisional: expiresAt/lastActive are not carried on DeviceSessionState
+        expiresAt: provisionalTimestamp,
+        lastActive: provisionalTimestamp,
+        userId: account.accountId,
+        isCurrent: account.accountId === state.activeAccountId,
+        authuser: account.authuser,
+    }));
+}
+/**
+ * The active account's `sessionId`, or `null` when there is no state or no
+ * active account is set.
+ */
+export function activeSessionIdOf(state) {
+    if (state === null || state.activeAccountId === null) {
+        return null;
+    }
+    const activeAccountId = state.activeAccountId;
+    const activeAccount = state.accounts.find((account) => account.accountId === activeAccountId);
+    return activeAccount?.sessionId ?? null;
+}
+/**
+ * The active account's `User`, resolved from `usersById`. `null` when there
+ * is no state, no active account is set, or the active account id is absent
+ * from `usersById`.
+ */
+export function activeUserOf(state, usersById) {
+    if (state === null || state.activeAccountId === null) {
+        return null;
+    }
+    return usersById.get(state.activeAccountId) ?? null;
+}
+/**
+ * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
+ * fetch. `[]` for `null` state.
+ */
+export function accountIdsOf(state) {
+    if (state === null) {
+        return [];
+    }
+    return state.accounts.map((account) => account.accountId);
+}

package/dist/esm/session/sessionClientHost.js

@@ -0,0 +1,27 @@
+/**
+ * Thin `SessionClientHost` adapter over an `OxyServices` instance.
+ *
+ * `SessionClient` is host-agnostic: it only needs a REST + token surface.
+ * `OxyServices` already exposes all of that except `getCurrentAccountId`,
+ * which has no direct equivalent — the adapter holds a mutable ref set by
+ * the caller (`OxyContext` in `@oxyhq/services`, `WebOxyProvider` in
+ * `@oxyhq/auth`) via `setCurrentAccountId`.
+ *
+ * Shared here (rather than duplicated per consumer) because it is entirely
+ * platform-agnostic: every method it calls exists identically on
+ * `OxyServices` regardless of host (web, Expo/RN, Node).
+ */
+export function createSessionClientHost(oxyServices) {
+    let currentAccountId = null;
+    return {
+        makeRequest: (method, url, data, options) => oxyServices.makeRequest(method, url, data, options),
+        getBaseURL: () => oxyServices.getBaseURL(),
+        getAccessToken: () => oxyServices.getAccessToken(),
+        onTokensChanged: (listener) => oxyServices.onTokensChanged(listener),
+        setTokens: (accessToken) => oxyServices.setTokens(accessToken),
+        getCurrentAccountId: () => currentAccountId,
+        setCurrentAccountId: (id) => {
+            currentAccountId = id;
+        },
+    };
+}

package/dist/esm/session/socketLoader.js

@@ -0,0 +1,19 @@
+import { logger } from '../utils/loggerUtils.js';
+let cachedFactory = null;
+let loadAttempted = false;
+export async function getSocketIO() {
+    if (cachedFactory)
+        return cachedFactory;
+    if (loadAttempted)
+        return null;
+    loadAttempted = true;
+    try {
+        const mod = (await import('socket.io-client'));
+        cachedFactory = mod.io ?? mod.default ?? null;
+        return cachedFactory;
+    }
+    catch (error) {
+        logger.warn('[SessionClient] socket.io-client import failed; realtime session sync disabled', { component: 'SessionClient' }, error);
+        return null;
+    }
+}

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

@@ -124,18 +124,18 @@ export function ssoPriorSessionKey(origin) {
  * 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.
+ * sign-out: a still-live IdP session (the central `fedcm_session`) would
+ * otherwise let 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, that silent cold-boot step is
+ * 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
+ *   - CLEARED on ANY deliberate sign-in (password, account switch, device
  *     claim) so a real sign-in fully re-enables silent restore — there is no
  *     "stuck signed out" state.
  *
@@ -279,8 +279,8 @@ export function guardActive(storage, origin, now = Date.now()) {
  * 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
+ * When `true`, the silent cold-boot step that can re-mint a session from a
+ * still-live IdP session WITHOUT user intent — 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.

package/dist/esm/utils/ssoEstablish.js

@@ -0,0 +1,107 @@
+/**
+ * Post-claim durable-session establish hop (web device-flow / "Sign in with
+ * Oxy" QR).
+ *
+ * A WEB device-flow claim (`claimSessionByToken`) plants only IN-MEMORY tokens:
+ * unlike a redirect/FedCM/silent sign-in, it never causes the IdP to plant a
+ * `fedcm_session` cookie. So a reload has nothing to restore from — the
+ * silent-iframe and `/sso` paths find no IdP session and the session is lost.
+ *
+ * This primitive closes that gap. AFTER the claim has committed and the session
+ * has been durably persisted, it performs ONE top-level establish hop through
+ * the RP's own per-apex IdP host (`auth.<rp-apex>`), reusing the EXISTING
+ * `/sso/establish` endpoint: the server mints a short-lived, host+audience-bound
+ * establish-token and returns a fully-formed establish URL; navigating to it
+ * plants the durable first-party `fedcm_session` cookie and bounces back to the
+ * RP callback with an opaque code the standard `sso-return` cold-boot step
+ * exchanges.
+ *
+ * It reuses the SAME per-origin `sessionStorage` bounce contract
+ * (`ssoStateKey` / `ssoGuardKey` / `ssoDestKey`) that {@link buildSsoBounceUrl}
+ * primes for the terminal `/sso` bounce, so the post-bounce `sso-return` step
+ * (`consumeSsoReturn`) validates the CSRF `state`, exchanges the code, and
+ * restores the user's real destination with no extra wiring.
+ *
+ * Contract:
+ *  - WEB only — off-web / native it is a no-op returning `false`.
+ *  - NEVER fires while sitting on the central IdP origin (that would loop the
+ *    IdP against itself).
+ *  - Bounce state is persisted ONLY after the establish-URL request succeeds, so
+ *    a failed request leaves no stale state behind.
+ *  - SINGLE attempt: the caller invokes this exactly once per successful claim.
+ *    On ANY failure it does NOT navigate and returns `false`, leaving the
+ *    committed in-memory session exactly as-is (the user is no worse off than
+ *    before this hop existed).
+ *  - Total: never throws. Failures are reported via {@link deps.onError} only.
+ */
+import { ssoStateKey, ssoGuardKey, ssoDestKey, ssoNavigate, isCentralIdPOrigin, } from './ssoBounce.js';
+import { generateSsoState } from '../mixins/OxyServices.sso.js';
+/**
+ * Perform the post-claim establish hop. Returns `true` when a navigation to the
+ * establish URL was initiated (the document is being torn down and replaced by
+ * the IdP), `false` on every no-op / failure path.
+ *
+ * @param client - The exchange surface (`oxyServices.requestSsoEstablishUrl`).
+ * @param deps - Injectable web seams; see {@link EstablishAfterClaimDeps}.
+ */
+export async function establishIdpSessionAfterClaim(client, deps = {}) {
+    const isWeb = deps.isWeb ??
+        (() => typeof window !== 'undefined' &&
+            typeof window.sessionStorage !== 'undefined');
+    if (!isWeb()) {
+        return false;
+    }
+    const storage = deps.storage ?? window.sessionStorage;
+    const location = deps.location ?? window.location;
+    const navigate = deps.navigate ?? ssoNavigate;
+    const generateState = deps.generateState ?? generateSsoState;
+    const now = deps.now ?? (() => Date.now());
+    const origin = location.origin;
+    // Never establish while sitting on the central IdP itself — that would bounce
+    // the IdP against itself. (The device-flow claim can only happen on an RP.)
+    if (isCentralIdPOrigin(origin)) {
+        return false;
+    }
+    const state = generateState();
+    let establishUrl;
+    try {
+        const result = await client.requestSsoEstablishUrl(origin, state);
+        if (!result ||
+            typeof result.establishUrl !== 'string' ||
+            result.establishUrl.length === 0) {
+            return false;
+        }
+        establishUrl = result.establishUrl;
+        // Defense-in-depth before a TOP-LEVEL navigation: the establish URL is
+        // server-formed, but never follow anything that is not a well-formed https
+        // `/sso/establish` on an `auth.` host. A malformed or unexpected URL aborts
+        // silently (no navigation, no state persisted) — same total/no-throw
+        // contract — rather than navigating the document somewhere unintended.
+        let parsedEstablishUrl;
+        try {
+            parsedEstablishUrl = new URL(establishUrl);
+        }
+        catch {
+            return false;
+        }
+        if (parsedEstablishUrl.protocol !== 'https:' ||
+            parsedEstablishUrl.pathname !== '/sso/establish' ||
+            !parsedEstablishUrl.hostname.toLowerCase().startsWith('auth.')) {
+            return false;
+        }
+        // Persist the bounce state ONLY now that the request has succeeded and the
+        // URL is validated — so a failed/rejected request never leaves stale state
+        // behind. This is the exact contract the terminal `/sso` bounce primes via
+        // `buildSsoBounceUrl`, so the post-bounce `sso-return` step (`consumeSsoReturn`)
+        // validates `state`, exchanges the returned code, and restores the dest.
+        storage.setItem(ssoStateKey(origin), state);
+        storage.setItem(ssoGuardKey(origin), String(now()));
+        storage.setItem(ssoDestKey(origin), location.href);
+    }
+    catch (error) {
+        deps.onError?.(error);
+        return false;
+    }
+    navigate(establishUrl);
+    return true;
+}