@oxy.so/core 1.0.0

package/dist/esm/session/refresh.js

@@ -0,0 +1,390 @@
+import { establishIdentitySession, resolveIdentityPin } from './identitySession.js';
+import { isNative } from '../utils/platform.js';
+import { extractErrorStatus } from '../utils/errorUtils.js';
+import { logger } from '../logger/index.js';
+/**
+ * Lead time (ms) before access-token expiry at which the proactive scheduler
+ * re-mints. Mirrors `HttpService`'s per-request `TOKEN_REFRESH_LEAD_SECONDS`
+ * (60s) so the scheduled re-mint and the request-time preflight use the same
+ * window — the scheduler just fires it during idle/background.
+ */
+export const TOKEN_REFRESH_LEAD_MS = 60000;
+/**
+ * Max `setTimeout` delay (2^31 − 1 ms, ~24.8 days). A larger delay overflows
+ * the int32 timer field and fires IMMEDIATELY — with a long-TTL token that
+ * turns the reschedule-on-finish loop into a tight busy refresh. Clamp to it.
+ */
+const MAX_TIMEOUT_DELAY_MS = 2147483647;
+/**
+ * Floor (ms) on ANY scheduled delay. An already-expired / in-lead-window token
+ * computes a non-positive `exp − now − lead`; without this floor that becomes
+ * `setTimeout(…, 0)`, and a FAILING re-mint (offline / server error) would
+ * re-arm at 0 in the finally block → a tight 100%-CPU busy loop. The floor
+ * guarantees every re-arm yields the event loop.
+ */
+const MIN_SCHEDULE_DELAY_MS = 1000;
+/**
+ * Backoff schedule (ms) applied when a scheduled re-mint FAILS: first retry
+ * after {@link MIN_FAILURE_BACKOFF_MS}, doubling up to {@link MAX_FAILURE_BACKOFF_MS}.
+ * Reset to 0 on any success or token change. This is what converts the former
+ * zero-delay failure loop into a bounded, backing-off retry.
+ */
+const MIN_FAILURE_BACKOFF_MS = 5000;
+const MAX_FAILURE_BACKOFF_MS = 5 * 60000;
+/**
+ * Arm 1 — the device-secret mint, run under the owning client's PROCESS-WIDE
+ * single-flight (`httpService.runSingleFlightDeviceSecretMint`).
+ *
+ * Concurrent lanes (cold boot, the proactive scheduler, a request-time preflight,
+ * a 401 retry, the socket token transport, or a tab-focus reconcile) must not
+ * each persist a different view of the mint response. Routing EVERY lane through
+ * this one single-flight makes concurrent callers await the SAME in-flight mint
+ * and all receive its result, so the durable store converges on one credential.
+ *
+ * On success it persists `nextDeviceSecret` (read-back-verified) BEFORE planting
+ * the access token; a failed durable persist yields `persist-failed` WITHOUT
+ * planting. This function performs NO store mutation on failure — the caller
+ * applies the drop/clear policy (which differs web vs native) from the returned
+ * status.
+ *
+ * `pin` makes the mint IDENTITY-BOUND: the request carries the pinned
+ * `accountId` (so the server mints that account's token without touching
+ * `activeAccountId`), and the persisted `sessionId`/`userId` are resolved from
+ * the PINNED account entry — never from `state.activeAccountId`, whose drift is
+ * exactly what the pin exists to stop.
+ */
+export async function refreshDeviceSecretArm(deps) {
+    const { oxy, store } = deps;
+    const pin = deps.pin ?? null;
+    return oxy.httpService.runSingleFlightDeviceSecretMint(async () => {
+        const persisted = await store.load();
+        if (!persisted?.deviceId || !persisted?.deviceSecret) {
+            return { status: 'no-secret' };
+        }
+        let mint;
+        try {
+            // Unpinned callers pass NO third argument at all, so the account-mode call
+            // shape (and therefore the request body) is untouched by this feature.
+            mint = pin
+                ? await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret, {
+                    accountId: pin.accountId,
+                })
+                : await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
+        }
+        catch (error) {
+            if (extractErrorStatus(error) === 401) {
+                // Structural read (not `instanceof Error`): the thrown value can be a
+                // plain ApiError-shaped object or come from another realm.
+                const message = error?.message;
+                const body = typeof message === 'string' ? message : '';
+                // ONLY the server's explicit `invalid_device_secret` proves the presented
+                // secret is bad and may clear the durable device credential. `no_active_session`
+                // is an authoritative signed-out. ANY OTHER 401 — a middleware/CSRF/proxy 401,
+                // an ALB/starting-instance 401, a CORS error page, etc., all common during a
+                // deploy/restart window — is NOT proof the secret diverged: treat it as
+                // transient and KEEP the credential so a later attempt self-heals. Wiping the
+                // credential on an ambiguous 401 is what logged users out on every deploy,
+                // ecosystem-wide.
+                if (body.includes('invalid_device_secret'))
+                    return { status: 'invalid-secret' };
+                if (body.includes('no_active_session'))
+                    return { status: 'no-session' };
+                // A pinned mint whose account left the device set. The secret is intact —
+                // never classify this as a bad secret, or the caller would drop a healthy
+                // credential over a stale identity binding.
+                if (body.includes('account_not_on_device'))
+                    return { status: 'account-not-on-device' };
+                return { status: 'transient' };
+            }
+            return { status: 'transient' };
+        }
+        // The account this session is BOUND to: the pinned one when identity-bound
+        // (the server already minted for it), else the device's active account.
+        const boundAccountId = pin ? pin.accountId : mint.state.activeAccountId;
+        const bound = mint.state.accounts.find((a) => a.accountId === boundAccountId);
+        const next = {
+            ...persisted,
+            deviceId: mint.state.deviceId,
+            deviceSecret: mint.nextDeviceSecret,
+            accessToken: mint.accessToken,
+            expiresAt: mint.expiresAt,
+            ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
+        };
+        // Persist nextDeviceSecret (read-back-verified) BEFORE planting the token.
+        // A failed durable persist must NOT plant.
+        const persistedOk = await store.save(next);
+        if (!persistedOk) {
+            return { status: 'persist-failed' };
+        }
+        oxy.setTokens(mint.accessToken);
+        return {
+            status: 'ok',
+            token: mint.accessToken,
+            sessionId: next.sessionId,
+            userId: next.userId,
+            state: mint.state,
+        };
+    });
+}
+/**
+ * Re-mint the persisted session and return the fresh access token, or `null`
+ * when no arm could produce one.
+ *
+ * Arm 1 (`POST /session/device/token`, via {@link refreshDeviceSecretArm}): mint
+ * from the persisted `deviceId` + `deviceSecret`. On a 401 the secret is diverged
+ * or the device has no live session: drop the secret so the mint lane stops (or
+ * clear the store on web, where there is no fallback), then fall to arm 2 on
+ * native. A transient error — or a durable-persist failure — leaves the store and
+ * returns `null` WITHOUT falling to shared-key (those are not bad-secret signals).
+ *
+ * Arm 2 (native shared-keychain): when the secret is absent or was just rejected,
+ * re-mint via `signInWithSharedIdentity` (which plants tokens). On success the
+ * recovered `{deviceId, deviceSecret, …}` is PERSISTED so the fast device-secret
+ * lane is repopulated (mirrors the cold boot's `shared-key-signin` step) — an
+ * in-session shared-key recovery must not leave the fast-lane credential empty.
+ *
+ * IDENTITY-BOUND clients (`deps.identity`) run a different arm 2: the
+ * shared-keychain lane is DISABLED (its cross-app slot may hold a different
+ * identity) and replaced by {@link establishIdentitySession}, which re-signs a
+ * challenge with the PRIMARY local key and rewrites the pin. Arm 1 is pinned.
+ */
+export async function refreshPersistedSession(deps) {
+    const { oxy, store } = deps;
+    const identity = deps.identity ?? null;
+    // The shared keychain is never an identity-bound client's recovery path.
+    const allowSharedKeyFallback = identity ? false : (deps.allowSharedKeyFallback ?? isNative());
+    // Resolved per call: a re-established identity session can move the pin, and a
+    // replaced/removed local key clears it (in which case arm 1 must NOT mint —
+    // an unpinned mint would adopt whatever account the device switched to).
+    const pin = identity ? await resolveIdentityPin(identity) : null;
+    if (identity && !pin) {
+        return recoverIdentitySession(oxy, store, identity);
+    }
+    const arm1 = await refreshDeviceSecretArm({ oxy, store, pin });
+    switch (arm1.status) {
+        case 'ok':
+            return arm1.token;
+        case 'transient':
+            logger.debug('Persisted deviceSecret mint failed (transient) — keeping store', { component: 'refresh', method: 'refreshPersistedSession' });
+            return null;
+        case 'persist-failed':
+            // The server rotated the secret but it did not durably persist. Do NOT fall
+            // to shared-key and do NOT plant — a later attempt re-mints (the process
+            // mirror still holds the rotated secret the server accepts) and can persist
+            // once storage recovers. Never advertise a session on an unsaved secret.
+            logger.error('Device-secret mint rotated the secret but it could not be durably persisted — refusing to plant (a later attempt re-mints)', undefined, { component: 'refresh', method: 'refreshPersistedSession' });
+            return null;
+        case 'invalid-secret':
+        case 'no-session': {
+            // 401: secret diverged or no live session. When a key-based arm 2 can still
+            // recover (native shared key, or an identity-bound client's own primary
+            // key) drop ONLY the secret and keep the deviceId; otherwise (web) the
+            // session is over — clear the store.
+            const persisted = await store.load();
+            if (allowSharedKeyFallback || identity) {
+                if (persisted) {
+                    await store.save({ ...persisted, deviceSecret: undefined });
+                }
+            }
+            else {
+                await store.clear();
+            }
+            break;
+        }
+        case 'account-not-on-device':
+            // The pinned account left this device's session set. The secret is healthy —
+            // leave the store untouched and let the identity arm re-establish.
+            logger.debug('Pinned device-secret mint rejected: the pinned account is no longer on this device — re-establishing from the identity key', { component: 'refresh', method: 'refreshPersistedSession' });
+            break;
+        case 'no-secret':
+            break;
+    }
+    if (identity) {
+        return recoverIdentitySession(oxy, store, identity);
+    }
+    if (allowSharedKeyFallback) {
+        try {
+            const session = await oxy.signInWithSharedIdentity();
+            if (session?.accessToken) {
+                // Repopulate the fast device-secret lane from the shared-key re-mint.
+                if (session.deviceId && session.deviceSecret) {
+                    await store.save({
+                        sessionId: session.sessionId,
+                        userId: session.user.id,
+                        deviceId: session.deviceId,
+                        deviceSecret: session.deviceSecret,
+                        accessToken: session.accessToken,
+                        expiresAt: session.expiresAt,
+                    });
+                }
+                return session.accessToken;
+            }
+        }
+        catch (error) {
+            logger.debug('Shared-key re-mint fallback failed', { component: 'refresh', method: 'refreshPersistedSession' }, error);
+        }
+    }
+    return null;
+}
+/**
+ * Arm 2 for an IDENTITY-BOUND client: re-establish the session from the PRIMARY
+ * local key and rewrite the pin (`establishIdentitySession` plants the token and
+ * persists the device credential itself).
+ *
+ * Returns `null` — never throws — when there is no local identity, the verify
+ * yielded no token, or the exchange failed: the caller treats that as "could not
+ * refresh", exactly like the shared-key arm. A locked keychain therefore ends
+ * signed out rather than falling back to the device's active account.
+ */
+async function recoverIdentitySession(oxy, store, binding) {
+    try {
+        const established = await establishIdentitySession({ oxy, store, binding });
+        return established?.session.accessToken ?? null;
+    }
+    catch (error) {
+        logger.debug('Identity-key re-sign-in failed', { component: 'refresh', method: 'recoverIdentitySession' }, error);
+        return 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 function createAuthRefreshHandler(deps) {
+    return async (_reason) => {
+        return refreshPersistedSession(deps);
+    };
+}
+/**
+ * Install the unified refresh handler on the owner client's `HttpService`.
+ * Returns a disposer that removes it.
+ */
+export function installAuthRefreshHandler(deps) {
+    deps.oxy.httpService.setAuthRefreshHandler(createAuthRefreshHandler(deps));
+    return () => {
+        deps.oxy.httpService.setAuthRefreshHandler(null);
+    };
+}
+/**
+ * Start the proactive re-mint 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, re-mints 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 re-mint trigger in that case. The timer is
+ * `.unref?.()`-ed so it never keeps a Node/Jest event loop alive.
+ */
+export function startTokenRefreshScheduler(oxy) {
+    let disposed = false;
+    let timer = null;
+    // 0 = no active backoff; grows on consecutive failures, resets on success /
+    // token change. Keeps a failing re-mint from re-arming at zero delay.
+    let failureBackoffMs = 0;
+    const clearTimer = () => {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    };
+    /** Arm the timer for `delayMs`, flooring at {@link MIN_SCHEDULE_DELAY_MS} and capping at the int32 max. */
+    const armTimer = (delayMs) => {
+        clearTimer();
+        const clamped = Math.min(Math.max(delayMs, MIN_SCHEDULE_DELAY_MS), MAX_TIMEOUT_DELAY_MS);
+        timer = setTimeout(runRefresh, clamped);
+        // Never keep a Node/Jest event loop alive for a background re-mint timer.
+        timer.unref?.();
+    };
+    /** Schedule the next re-mint from the current token's expiry (the healthy path). */
+    const scheduleFromExpiry = () => {
+        clearTimer();
+        if (disposed || !oxy.getAccessToken()) {
+            return;
+        }
+        const expSeconds = oxy.getAccessTokenExpiry();
+        if (expSeconds === null) {
+            return;
+        }
+        armTimer(expSeconds * 1000 - Date.now() - TOKEN_REFRESH_LEAD_MS);
+    };
+    const runRefresh = () => {
+        // Clear any pending timer up front so an out-of-band trigger (focus) plus
+        // a fired timer can never double-run.
+        clearTimer();
+        void oxy.httpService.refreshAccessToken('preflight')
+            .then((token) => Boolean(token))
+            .catch(() => false)
+            .then((ok) => {
+            if (disposed) {
+                return;
+            }
+            if (ok) {
+                // Success — drop any backoff and re-arm from the rotated token's exp.
+                failureBackoffMs = 0;
+                scheduleFromExpiry();
+                return;
+            }
+            // Failure — back off (never re-arm at zero) and retry.
+            failureBackoffMs =
+                failureBackoffMs === 0
+                    ? MIN_FAILURE_BACKOFF_MS
+                    : Math.min(failureBackoffMs * 2, MAX_FAILURE_BACKOFF_MS);
+            armTimer(failureBackoffMs);
+        });
+    };
+    /** Public (re)schedule entry: a fresh token / focus signal — drop backoff and arm from expiry. */
+    const schedule = () => {
+        failureBackoffMs = 0;
+        scheduleFromExpiry();
+    };
+    const onFocus = () => {
+        if (disposed || !oxy.getAccessToken()) {
+            return;
+        }
+        const expSeconds = oxy.getAccessTokenExpiry();
+        if (expSeconds === null) {
+            return;
+        }
+        const remainingMs = expSeconds * 1000 - Date.now();
+        if (remainingMs <= TOKEN_REFRESH_LEAD_MS) {
+            runRefresh();
+        }
+        else {
+            schedule();
+        }
+    };
+    const unsubscribeTokens = oxy.onTokensChanged(() => {
+        if (!disposed) {
+            schedule();
+        }
+    });
+    let removeFocusListener = null;
+    if (typeof document !== 'undefined') {
+        const handler = () => {
+            if (document.visibilityState === 'visible') {
+                onFocus();
+            }
+        };
+        document.addEventListener('visibilitychange', handler);
+        removeFocusListener = () => document.removeEventListener('visibilitychange', handler);
+    }
+    schedule();
+    return {
+        dispose() {
+            disposed = true;
+            clearTimer();
+            unsubscribeTokens();
+            removeFocusListener?.();
+            removeFocusListener = null;
+        },
+    };
+}

package/dist/esm/session/sessionClientHost.js

@@ -0,0 +1,31 @@
+/**
+ * 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 `@oxy.so/services`) 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;
+    let deviceCredential = null;
+    return {
+        makeRequest: (method, url, data, options) => oxyServices.makeRequest(method, url, data, options),
+        getBaseURL: () => oxyServices.getBaseURL(),
+        getAccessToken: () => oxyServices.getAccessToken(),
+        getDeviceCredential: () => deviceCredential,
+        onTokensChanged: (listener) => oxyServices.onTokensChanged(listener),
+        setTokens: (accessToken) => oxyServices.setTokens(accessToken),
+        getCurrentAccountId: () => currentAccountId,
+        setCurrentAccountId: (id) => {
+            currentAccountId = id;
+        },
+        setDeviceCredential: (credential) => {
+            deviceCredential = credential;
+        },
+    };
+}

package/dist/esm/session/sharedDeviceCredential.js

@@ -0,0 +1,239 @@
+/**
+ * The shared native DeviceSession credential — one device, one session, many apps.
+ *
+ * ## What this is, and what it deliberately is NOT
+ *
+ * Two different secrets can make a native Oxy app boot signed in, and conflating
+ * them is the bug this module exists to end:
+ *
+ *   Commons private identity key   → identity and signed approval ONLY. It is
+ *                                    self-custody, irreplaceable, and must never
+ *                                    become the general app session transport.
+ *   Shared DeviceSession credential → THIS module. An ordinary `deviceId` +
+ *                                    `deviceSecret` pair that restores ordinary
+ *                                    official apps, follows the device's active
+ *                                    context, and is individually rotatable and
+ *                                    revocable server-side.
+ *
+ * An ordinary app needs the second one. Handing it the first — which is what the
+ * `shared-key-signin` lane does today — gives every sibling app the ability to
+ * sign as the user's cryptographic identity to obtain something as mundane as a
+ * session. That lane stays as a recovery/compatibility path; this one supersedes
+ * it for the ordinary case.
+ *
+ * ## Why sharing one credential is safe against the server
+ *
+ * `POST /session/device/token` does NOT rotate: the response echoes the presented
+ * secret back as `nextDeviceSecret` precisely so several first-party apps sharing
+ * one `DeviceSession` can refresh concurrently without invalidating one another.
+ * So N apps holding one credential is a supported server state, not a race — and
+ * because they then share ONE `DeviceSession`, they automatically share its
+ * `activeContextId` and its token-free `session_state` broadcasts.
+ *
+ * ## The one safety rule everything here is built around
+ *
+ * A read that FAILED and a slot that is EMPTY must never be the same value. The
+ * empty answer authorises writes (seed the slot); the failed answer must
+ * authorise nothing. {@link SharedDeviceCredentialRead} keeps them apart at the
+ * type level, and every decision below fails closed on anything that is not a
+ * positive `absent`/`present`.
+ *
+ * Platform-agnostic: the actual keychain / keystore access is injected as a
+ * {@link SharedDeviceCredentialStore} by `@oxy.so/services`. ESM-safe, no
+ * `require()`, no react/react-native/expo imports.
+ */
+import { logger } from '../logger/index.js';
+/** The usable `{deviceId, deviceSecret}` pair in a persisted state, or null. */
+export function readLocalDeviceCredential(state) {
+    if (!state?.deviceId || !state.deviceSecret) {
+        return null;
+    }
+    return { deviceId: state.deviceId, deviceSecret: state.deviceSecret };
+}
+/**
+ * Narrow an UNTRUSTED bridge payload into a {@link SharedDeviceCredentialRead}.
+ *
+ * Anything unrecognised resolves to `unavailable`, never `absent`. A native
+ * module returning a shape this build does not understand (an older app in the
+ * signing group, a partially-applied upgrade) means we do not KNOW whether the
+ * device has a shared session — and "do not know" must never authorise a write
+ * that would overwrite one.
+ */
+export function normalizeSharedDeviceSessionRead(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return { state: 'unavailable', cause: new Error('shared device session bridge returned a non-object') };
+    }
+    const payload = raw;
+    if (payload.status === 'absent') {
+        return { state: 'absent' };
+    }
+    if (payload.status === 'present') {
+        const deviceId = payload.deviceId;
+        const deviceSecret = payload.deviceSecret;
+        if (typeof deviceId === 'string' &&
+            deviceId.length > 0 &&
+            typeof deviceSecret === 'string' &&
+            deviceSecret.length > 0) {
+            return { state: 'present', credential: { deviceId, deviceSecret } };
+        }
+        // A `present` verdict whose payload is incomplete is a broken slot, not an
+        // empty one. Reporting `absent` here would let the next successful sign-in
+        // overwrite whatever is really in there.
+        return {
+            state: 'unavailable',
+            cause: new Error('shared device session bridge reported `present` with an incomplete credential'),
+        };
+    }
+    if (payload.status === 'unavailable') {
+        const reason = typeof payload.reason === 'string' ? payload.reason : 'unknown';
+        return { state: 'unavailable', cause: new Error(`shared device session slot unavailable: ${reason}`) };
+    }
+    return {
+        state: 'unavailable',
+        cause: new Error(`shared device session bridge returned an unrecognised status: ${String(payload.status)}`),
+    };
+}
+/**
+ * Should this app adopt the shared credential? Pure.
+ *
+ * Adoption happens in exactly ONE case: the shared slot holds a credential and
+ * this app has none of its own. That single rule delivers the product
+ * requirement — a newly installed official app joins the device's existing
+ * session without another QR — while making the two failure modes that matter
+ * unreachable:
+ *
+ *  - An app that is already signed in is NEVER moved onto another credential, so
+ *    "no user is signed out merely because one app updates first" holds by
+ *    construction, in both upgrade directions.
+ *  - A failed read never looks like an empty slot, so a locked keychain resolves
+ *    to "keep what I have" rather than "this is a fresh device".
+ *
+ * The cost is stated plainly: two apps that each already own a DIFFERENT device
+ * session stay on their own until one of them loses its credential. Converging
+ * them would mean signing one of them out or a server-side device merge, and
+ * neither is something a boot path may do silently.
+ */
+export function decideSharedDeviceJoin(local, shared) {
+    if (readLocalDeviceCredential(local) !== null) {
+        return { action: 'skip', reason: 'local-credential-present' };
+    }
+    switch (shared.state) {
+        case 'present':
+            return { action: 'adopt', credential: shared.credential };
+        case 'absent':
+            return { action: 'skip', reason: 'shared-empty' };
+        case 'unavailable':
+            return { action: 'skip', reason: 'shared-unreadable' };
+        case 'unsupported':
+            return { action: 'skip', reason: 'shared-unsupported' };
+    }
+}
+/**
+ * Should this app write the credential it just proved into the shared slot? Pure.
+ *
+ * `proven` means the server accepted it moments ago — a successful sign-in or a
+ * successful mint. Only a proven credential is ever published, so the slot can
+ * never be seeded with something no app could use.
+ *
+ * A slot already held by a DIFFERENT `deviceId` is left alone. Overwriting it
+ * would silently migrate every other app on this device onto our session at their
+ * next cold boot — a real, user-visible change of who they are signed in as, and
+ * not something a background persist may decide.
+ */
+export function decideSharedDevicePublish(proven, shared) {
+    switch (shared.state) {
+        case 'unsupported':
+            return { action: 'skip', reason: 'shared-unsupported' };
+        case 'unavailable':
+            return { action: 'skip', reason: 'shared-unreadable' };
+        case 'absent':
+            return { action: 'publish' };
+        case 'present': {
+            if (shared.credential.deviceId !== proven.deviceId) {
+                return { action: 'skip', reason: 'owned-by-another-device' };
+            }
+            if (shared.credential.deviceSecret === proven.deviceSecret) {
+                return { action: 'skip', reason: 'already-current' };
+            }
+            // Same device, newer secret. Sign-in rotates the secret (the mint does
+            // not), so the just-proven one is the credential a fresh install should
+            // join with.
+            return { action: 'publish' };
+        }
+    }
+}
+/**
+ * Read the shared slot, apply {@link decideSharedDevicePublish}, and write when
+ * it says so. Best-effort by contract: the caller's own durable credential is
+ * already persisted, so a failure here only means a future install will have to
+ * sign in interactively.
+ */
+export async function publishProvenDeviceCredential(deps) {
+    const read = await deps.shared.read();
+    const decision = decideSharedDevicePublish(deps.credential, read);
+    if (decision.action === 'skip') {
+        if (decision.reason === 'shared-unreadable') {
+            logger.debug('shared device credential slot unreadable — not publishing (an unreadable slot is never an empty one)', { component: 'sharedDeviceCredential', method: 'publishProvenDeviceCredential' });
+        }
+        return { status: 'skipped', reason: decision.reason };
+    }
+    const published = await deps.shared.publish(deps.credential);
+    return published ? { status: 'published' } : { status: 'publish-failed' };
+}
+/**
+ * Wrap a platform {@link AuthStateStore} so that every durable credential it
+ * persists is ALSO mirrored into the shared slot.
+ *
+ * Writes mirror automatically; reads do NOT adopt. That split is deliberate:
+ *
+ *  - Mirroring on write is the right place because `save()` is where a proven
+ *    credential lands, on every lane there is — interactive sign-in, the cold
+ *    boot mint, the refresh scheduler, the 401 re-mint, shared-key recovery. One
+ *    seam, no lane left out, and no new call site to forget.
+ *  - Adopting on read would hide a change of WHO THIS APP IS SIGNED IN AS inside
+ *    a storage primitive, and would run on every `load()`. Adoption is an
+ *    explicit, once-per-boot cold-boot step instead (`shared-device-adopt`).
+ *
+ * `clear()` deliberately does NOT clear the shared slot. This app signing out is
+ * not authority over the device-wide join point: other apps may still be signed
+ * in on that same credential, and once the server session is really gone the
+ * credential mints `no_active_session` for everyone anyway.
+ */
+export function createSharedMirroringAuthStateStore(deps) {
+    const { local, shared } = deps;
+    // Process-local memo of the credential we last observed the shared slot to
+    // hold. Purely an optimization to keep the refresh scheduler from re-reading
+    // the keychain every mint; a slot wiped out from under us is re-seeded on the
+    // next launch rather than mid-process.
+    let mirrored = null;
+    return {
+        load: () => local.load(),
+        clear: () => local.clear(),
+        save: async (state) => {
+            // The durable local write is the contract this store owes its caller —
+            // run it first and report ITS result, unchanged. The mirror is additive.
+            const durablePersisted = await local.save(state);
+            const credential = readLocalDeviceCredential(state);
+            if (!credential) {
+                return durablePersisted;
+            }
+            if (mirrored !== null &&
+                mirrored.deviceId === credential.deviceId &&
+                mirrored.deviceSecret === credential.deviceSecret) {
+                return durablePersisted;
+            }
+            try {
+                const outcome = await publishProvenDeviceCredential({ shared, credential });
+                if (outcome.status === 'published' || (outcome.status === 'skipped' && outcome.reason === 'already-current')) {
+                    mirrored = credential;
+                }
+            }
+            catch (error) {
+                // A store implementation is contractually non-throwing, but a mirror
+                // failure must never take down the durable write that already succeeded.
+                logger.debug('mirroring the device credential into the shared slot threw — the local credential is unaffected', { component: 'sharedDeviceCredential', method: 'save' }, error);
+            }
+            return durablePersisted;
+        },
+    };
+}

package/dist/esm/session/socketLoader.js

@@ -0,0 +1,19 @@
+import { logger } from '../logger/index.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;
+    }
+}