@oxy.so/core 7.31.0 → 7.33.0

package/dist/cjs/api/identity.js

@@ -59,6 +59,7 @@ const client_1 = require("@oxy.so/contracts/client");
 const client_2 = require("@oxy.so/contracts/client");
 const platform_1 = require("../utils/platform");
 const logger_1 = require("../logger");
+const errorUtils_1 = require("../utils/errorUtils");
 /** Short-TTL read cache for public identity reads. */
 const SHORT_TTL = 60 * 1000;
 /**
@@ -236,7 +237,7 @@ class IdentityApi {
             try {
                 if (!oldPrivateKeyForRing)
                     throw new Error('no readable private key');
-                await retireIdentityKey({ privateKey: oldPrivateKeyForRing, publicKey: oldPublicKey });
+                await retireIdentityKey({ privateKey: oldPrivateKeyForRing, publicKey: oldPublicKey }, { ownerAccountId: userId });
             }
             catch (retainError) {
                 logger_1.logger.warn('Could not keep the current key as a retired key; not rotating.', { component: 'oxy.identity', method: 'rotateKey' }, retainError);
@@ -354,10 +355,31 @@ 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 (!(0, platform_1.isWeb)() && !localPersistFailed) {
+            try {
+                await this.backup.create(pending.phrase);
+                backupRefreshed = true;
+            }
+            catch (backupError) {
+                backupRefreshed = false;
+                logger_1.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
@@ -549,6 +571,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 (0, errorUtils_1.extractErrorStatus)(error) === 404;
+}
 /** Encode bytes as lowercase hex (cross-platform, no Buffer dependency). */
 function toHex(bytes) {
     let out = '';
@@ -608,7 +634,13 @@ 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);
@@ -626,6 +658,115 @@ 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 ((0, platform_1.isWeb)())
+            return [];
+        const { exportRetiredIdentityKeys } = await Promise.resolve().then(() => __importStar(require('../crypto/index')));
+        const userId = this.ctx.oxy.session.userId;
+        if (!userId)
+            throw new Error('No authenticated user — sign in before backing up.');
+        let held;
+        try {
+            held = await exportRetiredIdentityKeys({ ownerAccountId: userId });
+        }
+        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 = (0, client_1.checkContract)(client_2.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 Promise.resolve().then(() => __importStar(require('../crypto/index')));
+        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 Promise.resolve().then(() => __importStar(require('../crypto/index')));
+        // The backup is the signed-in account's (its phrase opened it): its keys
+        // are kept for that account only (R5-2).
+        const ownerAccountId = this.ctx.oxy.session.userId;
+        if (!ownerAccountId)
+            throw new Error('No authenticated user — sign in before restoring.');
+        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 }, { ownerAccountId });
+                kept += 1;
+            }
+            catch (error) {
+                logger_1.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.
@@ -656,25 +797,15 @@ class IdentityBackupApi {
      *   fails authentication (tamper), or an existing identity blocks the import.
      */
     async restore(phrase, options) {
-        const { KeyManager, RecoveryPhraseService, decryptAead } = await Promise.resolve().then(() => __importStar(require('../crypto/index')));
-        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 Promise.resolve().then(() => __importStar(require('../crypto/index')));
+        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;
     }
 }
 exports.IdentityBackupApi = IdentityBackupApi;

package/dist/cjs/crypto/identityMarker.js

@@ -30,6 +30,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IDENTITY_MARKER_STORAGE_KEY = void 0;
 exports.readIdentityMarker = readIdentityMarker;
+exports.readIdentityMarkerStrict = readIdentityMarkerStrict;
 exports.writeIdentityMarker = writeIdentityMarker;
 exports.updateIdentityMarker = updateIdentityMarker;
 exports.clearIdentityMarker = clearIdentityMarker;
@@ -152,6 +153,20 @@ 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.
+ */
+async function readIdentityMarkerStrict() {
+    const storage = await getStorage();
+    if (!storage) {
+        throw new Error('The identity marker storage is unavailable.');
+    }
+    return deserialize(await storage.getItem(exports.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/cjs/crypto/index.js

@@ -12,8 +12,8 @@
  * common chunk, which is the cost the lazy loading exists to avoid.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deriveScopedSeedFromKey = exports.MAX_SOCIAL_RECEIVE_INDEX = exports.SOCIAL_RECEIVE_CHAIN_CODE_KEY = exports.SCOPED_SEED_KDF_SALT = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.BACKUP_KDF_ENCRYPTION_INFO = exports.RecoveryPhraseService = exports.SignatureService = exports.retiredKeyFromPhrase = exports.syncRetiredKeys = exports.forgetRetiredIdentityKeys = exports.forgetRetiredIdentityKey = exports.listRetiredIdentityKeys = exports.retireIdentityKey = exports.ensureKeychainGroupsMigrated = exports.groupedKeychainStore = exports.deleteThroughPlan = exports.readThroughPlan = exports.ownKeychainItemPlan = exports.keychainWriteOption = exports.keychainDeletePlan = exports.keychainReadPlan = exports.keychainAccessGroupValue = exports.resolveKeychainAccess = exports.mayHoldKeychainItem = exports.keychainGroupFor = exports.KeychainAccessUnavailableError = exports.KEYCHAIN_ACCESS_GROUPS = exports.isHealthyOrganizationKeyPair = exports.isOrganizationAccountId = exports.syncOrganizationKeys = exports.deleteOrganizationKey = exports.listOrganizationKeys = exports.getOrganizationRecoveryPhrase = exports.getOrganizationPrivateKey = exports.getOrganizationPublicKey = exports.storeOrganizationKey = exports.organizationKeyFromPhrase = exports.generateOrganizationKey = exports.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = void 0;
-exports.verifySignature = exports.signMessage = exports.loadCommonsIdentityBridge = exports.canonicalize = exports.createContentHasher = exports.solveRegistrationPow = exports.deriveIdentityLinkCode = exports.signIdentityProof = exports.digestIdentityPayload = exports.authChallengeDigest = exports.signSocialReceiveDigest = void 0;
+exports.hkdfSha256 = exports.BACKUP_KDF_ENCRYPTION_INFO = exports.RecoveryPhraseService = exports.SignatureService = exports.RetiredKeyRingUnreadableError = exports.unmirrorPersonalRetiredKeys = exports.countQuarantinedRetiredKeys = exports.claimRetiredIdentityKeys = exports.exportRetiredIdentityKeys = exports.retiredKeyFromPrivateKey = exports.retiredKeyFromPhrase = exports.syncRetiredKeys = exports.forgetRetiredIdentityKeys = exports.forgetRetiredIdentityKey = exports.listRetiredIdentityKeys = exports.retireIdentityKey = exports.getPreSplitExposure = exports.ensureKeychainGroupsMigrated = exports.groupedKeychainStore = exports.deleteThroughPlan = exports.readThroughPlan = exports.ownKeychainItemPlan = exports.keychainWriteOption = exports.keychainDeletePlan = exports.keychainReadPlan = exports.keychainAccessGroupValue = exports.resolveKeychainAccess = exports.DEV_KEYCHAIN_GROUP_SUFFIX = exports.mayWriteKeychainItem = exports.mayHoldKeychainItem = exports.keychainGroupFor = exports.KeychainAccessUnavailableError = exports.KEYCHAIN_ACCESS_GROUPS = exports.isHealthyOrganizationKeyPair = exports.isOrganizationAccountId = exports.syncOrganizationKeys = exports.deleteOrganizationKey = exports.listOrganizationKeys = exports.getOrganizationRecoveryPhrase = exports.getOrganizationPrivateKey = exports.getOrganizationPublicKey = exports.storeOrganizationKey = exports.organizationKeyFromPhrase = exports.generateOrganizationKey = exports.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = void 0;
+exports.verifySignature = exports.signMessage = exports.loadCommonsIdentityBridge = exports.canonicalize = exports.createContentHasher = exports.solveRegistrationPow = exports.deriveIdentityLinkCode = exports.signIdentityProof = exports.digestIdentityPayload = exports.authChallengeDigest = exports.signSocialReceiveDigest = exports.deriveScopedSeedFromKey = exports.MAX_SOCIAL_RECEIVE_INDEX = exports.SOCIAL_RECEIVE_CHAIN_CODE_KEY = exports.SCOPED_SEED_KDF_SALT = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = void 0;
 // MUST stay the first import: the shim has to exist before any module below
 // evaluates or draws randomness (see `./polyfill`).
 require("./polyfill");
@@ -44,6 +44,8 @@ Object.defineProperty(exports, "KEYCHAIN_ACCESS_GROUPS", { enumerable: true, get
 Object.defineProperty(exports, "KeychainAccessUnavailableError", { enumerable: true, get: function () { return keychainAccessGroups_1.KeychainAccessUnavailableError; } });
 Object.defineProperty(exports, "keychainGroupFor", { enumerable: true, get: function () { return keychainAccessGroups_1.keychainGroupFor; } });
 Object.defineProperty(exports, "mayHoldKeychainItem", { enumerable: true, get: function () { return keychainAccessGroups_1.mayHoldKeychainItem; } });
+Object.defineProperty(exports, "mayWriteKeychainItem", { enumerable: true, get: function () { return keychainAccessGroups_1.mayWriteKeychainItem; } });
+Object.defineProperty(exports, "DEV_KEYCHAIN_GROUP_SUFFIX", { enumerable: true, get: function () { return keychainAccessGroups_1.DEV_KEYCHAIN_GROUP_SUFFIX; } });
 Object.defineProperty(exports, "resolveKeychainAccess", { enumerable: true, get: function () { return keychainAccessGroups_1.resolveKeychainAccess; } });
 Object.defineProperty(exports, "keychainAccessGroupValue", { enumerable: true, get: function () { return keychainAccessGroups_1.keychainAccessGroupValue; } });
 Object.defineProperty(exports, "keychainReadPlan", { enumerable: true, get: function () { return keychainAccessGroups_1.keychainReadPlan; } });
@@ -55,6 +57,7 @@ Object.defineProperty(exports, "deleteThroughPlan", { enumerable: true, get: fun
 Object.defineProperty(exports, "groupedKeychainStore", { enumerable: true, get: function () { return keychainAccessGroups_1.groupedKeychainStore; } });
 var keychainGroupMigration_1 = require("./keychainGroupMigration");
 Object.defineProperty(exports, "ensureKeychainGroupsMigrated", { enumerable: true, get: function () { return keychainGroupMigration_1.ensureKeychainGroupsMigrated; } });
+Object.defineProperty(exports, "getPreSplitExposure", { enumerable: true, get: function () { return keychainGroupMigration_1.getPreSplitExposure; } });
 // Retired identity keys: kept for spending after a rotation or replacement
 // (docs/adr/0061-organization-identity-key.md D7 as amended 2026-11-06)
 var retiredKeys_1 = require("./retiredKeys");
@@ -64,6 +67,12 @@ Object.defineProperty(exports, "forgetRetiredIdentityKey", { enumerable: true, g
 Object.defineProperty(exports, "forgetRetiredIdentityKeys", { enumerable: true, get: function () { return retiredKeys_1.forgetRetiredIdentityKeys; } });
 Object.defineProperty(exports, "syncRetiredKeys", { enumerable: true, get: function () { return retiredKeys_1.syncRetiredKeys; } });
 Object.defineProperty(exports, "retiredKeyFromPhrase", { enumerable: true, get: function () { return retiredKeys_1.retiredKeyFromPhrase; } });
+Object.defineProperty(exports, "retiredKeyFromPrivateKey", { enumerable: true, get: function () { return retiredKeys_1.retiredKeyFromPrivateKey; } });
+Object.defineProperty(exports, "exportRetiredIdentityKeys", { enumerable: true, get: function () { return retiredKeys_1.exportRetiredIdentityKeys; } });
+Object.defineProperty(exports, "claimRetiredIdentityKeys", { enumerable: true, get: function () { return retiredKeys_1.claimRetiredIdentityKeys; } });
+Object.defineProperty(exports, "countQuarantinedRetiredKeys", { enumerable: true, get: function () { return retiredKeys_1.countQuarantinedRetiredKeys; } });
+Object.defineProperty(exports, "unmirrorPersonalRetiredKeys", { enumerable: true, get: function () { return retiredKeys_1.unmirrorPersonalRetiredKeys; } });
+Object.defineProperty(exports, "RetiredKeyRingUnreadableError", { enumerable: true, get: function () { return retiredKeys_1.RetiredKeyRingUnreadableError; } });
 var signatureService_1 = require("./signatureService");
 Object.defineProperty(exports, "SignatureService", { enumerable: true, get: function () { return signatureService_1.SignatureService; } });
 var recoveryPhrase_1 = require("./recoveryPhrase");

package/dist/cjs/crypto/keyManager.js

@@ -211,9 +211,7 @@ async function loadRawSecureStore() {
 async function keychainItemStore(item) {
     const raw = await loadRawSecureStore();
     const access = await (0, keychainAccessGroups_1.resolveKeychainAccess)();
-    if (access.mode === 'grouped' && access.role === 'holder') {
-        await (0, keychainGroupMigration_1.ensureKeychainGroupsMigrated)();
-    }
+    await (0, keychainGroupMigration_1.prepareKeychainAccess)(access);
     return (0, keychainAccessGroups_1.groupedKeychainStore)(raw, access, item);
 }
 /** The store for the identity slots (primary, backup, legacy, phrase): Commons only on iOS. */
@@ -790,12 +788,30 @@ class KeyManager {
      * `signSocialReceive`) is fresh, so a cached key here would let a caller
      * compare a new seed against an old key.
      *
+     * iOS, in an app that holds the private key (Commons, the Peable wallet:
+     * keychain roles `holder` and `wallet`): DERIVED from the private key in the
+     * wallet group, never read from the public-key item, which sits in the shared
+     * group every Oxy app can write (R5-1); `null` when that app holds no private
+     * key. Every other iOS app reads the public-key item: it holds nothing it
+     * could derive from, and it never spends. Money code uses
+     * {@link getIdentityPublicKeyForMoney}.
+     *
      * @returns Shared public key or null if no shared identity exists
      */
     static async getSharedPublicKey() {
         if (isWebPlatform()) {
             return null;
         }
+        if ((0, platform_1.isIOS)() && (await KeyManager._holdsSpendingKeys())) {
+            // Not cached: a rotation in Commons changes it under the wallet.
+            try {
+                const privateKey = await KeyManager.getSharedPrivateKey();
+                return privateKey ? KeyManager.derivePublicKey(privateKey) : null;
+            }
+            catch {
+                return null;
+            }
+        }
         // Return cached value if available (iOS only; see above).
         if (!(0, platform_1.isAndroid)() && KeyManager.cachedSharedPublicKey !== null) {
             return KeyManager.cachedSharedPublicKey;
@@ -828,6 +844,68 @@ class KeyManager {
             return null;
         }
     }
+    /**
+     * Whether this iOS app holds spending keys (keychain role `holder` or
+     * `wallet`), so a public key it uses for money must be derived from them.
+     * Throws while the keychain cannot say. @internal
+     */
+    static async _holdsSpendingKeys() {
+        const access = await (0, keychainAccessGroups_1.resolveKeychainAccess)();
+        return access.mode === 'grouped' && access.role !== 'member';
+    }
+    /**
+     * THE public key of the identity a money holder (the Peable wallet, Commons)
+     * receives and spends with: the personal key, or with `opts.accountId` that
+     * organization's (ADR 0061 D6). It is the public half of exactly the private
+     * key {@link deriveScopedSeed} and {@link signSocialReceive} use, so an
+     * address shown from it is one this app can spend (R5-1).
+     *
+     * - iOS (Commons, the Peable wallet): DERIVED from the private key in the
+     *   restricted keychain groups (personal: the wallet group's slot, then
+     *   Commons' primary; organization: its pair). Never the shared group's
+     *   public-key item, which every Oxy app can write. `null` when no private
+     *   key is held, and in every other iOS app.
+     * - Android: inside Commons derived from its own key; elsewhere Commons'
+     *   identity host (`describe`), which answers from Commons' own signer
+     *   store over signature-protected IPC.
+     * - Web: `null`.
+     *
+     * Compare the answer with the account's published `#key-1` before showing a
+     * receive address (Peable ADR 0002). Lowercase uncompressed (`04…`).
+     */
+    static async getIdentityPublicKeyForMoney(opts) {
+        if (isWebPlatform()) {
+            return null;
+        }
+        const accountId = opts?.accountId;
+        if (accountId !== undefined) {
+            if (!(0, organizationKeys_1.isOrganizationAccountId)(accountId))
+                return null;
+            if ((0, platform_1.isAndroid)() && !KeyManager.identitySignerStore) {
+                const bridge = await (0, protocol_1.loadCommonsIdentityBridge)();
+                const description = (await bridge?.describe(accountId)) ?? null;
+                return description?.accountId === accountId && description.publicKey
+                    ? KeyManager.canonicalPublicKey(description.publicKey)
+                    : null;
+            }
+            const organizationKey = await (0, organizationKeys_1.getOrganizationPrivateKey)(accountId);
+            return organizationKey ? KeyManager.derivePublicKey(organizationKey) : null;
+        }
+        if ((0, platform_1.isAndroid)()) {
+            if (KeyManager.identitySignerStore) {
+                const local = await KeyManager.getPrivateKey();
+                return local ? KeyManager.derivePublicKey(local) : null;
+            }
+            const bridge = await (0, protocol_1.loadCommonsIdentityBridge)();
+            const publicKey = (await bridge?.describe())?.publicKey ?? null;
+            return publicKey ? KeyManager.canonicalPublicKey(publicKey) : null;
+        }
+        if (!(0, platform_1.isIOS)()) {
+            return null;
+        }
+        const privateKey = (await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey());
+        return privateKey ? KeyManager.derivePublicKey(privateKey) : null;
+    }
     /**
      * The shared private key, where this app may hold it: iOS only.
      *
@@ -2089,21 +2167,28 @@ 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 (0, retiredKeys_1.forgetRetiredIdentityKeys)();
-            }
-            catch (error) {
-                logger_1.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.
+            // Every personal entry is bound to its owner's account id (R5-2), so the
+            // same person signing in again finds it, and a different person on this
+            // phone never lists, derives from or signs with it. Only deleting the Oxy
+            // ACCOUNT clears it, explicitly (`forgetRetiredIdentityKeys`).
         }
         // 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
         // launch. Best-effort, like the other recovery sources.
         await KeyManager._clearDeviceBackup();
         // Same for the Android signer store: Commons' identity host must stop
-        // answering for a deleted identity, forced or not.
+        // answering for a deleted identity, forced or not — its personal retired
+        // keys included (R5-2): they stay in Commons' own ring, bound to their
+        // owner, but the host must not hand them to the next person on the phone.
         await KeyManager._clearIdentitySigner();
+        try {
+            await (0, retiredKeys_1.unmirrorPersonalRetiredKeys)();
+        }
+        catch (error) {
+            logger_1.logger.warn('Failed to withdraw the personal retired keys from the identity host', { component: 'KeyManager' }, error);
+        }
         // Clear the marker AFTER key deletion succeeds — a marker must never outlive
         // its identity (a leftover marker would route a truly-absent device to
         // `recovery` instead of `welcome`).
@@ -2632,11 +2717,16 @@ class KeyManager {
      * (personal, or `accountId`'s) whose public key it names: the current key
      * when it matches, else a RETIRED key Commons kept after a rotation or
      * replacement (`./retiredKeys`, ADR 0061 D7 as amended). Spending only: a
-     * retired key never signs in. Never falls back to another key.
+     * retired key never signs in. Never falls back to another key. A PERSONAL
+     * retired key is reached only with `opts.ownerAccountId`, the signed-in
+     * person's account id, and only when the ring keeps it for that account
+     * (R5-2); on Android outside Commons the identity host holds only the
+     * personal keys of the person Commons is signed in as.
      *
      * @param info Context/domain-binding label (distinct labels → independent seeds).
      * @param opts.accountId An organization's account id, for its key.
      * @param opts.publicKey Selects one key of that account by its public key.
+     * @param opts.ownerAccountId The person's account id, for a personal retired key.
      * @returns 32 bytes of derived keying material, or `null` on web / when no
      *          identity key is available to this app.
      */
@@ -2653,7 +2743,7 @@ class KeyManager {
                 const seed = (await bridge?.deriveRetiredScopedSeed?.(info, selected, opts.accountId)) ?? null;
                 return seed ? hexToBytes(seed) : null;
             }
-            const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+            const selected = await KeyManager._selectedPrivateKey({ ...opts, publicKey: opts.publicKey });
             return selected ? (0, identityDerivations_1.deriveScopedSeedFromKey)(selected, info) : null;
         }
         if (opts?.accountId !== undefined) {
@@ -2721,7 +2811,7 @@ class KeyManager {
                 return ((await bridge?.signRetiredSocialReceive?.(index, digest, selected, opts.accountId)) ??
                     null);
             }
-            const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+            const selected = await KeyManager._selectedPrivateKey({ ...opts, publicKey: opts.publicKey });
             return selected ? (0, identityDerivations_1.signSocialReceiveDigest)(selected, index, digest) : null;
         }
         const accountId = opts?.accountId;
@@ -2760,7 +2850,8 @@ class KeyManager {
     static _selectorKey(publicKey) {
         return KeyManager.isValidPublicKey(publicKey) ? KeyManager.canonicalPublicKey(publicKey) : null;
     }
-    static async _selectedPrivateKey(publicKey, accountId) {
+    static async _selectedPrivateKey(opts) {
+        const { publicKey, accountId, ownerAccountId } = opts;
         if ((0, retiredKeys_1.retiredKeyScope)({ accountId }) === null || !KeyManager.isValidPublicKey(publicKey)) {
             return null;
         }
@@ -2773,7 +2864,11 @@ class KeyManager {
         if (current && KeyManager.canonicalPublicKey(KeyManager.derivePublicKey(current)) === wanted) {
             return current;
         }
-        return (0, retiredKeys_1.getRetiredPrivateKey)(wanted, accountId !== undefined ? { accountId } : undefined);
+        return (0, retiredKeys_1.getRetiredPrivateKey)(wanted, accountId !== undefined
+            ? { accountId }
+            : ownerAccountId !== undefined
+                ? { ownerAccountId }
+                : undefined);
     }
     /**
      * Get a shortened version of the public key for display