@oxyhq/core 1.11.12 → 1.11.13

package/src/crypto/keyManager.ts

@@ -1,19 +1,71 @@
 /**
  * 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.
  */
 
 import { ec as EC } from 'elliptic';
 import type { ECKeyPair } from 'elliptic';
+import type { SecureStoreOptions } from 'expo-secure-store';
 import { isWeb, isIOS, isAndroid, isReactNative, isNodeJS } from '../utils/platform';
+import { loadExpoCrypto, loadNodeCrypto, loadSecureStore } from '../utils/platformCrypto';
 import { logger } from '../utils/loggerUtils';
 import { isDev } from '../shared/utils/debugUtils';
 
-// Lazy imports for React Native specific modules
-let SecureStore: typeof import('expo-secure-store') | null = null;
-let ExpoCrypto: typeof import('expo-crypto') | null = null;
+/**
+ * Extended SecureStoreOptions that explicitly includes `keychainAccessGroup`.
+ *
+ * The shipped `expo-secure-store` types in this repo (see
+ * `src/types/expo-secure-store.d.ts`) already declare `keychainAccessGroup`,
+ * but we redeclare it here as an `interface extends ...` so the field stays
+ * type-safe even when the upstream package types drift. Older versions of
+ * `@types/expo-secure-store` omitted this field, which is why the code base
+ * used to fall back to `as any` — that escape hatch is now removed.
+ */
+interface OxySecureStoreOptions extends SecureStoreOptions {
+  /**
+   * iOS Keychain access group. Required for sharing identity material across
+   * apps in the Oxy ecosystem via Keychain Sharing entitlements. The
+   * underlying `expo-secure-store` runtime supports this option.
+   */
+  keychainAccessGroup?: string;
+}
+
+/**
+ * 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.
+ */
+export class IdentityAlreadyExistsError extends Error {
+  override readonly name = 'IdentityAlreadyExistsError';
+  readonly existingPublicKey: string;
+  constructor(existingPublicKey: string) {
+    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.existingPublicKey = existingPublicKey;
+  }
+}
+
+/**
+ * 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.
+ */
+export class IdentityPersistError extends Error {
+  override readonly name = 'IdentityPersistError';
+  constructor(message: string, readonly cause?: unknown) {
+    super(message);
+  }
+}
 
 const ec = new EC('secp256k1');
 
