@oxyhq/core 12.9.0 → 12.10.0

package/dist/esm/crypto/keyManager.js

@@ -117,6 +117,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
@@ -1471,6 +1489,73 @@ export 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 (isDev()) {
+                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 (isDev()) {
+                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.
      *
@@ -1686,6 +1771,10 @@ export 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/esm/index.js

@@ -26,7 +26,8 @@ export { OXY_CLOUD_URL, oxyClient } from './OxyServices.js';
 // ---------------------------------------------------------------------------
 // Authentication
 // ---------------------------------------------------------------------------
-export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth.js';
+export { ServiceCredentialMismatchError, } from './mixins/OxyServices.auth.js';
+export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from './utils/commonsApproval.js';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData.js';
 // ---------------------------------------------------------------------------
 // User identity and handles

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

@@ -1,4 +1,5 @@
 import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
+export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from '../utils/commonsApproval.js';
 import { OxyAuthenticationError } from '../OxyServices.errors.js';
 import { KeyManager } from '../crypto/keyManager.js';
 import { SignatureService } from '../crypto/signatureService.js';

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

@@ -138,6 +138,17 @@ export function OxyServicesIdentityBackupMixin(Base) {
                 const aad = buildBackupAad(envelope.version, envelope.publicKeyHint);
                 const plaintext = 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 RecoveryPhraseService.derivePublicKeyFromPhrase(phrase);
+                const derivedFromPrivate = 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.importKeyPair(payload.privateKey, {

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

@@ -420,6 +420,10 @@ export 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/esm/utils/commonsApproval.js

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export 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. */
+export 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;
+}