@oxyhq/core 13.2.0 → 15.0.0

package/src/crypto/recoveryPhrase.ts

@@ -5,9 +5,16 @@
  * 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';
 import { hkdfSha256 } from './kdf';
 
@@ -108,15 +115,14 @@ export class RecoveryPhraseService {
     options?: GenerateIdentityOptions,
   ): Promise<RecoveryPhraseResult> {
     // 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.
@@ -140,11 +146,10 @@ export class RecoveryPhraseService {
     options?: GenerateIdentityOptions,
   ): Promise<RecoveryPhraseResult> {
     // Generate 256-bit entropy for 24-word mnemonic
-    const mnemonic = bip39.generateMnemonic(256);
+    const mnemonic = generateMnemonic(wordlist, 256);
 
-    const seed = await bip39.mnemonicToSeed(mnemonic);
-    const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
-    const privateKeyHex = toHex(seedSlice);
+    const seed = await mnemonicToSeed(mnemonic);
+    const privateKeyHex = toHex(seed.subarray(0, 32));
     const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
       overwrite: options?.overwrite === true,
     });
@@ -170,10 +175,9 @@ export class RecoveryPhraseService {
    * committed anywhere — if it is lost the account becomes unrecoverable.
    */
   static async derivePendingIdentity(): Promise<PendingIdentityResult> {
-    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 {
@@ -195,13 +199,12 @@ export class RecoveryPhraseService {
   static async derivePrivateKeyFromPhrase(phrase: string): Promise<string> {
     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));
   }
 
   /**
@@ -224,11 +227,11 @@ export class RecoveryPhraseService {
   static async deriveBackupMaterial(phrase: string): Promise<BackupMaterial> {
     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));
@@ -251,14 +254,13 @@ export class RecoveryPhraseService {
     // 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, {
@@ -273,21 +275,21 @@ export class RecoveryPhraseService {
    */
   static validatePhrase(phrase: string): boolean {
     const normalizedPhrase = phrase.trim().toLowerCase();
-    return bip39.validateMnemonic(normalizedPhrase);
+    return validateMnemonic(normalizedPhrase, wordlist);
   }
 
   /**
    * Get the word list for autocomplete/validation
    */
   static getWordList(): string[] {
-    return bip39.wordlists.english;
+    return wordlist;
   }
 
   /**
    * Check if a word is valid in the BIP39 word list
    */
   static isValidWord(word: string): boolean {
-    return bip39.wordlists.english.includes(word.toLowerCase());
+    return wordlist.includes(word.toLowerCase());
   }
 
   /**
@@ -295,9 +297,7 @@ export class RecoveryPhraseService {
    */
   static getSuggestions(partial: string, limit = 5): string[] {
     const lowerPartial = partial.toLowerCase();
-    return bip39.wordlists.english
-      .filter((word: string) => word.startsWith(lowerPartial))
-      .slice(0, limit);
+    return wordlist.filter((word: string) => word.startsWith(lowerPartial)).slice(0, limit);
   }
 
   /**
@@ -307,14 +307,13 @@ export class RecoveryPhraseService {
   static async derivePublicKeyFromPhrase(phrase: string): Promise<string> {
     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/src/index.ts

@@ -167,31 +167,12 @@ export type {
 export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
 
 // ---------------------------------------------------------------------------
-// Reputation (Oxy Trust: ledger, balances, disputes, rules, influence)
+// 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.
 // ---------------------------------------------------------------------------
-export type {
-    ReputationCategory,
-    TrustTier,
-    ReputationTransactionStatus,
-    ReputationTargetEntityType,
-    ReputationDisputeStatus,
-    ReputationInfluenceContext,
-    ReputationTransaction,
-    ReputationBalanceBreakdown,
-    ReputationInfluence,
-    ReputationReliability,
-    ReputationBalance,
-    ReputationDispute,
-    ReputationRule,
-    ReputationLeaderboardEntry,
-    ReputationInfluenceResult,
-    ReverseReputationTransactionResult,
-    AwardReputationInput,
-    CreateReputationDisputeInput,
-    ResolveReputationDisputeInput,
-    UpsertReputationRuleInput,
-    ReverseReputationTransactionInput,
-} from './mixins/OxyServices.reputation';
 
 // ---------------------------------------------------------------------------
 // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping,

package/src/mixins/OxyServices.deviceBoot.ts

@@ -12,13 +12,21 @@
  * 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 {
+  deviceBackgroundCredentialResponseSchema,
   deviceTokenMintResponseSchema,
   safeParseContract,
+  type DeviceBackgroundCredentialResponse,
   type DeviceTokenMintResponse,
 } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
+import { extractErrorStatus } from '../utils/errorUtils';
 
 /**
  * The server's `401 account_not_on_device` for a PINNED mint: the requested
@@ -120,5 +128,64 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
         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.
+     *
+     * @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(): Promise<DeviceBackgroundCredentialResponse | null> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          '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/src/mixins/OxyServices.identityBackup.ts

@@ -7,7 +7,7 @@
  *
  * Key schedule (from the recovery phrase; see
  * {@link RecoveryPhraseService.deriveBackupMaterial}):
- *   seed      = bip39.mnemonicToSeed(phrase)                    // 64 bytes, UNCHANGED
+ *   seed      = mnemonicToSeed(phrase)                          // 64 bytes, UNCHANGED
  *   backupKey = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-encryption-key')
  *   lookupId  = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-lookup-id')   // hex
  *