@oxyhq/core 3.9.1 → 3.10.1

package/dist/types/index.d.ts

@@ -80,7 +80,7 @@ export type { LogContext } from './utils/loggerUtils';
 export { updateAvatarVisibility } from './utils/avatarUtils';
 export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, mergeAccountsFromRefreshAll, getAccountColor, } from './utils/accountUtils';
 export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
-export { autoDetectAuthWebUrl, registrableApex, MULTIPART_TLDS } from './utils/fapiAutoDetect';
+export { autoDetectAuthWebUrl, registrableApex } from './utils/fapiAutoDetect';
 export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './utils/authWebUrl';
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
 export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';

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

@@ -1,5 +1,9 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
+interface FileDownloadUrlOptions {
+    /** Omit bearer access tokens from generated URLs, even when authenticated. */
+    omitToken?: boolean;
+}
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -32,7 +36,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          *
          * For a CDN-signed URL fetched from the API, use {@link getFileDownloadUrlAsync}.
          */
-        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string;
+        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number, options?: FileDownloadUrlOptions): string;
         /**
          * Get file download URL asynchronously (returns signed URL directly from CDN)
          */
@@ -168,3 +172,4 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         }>;
     };
 } & T;
+export {};

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

@@ -225,9 +225,9 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * Express.js middleware that enforces a specific service-token scope.
          *
          * Mount AFTER `auth()` / `serviceAuth()` — relies on `req.serviceApp` and
-         * (when delegation is in effect) `req.serviceActingAs.scopes`. The scope
-         * is granted if EITHER list contains it, mirroring the OAuth2 model where
-         * the app's app-level scopes and the per-user delegated scopes both count.
+         * (when delegation is in effect) `req.serviceActingAs.scopes`. App-only
+         * service requests require the app scope. Delegated user requests require
+         * BOTH the app scope and the per-user delegation scope.
          *
          * Requests authenticated as a regular user (no service token) are rejected
          * with 403 — scope-protected endpoints are service-to-service by design.

package/dist/types/server/cors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Strict CORS allowlist for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * App backends kept hand-rolling CORS, and the unsafe patterns recurred:
+ *   - `Access-Control-Allow-Origin: *` together with credentials (which is
+ *     spec-invalid AND a credential-leak vector), or
+ *   - a "reflect whatever Origin the request carried" fallback (effectively
+ *     `*` for credentialed requests — the Allo wildcard-fallback class).
+ *
+ * `createOxyCors` returns a self-contained Express middleware (no `cors`
+ * package dependency) that:
+ *   - allows the Oxy apex origin family (anything under `*.${CENTRAL_IDP_APEX}`,
+ *     i.e. `oxy.so` — covering `auth.oxy.so`, `api.oxy.so`, `accounts.oxy.so`,
+ *     `console.oxy.so`, `inbox.oxy.so`, the marketing site, …) reusing the
+ *     central-origin constants already in core, NOT a fresh hardcoded list,
+ *   - allows the caller's explicit `appOrigins`,
+ *   - DENIES everything else (no reflection, never a wildcard with credentials),
+ *   - echoes back the EXACT matched origin (so credentialed requests work) and
+ *     sets `Vary: Origin` for correct caching,
+ *   - answers CORS preflight (`OPTIONS`) with `204`.
+ *
+ * Node/Express-only: exported solely from `@oxyhq/core/server`.
+ */
+import type { RequestHandler } from 'express';
+export interface OxyCorsOptions {
+    /**
+     * Explicit additional allowed origins (exact-origin match, e.g.
+     * `https://app.example.com`, `http://localhost:3000`). These are allowed IN
+     * ADDITION TO the Oxy apex origin family. Each is normalized via `new URL().origin`.
+     */
+    appOrigins?: string[];
+    /**
+     * Whether to emit `Access-Control-Allow-Credentials: true`. Default `true`
+     * (the Oxy ecosystem uses cookie/bearer credentials). Even when `true`, the
+     * helper NEVER emits a wildcard origin — only an exact matched origin.
+     */
+    allowCredentials?: boolean;
+    /** HTTP methods to allow. Defaults to the full standard set. */
+    methods?: string[];
+    /** Request headers to allow. Defaults to the common Oxy set. */
+    allowedHeaders?: string[];
+    /** Response headers to expose to the browser. Defaults to none. */
+    exposedHeaders?: string[];
+    /** Preflight cache lifetime in seconds. Default 86400 (24h). */
+    maxAgeSeconds?: number;
+}
+/**
+ * Create a strict Oxy CORS middleware. See module docs.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxyCors({ appOrigins: ['https://app.example.com'] }));
+ * ```
+ */
+export declare function createOxyCors(options?: OxyCorsOptions): RequestHandler;

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

