@oxyhq/core 12.8.0 → 12.10.0

package/dist/esm/crypto/keyManager.js

@@ -7,9 +7,10 @@
 import _cjs_elliptic from 'elliptic';
 const { ec: EC } = _cjs_elliptic;
 import { isWeb, isIOS, isAndroid } from '../utils/platform.js';
-import { isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore, loadSharedIdentityBridge } from '@oxyhq/protocol';
+import { isReactNative, isNodeJS, loadAsyncStorage, loadExpoCrypto, loadNodeCrypto, loadSecureStore, loadSharedIdentityBridge } from '@oxyhq/protocol';
 import { isDev, logger } from '../logger/index.js';
 import { hkdfSha256 } from './kdf.js';
+import { clearIdentityMarker, readIdentityMarker, updateIdentityMarker, writeIdentityMarker, } from './identityMarker.js';
 /**
  * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
  * is invoked while a valid identity already exists on the device.
@@ -41,6 +42,25 @@ export class IdentityPersistError extends Error {
         this.name = 'IdentityPersistError';
     }
 }
+/**
+ * Thrown when identity storage cannot be read/written right now — the keychain
+ * is locked, the module failed to load, or a read threw — as opposed to the
+ * identity being genuinely absent.
+ *
+ * This is the crux of the corruption-vs-fresh-install fix: a storage THROW must
+ * NEVER be flattened into "no identity" (the old behavior, which let onboarding
+ * treat a momentarily-locked keystore as a blank device). Callers that used to
+ * tolerate a `false`/`null` from `hasIdentity()`/`getPublicKey()` on error must
+ * now treat this typed error as "cannot determine" — retry, surface a locked
+ * state, or abort a destructive path — never as "safe to create/overwrite".
+ */
+export class IdentityUnavailableError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'IdentityUnavailableError';
+    }
+}
 const ec = new EC('secp256k1');
 /**
  * HKDF salt that domain-separates every identity-scoped seed produced by
@@ -73,6 +93,74 @@ const STORAGE_KEYS = {
     SHARED_SESSION_TOKEN: 'oxy_shared_session_token',
     SHARED_SESSION_ID: 'oxy_shared_session_id',
 };
+/**
+ * v2 identity slot layout — blast-radius isolation.
+ *
+ * The legacy keys above were written WITHOUT a `keychainService`, so on Android
+ * they all shared expo-secure-store's single default `key_v1` AndroidKeyStore
+ * key — meaning ONE keystore invalidation deleted the primary AND the backup
+ * together (the exact loss this hardening closes). The v2 layout gives the
+ * primary and the backup DISTINCT keychain services (→ independent AndroidKeyStore
+ * keys, independent iOS keychain items), so they can no longer die together, and
+ * DISTINCT key names (`_v2`) so the post-copy migration verify can only observe
+ * what it actually wrote (old/new locations are non-aliasable).
+ *
+ * Migration from the legacy layout is lazy + verify-before-delete — see
+ * {@link KeyManager._runSlotMigration}.
+ */
+const V2_PRIMARY_KEYCHAIN_SERVICE = 'oxy_identity';
+const V2_BACKUP_KEYCHAIN_SERVICE = 'oxy_identity_backup';
+const V2_STORAGE_KEYS = {
+    PRIVATE_KEY: 'oxy_identity_private_key_v2',
+    PUBLIC_KEY: 'oxy_identity_public_key_v2',
+    BACKUP_PRIVATE_KEY: 'oxy_identity_backup_private_key_v2',
+    BACKUP_PUBLIC_KEY: 'oxy_identity_backup_public_key_v2',
+    BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp_v2',
+};
+/**
+ * Dedicated keychain slot for the recovery mnemonic (the 12-word phrase).
+ *
+ * Stored under its OWN keychain service — distinct from the v2 primary, backup,
+ * and shared slots — so it shares an AndroidKeyStore key with none of them
+ * (blast-radius isolation, same rationale as the v2 primary/backup split).
+ * Written `WHEN_UNLOCKED_THIS_DEVICE_ONLY` and NEVER exported off-device: it
+ * exists solely so the user can RE-READ their phrase from Settings on the SAME
+ * device that generated/imported it.
+ *
+ * This is convenience persistence, NOT a recovery mechanism — a keystore death
+ * wipes it alongside the keys, exactly like the private key itself. The user's
+ * written-down phrase remains the sole out-of-band recovery path. The mnemonic
+ * lives ONLY in this slot: it is never mirrored into the identity marker,
+ * {@link KeyManager.getIdentityStatus}, logs, or any exported bundle.
+ */
+const RECOVERY_MNEMONIC_KEYCHAIN_SERVICE = 'oxy_identity_mnemonic';
+const RECOVERY_MNEMONIC_STORAGE_KEY = 'oxy_identity_mnemonic_v1';
+/**
+ * Advisory AsyncStorage fast-path flag: set once the v2 slots own the identity.
+ * Re-derivable (its loss just re-runs the cheap slot check), so it lives in
+ * plain AsyncStorage rather than the keychain. It only SKIPS re-reading the
+ * legacy slots on an already-migrated device; it is never trusted over an actual
+ * v2 read (a set flag with an unhealthy v2 pair falls through to full migration).
+ */
+const SLOTS_MIGRATED_FLAG_KEY = 'oxy_identity_slots_migrated_v2';
+const V2_SLOT_LAYOUT = {
+    primaryService: V2_PRIMARY_KEYCHAIN_SERVICE,
+    primaryPrivateKeyName: V2_STORAGE_KEYS.PRIVATE_KEY,
+    primaryPublicKeyName: V2_STORAGE_KEYS.PUBLIC_KEY,
+    backupService: V2_BACKUP_KEYCHAIN_SERVICE,
+    backupPrivateKeyName: V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY,
+    backupPublicKeyName: V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY,
+    backupTimestampName: V2_STORAGE_KEYS.BACKUP_TIMESTAMP,
+};
+const LEGACY_SLOT_LAYOUT = {
+    primaryService: undefined,
+    primaryPrivateKeyName: STORAGE_KEYS.PRIVATE_KEY,
+    primaryPublicKeyName: STORAGE_KEYS.PUBLIC_KEY,
+    backupService: undefined,
+    backupPrivateKeyName: STORAGE_KEYS.BACKUP_PRIVATE_KEY,
+    backupPublicKeyName: STORAGE_KEYS.BACKUP_PUBLIC_KEY,
+    backupTimestampName: STORAGE_KEYS.BACKUP_TIMESTAMP,
+};
 /**
  * iOS Keychain Access Group for sharing identities across Oxy apps
  * All Oxy apps must have this access group enabled in their entitlements
@@ -157,6 +245,320 @@ export class KeyManager {
     static invalidateCache() {
         KeyManager.cachedPublicKey = null;
         KeyManager.cachedHasIdentity = null;
+        KeyManager.cachedPublicKeyResolved = false;
+        KeyManager.notifyIdentityChanged();
+    }
+    /**
+     * Subscribe to identity-verdict changes (create / import / delete / restore /
+     * cache invalidation). Fires synchronously; the returned function unsubscribes.
+     * Consumed via `useOxyEvent`-style hooks in commons to invalidate the routing
+     * queries the instant the identity state moves, without polling.
+     */
+    static subscribeIdentityChanged(listener) {
+        KeyManager.identityChangeListeners.add(listener);
+        return () => {
+            KeyManager.identityChangeListeners.delete(listener);
+        };
+    }
+    /** Synchronous fan-out with per-listener isolation (one throwing listener never blocks the rest). */
+    static notifyIdentityChanged() {
+        // Snapshot first — a listener may unsubscribe (mutate the Set) during fan-out.
+        for (const listener of Array.from(KeyManager.identityChangeListeners)) {
+            try {
+                listener();
+            }
+            catch (error) {
+                logger.warn('Identity-change listener threw', { component: 'KeyManager' }, error);
+            }
+        }
+    }
+    /** Build `getItemAsync`/`deleteItemAsync` options for a given keychain service (read/delete). */
+    static _slotOpts(service) {
+        return service ? { keychainService: service } : {};
+    }
+    /** Build private-key write options (device-only accessibility) for a given keychain service. */
+    static _privateWriteOpts(store, service) {
+        const opts = { keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY };
+        if (service) {
+            opts.keychainService = service;
+        }
+        return opts;
+    }
+    /** True only when both keys are present, well-formed, AND the public derives from the private. */
+    static _isHealthyPair(privateKey, publicKey) {
+        if (!privateKey || !publicKey) {
+            return false;
+        }
+        if (!KeyManager.isValidPrivateKey(privateKey) || !KeyManager.isValidPublicKey(publicKey)) {
+            return false;
+        }
+        try {
+            return KeyManager.derivePublicKey(privateKey).toLowerCase() === publicKey.toLowerCase();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Resolve the AsyncStorage-backed KV store for the advisory migration flag, or
+     * `null` off-RN / when unavailable. Independent of the keychain, so the flag
+     * cannot be taken down by the keystore event this whole subsystem defends
+     * against.
+     */
+    static async _advisoryStorage() {
+        if (!isReactNative()) {
+            return null;
+        }
+        try {
+            const mod = await loadAsyncStorage();
+            return mod.default;
+        }
+        catch {
+            // Advisory only — absence just means the slot check runs in full.
+            return null;
+        }
+    }
+    static async _readSlotsMigratedFlag() {
+        const storage = await KeyManager._advisoryStorage();
+        if (!storage) {
+            return false;
+        }
+        try {
+            return (await storage.getItem(SLOTS_MIGRATED_FLAG_KEY)) === 'true';
+        }
+        catch {
+            // Advisory only — treat an unreadable flag as "not yet migrated".
+            return false;
+        }
+    }
+    static async _setSlotsMigratedFlag() {
+        const storage = await KeyManager._advisoryStorage();
+        if (!storage) {
+            return;
+        }
+        try {
+            await storage.setItem(SLOTS_MIGRATED_FLAG_KEY, 'true');
+        }
+        catch (error) {
+            // Advisory only — a failed write just re-runs the cheap slot check next launch.
+            if (isDev()) {
+                logger.debug('Failed to set slots-migrated flag (advisory)', { component: 'KeyManager' }, error);
+            }
+        }
+    }
+    /**
+     * Ensure the identity has been migrated onto the isolated v2 slots (or that we
+     * know we must read legacy this session). Memoized so concurrent callers share
+     * ONE run; a `deferred` (read-threw) outcome is not cached so a later call
+     * retries after the keychain unlocks. Every identity-slot accessor awaits this
+     * before touching storage.
+     */
+    static async _ensureIdentitySlotsMigrated() {
+        if (KeyManager.slotMigrationResult && KeyManager.slotMigrationResult.mode !== 'deferred') {
+            return KeyManager.slotMigrationResult;
+        }
+        if (!KeyManager.slotMigrationPromise) {
+            const run = (async () => {
+                const result = await KeyManager._runSlotMigration();
+                KeyManager.slotMigrationResult = result;
+                return result;
+            })();
+            KeyManager.slotMigrationPromise = run;
+            // Clear the in-flight handle once settled so a deferred outcome retries.
+            run
+                .then((result) => {
+                if (result.mode === 'deferred') {
+                    KeyManager.slotMigrationPromise = null;
+                }
+            })
+                .catch(() => {
+                KeyManager.slotMigrationPromise = null;
+            });
+        }
+        return KeyManager.slotMigrationPromise;
+    }
+    /**
+     * One-shot slot migration state machine. All reads are DIRECT and a thrown
+     * read defers everything (zero writes/deletes) so a locked keychain is never
+     * mistaken for an empty one. INVARIANT: at every instant ≥1 readable copy of a
+     * previously-existing identity remains — legacy is deleted ONLY after the v2
+     * copy is verified re-readable in its new (non-aliasable) location.
+     */
+    static async _runSlotMigration() {
+        let store;
+        try {
+            store = await initSecureStore();
+        }
+        catch (error) {
+            return { mode: 'deferred', cause: error };
+        }
+        const migratedFlag = await KeyManager._readSlotsMigratedFlag();
+        // Read the v2 primary (dedicated keychain service).
+        let v2Private;
+        let v2Public;
+        try {
+            v2Private = await store.getItemAsync(V2_STORAGE_KEYS.PRIVATE_KEY, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
+            v2Public = await store.getItemAsync(V2_STORAGE_KEYS.PUBLIC_KEY, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
+        }
+        catch (error) {
+            return { mode: 'deferred', cause: error };
+        }
+        if (KeyManager._isHealthyPair(v2Private, v2Public)) {
+            // v2 already owns the identity. On the first observation, clean up any
+            // stale legacy copy and record the fast-path flag.
+            if (!migratedFlag) {
+                await KeyManager._bestEffortDeleteLegacyPrimaryAndBackup(store);
+                await KeyManager._setSlotsMigratedFlag();
+            }
+            return { mode: 'v2', layout: V2_SLOT_LAYOUT };
+        }
+        // v2 primary absent/partial but the flag says migration finished → v2 is
+        // simply empty (identity deleted / never created). No legacy to rescue.
+        if (migratedFlag) {
+            return { mode: 'v2', layout: V2_SLOT_LAYOUT };
+        }
+        // Read the legacy primary (default keychain service = the old `key_v1`).
+        let legacyPrivate;
+        let legacyPublic;
+        try {
+            legacyPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+            legacyPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+        }
+        catch (error) {
+            return { mode: 'deferred', cause: error };
+        }
+        if (!KeyManager._isHealthyPair(legacyPrivate, legacyPublic)) {
+            // Nothing readable in either generation → v2 is the canonical (empty) home.
+            // The marker (not this migration) decides fresh-vs-lost.
+            return { mode: 'v2', layout: V2_SLOT_LAYOUT };
+        }
+        // legacy healthy, v2 absent → migrate: copy → read-back verify → only then delete legacy.
+        const canonicalPrivate = KeyManager.canonicalPrivateKey(legacyPrivate);
+        const canonicalPublic = legacyPublic.toLowerCase();
+        try {
+            await store.setItemAsync(V2_STORAGE_KEYS.PUBLIC_KEY, canonicalPublic, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
+            await store.setItemAsync(V2_STORAGE_KEYS.PRIVATE_KEY, canonicalPrivate, KeyManager._privateWriteOpts(store, V2_PRIMARY_KEYCHAIN_SERVICE));
+            const readBackPrivate = await store.getItemAsync(V2_STORAGE_KEYS.PRIVATE_KEY, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
+            const readBackPublic = await store.getItemAsync(V2_STORAGE_KEYS.PUBLIC_KEY, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
+            const verified = readBackPrivate?.toLowerCase() === canonicalPrivate &&
+                readBackPublic?.toLowerCase() === canonicalPublic &&
+                KeyManager._isHealthyPair(readBackPrivate, readBackPublic);
+            if (!verified) {
+                // v2 write did not durably land — remove the partial v2 and serve reads
+                // from legacy this session (legacy is UNTOUCHED). Retry next launch.
+                await KeyManager._bestEffortDeleteV2Primary(store);
+                logger.warn('Identity slot migration verify failed; serving identity from legacy slots this session', { component: 'KeyManager' });
+                return { mode: 'legacy', layout: LEGACY_SLOT_LAYOUT };
+            }
+        }
+        catch (error) {
+            await KeyManager._bestEffortDeleteV2Primary(store);
+            logger.warn('Identity slot migration write threw; serving identity from legacy slots this session', { component: 'KeyManager' }, error);
+            return { mode: 'legacy', layout: LEGACY_SLOT_LAYOUT };
+        }
+        // v2 primary is verified re-readable. Migrate the backup slot (best-effort),
+        // then it is finally safe to delete the legacy generation.
+        await KeyManager._migrateBackupSlotToV2(store, canonicalPrivate, canonicalPublic);
+        await KeyManager._bestEffortDeleteLegacyPrimaryAndBackup(store);
+        await KeyManager._setSlotsMigratedFlag();
+        return { mode: 'v2', layout: V2_SLOT_LAYOUT };
+    }
+    /**
+     * Seed the v2 backup slot during migration. Prefers a healthy legacy backup;
+     * otherwise mirrors the (already-verified) v2 primary material so a v2 backup
+     * always exists on an independent keychain key. Best-effort — a failure just
+     * defers backup population to the next {@link _persistIdentityAtomic}.
+     */
+    static async _migrateBackupSlotToV2(store, primaryPrivate, primaryPublic) {
+        try {
+            let backupPrivate = null;
+            let backupPublic = null;
+            try {
+                backupPrivate = await store.getItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+                backupPublic = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+            }
+            catch (error) {
+                if (isDev()) {
+                    logger.debug('Legacy backup unreadable during migration (non-fatal)', { component: 'KeyManager' }, error);
+                }
+                backupPrivate = null;
+                backupPublic = null;
+            }
+            let seedPrivate;
+            let seedPublic;
+            if (KeyManager._isHealthyPair(backupPrivate, backupPublic)) {
+                seedPrivate = KeyManager.canonicalPrivateKey(backupPrivate);
+                seedPublic = backupPublic.toLowerCase();
+            }
+            else {
+                seedPrivate = primaryPrivate;
+                seedPublic = primaryPublic;
+            }
+            await store.setItemAsync(V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY, seedPublic, KeyManager._slotOpts(V2_BACKUP_KEYCHAIN_SERVICE));
+            await store.setItemAsync(V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY, seedPrivate, KeyManager._privateWriteOpts(store, V2_BACKUP_KEYCHAIN_SERVICE));
+            await store.setItemAsync(V2_STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString(), KeyManager._slotOpts(V2_BACKUP_KEYCHAIN_SERVICE));
+        }
+        catch (error) {
+            logger.warn('Failed to migrate identity backup slot to v2 (non-fatal)', { component: 'KeyManager' }, error);
+        }
+    }
+    /** Best-effort single delete under an optional keychain service. Cleanup only — never surfaces. */
+    static async _bestEffortDelete(store, key, service) {
+        try {
+            await store.deleteItemAsync(key, KeyManager._slotOpts(service));
+        }
+        catch (error) {
+            if (isDev()) {
+                logger.debug('Best-effort identity delete failed', { component: 'KeyManager' }, error);
+            }
+        }
+    }
+    static async _bestEffortDeleteV2Primary(store) {
+        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.PRIVATE_KEY, V2_PRIMARY_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.PUBLIC_KEY, V2_PRIMARY_KEYCHAIN_SERVICE);
+    }
+    static async _bestEffortDeleteLegacyPrimaryAndBackup(store) {
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PRIVATE_KEY);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PUBLIC_KEY);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_TIMESTAMP);
+    }
+    static async _bestEffortDeleteBackupsAllGenerations(store) {
+        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY, V2_BACKUP_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY, V2_BACKUP_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.BACKUP_TIMESTAMP, V2_BACKUP_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_TIMESTAMP);
+    }
+    /**
+     * Clear the cross-app shared identity slot (force-delete only) so a deleted
+     * identity cannot be resurrected via the recovery ladder's shared rung.
+     * Best-effort — the shared slot is a redundant convenience copy.
+     */
+    static async _clearSharedSlot(store) {
+        try {
+            if (isIOS()) {
+                const opts = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+                await store.deleteItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, opts);
+                await store.deleteItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, opts);
+            }
+            else if (isAndroid()) {
+                const bridge = await loadSharedIdentityBridge();
+                if (bridge) {
+                    await bridge.clearShared();
+                }
+                else {
+                    await store.deleteItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY);
+                    await store.deleteItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
+                }
+            }
+            KeyManager.invalidateSharedCache();
+        }
+        catch (error) {
+            logger.warn('Failed to clear shared identity slot during force delete', { component: 'KeyManager' }, error);
+        }
     }
     /**
      * Invalidate cached shared identity state
@@ -621,8 +1023,23 @@ export class KeyManager {
      *
      * @internal
      */
