@oxy.so/core 7.31.0 → 7.32.0

package/dist/esm/api/identity.js

@@ -21,6 +21,7 @@ import { checkContract, IDENTITY_PROOF_ACTIONS, identityLinkCreateResponseCheck,
 import { identityKeyHistoryCheck } from '@oxy.so/contracts/client';
 import { isAndroid, isWeb } from '../utils/platform.js';
 import { logger } from '../logger/index.js';
+import { extractErrorStatus } from '../utils/errorUtils.js';
 /** Short-TTL read cache for public identity reads. */
 const SHORT_TTL = 60 * 1000;
 /**
@@ -316,10 +317,31 @@ export class IdentityApi {
                 }
             }
         }
+        // 8. The rotation deleted the encrypted backup (it was sealed under the
+        //    replaced phrase). Seal a new one under the new phrase, carrying the
+        //    retired ring — now with the key just replaced — so the coins under it
+        //    survive a lost phone as long as the NEW phrase does (R4-4). Always,
+        //    not only when one existed: after a rotation it is the only copy of the
+        //    replaced key off this phone. Best-effort: the rotation already succeeded.
+        let backupRefreshed;
+        if (!isWeb() && !localPersistFailed) {
+            try {
+                await this.backup.create(pending.phrase);
+                backupRefreshed = true;
+            }
+            catch (backupError) {
+                backupRefreshed = false;
+                logger.warn('Key rotated, but the encrypted backup could not be re-created under the new phrase.', { component: 'oxy.identity', method: 'rotateKey' }, backupError);
+            }
+        }
         this.invalidate(userId);
-        return localPersistFailed
-            ? { newPublicKey, newPhrase: pending.phrase, words: pending.words, localPersistFailed: true }
-            : { newPublicKey, newPhrase: pending.phrase, words: pending.words };
+        return {
+            newPublicKey,
+            newPhrase: pending.phrase,
+            words: pending.words,
+            ...(localPersistFailed ? { localPersistFailed: true } : {}),
+            ...(backupRefreshed === undefined ? {} : { backupRefreshed }),
+        };
     }
     /**
      * The signed-in user's signed, open-format data-export bundle
@@ -508,6 +530,10 @@ const BACKUP_ALGORITHM = 'xchacha20poly1305';
  * to recognise WHICH identity a backup belongs to, but only a prefix.
  */
 const PUBLIC_KEY_HINT_LENGTH = 16;
+/** Whether a request error is the restore lookup's constant-shape 404. */
+function isNotFound(error) {
+    return extractErrorStatus(error) === 404;
+}
 /** Encode bytes as lowercase hex (cross-platform, no Buffer dependency). */
 function toHex(bytes) {
     let out = '';
@@ -567,7 +593,13 @@ export class IdentityBackupApi {
         const publicKey = KeyManager.derivePublicKey(privateKey);
         const createdAt = new Date().toISOString();
         const publicKeyHint = publicKey.slice(0, PUBLIC_KEY_HINT_LENGTH);
-        const payload = { privateKey, publicKey, createdAt };
+        const retiredKeys = await this.retiredKeysToCarry(publicKey);
+        const payload = {
+            privateKey,
+            publicKey,
+            createdAt,
+            ...(retiredKeys.length > 0 ? { retiredKeys } : {}),
+        };
         const plaintext = new TextEncoder().encode(JSON.stringify(payload));
         const aad = buildBackupAad(BACKUP_ENVELOPE_VERSION, publicKeyHint);
         const { nonce, ciphertext } = encryptAead(backupKey, plaintext, aad);
@@ -585,6 +617,107 @@ export class IdentityBackupApi {
             cache: false,
         });
     }
+    /**
+     * The retired ring this device holds for the person, limited to keys Oxy's
+     * key history names as THIS account's retired keys (the ring's iOS group is
+     * writable by the wallet app too, and a previous person's ring can outlive a
+     * "Start over"). Empty where no ring is held (web, any app but Commons).
+     * Throws when the history cannot be read while a ring exists, so a backup
+     * never silently drops keys it should carry.
+     */
+    async retiredKeysToCarry(currentPublicKey) {
+        if (isWeb())
+            return [];
+        const { exportRetiredIdentityKeys } = await import('../crypto/index.js');
+        let held;
+        try {
+            held = await exportRetiredIdentityKeys();
+        }
+        catch {
+            return []; // Not Commons: this app holds no ring to carry.
+        }
+        if (held.length === 0)
+            return [];
+        const history = await this.ctx.request('GET', '/identity/key-history', undefined, {
+            cache: false,
+        });
+        const parsed = checkContract(identityKeyHistoryCheck, history);
+        if (!parsed)
+            throw new Error('identity/key-history returned an unexpected response shape');
+        const retired = new Set(parsed.retired.map((entry) => entry.publicKey.toLowerCase()));
+        const current = currentPublicKey.toLowerCase();
+        return held.filter((key) => key.publicKey.toLowerCase() !== current && retired.has(key.publicKey.toLowerCase()));
+    }
+    /**
+     * Fetch and open the backup the phrase locates, checking it is the phrase's
+     * own identity. With `missingIsNull`, `null` when there is none (404);
+     * otherwise the request's own error propagates.
+     */
+    async open(phrase, missingIsNull = false) {
+        const { KeyManager, RecoveryPhraseService, decryptAead } = await import('../crypto/index.js');
+        const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
+        let envelope;
+        try {
+            envelope = await this.ctx.request('GET', `/identity/backup/${encodeURIComponent(lookupId)}`, undefined, { cache: false });
+        }
+        catch (error) {
+            if (missingIsNull && isNotFound(error))
+                return null;
+            throw error;
+        }
+        if (envelope.algorithm !== BACKUP_ALGORITHM) {
+            throw new Error(`Unsupported backup algorithm: ${envelope.algorithm}`);
+        }
+        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 phrasePk = (await RecoveryPhraseService.derivePublicKeyFromPhrase(phrase)).toLowerCase();
+        const payloadPk = payload.publicKey.toLowerCase();
+        const privatePk = KeyManager.derivePublicKey(payload.privateKey).toLowerCase();
+        if (phrasePk !== payloadPk || privatePk !== payloadPk) {
+            throw new Error('Backup payload does not match the recovery phrase');
+        }
+        return payload;
+    }
+    /**
+     * Keep every retired key a backup carries in this device's ring. Each pair
+     * must be healthy and must not be the current key; the envelope itself is
+     * authenticated by the phrase. Commons only (the ring refuses elsewhere).
+     * Resolves how many keys are now held; a key that fails is skipped.
+     */
+    async keepCarriedRetiredKeys(payload) {
+        const { KeyManager, retireIdentityKey } = await import('../crypto/index.js');
+        let kept = 0;
+        for (const key of Array.isArray(payload.retiredKeys) ? payload.retiredKeys : []) {
+            try {
+                if (typeof key?.privateKey !== 'string' || typeof key.publicKey !== 'string')
+                    continue;
+                if (key.publicKey.toLowerCase() === payload.publicKey.toLowerCase())
+                    continue;
+                if (KeyManager.derivePublicKey(key.privateKey).toLowerCase() !== key.publicKey.toLowerCase()) {
+                    continue;
+                }
+                await retireIdentityKey({ privateKey: key.privateKey, publicKey: key.publicKey });
+                kept += 1;
+            }
+            catch (error) {
+                logger.warn('Could not keep a retired key from the encrypted backup', { component: 'oxy.identity', method: 'backup.restoreRetiredKeys' }, error);
+            }
+        }
+        return kept;
+    }
+    /**
+     * Restore ONLY the retired keys the phrase's backup carries into this
+     * device's ring (Commons, after a phrase import or a silent device-backup
+     * restore). Resolves how many were kept; 0 when there is no backup.
+     */
+    async restoreRetiredKeys(phrase) {
+        const payload = await this.open(phrase, true);
+        return payload ? this.keepCarriedRetiredKeys(payload) : 0;
+    }
     /**
      * Whether the signed-in user has a stored backup, plus its non-sensitive hint
      * and timestamp. Returns no ciphertext and no locator.
@@ -615,24 +748,14 @@ export class IdentityBackupApi {
      *   fails authentication (tamper), or an existing identity blocks the import.
      */
     async restore(phrase, options) {
-        const { KeyManager, RecoveryPhraseService, decryptAead } = await import('../crypto/index.js');
-        const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
-        const envelope = await this.ctx.request('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 = 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 phrasePk = (await RecoveryPhraseService.derivePublicKeyFromPhrase(phrase)).toLowerCase();
-        const payloadPk = payload.publicKey.toLowerCase();
-        const privatePk = KeyManager.derivePublicKey(payload.privateKey).toLowerCase();
-        if (phrasePk !== payloadPk || privatePk !== payloadPk) {
-            throw new Error('Backup payload does not match the recovery phrase');
-        }
-        return KeyManager.importKeyPair(payload.privateKey, { overwrite: options?.overwrite === true });
+        const { KeyManager } = await import('../crypto/index.js');
+        const payload = await this.open(phrase);
+        if (!payload)
+            throw new Error('No encrypted backup was found for this recovery phrase.');
+        const publicKey = await KeyManager.importKeyPair(payload.privateKey, {
+            overwrite: options?.overwrite === true,
+        });
+        await this.keepCarriedRetiredKeys(payload);
+        return publicKey;
     }
 }

package/dist/esm/crypto/identityMarker.js

@@ -145,6 +145,20 @@ export async function readIdentityMarker() {
         return null;
     }
 }
