@oxy.so/core 7.28.0 → 7.29.0

package/src/crypto/organizationKeys.ts

@@ -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.
@@ -38,8 +40,28 @@ import {
   normalizeSecp256k1PublicKey,
 } from '@oxy.so/protocol/secp256k1';
 import { logger } from '../logger';
+import {
+  type KeychainItemClass,
+  groupedKeychainStore,
+  resolveKeychainAccess,
+} from '../utils/keychainAccessGroups';
 import { isAndroid, isIOS, isWeb } from '../utils/platform';
 import { registeredIdentitySignerStore } from './identitySigner';
+import { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+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';
+import type { OxySecureStoreOptions as SecureStoreOptions } from './secureStoreOptions';
+
+export { isOrganizationAccountId };
 
 /** A secp256k1 pair: private key 64 hex, public key lowercase uncompressed (`04…`, 130 hex). */
 export interface OrganizationKeyPair {
@@ -57,39 +79,14 @@ export interface StoredOrganizationKey extends OrganizationKeyPair {
   mnemonic?: string;
 }
 
-/** 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';
 const ORGANIZATION_PHRASE_WORDS = 24;
 
-interface SecureStoreOptions {
-  keychainService?: string;
-  keychainAccessible?: number;
-  keychainAccessGroup?: string;
-}
-
-/** Whether `value` is an account id an organization key can be stored under. */
-export function isOrganizationAccountId(value: string): boolean {
-  return ACCOUNT_ID.test(value);
-}
-
 function assertAccountId(accountId: string): void {
   if (!isOrganizationAccountId(accountId)) {
     throw new Error('organization key: accountId must be a 24-hex or uuid account id');
   }
 }
 
-const privateKeyName = (accountId: string) => `oxy_org_identity_private_key.${accountId}`;
-const publicKeyName = (accountId: string) => `oxy_org_identity_public_key.${accountId}`;
-const mnemonicName = (accountId: string) => `oxy_org_identity_mnemonic.${accountId}`;
-
 function toHex(bytes: Uint8Array): string {
   return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
 }
@@ -152,10 +149,25 @@ export async function organizationKeyFromPhrase(phrase: string): Promise<Organiz
   return pairFromPhrase(phrase);
 }
 
-async function secureStore(): Promise<ExpoSecureStoreLike> {
-  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: KeychainItemClass): Promise<ExpoSecureStoreLike> {
+  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: ExpoSecureStoreLike): Promise<string[]> {
   const raw = await store.getItemAsync(INDEX_STORAGE_KEY, {
     keychainService: INDEX_KEYCHAIN_SERVICE,
@@ -176,20 +188,18 @@ async function readIndex(store: ExpoSecureStoreLike): Promise<string[]> {
 }
 
 async function writeIndex(store: ExpoSecureStoreLike, ids: string[]): Promise<void> {
-  await store.setItemAsync(INDEX_STORAGE_KEY, JSON.stringify([...new Set(ids)].sort()), {
+  await store.setItemAsync(INDEX_STORAGE_KEY, serializeOrganizationIndex(ids), {
     keychainService: INDEX_KEYCHAIN_SERVICE,
   } satisfies SecureStoreOptions);
 }
 
-/** 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: ExpoSecureStoreLike, forPrivateWrite: boolean): SecureStoreOptions {
   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
     ? {
@@ -205,7 +215,7 @@ async function readLocalPair(accountId: string): Promise<OrganizationKeyPair | n
   if (isAndroid()) {
     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);
@@ -222,7 +232,9 @@ async function readLocalPair(accountId: string): Promise<OrganizationKeyPair | n
       : null;
   }
   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);
@@ -237,7 +249,7 @@ async function readLocalPair(accountId: string): Promise<OrganizationKeyPair | n
 /**
  * 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
@@ -267,7 +279,7 @@ export async function storeOrganizationKey(
       '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 (
@@ -278,22 +290,24 @@ export async function storeOrganizationKey(
       `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,
     } satisfies SecureStoreOptions);
   } else {
-    await store.deleteItemAsync(mnemonicName(accountId), {
+    await phrases.deleteItemAsync(mnemonicName(accountId), {
       keychainService: MNEMONIC_KEYCHAIN_SERVICE,
     } satisfies SecureStoreOptions);
   }
-  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).
  */
@@ -317,8 +331,8 @@ export async function getOrganizationPublicKey(accountId: string): Promise<strin
 
 /**
  * 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: string): Promise<string | null> {
   if (!isOrganizationAccountId(accountId)) return null;
@@ -336,7 +350,7 @@ export async function getOrganizationPrivateKey(accountId: string): Promise<stri
 /** The organization's phrase, if this device created or imported it with one. Commons only. */
 export async function getOrganizationRecoveryPhrase(accountId: string): Promise<string | null> {
   if (!isOrganizationAccountId(accountId) || isWeb()) return null;
-  const store = await secureStore();
+  const store = await phraseStore();
   return store.getItemAsync(mnemonicName(accountId), {
     keychainService: MNEMONIC_KEYCHAIN_SERVICE,
   } satisfies SecureStoreOptions);
@@ -345,25 +359,26 @@ export async function getOrganizationRecoveryPhrase(accountId: string): Promise<
 /** The organizations this device keeps a key for (Commons' own index). */
 export async function listOrganizationKeys(): Promise<string[]> {
   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: string): Promise<void> {
   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,
   } satisfies SecureStoreOptions);
   const signer = isAndroid() ? registeredIdentitySignerStore() : null;
   await signer?.clearOrganization?.(accountId);
+  const index = await indexStore();
   await writeIndex(
-    store,
-    (await readIndex(store)).filter((id) => id !== accountId),
+    index,
+    (await readIndex(index)).filter((id) => id !== accountId),
   );
 }
 
@@ -376,9 +391,9 @@ export async function deleteOrganizationKey(accountId: string): Promise<void> {
 export async function syncOrganizationKeys(): Promise<number> {
   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);

package/src/crypto/secureStoreOptions.ts

@@ -0,0 +1,32 @@
+/**
+ * The `expo-secure-store` options `@oxy.so/core` passes.
+ *
+ * Standalone, not `SecureStoreOptions` itself, so the PUBLISHED declarations
+ * never name expo-secure-store: under NodeNext its types pull in
+ * expo-modules-core and turn every Node timer into a DOM `number` in server
+ * consumers. The check below still makes `tsc` refuse a field name the real
+ * package does not have — `keychainAccessGroup` instead of `accessGroup` sat
+ * here unnoticed for years behind a hand-written ambient shim, so no item was
+ * ever written to the group the code named (docs/identity/ios-keychain-access-groups.md).
+ */
+import type { SecureStoreOptions } from 'expo-secure-store';
+
+export interface OxySecureStoreOptions {
+  /** Keychain service name (Android keystore alias / iOS `kSecAttrService`). */
+  keychainService?: string;
+  /** Item accessibility: the `ExpoSecureStoreLike` constant, e.g. `WHEN_UNLOCKED_THIS_DEVICE_ONLY`. */
+  keychainAccessible?: number;
+  /** Prompt shown for biometric-protected items. */
+  authenticationPrompt?: string;
+  /** Whether Face ID / Touch ID is required to read the item. */
+  requireAuthentication?: boolean;
+  /**
+   * iOS `kSecAttrAccessGroup`: the FULL, team-prefixed entitlement value. Set
+   * only through `../utils/keychainAccessGroups`, never by hand.
+   */
+  accessGroup?: string;
+}
+
+/** Every key above must be one `expo-secure-store` reads; a misspelt one fails `tsc` here. */
+type FieldsExpoReads = Pick<SecureStoreOptions, keyof OxySecureStoreOptions>;
+type AssertExpoReadsEveryField = FieldsExpoReads;

package/src/session/index.ts

@@ -166,6 +166,17 @@ export type {
   SharedDevicePublishOutcome,
   SharedDevicePublishSkipReason,
 } from './sharedDeviceCredential';
+// Where the shared device credential (and an app's own items) live on iOS:
+// docs/identity/ios-keychain-access-groups.md, ADR 0062.
+export {
+  KeychainAccessUnavailableError,
+  keychainAccessGroupValue,
+  ownKeychainItemPlan,
+  readThroughPlan,
+  deleteThroughPlan,
+  resolveKeychainAccess,
+} from '../utils/keychainAccessGroups';
+export type { KeychainAccess, KeychainGroupOption } from '../utils/keychainAccessGroups';
 
 // Identity-bound sessions (the identity vault). The pin is the durable
 // `{publicKey, accountId}` binding between this device's PRIMARY identity key

package/src/utils/keychainAccessGroups.ts

@@ -0,0 +1,308 @@
+/**
+ * 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.
+ */
+import { type KeychainDefaultAccessGroup, loadKeychainDefaultAccessGroup } from '@oxy.so/protocol';
+import { isIOS } from './platform';
+
+/** The group names after the team prefix, exactly as the entitlements list them. */
+export const KEYCHAIN_ACCESS_GROUPS = {
+  identity: 'so.oxy.identity',
+  wallet: 'so.oxy.wallet',
+  shared: 'group.so.oxy.shared',
+} as const;
+
+export type KeychainAccessGroupName = keyof typeof KEYCHAIN_ACCESS_GROUPS;
+
+/** What a keychain item IS, which decides its group. See the table above. */
+export type KeychainItemClass = 'identity-secret' | 'spending-key' | 'shared';
+
+/** Which holder this binary is, from its default access group. */
+export type KeychainRole = 'holder' | 'wallet' | 'member';
+
+/**
+ * - `grouped`: iOS with the probe answered. `prefix` ends with its dot
+ *   (`ABCDE12345.`); `defaultGroup` is the full default group string.
+ * - `ungrouped`: Android, web, or an iOS native build without the probe.
+ */
+export type KeychainAccess =
+  | { mode: 'grouped'; prefix: string; defaultGroup: string; role: KeychainRole }
+  | { mode: 'ungrouped' };
+
+/** The `expo-secure-store` option this module sets (its real name since 58). */
+export interface KeychainGroupOption {
+  accessGroup?: string;
+}
+
+/** Thrown while the probe cannot answer (before first unlock). Transient. */
+export class KeychainAccessUnavailableError extends Error {
+  override readonly name = 'KeychainAccessUnavailableError';
+  constructor(readonly cause?: unknown) {
+    super('The keychain cannot say which access groups this app holds right now.');
+  }
+}
+
+/**
+ * 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.
+ */
+export function keychainGroupFor(item: KeychainItemClass): KeychainAccessGroupName {
+  switch (item) {
+    case 'identity-secret':
+      return 'identity';
+    case 'spending-key':
+      return 'wallet';
+    case 'shared':
+      return 'shared';
+  }
+}
+
+/** Whether `role` holds the group `item` lives in. */
+export function mayHoldKeychainItem(role: KeychainRole, item: KeychainItemClass): boolean {
+  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. */
+export function keychainAccessFromDefaultGroup(defaultGroup: string): KeychainAccess {
+  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: KeychainRole =
+    group === KEYCHAIN_ACCESS_GROUPS.identity
+      ? 'holder'
+      : group === KEYCHAIN_ACCESS_GROUPS.wallet
+        ? 'wallet'
+        : 'member';
+  return { mode: 'grouped', prefix, defaultGroup, role };
+}
+
+let resolvedAccess: KeychainAccess | null = 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".
+ */
+export async function resolveKeychainAccess(): Promise<KeychainAccess> {
+  if (resolvedAccess) {
+    return resolvedAccess;
+  }
+  if (!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: KeychainDefaultAccessGroup;
+  try {
+    probe = await 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 */
+export function resetKeychainAccessForTests(): void {
+  resolvedAccess = null;
+}
+
+/** The full `kSecAttrAccessGroup` value of `group`, or `undefined` when ungrouped. */
+export function keychainAccessGroupValue(
+  access: KeychainAccess,
+  group: KeychainAccessGroupName,
+): string | undefined {
+  return access.mode === 'grouped' ? `${access.prefix}${KEYCHAIN_ACCESS_GROUPS[group]}` : undefined;
+}
+
+function option(value: string | undefined): KeychainGroupOption {
+  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.
+ */
+export function keychainReadPlan(
+  access: KeychainAccess,
+  item: KeychainItemClass,
+): KeychainGroupOption[] {
+  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.
+ */
+export function keychainDeletePlan(
+  access: KeychainAccess,
+  item: KeychainItemClass,
+): KeychainGroupOption[] {
+  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.
+ */
+export function keychainWriteOption(
+  access: KeychainAccess,
+  item: KeychainItemClass,
+): KeychainGroupOption {
+  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.
+ */
+export function ownKeychainItemPlan(access: KeychainAccess): {
+  read: KeychainGroupOption[];
+  write: KeychainGroupOption;
+  delete: KeychainGroupOption[];
+} {
+  if (access.mode === 'ungrouped' || access.role === 'member') {
+    return { read: [{}], write: {}, delete: [{}] };
+  }
+  return {
+    read: [option(access.defaultGroup), {}],
+    write: option(access.defaultGroup),
+    delete: [{}],
+  };
+}
+
+/** The subset of `expo-secure-store` a grouped store wraps. */
+export interface KeychainStoreLike {
+  getItemAsync(key: string, options?: object): Promise<string | null>;
+  setItemAsync(key: string, value: string, options?: object): Promise<void>;
+  deleteItemAsync(key: string, options?: object): Promise<void>;
+}
+
+/** Read `key` through `plan`: the first non-null answer. A thrown read propagates. */
+export async function readThroughPlan(
+  store: KeychainStoreLike,
+  key: string,
+  options: object,
+  plan: readonly KeychainGroupOption[],
+): Promise<string | null> {
+  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. */
+export async function deleteThroughPlan(
+  store: KeychainStoreLike,
+  key: string,
+  options: object,
+  plan: readonly KeychainGroupOption[],
+): Promise<void> {
+  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.
+ */
+export function groupedKeychainStore<S extends KeychainStoreLike>(
+  store: S,
+  access: KeychainAccess,
+  item: KeychainItemClass,
+): S {
+  const plan = keychainReadPlan(access, item);
+  const wrapped: KeychainStoreLike = {
+    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) as S, wrapped);
+}

package/src/types/expo-secure-store.d.ts

@@ -1,21 +0,0 @@
-declare module 'expo-secure-store' {
-  export interface SecureStoreOptions {
-    keychainAccessible?: number;
-    keychainAccessGroup?: string;
-    keychainService?: string;
-    requireAuthentication?: boolean;
-  }
-
-  export const WHEN_UNLOCKED: number;
-  export const AFTER_FIRST_UNLOCK: number;
-  export const WHEN_UNLOCKED_THIS_DEVICE_ONLY: number;
-  export const AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY: number;
-
-  export function getItemAsync(key: string, options?: SecureStoreOptions): Promise<string | null>;
-  export function setItemAsync(
-    key: string,
-    value: string,
-    options?: SecureStoreOptions,
-  ): Promise<void>;
-  export function deleteItemAsync(key: string, options?: SecureStoreOptions): Promise<void>;
-}