@oxy.so/core 7.27.0 → 7.29.0

package/dist/cjs/i18n/locales/en-US.js

@@ -666,6 +666,20 @@ const dict = {
                 month: 'Month',
                 year: 'Year',
             },
+            pronouns: {
+                title: 'Pronouns',
+                subtitle: 'How people should refer to you',
+                label: 'Pronouns',
+                options: {
+                    unspecified: 'Not set',
+                    he_him: 'He/him',
+                    she_her: 'She/her',
+                    they_them: 'They/them',
+                    he_they: 'He/they',
+                    she_they: 'She/they',
+                    it_its: 'It/its',
+                },
+            },
             locations: {
                 title: 'Locations',
                 subtitle: "Places you've been or live",

package/dist/cjs/i18n/locales/es-ES.js

@@ -368,6 +368,20 @@ const dict = {
                 month: 'Mes',
                 year: 'Año',
             },
+            pronouns: {
+                title: 'Pronombres',
+                subtitle: 'Cómo deben referirse a ti las personas',
+                label: 'Pronombres',
+                options: {
+                    unspecified: 'Sin definir',
+                    he_him: 'He/him',
+                    she_her: 'She/her',
+                    they_them: 'They/them',
+                    he_they: 'He/they',
+                    she_they: 'She/they',
+                    it_its: 'It/its',
+                },
+            },
             locations: {
                 title: 'Ubicaciones',
                 subtitle: 'Lugares donde has estado o vives',

package/dist/cjs/session/index.js

@@ -8,7 +8,8 @@
  * the API with a token it already has never needs it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runColdBoot = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.readLocalDeviceCredential = exports.publishProvenDeviceCredential = exports.normalizeSharedDeviceSessionRead = exports.decideSharedDevicePublish = exports.decideSharedDeviceJoin = exports.createSharedMirroringAuthStateStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.resolveAccountDelegationAccess = exports.canSwitchIntoAccount = exports.isSwitchTargetAccount = exports.deviceComparisonCode = exports.showsPrincipalHeaders = exports.buildSwitcherRows = exports.resolveDeviceContext = exports.resolveActiveContext = exports.projectDevicePrincipals = exports.directoryHandle = exports.directoryDisplayName = exports.canActivateContext = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.DeviceManager = void 0;
+exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.resolveKeychainAccess = exports.deleteThroughPlan = exports.readThroughPlan = exports.ownKeychainItemPlan = exports.keychainAccessGroupValue = exports.KeychainAccessUnavailableError = exports.readLocalDeviceCredential = exports.publishProvenDeviceCredential = exports.normalizeSharedDeviceSessionRead = exports.decideSharedDevicePublish = exports.decideSharedDeviceJoin = exports.createSharedMirroringAuthStateStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.resolveAccountDelegationAccess = exports.canSwitchIntoAccount = exports.isSwitchTargetAccount = exports.deviceComparisonCode = exports.showsPrincipalHeaders = exports.buildSwitcherRows = exports.resolveDeviceContext = exports.resolveActiveContext = exports.projectDevicePrincipals = exports.directoryHandle = exports.directoryDisplayName = exports.canActivateContext = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.DeviceManager = void 0;
+exports.runColdBoot = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = void 0;
 // Session code reaches the identity key (identity-bound sessions), so the
 // crypto shim goes first — see `../crypto/polyfill`.
 require("../crypto/polyfill");
@@ -107,6 +108,15 @@ Object.defineProperty(exports, "decideSharedDevicePublish", { enumerable: true,
 Object.defineProperty(exports, "normalizeSharedDeviceSessionRead", { enumerable: true, get: function () { return sharedDeviceCredential_1.normalizeSharedDeviceSessionRead; } });
 Object.defineProperty(exports, "publishProvenDeviceCredential", { enumerable: true, get: function () { return sharedDeviceCredential_1.publishProvenDeviceCredential; } });
 Object.defineProperty(exports, "readLocalDeviceCredential", { enumerable: true, get: function () { return sharedDeviceCredential_1.readLocalDeviceCredential; } });
+// Where the shared device credential (and an app's own items) live on iOS:
+// docs/identity/ios-keychain-access-groups.md, ADR 0062.
+var keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
+Object.defineProperty(exports, "KeychainAccessUnavailableError", { enumerable: true, get: function () { return keychainAccessGroups_1.KeychainAccessUnavailableError; } });
+Object.defineProperty(exports, "keychainAccessGroupValue", { enumerable: true, get: function () { return keychainAccessGroups_1.keychainAccessGroupValue; } });
+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, "resolveKeychainAccess", { enumerable: true, get: function () { return keychainAccessGroups_1.resolveKeychainAccess; } });
 // Identity-bound sessions (the identity vault). The pin is the durable
 // `{publicKey, accountId}` binding between this device's PRIMARY identity key
 // and the account it authenticates as; it is what keeps such a client from

package/dist/cjs/utils/keychainAccessGroups.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeychainAccessUnavailableError = exports.KEYCHAIN_ACCESS_GROUPS = void 0;
+exports.keychainGroupFor = keychainGroupFor;
+exports.mayHoldKeychainItem = mayHoldKeychainItem;
+exports.keychainAccessFromDefaultGroup = keychainAccessFromDefaultGroup;
+exports.resolveKeychainAccess = resolveKeychainAccess;
+exports.resetKeychainAccessForTests = resetKeychainAccessForTests;
+exports.keychainAccessGroupValue = keychainAccessGroupValue;
+exports.keychainReadPlan = keychainReadPlan;
+exports.keychainDeletePlan = keychainDeletePlan;
+exports.keychainWriteOption = keychainWriteOption;
+exports.ownKeychainItemPlan = ownKeychainItemPlan;
+exports.readThroughPlan = readThroughPlan;
+exports.deleteThroughPlan = deleteThroughPlan;
+exports.groupedKeychainStore = groupedKeychainStore;
+/**
+ * iOS keychain access groups: which group each Oxy keychain item lives in, and
+ * which apps may read it (docs/identity/ios-keychain-access-groups.md, ADR 0062).
+ *
+ * | Group                         | Held by                      | Item class        |
+ * |-------------------------------|------------------------------|-------------------|
+ * | `<TEAM>.so.oxy.identity`      | Commons only (listed FIRST)  | `identity-secret` |
+ * | `<TEAM>.so.oxy.wallet`        | Commons, the Peable wallet   | `spending-key`    |
+ * | `<TEAM>.group.so.oxy.shared`  | every Oxy app                | `shared`          |
+ *
+ * - `identity-secret`: the personal root (primary and backup slots), the
+ *   personal and organization recovery phrases, the organization index. Only
+ *   Commons may read or write them.
+ * - `spending-key`: private keys an app other than Commons signs or derives
+ *   with in process — the personal key's shared slot and organization pairs
+ *   (`deriveScopedSeed`, `signSocialReceive`). Commons writes them; the Peable
+ *   wallet reads them.
+ * - `shared`: what every Oxy app may read: the shared public key and the
+ *   device-session credential.
+ *
+ * The ROLE of this binary comes from the keychain itself: an item written
+ * without a group lands in the app's default group, the first entry of its
+ * `keychain-access-groups` entitlement, and `@oxy.so/app-preset` lets only
+ * Commons put the identity group first and only the Peable wallet the wallet
+ * group. The same probe gives the team prefix, which `kSecAttrAccessGroup`
+ * needs and JavaScript cannot otherwise see.
+ *
+ * Android and web have no access groups: there every helper here answers the
+ * single-store behaviour (`ungrouped`), and Android's narrowing is Commons'
+ * identity host. An iOS build whose native module predates the probe is also
+ * `ungrouped` — exactly what that build's entitlements (one shared group) do.
+ *
+ * This module never imports the identity stack: services' device-session store
+ * and Peable's wallet storage use it too.
+ */
+const protocol_1 = require("@oxy.so/protocol");
+const platform_1 = require("./platform");
+/** The group names after the team prefix, exactly as the entitlements list them. */
+exports.KEYCHAIN_ACCESS_GROUPS = {
+    identity: 'so.oxy.identity',
+    wallet: 'so.oxy.wallet',
+    shared: 'group.so.oxy.shared',
+};
+/** Thrown while the probe cannot answer (before first unlock). Transient. */
+class KeychainAccessUnavailableError extends Error {
+    constructor(cause) {
+        super('The keychain cannot say which access groups this app holds right now.');
+        this.cause = cause;
+        this.name = 'KeychainAccessUnavailableError';
+    }
+}
+exports.KeychainAccessUnavailableError = KeychainAccessUnavailableError;
+/**
+ * The single place each item class is assigned a group. A new kind of item
+ * (F1's retained keys, for one) picks its class and reuses everything below.
+ */
+function keychainGroupFor(item) {
+    switch (item) {
+        case 'identity-secret':
+            return 'identity';
+        case 'spending-key':
+            return 'wallet';
+        case 'shared':
+            return 'shared';
+    }
+}
+/** Whether `role` holds the group `item` lives in. */
+function mayHoldKeychainItem(role, item) {
+    switch (role) {
+        case 'holder':
+            return true;
+        case 'wallet':
+            return item !== 'identity-secret';
+        case 'member':
+            return item === 'shared';
+    }
+}
+/** Parse the default access group the probe reported. Exported for tests. */
+function keychainAccessFromDefaultGroup(defaultGroup) {
+    const dot = defaultGroup.indexOf('.');
+    if (dot <= 0 || dot === defaultGroup.length - 1) {
+        // Not `<prefix>.<group>`: an unsigned simulator build. Nothing to split.
+        return { mode: 'ungrouped' };
+    }
+    const prefix = defaultGroup.slice(0, dot + 1);
+    const group = defaultGroup.slice(dot + 1);
+    const role = group === exports.KEYCHAIN_ACCESS_GROUPS.identity
+        ? 'holder'
+        : group === exports.KEYCHAIN_ACCESS_GROUPS.wallet
+            ? 'wallet'
+            : 'member';
+    return { mode: 'grouped', prefix, defaultGroup, role };
+}
+let resolvedAccess = null;
+/**
+ * This binary's keychain access, memoized once known. THROWS
+ * {@link KeychainAccessUnavailableError} while the probe cannot answer, which
+ * every caller already treats as "storage unavailable, retry".
+ */
+async function resolveKeychainAccess() {
+    if (resolvedAccess) {
+        return resolvedAccess;
+    }
+    if (!(0, platform_1.isIOS)()) {
+        // Not memoized: until `@oxy.so/services` registers the platform, a phone
+        // reads as "not iOS", and caching that would keep the whole process on the
+        // pre-split behaviour.
+        return { mode: 'ungrouped' };
+    }
+    let probe;
+    try {
+        probe = await (0, protocol_1.loadKeychainDefaultAccessGroup)();
+    }
+    catch (cause) {
+        throw new KeychainAccessUnavailableError(cause);
+    }
+    if (probe.state === 'unavailable') {
+        throw new KeychainAccessUnavailableError(probe.cause);
+    }
+    resolvedAccess =
+        probe.state === 'resolved'
+            ? keychainAccessFromDefaultGroup(probe.accessGroup)
+            : { mode: 'ungrouped' };
+    return resolvedAccess;
+}
+/** Forget the memoized access. Tests only. @internal */
+function resetKeychainAccessForTests() {
+    resolvedAccess = null;
+}
+/** The full `kSecAttrAccessGroup` value of `group`, or `undefined` when ungrouped. */
+function keychainAccessGroupValue(access, group) {
+    return access.mode === 'grouped' ? `${access.prefix}${exports.KEYCHAIN_ACCESS_GROUPS[group]}` : undefined;
+}
+function option(value) {
+    return value === undefined ? {} : { accessGroup: value };
+}
+/**
+ * The option bags a READ of `item` tries, in order: its own group, then the
+ * shared group, where every item lived before the split (release 4 of the doc
+ * drops that fallback). Empty when this app may not hold the item: the caller
+ * answers `null` without touching the keychain.
+ */
+function keychainReadPlan(access, item) {
+    if (access.mode === 'ungrouped') {
+        return [{}];
+    }
+    if (!mayHoldKeychainItem(access.role, item)) {
+        return [];
+    }
+    const own = keychainGroupFor(item);
+    const plan = [option(keychainAccessGroupValue(access, own))];
+    if (own !== 'shared') {
+        plan.push(option(keychainAccessGroupValue(access, 'shared')));
+    }
+    return plan;
+}
+/**
+ * Every place a DELETE of `item` must reach: the read plan, so a delete never
+ * leaves a pre-split copy behind in the shared group.
+ */
+function keychainDeletePlan(access, item) {
+    return keychainReadPlan(access, item);
+}
+/**
+ * The option a WRITE of `item` carries. THROWS when this app may not hold the
+ * item: an identity secret written by any app but Commons would land in that
+ * app's default group, a second holder nobody knows about.
+ */
+function keychainWriteOption(access, item) {
+    if (access.mode === 'ungrouped') {
+        return {};
+    }
+    if (!mayHoldKeychainItem(access.role, item)) {
+        throw new Error(`This app (keychain role "${access.role}") may not hold a ${item} keychain item; only Commons writes the identity.`);
+    }
+    return option(keychainAccessGroupValue(access, keychainGroupFor(item)));
+}
+/**
+ * The plan for an app's OWN items (its session credential, its settings, an
+ * imported wallet's phrase) in Commons and the Peable wallet, whose default
+ * group the split changed: written to the default group explicitly — where a
+ * write without a group goes anyway — and read from it FIRST, then from every
+ * group (`{}`), where all of them were written before. Without the explicit
+ * order a read could return whichever of two copies the keychain met first.
+ * Deletes reach every group, as they always did.
+ *
+ * Every other app (`member`) and Android/web keep the calls they always made.
+ */
+function ownKeychainItemPlan(access) {
+    if (access.mode === 'ungrouped' || access.role === 'member') {
+        return { read: [{}], write: {}, delete: [{}] };
+    }
+    return {
+        read: [option(access.defaultGroup), {}],
+        write: option(access.defaultGroup),
+        delete: [{}],
+    };
+}
+/** Read `key` through `plan`: the first non-null answer. A thrown read propagates. */
+async function readThroughPlan(store, key, options, plan) {
+    for (const group of plan) {
+        const value = await store.getItemAsync(key, { ...options, ...group });
+        if (value !== null && value !== undefined) {
+            return value;
+        }
+    }
+    return null;
+}
+/** Delete `key` from every location in `plan`. A thrown delete propagates. */
+async function deleteThroughPlan(store, key, options, plan) {
+    for (const group of plan) {
+        await store.deleteItemAsync(key, { ...options, ...group });
+    }
+}
+/**
+ * `store` with every call routed to `item`'s groups for this app: reads walk
+ * the read plan, writes carry the write option (throwing for a role that may
+ * not hold the item), deletes reach every location. The constants of the
+ * wrapped store are kept, so `store.WHEN_UNLOCKED_THIS_DEVICE_ONLY` still reads.
+ */
+function groupedKeychainStore(store, access, item) {
+    const plan = keychainReadPlan(access, item);
+    const wrapped = {
+        getItemAsync: (key, options) => readThroughPlan(store, key, options ?? {}, plan),
+        setItemAsync: async (key, value, options) => {
+            const group = keychainWriteOption(access, item);
+            await store.setItemAsync(key, value, { ...(options ?? {}), ...group });
+        },
+        deleteItemAsync: (key, options) => deleteThroughPlan(store, key, options ?? {}, plan),
+    };
+    return Object.assign(Object.create(store), wrapped);
+}

package/dist/esm/crypto/index.js

@@ -17,6 +17,9 @@ export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, IdentityU
 export { readIdentityMarker, updateIdentityMarker } from './identityMarker.js';
 // Organization keys on the device (docs/adr/0061-organization-identity-key.md D6)
 export { generateOrganizationKey, organizationKeyFromPhrase, storeOrganizationKey, getOrganizationPublicKey, getOrganizationPrivateKey, getOrganizationRecoveryPhrase, listOrganizationKeys, deleteOrganizationKey, syncOrganizationKeys, isOrganizationAccountId, isHealthyOrganizationKeyPair, } from './organizationKeys.js';
+// iOS keychain access groups (docs/identity/ios-keychain-access-groups.md, ADR 0062)
+export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFor, mayHoldKeychainItem, resolveKeychainAccess, keychainAccessGroupValue, keychainReadPlan, keychainDeletePlan, keychainWriteOption, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, groupedKeychainStore, } from '../utils/keychainAccessGroups.js';
+export { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
 export { SignatureService } from './signatureService.js';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase.js';
 // Low-level primitives (encrypted backup, device transfer)

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