@oxy.so/core 7.28.0 → 7.30.0

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());
+}

package/dist/esm/crypto/organizationKeys.js

@@ -8,8 +8,10 @@
  * other Oxy apps reach it the way they reach the personal identity, by
  * derivation and never by the key:
  *
- * - iOS: the keychain access group `group.so.oxy.shared`, like the personal
- *   shared slot. Only Commons writes it.
+ * - iOS: the pair in the wallet keychain group (`<TEAM>.so.oxy.wallet`), which
+ *   only Commons and the Peable wallet hold; the phrase and the index in the
+ *   identity group, Commons only (docs/identity/ios-keychain-access-groups.md).
+ *   Only Commons writes them; every other app reads nothing.
  * - Android: Commons' own expo-secure-store slot, mirrored into the identity
  *   signer store (`./identitySigner`) that Commons' identity host answers
  *   `accountId` requests from. Every other app asks Commons over IPC
@@ -17,7 +19,7 @@
  *
  * The phrase is kept only in Commons, on the device that created or imported
  * it, so an owner can show it to another owner (ADR 0061 D5); it never reaches
- * the keychain group, an IPC answer or a log.
+ * the wallet or shared group, an IPC answer or a log.
  *
  * This module imports nothing from `./keyManager` (which imports it): the
  * signer store comes from `./identitySigner`'s registry.
@@ -27,29 +29,18 @@ import { wordlist } from '@scure/bip39/wordlists/english.js';
 import { loadCommonsIdentityBridge, loadSecureStore, } from '@oxy.so/protocol';
 import { deriveSecp256k1PublicKey, isValidSecp256k1PrivateKey, isValidSecp256k1PublicKey, normalizeSecp256k1PrivateKey, normalizeSecp256k1PublicKey, } from '@oxy.so/protocol/secp256k1';
 import { logger } from '../logger/index.js';
+import { groupedKeychainStore, resolveKeychainAccess, } from '../utils/keychainAccessGroups.js';
 import { isAndroid, isIOS, isWeb } from '../utils/platform.js';
 import { registeredIdentitySignerStore } from './identitySigner.js';
