@oxyhq/core 12.10.6 → 12.11.0

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

@@ -1,6 +1,8 @@
 import type { OxyServices } from '../OxyServices';
 import type { AuthRefreshHandler } from '../HttpService';
 import type { AuthStateStore } from './authStateStore';
+import type { IdentityPin } from './identityPin';
+import { type IdentityBinding } from './identitySession';
 /**
  * Lead time (ms) before access-token expiry at which the proactive scheduler
  * re-mints. Mirrors `HttpService`'s per-request `TOKEN_REFRESH_LEAD_SECONDS`
@@ -14,9 +16,19 @@ export interface RefreshDeps {
     /**
      * Whether to fall back to the native shared-keychain re-mint (arm 2) when the
      * persisted secret is absent / rejected. Defaults to `isNative()` — web has no
-     * shared keychain. Exposed for tests.
+     * shared keychain. Exposed for tests. IGNORED when {@link identity} is set: an
+     * identity-bound client must never adopt the CROSS-APP shared slot, which may
+     * hold a different identity than this device's primary key.
      */
     allowSharedKeyFallback?: boolean;
+    /**
+     * Identity-bound (pinned) mode. When present, every re-mint targets the
+     * PINNED account — resolved fresh from the pin store on each call, since a
+     * re-established session can move it — instead of the device's active
+     * account, and arm 2 becomes the PRIMARY-key identity sign-in rather than the
+     * shared-keychain one.
+     */
+    identity?: IdentityBinding;
 }
 /**
  * The outcome of ONE device-secret mint attempt (arm 1). Discriminated so both
@@ -28,6 +40,10 @@ export interface RefreshDeps {
  *    diverged (another tab/device rotated it past the grace window).
  *  - `no-session` — 401 `no_active_session`: the device is known but has no live
  *    session (authoritative signed-out).
+ *  - `account-not-on-device` — 401 `account_not_on_device` for a PINNED mint: the
+ *    pinned account is not (or no longer) a live account of this device session.
+ *    The device secret is FINE — it is the identity binding that went stale, so
+ *    the caller must re-establish from the local key, never drop the credential.
  *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
  *  - `persist-failed` — the mint succeeded (the SERVER rotated the secret) but
  *    the rotated `nextDeviceSecret` could NOT be durably persisted. The token is
@@ -45,6 +61,8 @@ export type DeviceSecretMintOutcome = {
     status: 'invalid-secret';
 } | {
     status: 'no-session';
+} | {
+    status: 'account-not-on-device';
 } | {
     status: 'transient';
 } | {
@@ -70,10 +88,18 @@ export type DeviceSecretMintOutcome = {
  * 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 declare function refreshDeviceSecretArm(deps: {
     oxy: OxyServices;
     store: AuthStateStore;
+    /** The identity pin, when this client is identity-bound. */
+    pin?: IdentityPin | null;
 }): Promise<DeviceSecretMintOutcome>;
 /**
  * Re-mint the persisted session and return the fresh access token, or `null`
@@ -91,6 +117,11 @@ export declare function refreshDeviceSecretArm(deps: {
  * 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 declare function refreshPersistedSession(deps: RefreshDeps): Promise<string | null>;
 /**

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

@@ -0,0 +1,105 @@
+/**
+ * Automatic "Sign in with Oxy" delivery selection (issue #691, Phase 4).
+ *
+ * The user performs ONE action ("Continue with Oxy"); Oxy — not the user —
+ * decides how the approval request reaches their Commons identity. This module
+ * is that decision, and nothing else: a single pure function mapping the facts
+ * the caller has gathered onto exactly ONE primary route.
+ *
+ * Deliberate design constraints:
+ *
+ *  - **Pure.** No I/O, no platform sniffing, no clock, no globals. Every input
+ *    is passed in by the caller, which is what makes the decision exhaustively
+ *    unit-testable and identical on web, native, and server.
+ *  - **One route, never a chain.** The result is the PRIMARY route only.
+ *    Alternatives stay hidden behind a "Having trouble?" affordance and are
+ *    revealed by the UI only once the primary route fails or is unavailable —
+ *    the SDK never silently cascades from one delivery surface to the next.
+ *  - **Fail-safe to QR.** QR is the route that works with no prior knowledge of
+ *    the device, so every ambiguous or malformed input degrades to it rather
+ *    than to a route that could leave the user staring at a dead end.
+ *
+ * Every route drives the SAME `AuthSession`, resolved from the same public
+ * `authorizeCode`; the route only decides how that code travels.
+ */
+/**
+ * The kind of surface the sign-in was initiated from.
+ *
+ * `'unknown'` is a first-class value, not an error: a caller that cannot
+ * confidently classify the surface must say so rather than guess, and an
+ * unknown surface never opts into the deep-link route (a custom-scheme
+ * navigation that does not resolve is a dead end with no automatic way back).
+ */
+export type CommonsDeliveryPlatform = 'mobile' | 'desktop' | 'unknown';
+/**
+ * The single primary route chosen for this request.
+ *
+ *  - `'open-commons'` — navigate to the verified Commons app/universal link on
+ *    THIS device and let the user confirm there.
+ *  - `'await-push'` — the request was pushed to a known Commons installation;
+ *    show "Check Commons on your phone" and wait for the authorization.
+ *  - `'qr'` — render the QR carrying the public `authorizeCode` for the user to
+ *    scan with Commons on another device.
+ */
+export type CommonsDeliveryRoute = 'open-commons' | 'await-push' | 'qr';
+/**
+ * The facts the caller must gather before asking for a route. All of them are
+ * observations, never decisions — the caller owns the platform detection, the
+ * app-link verification, and the delivery round-trip; this module owns only the
+ * choice between them.
+ */
+export interface CommonsDeliveryFacts {
+    /** Which surface the sign-in was initiated from (see {@link CommonsDeliveryPlatform}). */
+    platform: CommonsDeliveryPlatform;
+    /**
+     * `true` only when a VERIFIED Commons app/universal link can be opened on
+     * this very device (an installed, link-verified Commons). "The user probably
+     * has Commons somewhere" is not this fact — that is what `pushTargets`
+     * expresses.
+     */
+    commonsAvailable: boolean;
+    /**
+     * How many eligible Commons installations the server said it delivered the
+     * request to — the `targets` field of `deliverCommonsSignIn`. Zero is a
+     * NORMAL outcome (no capable Commons install is registered for this
+     * identity), never an error; it simply means push is not a usable route.
+     */
+    pushTargets: number;
+}
+/**
+ * Choose the ONE primary delivery route for a "Sign in with Oxy" request.
+ *
+ * Decision order (issue #691, "Automatic delivery selection"):
+ *
+ *  1. Mobile with a verified Commons link available → open Commons directly.
+ *     No push is needed when the identity is already reachable on this device.
+ *  2. At least one eligible Commons installation was pushed to → await the push.
+ *  3. Otherwise → QR.
+ *
+ * A caller that already knows it is on step 1 does not need to call
+ * `deliverCommonsSignIn` at all; every other caller runs the delivery
+ * round-trip first and passes its `targets` in here.
+ *
+ * `pushTargets` is server-derived, so it is validated rather than trusted: a
+ * negative, fractional, non-finite, or otherwise malformed count is treated as
+ * "no targets" and degrades to QR instead of parking the user on a "check your
+ * phone" screen that nothing will ever wake.
+ */
+export declare function selectCommonsDelivery(facts: CommonsDeliveryFacts): CommonsDeliveryRoute;
+/**
+ * Map a `deliverCommonsSignIn` result onto the `pushTargets` fact for
+ * {@link selectCommonsDelivery}. The server reports eligible install *count*
+ * separately from whether any push was accepted — a transport failure can leave
+ * `delivered: false` with `targets > 0`, which must NOT park the user on
+ * "check your phone".
+ */
+export declare function pushTargetsFromDelivery(result: {
+    delivered: boolean;
+    targets: number;
+}): number;
+/**
+ * Classify the current runtime surface for delivery selection. Callers that
+ * cannot confidently detect the platform should not use this — pass
+ * `'unknown'` explicitly instead.
+ */
+export declare function commonsDeliveryPlatform(): CommonsDeliveryPlatform;

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

