@oxyhq/core 8.0.0 → 9.0.0

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

@@ -4,12 +4,8 @@
  * The client FAPI auto-detection helper was removed in the device-first cutover
  * (which is why this file is now named for what it actually is, not the old
  * `fapiAutoDetect`). What survives is the pure registrable-domain kernel, still
- * used server-side by the api's device-first same-apex trust checks
- * (`deviceAuth.ts`'s `POST /auth/device/web-session`, via `sameSite.ts`'s
- * `isSameSiteTrustedRequest`) and the `@oxyhq/core/server` CORS/re-export layer.
- *
- * `registrableApex` is NOT legacy — the device-first same-apex check is a live
- * consumer, so this kernel stays regardless of the SSO/FedCM removal.
+ * used by the `@oxyhq/core/server` CORS layer (the `*.oxy.so` same-apex trust
+ * check) and its re-export surface.
  */
 /**
  * Compute the bare registrable apex (eTLD+1) of a hostname using the Public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.11.0",
+    "@oxyhq/contracts": "^0.13.0",
     "@oxyhq/protocol": "^0.1.2",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/HttpService.ts

@@ -74,13 +74,13 @@ export interface RequestOptions {
    * Skip BOTH the bearer auth header (and its near-expiry preflight refresh)
    * AND the 401-driven auto-refresh/retry for this request.
    *
-   * Required for the body-authenticated refresh endpoint (`POST
-   * /auth/refresh-token`): it does not need a bearer, and — critically — it is
+   * Required for the body-authenticated device-secret mint (`POST
+   * /session/device/token`): it does not need a bearer, and — critically — it is
    * itself invoked from inside the registered `AuthRefreshHandler`. If it went
    * through the normal preflight, `getAuthHeader` would call
    * `refreshAccessToken` while the handler-owning `tokenRefreshPromise` is
    * still in flight and await ITSELF (deadlock). Skipping auth makes the
-   * refresh call fully independent of the current (near-expired) bearer.
+   * mint call fully independent of the current (near-expired) bearer.
    */
   skipAuth?: boolean;
 }

package/src/boot/__tests__/coldBootV2.test.ts

@@ -1,261 +1,215 @@
+/**
+ * Cold boot v3 (`runSessionColdBoot`) — the zero-cookie, DOM-less device-first
+ * boot. Only two ordered steps remain:
+ *   1. `device-secret-mint` (web + native) — mint an access token from the
+ *      persisted `deviceId` + `deviceSecret`.
+ *   2. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
+ * Anything unresolved ends signed out (never a redirect).
+ */
 import type { OxyServices } from '../../OxyServices';
