@oxyhq/core 12.2.1 → 12.4.0

package/dist/cjs/crypto/aead.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Authenticated Encryption with Associated Data (XChaCha20-Poly1305)
+ *
+ * Pure-JS/TS AEAD via `@noble/ciphers` — identical behaviour on web, Node, and
+ * React Native with zero WebCrypto / native-module dependency. This replaces
+ * the `crypto.subtle`-based path (unreliable on React Native) for the Commons
+ * encrypted backup and device-to-device transfer flows.
+ *
+ * XChaCha20-Poly1305 is chosen over AES-GCM specifically for its 24-byte
+ * (192-bit) random nonce: the nonce space is large enough that random nonces
+ * never collide in practice, so callers do not need to maintain a per-key
+ * counter. The 16-byte Poly1305 tag is appended to the ciphertext by the
+ * underlying library and validated on decrypt.
+ *
+ * The optional Associated Data (AAD) is authenticated but NOT encrypted: it
+ * binds the ciphertext to its context (e.g. a backup version, a device id, a
+ * DID). Decryption fails if the key, nonce, ciphertext, OR aad differ from
+ * those used at encryption time.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = void 0;
+exports.encryptAead = encryptAead;
+exports.decryptAead = decryptAead;
+// Loading the polyfill guarantees `globalThis.crypto.getRandomValues` exists on
+// every platform (native crypto on web/Node; expo-crypto-backed shim on RN).
+require("./polyfill");
+const chacha_1 = require("@noble/ciphers/chacha");
+/** Key length for XChaCha20-Poly1305, in bytes (256-bit). */
+exports.AEAD_KEY_LENGTH = 32;
+/** Nonce length for XChaCha20-Poly1305, in bytes (192-bit). */
+exports.AEAD_NONCE_LENGTH = 24;
+function assertKey(key) {
+    if (key.length !== exports.AEAD_KEY_LENGTH) {
+        throw new Error(`AEAD key must be ${exports.AEAD_KEY_LENGTH} bytes, got ${key.length}`);
+    }
+}
+/** Generate a fresh 24-byte random nonce via the platform CSPRNG. */
+function randomNonce() {
+    const nonce = new Uint8Array(exports.AEAD_NONCE_LENGTH);
+    globalThis.crypto.getRandomValues(nonce);
+    return nonce;
+}
+/**
+ * Encrypt `plaintext` under `key` with a fresh random nonce, authenticating the
+ * optional `aad`.
+ *
+ * @param key       32-byte symmetric key (e.g. from `hkdfSha256`).
+ * @param plaintext Bytes to encrypt.
+ * @param aad       Optional associated data authenticated but not encrypted.
+ * @returns         `{ nonce, ciphertext }` — both are required to decrypt.
+ */
+function encryptAead(key, plaintext, aad) {
+    assertKey(key);
+    const nonce = randomNonce();
+    const ciphertext = (0, chacha_1.xchacha20poly1305)(key, nonce, aad).encrypt(plaintext);
+    return { nonce, ciphertext };
+}
+/**
+ * Decrypt and authenticate `ciphertext` produced by {@link encryptAead}.
+ *
+ * Throws if the key, nonce, ciphertext, or aad differ from those used at
+ * encryption time (tamper detection), or if the tag is invalid.
+ *
+ * @param key        32-byte symmetric key.
+ * @param nonce      The 24-byte nonce returned by `encryptAead`.
+ * @param ciphertext Ciphertext with the appended Poly1305 tag.
+ * @param aad        The same associated data supplied at encryption time.
+ * @returns          The recovered plaintext bytes.
+ */
+function decryptAead(key, nonce, ciphertext, aad) {
+    assertKey(key);
+    if (nonce.length !== exports.AEAD_NONCE_LENGTH) {
+        throw new Error(`AEAD nonce must be ${exports.AEAD_NONCE_LENGTH} bytes, got ${nonce.length}`);
+    }
+    return (0, chacha_1.xchacha20poly1305)(key, nonce, aad).decrypt(ciphertext);
+}

