@oxyhq/core 12.10.6 → 12.11.0

package/dist/esm/session/identityPin.js

@@ -0,0 +1,249 @@
+/**
+ * Identity pin — the durable binding between THIS device's PRIMARY identity key
+ * and the account that key authenticates as.
+ *
+ * An identity-bound client (Commons, the identity vault) must always act as the
+ * owner of the local signing key — permanently. The `DeviceSession` it shares
+ * with every other Oxy app on the same device tracks a MUTABLE `activeAccountId`
+ * that any sibling app can switch; following it silently changes both the user
+ * such a client renders and the bearer it sends. The pin is the client-side
+ * record that breaks that coupling: `{ publicKey, accountId }`, written when an
+ * identity-mode session is established (the only moment both facts are known
+ * first-hand), read on every boot, and reconciled against the live
+ * `KeyManager.getPublicKey()` before it is trusted (see
+ * `resolveIdentityPin` in `identitySession.ts`).
+ *
+ * It holds NO secret — a public key and an account id, both already known to the
+ * server — so it lives in the same per-origin storage as {@link PersistedAuthState}
+ * (`authStateStore.ts`) rather than the keychain, and mirrors that module's
+ * store shape: `load / save / clear`, an in-memory mirror, a read-back-verified
+ * durable write, and graceful degradation when storage is unavailable.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import { logger } from '../logger/index.js';
+/**
+ * Versioned storage key. Deliberately distinct from the `oxy.auth.*` keys so a
+ * session sign-out (which clears the auth blob) and an identity change (which
+ * clears the pin) can never take each other down.
+ */
+export const IDENTITY_PIN_STORAGE_KEY = 'oxy.identity.pin.v1';
+/**
+ * Structural check for a storable identity public key: `KeyManager` only ever
+ * persists secp256k1 hex — compressed (66 chars) or uncompressed (130). A stored
+ * value of any other shape is corrupt, so it is treated as "no pin" (fail
+ * closed) rather than compared. Full curve validation belongs to `KeyManager`;
+ * the pin's real authority is the reconcile against the live local key.
+ */
+function isStorablePublicKey(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    if (value.length !== 66 && value.length !== 130) {
+        return false;
+    }
+    return /^[0-9a-fA-F]+$/.test(value);
+}
+/**
+ * Parse + shape-validate a stored blob. Returns `null` for anything that is not
+ * a well-formed {@link IdentityPin} (absent, malformed JSON, wrong types, junk
+ * public key) so a corrupt entry degrades to "not pinned" rather than throwing —
+ * and, critically, never yields a pin that could bind a client to the wrong
+ * account.
+ */
+function deserialize(raw) {
+    if (!raw) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return null;
+    }
+    const candidate = parsed;
+    if (!isStorablePublicKey(candidate.publicKey)) {
+        return null;
+    }
+    if (typeof candidate.accountId !== 'string' || candidate.accountId.length === 0) {
+        return null;
+    }
+    return {
+        publicKey: candidate.publicKey.toLowerCase(),
+        accountId: candidate.accountId,
+    };
+}
+/**
+ * Serialize a pin, or `null` when the caller handed over a value that would not
+ * survive {@link deserialize} — writing it would produce an entry that silently
+ * reads back as "not pinned".
+ */
+function serialize(pin) {
+    if (!isStorablePublicKey(pin.publicKey) || pin.accountId.length === 0) {
+        return null;
+    }
+    return JSON.stringify({ publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId });
+}
+/**
+ * Whether `pin` still describes the identity currently on this device.
+ *
+ * `publicKey` comparison is case-insensitive (hex). A `null` local key is a
+ * definitive "no identity here" and therefore never a match — the caller clears
+ * the pin rather than binding to an account whose key is gone.
+ */
+export function identityPinMatches(pin, localPublicKey) {
+    if (!pin || !localPublicKey) {
+        return false;
+    }
+    return pin.publicKey.toLowerCase() === localPublicKey.toLowerCase();
+}
+/**
+ * A process-lifetime, in-memory {@link IdentityPinStore}. Used directly for
+ * tests/SSR and as the degraded fallback of the web store.
+ */
+export function createMemoryIdentityPinStore() {
+    let current = null;
+    return {
+        load: async () => current,
+        save: async (pin) => {
+            if (!serialize(pin)) {
+                return false;
+            }
+            // Memory IS this store's durability backing — the write always lands.
+            current = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+            return true;
+        },
+        clear: async () => {
+            current = null;
+        },
+    };
+}
+/**
+ * Read the ambient `localStorage`, tolerating the case where merely ACCESSING
+ * `window.localStorage` throws (sandboxed iframe `SecurityError`). Returns
+ * `null` when storage is unavailable.
+ */
+function safeGetLocalStorage() {
+    try {
+        if (typeof globalThis === 'undefined') {
+            return null;
+        }
+        const store = globalThis.localStorage;
+        return store ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A `localStorage`-backed {@link IdentityPinStore}. Degrades to an in-memory
+ * store when `localStorage` is unreachable, and keeps an in-memory mirror so a
+ * failed persist still pins THIS page's lifetime.
+ */
+export function createWebIdentityPinStore() {
+    const storage = safeGetLocalStorage();
+    if (!storage) {
+        return createMemoryIdentityPinStore();
+    }
+    // `undefined` = never written this session → fall back to storage; any set
+    // value (including `null` after clear) is authoritative.
+    let sessionMirror;
+    return {
+        load: async () => {
+            if (sessionMirror !== undefined) {
+                return sessionMirror;
+            }
+            try {
+                return deserialize(storage.getItem(IDENTITY_PIN_STORAGE_KEY));
+            }
+            catch {
+                return null;
+            }
+        },
+        save: async (pin) => {
+            const json = serialize(pin);
+            if (!json) {
+                logger.error('[identityPin] refusing to persist a malformed identity pin', undefined, { component: 'identityPin' });
+                return false;
+            }
+            sessionMirror = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+            try {
+                storage.setItem(IDENTITY_PIN_STORAGE_KEY, json);
+                if (storage.getItem(IDENTITY_PIN_STORAGE_KEY) === json) {
+                    return true;
+                }
+                logger.error('[identityPin] read-back mismatch after save — the identity pin did not persist; this process stays pinned via the in-memory mirror but the next boot must re-establish the identity session', undefined, { component: 'identityPin' });
+                return false;
+            }
+            catch (error) {
+                logger.error('[identityPin] persist threw — the identity pin did not persist; this process stays pinned via the in-memory mirror but the next boot must re-establish the identity session', error, { component: 'identityPin' });
+                return false;
+            }
+        },
+        clear: async () => {
+            sessionMirror = null;
+            try {
+                storage.removeItem(IDENTITY_PIN_STORAGE_KEY);
+            }
+            catch (error) {
+                logger.debug('[identityPin] clear failed', { component: 'identityPin' }, error);
+            }
+        },
+    };
+}
+/**
+ * A native {@link IdentityPinStore} over an injected async key/value store —
+ * the same seam `createNativeAuthStateStore` uses, so `@oxyhq/core` never
+ * imports `expo-secure-store`.
+ */
+export function createNativeIdentityPinStore(storage) {
+    let sessionMirror;
+    return {
+        load: async () => {
+            if (sessionMirror !== undefined) {
+                return sessionMirror;
+            }
+            try {
+                return deserialize(await storage.getItem(IDENTITY_PIN_STORAGE_KEY));
+            }
+            catch {
+                return null;
+            }
+        },
+        save: async (pin) => {
+            const json = serialize(pin);
+            if (!json) {
+                logger.error('[identityPin] refusing to persist a malformed identity pin', undefined, { component: 'identityPin' });
+                return false;
+            }
+            sessionMirror = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+            try {
+                await storage.setItem(IDENTITY_PIN_STORAGE_KEY, json);
+                // A native write can resolve WITHOUT throwing yet not land, so a
+                // read-back is the only reliable proof.
+                if ((await storage.getItem(IDENTITY_PIN_STORAGE_KEY)) === json) {
+                    return true;
+                }
+                logger.error('[identityPin] read-back mismatch after save — the identity pin did not persist; this app run stays pinned via the in-memory mirror but the next cold start must re-establish the identity session', undefined, { component: 'identityPin' });
+                return false;
+            }
+            catch (error) {
+                logger.error('[identityPin] persist threw — the identity pin did not persist; this app run stays pinned via the in-memory mirror but the next cold start must re-establish the identity session', error, { component: 'identityPin' });
+                return false;
+            }
+        },
+        clear: async () => {
+            sessionMirror = null;
+            try {
+                await storage.removeItem(IDENTITY_PIN_STORAGE_KEY);
+            }
+            catch (error) {
+                logger.debug('[identityPin] clear failed', { component: 'identityPin' }, error);
+            }
+        },
+    };
+}

package/dist/esm/session/identitySession.js

@@ -0,0 +1,131 @@
+/**
+ * Identity-bound session — pin reconciliation + establishment.
+ *
+ * This is the SDK half of "an identity vault's authenticated user is whoever
+ * owns the local primary key". Two operations, both consumed by the cold boot
+ * (`boot/sessionColdBoot.ts`) and the re-mint lane (`session/refresh.ts`):
+ *
+ *  - {@link resolveIdentityPin} — read the persisted `{publicKey, accountId}`
+ *    pin and reconcile it against the identity currently on this device. A
+ *    definitive mismatch (the key was replaced, or is gone) CLEARS the pin; an
+ *    INDETERMINATE read (keychain locked / storage threw) leaves it untouched.
+ *  - {@link establishIdentitySession} — mint a session from the PRIMARY local
+ *    key (`getPublicKey` → `requestChallenge` → `signChallenge` →
+ *    `verifyChallenge`), persist the resulting device credential, and write the
+ *    pin. This is the identity-mode replacement for the shared-keychain lane,
+ *    which reads the CROSS-APP shared slot and may therefore hold a different
+ *    identity than this device's primary.
+ *
+ * Both take their key/signature functions from an injectable {@link IdentityBinding}
+ * (defaulting to `KeyManager` / `SignatureService`) so the lanes above stay
+ * testable without a keychain.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import { KeyManager } from '../crypto/keyManager.js';
+import { SignatureService } from '../crypto/signatureService.js';
+import { identityPinMatches } from './identityPin.js';
+import { logger } from '../logger/index.js';
+function readPublicKeyOf(binding) {
+    return binding.readPublicKey ?? (() => KeyManager.getPublicKey());
+}
+function signChallengeOf(binding) {
+    return binding.signChallenge ?? ((challenge) => SignatureService.signChallenge(challenge));
+}
+/**
+ * Read the persisted pin and reconcile it against the identity on this device.
+ *
+ * Returns the pin ONLY when the local primary public key still matches it — that
+ * is the single condition under which a client may bind its token and its
+ * rendered user to that account.
+ *
+ * Outcomes:
+ *  - no pin stored → `null` (nothing to clear).
+ *  - local key MATCHES → the pin (trusted).
+ *  - local key read succeeded and differs / is absent → the identity was
+ *    replaced or lost: CLEAR the pin and return `null`. Keeping it would pin the
+ *    client to an account it can no longer prove control of.
+ *  - the local key read THREW (keychain locked, storage unavailable) → return
+ *    `null` WITHOUT clearing. A read that produced no verdict is never evidence
+ *    of an identity change (the same rule `KeyManager` applies to its own
+ *    transient errors); the caller falls through to the identity sign-in lane,
+ *    which fails closed on a locked keychain rather than adopting a foreign
+ *    account.
+ */
+export async function resolveIdentityPin(binding) {
+    const pin = await binding.pinStore.load();
+    if (!pin) {
+        return null;
+    }
+    let localPublicKey;
+    try {
+        localPublicKey = await readPublicKeyOf(binding)();
+    }
+    catch (error) {
+        logger.debug('Identity key read did not produce a verdict — keeping the pin untouched', { component: 'identitySession', method: 'resolveIdentityPin' }, error);
+        return null;
+    }
+    if (identityPinMatches(pin, localPublicKey)) {
+        return pin;
+    }
+    logger.warn('Identity pin no longer matches the device identity key — clearing it (the identity was replaced or removed)', { component: 'identitySession', method: 'resolveIdentityPin' });
+    await binding.pinStore.clear();
+    return null;
+}
+/**
+ * Establish a session for the device's PRIMARY identity key and pin it.
+ *
+ * `requestChallenge` → `signChallenge` → `verifyChallenge`; `verifyChallenge`
+ * plants the access token itself. The server resolves the account from the
+ * VERIFIED SIGNER, so the returned session is identity-authoritative — it
+ * ignores the device's `activeAccountId` entirely.
+ *
+ * Side effects on success: the durable device credential is persisted (so the
+ * next boot can take the fast pinned-mint lane) and the pin is written.
+ *
+ * Returns `null` — never throws — for the two "nothing to do" cases: no local
+ * identity (including every web caller, where `KeyManager` has no key), and a
+ * verify that produced no access token. Network/crypto failures propagate so the
+ * caller can classify them.
+ */
+export async function establishIdentitySession(args) {
+    const { oxy, store, binding, requestOptions } = args;
+    const publicKey = await readPublicKeyOf(binding)();
+    if (!publicKey) {
+        return null;
+    }
+    const { challenge } = await oxy.requestChallenge(publicKey, requestOptions);
+    const signed = await signChallengeOf(binding)(challenge);
+    if (signed.publicKey.toLowerCase() !== publicKey.toLowerCase()) {
+        // The signer disagrees with the key we resolved a challenge for — the
+        // identity changed mid-flight, or a custom signer was misconfigured. Refuse:
+        // verifying under a different key would bind this client to another account.
+        throw new Error('Identity sign-in aborted: the signing key does not match the device identity key');
+    }
+    // `signed.challenge` carries the SIGNATURE (mirrors `signChallengeWithSharedKey`).
+    const session = await oxy.verifyChallenge(signed.publicKey, challenge, signed.challenge, signed.timestamp, binding.deviceName, binding.deviceFingerprint, requestOptions);
+    if (!session?.accessToken) {
+        return null;
+    }
+    // Persist the rotating device credential so later boots re-mint through the
+    // fast `POST /session/device/token` lane instead of re-signing a challenge.
+    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,
+        });
+    }
+    const pin = { publicKey: publicKey.toLowerCase(), accountId: session.user.id };
+    // A failed pin persist is NOT fatal: this process is already pinned in memory,
+    // and a later boot without a pin skips the (unpinned) mint lane and re-runs
+    // this exact lane, which rewrites it. Never fail an established session on it.
+    const pinned = await binding.pinStore.save(pin);
+    if (!pinned) {
+        logger.warn('Identity session established but the pin did not durably persist — the next cold start will re-establish it', { component: 'identitySession', method: 'establishIdentitySession' });
+    }
+    return { session, pin };
+}

