@oxy.so/core 7.28.0 → 7.30.0

package/dist/cjs/api/identity.js

@@ -56,6 +56,7 @@ exports.signOwnChainRecord = signOwnChainRecord;
  * AEAD, signatures) load on first use, never with the client itself.
  */
 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");
 /** Short-TTL read cache for public identity reads. */
@@ -196,7 +197,7 @@ class IdentityApi {
         if (!userId) {
             throw new Error('No authenticated user — sign in before rotating your key.');
         }
-        const { KeyManager, RecoveryPhraseService, SignatureService, signMessage } = await Promise.resolve().then(() => __importStar(require('../crypto/index')));
+        const { KeyManager, RecoveryPhraseService, SignatureService, signMessage, retireIdentityKey } = await Promise.resolve().then(() => __importStar(require('../crypto/index')));
         // 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 RecoveryPhraseService.derivePendingIdentity());
@@ -204,6 +205,7 @@ class IdentityApi {
         // 2. Resolve the OLD signing capability from the chosen proof mode.
         let oldPublicKey;
         let signWithOldKey;
+        let oldPrivateKeyForRing;
         if (options.proof === 'phrase') {
             const phrase = options.phrase?.trim();
             if (!phrase) {
@@ -212,6 +214,7 @@ class IdentityApi {
             const oldPrivateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(phrase);
             oldPublicKey = KeyManager.derivePublicKey(oldPrivateKey);
             signWithOldKey = (message) => signMessage(message, oldPrivateKey);
+            oldPrivateKeyForRing = oldPrivateKey;
         }
         else {
             const currentPublicKey = await KeyManager.getPublicKey();
@@ -220,6 +223,25 @@ class IdentityApi {
             }
             oldPublicKey = currentPublicKey;
             signWithOldKey = (message) => SignatureService.sign(message);
+            oldPrivateKeyForRing = (0, platform_1.isWeb)() ? null : await KeyManager.getPrivateKey();
+        }
+        // 2b. Keep the key being replaced in the retired ring BEFORE anything
+        //     changes (oxy ADR 0061 D7 as amended, Peable ADR 0002): coins keep
+        //     arriving under it after the swap, and the Peable wallet spends them
+        //     through the `publicKey` selector of `deriveScopedSeed` /
+        //     `signSocialReceive`. A device that cannot keep it does not rotate:
+        //     the phrase would become the only way to those coins. Native only —
+        //     on web no key is stored. Idempotent, so a retried rotation is fine.
+        if (!(0, platform_1.isWeb)()) {
+            try {
+                if (!oldPrivateKeyForRing)
+                    throw new Error('no readable private key');
+                await retireIdentityKey({ privateKey: oldPrivateKeyForRing, publicKey: oldPublicKey });
+            }
+            catch (retainError) {
+                logger_1.logger.warn('Could not keep the current key as a retired key; not rotating.', { component: 'oxy.identity', method: 'rotateKey' }, retainError);
+                throw new Error('Your current key could not be kept on this device, so it was not rotated. Nothing changed.');
+            }
         }
         // 3. Request a single-use rotate_key challenge (bearer).
         const { challenge } = await this.ctx.request('POST', '/auth/rotate/challenge', undefined, {
@@ -376,6 +398,23 @@ class IdentityApi {
             keys.push(`GET:/u/${encodeURIComponent(userId)}/did.json`);
         this.ctx.http.invalidateCache({ keys, prefixes: ['GET:/users/me'] });
     }
+    /**
+     * The signed-in personal account's current root (`null` without one) and
+     * every root a rotation replaced, oldest first, all canonical (uncompressed,
+     * lowercase). Commons reads it to accept a previous recovery phrase only when
+     * it derives a key that WAS this account's root. A retired root is never any
+     * account's again. First-party only; a non-personal account is refused
+     * (`IDENTITY_NOT_PERSONAL_ACCOUNT`).
+     */
+    async keyHistory() {
+        const res = await this.ctx.request('GET', '/identity/key-history', undefined, {
+            cache: false,
+        });
+        const parsed = (0, client_1.checkContract)(client_2.identityKeyHistoryCheck, res);
+        if (!parsed)
+            throw new Error('identity/key-history returned an unexpected response shape');
+        return parsed;
+    }
 }
 exports.IdentityApi = IdentityApi;
 /** `oxy.identity.links` — joining Commons' root to an account (ADR 0029 D3). */

package/dist/cjs/crypto/index.js

@@ -12,7 +12,8 @@
  * common chunk, which is the cost the lazy loading exists to avoid.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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 = exports.hkdfSha256 = exports.BACKUP_KDF_ENCRYPTION_INFO = exports.RecoveryPhraseService = exports.SignatureService = 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.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;
 // MUST stay the first import: the shim has to exist before any module below
 // evaluates or draws randomness (see `./polyfill`).
 require("./polyfill");
@@ -37,6 +38,32 @@ Object.defineProperty(exports, "deleteOrganizationKey", { enumerable: true, get:
 Object.defineProperty(exports, "syncOrganizationKeys", { enumerable: true, get: function () { return organizationKeys_1.syncOrganizationKeys; } });
 Object.defineProperty(exports, "isOrganizationAccountId", { enumerable: true, get: function () { return organizationKeys_1.isOrganizationAccountId; } });
 Object.defineProperty(exports, "isHealthyOrganizationKeyPair", { enumerable: true, get: function () { return organizationKeys_1.isHealthyOrganizationKeyPair; } });
+// iOS keychain access groups (docs/identity/ios-keychain-access-groups.md, ADR 0062)
+var keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
+Object.defineProperty(exports, "KEYCHAIN_ACCESS_GROUPS", { enumerable: true, get: function () { return keychainAccessGroups_1.KEYCHAIN_ACCESS_GROUPS; } });
+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, "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; } });
+Object.defineProperty(exports, "keychainDeletePlan", { enumerable: true, get: function () { return keychainAccessGroups_1.keychainDeletePlan; } });
+Object.defineProperty(exports, "keychainWriteOption", { enumerable: true, get: function () { return keychainAccessGroups_1.keychainWriteOption; } });
+Object.defineProperty(exports, "ownKeychainItemPlan", { enumerable: true, get: function () { return keychainAccessGroups_1.ownKeychainItemPlan; } });
+Object.defineProperty(exports, "readThroughPlan", { enumerable: true, get: function () { return keychainAccessGroups_1.readThroughPlan; } });
+Object.defineProperty(exports, "deleteThroughPlan", { enumerable: true, get: function () { return keychainAccessGroups_1.deleteThroughPlan; } });
+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; } });
+// 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");
+Object.defineProperty(exports, "retireIdentityKey", { enumerable: true, get: function () { return retiredKeys_1.retireIdentityKey; } });
+Object.defineProperty(exports, "listRetiredIdentityKeys", { enumerable: true, get: function () { return retiredKeys_1.listRetiredIdentityKeys; } });
+Object.defineProperty(exports, "forgetRetiredIdentityKey", { enumerable: true, get: function () { return retiredKeys_1.forgetRetiredIdentityKey; } });
+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; } });
 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

@@ -47,6 +47,10 @@ const logger_1 = require("../logger");
 const identityDerivations_1 = require("./identityDerivations");
 const identitySigner_1 = require("./identitySigner");
 const organizationKeys_1 = require("./organizationKeys");
+const retiredKeys_1 = require("./retiredKeys");
+const keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
+const keychainGroupMigration_1 = require("./keychainGroupMigration");
+const keychainItems_1 = require("./keychainItems");
 const identityMarker_1 = require("./identityMarker");
 const deviceBackup_1 = require("./deviceBackup");
 /**
@@ -107,16 +111,6 @@ class IdentityUnavailableError extends Error {
     }
 }
 exports.IdentityUnavailableError = IdentityUnavailableError;
-const STORAGE_KEYS = {
-    PRIVATE_KEY: 'oxy_identity_private_key',
-    PUBLIC_KEY: 'oxy_identity_public_key',
-    BACKUP_PRIVATE_KEY: 'oxy_identity_backup_private_key',
-    BACKUP_PUBLIC_KEY: 'oxy_identity_backup_public_key',
-    BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp',
-    // The cross-app identity in the iOS keychain access group (iOS only).
-    SHARED_PRIVATE_KEY: 'oxy_shared_identity_private_key',
-    SHARED_PUBLIC_KEY: 'oxy_shared_identity_public_key',
-};
 /**
  * v2 identity slot layout — blast-radius isolation.
  *
@@ -132,15 +126,8 @@ const STORAGE_KEYS = {
  * Migration from the legacy layout is lazy + verify-before-delete — see
  * {@link KeyManager._runSlotMigration}.
  */
-const V2_PRIMARY_KEYCHAIN_SERVICE = 'oxy_identity';
-const V2_BACKUP_KEYCHAIN_SERVICE = 'oxy_identity_backup';
-const V2_STORAGE_KEYS = {
-    PRIVATE_KEY: 'oxy_identity_private_key_v2',
-    PUBLIC_KEY: 'oxy_identity_public_key_v2',
-    BACKUP_PRIVATE_KEY: 'oxy_identity_backup_private_key_v2',
-    BACKUP_PUBLIC_KEY: 'oxy_identity_backup_public_key_v2',
-    BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp_v2',
-};
+// The names (V2_PRIMARY_KEYCHAIN_SERVICE, V2_BACKUP_KEYCHAIN_SERVICE,
+// V2_STORAGE_KEYS) live in `./keychainItems`, beside every other identity item.
 /**
  * Dedicated keychain slot for the recovery mnemonic (the 12-word phrase).
  *
@@ -157,8 +144,7 @@ const V2_STORAGE_KEYS = {
  * 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';
+// RECOVERY_MNEMONIC_KEYCHAIN_SERVICE / RECOVERY_MNEMONIC_STORAGE_KEY: `./keychainItems`.
 /**
  * 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
@@ -176,29 +162,23 @@ const SLOTS_MIGRATED_FLAG_KEY = 'oxy_identity_slots_migrated_v2';
  */
 const ROTATION_PENDING_KEY = 'oxy_identity_rotation_pending_v1';
 const V2_SLOT_LAYOUT = {
-    primaryService: V2_PRIMARY_KEYCHAIN_SERVICE,
-    primaryPrivateKeyName: V2_STORAGE_KEYS.PRIVATE_KEY,
-    primaryPublicKeyName: V2_STORAGE_KEYS.PUBLIC_KEY,
-    backupService: V2_BACKUP_KEYCHAIN_SERVICE,
-    backupPrivateKeyName: V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY,
-    backupPublicKeyName: V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY,
-    backupTimestampName: V2_STORAGE_KEYS.BACKUP_TIMESTAMP,
+    primaryService: keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE,
+    primaryPrivateKeyName: keychainItems_1.V2_STORAGE_KEYS.PRIVATE_KEY,
+    primaryPublicKeyName: keychainItems_1.V2_STORAGE_KEYS.PUBLIC_KEY,
+    backupService: keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE,
+    backupPrivateKeyName: keychainItems_1.V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY,
+    backupPublicKeyName: keychainItems_1.V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY,
+    backupTimestampName: keychainItems_1.V2_STORAGE_KEYS.BACKUP_TIMESTAMP,
 };
 const LEGACY_SLOT_LAYOUT = {
     primaryService: undefined,
-    primaryPrivateKeyName: STORAGE_KEYS.PRIVATE_KEY,
-    primaryPublicKeyName: STORAGE_KEYS.PUBLIC_KEY,
+    primaryPrivateKeyName: keychainItems_1.STORAGE_KEYS.PRIVATE_KEY,
+    primaryPublicKeyName: keychainItems_1.STORAGE_KEYS.PUBLIC_KEY,
     backupService: undefined,
-    backupPrivateKeyName: STORAGE_KEYS.BACKUP_PRIVATE_KEY,
-    backupPublicKeyName: STORAGE_KEYS.BACKUP_PUBLIC_KEY,
-    backupTimestampName: STORAGE_KEYS.BACKUP_TIMESTAMP,
+    backupPrivateKeyName: keychainItems_1.STORAGE_KEYS.BACKUP_PRIVATE_KEY,
+    backupPublicKeyName: keychainItems_1.STORAGE_KEYS.BACKUP_PUBLIC_KEY,
+    backupTimestampName: keychainItems_1.STORAGE_KEYS.BACKUP_TIMESTAMP,
 };
-/**
- * iOS Keychain Access Group for sharing identities across Oxy apps
- * All Oxy apps must have this access group enabled in their entitlements
- * Format: [Team ID].so.oxy.shared or group.so.oxy.shared
- */
-const IOS_KEYCHAIN_GROUP = 'group.so.oxy.shared';
 /**
  * Initialize React Native specific modules
  *
@@ -208,7 +188,7 @@ const IOS_KEYCHAIN_GROUP = 'group.so.oxy.shared';
  * `expo-secure-store`; off RN it throws (and is never called because every
  * caller is gated by `isWebPlatform()` / native-only paths).
  */
-async function initSecureStore() {
+async function loadRawSecureStore() {
     try {
         return await (0, protocol_1.loadSecureStore)();
     }
@@ -217,6 +197,29 @@ async function initSecureStore() {
         throw new Error(`Failed to load expo-secure-store: ${errorMessage}. Make sure expo-secure-store is installed and properly configured.`);
     }
 }
+/**
+ * The secure store routed to the keychain group of `item`
+ * (`../utils/keychainAccessGroups`): on iOS reads walk the item's group then
+ * the pre-split shared group, writes carry the item's group and THROW in an app
+ * that may not hold it, and in Commons every access first awaits the
+ * access-group migration. Android and web are unchanged (`ungrouped`).
+ *
+ * Throws when the store cannot load or the keychain cannot say which groups
+ * this app holds; every caller already treats a throw here as "storage
+ * unavailable".
+ */
+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)();
+    }
+    return (0, keychainAccessGroups_1.groupedKeychainStore)(raw, access, item);
+}
+/** The store for the identity slots (primary, backup, legacy, phrase): Commons only on iOS. */
+function initSecureStore() {
+    return keychainItemStore('identity-secret');
+}
 /**
  * Check if we're on web platform
  * Identity storage is only available on native platforms (iOS/Android)
@@ -466,8 +469,8 @@ class KeyManager {
         let v2Private;
         let v2Public;
         try {
-            v2Private = await store.getItemAsync(V2_STORAGE_KEYS.PRIVATE_KEY, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
-            v2Public = await store.getItemAsync(V2_STORAGE_KEYS.PUBLIC_KEY, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
+            v2Private = await store.getItemAsync(keychainItems_1.V2_STORAGE_KEYS.PRIVATE_KEY, KeyManager._slotOpts(keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE));
+            v2Public = await store.getItemAsync(keychainItems_1.V2_STORAGE_KEYS.PUBLIC_KEY, KeyManager._slotOpts(keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE));
         }
         catch (error) {
             return { mode: 'deferred', cause: error };
@@ -490,8 +493,8 @@ class KeyManager {
         let legacyPrivate;
         let legacyPublic;
         try {
-            legacyPrivate = await store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
-            legacyPublic = await store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+            legacyPrivate = await store.getItemAsync(keychainItems_1.STORAGE_KEYS.PRIVATE_KEY);
+            legacyPublic = await store.getItemAsync(keychainItems_1.STORAGE_KEYS.PUBLIC_KEY);
         }
         catch (error) {
             return { mode: 'deferred', cause: error };
@@ -505,10 +508,10 @@ class KeyManager {
         const canonicalPrivate = KeyManager.canonicalPrivateKey(legacyPrivate);
         const canonicalPublic = legacyPublic.toLowerCase();
         try {
-            await store.setItemAsync(V2_STORAGE_KEYS.PUBLIC_KEY, canonicalPublic, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
-            await store.setItemAsync(V2_STORAGE_KEYS.PRIVATE_KEY, canonicalPrivate, KeyManager._privateWriteOpts(store, V2_PRIMARY_KEYCHAIN_SERVICE));
-            const readBackPrivate = await store.getItemAsync(V2_STORAGE_KEYS.PRIVATE_KEY, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
-            const readBackPublic = await store.getItemAsync(V2_STORAGE_KEYS.PUBLIC_KEY, KeyManager._slotOpts(V2_PRIMARY_KEYCHAIN_SERVICE));
+            await store.setItemAsync(keychainItems_1.V2_STORAGE_KEYS.PUBLIC_KEY, canonicalPublic, KeyManager._slotOpts(keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE));
+            await store.setItemAsync(keychainItems_1.V2_STORAGE_KEYS.PRIVATE_KEY, canonicalPrivate, KeyManager._privateWriteOpts(store, keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE));
+            const readBackPrivate = await store.getItemAsync(keychainItems_1.V2_STORAGE_KEYS.PRIVATE_KEY, KeyManager._slotOpts(keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE));
+            const readBackPublic = await store.getItemAsync(keychainItems_1.V2_STORAGE_KEYS.PUBLIC_KEY, KeyManager._slotOpts(keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE));
             const verified = readBackPrivate?.toLowerCase() === canonicalPrivate &&
                 readBackPublic?.toLowerCase() === canonicalPublic &&
                 KeyManager._isHealthyPair(readBackPrivate, readBackPublic);
@@ -543,8 +546,8 @@ class KeyManager {
             let backupPrivate = null;
             let backupPublic = null;
             try {
-                backupPrivate = await store.getItemAsync(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
-                backupPublic = await store.getItemAsync(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+                backupPrivate = await store.getItemAsync(keychainItems_1.STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+                backupPublic = await store.getItemAsync(keychainItems_1.STORAGE_KEYS.BACKUP_PUBLIC_KEY);
             }
             catch (error) {
                 if ((0, logger_1.isDev)()) {
@@ -563,9 +566,9 @@ class KeyManager {
                 seedPrivate = primaryPrivate;
                 seedPublic = primaryPublic;
             }
-            await store.setItemAsync(V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY, seedPublic, KeyManager._slotOpts(V2_BACKUP_KEYCHAIN_SERVICE));
-            await store.setItemAsync(V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY, seedPrivate, KeyManager._privateWriteOpts(store, V2_BACKUP_KEYCHAIN_SERVICE));
-            await store.setItemAsync(V2_STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString(), KeyManager._slotOpts(V2_BACKUP_KEYCHAIN_SERVICE));
+            await store.setItemAsync(keychainItems_1.V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY, seedPublic, KeyManager._slotOpts(keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE));
+            await store.setItemAsync(keychainItems_1.V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY, seedPrivate, KeyManager._privateWriteOpts(store, keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE));
+            await store.setItemAsync(keychainItems_1.V2_STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString(), KeyManager._slotOpts(keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE));
         }
         catch (error) {
             logger_1.logger.warn('Failed to migrate identity backup slot to v2 (non-fatal)', { component: 'KeyManager' }, error);
@@ -583,23 +586,23 @@ class KeyManager {
         }
     }
     static async _bestEffortDeleteV2Primary(store) {
-        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.PRIVATE_KEY, V2_PRIMARY_KEYCHAIN_SERVICE);
-        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.PUBLIC_KEY, V2_PRIMARY_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.V2_STORAGE_KEYS.PRIVATE_KEY, keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.V2_STORAGE_KEYS.PUBLIC_KEY, keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE);
     }
     static async _bestEffortDeleteLegacyPrimaryAndBackup(store) {
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PRIVATE_KEY);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PUBLIC_KEY);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_PRIVATE_KEY);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_PUBLIC_KEY);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_TIMESTAMP);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.PRIVATE_KEY);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.PUBLIC_KEY);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.BACKUP_TIMESTAMP);
     }
     static async _bestEffortDeleteBackupsAllGenerations(store) {
-        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY, V2_BACKUP_KEYCHAIN_SERVICE);
-        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY, V2_BACKUP_KEYCHAIN_SERVICE);
-        await KeyManager._bestEffortDelete(store, V2_STORAGE_KEYS.BACKUP_TIMESTAMP, V2_BACKUP_KEYCHAIN_SERVICE);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_PRIVATE_KEY);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_PUBLIC_KEY);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.BACKUP_TIMESTAMP);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY, keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY, keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.V2_STORAGE_KEYS.BACKUP_TIMESTAMP, keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.BACKUP_TIMESTAMP);
     }
     /**
      * Clear the iOS keychain-group copy of the identity (force-delete only) so a
@@ -607,12 +610,12 @@ class KeyManager {
      * rung. Best-effort — the shared slot is a redundant convenience copy. The
      * Android signer store is cleared on every delete, in {@link deleteIdentity}.
      */
