@oxyhq/core 12.8.0 → 12.10.0

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.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;
+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.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = 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.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.ServiceCredentialMismatchError = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.AssetUrlResolutionError = exports.OxyServices = void 0;
+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 = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = void 0;
+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 = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = 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 = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.runColdBoot = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -40,6 +40,9 @@ Object.defineProperty(exports, "oxyClient", { enumerable: true, get: function ()
 // ---------------------------------------------------------------------------
 var OxyServices_auth_1 = require("./mixins/OxyServices.auth");
 Object.defineProperty(exports, "ServiceCredentialMismatchError", { enumerable: true, get: function () { return OxyServices_auth_1.ServiceCredentialMismatchError; } });
+var commonsApproval_1 = require("./utils/commonsApproval");
+Object.defineProperty(exports, "getCommonsApprovalBlockingReason", { enumerable: true, get: function () { return commonsApproval_1.getCommonsApprovalBlockingReason; } });
+Object.defineProperty(exports, "parseCommonsApprovalExpiresAt", { enumerable: true, get: function () { return commonsApproval_1.parseCommonsApprovalExpiresAt; } });
 var OxyServices_appData_1 = require("./mixins/OxyServices.appData");
 Object.defineProperty(exports, "OxyAppDataIdentifierError", { enumerable: true, get: function () { return OxyServices_appData_1.OxyAppDataIdentifierError; } });
 // ---------------------------------------------------------------------------
@@ -100,6 +103,10 @@ var keyManager_1 = require("./crypto/keyManager");
 Object.defineProperty(exports, "KeyManager", { enumerable: true, get: function () { return keyManager_1.KeyManager; } });
 Object.defineProperty(exports, "IdentityAlreadyExistsError", { enumerable: true, get: function () { return keyManager_1.IdentityAlreadyExistsError; } });
 Object.defineProperty(exports, "IdentityPersistError", { enumerable: true, get: function () { return keyManager_1.IdentityPersistError; } });
+Object.defineProperty(exports, "IdentityUnavailableError", { enumerable: true, get: function () { return keyManager_1.IdentityUnavailableError; } });
+var identityMarker_1 = require("./crypto/identityMarker");
+Object.defineProperty(exports, "readIdentityMarker", { enumerable: true, get: function () { return identityMarker_1.readIdentityMarker; } });
+Object.defineProperty(exports, "updateIdentityMarker", { enumerable: true, get: function () { return identityMarker_1.updateIdentityMarker; } });
 var signatureService_1 = require("./crypto/signatureService");
 Object.defineProperty(exports, "SignatureService", { enumerable: true, get: function () { return signatureService_1.SignatureService; } });
 var recoveryPhrase_1 = require("./crypto/recoveryPhrase");

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

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServiceCredentialMismatchError = void 0;
+exports.ServiceCredentialMismatchError = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = void 0;
 exports.OxyServicesAuthMixin = OxyServicesAuthMixin;
 const contracts_1 = require("@oxyhq/contracts");
+var commonsApproval_1 = require("../utils/commonsApproval");
+Object.defineProperty(exports, "getCommonsApprovalBlockingReason", { enumerable: true, get: function () { return commonsApproval_1.getCommonsApprovalBlockingReason; } });
+Object.defineProperty(exports, "parseCommonsApprovalExpiresAt", { enumerable: true, get: function () { return commonsApproval_1.parseCommonsApprovalExpiresAt; } });
 const OxyServices_errors_1 = require("../OxyServices.errors");
 const keyManager_1 = require("../crypto/keyManager");
 const signatureService_1 = require("../crypto/signatureService");
@@ -298,12 +301,16 @@ function OxyServicesAuthMixin(Base) {
          * The client must sign this challenge with their private key
          *
          * @param publicKey - The user's public key
+         * @param requestOptions - Optional per-call transport overrides (`retry`,
+         *   `timeout`). Interactive callers omit it (defaults keep retries); the
+         *   cold-boot `shared-key-signin` step passes `{ retry: false }` so a slow
+         *   network cannot multiply boot latency via the inner retry loop.
          */
-        async requestChallenge(publicKey) {
+        async requestChallenge(publicKey, requestOptions) {
             try {
                 return await this.makeRequest('POST', '/auth/challenge', {
                     publicKey,
-                }, { cache: false });
+                }, { cache: false, ...requestOptions });
             }
             catch (error) {
                 throw this.handleError(error);
@@ -318,8 +325,12 @@ function OxyServicesAuthMixin(Base) {
          * @param timestamp - Timestamp when the signature was created
          * @param deviceName - Optional device name
          * @param deviceFingerprint - Optional device fingerprint
+         * @param requestOptions - Optional per-call transport overrides (`retry`,
+         *   `timeout`). Interactive callers omit it (defaults keep retries); the
+         *   cold-boot `shared-key-signin` step passes `{ retry: false }` so a slow
+         *   network cannot multiply boot latency via the inner retry loop.
          */
-        async verifyChallenge(publicKey, challenge, signature, timestamp, deviceName, deviceFingerprint) {
+        async verifyChallenge(publicKey, challenge, signature, timestamp, deviceName, deviceFingerprint, requestOptions) {
             try {
                 const res = await this.makeRequest('POST', '/auth/verify', {
                     publicKey,
@@ -328,7 +339,7 @@ function OxyServicesAuthMixin(Base) {
                     timestamp,
                     deviceName,
                     deviceFingerprint,
-                }, { cache: false });
+                }, { cache: false, ...requestOptions });
                 // Plant the freshly-minted tokens, mirroring `claimSessionByToken`.
                 // `/auth/verify` returns the first access token (and refresh token) in
                 // its body, so installing it here means callers get an authenticated
@@ -466,6 +477,13 @@ function OxyServicesAuthMixin(Base) {
          *
          * The cold-boot wiring that CALLS this lives in `OxyContext`
          * (`@oxyhq/services`); this method just performs the exchange.
+         *
+         * @param opts.requestOptions - Optional per-call transport overrides
+         *   (`retry`, `timeout`) forwarded to BOTH the `requestChallenge` and
+         *   `verifyChallenge` round-trips. Interactive flows omit it (defaults keep
+         *   retries); the cold-boot `shared-key-signin` step passes `{ retry: false }`
+         *   so this network step cannot multiply boot latency via the inner retry
+         *   loop. The token-refresh scheduler / 401 lane still retry later.
          */
         async signInWithSharedIdentity(opts = {}) {
             try {
@@ -479,10 +497,10 @@ function OxyServicesAuthMixin(Base) {
                 if (!sharedPublicKey) {
                     return null;
                 }
-                const { challenge } = await this.requestChallenge(sharedPublicKey);
+                const { challenge } = await this.requestChallenge(sharedPublicKey, opts.requestOptions);
                 const signed = await signatureService_1.SignatureService.signChallengeWithSharedKey(challenge);
                 // `signed.challenge` carries the SIGNATURE (mirrors `signChallenge`).
-                return await this.verifyChallenge(signed.publicKey, challenge, signed.challenge, signed.timestamp, opts.deviceName, opts.deviceFingerprint);
+                return await this.verifyChallenge(signed.publicKey, challenge, signed.challenge, signed.timestamp, opts.deviceName, opts.deviceFingerprint, opts.requestOptions);
             }
             catch (error) {
                 throw this.handleError(error);

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

@@ -32,11 +32,19 @@ function OxyServicesDeviceBootMixin(Base) {
          * `no_active_session`) to decide whether to drop the secret and fall back or
          * resolve signed-out.
          *
+         * `retry: false`: the mint is a single logical attempt. The proactive
+         * token-refresh scheduler and the reactive 401 lane already own backoff and
+         * re-arm, so `HttpService`'s inner retry loop here would only multiply the
+         * mint's latency on a slow/black-hole network (3 retries × 5s timeout ≈ 20s
+         * per lane) with no correctness benefit — it is the dominant term in the cold
+         * boot's worst-case time-to-route. A transient failure surfaces once and the
+         * scheduler/401 path retries it later.
+         *
          * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
          */
         async mintFromDeviceSecret(deviceId, deviceSecret) {
             try {
-                const res = await this.makeRequest('POST', '/session/device/token', { deviceId, deviceSecret }, { cache: false, skipAuth: true });
+                const res = await this.makeRequest('POST', '/session/device/token', { deviceId, deviceSecret }, { cache: false, skipAuth: true, retry: false });
                 const parsed = (0, contracts_1.safeParseContract)(contracts_1.deviceTokenMintResponseSchema, res);
                 if (!parsed) {
                     throw new Error('session/device/token returned an unexpected response shape');

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

@@ -141,6 +141,17 @@ function OxyServicesIdentityBackupMixin(Base) {
                 const aad = buildBackupAad(envelope.version, envelope.publicKeyHint);
                 const plaintext = (0, aead_1.decryptAead)(backupKey, fromHex(envelope.nonce), fromHex(envelope.ciphertext), aad);
                 const payload = JSON.parse(new TextDecoder().decode(plaintext));
+                if (!payload.privateKey || !payload.publicKey) {
+                    throw new Error('Backup payload is missing key material');
+                }
+                const derivedFromPhrase = await recoveryPhrase_1.RecoveryPhraseService.derivePublicKeyFromPhrase(phrase);
+                const derivedFromPrivate = keyManager_1.KeyManager.derivePublicKey(payload.privateKey);
+                const phrasePk = derivedFromPhrase.toLowerCase();
+                const payloadPk = payload.publicKey.toLowerCase();
+                const privatePk = derivedFromPrivate.toLowerCase();
+                if (phrasePk !== payloadPk || privatePk !== payloadPk) {
+                    throw new Error('Backup payload does not match the recovery phrase');
+                }
                 // Persist the recovered key. Native-only; refuses to clobber a different
                 // identity unless overwrite — the IdentityAlreadyExistsError propagates.
                 return await keyManager_1.KeyManager.importKeyPair(payload.privateKey, {

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

@@ -423,6 +423,10 @@ function OxyServicesUserMixin(Base) {
                 const result = await this.makeRequest('PATCH', `/privacy/${id}/privacy`, settings, {
                     cache: false,
                 });
+                this.clearCacheByPrefix('GET:/session/user/');
+                this.clearCacheByPrefix('GET:/users/me');
+                this.clearCacheByPrefix('GET:/profiles/username/');
+                this.clearCacheEntry(`GET:/users/${id}`);
                 this.clearCacheEntry(`GET:/privacy/${id}/privacy`);
                 return result;
             }

package/dist/cjs/utils/commonsApproval.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommonsApprovalBlockingReason = getCommonsApprovalBlockingReason;
+exports.parseCommonsApprovalExpiresAt = parseCommonsApprovalExpiresAt;
+/**
+ * Returns a user-facing blocking reason when an approval payload must not be
+ * shown as actionable, or `null` when the request is still pending and valid.
+ */
+function getCommonsApprovalBlockingReason(info) {
+    if (!info.application?.id) {
+        return 'The requesting application could not be resolved.';
+    }
+    if (info.status !== 'pending') {
+        return 'This sign-in request is invalid, already used, or expired.';
+    }
+    const expiresAtMs = parseCommonsApprovalExpiresAt(info.expiresAt);
+    if (expiresAtMs !== null && expiresAtMs < Date.now()) {
+        return 'This sign-in request has expired. Ask for a new QR code.';
+    }
+    return null;
+}
+/** Normalize API `expiresAt` (number or ISO string) to epoch ms. */
+function parseCommonsApprovalExpiresAt(expiresAt) {
+    if (typeof expiresAt === 'number' && Number.isFinite(expiresAt))
+        return expiresAt;
+    if (typeof expiresAt === 'string') {
+        const ms = Date.parse(expiresAt);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    return null;
+}