@oxy.so/core 1.18.1 → 3.0.0

package/dist/esm/api/users.js

@@ -0,0 +1,272 @@
+import { recommendationRequestSchema } from '@oxy.so/contracts';
+import { buildQueryParams } from '../utils/apiUtils.js';
+import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity.js';
+import { OXY_IDENTITY_CACHE_PREFIXES, oxyUserByIdCacheKey } from '../utils/identityCacheSweep.js';
+import { OXY_ACCOUNT_LIST_CACHE_KEY, OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX, oxyAccountDetailCacheKey, } from '../utils/accountCacheSweep.js';
+import { extractErrorStatus } from '../utils/errorUtils.js';
+import { logger } from '../logger/index.js';
+const PROFILE_TTL = 5 * 60 * 1000;
+const SESSION_USER_TTL = 2 * 60 * 1000;
+const ME_TTL = 60 * 1000;
+const SEARCH_TTL = 2 * 60 * 1000;
+/**
+ * Maximum number of ids sent per `POST /users/by-ids` request. Matches the
+ * server-side batch cap; larger inputs are split into chunked calls.
+ */
+const USERS_BY_IDS_CHUNK_SIZE = 100;
+export class UsersApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    // ── Reads ────────────────────────────────────────────────────────────────
+    /**
+     * A user by id. Cached 5 minutes; pass `{ cache: false }` for a
+     * registry-fresh read that neither serves nor overwrites a cached entry.
+     */
+    async get(userId, options) {
+        const user = await this.ctx.request('GET', `/users/${userId}`, undefined, {
+            cache: options?.cache ?? true,
+            cacheTTL: PROFILE_TTL,
+        });
+        return normalizeUserIdentity(user);
+    }
+    /**
+     * Many users by id, one round-trip per chunk of 100 — for hydration call
+     * sites that would otherwise issue one `get` per author.
+     *
+     * Ids are deduplicated and blank ids dropped; the result is unordered (map
+     * by `id`). `/users/by-ids` accepts a service token, a user session or an
+     * anonymous caller and returns the same public payload in every case: on a
+     * server that can mint a service token (`OxyServer`) the chunks go over the
+     * service lane — an anonymous call from a backend is charged to its shared
+     * NAT address's per-IP budget — and everywhere else over the user bearer.
+     *
+     * Chunks are independent: a failed chunk is logged and skipped. Not cached.
+     */
+    async getMany(ids) {
+        const uniqueIds = Array.from(new Set(ids.filter((id) => typeof id === 'string' && id.trim().length > 0)));
+        if (uniqueIds.length === 0)
+            return [];
+        const chunks = [];
+        for (let i = 0; i < uniqueIds.length; i += USERS_BY_IDS_CHUNK_SIZE) {
+            chunks.push(uniqueIds.slice(i, i + USERS_BY_IDS_CHUNK_SIZE));
+        }
+        const service = this.ctx.service?.available ? this.ctx.service : null;
+        const settled = await Promise.all(chunks.map(async (chunk) => {
+            try {
+                const users = service
+                    ? await service.request('POST', '/users/by-ids', { ids: chunk })
+                    : await this.ctx.request('POST', '/users/by-ids', { ids: chunk }, { cache: false });
+                return Array.isArray(users) ? users.map((user) => normalizeUserIdentity(user)) : [];
+            }
+            catch (error) {
+                logger.warn('users.getMany: chunk failed, continuing with remaining chunks', {
+                    method: 'users.getMany',
+                    mode: service ? 'service' : 'user',
+                    chunkSize: chunk.length,
+                    status: extractErrorStatus(error),
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return [];
+            }
+        }));
+        return settled.flat();
+    }
+    /** The signed-in user. Cached 1 minute. */
+    async me() {
+        const user = await this.ctx.request('GET', '/users/me', undefined, { cache: true, cacheTTL: ME_TTL });
+        return normalizeUserIdentity(user);
+    }
+    /** A profile by username. Cached 5 minutes; `{ cache: false }` as in `get`. */
+    async byUsername(username, options) {
+        const user = await this.ctx.request('GET', `/profiles/username/${encodeURIComponent(username)}`, undefined, {
+            cache: options?.cache ?? true,
+            cacheTTL: PROFILE_TTL,
+        });
+        return normalizeUserIdentity(user);
+    }
+    /** The user owning a public key. Public (pre-session): sends no bearer. */
+    async byPublicKey(publicKey) {
+        const user = await this.ctx.request('GET', `/auth/user/${encodeURIComponent(publicKey)}`, undefined, {
+            cache: true,
+            cacheTTL: SESSION_USER_TTL,
+            skipAuth: true,
+        });
+        return normalizeUserIdentity(user);
+    }
+    /** The user a session belongs to. */
+    async bySession(sessionId) {
+        const user = await this.ctx.request('GET', `/session/user/${sessionId}`, undefined, {
+            cache: true,
+            cacheTTL: SESSION_USER_TTL,
+        });
+        return normalizeUserIdentity(user);
+    }
+    /** The users of many sessions in one request; `user` is `null` for a dead session. */
+    async bySessions(sessionIds) {
+        if (!Array.isArray(sessionIds) || sessionIds.length === 0)
+            return [];
+        const unique = Array.from(new Set(sessionIds)).sort();
+        const entries = await this.ctx.request('POST', '/session/users/batch', { sessionIds: unique }, 
+        // A read over POST: sorted ids make the body a stable cache/dedupe key.
+        { cache: true, cacheTTL: SESSION_USER_TTL, deduplicate: true });
+        return entries.map((entry) => ({ ...entry, user: normalizeUserIdentityOrNull(entry.user) }));
+    }
+    /**
+     * Search profiles. Pass `signal` from a search box: every keystroke would
+     * otherwise run a search to completion while holding a request-queue slot.
+     */
+    async search(query, pagination, options) {
+        const response = await this.ctx.request('GET', '/profiles/search', buildQueryParams({ query, ...pagination }), { cache: true, cacheTTL: SEARCH_TTL, signal: options?.signal });
+        if (typeof response !== 'object' || response === null || !Array.isArray(response.data)) {
+            throw new Error('Unexpected search response format');
+        }
+        const limit = pagination?.limit ?? response.data.length;
+        const paginationInfo = response.pagination ?? {
+            total: response.data.length,
+            limit,
+            offset: pagination?.offset ?? 0,
+            hasMore: response.data.length === limit && limit > 0,
+        };
+        return { data: response.data, pagination: paginationInfo };
+    }
+    /**
+     * Resolve a fediverse handle (`@user@mastodon.social`) to an Oxy profile by
+     * WebFinger. `null` when it cannot be resolved — discovery is best-effort.
+     * Cached 5 minutes: the profile carries the viewer-relative `relationship`.
+     */
+    async resolveHandle(handle) {
+        try {
+            const result = await this.ctx.request('GET', '/profiles/resolve', { handle }, {
+                cache: true,
+                cacheTTL: PROFILE_TTL,
+            });
+            return normalizeUserIdentityOrNull(result);
+        }
+        catch (error) {
+            // A 404 (absent) and an upstream failure both return null; the log keeps
+            // them distinguishable without turning expected misses into noise.
+            const status = extractErrorStatus(error);
+            logger.debug(status === 404 ? 'users.resolveHandle: handle not found' : 'users.resolveHandle: discovery failed', {
+                method: 'users.resolveHandle',
+                handle,
+                status,
+                notFound: status === 404,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Find or create a non-local user (federated, agent, automated). All user
+     * creation for external accounts goes through here — services never write
+     * user data directly.
+     */
+    async resolveExternal(input) {
+        return normalizeUserIdentity(await this.ctx.request('PUT', '/users/resolve', input));
+    }
+    /** Profiles similar to `userId`, by co-follower overlap. Cached 5 minutes. */
+    async similar(userId, limitOrPagination) {
+        const pagination = typeof limitOrPagination === 'number' ? { limit: limitOrPagination } : limitOrPagination ?? {};
+        const users = await this.ctx.request('GET', `/profiles/${userId}/similar`, buildQueryParams(pagination), {
+            cache: true,
+            cacheTTL: PROFILE_TTL,
+        });
+        return users.map((user) => normalizeUserIdentity(user));
+    }
+    /**
+     * Profile recommendations. Works signed out (popular public profiles) and
+     * personalises when signed in.
+     *
+     * Only `excludeTypes` / `limit` → the cached `GET /profiles/recommendations`.
+     * Any scored field (`boosts`, `excludeIds`, `signalWeights`, `clientId`,
+     * `offset`) → `POST` with the body validated by `recommendationRequestSchema`
+     * (also cached, keyed on the body).
+     */
+    async recommendations(options) {
+        const scored = Boolean(options &&
+            (options.clientId !== undefined ||
+                options.offset !== undefined ||
+                (options.excludeIds?.length ?? 0) > 0 ||
+                (options.boosts?.length ?? 0) > 0 ||
+                options.signalWeights !== undefined));
+        try {
+            if (scored && options) {
+                const body = recommendationRequestSchema.parse(options);
+                return await this.ctx.request('POST', '/profiles/recommendations', body, { cache: true });
+            }
+            const params = {};
+            if (options?.excludeTypes?.length)
+                params.excludeTypes = options.excludeTypes.join(',');
+            if (options?.limit !== undefined)
+                params.limit = String(options.limit);
+            return await this.ctx.request('GET', '/profiles/recommendations', Object.keys(params).length > 0 ? params : undefined, { cache: true });
+        }
+        catch (error) {
+            logger.debug('users.recommendations: discovery read failed', {
+                method: 'users.recommendations',
+                path: scored ? 'POST' : 'GET',
+                excludeTypes: options?.excludeTypes,
+                status: extractErrorStatus(error),
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    // ── The signed-in user ───────────────────────────────────────────────────
+    /**
+     * Update the signed-in user's profile and settings (`PUT /users/me`) —
+     * including `notificationPreferences`, `userPreferences` and
+     * `themePreference`.
+     *
+     * Every cached read that can return this user goes, in one pass: the
+     * identity reads (the list `identityCacheSweep` owns) and the account forest
+     * (a personal account IS this user, and `AccountNode.account` embeds it).
+     *
+     * A 401 with no token held rejects with `AUTH_REQUIRED_OFFLINE_SESSION: …` so
+     * the caller knows to sync an offline session before retrying.
+     */
+    async updateMe(updates) {
+        let result;
+        try {
+            result = normalizeUserIdentity(await this.ctx.request('PUT', '/users/me', updates, { cache: false }));
+        }
+        catch (error) {
+            if (extractErrorStatus(error) === 401 && !this.ctx.oxy.session.isAuthenticated) {
+                throw new Error('AUTH_REQUIRED_OFFLINE_SESSION: Session needs to be synced to get a token');
+            }
+            throw error;
+        }
+        const id = result?.id;
+        this.ctx.http.invalidateCache({
+            prefixes: [...OXY_IDENTITY_CACHE_PREFIXES, OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX],
+            keys: id
+                ? [oxyUserByIdCacheKey(id), OXY_ACCOUNT_LIST_CACHE_KEY, oxyAccountDetailCacheKey(id)]
+                : [OXY_ACCOUNT_LIST_CACHE_KEY],
+        });
+        return result;
+    }
+    /** Ask for the verified badge. */
+    async requestVerification(reason, evidence) {
+        return this.ctx.request('POST', '/users/verify/request', { reason, evidence }, { cache: false });
+    }
+    /**
+     * Delete the signed-in account permanently. `confirmText` must equal the
+     * username. See {@link DeleteAccountProof} for what confirms it.
+     */
+    async deleteMe(confirmText, proof) {
+        if ('reauth' in proof) {
+            return this.ctx.request('DELETE', '/users/me', { confirmText, reauth: proof.reauth }, { cache: false });
+        }
+        // Loaded on demand: only a Commons account deleting from its own device
+        // needs the key store, and nobody else should ship it.
+        const { KeyManager, SignatureService } = await import('../crypto/internal.js');
+        const publicKey = await KeyManager.getPublicKey();
+        if (!publicKey) {
+            throw new Error('No identity found on this device. Account deletion requires the device that holds your identity key.');
+        }
+        const timestamp = Date.now();
+        const signature = await SignatureService.sign(`delete:${publicKey}:${timestamp}`);
+        return this.ctx.request('DELETE', '/users/me', { signature, timestamp, confirmText, ...(proof.totpCode ? { totpCode: proof.totpCode } : {}) }, { cache: false });
+    }
+}

package/dist/esm/boot/sessionColdBoot.js

@@ -14,7 +14,7 @@
  *   2. `device-secret-mint` (web + native) — the zero-cookie transport: when the
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
- *      navigation) and rotate the secret in-use.
+ *      navigation). The secret is stable across mints.
  *   3. `shared-device-adopt` (native, ACCOUNT mode) — this app has no credential
  *      of its own but a sibling official app already put one in the shared native
  *      slot: adopt it and mint. This is how a newly installed official app joins
@@ -124,7 +124,7 @@ export async function runSessionColdBoot(opts) {
                     return { kind: 'skip' };
                 }
             }
-            oxy.setTokens(persisted.accessToken);
+            oxy.session.setAccessToken(persisted.accessToken);
             return {
                 kind: 'session',
                 session: {
@@ -349,11 +349,11 @@ export async function runSessionColdBoot(opts) {
             id: 'shared-key-signin',
             enabled: () => isNative && !isOffline(),
             run: async () => {
-                const session = await oxy.signInWithSharedIdentity({ requestOptions: { retry: false } });
+                const session = await oxy.auth.signInWithSharedIdentity({ requestOptions: { retry: false } });
                 if (!session?.accessToken) {
                     return { kind: 'skip' };
                 }
-                // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
+                // `verifyChallenge` issues a deviceSecret; persist it so the next
                 // boot can use the faster device-secret-mint lane (sockets + tab-focus
                 // re-mint depend on the credential being in the store).
                 if (session.deviceId && session.deviceSecret) {

package/dist/esm/civic/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@oxy.so/core/civic` — the Oxy ID QR payloads: parse, build, verify.
+ *
+ * Pure functions over the signed public card and the real-life attestation
+ * QR. Their own entry because verifying a card pulls the protocol's signature
+ * code, which an app that never scans a card should not ship.
+ */
+// Verifying a card reaches `@noble/*`; the shim goes first (see `../crypto/polyfill`).
+import '../crypto/polyfill.js';
+export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation } from './payloads.js';

package/dist/esm/civic/payloads.js

@@ -0,0 +1,118 @@
+/** URI scheme/host that introduces a Commons Oxy ID card payload. */
+const CARD_MATCHER = /^oxycommons:\/\/card(?:[/?#]|$)/i;
+/** URI scheme/host that introduces a real-life counterparty attestation payload. */
+const ATTEST_MATCHER = /^oxycommons:\/\/attest(?:[/?#]|$)/i;
+/**
+ * Minimal, allocation-light query-string parser (no `URL` / `URLSearchParams`)
+ * so it runs identically under Hermes and jsdom — mirrors the robustness of the
+ * "Sign in with Oxy" approval-link parser. Shared by every `oxycommons://…`
+ * payload parser in this module.
+ */
+function parseCommonsQuery(raw) {
+    const params = new Map();
+    const qIndex = raw.indexOf('?');
+    if (qIndex < 0)
+        return params;
+    let query = raw.slice(qIndex + 1);
+    const hashIndex = query.indexOf('#');
+    if (hashIndex >= 0)
+        query = query.slice(0, hashIndex);
+    for (const pair of query.split('&')) {
+        if (pair.length === 0)
+            continue;
+        const eq = pair.indexOf('=');
+        const rawKey = eq < 0 ? pair : pair.slice(0, eq);
+        const rawValue = eq < 0 ? '' : pair.slice(eq + 1);
+        try {
+            params.set(decodeURIComponent(rawKey), decodeURIComponent(rawValue.replace(/\+/g, ' ')));
+        }
+        catch {
+            // Malformed percent-encoding — keep the raw token rather than throwing, so
+            // a single bad field doesn't sink an otherwise valid payload.
+            params.set(rawKey, rawValue);
+        }
+    }
+    return params;
+}
+/**
+ * Parse a scanned / deep-linked Oxy ID payload (`oxycommons://card?did=…`) into
+ * the referenced DID. Pure + dependency-free (Hermes-safe, no `URL` global) so
+ * Commons (and any scanner) can reuse it without an OxyServices instance.
+ *
+ * @param raw - The raw scanned string or deep-link URL.
+ * @returns `{ did }` when a usable DID is present; `null` for anything else (a
+ *   non-card scheme, a missing/empty `did`, or non-string input).
+ */
+export function parseIdPayload(raw) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        return null;
+    }
+    const value = raw.trim();
+    if (!CARD_MATCHER.test(value)) {
+        return null;
+    }
+    const did = parseCommonsQuery(value).get('did');
+    if (!did || did.length === 0) {
+        return null;
+    }
+    return { did };
+}
+/**
+ * Parse a scanned / deep-linked real-life-attestation payload
+ * (`oxycommons://attest?subject=…&ctx=…&nonce=…&exp=…`). Pure + dependency-free
+ * (Hermes-safe, no `URL` global), mirroring {@link parseIdPayload}, so Commons
+ * (and any scanner) can reuse it without an OxyServices instance.
+ *
+ * @param raw - The raw scanned string or deep-link URL.
+ * @returns `{ subjectDid, context, nonce, exp }` when the required fields are
+ *   present and `exp` is a positive finite number; `null` otherwise (a non-attest
+ *   scheme, a missing `subject`/`nonce`/`exp`, an unparseable `exp`, or non-string
+ *   input). `context` defaults to `''` when the QR omits `ctx`.
+ */
+export function parseAttestPayload(raw) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        return null;
+    }
+    const value = raw.trim();
+    if (!ATTEST_MATCHER.test(value)) {
+        return null;
+    }
+    const params = parseCommonsQuery(value);
+    const subjectDid = params.get('subject');
+    const nonce = params.get('nonce');
+    const expRaw = params.get('exp');
+    if (!subjectDid || !nonce || expRaw === undefined || expRaw.length === 0) {
+        return null;
+    }
+    const exp = Number(expRaw);
+    if (!Number.isFinite(exp) || exp <= 0) {
+        return null;
+    }
+    return { subjectDid, context: params.get('ctx') ?? '', nonce, exp };
+}
+/**
+ * Verify the Oxy custodial attestation on a public card.
+ *
+ * Re-canonicalizes the received `card` (so the order of the JSON keys on the
+ * wire is irrelevant; `canonicalize` also omits any `undefined`-valued optional
+ * key, matching the server which omits absent keys entirely) and checks the
+ * `ES256K-DER-SHA256` signature against `attestation.publicKey`.
+ *
+ * NEVER throws: `verifySignature` already swallows malformed-input
+ * errors and returns `false`, and an absent attestation short-circuits to
+ * `false`. A pure, reusable helper (Commons can call it on a cached card).
+ *
+ * @param card - The card to verify (exactly as received).
+ * @param attestation - The card's attestation, or `null` (unsigned ⇒ `false`).
+ */
+export async function verifyPublicCardAttestation(card, attestation) {
+    if (!attestation) {
+        return false;
+    }
+    const { signature, publicKey } = attestation;
+    if (!signature || !publicKey) {
+        return false;
+    }
+    const { canonicalize, verifySignature } = await import('../crypto/internal.js');
+    return verifySignature(canonicalize(card), signature, publicKey);
+}

package/dist/esm/client/context.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/crypto/identityLink.js

@@ -1,9 +1,9 @@
 /**
- * The code both screens show while Commons is being linked to a passkey
- * account (ADR 0029 D3): 6 digits derived from the link request and the key
- * Commons signed with. auth.oxy.so derives it from the key the API relayed,
- * Commons from its own; the person checks they match before the passkey is
- * asserted, so a photographed QR cannot slip another key in.
+ * The code both screens show while Commons is being linked to an account
+ * (ADR 0029 D3): 6 digits derived from the link request and the key Commons
+ * signed with. The linking panel derives it from the key the API relayed,
+ * Commons from its own; the person checks they match before the link is
+ * confirmed, so a photographed QR cannot slip another key in.
  */
 import { sha256 } from '@noble/hashes/sha256';
 import { utf8ToBytes } from '@noble/hashes/utils';

package/dist/esm/crypto/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@oxy.so/core/crypto` — the self-custody identity: keys, signatures, the
+ * recovery phrase, and the primitives under them.
+ *
+ * Its own entry so an app that never holds a key never ships secp256k1, bip39
+ * or the AEAD cipher. The `oxy.identity` / `oxy.civic` namespaces load what they
+ * need from here on first use.
+ */
+// MUST stay the first import: `@noble/hashes` captures `globalThis.crypto` when
+// it is evaluated, so the shim has to exist before anything below reaches it.
+import './polyfill.js';
+export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, IdentityUnavailableError, } from './keyManager.js';
+export { readIdentityMarker, updateIdentityMarker } from './identityMarker.js';
+export { SignatureService } from './signatureService.js';
+export { RecoveryPhraseService } from './recoveryPhrase.js';
+// Low-level primitives (encrypted backup, device transfer)
+export { hkdfSha256 } from './kdf.js';
+export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from './aead.js';
+export { deriveSharedSecret } from './ecdh.js';
+// Identity proofs — the one signed format for operations on a personal root
+// (docs/adr/0024-one-oxy-account-root-holders.md D7)
+export { digestIdentityPayload, signIdentityProof } from './identityProof.js';
+// Linking Commons to an account: the code both screens compare (ADR 0029 D3)
+export { deriveIdentityLinkCode } from './identityLink.js';

package/dist/esm/crypto/internal.js

@@ -0,0 +1,19 @@
+/**
+ * The one module the API namespaces load crypto through, with `import()`.
+ *
+ * It installs the polyfill FIRST: on Hermes `@noble/hashes` captures
+ * `globalThis.crypto` when it is evaluated, so a namespace that dynamically
+ * imported `./keyManager` directly — before anything installed the shim —
+ * would hand noble `undefined` and every random draw would throw. Loading
+ * through here makes the order a property of the module graph, not of which
+ * entry an app happened to import first.
+ */
+import './polyfill.js';
+export { KeyManager } from './keyManager.js';
+export { SignatureService } from './signatureService.js';
+export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase.js';
+export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from './aead.js';
+export { digestIdentityPayload, signIdentityProof } from './identityProof.js';
+export { deriveIdentityLinkCode } from './identityLink.js';
+export { solveRegistrationPow } from './registrationPow.js';
+export { canonicalize, signMessage, verifySignature } from '@oxy.so/protocol';

package/dist/esm/crypto/keyManager.js

@@ -186,8 +186,7 @@ async function initSecureStore() {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to load expo-secure-store: ${errorMessage}. ` +
-            'Make sure expo-secure-store is installed and properly configured.');
+        throw new Error(`Failed to load expo-secure-store: ${errorMessage}. Make sure expo-secure-store is installed and properly configured.`);
     }
 }
 /**
@@ -236,6 +235,7 @@ async function getSecureRandomBytes(length) {
         return Crypto.getRandomBytes(length);
     }
 }
+// biome-ignore lint/complexity/noStaticOnlyClass: a public, static-only API surface (`X.method()`) that consumers and tests call and spy on by name.
 export class KeyManager {
     /**
      * Register (or, with `null`, unregister) where the identity's device backup is

package/dist/esm/crypto/polyfill.js

@@ -7,15 +7,16 @@
  * Guard order when installing a `getRandomValues` shim (see bottom of file and
  * {@link cryptoPolyfill}):
  *
- *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browser, Node
+ *   1. A REAL `globalThis.crypto.getRandomValues` — used as-is (browsers, Node
  *      >= 20, modern Hermes). The shim below is only installed when the host is
  *      missing it, so this branch is the install-time gate.
- *   2. Node — backed by the built-in `node:crypto` module (`webcrypto`, else
- *      `randomFillSync`). This is what a Node runtime WITHOUT a global WebCrypto
- *      (Node 18 script entrypoints, some embedded hosts) falls back to.
- *   3. React Native — `expo-crypto.getRandomBytes`, through the dependency-free
+ *   2. React Native — `expo-crypto.getRandomBytes`, through the dependency-free
  *      `@oxy.so/protocol/random` entry.
  *
+ * There is deliberately no `node:crypto` branch: every supported Node has a
+ * global WebCrypto, and a `require('node:crypto')` here made web bundlers ship
+ * Node's crypto, stream and buffer polyfills (~600 KB) to every browser.
+ *
  * # Evaluation order — this module must import NOTHING that can capture the global
  *
  * `@noble/hashes` 1.x reads `globalThis.crypto` exactly once, when its
@@ -31,14 +32,10 @@
  * and `index.ts` imports this file first. `__tests__/polyfillOrder.test.ts`
  * guards both halves.
  *
- * Historically step (2) delegated to `@oxy.so/protocol`'s RN-only
- * `getRandomBytesRN`, which THROWS on Node — so any Node host lacking a global
- * WebCrypto crashed here instead of getting randomness. It is now a proper
- * Node-backed implementation.
  */
 import _cjs_buffer from 'buffer';
 const { Buffer } = _cjs_buffer;
-import { getRandomBytesRN, isNodeJS } from '@oxy.so/protocol/random';
+import { getRandomBytesRN } from '@oxy.so/protocol/random';
 const getGlobalObject = () => {
     if (typeof globalThis !== 'undefined')
         return globalThis;
@@ -55,79 +52,11 @@ const globalObject = getGlobalObject();
 if (!globalObject.Buffer) {
     globalObject.Buffer = Buffer;
 }
-/**
- * Lazily-resolved `node:crypto` module, cached after the first attempt.
- * `undefined` = not tried yet; `null` = tried and unavailable (non-Node host).
- */
-let cachedNodeCrypto;
-/**
- * Synchronously load `node:crypto` on a Node runtime, or `null` elsewhere.
- *
- * Uses a guarded, Node-only `require`. Every runtime that actually reaches this
- * branch has a working CommonJS `require`: `@oxy.so/core` publishes no
- * `"type": "module"`, so Node loads it as CommonJS and the `require` free
- * variable is present. Browsers never reach here (they own `globalThis.crypto`,
- * so this polyfill is never installed) and React Native takes the
- * `getRandomBytesRN` branch — so the `node:crypto` reference is dead code in
- * those bundles, and Expo's Metro resolver shims `node:*` builtins, keeping
- * web/native bundles green.
- */
-function loadNodeCryptoSync() {
-    if (cachedNodeCrypto !== undefined) {
-        return cachedNodeCrypto;
-    }
-    if (typeof require !== 'function') {
-        cachedNodeCrypto = null;
-        return cachedNodeCrypto;
-    }
-    try {
-        cachedNodeCrypto = require('node:crypto');
-    }
-    catch {
-        // No Node crypto (unexpected on a real Node host) — degrade to the next
-        // mechanism rather than crash.
-        cachedNodeCrypto = null;
-    }
-    return cachedNodeCrypto;
-}
-/**
- * Fill `array` with cryptographically-secure random bytes from `node:crypto`.
- * Prefers `webcrypto.getRandomValues`; falls back to `randomFillSync`. Returns
- * `false` when Node crypto is unavailable so the caller can try the next
- * mechanism.
- */
-function fillFromNodeCrypto(array) {
-    const nodeCrypto = loadNodeCryptoSync();
-    if (!nodeCrypto) {
-        return false;
-    }
-    const webcrypto = nodeCrypto.webcrypto;
-    if (webcrypto && typeof webcrypto.getRandomValues === 'function') {
-        try {
-            webcrypto.getRandomValues(array);
-            return true;
-        }
-        catch {
-            // `webcrypto.getRandomValues` rejects non-integer views (Float*Array,
-            // DataView); fall through to `randomFillSync`, which accepts any view.
-        }
-    }
-    if (typeof nodeCrypto.randomFillSync === 'function') {
-        nodeCrypto.randomFillSync(array);
-        return true;
-    }
-    return false;
-}
+/** Minimal structural shape of the parts of `node:crypto` this polyfill uses. */
 const cryptoPolyfill = {
     getRandomValues(array) {
-        // Node: back the CSPRNG with `node:crypto`. This is the path that matters on
-        // Node runtimes shipping WITHOUT a global WebCrypto — where delegating to
-        // the RN-only expo-crypto stub would throw.
-        if (isNodeJS() && fillFromNodeCrypto(array)) {
-            return array;
-        }
-        // React Native (and any non-Node host without WebCrypto): synchronous
-        // expo-crypto via @oxy.so/protocol's RN `platform/random` variant.
+        // React Native / Hermes (the one supported host without WebCrypto):
+        // synchronous expo-crypto via @oxy.so/protocol's RN `platform/random`.
         const bytes = getRandomBytesRN(array.byteLength);
         const uint8View = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
         uint8View.set(bytes);

package/dist/esm/crypto/recoveryPhrase.js

@@ -43,6 +43,7 @@ export const BACKUP_KDF_ENCRYPTION_INFO = 'oxy-backup-encryption-key';
 export const BACKUP_KDF_LOOKUP_INFO = 'oxy-backup-lookup-id';
 /** Byte length of both the derived backup key and the derived lookup id (256-bit). */
 export const BACKUP_MATERIAL_LENGTH = 32;
+// biome-ignore lint/complexity/noStaticOnlyClass: a public, static-only API surface (`X.method()`) that consumers and tests call and spy on by name.
 export class RecoveryPhraseService {
     /**
      * Generate a new identity with a recovery phrase.

package/dist/esm/crypto/registrationPow.js

@@ -1,6 +1,6 @@
 /**
  * Registration proof-of-work — the CLIENT half of the anti-automation nonce
- * `register()` (`mixins/OxyServices.auth.ts`) submits alongside the
+ * `auth.registerKey()` (`api/auth.ts`) submits alongside the
  * registration signature. The message format, difficulty and the full design
  * rationale (why 16 bits, why sequential nonces are fine, what this is and
  * isn't a defense against) live in `@oxy.so/protocol`'s