package/dist/cjs/crypto/ecdh.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * ECDH shared-secret derivation (secp256k1)
+ *
+ * Derives a raw 32-byte ECDH shared secret from a local private key and a
+ * remote public key, using the SAME `elliptic` `EC('secp256k1')` primitive the
+ * rest of core's identity layer uses (`keyManager.ts`). This is the key-exchange
+ * step for the Commons device-to-device transfer flow: each side computes the
+ * same shared secret, which is then run through `hkdfSha256` to derive the
+ * symmetric key handed to `encryptAead` / `decryptAead`.
+ *
+ * The returned value is the raw x-coordinate of the ECDH point, big-endian,
+ * zero-padded to 32 bytes. It is NOT itself a symmetric key — always pass it
+ * through a KDF (HKDF) with a context-binding `info` before use.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveSharedSecret = deriveSharedSecret;
+const elliptic_1 = require("elliptic");
+const ec = new elliptic_1.ec('secp256k1');
+/** Lowercase and left-pad a private-key hex string to canonical 64-char form. */
+function canonicalPrivateKey(key) {
+    return key.toLowerCase().padStart(64, '0');
+}
+const HEX_RE = /^[0-9a-fA-F]+$/;
+/**
+ * Compute the ECDH shared secret between a local private key and a remote
+ * public key on secp256k1.
+ *
+ * Symmetric by construction:
+ * `deriveSharedSecret(privA, pubB) === deriveSharedSecret(privB, pubA)`.
+ *
+ * @param privateKeyHex     Local private key, hex (up to 64 chars; canonicalized).
+ * @param otherPublicKeyHex Remote public key, hex — compressed (`02`/`03` + 32
+ *                          bytes) or uncompressed (`04` + 64 bytes).
+ * @returns                 The 32-byte big-endian shared secret.
+ */
+function deriveSharedSecret(privateKeyHex, otherPublicKeyHex) {
+    if (typeof privateKeyHex !== 'string' || !HEX_RE.test(privateKeyHex)) {
+        throw new Error('deriveSharedSecret: privateKeyHex must be a hex string');
+    }
+    if (typeof otherPublicKeyHex !== 'string' || !HEX_RE.test(otherPublicKeyHex)) {
+        throw new Error('deriveSharedSecret: otherPublicKeyHex must be a hex string');
+    }
+    const keyPair = ec.keyFromPrivate(canonicalPrivateKey(privateKeyHex));
+    const otherKey = ec.keyFromPublic(otherPublicKeyHex, 'hex');
+    // `derive` returns a BN (the shared point's x-coordinate). Serialize it
+    // big-endian, fixed 32 bytes, so both sides agree byte-for-byte regardless of
+    // any leading-zero stripping.
+    const sharedBytes = keyPair.derive(otherKey.getPublic()).toArray('be', 32);
+    return Uint8Array.from(sharedBytes);
+}

