@oxyhq/core 4.0.0 → 5.0.0

package/src/crypto/__tests__/signedRecord.test.ts

@@ -1,28 +1,37 @@
 /**
- * Signed-record envelope tests.
+ * Signed-record envelope tests — the DEVICE-key-bound path in `@oxyhq/core`.
  *
- * Exercises the full client-side path: `SignatureService.signRecord` builds an
- * envelope whose signature covers the canonical JSON of every field EXCEPT
- * `publicKey`/`signature`, and `SignatureService.verifyRecord` round-trips it.
- * We mock `KeyManager`'s key access with a REAL elliptic secp256k1 keypair, so
- * the signing/verification is genuine cryptography (not a stub).
+ * `SignatureService.signRecord` / `signRecordV2` read the device key from
+ * `KeyManager` and delegate the cryptography to `@oxyhq/protocol`'s
+ * `signEnvelope`. These tests prove the orchestration: an envelope built from a
+ * stored key round-trips through the protocol's `verifyEnvelopeSignature`, and
+ * tampering breaks it. The pure canonical-bytes / `computeRecordId` guards live
+ * in `@oxyhq/protocol`'s own suite.
+ *
+ * We mock `KeyManager.getPrivateKey` with a REAL elliptic secp256k1 private key,
+ * so the signing/verification is genuine cryptography (not a stub).
  */
 
 import { ec as EC } from 'elliptic';
 import type { SignedRecordEnvelope } from '@oxyhq/contracts';
+import {
+  canonicalize,
+  signedRecordSigningInput,
+  verifySignature,
+  verifyEnvelopeSignature,
+} from '@oxyhq/protocol';
 import { KeyManager } from '../keyManager';
-import { SignatureService, signedRecordSigningInput, computeRecordId } from '../signatureService';
-import { canonicalize } from '../canonicalJson';
+import { SignatureService } from '../signatureService';
 
 const ec = new EC('secp256k1');
 