-import type { AuthTokenBundle, TokenRefreshResponse, WebSessionResult } from '@oxyhq/contracts';
+import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../../models/session';
-import {
-  runSessionColdBoot,
-  createBrowserColdBootDom,
-  isSameApex,
-  BOOT_ATTEMPTED_KEY,
-  type ColdBootDom,
-} from '../coldBootV2';
-import { BOOT_STATE_SESSION_KEY } from '../deviceBootReturn';
-import { createMemoryAuthStateStore, type AuthStateStore } from '../../session/authStateStore';
-import { KeyManager } from '../../crypto/keyManager';
-
-const BUNDLE: AuthTokenBundle = {
-  sessionId: 'sess-boot',
-  accessToken: 'access-boot',
-  refreshToken: 'refresh-boot-abcdefghij',
-  expiresAt: '2030-01-01T00:00:00.000Z',
-  user: { id: 'user-boot', name: {} } as AuthTokenBundle['user'],
-};
-
-const ROTATED: TokenRefreshResponse = {
-  accessToken: 'access-rot',
-  refreshToken: 'refresh-rot-abcdefghij',
-  expiresAt: '2030-01-01T00:00:00.000Z',
-  sessionId: 'sess-rot',
-};
+import { runSessionColdBoot } from '../coldBootV2';
+import { createMemoryAuthStateStore, type PersistedAuthState } from '../../session/authStateStore';
 
 interface OxyOverrides {
-  baseURL?: string;
-  exchangeBootCode?: OxyServices['exchangeBootCode'];
-  refreshWithToken?: OxyServices['refreshWithToken'];
   signInWithSharedIdentity?: OxyServices['signInWithSharedIdentity'];
-  issueNativeDeviceToken?: OxyServices['issueNativeDeviceToken'];
-  requestWebSession?: OxyServices['requestWebSession'];
+  mintFromDeviceSecret?: OxyServices['mintFromDeviceSecret'];
 }
 
 function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: jest.Mock } {
   const setTokens = jest.fn();
   const oxy = {
-    getBaseURL: () => overrides.baseURL ?? 'https://api.oxy.so',
+    getBaseURL: () => 'https://api.oxy.so',
     setTokens,
-    exchangeBootCode: overrides.exchangeBootCode ?? (async () => BUNDLE),
-    refreshWithToken: overrides.refreshWithToken ?? (async () => ROTATED),
     signInWithSharedIdentity: overrides.signInWithSharedIdentity ?? (async () => null),
-    issueNativeDeviceToken: overrides.issueNativeDeviceToken ?? (async () => 'native-device-token'),
-    requestWebSession:
-      overrides.requestWebSession
-      ?? (async () => ({ reason: 'no_session', deviceToken: 'dt-web' }) as WebSessionResult),
-    buildBootstrapUrl: (returnTo: string, state: string) =>
-      `https://api.oxy.so/auth/device/bootstrap?return_to=${encodeURIComponent(returnTo)}&state=${state}`,
+    // Default: no persisted secret in these fixtures, so the mint step skips
+    // before ever calling this. Tests that exercise the mint pass an override.
+    mintFromDeviceSecret:
+      overrides.mintFromDeviceSecret
+      ?? (async () => {
+        throw new Error('mintFromDeviceSecret not stubbed');
+      }),
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }
 
-interface DomHandle {
-  dom: ColdBootDom;
-  navigate: jest.Mock;
-  strip: jest.Mock;
-  session: Map<string, string>;
-  local: Map<string, string>;
-}
+const MINT: DeviceTokenMintResponse = {
+  accessToken: 'access-minted',
+  expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+  nextDeviceSecret: 'ds-next-secret',
+  state: {
+    deviceId: 'dev-mint',
+    accounts: [{ accountId: 'user-mint', sessionId: 'sess-mint', authuser: 0 }],
+    activeAccountId: 'user-mint',
+    revision: 2,
+    updatedAt: 1_700_000_000_000,
+  },
+};
 
-function makeDom(opts: { hash?: string; hostname?: string; sessionState?: string; attempted?: boolean } = {}): DomHandle {
-  const session = new Map<string, string>();
-  const local = new Map<string, string>();
-  if (opts.sessionState !== undefined) session.set(BOOT_STATE_SESSION_KEY, opts.sessionState);
-  if (opts.attempted) local.set(BOOT_ATTEMPTED_KEY, '1');
-  const navigate = jest.fn();
-  const strip = jest.fn();
-  const dom: ColdBootDom = {
-    getHash: () => opts.hash ?? '',
-    stripFragment: strip,
-    getSessionItem: (k) => session.get(k) ?? null,
-    setSessionItem: (k, v) => {
-      session.set(k, v);
-    },
-    removeSessionItem: (k) => {
-      session.delete(k);
-    },
-    getLocalItem: (k) => local.get(k) ?? null,
-    setLocalItem: (k, v) => {
-      local.set(k, v);
-    },
-    getLocationHostname: () => opts.hostname ?? 'accounts.oxy.so',
-    getReturnToHref: () => 'https://accounts.oxy.so/home',
-    navigate,
-    randomState: () => 'state-fixed-1234',
-  };
-  return { dom, navigate, strip, session, local };
+/** A 401 error shaped like `HttpService`/`handleError` output for the given body. */
+function mint401(body: string): Error & { status: number } {
+  return Object.assign(new Error(body), { status: 401 });
 }
 
 const WEB = { isWeb: true, isNative: false };
 const NATIVE = { isWeb: false, isNative: true };
 
-describe('isSameApex', () => {
-  it('groups by registrable domain', () => {
-    expect(isSameApex('accounts.oxy.so', 'api.oxy.so')).toBe(true);
-    expect(isSameApex('oxy.so', 'api.oxy.so')).toBe(true);
-    expect(isSameApex('app.mention.earth', 'api.oxy.so')).toBe(false);
-    expect(isSameApex('homiio.com', 'api.oxy.so')).toBe(false);
-  });
+/** Seed a store with the zero-cookie mint credential. */
+function seedCredStore(extra: Partial<PersistedAuthState> = {}) {
+  const store = createMemoryAuthStateStore();
+  return {
+    store,
+    seed: async () => {
+      await store.save({
+        sessionId: 'sess-old',
+        userId: 'user-old',
+        deviceId: 'dev-mint',
+        deviceSecret: 'ds-secret-orig',
+        ...extra,
+      });
+    },
+  };
+}
 
-  it('does NOT collapse distinct IPv4 hosts that share trailing octets', () => {
-    // The last-2-labels heuristic would map both to "1.1" — must be exact.
-    expect(isSameApex('192.168.1.1', '10.0.1.1')).toBe(false);
-    expect(isSameApex('192.168.1.10', '192.168.1.5')).toBe(false);
-    expect(isSameApex('192.168.1.5', '192.168.1.5')).toBe(true);
-  });
+describe('runSessionColdBoot — device-secret-mint', () => {
+  it('wins FIRST via the mint, persisting nextDeviceSecret BEFORE planting the token', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+    const saveSpy = jest.spyOn(store, 'save');
+    const onSession = jest.fn();
 
-  it('requires exact equality for single-label / IPv6 / localhost hosts', () => {
-    expect(isSameApex('localhost', 'localhost')).toBe(true);
-    expect(isSameApex('localhost', 'api.oxy.so')).toBe(false);
-    expect(isSameApex('::1', '::1')).toBe(true);
-    expect(isSameApex('fe80::1', 'fe80::2')).toBe(false);
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSession });
+
+    expect(outcome).toEqual({ kind: 'session', via: 'device-secret-mint', session: expect.any(Object) });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith('dev-mint', 'ds-secret-orig');
+    expect(setTokens).toHaveBeenCalledWith('access-minted');
+    // Session identity comes from the mint's authoritative active account.
+    expect(onSession).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: 'sess-mint', userId: 'user-mint', via: 'device-secret-mint' }),
+    );
+    // Rotation-in-use anti-loss: the store held the NEXT secret before the plant.
+    const lastSaveOrder = Math.max(...saveSpy.mock.invocationCallOrder);
+    const firstPlantOrder = Math.min(...setTokens.mock.invocationCallOrder);
+    expect(lastSaveOrder).toBeLessThan(firstPlantOrder);
+    expect(await store.load()).toMatchObject({
+      deviceId: 'dev-mint',
+      deviceSecret: 'ds-next-secret',
+      sessionId: 'sess-mint',
+      userId: 'user-mint',
+      accessToken: 'access-minted',
+    });
   });
-});
 