@@ -45,23 +97,23 @@ const ANDROID_ACCOUNT_TYPE = 'com.oxy.account';
 
 /**
  * Initialize React Native specific modules
- * This allows the module to work in both Node.js and React Native environments
+ *
+ * Delegates to `platformCrypto`, which is a per-platform module
+ * (`platformCrypto.ts` vs `platformCrypto.react-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(): Promise<typeof import('expo-secure-store')> {
-  if (!SecureStore) {
-    try {
-      // Variable indirection prevents bundlers (Vite, webpack) from statically resolving this
-      const moduleName = 'expo-secure-store';
-      SecureStore = await import(/* @vite-ignore */ moduleName);
-    } 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.`);
-    }
-  }
-  if (!SecureStore) {
-    throw new Error('expo-secure-store module is not available');
+  try {
+    return await 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.',
+    );
   }
-  return SecureStore;
 }
 
 /**
@@ -73,12 +125,8 @@ function isWebPlatform(): boolean {
 }
 
 async function initExpoCrypto(): Promise<typeof import('expo-crypto')> {
-  if (!ExpoCrypto) {
-    // Variable indirection prevents bundlers (Vite, webpack) from statically resolving this
-    const moduleName = 'expo-crypto';
-    ExpoCrypto = await import(/* @vite-ignore */ moduleName);
-  }
-  return ExpoCrypto!;
+  // Same per-platform delegation as initSecureStore — see comment there.
+  return loadExpoCrypto();
 }
 
 /**
@@ -101,14 +149,18 @@ async function getSecureRandomBytes(length: number): Promise<Uint8Array> {
     return Crypto.getRandomBytes(length);
   }
   
-  // In Node.js, use Node's crypto module
-  // Variable indirection prevents bundlers (Vite, webpack) from statically resolving this
+  // 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 cryptoModuleName = 'crypto';
-    const nodeCrypto = await import(/* @vite-ignore */ cryptoModuleName);
+    const nodeCrypto = await loadNodeCrypto();
     return new Uint8Array(nodeCrypto.randomBytes(length));
   } catch (error) {
-    // Fallback to expo-crypto if Node crypto fails
+    // 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);
   }
@@ -144,14 +196,33 @@ export class KeyManager {
     KeyManager.cachedHasSharedIdentity = null;
   }
 
+  /**
+   * Lowercase and pad to canonical 64-hex-char form.
+   *
+   * Tolerates the 1-in-256 leading-zero-strip that elliptic's
+   * `getPrivate('hex')` produces, and the externally-imported uppercase-hex
+   * legacy keys. EVERY `ec.keyFromPrivate(...)` call site in this file must
+   * canonicalize first so that derivation is stable regardless of storage
+   * representation.
+   *
+   * Private (used only inside KeyManager) — public consumers should not need
+   * to think about hex representation.
+   */
+  private static canonicalPrivateKey(key: string): string {
+    return key.toLowerCase().padStart(64, '0');
+  }
+
   /**
    * Generate a new ECDSA secp256k1 key pair
    * Returns the keys in hexadecimal format
    */
   static generateKeyPairSync(): KeyPair {
     const keyPair = ec.genKeyPair();
+    // Pad to canonical 64 hex chars. `elliptic`'s `getPrivate('hex')` strips
+    // leading zero bytes which would otherwise corrupt strict-length checks
+    // and signature derivation on the read path.
     return {
-      privateKey: keyPair.getPrivate('hex'),
+      privateKey: keyPair.getPrivate('hex').padStart(64, '0'),
       publicKey: keyPair.getPublic('hex'),
     };
   }
@@ -162,10 +233,10 @@ export class KeyManager {
   static async generateKeyPair(): Promise<KeyPair> {
     const randomBytes = await getSecureRandomBytes(32);
     const privateKeyHex = uint8ArrayToHex(randomBytes);
-    const keyPair = ec.keyFromPrivate(privateKeyHex);
-    
+    const keyPair = ec.keyFromPrivate(KeyManager.canonicalPrivateKey(privateKeyHex));
+
     return {
-      privateKey: keyPair.getPrivate('hex'),
+      privateKey: keyPair.getPrivate('hex').padStart(64, '0'),
       publicKey: keyPair.getPublic('hex'),
     };
   }
@@ -200,14 +271,16 @@ export class KeyManager {
       // iOS: Store in shared keychain group
       // Note: keychainAccessGroup requires Keychain Sharing capability in Xcode
       try {
-        await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, {
+        const privateOpts: OxySecureStoreOptions = {
           keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-          keychainAccessGroup: IOS_KEYCHAIN_GROUP, // This enables sharing across apps
-        } as any); // Type assertion: keychainAccessGroup may not be in older @types but is supported
+          keychainAccessGroup: IOS_KEYCHAIN_GROUP, // Enables sharing across apps
+        };
+        await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, privateOpts);
 
-        await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, {
+        const publicOpts: OxySecureStoreOptions = {
           keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
+        };
+        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}`
@@ -254,9 +327,8 @@ export class KeyManager {
       let publicKey: string | null = null;
 
       if (isIOS()) {
-        publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, {
-          keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
+        const opts: OxySecureStoreOptions = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+        publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, opts);
       } else if (isAndroid()) {
         publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
       }
@@ -292,9 +364,8 @@ export class KeyManager {
       let privateKey: string | null = null;
 
       if (isIOS()) {
-        privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, {
-          keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
+        const opts: OxySecureStoreOptions = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+        privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, opts);
       } else if (isAndroid()) {
         privateKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY);
       }
@@ -357,20 +428,26 @@ export class KeyManager {
     }
 
     const store = await initSecureStore();
-    const keyPair = ec.keyFromPrivate(privateKey);
+    // 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 keyPair = ec.keyFromPrivate(canonicalPrivate);
     const publicKey = keyPair.getPublic('hex');
 
     if (isIOS()) {
-      await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, {
+      const privateOpts: OxySecureStoreOptions = {
         keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
         keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-      } as any);
+      };
+      await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, privateOpts);
 