-describe('SignatureService.signRecord / verifyRecord', () => {
+describe('SignatureService.signRecord / verifyEnvelopeSignature', () => {
   const keyPair = ec.genKeyPair();
   const publicKey = keyPair.getPublic('hex');
+  const privateKey = keyPair.getPrivate('hex').padStart(64, '0');
 
   beforeEach(() => {
-    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(publicKey);
-    jest.spyOn(KeyManager, 'getKeyPairObject').mockResolvedValue(keyPair);
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(privateKey);
   });
 
   afterEach(() => {
@@ -40,7 +49,7 @@ describe('SignatureService.signRecord / verifyRecord', () => {
     expect(envelope.subject).toBe(subject);
     expect(envelope.issuer).toBe(subject); // self-issued
     expect(envelope.record).toEqual(record);
-    expect(envelope.publicKey).toBe(publicKey);
+    expect(envelope.publicKey).toBe(publicKey); // derived from the stored private key
     expect(envelope.alg).toBe('ES256K-DER-SHA256');
     expect(typeof envelope.signature).toBe('string');
     expect(envelope.signature.length).toBeGreaterThan(0);
@@ -52,7 +61,7 @@ describe('SignatureService.signRecord / verifyRecord', () => {
       handle: '@nate',
       nested: { a: 1, b: [2, 3] },
     });
-    await expect(SignatureService.verifyRecord(envelope)).resolves.toBe(true);
+    await expect(verifyEnvelopeSignature(envelope)).resolves.toBe(true);
   });
 
   it('signs the canonical JSON of every field except publicKey + signature', async () => {
@@ -77,7 +86,7 @@ describe('SignatureService.signRecord / verifyRecord', () => {
 
     // The signature verifies against that exact input + the embedded key.
     await expect(
-      SignatureService.verify(expectedInput, envelope.signature, envelope.publicKey),
+      verifySignature(expectedInput, envelope.signature, envelope.publicKey),
     ).resolves.toBe(true);
   });
 
@@ -96,86 +105,41 @@ describe('SignatureService.signRecord / verifyRecord', () => {
         ...envelope,
         record: { ...envelope.record, displayName: 'Tampered' },
       };
-      await expect(SignatureService.verifyRecord(tampered)).resolves.toBe(false);
+      await expect(verifyEnvelopeSignature(tampered)).resolves.toBe(false);
     });
 
     it('rejects a changed subject', async () => {
       const tampered: SignedRecordEnvelope = { ...envelope, subject: 'did:web:oxy.so:u:evil' };
-      await expect(SignatureService.verifyRecord(tampered)).resolves.toBe(false);
+      await expect(verifyEnvelopeSignature(tampered)).resolves.toBe(false);
     });
 
     it('rejects a changed issuedAt', async () => {
       const tampered: SignedRecordEnvelope = { ...envelope, issuedAt: envelope.issuedAt + 1 };
-      await expect(SignatureService.verifyRecord(tampered)).resolves.toBe(false);
+      await expect(verifyEnvelopeSignature(tampered)).resolves.toBe(false);
     });
 
     it('rejects verification against an unrelated public key', async () => {
       const otherKey = ec.genKeyPair().getPublic('hex');
       const tampered: SignedRecordEnvelope = { ...envelope, publicKey: otherKey };
-      await expect(SignatureService.verifyRecord(tampered)).resolves.toBe(false);
+      await expect(verifyEnvelopeSignature(tampered)).resolves.toBe(false);
     });
   });
 
   it('throws when no identity is stored', async () => {
-    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(null);
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(null);
     await expect(
       SignatureService.signRecord('identity', 'did:web:oxy.so:u:u4', {}),
     ).rejects.toThrow(/No identity found/);
   });
 });
 
-/**
- * Critical regression guard: the v1 signing input MUST be byte-identical to the
- * original scheme. Every `identity`/`profile` record already in production was
- * signed over exactly these bytes, so any change to {@link signedRecordSigningInput}
- * for v1 would invalidate them all. This locks the exact canonical string.
- */
-describe('signedRecordSigningInput — v1 byte stability (regression guard)', () => {
-  it('produces the exact original canonical bytes for a v1 record', () => {
-    const input = signedRecordSigningInput({
-      version: 1,
-      type: 'identity',
-      subject: 'did:web:oxy.so:u:u1',
-      issuer: 'did:web:oxy.so:u:u1',
-      record: { handle: '@nate' },
-      issuedAt: 1750000000000,
-    });
-    expect(input).toBe(
-      '{"issuedAt":1750000000000,"issuer":"did:web:oxy.so:u:u1","record":{"handle":"@nate"},"subject":"did:web:oxy.so:u:u1","type":"identity","version":1}',
-    );
-  });
-
-  it('does NOT include any v2 chain fields for a v1 record even if they are passed', () => {
-    const input = signedRecordSigningInput({
-      version: 1,
-      type: 'identity',
-      subject: 'did:web:oxy.so:u:u1',
-      issuer: 'did:web:oxy.so:u:u1',
-      record: { handle: '@nate' },
-      issuedAt: 1750000000000,
-      // These must be ignored by the v1 branch — proving v1 bytes are immutable.
-      seq: 5,
-      prev: 'deadbeef',
-      collection: 'app.oxy.identity',
-      rkey: 'self',
-    });
-    expect(input).not.toContain('seq');
-    expect(input).not.toContain('prev');
-    expect(input).not.toContain('collection');
-    expect(input).not.toContain('rkey');
-    expect(input).toBe(
-      '{"issuedAt":1750000000000,"issuer":"did:web:oxy.so:u:u1","record":{"handle":"@nate"},"subject":"did:web:oxy.so:u:u1","type":"identity","version":1}',
-    );
-  });
-});
-
-describe('SignatureService.signRecordV2 / verifyRecord (v2 hash chain)', () => {
+describe('SignatureService.signRecordV2 / verifyEnvelopeSignature (v2 hash chain)', () => {
   const keyPair = ec.genKeyPair();
   const publicKey = keyPair.getPublic('hex');
+  const privateKey = keyPair.getPrivate('hex').padStart(64, '0');
 
   beforeEach(() => {
-    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(publicKey);
-    jest.spyOn(KeyManager, 'getKeyPairObject').mockResolvedValue(keyPair);
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(privateKey);
   });
 
   afterEach(() => {
@@ -218,7 +182,7 @@ describe('SignatureService.signRecordV2 / verifyRecord (v2 hash chain)', () => {
       { verdict: 'approve' },
       { seq: 3, prev: 'a'.repeat(64), collection: 'app.oxy.validation', rkey: 'req_9' },
     );
-    await expect(SignatureService.verifyRecord(envelope)).resolves.toBe(true);
+    await expect(verifyEnvelopeSignature(envelope)).resolves.toBe(true);
   });
 
   it('covers the chain fields in the signed bytes (tampering breaks verify)', async () => {
@@ -229,18 +193,14 @@ describe('SignatureService.signRecordV2 / verifyRecord (v2 hash chain)', () => {
       chain,
     );
 
+    await expect(verifyEnvelopeSignature({ ...envelope, seq: 1 })).resolves.toBe(false);
     await expect(
-      SignatureService.verifyRecord({ ...envelope, seq: 1 }),
-    ).resolves.toBe(false);
-    await expect(
-      SignatureService.verifyRecord({ ...envelope, prev: 'b'.repeat(64) }),
-    ).resolves.toBe(false);
-    await expect(
-      SignatureService.verifyRecord({ ...envelope, collection: 'app.evil' }),
+      verifyEnvelopeSignature({ ...envelope, prev: 'b'.repeat(64) }),
     ).resolves.toBe(false);
     await expect(
-      SignatureService.verifyRecord({ ...envelope, rkey: 'other' }),
+      verifyEnvelopeSignature({ ...envelope, collection: 'app.evil' }),
     ).resolves.toBe(false);
+    await expect(verifyEnvelopeSignature({ ...envelope, rkey: 'other' })).resolves.toBe(false);
   });
 
   it('a v2 envelope signs over DIFFERENT bytes than the same base fields as v1', async () => {
@@ -264,82 +224,9 @@ describe('SignatureService.signRecordV2 / verifyRecord (v2 hash chain)', () => {
   });
 
   it('throws when no identity is stored', async () => {
-    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(null);
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(null);
     await expect(
       SignatureService.signRecordV2('identity', 'did:web:oxy.so:u:u4', {}, chain),
     ).rejects.toThrow(/No identity found/);
   });
 });
-
-describe('computeRecordId — deterministic content address', () => {
-  const base: SignedRecordEnvelope = {
-    version: 2,
-    type: 'reputation_attestation',
-    subject: 'did:web:oxy.so:u:rid',
-    issuer: 'did:web:oxy.so',
-    record: { points: 25 },
-    issuedAt: 1750000000000,
-    seq: 0,
-    prev: null,
-    collection: 'app.oxy.reputation',
-    rkey: 'rt_1',
-    publicKey: '03oxykey',
-    alg: 'ES256K-DER-SHA256',
-    signature: 'sig-is-not-part-of-the-id',
-  };
-
-  it('is a 64-char lowercase hex SHA-256 digest', async () => {
-    const id = await computeRecordId(base);
-    expect(id).toMatch(/^[0-9a-f]{64}$/);
-  });
-
-  it('is deterministic for identical signing fields', async () => {
-    const a = await computeRecordId(base);
-    const b = await computeRecordId(base);
-    expect(a).toBe(b);
-  });
-
-  it('equals sha256 of the canonical signing input (content address, excludes publicKey/signature)', async () => {
-    const id = await computeRecordId(base);
-    const expected = await SignatureService.hashMessage(signedRecordSigningInput(base));
-    expect(id).toBe(expected);
-    // Changing only signature/publicKey does NOT change the recordId.
-    const sameId = await computeRecordId({
-      ...base,
-      signature: 'totally-different',
-      publicKey: 'different-key',
-    });
-    expect(sameId).toBe(id);
-  });
-
-  it('changes when any signed field changes', async () => {
-    const id = await computeRecordId(base);
-    expect(await computeRecordId({ ...base, seq: 1 })).not.toBe(id);
-    expect(await computeRecordId({ ...base, record: { points: 26 } })).not.toBe(id);
-    expect(await computeRecordId({ ...base, prev: 'a'.repeat(64) })).not.toBe(id);
-  });
-
-  it('a v1 record and a v2 record with the same base fields have different recordIds', async () => {
-    const v1Id = await computeRecordId({
-      version: 1,
-      type: 'profile',
-      subject: 'did:web:oxy.so:u:rid',
-      issuer: 'did:web:oxy.so:u:rid',
-      record: { points: 25 },
-      issuedAt: 1750000000000,
-    });
-    const v2Id = await computeRecordId({
-      version: 2,
-      type: 'profile',
-      subject: 'did:web:oxy.so:u:rid',
-      issuer: 'did:web:oxy.so:u:rid',
-      record: { points: 25 },
-      issuedAt: 1750000000000,
-      seq: 0,
-      prev: null,
-      collection: 'app.oxy.profile',
-      rkey: 'self',
-    });
-    expect(v1Id).not.toBe(v2Id);
-  });
-});

package/src/crypto/keyManager.ts

@@ -7,27 +7,38 @@
 
 import { ec as EC } from 'elliptic';
 import type { ECKeyPair } from 'elliptic';
-import type { SecureStoreOptions } from 'expo-secure-store';
-import { isWeb, isIOS, isAndroid, isReactNative, isNodeJS } from '../utils/platform';
-import { loadExpoCrypto, loadNodeCrypto, loadSecureStore } from '../utils/platformCrypto';
+import { isWeb, isIOS, isAndroid } from '../utils/platform';
+import { type ExpoCryptoLike, type ExpoSecureStoreLike, isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore } from '@oxyhq/protocol';
 import { logger } from '../utils/loggerUtils';
 import { isDev } from '../shared/utils/debugUtils';
 
 /**
- * Extended SecureStoreOptions that explicitly includes `keychainAccessGroup`.
+ * Options for expo-secure-store calls made by KeyManager.
  *
- * The shipped `expo-secure-store` types in this repo (see
- * `src/types/expo-secure-store.d.ts`) already declare `keychainAccessGroup`,
- * but we redeclare it here as an `interface extends ...` so the field stays
- * type-safe even when the upstream package types drift. Older versions of
- * `@types/expo-secure-store` omitted this field, which is why the code base
- * used to fall back to `as any` — that escape hatch is now removed.
+ * Defined as a standalone interface (not extending expo-secure-store's
+ * `SecureStoreOptions`) so that server / Node.js consumers of @oxyhq/core
+ * do not transitively pull in expo-modules-core's type declarations under
+ * NodeNext module resolution (which would cause NodeJS.Timeout / number
+ * pollution across all timer APIs). The fields mirror SecureStoreOptions
+ * exactly — any object satisfying this interface is safe to pass to the
+ * real expo-secure-store methods (which accept `options?: object`).
  */
-interface OxySecureStoreOptions extends SecureStoreOptions {
+interface OxySecureStoreOptions {
+  /** Keychain service name (Android keystore / iOS keychain tag). */
+  keychainService?: string;
+  /**
+   * Keychain / Keystore item accessibility. Use the constants from the
+   * `ExpoSecureStoreLike` handle returned by `initSecureStore()`, e.g.
+   * `store.WHEN_UNLOCKED_THIS_DEVICE_ONLY`.
+   */
+  keychainAccessible?: number;
+  /** Prompt shown to the user for biometric/auth-protected items. */
+  authenticationPrompt?: string;
+  /** Whether Face ID / Touch ID / biometric auth is required to read the item. */
+  requireAuthentication?: boolean;
   /**
    * iOS Keychain access group. Required for sharing identity material across
-   * apps in the Oxy ecosystem via Keychain Sharing entitlements. The
-   * underlying `expo-secure-store` runtime supports this option.
+   * apps in the Oxy ecosystem via Keychain Sharing entitlements.
    */
   keychainAccessGroup?: string;
 }
@@ -98,13 +109,13 @@ const ANDROID_ACCOUNT_TYPE = 'com.oxy.account';
 /**
  * Initialize React Native specific modules
  *
- * Delegates to `platformCrypto`, which is a per-platform module
- * (`platformCrypto.ts` vs `platformCrypto.react-native.ts`) selected by the
+ * Delegates to `@oxyhq/protocol`'s `platform/crypto`, a per-platform module
+ * (`crypto.ts` vs `crypto.native.ts`) selected by the
  * consumer's bundler. On RN it returns a statically-imported handle to
  * `expo-secure-store`; off RN it throws (and is never called because every
  * caller is gated by `isWebPlatform()` / native-only paths).
  */
-async function initSecureStore(): Promise<typeof import('expo-secure-store')> {
+async function initSecureStore(): Promise<ExpoSecureStoreLike> {
   try {
     return await loadSecureStore();
   } catch (error) {
@@ -124,7 +135,7 @@ function isWebPlatform(): boolean {
   return isWeb();
 }
 
-async function initExpoCrypto(): Promise<typeof import('expo-crypto')> {
+async function initExpoCrypto(): Promise<ExpoCryptoLike> {
   // Same per-platform delegation as initSecureStore — see comment there.
   return loadExpoCrypto();
 }

package/src/crypto/polyfill.ts

@@ -6,12 +6,12 @@
  *
  * - Browser/Node.js: Uses native crypto
  * - React Native: Uses expo-crypto (statically imported via the
- *   per-platform `platformCrypto` module — see that file's doc-comment for
- *   how platform routing works).
+ *   per-platform `platform/crypto` module in `@oxyhq/protocol` — see that
+ *   file's doc-comment for how platform routing works).
  */
 
 import { Buffer } from 'buffer';
-import { getRandomBytesRN } from '../utils/platformCrypto';
+import { getRandomBytesRN } from '@oxyhq/protocol';
 
 const getGlobalObject = (): typeof globalThis => {
   if (typeof globalThis !== 'undefined') return globalThis;
@@ -35,7 +35,8 @@ type CryptoLike = {
 /**
  * Synchronous random-bytes shim. On RN, this delegates to
  * `expo-crypto.getRandomBytes` (statically imported by the RN variant of
- * `platformCrypto`, so available without any async warm-up). On Node /
+ * `@oxyhq/protocol`'s `platform/crypto`, so available without any async
+ * warm-up). On Node /
  * browser, this throws — but is never called there because both platforms
  * already provide `globalThis.crypto.getRandomValues` natively.
  */