@oxy.so/core 7.31.0 → 7.32.0

package/src/crypto/organizationKeys.ts

@@ -47,7 +47,8 @@ import {
 } from '../utils/keychainAccessGroups';
 import { isAndroid, isIOS, isWeb } from '../utils/platform';
 import { registeredIdentitySignerStore } from './identitySigner';
-import { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+import { prepareKeychainAccess } from './keychainGroupMigration';
+import { retireIdentityKey } from './retiredKeys';
 import {
   ORGANIZATION_ANDROID_KEYCHAIN_SERVICE as ANDROID_KEYCHAIN_SERVICE,
   ORGANIZATION_INDEX_KEYCHAIN_SERVICE as INDEX_KEYCHAIN_SERVICE,
@@ -158,9 +159,7 @@ export async function organizationKeyFromPhrase(phrase: string): Promise<Organiz
 async function secureStore(item: KeychainItemClass): Promise<ExpoSecureStoreLike> {
   const raw = await loadSecureStore();
   const access = await resolveKeychainAccess();
-  if (access.mode === 'grouped' && access.role === 'holder') {
-    await ensureKeychainGroupsMigrated();
-  }
+  await prepareKeychainAccess(access);
   return groupedKeychainStore(raw, access, item);
 }
 
@@ -252,8 +251,10 @@ async function readLocalPair(accountId: string): Promise<OrganizationKeyPair | n
  * 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
- * the organization (a replaced key is the caller's decision, ADR 0061 D7).
+ * phrase that does not derive the pair. A DIFFERENT key this device already
+ * held for the organization is first kept in the organization's retired ring
+ * (ADR 0061 D7 as amended; R4-12): coins under it still need it. When that
+ * cannot be confirmed nothing is overwritten and this throws.
  */
 export async function storeOrganizationKey(
   accountId: string,
@@ -280,6 +281,19 @@ export async function storeOrganizationKey(
     );
   }
   const store = await pairStore();
+  const previous = await heldPrivateKey(store, accountId);
+  if (previous) {
+    const previousPublic = deriveSecp256k1PublicKey(previous);
+    if (previousPublic !== publicKey) {
+      try {
+        await retireIdentityKey({ privateKey: previous, publicKey: previousPublic }, { accountId });
+      } catch (error) {
+        throw new Error(
+          `organization key: the key this device held could not be kept as a previous key, so it was not replaced (${error instanceof Error ? error.message : 'unknown'})`,
+        );
+      }
+    }
+  }
   await store.setItemAsync(privateKeyName(accountId), privateKey, pairOptions(store, true));
   await store.setItemAsync(publicKeyName(accountId), publicKey, pairOptions(store, false));
   if (
@@ -362,6 +376,24 @@ export async function listOrganizationKeys(): Promise<string[]> {
   return readIndex(await indexStore());
 }
 
+/**
+ * The private key this device holds for `accountId`, whatever its public half
+ * says (an unhealthy pair is still a key coins may sit under): the slot, then
+ * on Android the signer store's copy. `null` when there is none.
+ */
+async function heldPrivateKey(
+  store: ExpoSecureStoreLike,
+  accountId: string,
+): Promise<string | null> {
+  const local = await store.getItemAsync(privateKeyName(accountId), pairOptions(store, false));
+  if (local && isValidSecp256k1PrivateKey(local)) return normalizeSecp256k1PrivateKey(local);
+  const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+  const mirrored = (await signer?.readOrganization?.(accountId)) ?? null;
+  return mirrored && isValidSecp256k1PrivateKey(mirrored.privateKey)
+    ? normalizeSecp256k1PrivateKey(mirrored.privateKey)
+    : null;
+}
+
 /** 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);

package/src/crypto/retiredKeys.ts

@@ -60,8 +60,8 @@ import { logger } from '../logger';
 import { groupedKeychainStore, resolveKeychainAccess } from '../utils/keychainAccessGroups';
 import { isAndroid, isIOS, isWeb } from '../utils/platform';
 import { registeredIdentitySignerStore } from './identitySigner';
-import { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
-import { isOrganizationAccountId } from './organizationKeys';
+import { isOrganizationAccountId } from './keychainItems';
+import { prepareKeychainAccess } from './keychainGroupMigration';
 import type { OxySecureStoreOptions as SecureStoreOptions } from './secureStoreOptions';
 
 /** Whose ring: the person's (`accountId` absent) or an organization's. */
@@ -97,15 +97,14 @@ const PUBLIC_KEY = /^04[0-9a-f]{128}$/;
  * The secure store for the ring. On iOS every item is a `spending-key`
  * (ADR 0062): the private keys AND the index live in the wallet group, which
  * only Commons and the Peable wallet can read, never the shared one. In
- * Commons every access first awaits the access-group migration. On Android
- * the grouping is a no-op and Commons' own services below apply.
+ * Commons every access first awaits the access-group migration (`gate: false`
+ * is the migration itself, keeping a pre-split copy). On Android the grouping
+ * is a no-op and Commons' own services below apply.
  */
-async function ringStore(): Promise<ExpoSecureStoreLike> {
+async function ringStore(gate = true): Promise<ExpoSecureStoreLike> {
   const raw = await loadSecureStore();
   const access = await resolveKeychainAccess();
-  if (access.mode === 'grouped' && access.role === 'holder') {
-    await ensureKeychainGroupsMigrated();
-  }
+  if (gate) await prepareKeychainAccess(access);
   return groupedKeychainStore(raw, access, 'spending-key');
 }
 
@@ -213,14 +212,25 @@ function toListed(entry: IndexEntry): RetiredIdentityKey {
     : { publicKey: entry.publicKey, accountId: entry.scope, retiredAt: entry.retiredAt };
 }
 
-/** Whether this app writes the ring: Commons (Android: the signer store it registers; iOS: native). */
-function assertMayWrite(): void {
+/**
+ * Whether this app writes the ring: Commons only (Android: the signer store it
+ * registers; iOS: the keychain role `holder`). The Peable wallet holds the
+ * wallet group too, but only reads, derives and signs: a key the wallet could
+ * add to the ring is a key it could choose (R4-14).
+ */
+async function assertMayWrite(): Promise<void> {
   if (isWeb()) throw new Error('retired key: only a native device holds one');
   if (isAndroid() && !registeredIdentitySignerStore()?.writeRetired) {
     throw new Error(
       'On Android only Commons holds retired keys; this app has no identity signer store for them.',
     );
   }
+  if (isIOS()) {
+    const access = await resolveKeychainAccess();
+    if (access.mode === 'grouped' && access.role !== 'holder') {
+      throw new Error('On iOS only Commons writes retired keys; this app may only read them.');
+    }
+  }
 }
 
 /**
@@ -233,16 +243,36 @@ function assertMayWrite(): void {
 export async function retireIdentityKey(
   key: RetiredKeyPair,
   selector?: RetiredKeySelector,
+): Promise<void> {
+  await keepRetired(key, selector, true);
+}
+
+/**
+ * {@link retireIdentityKey} from inside the iOS access-group migration, which
+ * keeps a replaced pre-split copy before deleting it from the shared group and
+ * cannot await itself. @internal
+ */
+export async function retireIdentityKeyDuringMigration(
+  key: RetiredKeyPair,
+  selector?: RetiredKeySelector,
+): Promise<void> {
+  await keepRetired(key, selector, false);
+}
+
+async function keepRetired(
+  key: RetiredKeyPair,
+  selector: RetiredKeySelector | undefined,
+  gate: boolean,
 ): Promise<void> {
   const scope = retiredKeyScope(selector);
   if (!scope) throw new Error('retired key: accountId must be a 24-hex or uuid account id');
-  assertMayWrite();
+  await assertMayWrite();
   if (!isHealthyPair(key.privateKey, key.publicKey)) {
     throw new Error('retired key: the public key does not derive from the private key');
   }
   const privateKey = normalizeSecp256k1PrivateKey(key.privateKey);
   const publicKey = normalizeSecp256k1PublicKey(key.publicKey);
-  const store = await ringStore();
+  const store = await ringStore(gate);
   await store.setItemAsync(
     privateKeyName(scope, publicKey),
     privateKey,
@@ -357,7 +387,7 @@ export async function forgetRetiredIdentityKey(
   const scope = retiredKeyScope(selector);
   const canonical = canonicalPublicKey(publicKey);
   if (!scope || !canonical) throw new Error('retired key: invalid selector or public key');
-  assertMayWrite();
+  await assertMayWrite();
   const store = await ringStore();
   await store.deleteItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
   const signer = isAndroid() ? registeredIdentitySignerStore() : null;
@@ -371,10 +401,12 @@ export async function forgetRetiredIdentityKey(
 }
 
 /**
- * Forget every retired key of one ring (the person's, or an organization's):
- * called when the identity itself is deleted from this device, so a phone
- * handed on keeps none of the person's old keys. Commons only. Resolves how
- * many it removed.
+ * Forget every retired key of one ring (the person's, or an organization's).
+ * Commons only, and only when the person deletes their Oxy ACCOUNT (Commons'
+ * delete-account flow), which tells them the coins go with it. Deleting the
+ * identity from this device — "Start over", a forced delete — never calls it:
+ * the ring is money, and the same person restoring their identity later must
+ * find it (R4-4). Resolves how many it removed.
  */
 export async function forgetRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<number> {
   const scope = retiredKeyScope(selector);
@@ -432,6 +464,44 @@ export async function syncRetiredKeys(): Promise<number> {
   return mirrored;
 }
 
+/**
+ * Every retired key of `selector`'s ring WITH its private half, for the
+ * encrypted identity backup (`oxy.identity.backup.create`), which carries them
+ * under the CURRENT phrase so a lost phone costs no more than the current
+ * phrase does (R4-4). Commons only; an entry whose private half is missing or
+ * does not derive its public key is left out. Never log or transmit the result
+ * except inside that encrypted envelope.
+ */
+export async function exportRetiredIdentityKeys(
+  selector?: RetiredKeySelector,
+): Promise<Array<RetiredKeyPair & { retiredAt: number }>> {
+  const scope = retiredKeyScope(selector);
+  if (!scope || isWeb()) return [];
+  await assertMayWrite();
+  const out: Array<RetiredKeyPair & { retiredAt: number }> = [];
+  for (const entry of await listRetiredIdentityKeys(selector)) {
+    const privateKey = await getRetiredPrivateKey(entry.publicKey, selector);
+    if (privateKey)
+      out.push({ privateKey, publicKey: entry.publicKey, retiredAt: entry.retiredAt });
+  }
+  return out;
+}
+
+/**
+ * The pair a previous key's raw PRIVATE KEY gives (64 hex, an optional `0x`),
+ * for a person whose old identity was imported as a private key and so has no
+ * phrase to re-enter. Stores nothing: the caller checks the public key against
+ * the account's key history and only then calls {@link retireIdentityKey}.
+ */
+export function retiredKeyFromPrivateKey(privateKeyHex: string): RetiredKeyPair {
+  const trimmed = privateKeyHex.trim().toLowerCase().replace(/^0x/, '');
+  if (!/^[0-9a-f]{64}$/.test(trimmed) || !isValidSecp256k1PrivateKey(trimmed)) {
+    throw new Error('retired key: not a valid private key');
+  }
+  const privateKey = normalizeSecp256k1PrivateKey(trimmed);
+  return { privateKey, publicKey: publicKeyOf(privateKey) };
+}
+
 /**
  * The pair a previous recovery phrase derives (`seed[0:32]`, the personal-root
  * and organization-key derivation; 12–24 words). Stores nothing: the caller

package/src/utils/keychainAccessGroups.ts

@@ -56,6 +56,16 @@ export const KEYCHAIN_ACCESS_GROUPS = {
   shared: 'group.so.oxy.shared',
 } as const;
 
+/**
+ * The suffix a DEVELOPMENT build's restricted groups carry (`so.oxy.commons.dev`,
+ * `to.peable.app.dev`: `so.oxy.identity.dev`, `so.oxy.wallet.dev`). A dev build
+ * sits beside the production app on the same phone, is signed by the same team
+ * and runs JavaScript from a dev server, so it never shares a restricted group
+ * with production (`@oxy.so/app-preset` enforces the entitlements). The shared
+ * group has no variant: it holds nothing secret.
+ */
+export const DEV_KEYCHAIN_GROUP_SUFFIX = '.dev' as const;
+
 export type KeychainAccessGroupName = keyof typeof KEYCHAIN_ACCESS_GROUPS;
 
 /**
@@ -85,6 +95,8 @@ export type KeychainAccess =
       defaultGroup: string;
       role: KeychainRole;
       appGroup?: string;
+      /** {@link DEV_KEYCHAIN_GROUP_SUFFIX} for a dev build; absent for production. */
+      variant?: typeof DEV_KEYCHAIN_GROUP_SUFFIX;
     }
   | { mode: 'ungrouped' };
 
@@ -120,6 +132,17 @@ export function keychainGroupFor(item: KeychainItemClass): KeychainGroup {
   }
 }
 
+/**
+ * Whether `role` may WRITE `item`. Only Commons writes a secret: the Peable
+ * wallet reads, derives and signs with spending keys (and the retired ring)
+ * but never adds one — a key the wallet could add is one the wallet could
+ * choose. (The keychain itself lets every app in the wallet group write it;
+ * this is the SDK's half, and readers check what they find, ADR 0062.)
+ */
+export function mayWriteKeychainItem(role: KeychainRole, item: KeychainItemClass): boolean {
+  return role === 'holder' || item === 'shared' || item === 'app';
+}
+
 /** Whether `role` holds the group `item` lives in. */
 export function mayHoldKeychainItem(role: KeychainRole, item: KeychainItemClass): boolean {
   switch (role) {
@@ -147,15 +170,19 @@ export function keychainAccessFromDefaultGroup(
   }
   const prefix = defaultGroup.slice(0, dot + 1);
   const group = defaultGroup.slice(dot + 1);
+  const dev = group.endsWith(DEV_KEYCHAIN_GROUP_SUFFIX);
+  const base = dev ? group.slice(0, -DEV_KEYCHAIN_GROUP_SUFFIX.length) : group;
   const role: KeychainRole =
-    group === KEYCHAIN_ACCESS_GROUPS.identity
+    base === KEYCHAIN_ACCESS_GROUPS.identity
       ? 'holder'
-      : group === KEYCHAIN_ACCESS_GROUPS.wallet
+      : base === KEYCHAIN_ACCESS_GROUPS.wallet
         ? 'wallet'
         : 'member';
+  // A `.dev` suffix on anything but a restricted group is not a variant.
+  const variant = dev && role !== 'member' ? { variant: DEV_KEYCHAIN_GROUP_SUFFIX } : {};
   return appGroup?.startsWith(prefix)
-    ? { mode: 'grouped', prefix, defaultGroup, role, appGroup }
-    : { mode: 'grouped', prefix, defaultGroup, role };
+    ? { mode: 'grouped', prefix, defaultGroup, role, appGroup, ...variant }
+    : { mode: 'grouped', prefix, defaultGroup, role, ...variant };
 }
 
 let resolvedAccess: KeychainAccess | null = null;
@@ -212,9 +239,11 @@ export async function resolveKeychainAccess(): Promise<KeychainAccess> {
   return resolvedAccess;
 }
 
-/** Forget the memoized access. Tests only. @internal */
+/** Forget the memoized access and the fallback state. Tests only. @internal */
 export function resetKeychainAccessForTests(): void {
   resolvedAccess = null;
+  holderSharedFallback = false;
+  walletSharedFallbackClosed = false;
 }
 
 /**
@@ -236,7 +265,46 @@ export function keychainAccessGroupValue(
     // default is the shared group: no group, the calls it always made.
     return access.appGroup ?? (access.role === 'member' ? undefined : access.defaultGroup);
   }
-  return `${access.prefix}${KEYCHAIN_ACCESS_GROUPS[group]}`;
+  const variant = group === 'shared' ? '' : (access.variant ?? '');
+  return `${access.prefix}${KEYCHAIN_ACCESS_GROUPS[group]}${variant}`;
+}
+
+/**
+ * Whether a SECRET read may still fall back to the pre-split shared group
+ * (R4-7). Every Oxy app can write that group, and keychain items survive an
+ * uninstall, so a secret found there is one Commons did not necessarily write.
+ *
+ * - Commons (`holder`): CLOSED, except while its one-shot migration has proved
+ *   the shared copies are its own (they carry the key its sandbox marker
+ *   records) and could not move them all yet; the migration opens it for that
+ *   launch only ({@link setHolderSharedSecretFallback}).
+ * - The Peable wallet: open until Commons' migration has finished (the
+ *   completion record Commons mirrors into the wallet group), because until
+ *   then an upgraded phone's keys are still in the shared group; closed for
+ *   good once it has seen that record ({@link closeWalletSharedSecretFallback}).
+ */
+let holderSharedFallback = false;
+let walletSharedFallbackClosed = false;
+
+/** The migration's switch for Commons' fallback. @internal */
+export function setHolderSharedSecretFallback(open: boolean): void {
+  holderSharedFallback = open;
+}
+
+/** The wallet saw Commons' completion record: no shared fallback again in this process. @internal */
+export function closeWalletSharedSecretFallback(): void {
+  walletSharedFallbackClosed = true;
+}
+
+function sharedFallbackOpen(access: Extract<KeychainAccess, { mode: 'grouped' }>): boolean {
+  switch (access.role) {
+    case 'holder':
+      return holderSharedFallback;
+    case 'wallet':
+      return !walletSharedFallbackClosed;
+    case 'member':
+      return false;
+  }
 }
 
 function option(value: string | undefined): KeychainGroupOption {
@@ -244,11 +312,13 @@ function option(value: string | undefined): KeychainGroupOption {
 }
 
 /**
- * The option bags a READ of `item` tries, in order: its own group, then, for
- * an identity secret or a spending key, the shared group, where those 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. An app's own items (`app`) take {@link ownKeychainItemPlan}.
+ * The option bags a READ of `item` tries, in order: its own group, then — for
+ * an identity secret or a spending key, and only while
+ * {@link sharedFallbackOpen} says so — the shared group, where those lived
+ * before the split. Empty when this app may not hold the item: the caller
+ * answers `null` without touching the keychain. Evaluated per read: the
+ * fallback closes during a process's life. An app's own items (`app`) take
+ * {@link ownKeychainItemPlan}.
  */
 export function keychainReadPlan(
   access: KeychainAccess,
@@ -262,22 +332,33 @@ export function keychainReadPlan(
   }
   const own = keychainGroupFor(item);
   const plan = [option(keychainAccessGroupValue(access, own))];
-  if (own === 'identity' || own === 'wallet') {
-    // Where the split moved these items from.
+  if ((own === 'identity' || own === 'wallet') && sharedFallbackOpen(access)) {
     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.
+ * Every place a DELETE of `item` must reach: its own group AND the shared
+ * group, whatever the read fallback says, so a delete never leaves a copy
+ * behind where every Oxy app can read it.
  */
 export function keychainDeletePlan(
   access: KeychainAccess,
   item: KeychainItemClass,
 ): KeychainGroupOption[] {
-  return 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 === 'identity' || own === 'wallet') {
+    plan.push(option(keychainAccessGroupValue(access, 'shared')));
+  }
+  return plan;
 }
 
 /**
@@ -292,9 +373,9 @@ export function keychainWriteOption(
   if (access.mode === 'ungrouped') {
     return {};
   }
-  if (!mayHoldKeychainItem(access.role, item)) {
+  if (!mayWriteKeychainItem(access.role, item)) {
     throw new Error(
-      `This app (keychain role "${access.role}") may not hold a ${item} keychain item; only Commons writes the identity.`,
+      `This app (keychain role "${access.role}") may not write a ${item} keychain item; only Commons writes the identity and the keys the wallet spends.`,
     );
   }
   return option(keychainAccessGroupValue(access, keychainGroupFor(item)));
@@ -413,23 +494,39 @@ export async function deleteThroughPlan(
 
 /**
  * `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.
+ * the read plan (evaluated per read), writes carry the write option (throwing
+ * for a role that may not write the item), deletes reach every location. A
+ * secret WRITE also deletes the item's copy in the shared group (R4-6): a value
+ * Commons writes replaces whatever any app could read there, and a copy that
+ * cannot be removed fails the write instead of staying readable. 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 sharedCopy =
+    access.mode === 'grouped' && (item === 'identity-secret' || item === 'spending-key')
+      ? option(keychainAccessGroupValue(access, 'shared'))
+      : null;
   const wrapped: KeychainStoreLike = {
-    getItemAsync: (key, options) => readThroughPlan(store, key, options ?? {}, plan),
+    getItemAsync: (key, options) =>
+      readThroughPlan(store, key, options ?? {}, keychainReadPlan(access, item)),
     setItemAsync: async (key, value, options) => {
       const group = keychainWriteOption(access, item);
       await store.setItemAsync(key, value, { ...(options ?? {}), ...group });
+      if (sharedCopy) {
+        const { keychainAccessible: _accessible, ...rest } = (options ?? {}) as Record<
+          string,
+          unknown
+        >;
+        await store.deleteItemAsync(key, { ...rest, ...sharedCopy });
+      }
     },
-    deleteItemAsync: (key, options) => deleteThroughPlan(store, key, options ?? {}, plan),
+    deleteItemAsync: (key, options) =>
+      deleteThroughPlan(store, key, options ?? {}, keychainDeletePlan(access, item)),
   };
   return Object.assign(Object.create(store) as S, wrapped);
 }