@oxy.so/core 1.18.1 → 3.0.0

package/src/client/context.ts

@@ -0,0 +1,34 @@
+/**
+ * What every API namespace is built on.
+ *
+ * `OxyServices` creates ONE context and hands it to each namespace it creates
+ * (lazily, on first access). It is the namespaces' only way into the client, so
+ * the plumbing they share — the transport, the service-token lane, cross-cache
+ * invalidation — never becomes public surface on `OxyServices` itself.
+ */
+import type { HttpService, RequestOptions } from '../HttpService';
+import type { OxyServices } from '../OxyServices';
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * The service-token lane. Installed only by `OxyServer`
+ * (`@oxy.so/core/server`); `null` on every client. A namespace whose route
+ * accepts a service token as well as a user session (e.g. `users.getMany`)
+ * prefers it when present.
+ */
+export interface ServiceLane {
+  /** Whether a service token can be minted here (a key pair, or workload identity). */
+  readonly available: boolean;
+  request<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions & { actAs?: string }): Promise<T>;
+}
+
+export interface OxyContext {
+  /** The client this context belongs to — for calls into other namespaces. */
+  readonly oxy: OxyServices;
+  readonly http: HttpService;
+  /** `oxy.request`: user bearer, rejects with `OxyApiError`. */
+  request<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions): Promise<T>;
+  /** The service-token lane, or `null` outside a server. */
+  service: ServiceLane | null;
+}

package/src/crypto/identityLink.ts

@@ -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';

package/src/crypto/index.ts

@@ -0,0 +1,39 @@
+/**
+ * `@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';
+
+export {
+    KeyManager,
+    IdentityAlreadyExistsError,
+    IdentityPersistError,
+    IdentityUnavailableError,
+} from './keyManager';
+export type { KeyPair, IdentityStatus, IdentityRecoveryResult } from './keyManager';
+export { readIdentityMarker, updateIdentityMarker } from './identityMarker';
+export type { IdentityMarker } from './identityMarker';
+export type { IdentityDeviceBackupStore } from './deviceBackup';
+export { SignatureService } from './signatureService';
+export type { SignedMessage, AuthChallenge } from './signatureService';
+export { RecoveryPhraseService } from './recoveryPhrase';
+export type { RecoveryPhraseResult, PendingIdentityResult, BackupMaterial } from './recoveryPhrase';
+
+// Low-level primitives (encrypted backup, device transfer)
+export { hkdfSha256 } from './kdf';
+export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from './aead';
+export type { AeadResult } from './aead';
+export { deriveSharedSecret } from './ecdh';
+
+// 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';
+// Linking Commons to an account: the code both screens compare (ADR 0029 D3)
+export { deriveIdentityLinkCode } from './identityLink';

package/src/crypto/internal.ts

@@ -0,0 +1,20 @@
+/**
+ * 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';
+
+export { KeyManager } from './keyManager';
+export { SignatureService } from './signatureService';
+export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase';
+export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH } from './aead';
+export { digestIdentityPayload, signIdentityProof } from './identityProof';
+export { deriveIdentityLinkCode } from './identityLink';
+export { solveRegistrationPow } from './registrationPow';
+export { canonicalize, signMessage, verifySignature } from '@oxy.so/protocol';

package/src/crypto/keyManager.ts

@@ -317,8 +317,7 @@ async function initSecureStore(): Promise<ExpoSecureStoreLike> {
   } 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.',
+      `Failed to load expo-secure-store: ${errorMessage}. Make sure expo-secure-store is installed and properly configured.`,
     );
   }
 }
@@ -378,6 +377,7 @@ export interface KeyPair {
   privateKey: string;
 }
 
+// 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 {
   // In-memory cache for identity state (invalidated on identity changes)
   private static cachedPublicKey: string | null = null;

package/src/crypto/polyfill.ts

@@ -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 { Buffer } from 'buffer';
-import { getRandomBytesRN, isNodeJS } from '@oxy.so/protocol/random';
+import { getRandomBytesRN } from '@oxy.so/protocol/random';
 
 const getGlobalObject = (): typeof globalThis => {
   if (typeof globalThis !== 'undefined') return globalThis;
@@ -60,87 +57,10 @@ type CryptoLike = {
 };
 
 /** Minimal structural shape of the parts of `node:crypto` this polyfill uses. */
