@oxyhq/core 12.5.4 → 12.7.0

package/dist/types/OxyServices.d.ts

@@ -57,7 +57,7 @@
  * See method JSDoc for more details and options.
  */
 import { type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
-import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
+import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 import { composeOxyServices } from './mixins';
 /**
  * OxyServices - Unified client library for interacting with the Oxy API
@@ -121,7 +121,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     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 { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError };
 /**
  * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
  */

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

@@ -6,6 +6,46 @@ export declare class OxyAuthenticationError extends Error {
     readonly status: number;
     constructor(message: string, code?: string, status?: number);
 }
+/**
+ * Thrown when an asset's authorized download URL cannot be resolved.
+ *
+ * `getFileDownloadUrlAsync` asks the API for a URL that is valid for the
+ * CALLER and the asset's actual visibility. When that resolution fails there is
+ * no honest fallback: the public CDN origin only serves `public` assets, so
+ * handing back `https://cloud.oxy.so/<id>` for an unresolved asset produces a
+ * hard 404 at render time and hides the real failure from the caller. This
+ * error surfaces the failure instead.
+ *
+ * The message and fields deliberately carry only the asset id, the requested
+ * variant and the HTTP status — never the resolved URL, which embeds a scoped
+ * media token.
+ *
+ * ## `status` lets a caller decide whether a CDN fallback is safe
+ *
+ * Core itself never falls back to the public CDN builder, because it has no
+ * knowledge of the asset's visibility and that URL is a guaranteed 404 for a
+ * private asset. A CALLER that knows an asset is public MAY choose to fall back
+ * to `getFileDownloadUrl(id, variant)` — but only for a TRANSIENT failure, not
+ * a definitive denial:
+ *   - `status` 401/403/404 → definitive: the asset is private/denied/missing.
+ *     Never CDN-fall-back — it will 404.
+ *   - `status` undefined (network error) or 5xx → transient: resolution itself
+ *     failed. If the caller independently knows the asset is public, a CDN
+ *     fallback is defensible best-effort.
+ */
+export declare class AssetUrlResolutionError extends Error {
+    readonly code = "ASSET_URL_UNRESOLVED";
+    readonly fileId: string;
+    readonly variant?: string;
+    readonly status?: number;
+    /**
+     * The underlying transport/API failure, when there was one. Declared on the
+     * class rather than relying on `Error.cause` because this package targets
+     * ES2020, where `cause` is not part of the `Error` type.
+     */
+    readonly cause?: unknown;
+    constructor(fileId: string, variant: string | undefined, status: number | undefined, cause?: unknown);
+}
 export declare class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
     constructor(operationName: string, timeoutMs: number);
 }

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