-describe('runSessionColdBoot — step ordering', () => {
-  it('stored-tokens warm-plants a still-valid access token before any hop', async () => {
-    const store = createMemoryAuthStateStore();
-    await store.save({
-      sessionId: 'sess-warm',
-      refreshToken: 'r-abcdefghij',
-      userId: 'user-warm',
-      accessToken: 'warm-token',
-      expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
-    });
-    const { oxy, setTokens } = makeOxy();
-    const requestWebSession = jest.spyOn(oxy, 'requestWebSession');
-    const onSession = jest.fn();
+  it('mints on native too (the step runs on both platforms)', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret, signInWithSharedIdentity });
 
-    const outcome = await runSessionColdBoot({
-      oxy, store, platform: WEB, dom: makeDom().dom, onSession,
-    });
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE });
 
-    expect(outcome).toEqual({ kind: 'session', via: 'stored-tokens', session: expect.any(Object) });
-    expect(setTokens).toHaveBeenCalledWith('warm-token');
-    expect(onSession).toHaveBeenCalledWith(expect.objectContaining({ userId: 'user-warm', via: 'stored-tokens' }));
-    expect(requestWebSession).not.toHaveBeenCalled();
+    expect(outcome).toMatchObject({ kind: 'session', via: 'device-secret-mint' });
+    expect(setTokens).toHaveBeenCalledWith('access-minted');
+    // The mint won first — the shared-key fallback was never reached.
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
   });
 
