@oxyhq/core 12.2.0 → 12.3.0

package/src/crypto/recoveryPhrase.ts

@@ -9,6 +9,7 @@
 
 import * as bip39 from 'bip39';
 import { KeyManager } from './keyManager';
+import { hkdfSha256 } from './kdf';
 
 /**
  * Convert Uint8Array or array-like to hexadecimal string
@@ -22,12 +23,64 @@ function toHex(data: Uint8Array | ArrayLike<number>): string {
     .join('');
 }
 
+/** UTF-8 encode an ASCII label to bytes (for HKDF salt/info). */
+function utf8(label: string): Uint8Array {
+  return new TextEncoder().encode(label);
+}
+
+/**
+ * HKDF context tag for the encrypted-backup key schedule (b3 Feature 1). Used as
+ * the HKDF `salt`; distinct from any other Oxy key-derivation salt so the backup
+ * key schedule is independent. Versioned so a future scheme change is a new tag.
+ */
+export const BACKUP_KDF_SALT = 'oxy-identity-backup-v1';
+/** HKDF `info` label that derives the symmetric AEAD key from the seed. */
+export const BACKUP_KDF_ENCRYPTION_INFO = 'oxy-backup-encryption-key';
+/** HKDF `info` label that derives the (server-hashed) backup locator from the seed. */
+export const BACKUP_KDF_LOOKUP_INFO = 'oxy-backup-lookup-id';
+/** Byte length of both the derived backup key and the derived lookup id (256-bit). */
+export const BACKUP_MATERIAL_LENGTH = 32;
+
+/**
+ * The two pieces of key material derived from a recovery phrase for the
+ * encrypted off-device backup, kept strictly separate by HKDF domain separation.
+ */
+export interface BackupMaterial {
+  /**
+   * The 32-byte symmetric key handed to `encryptAead`/`decryptAead`. NEVER
+   * leaves the device — the server sees only ciphertext produced with it.
+   */
+  backupKey: Uint8Array;
+  /**
+   * The 256-bit backup locator, hex. Sent to the server, which stores ONLY
+   * `sha256(lookupId)` — so possession of this value (which itself requires the
+   * full seed to compute) is what locates a backup, and the server can never
+   * recompute it from what it stores.
+   */
+  lookupId: string;
+}
+
 export interface RecoveryPhraseResult {
   phrase: string;
   words: string[];
   publicKey: string;
 }
 