@@ -18,3 +18,8 @@ export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequir
 export type { OxyActingAsContext, OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';
+export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch';
+export type { SafeFetchOptions, SafeFetchResult, SsrfCheckFail, SsrfCheckOk, SsrfCheckResult, } from './safeFetch';
+export { createOxyCors } from './cors';
+export type { OxyCorsOptions } from './cors';
+export { verifySecret } from './verifySecret';

package/dist/types/server/safeFetch.d.ts

@@ -0,0 +1,135 @@
+/**
+ * SSRF-safe upstream HTTP fetch for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every Oxy backend that contacts a caller-influenced URL — media proxies,
+ * the website MCP image upload/debug tools, federated fetches, link
+ * unfurlers — needs the exact same Server-Side Request Forgery (SSRF)
+ * defence. Apps were re-implementing it (or worse, omitting it), so the
+ * gold-standard primitive (originally `packages/backend/src/utils` in
+ * Mention) lives here ONCE.
+ *
+ * THE CONTRACT
+ * ------------
+ *  - Every URL — including each redirect hop — is validated by
+ *    {@link assertSafePublicUrl}: a real DNS resolution plus a denylist of
+ *    private/reserved/metadata ranges (10/8, 127/8, 169.254.169.254, ::1, …).
+ *  - The TCP connection is PINNED to the validated IP via a custom `lookup`,
+ *    closing the DNS-rebind TOCTOU window — DNS is NOT re-resolved at connect
+ *    time, so the address we validated is exactly the address Node connects to.
+ *  - Redirects are followed manually (bounded) so every hop is re-validated and
+ *    redirect bodies (potentially unbounded) are destroyed, not drained.
+ *
+ * Node-only: this module imports `node:http`/`node:https`/`node:dns` and is
+ * exported solely from `@oxyhq/core/server`. It MUST NOT be reachable from the
+ * browser `@oxyhq/core` entry.
+ */
+import { type IncomingMessage, type IncomingHttpHeaders } from 'node:http';
+/** Maximum accepted length of an input URL (DoS guard). */
+export declare const MAX_URL_LENGTH = 2048;
+/** The only network ports a safe fetch is allowed to reach upstream. */
+export declare const ALLOWED_PORTS: ReadonlySet<number>;
+/** Protocols a safe fetch is allowed to contact. */
+export declare const ALLOWED_PROTOCOLS: ReadonlySet<string>;
+/**
+ * Time-to-first-byte deadline: how long to wait for the upstream to establish
+ * the connection and send its RESPONSE HEADERS before aborting. Enforced via
+ * `req.setTimeout` on the `ClientRequest`; once headers arrive, the caller owns
+ * the (longer) streaming lifetime of the response body.
+ */
+export declare const UPSTREAM_HEADERS_TIMEOUT_MS = 8000;
+/** Maximum number of HTTP redirects to follow; each hop is re-validated. */
+export declare const MAX_REDIRECTS = 5;
+/** Default User-Agent presented to upstreams when the caller does not set one. */
+export declare const DEFAULT_USER_AGENT = "OxyServices/1.0 (+https://oxy.so)";
+/** Hostnames that must never be resolved or contacted, regardless of DNS. */
+export declare const BLOCKED_HOSTNAMES: ReadonlySet<string>;
+export interface SsrfCheckOk {
+    ok: true;
+    /** The validated literal IP the caller MUST connect to. */
+    ip: string;
+    /** IP family of the validated address (4 or 6). */
+    family: 4 | 6;
+}
+export interface SsrfCheckFail {
+    ok: false;
+    /** Human-readable, non-sensitive reason (safe to log; not echoed to clients). */
+    reason: string;
+}
+export type SsrfCheckResult = SsrfCheckOk | SsrfCheckFail;
+/**
+ * Return true if a literal IP address is private/loopback/link-local/reserved/
+ * multicast/metadata and therefore must NOT be contacted.
+ */
+export declare function isBlockedIp(rawIp: string): boolean;
+/**
+ * Validate that a URL is syntactically a public http(s) URL and that its
+ * hostname resolves ONLY to non-blocked, public IP addresses.
+ *
+ * On success, returns the single validated IP (the first allowed record) that
+ * the HTTP client MUST pin its connection to. Every resolved address is checked;
+ * if ANY resolves into a blocked range the URL is rejected (an attacker
+ * controlling a multi-record DNS response cannot smuggle one internal IP past
+ * the check).
+ *
+ * Re-run this on EVERY redirect hop so a public hostname cannot redirect (or
+ * DNS-rebind) into an internal address.
+ */
+export declare function assertSafePublicUrl(rawUrl: string): Promise<SsrfCheckResult>;
+/** Marker error for a blocked SSRF target (map to 403 at the route layer). */
+export declare class SsrfRejection extends Error {
+    constructor(reason: string);
+}
+/** Marker error for a generic upstream failure (map to 502 at the route layer). */
+export declare class UpstreamError extends Error {
+    constructor(reason: string);
+}
+/** Options for {@link safeFetch}. */
+export interface SafeFetchOptions {
+    /** HTTP method. Defaults to `GET`. */
+    method?: string;
+    /** Extra request headers. A `User-Agent` is added if none is provided. */
+    headers?: Record<string, string>;
+    /**
+     * Maximum number of redirects to follow (each re-validated). Defaults to
+     * {@link MAX_REDIRECTS}. Set to `0` to disallow redirects.
+     */
+    maxRedirects?: number;
+    /**
+     * Time-to-first-byte deadline in milliseconds (connect + response headers).
+     * Defaults to {@link UPSTREAM_HEADERS_TIMEOUT_MS}.
+     */
+    headersTimeoutMs?: number;
+    /**
+     * Optional external abort signal. When it fires the in-flight request is
+     * destroyed.
+     */
+    signal?: AbortSignal;
+}
+/** The validated, non-redirect response returned by {@link safeFetch}. */
+export interface SafeFetchResult {
+    /**
+     * The first non-redirect response. The caller OWNS draining/destroying this
+     * stream (stream it to the client, or buffer a bounded prefix, then destroy).
+     */
+    response: IncomingMessage;
+    /** The HTTP status code of the response. */
+    status: number;
+    /** Response headers. */
+    headers: IncomingHttpHeaders;
+    /** The final, post-redirect URL that produced the response. */
+    finalUrl: string;
+}
+/**
+ * SSRF-safe HTTP(S) fetch. Validates the URL (and every redirect hop) against
+ * the private/metadata-range denylist, pins the connection to the validated IP,
+ * follows a bounded number of redirects (destroying redirect bodies), and
+ * returns the first non-redirect response.
+ *
+ * The caller owns the returned response stream — drain or destroy it.
+ *
+ * @throws {SsrfRejection} when any hop targets a blocked address/host/port.
+ * @throws {UpstreamError} on redirect-loop / malformed-redirect / timeout.
+ */
+export declare function safeFetch(rawUrl: string, options?: SafeFetchOptions): Promise<SafeFetchResult>;

package/dist/types/server/verifySecret.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Constant-time secret comparison for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Backends kept comparing secrets with `provided !== EXPECTED`. A plain `===`/
+ * `!==` short-circuits on the first differing byte, leaking timing information
+ * an attacker can use to recover a secret byte-by-byte. This helper performs a
+ * constant-time comparison via `crypto.timingSafeEqual`, guarded by a length
+ * check, and never throws — replacing the `token !== SECRET` pattern (Alia
+ * docker-host / integrations webhook secrets, internal webhook bearers, etc.).
+ *
+ * Node-only (`node:crypto`); exported solely from `@oxyhq/core/server`.
+ */
+/**
+ * Compare two secrets in constant time.
+ *
+ * Returns `true` iff both are non-empty strings of equal byte length with
+ * identical contents. Returns `false` — without throwing — when either value is
+ * not a string, when lengths differ, or when contents differ.
+ *
+ * The length-equality guard is required because `crypto.timingSafeEqual` throws
+ * on unequal-length buffers; comparing lengths first leaks only the LENGTH of
+ * the expected secret (already low-value / often public), never its bytes.
+ *
+ * @param provided - The untrusted, caller-supplied value (e.g. a request token).
+ * @param expected - The trusted secret to compare against.
+ */
+export declare function verifySecret(provided: string, expected: string): boolean;

package/dist/types/utils/fapiAutoDetect.d.ts

@@ -20,10 +20,9 @@
  *   - SSR / non-browser (no `window`).
  *   - `localhost`, `127.0.0.1`, IPv4/IPv6 literals.
  *   - Hostnames with fewer than two labels.
- *   - Hostnames whose trailing two labels form a known multi-part public
- *     suffix (e.g. `co.uk`), where the naive `labels.slice(-2)` apex would be
- *     an attacker-registrable suffix like `auth.co.uk` rather than the real
- *     registrable domain.
+ *   - Hostnames where a registrable domain cannot be determined from the
+ *     Public Suffix List, including private hosted suffixes such as
+ *     `github.io`, `pages.dev`, and `netlify.app`.
  *
  * When the page is already loaded ON the IdP itself (`auth.<anything>`),
  * the helper returns the current origin so the SDK keeps everything
@@ -35,21 +34,8 @@
  * is required for end-to-end FedCM correctness — no per-RP config.
  */
 /**
- * Known multi-part public suffixes where the registrable domain is the LAST
- * THREE labels, not two. Deriving an apex from `labels.slice(-2)` against any
- * of these would yield an attacker-registrable suffix (e.g. `auth.co.uk`),
- * so we bail out instead.
- *
- * This is intentionally a small, explicit allow-list rather than the full
- * Public Suffix List — it covers the suffixes the Oxy ecosystem's RPs use.
- * Any multi-part-TLD RP MUST extend this set (or wire in a proper PSL check)
- * before relying on this helper, otherwise auto-detection silently bails to
- * `undefined` and the consumer must pass `authWebUrl` explicitly.
- */
-export declare const MULTIPART_TLDS: ReadonlySet<string>;
-/**
- * Compute the bare registrable apex (eTLD+1) of a hostname, guarding against
- * multi-part public suffixes.
+ * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
+ * Suffix List, including private hosted suffixes.
  *
  * This is the pure host-handling kernel shared by {@link autoDetectAuthWebUrl}
  * and the IdP worker — it performs NO protocol handling, NO `auth.` prefixing,
@@ -61,10 +47,7 @@ export declare const MULTIPART_TLDS: ReadonlySet<string>;
  *   - IPv4 literals (`192.168.1.10`);
  *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
  *   - single-label hosts (`intranet`, `localhost`);
- *   - hosts whose trailing two labels form a known multi-part public suffix
- *     (e.g. `foo.co.uk`), where `labels.slice(-2)` would yield an
- *     attacker-registrable suffix (`co.uk`) rather than a real registrable
- *     domain. Such hosts MUST configure `authWebUrl` explicitly.
+ *   - public suffixes without a registrable label (e.g. `co.uk`, `github.io`).
  *
  * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
  * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.9.1",
+  "version": "3.10.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -105,6 +105,7 @@
     "invariant": "^2.2.4",
     "jwt-decode": "^4.0.0",
     "socket.io-client": "^4.8.1",
+    "tldts": "^7.0.22",
     "zod": "^3.25.64"
   },
   "peerDependencies": {

package/src/__tests__/authSocket.test.ts

@@ -0,0 +1,96 @@
+import { OxyServices } from '../OxyServices';
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.forged-signature`;
+}
+
+async function runAuthSocket(oxy: OxyServices, token: string) {
+  const socket: {
+    handshake: { auth: { token: string } };
+    data?: Record<string, unknown>;
+    user?: { id: string; userId: string; sessionId?: string | null };
+  } = { handshake: { auth: { token } } };
+  let nextError: Error | undefined;
+
+  await oxy.authSocket()(socket, (err?: Error) => {
+    nextError = err;
+  });
+
+  return { socket, nextError };
+}
+
+describe('authSocket', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('rejects decoded JWT payloads that do not include a server-validated session', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const fetchMock = jest.fn();
+    globalThis.fetch = fetchMock;
+
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'victimUserId',
+      exp: 4102444800,
+    }));
+
+    expect(nextError?.message).toBe('Session required');
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(socket.data?.userId).toBeUndefined();
+    expect(socket.user).toBeUndefined();
+  });
+
+  it('rejects tokens whose decoded user does not match the validated session user', async () => {
+    globalThis.fetch = async () =>
+      jsonResponse({
+        valid: true,
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        lastActivity: '2026-06-24T00:00:00.000Z',
+        user: { id: 'realUserId', username: 'real', publicKey: 'pub_1' },
+      });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'victimUserId',
+      sessionId: 'session_1',
+      exp: 4102444800,
+    }));
+
+    expect(nextError?.message).toBe('Session user mismatch');
+    expect(socket.data?.userId).toBeUndefined();
+    expect(socket.user).toBeUndefined();
+  });
+
+  it('attaches the validated session user when the decoded user matches', async () => {
+    globalThis.fetch = async () =>
+      jsonResponse({
+        valid: true,
+        expiresAt: '2099-01-01T00:00:00.000Z',
+        lastActivity: '2026-06-24T00:00:00.000Z',
+        user: { id: 'user_1', username: 'nate', publicKey: 'pub_1' },
+      });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const { socket, nextError } = await runAuthSocket(oxy, createJwt({
+      userId: 'user_1',
+      sessionId: 'session_1',
+      exp: 4102444800,
+    }));
+
+    expect(nextError).toBeUndefined();
+    expect(socket.data?.userId).toBe('user_1');
+    expect(socket.data?.sessionId).toBe('session_1');
+    expect(socket.user).toEqual({ id: 'user_1', userId: 'user_1', sessionId: 'session_1' });
+  });
+});

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

@@ -129,6 +129,15 @@
       "title": "Reputation = Trust & Growth",
       "body": "Oxy Trust is a reputation system that reacts to what you do. Helpful, respectful, constructive actions earn it. Harmful or low‑effort stuff chips it away. More reputation can unlock benefits; low reputation can limit features. It keeps things fair and rewards real contribution."
     },
+    "name": {
+      "title": "What's your name?",
+      "body": "Add your name so people know who you are.",
+      "firstLabel": "First name",
+      "firstPlaceholder": "Your first name",
+      "lastLabel": "Last name",
+      "lastPlaceholder": "Your last name",
+      "saveFailed": "Could not save your name"
+    },
     "avatar": {
       "title": "Make It Yours",
       "body": "Add an avatar so people recognize you. It will show anywhere you show up here. Skip if you want — you can add it later.",

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

@@ -849,6 +849,15 @@
       "title": "Reputación = Confianza y crecimiento",
       "body": "Oxy Trust es un sistema de reputación que reacciona a lo que haces. Las acciones útiles, respetuosas y constructivas la aumentan. Las acciones dañinas o de poco esfuerzo la reducen. Más reputación puede desbloquear beneficios; poca reputación puede limitar funciones. Mantiene la justicia y recompensa la contribución real."
     },
+    "name": {
+      "title": "¿Cuál es tu nombre?",
+      "body": "Añade tu nombre para que la gente sepa quién eres.",
+      "firstLabel": "Nombre",
+      "firstPlaceholder": "Tu nombre",
+      "lastLabel": "Apellidos",
+      "lastPlaceholder": "Tus apellidos",
+      "saveFailed": "No se pudo guardar tu nombre"
+    },
     "avatar": {
       "title": "Hazlo tuyo",
       "body": "Añade un avatar para que te reconozcan. Se mostrará donde aparezcas aquí. Puedes omitirlo — puedes añadirlo más tarde.",

package/src/index.ts

@@ -462,7 +462,7 @@ export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 // ---------------------------------------------------------------------------
 // Cross-domain SSO infrastructure
 // ---------------------------------------------------------------------------
-export { autoDetectAuthWebUrl, registrableApex, MULTIPART_TLDS } from './utils/fapiAutoDetect';
+export { autoDetectAuthWebUrl, registrableApex } from './utils/fapiAutoDetect';
 
 // Central cross-domain SSO (opaque single-use code bounce via auth.oxy.so)
 export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './utils/authWebUrl';

package/src/mixins/OxyServices.assets.ts

@@ -1,5 +1,11 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
+import { isReactNative } from '../utils/platform';
+
+interface FileDownloadUrlOptions {
+  /** Omit bearer access tokens from generated URLs, even when authenticated. */
+  omitToken?: boolean;
+}
 
 export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -44,8 +50,13 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
      *
      * For a CDN-signed URL fetched from the API, use {@link getFileDownloadUrlAsync}.
      */
