@oxyhq/core 12.5.2 → 12.6.0

package/dist/cjs/HttpService.js

@@ -23,6 +23,7 @@ const jwt_decode_1 = require("jwt-decode");
 const platform_1 = require("./utils/platform");
 const protocol_1 = require("@oxyhq/protocol");
 const cacheKey_1 = require("./utils/cacheKey");
+const redactUrl_1 = require("./utils/redactUrl");
 /**
  * Check if we're running in a native app environment (React Native, not web)
  * This is used to determine CSRF handling mode
@@ -263,7 +264,9 @@ class HttpService {
             const cached = this.cache.get(cacheKey);
             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:', (0, redactUrl_1.redactUrlQuery)(url));
                 return cached;
             }
             this.requestMetrics.cacheMisses++;

package/dist/cjs/OxyServices.errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = void 0;
+exports.OxyAuthenticationTimeoutError = exports.AssetUrlResolutionError = exports.OxyAuthenticationError = void 0;
 /**
  * Custom error types for better error handling
  */
@@ -13,6 +13,47 @@ class OxyAuthenticationError extends Error {
     }
 }
 exports.OxyAuthenticationError = OxyAuthenticationError;
+/**
+ * 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.
+ */
+class AssetUrlResolutionError extends Error {
+    constructor(fileId, variant, status, cause) {
+        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.code = 'ASSET_URL_UNRESOLVED';
+        this.name = 'AssetUrlResolutionError';
+        this.fileId = fileId;
+        this.variant = variant;
+        this.status = status;
+        this.cause = cause;
+    }
+}
+exports.AssetUrlResolutionError = AssetUrlResolutionError;
 class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
     constructor(operationName, timeoutMs) {
         super(`Authentication timeout (${timeoutMs}ms): ${operationName} requires user authentication. Please ensure the user is logged in before calling this method.`, 'AUTH_TIMEOUT', 408);

package/dist/cjs/OxyServices.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.oxyClient = exports.OXY_API_URL = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyServices = void 0;
+exports.oxyClient = exports.OXY_API_URL = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.AssetUrlResolutionError = exports.OxyServices = void 0;
 const OxyServices_errors_1 = require("./OxyServices.errors");
+Object.defineProperty(exports, "AssetUrlResolutionError", { enumerable: true, get: function () { return OxyServices_errors_1.AssetUrlResolutionError; } });
 Object.defineProperty(exports, "OxyAuthenticationError", { enumerable: true, get: function () { return OxyServices_errors_1.OxyAuthenticationError; } });
 Object.defineProperty(exports, "OxyAuthenticationTimeoutError", { enumerable: true, get: function () { return OxyServices_errors_1.OxyAuthenticationTimeoutError; } });
 // Import mixin composition helper

package/dist/cjs/index.js

@@ -18,10 +18,10 @@
  * If a symbol does not appear here, it is NOT part of the public API.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.RecoveryPhraseService = exports.SignatureService = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.verifyPublicCardAttestation = exports.parseAttestPayload = exports.parseIdPayload = exports.buildUserDid = exports.ORGANIZATION_CATEGORIES = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.OxyAppDataIdentifierError = exports.ServiceCredentialMismatchError = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyServices = void 0;
-exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = void 0;
-exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.runColdBoot = exports.isOxyRpOrigin = exports.CENTRAL_IDP_APEX = exports.registrableApex = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.isValidDisplayName = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = void 0;
-exports.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.switchableAccountIds = exports.projectSwitchableAccounts = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.redeemHubTicketOnHub = exports.syncHubAfterSignIn = exports.parseHubSyncReturnUrl = exports.normalizeOfficialReturnOrigin = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.isIdpHubOrigin = exports.buildHubSyncUrl = exports.buildIdpHubOrigin = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.normalizeOAuthRedirectUri = exports.OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = exports.OXY_SILENT_OAUTH_ATTEMPTED_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = void 0;
+exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.RecoveryPhraseService = exports.SignatureService = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.verifyPublicCardAttestation = exports.parseAttestPayload = exports.parseIdPayload = exports.buildUserDid = exports.ORGANIZATION_CATEGORIES = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.OxyAppDataIdentifierError = exports.ServiceCredentialMismatchError = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.AssetUrlResolutionError = exports.OxyServices = void 0;
+exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = void 0;
+exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.runColdBoot = exports.isOxyRpOrigin = exports.CENTRAL_IDP_APEX = exports.registrableApex = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.isValidDisplayName = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = void 0;
+exports.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.switchableAccountIds = exports.projectSwitchableAccounts = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.redeemHubTicketOnHub = exports.syncHubAfterSignIn = exports.parseHubSyncReturnUrl = exports.normalizeOfficialReturnOrigin = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.isIdpHubOrigin = exports.buildHubSyncUrl = exports.buildIdpHubOrigin = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.normalizeOAuthRedirectUri = exports.OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = exports.OXY_SILENT_OAUTH_ATTEMPTED_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -29,6 +29,7 @@ require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
 var OxyServices_1 = require("./OxyServices");
 Object.defineProperty(exports, "OxyServices", { enumerable: true, get: function () { return OxyServices_1.OxyServices; } });
+Object.defineProperty(exports, "AssetUrlResolutionError", { enumerable: true, get: function () { return OxyServices_1.AssetUrlResolutionError; } });
 Object.defineProperty(exports, "OxyAuthenticationError", { enumerable: true, get: function () { return OxyServices_1.OxyAuthenticationError; } });
 Object.defineProperty(exports, "OxyAuthenticationTimeoutError", { enumerable: true, get: function () { return OxyServices_1.OxyAuthenticationTimeoutError; } });
 var OxyServices_2 = require("./OxyServices");

package/dist/cjs/mixins/OxyServices.assets.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OxyServicesAssetsMixin = OxyServicesAssetsMixin;
 const protocol_1 = require("@oxyhq/protocol");
 const logger_1 = require("../logger");
+const OxyServices_errors_1 = require("../OxyServices.errors");
 const errorUtils_1 = require("../utils/errorUtils");
 /**
  * Maximum number of ids sent per `POST /assets/service/by-ids` request. Matches
@@ -24,6 +25,37 @@ const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
  * never 400s an otherwise-valid chunk on the server.
  */
 const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+/**
+ * Conservative lower bound (10 min) the SDK assumes for the lifetime of the
+ * scoped media token (`mt`) the API embeds in the stream URL it returns for a
+ * private asset. The SDK never mints or inspects that token; this constant
+ * exists only so the SDK's own URL cache can be sized safely BELOW the token's
+ * real lifetime.
+ *
+ * The API currently mints tokens for 900s (`MEDIA_TOKEN_TTL_SECONDS` in
+ * `packages/api/src/utils/mediaToken.ts`). Core deliberately assumes a shorter
+ * 10-min floor rather than copying 15: core and the API are separate packages,
+ * so core cannot observe a server-side TTL change at runtime. Under-assuming the
+ * lifetime only ever shortens the cache (more refetches, never a dead URL), so
+ * it stays correct even if the server lowers its TTL toward this floor. The
+ * {@link ASSET_URL_CACHE_LIFETIME_FRACTION} discount is applied on top.
+ */
+const ASSET_MEDIA_TOKEN_TTL_MS = 10 * 60 * 1000;
+/**
+ * Fraction of a resolved URL's remaining lifetime the SDK is willing to keep it
+ * cached for. A resolved URL stops working the moment its media token expires,
+ * so caching it for its full nominal lifetime guarantees a window in which the
+ * cache hands out an already-dead URL (clock skew, time spent in the render
+ * pipeline, an image request queued behind others). Half the lifetime leaves a
+ * margin at least as large as the entry's own age.
+ */
+const ASSET_URL_CACHE_LIFETIME_FRACTION = 0.5;
+/**
+ * Fallback URL lifetime, in seconds, assumed when the caller does not request
+ * an explicit `expiresIn`. Mirrors the API's default signed-URL expiry; the
+ * effective value is still clamped by {@link ASSET_MEDIA_TOKEN_TTL_MS}.
+ */
+const DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS = 3600;
 function OxyServicesAssetsMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -41,14 +73,33 @@ function OxyServicesAssetsMixin(Base) {
             }
         }
         /**
-         * 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.
+         *
+         * ## Contract — read before calling
          *
-         * 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.
+         * 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, variant, expiresIn) {
             // Never embed the in-memory bearer token: this URL is rendered into DOM
@@ -69,16 +120,40 @@ function OxyServicesAssetsMixin(Base) {
             return `${base}/assets/${encodeURIComponent(fileId)}/stream${qs ? `?${qs}` : ''}`;
         }
         /**
-         * 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}.
          */
         async getFileDownloadUrlAsync(fileId, variant, expiresIn) {
+            let url;
             try {
-                const url = await this.fetchAssetDownloadUrl(fileId, variant, this.getAssetUrlCacheTTL(expiresIn), expiresIn);
-                return url || this.getFileDownloadUrl(fileId, variant, expiresIn);
+                url = await this.fetchAssetDownloadUrl(fileId, variant, this.getAssetUrlCacheTTL(expiresIn), expiresIn);
             }
             catch (error) {
-                return this.getFileDownloadUrl(fileId, variant, expiresIn);
+                throw new OxyServices_errors_1.AssetUrlResolutionError(fileId, variant, (0, errorUtils_1.extractErrorStatus)(error), error);
+            }
+            if (!url) {
+                throw new OxyServices_errors_1.AssetUrlResolutionError(fileId, variant, undefined);
             }
+            return url;
         }
         /**
          * List user files
@@ -142,13 +217,36 @@ function OxyServicesAssetsMixin(Base) {
             }
         }
         /**
-         * 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.
          */
