@oxy.so/core 7.28.0 → 7.29.0

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.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.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 = 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,23 @@ 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; } });
 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,9 @@ const logger_1 = require("../logger");
 const identityDerivations_1 = require("./identityDerivations");
 const identitySigner_1 = require("./identitySigner");
 const organizationKeys_1 = require("./organizationKeys");
+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 +110,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 +125,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 +143,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 +161,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 +187,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 +196,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 +468,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 +492,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 +507,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 +545,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 +565,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 +585,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 +609,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 +681,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 +730,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 +758,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 +802,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 +843,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 +940,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 +1777,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 +1812,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 +1858,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 +2077,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).
@@ -2606,7 +2605,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