@oxyhq/core 3.10.0 → 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/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.10.0",
+  "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');
         }

package/src/mixins/OxyServices.utility.ts

@@ -856,8 +856,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             return next(new Error('Invalid token'));
           }
 
-          const userId = decoded.userId || decoded.id;
-          if (!userId) {
+          const claimedUserId = decoded.userId || decoded.id;
+          if (!claimedUserId) {
             return next(new Error('Invalid token payload'));
           }
 
@@ -866,24 +866,39 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             return next(new Error('Token expired'));
           }
 
-          // Validate session if available
-          if (decoded.sessionId) {
-            try {
-              const result = await oxyInstance.validateSession(decoded.sessionId, {
-                useHeaderValidation: true,
-              });
-              if (!result || !result.valid) {
-                return next(new Error('Session invalid'));
-              }
-            } catch (validateErr) {
-              if (debug) {
-                logger.debug('[oxy.authSocket] Session validation failed', {
-                  component: 'auth',
-                  method: 'authSocket',
-                }, validateErr);
-              }
-              return next(new Error('Session validation failed'));
+          // A server-validated session is mandatory. A bare decoded JWT proves
+          // nothing — the signature is not verified here, so without a session
+          // round-trip a forged token could claim any user id.
+          if (!decoded.sessionId) {
+            return next(new Error('Session required'));
+          }
+
+          let userId = claimedUserId;
+          try {
+            const result = await oxyInstance.validateSession(decoded.sessionId, {
+              useHeaderValidation: true,
+            });
+            if (!result || !result.valid || !result.user) {
+              return next(new Error('Session invalid'));
             }
+
+            // The session is the source of truth. The client-claimed user id
+            // must match the server-validated identity, otherwise a valid
+            // session could be paired with a forged user id.
+            const validatedUserId = getUserIdentityId(result.user);
+            if (!validatedUserId || validatedUserId !== claimedUserId) {
+              return next(new Error('Session user mismatch'));
+            }
+
+            userId = validatedUserId;
+          } catch (validateErr) {
+            if (debug) {
+              logger.debug('[oxy.authSocket] Session validation failed', {
+                component: 'auth',
+                method: 'authSocket',
+              }, validateErr);
+            }
+            return next(new Error('Session validation failed'));
           }
 
           // Attach user data to socket. We expose BOTH `socket.data.userId`
@@ -953,9 +968,9 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
      * 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.
@@ -988,7 +1003,13 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
           return;
         }
 
-        if (appScopes.includes(scope) || delegatedScopes.includes(scope)) {
+        const appHasScope = appScopes.includes(scope);
+        const delegationHasScope = delegatedScopes.includes(scope);
+        const hasRequiredScope = req.serviceActingAs
+          ? appHasScope && delegationHasScope
+          : appHasScope;
+
+        if (hasRequiredScope) {
           next();
           return;
         }
@@ -1051,6 +1072,19 @@ async function verifyServiceTokenSignature(token: string, secret: string): Promi
  * access token signed by the same shared secret could be replayed as a
  * service token because no claim binding existed.
  */
+/**
+ * Resolve the canonical user id from a validated session's user object.
+ *
+ * The API serializer emits `id`, but some upstream shapes carry the raw Mongo
+ * `_id` instead. We accept either, but only a non-empty string — anything else
+ * means the validated identity is unusable and the caller must reject.
+ */
+function getUserIdentityId(user: User): string | null {
+  const candidate = (user as { id?: unknown; _id?: unknown }).id
+    ?? (user as { id?: unknown; _id?: unknown })._id;
+  return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
+}
+
 function verifyServiceTokenClaims(
   decoded: JwtPayload,
   expected: { audience: string; issuer: string },

package/src/mixins/__tests__/assetUpload.test.ts

@@ -0,0 +1,191 @@
+/**
+ * `OxyServices.assetUpload()` multipart-body tests.
+ *
+ * `assetUpload` accepts three input shapes: a web `File`, a web `Blob`, or a
+ * React Native `{ uri, type?, name?, size? }` descriptor. The descriptor path
+ * is platform-sensitive:
+ *
+ *   - React Native — RN's FormData reads the file from disk via the uri during
+ *     the multipart request, so the descriptor is appended as-is.
+ *   - Web (browser/Node) — the browser's FormData CANNOT read bytes from a plain
+ *     `{ uri }` object (it would serialize `[object Object]` → the server stores
+ *     a 0-byte asset). The uri must be materialized into a real `Blob` via
+ *     `fetch` before appending. An empty fetched blob must throw instead of
+ *     silently uploading an empty asset.
+ *
+ * These tests assert exactly which value lands in the FormData `file` part for
+ * each platform, and that an empty web source is rejected.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+/**
+ * Captures every `FormData.append` call so a test can inspect the multipart body
+ * that `assetUpload` built without sending a real network request.
+ */
+function captureUpload(oxy: OxyServices) {
+  const appended: Array<{ name: string; value: unknown; fileName?: string }> = [];
+  // Capture-only: do NOT delegate to the real (undici) FormData.append. Node's
+  // undici rejects a plain { uri } object as not-a-Blob, but real React Native
+  // FormData accepts it — the test asserts on captured args, not a built body.
+  const appendSpy = jest
+    .spyOn(FormData.prototype, 'append')
+    .mockImplementation(function (this: FormData, name: string, value: unknown, fileName?: string) {
+      appended.push({ name, value, fileName });
+    });
+
+  const requestSpy = jest
+    .spyOn(oxy.getClient(), 'request')
+    .mockResolvedValue({ file: { id: 'asset123' } } as never);
+
+  return {
+    appended,
+    requestSpy,
+    restore: () => {
+      appendSpy.mockRestore();
+      requestSpy.mockRestore();
+    },
+  };
+}
+
+describe('OxyServices.assetUpload — uri descriptor', () => {
+  const originalNavigator = (globalThis as { navigator?: unknown }).navigator;
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    if (originalNavigator === undefined) {
+      delete (globalThis as { navigator?: unknown }).navigator;
+    } else {
+      (globalThis as { navigator?: unknown }).navigator = originalNavigator;
+    }
+    globalThis.fetch = originalFetch;
+  });
+
+  describe('web (NOT React Native)', () => {
+    beforeEach(() => {
+      // Node/jsdom-like: no React Native navigator → isReactNative() === false.
+      delete (globalThis as { navigator?: unknown }).navigator;
+    });
+
+    it('materializes a blob: uri into a real, non-empty Blob before appending', async () => {
+      const bytes = new Blob([new Uint8Array([1, 2, 3, 4, 5])], { type: 'image/png' });
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue({ ok: true, status: 200, blob: async () => bytes });
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      try {
+        await oxy.assetUpload({ uri: 'blob:https://app.test/abc', type: 'image/png', name: 'avatar.png' });
+
+        expect(fetchMock).toHaveBeenCalledWith('blob:https://app.test/abc');
+
+        const filePart = capture.appended.find((p) => p.name === 'file');
+        expect(filePart).toBeDefined();
+        // The appended value is the fetched Blob with real bytes — NOT the { uri } object.
+        expect(filePart?.value).toBeInstanceOf(Blob);
+        expect((filePart?.value as Blob).size).toBe(5);
+        expect((filePart?.value as { uri?: string }).uri).toBeUndefined();
+        expect(filePart?.fileName).toBe('avatar.png');
+      } finally {
+        capture.restore();
+      }
+    });
+
+    it('wraps a typeless fetched blob with the descriptor MIME type', async () => {
+      const typeless = new Blob([new Uint8Array([9, 9, 9])]); // type === ''
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue({ ok: true, status: 200, blob: async () => typeless });
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      try {
+        await oxy.assetUpload({ uri: 'data:application/octet-stream;base64,CQkJ', type: 'image/jpeg', name: 'x.jpg' });
+
+        const filePart = capture.appended.find((p) => p.name === 'file');
+        expect(filePart?.value).toBeInstanceOf(Blob);
+        expect((filePart?.value as Blob).size).toBe(3);
+        expect((filePart?.value as Blob).type).toBe('image/jpeg');
+      } finally {
+        capture.restore();
+      }
+    });
+
+    it('throws "Cannot upload an empty file" when the fetched blob is empty', async () => {
+      const empty = new Blob([], { type: 'image/png' });
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue({ ok: true, status: 200, blob: async () => empty });
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      try {
+        await expect(
+          oxy.assetUpload({ uri: 'blob:https://app.test/empty', type: 'image/png', name: 'empty.png' }),
+        ).rejects.toThrow('Cannot upload an empty file');
+
+        // Nothing was sent — the empty source surfaces instead of creating a 0-byte asset.
+        expect(capture.requestSpy).not.toHaveBeenCalled();
+      } finally {
+        capture.restore();
+      }
+    });
+
+    it('throws when the uri cannot be fetched (non-ok response)', async () => {
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue({ ok: false, status: 404, blob: async () => new Blob([]) });
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      try {
+        await expect(
+          oxy.assetUpload({ uri: 'https://cdn.test/missing.png', type: 'image/png', name: 'missing.png' }),
+        ).rejects.toThrow('Failed to read file from uri (status 404)');
+        expect(capture.requestSpy).not.toHaveBeenCalled();
+      } finally {
+        capture.restore();
+      }
+    });
+  });
+
+  describe('React Native', () => {
+    beforeEach(() => {
+      // Make isReactNative() === true: navigator.product === 'ReactNative'.
+      (globalThis as { navigator?: unknown }).navigator = { product: 'ReactNative' };
+    });
+
+    it('appends the descriptor as-is and never calls fetch', async () => {
+      const fetchMock = jest.fn();
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      const descriptor = { uri: 'file:///tmp/avatar.png', type: 'image/png', name: 'avatar.png', size: 1024 };
+
+      try {
+        await oxy.assetUpload(descriptor);
+
+        // RN path: the raw descriptor object lands in the multipart body unchanged.
+        const filePart = capture.appended.find((p) => p.name === 'file');
+        expect(filePart?.value).toBe(descriptor);
+        expect(filePart?.fileName).toBe('avatar.png');
+        // No in-JS materialization on RN — FormData reads the file from the uri.
+        expect(fetchMock).not.toHaveBeenCalled();
+      } finally {
+        capture.restore();
+      }
+    });
+  });
+});

package/src/mixins/__tests__/getFileDownloadUrl.test.ts

@@ -49,6 +49,19 @@ describe('OxyServices.getFileDownloadUrl', () => {
         'https://cloud.oxy.so/a%2Fb%20c?variant=large%20size',
       );
     });
+
+    it('can omit the token for persisted public image URLs while authenticated', () => {
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      oxy.setTokens('access-token-abc');
+
+      const url = oxy.getFileDownloadUrl('file123', 'thumb', undefined, {
+        omitToken: true,
+      });
+
+      expect(url).toBe('https://cloud.oxy.so/file123?variant=thumb');
+      expect(url).not.toContain('access-token-abc');
+      expect(url).not.toContain('token=');
+    });
   });
 
   describe('signed / private assets → authenticated API origin', () => {