@oxyhq/core 12.2.0 → 12.3.0

package/src/mixins/OxyServices.identityBackup.ts

@@ -0,0 +1,237 @@
+/**
+ * Encrypted off-device identity backup mixin (b3 Feature 1).
+ *
+ * Lets a self-custody identity store an ENCRYPTED copy of its key off-device so
+ * a lost/wiped device can be recovered from the recovery phrase alone — while the
+ * platform never sees the phrase, the derived key, or the plaintext private key.
+ *
+ * Key schedule (from the recovery phrase; see
+ * {@link RecoveryPhraseService.deriveBackupMaterial}):
+ *   seed      = bip39.mnemonicToSeed(phrase)                    // 64 bytes, UNCHANGED
+ *   backupKey = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-encryption-key')
+ *   lookupId  = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-lookup-id')   // hex
+ *
+ * The two derivations require the FULL seed, so a device compromise that leaks
+ * only the raw 32-byte private key can neither locate nor decrypt the backup.
+ *
+ * Wire shapes come from `@oxyhq/contracts` (`EncryptedBackupEnvelope`,
+ * `BackupUploadRequest`, `BackupStatusResponse`) — the API validates its
+ * request/response against the same schemas, so producer and consumer cannot
+ * drift.
+ *
+ * Encryption/derivation are cross-platform (pure `@noble/*`), but persisting a
+ * restored key is NATIVE-ONLY: `restoreFromEncryptedBackup` ends in
+ * `KeyManager.importKeyPair`, which throws on web (SecureStore does not exist
+ * there) — decryption still succeeds, only the local write is native-only.
+ */
+import type {
+  BackupStatusResponse,
+  BackupUploadRequest,
+  EncryptedBackupEnvelope,
+} from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { KeyManager, IdentityAlreadyExistsError } from '../crypto/keyManager';
+import { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from '../crypto/recoveryPhrase';
+import { encryptAead, decryptAead } from '../crypto/aead';
+
+/** Envelope/KDF version — bump only on a breaking scheme change. */
+const BACKUP_ENVELOPE_VERSION = 1;
+/** The AEAD the backup is sealed with. Pinned so a mismatched decryptor fails loudly. */
+const BACKUP_ALGORITHM = 'xchacha20poly1305' as const;
+/**
+ * Length (hex chars) of the public-key HINT stored/echoed with a backup — enough
+ * to let the owner recognise WHICH identity a backup belongs to, but only a
+ * prefix (the full key is public anyway; a prefix keeps the record minimal).
+ */
+const PUBLIC_KEY_HINT_LENGTH = 16;
+
+/** The decrypted backup payload. */
+interface BackupPayload {
+  privateKey: string;
+  publicKey: string;
+  createdAt: string;
+}
+
+/** Encode bytes as lowercase hex (cross-platform, no Buffer dependency). */
+function toHex(bytes: Uint8Array): string {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 1) {
+    out += bytes[i].toString(16).padStart(2, '0');
+  }
+  return out;
+}
+
+/** Decode a lowercase/uppercase hex string to bytes. Throws on malformed input. */
+function fromHex(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) {
+    throw new Error('Malformed hex in encrypted backup envelope.');
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i += 1) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/**
+ * The AEAD associated data binds the ciphertext to its `{version, publicKeyHint}`
+ * context: the exact bytes must be reproduced at decrypt time, so a mismatched
+ * version or hint (e.g. an envelope re-stamped by a tamperer) fails the
+ * Poly1305 check. Deterministic: both sides build the SAME object literal, so
+ * `JSON.stringify` yields identical bytes.
+ */
+function buildBackupAad(version: number, publicKeyHint: string): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify({ version, publicKeyHint }));
+}
+
+export function OxyServicesIdentityBackupMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Derive the backup key material from the recovery phrase, encrypt the
+     * identity's `{privateKey, publicKey, createdAt}` with it, and upload the
+     * ciphertext + raw `lookupId` (`POST /identity/backup`, bearer). The server
+     * stores only `sha256(lookupId)` + the ciphertext. Idempotent per user: a
+     * re-upload REPLACES the prior backup (upsert by user id).
+     *
+     * The identity is derived from the PHRASE (not read from SecureStore), so
+     * this works cross-platform and does not require an on-device key.
+     *
+     * @param phrase - The identity's BIP-39 recovery phrase.
+     * @returns The post-write backup status (`{ exists: true, publicKeyHint, createdAt }`).
+     */
+    async createEncryptedBackup(phrase: string): Promise<BackupStatusResponse> {
+      try {
+        const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
+        const privateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(phrase);
+        const publicKey = KeyManager.derivePublicKey(privateKey);
+        const createdAt = new Date().toISOString();
+        const publicKeyHint = publicKey.slice(0, PUBLIC_KEY_HINT_LENGTH);
+
+        const payload: BackupPayload = { privateKey, publicKey, createdAt };
+        const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+        const aad = buildBackupAad(BACKUP_ENVELOPE_VERSION, publicKeyHint);
+        const { nonce, ciphertext } = encryptAead(backupKey, plaintext, aad);
+
+        const body: BackupUploadRequest = {
+          version: BACKUP_ENVELOPE_VERSION,
+          algorithm: BACKUP_ALGORITHM,
+          kdfInfo: BACKUP_KDF_ENCRYPTION_INFO,
+          nonce: toHex(nonce),
+          ciphertext: toHex(ciphertext),
+          publicKeyHint,
+          createdAt,
+          lookupId,
+        };
+
+        return await this.makeRequest<BackupStatusResponse>(
+          'POST',
+          '/identity/backup',
+          body,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Whether the authenticated user has a stored encrypted backup, plus the
+     * non-sensitive hint + timestamp when one exists (`GET /identity/backup/status`,
+     * bearer). Returns no ciphertext and no locator.
+     */
+    async getBackupStatus(): Promise<BackupStatusResponse> {
+      try {
+        return await this.makeRequest<BackupStatusResponse>(
+          'GET',
+          '/identity/backup/status',
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Delete the authenticated user's stored backup (`DELETE /identity/backup`,
+     * bearer). Idempotent — deleting a non-existent backup still succeeds.
+     */
+    async deleteBackup(): Promise<{ success: boolean }> {
+      try {
+        return await this.makeRequest<{ success: boolean }>(
+          'DELETE',
+          '/identity/backup',
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Restore an identity from its encrypted off-device backup using ONLY the
+     * recovery phrase: re-derive `{backupKey, lookupId}`, fetch the envelope by
+     * `lookupId` (`GET /identity/backup/:lookupId`, PUBLIC — the 256-bit locator
+     * is the protection), decrypt + authenticate locally, then persist the key.
+     *
+     * NATIVE-ONLY persistence: `KeyManager.importKeyPair` throws on web. It also
+     * refuses to clobber a DIFFERENT existing on-device identity unless
+     * `overwrite: true` — the {@link import('../crypto/keyManager').IdentityAlreadyExistsError}
+     * propagates to the caller (never swallowed) so the UI can confirm before
+     * overwriting.
+     *
+     * @param phrase - The identity's BIP-39 recovery phrase.
+     * @param options.overwrite - Replace a different existing on-device identity.
+     * @returns The restored identity's public key.
+     * @throws if the phrase is invalid, no backup exists (404), the ciphertext
+     *   fails authentication (tamper), or an existing identity blocks the import.
+     */
+    async restoreFromEncryptedBackup(
+      phrase: string,
+      options?: { overwrite?: boolean },
+    ): Promise<string> {
+      try {
+        const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
+
+        const envelope = await this.makeRequest<EncryptedBackupEnvelope>(
+          'GET',
+          `/identity/backup/${encodeURIComponent(lookupId)}`,
+          undefined,
+          { cache: false },
+        );
+
+        if (envelope.algorithm !== BACKUP_ALGORITHM) {
+          throw new Error(`Unsupported backup algorithm: ${envelope.algorithm}`);
+        }
+
+        const aad = buildBackupAad(envelope.version, envelope.publicKeyHint);
+        const plaintext = decryptAead(
+          backupKey,
+          fromHex(envelope.nonce),
+          fromHex(envelope.ciphertext),
+          aad,
+        );
+        const payload = JSON.parse(new TextDecoder().decode(plaintext)) as BackupPayload;
+
+        // Persist the recovered key. Native-only; refuses to clobber a different
+        // identity unless overwrite — the IdentityAlreadyExistsError propagates.
+        return await KeyManager.importKeyPair(payload.privateKey, {
+          overwrite: options?.overwrite === true,
+        });
+      } catch (error) {
+        // Preserve the typed "an identity already exists" signal so the caller
+        // can prompt for overwrite. `handleError` would flatten it to a generic
+        // Error and lose that discrimination.
+        if (error instanceof IdentityAlreadyExistsError) {
+          throw error;
+        }
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/OxyServices.user.ts

@@ -31,6 +31,33 @@ import { extractErrorStatus } from '../utils/errorUtils';
  */
 const USERS_BY_IDS_CHUNK_SIZE = 100;
 
+/**
+ * Maximum number of ids sent per `POST /users/follow-status/bulk` request.
+ * Matches the server-side `MAX_BULK_FOLLOW` cap; larger inputs are split into
+ * multiple chunked calls whose result maps are merged.
+ */
+const FOLLOW_STATUS_CHUNK_SIZE = 200;
+
+/**
+ * Response of the single follow/unfollow toggle route
+ * (`POST /users/:id/follow` and `DELETE /users/:id/follow`). The route reports a
+ * status message, which side of the toggle was applied, and the post-write
+ * follower/following counts for the affected users.
+ */
+export interface FollowMutationResult {
+  /** Human-readable status message. */
+  message: string;
+  /** Which side of the toggle was applied, when reported by the route. */
+  action?: 'follow' | 'unfollow';
+  /** Post-write counts, when reported by the route. */
+  counts?: {
+    /** The target user's follower count after the write. */
+    followers: number;
+    /** The viewer's following count after the write. */
+    following: number;
+  };
+}
+
 /** Per-user outcome returned by `POST /users/follow/bulk`. */
 export interface BulkFollowEntry {
   /** The user ID that was processed. */
@@ -679,9 +706,9 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * UI (the "follow resets after navigating away and back" bug).
      * `clearCacheEntry` deletes every identity-scoped variant of the key.
      */
-    async followUser(userId: string): Promise<{ success: boolean; message: string }> {
+    async followUser(userId: string): Promise<FollowMutationResult> {
       try {
-        const result = await this.makeRequest<{ success: boolean; message: string }>('POST', `/users/${userId}/follow`, undefined, { cache: false });
+        const result = await this.makeRequest<FollowMutationResult>('POST', `/users/${userId}/follow`, undefined, { cache: false });
         this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
         // The follow changed the viewer's graph — bust the cached consolidated
         // `GET /users/me/graph` so the next read reflects the new following/
@@ -748,9 +775,9 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     /**
      * Unfollow a user
      */
-    async unfollowUser(userId: string): Promise<{ success: boolean; message: string }> {
+    async unfollowUser(userId: string): Promise<FollowMutationResult> {
       try {
-        const result = await this.makeRequest<{ success: boolean; message: string }>('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
+        const result = await this.makeRequest<FollowMutationResult>('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
         // Bust the cached follow-status so a remount reads fresh truth (see `followUser`).
         this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
         // The unfollow changed the viewer's graph — bust the consolidated cache.
@@ -775,6 +802,57 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * Resolve the viewer's follow status for MANY users in one round-trip per
+     * chunk. Built for list UIs (a page of `FollowButton`s) that would otherwise
+     * fire one `getFollowStatus` per button (the classic N+1).
+     *
+     * Ids are deduplicated and validated (empty/blank ids dropped), split into
+     * chunks of {@link FOLLOW_STATUS_CHUNK_SIZE} (the server's bulk cap), and
+     * POSTed to `/users/follow-status/bulk` as `{ userIds }`. The per-chunk
+     * `{ statuses }` maps are merged into one `Record<string, boolean>` covering
+     * every requested id — ids the viewer does not follow come back `false`.
+     *
+     * Uncached (`{ cache: false }`): the UI store owns follow-status freshness
+     * and writes optimistically on every mutation, so an SDK cache here would
+     * serve a stale status right after a follow/unfollow. An empty/whitespace-
+     * only input resolves immediately with `{}` and performs no network call.
+     */
+    async getFollowStatuses(userIds: string[]): Promise<Record<string, boolean>> {
+      const uniqueIds = Array.from(
+        new Set(userIds.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)),
+      );
+      if (uniqueIds.length === 0) {
+        return {};
+      }
+
+      const chunks: string[][] = [];
+      for (let i = 0; i < uniqueIds.length; i += FOLLOW_STATUS_CHUNK_SIZE) {
+        chunks.push(uniqueIds.slice(i, i + FOLLOW_STATUS_CHUNK_SIZE));
+      }
+
+      try {
+        const responses = await Promise.all(
+          chunks.map((chunk) =>
+            this.makeRequest<{ statuses: Record<string, boolean> }>(
+              'POST',
+              '/users/follow-status/bulk',
+              { userIds: chunk },
+              { cache: false },
+            ),
+          ),
+        );
+
+        const merged: Record<string, boolean> = {};
+        for (const response of responses) {
+          Object.assign(merged, response?.statuses ?? {});
+        }
+        return merged;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Get user followers
      */

package/src/mixins/__tests__/OxyServices.rotateKey.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Key-rotation mixin tests (b3 Feature 3).
+ *
+ * Cover the client orchestration of `oxy.identity.rotateKey(...)`:
+ *  - the EXACT signed rotation payload (must match the server's reconstruction
+ *    byte-for-byte);
+ *  - device-proof signs with the on-device key; phrase-proof re-derives and
+ *    signs with the OLD key (proving the last credential can be replaced);
+ *  - BOTH proofs are sent: the OLD key signs `rotate_key`, the NEW key signs the
+ *    `rotate_key_new` proof-of-possession;
+ *  - the safety ordering (local key persisted ONLY after server confirmation);
+ *  - the local-persist failure path still surfaces the new phrase;
+ *  - the ambiguous-network-failure reconciliation against the DID document.
+ *
+ * `makeRequest` is stubbed so the tests run with no network. The real
+ * secp256k1 signing runs in the phrase-proof test so we can cryptographically
+ * assert which key produced each signature.
+ */
+
+import type { DidDocument } from '@oxyhq/contracts';
+import * as protocol from '@oxyhq/protocol';
+import { ec as EC } from 'elliptic';
+import { OxyServices } from '../../OxyServices';
+import { KeyManager } from '../../crypto/keyManager';
+import { SignatureService } from '../../crypto/signatureService';
+import { RecoveryPhraseService } from '../../crypto/recoveryPhrase';
+import { setPlatformOS } from '../../utils/platform';
+
+const ec = new EC('secp256k1');
+const oldKeyPair = ec.genKeyPair();
+const newKeyPair = ec.genKeyPair();
+const OLD_PUBLIC = oldKeyPair.getPublic('hex');
+const NEW_PUBLIC = newKeyPair.getPublic('hex');
+const NEW_PRIVATE = newKeyPair.getPrivate('hex');
+
+const pendingFixture = {
+  phrase: 'alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima',
+  words: ['alpha', 'bravo', 'charlie', 'delta', 'echo', 'foxtrot', 'golf', 'hotel', 'india', 'juliet', 'kilo', 'lima'],
+  privateKey: NEW_PRIVATE,
+  publicKey: NEW_PUBLIC,
+};
+
+function didDocWithKey(publicKeyHex: string): DidDocument {
+  return {
+    '@context': ['https://www.w3.org/ns/did/v1'],
+    id: 'did:web:oxy.so:u:user-123',
+    controller: ['did:web:oxy.so:u:user-123', 'did:web:oxy.so'],
+    verificationMethod: [
+      {
+        id: 'did:web:oxy.so:u:user-123#key-1',
+        type: 'EcdsaSecp256k1VerificationKey2019',
+        controller: 'did:web:oxy.so:u:user-123',
+        publicKeyHex,
+      },
+    ],
+    authentication: ['did:web:oxy.so:u:user-123#key-1'],
+    assertionMethod: ['did:web:oxy.so:u:user-123#key-1'],
+    alsoKnownAs: [],
+    service: [],
+  };
+}
+
+describe('OxyServices.rotateKey', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+  let clearEntrySpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    setPlatformOS('ios'); // native → the new key is persisted locally after success
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+    jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+    clearEntrySpy = jest.spyOn(oxy, 'clearCacheEntry').mockReturnValue(undefined);
+    jest.spyOn(oxy, 'getCurrentUserId').mockReturnValue('user-123');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('device proof', () => {
+    it('signs the exact rotation payload, POSTs challenge→complete, then persists the new key locally', async () => {
+      jest.spyOn(Date, 'now').mockReturnValue(1700000000000);
+      jest.spyOn(RecoveryPhraseService, 'derivePendingIdentity').mockResolvedValue(pendingFixture);
+      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(OLD_PUBLIC);
+      const signSpy = jest.spyOn(SignatureService, 'sign').mockResolvedValue('sig-hex');
+      // The new-key proof is signed with the pending private key via protocol.signMessage.
+      const newKeySignSpy = jest.spyOn(protocol, 'signMessage').mockResolvedValue('newkeyproof-hex');
+      const importSpy = jest.spyOn(KeyManager, 'importKeyPair').mockResolvedValue(NEW_PUBLIC);
+      makeRequestSpy
+        .mockResolvedValueOnce({ challenge: 'chal-1', expiresAt: '2999-01-01T00:00:00.000Z' })
+        .mockResolvedValueOnce({ success: true, publicKey: NEW_PUBLIC, message: 'ok' });
+
+      const result = await oxy.rotateKey({ proof: 'device' });
+
+      expect(result).toEqual({ newPublicKey: NEW_PUBLIC, newPhrase: pendingFixture.phrase, words: pendingFixture.words });
+
+      // The OLD-key signed message MUST match the server's reconstruction byte-for-byte.
+      const expectedMessage = JSON.stringify({
+        action: 'rotate_key',
+        userId: 'user-123',
+        oldPublicKey: KeyManager.canonicalPublicKey(OLD_PUBLIC),
+        newPublicKey: NEW_PUBLIC,
+        challenge: 'chal-1',
+        timestamp: 1700000000000,
+      });
+      expect(signSpy).toHaveBeenCalledWith(expectedMessage);
+      // The NEW-key proof is signed with the pending private key over rotate_key_new.
+      const expectedNewKeyMessage = JSON.stringify({
+        action: 'rotate_key_new',
+        userId: 'user-123',
+        newPublicKey: NEW_PUBLIC,
+        challenge: 'chal-1',
+        timestamp: 1700000000000,
+      });
+      expect(newKeySignSpy).toHaveBeenCalledWith(expectedNewKeyMessage, NEW_PRIVATE);
+
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(1, 'POST', '/auth/rotate/challenge', undefined, expect.objectContaining({ cache: false }));
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        2,
+        'POST',
+        '/auth/rotate/complete',
+        { newPublicKey: NEW_PUBLIC, challenge: 'chal-1', signature: 'sig-hex', newKeyProof: 'newkeyproof-hex', timestamp: 1700000000000 },
+        expect.objectContaining({ cache: false }),
+      );
+
+      // Persisted ONLY after the server confirmed the swap.
+      expect(importSpy).toHaveBeenCalledWith(NEW_PRIVATE, { overwrite: true });
+      // DID + auth-method caches are swept.
+      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/u/user-123/did.json');
+      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/auth/methods');
+    });
+
+    it('forwards signOutEverywhere in the complete body', async () => {
+      jest.spyOn(RecoveryPhraseService, 'derivePendingIdentity').mockResolvedValue(pendingFixture);
+      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(OLD_PUBLIC);
+      jest.spyOn(SignatureService, 'sign').mockResolvedValue('sig-hex');
+      jest.spyOn(protocol, 'signMessage').mockResolvedValue('newkeyproof-hex');
+      jest.spyOn(KeyManager, 'importKeyPair').mockResolvedValue(NEW_PUBLIC);
+      makeRequestSpy
+        .mockResolvedValueOnce({ challenge: 'chal-1', expiresAt: '2999-01-01T00:00:00.000Z' })
+        .mockResolvedValueOnce({ success: true, publicKey: NEW_PUBLIC, message: 'ok' });
+
+      await oxy.rotateKey({ proof: 'device', signOutEverywhere: true });
+
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        2,
+        'POST',
+        '/auth/rotate/complete',
+        expect.objectContaining({ signOutEverywhere: true, newKeyProof: 'newkeyproof-hex' }),
+        expect.anything(),
+      );
+    });
+
+    it('does NOT throw and surfaces the new phrase when the local key persist fails after a server rotation', async () => {
+      jest.spyOn(RecoveryPhraseService, 'derivePendingIdentity').mockResolvedValue(pendingFixture);
+      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(OLD_PUBLIC);
+      jest.spyOn(SignatureService, 'sign').mockResolvedValue('sig-hex');
+      jest.spyOn(protocol, 'signMessage').mockResolvedValue('newkeyproof-hex');
+      // The server rotated successfully, but the on-device persist fails.
+      jest.spyOn(KeyManager, 'importKeyPair').mockRejectedValue(new Error('secure store write failed'));
+      makeRequestSpy
+        .mockResolvedValueOnce({ challenge: 'chal-1', expiresAt: '2999-01-01T00:00:00.000Z' })
+        .mockResolvedValueOnce({ success: true, publicKey: NEW_PUBLIC, message: 'ok' });
+
+      const result = await oxy.rotateKey({ proof: 'device' });
+
+      // The phrase for the now-live key is surfaced, with a failure flag — never lost.
+      expect(result).toEqual({
+        newPublicKey: NEW_PUBLIC,
+        newPhrase: pendingFixture.phrase,
+        words: pendingFixture.words,
+        localPersistFailed: true,
+      });
+      // Caches are still swept (the server key is the new one).
+      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/u/user-123/did.json');
+    });
+
+    it('throws (no network) when the device holds no identity', async () => {
+      jest.spyOn(RecoveryPhraseService, 'derivePendingIdentity').mockResolvedValue(pendingFixture);
+      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(null);
+
+      await expect(oxy.rotateKey({ proof: 'device' })).rejects.toThrow(/No on-device identity/);
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('phrase proof (replace the LAST credential)', () => {
+    it('re-derives the CURRENT key from the entered phrase and signs the proof with it', async () => {
+      // A real "current" identity whose phrase the user re-enters, and a real new one.
+      const current = await RecoveryPhraseService.derivePendingIdentity();
+      const next = await RecoveryPhraseService.derivePendingIdentity();
+      jest.spyOn(RecoveryPhraseService, 'derivePendingIdentity').mockResolvedValue(next);
+      jest.spyOn(KeyManager, 'importKeyPair').mockResolvedValue(next.publicKey);
+
+      let completeBody: Record<string, unknown> | undefined;
+      makeRequestSpy.mockImplementation((_m: string, path: string, body?: unknown) => {
+        if (path === '/auth/rotate/challenge') return Promise.resolve({ challenge: 'chal-x', expiresAt: '2999-01-01T00:00:00.000Z' });
+        if (path === '/auth/rotate/complete') {
+          completeBody = body as Record<string, unknown>;
+          return Promise.resolve({ success: true, publicKey: next.publicKey, message: 'ok' });
+        }
+        return Promise.reject(new Error(`unexpected ${path}`));
+      });
+
+      const result = await oxy.rotateKey({ proof: 'phrase', phrase: current.phrase });
+      expect(result.newPublicKey).toBe(next.publicKey);
+
+      // The OLD-key signature MUST verify against the current key over the exact message.
+      const message = JSON.stringify({
+        action: 'rotate_key',
+        userId: 'user-123',
+        oldPublicKey: KeyManager.canonicalPublicKey(current.publicKey),
+        newPublicKey: next.publicKey,
+        challenge: 'chal-x',
+        timestamp: completeBody?.timestamp,
+      });
+      expect(await protocol.verifySignature(message, completeBody?.signature as string, current.publicKey)).toBe(true);
+      // …and must NOT verify against the new key (proves it was signed by the current key).
+      expect(await protocol.verifySignature(message, completeBody?.signature as string, next.publicKey)).toBe(false);
+
+      // The NEW-key proof-of-possession MUST verify against the NEW key.
+      const newKeyMessage = JSON.stringify({
+        action: 'rotate_key_new',
+        userId: 'user-123',
+        newPublicKey: next.publicKey,
+        challenge: 'chal-x',
+        timestamp: completeBody?.timestamp,
+      });
+      expect(await protocol.verifySignature(newKeyMessage, completeBody?.newKeyProof as string, next.publicKey)).toBe(true);
+      // …and must NOT verify against the old key (proves possession of the new key).
+      expect(await protocol.verifySignature(newKeyMessage, completeBody?.newKeyProof as string, current.publicKey)).toBe(false);
+    });
+
+    it('throws when proof is phrase but no phrase is supplied', async () => {
+      jest.spyOn(RecoveryPhraseService, 'derivePendingIdentity').mockResolvedValue(pendingFixture);
+      await expect(oxy.rotateKey({ proof: 'phrase' })).rejects.toThrow(/recovery phrase is required/);
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('ambiguous network failure', () => {
+    it('reconciles a lost complete-response against the DID and treats a landed swap as done', async () => {
+      jest.spyOn(RecoveryPhraseService, 'derivePendingIdentity').mockResolvedValue(pendingFixture);
+      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(OLD_PUBLIC);
+      jest.spyOn(protocol, 'signMessage').mockResolvedValue('newkeyproof-hex');
+      jest.spyOn(SignatureService, 'sign').mockResolvedValue('sig-hex');
+      const importSpy = jest.spyOn(KeyManager, 'importKeyPair').mockResolvedValue(NEW_PUBLIC);
+      makeRequestSpy
+        .mockResolvedValueOnce({ challenge: 'chal-1', expiresAt: '2999-01-01T00:00:00.000Z' })
+        .mockRejectedValueOnce(new Error('network lost'))
+        .mockResolvedValueOnce(didDocWithKey(NEW_PUBLIC)); // DID already advertises the new key
+
+      const result = await oxy.rotateKey({ proof: 'device' });
+
+      expect(result.newPublicKey).toBe(NEW_PUBLIC);
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(3, 'GET', '/u/user-123/did.json', undefined, expect.objectContaining({ cache: false }));
+      // The swap landed server-side, so the new key is persisted locally.
+      expect(importSpy).toHaveBeenCalledWith(NEW_PRIVATE, { overwrite: true });
+    });
+
+    it('surfaces the error and does NOT persist locally when the DID shows the swap did not land', async () => {
+      jest.spyOn(RecoveryPhraseService, 'derivePendingIdentity').mockResolvedValue(pendingFixture);
+      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(OLD_PUBLIC);
+      jest.spyOn(protocol, 'signMessage').mockResolvedValue('newkeyproof-hex');
+      jest.spyOn(SignatureService, 'sign').mockResolvedValue('sig-hex');
+      const importSpy = jest.spyOn(KeyManager, 'importKeyPair').mockResolvedValue(NEW_PUBLIC);
+      makeRequestSpy
+        .mockResolvedValueOnce({ challenge: 'chal-1', expiresAt: '2999-01-01T00:00:00.000Z' })
+        .mockRejectedValueOnce(new Error('network lost'))
+        .mockResolvedValueOnce(didDocWithKey(OLD_PUBLIC)); // DID still shows the OLD key
+
+      await expect(oxy.rotateKey({ proof: 'device' })).rejects.toBeDefined();
+      expect(importSpy).not.toHaveBeenCalled();
+    });
+  });
+});