@oxyhq/core 12.2.0 → 12.3.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.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = 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.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.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 = 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 = void 0;
-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 = 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.isValidDisplayName = exports.isValidPassword = 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 = void 0;
+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.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 = 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.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 = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -103,6 +103,16 @@ var signatureService_1 = require("./crypto/signatureService");
 Object.defineProperty(exports, "SignatureService", { enumerable: true, get: function () { return signatureService_1.SignatureService; } });
 var recoveryPhrase_1 = require("./crypto/recoveryPhrase");
 Object.defineProperty(exports, "RecoveryPhraseService", { enumerable: true, get: function () { return recoveryPhrase_1.RecoveryPhraseService; } });
+// Low-level crypto primitives (b3 Phase 0 — encrypted backup + device transfer)
+var kdf_1 = require("./crypto/kdf");
+Object.defineProperty(exports, "hkdfSha256", { enumerable: true, get: function () { return kdf_1.hkdfSha256; } });
+var aead_1 = require("./crypto/aead");
+Object.defineProperty(exports, "encryptAead", { enumerable: true, get: function () { return aead_1.encryptAead; } });
+Object.defineProperty(exports, "decryptAead", { enumerable: true, get: function () { return aead_1.decryptAead; } });
+Object.defineProperty(exports, "AEAD_KEY_LENGTH", { enumerable: true, get: function () { return aead_1.AEAD_KEY_LENGTH; } });
+Object.defineProperty(exports, "AEAD_NONCE_LENGTH", { enumerable: true, get: function () { return aead_1.AEAD_NONCE_LENGTH; } });
+var ecdh_1 = require("./crypto/ecdh");
+Object.defineProperty(exports, "deriveSharedSecret", { enumerable: true, get: function () { return ecdh_1.deriveSharedSecret; } });
 // ---------------------------------------------------------------------------
 // Devices
 // ---------------------------------------------------------------------------

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

@@ -2,8 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildUserDid = buildUserDid;
 exports.OxyServicesIdentityMixin = OxyServicesIdentityMixin;
+const protocol_1 = require("@oxyhq/protocol");
 const keyManager_1 = require("../crypto/keyManager");
 const signatureService_1 = require("../crypto/signatureService");