-    getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string {
-      const token = this.getClient().getAccessToken();
+    getFileDownloadUrl(
+      fileId: string,
+      variant?: string,
+      expiresIn?: number,
+      options: FileDownloadUrlOptions = {}
+    ): string {
+      const token = options.omitToken ? undefined : this.getClient().getAccessToken();
 
       // Public case: no auth token and no expiry requested → clean CDN URL.
       // CloudFront serves the public media origin under `${cloudURL}/<id>`.
@@ -212,10 +223,33 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
         } 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);
+          const descriptor = file as RNFileDescriptor;
+
+          if (isReactNative()) {
+            // 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', descriptor as unknown as Blob, fileName);
+          } else {
+            // Web (browser/Node): the browser's FormData cannot read bytes from a plain
+            // { uri } object — it would serialize "[object Object]" and the server would
+            // store a 0-byte asset. Materialize the uri into a real Blob first. `fetch`
+            // resolves blob:, data:, and http(s): uris on web, so all picker outputs work.
+            const res = await fetch(descriptor.uri);
+            if (!res.ok) {
+              throw new Error(`Failed to read file from uri (status ${res.status})`);
+            }
+            const fetched = await res.blob();
+            // Preserve the descriptor's declared MIME type when the fetched blob has none.
+            const blob =
+              fetched.type === '' && descriptor.type
+                ? new Blob([fetched], { type: descriptor.type })
+                : fetched;
+            if (blob.size === 0) {
+              throw new Error('Cannot upload an empty file');
+            }
+            formData.append('file', blob, fileName);
+          }
         } else {
           throw new Error('Unsupported file input: expected File, Blob, or { uri, type?, name?, size? } descriptor');
         }