@oxyhq/core 5.5.0 → 7.0.0

package/src/boot/coldBootV2.ts

@@ -0,0 +1,426 @@
+/**
+ * coldBootV2 — one device-first cold boot for every consumer.
+ *
+ * On a fresh page load / app launch this resolves the device's session in a
+ * deterministic order, built on the pure `runColdBoot` primitive. It NEVER
+ * redirects to a login page: an unresolved boot ends in a signed-out state that
+ * the app renders with a "Sign in with Oxy" button.
+ *
+ * Ordered steps (first to yield a session wins):
+ *   1. `bootstrap-return` (web) — consume a `#oxy_boot` return fragment from a
+ *      just-completed cross-apex hop: strip it, verify state, persist the
+ *      deviceToken, exchange the code.
+ *   2. `stored-tokens` — the persisted per-origin refresh family: warm-plant a
+ *      still-valid access token, else rotate via `/auth/refresh-token`.
+ *   3. `shared-key-signin` (native) — re-mint from the shared-keychain identity,
+ *      issuing + mirroring a shared deviceToken the first time.
+ *   4. `bootstrap-hop` (web) — same-apex: an inline credentialed
+ *      `/auth/device/web-session` fetch (no redirect); cross-apex: ONE top-level
+ *      navigation to `/auth/device/bootstrap`, guarded once-ever per origin.
+ *   5. Signed out.
+ *
+ * All mutable guard state lives in STORAGE (localStorage `oxy.boot.attempted` +
+ * sessionStorage `oxy.boot.state`), never in module scope, so the guard holds
+ * under Metro/bundler re-evaluation.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import { resolveUserId } from '@oxyhq/contracts';
+import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/coldBoot';
+import { isWeb as detectWeb, isNative as detectNative } from '../utils/platform';
+import { KeyManager } from '../crypto/keyManager';
+import { logger } from '../utils/loggerUtils';
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore, PersistedAuthState } from '../session/authStateStore';
+import { refreshPersistedSession } from '../session/refresh';
+import {
+  consumeDeviceBootReturn,
+  hashHasBootFragment,
+  BOOT_STATE_SESSION_KEY,
+  type DeviceBootSession,
+} from './deviceBootReturn';
+
+/**
+ * localStorage flag marking that the cross-apex bootstrap navigation has fired
+ * once for this origin. Persistent (not session) so the visible redirect
+ * happens AT MOST ONCE EVER per browser+origin — a signed-out user is never
+ * bounced again; they sign in explicitly.
+ */
+export const BOOT_ATTEMPTED_KEY = 'oxy.boot.attempted';
+
+/**
+ * Do not warm-plant a stored access token with less than this remaining — it
+ * would need an immediate refresh anyway, so fall through to the rotate path.
+ * Matches the refresh lead window.
+ */
+const WARM_MIN_REMAINING_MS = 60_000;
+
+/** Why a cold boot ended without a session. */
+export type SignedOutReason =
+  | 'no_session'
+  | 'new_device'
+  | 'state-mismatch'
+  | 'error';
+
+/**
+ * The DOM/storage seam. All access is injected so the boot is unit-testable
+ * under the jest `node` environment; {@link createBrowserColdBootDom} provides
+ * the guarded real-globals implementation used in production.
+ */
+export interface ColdBootDom {
+  getHash(): string;
+  stripFragment(): void;
+  getSessionItem(key: string): string | null;
+  setSessionItem(key: string, value: string): void;
+  removeSessionItem(key: string): void;
+  getLocalItem(key: string): string | null;
+  setLocalItem(key: string, value: string): void;
+  getLocationHostname(): string | null;
+  /** Current href WITHOUT its hash fragment (the bootstrap `return_to`). */
+  getReturnToHref(): string | null;
+  navigate(url: string): void;
+  /** A fresh high-entropy CSRF state token. */
+  randomState(): string;
+}
+
+export interface RunSessionColdBootOptions {
+  oxy: OxyServices;
+  store: AuthStateStore;
+  /** Platform hints; default derived from `@oxyhq/core`'s platform detection. */
+  platform?: { isWeb?: boolean; isNative?: boolean };
+  /**
+   * The RP return URL for the cross-apex hop. Defaults to the current href
+   * (sans fragment) via the DOM seam.
+   */
+  returnTo?: string;
+  /** Invoked with the winning session (token already planted). */
+  onSession?: (session: DeviceBootSession & { via: string }) => void | Promise<void>;
+  /** Invoked when the boot ended signed out (not while navigating away). */
+  onSignedOut?: (reason: SignedOutReason) => void | Promise<void>;
+  onStepError?: (id: string, error: unknown) => void;
+  /** DOM/storage seam; defaults to the guarded browser implementation. */
+  dom?: ColdBootDom;
+}
+
+/**
+ * Generate a 128-bit hex CSRF state token. Prefers Web Crypto
+ * (`crypto.getRandomValues`, present in browsers and modern Node); falls back
+ * to a time+`Math.random` mix only when no CSPRNG is reachable (this token
+ * gates a single-use CSRF echo, not a long-lived secret).
+ */
+function generateStateToken(): string {
+  const cryptoObj = (globalThis as { crypto?: Crypto }).crypto;
+  if (cryptoObj?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    cryptoObj.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  }
+  return `${Date.now().toString(16)}${Math.random().toString(16).slice(2, 18)}`;
+}
+
+/**
+ * The guarded real-globals {@link ColdBootDom}. Every accessor tolerates a
+ * missing/throwing global (SSR, sandboxed iframe) by returning a neutral value
+ * or no-op, so the boot degrades to signed-out rather than crashing.
+ */
+export function createBrowserColdBootDom(): ColdBootDom {
+  const safe = <T>(fn: () => T, fallback: T): T => {
+    try {
+      return fn();
+    } catch {
+      return fallback;
+    }
+  };
+  return {
+    getHash: () => safe(() => (typeof window !== 'undefined' ? window.location.hash : ''), ''),
+    stripFragment: () =>
+      safe(() => {
+        if (typeof window !== 'undefined' && window.history?.replaceState) {
+          const { pathname, search } = window.location;
+          window.history.replaceState(null, '', `${pathname}${search}`);
+        }
+      }, undefined),
+    getSessionItem: (key) =>
+      safe(() => (typeof sessionStorage !== 'undefined' ? sessionStorage.getItem(key) : null), null),
+    setSessionItem: (key, value) =>
+      safe(() => {
+        if (typeof sessionStorage !== 'undefined') sessionStorage.setItem(key, value);
+      }, undefined),
+    removeSessionItem: (key) =>
+      safe(() => {
+        if (typeof sessionStorage !== 'undefined') sessionStorage.removeItem(key);
+      }, undefined),
+    getLocalItem: (key) =>
+      safe(() => (typeof localStorage !== 'undefined' ? localStorage.getItem(key) : null), null),
+    setLocalItem: (key, value) =>
+      safe(() => {
+        if (typeof localStorage !== 'undefined') localStorage.setItem(key, value);
+      }, undefined),
+    getLocationHostname: () =>
+      safe(() => (typeof window !== 'undefined' ? window.location.hostname : null), null),
+    getReturnToHref: () =>
+      safe(() => {
+        if (typeof window === 'undefined') return null;
+        const { origin, pathname, search } = window.location;
+        return `${origin}${pathname}${search}`;
+      }, null),
+    navigate: (url) =>
+      safe(() => {
+        if (typeof window !== 'undefined') window.location.assign(url);
+      }, undefined),
+    randomState: generateStateToken,
+  };
+}
+
+/**
+ * Registrable domain = the last two labels of a host. A deliberately SMALL
+ * local helper (the plan forbids coupling the boot to `fapiAutoDetect`/`tldts`).
+ * Correct for every Oxy apex (all two-label domains: `oxy.so`, `mention.earth`,
+ * `alia.onl`, `homiio.com`); the only imprecision — a multi-part public suffix
+ * such as `co.uk` — never arises here because the compared API host is always
+ * `api.oxy.so`, so a page under a different registrable domain still classifies
+ * as cross-apex.
+ */
+function registrableDomain(host: string): string {
+  const labels = host.toLowerCase().split('.').filter(Boolean);
+  return labels.length <= 2 ? labels.join('.') : labels.slice(-2).join('.');
+}
+
+/**
+ * Is `host` an IP literal (v4/v6) or a single-label host (`localhost`)? Such
+ * hosts have NO registrable domain — the last-two-labels heuristic would
+ * mis-group them (`192.168.1.1` and `10.0.1.1` both collapse to `1.1`; IPv6
+ * `::1` and `localhost` are single "labels"), so a LAN/dev page could be wrongly
+ * classified same-apex as a different LAN API and skip the cross-apex hop.
+ */
+function isIpOrSingleLabel(host: string): boolean {
+  if (host.includes(':')) {
+    return true; // IPv6 literal
+  }
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) {
+    return true; // IPv4 literal
+  }
+  return !host.includes('.'); // single-label (e.g. `localhost`)
+}
+
+/**
+ * True when both hosts are same-site / same-apex. For a normal multi-label host
+ * pair, that means sharing a registrable domain. For an IP literal or a
+ * single-label host (no registrable domain), same-apex requires the two hosts
+ * to be EXACTLY equal — never grouped by a spurious trailing-label match.
+ */
+export function isSameApex(pageHost: string, apiHost: string): boolean {
+  const a = pageHost.toLowerCase();
+  const b = apiHost.toLowerCase();
+  if (isIpOrSingleLabel(a) || isIpOrSingleLabel(b)) {
+    return a === b;
+  }
+  const ra = registrableDomain(a);
+  const rb = registrableDomain(b);
+  return ra !== '' && ra === rb;
+}
+
+/** Build a `DeviceBootSession` from a persisted state (post-refresh/warm-plant). */
+function sessionFromPersisted(state: PersistedAuthState, accessToken: string): DeviceBootSession {
+  return { sessionId: state.sessionId, userId: state.userId, accessToken };
+}
+
+/**
+ * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
+ * a side effect, invokes `onSession` (winning session, token already planted)
+ * or `onSignedOut` (no session — unless the boot is navigating away for the
+ * cross-apex hop, in which case neither fires).
+ */
+export async function runSessionColdBoot(
+  opts: RunSessionColdBootOptions,
+): Promise<ColdBootOutcome<DeviceBootSession>> {
+  const { oxy, store } = opts;
+  const dom = opts.dom ?? createBrowserColdBootDom();
+  const isWeb = opts.platform?.isWeb ?? detectWeb();
+  const isNative = opts.platform?.isNative ?? detectNative();
+
+  // Signed-out reason + navigating flag are boot-local (not module-level), so
+  // they cannot leak across boots or break under bundler re-evaluation.
+  let signedOutReason: SignedOutReason = 'no_session';
+  let navigating = false;
+
+  const steps: Array<ColdBootStep<DeviceBootSession>> = [];
+
+  // 1. bootstrap-return (web) — consume a #oxy_boot fragment.
+  steps.push({
+    id: 'bootstrap-return',
+    enabled: () => isWeb && hashHasBootFragment(dom.getHash()),
+    run: async () => {
+      const outcome = await consumeDeviceBootReturn({
+        hash: dom.getHash(),
+        stripFragment: () => dom.stripFragment(),
+        readExpectedState: () => dom.getSessionItem(BOOT_STATE_SESSION_KEY),
+        clearExpectedState: () => dom.removeSessionItem(BOOT_STATE_SESSION_KEY),
+        store,
+        exchangeBootCode: (code) => oxy.exchangeBootCode(code),
+        plantAccessToken: (accessToken) => oxy.setTokens(accessToken),
+      });
+      if (outcome.kind === 'session') {
+        return { kind: 'session', session: outcome.session };
+      }
+      if (outcome.kind === 'state-mismatch') {
+        signedOutReason = 'state-mismatch';
+      } else if (outcome.kind === 'no-session') {
+        // `DeviceBootReason` also carries 'session'; a no-session outcome with
+        // that reason (a `session` reason but no code) is still signed out.
+        signedOutReason = outcome.reason === 'new_device' ? 'new_device' : 'no_session';
+      }
+      // Fall through: a stored refresh family (a prior same-origin session) may
+      // still recover below. The once-ever flag blocks a second hop.
+      return { kind: 'skip' };
+    },
+  });
+
+  // 2. stored-tokens — warm-plant or rotate the persisted refresh family.
+  steps.push({
+    id: 'stored-tokens',
+    run: async () => {
+      const persisted = await store.load();
+      if (!persisted) {
+        return { kind: 'skip' };
+      }
+      // Warm path: a still-valid access token → plant immediately (no network).
+      if (
+        persisted.accessToken &&
+        persisted.expiresAt &&
+        Date.parse(persisted.expiresAt) - Date.now() > WARM_MIN_REMAINING_MS
+      ) {
+        oxy.setTokens(persisted.accessToken);
+        return { kind: 'session', session: sessionFromPersisted(persisted, persisted.accessToken) };
+      }
+      // Rotate path: refreshPersistedSession plants + persists, and clears the
+      // store on a family-revoked error.
+      const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: isNative });
+      if (!token) {
+        return { kind: 'skip' };
+      }
+      const after = await store.load();
+      const base = after ?? persisted;
+      return { kind: 'session', session: sessionFromPersisted(base, token) };
+    },
+  });
+
+  // 3. shared-key-signin (native) — re-mint from the shared identity.
+  steps.push({
+    id: 'shared-key-signin',
+    enabled: () => isNative,
+    run: async () => {
+      const session = await oxy.signInWithSharedIdentity();
+      if (!session?.accessToken) {
+        return { kind: 'skip' };
+      }
+      // First shared-key sign-in on this device: issue + persist + mirror a
+      // shared deviceToken so every native Oxy app joins one DeviceSession.
+      // Best-effort — never fail the sign-in over device-token issuance.
+      try {
+        const existing = await KeyManager.getSharedDeviceToken();
+        if (!existing) {
+          const deviceToken = await oxy.issueNativeDeviceToken();
+          await store.saveDeviceToken(deviceToken);
+          await KeyManager.setSharedDeviceToken(deviceToken);
+        }
+      } catch (error) {
+        logger.debug(
+          'Native deviceToken issuance skipped',
+          { component: 'coldBootV2', method: 'shared-key-signin' },
+          error,
+        );
+      }
+      return {
+        kind: 'session',
+        session: {
+          sessionId: session.sessionId,
+          userId: session.user.id,
+          accessToken: session.accessToken,
+        },
+      };
+    },
+  });
+
+  // 4. bootstrap-hop (web, terminal) — same-apex inline fetch OR cross-apex nav.
+  steps.push({
+    id: 'bootstrap-hop',
+    enabled: () => isWeb,
+    run: async () => {
+      const pageHost = dom.getLocationHostname();
+      let apiHost: string | null = null;
+      try {
+        apiHost = new URL(oxy.getBaseURL()).hostname;
+      } catch {
+        apiHost = null;
+      }
+      if (!pageHost || !apiHost) {
+        return { kind: 'skip' };
+      }
+
+      // Same-apex: inline credentialed fetch, no redirect, runs every boot.
+      if (isSameApex(pageHost, apiHost)) {
+        const result = await oxy.requestWebSession();
+        // The rotated deviceToken is on BOTH arms (it is device-level, not
+        // session-level) — persist it before branching on the session.
+        await store.saveDeviceToken(result.deviceToken);
+        if (result.reason === 'session') {
+          const bundle = result.session;
+          const userId = resolveUserId(bundle.user);
+          if (!userId) {
+            return { kind: 'skip' };
+          }
+          const next: PersistedAuthState = {
+            sessionId: bundle.sessionId,
+            refreshToken: bundle.refreshToken,
+            userId,
+            deviceToken: result.deviceToken,
+            accessToken: bundle.accessToken,
+            expiresAt: bundle.expiresAt,
+          };
+          await store.save(next);
+          oxy.setTokens(bundle.accessToken);
+          return { kind: 'session', session: sessionFromPersisted(next, bundle.accessToken) };
+        }
+        // Known device, signed out.
+        signedOutReason = result.reason;
+        return { kind: 'skip' };
+      }
+
+      // Cross-apex: ONE visible top-level navigation, once-ever per origin.
+      if (dom.getLocalItem(BOOT_ATTEMPTED_KEY)) {
+        return { kind: 'skip' };
+      }
+      const returnTo = opts.returnTo ?? dom.getReturnToHref();
+      if (!returnTo) {
+        return { kind: 'skip' };
+      }
+      const state = dom.randomState();
+      dom.setSessionItem(BOOT_STATE_SESSION_KEY, state);
+      dom.setLocalItem(BOOT_ATTEMPTED_KEY, '1');
+      navigating = true;
+      dom.navigate(oxy.buildBootstrapUrl(returnTo, state));
+      return { kind: 'skip' };
+    },
+  });
+
+  const outcome = await runColdBoot<DeviceBootSession>({
+    steps,
+    onStepError: (id, error) => {
+      signedOutReason = 'error';
+      opts.onStepError?.(id, error);
+    },
+  });
+
+  if (outcome.kind === 'session') {
+    await opts.onSession?.({ ...outcome.session, via: outcome.via });
+    return outcome;
+  }
+
+  // Navigating away for the cross-apex hop: the page is unloading, so do not
+  // flash a signed-out state.
+  if (!navigating) {
+    await opts.onSignedOut?.(signedOutReason);
+  }
+  return outcome;
+}

