@oxy.so/core 7.28.0 → 7.29.0

package/dist/cjs/crypto/organizationKeys.js

@@ -9,8 +9,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
@@ -18,13 +20,13 @@
  *
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isOrganizationAccountId = isOrganizationAccountId;
+exports.isOrganizationAccountId = void 0;
 exports.isHealthyOrganizationKeyPair = isHealthyOrganizationKeyPair;
 exports.generateOrganizationKey = generateOrganizationKey;
 exports.organizationKeyFromPhrase = organizationKeyFromPhrase;
@@ -40,29 +42,18 @@ const english_js_1 = require("@scure/bip39/wordlists/english.js");
 const protocol_1 = require("@oxy.so/protocol");
 const secp256k1_1 = require("@oxy.so/protocol/secp256k1");
 const logger_1 = require("../logger");
+const keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
 const platform_1 = require("../utils/platform");
 const identitySigner_1 = require("./identitySigner");
-/** 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 keychainGroupMigration_1 = require("./keychainGroupMigration");
+const keychainItems_1 = require("./keychainItems");
+Object.defineProperty(exports, "isOrganizationAccountId", { enumerable: true, get: function () { return keychainItems_1.isOrganizationAccountId; } });
 const ORGANIZATION_PHRASE_WORDS = 24;
-/** Whether `value` is an account id an organization key can be stored under. */
-function isOrganizationAccountId(value) {
-    return ACCOUNT_ID.test(value);
-}
 function assertAccountId(accountId) {
-    if (!isOrganizationAccountId(accountId)) {
+    if (!(0, keychainItems_1.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('');
 }
@@ -115,19 +106,33 @@ async function generateOrganizationKey() {
 async function organizationKeyFromPhrase(phrase) {
     return pairFromPhrase(phrase);
 }
-async function secureStore() {
-    return (0, protocol_1.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 (0, protocol_1.loadSecureStore)();
+    const access = await (0, keychainAccessGroups_1.resolveKeychainAccess)();
+    if (access.mode === 'grouped' && access.role === 'holder') {
+        await (0, keychainGroupMigration_1.ensureKeychainGroupsMigrated)();
+    }
+    return (0, keychainAccessGroups_1.groupedKeychainStore)(raw, access, item);
 }
+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,
+    const raw = await store.getItemAsync(keychainItems_1.ORGANIZATION_INDEX_STORAGE_KEY, {
+        keychainService: keychainItems_1.ORGANIZATION_INDEX_KEYCHAIN_SERVICE,
     });
     if (!raw)
         return [];
     try {
         const parsed = JSON.parse(raw);
         return Array.isArray(parsed)
-            ? parsed.filter((id) => typeof id === 'string' && isOrganizationAccountId(id))
+            ? parsed.filter((id) => typeof id === 'string' && (0, keychainItems_1.isOrganizationAccountId)(id))
             : [];
     }
     catch (error) {
@@ -139,26 +144,24 @@ async function readIndex(store) {
     }
 }
 async function writeIndex(store, ids) {
-    await store.setItemAsync(INDEX_STORAGE_KEY, JSON.stringify([...new Set(ids)].sort()), {
-        keychainService: INDEX_KEYCHAIN_SERVICE,
+    await store.setItemAsync(keychainItems_1.ORGANIZATION_INDEX_STORAGE_KEY, (0, keychainItems_1.serializeOrganizationIndex)(ids), {
+        keychainService: keychainItems_1.ORGANIZATION_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 ((0, platform_1.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
         ? {
             keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-            keychainService: ANDROID_KEYCHAIN_SERVICE,
+            keychainService: keychainItems_1.ORGANIZATION_ANDROID_KEYCHAIN_SERVICE,
         }
-        : { keychainService: ANDROID_KEYCHAIN_SERVICE };
+        : { keychainService: keychainItems_1.ORGANIZATION_ANDROID_KEYCHAIN_SERVICE };
 }
 /** The pair from this app's own storage (iOS group; Android Commons slot, then signer store). */
 async function readLocalPair(accountId) {
@@ -168,10 +171,10 @@ async function readLocalPair(accountId) {
         const signer = (0, identitySigner_1.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);
+        const privateKey = await store.getItemAsync((0, keychainItems_1.organizationPrivateKeyName)(accountId), options);
+        const publicKey = await store.getItemAsync((0, keychainItems_1.organizationPublicKeyName)(accountId), options);
         if (privateKey && publicKey && isHealthyOrganizationKeyPair(privateKey, publicKey)) {
             return {
                 privateKey: (0, secp256k1_1.normalizeSecp256k1PrivateKey)(privateKey),
@@ -186,10 +189,12 @@ async function readLocalPair(accountId) {
     }
     if (!(0, platform_1.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);
+    const privateKey = await store.getItemAsync((0, keychainItems_1.organizationPrivateKeyName)(accountId), options);
+    const publicKey = await store.getItemAsync((0, keychainItems_1.organizationPublicKeyName)(accountId), options);
     return privateKey && publicKey && isHealthyOrganizationKeyPair(privateKey, publicKey)
         ? {
             privateKey: (0, secp256k1_1.normalizeSecp256k1PrivateKey)(privateKey),
@@ -200,7 +205,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
@@ -225,34 +230,36 @@ async function storeOrganizationKey(accountId, key) {
     if ((0, platform_1.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();
-    await store.setItemAsync(privateKeyName(accountId), privateKey, pairOptions(store, true));
-    await store.setItemAsync(publicKeyName(accountId), publicKey, pairOptions(store, false));
+    const store = await pairStore();
+    await store.setItemAsync((0, keychainItems_1.organizationPrivateKeyName)(accountId), privateKey, pairOptions(store, true));
+    await store.setItemAsync((0, keychainItems_1.organizationPublicKeyName)(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), {
-            keychainService: MNEMONIC_KEYCHAIN_SERVICE,
-            keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        await phrases.setItemAsync((0, keychainItems_1.organizationMnemonicName)(accountId), normalizePhrase(key.mnemonic), {
+            keychainService: keychainItems_1.ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE,
+            keychainAccessible: phrases.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
         });
     }
     else {
-        await store.deleteItemAsync(mnemonicName(accountId), {
-            keychainService: MNEMONIC_KEYCHAIN_SERVICE,
+        await phrases.deleteItemAsync((0, keychainItems_1.organizationMnemonicName)(accountId), {
+            keychainService: keychainItems_1.ORGANIZATION_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).
  */
 async function getOrganizationPublicKey(accountId) {
-    if (!isOrganizationAccountId(accountId) || (0, platform_1.isWeb)())
+    if (!(0, keychainItems_1.isOrganizationAccountId)(accountId) || (0, platform_1.isWeb)())
         return null;
     try {
         if ((0, platform_1.isAndroid)() && !(0, identitySigner_1.registeredIdentitySignerStore)()) {
@@ -272,11 +279,11 @@ 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.
  */
 async function getOrganizationPrivateKey(accountId) {
-    if (!isOrganizationAccountId(accountId))
+    if (!(0, keychainItems_1.isOrganizationAccountId)(accountId))
         return null;
     try {
         return (await readLocalPair(accountId))?.privateKey ?? null;
@@ -291,34 +298,35 @@ async function getOrganizationPrivateKey(accountId) {
 }
 /** The organization's phrase, if this device created or imported it with one. Commons only. */
 async function getOrganizationRecoveryPhrase(accountId) {
-    if (!isOrganizationAccountId(accountId) || (0, platform_1.isWeb)())
+    if (!(0, keychainItems_1.isOrganizationAccountId)(accountId) || (0, platform_1.isWeb)())
         return null;
-    const store = await secureStore();
-    return store.getItemAsync(mnemonicName(accountId), {
-        keychainService: MNEMONIC_KEYCHAIN_SERVICE,
+    const store = await phraseStore();
+    return store.getItemAsync((0, keychainItems_1.organizationMnemonicName)(accountId), {
+        keychainService: keychainItems_1.ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE,
     });
 }
 /** The organizations this device keeps a key for (Commons' own index). */
 async function listOrganizationKeys() {
     if ((0, platform_1.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. */
 async function deleteOrganizationKey(accountId) {
     assertAccountId(accountId);
     if ((0, platform_1.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), {
-        keychainService: MNEMONIC_KEYCHAIN_SERVICE,
+    await store.deleteItemAsync((0, keychainItems_1.organizationPrivateKeyName)(accountId), options);
+    await store.deleteItemAsync((0, keychainItems_1.organizationPublicKeyName)(accountId), options);
+    await (await phraseStore()).deleteItemAsync((0, keychainItems_1.organizationMnemonicName)(accountId), {
+        keychainService: keychainItems_1.ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE,
     });
     const signer = (0, platform_1.isAndroid)() ? (0, identitySigner_1.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
@@ -330,12 +338,12 @@ async function syncOrganizationKeys() {
     const signer = (0, platform_1.isAndroid)() ? (0, identitySigner_1.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);
+        const privateKey = await store.getItemAsync((0, keychainItems_1.organizationPrivateKeyName)(accountId), options);
+        const publicKey = await store.getItemAsync((0, keychainItems_1.organizationPublicKeyName)(accountId), options);
         if (!privateKey || !publicKey || !isHealthyOrganizationKeyPair(privateKey, publicKey))
             continue;
         const current = await signer.readOrganization(accountId);

package/dist/cjs/crypto/secureStoreOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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)