@oxyhq/core 1.11.12 → 1.11.14

package/src/HttpService.ts

@@ -18,7 +18,7 @@ import { RequestDeduplicator, RequestQueue, SimpleLogger } from './utils/request
 import { retryAsync } from './utils/asyncUtils';
 import { handleHttpError } from './utils/errorUtils';
 import { jwtDecode } from 'jwt-decode';
-import { isNative, getPlatformOS } from './utils/platform';
+import { isNative, isReactNative, getPlatformOS } from './utils/platform';
 import type { OxyConfig } from './models/interfaces';
 
 /**
@@ -35,6 +35,52 @@ interface JwtPayload {
   [key: string]: any;
 }
 
+/**
+ * Structural type that captures the multipart-write surface every supported
+ * FormData implementation exposes (browser, React Native, Node `form-data`
+ * polyfill, jsdom, undici, etc). We type-narrow against this in
+ * `isFormData()` so callers don't have to know which runtime produced the
+ * value.
+ *
+ * Deliberately mirrored from the lib.dom `FormData` interface — kept as a
+ * local type because @types/node and @types/react-native model FormData
+ * differently and a single import wouldn't be safe in both bundles.
+ */
+interface FormDataLike {
+  append(name: string, value: unknown, fileName?: string): void;
+  delete(name: string): void;
+  get(name: string): unknown;
+  getAll(name: string): unknown[];
+  has(name: string): boolean;
+}
+
+/**
+ * FNV-1a 32-bit non-cryptographic hash.
+ *
+ * Used by the cache-key generator for large payloads where full JSON
+ * inclusion would balloon the cache map keys. Content-addressed: every
+ * byte of the input contributes to the digest, so two payloads with the
+ * same top-level shape but different field values produce different keys
+ * (the previous `keys + length` heuristic collided on these).
+ *
+ * Trade-offs:
+ *  - 32 bits is ample for an in-process cache (collision risk negligible
+ *    at our key counts; we also prefix with method + url which further
+ *    partitions the keyspace).
+ *  - Not cryptographically secure — never use for security decisions.
+ *  - Zero dependencies, branch-free hot loop, ~1 GiB/s on V8.
+ */
+function fnv1a32(str: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    // h * 16777619 mod 2^32, written as shift-and-add for portability and
+    // to avoid 53-bit JS number truncation in the intermediate multiply.
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
 export interface RequestOptions {
   cache?: boolean;
   cacheTTL?: number;
@@ -165,35 +211,59 @@ export class HttpService {
   }
 
   /**
-   * 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(data: unknown): boolean {
-    if (!data) {
+  private isFormData(data: unknown): data is FormDataLike {
+    if (!data || typeof data !== 'object') {
       return false;
     }
 
-    // Primary check: instanceof FormData (works in browser and Node.js with proper polyfills)
-    if (data instanceof FormData) {
-      return true;
+    // Reject URLSearchParams up front: it shares the duck-typed surface
+    // (append / get / has) but is a fundamentally different content type.
+    // The caller routes URLSearchParams through the regular body path.
+    if (typeof URLSearchParams !== 'undefined' && data instanceof URLSearchParams) {
+      return false;
     }
 
-    // Fallback: Check constructor name (handles Node.js polyfills like form-data)
-    if (typeof data === 'object' && data !== null) {
-      const constructorName = data.constructor?.name;
-      if (constructorName === 'FormData' || constructorName === 'FormDataImpl') {
-        return true;
-      }
+    // Primary check: instanceof FormData. Works whenever the value was
+    // constructed by the same runtime/realm that exposes `FormData`.
+    if (typeof FormData !== 'undefined' && data instanceof FormData) {
+      return true;
+    }
 
-      // Additional check: Look for FormData-like methods
-      if (typeof (data as any).append === 'function' && 
-          typeof (data as any).get === 'function' &&
-          typeof (data as any).has === 'function') {
-        return true;
-      }
+    // Fallback: detect Node / RN polyfills by constructor name. Limited to
+    // the small handful of known names so we don't accept arbitrary
+    // user-supplied objects with a coincidental `name`.
+    const constructorName = data.constructor?.name;
+    if (constructorName === 'FormData' || constructorName === 'FormDataImpl') {
+      return true;
     }
 
-    return false;
+    // Last-resort duck typing — require the full FormData write surface
+    // (`append`, `get`, `has`, `getAll`, `delete`) so plain objects with
+    // an `append` method don't accidentally match.
+    const candidate = data as Partial<Record<keyof FormDataLike, unknown>>;
+    return (
+      typeof candidate.append === 'function' &&
+      typeof candidate.get === 'function' &&
+      typeof candidate.has === 'function' &&
+      typeof candidate.getAll === 'function' &&
+      typeof candidate.delete === 'function'
+    );
   }
 
   /**
@@ -314,17 +384,27 @@ export class HttpService {
           });
         }
 
-        const bodyValue = method !== 'GET' && data 
-            ? (isFormData ? data : JSON.stringify(data)) 
+        const bodyValue = method !== 'GET' && data
+            ? (isFormData ? data : JSON.stringify(data))
             : undefined;
-        
-        const response = await fetch(fullUrl, {
-          method,
-          headers,
-          body: bodyValue as BodyInit | null | undefined,
-          signal: controller.signal,
-          credentials: 'include', // Include cookies for cross-origin requests (CSRF, session)
-        });
+
+        // React Native FormData workaround:
+        // Expo SDK 56's "winter fetch" rejects RN file descriptors `{uri, type, name}`
+        // in FormDataPart conversion (`Unsupported FormDataPart implementation`).
+        // RN's native XMLHttpRequest handles those descriptors correctly, so we
+        // route multipart uploads through XHR on RN only. JSON, text, etc. still
+        // use fetch on every platform.
+        const useXhrForUpload = isFormData && isReactNative() && typeof XMLHttpRequest !== 'undefined';
+
+        const response = useXhrForUpload
+          ? await this.uploadViaXHR(fullUrl, method, headers, bodyValue as FormData, controller.signal, timeout)
+          : await fetch(fullUrl, {
+              method,
+              headers,
+              body: bodyValue as BodyInit | null | undefined,
+              signal: controller.signal,
+              credentials: 'include', // Include cookies for cross-origin requests (CSRF, session)
+            });
 
         if (timeoutId) clearTimeout(timeoutId);
 
@@ -473,28 +553,140 @@ export class HttpService {
     return result;
   }
 
+  /**
+   * 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(
+    url: string,
+    method: string,
+    headers: Record<string, string>,
+    body: FormData,
+    abortSignal: AbortSignal,
+    timeout: number,
+  ): Promise<Response> {
+    return new Promise<Response>((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.open(method, url, true);
+      // withCredentials mirrors fetch's `credentials: 'include'` so the
+      // session cookie and CSRF cookie continue to flow.
+      xhr.withCredentials = true;
+
+      // Forward headers but skip Content-Type — XHR sets the multipart
+      // boundary automatically and overriding it breaks the upload.
+      for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === 'content-type') continue;
+        try {
+          xhr.setRequestHeader(key, value);
+        } catch (headerError) {
+          // Some headers (e.g. forbidden header names) cannot be set —
+          // log and continue rather than failing the whole upload.
+          this.logger.warn('XHR setRequestHeader failed:', key, headerError);
+        }
+      }
+
+      xhr.responseType = 'text';
+      if (timeout > 0) {
+        xhr.timeout = timeout;
+      }
+
+      const onAbort = (): void => {
+        try { xhr.abort(); } catch { /* xhr already finished */ }
+      };
+      if (abortSignal.aborted) {
+        reject(new DOMException('The user aborted a request.', 'AbortError'));
+        return;
+      }
+      abortSignal.addEventListener('abort', onAbort);
+
+      const cleanup = (): void => {
+        abortSignal.removeEventListener('abort', onAbort);
+      };
+
+      xhr.onload = (): void => {
+        cleanup();
+        const responseHeaders = HttpService.parseXHRHeaders(xhr.getAllResponseHeaders());
+        resolve(new Response(xhr.responseText, {
+          status: xhr.status,
+          statusText: xhr.statusText,
+          headers: responseHeaders,
+        }));
+      };
+      xhr.onerror = (): void => {
+        cleanup();
+        reject(new TypeError('Network request failed'));
+      };
+      xhr.ontimeout = (): void => {
+        cleanup();
+        reject(new DOMException('The request timed out.', 'TimeoutError'));
+      };
+      xhr.onabort = (): void => {
+        cleanup();
+        reject(new DOMException('The user aborted a request.', 'AbortError'));
+      };
+
+      xhr.send(body);
+    });
+  }
+
+  /**
+   * Parse raw header string from `XMLHttpRequest.getAllResponseHeaders()`
+   * into a `Headers`-compatible object.
+   */
+  private static parseXHRHeaders(rawHeaders: string): Headers {
+    const headers = new Headers();
+    if (!rawHeaders) return headers;
+    // RFC 7230 line terminator is CRLF; some XHR implementations use LF only.
+    const lines = rawHeaders.trim().split(/\r?\n/);
+    for (const line of lines) {
+      const colonIndex = line.indexOf(':');
+      if (colonIndex <= 0) continue;
+      const key = line.slice(0, colonIndex).trim();
+      const value = line.slice(colonIndex + 1).trim();
+      if (key) {
+        try {
+          headers.append(key, value);
+        } catch {
+          // Invalid header name/value — skip.
+        }
+      }
+    }
+    return headers;
+  }
+
   /**
    * 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(method: string, url: string, data?: unknown): string {
     if (!data || (typeof data === 'object' && Object.keys(data).length === 0)) {
       return `${method}:${url}`;
     }
 
-    // For small objects, use JSON.stringify
+    // For small objects, the full serialization IS the key — fastest and
+    // guaranteed to be content-addressed.
     const dataStr = JSON.stringify(data);
     if (dataStr.length < 1000) {
       return `${method}:${url}:${dataStr}`;
     }
 
-    // For large objects, use a simple hash based on keys and values length
-    // This avoids expensive serialization while still being unique enough
-    const hash = typeof data === 'object' && data !== null
-      ? Object.keys(data).sort().join(',') + ':' + dataStr.length
-      : String(data).substring(0, 100);
-    
-    return `${method}:${url}:${hash}`;
+    // For large payloads, hash the full serialized string so the key remains
+    // content-addressed (any byte change yields a different hash). Previous
+    // implementation hashed `keys + length` which collided for any two
+    // payloads with the same top-level keys and serialized length.
+    return `${method}:${url}:${fnv1a32(dataStr)}`;
   }
 
   /**
@@ -760,6 +952,25 @@ export class HttpService {
     this.cache.delete(key);
   }
 
+  /**
+   * 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 {
+    let removed = 0;
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
   getCacheStats() {
     const cacheStats = this.cache.getStats();
     const total = this.requestMetrics.cacheHits + this.requestMetrics.cacheMisses;

package/src/OxyServices.base.ts

@@ -106,6 +106,16 @@ export class OxyServicesBase {
     this.httpService.clearCacheEntry(key);
   }
 
+  /**
+   * 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).
+   */
+  public clearCacheByPrefix(prefix: string): number {
+    return this.httpService.clearCacheByPrefix(prefix);
+  }
+
   /**
    * Get cache statistics
    */