package/dist/esm/session/projectSessionState.js

@@ -8,7 +8,25 @@
  * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
  * from the result before calling `deviceStateToClientSessions` /
  * `activeUserOf`.
+ *
+ * Each projection takes an OPTIONAL `pinnedAccountId`. Omit it (or pass `null`)
+ * and the projection resolves the device's `activeAccountId` exactly as before.
+ * Pass it — an IDENTITY-BOUND client, whose user is fixed by the local identity
+ * key — and the projection resolves THAT account instead, so an account switch
+ * made by another app on the same device changes `state` but never the user this
+ * client renders.
  */
+/**
+ * The account a projection should resolve: the pin when one is supplied and
+ * non-empty, else the device's active account. An empty-string pin is treated as
+ * "not pinned" rather than as an account that can never match.
+ */
+function boundAccountIdOf(state, pinnedAccountId) {
+    if (typeof pinnedAccountId === 'string' && pinnedAccountId.length > 0) {
+        return pinnedAccountId;
+    }
+    return state.activeAccountId;
+}
 /**
  * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
  *
@@ -20,9 +38,14 @@
  * though `ClientSession` only stores `userId` — a session is still
  * projected for an account whose id is absent from `usersById` (no
  * placeholder user is fabricated).
+ *
+ * `isCurrent` marks the PINNED account when one is supplied, so it can never
+ * disagree with {@link activeSessionIdOf} / {@link activeUserOf} for the same
+ * pin.
  */