+/**
+ * Read the marker, THROWING when the storage cannot answer (instead of the
+ * fail-open `null` of {@link readIdentityMarker}). For a caller that must not
+ * mistake "unreadable" for "never written": the iOS keychain migration, which
+ * adopts a pre-split secret only when this marker vouches for it, and records
+ * once that there is nothing to adopt.
+ */
+export async function readIdentityMarkerStrict() {
+    const storage = await getStorage();
+    if (!storage) {
+        throw new Error('The identity marker storage is unavailable.');
+    }
+    return deserialize(await storage.getItem(IDENTITY_MARKER_STORAGE_KEY));
+}
 /**
  * Write (create/replace) the marker. Returns `true` when it durably landed,
  * `false` when storage was unavailable or the write threw. Callers treat a

package/dist/esm/crypto/index.js

@@ -18,11 +18,11 @@ export { readIdentityMarker, updateIdentityMarker } from './identityMarker.js';
 // Organization keys on the device (docs/adr/0061-organization-identity-key.md D6)
 export { generateOrganizationKey, organizationKeyFromPhrase, storeOrganizationKey, getOrganizationPublicKey, getOrganizationPrivateKey, getOrganizationRecoveryPhrase, listOrganizationKeys, deleteOrganizationKey, syncOrganizationKeys, isOrganizationAccountId, isHealthyOrganizationKeyPair, } from './organizationKeys.js';
 // iOS keychain access groups (docs/identity/ios-keychain-access-groups.md, ADR 0062)
-export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFor, mayHoldKeychainItem, resolveKeychainAccess, keychainAccessGroupValue, keychainReadPlan, keychainDeletePlan, keychainWriteOption, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, groupedKeychainStore, } from '../utils/keychainAccessGroups.js';
-export { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
+export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFor, mayHoldKeychainItem, mayWriteKeychainItem, DEV_KEYCHAIN_GROUP_SUFFIX, resolveKeychainAccess, keychainAccessGroupValue, keychainReadPlan, keychainDeletePlan, keychainWriteOption, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, groupedKeychainStore, } from '../utils/keychainAccessGroups.js';
+export { ensureKeychainGroupsMigrated, getPreSplitExposure, } from './keychainGroupMigration.js';
 // Retired identity keys: kept for spending after a rotation or replacement
 // (docs/adr/0061-organization-identity-key.md D7 as amended 2026-11-06)
-export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, } from './retiredKeys.js';
+export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, retiredKeyFromPrivateKey, exportRetiredIdentityKeys, } from './retiredKeys.js';
 export { SignatureService } from './signatureService.js';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase.js';
 // Low-level primitives (encrypted backup, device transfer)

package/dist/esm/crypto/keyManager.js

@@ -11,9 +11,9 @@ import { isDev, logger } from '../logger/index.js';
 import { deriveScopedSeedFromKey, signSocialReceiveDigest } from './identityDerivations.js';
 import { registerIdentitySignerStore } from './identitySigner.js';
 import { getOrganizationPrivateKey, isOrganizationAccountId } from './organizationKeys.js';
-import { forgetRetiredIdentityKeys, getRetiredPrivateKey, retiredKeyScope } from './retiredKeys.js';
+import { getRetiredPrivateKey, retiredKeyScope } from './retiredKeys.js';
 import { groupedKeychainStore, resolveKeychainAccess, } from '../utils/keychainAccessGroups.js';
-import { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
+import { prepareKeychainAccess } from './keychainGroupMigration.js';
 import { RECOVERY_MNEMONIC_KEYCHAIN_SERVICE, RECOVERY_MNEMONIC_STORAGE_KEY, STORAGE_KEYS, V2_BACKUP_KEYCHAIN_SERVICE, V2_PRIMARY_KEYCHAIN_SERVICE, V2_STORAGE_KEYS, } from './keychainItems.js';
 import { clearIdentityMarker, readIdentityMarker, updateIdentityMarker, writeIdentityMarker, } from './identityMarker.js';
 import { DEVICE_BACKUP_VERSION, parseDeviceBackup, serializeDeviceBackup, } from './deviceBackup.js';
@@ -172,9 +172,7 @@ async function loadRawSecureStore() {
 async function keychainItemStore(item) {
     const raw = await loadRawSecureStore();
     const access = await resolveKeychainAccess();
-    if (access.mode === 'grouped' && access.role === 'holder') {
-        await ensureKeychainGroupsMigrated();
-    }
+    await prepareKeychainAccess(access);
     return groupedKeychainStore(raw, access, item);
 }
 /** The store for the identity slots (primary, backup, legacy, phrase): Commons only on iOS. */
@@ -2050,13 +2048,12 @@ export class KeyManager {
         if (force) {
             await KeyManager._bestEffortDeleteBackupsAllGenerations(store);
             await KeyManager._clearSharedSlot(store);
-            // The person's retired keys go with the identity they belonged to.
-            try {
-                await forgetRetiredIdentityKeys();
-            }
-            catch (error) {
-                logger.warn('Failed to clear retired keys during delete', { component: 'KeyManager' }, error);
-            }
+            // The retired ring is NOT cleared (R4-4): it is money under the person's
+            // previous keys, and "Start over" or a forced delete must not cost it.
+            // The same person restoring their identity finds it again; a different
+            // identity on this phone cannot use it (each entry is checked against
+            // that account's key history before use). Only deleting the Oxy ACCOUNT
+            // clears it, explicitly (`forgetRetiredIdentityKeys`, Commons' flow).
         }
         // The device backup goes on EVERY delete, forced or not: it is restored
         // silently, so leaving it would bring a deleted identity back on the next