-    static async _clearSharedSlot(store) {
+    static async _clearSharedSlot(_identityStore) {
         try {
             if ((0, platform_1.isIOS)()) {
-                const opts = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
-                await store.deleteItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, opts);
-                await store.deleteItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, opts);
+                // The shared slot lives in two groups of its own, not the identity slots'.
+                await (await keychainItemStore('spending-key')).deleteItemAsync(keychainItems_1.STORAGE_KEYS.SHARED_PRIVATE_KEY);
+                await (await keychainItemStore('shared')).deleteItemAsync(keychainItems_1.STORAGE_KEYS.SHARED_PUBLIC_KEY);
             }
             KeyManager.invalidateSharedCache();
         }
@@ -679,6 +682,20 @@ class KeyManager {
         KeyManager.cachedSharedPublicKey = null;
         KeyManager.cachedHasSharedIdentity = null;
     }
+    /**
+     * iOS: write the personal key's cross-app slot — the private key to the
+     * wallet group (Commons and the Peable wallet), the public key to the shared
+     * group (every Oxy app). Throws in any app that may not hold the private key.
+     * @internal
+     */
+    static async _writeIosSharedSlot(privateKey, publicKey) {
+        const privateStore = await keychainItemStore('spending-key');
+        const privateOpts = {
+            keychainAccessible: privateStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        };
+        await privateStore.setItemAsync(keychainItems_1.STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, privateOpts);
+        await (await keychainItemStore('shared')).setItemAsync(keychainItems_1.STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, {});
+    }
     /**
      * Lowercase and pad to canonical 64-hex-char form.
      *
@@ -714,8 +731,10 @@ class KeyManager {
     // ==================== SHARED IDENTITY METHODS ====================
     // One Oxy identity across every Oxy app on a device.
     //
-    // iOS: the keychain access group `group.so.oxy.shared`. Every Oxy app reads
-    //   the same keychain item, and no app can wipe another's keychain.
+    // iOS: keychain access groups (docs/identity/ios-keychain-access-groups.md).
+    //   The private key is in `<TEAM>.so.oxy.wallet` (Commons and the Peable
+    //   wallet only), the public key in `<TEAM>.group.so.oxy.shared`, which every
+    //   Oxy app reads. Every other app signs in through Commons (ADR 0029).
     // Android: every app has its own UID, so nothing is shared through storage.
     //   Commons is the ONLY holder of the private key. It keeps the identity
     //   signer store (`setIdentitySignerStore`) for its identity host, and every
@@ -740,21 +759,11 @@ class KeyManager {
         }
         const { privateKey, publicKey } = await KeyManager.generateKeyPair();
         if ((0, platform_1.isIOS)()) {
-            const store = await initSecureStore();
-            // Note: keychainAccessGroup requires Keychain Sharing capability in Xcode
             try {
-                const privateOpts = {
-                    keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-                    keychainAccessGroup: IOS_KEYCHAIN_GROUP, // Enables sharing across apps
-                };
-                await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, privateOpts);
-                const publicOpts = {
-                    keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-                };
-                await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, publicOpts);
+                await KeyManager._writeIosSharedSlot(privateKey, publicKey);
             }
             catch (error) {
-                throw new Error(`Failed to create shared identity on iOS. Ensure your app has the Keychain Sharing capability enabled with access group "${IOS_KEYCHAIN_GROUP}". Error: ${error}`);
+                throw new Error(`Failed to create shared identity on iOS. Only Commons may write it, with the keychain access groups of docs/identity/ios-keychain-access-groups.md. Error: ${error}`);
             }
         }
         else if ((0, platform_1.isAndroid)()) {
@@ -794,9 +803,8 @@ class KeyManager {
         try {
             let publicKey = null;
             if ((0, platform_1.isIOS)()) {
-                const store = await initSecureStore();
-                const opts = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
-                publicKey = await store.getItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, opts);
+                const store = await keychainItemStore('shared');
+                publicKey = await store.getItemAsync(keychainItems_1.STORAGE_KEYS.SHARED_PUBLIC_KEY, {});
             }
             else if ((0, platform_1.isAndroid)()) {
                 const signer = KeyManager.identitySignerStore;
@@ -836,9 +844,10 @@ class KeyManager {
             return null;
         }
         try {
-            const store = await initSecureStore();
-            const opts = { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
-            return await store.getItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, opts);
+            // The wallet group: Commons and the Peable wallet. Every other app's plan
+            // is empty, so this is `null` there without touching the keychain.
+            const store = await keychainItemStore('spending-key');
+            return await store.getItemAsync(keychainItems_1.STORAGE_KEYS.SHARED_PRIVATE_KEY, {});
         }
         catch (error) {
             if ((0, logger_1.isDev)()) {
@@ -932,16 +941,7 @@ class KeyManager {
         const canonicalPrivate = KeyManager.canonicalPrivateKey(privateKey);
         const publicKey = (0, secp256k1_1.deriveSecp256k1PublicKey)(canonicalPrivate);
         if ((0, platform_1.isIOS)()) {
-            const store = await initSecureStore();
-            const privateOpts = {
-                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-                keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-            };
-            await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, privateOpts);
-            const publicOpts = {
-                keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-            };
-            await store.setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, publicOpts);
+            await KeyManager._writeIosSharedSlot(canonicalPrivate, publicKey);
         }
         else if ((0, platform_1.isAndroid)()) {
             await KeyManager._writeIdentitySigner(canonicalPrivate, publicKey);
@@ -1778,7 +1778,7 @@ class KeyManager {
         }
         try {
             const store = await initSecureStore();
-            await store.setItemAsync(RECOVERY_MNEMONIC_STORAGE_KEY, mnemonic, KeyManager._privateWriteOpts(store, RECOVERY_MNEMONIC_KEYCHAIN_SERVICE));
+            await store.setItemAsync(keychainItems_1.RECOVERY_MNEMONIC_STORAGE_KEY, mnemonic, KeyManager._privateWriteOpts(store, keychainItems_1.RECOVERY_MNEMONIC_KEYCHAIN_SERVICE));
         }
         catch (error) {
             if ((0, logger_1.isDev)()) {
@@ -1813,7 +1813,7 @@ class KeyManager {
         }
         try {
             const store = await initSecureStore();
-            return await store.getItemAsync(RECOVERY_MNEMONIC_STORAGE_KEY, KeyManager._slotOpts(RECOVERY_MNEMONIC_KEYCHAIN_SERVICE));
+            return await store.getItemAsync(keychainItems_1.RECOVERY_MNEMONIC_STORAGE_KEY, KeyManager._slotOpts(keychainItems_1.RECOVERY_MNEMONIC_KEYCHAIN_SERVICE));
         }
         catch (error) {
             if ((0, logger_1.isDev)()) {
@@ -1859,7 +1859,7 @@ class KeyManager {
             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);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.RECOVERY_MNEMONIC_STORAGE_KEY, keychainItems_1.RECOVERY_MNEMONIC_KEYCHAIN_SERVICE);
     }
     /**
      * Check if a complete, parseable identity exists on this device.
@@ -2078,8 +2078,8 @@ class KeyManager {
             await store.deleteItemAsync(layout.primaryPublicKeyName, readOpts);
         }
         await KeyManager._bestEffortDeleteV2Primary(store);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PRIVATE_KEY);
-        await KeyManager._bestEffortDelete(store, STORAGE_KEYS.PUBLIC_KEY);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.STORAGE_KEYS.PRIVATE_KEY);
+        await KeyManager._bestEffortDelete(store, keychainItems_1.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).
@@ -2089,6 +2089,13 @@ 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 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
@@ -2606,7 +2613,8 @@ class KeyManager {
      * `HDKey.fromMasterSeed` and never touches the identity key.
      *
      * Key source (native only):
-     * - iOS: the shared identity in `group.so.oxy.shared`, then this device's
+     * - iOS: the shared slot's private key in the wallet keychain group (Commons
+     *   and the Peable wallet only; `null` in every other app), then this device's
      *   primary identity.
      * - Android: Commons (the one app with a signer store) uses its own primary
      *   identity; every other app asks Commons over IPC and never reads a local
@@ -2620,8 +2628,15 @@ class KeyManager {
      * keychain group, or Commons' identity host. It never falls back to the
      * personal key.
      *
+     * With `opts.publicKey` the seed is derived from the key of that account
+     * (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.
+     *
      * @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.
      * @returns 32 bytes of derived keying material, or `null` on web / when no
      *          identity key is available to this app.
      */
