@oxy.so/protocol 1.0.0

package/src/platform/crypto.native.ts

@@ -0,0 +1,251 @@
+/**
+ * Platform Crypto / Storage — React Native Variant
+ *
+ * Companion to `./crypto.ts`. See the doc-comment at the top of that file for
+ * the full design.
+ *
+ * Metro auto-selects this file in any non-web build (`preferNativePlatform`
+ * is `true` for iOS / Android, so `*.native.js` shadows `*.js` during
+ * source-extension resolution inside `node_modules/@oxy.so/protocol/dist/`). On
+ * iOS / Android `<base>.ios.js` / `<base>.android.js` would shadow this file
+ * if they existed, but they don't — `.native.js` is the shared RN variant.
+ *
+ *   - The default variant references Node's `'crypto'` and would crash Metro
+ *     if bundled into an RN app.
+ *   - This variant references the RN-only modules (`expo-crypto`,
+ *     `expo-secure-store`, `@react-native-async-storage/async-storage`),
+ *     each behind Metro's optional-dependency mechanism (see below).
+ *
+ * Both variants expose the same surface; importers don't care which one
+ * they got.
+ *
+ * # Why `try { require('literal') } catch` and not a static import?
+ *
+ * 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`
+ * 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
+ * error pointing at a dependency the app never mentions.
+ *
+ * Metro treats a `require()` of a STRING LITERAL that sits inside a `try`
+ * block as an optional dependency: it resolves it when present, and when
+ * absent emits a stub that throws on evaluation instead of failing the build.
+ * The `catch` turns that into a `null` module handle, and the loader below
+ * throws an actionable error naming the missing package the first time the
+ * capability is actually used. Bundle-time hard failure becomes a
+ * capability-scoped runtime failure — which is exactly what "optional peer"
+ * is supposed to mean.
+ *
+ * Two constraints this shape has to respect, both learned the hard way:
+ *
+ *   - The specifier MUST be a literal. A runtime-computed `require(variable)`
+ *     is unresolvable for Metro (that is the bug the shared-identity bridge
+ *     below documents) and silently yields nothing in a consuming repo.
+ *   - The load MUST stay synchronous. `getRandomBytesRN` backs
+ *     `globalThis.crypto.getRandomValues` in `@oxy.so/core`'s polyfill, which
+ *     cannot await anything.
+ *
+ * `expo-modules-core` is a NON-optional peer (every RN app has it via `expo`),
+ * so it stays a plain static import.
+ */
+
+import { requireOptionalNativeModule } from 'expo-modules-core';
+import type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './expoTypes';
+
+// Re-export the interfaces so consumers can import them from the same
+// entry-point they use for the loaders (mirrors the default variant).
+export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge };
+
+// ---------------------------------------------------------------------------
+// Optional peer resolution.
+//
+// `require` is declared locally rather than pulled from `@types/node`'s global:
+// this file only ever runs under Metro, and the local declaration returns
+// `unknown` so every module handle is narrowed explicitly instead of leaking
+// `any` from `NodeRequire`.
+// ---------------------------------------------------------------------------
+
+declare const require: (moduleName: string) => unknown;
+
+/** Persistent KV storage surface used from `@react-native-async-storage/async-storage`. */
+type AsyncStorageLike = {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+  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 {
+  secureStoreModule = require('expo-secure-store') as ExpoSecureStoreLike;
+} catch (error) {
+  secureStoreError = error;
+}
+
+let asyncStorageModule: AsyncStorageLike | null = null;
+let asyncStorageError: unknown;
+try {
+  // Babel's default-import interop unwraps `.default` for us on a static
+  // import; a raw `require` has to do it by hand. The `?? namespace` fallback
+  // covers a host that hands back a real ESM namespace with no `default`.
+  const namespace = require('@react-native-async-storage/async-storage') as AsyncStorageLike & {
+    default?: AsyncStorageLike;
+  };
+  asyncStorageModule = namespace.default ?? namespace;
+} catch (error) {
+  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.
+// ---------------------------------------------------------------------------
+
+export async function loadNodeCrypto(): Promise<typeof import('crypto')> {
+  // Unreachable in practice: every caller gates with `isNodeJS()` before
+  // invoking this. If it somehow does fire, throw immediately with a clear
+  // diagnostic rather than letting Metro / Hermes attempt to find a
+  // non-existent module at runtime.
+  throw new Error(
+    "[oxy.protocol.crypto] Node's built-in 'crypto' module is not available " +
+      'in a React Native runtime. Use the RN-specific helpers ' +
+      '(loadExpoCrypto, getRandomBytesRN) or the Web Crypto API (`globalThis.crypto`).',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// expo-crypto — RN cryptographic primitives.
+//
+// The real module satisfies `ExpoCryptoLike` structurally; the structural
+// interface narrows the surface so consumers never pull expo's own types into
+// their compilation (see expoTypes.ts).
+// ---------------------------------------------------------------------------
+
+export async function loadExpoCrypto(): Promise<ExpoCryptoLike> {
+  if (!expoCryptoModule) {
+    throw missingOptionalPeerError('expo-crypto', 'React Native cryptography', expoCryptoError);
+  }
+  return expoCryptoModule;
+}
+
+// ---------------------------------------------------------------------------
+// expo-secure-store — RN keychain / keystore.
+// ---------------------------------------------------------------------------
+
+export async function loadSecureStore(): Promise<ExpoSecureStoreLike> {
+  if (!secureStoreModule) {
+    throw missingOptionalPeerError(
+      'expo-secure-store',
+      'on-device identity storage',
+      secureStoreError,
+    );
+  }
+  return secureStoreModule;
+}
+
+// ---------------------------------------------------------------------------
+// @react-native-async-storage/async-storage — RN persistent KV storage.
+// ---------------------------------------------------------------------------
+
+export async function loadAsyncStorage(): Promise<{ default: AsyncStorageLike }> {
+  if (!asyncStorageModule) {
+    throw missingOptionalPeerError(
+      '@react-native-async-storage/async-storage',
+      'device/session persistence',
+      asyncStorageError,
+    );
+  }
+  // Mirror the shape callers historically used (`module.default.<method>`)
+  // so the call sites don't have to know whether the underlying module
+  // ships ESM or CJS-with-default.
+  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);
+}
+
+// ---------------------------------------------------------------------------
+// Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only, OPTIONAL).
+//
+// `@oxy.so/expo-oxy-identity` is the in-repo Expo module autolinked into the
+// identity apps (Commons + the reader RPs). We resolve its NATIVE module
+// directly via expo-modules-core's `requireOptionalNativeModule('OxyIdentity')`
+// — a static import Metro always resolves — instead of dynamically importing the
+// module's JS wrapper. A runtime-computed `import(moduleName)` compiled to a
+// `require(variable)` in the CJS build, which Metro cannot resolve in a consuming
+// repo (the bridge silently resolved `null` there — the cross-app SSO bug). Since
+// the native module is what actually holds the shared identity, going through the
+// native registry is both correct and Metro-safe. `requireOptionalNativeModule`
+// returns `null` (never throws) when the module is not autolinked (web, or apps
+// that don't ship it), so `@oxy.so/core`'s `KeyManager` cleanly falls back to its
+// package-private store.
+// ---------------------------------------------------------------------------
+
+let sharedIdentityBridgePromise: Promise<SharedIdentityBridge | null> | null = null;
+
+export function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null> {
+  if (!sharedIdentityBridgePromise) {
+    sharedIdentityBridgePromise = Promise.resolve().then(() => {
+      const native = requireOptionalNativeModule<Partial<SharedIdentityBridge>>('OxyIdentity');
+      if (
+        native &&
+        typeof native.getShared === 'function' &&
+        typeof native.putShared === 'function' &&
+        typeof native.hasShared === 'function' &&
+        typeof native.clearShared === 'function'
+      ) {
+        return {
+          getShared: native.getShared.bind(native),
+          putShared: native.putShared.bind(native),
+          hasShared: native.hasShared.bind(native),
+          clearShared: native.clearShared.bind(native),
+        } satisfies SharedIdentityBridge;
+      }
+      return null;
+    });
+  }
+  return sharedIdentityBridgePromise;
+}

package/src/platform/crypto.ts

@@ -0,0 +1,172 @@
+/**
+ * Platform Crypto / Storage — Default Variant (Node.js, Browser, generic bundlers)
+ *
+ * Provides lazy access to platform-specific crypto and storage modules.
+ *
+ * # Variants
+ *
+ * This module ships in two physical variants on disk, selected per consumer
+ * by the bundler / runtime:
+ *
+ * - `crypto.js`           — this file. Used by Node.js, Vite, webpack,
+ *                           Rollup, esbuild, and anything that does not match
+ *                           Metro's `*.native.js` source-extension preference.
+ * - `crypto.native.js`    — sibling file. Picked up automatically by Metro's
+ *                           resolver (which prefers `*.<platform>.js` and
+ *                           `*.native.js` over plain `*.js` when
+ *                           `preferNativePlatform` is true — Expo sets this for
+ *                           all non-web builds).
+ *
+ * The `package.json#exports` map also declares a `"react-native"` condition
+ * pointing at the same `dist/esm/index.js` entry — that entry transitively
+ * imports `./platform/crypto`, and Metro's per-file source-extension lookup
+ * substitutes the `.native.js` sibling automatically inside `dist/`. The
+ * package's top-level `"react-native"` map additionally pins the built
+ * `platform/crypto.js` (under both `dist/cjs` and `dist/esm`) to its
+ * `crypto.native.js` sibling belt-and-braces. This means consumers never have
+ * to add resolver shims; Metro Just Works.
+ *
+ * Both variants expose the EXACT same public API; importers don't need to know
+ * which one they got. The variant difference is purely about which underlying
+ * native modules each one references:
+ *
+ *   ┌──────────────────┬───────────────────────┬───────────────────────────────┐
+ *   │ Function         │ Default variant       │ React Native variant          │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadNodeCrypto   │ `await import('crypto')` (Node built-in)              │
+ *   │                  │                       │ throws — Node crypto is not   │
+ *   │                  │                       │ available on Hermes/RN        │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadExpoCrypto   │ throws — expo-crypto  │ optional `require('expo-      │
+ *   │                  │ is not part of a      │ crypto')`                     │
+ *   │                  │ Node/Vite bundle      │                               │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadSecureStore  │ throws (web/Node have │ optional `require('expo-      │
+ *   │                  │ their own storage)    │ secure-store')`               │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ loadAsyncStorage │ throws (web/Node have │ optional `require('@react-    │
+ *   │                  │ their own storage)    │ native-async-storage/...')`   │
+ *   ├──────────────────┼───────────────────────┼───────────────────────────────┤
+ *   │ getRandomBytesRN │ throws (RN-only)      │ direct call into expo-crypto  │
+ *   └──────────────────┴───────────────────────┴───────────────────────────────┘
+ *
+ * Crucially, the default variant references ONLY Node's `'crypto'`. It never
+ * mentions `expo-*` or `@react-native-async-storage/*` — so Vite, webpack,
+ * esbuild, Rollup, and Node itself can bundle / require it without ever
+ * attempting to resolve those RN-only packages.
+ *
+ * The React Native variant references ONLY the RN packages, each behind
+ * Metro's optional-dependency mechanism (a literal `require()` inside a `try`)
+ * because they are declared OPTIONAL peer dependencies. It never mentions
+ * `'crypto'` — so Metro and Hermes have nothing to choke on.
+ *
+ * # Why not a single file with dynamic import?
+ *
+ * A previous iteration used a "bundler-opaque" `new Function('s', 'return
+ * import(s)')` trick so a single file could service every platform. It
+ * bundled cleanly on Metro but Hermes refused to PARSE the resulting
+ * `import()` expression inside a Function-constructor body
+ * (`SyntaxError: Invalid expression encountered` at the `(` of `import(`).
+ * The platform-extension split is the only approach that lets each runtime
+ * see a file containing only specifiers it can understand — no tricks, no
+ * runtime parsing risks.
+ */
+
+import { isReactNative } from './platform';
+import type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge } from './expoTypes';
+
+// Re-export the interfaces so consumers can import them from the same
+// entry-point they use for the loaders.
+export type { ExpoCryptoLike, ExpoSecureStoreLike, SharedIdentityBridge };
+
+// ---------------------------------------------------------------------------
+// Node `crypto` — Node built-in
+//
+// `await import('crypto')` here is a real, static-from-tsc's-perspective
+// dynamic import. Node ESM, Vite, webpack, and esbuild all resolve it fine.
+// Metro never sees this file because the `.native.js` sibling shadows
+// it, so Metro never tries to resolve `'crypto'`.
+// ---------------------------------------------------------------------------
+
+let cachedNodeCrypto: typeof import('crypto') | null = null;
+
+export async function loadNodeCrypto(): Promise<typeof import('crypto')> {
+  if (cachedNodeCrypto) {
+    return cachedNodeCrypto;
+  }
+  cachedNodeCrypto = await import('node:crypto');
+  return cachedNodeCrypto;
+}
+
+// ---------------------------------------------------------------------------
+// RN-only modules — never called from this variant.
+//
+// These throw a clear error if anything ever reaches them outside RN. In
+// practice every caller gates with `isReactNative()` before calling, so
+// these are belt-and-braces.
+//
+// Return types use the structural interfaces from expoTypes.ts rather than
+// `typeof import('expo-crypto')` / `typeof import('expo-secure-store')`.
+// This prevents TypeScript from traversing into expo-modules-core under
+// NodeNext module resolution, which would otherwise pollute the global type
+// environment in server/Node consumers (TS2322 on NodeJS.Timeout vs number).
+// ---------------------------------------------------------------------------
+
+function notReactNativeError(module: string): Error {
+  return new Error(
+    `[oxy.protocol.crypto] Tried to load '${module}' 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.`,
+  );
+}
+
+export async function loadExpoCrypto(): Promise<ExpoCryptoLike> {
+  if (isReactNative()) {
+    // Should be unreachable: when running on RN, Metro / the `react-native`
+    // exports condition serves the sibling variant. If we got here, the
+    // package-exports map is misconfigured for this host. Throw with a
+    // helpful diagnostic rather than fall back to a broken dynamic import.
+    throw new Error(
+      '[oxy.protocol.crypto] React Native runtime resolved the default ' +
+        '(non-RN) variant of @oxy.so/protocol/platform/crypto. Check the ' +
+        "consumer's bundler resolution — Metro should pick the sibling " +
+        '.native.js file via package exports.',
+    );
+  }
+  throw notReactNativeError('expo-crypto');
+}
+
+export async function loadSecureStore(): Promise<ExpoSecureStoreLike> {
+  throw notReactNativeError('expo-secure-store');
+}
+
+export async function loadAsyncStorage(): Promise<{
+  default: {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+  };
+}> {
+  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)');
+}
+
+// ---------------------------------------------------------------------------
+// Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only).
+//
+// The default (web / Node) variant has no cross-app identity channel, so this
+// always resolves to `null`. `@oxy.so/core`'s `KeyManager` treats `null` as "no
+// bridge" and falls back to its package-private store — which is correct on web
+// (there is no shared identity there).
+// ---------------------------------------------------------------------------
+
+export function loadSharedIdentityBridge(): Promise<SharedIdentityBridge | null> {
+  return Promise.resolve(null);
+}

package/src/platform/expoTypes.ts

@@ -0,0 +1,99 @@
+/**
+ * Structural interfaces for Expo platform modules.
+ *
+ * These replace `typeof import('expo-crypto')` and
+ * `typeof import('expo-secure-store')` in the built declaration files of
+ * `@oxy.so/protocol` and `@oxy.so/core`.
+ *
+ * ## Why structural interfaces instead of `typeof import('expo-*')`?
+ *
+ * Under NodeNext module resolution (used by `@oxy.so/api` and `@oxy.so/node`),
+ * `expo-crypto` ships with `"exports": {}` (empty exports map). TypeScript
+ * traverses into the package anyway via the `types` field, which transitively
+ * loads `expo-modules-core`. That pollution makes `setInterval`/`setTimeout`
+ * resolve to DOM's `number` return type rather than Node's `NodeJS.Timeout`,
+ * producing ~10 spurious `TS2322` / `TS2339` errors in every consumer that
+ * uses Node timer APIs — none of which reference protocol types at all.
+ *
+ * Structural interfaces break the transitive expo-modules-core dependency
+ * entirely: consumers that don't have Expo installed see clean types, and
+ * the actual RN runtime (which DOES have Expo installed) still works because
+ * the real modules satisfy these interfaces structurally.
+ */
+
+/**
+ * Minimal structural interface for the subset of `expo-crypto` used by
+ * `@oxy.so/protocol` (SHA-256 hashing in RN) and `@oxy.so/core` (key-manager
+ * random-byte generation).
+ *
+ * The real `expo-crypto` namespace satisfies this interface structurally.
+ */
+export interface ExpoCryptoLike {
+  /** Generate `byteCount` cryptographically-random bytes synchronously. */
+  getRandomBytes(byteCount: number): Uint8Array;
+  /** Generate `byteCount` cryptographically-random bytes asynchronously. */
+  getRandomBytesAsync(byteCount: number): Promise<Uint8Array>;
+  /**
+   * Compute a digest of `data` using the given `algorithm` string
+   * (e.g. `CryptoDigestAlgorithm.SHA256`). Used by `recordId.ts` in the
+   * React Native runtime path for content-address hashing.
+   */
+  digestStringAsync(algorithm: string, data: string, options?: unknown): Promise<string>;
+  /**
+   * Algorithm constants (e.g. `CryptoDigestAlgorithm.SHA256 === 'SHA-256'`).
+   * Represented as a plain string-keyed record so the interface does not
+   * depend on the enum definition inside expo-crypto.
+   */
+  readonly CryptoDigestAlgorithm: Record<string, string>;
+}
+
+/**
+ * Minimal structural interface for the subset of `expo-secure-store` used by
+ * `@oxy.so/core` `KeyManager` for on-device identity storage.
+ *
+ * The real `expo-secure-store` namespace satisfies this interface structurally.
+ *
+ * `options` are typed as `object` (rather than the concrete `SecureStoreOptions`
+ * from expo-secure-store) so callers can pass any plain options bag without
+ * importing expo-secure-store's type declarations. TypeScript method bivariance
+ * makes the real `setItemAsync(opts?: SecureStoreOptions)` compatible with this
+ * `setItemAsync(opts?: object)` signature.
+ */
+export interface ExpoSecureStoreLike {
+  setItemAsync(key: string, value: string, options?: object): Promise<void>;
+  getItemAsync(key: string, options?: object): Promise<string | null>;
+  deleteItemAsync(key: string, options?: object): Promise<void>;
+  /**
+   * Keychain / Keystore accessibility constant: item accessible only when the
+   * device is unlocked, and only on this device (no iCloud backup).
+   * Value: `KeychainAccessibilityConstant` (a number alias in expo-secure-store).
+   */
+  readonly WHEN_UNLOCKED_THIS_DEVICE_ONLY: number;
+  /**
+   * Keychain / Keystore accessibility constant: item accessible whenever the
+   * device is unlocked (may be restored to a different device via backup).
+   */
+  readonly WHEN_UNLOCKED: number;
+}
+
+/**
+ * Structural interface for the `@oxy.so/expo-oxy-identity` native module — the
+ * cross-app shared Oxy identity bridge.
+ *
+ * On Android the keypair crosses the process boundary through a
+ * signature-protected `ContentProvider` hosted by Commons; on iOS every method
+ * is a no-op (the Keychain Access Group path in `@oxy.so/core`'s `KeyManager`
+ * owns iOS sharing). Typed structurally here so `@oxy.so/protocol` and
+ * `@oxy.so/core` can reference the bridge without a hard dependency on the
+ * optional native module.
+ */
+export interface SharedIdentityBridge {
+  /** Read the shared keypair, or null when none is available on this device. */
+  getShared(): Promise<{ privateKey: string; publicKey: string } | null>;
+  /** Persist the shared keypair into this app's hardware-backed store (Commons only). */
+  putShared(privateKey: string, publicKey: string): Promise<void>;
+  /** Whether a shared identity is readable on this device. */
+  hasShared(): Promise<boolean>;
+  /** Remove the shared identity from this app's local store (best-effort). */
+  clearShared(): Promise<void>;
+}

package/src/platform/platform.ts

@@ -0,0 +1,31 @@
+/**
+ * Platform Detection — runtime predicates.
+ *
+ * Detects the host runtime WITHOUT importing from 'react-native', so the
+ * protocol's crypto modules can be used in web / Node.js / React Native
+ * environments without bundlers failing on react-native imports.
+ *
+ * Only the two predicates the protocol's platform-crypto loaders need live
+ * here. Richer platform detection (`getPlatformOS`, `isWeb`, `isNative`, …)
+ * is an SDK concern and stays in `@oxy.so/core`.
+ */
+
+/**
+ * Check if running in React Native.
+ *
+ * Selects the React Native crypto variant (`expo-crypto` /
+ * `expo-secure-store` / async-storage) over the Node/web variant.
+ */
+export function isReactNative(): boolean {
+  return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+}
+
+/**
+ * Check if running in Node.js.
+ *
+ * Gates use of Node's built-in `crypto` (the synchronous SHA-256 path and
+ * `randomBytes`) and the `await import('node:crypto')` loader.
+ */
+export function isNodeJS(): boolean {
+  return typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+}