@oxy.so/protocol 1.1.0 → 1.1.1

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

@@ -83,11 +83,5 @@ export declare function loadAsyncStorage(): Promise<{
         removeItem: (key: string) => Promise<void>;
     };
 }>;
-/**
- * Synchronous random-bytes via `expo-crypto.getRandomBytes`. Only available
- * in the React Native variant. The default variant throws because Node and
- * browsers have their own native CSPRNGs (`crypto.randomBytes` and
- * `crypto.getRandomValues` respectively) — callers should use those.
- */
-export declare function getRandomBytesRN(_byteCount: number): Uint8Array;
+export { getRandomBytesRN } from './random';
 export declare function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null>;

package/dist/types/platform/crypto.native.d.ts

@@ -24,7 +24,7 @@
  * Those three RN modules are declared OPTIONAL peer dependencies in
  * `package.json`. A static `import` contradicts that: an optional peer that is
  * omitted does not degrade, it fails to RESOLVE, and Metro aborts the whole
- * bundle. Because `@oxy.so/core`'s `crypto/polyfill` imports `@oxy.so/protocol`
+ * bundle. Because `@oxy.so/core` imports `@oxy.so/protocol`
  * from its root entry, this file is in the eager graph of EVERY React Native
  * app on `@oxy.so/core` — so a single undeclared optional peer broke the native
  * bundle of every app that did not happen to install it, with a resolution
@@ -65,13 +65,5 @@ export declare function loadSecureStore(): Promise<ExpoSecureStoreLike>;
 export declare function loadAsyncStorage(): Promise<{
     default: AsyncStorageLike;
 }>;
-/**
- * Synchronous random-bytes via `expo-crypto.getRandomBytes`.
- *
- * Synchronous by contract: `@oxy.so/core`'s crypto polyfill uses this to back
- * `globalThis.crypto.getRandomValues`, which cannot await. That is why
- * `expo-crypto` is resolved with a synchronous `require` at module scope rather
- * than a dynamic `import()`.
- */
-export declare function getRandomBytesRN(byteCount: number): Uint8Array;
+export { getRandomBytesRN } from './random.native';
 export declare function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null>;

package/dist/types/platform/optionalPeer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Actionable error for a missing optional React Native peer.
+ *
+ * Shared by the React Native platform variants (`crypto.native.ts`,
+ * `random.native.ts`). It carries the underlying Metro resolution message so
+ * the failure is never silent: the variants' `try { require(...) } catch` only
+ * defers the report to the point where the capability is actually used.
+ */
+export declare function missingOptionalPeerError(packageName: string, capability: string, cause: unknown): Error;

package/dist/types/platform/random.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Synchronous CSPRNG source — default variant (Node.js, browsers, bundlers).
+ *
+ * Companion to `./random.native.ts`, which Metro substitutes on iOS / Android.
+ * Node and browsers own a native CSPRNG (`node:crypto`, `globalThis.crypto`),
+ * so `getRandomBytesRN` only exists here to keep both variants' surfaces
+ * identical, and throws if anything reaches it outside React Native.
+ *
+ * Like its sibling, this module imports nothing: it is part of the
+ * `@oxy.so/protocol/random` entry that `@oxy.so/core`'s crypto polyfill loads
+ * BEFORE any crypto library is evaluated.
+ */
+export declare function getRandomBytesRN(_byteCount: number): Uint8Array;