@@ -2629,6 +2644,18 @@ class KeyManager {
         if (isWebPlatform()) {
             return null;
         }
+        if (opts?.publicKey !== undefined) {
+            if ((0, platform_1.isAndroid)() && !KeyManager.identitySignerStore) {
+                const selected = KeyManager._selectorKey(opts.publicKey);
+                if (!selected)
+                    return null;
+                const bridge = await (0, protocol_1.loadCommonsIdentityBridge)();
+                const seed = (await bridge?.deriveRetiredScopedSeed?.(info, selected, opts.accountId)) ?? null;
+                return seed ? hexToBytes(seed) : null;
+            }
+            const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+            return selected ? (0, identityDerivations_1.deriveScopedSeedFromKey)(selected, info) : null;
+        }
         if (opts?.accountId !== undefined) {
             return KeyManager._deriveOrganizationScopedSeed(info, opts.accountId);
         }
@@ -2674,7 +2701,8 @@ class KeyManager {
      * compressed public key for the scriptSig.
      *
      * Key source: as {@link deriveScopedSeed}, including `opts.accountId` for an
-     * organization's key (ADR 0061 D6). On Android outside Commons the signature
+     * organization's key (ADR 0061 D6) and `opts.publicKey` for one key of the
+     * account, current or retired. On Android outside Commons the signature
      * comes from Commons, which allows it for the wallet app only.
      *
      * @returns the signature, or `null` on web / when no identity key is
@@ -2684,6 +2712,18 @@ class KeyManager {
         if (isWebPlatform()) {
             return null;
         }
+        if (opts?.publicKey !== undefined) {
+            if ((0, platform_1.isAndroid)() && !KeyManager.identitySignerStore) {
+                const selected = KeyManager._selectorKey(opts.publicKey);
+                if (!selected)
+                    return null;
+                const bridge = await (0, protocol_1.loadCommonsIdentityBridge)();
+                return ((await bridge?.signRetiredSocialReceive?.(index, digest, selected, opts.accountId)) ??
+                    null);
+            }
+            const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+            return selected ? (0, identityDerivations_1.signSocialReceiveDigest)(selected, index, digest) : null;
+        }
         const accountId = opts?.accountId;
         if (accountId !== undefined) {
             // An organization key (ADR 0061 D6); never the personal one in its place.
@@ -2707,6 +2747,34 @@ class KeyManager {
             : ((await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey()));
         return local ? (0, identityDerivations_1.signSocialReceiveDigest)(local, index, digest) : null;
     }
+    /**
+     * The private key of the account (personal, or `accountId`'s organization)
+     * whose public key is `publicKey`, from this app's own storage: the current
+     * key when it matches, else the retired ring. iOS and Commons only; `null`
+     * for a key this device does not hold. Never another key in its place. @internal
+     */
+    /**
+     * The selector in the identity host's encoding (lowercase uncompressed), so a
+     * compressed `#key-1` from a DID or a gateway row selects the same key. @internal
+     */
+    static _selectorKey(publicKey) {
+        return KeyManager.isValidPublicKey(publicKey) ? KeyManager.canonicalPublicKey(publicKey) : null;
+    }
+    static async _selectedPrivateKey(publicKey, accountId) {
+        if ((0, retiredKeys_1.retiredKeyScope)({ accountId }) === null || !KeyManager.isValidPublicKey(publicKey)) {
+            return null;
+        }
+        const wanted = KeyManager.canonicalPublicKey(publicKey);
+        const current = accountId !== undefined
+            ? await (0, organizationKeys_1.getOrganizationPrivateKey)(accountId)
+            : (0, platform_1.isAndroid)()
+                ? await KeyManager.getPrivateKey()
+                : ((await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey()));
+        if (current && KeyManager.canonicalPublicKey(KeyManager.derivePublicKey(current)) === wanted) {
+            return current;
+        }
+        return (0, retiredKeys_1.getRetiredPrivateKey)(wanted, accountId !== undefined ? { accountId } : undefined);
+    }
     /**
      * Get a shortened version of the public key for display
      * Format: first 8 chars...last 8 chars