@oxy.so/core 7.28.0 → 7.29.0

package/dist/types/crypto/secureStoreOptions.d.ts

@@ -0,0 +1,15 @@
+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;
+}

package/dist/types/session/index.d.ts

@@ -29,6 +29,8 @@ export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthSt
 export type { PersistedAuthState, AuthStateStore, AuthStateWriteGuard, NativeKeyValueStorage, } from './authStateStore';
 export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './sharedDeviceCredential';
 export type { SharedDeviceCredential, SharedDeviceCredentialRead, SharedDeviceCredentialStore, SharedDeviceJoinDecision, SharedDeviceJoinSkipReason, SharedDevicePublishDecision, SharedDevicePublishOutcome, SharedDevicePublishSkipReason, } from './sharedDeviceCredential';
+export { KeychainAccessUnavailableError, keychainAccessGroupValue, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, resolveKeychainAccess, } from '../utils/keychainAccessGroups';
+export type { KeychainAccess, KeychainGroupOption } from '../utils/keychainAccessGroups';
 export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './identityPin';
 export type { IdentityPin, IdentityPinStore } from './identityPin';
 export { resolveIdentityPin, establishIdentitySession, } from './identitySession';

package/dist/types/utils/keychainAccessGroups.d.ts

@@ -0,0 +1,104 @@
+/** The group names after the team prefix, exactly as the entitlements list them. */
+export declare const KEYCHAIN_ACCESS_GROUPS: {
+    readonly identity: "so.oxy.identity";
+    readonly wallet: "so.oxy.wallet";
+    readonly shared: "group.so.oxy.shared";
+};
+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 declare class KeychainAccessUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "KeychainAccessUnavailableError";
+    constructor(cause?: unknown | undefined);
+}
+/**
+ * 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 declare function keychainGroupFor(item: KeychainItemClass): KeychainAccessGroupName;
+/** Whether `role` holds the group `item` lives in. */
+export declare function mayHoldKeychainItem(role: KeychainRole, item: KeychainItemClass): boolean;
+/** Parse the default access group the probe reported. Exported for tests. */
+export declare function keychainAccessFromDefaultGroup(defaultGroup: string): KeychainAccess;
+/**
+ * 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 declare function resolveKeychainAccess(): Promise<KeychainAccess>;
+/** Forget the memoized access. Tests only. @internal */
+export declare function resetKeychainAccessForTests(): void;
+/** The full `kSecAttrAccessGroup` value of `group`, or `undefined` when ungrouped. */
+export declare function keychainAccessGroupValue(access: KeychainAccess, group: KeychainAccessGroupName): string | undefined;
+/**
+ * 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 declare function keychainReadPlan(access: KeychainAccess, item: KeychainItemClass): KeychainGroupOption[];
+/**
+ * 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 declare function keychainDeletePlan(access: KeychainAccess, item: KeychainItemClass): KeychainGroupOption[];
+/**
+ * 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 declare function keychainWriteOption(access: KeychainAccess, item: KeychainItemClass): KeychainGroupOption;
+/**
+ * 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 declare function ownKeychainItemPlan(access: KeychainAccess): {
+    read: KeychainGroupOption[];
+    write: KeychainGroupOption;
+    delete: KeychainGroupOption[];
+};
+/** 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 declare function readThroughPlan(store: KeychainStoreLike, key: string, options: object, plan: readonly KeychainGroupOption[]): Promise<string | null>;
+/** Delete `key` from every location in `plan`. A thrown delete propagates. */
+export declare function deleteThroughPlan(store: KeychainStoreLike, key: string, options: object, plan: readonly KeychainGroupOption[]): Promise<void>;
+/**
+ * `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 declare function groupedKeychainStore<S extends KeychainStoreLike>(store: S, access: KeychainAccess, item: KeychainItemClass): S;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.28.0",
+  "version": "7.29.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -182,7 +182,7 @@
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
     "@oxy.so/contracts": "^6.11.0",
-    "@oxy.so/protocol": "^1.7.0",
+    "@oxy.so/protocol": "^1.8.0",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^2.4.0",
     "buffer": "^6.0.3",

package/src/crypto/index.ts

@@ -45,6 +45,35 @@ export type {
   GeneratedOrganizationKey,
   StoredOrganizationKey,
 } from './organizationKeys';
+// 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';
+export type {
+  KeychainAccess,
+  KeychainAccessGroupName,
+  KeychainGroupOption,
+  KeychainItemClass,
+  KeychainRole,
+  KeychainStoreLike,
+} from '../utils/keychainAccessGroups';
+export { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+export type {
+  KeychainGroupMigrationReport,
+  KeychainItemMigrationOutcome,
+} from './keychainGroupMigration';
 export { SignatureService } from './signatureService';
 export type { SignedMessage, AuthChallenge } from './signatureService';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase';

package/src/crypto/keyManager.ts

@@ -32,6 +32,21 @@ import { isDev, logger } from '../logger';
 import { deriveScopedSeedFromKey, signSocialReceiveDigest } from './identityDerivations';
 import { type IdentitySignerStore, registerIdentitySignerStore } from './identitySigner';
 import { getOrganizationPrivateKey, isOrganizationAccountId } from './organizationKeys';
+import {
+  type KeychainItemClass,
+  groupedKeychainStore,
+  resolveKeychainAccess,
+} from '../utils/keychainAccessGroups';
+import { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+import {
+  RECOVERY_MNEMONIC_KEYCHAIN_SERVICE,
+  RECOVERY_MNEMONIC_STORAGE_KEY,
+  STORAGE_KEYS,
+  V2_BACKUP_KEYCHAIN_SERVICE,
+  V2_PRIMARY_KEYCHAIN_SERVICE,
+  V2_STORAGE_KEYS,
+} from './keychainItems';
+import type { OxySecureStoreOptions } from './secureStoreOptions';
 import {
   type IdentityMarker,
   clearIdentityMarker,
@@ -53,37 +68,6 @@ import {
  */
 const DEVICE_BACKUP_TOMBSTONE = JSON.stringify({ deleted: true });
 