+const recoveryPhrase_1 = require("../crypto/recoveryPhrase");
+const platform_1 = require("../utils/platform");
+const logger_1 = require("../logger");
 const mixinHelpers_1 = require("./mixinHelpers");
 /**
  * Registrable apex the Oxy DID method is anchored on. A user's DID is
@@ -141,6 +145,168 @@ function OxyServicesIdentityMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Rotate the account's identity key: derive a brand-new keypair, prove
+         * control of the CURRENT key, and have the server ATOMICALLY replace the old
+         * key with the new one.
+         *
+         * The rotation is an atomic REPLACE on the server (never remove-then-add), so
+         * it never passes through a zero-auth-method state and is independent of the
+         * unlink guards. Because control of the current key is PROVEN (from
+         * SecureStore in `'device'` mode, or a recovery-phrase re-derivation in
+         * `'phrase'` mode), even the LAST remaining credential can be replaced.
+         *
+         * Ordering (safety-critical): the new key is persisted on-device ONLY AFTER
+         * the server confirms the swap. Persisting earlier would clobber the local
+         * key while the server still trusts the old one, locking the device out.
+         *
+         * Ambiguous-network-failure guard: if the `complete` response is lost
+         * (request sent, no reply), the swap may already have applied server-side.
+         * Before surfacing the error we reconcile against the derived DID document —
+         * if it already advertises the new key, the rotation is treated as done.
+         *
+         * NOTE: the UI is responsible for showing `newPhrase` to the user. For a
+         * "show-phrase-first" flow, derive the identity up front via
+         * {@link RecoveryPhraseService.derivePendingIdentity}, display it, then pass
+         * it back as `options.pendingIdentity` so the SAME identity is committed.
+         *
+         * @throws when no user is authenticated, when `proof: 'phrase'` is given
+         *   without a `phrase`, when `proof: 'device'` runs with no on-device key,
+         *   or when the rotation does not complete.
+         */
+        async rotateKey(options) {
+            try {
+                const userId = this.getCurrentUserId();
+                if (!userId) {
+                    throw new Error('No authenticated user — sign in before rotating your key.');
+                }
+                // 1. The NEW identity (in memory only). The UI may pre-derive + pre-show
+                //    it and pass it back here so the phrase shown === the phrase committed.
+                const pending = options.pendingIdentity ?? (await recoveryPhrase_1.RecoveryPhraseService.derivePendingIdentity());
+                const newPublicKey = pending.publicKey;
+                // 2. Resolve the OLD signing capability from the chosen proof mode.
+                let oldPublicKey;
+                let signWithOldKey;
+                if (options.proof === 'phrase') {
+                    const phrase = options.phrase?.trim();
+                    if (!phrase) {
+                        throw new Error('A recovery phrase is required for phrase-proof rotation.');
+                    }
+                    const oldPrivateKey = await recoveryPhrase_1.RecoveryPhraseService.derivePrivateKeyFromPhrase(phrase);
+                    oldPublicKey = keyManager_1.KeyManager.derivePublicKey(oldPrivateKey);
+                    signWithOldKey = (message) => (0, protocol_1.signMessage)(message, oldPrivateKey);
+                }
+                else {
+                    const currentPublicKey = await keyManager_1.KeyManager.getPublicKey();
+                    if (!currentPublicKey) {
+                        throw new Error('No on-device identity found. Use the recovery-phrase option to rotate your key.');
+                    }
+                    oldPublicKey = currentPublicKey;
+                    signWithOldKey = (message) => signatureService_1.SignatureService.sign(message);
+                }
+                // 3. Request a single-use rotate_key challenge (bearer).
+                const { challenge } = await this.makeRequest('POST', '/auth/rotate/challenge', undefined, { cache: false });
+                // 4. Sign the rotation proofs. The OLD key proves control of the key being
+                //    replaced; the NEW key proves possession of the key being rotated in
+                //    (so the server never accepts a re-encoding of a key the caller does
+                //    not control). Both signed byte strings MUST match the server's
+                //    reconstruction exactly (this key order). The old key is canonicalized
+                //    so legacy compressed encodings in Mongo still verify.
+                const timestamp = Date.now();
+                const canonicalOldPublicKey = keyManager_1.KeyManager.canonicalPublicKey(oldPublicKey);
+                const message = JSON.stringify({
+                    action: 'rotate_key',
+                    userId,
+                    oldPublicKey: canonicalOldPublicKey,
+                    newPublicKey,
+                    challenge,
+                    timestamp,
+                });
+                const signature = await signWithOldKey(message);
+                const newKeyMessage = JSON.stringify({
+                    action: 'rotate_key_new',
+                    userId,
+                    newPublicKey,
+                    challenge,
+                    timestamp,
+                });
+                const newKeyProof = await (0, protocol_1.signMessage)(newKeyMessage, pending.privateKey);
+                // 5. Complete the rotation. On an AMBIGUOUS failure, reconcile against the
+                //    DID before deciding the rotation failed.
+                let applied = false;
+                try {
+                    const result = await this.makeRequest('POST', '/auth/rotate/complete', {
+                        newPublicKey,
+                        challenge,
+                        signature,
+                        newKeyProof,
+                        timestamp,
+                        ...(options.signOutEverywhere ? { signOutEverywhere: true } : {}),
+                    }, { cache: false });
+                    applied = result.success && result.publicKey.toLowerCase() === newPublicKey.toLowerCase();
+                }
+                catch (error) {
+                    const reconciled = await this._rotationAlreadyApplied(userId, newPublicKey);
+                    if (!reconciled) {
+                        throw error;
+                    }
+                    applied = true;
+                }
+                if (!applied) {
+                    throw new Error('Key rotation did not complete — your previous key is unchanged.');
+                }
+                // 6. ONLY after the server confirms the swap, persist the new key locally,
+                //    overwriting the old one. `importKeyPair({ overwrite: true })` uses the
+                //    atomic persist path (backs the previous key up first). Native-only —
+                //    on web the key never lived in SecureStore, so there is nothing to
+                //    persist locally.
+                //
+                //    If this local write fails the server key is ALREADY the new one, so
+                //    we must NOT throw and swallow the phrase — the caller needs it to
+                //    re-import the now-live key. Surface the result with
+                //    `localPersistFailed: true` (mirrors the pendingIdentity
+                //    show-phrase-first path, where the caller already holds the phrase).
+                let localPersistFailed = false;
+                if (!(0, platform_1.isWeb)()) {
+                    try {
+                        await keyManager_1.KeyManager.importKeyPair(pending.privateKey, { overwrite: true });
+                    }
+                    catch (persistError) {
+                        localPersistFailed = true;
+                        logger_1.logger.warn('Key rotated on the server but persisting the new key on-device failed; returning the new phrase so it can be re-imported.', { component: 'OxyServices.identity', method: 'rotateKey' }, persistError);
+                    }
+                }
+                this._invalidateIdentityCaches(userId);
+                return localPersistFailed
+                    ? { newPublicKey, newPhrase: pending.phrase, words: pending.words, localPersistFailed: true }
+                    : { newPublicKey, newPhrase: pending.phrase, words: pending.words };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Reconciliation probe for the rotation ambiguous-failure guard: fetch the
+         * account's derived DID document (uncached) and report whether it already
+         * advertises `newPublicKey` as a verification method — i.e. whether the swap
+         * already landed server-side. A failed probe returns `false` (unconfirmed),
+         * so the caller surfaces the original network error.
+         *
+         * Uses the DID document rather than `GET /auth/methods` because the latter
+         * intentionally does NOT expose raw public keys, whereas the DID's
+         * `verificationMethod[].publicKeyHex` is derived live from the account's
+         * current key — so it reflects a completed rotation immediately.
+         *
+         * Internal helper (leading underscore); public rather than `private` for the
+         * same TS4094 reason as {@link _invalidateIdentityCaches}.
+         */
+        async _rotationAlreadyApplied(userId, newPublicKey) {
+            return this.makeRequest('GET', `/u/${encodeURIComponent(userId)}/did.json`, undefined, { cache: false })
+                .then((doc) => doc.verificationMethod.some((vm) => 'publicKeyHex' in vm &&
+                typeof vm.publicKeyHex === 'string' &&
+                vm.publicKeyHex.toLowerCase() === newPublicKey.toLowerCase()))
+                .catch(() => false);
+        }
         /**
          * Sign a record with the on-device identity key, WITHOUT publishing it.
          * The subject is the current user's DID. NATIVE-ONLY (requires a stored

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

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesIdentityBackupMixin = OxyServicesIdentityBackupMixin;
+const keyManager_1 = require("../crypto/keyManager");
+const recoveryPhrase_1 = require("../crypto/recoveryPhrase");
+const aead_1 = require("../crypto/aead");
+/** Envelope/KDF version — bump only on a breaking scheme change. */
+const BACKUP_ENVELOPE_VERSION = 1;
+/** The AEAD the backup is sealed with. Pinned so a mismatched decryptor fails loudly. */
+const BACKUP_ALGORITHM = 'xchacha20poly1305';
+/**
+ * Length (hex chars) of the public-key HINT stored/echoed with a backup — enough
+ * to let the owner recognise WHICH identity a backup belongs to, but only a
+ * prefix (the full key is public anyway; a prefix keeps the record minimal).
+ */
+const PUBLIC_KEY_HINT_LENGTH = 16;
+/** Encode bytes as lowercase hex (cross-platform, no Buffer dependency). */
+function toHex(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 1) {
+        out += bytes[i].toString(16).padStart(2, '0');
+    }
+    return out;
+}
+/** Decode a lowercase/uppercase hex string to bytes. Throws on malformed input. */
+function fromHex(hex) {
+    if (hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) {
+        throw new Error('Malformed hex in encrypted backup envelope.');
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i += 1) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/**
+ * The AEAD associated data binds the ciphertext to its `{version, publicKeyHint}`
+ * context: the exact bytes must be reproduced at decrypt time, so a mismatched
+ * version or hint (e.g. an envelope re-stamped by a tamperer) fails the
+ * Poly1305 check. Deterministic: both sides build the SAME object literal, so
+ * `JSON.stringify` yields identical bytes.
+ */
+function buildBackupAad(version, publicKeyHint) {
+    return new TextEncoder().encode(JSON.stringify({ version, publicKeyHint }));
+}
+function OxyServicesIdentityBackupMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Derive the backup key material from the recovery phrase, encrypt the
+         * identity's `{privateKey, publicKey, createdAt}` with it, and upload the
+         * ciphertext + raw `lookupId` (`POST /identity/backup`, bearer). The server
+         * stores only `sha256(lookupId)` + the ciphertext. Idempotent per user: a
+         * re-upload REPLACES the prior backup (upsert by user id).
+         *
+         * The identity is derived from the PHRASE (not read from SecureStore), so
+         * this works cross-platform and does not require an on-device key.
+         *
+         * @param phrase - The identity's BIP-39 recovery phrase.
+         * @returns The post-write backup status (`{ exists: true, publicKeyHint, createdAt }`).
+         */
+        async createEncryptedBackup(phrase) {
+            try {
+                const { backupKey, lookupId } = await recoveryPhrase_1.RecoveryPhraseService.deriveBackupMaterial(phrase);
+                const privateKey = await recoveryPhrase_1.RecoveryPhraseService.derivePrivateKeyFromPhrase(phrase);
+                const publicKey = keyManager_1.KeyManager.derivePublicKey(privateKey);
+                const createdAt = new Date().toISOString();
+                const publicKeyHint = publicKey.slice(0, PUBLIC_KEY_HINT_LENGTH);
+                const payload = { privateKey, publicKey, createdAt };
+                const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+                const aad = buildBackupAad(BACKUP_ENVELOPE_VERSION, publicKeyHint);
+                const { nonce, ciphertext } = (0, aead_1.encryptAead)(backupKey, plaintext, aad);
+                const body = {
+                    version: BACKUP_ENVELOPE_VERSION,
+                    algorithm: BACKUP_ALGORITHM,
+                    kdfInfo: recoveryPhrase_1.BACKUP_KDF_ENCRYPTION_INFO,
+                    nonce: toHex(nonce),
+                    ciphertext: toHex(ciphertext),
+                    publicKeyHint,
+                    createdAt,
+                    lookupId,
+                };
+                return await this.makeRequest('POST', '/identity/backup', body, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Whether the authenticated user has a stored encrypted backup, plus the
+         * non-sensitive hint + timestamp when one exists (`GET /identity/backup/status`,
+         * bearer). Returns no ciphertext and no locator.
+         */
+        async getBackupStatus() {
+            try {
+                return await this.makeRequest('GET', '/identity/backup/status', undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Delete the authenticated user's stored backup (`DELETE /identity/backup`,
+         * bearer). Idempotent — deleting a non-existent backup still succeeds.
+         */
+        async deleteBackup() {
+            try {
+                return await this.makeRequest('DELETE', '/identity/backup', undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Restore an identity from its encrypted off-device backup using ONLY the
+         * recovery phrase: re-derive `{backupKey, lookupId}`, fetch the envelope by
+         * `lookupId` (`GET /identity/backup/:lookupId`, PUBLIC — the 256-bit locator
+         * is the protection), decrypt + authenticate locally, then persist the key.
+         *
+         * NATIVE-ONLY persistence: `KeyManager.importKeyPair` throws on web. It also
+         * refuses to clobber a DIFFERENT existing on-device identity unless
+         * `overwrite: true` — the {@link import('../crypto/keyManager').IdentityAlreadyExistsError}
+         * propagates to the caller (never swallowed) so the UI can confirm before
+         * overwriting.
+         *
+         * @param phrase - The identity's BIP-39 recovery phrase.
+         * @param options.overwrite - Replace a different existing on-device identity.
+         * @returns The restored identity's public key.
+         * @throws if the phrase is invalid, no backup exists (404), the ciphertext
+         *   fails authentication (tamper), or an existing identity blocks the import.
+         */
+        async restoreFromEncryptedBackup(phrase, options) {
+            try {
+                const { backupKey, lookupId } = await recoveryPhrase_1.RecoveryPhraseService.deriveBackupMaterial(phrase);
+                const envelope = await this.makeRequest('GET', `/identity/backup/${encodeURIComponent(lookupId)}`, undefined, { cache: false });
+                if (envelope.algorithm !== BACKUP_ALGORITHM) {
+                    throw new Error(`Unsupported backup algorithm: ${envelope.algorithm}`);
+                }
+                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));
+                // 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, {
+                    overwrite: options?.overwrite === true,
+                });
+            }
+            catch (error) {
+                // Preserve the typed "an identity already exists" signal so the caller
+                // can prompt for overwrite. `handleError` would flatten it to a generic
+                // Error and lose that discrimination.
+                if (error instanceof keyManager_1.IdentityAlreadyExistsError) {
+                    throw error;
+                }
+                throw this.handleError(error);
+            }
+        }
+    };
+}

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

@@ -13,6 +13,12 @@ const errorUtils_1 = require("../utils/errorUtils");
  * server-side batch cap; larger inputs are split into multiple chunked calls.
  */
 const USERS_BY_IDS_CHUNK_SIZE = 100;
+/**
+ * Maximum number of ids sent per `POST /users/follow-status/bulk` request.
+ * Matches the server-side `MAX_BULK_FOLLOW` cap; larger inputs are split into
+ * multiple chunked calls whose result maps are merged.
+ */
+const FOLLOW_STATUS_CHUNK_SIZE = 200;
 function OxyServicesUserMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -604,6 +610,43 @@ function OxyServicesUserMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Resolve the viewer's follow status for MANY users in one round-trip per
+         * chunk. Built for list UIs (a page of `FollowButton`s) that would otherwise
+         * fire one `getFollowStatus` per button (the classic N+1).
+         *
+         * Ids are deduplicated and validated (empty/blank ids dropped), split into
+         * chunks of {@link FOLLOW_STATUS_CHUNK_SIZE} (the server's bulk cap), and
+         * POSTed to `/users/follow-status/bulk` as `{ userIds }`. The per-chunk
+         * `{ statuses }` maps are merged into one `Record<string, boolean>` covering
+         * every requested id — ids the viewer does not follow come back `false`.
+         *
+         * Uncached (`{ cache: false }`): the UI store owns follow-status freshness
+         * and writes optimistically on every mutation, so an SDK cache here would
+         * serve a stale status right after a follow/unfollow. An empty/whitespace-
+         * only input resolves immediately with `{}` and performs no network call.
+         */
+        async getFollowStatuses(userIds) {
+            const uniqueIds = Array.from(new Set(userIds.filter((id) => typeof id === 'string' && id.trim().length > 0)));
+            if (uniqueIds.length === 0) {
+                return {};
+            }
+            const chunks = [];
+            for (let i = 0; i < uniqueIds.length; i += FOLLOW_STATUS_CHUNK_SIZE) {
+                chunks.push(uniqueIds.slice(i, i + FOLLOW_STATUS_CHUNK_SIZE));
+            }
+            try {
+                const responses = await Promise.all(chunks.map((chunk) => this.makeRequest('POST', '/users/follow-status/bulk', { userIds: chunk }, { cache: false })));
+                const merged = {};
+                for (const response of responses) {
+                    Object.assign(merged, response?.statuses ?? {});
+                }
+                return merged;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * Get user followers
          */

package/dist/cjs/mixins/index.js

@@ -12,6 +12,7 @@ const OxyServices_base_1 = require("../OxyServices.base");
 const OxyServices_auth_1 = require("./OxyServices.auth");
 const OxyServices_user_1 = require("./OxyServices.user");
 const OxyServices_identity_1 = require("./OxyServices.identity");
+const OxyServices_identityBackup_1 = require("./OxyServices.identityBackup");
 const OxyServices_privacy_1 = require("./OxyServices.privacy");
 const OxyServices_language_1 = require("./OxyServices.language");
 const OxyServices_payment_1 = require("./OxyServices.payment");
@@ -50,6 +51,9 @@ const MIXIN_PIPELINE = [
     OxyServices_user_1.OxyServicesUserMixin,
     // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping)
     OxyServices_identity_1.OxyServicesIdentityMixin,
+    // Encrypted off-device identity backup (b3 Feature 1): store/restore an
+    // encrypted copy of the self-custody key, keyed off the recovery phrase.
+    OxyServices_identityBackup_1.OxyServicesIdentityBackupMixin,
     OxyServices_privacy_1.OxyServicesPrivacyMixin,
     // Feature mixins
     OxyServices_language_1.OxyServicesLanguageMixin,