package/src/boot/deviceBootReturn.ts

@@ -0,0 +1,195 @@
+/**
+ * Device-boot return-fragment consumption (web cross-apex hop).
+ *
+ * After the top-level `GET /auth/device/bootstrap` hop, the API 303s back to the
+ * RP with a `#oxy_boot=<base64url(JSON)>` fragment. This module parses and
+ * consumes it: it strips the fragment from the URL FIRST (so the opaque
+ * deviceToken / code never linger in history or a `Referer`), verifies the
+ * echoed CSRF `state` against the value the initiator stashed in
+ * `sessionStorage`, persists the deviceToken, and — when a session resolved —
+ * exchanges the single-use `code` for a token bundle.
+ *
+ * Pure/injectable: all DOM access (hash, `history.replaceState`,
+ * `sessionStorage`) is passed in as callbacks so the logic is unit-testable
+ * under the jest `node` environment and reusable by `coldBootV2`.
+ *
+ * ESM-safe (no `require()`).
+ */
+import {
+  deviceBootFragmentSchema,
+  resolveUserId,
+  safeParseContract,
+  type AuthTokenBundle,
+  type DeviceBootFragment,
+  type DeviceBootReason,
+} from '@oxyhq/contracts';
+import type { AuthStateStore, PersistedAuthState } from '../session/authStateStore';
+
+/** The `#oxy_boot=` fragment parameter name the API appends on the return hop. */
+export const BOOT_FRAGMENT_PARAM = 'oxy_boot';
+
+/**
+ * `sessionStorage` key under which the bootstrap-hop initiator stashes the
+ * 128-bit CSRF `state` before navigating, and which the return step reads back
+ * (single-use).
+ */
+export const BOOT_STATE_SESSION_KEY = 'oxy.boot.state';
+
+/**
+ * Decode a base64url string to UTF-8 text, or `null` on any malformed input.
+ * Handles both web (`atob` + `TextDecoder`) and Node (`Buffer`) without a
+ * `require()` — the ESM build stays clean.
+ */
+function base64UrlDecode(input: string): string | null {
+  try {
+    let b64 = input.replace(/-/g, '+').replace(/_/g, '/');
+    while (b64.length % 4 !== 0) {
+      b64 += '=';
+    }
+    if (typeof atob === 'function') {
+      const binary = atob(b64);
+      const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+      if (typeof TextDecoder !== 'undefined') {
+        return new TextDecoder().decode(bytes);
+      }
+      return binary;
+    }
+    if (typeof Buffer !== 'undefined') {
+      return Buffer.from(b64, 'base64').toString('utf-8');
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when a location hash carries the `oxy_boot` return fragment. */
+export function hashHasBootFragment(hash: string): boolean {
+  return new RegExp(`(^|[#&])${BOOT_FRAGMENT_PARAM}=`).test(hash);
+}
+
+/**
+ * Extract + decode + validate the `oxy_boot` fragment from a location hash.
+ * Returns the parsed {@link DeviceBootFragment}, or `null` when the parameter
+ * is absent, not valid base64url, not JSON, or fails the contract schema.
+ */
+export function parseDeviceBootFragment(hash: string): DeviceBootFragment | null {
+  const withoutHash = hash.startsWith('#') ? hash.slice(1) : hash;
+  const params = new URLSearchParams(withoutHash);
+  const raw = params.get(BOOT_FRAGMENT_PARAM);
+  if (!raw) {
+    return null;
+  }
+  const json = base64UrlDecode(raw);
+  if (!json) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  return safeParseContract(deviceBootFragmentSchema, parsed);
+}
+
+/** The winning session shape a cold-boot step reports. */
+export interface DeviceBootSession {
+  sessionId: string;
+  userId: string;
+  accessToken: string;
+}
+
+/** Outcome of {@link consumeDeviceBootReturn}. */
+export type DeviceBootReturnOutcome =
+  | { kind: 'none' }
+  | { kind: 'state-mismatch' }
+  | { kind: 'session'; session: DeviceBootSession }
+  | { kind: 'no-session'; reason: DeviceBootReason };
+
+export interface ConsumeDeviceBootReturnDeps {
+  /** The current location hash (e.g. `window.location.hash`). */
+  hash: string;
+  /** Strip the fragment from the URL (e.g. `history.replaceState`). */
+  stripFragment: () => void;
+  /** Read the expected CSRF state (e.g. `sessionStorage.getItem(BOOT_STATE_SESSION_KEY)`). */
+  readExpectedState: () => string | null;
+  /** Clear the expected CSRF state (single-use). */
+  clearExpectedState: () => void;
+  store: AuthStateStore;
+  /** Exchange the single-use boot code for a token bundle (`oxy.exchangeBootCode`). */
+  exchangeBootCode: (code: string) => Promise<AuthTokenBundle>;
+  /** Plant the freshly-minted access token on the owner client (`oxy.setTokens`). */
+  plantAccessToken: (accessToken: string) => void;
+}
+
+/**
+ * Consume the device-boot return fragment.
+ *
+ * Order is load-bearing:
+ *   1. If no fragment is present, return `none` (no URL mutation).
+ *   2. STRIP the fragment from the URL immediately — before validation or any
+ *      network — so the deviceToken/code never persist in history/referrer.
+ *   3. Verify the echoed `state` against the stashed (single-use) value; a
+ *      mismatch returns `state-mismatch` without persisting or exchanging.
+ *   4. Persist the deviceToken (survives sign-out).
+ *   5. If a session resolved (`reason:'session'` + `code`), exchange the code,
+ *      persist the rotated session, plant the token, and return `session`.
+ *      Otherwise return `no-session` with the reason.
+ */
+export async function consumeDeviceBootReturn(
+  deps: ConsumeDeviceBootReturnDeps,
+): Promise<DeviceBootReturnOutcome> {
+  if (!hashHasBootFragment(deps.hash)) {
+    return { kind: 'none' };
+  }
+
+  // Strip FIRST — even a forged/malformed fragment must not linger in the URL.
+  deps.stripFragment();
+
+  const fragment = parseDeviceBootFragment(deps.hash);
+  if (!fragment) {
+    return { kind: 'none' };
+  }
+
+  const expected = deps.readExpectedState();
+  deps.clearExpectedState();
+  if (!expected || expected !== fragment.state) {
+    return { kind: 'state-mismatch' };
+  }
+
+  await deps.store.saveDeviceToken(fragment.deviceToken);
+
+  // `code` is guaranteed present on the `session` arm (the contract's
+  // discriminated union requires it; a session fragment without a code fails to
+  // parse and never reaches here).
+  if (fragment.reason === 'session') {
+    try {
+      const bundle = await deps.exchangeBootCode(fragment.code);
+      const userId = resolveUserId(bundle.user);
+      if (!userId) {
+        return { kind: 'no-session', reason: 'no_session' };
+      }
+      const next: PersistedAuthState = {
+        sessionId: bundle.sessionId,
+        refreshToken: bundle.refreshToken,
+        userId,
+        deviceToken: fragment.deviceToken,
+        accessToken: bundle.accessToken,
+        expiresAt: bundle.expiresAt,
+      };
+      await deps.store.save(next);
+      deps.plantAccessToken(bundle.accessToken);
+      return {
+        kind: 'session',
+        session: { sessionId: bundle.sessionId, userId, accessToken: bundle.accessToken },
+      };
+    } catch {
+      // The code burned/expired between hop and exchange — resolve signed-out
+      // rather than throwing (the once-ever hop already fired; do not retry).
+      return { kind: 'no-session', reason: 'no_session' };
+    }
+  }
+
+  return { kind: 'no-session', reason: fragment.reason };
+}

package/src/crypto/__tests__/sharedDeviceToken.test.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared device-token contract on web. Under the jest `node` environment
+ * `getPlatformOS()` resolves to `'web'`, so the shared-keychain device-token
+ * methods are no-ops (web persists its deviceToken in the per-origin
+ * AuthStateStore instead of a keychain). The native keychain plumbing is
+ * exercised via spies in the coldBootV2 suite.
+ */
+import { KeyManager } from '../keyManager';
+
+describe('KeyManager shared device token (web)', () => {
+  it('getSharedDeviceToken returns null on web', async () => {
+    expect(await KeyManager.getSharedDeviceToken()).toBeNull();
+  });
+
+  it('setSharedDeviceToken is a no-op that does not throw on web', async () => {
+    await expect(KeyManager.setSharedDeviceToken('dt-web')).resolves.toBeUndefined();
+    // Still null — nothing was persisted on web.
+    expect(await KeyManager.getSharedDeviceToken()).toBeNull();
+  });
+
+  it('clearSharedDeviceToken is a no-op that does not throw on web', async () => {
+    await expect(KeyManager.clearSharedDeviceToken()).resolves.toBeUndefined();
+  });
+});