@oxyhq/core 12.5.0 → 12.5.1

package/dist/types/crypto/polyfill.d.ts

@@ -4,10 +4,22 @@
  * Ensures Buffer and crypto.getRandomValues are available
  * across all platforms (Node.js, Browser, React Native).
  *
- * - Browser/Node.js: Uses native crypto
- * - React Native: Uses expo-crypto (statically imported via the
- *   per-platform `platform/crypto` module in `@oxyhq/protocol` — see that
- *   file's doc-comment for how platform routing works).
+ * Guard order when installing a `getRandomValues` shim (see bottom of file and
+ * {@link cryptoPolyfill}):
+ *
+ *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browser, Node
+ *      >= 20, modern Hermes). The shim below is only installed when the host is
+ *      missing it, so this branch is the install-time gate.
+ *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
+ *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
+ *      (Node 18 script entrypoints, some embedded hosts) falls back to.
+ *   3. React Native — `expo-crypto.getRandomBytes` (statically imported via the
+ *      per-platform `platform/crypto` module in `@oxyhq/protocol`).
+ *
+ * Historically step (2) delegated to `@oxyhq/protocol`'s RN-only
+ * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global
+ * WebCrypto crashed here instead of getting randomness. It is now a proper
+ * Node-backed implementation.
  */
 import { Buffer } from 'buffer';
 export { Buffer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.5.0",
+  "version": "12.5.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

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

@@ -0,0 +1,109 @@
+/**
+ * Crypto polyfill — `getRandomValues` install + platform routing.
+ *
+ * Regression coverage for the latent Node crash: when a Node runtime ships
+ * WITHOUT a global WebCrypto (Node 18 script entrypoints, some embedded hosts),
+ * the installed `getRandomValues` shim must be backed by `node:crypto` and MUST
+ * NOT fall through to `@oxyhq/protocol`'s RN-only `getRandomBytesRN` stub (which
+ * throws `Tried to load 'expo-crypto...' outside React Native`).
+ */
+
+// Controllable stand-ins for `@oxyhq/protocol`'s platform predicates. Names are
+// `mock`-prefixed so the (hoisted) `jest.mock` factory may reference them.
+const mockGetRandomBytesRN = jest.fn<Uint8Array, [number]>();
+const mockState = { isNodeJS: true };
+
+jest.mock('@oxyhq/protocol', () => ({
+  isNodeJS: () => mockState.isNodeJS,
+  getRandomBytesRN: (byteCount: number) => mockGetRandomBytesRN(byteCount),
+}));
+
+type CryptoLike = {
+  getRandomValues: <T extends ArrayBufferView>(array: T) => T;
+};
+
+const ORIGINAL_CRYPTO_DESCRIPTOR = Object.getOwnPropertyDescriptor(globalThis, 'crypto');
+
+/**
+ * Re-run the polyfill module with NO host `globalThis.crypto`, returning the
+ * `getRandomValues` shim it installs. Restores the real global afterwards so
+ * the manipulation never leaks into other tests.
+ */
+function installShimWithoutHostCrypto(): CryptoLike {
+  Object.defineProperty(globalThis, 'crypto', {
+    value: undefined,
+    configurable: true,
+    writable: true,
+  });
+  try {
+    jest.isolateModules(() => {
+      require('../polyfill');
+    });
+    const installed = (globalThis as { crypto?: CryptoLike }).crypto;
+    if (!installed || typeof installed.getRandomValues !== 'function') {
+      throw new Error('polyfill did not install a getRandomValues shim');
+    }
+    return installed;
+  } finally {
+    Object.defineProperty(
+      globalThis,
+      'crypto',
+      ORIGINAL_CRYPTO_DESCRIPTOR ?? { value: undefined, configurable: true, writable: true },
+    );
+  }
+}
+
+beforeEach(() => {
+  mockGetRandomBytesRN.mockReset();
+  mockState.isNodeJS = true;
+});
+
+describe('crypto polyfill getRandomValues', () => {
+  it('on Node without global WebCrypto, fills from node:crypto and never calls the RN stub', () => {
+    mockState.isNodeJS = true;
+    // If the shim ever fell through to the RN path on Node, this would throw —
+    // exactly the latent crash we are guarding against.
+    mockGetRandomBytesRN.mockImplementation(() => {
+      throw new Error('RN getRandomBytesRN must not be called on Node');
+    });
+
+    const shim = installShimWithoutHostCrypto();
+    const array = new Uint8Array(16);
+
+    expect(() => shim.getRandomValues(array)).not.toThrow();
+    // Backed by a real CSPRNG: all-zero output is cryptographically impossible.
+    expect(array.some((byte) => byte !== 0)).toBe(true);
+    expect(mockGetRandomBytesRN).not.toHaveBeenCalled();
+  });
+
+  it('on Node, routes a non-integer view (DataView) through randomFillSync', () => {
+    mockState.isNodeJS = true;
+    mockGetRandomBytesRN.mockImplementation(() => {
+      throw new Error('RN getRandomBytesRN must not be called on Node');
+    });
+
+    const shim = installShimWithoutHostCrypto();
+    const view = new DataView(new ArrayBuffer(16));
+
+    expect(() => shim.getRandomValues(view)).not.toThrow();
+    let anyNonZero = false;
+    for (let i = 0; i < view.byteLength; i += 1) {
+      if (view.getUint8(i) !== 0) anyNonZero = true;
+    }
+    expect(anyNonZero).toBe(true);
+    expect(mockGetRandomBytesRN).not.toHaveBeenCalled();
+  });
+
+  it('on React Native, delegates to expo-crypto via getRandomBytesRN (path unchanged)', () => {
+    mockState.isNodeJS = false;
+    const rnBytes = Uint8Array.from([1, 2, 3, 4, 5, 6, 7, 8]);
+    mockGetRandomBytesRN.mockReturnValue(rnBytes);
+
+    const shim = installShimWithoutHostCrypto();
+    const array = new Uint8Array(8);
+    const result = shim.getRandomValues(array);
+
+    expect(mockGetRandomBytesRN).toHaveBeenCalledWith(8);
+    expect(Array.from(result)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+  });
+});

package/src/crypto/polyfill.ts

@@ -4,14 +4,26 @@
  * Ensures Buffer and crypto.getRandomValues are available
  * across all platforms (Node.js, Browser, React Native).
  *
- * - Browser/Node.js: Uses native crypto
- * - React Native: Uses expo-crypto (statically imported via the
- *   per-platform `platform/crypto` module in `@oxyhq/protocol` — see that
- *   file's doc-comment for how platform routing works).
+ * Guard order when installing a `getRandomValues` shim (see bottom of file and
+ * {@link cryptoPolyfill}):
+ *
+ *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browser, Node
+ *      >= 20, modern Hermes). The shim below is only installed when the host is
+ *      missing it, so this branch is the install-time gate.
+ *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
+ *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
+ *      (Node 18 script entrypoints, some embedded hosts) falls back to.
+ *   3. React Native — `expo-crypto.getRandomBytes` (statically imported via the
+ *      per-platform `platform/crypto` module in `@oxyhq/protocol`).
+ *
+ * Historically step (2) delegated to `@oxyhq/protocol`'s RN-only
+ * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global
+ * WebCrypto crashed here instead of getting randomness. It is now a proper
+ * Node-backed implementation.
  */
 
 import { Buffer } from 'buffer';
-import { getRandomBytesRN } from '@oxyhq/protocol';
+import { getRandomBytesRN, isNodeJS } from '@oxyhq/protocol';
 
 const getGlobalObject = (): typeof globalThis => {
   if (typeof globalThis !== 'undefined') return globalThis;
@@ -32,25 +44,89 @@ type CryptoLike = {
   getRandomValues: <T extends ArrayBufferView>(array: T) => T;
 };
 
+/** Minimal structural shape of the parts of `node:crypto` this polyfill uses. */
+interface NodeCryptoLike {
+  webcrypto?: {
+    getRandomValues?: <T extends ArrayBufferView>(array: T) => T;
+  };
+  randomFillSync?: <T extends ArrayBufferView>(buffer: T) => T;
+}
+
+/**
+ * Lazily-resolved `node:crypto` module, cached after the first attempt.
+ * `undefined` = not tried yet; `null` = tried and unavailable (non-Node host).
+ */
+let cachedNodeCrypto: NodeCryptoLike | null | undefined;
+
+/**
+ * Synchronously load `node:crypto` on a Node runtime, or `null` elsewhere.
+ *
+ * Uses a guarded, Node-only `require`. Every runtime that actually reaches this
+ * branch has a working CommonJS `require`: `@oxyhq/core` publishes no
+ * `"type": "module"`, so Node loads it as CommonJS and the `require` free
+ * variable is present. Browsers never reach here (they own `globalThis.crypto`,
+ * so this polyfill is never installed) and React Native takes the
+ * `getRandomBytesRN` branch — so the `node:crypto` reference is dead code in
+ * those bundles, and Expo's Metro resolver shims `node:*` builtins, keeping
+ * web/native bundles green.
+ */
+function loadNodeCryptoSync(): NodeCryptoLike | null {
+  if (cachedNodeCrypto !== undefined) {
+    return cachedNodeCrypto;
+  }
+  if (typeof require !== 'function') {
+    cachedNodeCrypto = null;
+    return cachedNodeCrypto;
+  }
+  try {
+    cachedNodeCrypto = require('node:crypto') as NodeCryptoLike;
+  } catch {
+    // No Node crypto (unexpected on a real Node host) — degrade to the next
+    // mechanism rather than crash.
+    cachedNodeCrypto = null;
+  }
+  return cachedNodeCrypto;
+}
+
 /**
- * Synchronous random-bytes shim. On RN, this delegates to
- * `expo-crypto.getRandomBytes` (statically imported by the RN variant of
- * `@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.
+ * Fill `array` with cryptographically-secure random bytes from `node:crypto`.
+ * Prefers `webcrypto.getRandomValues`; falls back to `randomFillSync`. Returns
+ * `false` when Node crypto is unavailable so the caller can try the next
+ * mechanism.
  */
-function getRandomBytesSync(byteCount: number): Uint8Array {
-  // `getRandomBytesRN` throws on non-RN platforms. That's fine: this
-  // function is only ever called as a fallback when the native
-  // `globalThis.crypto.getRandomValues` is missing, which on a normal
-  // Node/browser host never happens.
-  return getRandomBytesRN(byteCount);
+function fillFromNodeCrypto(array: ArrayBufferView): boolean {
+  const nodeCrypto = loadNodeCryptoSync();
+  if (!nodeCrypto) {
+    return false;
+  }
+  const webcrypto = nodeCrypto.webcrypto;
+  if (webcrypto && typeof webcrypto.getRandomValues === 'function') {
+    try {
+      webcrypto.getRandomValues(array);
+      return true;
+    } catch {
+      // `webcrypto.getRandomValues` rejects non-integer views (Float*Array,
+      // DataView); fall through to `randomFillSync`, which accepts any view.
+    }
+  }
+  if (typeof nodeCrypto.randomFillSync === 'function') {
+    nodeCrypto.randomFillSync(array);
+    return true;
+  }
+  return false;
 }
 
 const cryptoPolyfill: CryptoLike = {
   getRandomValues<T extends ArrayBufferView>(array: T): T {
-    const bytes = getRandomBytesSync(array.byteLength);
+    // Node: back the CSPRNG with `node:crypto`. This is the path that matters on
+    // Node runtimes shipping WITHOUT a global WebCrypto — where delegating to
+    // the RN-only expo-crypto stub would throw.
+    if (isNodeJS() && fillFromNodeCrypto(array)) {
+      return array;
+    }
+    // React Native (and any non-Node host without WebCrypto): synchronous
+    // expo-crypto via @oxyhq/protocol's RN `platform/crypto` variant.
+    const bytes = getRandomBytesRN(array.byteLength);
     const uint8View = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
     uint8View.set(bytes);
     return array;