-  it('stored-tokens rotates when the warm token is absent/expired', async () => {
+  it('skips (no mint) when only one of deviceId / deviceSecret is persisted', async () => {
     const store = createMemoryAuthStateStore();
-    await store.save({ sessionId: 'sess-old', refreshToken: 'r-abcdefghij', userId: 'user-1' });
-    const { oxy, setTokens } = makeOxy();
+    await store.save({ sessionId: 's', userId: 'u', deviceSecret: 'ds-only' });
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+    const onSignedOut = jest.fn();
 
-    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: makeDom().dom });
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSignedOut });
 
-    expect(outcome.kind).toBe('session');
-    expect(setTokens).toHaveBeenCalledWith('access-rot');
-    expect(await store.load()).toMatchObject({ sessionId: 'sess-rot', refreshToken: 'refresh-rot-abcdefghij' });
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    // Nothing else can resolve on web → signed out.
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
   });
 
-  it('bootstrap-return wins over later steps when a valid fragment is present', async () => {
-    const store = createMemoryAuthStateStore();
-    // A base64url fragment carrying reason:session + matching state.
-    const frag = {
-      v: 1,
-      state: 'state-match',
-      reason: 'session',
-      code: 'c'.repeat(24),
-      deviceToken: 'd'.repeat(24),
-    };
-    const b64 = Buffer.from(JSON.stringify(frag), 'utf-8')
-      .toString('base64')
-      .replace(/\+/g, '-')
-      .replace(/\//g, '_')
-      .replace(/=+$/, '');
-    const domHandle = makeDom({ hash: `#oxy_boot=${b64}`, sessionState: 'state-match' });
-    const { oxy, setTokens } = makeOxy();
-    const onSession = jest.fn();
-
-    const outcome = await runSessionColdBoot({
-      oxy, store, platform: WEB, dom: domHandle.dom, onSession,
+  it('401 invalid_device_secret → drops the secret (keeps deviceId) and ends signed out on web', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw mint401('invalid_device_secret');
     });
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+    const onSignedOut = jest.fn();
 
-    expect(outcome).toEqual({ kind: 'session', via: 'bootstrap-return', session: expect.any(Object) });
-    expect(domHandle.strip).toHaveBeenCalled();
-    expect(setTokens).toHaveBeenCalledWith('access-boot');
-    expect(onSession).toHaveBeenCalledWith(expect.objectContaining({ via: 'bootstrap-return' }));
-  });
-});
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSignedOut });
 
-describe('runSessionColdBoot — bootstrap-hop (web)', () => {
-  it('same-apex: resolves a session via the inline web-session fetch (no navigation)', async () => {
-    const store = createMemoryAuthStateStore();
-    // The EXACT post-unwrap server shape (PR #526): a reason-`session` envelope
-    // nesting the bundle under `session` plus the rotated deviceToken.
-    const sessionEnvelope: WebSessionResult = { reason: 'session', session: BUNDLE, deviceToken: 'dt-rotated' };
-    const requestWebSession = jest.fn(async () => sessionEnvelope);
-    const { oxy, setTokens } = makeOxy({ requestWebSession });
-    const domHandle = makeDom({ hostname: 'accounts.oxy.so' });
-
-    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom });
-
-    expect(outcome).toEqual({ kind: 'session', via: 'bootstrap-hop', session: expect.any(Object) });
-    expect(requestWebSession).toHaveBeenCalledTimes(1);
-    expect(setTokens).toHaveBeenCalledWith('access-boot');
-    expect(domHandle.navigate).not.toHaveBeenCalled();
-    expect(await store.load()).toMatchObject({ sessionId: 'sess-boot', refreshToken: 'refresh-boot-abcdefghij' });
-    // deviceToken from the SAME envelope is persisted on the session arm too.
-    expect(await store.loadDeviceToken()).toBe('dt-rotated');
+    expect(mintFromDeviceSecret).toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+    const persisted = await store.load();
+    expect(persisted?.deviceSecret).toBeUndefined();
+    expect(persisted?.deviceId).toBe('dev-mint');
   });
 
-  it('same-apex: signed-out device persists the deviceToken and reports signed out', async () => {
-    const store = createMemoryAuthStateStore();
-    const requestWebSession = jest.fn(async () => ({ reason: 'no_session', deviceToken: 'dt-web' }) as WebSessionResult);
-    const { oxy } = makeOxy({ requestWebSession });
-    const domHandle = makeDom({ hostname: 'accounts.oxy.so' });
+  it('401 no_active_session → keeps the secret and reports signed out', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw mint401('no_active_session');
+    });
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy } = makeOxy({ mintFromDeviceSecret, signInWithSharedIdentity });
     const onSignedOut = jest.fn();
 
