@oxy.so/protocol 1.0.0

package/dist/cjs/node/rateLimit.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_RATE_LIMIT_ENTRIES = exports.DEFAULT_WRITE_RATE_LIMIT = void 0;
+exports.clientRateLimitKey = clientRateLimitKey;
+exports.createRateLimiter = createRateLimiter;
+const node_crypto_1 = require("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 = (0, node_crypto_1.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.
+ */
+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 (0, node_crypto_1.createHmac)('sha256', CLIENT_KEY_SALT).update(ip).digest('hex').slice(0, 24);
+}
+/** Default budget for owner write routes (generous — single-writer model). */
+exports.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.
+ */
+exports.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).
+ */
+function createRateLimiter(config) {
+    const windows = new Map();
+    const maxEntries = config.maxEntries ?? exports.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/cjs/node/verifyRecord.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyNodeRecordEnvelope = verifyNodeRecordEnvelope;
+const contracts_1 = require("@oxy.so/contracts");
+const recordId_1 = require("../envelope/recordId");
+const sign_1 = require("../envelope/sign");
+/**
+ * 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.
+ */
+async function verifyNodeRecordEnvelope(input) {
+    const parsed = contracts_1.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 (0, sign_1.verifyEnvelopeSignature)(envelope);
+    if (!signatureValid) {
+        return { ok: false, reason: 'bad_signature' };
+    }
+    const recordId = await (0, recordId_1.computeRecordId)(envelope);
+    return { ok: true, envelope, recordId };
+}

package/dist/cjs/platform/crypto.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadNodeCrypto = loadNodeCrypto;
+exports.loadExpoCrypto = loadExpoCrypto;
+exports.loadSecureStore = loadSecureStore;
+exports.loadAsyncStorage = loadAsyncStorage;
+exports.getRandomBytesRN = getRandomBytesRN;
+exports.loadSharedIdentityBridge = loadSharedIdentityBridge;
+const platform_1 = require("./platform");
+// ---------------------------------------------------------------------------
+// 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;
+async function loadNodeCrypto() {
+    if (cachedNodeCrypto) {
+        return cachedNodeCrypto;
+    }
+    cachedNodeCrypto = await Promise.resolve().then(() => __importStar(require('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.`);
+}
+async function loadExpoCrypto() {
+    if ((0, platform_1.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');
+}
+async function loadSecureStore() {
+    throw notReactNativeError('expo-secure-store');
+}
+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.
+ */
+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).
+// ---------------------------------------------------------------------------
+function loadSharedIdentityBridge() {
+    return Promise.resolve(null);
+}

package/dist/cjs/platform/crypto.native.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadNodeCrypto = loadNodeCrypto;
+exports.loadExpoCrypto = loadExpoCrypto;
+exports.loadSecureStore = loadSecureStore;
+exports.loadAsyncStorage = loadAsyncStorage;
+exports.getRandomBytesRN = getRandomBytesRN;
+exports.loadSharedIdentityBridge = loadSharedIdentityBridge;
+const expo_modules_core_1 = require("expo-modules-core");
+let expoCryptoModule = null;
+let expoCryptoError;
+try {
+    expoCryptoModule = require('expo-crypto');
+}
+catch (error) {
+    expoCryptoError = error;
+}
+let secureStoreModule = null;
+let secureStoreError;
+try {
+    secureStoreModule = require('expo-secure-store');
+}
+catch (error) {
+    secureStoreError = error;
+}
+let asyncStorageModule = null;
+let asyncStorageError;
+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');
+    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, capability, cause) {
+    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.
+// ---------------------------------------------------------------------------
+async function loadNodeCrypto() {
+    // 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).
+// ---------------------------------------------------------------------------
+async function loadExpoCrypto() {
+    if (!expoCryptoModule) {
+        throw missingOptionalPeerError('expo-crypto', 'React Native cryptography', expoCryptoError);
+    }
+    return expoCryptoModule;
+}
+// ---------------------------------------------------------------------------
+// expo-secure-store — RN keychain / keystore.
+// ---------------------------------------------------------------------------
+async function loadSecureStore() {
+    if (!secureStoreModule) {
+        throw missingOptionalPeerError('expo-secure-store', 'on-device identity storage', secureStoreError);
+    }
+    return secureStoreModule;
+}
+// ---------------------------------------------------------------------------
+// @react-native-async-storage/async-storage — RN persistent KV storage.
+// ---------------------------------------------------------------------------
+async function loadAsyncStorage() {
+    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()`.
+ */
+function getRandomBytesRN(byteCount) {
+    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 = null;
+function loadSharedIdentityBridge() {
+    if (!sharedIdentityBridgePromise) {
+        sharedIdentityBridgePromise = Promise.resolve().then(() => {
+            const native = (0, expo_modules_core_1.requireOptionalNativeModule)('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),
+                };
+            }
+            return null;
+        });
+    }
+    return sharedIdentityBridgePromise;
+}

package/dist/cjs/platform/expoTypes.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });