@oxyhq/core 1.11.12 → 1.11.14

package/dist/types/HttpService.d.ts

@@ -54,17 +54,52 @@ export declare class HttpService {
     private requestMetrics;
     constructor(config: OxyConfig);
     /**
-     * Robust FormData detection that works in browser and Node.js environments
-     * Checks multiple conditions to handle different FormData implementations
+     * Robust FormData detection that works in browser, React Native, and
+     * Node.js polyfill environments.
+     *
+     * Why we don't use `instanceof FormData` alone:
+     *  - React Native's FormData is a separate class, not the browser one —
+     *    `instanceof FormData` is true only inside the JS runtime that
+     *    instantiated the value (browser-side polyfills also have their own).
+     *  - The Node.js `form-data` polyfill ships its own constructor.
+     *
+     * Why we explicitly reject `URLSearchParams`:
+     *  - `URLSearchParams` ALSO exposes `append` / `get` / `has`, so the
+     *    duck-type fallback below would have misidentified it as FormData.
+     *  - We want urlencoded payloads to take the JSON-stringify path so the
+     *    server receives them as `application/x-www-form-urlencoded` instead
+     *    of an empty multipart body.
      */
     private isFormData;
     /**
      * Main request method - handles everything in one place
      */
     request<T = unknown>(config: RequestConfig): Promise<T>;
+    /**
+     * Upload via XMLHttpRequest (React Native FormData workaround).
+     *
+     * Expo SDK 56's "winter fetch" cannot serialize RN file descriptors
+     * (`{uri, type, name}`) — `convertFormDataAsync` rejects them as
+     * `Unsupported FormDataPart implementation`. RN's native XHR streams
+     * the file from disk correctly, so multipart uploads go through XHR
+     * on RN only.
+     *
+     * Returns a standard `Response` so downstream parsing in `request()`
+     * (status checks, 401/403 retries, JSON/blob/text parsing) is identical
+     * to the fetch path.
+     */
+    private uploadViaXHR;
+    /**
+     * Parse raw header string from `XMLHttpRequest.getAllResponseHeaders()`
+     * into a `Headers`-compatible object.
+     */
+    private static parseXHRHeaders;
     /**
      * Generate cache key efficiently
-     * Uses simple hash for large objects to avoid expensive JSON.stringify
+     * Uses a content-addressed hash for large payloads so two requests with
+     * the same shape but different values never collide on the same key
+     * (which would silently serve stale data — e.g. paginated search results,
+     * large object updates).
      */
     private generateCacheKey;
     /**
@@ -104,6 +139,15 @@ export declare class HttpService {
     getBaseURL(): string;
     clearCache(): void;
     clearCacheEntry(key: string): void;
+    /**
+     * Delete every cache entry whose key starts with `prefix`.
+     *
+     * Used by mutations that don't know the exact downstream cache keys —
+     * e.g. `updateProfile` invalidating all `GET:/session/user/*` entries
+     * without having to track every active session ID. Returns the number of
+     * deleted entries (for observability in tests).
+     */
+    clearCacheByPrefix(prefix: string): number;
     getCacheStats(): {
         size: number;
         hits: number;

package/dist/types/OxyServices.base.d.ts

@@ -45,6 +45,13 @@ export declare class OxyServicesBase {
      * Clear specific cache entry
      */
     clearCacheEntry(key: string): void;
+    /**
+     * Clear every cache entry whose key starts with `prefix`.
+     * Useful for mutations that invalidate a family of GET responses
+     * without enumerating each one (e.g. all session-user lookups after
+     * a profile update).
+     */
+    clearCacheByPrefix(prefix: string): number;
     /**
      * Get cache statistics
      */

package/dist/types/OxyServices.d.ts

@@ -63,8 +63,41 @@ import type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
 import type { PopupAuthOptions } from './mixins/OxyServices.popup';
 import type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 import { composeOxyServices } from './mixins';
-declare const OxyServices_base: any;
-export declare class OxyServices extends OxyServices_base {
+/**
+ * OxyServices - Unified client library for interacting with the Oxy API
+ *
+ * This class provides all API functionality in one simple, easy-to-use interface.
+ *
+ * ## Architecture
+ * - **HttpService**: Unified HTTP service handling authentication, caching, deduplication, queuing, and retry
+ * - **OxyServices**: Provides high-level API methods
+ *
+ * ## Mixin Composition
+ * The class is composed using TypeScript mixins for better code organization:
+ * - **Base**: Core infrastructure (HTTP client, request management, error handling)
+ * - **Auth**: Authentication and session management
+ * - **User**: User profiles, follow, notifications
+ * - **Privacy**: Blocked and restricted users
+ * - **Language**: Language detection and metadata
+ * - **Payment**: Payment processing
+ * - **Karma**: Karma system
+ * - **Assets**: File upload and asset management
+ * - **Developer**: Developer API management
+ * - **Location**: Location-based features
+ * - **Analytics**: Analytics tracking
+ * - **Devices**: Device management
+ * - **Utility**: Utility methods and Express middleware
+ *
+ * @example
+ * ```typescript
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so'
+ * });
+ * ```
+ */
+declare const OxyServicesComposed: import("./mixins").ComposedOxyServicesConstructor;
+export declare class OxyServices extends OxyServicesComposed {
     constructor(config: OxyConfig);
 }
 export interface OxyServices extends InstanceType<ReturnType<typeof composeOxyServices>> {
@@ -79,24 +112,34 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     signUpWithRedirect(options?: RedirectAuthOptions): void;
     auth(options?: {
         debug?: boolean;
-        onError?: (error: any) => any;
+        onError?: (error: unknown) => unknown;
         loadUser?: boolean;
         optional?: boolean;
-    }): (req: any, res: any, next: any) => Promise<void>;
+        jwtSecret?: string;
+        expectedIssuer?: string;
+        expectedAudience?: string;
+    }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
     authSocket(options?: {
         debug?: boolean;
-    }): (socket: any, next: (err?: Error) => void) => Promise<void>;
+    }): (socket: unknown, next: (err?: Error) => void) => Promise<void>;
+    serviceAuth(options?: {
+        debug?: boolean;
+        jwtSecret?: string;
+        expectedIssuer?: string;
+        expectedAudience?: string;
+    }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
+    requireScope(scope: string): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
     assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
 }
 export { OxyAuthenticationError, OxyAuthenticationTimeoutError };
 /**
- * Export the default Oxy Cloud URL (for backward compatibility)
+ * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
  */
 export declare const OXY_CLOUD_URL = "https://cloud.oxy.so";
 /**
  * Export the default Oxy API URL (for documentation)
  */
-export declare const OXY_API_URL: string;
+export declare const OXY_API_URL: any;
 /**
  * Pre-configured client instance for easy import
  * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL

package/dist/types/crypto/index.d.ts

@@ -5,7 +5,7 @@
  * Handles key generation, secure storage, digital signatures, and recovery phrases.
  */
 import './polyfill';
-export { KeyManager, type KeyPair } from './keyManager';
+export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, type KeyPair, } from './keyManager';
 export { SignatureService, type SignedMessage, type AuthChallenge } from './signatureService';
 export { RecoveryPhraseService, type RecoveryPhraseResult } from './recoveryPhrase';
 export { KeyManager as default } from './keyManager';

package/dist/types/crypto/keyManager.d.ts

@@ -5,6 +5,31 @@
  * Private keys are stored securely using expo-secure-store and never leave the device.
  */
 import type { ECKeyPair } from 'elliptic';
+/**
+ * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
+ * is invoked while a valid identity already exists on the device.
+ *
+ * The local private key IS the user's identity — overwriting it without
+ * explicit consent permanently loses access to their account (unless
+ * they previously saved their recovery phrase). This error forces callers
+ * to make an explicit, audited decision instead of silently clobbering.
+ */
+export declare class IdentityAlreadyExistsError extends Error {
+    readonly name = "IdentityAlreadyExistsError";
+    readonly existingPublicKey: string;
+    constructor(existingPublicKey: string);
+}
+/**
+ * Thrown when a freshly written identity cannot be read back, parsed, or
+ * round-tripped through sign/verify. Indicates a storage failure or
+ * corruption that would otherwise silently leave the user with an
+ * unusable account.
+ */
+export declare class IdentityPersistError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "IdentityPersistError";
+    constructor(message: string, cause?: unknown | undefined);
+}
 export interface KeyPair {
     publicKey: string;
     privateKey: string;
@@ -24,6 +49,19 @@ export declare class KeyManager {
      * Called internally when shared identity is created/deleted/imported
      */
     private static invalidateSharedCache;
+    /**
+     * Lowercase and pad to canonical 64-hex-char form.
+     *
+     * Tolerates the 1-in-256 leading-zero-strip that elliptic's
+     * `getPrivate('hex')` produces, and the externally-imported uppercase-hex
+     * legacy keys. EVERY `ec.keyFromPrivate(...)` call site in this file must
+     * canonicalize first so that derivation is stable regardless of storage
+     * representation.
+     *
+     * Private (used only inside KeyManager) — public consumers should not need
+     * to think about hex representation.
+     */
+    private static canonicalPrivateKey;
     /**
      * Generate a new ECDSA secp256k1 key pair
      * Returns the keys in hexadecimal format
@@ -120,14 +158,45 @@ export declare class KeyManager {
      */
     static migrateToSharedIdentity(): Promise<boolean>;
     /**
-     * Generate and securely store a new key pair on the device
-     * Returns only the public key (private key is stored securely)
+     * Atomically persist a key pair to secure storage with verification + backup.
+     *
+     * Write order is critical:
+     *   1. Backup (BACKUP_PRIVATE_KEY + BACKUP_PUBLIC_KEY + BACKUP_TIMESTAMP)
+     *   2. Primary public key
+     *   3. Primary private key (last so a partial write leaves us in a known
+     *      "no identity yet" state — easier to retry than a half-written one)
+     *   4. Read back + sign/verify to confirm the storage round-trip works
+     *
+     * If any step throws, the caller sees the error AND any partial state is
+     * cleaned up so the device is left either fully consistent or fully empty.
+     * It never leaves an unusable half-identity that would fool `hasIdentity()`.
+     *
+     * @internal
      */
-    static createIdentity(): Promise<string>;
+    private static _persistIdentityAtomic;
     /**
-     * Import an existing key pair (e.g., from recovery phrase)
+     * Generate and securely store a new key pair on the device.
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     * Returns the public key. The private key never leaves secure storage.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     * @throws IdentityPersistError if the key cannot be durably written
      */
-    static importKeyPair(privateKey: string): Promise<string>;
+    static createIdentity(options?: {
+        overwrite?: boolean;
+    }): Promise<string>;
+    /**
+     * Import an existing key pair (e.g., from recovery phrase).
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     * @throws IdentityPersistError if the key cannot be durably written
+     */
+    static importKeyPair(privateKey: string, options?: {
+        overwrite?: boolean;
+    }): Promise<string>;
     /**
      * Get the stored private key
      * WARNING: Only use this for signing operations within the app
@@ -138,7 +207,15 @@ export declare class KeyManager {
      */
     static getPublicKey(): Promise<string | null>;
     /**
-     * Check if an identity (key pair) exists on this device (cached for performance)
+     * Check if a complete, parseable identity exists on this device.
+     *
+     * Returns `true` only when BOTH the private and public keys are present,
+     * both are well-formed, AND the public key derives from the private key.
+     * A partially-written or corrupted identity returns `false` so that
+     * downstream code can resume the create / restore flow correctly.
+     *
+     * Note: this does NOT perform the full sign/verify roundtrip — call
+     * `verifyIdentityIntegrity()` for that.
      */
     static hasIdentity(): Promise<boolean>;
     /**
@@ -156,11 +233,26 @@ export declare class KeyManager {
      */
     static backupIdentity(): Promise<boolean>;
     /**
-     * Verify identity integrity - checks if keys are valid and accessible
+     * Verify identity integrity — checks keys are valid, accessible, derive
+     * consistently, AND can sign + verify a probe message.
+     *
+     * Returns true only when the full sign/verify roundtrip succeeds. Use
+     * this on app start to detect silent corruption before the user finds
+     * out by failing to sign in.
      */
     static verifyIdentityIntegrity(): Promise<boolean>;
     /**
-     * Restore identity from backup if primary storage is corrupted
+     * Restore identity from backup if primary storage is corrupted.
+     *
+     * SAFETY: this method will NEVER overwrite a verifying primary identity.
+     * If the primary passes a sign/verify probe, the backup is left untouched
+     * and `false` is returned — this protects against a transient
+     * `verifyIdentityIntegrity()` blip clobbering valid keys with stale
+     * backup keys (e.g., from a previous account before an import).
+     *
+     * Additionally, if the backup public key does NOT match the (still-
+     * present-but-failing) primary public key, we refuse to overwrite — the
+     * backup may belong to a different identity entirely.
      */
     static restoreIdentityFromBackup(): Promise<boolean>;
     /**
@@ -174,10 +266,19 @@ export declare class KeyManager {
     static derivePublicKey(privateKey: string): string;
     /**
      * Validate that a string is a valid public key
+     *
+     * Returns false on parse errors (invalid input is the expected fail mode here).
+     * Errors are logged at debug level so they're available when troubleshooting
+     * but don't pollute production logs.
      */
     static isValidPublicKey(publicKey: string): boolean;
     /**
-     * Validate that a string is a valid private key
+     * Validate that a string is a valid private key.
+     *
+     * secp256k1 private keys are 256-bit, so 64 hex chars. We require strict
+     * hex-only input because `elliptic`'s underlying `BN(input, 16)` happily
+     * accepts non-hex characters (treating them as zero), which would let
+     * "not-hex" pass through as a valid (but compromised, near-zero) key.
      */
     static isValidPrivateKey(privateKey: string): boolean;
     /**

package/dist/types/crypto/polyfill.d.ts

@@ -5,7 +5,9 @@
  * 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';
 export { Buffer };

package/dist/types/crypto/recoveryPhrase.d.ts

@@ -11,20 +11,44 @@ export interface RecoveryPhraseResult {
     words: string[];
     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 declare 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 generateIdentityWithRecovery(): Promise<RecoveryPhraseResult>;
+    static generateIdentityWithRecovery(options?: GenerateIdentityOptions): Promise<RecoveryPhraseResult>;
     /**
-     * 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 generateIdentityWithRecovery24(): Promise<RecoveryPhraseResult>;
+    static generateIdentityWithRecovery24(options?: GenerateIdentityOptions): Promise<RecoveryPhraseResult>;
     /**
-     * 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 restoreFromPhrase(phrase: string): Promise<string>;
+    static restoreFromPhrase(phrase: string, options?: GenerateIdentityOptions): Promise<string>;
     /**
      * Validate a recovery phrase without importing it
      */

package/dist/types/crypto/signatureService.d.ts

@@ -37,6 +37,10 @@ export declare class SignatureService {
     static signWithKey(message: string, privateKey: string): Promise<string>;
     /**
      * 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 verify(message: string, signature: string, publicKey: string): Promise<boolean>;
     /**

package/dist/types/index.d.ts

@@ -23,10 +23,12 @@ export type { CrossDomainAuthOptions } from './CrossDomainAuth';
 export type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
 export type { PopupAuthOptions } from './mixins/OxyServices.popup';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
+export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
-export type { ServiceApp } from './mixins/OxyServices.utility';
+export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount } from './mixins/OxyServices.managedAccounts';
-export { KeyManager, SignatureService, RecoveryPhraseService } from './crypto';
+export type { ContactDiscoveryMatch, ContactDiscoveryResponse } from './mixins/OxyServices.contacts';
+export { KeyManager, SignatureService, RecoveryPhraseService, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto';
 export type { KeyPair, SignedMessage, AuthChallenge, RecoveryPhraseResult } from './crypto';
 export * from './models/interfaces';
 export * from './models/session';
@@ -34,7 +36,7 @@ export type { TopicData, TopicTranslation } from './models/Topic';
 export { TopicType, TopicSource } from './models/Topic';
 export { DeviceManager } from './utils/deviceManager';
 export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
-export { SUPPORTED_LANGUAGES, getLanguageMetadata, getLanguageName, getNativeLanguageName, normalizeLanguageCode, } from './utils/languageUtils';
+export { SUPPORTED_LANGUAGES, getLanguageMetadata, getLanguageName, getNativeLanguageName, normalizeLanguageCode, isRTLLocale, } from './utils/languageUtils';
 export type { LanguageMetadata } from './utils/languageUtils';
 export { getPlatformOS, setPlatformOS, isWeb, isNative, isIOS, isAndroid, } from './utils/platform';
 export type { PlatformOS } from './utils/platform';
@@ -57,7 +59,7 @@ export * from './utils/validationUtils';
 export { logger, LogLevel, logAuth, logApi, logSession, logUser, logDevice, logPayment, logPerformance, } from './utils/loggerUtils';
 export type { LogContext } from './utils/loggerUtils';
 export { updateAvatarVisibility } from './utils/avatarUtils';
-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';
 import { OxyServices } from './OxyServices';
 export default OxyServices;

package/dist/types/mixins/OxyServices.analytics.d.ts

@@ -36,6 +36,7 @@ export declare function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBa
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;

package/dist/types/mixins/OxyServices.assets.d.ts

@@ -1,4 +1,4 @@
-import type { AccountStorageUsageResponse, AssetUrlResponse, AssetVariant } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -45,7 +45,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         /**
          * Upload raw file data
          */
-        uploadRawFile(file: File | Blob, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>): Promise<any>;
+        uploadRawFile(file: AssetUploadInput, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>): Promise<any>;
         /**
          * Upload file using Central Asset Service.
          *
@@ -53,12 +53,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          * ({uri, type, name, size}). RN descriptors are passed directly to
          * FormData.append, which handles them natively.
          */
-        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>;
+        assetUpload(file: AssetUploadInput, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>, onProgress?: (progress: number) => void): Promise<any>;
         /**
          * Link asset to an entity
          */
@@ -91,8 +86,8 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          * Update asset visibility
          */
         assetUpdateVisibility(fileId: string, visibility: "private" | "public" | "unlisted"): Promise<any>;
-        uploadAvatar(file: File, userId: string, app?: string): Promise<any>;
-        uploadProfileBanner(file: File, userId: string, app?: string): Promise<any>;
+        uploadAvatar(file: AssetUploadInput, userId: string, app?: string): Promise<any>;
+        uploadProfileBanner(file: AssetUploadInput, userId: string, app?: string): Promise<any>;
         getAssetUrlCacheTTL(expiresIn?: number): number;
         fetchAssetDownloadUrl(fileId: string, variant?: string, cacheTTL?: number, expiresIn?: number): Promise<string | null>;
         fetchAssetContent(url: string, type: "text"): Promise<string>;
@@ -114,6 +109,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -34,29 +34,104 @@ export interface ServiceTokenResponse {
     expiresIn: number;
     appName: string;
 }
+/**
+ * One cache entry per (apiKey hash) → issued token + the secret that produced it.
+ * The secret is kept around in raw Buffer form so we can perform a
+ * constant-time compare against any reused credential pair — this prevents an
+ * attacker who learned a victim's apiKey from receiving the victim's cached
+ * service token by simply guessing the secret.
+ *
+ * @internal
+ */
+interface ServiceTokenCacheEntry {
+    token: string;
+    /** Expiry as ms since epoch */
+    expiresAt: number;
+    /** Raw secret stored as Buffer for constant-time comparison on cache hit */
+    secretBuf: Buffer;
+    /** In-flight refresh promise (deduplicates concurrent callers) */
+    pending: Promise<string> | null;
+}
+/**
+ * Sentinel error raised when getServiceToken() is called with a known apiKey
+ * but a non-matching secret. Indicates either credential drift in the caller
+ * or a cross-tenant cache lookup attempt. Surface as a 401-equivalent.
+ */
+export declare class ServiceCredentialMismatchError extends Error {
+    constructor();
+}
 export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
-        /** @internal */ _serviceToken: string | null;
-        /** @internal */ _serviceTokenExp: number;
-        /** @internal */ _serviceApiKey: string | null;
-        /** @internal */ _serviceApiSecret: string | null;
+        /**
+         * Per-credential token cache.
+         *
+         * Keyed by SHA-256(apiKey). Each entry carries:
+         *   - the issued service JWT
+         *   - its expiry timestamp
+         *   - the secret that produced it (Buffer for constant-time compare)
+         *   - an optional in-flight promise to deduplicate concurrent refreshes
+         *
+         * The previous implementation kept ONE token/exp pair per OxyServices
+         * instance. That meant calling `getServiceToken(keyA, secretA)` populated
+         * the cache, and a subsequent `getServiceToken(keyB, secretB)` (different
+         * tenant) would receive tenant A's token. This is fixed by routing every
+         * lookup through the Map.
+         *
+         * @internal
+         */
+        _serviceTokenCache: Map<string, ServiceTokenCacheEntry>;
+        /** @internal Raw apiKey stored by configureServiceAuth() for use by getServiceToken() */
+        _serviceApiKey: string | null;
+        /** @internal Raw apiSecret stored by configureServiceAuth() for use by getServiceToken() */
+        _serviceApiSecret: string | null;
+        /**
+         * Hash an apiKey into a stable Map cache key. Uses Node's SHA-256 — service
+         * tokens are only ever issued by a Node host (the SDK on web/RN never has
+         * the apiSecret in the first place), so we can rely on Node crypto here.
+         *
+         * @internal
+         */
+        _hashApiKey(apiKey: string): Promise<string>;
         /**
          * Configure service credentials for internal service-to-service communication.
          * Call this once at startup so that getServiceToken() and makeServiceRequest()
          * can automatically obtain and refresh tokens.
          *
+         * Calling this with credentials that differ from a previously-configured pair
+         * is allowed — each `(apiKey, apiSecret)` pair is cached independently, so
+         * legitimate multi-tenant hosts that need to switch credentials cannot leak
+         * one tenant's token to another tenant on the same instance.
+         *
          * @param apiKey - DeveloperApp API key (oxy_dk_*)
          * @param apiSecret - DeveloperApp API secret
          */
         configureServiceAuth(apiKey: string, apiSecret: string): void;
         /**
          * Get a service token for internal service-to-service communication.
-         * Tokens are short-lived (1h) and automatically cached/refreshed.
+         * Tokens are short-lived (1h) and automatically cached/refreshed per
+         * `(apiKey, apiSecret)` pair.
+         *
+         * Concurrent callers for the same credential pair share a single in-flight
+         * request to avoid hammering `/auth/service-token` when the cache is empty
+         * or expired.
+         *
+         * **Security guarantee:** if the cache already holds a token for this
+         * apiKey but the supplied apiSecret does not constant-time match the
+         * secret that originally produced that token, this method throws
+         * `ServiceCredentialMismatchError` instead of returning the cached token.
+         * This prevents an attacker who learned a peer's apiKey from extracting
+         * their service token by polling with a wrong secret.
          *
          * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
          * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
          */
         getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
+        /**
+         * Perform the actual /auth/service-token request and cache the result.
+         * Separated so getServiceToken() can deduplicate concurrent calls.
+         * @internal
+         */
+        _doFetchServiceToken(key: string, secret: string, cacheKey: string, secretBuf: Buffer): Promise<string>;
         /**
          * Make an authenticated request on behalf of a user using a service token.
          * Automatically obtains/refreshes the service token.
@@ -192,6 +267,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;
@@ -224,3 +300,4 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         }>;
     };
 } & T;
+export {};