package/src/OxyServices.ts

@@ -99,11 +99,16 @@ import { composeOxyServices } from './mixins';
  * });
  * ```
  */
-// Compose all mixins into the final OxyServices class
+// Compose all mixins into the final OxyServices class. The composed runtime
+// class augments OxyServicesBase with every mixin's methods (see mixins/index.ts).
+// Statically, TypeScript sees this as a constructor producing OxyServicesBase;
+// the additional methods are exposed via interface merging on `OxyServices` below.
 const OxyServicesComposed = composeOxyServices();
 
-// Export as a named class to avoid TypeScript issues with anonymous class types
-export class OxyServices extends (OxyServicesComposed as any) {
+// Export as a named class to avoid TypeScript issues with anonymous class types.
+// We extend the composed constructor directly — its public surface is broadened
+// to the full mixin set via the interface declaration that follows.
+export class OxyServices extends OxyServicesComposed {
   constructor(config: OxyConfig) {
     super(config);
   }
@@ -132,15 +137,29 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   // Express.js middleware
   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>;
 
   // Socket.IO middleware
   authSocket(options?: {
     debug?: boolean;
-  }): (socket: any, next: (err?: Error) => void) => Promise<void>;
+  }): (socket: unknown, next: (err?: Error) => void) => Promise<void>;
+
+  // Service-token-only middleware (delegates to auth() internally)
+  serviceAuth(options?: {
+    debug?: boolean;
+    jwtSecret?: string;
+    expectedIssuer?: string;
+    expectedAudience?: string;
+  }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
+
+  // Scope enforcement for service-token-protected routes
+  requireScope(scope: string): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
 
   // Asset management
   assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
@@ -150,7 +169,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
 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 const OXY_CLOUD_URL = 'https://cloud.oxy.so';