@@ -47,6 +47,18 @@ export interface BuildOAuthAuthorizeUrlParams {
      * (no UI when the IdP hub already has a session + grant).
      */
     prompt?: 'none' | 'login' | 'consent';
+    /**
+     * How the IdP should deliver the authorization response. Omitted (the
+     * default) means the ordinary top-level redirect back to `redirectUri`.
+     *
+     * `web_message` asks the IdP to `postMessage` the result to its opener
+     * instead, so a popup sign-in never navigates the relying party's tab. It is
+     * a REQUEST, not a guarantee: an IdP with no opener still redirects, which is
+     * why the popup transport must handle both outcomes. Only the authorization
+     * code, the `state`, and a typed OAuth error ever cross that channel — never
+     * a token, device secret, or the PKCE verifier, which the opener keeps.
+     */
+    responseMode?: 'web_message';
 }
 /**
  * Compute the PKCE S256 `code_challenge` for a given verifier:
@@ -81,6 +93,8 @@ export declare function buildOAuthAuthorizeUrl(params: BuildOAuthAuthorizeUrlPar
 export declare const OXY_OAUTH_STATE_STORAGE_KEY = "oxy_oauth_state";
 /** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
 export declare const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = "oxy_oauth_code_verifier";
+/** `sessionStorage` key — the exact `redirect_uri` sent on the authorize request. */
+export declare const OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = "oxy.oauth_redirect_uri";
 /** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
 export declare const OXY_SILENT_OAUTH_ATTEMPTED_KEY = "oxy.silent_oauth_attempted";
 /** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
@@ -100,6 +114,11 @@ export declare const OXY_OAUTH_RETURN_PATH_STORAGE_KEY = "oxy.oauth_return_path"
  * out-of-band and restored on return.
  */
 export declare function normalizeOAuthRedirectUri(input: string): string;