-    static async _persistIdentityAtomic(privateKey, publicKey) {
+    static async _persistIdentityAtomic(privateKey, publicKey, origin) {
         const store = await initSecureStore();
+        // Resolve the active slot layout (normally v2; legacy only in the rare
+        // migration-fallback session). Reading and writing the SAME layout keeps the
+        // snapshot/rollback machinery below internally consistent. A deferred
+        // migration (keychain locked) must never write blind.
+        const migration = await KeyManager._ensureIdentitySlotsMigrated();
+        if (migration.mode === 'deferred') {
+            throw new IdentityUnavailableError('Identity storage is temporarily unavailable; refusing to persist an identity.', migration.cause);
+        }
+        const layout = migration.layout;
+        const primaryReadOpts = KeyManager._slotOpts(layout.primaryService);
+        const primaryPrivWriteOpts = KeyManager._privateWriteOpts(store, layout.primaryService);
+        const primaryPubWriteOpts = KeyManager._slotOpts(layout.primaryService);
+        const backupReadOpts = KeyManager._slotOpts(layout.backupService);
+        const backupPrivWriteOpts = KeyManager._privateWriteOpts(store, layout.backupService);
+        const backupPubWriteOpts = KeyManager._slotOpts(layout.backupService);
         // Canonicalize BEFORE persistence so the stored value is always in
         // canonical 64-hex-char lowercase form going forward. This is the single
         // place all primary writes flow through, so once a value lands here all
@@ -637,8 +1054,8 @@ export class KeyManager {
         let priorPrivate;
         let priorPublic;
         try {
-            priorPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
-            priorPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+            priorPrivate = await store.getItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
+            priorPublic = await store.getItemAsync(layout.primaryPublicKeyName, primaryReadOpts);
         }
         catch (error) {
             logger.error('Failed to read existing primary before persist', error, { component: 'KeyManager' });
@@ -660,18 +1077,16 @@ export class KeyManager {
         if (priorIsHealthyDifferent && priorPrivate && priorPublic) {
             let existingBackupPublic = null;
             try {
-                existingBackupPublic = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+                existingBackupPublic = await store.getItemAsync(layout.backupPublicKeyName, backupReadOpts);
             }
             catch {
                 existingBackupPublic = null;
             }
             if (existingBackupPublic?.toLowerCase() !== priorPublic.toLowerCase()) {
                 try {
-                    await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, KeyManager.canonicalPrivateKey(priorPrivate), {
-                        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-                    });
-                    await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, priorPublic.toLowerCase());
-                    await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+                    await store.setItemAsync(layout.backupPrivateKeyName, KeyManager.canonicalPrivateKey(priorPrivate), backupPrivWriteOpts);
+                    await store.setItemAsync(layout.backupPublicKeyName, priorPublic.toLowerCase(), backupPubWriteOpts);
+                    await store.setItemAsync(layout.backupTimestampName, Date.now().toString(), backupPubWriteOpts);
                 }
                 catch (error) {
                     logger.error('Failed to back up existing identity before overwrite', error, { component: 'KeyManager' });
@@ -684,14 +1099,12 @@ export class KeyManager {
         // NOT touched here — it still holds the previous good identity until the
         // new primary is proven durable.
         try {
-            await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, canonicalPublic);
-            await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, canonicalPrivate, {
-                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-            });
+            await store.setItemAsync(layout.primaryPublicKeyName, canonicalPublic, primaryPubWriteOpts);
+            await store.setItemAsync(layout.primaryPrivateKeyName, canonicalPrivate, primaryPrivWriteOpts);
         }
         catch (error) {
             logger.error('Failed to write primary identity to secure store', error, { component: 'KeyManager' });
-            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
+            await KeyManager._rollbackPrimary(store, layout, priorPrivate, priorPublic);
             throw new IdentityPersistError('Failed to write identity to secure store', error);
         }
         // Step 2: Verify round-trip. If the store silently drops our writes
@@ -701,12 +1114,12 @@ export class KeyManager {
         let readBackPrivate;
         let readBackPublic;
         try {
-            readBackPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
-            readBackPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+            readBackPrivate = await store.getItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
+            readBackPublic = await store.getItemAsync(layout.primaryPublicKeyName, primaryReadOpts);
         }
         catch (error) {
             logger.error('Failed to read identity back after write', error, { component: 'KeyManager' });
-            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
+            await KeyManager._rollbackPrimary(store, layout, priorPrivate, priorPublic);
             throw new IdentityPersistError('Failed to verify identity after write', error);
         }
         // Hex comparisons are case-insensitive — normalize on both sides so a
@@ -715,7 +1128,7 @@ export class KeyManager {
         if (readBackPrivate?.toLowerCase() !== canonicalPrivate ||
             readBackPublic?.toLowerCase() !== canonicalPublic) {
             logger.error('Identity round-trip mismatch after write', undefined, { component: 'KeyManager' });
-            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
+            await KeyManager._rollbackPrimary(store, layout, priorPrivate, priorPublic);
             throw new IdentityPersistError('Identity write was not persisted correctly (round-trip mismatch).');
         }
         // Final sanity: derive public from the stored private and confirm the
@@ -736,7 +1149,7 @@ export class KeyManager {
             }
         }
         catch (error) {
-            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
+            await KeyManager._rollbackPrimary(store, layout, priorPrivate, priorPublic);
             if (error instanceof IdentityPersistError)
                 throw error;
             logger.error('Identity sign/verify probe failed', error, { component: 'KeyManager' });
@@ -753,31 +1166,60 @@ export class KeyManager {
         let priorBackupPublic;
         let priorBackupTimestamp;
         try {
-            priorBackupPrivate = await store.getItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
-            priorBackupPublic = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
-            priorBackupTimestamp = await store.getItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP);
+            priorBackupPrivate = await store.getItemAsync(layout.backupPrivateKeyName, backupReadOpts);
+            priorBackupPublic = await store.getItemAsync(layout.backupPublicKeyName, backupReadOpts);
+            priorBackupTimestamp = await store.getItemAsync(layout.backupTimestampName, backupReadOpts);
         }
         catch (error) {
             logger.error('Failed to snapshot identity backup before refresh', error, { component: 'KeyManager' });
-            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
+            await KeyManager._rollbackPrimary(store, layout, priorPrivate, priorPublic);
             throw new IdentityPersistError('Failed to snapshot identity backup before refresh', error);
         }
         try {
-            await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, canonicalPrivate, {
-                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-            });
-            await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, canonicalPublic);
-            await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+            await store.setItemAsync(layout.backupPrivateKeyName, canonicalPrivate, backupPrivWriteOpts);
+            await store.setItemAsync(layout.backupPublicKeyName, canonicalPublic, backupPubWriteOpts);
+            await store.setItemAsync(layout.backupTimestampName, Date.now().toString(), backupPubWriteOpts);
         }
         catch (error) {
             logger.error('Failed to refresh identity backup after primary write', error, { component: 'KeyManager' });
-            await KeyManager._rollbackBackup(store, priorBackupPrivate, priorBackupPublic, priorBackupTimestamp);
-            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
+            await KeyManager._rollbackBackup(store, layout, priorBackupPrivate, priorBackupPublic, priorBackupTimestamp);
+            await KeyManager._rollbackPrimary(store, layout, priorPrivate, priorPublic);
             throw new IdentityPersistError('Failed to refresh identity backup after primary write', error);
         }
-        // Update cache only after we are certain the identity is durable.
+        // Update cache only after we are certain the identity is durable, then fan
+        // out to identity-change subscribers.
         KeyManager.cachedPublicKey = canonicalPublic;
         KeyManager.cachedHasIdentity = true;
+        KeyManager.cachedPublicKeyResolved = false;
+        KeyManager.notifyIdentityChanged();
+        // LAST step: mirror the identity into the AndroidKeyStore-independent marker
+        // so a later keystore death can be told apart from a fresh install. This is
+        // best-effort — a marker write failure must NEVER fail an otherwise-durable
+        // persist (a subsequent healthy read re-backfills it). Rollback paths above
+        // return before reaching here, so they never touch the marker.
+        await KeyManager._syncMarkerAfterPersist(canonicalPublic, origin);
+    }
+    /**
+     * Write/refresh the identity marker after a successful persist. A same-identity
+     * re-persist (e.g. backup refresh, idempotent re-import) preserves `createdAt`
+     * and the `onboardingComplete` milestone by only updating `origin`; a NEW or
+     * switched identity writes a fresh marker. Best-effort — never throws.
+     *
+     * @internal
+     */
+    static async _syncMarkerAfterPersist(publicKey, origin) {
+        try {
+            const existing = await readIdentityMarker();
+            if (existing && existing.publicKey.toLowerCase() === publicKey.toLowerCase()) {
+                await updateIdentityMarker({ origin });
+            }
+            else {
+                await writeIdentityMarker({ publicKey, origin });
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to sync identity marker after persist (non-fatal)', { component: 'KeyManager' }, error);
+        }
     }
     /**
      * Restore the backup slot to a previously-snapshotted state. Best-effort so
@@ -785,34 +1227,35 @@ export class KeyManager {
      *
      * @internal
      */
-    static async _rollbackBackup(store, priorBackupPrivate, priorBackupPublic, priorBackupTimestamp) {
+    static async _rollbackBackup(store, layout, priorBackupPrivate, priorBackupPublic, priorBackupTimestamp) {
+        const backupPrivWriteOpts = KeyManager._privateWriteOpts(store, layout.backupService);
+        const backupPubWriteOpts = KeyManager._slotOpts(layout.backupService);
+        const backupReadOpts = KeyManager._slotOpts(layout.backupService);
         try {
             if (priorBackupPrivate) {
-                await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, priorBackupPrivate, {
-                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-                });
+                await store.setItemAsync(layout.backupPrivateKeyName, priorBackupPrivate, backupPrivWriteOpts);
             }
             else {
                 try {
-                    await store.deleteItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+                    await store.deleteItemAsync(layout.backupPrivateKeyName, backupReadOpts);
                 }
                 catch { /* best effort */ }
             }
             if (priorBackupPublic) {
-                await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, priorBackupPublic);
+                await store.setItemAsync(layout.backupPublicKeyName, priorBackupPublic, backupPubWriteOpts);
             }
             else {
                 try {
-                    await store.deleteItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+                    await store.deleteItemAsync(layout.backupPublicKeyName, backupReadOpts);
                 }
                 catch { /* best effort */ }
             }
             if (priorBackupTimestamp) {
-                await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, priorBackupTimestamp);
+                await store.setItemAsync(layout.backupTimestampName, priorBackupTimestamp, backupPubWriteOpts);
             }
             else {
                 try {
-                    await store.deleteItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP);
+                    await store.deleteItemAsync(layout.backupTimestampName, backupReadOpts);
                 }
                 catch { /* best effort */ }
             }
@@ -830,24 +1273,25 @@ export class KeyManager {
      *
      * @internal
      */
-    static async _rollbackPrimary(store, priorPrivate, priorPublic) {
+    static async _rollbackPrimary(store, layout, priorPrivate, priorPublic) {
+        const primaryPrivWriteOpts = KeyManager._privateWriteOpts(store, layout.primaryService);
+        const primaryPubWriteOpts = KeyManager._slotOpts(layout.primaryService);
+        const primaryReadOpts = KeyManager._slotOpts(layout.primaryService);
         try {
             if (priorPrivate && priorPublic) {
                 // Restore exactly what was there before the failed write.
-                await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, priorPublic, {});
-                await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, priorPrivate, {
-                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-                });
+                await store.setItemAsync(layout.primaryPublicKeyName, priorPublic, primaryPubWriteOpts);
+                await store.setItemAsync(layout.primaryPrivateKeyName, priorPrivate, primaryPrivWriteOpts);
             }
             else {
                 // There was no prior identity — leave the device empty rather than
                 // half-written so hasIdentity() does not lie.
                 try {
-                    await store.deleteItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+                    await store.deleteItemAsync(layout.primaryPublicKeyName, primaryReadOpts);
                 }
                 catch { /* best effort */ }
                 try {
-                    await store.deleteItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+                    await store.deleteItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
                 }
                 catch { /* best effort */ }
             }
@@ -877,16 +1321,50 @@ export class KeyManager {
         // The local key IS the account — clobbering it without consent is
         // catastrophic. Callers must opt in explicitly when they have already
         // confirmed (via UI) that the user has saved their recovery phrase.
+        //
+        // The guard reads storage DIRECTLY (cache-bypassing) AND consults the
+        // AndroidKeyStore-independent marker: either a stored key OR a marker means
+        // an identity exists here → refuse. A storage THROW surfaces as
+        // IdentityUnavailableError (never a blind write over a locked keystore).
         if (!options?.overwrite) {
-            const existing = await KeyManager.getPublicKey();
-            if (existing) {
-                throw new IdentityAlreadyExistsError(existing);
+            const marker = await readIdentityMarker();
+            const direct = await KeyManager._readPrimaryDirect();
+            if (direct.publicKey) {
+                throw new IdentityAlreadyExistsError(direct.publicKey);
+            }
+            if (marker) {
+                throw new IdentityAlreadyExistsError(marker.publicKey);
             }
         }
         const { privateKey, publicKey } = await KeyManager.generateKeyPair();
-        await KeyManager._persistIdentityAtomic(privateKey, publicKey);
+        await KeyManager._persistIdentityAtomic(privateKey, publicKey, 'create');
         return publicKey;
     }
+    /**
+     * Read the primary key pair DIRECTLY from storage, bypassing the in-memory
+     * cache (which a prior transient failure could have poisoned). Awaits slot
+     * migration first. Throws {@link IdentityUnavailableError} if storage is
+     * deferred/locked or a read throws — so overwrite guards never write blind.
+     *
+     * @internal
+     */
+    static async _readPrimaryDirect() {
+        const migration = await KeyManager._ensureIdentitySlotsMigrated();
+        if (migration.mode === 'deferred') {
+            throw new IdentityUnavailableError('Identity storage is temporarily unavailable; refusing to write blind.', migration.cause);
+        }
+        const layout = migration.layout;
+        const readOpts = KeyManager._slotOpts(layout.primaryService);
+        try {
+            const store = await initSecureStore();
+            const privateKey = await store.getItemAsync(layout.primaryPrivateKeyName, readOpts);
+            const publicKey = await store.getItemAsync(layout.primaryPublicKeyName, readOpts);
+            return { privateKey, publicKey };
+        }
+        catch (error) {
+            throw new IdentityUnavailableError('Could not read existing identity; refusing to write blind.', error);
+        }
+    }
     /**
      * Import an existing key pair (e.g., from recovery phrase).
      *
@@ -909,30 +1387,53 @@ export class KeyManager {
         const canonicalPrivate = KeyManager.canonicalPrivateKey(privateKey);
         const keyPair = ec.keyFromPrivate(canonicalPrivate);
         const publicKey = keyPair.getPublic('hex');
-        // Refuse silent overwrite — see createIdentity() for rationale.
+        // Refuse silent overwrite — see createIdentity() for rationale. The guard
+        // reads storage DIRECTLY (cache-bypassing) AND the marker, and treats
+        // storage as authoritative:
+        //   - stored key === this import  → safe idempotent refresh (fall through)
+        //   - stored key differs          → a DIFFERENT identity is present → refuse
+        //   - storage empty + marker for a DIFFERENT identity (lost state) → refuse
+        //   - storage empty + marker matches this import (recovery) / no marker → allow
+        // A storage throw surfaces as IdentityUnavailableError (never a blind write).
         if (!options?.overwrite) {
-            const existing = await KeyManager.getPublicKey();
-            if (existing && existing.toLowerCase() !== publicKey.toLowerCase()) {
-                throw new IdentityAlreadyExistsError(existing);
-            }
-            // If existing === publicKey, the device already has this exact identity;
-            // re-persisting is a no-op but harmless. Fall through to ensure backup
-            // is up to date.
-        }
-        await KeyManager._persistIdentityAtomic(canonicalPrivate, publicKey);
+            const marker = await readIdentityMarker();
+            const direct = await KeyManager._readPrimaryDirect();
+            const importedPub = publicKey.toLowerCase();
+            const existingPub = direct.publicKey?.toLowerCase() ?? null;
+            const markerPub = marker?.publicKey.toLowerCase() ?? null;
+            if (existingPub && existingPub !== importedPub) {
+                throw new IdentityAlreadyExistsError(direct.publicKey);
+            }
+            if (!existingPub && markerPub && markerPub !== importedPub) {
+                throw new IdentityAlreadyExistsError(marker?.publicKey);
+            }
+            // Otherwise: existing === import (idempotent refresh), or storage empty
+            // with a matching/absent marker (fresh import or lost-identity recovery)
+            // → fall through and (re-)persist to refresh the backup + marker.
+        }
+        await KeyManager._persistIdentityAtomic(canonicalPrivate, publicKey, 'import');
         return publicKey;
     }
     /**
      * Get the stored private key
      * WARNING: Only use this for signing operations within the app
+     *
+     * Preserves the "return null on any storage failure" contract signing paths
+     * rely on (a locked keychain simply means "cannot sign now"); unlike
+     * {@link getPublicKey}, it does NOT throw {@link IdentityUnavailableError}.
      */
     static async getPrivateKey() {
         if (isWebPlatform()) {
             return null; // Identity storage is only available on native platforms
         }
         try {
+            const migration = await KeyManager._ensureIdentitySlotsMigrated();
+            if (migration.mode === 'deferred') {
+                // Storage unreadable right now — preserve the null contract.
+                return null;
+            }
             const store = await initSecureStore();
-            return await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+            return await store.getItemAsync(migration.layout.primaryPrivateKeyName, KeyManager._slotOpts(migration.layout.primaryService));
         }
         catch (error) {
             // If secure store is not available, return null (no identity)
@@ -944,7 +1445,12 @@ export class KeyManager {
         }
     }
     /**
-     * Get the stored public key (cached for performance)
+     * Get the stored public key (cached for performance).
+     *
+     * Returns the public key, or `null` when a read SUCCEEDS and finds none.
+     * THROWS {@link IdentityUnavailableError} when storage is unreadable (keychain
+     * locked / module load failure) — a thrown read is NEVER flattened to `null`
+     * and NEVER cached, so a poisoned "no identity" verdict can no longer stick.
      */
     static async getPublicKey() {
         if (isWebPlatform()) {
@@ -953,30 +1459,113 @@ export class KeyManager {
         if (KeyManager.cachedPublicKey !== null) {
             return KeyManager.cachedPublicKey;
         }
+        // A genuine-absent result (read succeeded, empty) is cacheable distinctly
+        // from a thrown read — only the former sets this flag.
+        if (KeyManager.cachedPublicKeyResolved) {
+            return null;
+        }
+        const migration = await KeyManager._ensureIdentitySlotsMigrated();
+        if (migration.mode === 'deferred') {
+            throw new IdentityUnavailableError('Identity storage is temporarily unavailable (keychain locked or unreadable).', migration.cause);
+        }
         try {
             const store = await initSecureStore();
-            const publicKey = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
-            // Cache result (null is a valid cache value meaning no identity)
-            KeyManager.cachedPublicKey = publicKey;
+            const publicKey = await store.getItemAsync(migration.layout.primaryPublicKeyName, KeyManager._slotOpts(migration.layout.primaryService));
+            if (publicKey !== null) {
+                KeyManager.cachedPublicKey = publicKey;
+            }
+            else {
+                // Genuine-absent (successful empty read) IS safe to cache.
+                KeyManager.cachedPublicKeyResolved = true;
+            }
             return publicKey;
         }
         catch (error) {
-            // If secure store is not available, return null (no identity)
-            // Cache null to avoid repeated failed attempts
-            KeyManager.cachedPublicKey = null;
+            // Storage threw AFTER migration resolved — transient/unavailable. Do NOT
+            // cache; surface a typed error so callers never misread it as "no identity".
             if (isDev()) {
                 logger.warn('Failed to access secure store', { component: 'KeyManager' }, error);
             }
-            return null;
+            throw new IdentityUnavailableError('Failed to read identity from secure storage.', error);
+        }
+    }
+    /**
+     * Persist the recovery mnemonic (the 12-word phrase) into its dedicated,
+     * device-only keychain slot so the user can re-reveal it from Settings after
+     * onboarding.
+     *
+     * Called best-effort at identity creation/import, where the phrase is already
+     * in memory: a failure to persist it must NEVER fail the identity itself, so
+     * callers deliberately swallow the thrown error (logging it). Storage errors
+     * throw {@link IdentityUnavailableError} — same "cannot determine" semantics as
+     * the other getters — so a caller MAY observe/log the failure.
+     *
+     * The mnemonic is stored ONLY here — never in the marker, `getIdentityStatus`,
+     * logs, or any exported bundle.
+     */
+    static async storeRecoveryMnemonic(mnemonic) {
+        if (isWebPlatform()) {
+            return; // Identity storage is only available on native platforms
+        }
+        try {
+            const store = await initSecureStore();
+            await store.setItemAsync(RECOVERY_MNEMONIC_STORAGE_KEY, mnemonic, KeyManager._privateWriteOpts(store, RECOVERY_MNEMONIC_KEYCHAIN_SERVICE));
+        }
+        catch (error) {
+            if (isDev()) {
+                logger.warn('Failed to persist recovery mnemonic', { component: 'KeyManager' }, error);
+            }
+            throw new IdentityUnavailableError('Failed to persist recovery mnemonic.', error);
+        }
+    }
+    /**
+     * Read the stored recovery mnemonic for re-reveal in Settings.
+     *
+     * Returns the phrase, or `null` when a read SUCCEEDS and finds none — the
+     * expected result for any identity created/imported before this feature
+     * existed, since the phrase was never captured for those. THROWS
+     * {@link IdentityUnavailableError} when storage is unreadable (keychain locked
+     * / module load failure), matching {@link getPublicKey}'s contract — a thrown
+     * read is never flattened to `null`, so a caller distinguishes "phrase was
+     * never stored" from "keychain temporarily locked, retry".
+     */
+    static async getRecoveryMnemonic() {
+        if (isWebPlatform()) {
+            return null; // Identity storage is only available on native platforms
+        }
+        try {
+            const store = await initSecureStore();
+            return await store.getItemAsync(RECOVERY_MNEMONIC_STORAGE_KEY, KeyManager._slotOpts(RECOVERY_MNEMONIC_KEYCHAIN_SERVICE));
+        }
+        catch (error) {
+            if (isDev()) {
+                logger.warn('Failed to read recovery mnemonic', { component: 'KeyManager' }, error);
+            }
+            throw new IdentityUnavailableError('Failed to read recovery mnemonic from secure storage.', error);
         }
     }
+    /**
+     * Delete the stored recovery mnemonic. Best-effort: a delete failure is logged
+     * and swallowed, never thrown — it runs inside the identity-deletion path where
+     * an unreadable keychain must not abort the wider teardown.
+     */
+    static async deleteRecoveryMnemonic() {
+        if (isWebPlatform()) {
+            return; // Identity storage is only available on native platforms
+        }
+        const store = await initSecureStore();
+        await KeyManager._bestEffortDelete(store, RECOVERY_MNEMONIC_STORAGE_KEY, RECOVERY_MNEMONIC_KEYCHAIN_SERVICE);
+    }
     /**
      * Check if a complete, parseable identity exists on this device.
      *
      * Returns `true` only when BOTH the private and public keys are present,
      * both are well-formed, AND the public key derives from the private key.
-     * A partially-written or corrupted identity returns `false` so that
-     * downstream code can resume the create / restore flow correctly.
+     * A partially-written or corrupted identity (read succeeded, bytes empty/bad)
+     * returns `false` so that downstream code can resume the create / restore flow.
+     * THROWS {@link IdentityUnavailableError} when storage is unreadable — a locked
+     * keychain must never be mistaken for "no identity" (the old behavior that let
+     * onboarding treat a transient lock as a blank device).
      *
      * Note: this does NOT perform the full sign/verify roundtrip — call
      * `verifyIdentityIntegrity()` for that.
@@ -988,23 +1577,26 @@ export class KeyManager {
         if (KeyManager.cachedHasIdentity !== null) {
             return KeyManager.cachedHasIdentity;
         }
+        const migration = await KeyManager._ensureIdentitySlotsMigrated();
+        if (migration.mode === 'deferred') {
+            throw new IdentityUnavailableError('Identity storage is temporarily unavailable.', migration.cause);
+        }
         let privateKey;
         let publicKey;
         try {
             const store = await initSecureStore();
             [privateKey, publicKey] = await Promise.all([
-                store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY),
-                store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY),
+                store.getItemAsync(migration.layout.primaryPrivateKeyName, KeyManager._slotOpts(migration.layout.primaryService)),
+                store.getItemAsync(migration.layout.primaryPublicKeyName, KeyManager._slotOpts(migration.layout.primaryService)),
             ]);
         }
         catch (error) {
             // Storage threw — could be a transient keychain lock (e.g., background
-            // fetch before the device is unlocked). Do NOT cache `false`: if we
-            // did, the next call would skip storage entirely and return false even
-            // after the device is unlocked. Just return false and let the next
-            // call retry from storage.
+            // fetch before the device is unlocked). Do NOT cache; throw a TYPED error
+            // so callers distinguish "temporarily unavailable" from "genuinely absent"
+            // instead of silently treating a locked keystore as a blank device.
             logger.error('Failed to read identity from secure storage', error, { component: 'KeyManager' });
-            return false;
+            throw new IdentityUnavailableError('Failed to read identity from secure storage.', error);
         }
         // Storage succeeded. Now classify the result. From here onward, any
         // outcome is stable and safe to cache (the bytes won't change between
@@ -1058,6 +1650,75 @@ export class KeyManager {
         }
         return hasIdentity;
     }
+    /**
+     * Authoritative identity verdict — the corruption-vs-fresh-install
+     * disambiguator that routing (commons) keys off of.
+     *
+     * - Healthy pair → `present` (and the marker is backfilled if missing or
+     *   pointing at a different key, `origin: 'backfill'`).
+     * - Read succeeded but no healthy pair, WITH a marker → `lost` (keystore death
+     *   / corruption; route to recovery, NEVER to create).
+     * - Read succeeded, no pair, NO marker → `absent` (a genuine fresh device; the
+     *   only state that may route to onboarding/create).
+     * - A read THREW → `unavailable` (keychain locked); this verdict is NEVER
+     *   cached, so a later call re-reads.
+     *
+     * @param opts.bypassCache When true, never reads OR writes the in-memory cache
+     *   — a pure, fresh storage verdict for the auto-create interlock preflight.
+     */
+    static async getIdentityStatus(opts) {
+        if (isWebPlatform()) {
+            return { state: 'absent' }; // Identity storage is only available on native platforms
+        }
+        const bypassCache = opts?.bypassCache === true;
+        // Read the marker FIRST (fail-open null) — it is the AndroidKeyStore-independent
+        // signal that survives a keystore death.
+        const marker = await readIdentityMarker();
+        const migration = await KeyManager._ensureIdentitySlotsMigrated();
+        if (migration.mode === 'deferred') {
+            return { state: 'unavailable', cause: migration.cause };
+        }
+        let privateKey;
+        let publicKey;
+        try {
+            const store = await initSecureStore();
+            const readOpts = KeyManager._slotOpts(migration.layout.primaryService);
+            privateKey = await store.getItemAsync(migration.layout.primaryPrivateKeyName, readOpts);
+            publicKey = await store.getItemAsync(migration.layout.primaryPublicKeyName, readOpts);
+        }
+        catch (error) {
+            // Storage threw — NEVER cache this verdict; callers retry.
+            return { state: 'unavailable', cause: error };
+        }
+        if (KeyManager._isHealthyPair(privateKey, publicKey) && publicKey) {
+            const canonicalPublic = publicKey.toLowerCase();
+            // Backfill the marker when missing or pointing at a DIFFERENT identity —
+            // e.g. a loss that predates markers, healed on first healthy read.
+            if (!marker || marker.publicKey.toLowerCase() !== canonicalPublic) {
+                try {
+                    await writeIdentityMarker({ publicKey: canonicalPublic, origin: 'backfill' });
+                }
+                catch (error) {
+                    logger.warn('Failed to backfill identity marker', { component: 'KeyManager' }, error);
+                }
+            }
+            if (!bypassCache) {
+                KeyManager.cachedPublicKey = canonicalPublic;
+                KeyManager.cachedHasIdentity = true;
+                KeyManager.cachedPublicKeyResolved = false;
+            }
+            return { state: 'present', publicKey: canonicalPublic };
+        }
+        // Read succeeded but no healthy pair present.
+        if (!bypassCache) {
+            KeyManager.cachedHasIdentity = false;
+            KeyManager.cachedPublicKeyResolved = true;
+        }
+        if (marker) {
+            return { state: 'lost', marker };
+        }
+        return { state: 'absent' };
+    }
     /**
      * Delete the stored identity (both keys)
      * Use with EXTREME caution - this is irreversible without a recovery phrase
@@ -1075,6 +1736,8 @@ export class KeyManager {
             throw new Error('Identity deletion requires explicit user confirmation. This is a safety measure to prevent accidental data loss.');
         }
         if (!force) {
+            // May throw IdentityUnavailableError if storage is locked — correct: a
+            // non-force delete must abort rather than run against an unreadable store.
             const hasIdentity = await KeyManager.hasIdentity();
             if (!hasIdentity) {
                 return; // Nothing to delete
@@ -1095,21 +1758,42 @@ export class KeyManager {
                 }
             }
         }
-        await store.deleteItemAsync(STORAGE_KEYS.PRIVATE_KEY);
-        await store.deleteItemAsync(STORAGE_KEYS.PUBLIC_KEY);
-        // Invalidate cache
-        KeyManager.invalidateCache();
-        // Also clear backup if force deletion
+        // Delete the primary from the active layout (authoritative), then best-effort
+        // delete BOTH generations so a stale legacy copy can never resurrect the
+        // identity after deletion.
+        const migration = await KeyManager._ensureIdentitySlotsMigrated();
+        if (migration.mode !== 'deferred') {
+            const layout = migration.layout;
+            const readOpts = KeyManager._slotOpts(layout.primaryService);
+            await store.deleteItemAsync(layout.primaryPrivateKeyName, readOpts);
+            await store.deleteItemAsync(layout.primaryPublicKeyName, readOpts);
+        }
+        await KeyManager._bestEffortDeleteV2Primary(store);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PRIVATE_KEY);
+        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PUBLIC_KEY);
+        // Always drop the stored recovery mnemonic — it is scoped to the identity
+        // being deleted, so a leftover would let Settings reveal a stale phrase for
+        // an identity that no longer exists (or a DIFFERENT one after re-onboarding).
+        await KeyManager.deleteRecoveryMnemonic();
+        // Also clear backups + the shared slot on force deletion, so a deleted
+        // identity cannot be resurrected from any recovery source.
         if (force) {
-            try {
-                await store.deleteItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
-                await store.deleteItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
-                await store.deleteItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP);
-            }
-            catch (error) {
-                // Ignore backup deletion errors
-            }
+            await KeyManager._bestEffortDeleteBackupsAllGenerations(store);
+            await KeyManager._clearSharedSlot(store);
         }
+        // Clear the marker AFTER key deletion succeeds — a marker must never outlive
+        // its identity (a leftover marker would route a truly-absent device to
+        // `recovery` instead of `welcome`).
+        try {
+            await clearIdentityMarker();
+        }
+        catch (error) {
+            logger.warn('Failed to clear identity marker during delete', { component: 'KeyManager' }, error);
+        }
+        // Invalidate cache LAST — its subscriber fan-out fires only after both the
+        // keys AND the marker are gone, so a routing subscriber that re-reads on the
+        // notification observes `absent`, never a transient `lost`.
+        KeyManager.invalidateCache();
     }
     /**
      * Backup identity to SecureStore (separate backup storage)
@@ -1121,17 +1805,23 @@ export class KeyManager {
         }
         try {
             const store = await initSecureStore();
-            const privateKey = await KeyManager.getPrivateKey();
-            const publicKey = await KeyManager.getPublicKey();
+            const migration = await KeyManager._ensureIdentitySlotsMigrated();
+            if (migration.mode === 'deferred') {
+                return false; // Cannot read the primary safely → nothing to back up
+            }
+            const layout = migration.layout;
+            // Read the primary DIRECTLY (raw) rather than via getPublicKey (which now
+            // throws) — a locked keychain here should simply mean "nothing to back up".
+            const primaryReadOpts = KeyManager._slotOpts(layout.primaryService);
+            const privateKey = await store.getItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
+            const publicKey = await store.getItemAsync(layout.primaryPublicKeyName, primaryReadOpts);
             if (!privateKey || !publicKey) {
                 return false; // Nothing to backup
             }
             // Store backup in SecureStore (still secure, but separate from primary storage)
-            await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, privateKey, {
-                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-            });
-            await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, publicKey);
-            await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+            await store.setItemAsync(layout.backupPrivateKeyName, privateKey, KeyManager._privateWriteOpts(store, layout.backupService));
+            await store.setItemAsync(layout.backupPublicKeyName, publicKey, KeyManager._slotOpts(layout.backupService));
+            await store.setItemAsync(layout.backupTimestampName, Date.now().toString(), KeyManager._slotOpts(layout.backupService));
             return true;
         }
         catch (error) {
@@ -1215,6 +1905,15 @@ export class KeyManager {
         }
         try {
             const store = await initSecureStore();
+            const migration = await KeyManager._ensureIdentitySlotsMigrated();
+            if (migration.mode === 'deferred') {
+                // Storage locked — refuse to restore (guard 2). Retry a later call.
+                logger.warn('restoreIdentityFromBackup: identity storage unavailable. Refusing to restore.', { component: 'KeyManager' });
+                return false;
+            }
+            const layout = migration.layout;
+            const primaryReadOpts = KeyManager._slotOpts(layout.primaryService);
+            const backupReadOpts = KeyManager._slotOpts(layout.backupService);
             // Read the primary DIRECTLY (not via the error-swallowing getters) so
             // we can distinguish a transient read failure from a genuinely absent
             // key. A thrown read here means the keychain is locked/unavailable —
@@ -1223,8 +1922,8 @@ export class KeyManager {
             let primaryPrivate;
             let primaryPublic;
             try {
-                primaryPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
-                primaryPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+                primaryPrivate = await store.getItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
+                primaryPublic = await store.getItemAsync(layout.primaryPublicKeyName, primaryReadOpts);
             }
             catch (error) {
                 logger.warn('restoreIdentityFromBackup: could not read primary (transient?). Refusing to restore.', { component: 'KeyManager' }, error);
@@ -1240,8 +1939,8 @@ export class KeyManager {
                 }
             }
             // Load + validate the backup.
-            const backupPrivateKey = await store.getItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
-            const backupPublicKey = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+            const backupPrivateKey = await store.getItemAsync(layout.backupPrivateKeyName, backupReadOpts);
+            const backupPublicKey = await store.getItemAsync(layout.backupPublicKeyName, backupReadOpts);
             if (!backupPrivateKey || !backupPublicKey) {
                 return false; // No backup available
             }
@@ -1277,13 +1976,13 @@ export class KeyManager {
             // Safe to restore: rebuild the primary using the same atomic write
             // path createIdentity uses, including verification.
             try {
-                await KeyManager._persistIdentityAtomic(backupPrivateKey, backupPublicKey);
+                await KeyManager._persistIdentityAtomic(backupPrivateKey, backupPublicKey, 'restore');
             }
             catch (error) {
                 logger.error('Failed to persist identity restored from backup', error, { component: 'KeyManager' });
                 return false;
             }
-            await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+            await store.setItemAsync(layout.backupTimestampName, Date.now().toString(), backupReadOpts);
             return true;
         }
         catch (error) {
@@ -1291,6 +1990,116 @@ export class KeyManager {
             return false;
         }
     }
+    /**
+     * Recovery ladder — restore a `lost` identity from an independent,
+     * `key_v1`-surviving source WITHOUT the user re-entering their recovery phrase.
+     *
+     * Gated on {@link getIdentityStatus} being `lost` (marker present, keys empty):
+     *   - `present` / `absent` → `not-lost` (nothing to recover / nothing lost)
+     *   - `unavailable`        → `unavailable` (keychain locked; retry later)
+     *
+     * Rungs, tried in order, each fully validated (well-formed + derive-match +
+     * `publicKey === marker.publicKey`, so a source holding a DIFFERENT account is
+     * SKIPPED, never restored):
+     *   1. the v2 backup slot (independent keychain key from the primary), then
+     *   2. the cross-app shared slot (Android bridge `getShared` / iOS keychain
+     *      group) — the copy that survives a primary+backup `key_v1` death.
+     *
+     * On success it re-persists via {@link _persistIdentityAtomic} (origin
+     * `'restore'`) and invalidates the cache so routing re-reads `present`. When no
+     * rung matches, the UI proceeds to recovery-phrase entry.
+     */
+    static async attemptIdentityRecovery() {
+        if (isWebPlatform()) {
+            return { recovered: false, reason: 'not-lost' };
+        }
+        const status = await KeyManager.getIdentityStatus({ bypassCache: true });
+        if (status.state === 'present' || status.state === 'absent') {
+            return { recovered: false, reason: 'not-lost' };
+        }
+        if (status.state === 'unavailable') {
+            return { recovered: false, reason: 'unavailable' };
+        }
+        // status.state === 'lost'
+        const expectedPublic = status.marker.publicKey.toLowerCase();
+        let sawMismatch = false;
+        // Rung 1: backup slot.
+        const backupCandidate = await KeyManager._readBackupCandidate();
+        if (backupCandidate) {
+            if (backupCandidate.publicKey.toLowerCase() === expectedPublic) {
+                if (await KeyManager._commitRecovery(backupCandidate.privateKey, backupCandidate.publicKey)) {
+                    return { recovered: true, source: 'backup', publicKey: backupCandidate.publicKey };
+                }
+            }
+            else {
+                sawMismatch = true;
+            }
+        }
+        // Rung 2: cross-app shared slot.
+        const sharedCandidate = await KeyManager._readSharedCandidate();
+        if (sharedCandidate) {
+            if (sharedCandidate.publicKey.toLowerCase() === expectedPublic) {
+                if (await KeyManager._commitRecovery(sharedCandidate.privateKey, sharedCandidate.publicKey)) {
+                    return { recovered: true, source: 'shared', publicKey: sharedCandidate.publicKey };
+                }
+            }
+            else {
+                sawMismatch = true;
+            }
+        }
+        // A source existed but identified a DIFFERENT account — never silently
+        // switched. Report `mismatch` so the UI can require explicit confirmation.
+        return { recovered: false, reason: sawMismatch ? 'mismatch' : 'no-sources' };
+    }
+    /** Read the active-layout backup slot as a healthy candidate, or null. @internal */
+    static async _readBackupCandidate() {
+        try {
+            const migration = await KeyManager._ensureIdentitySlotsMigrated();
+            if (migration.mode === 'deferred') {
+                return null;
+            }
+            const layout = migration.layout;
+            const backupReadOpts = KeyManager._slotOpts(layout.backupService);
+            const store = await initSecureStore();
+            const privateKey = await store.getItemAsync(layout.backupPrivateKeyName, backupReadOpts);
+            const publicKey = await store.getItemAsync(layout.backupPublicKeyName, backupReadOpts);
+            if (KeyManager._isHealthyPair(privateKey, publicKey) && privateKey && publicKey) {
+                return { privateKey, publicKey };
+            }
+            return null;
+        }
+        catch (error) {
+            logger.warn('Recovery: failed to read backup slot', { component: 'KeyManager' }, error);
+            return null;
+        }
+    }
+    /** Read the cross-app shared slot as a healthy candidate, or null. @internal */
+    static async _readSharedCandidate() {
+        try {
+            const privateKey = await KeyManager.getSharedPrivateKey();
+            const publicKey = await KeyManager.getSharedPublicKey();
+            if (KeyManager._isHealthyPair(privateKey, publicKey) && privateKey && publicKey) {
+                return { privateKey, publicKey };
+            }
+            return null;
+        }
+        catch (error) {
+            logger.warn('Recovery: failed to read shared slot', { component: 'KeyManager' }, error);
+            return null;
+        }
+    }
+    /** Persist a validated recovery candidate + refresh caches/subscribers. @internal */
+    static async _commitRecovery(privateKey, publicKey) {
+        try {
+            await KeyManager._persistIdentityAtomic(privateKey, publicKey, 'restore');
+            KeyManager.invalidateCache();
+            return true;
+        }
+        catch (error) {
+            logger.error('Recovery: failed to persist recovered identity', error, { component: 'KeyManager' });
+            return false;
+        }
+    }
     /**
      * Get the elliptic curve key object from the stored private key
      * Used internally for signing operations
@@ -1450,4 +2259,21 @@ KeyManager.cachedPublicKey = null;
 KeyManager.cachedHasIdentity = null;
 KeyManager.cachedSharedPublicKey = null;
 KeyManager.cachedHasSharedIdentity = null;
+/**
+ * Distinguishes "public key genuinely absent (a successful empty read, safe to
+ * cache)" from "never resolved / storage threw (must NOT be cached)". A `null`
+ * {@link cachedPublicKey} alone is ambiguous — this flag makes the genuine
+ * absence cacheable WITHOUT ever caching a null produced by a thrown read.
+ */
+KeyManager.cachedPublicKeyResolved = false;
+/** Listeners notified synchronously whenever the identity verdict may have changed. */
+KeyManager.identityChangeListeners = new Set();
+/**
+ * Memoized one-run-per-process slot migration. `slotMigrationResult` caches a
+ * STABLE outcome (`v2`/`legacy`); a `deferred` outcome is intentionally not
+ * cached (the in-flight promise is cleared) so a later call retries once the
+ * keychain unlocks.
+ */
+KeyManager.slotMigrationPromise = null;
+KeyManager.slotMigrationResult = null;
 export default KeyManager;