-interface NodeCryptoLike {
-  webcrypto?: {
-    getRandomValues?: <T extends ArrayBufferView>(array: T) => T;
-  };
-  randomFillSync?: <T extends ArrayBufferView>(buffer: T) => T;
-}
-
-/**
- * Lazily-resolved `node:crypto` module, cached after the first attempt.
- * `undefined` = not tried yet; `null` = tried and unavailable (non-Node host).
- */
-let cachedNodeCrypto: NodeCryptoLike | null | undefined;
-
-/**
- * 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(): NodeCryptoLike | null {
-  if (cachedNodeCrypto !== undefined) {
-    return cachedNodeCrypto;
-  }
-  if (typeof require !== 'function') {
-    cachedNodeCrypto = null;
-    return cachedNodeCrypto;
-  }
-  try {
-    cachedNodeCrypto = require('node:crypto') as NodeCryptoLike;
-  } 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: ArrayBufferView): boolean {
-  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;
-}
-
 const cryptoPolyfill: CryptoLike = {
   getRandomValues<T extends ArrayBufferView>(array: T): T {
-    // 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/src/crypto/recoveryPhrase.ts

@@ -101,6 +101,7 @@ export interface GenerateIdentityOptions {
   overwrite?: boolean;
 }
 
+// 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/src/crypto/registrationPow.ts

@@ -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

package/src/crypto/signatureService.ts

@@ -35,6 +35,7 @@ export interface AuthChallenge {
   timestamp: number;
 }
 
+// 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 SignatureService {
   /**
    * Generate a random challenge string (for offline use)

package/src/i18n/accountCategoryLabels.ts

@@ -1,12 +1,12 @@
 import type { AccountCategoryId } from '@oxy.so/contracts';
-import enUS from './locales/en-US.json';
+import enUS from './locales/en-US';
 import { translate } from './index';
 
 /**
  * Every account category's English name, keyed by its stable id.
  *
  * **The annotation is the point.** The vocabulary lives in `@oxy.so/contracts`
- * and the names live in `locales/en-US.json`, so they are two lists that must
+ * and the names live in `locales/en-US.ts`, so they are two lists that must
  * agree and nothing but a type can make them. Declaring the JSON node as a
  * TOTAL `Record<AccountCategoryId, string>` turns "somebody added a category at
  * Oxy and nobody wrote its English" into a `TS2741` naming the missing id, at

package/src/i18n/accountRoleLabels.ts

@@ -1,5 +1,5 @@
-import type { AccountRole } from '../mixins/OxyServices.accounts';
-import enUS from './locales/en-US.json';
+import type { AccountRole } from '../api/accounts';
+import enUS from './locales/en-US';
 import { translate } from './index';
 
 /**

package/src/i18n/index.ts

@@ -1,65 +1,116 @@
-import enUS from './locales/en-US.json';
-import esES from './locales/es-ES.json';
-import caES from './locales/ca-ES.json';
-import frFR from './locales/fr-FR.json';
-import deDE from './locales/de-DE.json';
-import itIT from './locales/it-IT.json';
-import ptPT from './locales/pt-PT.json';
-import jaJP from './locales/ja-JP.json';
-import koKR from './locales/ko-KR.json';
-import zhCN from './locales/zh-CN.json';
-import arSA from './locales/ar-SA.json';
+import enUS from './locales/en-US';
 import { getBaseLanguage } from '../utils/languageUtils';
 
-export type LocaleDict = Record<string, any>;
+/** A nested dictionary of strings. */
+export interface LocaleDict {
+  [key: string]: string | LocaleDict | LocaleDict[] | string[];
+}
+
+const FALLBACK = 'en-US';
 