-      await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, {
+      const publicOpts: OxySecureStoreOptions = {
         keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-      } as any);
+      };
+      await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, publicOpts);
     } else if (isAndroid()) {
-      await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, {
+      await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, {
         keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
       });
 
@@ -407,14 +484,16 @@ export class KeyManager {
       const store = await initSecureStore();
 
       if (isIOS()) {
-        await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, sessionId, {
+        const sessionIdOpts: OxySecureStoreOptions = {
           keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
+        };
+        await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, sessionId, sessionIdOpts);
 
-        await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, accessToken, {
+        const tokenOpts: OxySecureStoreOptions = {
           keychainAccessible: store.WHEN_UNLOCKED,
           keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
+        };
+        await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, accessToken, tokenOpts);
       } else if (isAndroid()) {
         await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, sessionId);
         await store.setItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, accessToken);
@@ -450,13 +529,9 @@ export class KeyManager {
       let accessToken: string | null = null;
 
       if (isIOS()) {
-        sessionId = await store.getItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, {
-          keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
-
-        accessToken = await store.getItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, {
-          keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
+        const opts: OxySecureStoreOptions = { 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 (isAndroid()) {
         sessionId = await store.getItemAsync(STORAGE_KEYS.SHARED_SESSION_ID);
         accessToken = await store.getItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN);
@@ -490,12 +565,9 @@ export class KeyManager {
       const store = await initSecureStore();
 
       if (isIOS()) {
-        await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, {
-          keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
-        await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, {
-          keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-        } as any);
+        const opts: OxySecureStoreOptions = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+        await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_ID, opts);
+        await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN, opts);
       } else if (isAndroid()) {
         await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_ID);
         await store.deleteItemAsync(STORAGE_KEYS.SHARED_SESSION_TOKEN);
@@ -563,50 +635,186 @@ export class KeyManager {
   // ==================== END SHARED IDENTITY METHODS ====================
 
   /**
-   * Generate and securely store a new key pair on the device
-   * Returns only the public key (private key is stored securely)
+   * Atomically persist a key pair to secure storage with verification + backup.
+   *
+   * Write order is critical:
+   *   1. Backup (BACKUP_PRIVATE_KEY + BACKUP_PUBLIC_KEY + BACKUP_TIMESTAMP)
+   *   2. Primary public key
+   *   3. Primary private key (last so a partial write leaves us in a known
+   *      "no identity yet" state — easier to retry than a half-written one)
+   *   4. Read back + sign/verify to confirm the storage round-trip works
+   *
+   * If any step throws, the caller sees the error AND any partial state is
+   * cleaned up so the device is left either fully consistent or fully empty.
+   * It never leaves an unusable half-identity that would fool `hasIdentity()`.
+   *
+   * @internal
    */
-  static async createIdentity(): Promise<string> {
-    if (isWebPlatform()) {
-      throw new Error('Identity creation is only available on native platforms (iOS/Android). Please use the native app to create your identity.');
-    }
+  private static async _persistIdentityAtomic(
+    privateKey: string,
+    publicKey: string,
+  ): Promise<void> {
     const store = await initSecureStore();
-    const { privateKey, publicKey } = await KeyManager.generateKeyPair();
 
-    await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, privateKey, {
-      keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-    });
+    // 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 1: Backup BEFORE touching primary storage so we always have a
+    // recoverable copy even if the device crashes mid-write. Store the
+    // backup in canonical form too so a backup-restore cycle preserves
+    // canonicalization.
+    try {
+      await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, canonicalPrivate, {
+        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+      });
+      await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, canonicalPublic);
+      await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+    } catch (error) {
+      logger.error('Failed to write identity backup before primary', error, { component: 'KeyManager' });
+      throw new IdentityPersistError('Failed to write identity backup', error);
+    }
 
-    await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, publicKey);
+    // Step 2 + 3: Write primary keys. Public first so that if private write
+    // fails we are still missing the most critical bit.
+    try {
+      await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, canonicalPublic);
+      await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, canonicalPrivate, {
+        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+      });
+    } catch (error) {
+      logger.error('Failed to write primary identity to secure store', error, { component: 'KeyManager' });
+      // Roll back the public-key half-write so hasIdentity() doesn't lie later.
+      try { await store.deleteItemAsync(STORAGE_KEYS.PUBLIC_KEY); } catch { /* best effort */ }
+      try { await store.deleteItemAsync(STORAGE_KEYS.PRIVATE_KEY); } catch { /* best effort */ }
+      throw new IdentityPersistError('Failed to write identity to secure store', error);
+    }
 
-    // Update cache
-    KeyManager.cachedPublicKey = publicKey;
+    // Step 4: 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: string | null;
+    let readBackPublic: string | null;
+    try {
+      readBackPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+      readBackPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+    } catch (error) {
+      logger.error('Failed to read identity back after write', error, { component: 'KeyManager' });
+      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.error('Identity round-trip mismatch after write', undefined, { component: 'KeyManager' });
+      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 a (theoretical) elliptic library
+    // corruption immediately rather than the next time the user tries to
+    // sign in.
+    try {
+      const keyPair = ec.keyFromPrivate(KeyManager.canonicalPrivateKey(readBackPrivate));
+      const derived = keyPair.getPublic('hex');
+      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 = keyPair.sign(probeHash);
+      if (!keyPair.verify(probeHash, signature)) {
+        throw new IdentityPersistError('Sign/verify roundtrip failed for newly stored identity.');
+      }
+    } catch (error) {
+      if (error instanceof IdentityPersistError) throw error;
+      logger.error('Identity sign/verify probe failed', error, { component: 'KeyManager' });
+      throw new IdentityPersistError('Stored identity failed crypto self-test', error);
+    }
+
+    // Update cache only after we are certain the identity is durable.
+    KeyManager.cachedPublicKey = canonicalPublic;
     KeyManager.cachedHasIdentity = true;
+  }
 
+  /**
+   * 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?: { overwrite?: boolean }): Promise<string> {
+    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.
+    if (!options?.overwrite) {
+      const existing = await KeyManager.getPublicKey();
+      if (existing) {
+        throw new IdentityAlreadyExistsError(existing);
+      }
+    }
+
+    const { privateKey, publicKey } = await KeyManager.generateKeyPair();
+    await KeyManager._persistIdentityAtomic(privateKey, publicKey);
     return publicKey;
   }
 
   /**
-   * Import an existing key pair (e.g., from recovery phrase)
+   * 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: string): Promise<string> {
+  static async importKeyPair(
+    privateKey: string,
+    options?: { overwrite?: boolean },
+  ): Promise<string> {
     if (isWebPlatform()) {
       throw new Error('Identity import is only available on native platforms (iOS/Android). Please use the native app to import your identity.');
     }
-    const store = await initSecureStore();
-    
-    const keyPair = ec.keyFromPrivate(privateKey);
-    const publicKey = keyPair.getPublic('hex');
 
-    await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, privateKey, {
-      keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-    });
-    await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, publicKey);
+    if (!KeyManager.isValidPrivateKey(privateKey)) {
+      throw new Error('Invalid private key supplied to importKeyPair.');
+    }
 
-    // Update cache
-    KeyManager.cachedPublicKey = publicKey;
-    KeyManager.cachedHasIdentity = true;
+    // 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 keyPair = ec.keyFromPrivate(canonicalPrivate);
+    const publicKey = keyPair.getPublic('hex');
+
+    // Refuse silent overwrite — see createIdentity() for rationale.
+    if (!options?.overwrite) {
+      const existing = await KeyManager.getPublicKey();
+      if (existing && existing.toLowerCase() !== publicKey.toLowerCase()) {
+        throw new IdentityAlreadyExistsError(existing);
+      }
+      // If existing === publicKey, the device already has this exact identity;
+      // re-persisting is a no-op but harmless. Fall through to ensure backup
+      // is up to date.
+    }
 
+    await KeyManager._persistIdentityAtomic(canonicalPrivate, publicKey);
     return publicKey;
   }
 
@@ -662,7 +870,15 @@ export class KeyManager {
   }
 
   /**
-   * Check if an identity (key pair) exists on this device (cached for performance)
+   * Check if a complete, parseable identity exists on this device.
+   *
+   * Returns `true` only when BOTH the private and public keys are present,
+   * both are well-formed, AND the public key derives from the private key.
+   * A partially-written or corrupted identity returns `false` so that
+   * downstream code can resume the create / restore flow correctly.
+   *
+   * Note: this does NOT perform the full sign/verify roundtrip — call
+   * `verifyIdentityIntegrity()` for that.
    */
   static async hasIdentity(): Promise<boolean> {
     if (isWebPlatform()) {
@@ -672,23 +888,88 @@ export class KeyManager {
       return KeyManager.cachedHasIdentity;
     }
 
+    let privateKey: string | null;
+    let publicKey: string | null;
     try {
-      const privateKey = await KeyManager.getPrivateKey();
-      const hasIdentity = privateKey !== null;
-      
-      // Cache result
-      KeyManager.cachedHasIdentity = hasIdentity;
-      
-      return hasIdentity;
+      const store = await initSecureStore();
+      [privateKey, publicKey] = await Promise.all([
+        store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY),
+        store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY),
+      ]);
     } catch (error) {
-      // If we can't check, assume no identity (safer default)
-      // Cache false to avoid repeated failed attempts
-      KeyManager.cachedHasIdentity = false;
-      if (isDev()) {
-        logger.warn('Failed to check identity', { component: 'KeyManager' }, error);
-      }
+      // Storage threw — could be a transient keychain lock (e.g., background
+      // fetch before the device is unlocked). Do NOT cache `false`: if we
+      // did, the next call would skip storage entirely and return false even
+      // after the device is unlocked. Just return false and let the next
+      // call retry from storage.
+      logger.error('Failed to read identity from secure storage', error, { component: 'KeyManager' });
       return false;
     }
+
+    // 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 = ec
+            .keyFromPrivate(KeyManager.canonicalPrivateKey(privateKey))
+            .getPublic('hex');
+          // Hex equality is case-insensitive; normalize on both sides to
+          // tolerate legacy uppercase-stored public keys.
+          hasIdentity = derived.toLowerCase() === publicKey.toLowerCase();
+          if (!hasIdentity) {
+            logger.warn(
+              'KeyManager.hasIdentity: stored public key does not match derived public key',
+              { component: 'KeyManager' },
+            );
+          }
+        } catch (error) {
+          logger.warn(
+            'KeyManager.hasIdentity: failed to derive public key from stored private key',
+            { component: 'KeyManager' },
+            error,
+          );
+        }
+      } else {
+        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 (isDev()) {
+      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;
   }
 
   /**
@@ -787,7 +1068,12 @@ export class KeyManager {
   }
 
   /**
-   * Verify identity integrity - checks if keys are valid and accessible
+   * 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(): Promise<boolean> {
     if (isWebPlatform()) {
@@ -801,39 +1087,52 @@ export class KeyManager {
         return false;
       }
 
-      // Validate private key format
+      // Validate formats
       if (!KeyManager.isValidPrivateKey(privateKey)) {
         return false;
       }
-
-      // Validate public key format
       if (!KeyManager.isValidPublicKey(publicKey)) {
         return false;
       }
 
-      // Verify public key can be derived from private key
+      // 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 !== publicKey) {
+      if (derivedPublicKey.toLowerCase() !== publicKey.toLowerCase()) {
         return false; // Keys don't match
       }
 
-      // Verify we can create a key pair object (tests elliptic curve operations)
-      const keyPair = await KeyManager.getKeyPairObject();
-      if (!keyPair) {
+      // Full sign/verify probe — proves the keypair is functional, not just
+      // bytewise parseable. A previous version of this method would return
+      // true even when the underlying elliptic curve state was wedged.
+      const keyPair = ec.keyFromPrivate(KeyManager.canonicalPrivateKey(privateKey));
+      const probeHash = '0'.repeat(64);
+      const signature = keyPair.sign(probeHash);
+      if (!keyPair.verify(probeHash, signature)) {
+        logger.error('Identity sign/verify probe failed during integrity check', undefined, { component: 'KeyManager' });
         return false;
       }
 
       return true;
     } catch (error) {
-      if (isDev()) {
-        logger.error('Identity integrity check failed', error, { component: 'KeyManager' });
-      }
+      logger.error('Identity integrity check failed', error, { component: 'KeyManager' });
       return false;
     }
   }
 
   /**
-   * Restore identity from backup if primary storage is corrupted
+   * Restore identity from backup if primary storage is corrupted.
+   *
+   * SAFETY: this method will NEVER overwrite a verifying primary identity.
+   * If the primary passes a sign/verify probe, the backup is left untouched
+   * and `false` is returned — this protects against a transient
+   * `verifyIdentityIntegrity()` blip clobbering valid keys with stale
+   * backup keys (e.g., from a previous account before an import).
+   *
+   * Additionally, if the backup public key does NOT match the (still-
+   * present-but-failing) primary public key, we refuse to overwrite — the
+   * backup may belong to a different identity entirely.
    */
   static async restoreIdentityFromBackup(): Promise<boolean> {
     if (isWebPlatform()) {
@@ -841,7 +1140,15 @@ export class KeyManager {
     }
     try {
       const store = await initSecureStore();
-      
+
+      // First: if the primary still works, do nothing. Returning true here
+      // would be misleading; returning false (no restore needed) is the
+      // honest answer.
+      const primaryOk = await KeyManager.verifyIdentityIntegrity();
+      if (primaryOk) {
+        return false;
+      }
+
       // Check if backup exists
       const backupPrivateKey = await store.getItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
       const backupPublicKey = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
@@ -851,40 +1158,50 @@ export class KeyManager {
       }
 
       // Verify backup integrity
-      if (!KeyManager.isValidPrivateKey(backupPrivateKey)) {
+      if (!KeyManager.isValidPrivateKey(backupPrivateKey) || !KeyManager.isValidPublicKey(backupPublicKey)) {
+        logger.warn('Backup identity is malformed; refusing to restore', { component: 'KeyManager' });
         return false;
       }
 
-      if (!KeyManager.isValidPublicKey(backupPublicKey)) {
+      // 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.warn('Backup public key does not match derived; refusing to restore', { component: 'KeyManager' });
         return false;
       }
 
-      // Verify keys match
-      const derivedPublicKey = KeyManager.derivePublicKey(backupPrivateKey);
-      if (derivedPublicKey !== backupPublicKey) {
-        return false; // Backup keys don't match
+      // CRITICAL: if there is still a (broken) primary public key present
+      // that does NOT match the backup, the backup may be from a completely
+      // different identity. Better to surface a corrupted state than
+      // silently switch the user to a different account.
+      const currentPrimaryPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY).catch(() => null);
+      if (
+        currentPrimaryPublic &&
+        currentPrimaryPublic.toLowerCase() !== backupPublicKey.toLowerCase()
+      ) {
+        logger.error(
+          'Primary identity is corrupted AND does not match the backup. Refusing to restore to avoid switching accounts.',
+          undefined,
+          { component: 'KeyManager' },
+        );
+        return false;
       }
 
-      await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, backupPrivateKey, {
-        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-      });
-      await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, backupPublicKey);
-
-      const restored = await KeyManager.verifyIdentityIntegrity();
-      if (restored) {
-        // Update cache
-        KeyManager.cachedPublicKey = backupPublicKey;
-        KeyManager.cachedHasIdentity = true;
-
-        await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
-        return true;
+      // Safe to restore: rebuild the primary using the same atomic write
+      // path createIdentity uses, including verification.
+      try {
+        await KeyManager._persistIdentityAtomic(backupPrivateKey, backupPublicKey);
+      } catch (error) {
+        logger.error('Failed to persist identity restored from backup', error, { component: 'KeyManager' });
+        return false;
       }
 
-      return false;
+      await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+      return true;
     } catch (error) {
-      if (isDev()) {
-        logger.error('Failed to restore identity from backup', error, { component: 'KeyManager' });
-      }
+      logger.error('Failed to restore identity from backup', error, { component: 'KeyManager' });
       return false;
     }
   }
@@ -899,39 +1216,100 @@ export class KeyManager {
     }
     const privateKey = await KeyManager.getPrivateKey();
     if (!privateKey) return null;
-    return ec.keyFromPrivate(privateKey);
+    return ec.keyFromPrivate(KeyManager.canonicalPrivateKey(privateKey));
   }
 
   /**
    * Derive public key from a private key (without storing)
    */
   static derivePublicKey(privateKey: string): string {
-    const keyPair = ec.keyFromPrivate(privateKey);
+    const keyPair = ec.keyFromPrivate(KeyManager.canonicalPrivateKey(privateKey));
     return keyPair.getPublic('hex');
   }
 
   /**
    * 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: string): boolean {
+    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;
+    }
     try {
       ec.keyFromPublic(publicKey, 'hex');
       return true;
-    } catch {
+    } catch (error) {
+      if (isDev()) {
+        logger.debug('[oxy.crypto] isValidPublicKey rejected input', { component: 'KeyManager' }, error);
+      }
       return false;
     }
   }
 
   /**
-   * Validate that a string is a valid private key
+   * 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 because `elliptic`'s underlying `BN(input, 16)` happily
+   * accepts non-hex characters (treating them as zero), which would let
+   * "not-hex" pass through as a valid (but compromised, near-zero) key.
    */
   static isValidPrivateKey(privateKey: string): boolean {
+    if (typeof privateKey !== 'string' || privateKey.length === 0) {
+      return false;
+    }
+    if (!/^[0-9a-fA-F]+$/.test(privateKey)) {
+      return false;
+    }
+    // secp256k1 private keys are 32 bytes (64 hex chars). `elliptic`'s
+    // `getPrivate('hex')` strips leading zero bytes, so a valid key whose
+    // leading byte is 0 ends up as 62 hex chars in storage. Accept any
+    // length from 1..64 here — we re-pad before deriving below — and
+    // reject longer than 64.
+    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;
+    }
     try {
-      const keyPair = ec.keyFromPrivate(privateKey);
+      const keyPair = ec.keyFromPrivate(padded);
+      const priv = keyPair.getPrivate();
+      // Private key must be > 0 and < curve order n. elliptic doesn't
+      // enforce this on keyFromPrivate, so we do it here.
+      if (priv.isZero() || priv.cmp(ec.curve.n) >= 0) {
+        return false;
+      }
       // Verify it can derive a public key
-      keyPair.getPublic('hex');
+      const pub = keyPair.getPublic('hex');
+      if (!pub || pub.length === 0) {
+        return false;
+      }
       return true;
-    } catch {
+    } catch (error) {
+      if (isDev()) {
+        logger.debug('[oxy.crypto] isValidPrivateKey rejected input', { component: 'KeyManager' }, error);
+      }
       return false;
     }
   }