-/** 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})$/;
-const IOS_KEYCHAIN_GROUP = 'group.so.oxy.shared';
-/** Android, Commons-local: its own Keystore key, shared with no personal slot. */
-const ANDROID_KEYCHAIN_SERVICE = 'oxy_org_identity';
-const MNEMONIC_KEYCHAIN_SERVICE = 'oxy_org_identity_mnemonic';
-const INDEX_KEYCHAIN_SERVICE = 'oxy_org_identity_index';
-const INDEX_STORAGE_KEY = 'oxy_org_identity_index_v1';
+import { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
+import { ORGANIZATION_ANDROID_KEYCHAIN_SERVICE as ANDROID_KEYCHAIN_SERVICE, ORGANIZATION_INDEX_KEYCHAIN_SERVICE as INDEX_KEYCHAIN_SERVICE, ORGANIZATION_INDEX_STORAGE_KEY as INDEX_STORAGE_KEY, ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE as MNEMONIC_KEYCHAIN_SERVICE, isOrganizationAccountId, organizationMnemonicName as mnemonicName, organizationPrivateKeyName as privateKeyName, organizationPublicKeyName as publicKeyName, serializeOrganizationIndex, } from './keychainItems.js';
+export { isOrganizationAccountId };
 const ORGANIZATION_PHRASE_WORDS = 24;
-/** Whether `value` is an account id an organization key can be stored under. */
-export function isOrganizationAccountId(value) {
-    return ACCOUNT_ID.test(value);
-}
 function assertAccountId(accountId) {
     if (!isOrganizationAccountId(accountId)) {
         throw new Error('organization key: accountId must be a 24-hex or uuid account id');
     }
 }
-const privateKeyName = (accountId) => `oxy_org_identity_private_key.${accountId}`;
-const publicKeyName = (accountId) => `oxy_org_identity_public_key.${accountId}`;
-const mnemonicName = (accountId) => `oxy_org_identity_mnemonic.${accountId}`;
 function toHex(bytes) {
     return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
 }
@@ -102,9 +93,23 @@ export async function generateOrganizationKey() {
 export async function organizationKeyFromPhrase(phrase) {
     return pairFromPhrase(phrase);
 }
-async function secureStore() {
-    return loadSecureStore();
+/**
+ * The secure store for one class of organization item: on iOS the pair is a
+ * `spending-key` (wallet group), the phrase and the index `identity-secret`
+ * (identity group); see `../utils/keychainAccessGroups`. In Commons every
+ * access first awaits the access-group migration. Android is unchanged.
+ */
+async function secureStore(item) {
+    const raw = await loadSecureStore();
+    const access = await resolveKeychainAccess();
+    if (access.mode === 'grouped' && access.role === 'holder') {
+        await ensureKeychainGroupsMigrated();
+    }
+    return groupedKeychainStore(raw, access, item);
 }
+const pairStore = () => secureStore('spending-key');
+const phraseStore = () => secureStore('identity-secret');
+const indexStore = () => secureStore('identity-secret');
 async function readIndex(store) {
     const raw = await store.getItemAsync(INDEX_STORAGE_KEY, {
         keychainService: INDEX_KEYCHAIN_SERVICE,
@@ -126,19 +131,17 @@ async function readIndex(store) {
     }
 }
 async function writeIndex(store, ids) {
-    await store.setItemAsync(INDEX_STORAGE_KEY, JSON.stringify([...new Set(ids)].sort()), {
+    await store.setItemAsync(INDEX_STORAGE_KEY, serializeOrganizationIndex(ids), {
         keychainService: INDEX_KEYCHAIN_SERVICE,
     });
 }
-/** Where this platform keeps the pair: the iOS keychain group, or Commons' own Android slot. */
+/**
+ * The options of the pair on this platform: on iOS no keychain service (the
+ * wallet group comes from {@link pairStore}), on Android Commons' own slot.
+ */
 function pairOptions(store, forPrivateWrite) {
     if (isIOS()) {
-        return forPrivateWrite
-            ? {
-                keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-                keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-            }
-            : { keychainAccessGroup: IOS_KEYCHAIN_GROUP };
+        return forPrivateWrite ? { keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY } : {};
     }
     return forPrivateWrite
         ? {
@@ -155,7 +158,7 @@ async function readLocalPair(accountId) {
         const signer = registeredIdentitySignerStore();
         if (!signer)
             return null; // Only Commons holds organization keys on Android.
-        const store = await secureStore();
+        const store = await pairStore();
         const options = pairOptions(store, false);
         const privateKey = await store.getItemAsync(privateKeyName(accountId), options);
         const publicKey = await store.getItemAsync(publicKeyName(accountId), options);
@@ -173,7 +176,9 @@ async function readLocalPair(accountId) {
     }
     if (!isIOS())
         return null;
-    const store = await secureStore();
+    // The wallet group: `null` without a keychain read in every app but Commons
+    // and the Peable wallet.
+    const store = await pairStore();
     const options = pairOptions(store, false);
     const privateKey = await store.getItemAsync(privateKeyName(accountId), options);
     const publicKey = await store.getItemAsync(publicKeyName(accountId), options);
@@ -187,7 +192,7 @@ async function readLocalPair(accountId) {
 /**
  * Keep an organization key on this device. Commons only: on Android it needs
  * the identity signer store Commons registers, so the identity host can serve
- * it; on iOS only Commons calls it (the keychain group is shared).
+ * it; on iOS only Commons holds the groups it writes (any other app throws).
  *
  * Refuses a pair whose public key does not derive from its private key, and a
  * phrase that does not derive the pair. Overwrites whatever this device held for
@@ -212,29 +217,31 @@ export async function storeOrganizationKey(accountId, key) {
     if (isAndroid() && !signer?.writeOrganization) {
         throw new Error('On Android only Commons holds organization keys; this app has no identity signer store for them.');
     }
-    const store = await secureStore();
+    const store = await pairStore();
     await store.setItemAsync(privateKeyName(accountId), privateKey, pairOptions(store, true));
     await store.setItemAsync(publicKeyName(accountId), publicKey, pairOptions(store, false));
     if (signer?.writeOrganization &&
         !(await signer.writeOrganization(accountId, privateKey, publicKey))) {
         throw new Error(`The identity signer store (${signer.name}) did not confirm the organization key.`);
     }
+    const phrases = await phraseStore();
     if (key.mnemonic !== undefined) {
-        await store.setItemAsync(mnemonicName(accountId), normalizePhrase(key.mnemonic), {
+        await phrases.setItemAsync(mnemonicName(accountId), normalizePhrase(key.mnemonic), {
             keychainService: MNEMONIC_KEYCHAIN_SERVICE,
-            keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+            keychainAccessible: phrases.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
         });
     }
     else {
-        await store.deleteItemAsync(mnemonicName(accountId), {
+        await phrases.deleteItemAsync(mnemonicName(accountId), {
             keychainService: MNEMONIC_KEYCHAIN_SERVICE,
         });
     }
-    await writeIndex(store, [...(await readIndex(store)), accountId]);
+    const index = await indexStore();
+    await writeIndex(index, [...(await readIndex(index)), accountId]);
 }
 /**
  * The organization's public key as THIS device can reach it, or `null`.
- * iOS: the keychain group. Android: Commons' own slot inside Commons, and
+ * iOS: the wallet keychain group (Commons, the Peable wallet). Android: Commons' own slot inside Commons, and
  * Commons' identity host (`describe` with `accountId`) everywhere else. Compare
  * it with the organization's DID `#key-1` before receiving (Peable ADR 0002).
  */
@@ -259,8 +266,8 @@ export async function getOrganizationPublicKey(accountId) {
 }
 /**
  * The organization's private key, where this app may hold it: Commons (both
- * platforms) and, on iOS, the keychain group. `null` on Android outside
- * Commons. Use it to sign within the app only; never transmit it.
+ * platforms) and, on iOS, the Peable wallet through the wallet keychain group.
+ * `null` everywhere else. Use it to sign within the app only; never transmit it.
  */
 export async function getOrganizationPrivateKey(accountId) {
     if (!isOrganizationAccountId(accountId))
@@ -280,7 +287,7 @@ export async function getOrganizationPrivateKey(accountId) {
 export async function getOrganizationRecoveryPhrase(accountId) {
     if (!isOrganizationAccountId(accountId) || isWeb())
         return null;
-    const store = await secureStore();
+    const store = await phraseStore();
     return store.getItemAsync(mnemonicName(accountId), {
         keychainService: MNEMONIC_KEYCHAIN_SERVICE,
     });
@@ -289,23 +296,24 @@ export async function getOrganizationRecoveryPhrase(accountId) {
 export async function listOrganizationKeys() {
     if (isWeb())
         return [];
-    return readIndex(await secureStore());
+    return readIndex(await indexStore());
 }
 /** Forget an organization key on this device: its pair, its phrase, its signer copy and its index entry. */
 export async function deleteOrganizationKey(accountId) {
     assertAccountId(accountId);
     if (isWeb())
         return;
-    const store = await secureStore();
+    const store = await pairStore();
     const options = pairOptions(store, false);
     await store.deleteItemAsync(privateKeyName(accountId), options);
     await store.deleteItemAsync(publicKeyName(accountId), options);
-    await store.deleteItemAsync(mnemonicName(accountId), {
+    await (await phraseStore()).deleteItemAsync(mnemonicName(accountId), {
         keychainService: MNEMONIC_KEYCHAIN_SERVICE,
     });
     const signer = isAndroid() ? registeredIdentitySignerStore() : null;
     await signer?.clearOrganization?.(accountId);
-    await writeIndex(store, (await readIndex(store)).filter((id) => id !== accountId));
+    const index = await indexStore();
+    await writeIndex(index, (await readIndex(index)).filter((id) => id !== accountId));
 }
 /**
  * Commons on Android: copy every held organization key into the identity
@@ -317,9 +325,9 @@ export async function syncOrganizationKeys() {
     const signer = isAndroid() ? registeredIdentitySignerStore() : null;
     if (!signer?.writeOrganization || !signer.readOrganization)
         return 0;
-    const store = await secureStore();
+    const store = await pairStore();
     let mirrored = 0;
-    for (const accountId of await readIndex(store)) {
+    for (const accountId of await readIndex(await indexStore())) {
         const options = pairOptions(store, false);
         const privateKey = await store.getItemAsync(privateKeyName(accountId), options);
         const publicKey = await store.getItemAsync(publicKeyName(accountId), options);