-    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom, onSignedOut });
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSignedOut });
 
     expect(outcome).toEqual({ kind: 'unauthenticated' });
     expect(onSignedOut).toHaveBeenCalledWith('no_session');
-    expect(await store.loadDeviceToken()).toBe('dt-web');
-    expect(domHandle.navigate).not.toHaveBeenCalled();
+    // The known-signed-out device retains its secret (it may sign in again).
+    expect((await store.load())?.deviceSecret).toBe('ds-secret-orig');
+    // Web has no shared-key lane.
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
   });
 
-  it('cross-apex: navigates ONCE, stashing state + the attempted flag', async () => {
-    const store = createMemoryAuthStateStore();
-    const { oxy } = makeOxy();
-    const domHandle = makeDom({ hostname: 'app.mention.earth' });
+  it('classifies a PLAIN-OBJECT 401 (no Error prototype) — no_active_session still keeps the secret', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    // Cross-realm / ApiError-shaped throw: not `instanceof Error`. Must still be
+    // read as no_active_session — misreading it as a stale secret would drop it.
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw { status: 401, message: 'no_active_session' };
+    });
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
     const onSignedOut = jest.fn();
-    const onSession = jest.fn();
 
-    await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom, onSignedOut, onSession });
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSignedOut });
 
-    expect(domHandle.navigate).toHaveBeenCalledTimes(1);
-    expect(domHandle.navigate).toHaveBeenCalledWith(expect.stringContaining('/auth/device/bootstrap?return_to='));
-    expect(domHandle.session.get(BOOT_STATE_SESSION_KEY)).toBe('state-fixed-1234');
-    expect(domHandle.local.get(BOOT_ATTEMPTED_KEY)).toBe('1');
-    // Navigating away — neither callback fires (no signed-out flash).
-    expect(onSignedOut).not.toHaveBeenCalled();
-    expect(onSession).not.toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+    expect((await store.load())?.deviceSecret).toBe('ds-secret-orig');
   });
 
-  it('cross-apex: NEVER navigates a second time once the attempted flag is set', async () => {
-    const store = createMemoryAuthStateStore();
-    const { oxy } = makeOxy();
-    const domHandle = makeDom({ hostname: 'app.mention.earth', attempted: true });
+  it('transient (non-401) mint error → keeps the secret and reports signed out on web', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw new Error('network down');
+    });
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
     const onSignedOut = jest.fn();
 
-    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom, onSignedOut });
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSignedOut });
 
-    expect(domHandle.navigate).not.toHaveBeenCalled();
     expect(outcome).toEqual({ kind: 'unauthenticated' });
     expect(onSignedOut).toHaveBeenCalledWith('no_session');
+    // The secret survives a transient failure so a later attempt can succeed.
+    expect((await store.load())?.deviceSecret).toBe('ds-secret-orig');
   });
-});
-
-describe('runSessionColdBoot — native shared-key', () => {
-  afterEach(() => jest.restoreAllMocks());
 
-  it('re-mints via shared identity and issues + mirrors a deviceToken the first time', async () => {
-    const store = createMemoryAuthStateStore();
+  it('a dropped secret (401) on native falls through to the shared-key lane', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
     const sharedSession: SessionLoginResponse = {
       sessionId: 'sess-shared',
       deviceId: 'dev-1',
@@ -263,55 +217,102 @@ describe('runSessionColdBoot — native shared-key', () => {
       user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
       accessToken: 'access-shared',
     };
-    const issueNativeDeviceToken = jest.fn(async () => 'fresh-device-token');
-    const { oxy } = makeOxy({
-      signInWithSharedIdentity: async () => sharedSession,
-      issueNativeDeviceToken,
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw mint401('invalid_device_secret');
     });
-    const getShared = jest.spyOn(KeyManager, 'getSharedDeviceToken').mockResolvedValue(null);
-    const setShared = jest.spyOn(KeyManager, 'setSharedDeviceToken').mockResolvedValue(undefined);
-    const requestWebSession = jest.spyOn(oxy, 'requestWebSession');
+    const signInWithSharedIdentity = jest.fn(async () => sharedSession);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret, signInWithSharedIdentity });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE });
+
+    expect(outcome).toEqual({ kind: 'session', via: 'shared-key-signin', session: expect.any(Object) });
+    expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+    // The mint lane still dropped the stale secret before falling through.
+    expect((await store.load())?.deviceSecret).toBeUndefined();
+    // Shared-key plants tokens itself (via verifyChallenge); the cold boot does not.
+    expect(setTokens).not.toHaveBeenCalled();
+  });
+});
+
+describe('runSessionColdBoot — shared-key-signin (native)', () => {
+  const sharedSession: SessionLoginResponse = {
+    sessionId: 'sess-shared',
+    deviceId: 'dev-1',
+    expiresAt: '2030-01-01T00:00:00.000Z',
+    user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
+    accessToken: 'access-shared',
+  };
 
-    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE, dom: makeDom().dom });
+  it('re-mints via the shared identity when there is no persisted mint credential', async () => {
+    const store = createMemoryAuthStateStore(); // no deviceId/deviceSecret
+    const signInWithSharedIdentity = jest.fn(async () => sharedSession);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+    const onSession = jest.fn();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE, onSession });
 
     expect(outcome).toEqual({ kind: 'session', via: 'shared-key-signin', session: expect.any(Object) });