package/dist/types/platform/random.native.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Synchronous CSPRNG source — React Native variant.
+ *
+ * Companion to `./random.ts`; Metro substitutes this file on iOS / Android
+ * (see `./crypto.ts` for how the `.native` split works).
+ *
+ * This module is deliberately tiny and imports NOTHING but `expo-crypto`: it
+ * backs `@oxy.so/core`'s `globalThis.crypto.getRandomValues` polyfill, which
+ * must be fully installed before any module that captures `globalThis.crypto`
+ * at evaluation time (`@noble/hashes` 1.x's `crypto.js` does exactly that) is
+ * evaluated. Reaching a crypto library from here would let that library
+ * capture the missing global first and throw
+ * `crypto.getRandomValues must be defined` for the lifetime of the app.
+ *
+ * `expo-crypto` is an OPTIONAL peer, so it is resolved with a string-literal
+ * `require` inside a `try` (Metro's optional-dependency form; see
+ * `./crypto.native.ts`), and the load stays synchronous because
+ * `getRandomValues` cannot await.
+ */
+import type { ExpoCryptoLike } from './expoTypes';
+/**
+ * The resolved `expo-crypto` module, or an actionable error naming the missing
+ * peer and the capability that needed it. Shared with `./crypto.native.ts` so
+ * the optional peer is resolved in exactly one place.
+ */
+export declare function requireExpoCrypto(capability: string): ExpoCryptoLike;
+/**
+ * Synchronous random bytes via `expo-crypto.getRandomBytes`.
+ *
+ * Synchronous by contract: `@oxy.so/core`'s crypto polyfill uses this to back
+ * `globalThis.crypto.getRandomValues`, which cannot await.
+ */
+export declare function getRandomBytesRN(byteCount: number): Uint8Array;

package/dist/types/random.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@oxy.so/protocol/random` — the platform randomness source, and nothing else.
+ *
+ * `@oxy.so/core`'s crypto polyfill installs `globalThis.crypto.getRandomValues`
+ * on hosts that lack it (React Native / Hermes). `@noble/hashes` 1.x captures
+ * `globalThis.crypto` ONCE, when its `crypto.js` is evaluated, so the polyfill
+ * has to be installed before any `@noble/*` module is evaluated. ES imports are
+ * evaluated before the importing module's body, so whatever the polyfill
+ * imports is evaluated first: importing the ROOT entry (which reaches
+ * `@noble/curves` through the envelope signer) let noble capture `undefined`
+ * and broke identity creation on Android.
+ *
+ * This entry therefore reaches no crypto library, no `@oxy.so/*` package and no
+ * third-party module other than the optional `expo-crypto` peer (RN variant
+ * only). `src/__tests__/randomEntry.test.ts` walks its module graph to keep it
+ * that way.
+ */
+export { isNodeJS, isReactNative } from './platform/platform';
+export { getRandomBytesRN } from './platform/random';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/protocol",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Oxy Protocol — the app-agnostic base substrate: signed-record envelope, canonical JSON, signature/verification, and platform crypto. Reused by any Oxy app to decentralize its own content.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -12,6 +12,9 @@
       ],
       "node": [
         "dist/types/node/index.d.ts"
+      ],
+      "random": [
+        "dist/types/random.d.ts"
       ]
     }
   },
@@ -56,11 +59,25 @@
       },
       "default": "./dist/esm/secp256k1.js"
     },
