@oxyhq/core 12.2.0 → 12.3.0

package/src/mixins/__tests__/getFollowStatuses.test.ts

@@ -0,0 +1,95 @@
+/**
+ * `getFollowStatuses` — batched follow-status resolution tests.
+ *
+ * The SDK method collapses N per-button `getFollowStatus` calls into one bulk
+ * `POST /users/follow-status/bulk` per chunk. It must:
+ *  - dedup + drop blank ids, and resolve to `{}` with NO network call on empty
+ *    input;
+ *  - POST `{ userIds }` uncached (`{ cache: false }`) so the UI store owns
+ *    follow-status freshness;
+ *  - chunk at the server cap (200) and MERGE the per-chunk `{ statuses }` maps
+ *    into one record covering every requested id.
+ *
+ * `makeRequest` is stubbed so the tests run with no network.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+describe('OxyServices.getFollowStatuses — batched follow status', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('returns {} and performs no network call for empty / whitespace input', async () => {
+    await expect(oxy.getFollowStatuses([])).resolves.toEqual({});
+    await expect(oxy.getFollowStatuses(['', '   '])).resolves.toEqual({});
+    expect(makeRequestSpy).not.toHaveBeenCalled();
+  });
+
+  it('POSTs { userIds } uncached and returns the statuses map', async () => {
+    makeRequestSpy.mockResolvedValueOnce({ statuses: { a: true, b: false } });
+
+    const result = await oxy.getFollowStatuses(['a', 'b']);
+
+    expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+    expect(makeRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/users/follow-status/bulk',
+      { userIds: ['a', 'b'] },
+      { cache: false },
+    );
+    expect(result).toEqual({ a: true, b: false });
+  });
+
+  it('de-duplicates ids and drops blanks before the request', async () => {
+    makeRequestSpy.mockResolvedValueOnce({ statuses: { a: true } });
+
+    await oxy.getFollowStatuses(['a', 'a', '   ', 'a']);
+
+    expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+    expect(makeRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/users/follow-status/bulk',
+      { userIds: ['a'] },
+      { cache: false },
+    );
+  });
+
+  it('chunks at 200 ids per request and merges the per-chunk maps', async () => {
+    const ids = Array.from({ length: 450 }, (_, i) => `id-${i}`);
+    makeRequestSpy.mockImplementation(
+      async (
+        _method: string,
+        _url: string,
+        data?: { userIds: string[] },
+      ): Promise<{ statuses: Record<string, boolean> }> => {
+        const statuses: Record<string, boolean> = {};
+        for (const id of data?.userIds ?? []) {
+          statuses[id] = id.endsWith('0'); // deterministic mix of true/false
+        }
+        return { statuses };
+      },
+    );
+
+    const result = await oxy.getFollowStatuses(ids);
+
+    // 450 unique ids => 200 + 200 + 50 across three POSTs.
+    expect(makeRequestSpy).toHaveBeenCalledTimes(3);
+    const chunkSizes = makeRequestSpy.mock.calls.map(
+      (call) => (call[2] as { userIds: string[] }).userIds.length,
+    );
+    expect(chunkSizes).toEqual([200, 200, 50]);
+    // Every requested id is present in the merged result.
+    expect(Object.keys(result)).toHaveLength(450);
+    expect(result['id-10']).toBe(true);
+    expect(result['id-11']).toBe(false);
+  });
+});

package/src/mixins/__tests__/identityBackup.test.ts

@@ -0,0 +1,258 @@
+/**
+ * Encrypted off-device identity backup mixin (b3 Feature 1).
+ *
+ * Exercises the full client contract with a REAL crypto round-trip (only
+ * `KeyManager.importKeyPair` — the native SecureStore write — is mocked):
+ *  - `createEncryptedBackup` derives the material, encrypts the identity, and
+ *    POSTs the envelope + raw `lookupId` (the server never sees the phrase/key).
+ *  - the uploaded envelope decrypts back to the SAME private key via
+ *    `restoreFromEncryptedBackup` (round-trip).
+ *  - any tamper (ciphertext / nonce / AAD-bound publicKeyHint) fails the
+ *    Poly1305 check → restore rejects.
+ *  - an existing on-device identity surfaces `IdentityAlreadyExistsError`
+ *    UNCHANGED (not flattened by `handleError`), and `overwrite` forwards.
+ */
+import { OxyServices } from '../../OxyServices';
+import { KeyManager, IdentityAlreadyExistsError } from '../../crypto/keyManager';
+import { RecoveryPhraseService } from '../../crypto/recoveryPhrase';
+import type { EncryptedBackupEnvelope, BackupUploadRequest } from '@oxyhq/contracts';
+
+const FIXED_PHRASE =
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+const EXPECTED_LOOKUP_ID = '8cad137ca961bfc62a2ef329869e8369777737c7c5353a8d94bb70d888c0ad0d';
+const EXPECTED_PRIVATE_KEY = '5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc1';
+
+/** Build a non-verified JWT whose payload decodes to the given claims. */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+/** A JSON `Response` returning the body verbatim (no `{ data }` wrapper). */
+function plainResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('encrypted identity backup mixin', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.clearAllMocks();
+  });
+
+  /** Read + parse the body of the Nth fetch call as the upload request. */
+  function uploadBodyFromCall(index: number): BackupUploadRequest {
+    const init = fetchMock.mock.calls[index][1];
+    return JSON.parse(String(init?.body)) as BackupUploadRequest;
+  }
+
+  it('createEncryptedBackup uploads an envelope + raw lookupId derived from the phrase', async () => {
+    fetchMock.mockResolvedValueOnce(
+      plainResponse({ exists: true, publicKeyHint: '04abc', createdAt: 'x' }),
+    );
+
+    await oxy.createEncryptedBackup(FIXED_PHRASE);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/identity/backup');
+    expect(init?.method).toBe('POST');
+
+    const body = uploadBodyFromCall(0);
+    // Envelope metadata.
+    expect(body.version).toBe(1);
+    expect(body.algorithm).toBe('xchacha20poly1305');
+    expect(body.kdfInfo).toBe('oxy-backup-encryption-key');
+    // The raw lookup id is the phrase-derived value (server will hash it).
+    expect(body.lookupId).toBe(EXPECTED_LOOKUP_ID);
+    // Hex ciphertext + 24-byte (48 hex) nonce.
+    expect(body.nonce).toMatch(/^[0-9a-f]{48}$/);
+    expect(body.ciphertext).toMatch(/^[0-9a-f]+$/);
+    // The hint is a 16-char prefix of the identity's real public key.
+    const publicKey = KeyManager.derivePublicKey(EXPECTED_PRIVATE_KEY);
+    expect(body.publicKeyHint).toBe(publicKey.slice(0, 16));
+    expect(body.publicKeyHint).toHaveLength(16);
+    // The plaintext private key NEVER appears on the wire.
+    expect(String(init?.body)).not.toContain(EXPECTED_PRIVATE_KEY);
+  });
+
+  it('round-trips: the uploaded envelope decrypts back to the SAME private key', async () => {
+    // 1) Encrypt + capture the real envelope.
+    fetchMock.mockResolvedValueOnce(
+      plainResponse({ exists: true, publicKeyHint: '04', createdAt: 'x' }),
+    );
+    await oxy.createEncryptedBackup(FIXED_PHRASE);
+    const uploaded = uploadBodyFromCall(0);
+    const envelope: EncryptedBackupEnvelope = {
+      version: uploaded.version,
+      algorithm: uploaded.algorithm,
+      kdfInfo: uploaded.kdfInfo,
+      nonce: uploaded.nonce,
+      ciphertext: uploaded.ciphertext,
+      publicKeyHint: uploaded.publicKeyHint,
+      createdAt: uploaded.createdAt,
+    };
+
+    // 2) Restore: intercept the native SecureStore write.
+    const importSpy = jest
+      .spyOn(KeyManager, 'importKeyPair')
+      .mockResolvedValue('restored-public-key');
+    fetchMock.mockResolvedValueOnce(plainResponse(envelope));
+
+    const publicKey = await oxy.restoreFromEncryptedBackup(FIXED_PHRASE);
+
+    // The GET targets the locator; import receives the decrypted private key.
+    const [url, init] = fetchMock.mock.calls[1];
+    expect(String(url)).toBe(`http://test.invalid/identity/backup/${EXPECTED_LOOKUP_ID}`);
+    expect(init?.method).toBe('GET');
+    expect(importSpy).toHaveBeenCalledWith(EXPECTED_PRIVATE_KEY, { overwrite: false });
+    expect(publicKey).toBe('restored-public-key');
+  });
+
+  it('rejects a tampered ciphertext (Poly1305 authentication fails)', async () => {
+    fetchMock.mockResolvedValueOnce(plainResponse({ exists: true }));
+    await oxy.createEncryptedBackup(FIXED_PHRASE);
+    const uploaded = uploadBodyFromCall(0);
+
+    // Flip the first ciphertext byte.
+    const firstByte = uploaded.ciphertext.slice(0, 2);
+    const flipped = (Number.parseInt(firstByte, 16) ^ 0xff).toString(16).padStart(2, '0');
+    const tampered: EncryptedBackupEnvelope = {
+      version: uploaded.version,
+      algorithm: uploaded.algorithm,
+      kdfInfo: uploaded.kdfInfo,
+      nonce: uploaded.nonce,
+      ciphertext: flipped + uploaded.ciphertext.slice(2),
+      publicKeyHint: uploaded.publicKeyHint,
+      createdAt: uploaded.createdAt,
+    };
+
+    const importSpy = jest.spyOn(KeyManager, 'importKeyPair').mockResolvedValue('x');
+    fetchMock.mockResolvedValueOnce(plainResponse(tampered));
+
+    await expect(oxy.restoreFromEncryptedBackup(FIXED_PHRASE)).rejects.toThrow();
+    expect(importSpy).not.toHaveBeenCalled();
+  });
+
+  it('rejects when the AAD-bound publicKeyHint is altered', async () => {
+    fetchMock.mockResolvedValueOnce(plainResponse({ exists: true }));
+    await oxy.createEncryptedBackup(FIXED_PHRASE);
+    const uploaded = uploadBodyFromCall(0);
+
+    const tampered: EncryptedBackupEnvelope = {
+      version: uploaded.version,
+      algorithm: uploaded.algorithm,
+      kdfInfo: uploaded.kdfInfo,
+      nonce: uploaded.nonce,
+      ciphertext: uploaded.ciphertext,
+      publicKeyHint: 'deadbeefdeadbeef', // wrong hint → AAD mismatch
+      createdAt: uploaded.createdAt,
+    };
+
+    const importSpy = jest.spyOn(KeyManager, 'importKeyPair').mockResolvedValue('x');
+    fetchMock.mockResolvedValueOnce(plainResponse(tampered));
+
+    await expect(oxy.restoreFromEncryptedBackup(FIXED_PHRASE)).rejects.toThrow();
+    expect(importSpy).not.toHaveBeenCalled();
+  });
+
+  it('rejects a mismatched nonce', async () => {
+    fetchMock.mockResolvedValueOnce(plainResponse({ exists: true }));
+    await oxy.createEncryptedBackup(FIXED_PHRASE);
+    const uploaded = uploadBodyFromCall(0);
+
+    const tampered: EncryptedBackupEnvelope = {
+      version: uploaded.version,
+      algorithm: uploaded.algorithm,
+      kdfInfo: uploaded.kdfInfo,
+      nonce: '00'.repeat(24), // wrong nonce
+      ciphertext: uploaded.ciphertext,
+      publicKeyHint: uploaded.publicKeyHint,
+      createdAt: uploaded.createdAt,
+    };
+
+    fetchMock.mockResolvedValueOnce(plainResponse(tampered));
+    await expect(oxy.restoreFromEncryptedBackup(FIXED_PHRASE)).rejects.toThrow();
+  });
+
+  it('propagates IdentityAlreadyExistsError UNCHANGED (so the caller can offer overwrite)', async () => {
+    fetchMock.mockResolvedValueOnce(plainResponse({ exists: true }));
+    await oxy.createEncryptedBackup(FIXED_PHRASE);
+    const uploaded = uploadBodyFromCall(0);
+    const envelope: EncryptedBackupEnvelope = {
+      version: uploaded.version,
+      algorithm: uploaded.algorithm,
+      kdfInfo: uploaded.kdfInfo,
+      nonce: uploaded.nonce,
+      ciphertext: uploaded.ciphertext,
+      publicKeyHint: uploaded.publicKeyHint,
+      createdAt: uploaded.createdAt,
+    };
+
+    jest
+      .spyOn(KeyManager, 'importKeyPair')
+      .mockRejectedValue(new IdentityAlreadyExistsError('04existingkey'));
+    fetchMock.mockResolvedValueOnce(plainResponse(envelope));
+
+    await expect(oxy.restoreFromEncryptedBackup(FIXED_PHRASE)).rejects.toBeInstanceOf(
+      IdentityAlreadyExistsError,
+    );
+  });
+
+  it('forwards overwrite:true to importKeyPair', async () => {
+    fetchMock.mockResolvedValueOnce(plainResponse({ exists: true }));
+    await oxy.createEncryptedBackup(FIXED_PHRASE);
+    const uploaded = uploadBodyFromCall(0);
+    const envelope: EncryptedBackupEnvelope = {
+      version: uploaded.version,
+      algorithm: uploaded.algorithm,
+      kdfInfo: uploaded.kdfInfo,
+      nonce: uploaded.nonce,
+      ciphertext: uploaded.ciphertext,
+      publicKeyHint: uploaded.publicKeyHint,
+      createdAt: uploaded.createdAt,
+    };
+
+    const importSpy = jest
+      .spyOn(KeyManager, 'importKeyPair')
+      .mockResolvedValue('restored-public-key');
+    fetchMock.mockResolvedValueOnce(plainResponse(envelope));
+
+    await oxy.restoreFromEncryptedBackup(FIXED_PHRASE, { overwrite: true });
+    expect(importSpy).toHaveBeenCalledWith(EXPECTED_PRIVATE_KEY, { overwrite: true });
+  });
+
+  it('getBackupStatus + deleteBackup hit the right endpoints', async () => {
+    fetchMock.mockResolvedValueOnce(
+      plainResponse({ exists: true, publicKeyHint: '04abc', createdAt: 'iso' }),
+    );
+    const status = await oxy.getBackupStatus();
+    expect(status).toEqual({ exists: true, publicKeyHint: '04abc', createdAt: 'iso' });
+    let [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/identity/backup/status');
+    expect(init?.method).toBe('GET');
+
+    fetchMock.mockResolvedValueOnce(plainResponse({ success: true }));
+    await expect(oxy.deleteBackup()).resolves.toEqual({ success: true });
+    [url, init] = fetchMock.mock.calls[1];
+    expect(String(url)).toBe('http://test.invalid/identity/backup');
+    expect(init?.method).toBe('DELETE');
+  });
+});

