@oxyhq/core 14.0.0 → 15.0.1

package/dist/esm/crypto/recoveryPhrase.js

@@ -5,8 +5,15 @@
  * for backing up and restoring user identities.
  *
  * Note: This module requires the polyfill to be loaded first (done via crypto/index.ts)
+ *
+ * Oxy recovery phrases are English-only, so the English wordlist is imported by
+ * its own subpath. Never reach for a package that exposes its wordlists through
+ * a barrel: `bip39`'s `_wordlists` hard-requires all ten languages, which put
+ * ~265 KB of unreachable wordlists into the initial chunk of every consuming
+ * app. Adding another language means one more subpath import, ideally lazy.
  */
-import * as bip39 from 'bip39';
+import { generateMnemonic, mnemonicToSeed, validateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
 import { KeyManager } from './keyManager.js';
 import { hkdfSha256 } from './kdf.js';
 /**
@@ -48,13 +55,12 @@ export class RecoveryPhraseService {
      */
     static async generateIdentityWithRecovery(options) {
         // Generate 128-bit entropy for 12-word mnemonic
-        const mnemonic = bip39.generateMnemonic(128);
+        const mnemonic = generateMnemonic(wordlist, 128);
         // Derive private key from mnemonic
         // Using the seed directly as the private key (simplified approach)
-        const seed = await bip39.mnemonicToSeed(mnemonic);
+        const seed = await mnemonicToSeed(mnemonic);
         // Use first 32 bytes of seed as private key
-        const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
-        const privateKeyHex = toHex(seedSlice);
+        const privateKeyHex = toHex(seed.subarray(0, 32));
         // Import the derived key pair. KeyManager.importKeyPair will refuse to
         // clobber an existing identity unless overwrite is explicitly requested.
         const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
@@ -73,10 +79,9 @@ export class RecoveryPhraseService {
      */
     static async generateIdentityWithRecovery24(options) {
         // Generate 256-bit entropy for 24-word mnemonic
-        const mnemonic = bip39.generateMnemonic(256);
-        const seed = await bip39.mnemonicToSeed(mnemonic);
-        const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
-        const privateKeyHex = toHex(seedSlice);
+        const mnemonic = generateMnemonic(wordlist, 256);
+        const seed = await mnemonicToSeed(mnemonic);
+        const privateKeyHex = toHex(seed.subarray(0, 32));
         const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
             overwrite: options?.overwrite === true,
         });
@@ -100,10 +105,9 @@ export class RecoveryPhraseService {
      * committed anywhere — if it is lost the account becomes unrecoverable.
      */
     static async derivePendingIdentity() {
-        const mnemonic = bip39.generateMnemonic(128);
-        const seed = await bip39.mnemonicToSeed(mnemonic);
-        const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
-        const privateKey = toHex(seedSlice);
+        const mnemonic = generateMnemonic(wordlist, 128);
+        const seed = await mnemonicToSeed(mnemonic);
+        const privateKey = toHex(seed.subarray(0, 32));
         const publicKey = KeyManager.derivePublicKey(privateKey);
         return {
             phrase: mnemonic,
@@ -122,12 +126,11 @@ export class RecoveryPhraseService {
      */
     static async derivePrivateKeyFromPhrase(phrase) {
         const normalizedPhrase = phrase.trim().toLowerCase();
-        if (!bip39.validateMnemonic(normalizedPhrase)) {
+        if (!validateMnemonic(normalizedPhrase, wordlist)) {
             throw new Error('Invalid recovery phrase');
         }
-        const seed = await bip39.mnemonicToSeed(normalizedPhrase);
-        const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
-        return toHex(seedSlice);
+        const seed = await mnemonicToSeed(normalizedPhrase);
+        return toHex(seed.subarray(0, 32));
     }
     /**
      * Derive the encrypted-backup key material from a recovery phrase (b3 Feature
@@ -148,10 +151,10 @@ export class RecoveryPhraseService {
      */
     static async deriveBackupMaterial(phrase) {
         const normalizedPhrase = phrase.trim().toLowerCase();
-        if (!bip39.validateMnemonic(normalizedPhrase)) {
+        if (!validateMnemonic(normalizedPhrase, wordlist)) {
             throw new Error('Invalid recovery phrase. Please check the words and try again.');
         }
-        const seed = await bip39.mnemonicToSeed(normalizedPhrase);
+        const seed = await mnemonicToSeed(normalizedPhrase);
         const salt = utf8(BACKUP_KDF_SALT);
         const backupKey = hkdfSha256(seed, salt, utf8(BACKUP_KDF_ENCRYPTION_INFO), BACKUP_MATERIAL_LENGTH);
         const lookupId = toHex(hkdfSha256(seed, salt, utf8(BACKUP_KDF_LOOKUP_INFO), BACKUP_MATERIAL_LENGTH));
@@ -168,13 +171,12 @@ export class RecoveryPhraseService {
     static async restoreFromPhrase(phrase, options) {
         // Normalize and validate the phrase
         const normalizedPhrase = phrase.trim().toLowerCase();
-        if (!bip39.validateMnemonic(normalizedPhrase)) {
+        if (!validateMnemonic(normalizedPhrase, wordlist)) {
             throw new Error('Invalid recovery phrase. Please check the words and try again.');
         }
         // Derive the same private key from the mnemonic
-        const seed = await bip39.mnemonicToSeed(normalizedPhrase);
-        const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
-        const privateKeyHex = toHex(seedSlice);
+        const seed = await mnemonicToSeed(normalizedPhrase);
+        const privateKeyHex = toHex(seed.subarray(0, 32));
         // Import and store the key pair
         const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
             overwrite: options?.overwrite === true,
@@ -186,28 +188,26 @@ export class RecoveryPhraseService {
      */
     static validatePhrase(phrase) {
         const normalizedPhrase = phrase.trim().toLowerCase();
-        return bip39.validateMnemonic(normalizedPhrase);
+        return validateMnemonic(normalizedPhrase, wordlist);
     }
     /**
      * Get the word list for autocomplete/validation
      */
     static getWordList() {
-        return bip39.wordlists.english;
+        return wordlist;
     }
     /**
      * Check if a word is valid in the BIP39 word list
      */
     static isValidWord(word) {
-        return bip39.wordlists.english.includes(word.toLowerCase());
+        return wordlist.includes(word.toLowerCase());
     }
     /**
      * Get suggestions for a partial word
      */
     static getSuggestions(partial, limit = 5) {
         const lowerPartial = partial.toLowerCase();
-        return bip39.wordlists.english
-            .filter((word) => word.startsWith(lowerPartial))
-            .slice(0, limit);
+        return wordlist.filter((word) => word.startsWith(lowerPartial)).slice(0, limit);
     }
     /**
      * Derive the public key from a phrase without storing
@@ -215,12 +215,11 @@ export class RecoveryPhraseService {
      */
     static async derivePublicKeyFromPhrase(phrase) {
         const normalizedPhrase = phrase.trim().toLowerCase();
-        if (!bip39.validateMnemonic(normalizedPhrase)) {
+        if (!validateMnemonic(normalizedPhrase, wordlist)) {
             throw new Error('Invalid recovery phrase');
         }
-        const seed = await bip39.mnemonicToSeed(normalizedPhrase);
-        const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
-        const privateKeyHex = toHex(seedSlice);
+        const seed = await mnemonicToSeed(normalizedPhrase);
+        const privateKeyHex = toHex(seed.subarray(0, 32));
         return KeyManager.derivePublicKey(privateKeyHex);
     }
     /**

package/dist/esm/index.js

@@ -40,6 +40,13 @@ export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHa
 export { normalizeProfileLinks } from './utils/profileLinks.js';
 export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts.js';
 // ---------------------------------------------------------------------------
+// Reputation (Oxy Trust: ledger, balances, disputes, rules, influence).
+// The whole type family — the closed value sets, the two balance views and the
+// `isFullReputationBalance` narrowing guard, the ledger/dispute/rule/leaderboard
+// shapes, and the write-endpoint inputs — is owned by `@oxyhq/contracts`, which
+// the API's serializers are validated against. Import them from there.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
 // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping,
 // verified domains). Wire shapes (DidDocument, SignedRecordEnvelope,
 // AuthMethodsResponse, VerifiedDomain, DomainVerificationInstructions,

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

@@ -12,8 +12,14 @@
  * This method carries NO persistence or token-planting side effects of its own;
  * the cold boot / re-mint handler own persistence and `setTokens`, so the same
  * primitive can be reused from either without double-planting.
+ *
+ * `provisionBackgroundCredential` is the mixin's second, adjacent call: it hands
+ * native background code (no JS runtime) its own non-rotating credential so that
+ * code never has to mint from — and therefore never rotates — the device secret
+ * JS depends on.
  */
-import { deviceTokenMintResponseSchema, safeParseContract, } from '@oxyhq/contracts';
+import { deviceBackgroundCredentialResponseSchema, deviceTokenMintResponseSchema, safeParseContract, } from '@oxyhq/contracts';
+import { extractErrorStatus } from '../utils/errorUtils.js';
 /**
  * The server's `401 account_not_on_device` for a PINNED mint: the requested
  * `accountId` is not (or is no longer) a live account of this device session.
@@ -105,5 +111,75 @@ export function OxyServicesDeviceBootMixin(Base) {
                 throw normalized;
             }
         }
+        /**
+         * Provision a NON-rotating background credential for the caller's account on
+         * this device — the credential native background code (an Android widget
+         * worker, which runs with no JS runtime) presents to mint its own access
+         * tokens without any JS involvement.
+         *
+         * It exists precisely so background code never touches the device secret:
+         * `POST /session/device/token` ROTATES that secret on every mint (the
+         * presented one stays valid only for a short grace), so a worker minting
+         * from it would become a second writer of the value JS depends on and could
+         * silently sign the user out. The background credential is a separate,
+         * non-rotating value minted server-side, so the two lanes never contend.
+         *
+         * Bearer required and NO body: the server derives both the `deviceId` and
+         * the account from the validated bearer. This is the only way a background
+         * credential comes into existence, so background code can EXTEND a session
+         * the user established in-app but can never bootstrap one from nothing.
+         *
+         * Unlike the mint above this is NOT a control-plane call — it runs while a
+         * session is already live — so it takes the normal authenticated path: no
+         * `skipAuth` (a 401 should go through the ordinary re-mint lane) and no
+         * `bypassQueue` (nothing in the auth lane is parked awaiting it).
+         *
+         * There is deliberately no JS counterpart that MINTS from the returned
+         * credential: the native side owns that call, and a symmetric-looking JS
+         * method would be dead code plus a second implementation of the failure
+         * rules. The asymmetry is the design.
+         *
+         * **Call this from NATIVE only.** There is no background worker on web to
+         * consume the credential, and handing a browser origin a long-lived
+         * non-rotating secret to persist is strictly weaker than the rotating device
+         * secret it already holds. The 404 degrade below is also native-shaped: a
+         * browser attaches `Origin`, which a server predating this route answers
+         * `403 BAD_ORIGIN` from its router-wide same-site guard rather than 404, so
+         * the quiet degrade would not fire there. A native client sends no `Origin`
+         * and gets the 404. Gate the caller by platform; do not widen the degrade to
+         * 403, which would also swallow a genuine origin misconfiguration.
+         *
+         * That paragraph is LOAD-BEARING, not belt-and-braces: the route sits above
+         * oxy-api's router-wide origin guard (deliberately, so a native client with
+         * no `Origin` is not rejected), so as of this writing NOTHING server-side
+         * refuses a browser caller that presents a valid bearer. Until a server-side
+         * check lands, caller discipline is the only control — which is also why a
+         * doc note cannot be the whole answer to browser XSS minting a long-lived
+         * credential with the victim's bearer.
+         *
+         * @returns the provisioned credential, or `null` when the endpoint is absent
+         * (404). The API deploy leads the SDK release, so a client on a newer SDK
+         * than the server degrades to "no background session" quietly instead of
+         * surfacing an error. The status is read off the RAW rejection because
+         * `handleError` only preserves it for errors carrying `HttpService`'s
+         * annotations.
+         * @throws if the response does not match {@link deviceBackgroundCredentialResponseSchema}.
+         */
+        async provisionBackgroundCredential() {
+            try {
+                const res = await this.makeRequest('POST', '/session/device/background-credential', undefined, { cache: false });
+                const parsed = safeParseContract(deviceBackgroundCredentialResponseSchema, res);
+                if (!parsed) {
+                    throw new Error('session/device/background-credential returned an unexpected response shape');
+                }
+                return parsed;
+            }
+            catch (error) {
+                if (extractErrorStatus(error) === 404) {
+                    return null;
+                }
+                throw this.handleError(error);
+            }
+        }
     };
 }

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

@@ -1,3 +1,5 @@
+import { isFullReputationBalance } from '@oxyhq/contracts';
+import { OxyAuthenticationError } from '../OxyServices.errors.js';
 import { CACHE_TIMES } from './mixinHelpers.js';
 /** Cache-key prefix for every cached `GET /reputation/...` response. */
 const REPUTATION_CACHE_PREFIX = 'GET:/reputation/';
@@ -7,8 +9,16 @@ export function OxyServicesReputationMixin(Base) {
             super(...args);
         }
         /**
-         * Get a user's cached reputation balance — derived totals, per-category
-         * breakdown, trust tier, capped influence weights, and reliability signals.
+         * Get ANY user's reputation balance, in whichever view the server serves the
+         * caller.
+         *
+         * A third party gets `userId`, `total` and `trustTier` and nothing else, so
+         * the return type is a {@link ReputationBalanceView} union: narrow it with
+         * {@link isFullReputationBalance} before touching `breakdown`, `influence`
+         * or `reliability`. To read your OWN balance, call
+         * {@link getMyReputationBalance} instead — it returns the full shape with no
+         * narrowing.
+         *
          * @param userId - The subject user's `_id` or publicKey.
          */
         async getReputationBalance(userId) {
@@ -19,6 +29,37 @@ export function OxyServicesReputationMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Get the SIGNED-IN user's own reputation balance, in full.
+         *
+         * The subject view is the only one carrying `breakdown`, `influence` and
+         * `reliability`, and the subject is the common caller, so this is the
+         * ergonomic path: no id to pass, no narrowing to do.
+         *
+         * Throws rather than returning a half-populated object when the request was
+         * not authenticated as the subject — with no signed-in user, and when the
+         * server answered `200` with the public view anyway (which it does for an
+         * absent or lapsed token, since the endpoint's auth is optional). Both mean
+         * the private blocks are simply absent, and a thrown error is the only
+         * honest report of that.
+         */
+        async getMyReputationBalance() {
+            const userId = this.getCurrentUserId();
+            if (!userId) {
+                throw new OxyAuthenticationError('Reading your own reputation balance requires a signed-in user');
+            }
+            let balance;
+            try {
+                balance = await this.makeRequest('GET', `/reputation/${encodeURIComponent(userId)}/balance`, undefined, { cache: true, cacheTTL: CACHE_TIMES.MEDIUM });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+            if (!isFullReputationBalance(balance)) {
+                throw new OxyAuthenticationError('The reputation balance came back as the public view — the request was not authenticated as its subject');
+            }
+            return balance;
+        }
         /**
          * Get the reputation leaderboard, ordered by lifetime total descending.
          * @param limit - Page size (server-capped).
@@ -189,6 +230,10 @@ export function OxyServicesReputationMixin(Base) {
         /**
          * Force a recompute of a user's balance snapshot from their active ledger
          * (staff only). Invalidates cached reputation reads.
+         *
+         * Staff-gated, so the response is always the full subject view — no
+         * narrowing needed.
+         *
          * @param userId - The subject user's `_id` or publicKey.
          */
         async recalculateReputation(userId) {

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

@@ -217,10 +217,9 @@ export function OxyServicesUserMixin(Base) {
         /**
          * Get profiles similar to a given user, based on co-follower overlap.
          */
-        async getSimilarProfiles(userId, limit) {
-            const params = {};
-            if (limit)
-                params.limit = String(limit);
+        async getSimilarProfiles(userId, limitOrParams) {
+            const pagination = typeof limitOrParams === 'number' ? { limit: limitOrParams } : limitOrParams ?? {};
+            const params = buildQueryParams(pagination);
             const users = await this.makeRequest('GET', `/profiles/${userId}/similar`, params, {
                 cache: true,
                 cacheTTL: 5 * 60 * 1000, // 5 min cache

package/dist/esm/session/accountProjection.js

@@ -17,6 +17,7 @@
  * atomic, so no cross-call current-row reconciliation is needed).
  */
 import { getAccountDisplayName, getAccountFallbackHandle } from '../utils/accountUtils.js';
+import { getNormalizedUserHandle } from '../utils/userHandle.js';
 /**
  * Pure union of device sign-ins and account-graph nodes into the flat
  * {@link SwitchableAccount}[] every switcher renders.
@@ -43,7 +44,9 @@ export function projectSwitchableAccounts(input) {
             kind: opts.kind,
             parentAccountId: opts.parentAccountId,
             callerMembership: opts.callerMembership,
-            displayName: getAccountDisplayName(accountUser, locale),
+            displayName: accountUser.name?.displayName ??
+                getNormalizedUserHandle(accountUser) ??
+                getAccountDisplayName(null, locale),
             // Real email, or the `@handle` fallback (NEVER synthesized).
             email: accountUser.email ?? secondaryHandle,
             avatarUrl: resolveAvatarUrl(accountUser.avatar),