@oxy.so/protocol 1.0.1 → 1.1.1

package/dist/esm/auth/registrationPow.js

@@ -0,0 +1,143 @@
+/**
+ * Registration proof-of-work — the message format and difficulty check a
+ * signup grinds a nonce against, shared verbatim between the client (which
+ * SOLVES it) and the server (which CHECKS it).
+ *
+ * ## Why this exists
+ *
+ * `POST /auth/register` mints an account from nothing more than a freshly
+ * generated secp256k1 keypair and a signature over
+ * `oxy:register:{publicKey}:{timestamp}` — computationally free. A PoW nonce
+ * makes each account cost a small, real amount of CPU time to mint, without
+ * asking a real signer for anything beyond what they already do locally: no
+ * server round trip, no third-party CAPTCHA, no extra user-visible step.
+ *
+ * ## Single source, on purpose
+ *
+ * The client must SOLVE the exact message the server CHECKS, so the message
+ * format and the difficulty threshold live here once, in a package both
+ * `@oxy.so/core` (the client SDK) and the API already depend on for
+ * secp256k1 — see `packages/contracts/src/username.ts`'s docblock for why
+ * this codebase treats "the same rule declared twice" as a bug class, not a
+ * style preference. This file is deliberately CRYPTO-FREE: it is pure
+ * string/bit arithmetic over a caller-supplied hex digest, so it needs no
+ * platform hashing primitive and is trivially unit-testable with fixed
+ * digests. Each side hashes with whatever SHA-256 it already has — Node's
+ * `crypto` server-side (`packages/api/src/controllers/session.controller.ts`),
+ * `@noble/hashes/sha256` client-side (`packages/core/src/crypto/registrationPow.ts`,
+ * already a `@oxy.so/core` dependency — see `crypto/kdf.ts`,
+ * `crypto/identityProof.ts`) — and both produce byte-identical digests over
+ * the same message, because SHA-256 has exactly one correct output for a
+ * given input regardless of implementation.
+ *
+ * ## What this is NOT
+ *
+ * Not a defense against a targeted, patient attacker: nothing stops one from
+ * choosing their OWN `timestamp` a few minutes in the future and grinding the
+ * nonce ahead of time, banking a queue of pre-solved (timestamp, nonce) pairs
+ * to spend inside the 5-minute signature freshness window
+ * (`SignatureService.isTimestampFresh` / `MAX_SIGNATURE_AGE_MS`). Closing that
+ * needs a server-issued, single-use challenge — a real round trip and server
+ * state this deliberately does not add, because the goal here is raising the
+ * COST of unattended bulk signup, not proving liveness. Combined with a
+ * per-IP rate limit on `/auth/register`, it still meaningfully raises the
+ * price of automated mass account creation over today's zero-cost baseline.
+ *
+ * ## Rollout: advisory only, for now
+ *
+ * `POST /auth/register`'s `powNonce` field is OPTIONAL on the wire and the
+ * server does not yet reject a missing or failing one — see the comment at
+ * the check site in `packages/api/src/controllers/session.controller.ts` for
+ * why (every Oxy app consumes the SDK as a published package, not this
+ * monorepo live, so hard-enforcing before every app has picked up a client
+ * new enough to send it would break their signup outright) and exactly what
+ * to change to flip it to a hard 400.
+ */
+/**
+ * Leading zero BITS contributed by one lowercase hex nibble.
+ *
+ * A hex digit is 4 bits: `'0'` contributes all 4, `'8'`–`'f'` (binary `1xxx`)
+ * contribute none because their own leading bit is already `1`. Spelled out
+ * as a table rather than derived with `Math.clz32` so the mapping is checkable
+ * by eye against the difficulty this gates.
+ */
+const NIBBLE_LEADING_ZERO_BITS = {
+    '0': 4,
+    '1': 3,
+    '2': 2,
+    '3': 2,
+    '4': 1,
+    '5': 1,
+    '6': 1,
+    '7': 1,
+    '8': 0,
+    '9': 0,
+    a: 0,
+    b: 0,
+    c: 0,
+    d: 0,
+    e: 0,
+    f: 0,
+};
+/**
+ * The message a registration PoW nonce is grinded against, given the same
+ * `publicKey`/`timestamp` the registration signature (`oxy:register:…`)
+ * already commits to. A distinct prefix (`register-pow`, not `register`) so a
+ * solved PoW nonce can never be replayed as a registration signature input or
+ * vice versa — the two are unrelated preimages even for the same
+ * `publicKey`/`timestamp` pair.
+ */
+export function registrationPowMessage(publicKey, timestamp, nonce) {
+    return `oxy:register-pow:${publicKey}:${timestamp}:${nonce}`;
+}
+/**
+ * The number of leading zero bits {@link meetsRegistrationPowDifficulty}
+ * requires of a solved nonce's digest.
+ *
+ * 16 bits ⇒ 65,536 SHA-256 attempts on average to solve. The client grinds
+ * with `@noble/hashes/sha256` — a pure-JS, SYNCHRONOUS implementation with
+ * "identical behaviour on web, Node, and React Native with zero WebCrypto /
+ * native-module dependency" (its own doc comment in `crypto/kdf.ts`) — so,
+ * unlike a solve loop built on a platform hashing primitive that crosses a
+ * JS↔native bridge per call (`expo-crypto`'s `digestStringAsync`, which this
+ * deliberately avoids for exactly that reason), there is no per-attempt
+ * bridge cost to budget for. The remaining uncertainty is Hermes' lack of a
+ * JIT, which can make a tight pure-JS loop meaningfully slower than V8 — 16
+ * bits is chosen to stay a sub-second grind even under that penalty, without
+ * reaching for a bound high enough to make Hermes specifically the deciding
+ * factor. Retune this constant (it is the only place the number is declared)
+ * once there is real on-device telemetry across the low end of the supported
+ * device range.
+ */
+export const REGISTRATION_POW_DIFFICULTY_BITS = 16;
+/**
+ * Count the leading zero BITS of a lowercase hex digest.
+ *
+ * Stops at the first non-zero nibble — a solved nonce only ever needs to beat
+ * a bound in the tens of bits, so scanning the full 256-bit digest is wasted
+ * work. A character outside `[0-9a-f]` (not a real digest — a caller passed
+ * something malformed) stops the count where it is rather than throwing: the
+ * caller compares the result against a difficulty, and an under-count from bad
+ * input correctly fails that comparison instead of crashing a request path.
+ */
+export function countLeadingZeroBits(hexDigest) {
+    let bits = 0;
+    for (const char of hexDigest.toLowerCase()) {
+        const nibbleZeroBits = NIBBLE_LEADING_ZERO_BITS[char];
+        if (nibbleZeroBits === undefined)
+            break;
+        bits += nibbleZeroBits;
+        if (nibbleZeroBits < 4)
+            break;
+    }
+    return bits;
+}
+/**
+ * Whether a SHA-256 hex digest — of {@link registrationPowMessage} — clears
+ * `difficultyBits` leading zero bits. The one predicate both the client's
+ * solve loop and the server's check call, so neither can drift from what
+ * "solved" means.
+ */
+export function meetsRegistrationPowDifficulty(hexDigest, difficultyBits) {
+    return countLeadingZeroBits(hexDigest) >= difficultyBits;
+}