+/**
+ * Collapse `https://app.example/` → `https://app.example` for OAuth binding.
+ * Path-qualified redirect URIs are preserved — matches the API token exchange.
+ */
+export declare function canonicalizeOAuthRedirectUri(redirectUri: string): string;
 /**
  * Remember the page the user was on before a full-page authorize redirect.
  *
@@ -123,11 +142,12 @@ export declare function persistOAuthReturnPath(path: string): void;
  */
 export declare function consumeOAuthReturnPath(): string | null;
 /** Persist the OAuth handshake for a full-page redirect return (web only). */
-export declare function persistOAuthHandshake(state: string, codeVerifier: string): boolean;
+export declare function persistOAuthHandshake(state: string, codeVerifier: string, redirectUri?: string): boolean;
 /** Read the persisted OAuth handshake, or `null` when absent. */
 export declare function readOAuthHandshake(): {
     state: string;
     codeVerifier: string;
+    redirectUri?: string;
 } | null;
 /** Drop persisted OAuth handshake keys after a successful or aborted return. */
 export declare function clearOAuthHandshake(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.10.6",
+  "version": "12.11.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,7 +115,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.17.0",
+    "@oxyhq/contracts": "^0.18.0",
     "@oxyhq/protocol": "^0.1.5",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/boot/__tests__/sessionColdBoot.identity.test.ts

@@ -0,0 +1,393 @@
+/**
+ * Cold boot in IDENTITY mode — the identity vault's boot.
+ *
+ * Invariants under test:
+ *   - a persisted warm token that belongs to ANOTHER account is never planted;
+ *     the boot falls through to the PINNED mint instead;
+ *   - the mint carries the pinned `accountId`, and the resolved session is the
+ *     pinned account even while the device is switched elsewhere;
+ *   - `identity-key-signin` (the PRIMARY local key) replaces `shared-key-signin`
+ *     (the CROSS-APP shared slot) — and the reverse in account mode;
+ *   - with no verified pin the (unpinned) mint lane is skipped entirely rather
+ *     than adopting whichever account the device is currently switched to.
+ */
+import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
+import type { OxyServices } from '../../OxyServices';
+import type { SessionLoginResponse } from '../../models/session';
+import type { AuthChallenge } from '../../crypto/signatureService';
+import { runSessionColdBoot } from '../sessionColdBoot';
+import type { DeviceSecretMintOutcome } from '../../session/refresh';
+import { createMemoryAuthStateStore, type PersistedAuthState } from '../../session/authStateStore';
+import { createMemoryIdentityPinStore, type IdentityPin } from '../../session/identityPin';
+import type { IdentityBinding } from '../../session/identitySession';
+
+const PUBLIC_KEY = `02${'a'.repeat(64)}`;
+const OTHER_PUBLIC_KEY = `03${'b'.repeat(64)}`;
+const PIN: IdentityPin = { publicKey: PUBLIC_KEY, accountId: 'vault-user' };
+
+const NATIVE = { isWeb: false, isNative: true };
+
+/** A minimal jwt-decode-able token whose `userId` claim is `accountId`. */
+function jwtFor(accountId: string): string {
+  const payload = Buffer.from(JSON.stringify({ userId: accountId })).toString('base64url');
+  return `h.${payload}.s`;
+}
+
+/** Comfortably beyond the 60s refresh lead window. */
+const farFuture = (): string => new Date(Date.now() + 3_600_000).toISOString();
+
+function makeMintSingleFlight(): (mint: () => Promise<DeviceSecretMintOutcome>) => Promise<DeviceSecretMintOutcome> {
+  let inFlight: Promise<DeviceSecretMintOutcome> | null = null;
+  return (mint) => {
+    if (!inFlight) {
+      inFlight = mint().finally(() => {
+        inFlight = null;
+      });
+    }
+    return inFlight;
+  };
+}
+
+/** The device is switched to `other-user`; the pinned account is still a member. */
+const MINT_WHILE_SWITCHED: DeviceTokenMintResponse = {
+  accessToken: jwtFor('vault-user'),
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  nextDeviceSecret: 'ds-next-secret',
+  state: {
+    deviceId: 'dev-1',
+    accounts: [
+      { accountId: 'vault-user', sessionId: 'sess-vault-new', authuser: 0 },
+      { accountId: 'other-user', sessionId: 'sess-other', authuser: 1 },
+    ],
+    activeAccountId: 'other-user',
+    revision: 9,
+    updatedAt: 1_700_000_000_000,
+  },
+};
+
+const IDENTITY_SESSION: SessionLoginResponse = {
+  sessionId: 'sess-identity',
+  deviceId: 'dev-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  accessToken: 'access-identity',
+  deviceSecret: 'ds-identity',
+  user: { id: 'vault-user', username: 'vault', name: {} },
+};
+
+const SHARED_SESSION: SessionLoginResponse = {
+  sessionId: 'sess-shared',
+  deviceId: 'dev-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  accessToken: 'access-shared',
+  user: { id: 'shared-user', username: 'shared', name: {} },
+};
+
+interface OxyOverrides {
+  mintFromDeviceSecret?: OxyServices['mintFromDeviceSecret'];
+  signInWithSharedIdentity?: OxyServices['signInWithSharedIdentity'];
+  requestChallenge?: OxyServices['requestChallenge'];
+  verifyChallenge?: OxyServices['verifyChallenge'];
+}
+
+function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: jest.Mock } {
+  const setTokens = jest.fn();
+  const oxy = {
+    getBaseURL: () => 'https://api.oxy.so',
+    setTokens,
+    mintFromDeviceSecret:
+      overrides.mintFromDeviceSecret
+      ?? (async () => {
+        throw new Error('mintFromDeviceSecret not stubbed');
+      }),
+    signInWithSharedIdentity: overrides.signInWithSharedIdentity ?? (async () => null),
+    requestChallenge:
+      overrides.requestChallenge
+      ?? (async () => ({ challenge: 'chal-1', expiresAt: '2030-01-01T00:00:00.000Z' })),
+    verifyChallenge: overrides.verifyChallenge ?? (async () => IDENTITY_SESSION),
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+  } as unknown as OxyServices;
+  return { oxy, setTokens };
+}
+
+function signWith(publicKey: string): (challenge: string) => Promise<AuthChallenge> {
+  return async (challenge) => ({
+    challenge: `sig(${challenge})`,
+    publicKey,
+    timestamp: 1_700_000_000_000,
+  });
+}
+
+/** An identity binding, optionally pre-seeded with a pin. */
+async function makeBinding(options: { pin?: IdentityPin; publicKey?: string } = {}): Promise<IdentityBinding> {
+  const publicKey = options.publicKey ?? PUBLIC_KEY;
+  const pinStore = createMemoryIdentityPinStore();
+  if (options.pin) {
+    await pinStore.save(options.pin);
+  }
+  return { pinStore, readPublicKey: async () => publicKey, signChallenge: signWith(publicKey) };
+}
+
+async function seedStore(extra: Partial<PersistedAuthState> = {}) {
+  const store = createMemoryAuthStateStore();
+  await store.save({
+    sessionId: 'sess-vault',
+    userId: 'vault-user',
+    deviceId: 'dev-1',
+    deviceSecret: 'ds-secret-orig',
+    ...extra,
+  });
+  return store;
+}
+
+describe('runSessionColdBoot — identity mode: warm-token-plant', () => {
+  it('plants a warm token that belongs to the pinned account', async () => {
+    const store = await seedStore({ accessToken: jwtFor('vault-user'), expiresAt: farFuture() });
+    const { oxy, setTokens } = makeOxy();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: await makeBinding({ pin: PIN }),
+    });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'warm-token-plant' });
+    expect(setTokens).toHaveBeenCalledWith(jwtFor('vault-user'));
+  });
+
+  it('does NOT plant a warm token minted for ANOTHER account — falls through to the pinned mint', async () => {
+    // The durable drift: an account-mode re-mint rewrote the persisted session to
+    // `other-user` while the device was switched. Identity mode must reject it.
+    const store = await seedStore({
+      sessionId: 'sess-other',
+      userId: 'other-user',
+      accessToken: jwtFor('other-user'),
+      expiresAt: farFuture(),
+    });
+    const mintFromDeviceSecret = jest.fn(async () => MINT_WHILE_SWITCHED);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: await makeBinding({ pin: PIN }),
+    });
+
+    expect(setTokens).not.toHaveBeenCalledWith(jwtFor('other-user'));
+    expect(outcome).toMatchObject({
+      kind: 'session',
+      via: 'device-secret-mint',
+      session: { sessionId: 'sess-vault-new', userId: 'vault-user' },
+    });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith('dev-1', 'ds-secret-orig', {
+      accountId: 'vault-user',
+    });
+  });
+
+  it('does NOT plant a warm token whose persisted identity matches but whose CLAIM does not', async () => {
+    // Belt-and-braces: `userId` says the pinned account, the token itself does not.
+    const store = await seedStore({ accessToken: jwtFor('other-user'), expiresAt: farFuture() });
+    const mintFromDeviceSecret = jest.fn(async () => MINT_WHILE_SWITCHED);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: await makeBinding({ pin: PIN }),
+    });
+
+    expect(setTokens).not.toHaveBeenCalledWith(jwtFor('other-user'));
+    expect(outcome).toMatchObject({ kind: 'session', via: 'device-secret-mint' });
+  });
+
+  it('plants a warm token in ACCOUNT mode regardless of which account it belongs to (unchanged)', async () => {
+    const store = await seedStore({
+      sessionId: 'sess-other',
+      userId: 'other-user',
+      accessToken: jwtFor('other-user'),
+      expiresAt: farFuture(),
+    });
+    const { oxy, setTokens } = makeOxy();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'warm-token-plant' });
+    expect(setTokens).toHaveBeenCalledWith(jwtFor('other-user'));
+  });
+});
+
+describe('runSessionColdBoot — identity mode: device-secret-mint', () => {
+  it('skips the mint entirely when there is no verified pin', async () => {
+    const store = await seedStore();
+    const mintFromDeviceSecret = jest.fn(async () => MINT_WHILE_SWITCHED);
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: await makeBinding(), // no pin seeded
+    });
+
+    // An unpinned mint would have resolved `other-user` — never acceptable here.
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    expect(outcome).toMatchObject({
+      kind: 'session',
+      via: 'identity-key-signin',
+      session: { userId: 'vault-user' },
+    });
+  });
+
+  it('keeps the device secret and re-establishes when the pinned account left the device', async () => {
+    const store = await seedStore();
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw Object.assign(new Error('account_not_on_device'), { status: 401 });
+    });
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: await makeBinding({ pin: PIN }),
+    });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'identity-key-signin' });
+    // The healthy credential was never dropped over a stale identity binding
+    // (the identity sign-in then overwrote it with the freshly minted one).
+    expect(await store.load()).toMatchObject({ deviceSecret: 'ds-identity' });
+  });
+
+  it('clears a pin whose key no longer matches, then re-establishes from the current key', async () => {
+    const store = await seedStore();
+    const mintFromDeviceSecret = jest.fn(async () => MINT_WHILE_SWITCHED);
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+    const pinStore = createMemoryIdentityPinStore();
+    await pinStore.save(PIN);
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: {
+        pinStore,
+        readPublicKey: async () => OTHER_PUBLIC_KEY,
+        signChallenge: signWith(OTHER_PUBLIC_KEY),
+      },
+    });
+
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    expect(outcome).toMatchObject({ kind: 'session', via: 'identity-key-signin' });
+    expect(await pinStore.load()).toEqual({ publicKey: OTHER_PUBLIC_KEY, accountId: 'vault-user' });
+  });
+});
+
+describe('runSessionColdBoot — identity-key-signin vs shared-key-signin', () => {
+  it('identity mode runs identity-key-signin and NEVER the shared-keychain lane', async () => {
+    const store = createMemoryAuthStateStore(); // no mint credential
+    const signInWithSharedIdentity = jest.fn(async () => SHARED_SESSION);
+    const requestChallenge = jest.fn(async () => ({
+      challenge: 'chal-1',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+    }));
+    const verifyChallenge = jest.fn(async () => IDENTITY_SESSION);
+    const { oxy } = makeOxy({ signInWithSharedIdentity, requestChallenge, verifyChallenge });
+    const binding = await makeBinding();
+    const onSession = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: binding,
+      onSession,
+    });
+
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+    expect(outcome).toMatchObject({ kind: 'session', via: 'identity-key-signin' });
+    expect(onSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionId: 'sess-identity',
+        userId: 'vault-user',
+        via: 'identity-key-signin',
+      }),
+    );
+    // Boot-path network calls stay single-attempt.
+    expect(requestChallenge).toHaveBeenCalledWith(PUBLIC_KEY, { retry: false });
+    expect(verifyChallenge).toHaveBeenCalledWith(
+      PUBLIC_KEY,
+      'chal-1',
+      'sig(chal-1)',
+      1_700_000_000_000,
+      undefined,
+      undefined,
+      { retry: false },
+    );
+    // The pin and the fast-lane credential are both written for the next boot.
+    expect(await binding.pinStore.load()).toEqual(PIN);
+    expect(await store.load()).toMatchObject({ userId: 'vault-user', deviceSecret: 'ds-identity' });
+  });
+
+  it('account mode runs shared-key-signin and NEVER the identity lane (unchanged)', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => SHARED_SESSION);
+    const requestChallenge = jest.fn(async () => ({ challenge: 'c', expiresAt: 'e' }));
+    const { oxy } = makeOxy({ signInWithSharedIdentity, requestChallenge });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'shared-key-signin' });
+    expect(signInWithSharedIdentity).toHaveBeenCalledWith({ requestOptions: { retry: false } });
+    expect(requestChallenge).not.toHaveBeenCalled();
+  });
+
+  it('is offline-gated like every other network step', async () => {
+    const store = createMemoryAuthStateStore();
+    const requestChallenge = jest.fn(async () => ({ challenge: 'c', expiresAt: 'e' }));
+    const { oxy } = makeOxy({ requestChallenge });
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: await makeBinding(),
+      isOffline: () => true,
+      onSignedOut,
+    });
+
+    expect(requestChallenge).not.toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+  });
+
+  it('ends signed out (never account-mode) when identity mode is requested without a binding', async () => {
+    const store = await seedStore({ accessToken: jwtFor('other-user'), expiresAt: farFuture() });
+    const mintFromDeviceSecret = jest.fn(async () => MINT_WHILE_SWITCHED);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sessionMode: 'identity',
+      onSignedOut,
+    });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('error');
+    expect(setTokens).not.toHaveBeenCalled();
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+  });
+});