@oxyhq/core 12.9.0 → 12.10.0

package/dist/cjs/crypto/keyManager.js

@@ -122,6 +122,24 @@ const V2_STORAGE_KEYS = {
     BACKUP_PUBLIC_KEY: 'oxy_identity_backup_public_key_v2',
     BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp_v2',
 };
+/**
+ * Dedicated keychain slot for the recovery mnemonic (the 12-word phrase).
+ *
+ * Stored under its OWN keychain service — distinct from the v2 primary, backup,
+ * and shared slots — so it shares an AndroidKeyStore key with none of them
+ * (blast-radius isolation, same rationale as the v2 primary/backup split).
+ * Written `WHEN_UNLOCKED_THIS_DEVICE_ONLY` and NEVER exported off-device: it
+ * exists solely so the user can RE-READ their phrase from Settings on the SAME
+ * device that generated/imported it.
+ *
+ * This is convenience persistence, NOT a recovery mechanism — a keystore death
+ * wipes it alongside the keys, exactly like the private key itself. The user's
+ * written-down phrase remains the sole out-of-band recovery path. The mnemonic
+ * lives ONLY in this slot: it is never mirrored into the identity marker,
+ * {@link KeyManager.getIdentityStatus}, logs, or any exported bundle.
+ */
+const RECOVERY_MNEMONIC_KEYCHAIN_SERVICE = 'oxy_identity_mnemonic';
+const RECOVERY_MNEMONIC_STORAGE_KEY = 'oxy_identity_mnemonic_v1';
 /**
  * Advisory AsyncStorage fast-path flag: set once the v2 slots own the identity.
  * Re-derivable (its loss just re-runs the cheap slot check), so it lives in
@@ -1476,6 +1494,73 @@ class KeyManager {
             throw new IdentityUnavailableError('Failed to read identity from secure storage.', error);
         }
     }
+    /**
+     * Persist the recovery mnemonic (the 12-word phrase) into its dedicated,
+     * device-only keychain slot so the user can re-reveal it from Settings after
+     * onboarding.
+     *
+     * Called best-effort at identity creation/import, where the phrase is already
+     * in memory: a failure to persist it must NEVER fail the identity itself, so
+     * callers deliberately swallow the thrown error (logging it). Storage errors
+     * throw {@link IdentityUnavailableError} — same "cannot determine" semantics as
+     * the other getters — so a caller MAY observe/log the failure.
+     *
+     * The mnemonic is stored ONLY here — never in the marker, `getIdentityStatus`,
+     * logs, or any exported bundle.
+     */
+    static async storeRecoveryMnemonic(mnemonic) {
+        if (isWebPlatform()) {
+            return; // Identity storage is only available on native platforms
+        }
+        try {
+            const store = await initSecureStore();
+            await store.setItemAsync(RECOVERY_MNEMONIC_STORAGE_KEY, mnemonic, KeyManager._privateWriteOpts(store, RECOVERY_MNEMONIC_KEYCHAIN_SERVICE));
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.warn('Failed to persist recovery mnemonic', { component: 'KeyManager' }, error);
+            }
+            throw new IdentityUnavailableError('Failed to persist recovery mnemonic.', error);
+        }
+    }
+    /**
+     * Read the stored recovery mnemonic for re-reveal in Settings.
+     *
+     * Returns the phrase, or `null` when a read SUCCEEDS and finds none — the
+     * expected result for any identity created/imported before this feature
+     * existed, since the phrase was never captured for those. THROWS
+     * {@link IdentityUnavailableError} when storage is unreadable (keychain locked
+     * / module load failure), matching {@link getPublicKey}'s contract — a thrown
+     * read is never flattened to `null`, so a caller distinguishes "phrase was
+     * never stored" from "keychain temporarily locked, retry".
+     */
+    static async getRecoveryMnemonic() {
+        if (isWebPlatform()) {
+            return null; // Identity storage is only available on native platforms
+        }
+        try {
+            const store = await initSecureStore();
+            return await store.getItemAsync(RECOVERY_MNEMONIC_STORAGE_KEY, KeyManager._slotOpts(RECOVERY_MNEMONIC_KEYCHAIN_SERVICE));
+        }
+        catch (error) {
+            if ((0, logger_1.isDev)()) {
+                logger_1.logger.warn('Failed to read recovery mnemonic', { component: 'KeyManager' }, error);
+            }
+            throw new IdentityUnavailableError('Failed to read recovery mnemonic from secure storage.', error);
+        }
+    }
+    /**
+     * Delete the stored recovery mnemonic. Best-effort: a delete failure is logged
+     * and swallowed, never thrown — it runs inside the identity-deletion path where
+     * an unreadable keychain must not abort the wider teardown.
+     */
+    static async deleteRecoveryMnemonic() {
+        if (isWebPlatform()) {
+            return; // Identity storage is only available on native platforms
+        }
+        const store = await initSecureStore();
+        await KeyManager._bestEffortDelete(store, RECOVERY_MNEMONIC_STORAGE_KEY, RECOVERY_MNEMONIC_KEYCHAIN_SERVICE);
+    }
     /**
      * Check if a complete, parseable identity exists on this device.
      *
@@ -1691,6 +1776,10 @@ class KeyManager {
         await KeyManager._bestEffortDeleteV2Primary(store);
         await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PRIVATE_KEY);
         await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PUBLIC_KEY);
+        // Always drop the stored recovery mnemonic — it is scoped to the identity
+        // being deleted, so a leftover would let Settings reveal a stale phrase for
+        // an identity that no longer exists (or a DIFFERENT one after re-onboarding).
+        await KeyManager.deleteRecoveryMnemonic();
         // Also clear backups + the shared slot on force deletion, so a deleted
         // identity cannot be resurrected from any recovery source.
         if (force) {

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.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.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.ServiceCredentialMismatchError = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.AssetUrlResolutionError = exports.OxyServices = void 0;
-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 = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = void 0;
-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 = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = 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 = 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; } });
 // ---------------------------------------------------------------------------

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");

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;
+}