@oxyhq/core 1.11.16 → 1.11.18

package/dist/esm/crypto/keyManager.js

@@ -544,16 +544,28 @@ export 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
+     * 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.
      *
-     * 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()`.
+     * 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
      */
@@ -565,23 +577,60 @@ export class KeyManager {
         // 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.
+        // 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 {
-            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());
+            priorPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+            priorPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
         }
         catch (error) {
-            logger.error('Failed to write identity backup before primary', error, { component: 'KeyManager' });
-            throw new IdentityPersistError('Failed to write identity backup', error);
+            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(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+            }
+            catch {
+                existingBackupPublic = null;
+            }
+            if (existingBackupPublic?.toLowerCase() !== priorPublic.toLowerCase()) {
+                try {
+                    await store.setItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY, KeyManager.canonicalPrivateKey(priorPrivate), {
+                        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                    });
+                    await store.setItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY, priorPublic.toLowerCase());
+                    await store.setItemAsync(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+                }
+                catch (error) {
+                    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 2 + 3: Write primary keys. Public first so that if private write
-        // fails we are still missing the most critical bit.
+        // 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(STORAGE_KEYS.PUBLIC_KEY, canonicalPublic);
             await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, canonicalPrivate, {
@@ -590,18 +639,10 @@ export class KeyManager {
         }
         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 */ }
+            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
             throw new IdentityPersistError('Failed to write identity to secure store', error);
         }
-        // Step 4: Verify round-trip. If the store silently drops our writes
+        // 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.
@@ -613,6 +654,7 @@ export class KeyManager {
         }
         catch (error) {
             logger.error('Failed to read identity back after write', error, { component: 'KeyManager' });
+            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
             throw new IdentityPersistError('Failed to verify identity after write', error);
         }
         // Hex comparisons are case-insensitive — normalize on both sides so a
@@ -621,6 +663,7 @@ export class KeyManager {
         if (readBackPrivate?.toLowerCase() !== canonicalPrivate ||
             readBackPublic?.toLowerCase() !== canonicalPublic) {
             logger.error('Identity round-trip mismatch after write', undefined, { component: 'KeyManager' });
+            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
             throw new IdentityPersistError('Identity write was not persisted correctly (round-trip mismatch).');
         }
         // Final sanity: derive public from the stored private and confirm the
@@ -641,15 +684,71 @@ export class KeyManager {
             }
         }
         catch (error) {
+            await KeyManager._rollbackPrimary(store, priorPrivate, priorPublic);
             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);
         }
+        // Step 3: The new primary is durable and functional. NOW it is safe to
+        // refresh the backup to the new key. If this final backup write fails the
+        // user still has a fully working primary, and the backup still holds the
+        // PREVIOUS good identity — so we log and continue rather than failing the
+        // whole operation (failing here would be strictly worse: a working
+        // primary would be reported as an error to the caller).
+        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.warn('Primary identity persisted successfully but refreshing the backup failed; primary is usable, backup may be stale', { component: 'KeyManager' }, error);
+        }
         // Update cache only after we are certain the identity is durable.
         KeyManager.cachedPublicKey = canonicalPublic;
         KeyManager.cachedHasIdentity = true;
     }
+    /**
+     * 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, priorPrivate, priorPublic) {
+        try {
+            if (priorPrivate && priorPublic) {
+                // Restore exactly what was there before the failed write.
+                await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, priorPublic, {});
+                await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, priorPrivate, {
+                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+                });
+            }
+            else {
+                // There was no prior identity — leave the device empty rather than
+                // half-written so hasIdentity() does not lie.
+                try {
+                    await store.deleteItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+                }
+                catch { /* best effort */ }
+                try {
+                    await store.deleteItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+                }
+                catch { /* best effort */ }
+            }
+        }
+        catch (rollbackError) {
+            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.
      *
@@ -981,17 +1080,23 @@ export class KeyManager {
         }
     }
     /**
-     * Restore identity from backup if primary storage is corrupted.
+     * Restore identity from backup if primary storage is genuinely missing or
+     * corrupt.
      *
-     * 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).
+     * 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.
      *
-     * 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.
+     * 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()) {
@@ -999,20 +1104,36 @@ 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) {
+            // 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(STORAGE_KEYS.PRIVATE_KEY);
+                primaryPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+            }
+            catch (error) {
+                logger.warn('restoreIdentityFromBackup: could not read primary (transient?). Refusing to restore.', { component: 'KeyManager' }, error);
                 return false;
             }
-            // Check if backup exists
+            // 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(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
             const backupPublicKey = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
             if (!backupPrivateKey || !backupPublicKey) {
                 return false; // No backup available
             }
-            // Verify backup integrity
             if (!KeyManager.isValidPrivateKey(backupPrivateKey) || !KeyManager.isValidPublicKey(backupPublicKey)) {
                 logger.warn('Backup identity is malformed; refusing to restore', { component: 'KeyManager' });
                 return false;
@@ -1025,14 +1146,21 @@ export class KeyManager {
                 logger.warn('Backup public key does not match derived; refusing to restore', { component: 'KeyManager' });
                 return false;
             }
-            // 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' });
+            // 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.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.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

package/dist/esm/mixins/OxyServices.auth.js

@@ -317,6 +317,11 @@ export function OxyServicesAuthMixin(Base) {
         }
         /**
          * 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.
          */
         async getTokenBySession(sessionId) {
             try {
@@ -328,6 +333,40 @@ export function OxyServicesAuthMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * 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.
+         */
+        async claimSessionByToken(sessionToken, options = {}) {
+            try {
+                const res = await this.makeRequest('POST', '/auth/session/claim', {
+                    sessionToken,
+                    ...(options.deviceFingerprint ? { deviceFingerprint: options.deviceFingerprint } : {}),
+                }, { cache: false, retry: false });
+                this.setTokens(res.accessToken, res.refreshToken);
+                return res;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * Get sessions by session ID
          */

package/dist/esm/mixins/OxyServices.fedcm.js

@@ -82,7 +82,10 @@ export function OxyServicesFedCMMixin(Base) {
                     throw new OxyAuthenticationError('FedCM not supported in this browser. Please update your browser or use an alternative sign-in method.');
                 }
                 try {
-                    const nonce = options.nonce || this.generateNonce();
+                    // Prefer a server-minted, origin-bound nonce so the downstream
+                    // `/fedcm/exchange` can validate it. A caller-supplied nonce is
+                    // respected as-is for advanced use cases.
+                    const nonce = options.nonce || (await this.getFedcmNonce());
                     const clientId = this.getClientId();
                     // Use provided loginHint, or fall back to stored last-used account ID
                     const loginHint = options.loginHint || this.getStoredLoginHint();
@@ -177,7 +180,9 @@ export function OxyServicesFedCMMixin(Base) {
                 let credential = null;
                 const loginHint = this.getStoredLoginHint();
                 try {
-                    const nonce = this.generateNonce();
+                    // Server-minted, origin-bound nonce — required for `/fedcm/exchange`
+                    // to accept the resulting ID token (anti-replay binding).
+                    const nonce = await this.getFedcmNonce();
                     debug.log('Silent SSO: Attempting silent mediation...', loginHint ? `(hint: ${loginHint})` : '');
                     credential = await this.requestIdentityCredential({
                         configURL: this.resolveFedcmConfigUrl(),
@@ -419,7 +424,14 @@ export function OxyServicesFedCMMixin(Base) {
                 };
             }
             /**
-             * 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
              */
@@ -434,6 +446,49 @@ export function OxyServicesFedCMMixin(Base) {
                 }
                 throw new Error('No secure random source available for nonce generation');
             }
+            /**
+             * 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
+             */
+            async mintServerNonce() {
+                const result = await this.makeRequest('POST', '/fedcm/nonce', {}, { cache: false });
+                if (!result?.nonce) {
+                    throw new OxyAuthenticationError('FedCM nonce endpoint returned no nonce');
+                }
+                return result.nonce;
+            }
+            /**
+             * 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
+             */
+            async getFedcmNonce() {
+                try {
+                    return await this.mintServerNonce();
+                }
+                catch (error) {
+                    debug.warn('Could not mint server nonce, falling back to local nonce:', error instanceof Error ? error.message : String(error));
+                    return this.generateNonce();
+                }
+            }
             /**
              * Get the client ID for this origin
              *