-        async getBatchFileAccess(fileIds, context) {
+        async getBatchFileAccess(requests, options) {
+            const files = dedupeFileAccessRequests(requests);
+            if (files.length === 0) {
+                return { results: {} };
+            }
+            const body = {
+                files,
+            };
+            if (typeof options?.expiresIn === 'number')
+                body.expiresIn = options.expiresIn;
+            if (typeof options?.context === 'string')
+                body.context = options.context;
             try {
-                return await this.makeRequest('POST', '/assets/batch-access', {
-                    fileIds,
-                    context
+                return await this.makeRequest('POST', '/assets/batch-access', body, {
+                    cache: false,
                 });
             }
             catch (error) {
@@ -156,13 +254,27 @@ function OxyServicesAssetsMixin(Base) {
             }
         }
         /**
-         * 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`.
          */
-        async getFileDownloadUrls(fileIds, context) {
-            const response = await this.getBatchFileAccess(fileIds, context);
+        async getFileDownloadUrls(requests, options) {
+            const response = await this.getBatchFileAccess(requests, options);
             const urls = {};
-            const results = response.results || {};
-            for (const [id, result] of Object.entries(results)) {
+            for (const [id, result] of Object.entries(response.results ?? {})) {
                 if (result.allowed && result.url) {
                     urls[id] = result.url;
                 }
@@ -461,7 +573,7 @@ function OxyServicesAssetsMixin(Base) {
                     params.expiresIn = expiresIn;
                 return await this.makeRequest('GET', `/assets/${fileId}/url`, params, {
                     cache: true,
-                    cacheTTL: 10 * 60 * 1000,
+                    cacheTTL: this.getAssetUrlCacheTTL(expiresIn),
                 });
             }
             catch (error) {
@@ -549,9 +661,21 @@ function OxyServicesAssetsMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * 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) {
-            const desiredTtlMs = (expiresIn ?? 3600) * 1000;
-            return Math.min(desiredTtlMs, 10 * 60 * 1000);
+            const requestedLifetimeMs = (expiresIn ?? DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS) * 1000;
+            const boundedLifetimeMs = Math.min(requestedLifetimeMs, ASSET_MEDIA_TOKEN_TTL_MS);
+            return Math.floor(boundedLifetimeMs * ASSET_URL_CACHE_LIFETIME_FRACTION);
         }
         async fetchAssetDownloadUrl(fileId, variant, cacheTTL, expiresIn) {
             const params = {};
@@ -561,7 +685,10 @@ function OxyServicesAssetsMixin(Base) {
                 params.expiresIn = expiresIn;
             const urlRes = await this.makeRequest('GET', `/assets/${encodeURIComponent(fileId)}/url`, Object.keys(params).length ? params : undefined, {
                 cache: true,
-                cacheTTL: cacheTTL ?? 10 * 60 * 1000,
+                // Cap the cached URL well below the media token's lifetime. The
+                // response body is a scoped, expiring URL; over-caching it serves a
+                // dead URL after the token expires (see getAssetUrlCacheTTL).
+                cacheTTL: cacheTTL ?? this.getAssetUrlCacheTTL(expiresIn),
             });
             return urlRes?.url || null;
         }
@@ -576,6 +703,29 @@ function OxyServicesAssetsMixin(Base) {
         }
     };
 }
+/**
+ * Normalize the per-file batch-access request list: drop entries with a blank
+ * `fileId` and collapse exact `(fileId, variant)` duplicates (first occurrence
+ * wins, preserving order). Two entries for the SAME `fileId` with DIFFERENT
+ * variants are intentionally kept — but note the response is keyed by `fileId`,
+ * so a caller that needs two variants of one file must issue separate calls.
+ */
+function dedupeFileAccessRequests(requests) {
+    const seen = new Set();
+    const out = [];
+    for (const req of requests) {
+        if (typeof req?.fileId !== 'string' || req.fileId.trim().length === 0) {
+            continue;
+        }
+        const key = `${req.fileId}\u0000${req.variant ?? ''}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(req.variant === undefined ? { fileId: req.fileId } : { fileId: req.fileId, variant: req.variant });
+    }
+    return out;
+}
 /**
  * Only send ambient credentials (cookies) when the asset URL is same-origin with
  * the configured API base. Caller-supplied cross-origin asset URLs must not leak

package/dist/cjs/mixins/OxyServices.user.js

@@ -40,7 +40,7 @@ function OxyServicesUserMixin(Base) {
          */
         async getProfileByUsername(username, options) {
             try {
-                const user = await this.makeRequest('GET', `/profiles/username/${username}`, undefined, {
+                const user = await this.makeRequest('GET', `/profiles/username/${encodeURIComponent(username)}`, undefined, {
                     cache: options?.cache ?? true,
                     cacheTTL: 5 * 60 * 1000, // 5 minutes cache for profiles
                 });
@@ -537,6 +537,11 @@ function OxyServicesUserMixin(Base) {
             try {
                 const result = await this.makeRequest('POST', `/users/${userId}/follow`, undefined, { cache: false });
                 this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
+                // Profile fetches embed viewer-relative `relationship` — bust so a
+                // remount doesn't serve a stale isFollowing for up to 5 minutes.
+                this.clearCacheEntry(`GET:/users/${userId}`);
+                this.clearCacheByPrefix('GET:/profiles/username/');
+                this.clearCacheByPrefix('GET:/profiles/resolve');
                 // The follow changed the viewer's graph — bust the cached consolidated
                 // `GET /users/me/graph` so the next read reflects the new following/
                 // mutual set instead of the stale pre-write snapshot.
@@ -564,7 +569,10 @@ function OxyServicesUserMixin(Base) {
                 // Bust each affected user's cached follow-status (see `followUser`).
                 for (const id of userIds) {
                     this.clearCacheEntry(`GET:/users/${id}/follow-status`);
+                    this.clearCacheEntry(`GET:/users/${id}`);
                 }
+                this.clearCacheByPrefix('GET:/profiles/username/');
+                this.clearCacheByPrefix('GET:/profiles/resolve');
                 // The batch changed the viewer's graph — bust the consolidated cache.
                 this.clearCacheEntry('GET:/users/me/graph');
                 return result;
@@ -590,7 +598,10 @@ function OxyServicesUserMixin(Base) {
                 // Bust each affected user's cached follow-status (see `followUser`).
                 for (const id of userIds) {
                     this.clearCacheEntry(`GET:/users/${id}/follow-status`);
+                    this.clearCacheEntry(`GET:/users/${id}`);
                 }
+                this.clearCacheByPrefix('GET:/profiles/username/');
+                this.clearCacheByPrefix('GET:/profiles/resolve');
                 // The batch changed the viewer's graph — bust the consolidated cache.
                 this.clearCacheEntry('GET:/users/me/graph');
                 return result;
@@ -607,6 +618,9 @@ function OxyServicesUserMixin(Base) {
                 const result = await this.makeRequest('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
                 // Bust the cached follow-status so a remount reads fresh truth (see `followUser`).
                 this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
+                this.clearCacheEntry(`GET:/users/${userId}`);
+                this.clearCacheByPrefix('GET:/profiles/username/');
+                this.clearCacheByPrefix('GET:/profiles/resolve');
                 // The unfollow changed the viewer's graph — bust the consolidated cache.
                 this.clearCacheEntry('GET:/users/me/graph');
                 return result;

package/dist/cjs/session/SessionClient.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionClient = void 0;
 const contracts_1 = require("@oxyhq/contracts");
 const logger_1 = require("../logger");
+const cacheKey_1 = require("../utils/cacheKey");
 const socketLoader_1 = require("./socketLoader");
 /**
  * Same-origin `BroadcastChannel` name for instant, network-free session-state
@@ -83,8 +84,25 @@ class SessionClient {
             }
         }
     }
-    /** Validate + last-writer-wins by revision. Returns true if applied. */
-    applyState(raw, origin = 'push') {
+    /**
+     * 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.
+     */
+    applyState(raw, origin = 'push', activeToken) {
         const next = (0, contracts_1.safeParseContract)(contracts_1.deviceSessionStateSchema, raw);
         if (!next) {
             logger_1.logger.warn('[SessionClient] discarded invalid session state');
@@ -101,9 +119,26 @@ class SessionClient {
             next.revision <= this.state.revision) {
             return false;
         }
+        const previousState = this.state;
         this.state = next;
+        // Plant the sync-supplied active token (it is for `next.activeAccountId`)
+        // now — before the notify below — so the bearer matches the new active
+        // account when subscribers observe it. Guarded on difference to avoid a
+        // redundant token-change notification on an unchanged token (bootstrap
+        // restate).
+        if (activeToken && next.activeAccountId !== null && activeToken !== this.host.getAccessToken()) {
+            this.host.setTokens(activeToken);
+        }
         const transport = this.options.transport;
-        const needsMintBeforeNotify = transport != null && next.accounts.length > 0 && !this.host.getAccessToken();
+        const activeAccountId = next.activeAccountId;
+        // Mint before notifying when the bearer does not already belong to the new
+        // active account: no bearer at all, an opaque bearer, OR a bearer for a
+        // DIFFERENT account. `computeIdentityTag` yields the token's `userId`/`id`
+        // for a real JWT (comparable to the account id) and a non-account sentinel
+        // otherwise, so a mismatch always resolves to "mint".
+        const needsMintBeforeNotify = transport != null &&
+            next.accounts.length > 0 &&
+            (activeAccountId === null || (0, cacheKey_1.computeIdentityTag)(this.host.getAccessToken()) !== activeAccountId);
         const finishApply = () => {
             this.notify();
             if (next.accounts.length === 0 && this.options.onUnauthenticated) {
@@ -117,8 +152,10 @@ class SessionClient {
         };
         if (needsMintBeforeNotify) {
             void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
-                logger_1.logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
-                finishApply();
+                logger_1.logger.warn('[SessionClient] ensureActiveToken failed — reverting session state', { component: 'SessionClient' }, error);
+                // Do NOT notify under a mismatched bearer. Revert to the last applied
+                // state so subscribers keep observing the account whose token is planted.
+                this.state = previousState ?? null;
             });
         }
         else {
@@ -156,9 +193,21 @@ class SessionClient {
         }
         // A `sync` is always the response to a direct REST call this client made
         // (bootstrap / switch / signOut / add) → a `request`-origin, authoritative
-        // verdict.
-        this.applyState(sync.state, 'request');
-        if (sync.activeToken && this.state && sync.state.activeAccountId === this.state.activeAccountId) {
+        // verdict. Hand the active token to `applyState`: in the applied path it is
+        // planted BEFORE notify (bearer matches the new active account when
+        // subscribers observe it, and no redundant device-secret mint is triggered).
+        const applied = this.applyState(sync.state, 'request', sync.activeToken?.accessToken);
+        // Equal-revision restate (this revision was already applied by a preceding
+        // socket push): `applyState` no-ops without planting, but the token still
+        // needs planting. Guard on the sync's active account STILL being the current
+        // active account so a stale response cannot adopt a token for an account a
+        // newer state already switched away from.
+        if (!applied &&
+            sync.activeToken &&
+            this.state &&
+            sync.state.activeAccountId !== null &&
+            sync.state.activeAccountId === this.state.activeAccountId &&
+            sync.activeToken.accessToken !== this.host.getAccessToken()) {
             this.host.setTokens(sync.activeToken.accessToken);
         }
     }