-/**
- * Options for expo-secure-store calls made by KeyManager.
- *
- * Defined as a standalone interface (not extending expo-secure-store's
- * `SecureStoreOptions`) so that server / Node.js consumers of @oxy.so/core
- * do not transitively pull in expo-modules-core's type declarations under
- * NodeNext module resolution (which would cause NodeJS.Timeout / number
- * pollution across all timer APIs). The fields mirror SecureStoreOptions
- * exactly — any object satisfying this interface is safe to pass to the
- * real expo-secure-store methods (which accept `options?: object`).
- */
-interface OxySecureStoreOptions {
-  /** Keychain service name (Android keystore / iOS keychain tag). */
-  keychainService?: string;
-  /**
-   * Keychain / Keystore item accessibility. Use the constants from the
-   * `ExpoSecureStoreLike` handle returned by `initSecureStore()`, e.g.
-   * `store.WHEN_UNLOCKED_THIS_DEVICE_ONLY`.
-   */
-  keychainAccessible?: number;
-  /** Prompt shown to the user for biometric/auth-protected items. */
-  authenticationPrompt?: string;
-  /** Whether Face ID / Touch ID / biometric auth is required to read the item. */
-  requireAuthentication?: boolean;
-  /**
-   * iOS Keychain access group. Required for sharing identity material across
-   * apps in the Oxy ecosystem via Keychain Sharing entitlements.
-   */
-  keychainAccessGroup?: string;
-}
-
 /**
  * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
  * is invoked while a valid identity already exists on the device.
@@ -181,17 +165,6 @@ export type IdentityRecoveryResult =
   | { recovered: true; source: 'backup' | 'shared' | 'device-backup'; publicKey: string }
   | { recovered: false; reason: 'not-lost' | 'no-sources' | 'mismatch' | 'unavailable' };
 
-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',
-} as const;
-
 /**
  * v2 identity slot layout — blast-radius isolation.
  *
@@ -207,16 +180,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',
-} as const;
+// 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).
@@ -234,8 +199,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.
@@ -301,13 +265,6 @@ type SlotMigrationResult =
   | { mode: 'legacy'; layout: ResolvedSlotLayout }
   | { mode: 'deferred'; cause: unknown };
 
-/**
- * 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
  *
@@ -317,7 +274,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(): Promise<ExpoSecureStoreLike> {
+async function loadRawSecureStore(): Promise<ExpoSecureStoreLike> {
   try {
     return await loadSecureStore();
   } catch (error) {
@@ -328,6 +285,31 @@ async function initSecureStore(): Promise<ExpoSecureStoreLike> {
   }
 }
 
+/**
+ * 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: KeychainItemClass): Promise<ExpoSecureStoreLike> {
+  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(): Promise<ExpoSecureStoreLike> {
+  return keychainItemStore('identity-secret');
+}
+
 /**
  * Check if we're on web platform
  * Identity storage is only available on native platforms (iOS/Android)
@@ -875,13 +857,15 @@ export class KeyManager {
    * Android signer store is cleared on every delete, in {@link deleteIdentity}.
    */
   private static async _clearSharedSlot(
-    store: Awaited<ReturnType<typeof initSecureStore>>,
+    _identityStore: Awaited<ReturnType<typeof initSecureStore>>,
   ): Promise<void> {
     try {
       if (isIOS()) {
-        const opts: OxySecureStoreOptions = { 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();
     } catch (error) {
@@ -964,6 +948,25 @@ export class KeyManager {
     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
+   */
+  private static async _writeIosSharedSlot(privateKey: string, publicKey: string): Promise<void> {
+    const privateStore = await keychainItemStore('spending-key');
+    const privateOpts: OxySecureStoreOptions = {
+      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.
    *
@@ -1002,8 +1005,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
@@ -1031,22 +1036,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: OxySecureStoreOptions = {
-          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: OxySecureStoreOptions = {
-          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}`,
+          `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()) {
@@ -1093,9 +1087,8 @@ export class KeyManager {
       let publicKey: string | null = null;
 
       if (isIOS()) {
-        const store = await initSecureStore();
-        const opts: OxySecureStoreOptions = { 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;
         if (signer) {
@@ -1136,9 +1129,10 @@ export class KeyManager {
     }
 
     try {
-      const store = await initSecureStore();
-      const opts: OxySecureStoreOptions = { 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()) {
         logger.warn('Failed to get shared private key', { component: 'KeyManager' }, error);
@@ -1245,17 +1239,7 @@ export class KeyManager {
     const publicKey = deriveSecp256k1PublicKey(canonicalPrivate);
 
     if (isIOS()) {
-      const store = await initSecureStore();
-      const privateOpts: OxySecureStoreOptions = {
-        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
-        keychainAccessGroup: IOS_KEYCHAIN_GROUP,
-      };
-      await store.setItemAsync(STORAGE_KEYS.SHARED_PRIVATE_KEY, canonicalPrivate, privateOpts);
-
-      const publicOpts: OxySecureStoreOptions = {
-        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);
     }
@@ -3230,7 +3214,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