@oxy.so/core 7.28.0 → 7.30.0

package/src/crypto/keyManager.ts

@@ -32,6 +32,22 @@ import { isDev, logger } from '../logger';
 import { deriveScopedSeedFromKey, signSocialReceiveDigest } from './identityDerivations';
 import { type IdentitySignerStore, registerIdentitySignerStore } from './identitySigner';
 import { getOrganizationPrivateKey, isOrganizationAccountId } from './organizationKeys';
+import { forgetRetiredIdentityKeys, getRetiredPrivateKey, retiredKeyScope } from './retiredKeys';
+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 +69,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 +166,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 +181,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 +200,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 +266,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 +275,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 +286,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 +858,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 +949,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 +1006,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 +1037,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 +1088,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 +1130,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 +1240,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);
     }
@@ -2627,6 +2612,16 @@ export class KeyManager {
     if (force) {
       await KeyManager._bestEffortDeleteBackupsAllGenerations(store);
       await KeyManager._clearSharedSlot(store);
+      // The person's retired keys go with the identity they belonged to.
+      try {
+        await forgetRetiredIdentityKeys();
+      } catch (error) {
+        logger.warn(
+          'Failed to clear retired keys during delete',
+          { component: 'KeyManager' },
+          error,
+        );
+      }
     }
 
     // The device backup goes on EVERY delete, forced or not: it is restored
@@ -3230,7 +3225,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
@@ -3244,18 +3240,37 @@ export class KeyManager {
    * keychain group, or Commons' identity host. It never falls back to the
    * personal key.
    *
+   * With `opts.publicKey` the seed is derived from the key of that account
+   * (personal, or `accountId`'s) whose public key it names: the current key
+   * when it matches, else a RETIRED key Commons kept after a rotation or
+   * replacement (`./retiredKeys`, ADR 0061 D7 as amended). Spending only: a
+   * retired key never signs in. Never falls back to another key.
+   *
    * @param info Context/domain-binding label (distinct labels → independent seeds).
    * @param opts.accountId An organization's account id, for its key.
+   * @param opts.publicKey Selects one key of that account by its public key.
    * @returns 32 bytes of derived keying material, or `null` on web / when no
    *          identity key is available to this app.
    */
   static async deriveScopedSeed(
     info: string,
-    opts?: { accountId?: string },
+    opts?: { accountId?: string; publicKey?: string },
   ): Promise<Uint8Array | null> {
     if (isWebPlatform()) {
       return null;
     }
+    if (opts?.publicKey !== undefined) {
+      if (isAndroid() && !KeyManager.identitySignerStore) {
+        const selected = KeyManager._selectorKey(opts.publicKey);
+        if (!selected) return null;
+        const bridge = await loadCommonsIdentityBridge();
+        const seed =
+          (await bridge?.deriveRetiredScopedSeed?.(info, selected, opts.accountId)) ?? null;
+        return seed ? hexToBytes(seed) : null;
+      }
+      const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+      return selected ? deriveScopedSeedFromKey(selected, info) : null;
+    }
     if (opts?.accountId !== undefined) {
       return KeyManager._deriveOrganizationScopedSeed(info, opts.accountId);
     }
@@ -3307,7 +3322,8 @@ export class KeyManager {
    * compressed public key for the scriptSig.
    *
    * Key source: as {@link deriveScopedSeed}, including `opts.accountId` for an
-   * organization's key (ADR 0061 D6). On Android outside Commons the signature
+   * organization's key (ADR 0061 D6) and `opts.publicKey` for one key of the
+   * account, current or retired. On Android outside Commons the signature
    * comes from Commons, which allows it for the wallet app only.
    *
    * @returns the signature, or `null` on web / when no identity key is
@@ -3316,11 +3332,24 @@ export class KeyManager {
   static async signSocialReceive(
     index: number,
     digest: string,
-    opts?: { accountId?: string },
+    opts?: { accountId?: string; publicKey?: string },
   ): Promise<CommonsSocialReceiveSignature | null> {
     if (isWebPlatform()) {
       return null;
     }
+    if (opts?.publicKey !== undefined) {
+      if (isAndroid() && !KeyManager.identitySignerStore) {
+        const selected = KeyManager._selectorKey(opts.publicKey);
+        if (!selected) return null;
+        const bridge = await loadCommonsIdentityBridge();
+        return (
+          (await bridge?.signRetiredSocialReceive?.(index, digest, selected, opts.accountId)) ??
+          null
+        );
+      }
+      const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+      return selected ? signSocialReceiveDigest(selected, index, digest) : null;
+    }
     const accountId = opts?.accountId;
     if (accountId !== undefined) {
       // An organization key (ADR 0061 D6); never the personal one in its place.
@@ -3345,6 +3374,40 @@ export class KeyManager {
     return local ? signSocialReceiveDigest(local, index, digest) : null;
   }
 
+  /**
+   * The private key of the account (personal, or `accountId`'s organization)
+   * whose public key is `publicKey`, from this app's own storage: the current
+   * key when it matches, else the retired ring. iOS and Commons only; `null`
+   * for a key this device does not hold. Never another key in its place. @internal
+   */
+  /**
+   * The selector in the identity host's encoding (lowercase uncompressed), so a
+   * compressed `#key-1` from a DID or a gateway row selects the same key. @internal
+   */
+  private static _selectorKey(publicKey: string): string | null {
+    return KeyManager.isValidPublicKey(publicKey) ? KeyManager.canonicalPublicKey(publicKey) : null;
+  }
+
+  private static async _selectedPrivateKey(
+    publicKey: string,
+    accountId?: string,
+  ): Promise<string | null> {
+    if (retiredKeyScope({ accountId }) === null || !KeyManager.isValidPublicKey(publicKey)) {
+      return null;
+    }
+    const wanted = KeyManager.canonicalPublicKey(publicKey);
+    const current =
+      accountId !== undefined
+        ? await getOrganizationPrivateKey(accountId)
+        : isAndroid()
+          ? await KeyManager.getPrivateKey()
+          : ((await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey()));
+    if (current && KeyManager.canonicalPublicKey(KeyManager.derivePublicKey(current)) === wanted) {
+      return current;
+    }
+    return getRetiredPrivateKey(wanted, accountId !== undefined ? { accountId } : undefined);
+  }
+
   /**
    * Get a shortened version of the public key for display
    * Format: first 8 chars...last 8 chars