@oxy.so/core 1.0.0

package/dist/cjs/crypto/keyManager.js

@@ -0,0 +1,2234 @@
+"use strict";
+/**
+ * Key Manager - ECDSA secp256k1 Key Generation and Storage
+ *
+ * Handles secure generation, storage, and retrieval of cryptographic keys.
+ * Private keys are stored securely using expo-secure-store and never leave the device.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyManager = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = void 0;
+const platform_1 = require("../utils/platform");
+const protocol_1 = require("@oxy.so/protocol");
+const secp256k1_1 = require("@oxy.so/protocol/secp256k1");
+const logger_1 = require("../logger");
+const kdf_1 = require("./kdf");
+const identityMarker_1 = require("./identityMarker");
+/**
+ * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
+ * is invoked while a valid identity already exists on the device.
+ *
+ * The local private key IS the user's identity — overwriting it without
+ * explicit consent permanently loses access to their account (unless
+ * they previously saved their recovery phrase). This error forces callers
+ * to make an explicit, audited decision instead of silently clobbering.
+ */
+class IdentityAlreadyExistsError extends Error {
+    constructor(existingPublicKey) {
+        super('An identity already exists on this device. Refusing to overwrite without explicit consent. ' +
+            'If you really want to replace it, ensure the user has saved their recovery phrase, then call ' +
+            'the operation with { overwrite: true }.');
+        this.name = 'IdentityAlreadyExistsError';
+        this.existingPublicKey = existingPublicKey;
+    }
+}
+exports.IdentityAlreadyExistsError = IdentityAlreadyExistsError;
+/**
+ * Thrown when a freshly written identity cannot be read back, parsed, or
+ * round-tripped through sign/verify. Indicates a storage failure or
+ * corruption that would otherwise silently leave the user with an
+ * unusable account.
+ */
+class IdentityPersistError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'IdentityPersistError';
+    }
+}
+exports.IdentityPersistError = 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".
+ */
+class IdentityUnavailableError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'IdentityUnavailableError';
+    }
+}
+exports.IdentityUnavailableError = IdentityUnavailableError;
+/**
+ * HKDF salt that domain-separates every identity-scoped seed produced by
+ * {@link KeyManager.deriveScopedSeed}. Versioned so a future scheme change is a
+ * new, non-colliding tag. The per-app domain (e.g. Oxy Pay's FairCoin wallet)
+ * is carried by the caller's `info` string, not this salt.
+ */
+const SCOPED_SEED_KDF_SALT = 'oxy-identity-scoped-seed-v1';
+/** UTF-8 encode an ASCII label to bytes (HKDF salt/info). */
+function utf8ToBytes(label) {
+    return new TextEncoder().encode(label);
+}
+/** Decode a hex string to bytes. Inverse of {@link uint8ArrayToHex}. */
+function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+const STORAGE_KEYS = {
+    PRIVATE_KEY: 'oxy_identity_private_key',
+    PUBLIC_KEY: 'oxy_identity_public_key',
+    BACKUP_PRIVATE_KEY: 'oxy_identity_backup_private_key',
+    BACKUP_PUBLIC_KEY: 'oxy_identity_backup_public_key',
+    BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp',
+    // Shared keys accessible across all Oxy apps (iOS Keychain Group / Android Account Manager)
+    SHARED_PRIVATE_KEY: 'oxy_shared_identity_private_key',
+    SHARED_PUBLIC_KEY: 'oxy_shared_identity_public_key',
+    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
+ * Format: [Team ID].so.oxy.shared or group.so.oxy.shared
+ */
+const IOS_KEYCHAIN_GROUP = 'group.so.oxy.shared';
+/**
+ * Android Account Manager type for shared authentication
+ * Used with sharedUserId to share sessions across apps
+ */
+const ANDROID_ACCOUNT_TYPE = 'com.oxy.account';
+/**
+ * Initialize React Native specific modules
+ *
+ * Delegates to `@oxy.so/protocol`'s `platform/crypto`, a per-platform module
+ * (`crypto.ts` vs `crypto.native.ts`) selected by the
+ * consumer's bundler. On RN it returns a statically-imported handle to
+ * `expo-secure-store`; off RN it throws (and is never called because every
+ * caller is gated by `isWebPlatform()` / native-only paths).
+ */
+async function initSecureStore() {
+    try {
+        return await (0, protocol_1.loadSecureStore)();
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load expo-secure-store: ${errorMessage}. ` +
+            'Make sure expo-secure-store is installed and properly configured.');
+    }
+}
+/**
+ * Check if we're on web platform
+ * Identity storage is only available on native platforms (iOS/Android)
+ */
+function isWebPlatform() {
+    return (0, platform_1.isWeb)();
+}
+async function initExpoCrypto() {
+    // Same per-platform delegation as initSecureStore — see comment there.
+    return (0, protocol_1.loadExpoCrypto)();
+}
+/**
+ * Convert Uint8Array to hexadecimal string
+ * Works in both Node.js and React Native
+ */
+function uint8ArrayToHex(bytes) {
+    return Array.from(bytes)
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Generate cryptographically secure random bytes
+ */
+async function getSecureRandomBytes(length) {
+    // In React Native, always use expo-crypto
+    if ((0, protocol_1.isReactNative)() || !(0, protocol_1.isNodeJS)()) {
+        const Crypto = await initExpoCrypto();
+        return Crypto.getRandomBytes(length);
+    }
+    // In Node.js, use Node's crypto module.
+    //
+    // `loadNodeCrypto` is per-platform: the default variant performs
+    // `await import('crypto')`, the RN variant throws (and we'd never reach
+    // here on RN because the early-return above caught it).
+    try {
+        const nodeCrypto = await (0, protocol_1.loadNodeCrypto)();
+        return new Uint8Array(nodeCrypto.randomBytes(length));
+    }
+    catch (error) {
+        // Fallback to expo-crypto if Node crypto fails (defensive — should not
+        // happen on real Node, but the platform-detection edge cases are
+        // surprisingly varied).
+        const Crypto = await initExpoCrypto();
+        return Crypto.getRandomBytes(length);
+    }
+}
+class KeyManager {
+    /**
+     * Invalidate cached identity state
+     * Called internally when identity is created/deleted/imported
+     */
+    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_1.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 (!(0, protocol_1.isReactNative)()) {
+            return null;
+        }
+        try {
+            const mod = await (0, protocol_1.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 ((0, logger_1.isDev)()) {
+                logger_1.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_1.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_1.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 ((0, logger_1.isDev)()) {
+                    logger_1.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_1.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 ((0, logger_1.isDev)()) {
+                logger_1.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 ((0, platform_1.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 ((0, platform_1.isAndroid)()) {
+                const bridge = await (0, protocol_1.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_1.logger.warn('Failed to clear shared identity slot during force delete', { component: 'KeyManager' }, error);
+        }
+    }
+    /**
+     * Invalidate cached shared identity state
+     * Called internally when shared identity is created/deleted/imported
+     */
+    static invalidateSharedCache() {
+        KeyManager.cachedSharedPublicKey = null;
+        KeyManager.cachedHasSharedIdentity = null;
+    }
+    /**
+     * Lowercase and pad to canonical 64-hex-char form.
+     *
+     * Tolerates legacy leading-zero-stripped keys and externally imported
+     * uppercase hex. Every derivation path canonicalizes first so storage
+     * representation cannot change the resulting identity.
+     *
+     * Private (used only inside KeyManager) — public consumers should not need
+     * to think about hex representation.
+     */
+    static canonicalPrivateKey(key) {
+        return (0, secp256k1_1.normalizeSecp256k1PrivateKey)(key);
+    }
+    /**
+     * Generate a new ECDSA secp256k1 key pair
+     * Returns the keys in hexadecimal format
+     */
+    static generateKeyPairSync() {
+        return (0, secp256k1_1.generateSecp256k1KeyPair)();
+    }
+    /**
+     * Generate a new key pair using secure random bytes
+     */
+    static async generateKeyPair() {
+        for (let attempt = 0; attempt < 128; attempt += 1) {
+            const privateKey = uint8ArrayToHex(await getSecureRandomBytes(32));
+            if ((0, secp256k1_1.isValidSecp256k1PrivateKey)(privateKey)) {
+                return { privateKey, publicKey: (0, secp256k1_1.deriveSecp256k1PublicKey)(privateKey) };
+            }
+        }
+        throw new Error('Unable to generate a valid secp256k1 private key');
+    }
+    // ==================== SHARED IDENTITY METHODS ====================
+    // These methods enable cross-app session sharing (like Google)
+    // iOS: Uses Keychain Access Groups
+    // Android: Uses Account Manager with shared user ID
+    // =================================================================
+    /**
+     * Create a shared identity accessible across all Oxy apps
+     *
+     * iOS: Stores in shared keychain group (requires entitlement configuration)
+     * Android: Stores in Account Manager (requires sharedUserId in manifest)
+     *
+     * This enables true cross-app SSO - when user signs in to one Oxy app,
+     * they're automatically signed in to all other Oxy apps.
+     *
+     * @returns Public key of the shared identity
+     * @throws Error if not on native platform or if sharing is not configured
+     */
+    static async createSharedIdentity() {
+        if (isWebPlatform()) {
+            throw new Error('Shared identity is only available on native platforms (iOS/Android).');
+        }
+        const store = await initSecureStore();
+        const { privateKey, publicKey } = await KeyManager.generateKeyPair();
+        if ((0, platform_1.isIOS)()) {
+            // iOS: Store in shared keychain group
+            // Note: keychainAccessGroup requires Keychain Sharing capability in Xcode
+            try {
+                const privateOpts = {
+                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                    keychainAccessGroup: IOS_KEYCHAIN_GROUP, // Enables sharing across apps
+                };
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, privateOpts);
+                const publicOpts = {
+                    keychainAccessGroup: IOS_KEYCHAIN_GROUP,
+                };
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, publicOpts);
+            }
+            catch (error) {
+                throw new Error(`Failed to create shared identity on iOS. Ensure your app has the Keychain Sharing capability enabled with access group "${IOS_KEYCHAIN_GROUP}". Error: ${error}`);
+            }
+        }
+        else if ((0, platform_1.isAndroid)()) {
+            // Android: write through the cross-app bridge (`@oxy.so/expo-oxy-identity`)
+            // when present — it persists into Commons's hardware-backed
+            // EncryptedSharedPreferences behind a signature-protected ContentProvider,
+            // so same-key Oxy apps can read it. When the bridge is not linked, fall
+            // back to the package-private secure store (no cross-app sharing).
+            const bridge = await (0, protocol_1.loadSharedIdentityBridge)();
+            if (bridge) {
+                await bridge.putShared(privateKey, publicKey);
+            }
+            else {
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, {
+                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                });
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+            }
+        }
+        // Update cache
+        KeyManager.cachedSharedPublicKey = publicKey;
+        KeyManager.cachedHasSharedIdentity = true;
+        if ((0, logger_1.isDev)()) {
+            logger_1.logger.debug('Shared identity created successfully', { component: 'KeyManager' });
+        }
+        return publicKey;
+    }
+    /**
+     * Get the shared public key (accessible across all Oxy apps)
+     *
+     * @returns Shared public key or null if no shared identity exists
+     */
+    static async getSharedPublicKey() {
+        if (isWebPlatform()) {
+            return null;
+        }
+        // Return cached value if available
+        if (KeyManager.cachedSharedPublicKey !== null) {
+            return KeyManager.cachedSharedPublicKey;
+        }
+        try {
+            const store = await initSecureStore();
+            let publicKey = null;
+            if ((0, platform_1.isIOS)()) {
+                const opts = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+                publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, opts);
+            }
+            else if ((0, platform_1.isAndroid)()) {
+                // Android reads through the cross-app bridge; when it is not linked, fall
+                // back to the package-private store the fallback write path used.
+                const bridge = await (0, protocol_1.loadSharedIdentityBridge)();
+                if (bridge) {
+                    publicKey = (await bridge.getShared())?.publicKey ?? null;
+                }
+                else {
+                    publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
+                }
+            }
+            // Cache result
+            KeyManager.cachedSharedPublicKey = publicKey;
+            return publicKey;
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.warn('Failed to get shared public key', { component: 'KeyManager' }, error);
+            }
+            KeyManager.cachedSharedPublicKey = null;
+            return null;
+        }
+    }
+    /**
+     * Get the shared private key (for signing operations)
+     *
+     * WARNING: Only use this for signing operations within the app.
+     * The private key should NEVER be transmitted or exposed.
+     *
+     * @returns Shared private key or null if no shared identity exists
+     */
+    static async getSharedPrivateKey() {
+        if (isWebPlatform()) {
+            return null;
+        }
+        try {
+            const store = await initSecureStore();
+            let privateKey = null;
+            if ((0, platform_1.isIOS)()) {
+                const opts = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+                privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, opts);
+            }
+            else if ((0, platform_1.isAndroid)()) {
+                // Android reads through the cross-app bridge; when it is not linked, fall
+                // back to the package-private store the fallback write path used.
+                const bridge = await (0, protocol_1.loadSharedIdentityBridge)();
+                if (bridge) {
+                    privateKey = (await bridge.getShared())?.privateKey ?? null;
+                }
+                else {
+                    privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY);
+                }
+            }
+            return privateKey;
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.warn('Failed to get shared private key', { component: 'KeyManager' }, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Check if a shared identity exists (accessible across all Oxy apps)
+     *
+     * @returns True if shared identity exists, false otherwise
+     */
+    static async hasSharedIdentity() {
+        if (isWebPlatform()) {
+            return false;
+        }
+        // Return cached value if available
+        if (KeyManager.cachedHasSharedIdentity !== null) {
+            return KeyManager.cachedHasSharedIdentity;
+        }
+        try {
+            const privateKey = await KeyManager.getSharedPrivateKey();
+            const hasShared = privateKey !== null;
+            // Cache result
+            KeyManager.cachedHasSharedIdentity = hasShared;
+            return hasShared;
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.warn('Failed to check shared identity', { component: 'KeyManager' }, error);
+            }
+            KeyManager.cachedHasSharedIdentity = false;
+            return false;
+        }
+    }
+    /**
+     * Import an existing key pair as shared identity
+     *
+     * This is used when:
+     * 1. User signs in to a new Oxy app for the first time
+     * 2. User has existing identity on another Oxy app
+     * 3. We want to sync the identity across apps
+     *
+     * @param privateKey - Private key in hex format
+     * @returns Public key
+     */
+    static async importSharedIdentity(privateKey) {
+        if (isWebPlatform()) {
+            throw new Error('Shared identity import is only available on native platforms.');
+        }
+        const store = await initSecureStore();
+        // Canonicalize incoming key BEFORE storage so the stored value is always
+        // in canonical 64-hex-char lowercase form going forward. Without this,
+        // legacy short keys would derive a different public key on the read path.
+        const canonicalPrivate = KeyManager.canonicalPrivateKey(privateKey);
+        const publicKey = (0, secp256k1_1.deriveSecp256k1PublicKey)(canonicalPrivate);
+        if ((0, platform_1.isIOS)()) {
+            const privateOpts = {
+                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                keychainAccessGroup: IOS_KEYCHAIN_GROUP,
+            };
+            await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, privateOpts);
+            const publicOpts = {
+                keychainAccessGroup: IOS_KEYCHAIN_GROUP,
+            };
+            await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, publicOpts);
+        }
+        else if ((0, platform_1.isAndroid)()) {
+            // Android: write through the cross-app bridge when present; otherwise the
+            // package-private store (kept consistent with the read fallback).
+            const bridge = await (0, protocol_1.loadSharedIdentityBridge)();
+            if (bridge) {
+                await bridge.putShared(canonicalPrivate, publicKey);
+            }
+            else {
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, {
+                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                });
+                await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey);
+            }
+        }
+        // Update cache
+        KeyManager.cachedSharedPublicKey = publicKey;
+        KeyManager.cachedHasSharedIdentity = true;
+        if ((0, logger_1.isDev)()) {
+            logger_1.logger.debug('Shared identity imported successfully', { component: 'KeyManager' });
+        }
+        return publicKey;
+    }
+    /**
+     * Store session information in shared storage
+     *
+     * This allows all Oxy apps to access the same session without
+     * re-authenticating. When user signs in to one app, all apps
+     * get the session automatically.
+     *
+     * @param sessionId - Session ID from authentication
+     * @param accessToken - Access token for API calls
+     */
+    static async storeSharedSession(sessionId, accessToken) {
+        if (isWebPlatform()) {
+            return; // Not supported on web
+        }
+        try {
+            const store = await initSecureStore();
+            if ((0, platform_1.isIOS)()) {
+                const sessionIdOpts = {
+                    keychainAccessGroup: IOS_KEYCHAIN_GROUP,
+                };
+                await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, sessionId, sessionIdOpts);
+                const tokenOpts = {
+                    keychainAccessible: store.WHEN_UNLOCKED,
+                    keychainAccessGroup: IOS_KEYCHAIN_GROUP,
+                };
+                await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, accessToken, tokenOpts);
+            }
+            else if ((0, platform_1.isAndroid)()) {
+                await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, sessionId);
+                await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, accessToken);
+            }
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.debug('Shared session stored successfully', { component: 'KeyManager' });
+            }
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.error('Failed to store shared session', error, { component: 'KeyManager' });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get shared session information
+     *
+     * This allows any Oxy app to check if user is already signed in
+     * via another Oxy app. Enables instant cross-app SSO.
+     *
+     * @returns Session data or null if no shared session exists
+     */
+    static async getSharedSession() {
+        if (isWebPlatform()) {
+            return null;
+        }
+        try {
+            const store = await initSecureStore();
+            let sessionId = null;
+            let accessToken = null;
+            if ((0, platform_1.isIOS)()) {
+                const opts = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+                sessionId = await store.getItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, opts);
+                accessToken = await store.getItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, opts);
+            }
+            else if ((0, platform_1.isAndroid)()) {
+                sessionId = await store.getItemAsync(STORAGE_KEYS.SHARED_SESSION_ID);
+                accessToken = await store.getItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN);
+            }
+            if (!sessionId || !accessToken) {
+                return null;
+            }
+            return { sessionId, accessToken };
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.warn('Failed to get shared session', { component: 'KeyManager' }, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Clear shared session (on logout)
+     *
+     * This signs out the user from ALL Oxy apps simultaneously.
+     * Call this when user explicitly logs out.
+     */
+    static async clearSharedSession() {
+        if (isWebPlatform()) {
+            return;
+        }
+        try {
+            const store = await initSecureStore();
+            if ((0, platform_1.isIOS)()) {
+                const opts = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+                await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, opts);
+                await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, opts);
+            }
+            else if ((0, platform_1.isAndroid)()) {
+                await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_ID);
+                await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN);
+            }
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.debug('Shared session cleared successfully', { component: 'KeyManager' });
+            }
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.error('Failed to clear shared session', error, { component: 'KeyManager' });
+            }
+        }
+    }
+    /**
+     * Migrate local identity to shared identity
+     *
+     * Call this when upgrading existing apps to use shared identities.
+     * Copies the device-specific identity to shared storage so it can
+     * be accessed by other Oxy apps.
+     *
+     * @returns True if migration was successful, false if no local identity exists
+     */
+    static async migrateToSharedIdentity() {
+        if (isWebPlatform()) {
+            return false;
+        }
+        try {
+            // Check if we already have a shared identity
+            const hasShared = await KeyManager.hasSharedIdentity();
+            if (hasShared) {
+                if ((0, logger_1.isDev)()) {
+                    logger_1.logger.debug('Shared identity already exists, skipping migration', { component: 'KeyManager' });
+                }
+                return true;
+            }
+            // Get local identity
+            const privateKey = await KeyManager.getPrivateKey();
+            if (!privateKey) {
+                if ((0, logger_1.isDev)()) {
+                    logger_1.logger.debug('No local identity to migrate', { component: 'KeyManager' });
+                }
+                return false;
+            }
+            // Import to shared storage
+            await KeyManager.importSharedIdentity(privateKey);
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.debug('Successfully migrated local identity to shared identity', { component: 'KeyManager' });
+            }
+            return true;
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.error('Failed to migrate to shared identity', error, { component: 'KeyManager' });
+            }
+            return false;
+        }
+    }
+    // ==================== END SHARED IDENTITY METHODS ====================
+    /**
+     * Atomically persist a key pair to secure storage with verification + backup.
+     *
+     * INVARIANT (the reason this method exists): at no instant during the write
+     * may the device be left holding ZERO recoverable copies of a healthy
+     * identity. This matters most on the OVERWRITE / account-switch path: if we
+     * are replacing identity A with B and the write fails halfway, we MUST end
+     * up back on A — never on a half-written B, and never on nothing.
+     *
+     * Algorithm (recoverability-preserving):
+     *   0. Snapshot the existing primary (privA, pubA) so we can roll back to
+     *      EXACTLY what was there.
+     *   1. Write the new primary: public first, then private.
+     *   2. Read back + sign/verify the new primary.
+     *   3. ONLY after the new primary is proven durable, refresh the backup to
+     *      the new key. The backup is NEVER touched before this point, so any
+     *      prior identity's backup remains intact and `restoreIdentityFromBackup`
+     *      can always recover it.
+     *   4. On ANY failure in steps 1–2, restore the snapshotted primary verbatim
+     *      (or delete it if there was none), then surface the error.
+     *
+     * Earlier versions wrote the *incoming* key to the backup FIRST, which
+     * destroyed the previous identity's backup, and rolled back by blindly
+     * deleting the primary — so a failed overwrite silently switched the user
+     * to (or lost them into) the half-written new identity. That is fixed here.
+     *
+     * @internal
+     */
+    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
+        // subsequent reads see a stable representation.
+        const canonicalPrivate = KeyManager.canonicalPrivateKey(privateKey);
+        const canonicalPublic = publicKey.toLowerCase();
+        // Step 0: Snapshot the existing primary so a failed write can be rolled
+        // back to EXACTLY the prior state. If the read itself fails we treat the
+        // prior primary as unknown and refuse to proceed — overwriting blind
+        // would risk clobbering an identity we just couldn't see (e.g. a
+        // transient keychain lock).
+        let priorPrivate;
+        let priorPublic;
+        try {
+            priorPrivate = await store.getItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
+            priorPublic = await store.getItemAsync(layout.primaryPublicKeyName, primaryReadOpts);
+        }
+        catch (error) {
+            logger_1.logger.error('Failed to read existing primary before persist', error, { component: 'KeyManager' });
+            throw new IdentityPersistError('Could not read existing identity before writing a new one; refusing to overwrite blind.', error);
+        }
+        // If we are replacing a DIFFERENT, currently-healthy identity, make sure
+        // it is recoverable from the backup slot BEFORE we overwrite the primary.
+        // We only do this when the existing backup does not already hold that
+        // identity — otherwise we would needlessly churn the keychain. This keeps
+        // the "always at least one recoverable copy" invariant intact across the
+        // window where the primary briefly holds the new key but the new backup
+        // has not been written yet.
+        const priorIsHealthyDifferent = !!priorPrivate &&
+            !!priorPublic &&
+            priorPublic.toLowerCase() !== canonicalPublic &&
+            KeyManager.isValidPrivateKey(priorPrivate) &&
+            KeyManager.isValidPublicKey(priorPublic) &&
+            KeyManager.derivePublicKey(priorPrivate).toLowerCase() === priorPublic.toLowerCase();
+        if (priorIsHealthyDifferent && priorPrivate && priorPublic) {
+            let existingBackupPublic = null;
+            try {
+                existingBackupPublic = await store.getItemAsync(layout.backupPublicKeyName, backupReadOpts);
+            }
+            catch {
+                existingBackupPublic = null;
+            }
+            if (existingBackupPublic?.toLowerCase() !== priorPublic.toLowerCase()) {
+                try {
+                    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_1.logger.error('Failed to back up existing identity before overwrite', error, { component: 'KeyManager' });
+                    throw new IdentityPersistError('Failed to back up existing identity before overwrite', error);
+                }
+            }
+        }
+        // Step 1: Write the new primary. Public first so that if the private write
+        // fails we are missing the most critical bit. The backup is intentionally
+        // NOT touched here — it still holds the previous good identity until the
+        // new primary is proven durable.
+        try {
+            await store.setItemAsync(layout.primaryPublicKeyName, canonicalPublic, primaryPubWriteOpts);
+            await store.setItemAsync(layout.primaryPrivateKeyName, canonicalPrivate, primaryPrivWriteOpts);
+        }
+        catch (error) {
+            logger_1.logger.error('Failed to write primary identity to secure store', error, { component: 'KeyManager' });
+            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
+        // (e.g., a misconfigured keychain access group), we MUST surface it
+        // before declaring success — otherwise the caller will think the
+        // identity was saved and discard the in-memory copy.
+        let readBackPrivate;
+        let readBackPublic;
+        try {
+            readBackPrivate = await store.getItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
+            readBackPublic = await store.getItemAsync(layout.primaryPublicKeyName, primaryReadOpts);
+        }
+        catch (error) {
+            logger_1.logger.error('Failed to read identity back after write', error, { component: 'KeyManager' });
+            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
+        // store that uppercases on round-trip (some keychain backends) doesn't
+        // trigger a spurious mismatch.
+        if (readBackPrivate?.toLowerCase() !== canonicalPrivate ||
+            readBackPublic?.toLowerCase() !== canonicalPublic) {
+            logger_1.logger.error('Identity round-trip mismatch after write', undefined, { component: 'KeyManager' });
+            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
+        // pair signs/verifies cleanly. Catches crypto-state corruption immediately
+        // rather than the next time the user tries to sign in.
+        try {
+            const privateKey = KeyManager.canonicalPrivateKey(readBackPrivate);
+            const derived = (0, secp256k1_1.deriveSecp256k1PublicKey)(privateKey);
+            if (derived.toLowerCase() !== readBackPublic.toLowerCase()) {
+                throw new IdentityPersistError('Stored public key does not match derived public key.');
+            }
+            // Sign/verify roundtrip using a known test vector
+            const probeHash = '0'.repeat(64);
+            const signature = (0, secp256k1_1.signSecp256k1Digest)(privateKey, probeHash);
+            if (!(0, secp256k1_1.verifySecp256k1Digest)(derived, probeHash, signature)) {
+                throw new IdentityPersistError('Sign/verify roundtrip failed for newly stored identity.');
+            }
+        }
+        catch (error) {
+            await KeyManager._rollbackPrimary(store, layout, priorPrivate, priorPublic);
+            if (error instanceof IdentityPersistError)
+                throw error;
+            logger_1.logger.error('Identity sign/verify probe failed', error, { component: 'KeyManager' });
+            throw new IdentityPersistError('Stored identity failed crypto self-test', error);
+        }
+        // Step 3: The new primary is durable and functional. NOW it is safe to
+        // refresh the backup to the new key. This is part of the successful write
+        // contract: returning success while the backup still belongs to the
+        // previous identity would allow a later restore with an absent primary to
+        // silently switch the device back to the previous account. Snapshot the
+        // backup first so a partial backup refresh can be rolled back along with
+        // the primary before surfacing the failure.
+        let priorBackupPrivate;
+        let priorBackupPublic;
+        let priorBackupTimestamp;
+        try {
+            priorBackupPrivate = await store.getItemAsync(layout.backupPrivateKeyName, backupReadOpts);
+            priorBackupPublic = await store.getItemAsync(layout.backupPublicKeyName, backupReadOpts);
+            priorBackupTimestamp = await store.getItemAsync(layout.backupTimestampName, backupReadOpts);
+        }
+        catch (error) {
+            logger_1.logger.error('Failed to snapshot identity backup before refresh', error, { component: 'KeyManager' });
+            await KeyManager._rollbackPrimary(store, layout, priorPrivate, priorPublic);
+            throw new IdentityPersistError('Failed to snapshot identity backup before refresh', error);
+        }
+        try {
+            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_1.logger.error('Failed to refresh identity backup after primary write', error, { component: 'KeyManager' });
+            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, 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 (0, identityMarker_1.readIdentityMarker)();
+            if (existing && existing.publicKey.toLowerCase() === publicKey.toLowerCase()) {
+                await (0, identityMarker_1.updateIdentityMarker)({ origin });
+            }
+            else {
+                await (0, identityMarker_1.writeIdentityMarker)({ publicKey, origin });
+            }
+        }
+        catch (error) {
+            logger_1.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
+     * the original persistence error remains the one surfaced to the caller.
+     *
+     * @internal
+     */
+    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(layout.backupPrivateKeyName, priorBackupPrivate, backupPrivWriteOpts);
+            }
+            else {
+                try {
+                    await store.deleteItemAsync(layout.backupPrivateKeyName, backupReadOpts);
+                }
+                catch { /* best effort */ }
+            }
+            if (priorBackupPublic) {
+                await store.setItemAsync(layout.backupPublicKeyName, priorBackupPublic, backupPubWriteOpts);
+            }
+            else {
+                try {
+                    await store.deleteItemAsync(layout.backupPublicKeyName, backupReadOpts);
+                }
+                catch { /* best effort */ }
+            }
+            if (priorBackupTimestamp) {
+                await store.setItemAsync(layout.backupTimestampName, priorBackupTimestamp, backupPubWriteOpts);
+            }
+            else {
+                try {
+                    await store.deleteItemAsync(layout.backupTimestampName, backupReadOpts);
+                }
+                catch { /* best effort */ }
+            }
+        }
+        catch (rollbackError) {
+            logger_1.logger.error('Failed to roll back identity backup after a failed refresh', rollbackError, { component: 'KeyManager' });
+        }
+    }
+    /**
+     * Restore the primary slot to a previously-snapshotted (privA, pubA) pair,
+     * or delete it entirely if there was no prior identity. Best-effort: every
+     * step is wrapped so a rollback failure never masks the original error the
+     * caller is about to throw. Invalidates the in-memory cache so the next read
+     * reflects whatever actually landed on disk.
+     *
+     * @internal
+     */
+    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(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(layout.primaryPublicKeyName, primaryReadOpts);
+                }
+                catch { /* best effort */ }
+                try {
+                    await store.deleteItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
+                }
+                catch { /* best effort */ }
+            }
+        }
+        catch (rollbackError) {
+            logger_1.logger.error('Failed to roll back primary identity after a failed write', rollbackError, { component: 'KeyManager' });
+        }
+        finally {
+            // Whatever happened, the cached verdict is no longer trustworthy.
+            KeyManager.invalidateCache();
+        }
+    }
+    /**
+     * Generate and securely store a new key pair on the device.
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     * Returns the public key. The private key never leaves secure storage.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     * @throws IdentityPersistError if the key cannot be durably written
+     */
+    static async createIdentity(options) {
+        if (isWebPlatform()) {
+            throw new Error('Identity creation is only available on native platforms (iOS/Android). Please use the native app to create your identity.');
+        }
+        // CRITICAL SAFEGUARD: never silently overwrite an existing identity.
+        // 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 marker = await (0, identityMarker_1.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, '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).
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     * @throws IdentityPersistError if the key cannot be durably written
+     */
+    static async importKeyPair(privateKey, options) {
+        if (isWebPlatform()) {
+            throw new Error('Identity import is only available on native platforms (iOS/Android). Please use the native app to import your identity.');
+        }
+        if (!KeyManager.isValidPrivateKey(privateKey)) {
+            throw new Error('Invalid private key supplied to importKeyPair.');
+        }
+        // Canonicalize the incoming private key so the stored value (and the
+        // derived public key) are always in canonical form. Without this, an
+        // externally-imported short or uppercase key would derive one public
+        // key here and a different one when later read back unpadded.
+        const canonicalPrivate = KeyManager.canonicalPrivateKey(privateKey);
+        const publicKey = (0, secp256k1_1.deriveSecp256k1PublicKey)(canonicalPrivate);
+        // 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 marker = await (0, identityMarker_1.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(migration.layout.primaryPrivateKeyName, KeyManager._slotOpts(migration.layout.primaryService));
+        }
+        catch (error) {
+            // If secure store is not available, return null (no identity)
+            // This allows the app to continue functioning even if secure store fails to load
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.warn('Failed to access secure store', { component: 'KeyManager' }, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * 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()) {
+            return null; // Identity storage is only available on native platforms
+        }
+        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(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) {
+            // Storage threw AFTER migration resolved — transient/unavailable. Do NOT
+            // cache; surface a typed error so callers never misread it as "no identity".
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.warn('Failed to access secure store', { component: 'KeyManager' }, error);
+            }
+            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 ((0, logger_1.isDev)()) {
+                logger_1.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 ((0, logger_1.isDev)()) {
+                logger_1.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 (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.
+     */
+    static async hasIdentity() {
+        if (isWebPlatform()) {
+            return false; // Identity storage is only available on native platforms
+        }
+        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(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; throw a TYPED error
+            // so callers distinguish "temporarily unavailable" from "genuinely absent"
+            // instead of silently treating a locked keystore as a blank device.
+            logger_1.logger.error('Failed to read identity from secure storage', error, { component: 'KeyManager' });
+            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
+        // calls).
+        let hasIdentity = false;
+        if (privateKey && publicKey) {
+            // Require BOTH bytes-present AND parseable AND matching. Any weaker
+            // check would let a half-written identity (private without public)
+            // pretend to be a real one, which then fails opaquely later in the
+            // sign-in flow when SignatureService.sign() can't find the keypair.
+            if (KeyManager.isValidPrivateKey(privateKey) && KeyManager.isValidPublicKey(publicKey)) {
+                try {
+                    const derived = (0, secp256k1_1.deriveSecp256k1PublicKey)(KeyManager.canonicalPrivateKey(privateKey));
+                    // Hex equality is case-insensitive; normalize on both sides to
+                    // tolerate legacy uppercase-stored public keys.
+                    hasIdentity = derived.toLowerCase() === publicKey.toLowerCase();
+                    if (!hasIdentity) {
+                        logger_1.logger.warn('KeyManager.hasIdentity: stored public key does not match derived public key', { component: 'KeyManager' });
+                    }
+                }
+                catch (error) {
+                    logger_1.logger.warn('KeyManager.hasIdentity: failed to derive public key from stored private key', { component: 'KeyManager' }, error);
+                }
+            }
+            else {
+                logger_1.logger.warn('KeyManager.hasIdentity: stored key material is malformed', { component: 'KeyManager' });
+            }
+        }
+        // Cache result. Storage succeeded, so this verdict is stable:
+        //   - true  → identity exists and round-trips cleanly
+        //   - false → storage is empty / partial / malformed (a stable result;
+        //             callers should run integrity-recovery / restore from
+        //             backup explicitly)
+        KeyManager.cachedHasIdentity = hasIdentity;
+        if (hasIdentity && publicKey) {
+            KeyManager.cachedPublicKey = publicKey;
+        }
+        // Diagnostic breadcrumb (dev only). Logs lengths + validity flags so we
+        // can tell from `adb logcat` exactly WHY hasIdentity returned what it
+        // did. Never log the key material itself.
+        if ((0, logger_1.isDev)()) {
+            logger_1.logger.debug('KeyManager.hasIdentity result', { component: 'KeyManager' }, {
+                privateLen: privateKey?.length ?? 0,
+                publicLen: publicKey?.length ?? 0,
+                privateValid: privateKey ? KeyManager.isValidPrivateKey(privateKey) : null,
+                publicValid: publicKey ? KeyManager.isValidPublicKey(publicKey) : null,
+                derived: hasIdentity,
+            });
+        }
+        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 (0, identityMarker_1.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 (0, identityMarker_1.writeIdentityMarker)({ publicKey: canonicalPublic, origin: 'backfill' });
+                }
+                catch (error) {
+                    logger_1.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
+     * This should ONLY be called when explicitly requested by the user
+     * @param skipBackup - If true, skip backup before deletion (default: false)
+     * @param force - If true, skip confirmation checks (default: false)
+     * @param userConfirmed - If true, user has explicitly confirmed deletion (default: false)
+     */
+    static async deleteIdentity(skipBackup = false, force = false, userConfirmed = false) {
+        if (isWebPlatform()) {
+            return; // Identity storage is only available on native platforms, nothing to delete
+        }
+        // CRITICAL SAFEGUARD: Require explicit user confirmation unless force is true
+        if (!force && !userConfirmed) {
+            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
+            }
+        }
+        const store = await initSecureStore();
+        // ALWAYS create backup before deletion unless explicitly skipped
+        if (!skipBackup) {
+            try {
+                const backupSuccess = await KeyManager.backupIdentity();
+                if (!backupSuccess && (0, logger_1.isDev)()) {
+                    logger_1.logger.warn('Failed to backup identity before deletion - proceeding anyway', { component: 'KeyManager' });
+                }
+            }
+            catch (backupError) {
+                if ((0, logger_1.isDev)()) {
+                    logger_1.logger.warn('Failed to backup identity before deletion', { component: 'KeyManager' }, backupError);
+                }
+            }
+        }
+        // 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) {
+            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 (0, identityMarker_1.clearIdentityMarker)();
+        }
+        catch (error) {
+            logger_1.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)
+     * This provides a recovery mechanism if primary storage fails
+     */
+    static async backupIdentity() {
+        if (isWebPlatform()) {
+            return false; // Identity storage is only available on native platforms
+        }
+        try {
+            const store = await initSecureStore();
+            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(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) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.error('Failed to backup identity', error, { component: 'KeyManager' });
+            }
+            return false;
+        }
+    }
+    /**
+     * Verify identity integrity — checks keys are valid, accessible, derive
+     * consistently, AND can sign + verify a probe message.
+     *
+     * Returns true only when the full sign/verify roundtrip succeeds. Use
+     * this on app start to detect silent corruption before the user finds
+     * out by failing to sign in.
+     */
+    static async verifyIdentityIntegrity() {
+        if (isWebPlatform()) {
+            return false; // Identity storage is only available on native platforms
+        }
+        try {
+            const privateKey = await KeyManager.getPrivateKey();
+            const publicKey = await KeyManager.getPublicKey();
+            if (!privateKey || !publicKey) {
+                return false;
+            }
+            // Validate formats
+            if (!KeyManager.isValidPrivateKey(privateKey)) {
+                return false;
+            }
+            if (!KeyManager.isValidPublicKey(publicKey)) {
+                return false;
+            }
+            // Verify public key derives from private key (case-insensitive
+            // because hex is case-insensitive — legacy uppercase stored values
+            // must still validate).
+            const derivedPublicKey = KeyManager.derivePublicKey(privateKey);
+            if (derivedPublicKey.toLowerCase() !== publicKey.toLowerCase()) {
+                return false; // Keys don't match
+            }
+            // Full sign/verify probe — proves the keypair is functional, not just
+            // bytewise parseable. A previous version of this method would return true
+            // without proving the signing primitive could operate on the key.
+            const canonicalPrivateKey = KeyManager.canonicalPrivateKey(privateKey);
+            const probeHash = '0'.repeat(64);
+            const signature = (0, secp256k1_1.signSecp256k1Digest)(canonicalPrivateKey, probeHash);
+            if (!(0, secp256k1_1.verifySecp256k1Digest)(publicKey, probeHash, signature)) {
+                logger_1.logger.error('Identity sign/verify probe failed during integrity check', undefined, { component: 'KeyManager' });
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            logger_1.logger.error('Identity integrity check failed', error, { component: 'KeyManager' });
+            return false;
+        }
+    }
+    /**
+     * Restore identity from backup if primary storage is genuinely missing or
+     * corrupt.
+     *
+     * SAFETY (three independent guards against silently switching accounts):
+     *   1. If the primary passes a full sign/verify probe, do nothing.
+     *   2. If the primary keys CANNOT BE READ (storage threw — e.g. a transient
+     *      keychain lock during a background launch), do nothing. We must NOT
+     *      treat "couldn't read" as "corrupted" and restore a possibly-stale
+     *      backup over an identity that is actually fine but momentarily
+     *      inaccessible.
+     *   3. If a primary private/public key IS present but does not match the
+     *      backup, the backup may belong to a different identity — refuse, so we
+     *      never silently switch the user to another account.
+     *
+     * Only when the primary is provably absent (read succeeded, returned
+     * null/empty) or provably corrupt (read succeeded, bytes malformed AND no
+     * conflicting key material is present) do we rebuild it from the backup.
+     */
+    static async restoreIdentityFromBackup() {
+        if (isWebPlatform()) {
+            return false; // Identity storage is only available on native platforms
+        }
+        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_1.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 —
+            // bail out and let a later call retry rather than risk restoring over a
+            // healthy-but-locked identity.
+            let primaryPrivate;
+            let primaryPublic;
+            try {
+                primaryPrivate = await store.getItemAsync(layout.primaryPrivateKeyName, primaryReadOpts);
+                primaryPublic = await store.getItemAsync(layout.primaryPublicKeyName, primaryReadOpts);
+            }
+            catch (error) {
+                logger_1.logger.warn('restoreIdentityFromBackup: could not read primary (transient?). Refusing to restore.', { component: 'KeyManager' }, error);
+                return false;
+            }
+            // If the primary reads back as a complete, self-consistent identity, it
+            // is healthy — nothing to restore. (Guard 1.)
+            if (primaryPrivate && primaryPublic) {
+                if (KeyManager.isValidPrivateKey(primaryPrivate) &&
+                    KeyManager.isValidPublicKey(primaryPublic) &&
+                    KeyManager.derivePublicKey(primaryPrivate).toLowerCase() === primaryPublic.toLowerCase()) {
+                    return false;
+                }
+            }
+            // Load + validate the backup.
+            const backupPrivateKey = await store.getItemAsync(layout.backupPrivateKeyName, backupReadOpts);
+            const backupPublicKey = await store.getItemAsync(layout.backupPublicKeyName, backupReadOpts);
+            if (!backupPrivateKey || !backupPublicKey) {
+                return false; // No backup available
+            }
+            if (!KeyManager.isValidPrivateKey(backupPrivateKey) || !KeyManager.isValidPublicKey(backupPublicKey)) {
+                logger_1.logger.warn('Backup identity is malformed; refusing to restore', { component: 'KeyManager' });
+                return false;
+            }
+            // Verify backup keys derive consistently. Hex is case-insensitive so
+            // normalize both sides — a legacy uppercase-stored backup must still
+            // be considered valid.
+            const derivedPublicKey = KeyManager.derivePublicKey(backupPrivateKey);
+            if (derivedPublicKey.toLowerCase() !== backupPublicKey.toLowerCase()) {
+                logger_1.logger.warn('Backup public key does not match derived; refusing to restore', { component: 'KeyManager' });
+                return false;
+            }
+            // Guard 3: if ANY primary key material is still present and identifies a
+            // DIFFERENT identity than the backup, refuse — the backup may be from a
+            // completely different account and restoring it would silently switch
+            // the user. We check the private key too (not just the public): a
+            // present private key that derives to a non-backup public means a real,
+            // different identity is sitting in the primary slot.
+            if (primaryPublic &&
+                primaryPublic.toLowerCase() !== backupPublicKey.toLowerCase()) {
+                logger_1.logger.error('Primary public key is present, corrupt-or-mismatched, AND differs from the backup. Refusing to restore to avoid switching accounts.', undefined, { component: 'KeyManager' });
+                return false;
+            }
+            if (primaryPrivate &&
+                KeyManager.isValidPrivateKey(primaryPrivate) &&
+                KeyManager.derivePublicKey(primaryPrivate).toLowerCase() !== backupPublicKey.toLowerCase()) {
+                logger_1.logger.error('Primary private key identifies a DIFFERENT identity than the backup. Refusing to restore to avoid switching accounts.', undefined, { component: 'KeyManager' });
+                return false;
+            }
+            // Safe to restore: rebuild the primary using the same atomic write
+            // path createIdentity uses, including verification.
+            try {
+                await KeyManager._persistIdentityAtomic(backupPrivateKey, backupPublicKey, 'restore');
+            }
+            catch (error) {
+                logger_1.logger.error('Failed to persist identity restored from backup', error, { component: 'KeyManager' });
+                return false;
+            }
+            await store.setItemAsync(layout.backupTimestampName, Date.now().toString(), backupReadOpts);
+            return true;
+        }
+        catch (error) {
+            logger_1.logger.error('Failed to restore identity from backup', error, { component: '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_1.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_1.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_1.logger.error('Recovery: failed to persist recovered identity', error, { component: 'KeyManager' });
+            return false;
+        }
+    }
+    /**
+     * Derive public key from a private key (without storing)
+     */
+    static derivePublicKey(privateKey) {
+        return (0, secp256k1_1.deriveSecp256k1PublicKey)(KeyManager.canonicalPrivateKey(privateKey));
+    }
+    /**
+     * Normalize a public key to uncompressed, lowercased hex. Used when building
+     * signed rotation payloads so legacy compressed/cased encodings still verify.
+     */
+    static canonicalPublicKey(publicKey) {
+        return (0, secp256k1_1.normalizeSecp256k1PublicKey)(publicKey);
+    }
+    /**
+     * Validate that a string is a valid public key
+     *
+     * Returns false on parse errors (invalid input is the expected fail mode here).
+     * Errors are logged at debug level so they're available when troubleshooting
+     * but don't pollute production logs.
+     */
+    static isValidPublicKey(publicKey) {
+        if (typeof publicKey !== 'string' || publicKey.length === 0) {
+            return false;
+        }
+        // secp256k1 public keys are either uncompressed (130 hex chars, starts with 04)
+        // or compressed (66 hex chars, starts with 02 or 03). Anything else is
+        // clearly bogus; reject up front so we never silently widen the trust
+        // boundary by accepting whatever BN(...) parses out of junk input.
+        if (!/^[0-9a-fA-F]+$/.test(publicKey)) {
+            return false;
+        }
+        if (publicKey.length !== 130 && publicKey.length !== 66) {
+            return false;
+        }
+        if ((0, secp256k1_1.isValidSecp256k1PublicKey)(publicKey)) {
+            return true;
+        }
+        if ((0, logger_1.isDev)()) {
+            logger_1.logger.debug('[oxy.crypto] isValidPublicKey rejected input', { component: 'KeyManager' });
+        }
+        return false;
+    }
+    /**
+     * Validate that a string is a valid private key.
+     *
+     * secp256k1 private keys are 256-bit, so 64 hex chars. We require strict
+     * hex-only input so malformed text can never be coerced into a scalar.
+     */
+    static isValidPrivateKey(privateKey) {
+        if (typeof privateKey !== 'string' || privateKey.length === 0) {
+            return false;
+        }
+        if (!/^[0-9a-fA-F]+$/.test(privateKey)) {
+            return false;
+        }
+        // Legacy storage may have stripped leading zero bytes. Accept 1..64 chars
+        // here and normalize before curve validation.
+        if (privateKey.length > 64) {
+            return false;
+        }
+        const padded = privateKey.padStart(64, '0').toLowerCase();
+        // After padding, require minimum entropy: reject obvious low-scalar
+        // keys. A scalar that fits in 8 hex chars (~32 bits of entropy) is a
+        // degenerate / accidental key, not a real one. The existing isZero()
+        // check below covers literal 0; this also rejects trivially small
+        // scalars like '1', '2', etc. that would otherwise pad to a valid but
+        // weak key whose public point is trivially derivable.
+        if (/^0{56}/.test(padded)) {
+            return false;
+        }
+        if ((0, secp256k1_1.isValidSecp256k1PrivateKey)(padded)) {
+            return true;
+        }
+        if ((0, logger_1.isDev)()) {
+            logger_1.logger.debug('[oxy.crypto] isValidPrivateKey rejected input', { component: 'KeyManager' });
+        }
+        return false;
+    }
+    /**
+     * Derive a 32-byte, domain-separated seed from the on-device Oxy identity
+     * private key via HKDF-SHA256, WITHOUT ever exposing the raw private key.
+     *
+     * The domain separation is carried by `info` (e.g. `"oxypay/faircoin/v1"`),
+     * so distinct apps/purposes get independent seeds from the same identity.
+     * The output is HKDF keying material, never the private key itself — a
+     * consumer (e.g. Oxy Pay's FairCoin HD wallet) can feed it straight into
+     * `HDKey.fromMasterSeed` and never touches the identity key.
+     *
+     * Key source (native only): prefers the shared ecosystem identity written to
+     * `group.so.oxy.shared` (what a Relying Party like Oxy Pay reads), then falls
+     * back to this device's primary identity (Commons/Accounts). Both reproduce
+     * from the user's Oxy recovery phrase, so the derived seed is recoverable.
+     *
+     * @param info Context/domain-binding label (distinct labels → independent seeds).
+     * @returns 32 bytes of derived keying material, or `null` on web / when no
+     *          identity key is available on this device.
+     */
+    static async deriveScopedSeed(info) {
+        if (isWebPlatform()) {
+            return null;
+        }
+        const privateKey = (await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey());
+        if (!privateKey) {
+            return null;
+        }
+        const ikm = hexToBytes(KeyManager.canonicalPrivateKey(privateKey));
+        return (0, kdf_1.hkdfSha256)(ikm, utf8ToBytes(SCOPED_SEED_KDF_SALT), utf8ToBytes(info), 32);
+    }
+    /**
+     * Get a shortened version of the public key for display
+     * Format: first 8 chars...last 8 chars
+     */
+    static shortenPublicKey(publicKey) {
+        if (publicKey.length <= 20)
+            return publicKey;
+        return `${publicKey.slice(0, 8)}...${publicKey.slice(-8)}`;
+    }
+}
+exports.KeyManager = KeyManager;
+// In-memory cache for identity state (invalidated on identity changes)
+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;
+exports.default = KeyManager;