package/src/mixins/index.ts

@@ -9,6 +9,7 @@ import { OxyServicesBase } from '../OxyServices.base';
 import { OxyServicesAuthMixin } from './OxyServices.auth';
 import { OxyServicesUserMixin } from './OxyServices.user';
 import { OxyServicesIdentityMixin } from './OxyServices.identity';
+import { OxyServicesIdentityBackupMixin } from './OxyServices.identityBackup';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
 import { OxyServicesLanguageMixin } from './OxyServices.language';
 import { OxyServicesPaymentMixin } from './OxyServices.payment';
@@ -43,6 +44,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>>
@@ -98,6 +100,9 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesUserMixin,
     // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping)
     OxyServicesIdentityMixin,
+    // Encrypted off-device identity backup (b3 Feature 1): store/restore an
+    // encrypted copy of the self-custody key, keyed off the recovery phrase.
+    OxyServicesIdentityBackupMixin,
     OxyServicesPrivacyMixin,
 
     // Feature mixins

package/src/types/elliptic.d.ts

@@ -1,12 +1,20 @@
 declare module 'elliptic' {
+  export interface BN {
+    toArray(endian?: 'be' | 'le', length?: number): number[];
+    toString(base?: number): string;
+  }
+
   export interface KeyPair {
     getPrivate(enc?: 'hex' | 'array' | 'bn'): string | number[] | any;
-    getPublic(enc?: 'hex'): string;
-    getPublic(enc?: 'array'): number[];
+    getPublic(): Point;
+    getPublic(enc: 'hex'): string;
+    getPublic(enc: 'array'): number[];
     getPublic(compressed: boolean, enc?: 'hex'): string;
     getPublic(compressed: boolean, enc?: 'array'): number[];
     sign(msg: string | number[]): Signature;
     verify(msg: string | number[], signature: Signature | string | { r: string | number[]; s: string | number[] }): boolean;
+    /** ECDH: derive the shared point's x-coordinate against another party's public point. */
+    derive(pub: Point): BN;
   }
 
   export interface Signature {