-const DICTS: Record<string, LocaleDict> = {
-  'en': enUS,
-  'en-US': enUS,
-  'es': esES,
-  'es-ES': esES,
-  'ca': caES,
-  'ca-ES': caES,
-  'fr': frFR,
-  'fr-FR': frFR,
-  'de': deDE,
-  'de-DE': deDE,
-  'it': itIT,
-  'it-IT': itIT,
-  'pt': ptPT,
-  'pt-PT': ptPT,
-  'ja': jaJP,
-  'ja-JP': jaJP,
-  'ko': koKR,
-  'ko-KR': koKR,
-  'zh': zhCN,
-  'zh-CN': zhCN,
-  'ar': arSA,
-  'ar-SA': arSA,
+/**
+ * Every dictionary but English loads on demand: an app ships only the languages
+ * its people actually use (~200 KB of the ~285 KB total is non-English). English
+ * is the fallback for every missing key, so it is always present.
+ */
+const LOADERS: Record<string, () => Promise<{ default: LocaleDict }>> = {
+  'es-ES': () => import('./locales/es-ES'),
+  'ca-ES': () => import('./locales/ca-ES'),
+  'fr-FR': () => import('./locales/fr-FR'),
+  'de-DE': () => import('./locales/de-DE'),
+  'it-IT': () => import('./locales/it-IT'),
+  'pt-PT': () => import('./locales/pt-PT'),
+  'ja-JP': () => import('./locales/ja-JP'),
+  'ko-KR': () => import('./locales/ko-KR'),
+  'zh-CN': () => import('./locales/zh-CN'),
+  'ar-SA': () => import('./locales/ar-SA'),
 };
 
-const FALLBACK = 'en-US';
+/** Base subtag → the dictionary that serves it. */
+const ALIASES: Record<string, string> = {
+  en: 'en-US', es: 'es-ES', ca: 'ca-ES', fr: 'fr-FR', de: 'de-DE', it: 'it-IT',
+  pt: 'pt-PT', ja: 'ja-JP', ko: 'ko-KR', zh: 'zh-CN', ar: 'ar-SA',
+};
+
+const DICTS: Record<string, LocaleDict> = { [FALLBACK]: enUS };
+const pending = new Map<string, Promise<boolean>>();
+const listeners = new Set<() => void>();
+let version = 0;
+
+/** The dictionary key serving `locale`, whether or not it is loaded yet. */
+function dictionaryFor(locale: string | undefined): string {
+  if (locale) {
+    if (locale === FALLBACK || LOADERS[locale]) return locale;
+    const base = ALIASES[getBaseLanguage(locale)];
+    if (base) return base;
+  }
+  return FALLBACK;
+}
+
+/**
+ * Load the dictionary serving `locale`. Resolves `true` once it is available
+ * (immediately for English or one already loaded), `false` if it failed to load
+ * — `translate` then keeps serving English.
+ */
+export function loadLocale(locale: string | undefined): Promise<boolean> {
+  const key = dictionaryFor(locale);
+  if (DICTS[key]) return Promise.resolve(true);
+  let load = pending.get(key);
+  if (!load) {
+    load = LOADERS[key]()
+      .then((mod) => {
+        DICTS[key] = mod.default;
+        version++;
+        for (const listener of listeners) listener();
+        return true;
+      })
+      .catch(() => false)
+      .finally(() => pending.delete(key));
+    pending.set(key, load);
+  }
+  return load;
+}
+
+/** Whether the dictionary serving `locale` is loaded (English always is). */
+export function isLocaleLoaded(locale: string | undefined): boolean {
+  return Boolean(DICTS[dictionaryFor(locale)]);
+}
+
+/**
+ * Subscribe to dictionaries finishing loading (for re-rendering once a
+ * language arrives). Returns the unsubscribe. Pair with {@link getLocalesVersion}
+ * in `useSyncExternalStore`.
+ */
+export function subscribeLocales(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Bumps each time a dictionary loads. */
+export function getLocalesVersion(): number {
+  return version;
+}
 
 /**
- * Resolve a locale tag to the key of the dictionary that should serve it.
+ * Resolve a locale tag to the LOADED dictionary that should serve it.
  *
- * Account locales are full BCP-47 tags (e.g. `es-MX`, `pt-BR`, `fr-CA`), but a
- * translation dictionary is shipped per base language. Resolution order:
- *   1. Exact dictionary for the tag (e.g. `es-ES`).
- *   2. Dictionary for the base subtag (e.g. `es-MX` → `es`).
- *   3. The English fallback.
+ * Account locales are full BCP-47 tags (e.g. `es-MX`, `pt-BR`), but a
+ * dictionary is shipped per language: the exact tag, else its base subtag,
+ * else English. A dictionary not loaded yet serves English for now and starts
+ * loading — `subscribeLocales` announces its arrival.
  */
 function resolveLang(locale: string | undefined): string {
-  if (locale) {
-    if (DICTS[locale]) return locale;
-    const base = getBaseLanguage(locale);
-    if (DICTS[base]) return base;
-  }
+  const key = dictionaryFor(locale);
+  if (DICTS[key]) return key;
+  void loadLocale(key);
   return FALLBACK;
 }
 
-function getNested(obj: any, path: string): any {
-  return path.split('.').reduce((acc, key) => (acc && acc[key] != null ? acc[key] : undefined), obj);
+function getNested(obj: unknown, path: string): unknown {
+  return path.split('.').reduce<unknown>(
+    (acc, key) => (acc && typeof acc === 'object' && (acc as Record<string, unknown>)[key] != null ? (acc as Record<string, unknown>)[key] : undefined),
+    obj,
+  );
 }
 
 export function translate(locale: string | undefined, key: string, vars?: Record<string, string | number>): string {
@@ -73,13 +124,13 @@ export function translate(locale: string | undefined, key: string, vars?: Record
     val = getNested(DICTS[FALLBACK], key);
   }
   if (typeof val !== 'string') return key; // last resort: echo the key when truly absent everywhere
+  let text = val;
   if (vars) {
-    Object.keys(vars).forEach(k => {
-      const token = `{{${k}}}`;
-      val = val.replaceAll(token, String(vars[k]));
-    });
+    for (const k of Object.keys(vars)) {
+      text = text.split(`{{${k}}}`).join(String(vars[k]));
+    }
   }
-  return val;
+  return text;
 }
 
 export function hasKey(locale: string | undefined, key: string): boolean {