@oxy.so/core 1.0.0

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

@@ -0,0 +1,341 @@
+/**
+ * User-Node Mixin tests (self-sovereign identity layer — Fase 5 user nodes).
+ *
+ * Stubs `makeRequest` so the tests run with no network, then asserts:
+ *  - `registerNode` fetches the caller's chain head (uncached), signs a
+ *    self-issued v2 `type:'node'` envelope (record `{ endpoint, nodePublicKey,
+ *    mode }`, seq=head+1, prev=head id, collection `app.oxy.node`, rkey `self`),
+ *    POSTs it to the EXISTING `/identity/records` path, sweeps the node +
+ *    `/users/me` GET caches, then returns the freshly-read status. `mode`
+ *    defaults to `pull`; an explicit `mode` is forwarded; genesis coords apply
+ *    when there is no head. It is NATIVE-ONLY: a signing failure (no on-device
+ *    identity) propagates, and no-auth throws before any network. It does NOT
+ *    sweep when the POST fails, and throws when the node fails to materialize.
+ *  - `getMyNode` shapes the cached GET `/nodes/me` and unwraps `.node` (or null).
+ *  - `removeMyNode` DELETEs `/nodes/me`, maps `{success}`→`{revoked}`, and sweeps.
+ *  - `provisionManagedVault` POSTs `/nodes/managed`, returns `.node`, and sweeps.
+ *  - `notifyNodeIngest` POSTs the URL-encoded hint path and resolves void.
+ *
+ * The write tests mock `SignatureService.signRecordV2` (asserting the exact
+ * record + chain coords) so they isolate the SDK's request shaping from native
+ * key storage — mirroring the civic mixin tests.
+ */
+
+import type { SignedRecordEnvelope } from '@oxy.so/contracts';
+import { OxyServices } from '../../OxyServices';
+import { SignatureService } from '../../crypto/signatureService';
+import type { UserNodeStatus } from '../OxyServices.nodes';
+
+const NODE_PUBLIC_KEY = `04${'ab'.repeat(63)}`; // 128 hex chars (uncompressed secp256k1)
+
+const sampleNode: UserNodeStatus = {
+  endpoint: 'https://node.example.com',
+  nodePublicKey: NODE_PUBLIC_KEY,
+  mode: 'pull',
+  managed: false,
+  controller: 'self',
+  status: 'active',
+  createdAt: '2026-06-27T00:00:00.000Z',
+  updatedAt: '2026-06-27T00:00:00.000Z',
+};
+
+describe('OxyServices.nodes', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+    jest.spyOn(oxy, 'getCurrentUserId').mockReturnValue('user-123');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('registerNode', () => {
+    const signedEnvelope: SignedRecordEnvelope = {
+      version: 2,
+      type: 'node',
+      subject: 'did:web:oxy.so:u:user-123',
+      issuer: 'did:web:oxy.so:u:user-123',
+      record: { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+      issuedAt: 1700000000000,
+      seq: 4,
+      prev: 'rec-3',
+      collection: 'app.oxy.node',
+      rkey: 'self',
+      publicKey: 'pub',
+      alg: 'ES256K-DER-SHA256',
+      signature: 'sig',
+    };
+
+    it('signs a v2 node record on the caller chain, POSTs /identity/records, sweeps, and returns the status', async () => {
+      const signV2Spy = jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      // 1st makeRequest = chain head; 2nd = POST /identity/records; 3rd = GET /nodes/me.
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      const result = await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+        mode: 'pull',
+      });
+
+      // Fetched the caller's chain head first (uncached).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        1,
+        'GET',
+        '/identity/records/user-123/chain/head',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      // Signed a self-issued v2 `node` record: subject=caller DID, exact record,
+      // seq=head+1, prev=head id, collection app.oxy.node, rkey self.
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+        { seq: 4, prev: 'rec-3', collection: 'app.oxy.node', rkey: 'self' },
+      );
+      // Published via the EXISTING /identity/records path (NOT a bespoke endpoint).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        2,
+        'POST',
+        '/identity/records',
+        signedEnvelope,
+        expect.objectContaining({ cache: false }),
+      );
+      // Re-read the freshly-materialized status (cached GET /nodes/me).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        3,
+        'GET',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: true }),
+      );
+      // Swept the node + /users/me GET caches after the publish.
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+      expect(result).toEqual(sampleNode);
+    });
+
+    it('forwards an explicit push mode in the signed record', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+        mode: 'push',
+      });
+
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'push' },
+        { seq: 4, prev: 'rec-3', collection: 'app.oxy.node', rkey: 'self' },
+      );
+    });
+
+    it('defaults mode to pull and uses genesis coords when there is no chain head', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: null, seq: -1, recordCount: 0 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+      });
+
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+        { seq: 0, prev: null, collection: 'app.oxy.node', rkey: 'self' },
+      );
+    });
+
+    it('throws when no user is authenticated (before any network)', async () => {
+      jest.spyOn(oxy, 'getCurrentUserId').mockReturnValue(null);
+      const signV2Spy = jest.spyOn(SignatureService, 'signRecordV2');
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/No authenticated user/);
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+      expect(signV2Spy).not.toHaveBeenCalled();
+    });
+
+    it('propagates a signing failure (native-only: no on-device identity)', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockRejectedValue(new Error('No identity found. Please create or import an identity first.'));
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 });
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/No identity found/);
+      // Only the chain-head read happened; no publish, no sweep.
+      expect(signV2Spy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+
+    it('does NOT sweep caches when the publish POST fails', async () => {
+      jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockRejectedValueOnce(new Error('Signed record rejected: chain_fork'));
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+
+    it('throws when the node was stored on the chain but not materialized', async () => {
+      jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: null });
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/could not be materialized/);
+    });
+  });
+
+  describe('getMyNode', () => {
+    it('GETs /nodes/me (cached) and unwraps the node', async () => {
+      makeRequestSpy.mockResolvedValue({ node: sampleNode });
+
+      const result = await oxy.getMyNode();
+
+      expect(result).toEqual(sampleNode);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: true }),
+      );
+    });
+
+    it('returns null when the caller has no node', async () => {
+      makeRequestSpy.mockResolvedValue({ node: null });
+      await expect(oxy.getMyNode()).resolves.toBeNull();
+    });
+
+    it('rejects on a transport failure', async () => {
+      makeRequestSpy.mockRejectedValue(new Error('network down'));
+      await expect(oxy.getMyNode()).rejects.toThrow();
+    });
+  });
+
+  describe('removeMyNode', () => {
+    it('DELETEs /nodes/me, maps success→revoked, and sweeps caches', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValue({ success: true });
+
+      const result = await oxy.removeMyNode();
+
+      expect(result).toEqual({ revoked: true });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'DELETE',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+    });
+
+    it('does NOT sweep caches when the DELETE fails', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockRejectedValue(new Error('No active node registration to revoke'));
+
+      await expect(oxy.removeMyNode()).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('provisionManagedVault', () => {
+    it('POSTs /nodes/managed, returns the node, and sweeps caches', async () => {
+      const managedNode: UserNodeStatus = {
+        ...sampleNode,
+        managed: true,
+        controller: 'oxy',
+      };
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValue({ node: managedNode });
+
+      const result = await oxy.provisionManagedVault();
+
+      expect(result).toEqual(managedNode);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/managed',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+    });
+
+    it('does NOT sweep caches when provisioning fails', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockRejectedValue(new Error('Managed vaults are not available right now'));
+
+      await expect(oxy.provisionManagedVault()).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('notifyNodeIngest', () => {
+    it('POSTs the ingest-notify hint and resolves void', async () => {
+      makeRequestSpy.mockResolvedValue({ accepted: true });
+
+      await expect(oxy.notifyNodeIngest('user-9')).resolves.toBeUndefined();
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/ingest/notify/user-9',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('URL-encodes the userId path segment', async () => {
+      makeRequestSpy.mockResolvedValue({ accepted: true });
+      await oxy.notifyNodeIngest('a/b');
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/ingest/notify/a%2Fb',
+        undefined,
+        expect.anything(),
+      );
+    });
+
+    it('rejects on a transport failure', async () => {
+      makeRequestSpy.mockRejectedValue(new Error('network down'));
+      await expect(oxy.notifyNodeIngest('user-9')).rejects.toThrow();
+    });
+  });
+});

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

@@ -0,0 +1,276 @@
+/**
+ * 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 { generateSecp256k1KeyPair } from '@oxy.so/protocol/secp256k1';
+import type { DidDocument } from '@oxy.so/contracts';
+import * as protocol from '@oxy.so/protocol';
+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 oldKeyPair = generateSecp256k1KeyPair();
+const newKeyPair = generateSecp256k1KeyPair();
+const OLD_PUBLIC = oldKeyPair.publicKey;
+const NEW_PUBLIC = newKeyPair.publicKey;
+const NEW_PRIVATE = newKeyPair.privateKey;
+
+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();
+    });
+  });
+});