@oxyhq/core 1.11.16 → 1.11.18

package/dist/types/crypto/keyManager.d.ts

@@ -160,20 +160,42 @@ export declare class KeyManager {
     /**
      * 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()`.
+     * 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
      */
     private static _persistIdentityAtomic;
+    /**
+     * 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
+     */
+    private static _rollbackPrimary;
     /**
      * Generate and securely store a new key pair on the device.
      *
@@ -242,17 +264,23 @@ export declare class KeyManager {
      */
     static verifyIdentityIntegrity(): Promise<boolean>;
     /**
-     * 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.
+     * 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 restoreIdentityFromBackup(): Promise<boolean>;
     /**

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -193,11 +193,47 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         }>>;
         /**
          * Get access token by session ID
+         *
+         * SECURITY: this endpoint requires the caller to already hold a
+         * bearer token whose user owns the referenced session (C1 hardening
+         * in the API). For the device-flow / QR sign-in case where the
+         * client has no bearer token yet, use `claimSessionByToken` instead.
          */
         getTokenBySession(sessionId: string): Promise<{
             accessToken: string;
             expiresAt: string;
         }>;
+        /**
+         * Exchange a device-flow sessionToken for the first access token.
+         *
+         * The originating client holds a 128-bit `sessionToken` that nobody
+         * else has seen — it was generated client-side, sent once on
+         * `POST /auth/session/create`, and is never echoed back. After
+         * another authenticated device approves the session via
+         * `POST /auth/session/authorize/{sessionToken}` (bearer-authed) and
+         * the auth socket / poll loop notifies this client, the client
+         * exchanges its `sessionToken` here for the first access token,
+         * refresh token, sessionId, and the authorized user.
+         *
+         * This call requires no Authorization header — the high-entropy
+         * `sessionToken` IS the credential (RFC 8628 §3.4). The exchange is
+         * single-use; replay attempts are rejected with 401.
+         *
+         * @param sessionToken - The same sessionToken the SDK passed to
+         *   `POST /auth/session/create` at the start of the flow.
+         * @param options.deviceFingerprint - Optional fingerprint of the
+         *   originating client device.
+         */
+        claimSessionByToken(sessionToken: string, options?: {
+            deviceFingerprint?: string;
+        }): Promise<{
+            accessToken: string;
+            refreshToken: string;
+            sessionId: string;
+            deviceId: string;
+            expiresAt: string;
+            user: User;
+        }>;
         /**
          * Get sessions by session ID
          */

package/dist/types/mixins/OxyServices.fedcm.d.ts

@@ -140,11 +140,47 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
          */
         getFedCMConfig(): FedCMConfig;
         /**
-         * Generate a cryptographically secure nonce for FedCM
+         * Generate a cryptographically secure local nonce for FedCM.
+         *
+         * NOTE: this is a *local* fallback only. The server-side `/fedcm/exchange`
+         * endpoint requires the nonce embedded in the ID token to have been minted
+         * by `POST /fedcm/nonce` (see {@link mintServerNonce}) and bound to this
+         * origin. A purely local nonce will be rejected with `invalid_nonce`. Use
+         * {@link getFedcmNonce}, which prefers a server-minted nonce and only falls
+         * back to this generator when the mint endpoint is unreachable.
          *
          * @private
          */
         generateNonce(): string;
+        /**
+         * Mint a single-use, origin-bound nonce from the Oxy API.
+         *
+         * The FedCM ID token issued by the IdP embeds this nonce as the `nonce`
+         * claim. When the consuming app calls `POST /fedcm/exchange`, the API burns
+         * the nonce (atomic `usedAt` transition) and verifies it was minted for the
+         * same origin as the token `aud`. This is the anti-replay binding required
+         * by the API's H9 hardening — without a server-minted nonce the exchange
+         * always fails.
+         *
+         * The browser attaches the `Origin` header automatically on this
+         * cross-origin request, so the API binds the nonce to the calling app's
+         * origin (which also becomes the FedCM `clientId`/token `aud`).
+         *
+         * @private
+         */
+        mintServerNonce(): Promise<string>;
+        /**
+         * Resolve the nonce to use for a FedCM credential request.
+         *
+         * Prefers a server-minted, origin-bound nonce (required for the token
+         * exchange to succeed). If the mint endpoint is unreachable we fall back to
+         * a locally generated nonce so the browser flow can still proceed; the
+         * exchange may then fail server-side, but that is strictly better than
+         * throwing before the browser ever shows its UI.
+         *
+         * @private
+         */
+        getFedcmNonce(): Promise<string>;
         /**
          * Get the client ID for this origin
          *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "1.11.16",
+  "version": "1.11.18",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/crypto/__tests__/keyManager.atomicity.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Tests for KeyManager atomic-write & backup-restore safety under FLAKY storage.
+ *
+ * These pin the "never leave the device with zero recoverable copies of a
+ * healthy identity" invariant. Each scenario corresponds to a real
+ * account-loss / account-switch bug that a half-failed SecureStore write could
+ * otherwise cause:
+ *
+ *   1. A failed OVERWRITE must roll the primary back to the ORIGINAL identity
+ *      and must keep a recoverable backup of it — never switch to the
+ *      half-written new identity.
+ *   2. A transient read failure must not cause restoreIdentityFromBackup() to
+ *      clobber a healthy-but-momentarily-locked primary with a stale backup.
+ *   3. restoreIdentityFromBackup() must refuse when the backup identifies a
+ *      different account than a private key still present in the primary slot.
+ *   4. A first-time create still writes a backup (no regression).
+ */
+
+import { setPlatformOS } from '../../utils/platform';
+
+// Fault-injectable in-memory secure store. `failPlan` lets a test make a
+// specific (op, key) pair throw to simulate a keychain that fails mid-write or
+// is transiently locked.
+const failPlan: { failKey?: string; failOp?: 'set' | 'get' } = {};
+
+jest.mock(
+  'expo-secure-store',
+  () => {
+    const store = new Map<string, string>();
+    const maybeFail = (op: 'set' | 'get', key: string) => {
+      if (failPlan.failOp === op && failPlan.failKey === key) {
+        throw new Error(`Simulated ${op} failure for ${key}`);
+      }
+    };
+    return {
+      __esModule: true,
+      WHEN_UNLOCKED_THIS_DEVICE_ONLY: 'WHEN_UNLOCKED_THIS_DEVICE_ONLY',
+      WHEN_UNLOCKED: 'WHEN_UNLOCKED',
+      setItemAsync: jest.fn(async (key: string, value: string) => {
+        maybeFail('set', key);
+        store.set(key, value);
+      }),
+      getItemAsync: jest.fn(async (key: string) => {
+        maybeFail('get', key);
+        return store.get(key) ?? null;
+      }),
+      deleteItemAsync: jest.fn(async (key: string) => {
+        store.delete(key);
+      }),
+      __resetStore__: () => {
+        store.clear();
+        failPlan.failKey = undefined;
+        failPlan.failOp = undefined;
+      },
+      __getStore__: () => store,
+      __failPlan__: failPlan,
+    };
+  },
+  { virtual: true },
+);
+
+jest.mock(
+  'expo-crypto',
+  () => ({
+    __esModule: true,
+    getRandomBytes: (length: number) => {
+      const out = new Uint8Array(length);
+      for (let i = 0; i < length; i++) out[i] = (Math.random() * 256) & 0xff;
+      return out;
+    },
+    digestStringAsync: async () => '0'.repeat(64),
+    CryptoDigestAlgorithm: { SHA256: 'SHA-256' },
+  }),
+  { virtual: true },
+);
+
+jest.mock('../../utils/platformCrypto', () => ({
+  __esModule: true,
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  loadExpoCrypto: async () => require('expo-crypto'),
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  loadSecureStore: async () => require('expo-secure-store'),
+  loadAsyncStorage: async () => ({
+    default: { getItem: async () => null, setItem: async () => undefined, removeItem: async () => undefined },
+  }),
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  loadNodeCrypto: async () => require('crypto'),
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  getRandomBytesRN: (n: number) => require('expo-crypto').getRandomBytes(n),
+}));
+
+interface SecureStoreTestHandle {
+  __resetStore__: () => void;
+  __getStore__: () => Map<string, string>;
+  __failPlan__: { failKey?: string; failOp?: 'set' | 'get' };
+}
+
+describe('KeyManager atomicity & recoverability under flaky storage', () => {
+  let KeyManager: typeof import('../keyManager').KeyManager;
+
+  const resetCaches = () => {
+    const km = KeyManager as unknown as { cachedPublicKey: unknown; cachedHasIdentity: unknown };
+    km.cachedPublicKey = null;
+    km.cachedHasIdentity = null;
+  };
+
+  beforeAll(() => {
+    setPlatformOS('ios');
+    (globalThis as unknown as { navigator: unknown }).navigator = { product: 'ReactNative' };
+  });
+
+  beforeEach(async () => {
+    jest.resetModules();
+    setPlatformOS('ios');
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    ss.__resetStore__();
+    const km = await import('../keyManager');
+    KeyManager = km.KeyManager;
+    resetCaches();
+  });
+
+  it('a failed OVERWRITE leaves the ORIGINAL identity intact and recoverable (no silent switch)', async () => {
+    const originalPublic = await KeyManager.createIdentity();
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    const originalPriv = ss.__getStore__().get('oxy_identity_private_key');
+    resetCaches();
+
+    // The new primary private write fails mid-overwrite.
+    ss.__failPlan__.failOp = 'set';
+    ss.__failPlan__.failKey = 'oxy_identity_private_key';
+    await expect(KeyManager.createIdentity({ overwrite: true })).rejects.toBeDefined();
+
+    // Recover from the simulated fault.
+    ss.__failPlan__.failKey = undefined;
+    ss.__failPlan__.failOp = undefined;
+    resetCaches();
+
+    // Primary must still be the original identity (rolled back).
+    expect(await KeyManager.hasIdentity()).toBe(true);
+    expect(await KeyManager.getPublicKey()).toBe(originalPublic);
+    expect(ss.__getStore__().get('oxy_identity_private_key')).toBe(originalPriv);
+
+    // And the backup must still hold the ORIGINAL identity, never the new one.
+    const m = ss.__getStore__();
+    expect(m.get('oxy_identity_backup_private_key')).toBe(originalPriv);
+    expect(m.get('oxy_identity_backup_public_key')).toBe(originalPublic);
+  });
+
+  it('restoreIdentityFromBackup does NOT clobber a healthy primary that is only transiently unreadable', async () => {
+    const original = await KeyManager.createIdentity();
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+
+    // Put a DIFFERENT identity in the backup slot (simulates a stale backup
+    // from a previous account that a failed backup-refresh left behind).
+    const other = await KeyManager.generateKeyPair();
+    ss.__getStore__().set('oxy_identity_backup_private_key', other.privateKey);
+    ss.__getStore__().set('oxy_identity_backup_public_key', other.publicKey);
+    resetCaches();
+
+    // Make the primary PRIVATE read throw (transient keychain lock).
+    ss.__failPlan__.failOp = 'get';
+    ss.__failPlan__.failKey = 'oxy_identity_private_key';
+
+    const restored = await KeyManager.restoreIdentityFromBackup();
+    expect(restored).toBe(false); // refused — transient read must not trigger a restore
+
+    // Clear the fault; the original primary must be intact and unchanged.
+    ss.__failPlan__.failKey = undefined;
+    ss.__failPlan__.failOp = undefined;
+    resetCaches();
+    expect(await KeyManager.getPublicKey()).toBe(original);
+    expect(ss.__getStore__().get('oxy_identity_public_key')).toBe(original);
+  });
+
+  it('restoreIdentityFromBackup refuses when a present primary private key identifies a different account than the backup', async () => {
+    // Primary holds identity A (valid). Corrupt ONLY the public key so the
+    // primary fails its consistency check but the private key still derives a
+    // real, different identity than the backup.
+    const a = await KeyManager.createIdentity();
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    const m = ss.__getStore__();
+
+    // Backup holds a DIFFERENT identity B.
+    const b = await KeyManager.generateKeyPair();
+    m.set('oxy_identity_backup_private_key', b.privateKey);
+    m.set('oxy_identity_backup_public_key', b.publicKey);
+    // Corrupt A's stored public key (private key A still present & valid).
+    m.set('oxy_identity_public_key', `04${'e'.repeat(128)}`);
+    resetCaches();
+
+    const restored = await KeyManager.restoreIdentityFromBackup();
+    expect(restored).toBe(false);
+    // Must NOT have switched the primary to B.
+    expect(m.get('oxy_identity_public_key')).not.toBe(b.publicKey);
+    expect(m.get('oxy_identity_private_key')).not.toBe(b.privateKey);
+    // The original A private key is still in place (untouched).
+    expect(KeyManager.derivePublicKey(m.get('oxy_identity_private_key') as string)).toBe(a);
+  });
+
+  it('restores a provably-absent primary from a valid backup', async () => {
+    const original = await KeyManager.createIdentity();
+    const ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    const m = ss.__getStore__();
+    // Wipe the primary entirely (backup remains).
+    m.delete('oxy_identity_private_key');
+    m.delete('oxy_identity_public_key');
+    resetCaches();
+
+    const restored = await KeyManager.restoreIdentityFromBackup();
+    expect(restored).toBe(true);
+    expect(await KeyManager.getPublicKey()).toBe(original);
+    expect(await KeyManager.verifyIdentityIntegrity()).toBe(true);
+  });
+});