@oxy.so/core 7.28.0 → 7.29.0

package/dist/esm/crypto/keyManager.js

@@ -11,6 +11,9 @@ import { isDev, logger } from '../logger/index.js';
 import { deriveScopedSeedFromKey, signSocialReceiveDigest } from './identityDerivations.js';
 import { registerIdentitySignerStore } from './identitySigner.js';
 import { getOrganizationPrivateKey, isOrganizationAccountId } from './organizationKeys.js';
+import { groupedKeychainStore, resolveKeychainAccess, } from '../utils/keychainAccessGroups.js';
+import { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
+import { RECOVERY_MNEMONIC_KEYCHAIN_SERVICE, RECOVERY_MNEMONIC_STORAGE_KEY, STORAGE_KEYS, V2_BACKUP_KEYCHAIN_SERVICE, V2_PRIMARY_KEYCHAIN_SERVICE, V2_STORAGE_KEYS, } from './keychainItems.js';
 import { clearIdentityMarker, readIdentityMarker, updateIdentityMarker, writeIdentityMarker, } from './identityMarker.js';
 import { DEVICE_BACKUP_VERSION, parseDeviceBackup, serializeDeviceBackup, } from './deviceBackup.js';
 /**
@@ -68,16 +71,6 @@ export class IdentityUnavailableError extends Error {
         this.name = '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.
  *
@@ -93,15 +86,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).
  *
@@ -118,8 +104,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
@@ -154,12 +139,6 @@ const LEGACY_SLOT_LAYOUT = {
     backupPublicKeyName: STORAGE_KEYS.BACKUP_PUBLIC_KEY,
     backupTimestampName: 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
  *
@@ -169,7 +148,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 loadSecureStore();
     }
@@ -178,6 +157,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 resolveKeychainAccess();
+    if (access.mode === 'grouped' && access.role === 'holder') {
+        await ensureKeychainGroupsMigrated();
+    }
+    return 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)
@@ -568,12 +570,12 @@ export 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 (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(STORAGE_KEYS.SHARED_PRIVATE_KEY);
+                await (await keychainItemStore('shared')).deleteItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY);
             }
             KeyManager.invalidateSharedCache();
         }
@@ -640,6 +642,20 @@ export 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(STORAGE_KEYS.SHARED_PRIVATE_KEY, privateKey, privateOpts);
+        await (await keychainItemStore('shared')).setItemAsync(STORAGE_KEYS.SHARED_PUBLIC_KEY, publicKey, {});
+    }
     /**
      * Lowercase and pad to canonical 64-hex-char form.
      *
@@ -675,8 +691,10 @@ export 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
@@ -701,21 +719,11 @@ export class KeyManager {
         }
         const { privateKey, publicKey } = await KeyManager.generateKeyPair();
         if (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 (isAndroid()) {
@@ -755,9 +763,8 @@ export class KeyManager {
         try {
             let publicKey = null;
             if (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(STORAGE_KEYS.SHARED_PUBLIC_KEY, {});
             }
             else if (isAndroid()) {
                 const signer = KeyManager.identitySignerStore;
@@ -797,9 +804,10 @@ export 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(STORAGE_KEYS.SHARED_PRIVATE_KEY, {});
         }
         catch (error) {
             if (isDev()) {
@@ -893,16 +901,7 @@ export class KeyManager {
         const canonicalPrivate = KeyManager.canonicalPrivateKey(privateKey);
         const publicKey = deriveSecp256k1PublicKey(canonicalPrivate);
         if (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 (isAndroid()) {
             await KeyManager._writeIdentitySigner(canonicalPrivate, publicKey);
@@ -2567,7 +2566,8 @@ export 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

package/dist/esm/crypto/keychainGroupMigration.js

@@ -0,0 +1,348 @@
+/**
+ * Commons, iOS: move every identity item out of the shared keychain group
+ * into the group it belongs to (docs/identity/ios-keychain-access-groups.md
+ * "Migrating existing items", ADR 0062).
+ *
+ * Before the split Commons listed one access group, the shared one, so every
+ * item it wrote landed there — the root key, both phrases, organization keys.
+ * Each item is moved by VERIFY-BEFORE-DELETE:
+ *
+ *   1. read it from the shared group (an explicit `accessGroup`);
+ *   2. write it to its new group;
+ *   3. read it back from there and check it: a pair must be healthy (the
+ *      public key derives from the private one), any value byte-identical;
+ *   4. only then delete it from the shared group.
+ *
+ * INVARIANT: at every instant each item has at least one readable copy, and a
+ * copy is never overwritten with a different value. A failure at any step
+ * leaves the shared copy where it is; the next run (the next accessor call
+ * for a thrown read, the next launch otherwise) resumes from whatever state
+ * the last one reached:
+ *
+ * - shared only            → copy, verify, delete;
+ * - shared and new, equal  → (a crash after the copy) verify, delete;
+ * - new only               → done;
+ * - shared and new DIFFER  → `conflict`: both stay. The new group was written
+ *   after the split, so it is current, but the shared copy may be a replaced
+ *   key that still receives money, and no step here may destroy one.
+ * - a pair that is not healthy → `unhealthy`: left in place, never moved.
+ *
+ * Every read the rest of the SDK makes goes through `keychainReadPlan` (its
+ * group, then the shared group), so it finds an item wherever this run left it.
+ * `ensureKeychainGroupsMigrated` is awaited by every KeyManager and
+ * organization-key storage access in Commons, so no write of theirs can
+ * interleave with a copy here (a copy racing a rotation could otherwise put
+ * the replaced key back).
+ *
+ * Nothing is logged but item labels and outcomes; never a value.
+ */
+import { deriveSecp256k1PublicKey, normalizeSecp256k1PrivateKey, normalizeSecp256k1PublicKey, } from '@oxy.so/protocol/secp256k1';
+import { loadSecureStore } from '@oxy.so/protocol';
+import { logger } from '../logger/index.js';
+import { keychainAccessGroupValue, keychainGroupFor, resolveKeychainAccess, } from '../utils/keychainAccessGroups.js';
+import { ORGANIZATION_INDEX_KEYCHAIN_SERVICE, ORGANIZATION_INDEX_STORAGE_KEY, ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE, RECOVERY_MNEMONIC_KEYCHAIN_SERVICE, RECOVERY_MNEMONIC_STORAGE_KEY, STORAGE_KEYS, V2_BACKUP_KEYCHAIN_SERVICE, V2_PRIMARY_KEYCHAIN_SERVICE, V2_STORAGE_KEYS, organizationMnemonicName, organizationPrivateKeyName, organizationPublicKeyName, parseOrganizationIndex, serializeOrganizationIndex, } from './keychainItems.js';
+const slot = (key, item, service, deviceOnly = true) => ({
+    key,
+    service,
+    group: keychainGroupFor(item),
+    deviceOnly,
+});
+function isHealthyPair(privateKey, publicKey) {
+    if (!privateKey || !publicKey)
+        return false;
+    try {
+        return (deriveSecp256k1PublicKey(normalizeSecp256k1PrivateKey(privateKey)) ===
+            normalizeSecp256k1PublicKey(publicKey));
+    }
+    catch {
+        return false;
+    }
+}
+class Deferred extends Error {
+}
+class Mover {
+    constructor(store, access) {
+        this.store = store;
+        this.access = access;
+    }
+    options(s, group, write = false) {
+        return {
+            ...(s.service ? { keychainService: s.service } : {}),
+            accessGroup: keychainAccessGroupValue(this.access, group),
+            ...(write && s.deviceOnly
+                ? { keychainAccessible: this.store.WHEN_UNLOCKED_THIS_DEVICE_ONLY }
+                : {}),
+        };
+    }
+    /** A read that throws means the keychain is unavailable: the whole run defers. */
+    async read(s, group) {
+        try {
+            return (await this.store.getItemAsync(s.key, this.options(s, group))) ?? null;
+        }
+        catch (error) {
+            throw new Deferred(error instanceof Error ? error.message : 'keychain read threw');
+        }
+    }
+    /**
+     * Write `value` where the new group had nothing, then read it back; `true`
+     * only when the new group holds exactly `value`. A copy that reads back as
+     * something else is removed again (best effort), because reads look in the
+     * new group FIRST and must not find it there.
+     */
+    async copy(s, value, replacing = false) {
+        try {
+            await this.store.setItemAsync(s.key, value, this.options(s, s.group, true));
+            if ((await this.store.getItemAsync(s.key, this.options(s, s.group))) === value) {
+                return true;
+            }
+        }
+        catch {
+            return false;
+        }
+        if (replacing) {
+            // A merge overwrote what was there; keep whatever is there now.
+            return false;
+        }
+        try {
+            await this.store.deleteItemAsync(s.key, this.options(s, s.group));
+        }
+        catch {
+            // The next run reads it as a conflict and leaves both; the shared copy is intact.
+        }
+        return false;
+    }
+    async deleteShared(s) {
+        try {
+            await this.store.deleteItemAsync(s.key, this.options(s, 'shared'));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async moveValue(unit) {
+        const { slot: s } = unit;
+        const shared = await this.read(s, 'shared');
+        if (shared === null)
+            return 'absent';
+        const target = await this.read(s, s.group);
+        let keep = target ?? shared;
+        if (target !== null && target !== shared) {
+            const merged = unit.merge?.(shared, target) ?? null;
+            if (merged === null)
+                return 'conflict';
+            keep = merged;
+        }
+        if (target !== keep && !(await this.copy(s, keep, target !== null)))
+            return 'failed';
+        // Verify the copy that is about to become the only one.
+        if ((await this.read(s, s.group)) !== keep)
+            return 'failed';
+        return (await this.deleteShared(s)) ? 'moved' : 'failed';
+    }
+    async movePair(unit) {
+        const halves = [unit.privateSlot, unit.publicSlot];
+        // A half whose group IS the shared group stays: it is read, never moved.
+        const movable = halves.filter((h) => h.group !== 'shared');
+        const shared = await Promise.all(halves.map((h) => this.read(h, 'shared')));
+        if (movable.every((h) => shared[halves.indexOf(h)] === null))
+            return 'absent';
+        const target = await Promise.all(halves.map((h, i) => (h.group === 'shared' ? shared[i] : this.read(h, h.group))));
+        for (const h of movable) {
+            const i = halves.indexOf(h);
+            if (shared[i] !== null && target[i] !== null && shared[i] !== target[i])
+                return 'conflict';
+        }
+        const finalPair = halves.map((_, i) => target[i] ?? shared[i]);
+        if (!isHealthyPair(finalPair[0], finalPair[1]))
+            return 'unhealthy';
+        for (const h of movable) {
+            const i = halves.indexOf(h);
+            const value = shared[i];
+            if (value !== null && target[i] === null && !(await this.copy(h, value)))
+                return 'failed';
+        }
+        const readBack = await Promise.all(halves.map((h, i) => (h.group === 'shared' ? shared[i] : this.read(h, h.group))));
+        if (readBack.some((v, i) => v !== finalPair[i]) || !isHealthyPair(readBack[0], readBack[1])) {
+            return 'failed';
+        }
+        for (const h of movable) {
+            if (shared[halves.indexOf(h)] !== null && !(await this.deleteShared(h)))
+                return 'failed';
+        }
+        return 'moved';
+    }
+    move(unit) {
+        return unit.kind === 'pair' ? this.movePair(unit) : this.moveValue(unit);
+    }
+}
+/** The personal items, in the order they move. */
+function personalUnits() {
+    const v2 = (key, service, deviceOnly) => slot(key, 'identity-secret', service, deviceOnly);
+    const legacy = (key, deviceOnly) => slot(key, 'identity-secret', undefined, deviceOnly);
+    return [
+        {
+            label: 'primary',
+            kind: 'pair',
+            privateSlot: v2(V2_STORAGE_KEYS.PRIVATE_KEY, V2_PRIMARY_KEYCHAIN_SERVICE, true),
+            publicSlot: v2(V2_STORAGE_KEYS.PUBLIC_KEY, V2_PRIMARY_KEYCHAIN_SERVICE, false),
+        },
+        {
+            label: 'backup',
+            kind: 'pair',
+            privateSlot: v2(V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY, V2_BACKUP_KEYCHAIN_SERVICE, true),
+            publicSlot: v2(V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY, V2_BACKUP_KEYCHAIN_SERVICE, false),
+        },
+        {
+            label: 'backup-timestamp',
+            kind: 'value',
+            slot: v2(V2_STORAGE_KEYS.BACKUP_TIMESTAMP, V2_BACKUP_KEYCHAIN_SERVICE, false),
+        },
+        {
+            label: 'legacy-primary',
+            kind: 'pair',
+            privateSlot: legacy(STORAGE_KEYS.PRIVATE_KEY, true),
+            publicSlot: legacy(STORAGE_KEYS.PUBLIC_KEY, false),
+        },
+        {
+            label: 'legacy-backup',
+            kind: 'pair',
+            privateSlot: legacy(STORAGE_KEYS.BACKUP_PRIVATE_KEY, true),
+            publicSlot: legacy(STORAGE_KEYS.BACKUP_PUBLIC_KEY, false),
+        },
+        {
+            label: 'legacy-backup-timestamp',
+            kind: 'value',
+            slot: legacy(STORAGE_KEYS.BACKUP_TIMESTAMP, false),
+        },
+        {
+            label: 'phrase',
+            kind: 'value',
+            slot: slot(RECOVERY_MNEMONIC_STORAGE_KEY, 'identity-secret', RECOVERY_MNEMONIC_KEYCHAIN_SERVICE),
+        },
+        {
+            // The private key moves to the wallet group; its public key stays shared.
+            label: 'shared-slot',
+            kind: 'pair',
+            privateSlot: slot(STORAGE_KEYS.SHARED_PRIVATE_KEY, 'spending-key'),
+            publicSlot: slot(STORAGE_KEYS.SHARED_PUBLIC_KEY, 'shared', undefined, false),
+        },
+    ];
+}
+const INDEX_SLOT = slot(ORGANIZATION_INDEX_STORAGE_KEY, 'identity-secret', ORGANIZATION_INDEX_KEYCHAIN_SERVICE, false);
+/** Union of two indexes; never drops an id either side lists. */
+function mergeIndexes(shared, target) {
+    return serializeOrganizationIndex([
+        ...parseOrganizationIndex(shared),
+        ...parseOrganizationIndex(target),
+    ]);
+}
+/** Run the migration once. Exported for tests; production code awaits the gate. */
+export async function runKeychainGroupMigration() {
+    let access;
+    try {
+        access = await resolveKeychainAccess();
+    }
+    catch {
+        return { state: 'deferred', items: {} };
+    }
+    if (access.mode !== 'grouped' || access.role !== 'holder') {
+        return { state: 'not-applicable', items: {} };
+    }
+    let store;
+    try {
+        store = await loadSecureStore();
+    }
+    catch {
+        return { state: 'deferred', items: {} };
+    }
+    const mover = new Mover(store, access);
+    const items = {};
+    try {
+        for (const unit of personalUnits()) {
+            items[unit.label] = await mover.move(unit);
+        }
+        // Organizations: every id either copy of the index names.
+        const ids = new Set([
+            ...parseOrganizationIndex(await mover.read(INDEX_SLOT, 'shared')),
+            ...parseOrganizationIndex(await mover.read(INDEX_SLOT, INDEX_SLOT.group)),
+        ]);
+        let n = 0;
+        for (const accountId of [...ids].sort()) {
+            n += 1;
+            items[`organization-${n}`] = await mover.move({
+                label: `organization-${n}`,
+                kind: 'pair',
+                privateSlot: slot(organizationPrivateKeyName(accountId), 'spending-key'),
+                publicSlot: slot(organizationPublicKeyName(accountId), 'spending-key', undefined, false),
+            });
+            items[`organization-${n}-phrase`] = await mover.move({
+                label: `organization-${n}-phrase`,
+                kind: 'value',
+                slot: slot(organizationMnemonicName(accountId), 'identity-secret', ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE),
+            });
+        }
+        // The index last: it is how a later run finds the organizations above.
+        items['organization-index'] = await mover.move({
+            label: 'organization-index',
+            kind: 'value',
+            slot: INDEX_SLOT,
+            merge: mergeIndexes,
+        });
+    }
+    catch (error) {
+        if (error instanceof Deferred) {
+            return { state: 'deferred', items };
+        }
+        throw error;
+    }
+    const settled = Object.values(items).every((o) => o === 'absent' || o === 'moved');
+    const report = {
+        state: settled ? 'complete' : 'incomplete',
+        items,
+    };
+    if (!settled) {
+        logger.warn('Keychain access-group migration left items in the shared group', {
+            component: 'KeychainGroupMigration',
+            items: Object.entries(items)
+                .filter(([, o]) => o !== 'absent' && o !== 'moved')
+                .map(([label, o]) => `${label}:${o}`)
+                .join(','),
+        });
+    }
+    return report;
+}
+let settledReport = null;
+let inFlight = null;
+/**
+ * The gate every Commons identity-storage access awaits. One run per process
+ * (`complete`, `incomplete` and `not-applicable` are kept; `incomplete` is
+ * retried on the next launch); a `deferred` run is forgotten, so the next
+ * access tries again once the keychain unlocks. Concurrent callers share one
+ * run. Never throws.
+ */
+export function ensureKeychainGroupsMigrated() {
+    if (settledReport) {
+        return Promise.resolve(settledReport);
+    }
+    if (!inFlight) {
+        inFlight = runKeychainGroupMigration()
+            .catch((error) => {
+            logger.warn('Keychain access-group migration threw; retrying on the next access', { component: 'KeychainGroupMigration' }, error);
+            return { state: 'deferred', items: {} };
+        })
+            .then((report) => {
+            if (report.state !== 'deferred') {
+                settledReport = report;
+            }
+            inFlight = null;
+            return report;
+        });
+    }
+    return inFlight;
+}
+/** Forget the memoized run. Tests only. @internal */
+export function resetKeychainGroupMigrationForTests() {
+    settledReport = null;
+    inFlight = null;
+}

package/dist/esm/crypto/keychainItems.js

@@ -0,0 +1,61 @@
+/**
+ * The names of every identity item `KeyManager` and `./organizationKeys` keep
+ * in `expo-secure-store`, in one place so the access-group migration
+ * (`./keychainGroupMigration`) moves exactly what those modules read. Values
+ * are stable on-device identifiers: renaming one strands what is stored.
+ */
+/** Legacy (pre-v2) and shared-slot keys; the legacy ones have no keychain service. */
+export 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 personal key's cross-app slot: the private key in the wallet group, the
+    // public key in the shared group (iOS only), no keychain service.
+    SHARED_PRIVATE_KEY: 'oxy_shared_identity_private_key',
+    SHARED_PUBLIC_KEY: 'oxy_shared_identity_public_key',
+};
+export const V2_PRIMARY_KEYCHAIN_SERVICE = 'oxy_identity';
+export const V2_BACKUP_KEYCHAIN_SERVICE = 'oxy_identity_backup';
+export 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',
+};
+export const RECOVERY_MNEMONIC_KEYCHAIN_SERVICE = 'oxy_identity_mnemonic';
+export const RECOVERY_MNEMONIC_STORAGE_KEY = 'oxy_identity_mnemonic_v1';
+/** Organization keys (ADR 0061 D6). On iOS the pair has no keychain service. */
+export const ORGANIZATION_ANDROID_KEYCHAIN_SERVICE = 'oxy_org_identity';
+export const ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE = 'oxy_org_identity_mnemonic';
+export const ORGANIZATION_INDEX_KEYCHAIN_SERVICE = 'oxy_org_identity_index';
+export const ORGANIZATION_INDEX_STORAGE_KEY = 'oxy_org_identity_index_v1';
+export const organizationPrivateKeyName = (accountId) => `oxy_org_identity_private_key.${accountId}`;
+export const organizationPublicKeyName = (accountId) => `oxy_org_identity_public_key.${accountId}`;
+export const organizationMnemonicName = (accountId) => `oxy_org_identity_mnemonic.${accountId}`;
+/** Same set the server's account ids come from: a legacy 24-hex id or a lowercase uuid. */
+const ACCOUNT_ID = /^(?:[0-9a-f]{24}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+/** Whether `value` is an account id an organization key can be stored under. */
+export function isOrganizationAccountId(value) {
+    return ACCOUNT_ID.test(value);
+}
+/** The account ids in a stored organization index; anything malformed is skipped. */
+export function parseOrganizationIndex(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed)
+            ? parsed.filter((id) => typeof id === 'string' && isOrganizationAccountId(id))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The stored form of an organization index: unique, sorted. */
+export function serializeOrganizationIndex(ids) {
+    return JSON.stringify([...new Set(ids)].sort());
+}