@oxy.so/core 7.29.0 → 7.31.0

package/src/crypto/keyManager.ts

@@ -32,6 +32,7 @@ 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,
@@ -2611,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
@@ -3229,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);
     }
@@ -3292,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
@@ -3301,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.
@@ -3330,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

package/src/crypto/keychainGroupMigration.ts

@@ -110,7 +110,12 @@ type Unit =
       merge?: (shared: string, target: string) => string | null;
     };
 
-const slot = (key: string, item: KeychainItemClass, service?: string, deviceOnly = true): Slot => ({
+const slot = (
+  key: string,
+  item: Exclude<KeychainItemClass, 'app'>,
+  service?: string,
+  deviceOnly = true,
+): Slot => ({
   key,
   service,
   group: keychainGroupFor(item),

package/src/crypto/retiredKeys.ts

@@ -0,0 +1,453 @@
+/**
+ * Retired identity keys: the keys an account HAD, kept on the device for
+ * spending only (oxy ADR 0061 D7 as amended 2026-11-06, Peable ADR 0002).
+ *
+ * The Peable wallet derives from the account's identity key (`deriveScopedSeed`
+ * for its HD wallet, `signSocialReceive` for its social-receive addresses), and
+ * coins keep arriving under a key after it is replaced: payments already
+ * broadcast settle against the key they were reserved under, and late payers
+ * and `@username` senders hold old addresses. So a personal rotation
+ * (`oxy.identity.rotateKey`) and an organization replacement keep the replaced
+ * private key here, in a ring per account — `personal`, and one per
+ * organization account id — instead of deleting it.
+ *
+ * A retired key is NEVER a way to sign in, publish, receive a new reservation or
+ * rotate: nothing here signs a challenge, and the identity host refuses
+ * `proveIdentity` / `describe` for one. It is reached exactly as the current key
+ * is, by derivation and never by export, through the `publicKey` selector of
+ * `KeyManager.deriveScopedSeed` / `signSocialReceive`:
+ *
+ * - iOS: the private key in the wallet keychain group (ADR 0062's
+ *   `spending-key`: Commons and the Peable wallet only), beside the current
+ *   private keys; the ring's index (public keys and dates only) in the same
+ *   group, so the wallet can list it. Only Commons writes either.
+ * - Android: Commons' own expo-secure-store slot, mirrored into the identity
+ *   signer store (`./identitySigner`) that Commons' identity host answers
+ *   `keyPublicKey` requests from (wallet only). Every other app asks over IPC
+ *   (`loadCommonsIdentityBridge`) and never gets the key.
+ *
+ * A retired phrase is not kept: the person wrote it down, and a phrase is a
+ * second copy of the key that buys the wallet nothing.
+ *
+ * A key enters the ring only from Commons: the key being replaced (rotation,
+ * organization replacement), or a previous recovery phrase the person adds,
+ * which Commons accepts only when Oxy's key history names it as one of the
+ * account's retired keys. Never into the current slot.
+ *
+ * Security: a retired key that was compromised is also the attacker's. The
+ * ring makes the coins under it spendable from Peable again; it cannot make
+ * them safe. A rotation forced by a compromise must be followed at once by the
+ * wallet's "move to your current key" sweep, which races the attacker.
+ *
+ * This module imports nothing from `./keyManager` (which imports it).
+ */
+
+import { mnemonicToSeed, validateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import {
+  type ExpoSecureStoreLike,
+  loadCommonsIdentityBridge,
+  loadSecureStore,
+} from '@oxy.so/protocol';
+import {
+  deriveSecp256k1PublicKey,
+  isValidSecp256k1PrivateKey,
+  isValidSecp256k1PublicKey,
+  normalizeSecp256k1PrivateKey,
+  normalizeSecp256k1PublicKey,
+} from '@oxy.so/protocol/secp256k1';
+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 type { OxySecureStoreOptions as SecureStoreOptions } from './secureStoreOptions';
+
+/** Whose ring: the person's (`accountId` absent) or an organization's. */
+export interface RetiredKeySelector {
+  /** An organization's account id; absent for the personal ring. */
+  accountId?: string;
+}
+
+/** One retired key as the ring lists it: public data only. */
+export interface RetiredIdentityKey {
+  /** Lowercase uncompressed secp256k1 public key (`04…`, 130 hex). */
+  publicKey: string;
+  /** The organization it was the key of; absent for a personal root. */
+  accountId?: string;
+  /** Unix milliseconds when this device kept it. */
+  retiredAt: number;
+}
+
+/** A pair to keep in the ring. */
+export interface RetiredKeyPair {
+  privateKey: string;
+  publicKey: string;
+}
+
+const PERSONAL_SCOPE = 'personal';
+/** Android, Commons-local: its own Keystore-backed slot, shared with no other key. */
+const ANDROID_KEYCHAIN_SERVICE = 'oxy_retired_identity';
+const INDEX_KEYCHAIN_SERVICE = 'oxy_retired_identity_index';
+const INDEX_STORAGE_KEY = 'oxy_retired_identity_index_v1';
+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.
+ */
+async function ringStore(): Promise<ExpoSecureStoreLike> {
+  const raw = await loadSecureStore();
+  const access = await resolveKeychainAccess();
+  if (access.mode === 'grouped' && access.role === 'holder') {
+    await ensureKeychainGroupsMigrated();
+  }
+  return groupedKeychainStore(raw, access, 'spending-key');
+}
+
+/** The ring a selector names: `personal`, or the organization's account id. */
+export function retiredKeyScope(selector?: RetiredKeySelector): string | null {
+  const accountId = selector?.accountId;
+  if (accountId === undefined) return PERSONAL_SCOPE;
+  return isOrganizationAccountId(accountId) ? accountId : null;
+}
+
+function canonicalPublicKey(publicKey: string): string | null {
+  try {
+    const normalized = normalizeSecp256k1PublicKey(publicKey.trim());
+    return PUBLIC_KEY.test(normalized) ? normalized : null;
+  } catch {
+    return null;
+  }
+}
+
+function publicKeyOf(privateKey: string): string {
+  return deriveSecp256k1PublicKey(normalizeSecp256k1PrivateKey(privateKey));
+}
+
+function isHealthyPair(privateKey: string, publicKey: string): boolean {
+  if (!isValidSecp256k1PrivateKey(privateKey) || !isValidSecp256k1PublicKey(publicKey)) {
+    return false;
+  }
+  try {
+    return publicKeyOf(privateKey) === normalizeSecp256k1PublicKey(publicKey);
+  } catch {
+    return false;
+  }
+}
+
+const privateKeyName = (scope: string, publicKey: string) =>
+  `oxy_retired_identity_private_key.${scope}.${publicKey}`;
+
+/** The options of a private half: on iOS none but accessibility (the group comes from {@link ringStore}). */
+function privateOptions(store: ExpoSecureStoreLike, forWrite: boolean): SecureStoreOptions {
+  if (isIOS()) {
+    return forWrite ? { keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY } : {};
+  }
+  return forWrite
+    ? {
+        keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+        keychainService: ANDROID_KEYCHAIN_SERVICE,
+      }
+    : { keychainService: ANDROID_KEYCHAIN_SERVICE };
+}
+
+/** The index: public keys and dates, beside the private halves. */
+function indexOptions(): SecureStoreOptions {
+  return isIOS() ? {} : { keychainService: INDEX_KEYCHAIN_SERVICE };
+}
+
+interface IndexEntry {
+  scope: string;
+  publicKey: string;
+  retiredAt: number;
+}
+
+function isIndexEntry(value: unknown): value is IndexEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    typeof entry.scope === 'string' &&
+    (entry.scope === PERSONAL_SCOPE || isOrganizationAccountId(entry.scope)) &&
+    typeof entry.publicKey === 'string' &&
+    PUBLIC_KEY.test(entry.publicKey) &&
+    typeof entry.retiredAt === 'number' &&
+    Number.isFinite(entry.retiredAt)
+  );
+}
+
+async function readIndex(store: ExpoSecureStoreLike): Promise<IndexEntry[]> {
+  const raw = await store.getItemAsync(INDEX_STORAGE_KEY, indexOptions());
+  if (!raw) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter(isIndexEntry) : [];
+  } catch (error) {
+    logger.warn('Retired key index unreadable; treating as empty', {
+      component: 'RetiredKeys',
+      error: error instanceof Error ? error.name : 'unknown',
+    });
+    return [];
+  }
+}
+
+async function writeIndex(store: ExpoSecureStoreLike, entries: IndexEntry[]): Promise<void> {
+  const unique = new Map<string, IndexEntry>();
+  for (const entry of entries) {
+    const id = `${entry.scope}.${entry.publicKey}`;
+    if (!unique.has(id)) unique.set(id, entry);
+  }
+  const sorted = [...unique.values()].sort(
+    (a, b) => a.retiredAt - b.retiredAt || a.publicKey.localeCompare(b.publicKey),
+  );
+  await store.setItemAsync(INDEX_STORAGE_KEY, JSON.stringify(sorted), indexOptions());
+}
+
+function toListed(entry: IndexEntry): RetiredIdentityKey {
+  return entry.scope === PERSONAL_SCOPE
+    ? { publicKey: entry.publicKey, retiredAt: entry.retiredAt }
+    : { 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 {
+  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.',
+    );
+  }
+}
+
+/**
+ * Keep `key` in the ring of `selector`'s account. Commons only. Idempotent: a
+ * key already kept stays, with its first date. Refuses a pair whose public key
+ * does not derive from its private key. Resolves once every copy confirmed it
+ * (Android: the signer store's read-back too), and throws otherwise, so a
+ * caller about to replace the key can stop before anything is lost.
+ */
+export async function retireIdentityKey(
+  key: RetiredKeyPair,
+  selector?: RetiredKeySelector,
+): Promise<void> {
+  const scope = retiredKeyScope(selector);
+  if (!scope) throw new Error('retired key: accountId must be a 24-hex or uuid account id');
+  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();
+  await store.setItemAsync(
+    privateKeyName(scope, publicKey),
+    privateKey,
+    privateOptions(store, true),
+  );
+  const readBack = await store.getItemAsync(
+    privateKeyName(scope, publicKey),
+    privateOptions(store, false),
+  );
+  if (readBack !== privateKey) {
+    throw new Error('retired key: the keychain did not confirm the key');
+  }
+  const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+  if (signer?.writeRetired && !(await signer.writeRetired(scope, privateKey, publicKey))) {
+    throw new Error(`The identity signer store (${signer.name}) did not confirm the retired key.`);
+  }
+  const index = await readIndex(store);
+  if (!index.some((entry) => entry.scope === scope && entry.publicKey === publicKey)) {
+    await writeIndex(store, [...index, { scope, publicKey, retiredAt: Date.now() }]);
+  }
+}
+
+/**
+ * The retired keys of `selector`'s account this app can reach, oldest first.
+ * iOS and Commons: the ring's index. Android elsewhere: Commons' identity host
+ * (the wallet only), which leaves out the scope's current key. After an
+ * interrupted rotation the local list can include the current key: compare
+ * with the DID's `#key-1` before treating an entry as retired.
+ */
+export async function listRetiredIdentityKeys(
+  selector?: RetiredKeySelector,
+): Promise<RetiredIdentityKey[]> {
+  const scope = retiredKeyScope(selector);
+  if (!scope || isWeb()) return [];
+  try {
+    if (isAndroid() && !registeredIdentitySignerStore()) {
+      const bridge = await loadCommonsIdentityBridge();
+      const keys = (await bridge?.listRetiredKeys?.(selector?.accountId)) ?? null;
+      return (keys ?? []).map((publicKey) =>
+        scope === PERSONAL_SCOPE
+          ? { publicKey, retiredAt: 0 }
+          : { publicKey, accountId: scope, retiredAt: 0 },
+      );
+    }
+    if (!isIOS() && !isAndroid()) return [];
+    const store = await ringStore();
+    return (await readIndex(store)).filter((entry) => entry.scope === scope).map(toListed);
+  } catch (error) {
+    logger.warn('Failed to list retired keys', {
+      component: 'RetiredKeys',
+      error: error instanceof Error ? error.name : 'unknown',
+    });
+    return [];
+  }
+}
+
+/**
+ * The private half of a retired key, where this app may hold it: Commons (both
+ * platforms) and, on iOS, the keychain group. `null` on Android outside Commons
+ * (ask the identity host instead) and for a key not in the ring. Sign within
+ * the app only; never transmit it. @internal — `KeyManager` reads it for the
+ * `publicKey` selector.
+ */
+export async function getRetiredPrivateKey(
+  publicKey: string,
+  selector?: RetiredKeySelector,
+): Promise<string | null> {
+  const scope = retiredKeyScope(selector);
+  const canonical = canonicalPublicKey(publicKey);
+  if (!scope || !canonical || isWeb()) return null;
+  try {
+    if (isAndroid()) {
+      const signer = registeredIdentitySignerStore();
+      if (!signer) return null;
+      const store = await ringStore();
+      const local = await store.getItemAsync(
+        privateKeyName(scope, canonical),
+        privateOptions(store, false),
+      );
+      if (local && isHealthyPair(local, canonical)) return normalizeSecp256k1PrivateKey(local);
+      // The signer store is a rung: a wiped expo-secure-store slot still has it.
+      const mirrored = (await signer.readRetired?.(scope, canonical)) ?? null;
+      return mirrored && isHealthyPair(mirrored.privateKey, canonical)
+        ? normalizeSecp256k1PrivateKey(mirrored.privateKey)
+        : null;
+    }
+    if (!isIOS()) return null;
+    const store = await ringStore();
+    const value = await store.getItemAsync(
+      privateKeyName(scope, canonical),
+      privateOptions(store, false),
+    );
+    return value && isHealthyPair(value, canonical) ? normalizeSecp256k1PrivateKey(value) : null;
+  } catch (error) {
+    logger.warn('Failed to read a retired key', {
+      component: 'RetiredKeys',
+      error: error instanceof Error ? error.name : 'unknown',
+    });
+    return null;
+  }
+}
+
+/**
+ * Forget a retired key on this device: its private half, its signer copy and
+ * its index entry. Commons only, and only on the person's explicit request
+ * (their coins under it are then spendable only with its phrase again).
+ */
+export async function forgetRetiredIdentityKey(
+  publicKey: string,
+  selector?: RetiredKeySelector,
+): Promise<void> {
+  const scope = retiredKeyScope(selector);
+  const canonical = canonicalPublicKey(publicKey);
+  if (!scope || !canonical) throw new Error('retired key: invalid selector or public key');
+  assertMayWrite();
+  const store = await ringStore();
+  await store.deleteItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
+  const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+  await signer?.clearRetired?.(scope, canonical);
+  await writeIndex(
+    store,
+    (await readIndex(store)).filter(
+      (entry) => !(entry.scope === scope && entry.publicKey === canonical),
+    ),
+  );
+}
+
+/**
+ * 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.
+ */
+export async function forgetRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<number> {
+  const scope = retiredKeyScope(selector);
+  if (!scope || isWeb()) return 0;
+  if (isAndroid() && !registeredIdentitySignerStore()) return 0;
+  const store = await ringStore();
+  const index = await readIndex(store);
+  const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+  let removed = 0;
+  for (const entry of index) {
+    if (entry.scope !== scope) continue;
+    await store.deleteItemAsync(
+      privateKeyName(scope, entry.publicKey),
+      privateOptions(store, false),
+    );
+    await signer?.clearRetired?.(scope, entry.publicKey);
+    removed += 1;
+  }
+  await writeIndex(
+    store,
+    index.filter((entry) => entry.scope !== scope),
+  );
+  return removed;
+}
+
+/**
+ * Commons on Android: copy every retired key into the identity signer store
+ * again, so the identity host answers for it after that file was rebuilt (its
+ * self-heal leaves it empty). Call on every boot, beside `syncOrganizationKeys`.
+ * Resolves how many it mirrored. Elsewhere 0.
+ */
+export async function syncRetiredKeys(): Promise<number> {
+  const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+  if (!signer?.writeRetired || !signer.readRetired) return 0;
+  const store = await ringStore();
+  let mirrored = 0;
+  for (const entry of await readIndex(store)) {
+    const privateKey = await store.getItemAsync(
+      privateKeyName(entry.scope, entry.publicKey),
+      privateOptions(store, false),
+    );
+    if (!privateKey || !isHealthyPair(privateKey, entry.publicKey)) continue;
+    const current = await signer.readRetired(entry.scope, entry.publicKey);
+    if (current?.publicKey.toLowerCase() === entry.publicKey) continue;
+    if (
+      await signer.writeRetired(
+        entry.scope,
+        normalizeSecp256k1PrivateKey(privateKey),
+        entry.publicKey,
+      )
+    ) {
+      mirrored += 1;
+    }
+  }
+  return mirrored;
+}
+
+/**
+ * The pair a previous recovery phrase derives (`seed[0:32]`, the personal-root
+ * and organization-key derivation; 12–24 words). Stores nothing: the caller
+ * checks the public key against the account's key history (personal:
+ * `oxy.identity.keyHistory()`; organization: `oxy.accounts.identityKey.get`)
+ * and only then calls {@link retireIdentityKey}.
+ */
+export async function retiredKeyFromPhrase(phrase: string): Promise<RetiredKeyPair> {
+  const normalized = phrase.trim().toLowerCase().split(/\s+/).join(' ');
+  const words = normalized.split(' ').length;
+  if (words < 12 || words > 24 || words % 3 !== 0 || !validateMnemonic(normalized, wordlist)) {
+    throw new Error('retired key: not a valid recovery phrase');
+  }
+  const seed = await mnemonicToSeed(normalized);
+  const privateKey = Array.from(seed.subarray(0, 32), (b) => b.toString(16).padStart(2, '0')).join(
+    '',
+  );
+  return { privateKey, publicKey: publicKeyOf(privateKey) };
+}

package/src/session/authStateStore.ts

@@ -18,6 +18,7 @@
  */
 
 import { logger } from '../logger';
+import type { OwnKeychainItemNames } from '../utils/keychainAccessGroups';
 
 /**
  * The persisted session credential set for a single origin.
@@ -150,6 +151,19 @@ export const AUTH_STATE_STORAGE_KEY = 'oxy.auth.v1';
 export const AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY =
   'oxy.auth.automatic-identity-signin-suppressed.v1';
 
+/**
+ * What `ownKeychainItemPlan` (ADR 0062 D6) must know about a key a native
+ * session store keeps — this module's three and the identity pin: every Oxy app
+ * writes it under the same name, so on iOS a copy in the shared group may be
+ * another app's session and is never read as this app's. The sign-out marker
+ * can only withhold, so a shared copy of it still counts.
+ */
+export function nativeSessionItemNames(key: string): OwnKeychainItemNames {
+  return key === AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY
+    ? 'every-oxy-app-withholding'
+    : 'every-oxy-app';
+}
+
 /**
  * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
  * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a

package/src/session/index.ts

@@ -134,7 +134,10 @@ export {
   createWebAuthStateStore,
   createNativeAuthStateStore,
   createMemoryAuthStateStore,
+  nativeSessionItemNames,
   AUTH_STATE_STORAGE_KEY,
+  AUTH_STATE_TOKEN_STORAGE_KEY,
+  AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY,
 } from './authStateStore';
 export type {
   PersistedAuthState,
@@ -176,7 +179,11 @@ export {
   deleteThroughPlan,
   resolveKeychainAccess,
 } from '../utils/keychainAccessGroups';
-export type { KeychainAccess, KeychainGroupOption } from '../utils/keychainAccessGroups';
+export type {
+  KeychainAccess,
+  KeychainGroupOption,
+  OwnKeychainItemNames,
+} from '../utils/keychainAccessGroups';
 
 // Identity-bound sessions (the identity vault). The pin is the durable
 // `{publicKey, accountId}` binding between this device's PRIMARY identity key