@@ -321,6 +321,26 @@ export declare class KeyManager {
      * "not-hex" pass through as a valid (but compromised, near-zero) key.
      */
     static isValidPrivateKey(privateKey: string): boolean;
+    /**
+     * Derive a 32-byte, domain-separated seed from the on-device Oxy identity
+     * private key via HKDF-SHA256, WITHOUT ever exposing the raw private key.
+     *
+     * The domain separation is carried by `info` (e.g. `"oxypay/faircoin/v1"`),
+     * so distinct apps/purposes get independent seeds from the same identity.
+     * The output is HKDF keying material, never the private key itself — a
+     * consumer (e.g. Oxy Pay's FairCoin HD wallet) can feed it straight into
+     * `HDKey.fromMasterSeed` and never touches the identity key.
+     *
+     * Key source (native only): prefers the shared ecosystem identity written to
+     * `group.so.oxy.shared` (what a Relying Party like Oxy Pay reads), then falls
+     * back to this device's primary identity (Commons/Accounts). Both reproduce
+     * from the user's Oxy recovery phrase, so the derived seed is recoverable.
+     *
+     * @param info Context/domain-binding label (distinct labels → independent seeds).
+     * @returns 32 bytes of derived keying material, or `null` on web / when no
+     *          identity key is available on this device.
+     */
+    static deriveScopedSeed(info: string): Promise<Uint8Array | null>;
     /**
      * Get a shortened version of the public key for display
      * Format: first 8 chars...last 8 chars

package/dist/types/index.d.ts

@@ -17,7 +17,7 @@
  * If a symbol does not appear here, it is NOT part of the public API.
  */
 import './crypto/polyfill';
-export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
+export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
 export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';
@@ -26,6 +26,7 @@ export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 export type { CommonsSignInHandle, CommonsSignInStatus, CommonsApprovalInfo, CommonsSignInActionResult, } from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
+export type { InitDeviceTransferResult, DeviceTransferOutcome, } from './mixins/OxyServices.deviceTransfer';
 export type { BulkFollowEntry, BulkFollowResult, BulkUnfollowEntry, BulkUnfollowResult, FollowMutationResult, ViewerGraph, } from './mixins/OxyServices.user';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
@@ -58,7 +59,7 @@ export type { AeadResult } from './crypto/aead';
 export { deriveSharedSecret } from './crypto/ecdh';
 export { DeviceManager } from './utils/deviceManager';
 export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
-export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
+export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, BatchFileAccessEntry, BatchFileAccessResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 export { TopicType, TopicSource } from './models/Topic';
 export type { TopicData, TopicTranslation, TopicListResult } from './models/Topic';

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

@@ -1,4 +1,4 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, BatchFileAccessResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -17,18 +17,57 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          */
         deleteFile(fileId: string): Promise<any>;
         /**
-         * Build a synchronous, `<img src>`-ready file URL from an Oxy asset id.
+         * Build a synchronous, `<img src>`-ready URL for a **PUBLIC** Oxy asset.
          *
-         * This method must never embed the caller's general access token in the
-         * returned URL. The URL is commonly rendered into DOM attributes, browser
-         * network panels, caches, and logs. Public asset URLs use the clean CDN
-         * origin; callers that need authorized/private access should use
-         * {@link getFileDownloadUrlAsync}, which asks the API for a scoped download
-         * URL instead of exposing the in-memory bearer token in a query string.
+         * ## Contract — read before calling
+         *
+         * This is a pure string builder. It performs no network call and therefore
+         * has **no knowledge of the asset's visibility**. It always produces the
+         * public form: `${cloudURL}/<id>[?variant=…]`, which the CDN serves from
+         * the public media origin only.
+         *
+         * Consequently:
+         *  - Call it ONLY when the asset is known to be `public` — e.g. avatars and
+         *    profile banners, which {@link uploadAvatar} / {@link uploadProfileBanner}
+         *    upload with `visibility: 'public'`.
+         *  - For an asset that may be `private` or `unlisted` — anything uploaded
+         *    through the generic {@link assetUpload} path, whose server-side default
+         *    is private — this URL resolves to a hard **404**. Use
+         *    {@link getFileDownloadUrlAsync}, which asks the API for a URL scoped to
+         *    the current caller.
+         *  - It must never guess visibility, and must never embed the caller's
+         *    bearer token: the returned string is rendered into DOM attributes,
+         *    browser network panels, HTTP caches, and logs.
+         *
+         * Passing `expiresIn` switches to the API-origin stream form
+         * (`${baseURL}/assets/<id>/stream?…`) WITHOUT any credential. That form
+         * still only serves what an unauthenticated request may see — it is not a
+         * synchronous private-asset path, and none exists: authorization for a
+         * private asset requires the round-trip in {@link getFileDownloadUrlAsync}.
          */
         getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string;
         /**
-         * Get file download URL asynchronously (returns signed URL directly from CDN)
+         * Resolve an asset id to a URL that is valid for the CURRENT caller,
+         * whatever the asset's visibility.
+         *
+         * Asks the API (`GET /assets/:id/url`) rather than guessing: a `public`
+         * asset resolves to the CDN form, while a `private`/`unlisted` asset the
+         * caller may read resolves to an API-origin stream URL carrying a scoped,
+         * short-lived media token. The returned URL is passed through **unchanged**
+         * — the SDK never rewrites, re-signs, or strips it.
+         *
+         * ## Failure behaviour — no CDN fallback
+         *
+         * Throws {@link AssetUrlResolutionError} when the API returns no URL or the
+         * request fails (including 401/403/404). It deliberately does NOT fall back
+         * to {@link getFileDownloadUrl}: that builder only produces the public CDN
+         * form, so falling back would hand the caller a URL that renders as a hard
+         * 404 for every private asset and would silently swallow the real failure.
+         * A caller that knows an asset is public should call the synchronous
+         * builder directly instead of relying on a fallback here.
+         *
+         * The resolved URL is cached per identity for well under the media token's
+         * lifetime — see {@link getAssetUrlCacheTTL}.
          */
         getFileDownloadUrlAsync(fileId: string, variant?: string, expiresIn?: number): Promise<string>;
         /**
@@ -52,13 +91,53 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          */
         getFileContentAsBlob(fileId: string, variant?: string): Promise<Blob>;
         /**
-         * Get batch access to multiple files
+         * Resolve access + a caller-scoped URL for many assets — each with its OWN
+         * requested variant — in ONE round trip via `POST /assets/batch-access`.
+         *
+         * `requests` is a per-file `{ fileId, variant? }` list (a `variant` of
+         * `undefined` asks for the original). `options.expiresIn` sets the requested
+         * media-token / signed-URL lifetime (seconds); `options.context` is the
+         * server-side access-check context. Entries with a blank `fileId` are
+         * dropped and exact `(fileId, variant)` duplicates are collapsed before the
+         * request; an empty effective list performs no network call.
+         *
+         * The server caps the batch at 100 entries — callers that page beyond that
+         * must chunk. Returns the raw per-file envelope (see
+         * {@link BatchFileAccessResponse}); most callers want {@link getFileDownloadUrls},
+         * which flattens it to just the usable URLs.
          */
-        getBatchFileAccess(fileIds: string[], context?: string): Promise<Record<string, any>>;
+        getBatchFileAccess(requests: Array<{
+            fileId: string;
+            variant?: string;
+        }>, options?: {
+            expiresIn?: number;
+            context?: string;
+        }): Promise<BatchFileAccessResponse>;
         /**
-         * Get download URLs for multiple files efficiently
+         * Resolve many assets — each with its OWN variant — to caller-scoped,
+         * `<img src>`-ready URLs in one round trip. The batch counterpart of
+         * {@link getFileDownloadUrlAsync}, built to resolve a whole grid page at once.
+         *
+         * `requests` is a per-file `{ fileId, variant? }` list (e.g. `poster` for a
+         * video, `thumb` for an image); the per-file variant RULE lives in the
+         * caller — core just forwards what it is given. `options.expiresIn` /
+         * `options.context` are passed through to the endpoint.
+         *
+         * Each returned URL is the API's own scoped form, passed through unchanged:
+         * the public CDN URL for a public asset, or an API-origin
+         * `/assets/:id/stream?…&mt=<media token>` URL for a private asset the caller
+         * may read. Ids the caller cannot access (or that do not exist) are simply
+         * OMITTED from the returned map — there is NO public-CDN fallback, so a grid
+         * never renders a known-404 URL. Callers detect a miss by the absent key
+         * (the map never contains an empty-string value). Keyed by `fileId`.
          */
-        getFileDownloadUrls(fileIds: string[], context?: string): Promise<Record<string, string>>;
+        getFileDownloadUrls(requests: Array<{
+            fileId: string;
+            variant?: string;
+        }>, options?: {
+            expiresIn?: number;
+            context?: string;
+        }): Promise<Record<string, string>>;
         /**
          * Resolve many Oxy asset ids to their content-addressed metadata in one
          * round-trip per chunk via `POST /assets/service/by-ids` (body `{ ids }`).
@@ -170,6 +249,17 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         assetUpdateVisibility(fileId: string, visibility: "private" | "public" | "unlisted"): Promise<any>;
         uploadAvatar(file: AssetUploadInput, userId: string, app?: string): Promise<any>;
         uploadProfileBanner(file: AssetUploadInput, userId: string, app?: string): Promise<any>;
+        /**
+         * How long a resolved asset URL may stay in the SDK's GET cache, in ms.
+         *
+         * A resolved private-asset URL dies the instant its scoped media token
+         * expires (~{@link ASSET_MEDIA_TOKEN_TTL_MS}). Caching it for its full
+         * nominal lifetime would leave a window where the cache serves an
+         * already-dead URL (clock skew, render-pipeline latency, an image request
+         * queued behind others). So the TTL is (a) never longer than the token's
+         * lifetime and (b) discounted to {@link ASSET_URL_CACHE_LIFETIME_FRACTION}
+         * of that bound — comfortably below the token TTL by construction.
+         */
         getAssetUrlCacheTTL(expiresIn?: number): number;
         fetchAssetDownloadUrl(fileId: string, variant?: string, cacheTTL?: number, expiresIn?: number): Promise<string | null>;
         fetchAssetContent(url: string, type: "text"): Promise<string>;

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

@@ -0,0 +1,149 @@
+/**
+ * Device-to-device Identity Transfer Mixin (b3 Feature 2 — "add a device")
+ *
+ * Clones an existing device's secp256k1 identity onto a fresh device over a
+ * short-lived, unauthenticated relay, WITHOUT the server ever holding a
+ * decryption key. Both devices end up holding the SAME private key.
+ *
+ * The two devices agree on a symmetric key via an ephemeral secp256k1 ECDH
+ * handshake (Phase-0 crypto): `deriveSharedSecret` → `hkdfSha256` → a per-pairing
+ * transfer key, used with `encryptAead`/`decryptAead` (XChaCha20-Poly1305) to
+ * seal `{ privateKey, publicKey }`. The relay carries only ephemeral public keys
+ * plus opaque ciphertext — a passive/at-rest-compromised backend cannot decrypt.
+ *
+ * Roles:
+ *  - NEW device (no identity): {@link initDeviceTransfer} (generate ephemeral
+ *    pair, register the pairing, render `pairingId` as a QR) then
+ *    {@link subscribeDeviceTransfer} (await approval over the `/device-pair`
+ *    socket with a poll fallback, decrypt, and import the key).
+ *  - OLD device (has identity): {@link getDeviceTransferInfo} (resolve the
+ *    scanned `pairingId` server-side — the QR is NOT self-contained) then
+ *    {@link approveDeviceTransfer} (biometric-gate in the UI, seal the key
+ *    material, and post it with a fresh signature over the CURRENT identity key).
+ *
+ * SECURITY: E2E against a passive relay only. Explicitly NOT hardened against an
+ * actively-malicious backend MITM'ing the ephemeral keys (same trust boundary as
+ * the existing QR sign-in; SAS compare deferred per owner decision). Approve
+ * requires BOTH a bearer token AND a fresh identity-key signature.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import type { DeviceTransferInfoResponse, DeviceTransferApproveResponse, DeviceTransferDenyResponse } from '@oxyhq/contracts';
+/** Result of {@link OxyServicesDeviceTransferMixin.initDeviceTransfer}. */
+export interface InitDeviceTransferResult {
+    /** 128-bit single-use handle to render in the QR (also the HKDF salt). */
+    pairingId: string;
+    /** ISO-8601 expiry (3 minutes). */
+    expiresAt: string;
+    /** The new device's ephemeral public key registered with the relay. */
+    newEphemeralPublicKey: string;
+}
+/** Terminal outcome delivered to {@link subscribeDeviceTransfer}'s callback. */
+export type DeviceTransferOutcome = {
+    status: 'approved';
+    publicKey: string;
+} | {
+    status: 'denied';
+} | {
+    status: 'expired';
+};
+export declare function OxyServicesDeviceTransferMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * NEW device — begin an "add a device" transfer. Generates a single-use
+         * ephemeral secp256k1 pair, registers the pairing, and returns the
+         * `pairingId` to render as a QR. The ephemeral private key is held in memory
+         * (keyed by `pairingId`) for the subsequent {@link subscribeDeviceTransfer}.
+         *
+         * @param label - Optional human-readable label for this new device.
+         */
+        initDeviceTransfer(label?: string): Promise<InitDeviceTransferResult>;
+        /**
+         * Resolve a pairing server-side (the QR carries only `pairingId`). The OLD
+         * device calls this after scanning to read the new device's ephemeral public
+         * key + label; the NEW device polls it to fetch the sealed material once
+         * approved. Public — no auth required.
+         */
+        getDeviceTransferInfo(pairingId: string): Promise<DeviceTransferInfoResponse>;
+        /**
+         * OLD device — approve a scanned transfer. Reads the new device's ephemeral
+         * public key, derives the shared transfer key, AEAD-seals
+         * `{ privateKey, publicKey }`, and posts it PLUS a fresh signature over
+         * `{ action:'approve_device_transfer', pairingId, timestamp }` made with the
+         * CURRENT identity key (dual-proof alongside the bearer token).
+         *
+         * NATIVE-ONLY: requires a stored identity (throws otherwise). The UI must
+         * biometric-gate before calling this — a key clone leaves the device.
+         */
+        approveDeviceTransfer(pairingId: string): Promise<DeviceTransferApproveResponse>;
+        /**
+         * OLD device — deny (cancel) a scanned transfer so the waiting new device
+         * stops. Public — no auth required.
+         */
+        denyDeviceTransfer(pairingId: string): Promise<DeviceTransferDenyResponse>;
+        /**
+         * NEW device — await approval for a pairing started with
+         * {@link initDeviceTransfer}, then decrypt and import the transferred
+         * identity key. Primary path is an instant `device_pair_update` push over the
+         * `/device-pair` socket; a poll backstops a socket that can't connect.
+         *
+         * On `approved`: re-derives the shared transfer key from the old device's
+         * ephemeral public key, decrypts `{ privateKey, publicKey }`, imports it via
+         * `KeyManager.importKeyPair(privateKey, { overwrite: false })`, and invokes
+         * `onOutcome({ status:'approved', publicKey })`. The caller then runs the
+         * NORMAL challenge/verify sign-in — this method does not mint a session.
+         *
+         * @returns An unsubscribe function; call it to stop waiting (also called
+         *   automatically once the transfer settles).
+         */
+        subscribeDeviceTransfer(pairingId: string, onOutcome: (outcome: DeviceTransferOutcome) => void): () => void;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

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

@@ -29,6 +29,7 @@ import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
+import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -38,7 +39,7 @@ import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/dist/types/models/interfaces.d.ts

@@ -448,6 +448,24 @@ export interface AssetUrlResponse {
     variant?: string;
     expiresIn: number;
 }
+/**
+ * Per-file result of `POST /assets/batch-access`. `allowed` is authoritative:
+ * when `false` the entry carries an `error` string (e.g. `'Access denied'`,
+ * `'File not found'`) and no `url`. When `true`, `url` is a caller-scoped,
+ * `<img src>`-ready URL — the public CDN form for a public asset or an
+ * API-origin stream URL carrying a short-lived media token for a private one.
+ */
+export interface BatchFileAccessEntry {
+    allowed: boolean;
+    url?: string;
+    visibility?: FileVisibility;
+    mime?: string;
+    error?: string;
+}
+/** Envelope returned by `POST /assets/batch-access`, keyed by file id. */
+export interface BatchFileAccessResponse {
+    results: Record<string, BatchFileAccessEntry>;
+}
 export interface AssetDeleteSummary {
     fileId: string;
     wouldDelete: boolean;

package/dist/types/session/SessionClient.d.ts

@@ -93,8 +93,25 @@ export declare class SessionClient {
     onServerEvent(event: string, listener: (payload: unknown) => void): () => void;
     private bindServerEvent;
     protected notify(): void;
-    /** Validate + last-writer-wins by revision. Returns true if applied. */
-    protected applyState(raw: unknown, origin?: SessionStateOrigin): boolean;
+    /**
+     * Validate + last-writer-wins by revision. Returns true if applied.
+     *
+     * `activeToken` (sync path only) is the server-issued access token for
+     * `raw.activeAccountId`. When present and the state is applied, it is planted
+     * BEFORE any subscriber is notified so the bearer already belongs to the new
+     * active account — the local switch/bootstrap path then needs no redundant
+     * device-secret mint. Push-origin applies carry no token and rely on the
+     * mint-before-notify gate below.
+     *
+     * ORDERING INVARIANT: a subscriber must NEVER observe a newly-active account
+     * while the planted bearer still identifies the PREVIOUS one — otherwise a
+     * `useCurrentUser`-style refetch fires under the wrong account's token (the
+     * account-switch 404 race). So when a transport is available and the planted
+     * bearer does not already belong to `next.activeAccountId`, minting is awaited
+     * BEFORE `notify()`. This covers EVERY notify source (a switch push, a
+     * cross-device push, a cold mint), not just the initial "no bearer yet" case.
+     */
+    protected applyState(raw: unknown, origin?: SessionStateOrigin, activeToken?: string): boolean;
     /**
      * Validate `{ state, activeToken }`, apply the state, and plant the active token host-side.
      * Token-planting is decoupled from whether `applyState` advanced the revision: a socket push

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

@@ -0,0 +1,17 @@
+/**
+ * URL redaction for logging.
+ *
+ * Asset URLs the API hands back for private assets carry a scoped, short-lived
+ * media token (`mt=…`) in their query string. That token is a bearer credential
+ * for the underlying object, so it must never land in a log line, breadcrumb,
+ * or metric — a captured log would otherwise grant read access until the token
+ * expires. Query strings on API URLs can also carry other sensitive params, so
+ * we redact the whole query rather than allow-listing one key.
+ *
+ * `redactUrlQuery` returns the URL's path portion with a `?<redacted>` marker
+ * when a query string is present, and the input unchanged otherwise. It is
+ * defensive: any input that does not parse as a URL is passed through as-is,
+ * except that a bare `?query` tail is still stripped so a relative path with a
+ * query never leaks.
+ */
+export declare function redactUrlQuery(url: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.5.4",
+  "version": "12.7.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -21,6 +21,7 @@ import { jwtDecode } from 'jwt-decode';
 import { isNative, getPlatformOS } from './utils/platform';
 import { isReactNative } from '@oxyhq/protocol';
 import { computeIdentityTag, fnv1a32 } from './utils/cacheKey';
+import { redactUrlQuery } from './utils/redactUrl';
 import type { OxyConfig } from './models/interfaces';
 import type { DeviceSecretMintOutcome } from './session/refresh';
 
@@ -405,7 +406,9 @@ export class HttpService {
       const cached = this.cache.get(cacheKey) as T | null;
       if (cached !== null) {
         this.requestMetrics.cacheHits++;
-        this.logger.debug('Cache hit:', url);
+        // Redact the query string: an asset stream URL passed here carries a
+        // scoped `mt=` media token that must never reach a log sink.
+        this.logger.debug('Cache hit:', redactUrlQuery(url));
         return cached;
       }
       this.requestMetrics.cacheMisses++;

package/src/OxyServices.errors.ts

@@ -13,6 +13,57 @@ export class OxyAuthenticationError extends Error {
   }
 }
 
+/**
+ * Thrown when an asset's authorized download URL cannot be resolved.
+ *
+ * `getFileDownloadUrlAsync` asks the API for a URL that is valid for the
+ * CALLER and the asset's actual visibility. When that resolution fails there is
+ * no honest fallback: the public CDN origin only serves `public` assets, so
+ * handing back `https://cloud.oxy.so/<id>` for an unresolved asset produces a
+ * hard 404 at render time and hides the real failure from the caller. This
+ * error surfaces the failure instead.
+ *
+ * The message and fields deliberately carry only the asset id, the requested
+ * variant and the HTTP status — never the resolved URL, which embeds a scoped
+ * media token.
+ *
+ * ## `status` lets a caller decide whether a CDN fallback is safe
+ *
+ * Core itself never falls back to the public CDN builder, because it has no
+ * knowledge of the asset's visibility and that URL is a guaranteed 404 for a
+ * private asset. A CALLER that knows an asset is public MAY choose to fall back
+ * to `getFileDownloadUrl(id, variant)` — but only for a TRANSIENT failure, not
+ * a definitive denial:
+ *   - `status` 401/403/404 → definitive: the asset is private/denied/missing.
+ *     Never CDN-fall-back — it will 404.
+ *   - `status` undefined (network error) or 5xx → transient: resolution itself
+ *     failed. If the caller independently knows the asset is public, a CDN
+ *     fallback is defensible best-effort.
+ */
+export class AssetUrlResolutionError extends Error {
+  public readonly code = 'ASSET_URL_UNRESOLVED';
+  public readonly fileId: string;
+  public readonly variant?: string;
+  public readonly status?: number;
+  /**
+   * The underlying transport/API failure, when there was one. Declared on the
+   * class rather than relying on `Error.cause` because this package targets
+   * ES2020, where `cause` is not part of the `Error` type.
+   */
+  public readonly cause?: unknown;
+
+  constructor(fileId: string, variant: string | undefined, status: number | undefined, cause?: unknown) {
+    const variantSuffix = variant ? ` (variant "${variant}")` : '';
+    const statusSuffix = typeof status === 'number' ? ` — status ${status}` : '';
+    super(`Could not resolve a download URL for asset "${fileId}"${variantSuffix}${statusSuffix}`);
+    this.name = 'AssetUrlResolutionError';
+    this.fileId = fileId;
+    this.variant = variant;
+    this.status = status;
+    this.cause = cause;
+  }
+}
+
 export class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
   constructor(operationName: string, timeoutMs: number) {
     super(

package/src/OxyServices.ts

@@ -57,7 +57,7 @@
  * See method JSDoc for more details and options.
  */
 import { OxyServicesBase, type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
-import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
+import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 
 // Import mixin composition helper
 import { composeOxyServices } from './mixins';
@@ -151,7 +151,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
 }
 
 // Re-export error classes for convenience
-export { OxyAuthenticationError, OxyAuthenticationTimeoutError };
+export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError };
 
 /**
  * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.