package/dist/cjs/crypto/kdf.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Key Derivation Function (HKDF-SHA256)
+ *
+ * Pure-JS/TS HKDF via `@noble/hashes` — identical behaviour on web, Node, and
+ * React Native with zero WebCrypto / native-module dependency. Used to derive
+ * fixed-length symmetric keys from higher-entropy input keying material (an
+ * ECDH shared secret, a recovery-phrase seed, etc.) for the Commons encrypted
+ * backup and device-to-device transfer flows.
+ *
+ * ESM/CJS safe: static `import` only, no `require()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hkdfSha256 = hkdfSha256;
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha256_1 = require("@noble/hashes/sha256");
+/**
+ * Derive `length` bytes of keying material from `ikm` using HKDF-SHA256
+ * (RFC 5869 — extract-then-expand).
+ *
+ * @param ikm    Input keying material (the raw secret; NOT necessarily uniform).
+ * @param salt   Non-secret random salt. An empty array is treated by HKDF as a
+ *               zero-filled salt of the hash length — pass a real salt whenever
+ *               one is available so derivations for different contexts diverge.
+ * @param info   Context/application-binding string ("what is this key for").
+ *               Distinct `info` values yield independent keys from the same ikm.
+ * @param length Number of output bytes. Must be in (0, 255 * 32].
+ * @returns      Exactly `length` bytes of derived keying material.
+ */
+function hkdfSha256(ikm, salt, info, length) {
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error('hkdfSha256: length must be a positive integer');
+    }
+    // HKDF-Expand is defined for at most 255 * HashLen bytes of output.
+    if (length > 255 * 32) {
+        throw new Error('hkdfSha256: length must not exceed 8160 bytes (255 * 32)');
+    }
+    return (0, hkdf_1.hkdf)(sha256_1.sha256, ikm, salt, info, length);
+}

package/dist/cjs/crypto/keyManager.js

@@ -1295,6 +1295,13 @@ class KeyManager {
         const keyPair = ec.keyFromPrivate(KeyManager.canonicalPrivateKey(privateKey));
         return keyPair.getPublic('hex');
     }
+    /**
+     * Normalize a public key to uncompressed, lowercased hex. Used when building
+     * signed rotation payloads so legacy compressed/cased encodings still verify.
+     */
+    static canonicalPublicKey(publicKey) {
+        return ec.keyFromPublic(publicKey, 'hex').getPublic(false, 'hex').toLowerCase();
+    }
     /**
      * Validate that a string is a valid public key
      *

package/dist/cjs/crypto/recoveryPhrase.js

@@ -41,9 +41,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecoveryPhraseService = void 0;
+exports.RecoveryPhraseService = exports.BACKUP_MATERIAL_LENGTH = exports.BACKUP_KDF_LOOKUP_INFO = exports.BACKUP_KDF_ENCRYPTION_INFO = exports.BACKUP_KDF_SALT = void 0;
 const bip39 = __importStar(require("bip39"));
 const keyManager_1 = require("./keyManager");
+const kdf_1 = require("./kdf");
 /**
  * Convert Uint8Array or array-like to hexadecimal string
  * Works in both Node.js and React Native without depending on Buffer
@@ -55,6 +56,22 @@ function toHex(data) {
         .map(b => b.toString(16).padStart(2, '0'))
         .join('');
 }
+/** UTF-8 encode an ASCII label to bytes (for HKDF salt/info). */
+function utf8(label) {
+    return new TextEncoder().encode(label);
+}
+/**
+ * HKDF context tag for the encrypted-backup key schedule (b3 Feature 1). Used as
+ * the HKDF `salt`; distinct from any other Oxy key-derivation salt so the backup
+ * key schedule is independent. Versioned so a future scheme change is a new tag.
+ */
+exports.BACKUP_KDF_SALT = 'oxy-identity-backup-v1';
+/** HKDF `info` label that derives the symmetric AEAD key from the seed. */
+exports.BACKUP_KDF_ENCRYPTION_INFO = 'oxy-backup-encryption-key';
+/** HKDF `info` label that derives the (server-hashed) backup locator from the seed. */
+exports.BACKUP_KDF_LOOKUP_INFO = 'oxy-backup-lookup-id';
+/** Byte length of both the derived backup key and the derived lookup id (256-bit). */
+exports.BACKUP_MATERIAL_LENGTH = 32;
 class RecoveryPhraseService {
     /**
      * Generate a new identity with a recovery phrase.
@@ -105,6 +122,77 @@ class RecoveryPhraseService {
             publicKey,
         };
     }
+    /**
+     * Derive a brand-new identity + recovery phrase WITHOUT persisting anything.
+     *
+     * Pure: same derivation as {@link generateIdentityWithRecovery} (128-bit
+     * mnemonic → seed → first 32 bytes as the secp256k1 private key) but it stops
+     * BEFORE `KeyManager.importKeyPair`, so no on-device identity is touched. The
+     * caller decides if/when to commit the material (e.g. only after a server
+     * confirms a key rotation). Works on web too — it never reads or writes secure
+     * storage.
+     *
+     * The 12-word `phrase` MUST be shown to the user before the identity is
+     * committed anywhere — if it is lost the account becomes unrecoverable.
+     */
+    static async derivePendingIdentity() {
+        const mnemonic = bip39.generateMnemonic(128);
+        const seed = await bip39.mnemonicToSeed(mnemonic);
+        const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
+        const privateKey = toHex(seedSlice);
+        const publicKey = keyManager_1.KeyManager.derivePublicKey(privateKey);
+        return {
+            phrase: mnemonic,
+            words: mnemonic.split(' '),
+            privateKey,
+            publicKey,
+        };
+    }
+    /**
+     * Derive the private key from a recovery phrase WITHOUT storing it.
+     *
+     * The private-key counterpart of {@link derivePublicKeyFromPhrase}. Used to
+     * re-derive a key in memory (e.g. to sign a rotation proof with the current
+     * key when the device has no SecureStore copy). Never persists — the returned
+     * material lives only in the caller's memory.
+     */
+    static async derivePrivateKeyFromPhrase(phrase) {
+        const normalizedPhrase = phrase.trim().toLowerCase();
+        if (!bip39.validateMnemonic(normalizedPhrase)) {
+            throw new Error('Invalid recovery phrase');
+        }
+        const seed = await bip39.mnemonicToSeed(normalizedPhrase);
+        const seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
+        return toHex(seedSlice);
+    }
+    /**
+     * Derive the encrypted-backup key material from a recovery phrase (b3 Feature
+     * 1). PURE and additive — it does NOT touch the frozen phrase→privateKey
+     * derivation ({@link derivePrivateKeyFromPhrase} slices the first 32 seed
+     * bytes) and never reads or writes secure storage.
+     *
+     * Both outputs are derived from the FULL 64-byte BIP-39 seed via HKDF-SHA256
+     * with domain-separated `info` labels, so the domain separation is real: a
+     * device compromise that leaks only the raw 32-byte private key can compute
+     * NEITHER the backup key nor the lookup id (both need the whole seed). Locating
+     * AND decrypting a backup therefore requires the recovery phrase.
+     *
+     * @param phrase - The BIP-39 recovery phrase (validated + normalized here).
+     * @returns `{ backupKey, lookupId }` — the AEAD key (kept local) and the hex
+     *   locator (uploaded; server stores only its hash).
+     * @throws if the phrase is not a valid BIP-39 mnemonic.
+     */
+    static async deriveBackupMaterial(phrase) {
+        const normalizedPhrase = phrase.trim().toLowerCase();
+        if (!bip39.validateMnemonic(normalizedPhrase)) {
+            throw new Error('Invalid recovery phrase. Please check the words and try again.');
+        }
+        const seed = await bip39.mnemonicToSeed(normalizedPhrase);
+        const salt = utf8(exports.BACKUP_KDF_SALT);
+        const backupKey = (0, kdf_1.hkdfSha256)(seed, salt, utf8(exports.BACKUP_KDF_ENCRYPTION_INFO), exports.BACKUP_MATERIAL_LENGTH);
+        const lookupId = toHex((0, kdf_1.hkdfSha256)(seed, salt, utf8(exports.BACKUP_KDF_LOOKUP_INFO), exports.BACKUP_MATERIAL_LENGTH));
+        return { backupKey, lookupId };
+    }
     /**
      * Restore an identity from a recovery phrase.
      *

package/dist/cjs/i18n/locales/en-US.json

@@ -72,6 +72,9 @@
         "backToSignInLink": "Already have an account? Sign in",
         "hubExplainer": "Create your Oxy ID in a secure window, then come right back.",
         "continueInWindow": "Continue in a new window",
+        "toasts": {
+            "passkeyCreateFailed": "We couldn't create your account. Please try again."
+        },
         "welcome": {
             "title": "Welcome to Oxy!",
             "subtitle": "Let's create your account in just a few steps",
@@ -374,6 +377,8 @@
         "toasts": {
             "switchSuccess": "Account switched successfully!",
             "switchFailed": "There was a problem switching accounts. Please try again.",
+            "signInFailed": "Sign-in failed. Please try again.",
+            "passkeySignInFailed": "Passkey sign-in failed. Please try again.",
             "removeSuccess": "Account removed successfully!",
             "removeFailed": "There was a problem removing the account. Please try again.",
             "signOutAllSuccess": "All accounts signed out successfully!",

package/dist/cjs/i18n/locales/es-ES.json

@@ -72,6 +72,9 @@
         "backToSignInLink": "¿Ya tienes cuenta? Inicia sesión",
         "hubExplainer": "Crea tu Oxy ID en una ventana segura y vuelve enseguida.",
         "continueInWindow": "Continuar en una ventana nueva",
+        "toasts": {
+            "passkeyCreateFailed": "No pudimos crear tu cuenta. Inténtalo de nuevo."
+        },
         "welcome": {
             "title": "¡Te damos la bienvenida a Oxy!",
             "subtitle": "Crea tu cuenta en pocos pasos",
@@ -572,6 +575,8 @@
         "toasts": {
             "switchSuccess": "¡Cuenta cambiada correctamente!",
             "switchFailed": "Hubo un problema al cambiar de cuenta. Inténtalo de nuevo.",
+            "signInFailed": "No se pudo iniciar sesión. Inténtalo de nuevo.",
+            "passkeySignInFailed": "No se pudo iniciar sesión con la llave de acceso. Inténtalo de nuevo.",
             "removeSuccess": "¡Cuenta eliminada correctamente!",
             "removeFailed": "Hubo un problema al eliminar la cuenta. Inténtalo de nuevo.",
             "signOutAllSuccess": "¡Todas las cuentas cerradas correctamente!",

package/dist/cjs/i18n/locales/locales/en-US.json

@@ -72,6 +72,9 @@
     "backToSignInLink": "Already have an account? Sign in",
     "hubExplainer": "Create your Oxy ID in a secure window, then come right back.",
     "continueInWindow": "Continue in a new window",
+    "toasts": {
+      "passkeyCreateFailed": "We couldn't create your account. Please try again."
+    },
     "welcome": {
       "title": "Welcome to Oxy!",
       "subtitle": "Let's create your account in just a few steps",
@@ -374,6 +377,8 @@
     "toasts": {
       "switchSuccess": "Account switched successfully!",
       "switchFailed": "There was a problem switching accounts. Please try again.",
+      "signInFailed": "Sign-in failed. Please try again.",
+      "passkeySignInFailed": "Passkey sign-in failed. Please try again.",
       "removeSuccess": "Account removed successfully!",
       "removeFailed": "There was a problem removing the account. Please try again.",
       "signOutAllSuccess": "All accounts signed out successfully!",

package/dist/cjs/i18n/locales/locales/es-ES.json

@@ -72,6 +72,9 @@
     "backToSignInLink": "¿Ya tienes cuenta? Inicia sesión",
     "hubExplainer": "Crea tu Oxy ID en una ventana segura y vuelve enseguida.",
     "continueInWindow": "Continuar en una ventana nueva",
+    "toasts": {
+      "passkeyCreateFailed": "No pudimos crear tu cuenta. Inténtalo de nuevo."
+    },
     "welcome": {
       "title": "¡Te damos la bienvenida a Oxy!",
       "subtitle": "Crea tu cuenta en pocos pasos",
@@ -572,6 +575,8 @@
     "toasts": {
       "switchSuccess": "¡Cuenta cambiada correctamente!",
       "switchFailed": "Hubo un problema al cambiar de cuenta. Inténtalo de nuevo.",
+      "signInFailed": "No se pudo iniciar sesión. Inténtalo de nuevo.",
+      "passkeySignInFailed": "No se pudo iniciar sesión con la llave de acceso. Inténtalo de nuevo.",
       "removeSuccess": "¡Cuenta eliminada correctamente!",
       "removeFailed": "Hubo un problema al eliminar la cuenta. Inténtalo de nuevo.",
       "signOutAllSuccess": "¡Todas las cuentas cerradas correctamente!",

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.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;
 // 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
 // ---------------------------------------------------------------------------
@@ -212,6 +222,9 @@ Object.defineProperty(exports, "isValidEmail", { enumerable: true, get: function
 Object.defineProperty(exports, "isValidUsername", { enumerable: true, get: function () { return validationUtils_1.isValidUsername; } });
 Object.defineProperty(exports, "isValidPassword", { enumerable: true, get: function () { return validationUtils_1.isValidPassword; } });
 Object.defineProperty(exports, "isValidDisplayName", { enumerable: true, get: function () { return validationUtils_1.isValidDisplayName; } });
+Object.defineProperty(exports, "DISPLAY_NAME_ALLOWED_SCRIPTS", { enumerable: true, get: function () { return validationUtils_1.DISPLAY_NAME_ALLOWED_SCRIPTS; } });
+Object.defineProperty(exports, "DISPLAY_NAME_DISALLOWED_SOURCE", { enumerable: true, get: function () { return validationUtils_1.DISPLAY_NAME_DISALLOWED_SOURCE; } });
+Object.defineProperty(exports, "DISPLAY_NAME_ORPHANED_MARK_SOURCE", { enumerable: true, get: function () { return validationUtils_1.DISPLAY_NAME_ORPHANED_MARK_SOURCE; } });
 Object.defineProperty(exports, "isRequiredString", { enumerable: true, get: function () { return validationUtils_1.isRequiredString; } });
 Object.defineProperty(exports, "isRequiredNumber", { enumerable: true, get: function () { return validationUtils_1.isRequiredNumber; } });
 Object.defineProperty(exports, "isRequiredBoolean", { enumerable: true, get: function () { return validationUtils_1.isRequiredBoolean; } });

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