@oxy.so/protocol 1.0.0

package/dist/esm/node/nodeClient.js

@@ -0,0 +1,198 @@
+/**
+ * `NodeClient` — the HTTP client that drives an Oxy-protocol data node's
+ * routes (head / log / records / blobs). It is the OUTBOUND half of the node
+ * protocol: oxy-api uses it to PULL a user's chain back from their node; a
+ * future Mention backend (B3) uses it to drive a node + push records/blobs.
+ *
+ * The client is transport-agnostic — it takes an injected {@link NodeFetch} so
+ * the protocol package never depends on `@oxy.so/core`. Oxy supplies an adapter
+ * over `@oxy.so/core/server`'s `safeFetch` (HTTPS-only, DNS-pinned, private-IP
+ * denylist, bounded redirects); a test supplies an in-process stub. Every
+ * response body is read with a hard byte ceiling, so a node cannot stream an
+ * unbounded body into the caller.
+ */
+import { readBoundedBytes, readBoundedJson, } from './httpFetch.js';
+import { DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_MAX_BLOB_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, NODE_BLOBS_PATH, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, OWNER_AUTH_HEADERS, } from './constants.js';
+/** A non-2xx node response (or a node that returned a malformed body). */
+export class NodeClientError extends Error {
+    constructor(message, status, reason) {
+        super(message);
+        this.status = status;
+        this.reason = reason;
+        this.name = 'NodeClientError';
+    }
+}
+function readError(body) {
+    if (typeof body === 'object' && body !== null && typeof body.error === 'string') {
+        return body.error;
+    }
+    return undefined;
+}
+/**
+ * Trim every trailing slash from a base URL in LINEAR time.
+ *
+ * Replaces an anchored-quantifier regex (`/\/+$/`) whose backtracking is a
+ * polynomial-ReDoS sink on a long all-slash input; a single-pass scan is O(n)
+ * with no ReDoS surface.
+ */
+export function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */) {
+        end -= 1;
+    }
+    return end === value.length ? value : value.slice(0, end);
+}
+export class NodeClient {
+    constructor(options) {
+        this.baseUrl = trimTrailingSlashes(options.baseUrl);
+        this.fetch = options.fetch;
+        this.headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_CLIENT_TIMEOUT_MS;
+        this.maxRedirects = options.maxRedirects ?? DEFAULT_CLIENT_MAX_REDIRECTS;
+        this.headMaxBytes = options.headMaxBytes ?? DEFAULT_HEAD_MAX_BYTES;
+        this.logMaxBytes = options.logMaxBytes ?? DEFAULT_LOG_MAX_BYTES;
+        this.writeResponseMaxBytes = options.writeResponseMaxBytes ?? DEFAULT_WRITE_RESPONSE_MAX_BYTES;
+        this.blobMaxBytes = options.blobMaxBytes ?? DEFAULT_MAX_BLOB_BYTES;
+    }
+    /** Base request options shared by every call (timeout + redirect budget). */
+    init(extra) {
+        return {
+            headersTimeoutMs: this.headersTimeoutMs,
+            maxRedirects: this.maxRedirects,
+            ...extra,
+        };
+    }
+    /** The node's current chain head. Throws {@link NodeClientError} on a non-2xx. */
+    async head() {
+        const res = await this.fetch(`${this.baseUrl}${NODE_HEAD_PATH}`, this.init({ method: 'GET' }));
+        if (res.status < 200 || res.status >= 300) {
+            res.destroy();
+            throw new NodeClientError(`node ${NODE_HEAD_PATH} responded HTTP ${res.status}`, res.status);
+        }
+        const body = await readBoundedJson(res, this.headMaxBytes);
+        const obj = (typeof body === 'object' && body !== null ? body : {});
+        return {
+            seq: typeof obj.seq === 'number' ? obj.seq : null,
+            headRecordId: typeof obj.headRecordId === 'string' ? obj.headRecordId : null,
+            recordCount: typeof obj.recordCount === 'number' ? obj.recordCount : 0,
+        };
+    }
+    /**
+     * One ordered page of the node's log strictly after `sinceSeq` (pass `-1` from
+     * genesis), capped at `limit`. Throws {@link NodeClientError} on a non-2xx or a
+     * response missing the `records` array.
+     */
+    async log(sinceSeq, limit) {
+        // A genesis cursor (`sinceSeq < 0`) is expressed by OMITTING `since` — the
+        // node reads an absent cursor as "from genesis". A negative numeric `since`
+        // is not a valid cursor on the wire (only an absent one, a non-negative seq,
+        // or a recordId), so omitting it is the correct way to request the whole log.
+        const sinceParam = sinceSeq >= 0 ? `since=${encodeURIComponent(String(sinceSeq))}&` : '';
+        const url = `${this.baseUrl}${NODE_LOG_PATH}?${sinceParam}limit=${encodeURIComponent(String(limit))}`;
+        const res = await this.fetch(url, this.init({ method: 'GET' }));
+        if (res.status < 200 || res.status >= 300) {
+            res.destroy();
+            throw new NodeClientError(`node ${NODE_LOG_PATH} responded HTTP ${res.status}`, res.status);
+        }
+        const body = await readBoundedJson(res, this.logMaxBytes);
+        const records = body.records;
+        if (!Array.isArray(records)) {
+            throw new NodeClientError(`node ${NODE_LOG_PATH} returned no records array`, res.status);
+        }
+        const headRaw = body.head;
+        const head = typeof headRaw === 'object' &&
+            headRaw !== null &&
+            typeof headRaw.seq === 'number' &&
+            typeof headRaw.headRecordId === 'string'
+            ? { seq: headRaw.seq, headRecordId: headRaw.headRecordId }
+            : null;
+        return { records, count: records.length, head };
+    }
+    /**
+     * Write a single owner-signed envelope (`POST /records`). Throws
+     * {@link NodeClientError} (carrying the node's `reason`) on any non-2xx — a
+     * chain rejection (`chain_gap`/`chain_fork`/`bad_seq`/`chain_conflict`) or an
+     * authorization failure.
+     */
+    async writeRecord(envelope) {
+        const res = await this.fetch(`${this.baseUrl}${NODE_RECORDS_PATH}`, this.init({
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: Buffer.from(JSON.stringify(envelope), 'utf8'),
+        }));
+        const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+        if (res.status < 200 || res.status >= 300) {
+            const reason = readError(body);
+            throw new NodeClientError(`node ${NODE_RECORDS_PATH} responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);
+        }
+        const obj = body;
+        if (typeof obj.recordId !== 'string' || typeof obj.seq !== 'number') {
+            throw new NodeClientError(`node ${NODE_RECORDS_PATH} returned a malformed write result`, res.status);
+        }
+        return { recordId: obj.recordId, seq: obj.seq };
+    }
+    /**
+     * Push a batch of owner-signed envelopes (`POST /sync/push`). Returns the
+     * node's per-item results. Throws {@link NodeClientError} only on a non-2xx
+     * batch-level failure (`invalid_batch` / `batch_too_large`).
+     */
+    async pushRecords(envelopes) {
+        const res = await this.fetch(`${this.baseUrl}${NODE_SYNC_PUSH_PATH}`, this.init({
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: Buffer.from(JSON.stringify({ records: envelopes }), 'utf8'),
+        }));
+        const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+        if (res.status < 200 || res.status >= 300) {
+            const reason = readError(body);
+            throw new NodeClientError(`node ${NODE_SYNC_PUSH_PATH} responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);
+        }
+        const obj = body;
+        return {
+            accepted: typeof obj.accepted === 'number' ? obj.accepted : 0,
+            results: Array.isArray(obj.results)
+                ? obj.results
+                : [],
+        };
+    }
+    /** Fetch a content-addressed blob. Returns `null` on a 404; throws on other non-2xx. */
+    async getBlob(hash) {
+        const res = await this.fetch(`${this.baseUrl}${NODE_BLOBS_PATH}/${encodeURIComponent(hash)}`, this.init({ method: 'GET' }));
+        if (res.status === 404) {
+            res.destroy();
+            return null;
+        }
+        if (res.status < 200 || res.status >= 300) {
+            res.destroy();
+            throw new NodeClientError(`node ${NODE_BLOBS_PATH}/:hash responded HTTP ${res.status}`, res.status);
+        }
+        return readBoundedBytes(res, this.blobMaxBytes);
+    }
+    /**
+     * Pin a content-addressed blob with an owner-signed authorization
+     * (`PUT /blobs/:hash`). The caller signs the pin (it holds the owner key) and
+     * passes the resulting `{ publicKey, signature, timestamp }`; the client sets
+     * the owner-auth headers. Throws {@link NodeClientError} on a non-2xx.
+     */
+    async putBlob(hash, bytes, auth) {
+        const res = await this.fetch(`${this.baseUrl}${NODE_BLOBS_PATH}/${encodeURIComponent(hash)}`, this.init({
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/octet-stream',
+                [OWNER_AUTH_HEADERS.publicKey]: auth.publicKey,
+                [OWNER_AUTH_HEADERS.signature]: auth.signature,
+                [OWNER_AUTH_HEADERS.timestamp]: String(auth.timestamp),
+            },
+            body: bytes,
+        }));
+        const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+        if (res.status < 200 || res.status >= 300) {
+            const reason = readError(body);
+            throw new NodeClientError(`node ${NODE_BLOBS_PATH}/:hash responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);
+        }
+        const obj = body;
+        if (typeof obj.hash !== 'string' || typeof obj.size !== 'number') {
+            throw new NodeClientError(`node ${NODE_BLOBS_PATH}/:hash returned a malformed pin result`, res.status);
+        }
+        return { hash: obj.hash, size: obj.size };
+    }
+}

package/dist/esm/node/rateLimit.js

@@ -0,0 +1,182 @@
+/**
+ * A small, dependency-free fixed-window per-IP rate limiter for the node app's
+ * owner-authorized write routes.
+ *
+ * The node is a single-writer model (only the owner key may write), so the
+ * limiter is a defence-in-depth budget on the unauthenticated edge — it caps the
+ * request rate BEFORE signature verification so a flood of bogus envelopes can't
+ * pin CPU on crypto. It is intentionally process-local (a single node serves one
+ * owner's repo); there is no shared store to coordinate.
+ *
+ * Fixed-window counting, one budget per client: each key gets `max` requests per
+ * `windowMs`, and the window resets lazily on the first request after it elapses.
+ * The key is a SALTED HASH of the client address, never the address itself — see
+ * {@link clientRateLimitKey}.
+ *
+ * Bounded memory (defence against a key-rotation DoS — spoofed IPs / many DIDs
+ * growing the map without limit → memory exhaustion):
+ *  - An ACTIVE periodic sweep on an `unref()`'d interval deletes every entry
+ *    whose window has fully elapsed, so keys that are never touched again do not
+ *    leak forever (lazy expiry-on-access alone cannot reclaim them). The
+ *    interval is `unref()`'d so it never keeps the node process alive, and
+ *    {@link RateLimiter.stop} clears it for a clean lifecycle teardown.
+ *  - A hard cap on the number of tracked keys ({@link RateLimitConfig.maxEntries})
+ *    evicts the OLDEST window (insertion-order LRU) when exceeded — a synchronous
+ *    backstop against a burst that arrives between sweeps.
+ */
+import { createHmac, randomBytes } from 'node:crypto';
+// The package's `lib` includes `DOM` (the isomorphic root code uses Web Crypto),
+// so the ambient `setInterval` overload TypeScript picks for a bare call is the
+// browser one returning `number` — which has no `.unref()`. This `node/` subpath
+// is Node-only; reach the Node timer globals through their `@types/node`
+// signatures so the handle is correctly `NodeJS.Timeout` (no cast, no shadowing).
+// Resolved at call time (not captured at module load) so test fake-timers that
+// swap the globals still drive the sweep.
+function nodeSetInterval(handler, ms) {
+    const set = globalThis.setInterval;
+    return set(handler, ms);
+}
+function nodeClearInterval(timer) {
+    const clear = globalThis.clearInterval;
+    clear(timer);
+}
+/**
+ * The HMAC key under which client addresses are hashed into rate-limit keys.
+ * 256 CSPRNG bits, minted once when this module is first loaded and held only in
+ * memory — never read from a config, never written anywhere, never sent.
+ *
+ * ## Why the salt is deliberately EPHEMERAL, and what a stable one would cost
+ *
+ * A rate-limit window is short-lived (`windowMs`, seconds to a minute) and this
+ * limiter is process-local by design — a node serves one owner's repo and there
+ * is no shared store to coordinate. So nothing here needs a key to mean the same
+ * thing after a restart, or to mean the same thing on another node. That makes a
+ * per-process salt not merely sufficient but BETTER than a configured one:
+ *
+ *   - there is no value to distribute, so there is nothing for a node operator to
+ *     get wrong, nothing to rotate, and nothing to leak from an env file, a
+ *     process listing or a container image;
+ *   - the mapping dies with the process, so the same address hashes to a
+ *     different key after every restart and the keys correlate to nothing once
+ *     the process exits.
+ *
+ * A stable salt (an env var, a file) would buy exactly one thing this limiter
+ * does not want — a client identifier that survives a restart and can be compared
+ * across nodes — in exchange for a config burden and a secret at rest. That is
+ * the trade, and it is why this is not configurable.
+ *
+ * ## What the hash does and does not buy, stated honestly
+ *
+ * It removes the raw address from the process's data structures: the limiter's
+ * Map holds digests, so an address is no longer sitting in memory as a key for
+ * the lifetime of a window, and nothing downstream can casually read one back
+ * out. What it does NOT claim is secrecy against an attacker who already has the
+ * live process — the salt is in the same heap, and with it the IPv4 space is
+ * enumerable. That is the general reason hashing is not an acceptable AT-REST
+ * form for an address anywhere in Oxy; this value is never at rest.
+ */
+const CLIENT_KEY_SALT = randomBytes(32);
+/**
+ * The rate-limit key for a request: a salted hash of the client address, or the
+ * `'unknown'` sentinel when Express resolved no address at all (a request whose
+ * address is unknown cannot be budgeted individually, so all of them share one
+ * bucket — the same behaviour this limiter has always had).
+ *
+ * Truncated to 96 bits, which keeps a tracked entry to a short string beside its
+ * two numbers (the memory-bounding rationale on {@link RateLimitConfig.maxEntries}
+ * assumes exactly that). At the 10 000-entry cap a collision — two clients
+ * sharing one budget — has probability around 10⁸/2⁹⁷, i.e. never.
+ *
+ * Residue, named rather than left implicit: the address is hashed VERBATIM, so an
+ * IPv6 client that rotates through its /64 still mints a fresh key per address,
+ * exactly as it did before this was hashed. oxy-api's `hashedIpKey` buckets IPv6
+ * to /56 first to close that; doing the same here is a rate-limiting change with
+ * its own reasoning (it makes a whole prefix share one budget) and is deliberately
+ * not folded into a privacy fix.
+ *
+ * Exported for {@link createRateLimiter}'s own tests, not part of
+ * `@oxy.so/protocol/node`'s public surface — it is not re-exported by the barrel.
+ */
+export function clientRateLimitKey(req) {
+    const ip = req.ip;
+    if (!ip) {
+        return 'unknown';
+    }
+    // Single-purpose salt: it derives this key and nothing else, so there is no
+    // second derivation to namespace against (oxy-api's `hashedIpKey` prefixes
+    // `rl|` because its salt is shared with deviceId derivation). A future second
+    // use of this salt would need a namespace, or its own salt.
+    return createHmac('sha256', CLIENT_KEY_SALT).update(ip).digest('hex').slice(0, 24);
+}
+/** Default budget for owner write routes (generous — single-writer model). */
+export const DEFAULT_WRITE_RATE_LIMIT = { windowMs: 60000, max: 60 };
+/**
+ * Default hard cap on tracked keys. Sized so the map's worst-case footprint
+ * stays small (each entry is a short string key + two numbers) while never
+ * evicting a legitimately active key for the single-writer node — the owner
+ * drives traffic from a handful of IPs, far below this ceiling.
+ */
+export const DEFAULT_MAX_RATE_LIMIT_ENTRIES = 10000;
+/**
+ * Build an Express middleware enforcing a fixed-window per-client rate limit.
+ * Exceeding the budget responds `429 { error: 'rate_limited' }` and does not call
+ * `next`. The key is {@link clientRateLimitKey} — a salted hash of Express's
+ * resolved client IP, so no address is held in the tracked map.
+ *
+ * The returned middleware owns a background sweep timer; call {@link RateLimiter.stop}
+ * to release it (e.g. on app shutdown).
+ */
+export function createRateLimiter(config) {
+    const windows = new Map();
+    const maxEntries = config.maxEntries ?? DEFAULT_MAX_RATE_LIMIT_ENTRIES;
+    // Active sweep: delete every entry whose window has fully elapsed. Running on
+    // a timer (rather than only on request arrival) reclaims keys that are never
+    // touched again, so a churn of distinct IPs cannot leak memory once traffic
+    // for those keys stops. One pass per window is sufficient: an entry lives at
+    // most `2 * windowMs` before a sweep removes it.
+    function sweepExpired() {
+        const now = Date.now();
+        for (const [key, counter] of windows) {
+            if (now - counter.start >= config.windowMs) {
+                windows.delete(key);
+            }
+        }
+    }
+    const sweepTimer = nodeSetInterval(sweepExpired, config.windowMs);
+    // Never let the sweep keep the node process alive on its own.
+    sweepTimer.unref();
+    function rateLimit(req, res, next) {
+        const now = Date.now();
+        const key = clientRateLimitKey(req);
+        const counter = windows.get(key);
+        if (!counter || now - counter.start >= config.windowMs) {
+            // Hard cap backstop: if a burst of distinct keys outran the sweep, evict
+            // the oldest-inserted window before admitting a new key. A `Map` preserves
+            // insertion order, so its first key is the oldest tracked entry.
+            if (!counter && windows.size >= maxEntries) {
+                const oldest = windows.keys().next().value;
+                if (oldest !== undefined) {
+                    windows.delete(oldest);
+                }
+            }
+            windows.set(key, { start: now, count: 1 });
+            next();
+            return;
+        }
+        if (counter.count >= config.max) {
+            const retryAfterSec = Math.ceil((counter.start + config.windowMs - now) / 1000);
+            res.setHeader('Retry-After', String(Math.max(retryAfterSec, 1)));
+            res.status(429).json({ error: 'rate_limited' });
+            return;
+        }
+        counter.count += 1;
+        next();
+    }
+    // Attach the lifecycle hook to the middleware, yielding the `RateLimiter`
+    // callable-with-`stop` without a cast.
+    return Object.assign(rateLimit, {
+        stop() {
+            nodeClearInterval(sweepTimer);
+        },
+    });
+}

package/dist/esm/node/verifyRecord.js

@@ -0,0 +1,48 @@
+/**
+ * Record verification for a data node — reuses the protocol envelope primitives
+ * so a record verifies on the node with the EXACT code Oxy uses. No crypto is
+ * re-implemented:
+ *
+ *  - {@link verifyEnvelopeSignature} recomputes the canonical signing input (the
+ *    bytes the signature covers) from the envelope's own fields and checks the
+ *    secp256k1 DER signature against the envelope's embedded `publicKey`.
+ *  - {@link computeRecordId} recomputes `recordId = sha256(signingInput)` — the
+ *    content address used as the chain's `prev` pointer.
+ *
+ * The envelope shape is validated with the shared `signedRecordEnvelopeSchema`.
+ * A node is a v2 hash chain, so only v2 envelopes (carrying
+ * `seq`/`prev`/`collection`/`rkey`) are accepted; v1 singletons have no chain
+ * coordinates.
+ *
+ * Verification here proves the signature is internally consistent with the
+ * embedded `publicKey`. Whether that key is authorized for the node is the OWNER
+ * check (the injected owner-key authority) — on a node the authority is the
+ * configured owner public key, not a DID lookup.
+ */
+import { signedRecordEnvelopeSchema } from '@oxy.so/contracts';
+import { computeRecordId } from '../envelope/recordId.js';
+import { verifyEnvelopeSignature } from '../envelope/sign.js';
+/**
+ * Validate, signature-check, and content-address a candidate signed record for a
+ * v2 hash-chain node.
+ *
+ * On success the parsed envelope and its `recordId` are returned; the caller
+ * (the node app) still enforces owner authority and chain continuity before the
+ * record is appended.
+ */
+export async function verifyNodeRecordEnvelope(input) {
+    const parsed = signedRecordEnvelopeSchema.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: 'invalid_envelope' };
+    }
+    const envelope = parsed.data;
+    if (envelope.version !== 2) {
+        return { ok: false, reason: 'not_v2' };
+    }
+    const signatureValid = await verifyEnvelopeSignature(envelope);
+    if (!signatureValid) {
+        return { ok: false, reason: 'bad_signature' };
+    }
+    const recordId = await computeRecordId(envelope);
+    return { ok: true, envelope, recordId };
+}

package/dist/esm/platform/crypto.js

@@ -0,0 +1,145 @@
+/**
+ * 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.js';
+// ---------------------------------------------------------------------------
+// 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 = null;
+export async function loadNodeCrypto() {
+    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) {
+    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() {
+    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() {
+    throw notReactNativeError('expo-secure-store');
+}
+export async function loadAsyncStorage() {
+    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) {
+    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() {
+    return Promise.resolve(null);
+}