@oxyhq/core 12.2.1 → 12.4.0

package/dist/esm/mixins/OxyServices.identityBackup.js

@@ -0,0 +1,158 @@
+import { KeyManager, IdentityAlreadyExistsError } from '../crypto/keyManager.js';
+import { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from '../crypto/recoveryPhrase.js';
+import { encryptAead, decryptAead } from '../crypto/aead.js';
+/** Envelope/KDF version — bump only on a breaking scheme change. */
+const BACKUP_ENVELOPE_VERSION = 1;
+/** The AEAD the backup is sealed with. Pinned so a mismatched decryptor fails loudly. */
+const BACKUP_ALGORITHM = 'xchacha20poly1305';
+/**
+ * Length (hex chars) of the public-key HINT stored/echoed with a backup — enough
+ * to let the owner recognise WHICH identity a backup belongs to, but only a
+ * prefix (the full key is public anyway; a prefix keeps the record minimal).
+ */
+const PUBLIC_KEY_HINT_LENGTH = 16;
+/** Encode bytes as lowercase hex (cross-platform, no Buffer dependency). */
+function toHex(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 1) {
+        out += bytes[i].toString(16).padStart(2, '0');
+    }
+    return out;
+}
+/** Decode a lowercase/uppercase hex string to bytes. Throws on malformed input. */
+function fromHex(hex) {
+    if (hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) {
+        throw new Error('Malformed hex in encrypted backup envelope.');
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i += 1) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/**
+ * The AEAD associated data binds the ciphertext to its `{version, publicKeyHint}`
+ * context: the exact bytes must be reproduced at decrypt time, so a mismatched
+ * version or hint (e.g. an envelope re-stamped by a tamperer) fails the
+ * Poly1305 check. Deterministic: both sides build the SAME object literal, so
+ * `JSON.stringify` yields identical bytes.
+ */
+function buildBackupAad(version, publicKeyHint) {
+    return new TextEncoder().encode(JSON.stringify({ version, publicKeyHint }));
+}
+export function OxyServicesIdentityBackupMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Derive the backup key material from the recovery phrase, encrypt the
+         * identity's `{privateKey, publicKey, createdAt}` with it, and upload the
+         * ciphertext + raw `lookupId` (`POST /identity/backup`, bearer). The server
+         * stores only `sha256(lookupId)` + the ciphertext. Idempotent per user: a
+         * re-upload REPLACES the prior backup (upsert by user id).
+         *
+         * The identity is derived from the PHRASE (not read from SecureStore), so
+         * this works cross-platform and does not require an on-device key.
+         *
+         * @param phrase - The identity's BIP-39 recovery phrase.
+         * @returns The post-write backup status (`{ exists: true, publicKeyHint, createdAt }`).
+         */
+        async createEncryptedBackup(phrase) {
+            try {
+                const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
+                const privateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(phrase);
+                const publicKey = KeyManager.derivePublicKey(privateKey);
+                const createdAt = new Date().toISOString();
+                const publicKeyHint = publicKey.slice(0, PUBLIC_KEY_HINT_LENGTH);
+                const payload = { privateKey, publicKey, createdAt };
+                const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+                const aad = buildBackupAad(BACKUP_ENVELOPE_VERSION, publicKeyHint);
+                const { nonce, ciphertext } = encryptAead(backupKey, plaintext, aad);
+                const body = {
+                    version: BACKUP_ENVELOPE_VERSION,
+                    algorithm: BACKUP_ALGORITHM,
+                    kdfInfo: BACKUP_KDF_ENCRYPTION_INFO,
+                    nonce: toHex(nonce),
+                    ciphertext: toHex(ciphertext),
+                    publicKeyHint,
+                    createdAt,
+                    lookupId,
+                };
+                return await this.makeRequest('POST', '/identity/backup', body, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Whether the authenticated user has a stored encrypted backup, plus the
+         * non-sensitive hint + timestamp when one exists (`GET /identity/backup/status`,
+         * bearer). Returns no ciphertext and no locator.
+         */
+        async getBackupStatus() {
+            try {
+                return await this.makeRequest('GET', '/identity/backup/status', undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Delete the authenticated user's stored backup (`DELETE /identity/backup`,
+         * bearer). Idempotent — deleting a non-existent backup still succeeds.
+         */
+        async deleteBackup() {
+            try {
+                return await this.makeRequest('DELETE', '/identity/backup', undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Restore an identity from its encrypted off-device backup using ONLY the
+         * recovery phrase: re-derive `{backupKey, lookupId}`, fetch the envelope by
+         * `lookupId` (`GET /identity/backup/:lookupId`, PUBLIC — the 256-bit locator
+         * is the protection), decrypt + authenticate locally, then persist the key.
+         *
+         * NATIVE-ONLY persistence: `KeyManager.importKeyPair` throws on web. It also
+         * refuses to clobber a DIFFERENT existing on-device identity unless
+         * `overwrite: true` — the {@link import('../crypto/keyManager').IdentityAlreadyExistsError}
+         * propagates to the caller (never swallowed) so the UI can confirm before
+         * overwriting.
+         *
+         * @param phrase - The identity's BIP-39 recovery phrase.
+         * @param options.overwrite - Replace a different existing on-device identity.
+         * @returns The restored identity's public key.
+         * @throws if the phrase is invalid, no backup exists (404), the ciphertext
+         *   fails authentication (tamper), or an existing identity blocks the import.
+         */
+        async restoreFromEncryptedBackup(phrase, options) {
+            try {
+                const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
+                const envelope = await this.makeRequest('GET', `/identity/backup/${encodeURIComponent(lookupId)}`, undefined, { cache: false });
+                if (envelope.algorithm !== BACKUP_ALGORITHM) {
+                    throw new Error(`Unsupported backup algorithm: ${envelope.algorithm}`);
+                }
+                const aad = buildBackupAad(envelope.version, envelope.publicKeyHint);
+                const plaintext = decryptAead(backupKey, fromHex(envelope.nonce), fromHex(envelope.ciphertext), aad);
+                const payload = JSON.parse(new TextDecoder().decode(plaintext));
+                // Persist the recovered key. Native-only; refuses to clobber a different
+                // identity unless overwrite — the IdentityAlreadyExistsError propagates.
+                return await KeyManager.importKeyPair(payload.privateKey, {
+                    overwrite: options?.overwrite === true,
+                });
+            }
+            catch (error) {
+                // Preserve the typed "an identity already exists" signal so the caller
+                // can prompt for overwrite. `handleError` would flatten it to a generic
+                // Error and lose that discrimination.
+                if (error instanceof IdentityAlreadyExistsError) {
+                    throw error;
+                }
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.user.js

@@ -10,6 +10,12 @@ import { extractErrorStatus } from '../utils/errorUtils.js';
  * server-side batch cap; larger inputs are split into multiple chunked calls.
  */
 const USERS_BY_IDS_CHUNK_SIZE = 100;
+/**
+ * Maximum number of ids sent per `POST /users/follow-status/bulk` request.
+ * Matches the server-side `MAX_BULK_FOLLOW` cap; larger inputs are split into
+ * multiple chunked calls whose result maps are merged.
+ */
+const FOLLOW_STATUS_CHUNK_SIZE = 200;
 export function OxyServicesUserMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -601,6 +607,43 @@ export function OxyServicesUserMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Resolve the viewer's follow status for MANY users in one round-trip per
+         * chunk. Built for list UIs (a page of `FollowButton`s) that would otherwise
+         * fire one `getFollowStatus` per button (the classic N+1).
+         *
+         * Ids are deduplicated and validated (empty/blank ids dropped), split into
+         * chunks of {@link FOLLOW_STATUS_CHUNK_SIZE} (the server's bulk cap), and
+         * POSTed to `/users/follow-status/bulk` as `{ userIds }`. The per-chunk
+         * `{ statuses }` maps are merged into one `Record<string, boolean>` covering
+         * every requested id — ids the viewer does not follow come back `false`.
+         *
+         * Uncached (`{ cache: false }`): the UI store owns follow-status freshness
+         * and writes optimistically on every mutation, so an SDK cache here would
+         * serve a stale status right after a follow/unfollow. An empty/whitespace-
+         * only input resolves immediately with `{}` and performs no network call.
+         */
+        async getFollowStatuses(userIds) {
+            const uniqueIds = Array.from(new Set(userIds.filter((id) => typeof id === 'string' && id.trim().length > 0)));
+            if (uniqueIds.length === 0) {
+                return {};
+            }
+            const chunks = [];
+            for (let i = 0; i < uniqueIds.length; i += FOLLOW_STATUS_CHUNK_SIZE) {
+                chunks.push(uniqueIds.slice(i, i + FOLLOW_STATUS_CHUNK_SIZE));
+            }
+            try {
+                const responses = await Promise.all(chunks.map((chunk) => this.makeRequest('POST', '/users/follow-status/bulk', { userIds: chunk }, { cache: false })));
+                const merged = {};
+                for (const response of responses) {
+                    Object.assign(merged, response?.statuses ?? {});
+                }
+                return merged;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * Get user followers
          */

package/dist/esm/mixins/index.js

@@ -8,6 +8,7 @@ import { OxyServicesBase } from '../OxyServices.base.js';
 import { OxyServicesAuthMixin } from './OxyServices.auth.js';
 import { OxyServicesUserMixin } from './OxyServices.user.js';
 import { OxyServicesIdentityMixin } from './OxyServices.identity.js';
+import { OxyServicesIdentityBackupMixin } from './OxyServices.identityBackup.js';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy.js';
 import { OxyServicesLanguageMixin } from './OxyServices.language.js';
 import { OxyServicesPaymentMixin } from './OxyServices.payment.js';
@@ -46,6 +47,9 @@ const MIXIN_PIPELINE = [
     OxyServicesUserMixin,
     // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping)
     OxyServicesIdentityMixin,
+    // Encrypted off-device identity backup (b3 Feature 1): store/restore an
+    // encrypted copy of the self-custody key, keyed off the recovery phrase.
+    OxyServicesIdentityBackupMixin,
     OxyServicesPrivacyMixin,
     // Feature mixins
     OxyServicesLanguageMixin,

package/dist/esm/utils/validationUtils.js

@@ -36,7 +36,11 @@ export function isValidPassword(password) {
  * Display-name character policy.
  *
  * A clean display name is composed ONLY of:
- *   - letters of any script (`\p{L}`),
+ *   - letters from a curated ALLOWLIST of scripts that real names use
+ *     ({@link DISPLAY_NAME_ALLOWED_SCRIPTS}) — NOT `\p{L}` (letters of ANY
+ *     script), which admits decorative / historic / limited-use scripts whose
+ *     characters are `\p{L}` yet never appear in a real name (e.g. `ᯅ` U+1BC5
+ *     Batak, Runic, Deseret, dingbat letters),
  *   - combining marks / accents (`\p{M}`, e.g. the acute accent in a decomposed
  *     "é"),
  *   - Unicode space separators (`\p{Zs}`: the ASCII space, NBSP, ideographic
@@ -45,32 +49,65 @@ export function isValidPassword(password) {
  *   - the straight apostrophe (`'`, e.g. "O'Brien").
  *
  * Everything else is rejected: emoji (🐧), symbols (⁂ ⏚), `:emoji:` shortcodes,
- * digits, hyphens, dots, control whitespace (tab/newline/CR), and any other
- * punctuation. The allowed set `\p{L}\p{M}\p{Zs}'` explicitly EXCLUDES `<`, `>`,
- * `&`, and `"`, so a value that passes this predicate can never contain an
- * HTML/XSS vector.
+ * digits, hyphens, dots, control whitespace (tab/newline/CR), letters from
+ * non-allowlisted scripts, and any other punctuation. The allowed set never
+ * includes `<`, `>`, `&`, or `"`, so a value that passes this predicate can
+ * never contain an HTML/XSS vector.
  *
- * This is the SINGLE definition of the policy, shared between the API 400-gate
- * (`@oxyhq/api` `displayNameSanitize.ts`) and client-side inline validation
- * (the RN profile editor) so the two can never drift. It is platform-agnostic
+ * The allowlist is expressed with Unicode Script_Extensions (`\p{scx=…}`)
+ * escapes so a letter shared by several scripts (e.g. a Han ideograph used in
+ * both Chinese and Japanese) still matches. It is the set of scripts Unicode
+ * UTS #39 marks "Recommended" for general interchange / identifiers, plus
+ * Cherokee and Mongolian (both in real modern name use). "Common" script is
+ * deliberately EXCLUDED — that is where ASCII digits and general punctuation
+ * live, and this policy excludes those; the space separators, combining marks,
+ * and apostrophe a name needs are added back explicitly. Limited-use / excluded
+ * / historic scripts (Batak, Runic, Deseret, Adlam, …) are simply absent.
+ *
+ * This is the SINGLE definition of the policy: the character-class sources below
+ * are the ONE source of truth, shared between the API strip/gate
+ * (`@oxyhq/api` `displayNameSanitize.ts` builds its global-flag patterns from
+ * them) and client-side inline validation (the RN profile editor via
+ * {@link isValidDisplayName}) so the two can never drift. It is platform-agnostic
  * (no react/react-native/expo).
  */
 /**
- * Single test for the presence of a disallowed character (non-global). The
- * whitespace class is `\p{Zs}` (space separators only), NOT `\s` — the latter
- * would admit tab/newline/carriage return, which break layout and enable
- * multi-line spoofing.
- */
-const DISALLOWED_PROBE = /[^\p{L}\p{M}\p{Zs}']/u;
-/**
- * Single test for the presence of an orphaned combining mark (non-global) — a
- * `\p{M}` not attached to a base letter (string start, whitespace, the
- * apostrophe, or a position vacated by a stripped character). A mark preceded by
- * `\p{L}` (a base letter, e.g. the decomposed accent in "Renée") or by another
- * `\p{M}` (a multi-mark cluster) is NOT matched because the negative lookbehind
- * fails at its position.
- */
-const ORPHANED_MARK_PROBE = /(?<![\p{L}\p{M}])\p{M}/u;
+ * The curated allowlist of Unicode scripts permitted in a display name, as a
+ * character-class body of Script_Extensions (`scx`) property escapes. Ordered by
+ * rough script family for readability; order has no semantic effect.
+ */
+export const DISPLAY_NAME_ALLOWED_SCRIPTS = '\\p{scx=Latin}\\p{scx=Greek}\\p{scx=Cyrillic}\\p{scx=Armenian}' +
+    '\\p{scx=Hebrew}\\p{scx=Arabic}\\p{scx=Thaana}\\p{scx=Devanagari}' +
+    '\\p{scx=Bengali}\\p{scx=Gurmukhi}\\p{scx=Gujarati}\\p{scx=Oriya}' +
+    '\\p{scx=Tamil}\\p{scx=Telugu}\\p{scx=Kannada}\\p{scx=Malayalam}' +
+    '\\p{scx=Sinhala}\\p{scx=Thai}\\p{scx=Lao}\\p{scx=Tibetan}' +
+    '\\p{scx=Myanmar}\\p{scx=Georgian}\\p{scx=Hangul}\\p{scx=Ethiopic}' +
+    '\\p{scx=Cherokee}\\p{scx=Khmer}\\p{scx=Mongolian}\\p{scx=Hiragana}' +
+    '\\p{scx=Katakana}\\p{scx=Bopomofo}\\p{scx=Han}';
+/**
+ * Source of the disallowed-character pattern: the negation of the full allowed
+ * set (allowlisted scripts + combining marks `\p{M}` + space separators `\p{Zs}`
+ * + the straight apostrophe). Consumers compile this with the `u` flag (and `g`
+ * for a global strip). The whitespace class is `\p{Zs}` (space separators only),
+ * NOT `\s` — the latter would admit tab/newline/carriage return, which break
+ * layout and enable multi-line spoofing.
+ */
+export const DISPLAY_NAME_DISALLOWED_SOURCE = `[^${DISPLAY_NAME_ALLOWED_SCRIPTS}\\p{M}\\p{Zs}']`;
+/**
+ * Source of the orphaned combining-mark pattern: a run of `\p{M}` NOT attached
+ * to a base letter (preceded by string start, whitespace, the apostrophe, or a
+ * position vacated by a stripped character). A mark preceded by `\p{L}` (a base
+ * letter, e.g. the decomposed accent in "Renée") or by another `\p{M}` (a
+ * multi-mark cluster) is NOT matched because the negative lookbehind fails at its
+ * position. Used both as a non-global probe (`.test`) and, with the `g` flag, to
+ * strip whole orphaned runs. The lookbehind intentionally still uses the broad
+ * `\p{L}` so that a mark riding on an allowlisted base letter is preserved.
+ */
+export const DISPLAY_NAME_ORPHANED_MARK_SOURCE = '(?<![\\p{L}\\p{M}])\\p{M}+';
+/** Non-global probe for the presence of a disallowed character. */
+const DISALLOWED_PROBE = new RegExp(DISPLAY_NAME_DISALLOWED_SOURCE, 'u');
+/** Non-global probe for the presence of an orphaned combining mark. */
+const ORPHANED_MARK_PROBE = new RegExp(DISPLAY_NAME_ORPHANED_MARK_SOURCE, 'u');
 /**
  * Whether `raw` already satisfies the display-name policy, i.e. it contains no
  * disallowed characters AND no orphaned combining marks. Used to REJECT native