+    "./random": {
+      "react-native": "./dist/esm/random.js",
+      "import": {
+        "types": "./dist/types/random.d.ts",
+        "default": "./dist/esm/random.js"
+      },
+      "require": {
+        "types": "./dist/types/random.d.ts",
+        "default": "./dist/cjs/random.js"
+      },
+      "default": "./dist/esm/random.js"
+    },
     "./package.json": "./package.json"
   },
   "react-native": {
     "./dist/esm/platform/crypto.js": "./dist/esm/platform/crypto.native.js",
-    "./dist/cjs/platform/crypto.js": "./dist/cjs/platform/crypto.native.js"
+    "./dist/cjs/platform/crypto.js": "./dist/cjs/platform/crypto.native.js",
+    "./dist/esm/platform/random.js": "./dist/esm/platform/random.native.js",
+    "./dist/cjs/platform/random.js": "./dist/cjs/platform/random.native.js"
   },
   "files": [
     "NOTICE",
@@ -114,7 +131,7 @@
   },
   "dependencies": {
     "@noble/curves": "^1.9.7",
-    "@oxy.so/contracts": "^1.3.0",
+    "@oxy.so/contracts": "^1.4.0",
     "zod": "^3.25.64"
   },
   "peerDependencies": {

package/src/__tests__/randomEntry.test.ts

@@ -0,0 +1,107 @@
+/**
+ * `@oxy.so/protocol/random` must reach no module other than its own platform
+ * files and the optional `expo-crypto` peer.
+ *
+ * `@oxy.so/core`'s crypto polyfill imports this entry to install
+ * `globalThis.crypto.getRandomValues` on React Native. Everything the polyfill
+ * imports is evaluated BEFORE the polyfill body, and `@noble/hashes` 1.x
+ * captures `globalThis.crypto` once, at evaluation. When the polyfill imported
+ * the root entry instead, noble was reached through the envelope signer,
+ * captured `undefined`, and every Android identity creation failed with
+ * `crypto.getRandomValues must be defined`. This guard keeps the entry's graph
+ * dependency-free, including the `.native` siblings Metro substitutes.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const SRC_DIR = resolve(__dirname, '..');
+const RANDOM_ENTRY = join(SRC_DIR, 'random.ts');
+
+/**
+ * Every value-level module specifier: static imports/re-exports, literal
+ * `require()`s and `import()`s. Comments are stripped first so prose that
+ * mentions a module (these files document why they avoid them) is not counted.
+ */
+function valueSpecifiers(rawSource: string): string[] {
+  const source = rawSource.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+  const specifiers: string[] = [];
+  const patterns = [
+    /(?:^|\n)\s*(?:import|export)\s+(?!type\s)[\s\S]*?\sfrom\s+['"]([^'"]+)['"]/g,
+    /(?:^|\n)\s*import\s+['"]([^'"]+)['"]/g,
+    /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g,
+    /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g,
+  ];
+  for (const pattern of patterns) {
+    let match = pattern.exec(source);
+    while (match !== null) {
+      specifiers.push(match[1]);
+      match = pattern.exec(source);
+    }
+  }
+  return specifiers;
+}
+
+function resolveRelative(fromFile: string, specifier: string): string {
+  const base = resolve(dirname(fromFile), specifier);
+  for (const candidate of [`${base}.ts`, join(base, 'index.ts')]) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(`unresolved relative import '${specifier}' in ${fromFile}`);
+}
+
+function walk(entry: string): { files: string[]; external: string[] } {
+  const seen = new Set<string>();
+  const external = new Set<string>();
+  const queue = [entry];
+  while (queue.length > 0) {
+    const file = queue.shift() as string;
+    if (seen.has(file)) {
+      continue;
+    }
+    seen.add(file);
+    const nativeSibling = file.replace(/\.ts$/, '.native.ts');
+    if (!file.endsWith('.native.ts') && existsSync(nativeSibling)) {
+      queue.push(nativeSibling);
+    }
+    for (const specifier of valueSpecifiers(readFileSync(file, 'utf8'))) {
+      if (specifier.startsWith('.')) {
+        queue.push(resolveRelative(file, specifier));
+      } else {
+        external.add(specifier);
+      }
+    }
+  }
+  return { files: [...seen], external: [...external] };
+}
+
+describe('@oxy.so/protocol/random entry', () => {
+  it('reaches no third-party module other than the optional expo-crypto peer', () => {
+    expect(walk(RANDOM_ENTRY).external).toEqual(['expo-crypto']);
+  });
+
+  it('includes the React Native variant that Metro substitutes', () => {
+    // Sanity check on the walker: without the native sibling the guard above
+    // would pass vacuously on the default (import-free) variant.
+    expect(walk(RANDOM_ENTRY).files).toEqual(
+      expect.arrayContaining([join(SRC_DIR, 'platform', 'random.native.ts')]),
+    );
+  });
+
+  it('is exported as a package subpath', () => {
+    const manifest = JSON.parse(readFileSync(resolve(SRC_DIR, '..', 'package.json'), 'utf8')) as {
+      exports: Record<string, unknown>;
+    };
+    expect(manifest.exports['./random']).toBeDefined();
+  });
+
+  it('exposes the platform predicates and the RN randomness source', () => {
+    const entry = require('../random') as typeof import('../random');
+    expect(typeof entry.isNodeJS).toBe('function');
+    expect(typeof entry.isReactNative).toBe('function');
+    expect(entry.isNodeJS()).toBe(true);
+    expect(() => entry.getRandomBytesRN(8)).toThrow(/outside React Native/);
+  });
+});

package/src/platform/crypto.native.ts

@@ -24,7 +24,7 @@
  * Those three RN modules are declared OPTIONAL peer dependencies in
  * `package.json`. A static `import` contradicts that: an optional peer that is
  * omitted does not degrade, it fails to RESOLVE, and Metro aborts the whole
- * bundle. Because `@oxy.so/core`'s `crypto/polyfill` imports `@oxy.so/protocol`
+ * bundle. Because `@oxy.so/core` imports `@oxy.so/protocol`
  * from its root entry, this file is in the eager graph of EVERY React Native
  * app on `@oxy.so/core` — so a single undeclared optional peer broke the native
  * bundle of every app that did not happen to install it, with a resolution
@@ -54,6 +54,8 @@
 
 import { requireOptionalNativeModule } from 'expo-modules-core';
 import type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './expoTypes';
+import { missingOptionalPeerError } from './optionalPeer';
+import { requireExpoCrypto } from './random.native';
 
 // Re-export the interfaces so consumers can import them from the same
 // entry-point they use for the loaders (mirrors the default variant).
@@ -77,14 +79,6 @@ type AsyncStorageLike = {
   removeItem: (key: string) => Promise<void>;
 };
 
-let expoCryptoModule: ExpoCryptoLike | null = null;
-let expoCryptoError: unknown;
-try {
-  expoCryptoModule = require('expo-crypto') as ExpoCryptoLike;
-} catch (error) {
-  expoCryptoError = error;
-}
-
 let secureStoreModule: ExpoSecureStoreLike | null = null;
 let secureStoreError: unknown;
 try {
@@ -107,23 +101,6 @@ try {
   asyncStorageError = error;
 }
 
-/**
- * Actionable error for a missing optional peer. Carries the underlying Metro
- * resolution message so the failure is never silent — the `catch` above only
- * defers the report to the point where the capability is actually needed.
- */
-function missingOptionalPeerError(packageName: string, capability: string, cause: unknown): Error {
-  const sentences = [
-    `[oxy.protocol.crypto] '${packageName}' is not installed, so ${capability} is unavailable in this app.`,
-    'It is an optional peer dependency of @oxy.so/protocol that the React Native runtime needs —',
-    `install it with \`npx expo install ${packageName}\`.`,
-  ];
-  if (cause instanceof Error) {
-    sentences.push(`Underlying error: ${cause.message}`);
-  }
-  return new Error(sentences.join(' '));
-}
-
 // ---------------------------------------------------------------------------
 // Node `crypto` — never available in RN.
 // ---------------------------------------------------------------------------
@@ -149,10 +126,7 @@ export async function loadNodeCrypto(): Promise<typeof import('crypto')> {
 // ---------------------------------------------------------------------------
 
 export async function loadExpoCrypto(): Promise<ExpoCryptoLike> {
-  if (!expoCryptoModule) {
-    throw missingOptionalPeerError('expo-crypto', 'React Native cryptography', expoCryptoError);
-  }
-  return expoCryptoModule;
+  return requireExpoCrypto('React Native cryptography');
 }
 
 // ---------------------------------------------------------------------------
@@ -188,24 +162,12 @@ export async function loadAsyncStorage(): Promise<{ default: AsyncStorageLike }>
   return { default: asyncStorageModule };
 }
 
-/**
- * Synchronous random-bytes via `expo-crypto.getRandomBytes`.
- *
- * Synchronous by contract: `@oxy.so/core`'s crypto polyfill uses this to back
- * `globalThis.crypto.getRandomValues`, which cannot await. That is why
- * `expo-crypto` is resolved with a synchronous `require` at module scope rather
- * than a dynamic `import()`.
- */
-export function getRandomBytesRN(byteCount: number): Uint8Array {
-  if (!expoCryptoModule) {
-    throw missingOptionalPeerError(
-      'expo-crypto',
-      'the React Native CSPRNG (crypto.getRandomValues)',
-      expoCryptoError,
-    );
-  }
-  return expoCryptoModule.getRandomBytes(byteCount);
-}
+// Synchronous random bytes (and the single `expo-crypto` resolution) live in
+// the dependency-free `./random.native` module, so `@oxy.so/core`'s crypto
+// polyfill can load them through `@oxy.so/protocol/random` without evaluating
+// any crypto library first. The explicit `.native` specifier keeps tsc and
+// Metro pointed at the same file.
+export { getRandomBytesRN } from './random.native';
 
 // ---------------------------------------------------------------------------
 // Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only, OPTIONAL).

package/src/platform/crypto.ts

@@ -148,15 +148,10 @@ export async function loadAsyncStorage(): Promise<{
   throw notReactNativeError('@react-native-async-storage/async-storage');
 }
 
-/**
- * Synchronous random-bytes via `expo-crypto.getRandomBytes`. Only available
- * in the React Native variant. The default variant throws because Node and
- * browsers have their own native CSPRNGs (`crypto.randomBytes` and
- * `crypto.getRandomValues` respectively) — callers should use those.
- */
-export function getRandomBytesRN(_byteCount: number): Uint8Array {
-  throw notReactNativeError('expo-crypto.getRandomBytes (sync)');
-}
+// Synchronous random bytes live in the dependency-free `./random` module so
+// `@oxy.so/core`'s crypto polyfill can load them through the
+// `@oxy.so/protocol/random` entry without evaluating any crypto library first.
+export { getRandomBytesRN } from './random';
 
 // ---------------------------------------------------------------------------
 // Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only).

package/src/platform/optionalPeer.ts

@@ -0,0 +1,23 @@
+/**
+ * Actionable error for a missing optional React Native peer.
+ *
+ * Shared by the React Native platform variants (`crypto.native.ts`,
+ * `random.native.ts`). It carries the underlying Metro resolution message so
+ * the failure is never silent: the variants' `try { require(...) } catch` only
+ * defers the report to the point where the capability is actually used.
+ */
+export function missingOptionalPeerError(
+  packageName: string,
+  capability: string,
+  cause: unknown,
+): Error {
+  const sentences = [
+    `[oxy.protocol.crypto] '${packageName}' is not installed, so ${capability} is unavailable in this app.`,
+    'It is an optional peer dependency of @oxy.so/protocol that the React Native runtime needs —',
+    `install it with \`npx expo install ${packageName}\`.`,
+  ];
+  if (cause instanceof Error) {
+    sentences.push(`Underlying error: ${cause.message}`);
+  }
+  return new Error(sentences.join(' '));
+}

package/src/platform/random.native.ts

@@ -0,0 +1,56 @@
+/**
+ * Synchronous CSPRNG source — React Native variant.
+ *
+ * Companion to `./random.ts`; Metro substitutes this file on iOS / Android
+ * (see `./crypto.ts` for how the `.native` split works).
+ *
+ * This module is deliberately tiny and imports NOTHING but `expo-crypto`: it
+ * backs `@oxy.so/core`'s `globalThis.crypto.getRandomValues` polyfill, which
+ * must be fully installed before any module that captures `globalThis.crypto`
+ * at evaluation time (`@noble/hashes` 1.x's `crypto.js` does exactly that) is
+ * evaluated. Reaching a crypto library from here would let that library
+ * capture the missing global first and throw
+ * `crypto.getRandomValues must be defined` for the lifetime of the app.
+ *
+ * `expo-crypto` is an OPTIONAL peer, so it is resolved with a string-literal
+ * `require` inside a `try` (Metro's optional-dependency form; see
+ * `./crypto.native.ts`), and the load stays synchronous because
+ * `getRandomValues` cannot await.
+ */
+
+import type { ExpoCryptoLike } from './expoTypes';
+import { missingOptionalPeerError } from './optionalPeer';
+
+declare const require: (moduleName: string) => unknown;
+
+let expoCryptoModule: ExpoCryptoLike | null = null;
+let expoCryptoError: unknown;
+try {
+  expoCryptoModule = require('expo-crypto') as ExpoCryptoLike;
+} catch (error) {
+  expoCryptoError = error;
+}
+
+/**
+ * The resolved `expo-crypto` module, or an actionable error naming the missing
+ * peer and the capability that needed it. Shared with `./crypto.native.ts` so
+ * the optional peer is resolved in exactly one place.
+ */
+export function requireExpoCrypto(capability: string): ExpoCryptoLike {
+  if (!expoCryptoModule) {
+    throw missingOptionalPeerError('expo-crypto', capability, expoCryptoError);
+  }
+  return expoCryptoModule;
+}
+
+/**
+ * Synchronous random bytes via `expo-crypto.getRandomBytes`.
+ *
+ * Synchronous by contract: `@oxy.so/core`'s crypto polyfill uses this to back
+ * `globalThis.crypto.getRandomValues`, which cannot await.
+ */
+export function getRandomBytesRN(byteCount: number): Uint8Array {
+  return requireExpoCrypto('the React Native CSPRNG (crypto.getRandomValues)').getRandomBytes(
+    byteCount,
+  );
+}

package/src/platform/random.ts

@@ -0,0 +1,18 @@
+/**
+ * Synchronous CSPRNG source — default variant (Node.js, browsers, bundlers).
+ *
+ * Companion to `./random.native.ts`, which Metro substitutes on iOS / Android.
+ * Node and browsers own a native CSPRNG (`node:crypto`, `globalThis.crypto`),
+ * so `getRandomBytesRN` only exists here to keep both variants' surfaces
+ * identical, and throws if anything reaches it outside React Native.
+ *
+ * Like its sibling, this module imports nothing: it is part of the
+ * `@oxy.so/protocol/random` entry that `@oxy.so/core`'s crypto polyfill loads
+ * BEFORE any crypto library is evaluated.
+ */
+
+export function getRandomBytesRN(_byteCount: number): Uint8Array {
+  throw new Error(
+    "[oxy.protocol.crypto] Tried to load 'expo-crypto.getRandomBytes (sync)' outside React Native. This module is only available in a React Native runtime; bundling routed this consumer to the default (Node/web) variant. This indicates a missing platform gate (`isReactNative()`) in the calling code.",
+  );
+}

package/src/random.ts

@@ -0,0 +1,20 @@
+/**
+ * `@oxy.so/protocol/random` — the platform randomness source, and nothing else.
+ *
+ * `@oxy.so/core`'s crypto polyfill installs `globalThis.crypto.getRandomValues`
+ * on hosts that lack it (React Native / Hermes). `@noble/hashes` 1.x captures
+ * `globalThis.crypto` ONCE, when its `crypto.js` is evaluated, so the polyfill
+ * has to be installed before any `@noble/*` module is evaluated. ES imports are
+ * evaluated before the importing module's body, so whatever the polyfill
+ * imports is evaluated first: importing the ROOT entry (which reaches
+ * `@noble/curves` through the envelope signer) let noble capture `undefined`
+ * and broke identity creation on Android.
+ *
+ * This entry therefore reaches no crypto library, no `@oxy.so/*` package and no
+ * third-party module other than the optional `expo-crypto` peer (RN variant
+ * only). `src/__tests__/randomEntry.test.ts` walks its module graph to keep it
+ * that way.
+ */
+
+export { isNodeJS, isReactNative } from './platform/platform';
+export { getRandomBytesRN } from './platform/random';