+/**
+ * A freshly-derived identity that has NOT been persisted to secure storage.
+ *
+ * Unlike {@link RecoveryPhraseResult} this also exposes the `privateKey`, because
+ * the caller must be able to sign with (or later persist) the material itself —
+ * the whole point of a "pending" identity is that nothing is committed until an
+ * external step (e.g. a server-confirmed key rotation) succeeds.
+ */
+export interface PendingIdentityResult {
+  phrase: string;
+  words: string[];
+  privateKey: string;
+  publicKey: string;
+}
+
 export interface GenerateIdentityOptions {
   /**
    * Pass `true` to allow overwriting an existing on-device identity.
@@ -103,6 +156,86 @@ export class RecoveryPhraseService {
     };
   }
 
+  /**
+   * Derive a brand-new identity + recovery phrase WITHOUT persisting anything.
+   *
+   * Pure: same derivation as {@link generateIdentityWithRecovery} (128-bit
+   * mnemonic → seed → first 32 bytes as the secp256k1 private key) but it stops
+   * BEFORE `KeyManager.importKeyPair`, so no on-device identity is touched. The
+   * caller decides if/when to commit the material (e.g. only after a server
+   * confirms a key rotation). Works on web too — it never reads or writes secure
+   * storage.
+   *
+   * The 12-word `phrase` MUST be shown to the user before the identity is
+   * committed anywhere — if it is lost the account becomes unrecoverable.
+   */
+  static async derivePendingIdentity(): Promise<PendingIdentityResult> {
+    const mnemonic = bip39.generateMnemonic(128);
+    const seed = await bip39.mnemonicToSeed(mnemonic);
+    const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
+    const privateKey = toHex(seedSlice);
+    const publicKey = KeyManager.derivePublicKey(privateKey);
+
+    return {
+      phrase: mnemonic,
+      words: mnemonic.split(' '),
+      privateKey,
+      publicKey,
+    };
+  }
+
+  /**
+   * Derive the private key from a recovery phrase WITHOUT storing it.
+   *
+   * The private-key counterpart of {@link derivePublicKeyFromPhrase}. Used to
+   * re-derive a key in memory (e.g. to sign a rotation proof with the current
+   * key when the device has no SecureStore copy). Never persists — the returned
+   * material lives only in the caller's memory.
+   */
+  static async derivePrivateKeyFromPhrase(phrase: string): Promise<string> {
+    const normalizedPhrase = phrase.trim().toLowerCase();
+
+    if (!bip39.validateMnemonic(normalizedPhrase)) {
+      throw new Error('Invalid recovery phrase');
+    }
+
+    const seed = await bip39.mnemonicToSeed(normalizedPhrase);
+    const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
+    return toHex(seedSlice);
+  }
+
+  /**
+   * Derive the encrypted-backup key material from a recovery phrase (b3 Feature
+   * 1). PURE and additive — it does NOT touch the frozen phrase→privateKey
+   * derivation ({@link derivePrivateKeyFromPhrase} slices the first 32 seed
+   * bytes) and never reads or writes secure storage.
+   *
+   * Both outputs are derived from the FULL 64-byte BIP-39 seed via HKDF-SHA256
+   * with domain-separated `info` labels, so the domain separation is real: a
+   * device compromise that leaks only the raw 32-byte private key can compute
+   * NEITHER the backup key nor the lookup id (both need the whole seed). Locating
+   * AND decrypting a backup therefore requires the recovery phrase.
+   *
+   * @param phrase - The BIP-39 recovery phrase (validated + normalized here).
+   * @returns `{ backupKey, lookupId }` — the AEAD key (kept local) and the hex
+   *   locator (uploaded; server stores only its hash).
+   * @throws if the phrase is not a valid BIP-39 mnemonic.
+   */
+  static async deriveBackupMaterial(phrase: string): Promise<BackupMaterial> {
+    const normalizedPhrase = phrase.trim().toLowerCase();
+
+    if (!bip39.validateMnemonic(normalizedPhrase)) {
+      throw new Error('Invalid recovery phrase. Please check the words and try again.');
+    }
+
+    const seed = await bip39.mnemonicToSeed(normalizedPhrase);
+    const salt = utf8(BACKUP_KDF_SALT);
+    const backupKey = hkdfSha256(seed, salt, utf8(BACKUP_KDF_ENCRYPTION_INFO), BACKUP_MATERIAL_LENGTH);
+    const lookupId = toHex(hkdfSha256(seed, salt, utf8(BACKUP_KDF_LOOKUP_INFO), BACKUP_MATERIAL_LENGTH));
+
+    return { backupKey, lookupId };
+  }
+
   /**
    * Restore an identity from a recovery phrase.
    *

package/src/i18n/locales/ar-SA.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "أنشئ حسابك",
+    "subtitle": "هوية واحدة لكل النظام البيئي.",
     "commonsHeadline": "أنشئ هويتك في Commons",
     "commonsExplainer": "‏Commons هي هوية Oxy الخاصة بك بحفظ ذاتي كامل — تطبيق واحد يعمل في كل مكان.",
     "createInCommons": "أنشئ هويتك في Commons",

package/src/i18n/locales/ca-ES.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Crea el teu compte",
+    "subtitle": "Una identitat per a tot l'ecosistema.",
     "commonsHeadline": "Crea la teva identitat a Commons",
     "commonsExplainer": "Commons és la teva identitat d'Oxy amb autocustòdia completa: una app que funciona a tot arreu.",
     "createInCommons": "Crea la teva identitat a Commons",

package/src/i18n/locales/de-DE.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Erstellen Sie Ihr Konto",
+    "subtitle": "Eine Identität für das gesamte Ökosystem.",
     "commonsHeadline": "Erstellen Sie Ihre Identität in Commons",
     "commonsExplainer": "Commons ist Ihre vollständig selbstverwaltete Oxy-Identität – eine App, überall einsetzbar.",
     "createInCommons": "Erstellen Sie Ihre Identität in Commons",

package/src/i18n/locales/en-US.json

@@ -57,6 +57,8 @@
     }
   },
   "signup": {
+    "title": "Create your account",
+    "subtitle": "One identity for the whole ecosystem.",
     "commonsHeadline": "Create your identity in Commons",
     "commonsExplainer": "Commons is your full self-custody Oxy identity — one app, works everywhere.",
     "createInCommons": "Create your identity in Commons",
@@ -70,6 +72,9 @@
     "backToSignInLink": "Already have an account? Sign in",
     "hubExplainer": "Create your Oxy ID in a secure window, then come right back.",
     "continueInWindow": "Continue in a new window",
+    "toasts": {
+      "passkeyCreateFailed": "We couldn't create your account. Please try again."
+    },
     "welcome": {
       "title": "Welcome to Oxy!",
       "subtitle": "Let's create your account in just a few steps",
@@ -372,6 +377,8 @@
     "toasts": {
       "switchSuccess": "Account switched successfully!",
       "switchFailed": "There was a problem switching accounts. Please try again.",
+      "signInFailed": "Sign-in failed. Please try again.",
+      "passkeySignInFailed": "Passkey sign-in failed. Please try again.",
       "removeSuccess": "Account removed successfully!",
       "removeFailed": "There was a problem removing the account. Please try again.",
       "signOutAllSuccess": "All accounts signed out successfully!",

package/src/i18n/locales/es-ES.json

@@ -57,6 +57,8 @@
     }
   },
   "signup": {
+    "title": "Crea tu cuenta",
+    "subtitle": "Una identidad para todo el ecosistema.",
     "commonsHeadline": "Crea tu identidad en Commons",
     "commonsExplainer": "Commons es tu identidad de Oxy con autocustodia completa: una app que funciona en todas partes.",
     "createInCommons": "Crea tu identidad en Commons",
@@ -70,6 +72,9 @@
     "backToSignInLink": "¿Ya tienes cuenta? Inicia sesión",
     "hubExplainer": "Crea tu Oxy ID en una ventana segura y vuelve enseguida.",
     "continueInWindow": "Continuar en una ventana nueva",
+    "toasts": {
+      "passkeyCreateFailed": "No pudimos crear tu cuenta. Inténtalo de nuevo."
+    },
     "welcome": {
       "title": "¡Te damos la bienvenida a Oxy!",
       "subtitle": "Crea tu cuenta en pocos pasos",
@@ -570,6 +575,8 @@
     "toasts": {
       "switchSuccess": "¡Cuenta cambiada correctamente!",
       "switchFailed": "Hubo un problema al cambiar de cuenta. Inténtalo de nuevo.",
+      "signInFailed": "No se pudo iniciar sesión. Inténtalo de nuevo.",
+      "passkeySignInFailed": "No se pudo iniciar sesión con la llave de acceso. Inténtalo de nuevo.",
       "removeSuccess": "¡Cuenta eliminada correctamente!",
       "removeFailed": "Hubo un problema al eliminar la cuenta. Inténtalo de nuevo.",
       "signOutAllSuccess": "¡Todas las cuentas cerradas correctamente!",

package/src/i18n/locales/fr-FR.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Créez votre compte",
+    "subtitle": "Une seule identité pour tout l'écosystème.",
     "commonsHeadline": "Créez votre identité dans Commons",
     "commonsExplainer": "Commons est votre identité Oxy en autoconservation complète : une seule app, partout.",
     "createInCommons": "Créez votre identité dans Commons",

package/src/i18n/locales/it-IT.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Crea il tuo account",
+    "subtitle": "Un'unica identità per tutto l'ecosistema.",
     "commonsHeadline": "Crea la tua identità in Commons",
     "commonsExplainer": "Commons è la tua identità Oxy in piena autocustodia: un'unica app, ovunque.",
     "createInCommons": "Crea la tua identità in Commons",

package/src/i18n/locales/ja-JP.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "アカウントを作成",
+    "subtitle": "エコシステム全体で使える1つのアイデンティティ。",
     "commonsHeadline": "Commonsであなたのアイデンティティを作成",
     "commonsExplainer": "Commonsは完全に自己管理できるあなたのOxy IDです。1つのアプリでどこでも使えます。",
     "createInCommons": "Commonsであなたのアイデンティティを作成",

package/src/i18n/locales/ko-KR.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "계정 만들기",
+    "subtitle": "생태계 전체를 위한 하나의 아이덴티티.",
     "commonsHeadline": "Commons에서 나의 아이덴티티 만들기",
     "commonsExplainer": "Commons는 완전한 자기 보관 방식의 Oxy 아이덴티티입니다. 하나의 앱으로 어디서나 사용하세요.",
     "createInCommons": "Commons에서 나의 아이덴티티 만들기",

package/src/i18n/locales/pt-PT.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Crie a sua conta",
+    "subtitle": "Uma identidade para todo o ecossistema.",
     "commonsHeadline": "Crie a sua identidade no Commons",
     "commonsExplainer": "O Commons é a sua identidade Oxy com autocustódia total: uma app que funciona em todo o lado.",
     "createInCommons": "Crie a sua identidade no Commons",

package/src/i18n/locales/zh-CN.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "创建您的账户",
+    "subtitle": "一个身份，畅行整个生态系统。",
     "commonsHeadline": "在 Commons 中创建您的身份",
     "commonsExplainer": "Commons 是您完全自主保管的 Oxy 身份——一个应用，随处可用。",
     "createInCommons": "在 Commons 中创建您的身份",

package/src/index.ts

@@ -53,6 +53,7 @@ export type {
     BulkFollowResult,
     BulkUnfollowEntry,
     BulkUnfollowResult,
+    FollowMutationResult,
     ViewerGraph,
 } from './mixins/OxyServices.user';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
@@ -173,6 +174,9 @@ export type {
     VerifyRecordResult,
     VerifyDomainResult,
     RemoveDomainResult,
+    RotateKeyProof,
+    RotateKeyOptions,
+    RotateKeyResult,
 } from './mixins/OxyServices.identity';
 
 // ---------------------------------------------------------------------------
@@ -242,7 +246,18 @@ export type { KeyPair } from './crypto/keyManager';
 export { SignatureService } from './crypto/signatureService';
 export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';
-export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
+export type { RecoveryPhraseResult, PendingIdentityResult, BackupMaterial } from './crypto/recoveryPhrase';
+
+// Low-level crypto primitives (b3 Phase 0 — encrypted backup + device transfer)
+export { hkdfSha256 } from './crypto/kdf';
+export {
+    encryptAead,
+    decryptAead,
+    AEAD_KEY_LENGTH,
+    AEAD_NONCE_LENGTH,
+} from './crypto/aead';
+export type { AeadResult } from './crypto/aead';
+export { deriveSharedSecret } from './crypto/ecdh';
 
 // ---------------------------------------------------------------------------
 // Devices

package/src/mixins/OxyServices.identity.ts

@@ -29,12 +29,18 @@ import type {
   DomainVerificationInstructions,
   ExportBundle,
   OxySignedRecordType,
+  RotateKeyChallengeResponse,
+  RotateKeyCompleteResponse,
   SignedRecordEnvelope,
   VerifiedDomain,
 } from '@oxyhq/contracts';
+import { signMessage } from '@oxyhq/protocol';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
+import { RecoveryPhraseService, type PendingIdentityResult } from '../crypto/recoveryPhrase';
+import { isWeb } from '../utils/platform';
+import { logger } from '../logger';
 import { CACHE_TIMES } from './mixinHelpers';
 
 /**
@@ -93,6 +99,57 @@ export interface RemoveDomainResult {
   success: boolean;
 }
 
+/** How the caller proves control of the CURRENT key during a key rotation. */
+export type RotateKeyProof = 'device' | 'phrase';
+
+/** Options for {@link OxyServicesIdentityMixin.rotateKey}. */
+export interface RotateKeyOptions {
+  /**
+   * How to prove control of the CURRENT key:
+   *  - `'device'`: sign with the on-device SecureStore key (native-only).
+   *  - `'phrase'`: re-derive the current key from the entered recovery `phrase`
+   *    and sign with it. This works even when the device holds NO SecureStore
+   *    copy of the key — it is how the LAST remaining credential is replaced.
+   */
+  proof: RotateKeyProof;
+  /** The CURRENT identity's recovery phrase. Required when `proof: 'phrase'`. */
+  phrase?: string;
+  /**
+   * When true, all OTHER active sessions are revoked after a successful
+   * rotation (the rotating device stays signed in). Use it when the old key is
+   * presumed compromised.
+   */
+  signOutEverywhere?: boolean;
+  /**
+   * A pre-derived NEW identity to rotate to (from
+   * {@link RecoveryPhraseService.derivePendingIdentity}). Pass it when the UI
+   * derived + SHOWED the new phrase to the user BEFORE committing, so the SAME
+   * identity is the one rotated in. When omitted, a fresh identity is derived
+   * internally and its phrase is returned in the result.
+   */
+  pendingIdentity?: PendingIdentityResult;
+}
+
+/** Result of a successful key rotation. */
+export interface RotateKeyResult {
+  /** The account's new (rotated) public key. */
+  newPublicKey: string;
+  /**
+   * The NEW identity's recovery phrase. It MUST be surfaced to the user so they
+   * can back up the rotated key — if lost, the new identity is unrecoverable.
+   */
+  newPhrase: string;
+  /** The recovery phrase split into its individual words. */
+  words: string[];
+  /**
+   * Present (and `true`) only when the server rotated successfully but the new
+   * key could NOT be persisted on-device. The account key IS the new one
+   * server-side, so the user must re-import it from `newPhrase`; the caller
+   * should surface a recovery prompt. Omitted on full success.
+   */
+  localPersistFailed?: true;
+}
+
 /**
  * Derive a user's Oxy DID from their stable account id.
  * `did:web:oxy.so:u:<userId>`.
@@ -254,6 +311,199 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
+    /**
+     * Rotate the account's identity key: derive a brand-new keypair, prove
+     * control of the CURRENT key, and have the server ATOMICALLY replace the old
+     * key with the new one.
+     *
+     * The rotation is an atomic REPLACE on the server (never remove-then-add), so
+     * it never passes through a zero-auth-method state and is independent of the
+     * unlink guards. Because control of the current key is PROVEN (from
+     * SecureStore in `'device'` mode, or a recovery-phrase re-derivation in
+     * `'phrase'` mode), even the LAST remaining credential can be replaced.
+     *
+     * Ordering (safety-critical): the new key is persisted on-device ONLY AFTER
+     * the server confirms the swap. Persisting earlier would clobber the local
+     * key while the server still trusts the old one, locking the device out.
+     *
+     * Ambiguous-network-failure guard: if the `complete` response is lost
+     * (request sent, no reply), the swap may already have applied server-side.
+     * Before surfacing the error we reconcile against the derived DID document —
+     * if it already advertises the new key, the rotation is treated as done.
+     *
+     * NOTE: the UI is responsible for showing `newPhrase` to the user. For a
+     * "show-phrase-first" flow, derive the identity up front via
+     * {@link RecoveryPhraseService.derivePendingIdentity}, display it, then pass
+     * it back as `options.pendingIdentity` so the SAME identity is committed.
+     *
+     * @throws when no user is authenticated, when `proof: 'phrase'` is given
+     *   without a `phrase`, when `proof: 'device'` runs with no on-device key,
+     *   or when the rotation does not complete.
+     */
+    async rotateKey(options: RotateKeyOptions): Promise<RotateKeyResult> {
+      try {
+        const userId = this.getCurrentUserId();
+        if (!userId) {
+          throw new Error('No authenticated user — sign in before rotating your key.');
+        }
+
+        // 1. The NEW identity (in memory only). The UI may pre-derive + pre-show
+        //    it and pass it back here so the phrase shown === the phrase committed.
+        const pending = options.pendingIdentity ?? (await RecoveryPhraseService.derivePendingIdentity());
+        const newPublicKey = pending.publicKey;
+
+        // 2. Resolve the OLD signing capability from the chosen proof mode.
+        let oldPublicKey: string;
+        let signWithOldKey: (message: string) => Promise<string>;
+        if (options.proof === 'phrase') {
+          const phrase = options.phrase?.trim();
+          if (!phrase) {
+            throw new Error('A recovery phrase is required for phrase-proof rotation.');
+          }
+          const oldPrivateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(phrase);
+          oldPublicKey = KeyManager.derivePublicKey(oldPrivateKey);
+          signWithOldKey = (message) => signMessage(message, oldPrivateKey);
+        } else {
+          const currentPublicKey = await KeyManager.getPublicKey();
+          if (!currentPublicKey) {
+            throw new Error('No on-device identity found. Use the recovery-phrase option to rotate your key.');
+          }
+          oldPublicKey = currentPublicKey;
+          signWithOldKey = (message) => SignatureService.sign(message);
+        }
+
+        // 3. Request a single-use rotate_key challenge (bearer).
+        const { challenge } = await this.makeRequest<RotateKeyChallengeResponse>(
+          'POST',
+          '/auth/rotate/challenge',
+          undefined,
+          { cache: false },
+        );
+
+        // 4. Sign the rotation proofs. The OLD key proves control of the key being
+        //    replaced; the NEW key proves possession of the key being rotated in
+        //    (so the server never accepts a re-encoding of a key the caller does
+        //    not control). Both signed byte strings MUST match the server's
+        //    reconstruction exactly (this key order). The old key is canonicalized
+        //    so legacy compressed encodings in Mongo still verify.
+        const timestamp = Date.now();
+        const canonicalOldPublicKey = KeyManager.canonicalPublicKey(oldPublicKey);
+        const message = JSON.stringify({
+          action: 'rotate_key',
+          userId,
+          oldPublicKey: canonicalOldPublicKey,
+          newPublicKey,
+          challenge,
+          timestamp,
+        });
+        const signature = await signWithOldKey(message);
+        const newKeyMessage = JSON.stringify({
+          action: 'rotate_key_new',
+          userId,
+          newPublicKey,
+          challenge,
+          timestamp,
+        });
+        const newKeyProof = await signMessage(newKeyMessage, pending.privateKey);
+
+        // 5. Complete the rotation. On an AMBIGUOUS failure, reconcile against the
+        //    DID before deciding the rotation failed.
+        let applied = false;
+        try {
+          const result = await this.makeRequest<RotateKeyCompleteResponse>(
+            'POST',
+            '/auth/rotate/complete',
+            {
+              newPublicKey,
+              challenge,
+              signature,
+              newKeyProof,
+              timestamp,
+              ...(options.signOutEverywhere ? { signOutEverywhere: true } : {}),
+            },
+            { cache: false },
+          );
+          applied = result.success && result.publicKey.toLowerCase() === newPublicKey.toLowerCase();
+        } catch (error) {
+          const reconciled = await this._rotationAlreadyApplied(userId, newPublicKey);
+          if (!reconciled) {
+            throw error;
+          }
+          applied = true;
+        }
+
+        if (!applied) {
+          throw new Error('Key rotation did not complete — your previous key is unchanged.');
+        }
+
+        // 6. ONLY after the server confirms the swap, persist the new key locally,
+        //    overwriting the old one. `importKeyPair({ overwrite: true })` uses the
+        //    atomic persist path (backs the previous key up first). Native-only —
+        //    on web the key never lived in SecureStore, so there is nothing to
+        //    persist locally.
+        //
+        //    If this local write fails the server key is ALREADY the new one, so
+        //    we must NOT throw and swallow the phrase — the caller needs it to
+        //    re-import the now-live key. Surface the result with
+        //    `localPersistFailed: true` (mirrors the pendingIdentity
+        //    show-phrase-first path, where the caller already holds the phrase).
+        let localPersistFailed = false;
+        if (!isWeb()) {
+          try {
+            await KeyManager.importKeyPair(pending.privateKey, { overwrite: true });
+          } catch (persistError) {
+            localPersistFailed = true;
+            logger.warn(
+              'Key rotated on the server but persisting the new key on-device failed; returning the new phrase so it can be re-imported.',
+              { component: 'OxyServices.identity', method: 'rotateKey' },
+              persistError,
+            );
+          }
+        }
+
+        this._invalidateIdentityCaches(userId);
+
+        return localPersistFailed
+          ? { newPublicKey, newPhrase: pending.phrase, words: pending.words, localPersistFailed: true }
+          : { newPublicKey, newPhrase: pending.phrase, words: pending.words };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Reconciliation probe for the rotation ambiguous-failure guard: fetch the
+     * account's derived DID document (uncached) and report whether it already
+     * advertises `newPublicKey` as a verification method — i.e. whether the swap
+     * already landed server-side. A failed probe returns `false` (unconfirmed),
+     * so the caller surfaces the original network error.
+     *
+     * Uses the DID document rather than `GET /auth/methods` because the latter
+     * intentionally does NOT expose raw public keys, whereas the DID's
+     * `verificationMethod[].publicKeyHex` is derived live from the account's
+     * current key — so it reflects a completed rotation immediately.
+     *
+     * Internal helper (leading underscore); public rather than `private` for the
+     * same TS4094 reason as {@link _invalidateIdentityCaches}.
+     */
+    async _rotationAlreadyApplied(userId: string, newPublicKey: string): Promise<boolean> {
+      return this.makeRequest<DidDocument>(
+        'GET',
+        `/u/${encodeURIComponent(userId)}/did.json`,
+        undefined,
+        { cache: false },
+      )
+        .then((doc) =>
+          doc.verificationMethod.some(
+            (vm) =>
+              'publicKeyHex' in vm &&
+              typeof vm.publicKeyHex === 'string' &&
+              vm.publicKeyHex.toLowerCase() === newPublicKey.toLowerCase(),
+          ),
+        )
+        .catch(() => false);
+    }
+
     /**
      * Sign a record with the on-device identity key, WITHOUT publishing it.
      * The subject is the current user's DID. NATIVE-ONLY (requires a stored