@oxyhq/core 1.11.11 → 1.11.13

package/src/crypto/polyfill.ts

@@ -5,10 +5,13 @@
  * across all platforms (Node.js, Browser, React Native).
  *
  * - Browser/Node.js: Uses native crypto
- * - React Native: Falls back to expo-crypto if native crypto unavailable
+ * - React Native: Uses expo-crypto (statically imported via the
+ *   per-platform `platformCrypto` module — see that file's doc-comment for
+ *   how platform routing works).
  */
 
 import { Buffer } from 'buffer';
+import { getRandomBytesRN } from '../utils/platformCrypto';
 
 const getGlobalObject = (): typeof globalThis => {
   if (typeof globalThis !== 'undefined') return globalThis;
@@ -29,39 +32,19 @@ type CryptoLike = {
   getRandomValues: <T extends ArrayBufferView>(array: T) => T;
 };
 
-// Cache for expo-crypto module (lazy loaded only in React Native)
-let expoCryptoModule: { getRandomBytes: (count: number) => Uint8Array } | null = null;
-let expoCryptoLoadPromise: Promise<void> | null = null;
-
 /**
- * Eagerly start loading expo-crypto. The module is cached once resolved so
- * the synchronous getRandomValues shim can read from it immediately.
- * Uses dynamic import with variable indirection to prevent ESM bundlers
- * (Vite, webpack) from statically resolving the specifier.
+ * Synchronous random-bytes shim. On RN, this delegates to
+ * `expo-crypto.getRandomBytes` (statically imported by the RN variant of
+ * `platformCrypto`, so available without any async warm-up). On Node /
+ * browser, this throws — but is never called there because both platforms
+ * already provide `globalThis.crypto.getRandomValues` natively.
  */
-function startExpoCryptoLoad(): void {
-  if (expoCryptoLoadPromise) return;
-  expoCryptoLoadPromise = (async () => {
-    try {
-      const moduleName = 'expo-crypto';
-      expoCryptoModule = await import(moduleName);
-    } catch {
-      // expo-crypto not available — expected in non-RN environments
-    }
-  })();
-}
-
 function getRandomBytesSync(byteCount: number): Uint8Array {
-  // Kick off loading if not already started (should have been started at module init)
-  startExpoCryptoLoad();
-  if (expoCryptoModule) {
-    return expoCryptoModule.getRandomBytes(byteCount);
-  }
-  throw new Error(
-    'No crypto.getRandomValues implementation available. ' +
-    'In React Native, install expo-crypto. ' +
-    'If expo-crypto is installed, ensure the polyfill module is imported early enough for the async load to complete.'
-  );
+  // `getRandomBytesRN` throws on non-RN platforms. That's fine: this
+  // function is only ever called as a fallback when the native
+  // `globalThis.crypto.getRandomValues` is missing, which on a normal
+  // Node/browser host never happens.
+  return getRandomBytesRN(byteCount);
 }
 
 const cryptoPolyfill: CryptoLike = {
@@ -75,11 +58,8 @@ const cryptoPolyfill: CryptoLike = {
 
 // Only polyfill if crypto or crypto.getRandomValues is not available
 if (typeof globalObject.crypto === 'undefined') {
-  // Start loading expo-crypto eagerly so it is ready by the time getRandomValues is called
-  startExpoCryptoLoad();
   (globalObject as unknown as { crypto: CryptoLike }).crypto = cryptoPolyfill;
 } else if (typeof globalObject.crypto.getRandomValues !== 'function') {
-  startExpoCryptoLoad();
   (globalObject.crypto as CryptoLike).getRandomValues = cryptoPolyfill.getRandomValues;
 }
 

package/src/crypto/recoveryPhrase.ts

@@ -28,25 +28,48 @@ export interface RecoveryPhraseResult {
   publicKey: string;
 }
 
+export interface GenerateIdentityOptions {
+  /**
+   * Pass `true` to allow overwriting an existing on-device identity.
+   *
+   * Defaults to `false`. When false, this method throws
+   * `IdentityAlreadyExistsError` if a complete identity already exists,
+   * preventing accidental account loss. UI flows MUST only set this to
+   * `true` after explicitly confirming the user has saved their previous
+   * recovery phrase (or has otherwise been warned).
+   */
+  overwrite?: boolean;
+}
+
 export class RecoveryPhraseService {
   /**
-   * Generate a new identity with a recovery phrase
-   * Returns the mnemonic phrase (should only be shown once to the user)
+   * Generate a new identity with a recovery phrase.
+   * The mnemonic phrase MUST be shown to the user exactly once after this
+   * call resolves — if it is lost, the account becomes unrecoverable.
+   *
+   * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+   *
+   * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
    */
-  static async generateIdentityWithRecovery(): Promise<RecoveryPhraseResult> {
+  static async generateIdentityWithRecovery(
+    options?: GenerateIdentityOptions,
+  ): Promise<RecoveryPhraseResult> {
     // Generate 128-bit entropy for 12-word mnemonic
     const mnemonic = bip39.generateMnemonic(128);
-    
+
     // Derive private key from mnemonic
     // Using the seed directly as the private key (simplified approach)
     const seed = await bip39.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);
-    
-    // Import the derived key pair
-    const publicKey = await KeyManager.importKeyPair(privateKeyHex);
+
+    // 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, {
+      overwrite: options?.overwrite === true,
+    });
 
     return {
       phrase: mnemonic,
@@ -56,16 +79,22 @@ export class RecoveryPhraseService {
   }
 
   /**
-   * Generate a 24-word recovery phrase for higher security
+   * Generate a 24-word recovery phrase for higher security.
+   *
+   * Same overwrite-protection semantics as `generateIdentityWithRecovery`.
    */
-  static async generateIdentityWithRecovery24(): Promise<RecoveryPhraseResult> {
+  static async generateIdentityWithRecovery24(
+    options?: GenerateIdentityOptions,
+  ): Promise<RecoveryPhraseResult> {
     // 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 publicKey = await KeyManager.importKeyPair(privateKeyHex);
+    const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
+      overwrite: options?.overwrite === true,
+    });
 
     return {
       phrase: mnemonic,
@@ -75,12 +104,20 @@ export class RecoveryPhraseService {
   }
 
   /**
-   * Restore an identity from a recovery phrase
+   * Restore an identity from a recovery phrase.
+   *
+   * Refuses to overwrite a DIFFERENT existing identity unless
+   * `options.overwrite === true`. Re-importing the same phrase that
+   * matches the current identity is always allowed (it's a no-op refresh
+   * of the backup record).
    */
-  static async restoreFromPhrase(phrase: string): Promise<string> {
+  static async restoreFromPhrase(
+    phrase: string,
+    options?: GenerateIdentityOptions,
+  ): Promise<string> {
     // Normalize and validate the phrase
     const normalizedPhrase = phrase.trim().toLowerCase();
-    
+
     if (!bip39.validateMnemonic(normalizedPhrase)) {
       throw new Error('Invalid recovery phrase. Please check the words and try again.');
     }
@@ -89,9 +126,11 @@ export class RecoveryPhraseService {
     const seed = await bip39.mnemonicToSeed(normalizedPhrase);
     const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
     const privateKeyHex = toHex(seedSlice);
-    
+
     // Import and store the key pair
-    const publicKey = await KeyManager.importKeyPair(privateKeyHex);
+    const publicKey = await KeyManager.importKeyPair(privateKeyHex, {
+      overwrite: options?.overwrite === true,
+    });
 
     return publicKey;
   }

package/src/crypto/signatureService.ts

@@ -8,44 +8,32 @@
 import { ec as EC } from 'elliptic';
 import { KeyManager } from './keyManager';
 import { isReactNative, isNodeJS } from '../utils/platform';
-
-// Lazy import for expo-crypto
-let ExpoCrypto: typeof import('expo-crypto') | null = null;
+import { loadExpoCrypto, loadNodeCrypto } from '../utils/platformCrypto';
+import { logger } from '../utils/loggerUtils';
+import { isDev } from '../shared/utils/debugUtils';
 
 const ec = new EC('secp256k1');
 
-/**
- * Initialize expo-crypto module
- */
-async function initExpoCrypto(): Promise<typeof import('expo-crypto')> {
-  if (!ExpoCrypto) {
-    // Variable indirection prevents bundlers (Vite, webpack) from statically resolving this
-    const moduleName = 'expo-crypto';
-    ExpoCrypto = await import(moduleName);
-  }
-  return ExpoCrypto!;
-}
-
 /**
  * Compute SHA-256 hash of a string
  */
 async function sha256(message: string): Promise<string> {
   // In React Native, use expo-crypto
   if (isReactNative()) {
-    const Crypto = await initExpoCrypto();
+    const Crypto = await loadExpoCrypto();
     return Crypto.digestStringAsync(
       Crypto.CryptoDigestAlgorithm.SHA256,
       message
     );
   }
 
-  // In Node.js, use Node's crypto module
   if (isNodeJS()) {
     try {
-      const nodeCrypto = await import('crypto');
+      const nodeCrypto = await loadNodeCrypto();
       return nodeCrypto.createHash('sha256').update(message).digest('hex');
-    } catch {
-      // Fall through to Web Crypto API
+    } catch (error) {
+      // Node crypto failed to load — log and fall through to Web Crypto API
+      logger.warn('[oxy.crypto] Node crypto unavailable, falling back to Web Crypto', { component: 'SignatureService' }, error);
     }
   }
 
@@ -78,22 +66,20 @@ export class SignatureService {
   static async generateChallenge(): Promise<string> {
     // In React Native, use expo-crypto
     if (isReactNative()) {
-      const Crypto = await initExpoCrypto();
+      const Crypto = await loadExpoCrypto();
       const randomBytes = await Crypto.getRandomBytesAsync(32);
       return Array.from(new Uint8Array(randomBytes))
         .map((b) => b.toString(16).padStart(2, '0'))
         .join('');
     }
 
-    // In Node.js, use Node's crypto module
-    // Variable indirection prevents bundlers (Vite, webpack) from statically resolving this
     if (isNodeJS()) {
       try {
-        const cryptoModuleName = 'crypto';
-        const nodeCrypto = await import(cryptoModuleName);
+        const nodeCrypto = await loadNodeCrypto();
         return nodeCrypto.randomBytes(32).toString('hex');
-      } catch {
-        // Fall through to Web Crypto API
+      } catch (error) {
+        // Node crypto failed to load — log and fall through to Web Crypto API
+        logger.warn('[oxy.crypto] Node crypto unavailable, falling back to Web Crypto', { component: 'SignatureService' }, error);
       }
     }
 
@@ -140,13 +126,20 @@ export class SignatureService {
 
   /**
    * Verify a signature against a message and public key
+   *
+   * Returns false on any error (invalid signature, malformed input, etc.).
+   * Errors are logged at debug level so they're available when troubleshooting
+   * signature mismatches but don't surface to the caller.
    */
   static async verify(message: string, signature: string, publicKey: string): Promise<boolean> {
     try {
       const key = ec.keyFromPublic(publicKey, 'hex');
       const messageHash = await sha256(message);
       return key.verify(messageHash, signature);
-    } catch {
+    } catch (error) {
+      if (isDev()) {
+        logger.debug('[oxy.crypto] verify() returned false', { component: 'SignatureService' }, error);
+      }
       return false;
     }
   }
@@ -172,7 +165,10 @@ export class SignatureService {
       const key = ec.keyFromPublic(publicKey, 'hex');
       const messageHash = crypto.createHash('sha256').update(message).digest('hex');
       return key.verify(messageHash, signature);
-    } catch {
+    } catch (error) {
+      if (isDev()) {
+        logger.debug('[oxy.crypto] verifySync() returned false', { component: 'SignatureService' }, error);
+      }
       return false;
     }
   }

package/src/i18n/locales/en-US.json

@@ -655,6 +655,21 @@
     "confirms": {
       "removeAvatar": "Remove your profile picture?"
     },
+    "crop": {
+      "title": "Crop avatar",
+      "subtitle": "Pinch to zoom, drag to position",
+      "noImage": "No image to crop",
+      "reset": "Reset",
+      "resetToCenter": "Reset to center",
+      "confirm": "Use photo",
+      "cancel": "Cancel",
+      "saving": "Saving…",
+      "helper": "The cropped circle is what will appear on your profile. Pinch to zoom, drag to position.",
+      "zoom": "{{value}}×",
+      "a11yImage": "Crop preview. Pinch to zoom and drag to reposition the image.",
+      "a11yReset": "Reset crop to default position",
+      "a11yResetAnnouncement": "Crop reset"
+    },
     "toasts": {
       "profileUpdated": "Profile updated successfully",
       "updateFailed": "Failed to update profile",
@@ -664,7 +679,10 @@
       "avatarSelected": "Avatar selected",
       "avatarUpdated": "Avatar updated",
       "updateAvatarFailed": "Failed to update avatar",
-      "noActiveSession": "No active session"
+      "noActiveSession": "No active session",
+      "cropMeasureFailed": "Could not measure the image",
+      "cropNotReady": "Image not ready yet",
+      "cropFailed": "Failed to crop image"
     }
   },
   "accountOverview": {
@@ -1046,6 +1064,8 @@
     "save": "Save",
     "saved": "Saved successfully",
     "saving": "Saving...",
+    "unnamed": "Unnamed",
+    "accountFallback": "Account {{handle}}",
     "links": {
       "recoverAccount": "Recover your account",
       "signUp": "Sign Up"
@@ -1308,9 +1328,34 @@
     "loadingMore": "Loading more...",
     "loadingPhotoLayout": "Loading photo layout...",
     "uploading": "Uploading",
+    "upload": "Upload",
+    "uploadPhoto": "Upload Photo",
     "uploadPhotos": "Upload Photos",
     "uploadFiles": "Upload Files",
     "clearSearch": "Clear Search",
+    "choosePhoto": "Choose Photo",
+    "done": "Done",
+    "doneWithCount": "Done ({{count}})",
+    "photoPicker": {
+      "emptyTitle": "No photos yet",
+      "emptySubtitle": "Upload from your device to get started"
+    },
+    "a11y": {
+      "viewAll": "Show all files",
+      "viewPhotos": "Show photos only",
+      "viewVideos": "Show videos only",
+      "viewDocuments": "Show documents only",
+      "viewAudio": "Show audio only",
+      "sortBy": "Sort by {{field}}, {{order}}",
+      "uploadFile": "Upload file from device",
+      "uploadFromDevice": "Upload photo from device",
+      "photoCellSelected": "Photo {{name}}, selected",
+      "photoCellUnselected": "Photo {{name}}, not selected",
+      "selectionCount": "{{count}} photo selected",
+      "selectionCount_plural": "{{count}} photos selected",
+      "cancelPicker": "Cancel photo selection",
+      "confirmSelection": "Confirm selection"
+    },
     "emptyPhotos": {
       "title": "No Photos Yet",
       "ownDescription": "Upload photos to get started. You can select multiple photos at once.",

package/src/i18n/locales/es-ES.json

@@ -241,6 +241,21 @@
     "confirms": {
       "removeAvatar": "¿Eliminar tu foto de perfil?"
     },
+    "crop": {
+      "title": "Recortar avatar",
+      "subtitle": "Pellizca para acercar, arrastra para colocar",
+      "noImage": "No hay imagen para recortar",
+      "reset": "Restablecer",
+      "resetToCenter": "Restablecer al centro",
+      "confirm": "Usar foto",
+      "cancel": "Cancelar",
+      "saving": "Guardando…",
+      "helper": "El círculo recortado es lo que aparecerá en tu perfil. Pellizca para acercar, arrastra para colocar.",
+      "zoom": "{{value}}×",
+      "a11yImage": "Vista previa del recorte. Pellizca para acercar y arrastra para reposicionar la imagen.",
+      "a11yReset": "Restablecer el recorte a la posición predeterminada",
+      "a11yResetAnnouncement": "Recorte restablecido"
+    },
     "toasts": {
       "profileUpdated": "Perfil actualizado correctamente",
       "updateFailed": "Error al actualizar el perfil",
@@ -250,7 +265,10 @@
       "avatarSelected": "Avatar seleccionado",
       "avatarUpdated": "Avatar actualizado",
       "updateAvatarFailed": "Error al actualizar el avatar",
-      "noActiveSession": "No hay sesión activa"
+      "noActiveSession": "No hay sesión activa",
+      "cropMeasureFailed": "No se pudo medir la imagen",
+      "cropNotReady": "La imagen aún no está lista",
+      "cropFailed": "No se pudo recortar la imagen"
     }
   },
   "common": {
@@ -270,6 +288,8 @@
     "save": "Guardar",
     "saved": "Guardado correctamente",
     "saving": "Guardando...",
+    "unnamed": "Sin nombre",
+    "accountFallback": "Cuenta {{handle}}",
     "links": {
       "recoverAccount": "Recuperar tu cuenta",
       "signUp": "Registrarse"
@@ -1296,9 +1316,34 @@
     "loadingMore": "Cargando más...",
     "loadingPhotoLayout": "Cargando diseño de fotos...",
     "uploading": "Subiendo",
+    "upload": "Subir",
+    "uploadPhoto": "Subir foto",
     "uploadPhotos": "Subir fotos",
     "uploadFiles": "Subir archivos",
     "clearSearch": "Limpiar búsqueda",
+    "choosePhoto": "Elegir foto",
+    "done": "Listo",
+    "doneWithCount": "Listo ({{count}})",
+    "photoPicker": {
+      "emptyTitle": "Aún no hay fotos",
+      "emptySubtitle": "Sube desde tu dispositivo para empezar"
+    },
+    "a11y": {
+      "viewAll": "Mostrar todos los archivos",
+      "viewPhotos": "Mostrar solo fotos",
+      "viewVideos": "Mostrar solo vídeos",
+      "viewDocuments": "Mostrar solo documentos",
+      "viewAudio": "Mostrar solo audio",
+      "sortBy": "Ordenar por {{field}}, {{order}}",
+      "uploadFile": "Subir archivo desde el dispositivo",
+      "uploadFromDevice": "Subir foto desde el dispositivo",
+      "photoCellSelected": "Foto {{name}}, seleccionada",
+      "photoCellUnselected": "Foto {{name}}, no seleccionada",
+      "selectionCount": "{{count}} foto seleccionada",
+      "selectionCount_plural": "{{count}} fotos seleccionadas",
+      "cancelPicker": "Cancelar selección de foto",
+      "confirmSelection": "Confirmar selección"
+    },
     "emptyPhotos": {
       "title": "Aún no hay fotos",
       "ownDescription": "Sube fotos para empezar. Puedes seleccionar varias fotos a la vez.",

package/src/index.ts

@@ -33,9 +33,16 @@ export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 export type { ServiceApp } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount } from './mixins/OxyServices.managedAccounts';
+export type { ContactDiscoveryMatch, ContactDiscoveryResponse } from './mixins/OxyServices.contacts';
 
 // --- Crypto / Identity ---
-export { KeyManager, SignatureService, RecoveryPhraseService } from './crypto';
+export {
+  KeyManager,
+  SignatureService,
+  RecoveryPhraseService,
+  IdentityAlreadyExistsError,
+  IdentityPersistError,
+} from './crypto';
 export type { KeyPair, SignedMessage, AuthChallenge, RecoveryPhraseResult } from './crypto';
 
 // --- Models & Types ---
@@ -170,8 +177,14 @@ export type { LogContext } from './utils/loggerUtils';
 export { updateAvatarVisibility } from './utils/avatarUtils';
 
 // --- Account Utilities ---
-export { buildAccountsArray, createQuickAccount } from './utils/accountUtils';
-export type { QuickAccount } from './utils/accountUtils';
+export {
+  buildAccountsArray,
+  createQuickAccount,
+  getAccountDisplayName,
+  getAccountFallbackHandle,
+  formatPublicKeyHandle,
+} from './utils/accountUtils';
+export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 
 // Default export
 import { OxyServices } from './OxyServices';

package/src/mixins/OxyServices.assets.ts

@@ -1,4 +1,4 @@
-import type { AccountStorageUsageResponse, AssetUrlResponse, AssetVariant } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 
 export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T) {
@@ -155,8 +155,8 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     /**
      * Upload raw file data
      */
-    async uploadRawFile(file: File | Blob, visibility?: 'private' | 'public' | 'unlisted', metadata?: Record<string, any>): Promise<any> {
-      return this.assetUpload(file as File, visibility, metadata);
+    async uploadRawFile(file: AssetUploadInput, visibility?: 'private' | 'public' | 'unlisted', metadata?: Record<string, any>): Promise<any> {
+      return this.assetUpload(file, visibility, metadata);
     }
 
     /**
@@ -166,20 +166,24 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
      * ({uri, type, name, size}). RN descriptors are passed directly to
      * FormData.append, which handles them natively.
      */
-    async assetUpload(file: File | { uri: string; type?: string; name?: string; size?: number }, visibility?: 'private' | 'public' | 'unlisted', metadata?: Record<string, any>, onProgress?: (progress: number) => void): Promise<any> {
+    async assetUpload(file: AssetUploadInput, visibility?: 'private' | 'public' | 'unlisted', metadata?: Record<string, any>, onProgress?: (progress: number) => void): Promise<any> {
       const fileName = 'name' in file && file.name ? file.name : 'unknown';
       const fileSize = 'size' in file && file.size ? file.size : 0;
 
       try {
         const formData = new FormData();
 
-        if ('uri' in file && typeof file.uri === 'string') {
-          // React Native file descriptor — RN's FormData handles {uri, type, name} natively
-          formData.append('file', file as unknown as Blob, fileName);
-        } else if (file instanceof Blob) {
+        if (typeof File !== 'undefined' && file instanceof File) {
+          formData.append('file', file, fileName);
+        } else if (typeof Blob !== 'undefined' && file instanceof Blob) {
           formData.append('file', file, fileName);
+        } else if ('uri' in file && typeof (file as RNFileDescriptor).uri === 'string') {
+          // React Native file descriptor — RN's FormData handles {uri, type, name} natively.
+          // It reads the file from disk during the multipart request — no in-JS Blob
+          // conversion (which would fail on Hermes for ArrayBuffer-backed Blobs).
+          formData.append('file', file as unknown as Blob, fileName);
         } else {
-          formData.append('file', new Blob([file as unknown as BlobPart], { type: 'application/octet-stream' }), fileName);
+          throw new Error('Unsupported file input: expected File, Blob, or { uri, type?, name?, size? } descriptor');
         }
         if (visibility) {
           formData.append('visibility', visibility);
@@ -350,7 +354,7 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
       }
     }
 
-    async uploadAvatar(file: File, userId: string, app: string = 'profiles'): Promise<any> {
+    async uploadAvatar(file: AssetUploadInput, userId: string, app: string = 'profiles'): Promise<any> {
       try {
         const asset = await this.assetUpload(file, 'public');
         await this.assetLink(asset.file.id, app, 'avatar', userId, 'public');
@@ -360,7 +364,7 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
       }
     }
 
-    async uploadProfileBanner(file: File, userId: string, app: string = 'profiles'): Promise<any> {
+    async uploadProfileBanner(file: AssetUploadInput, userId: string, app: string = 'profiles'): Promise<any> {
       try {
         const asset = await this.assetUpload(file, 'public');
         await this.assetLink(asset.file.id, app, 'profile-banner', userId, 'public');

package/src/mixins/OxyServices.auth.ts

@@ -47,6 +47,12 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     /** @internal */ _serviceTokenExp: number = 0;
     /** @internal */ _serviceApiKey: string | null = null;
     /** @internal */ _serviceApiSecret: string | null = null;
+    /**
+     * In-flight promise for service token fetch. Used to deduplicate concurrent
+     * calls to getServiceToken() — pattern mirrors AuthManager.refreshToken().
+     * @internal
+     */
+    _serviceTokenPromise: Promise<string> | null = null;
 
     constructor(...args: any[]) {
       super(...(args as [any]));
@@ -72,6 +78,9 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * Get a service token for internal service-to-service communication.
      * Tokens are short-lived (1h) and automatically cached/refreshed.
      *
+     * Concurrent callers share a single in-flight request to avoid hammering
+     * `/auth/service-token` when the cache is empty or expired.
+     *
      * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
      * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
      */
@@ -88,6 +97,25 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         return this._serviceToken;
       }
 
+      // If a fetch is already in-flight, share the same promise
+      if (this._serviceTokenPromise) {
+        return this._serviceTokenPromise;
+      }
+
+      this._serviceTokenPromise = this._doFetchServiceToken(key, secret);
+      try {
+        return await this._serviceTokenPromise;
+      } finally {
+        this._serviceTokenPromise = null;
+      }
+    }
+
+    /**
+     * Perform the actual /auth/service-token request and cache the result.
+     * Separated so getServiceToken() can deduplicate concurrent calls.
+     * @internal
+     */
+    async _doFetchServiceToken(key: string, secret: string): Promise<string> {
       const response = await this.makeRequest<ServiceTokenResponse>(
         'POST',
         '/auth/service-token',