-    expect(getShared).toHaveBeenCalled();
-    expect(issueNativeDeviceToken).toHaveBeenCalled();
-    expect(setShared).toHaveBeenCalledWith('fresh-device-token');
-    expect(await store.loadDeviceToken()).toBe('fresh-device-token');
-    // bootstrap-hop is web-only — never runs on native.
-    expect(requestWebSession).not.toHaveBeenCalled();
+    expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+    expect(onSession).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: 'sess-shared', userId: 'user-shared', via: 'shared-key-signin' }),
+    );
   });
 
-  it('skips device-token issuance when the shared token already exists', async () => {
+  it('does NOT run the shared-key lane on web', async () => {
     const store = createMemoryAuthStateStore();
-    const issueNativeDeviceToken = jest.fn(async () => 'unused');
-    const { oxy } = makeOxy({
-      signInWithSharedIdentity: async () => ({
-        sessionId: 'sess-shared',
-        deviceId: 'dev-1',
-        expiresAt: '2030-01-01T00:00:00.000Z',
-        user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
-        accessToken: 'access-shared',
-      }),
-      issueNativeDeviceToken,
+    const signInWithSharedIdentity = jest.fn(async () => sharedSession);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSignedOut });
+
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+  });
+
+  it('reports signed out when the shared identity yields no session', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE, onSignedOut });
+
+    expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+  });
+
+  it('reports a step error (onStepError + signed-out reason `error`) when the shared identity throws', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => {
+      throw new Error('keychain locked');
     });
-    jest.spyOn(KeyManager, 'getSharedDeviceToken').mockResolvedValue('already-there');
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+    const onSignedOut = jest.fn();
+    const onStepError = jest.fn();
 
-    await runSessionColdBoot({ oxy, store, platform: NATIVE, dom: makeDom().dom });
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE, onSignedOut, onStepError });
 
-    expect(issueNativeDeviceToken).not.toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onStepError).toHaveBeenCalledWith('shared-key-signin', expect.any(Error));
+    expect(onSignedOut).toHaveBeenCalledWith('error');
   });
 });
 
-describe('createBrowserColdBootDom', () => {
-  it('returns neutral values under the jest node environment (no window)', () => {
-    const dom = createBrowserColdBootDom();
-    expect(dom.getHash()).toBe('');
-    expect(dom.getLocationHostname()).toBeNull();
-    expect(dom.getSessionItem('x')).toBeNull();
-    expect(() => dom.stripFragment()).not.toThrow();
-    expect(() => dom.navigate('https://x')).not.toThrow();
-    expect(dom.randomState()).toMatch(/^[0-9a-f]+$/);
+describe('runSessionColdBoot — signed out', () => {
+  it('reports signed out when the store is empty and no lane resolves (web)', async () => {
+    const store = createMemoryAuthStateStore();
+    const { oxy, setTokens } = makeOxy();
+    const onSession = jest.fn();
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, onSession, onSignedOut });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+    expect(onSession).not.toHaveBeenCalled();
+    expect(setTokens).not.toHaveBeenCalled();
   });
 });