@oxyhq/core 12.10.6 → 12.11.1

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();
+  });
+});

package/src/boot/sessionColdBoot.ts

@@ -15,18 +15,45 @@
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   3. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
+ *   3. `shared-key-signin` (native, ACCOUNT mode) — re-mint from the
+ *      shared-keychain identity — OR `identity-key-signin` (IDENTITY mode) —
+ *      re-mint from THIS device's primary identity key.
  *   4. Signed out.
  *
+ * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
+ *   - `account` (default) — the device's ACTIVE account owns the session. Every
+ *     Oxy app but the identity vault boots this way; behaviour is unchanged.
+ *   - `identity` — the owner of the local PRIMARY identity key owns the session,
+ *     permanently, regardless of which account the device is switched to. Each
+ *     step above is bound to the persisted identity pin, and the shared-keychain
+ *     lane is replaced by the primary-key one (the shared slot is a CROSS-APP
+ *     slot that may hold a different identity).
+ *
  * ESM-safe (no `require()`); no react/react-native/expo imports.
  */
 import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/coldBoot';
 import { isNative as detectNative } from '../utils/platform';
 import { logger } from '../logger';
+import { computeIdentityTag } from '../utils/cacheKey';
 import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh';
+import {
+  establishIdentitySession,
+  resolveIdentityPin,
+  type IdentityBinding,
+} from '../session/identitySession';
+import type { IdentityPin } from '../session/identityPin';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore } from '../session/authStateStore';
 