-export function deviceStateToClientSessions(state, usersById) {
+export function deviceStateToClientSessions(state, usersById, pinnedAccountId) {
     const provisionalTimestamp = new Date(state.updatedAt).toISOString();
+    const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
     return state.accounts.map((account) => ({
         sessionId: account.sessionId,
         deviceId: state.deviceId,
@@ -30,32 +53,48 @@ export function deviceStateToClientSessions(state, usersById) {
         expiresAt: provisionalTimestamp,
         lastActive: provisionalTimestamp,
         userId: account.accountId,
-        isCurrent: account.accountId === state.activeAccountId,
+        isCurrent: account.accountId === boundAccountId,
         authuser: account.authuser,
     }));
 }
 /**
- * The active account's `sessionId`, or `null` when there is no state or no
- * active account is set.
+ * The bound account's `sessionId`, or `null` when there is no state, no bound
+ * account, or that account has no session on this device.
+ *
+ * A pinned account that is ABSENT from `state.accounts` yields `null` — the
+ * honest signal that this device no longer carries a session for the pinned
+ * identity, which the caller answers by re-establishing the identity session
+ * (never by adopting the device's active account).
  */
-export function activeSessionIdOf(state) {
-    if (state === null || state.activeAccountId === null) {
+export function activeSessionIdOf(state, pinnedAccountId) {
+    if (state === null) {
+        return null;
+    }
+    const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
+    if (boundAccountId === null) {
         return null;
     }
-    const activeAccountId = state.activeAccountId;
-    const activeAccount = state.accounts.find((account) => account.accountId === activeAccountId);
-    return activeAccount?.sessionId ?? null;
+    const boundAccount = state.accounts.find((account) => account.accountId === boundAccountId);
+    return boundAccount?.sessionId ?? null;
 }
 /**
- * The active account's `User`, resolved from `usersById`. `null` when there
- * is no state, no active account is set, or the active account id is absent
- * from `usersById`.
+ * The bound account's `User`, resolved from `usersById`. `null` when there is no
+ * state, no bound account, or the bound account id is absent from `usersById`.
+ *
+ * A pinned user is resolved from `usersById` alone — deliberately NOT gated on
+ * device membership — so a transient device-state gap cannot flicker the
+ * identity vault's rendered user. Whether the pinned session still exists on the
+ * device is answered by {@link activeSessionIdOf}.
  */
-export function activeUserOf(state, usersById) {
-    if (state === null || state.activeAccountId === null) {
+export function activeUserOf(state, usersById, pinnedAccountId) {
+    if (state === null) {
+        return null;
+    }
+    const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
+    if (boundAccountId === null) {
         return null;
     }
-    return usersById.get(state.activeAccountId) ?? null;
+    return usersById.get(boundAccountId) ?? null;
 }
 /**
  * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`

package/dist/esm/session/refresh.js

@@ -1,3 +1,4 @@
+import { establishIdentitySession, resolveIdentityPin } from './identitySession.js';
 import { isNative } from '../utils/platform.js';
 import { extractErrorStatus } from '../utils/errorUtils.js';
 import { logger } from '../logger/index.js';
@@ -50,9 +51,16 @@ const MAX_FAILURE_BACKOFF_MS = 5 * 60000;
  * planting. This function performs NO store mutation on failure — the caller
  * applies the drop/clear policy (which differs web vs native) from the returned
  * status.
+ *
+ * `pin` makes the mint IDENTITY-BOUND: the request carries the pinned
+ * `accountId` (so the server mints that account's token without touching
+ * `activeAccountId`), and the persisted `sessionId`/`userId` are resolved from
+ * the PINNED account entry — never from `state.activeAccountId`, whose drift is
+ * exactly what the pin exists to stop.
  */
 export async function refreshDeviceSecretArm(deps) {
     const { oxy, store } = deps;
+    const pin = deps.pin ?? null;
     return oxy.httpService.runSingleFlightDeviceSecretMint(async () => {
         const persisted = await store.load();
         if (!persisted?.deviceId || !persisted?.deviceSecret) {
@@ -60,7 +68,13 @@ export async function refreshDeviceSecretArm(deps) {
         }
         let mint;
         try {
-            mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
+            // Unpinned callers pass NO third argument at all, so the account-mode call
+            // shape (and therefore the request body) is untouched by this feature.
+            mint = pin
+                ? await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret, {
+                    accountId: pin.accountId,
+                })
+                : await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
         }
         catch (error) {
             if (extractErrorStatus(error) === 401) {
@@ -80,18 +94,26 @@ export async function refreshDeviceSecretArm(deps) {
                     return { status: 'invalid-secret' };
                 if (body.includes('no_active_session'))
                     return { status: 'no-session' };
+                // A pinned mint whose account left the device set. The secret is intact —
+                // never classify this as a bad secret, or the caller would drop a healthy
+                // credential over a stale identity binding.
+                if (body.includes('account_not_on_device'))
+                    return { status: 'account-not-on-device' };
                 return { status: 'transient' };
             }
             return { status: 'transient' };
         }
-        const active = mint.state.accounts.find((a) => a.accountId === mint.state.activeAccountId);
+        // The account this session is BOUND to: the pinned one when identity-bound
+        // (the server already minted for it), else the device's active account.
+        const boundAccountId = pin ? pin.accountId : mint.state.activeAccountId;
+        const bound = mint.state.accounts.find((a) => a.accountId === boundAccountId);
         const next = {
             ...persisted,
             deviceId: mint.state.deviceId,
             deviceSecret: mint.nextDeviceSecret,
             accessToken: mint.accessToken,
             expiresAt: mint.expiresAt,
-            ...(active ? { sessionId: active.sessionId, userId: active.accountId } : {}),
+            ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
         };
         // Rotation-in-use anti-loss: persist the NEXT secret and read-back-VERIFY it
         // landed BEFORE planting the token. A failed durable persist must NOT plant.
@@ -119,11 +141,25 @@ export async 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 async function refreshPersistedSession(deps) {
     const { oxy, store } = deps;
-    const allowSharedKeyFallback = deps.allowSharedKeyFallback ?? isNative();
-    const arm1 = await refreshDeviceSecretArm({ oxy, store });
+    const identity = deps.identity ?? null;
+    // The shared keychain is never an identity-bound client's recovery path.
+    const allowSharedKeyFallback = identity ? false : (deps.allowSharedKeyFallback ?? isNative());
+    // Resolved per call: a re-established identity session can move the pin, and a
+    // replaced/removed local key clears it (in which case arm 1 must NOT mint —
+    // an unpinned mint would adopt whatever account the device switched to).
+    const pin = identity ? await resolveIdentityPin(identity) : null;
+    if (identity && !pin) {
+        return recoverIdentitySession(oxy, store, identity);
+    }
+    const arm1 = await refreshDeviceSecretArm({ oxy, store, pin });
     switch (arm1.status) {
         case 'ok':
             return arm1.token;
@@ -139,11 +175,12 @@ export async function refreshPersistedSession(deps) {
             return null;
         case 'invalid-secret':
         case 'no-session': {
-            // 401: secret diverged or no live session. On a shared-key device drop only
-            // the secret (keep the identity so arm 2 can recover); otherwise (web) the
+            // 401: secret diverged or no live session. When a key-based arm 2 can still
+            // recover (native shared key, or an identity-bound client's own primary
+            // key) drop ONLY the secret and keep the deviceId; otherwise (web) the
             // session is over — clear the store.
             const persisted = await store.load();
-            if (allowSharedKeyFallback) {
+            if (allowSharedKeyFallback || identity) {
                 if (persisted) {
                     await store.save({ ...persisted, deviceSecret: undefined });
                 }
@@ -153,9 +190,17 @@ export async function refreshPersistedSession(deps) {
             }
             break;
         }
+        case 'account-not-on-device':
+            // The pinned account left this device's session set. The secret is healthy —
+            // leave the store untouched and let the identity arm re-establish.
+            logger.debug('Pinned device-secret mint rejected: the pinned account is no longer on this device — re-establishing from the identity key', { component: 'refresh', method: 'refreshPersistedSession' });
+            break;
         case 'no-secret':
             break;
     }
+    if (identity) {
+        return recoverIdentitySession(oxy, store, identity);
+    }
     if (allowSharedKeyFallback) {
         try {
             const session = await oxy.signInWithSharedIdentity();
@@ -180,6 +225,26 @@ export async function refreshPersistedSession(deps) {
     }
     return null;
 }
+/**
+ * Arm 2 for an IDENTITY-BOUND client: re-establish the session from the PRIMARY
+ * local key and rewrite the pin (`establishIdentitySession` plants the token and
+ * persists the device credential itself).
+ *
+ * Returns `null` — never throws — when there is no local identity, the verify
+ * yielded no token, or the exchange failed: the caller treats that as "could not
+ * refresh", exactly like the shared-key arm. A locked keychain therefore ends
+ * signed out rather than falling back to the device's active account.
+ */
+async function recoverIdentitySession(oxy, store, binding) {
+    try {
+        const established = await establishIdentitySession({ oxy, store, binding });
+        return established?.session.accessToken ?? null;
+    }
+    catch (error) {
+        logger.debug('Identity-key re-sign-in failed', { component: 'refresh', method: 'recoverIdentitySession' }, error);
+        return null;
+    }
+}
 /**
  * Build the reactive `AuthRefreshHandler` (arm 1 + arm 2). Install it via
  * {@link installAuthRefreshHandler} or directly on