package/dist/esm/index.js

@@ -26,6 +26,10 @@ export { verifyAndAppend } from './chain/engine.js';
 export { EMPTY_TRANSPARENCY_ROOT, transparencyLeafHash, buildTransparencyTree, buildTransparencyTreeFromHeads, inclusionProof, verifyInclusionProof, } from './transparency/tree.js';
 export { checkpointSigningInput, checkpointHash, signCheckpoint, verifyCheckpointSignature, } from './transparency/checkpoint.js';
 // ---------------------------------------------------------------------------
+// Auth — registration proof-of-work (message format + difficulty check)
+// ---------------------------------------------------------------------------
+export { registrationPowMessage, countLeadingZeroBits, meetsRegistrationPowDifficulty, REGISTRATION_POW_DIFFICULTY_BITS, } from './auth/registrationPow.js';
+// ---------------------------------------------------------------------------
 // Identity — injected verification-method resolution + authorization rule
 // ---------------------------------------------------------------------------
 export { isAuthorizedKey } from './identity/resolver.js';

package/dist/esm/platform/crypto.js

@@ -123,15 +123,10 @@ export async function loadSecureStore() {
 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)');
-}
+// 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.js';
 // ---------------------------------------------------------------------------
 // Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only).
 //

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

@@ -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
@@ -52,14 +52,8 @@
  * so it stays a plain static import.
  */
 import { requireOptionalNativeModule } from 'expo-modules-core';
-let expoCryptoModule = null;
-let expoCryptoError;
-try {
-    expoCryptoModule = require('expo-crypto');
-}
-catch (error) {
-    expoCryptoError = error;
-}
+import { missingOptionalPeerError } from './optionalPeer.js';
+import { requireExpoCrypto } from './random.native.js';
 let secureStoreModule = null;
 let secureStoreError;
 try {
@@ -80,22 +74,6 @@ try {
 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.
 // ---------------------------------------------------------------------------
@@ -116,10 +94,7 @@ export async function loadNodeCrypto() {
 // their compilation (see expoTypes.ts).
 // ---------------------------------------------------------------------------
 export async function loadExpoCrypto() {
-    if (!expoCryptoModule) {
-        throw missingOptionalPeerError('expo-crypto', 'React Native cryptography', expoCryptoError);
-    }
-    return expoCryptoModule;
+    return requireExpoCrypto('React Native cryptography');
 }
 // ---------------------------------------------------------------------------
 // expo-secure-store — RN keychain / keystore.
@@ -142,20 +117,12 @@ export async function loadAsyncStorage() {
     // 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) {
-    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.js';
 // ---------------------------------------------------------------------------
 // Shared identity bridge — `@oxy.so/expo-oxy-identity` (native-only, OPTIONAL).
 //

package/dist/esm/platform/optionalPeer.js

@@ -0,0 +1,19 @@
+/**
+ * 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, 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(' '));
+}

package/dist/esm/platform/random.js

@@ -0,0 +1,15 @@
+/**
+ * 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) {
+    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/dist/esm/platform/random.native.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { missingOptionalPeerError } from './optionalPeer.js';
+let expoCryptoModule = null;
+let expoCryptoError;
+try {
+    expoCryptoModule = require('expo-crypto');
+}
+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) {
+    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) {
+    return requireExpoCrypto('the React Native CSPRNG (crypto.getRandomValues)').getRandomBytes(byteCount);
+}

package/dist/esm/random.js

@@ -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.js';
+export { getRandomBytesRN } from './platform/random.js';