+/**
+ * Who owns the session this boot resolves.
+ *
+ * - `account` — the device's active account (every ordinary Oxy app).
+ * - `identity` — the owner of the device's primary identity key (the identity
+ *   vault). Requires {@link RunSessionColdBootOptions.identity}.
+ */
+export type SessionMode = 'account' | 'identity';
+
 /** The winning session shape a cold-boot step reports. */
 export interface DeviceBootSession {
   sessionId: string;
@@ -72,6 +99,23 @@ export interface RunSessionColdBootOptions {
    * so a flaky probe can never falsely skip a real sign-in.
    */
   isOffline?: () => boolean;
+  /**
+   * Who owns the resolved session. Defaults to `'account'` — the device's active
+   * account — which is the behaviour every ordinary Oxy app has today and which
+   * this option leaves byte-for-byte unchanged.
+   *
+   * `'identity'` binds the boot to the owner of this device's PRIMARY identity
+   * key and REQUIRES {@link identity}. When it is missing the boot refuses to
+   * run any lane (an identity-bound client silently falling back to the device's
+   * active account is precisely the bug this mode exists to prevent) and
+   * resolves signed out.
+   */
+  sessionMode?: SessionMode;
+  /**
+   * The identity binding (pin store + key/signature access) used by
+   * `sessionMode: 'identity'`. Ignored in `'account'` mode.
+   */
+  identity?: IdentityBinding;
 }
 
 /**
@@ -85,6 +129,19 @@ export async function runSessionColdBoot(
   const { oxy, store } = opts;
   const isNative = opts.platform?.isNative ?? detectNative();
 
+  // Non-null ONLY in identity mode; every `!== null` test below therefore reads
+  // as "is this boot identity-bound?" while also narrowing the binding.
+  const identityBinding = opts.sessionMode === 'identity' ? opts.identity ?? null : null;
+  if (opts.sessionMode === 'identity' && identityBinding === null) {
+    logger.error(
+      'runSessionColdBoot: sessionMode "identity" requires an `identity` binding — refusing to run any lane (an identity-bound client must never adopt the device active account)',
+      undefined,
+      { component: 'sessionColdBoot', method: 'runSessionColdBoot' },
+    );
+    await opts.onSignedOut?.('error');
+    return { kind: 'unauthenticated' };
+  }
+
   // Best-effort connectivity gate for the NETWORK steps only. A missing hint or
   // any non-`true` verdict means "assume online" — never falsely skip a real
   // sign-in on an ambiguous probe.
@@ -94,6 +151,23 @@ export async function runSessionColdBoot(
   // bundler re-evaluation.
   let signedOutReason: SignedOutReason = 'no_session';
 
+  // Boot-local memo for the identity pin. Resolved lazily INSIDE a step so the
+  // (local, but storage-backed) read is covered by `overallDeadlineMs`, and
+  // resolved at most once per boot so two steps cannot disagree. Always `null`
+  // in account mode.
+  let pinResolved = false;
+  let cachedPin: IdentityPin | null = null;
+  const getIdentityPin = async (): Promise<IdentityPin | null> => {
+    if (identityBinding === null) {
+      return null;
+    }
+    if (!pinResolved) {
+      cachedPin = await resolveIdentityPin(identityBinding);
+      pinResolved = true;
+    }
+    return cachedPin;
+  };
+
   const steps: Array<ColdBootStep<DeviceBootSession>> = [];
 
   // 1. warm-token-plant (web + native) — the fastest path. When the persisted
@@ -122,6 +196,21 @@ export async function runSessionColdBoot(
       if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now() + TOKEN_REFRESH_LEAD_MS) {
         return { kind: 'skip' };
       }
+      if (identityBinding !== null) {
+        // Identity-bound: a persisted token is only acceptable when it belongs to
+        // the PINNED account. Both the token's own claim (`computeIdentityTag`,
+        // the same derivation `SessionClient.applyState` uses) and the owning
+        // session identity must match — a token planted for another account by an
+        // earlier account-mode write is exactly the durable drift this gate stops.
+        const pin = await getIdentityPin();
+        if (
+          pin === null ||
+          persisted.userId !== pin.accountId ||
+          computeIdentityTag(persisted.accessToken) !== pin.accountId
+        ) {
+          return { kind: 'skip' };
+        }
+      }
       oxy.setTokens(persisted.accessToken);
       return {
         kind: 'session',
@@ -148,7 +237,16 @@ export async function runSessionColdBoot(
     // a doomed mint cannot burn the overall deadline before routing settles.
     enabled: () => !isOffline(),
     run: async () => {
-      const result = await refreshDeviceSecretArm({ oxy, store });
+      const pin = await getIdentityPin();
+      if (identityBinding !== null && pin === null) {
+        // Identity-bound with no verified pin (never written, or cleared because
+        // the local key changed/vanished). An UNPINNED mint would adopt whichever
+        // account the device is currently switched to — the exact drift this mode
+        // exists to prevent. Fall through to `identity-key-signin`, which
+        // re-derives the account from the local key and rewrites the pin.
+        return { kind: 'skip' };
+      }
+      const result = await refreshDeviceSecretArm({ oxy, store, pin });
       switch (result.status) {
         case 'ok':
           // The arm persisted the rotated secret and planted the token.
@@ -186,6 +284,15 @@ export async function runSessionColdBoot(
             { component: 'sessionColdBoot', method: 'device-secret-mint' },
           );
           return { kind: 'skip' };
+        case 'account-not-on-device':
+          // Pinned mint rejected: the pinned account is no longer a live account
+          // of this device session. The secret is healthy — keep it untouched and
+          // let `identity-key-signin` re-establish from the local key.
+          logger.debug(
+            'pinned device-secret mint rejected (account_not_on_device) — keeping secret, re-establishing from the identity key',
+            { component: 'sessionColdBoot', method: 'device-secret-mint' },
+          );
+          return { kind: 'skip' };
         case 'transient':
           // Network / 5xx: keep the secret; a later attempt can succeed.
           logger.debug(
@@ -199,42 +306,81 @@ export async function runSessionColdBoot(
     },
   });
 
-  // 3. shared-key-signin (native) — re-mint from the shared identity. Native
-  //    AND online: it is a network step (challenge + verify round-trips), so it
-  //    is gated by the same offline hint as the mint lane. `{ retry: false }`
-  //    keeps the two round-trips as single attempts — the refresh scheduler /
-  //    401 lane own later retries — so this step cannot multiply boot latency.
-  steps.push({
-    id: 'shared-key-signin',
-    enabled: () => isNative && !isOffline(),
-    run: async () => {
-      const session = await oxy.signInWithSharedIdentity({ requestOptions: { retry: false } });
-      if (!session?.accessToken) {
-        return { kind: 'skip' };
-      }
-      // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
-      // boot can use the faster device-secret-mint lane (sockets + tab-focus
-      // re-mint depend on the credential being in the store).
-      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,
+  if (identityBinding !== null) {
+    // 3-identity. identity-key-signin — re-mint from THIS device's PRIMARY
+    //    identity key (`getPublicKey` → challenge → sign → verify). It REPLACES
+    //    `shared-key-signin`, which reads the CROSS-APP shared keychain slot and
+    //    may therefore hold a different identity than the device's primary — the
+    //    one thing an identity-bound client must never adopt. The server resolves
+    //    the account from the verified signer, so the winning session is
+    //    identity-authoritative and the pin is (re)written from it.
+    //
+    //    Online-gated like every network step; `{ retry: false }` keeps the two
+    //    round-trips single attempts (the refresh scheduler / 401 lane own later
+    //    retries) so this step cannot multiply boot latency. On web
+    //    `KeyManager.getPublicKey()` resolves to `null`, so it skips.
+    steps.push({
+      id: 'identity-key-signin',
+      enabled: () => !isOffline(),
+      run: async () => {
+        const established = await establishIdentitySession({
+          oxy,
+          store,
+          binding: identityBinding,
+          requestOptions: { retry: false },
         });
-      }
-      return {
-        kind: 'session',
-        session: {
-          sessionId: session.sessionId,
-          userId: session.user.id,
-          accessToken: session.accessToken,
-        },
-      };
-    },
-  });
+        const accessToken = established?.session.accessToken;
+        if (!established || !accessToken) {
+          return { kind: 'skip' };
+        }
+        return {
+          kind: 'session',
+          session: {
+            sessionId: established.session.sessionId,
+            userId: established.session.user.id,
+            accessToken,
+          },
+        };
+      },
+    });
+  } else {
+    // 3. shared-key-signin (native) — re-mint from the shared identity. Native
+    //    AND online: it is a network step (challenge + verify round-trips), so it
+    //    is gated by the same offline hint as the mint lane. `{ retry: false }`
+    //    keeps the two round-trips as single attempts — the refresh scheduler /
+    //    401 lane own later retries — so this step cannot multiply boot latency.
+    steps.push({
+      id: 'shared-key-signin',
+      enabled: () => isNative && !isOffline(),
+      run: async () => {
+        const session = await oxy.signInWithSharedIdentity({ requestOptions: { retry: false } });
+        if (!session?.accessToken) {
+          return { kind: 'skip' };
+        }
+        // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
+        // boot can use the faster device-secret-mint lane (sockets + tab-focus
+        // re-mint depend on the credential being in the store).
+        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 {
+          kind: 'session',
+          session: {
+            sessionId: session.sessionId,
+            userId: session.user.id,
+            accessToken: session.accessToken,
+          },
+        };
+      },
+    });
+  }
 
   const outcome = await runColdBoot<DeviceBootSession>({
     steps,