@oxy.so/core 7.29.0 → 7.30.0

package/dist/esm/api/identity.js

@@ -18,6 +18,7 @@
  * AEAD, signatures) load on first use, never with the client itself.
  */
 import { checkContract, IDENTITY_PROOF_ACTIONS, identityLinkCreateResponseCheck, identityLinkStateCheck, } from '@oxy.so/contracts/client';
+import { identityKeyHistoryCheck } from '@oxy.so/contracts/client';
 import { isAndroid, isWeb } from '../utils/platform.js';
 import { logger } from '../logger/index.js';
 /** Short-TTL read cache for public identity reads. */
@@ -158,7 +159,7 @@ export class IdentityApi {
         if (!userId) {
             throw new Error('No authenticated user — sign in before rotating your key.');
         }
-        const { KeyManager, RecoveryPhraseService, SignatureService, signMessage } = await import('../crypto/index.js');
+        const { KeyManager, RecoveryPhraseService, SignatureService, signMessage, retireIdentityKey } = await import('../crypto/index.js');
         // 1. The NEW identity (in memory only). The UI may pre-derive + pre-show
         //    it and pass it back here so the phrase shown === the phrase committed.
         const pending = options.pendingIdentity ?? (await RecoveryPhraseService.derivePendingIdentity());
@@ -166,6 +167,7 @@ export class IdentityApi {
         // 2. Resolve the OLD signing capability from the chosen proof mode.
         let oldPublicKey;
         let signWithOldKey;
+        let oldPrivateKeyForRing;
         if (options.proof === 'phrase') {
             const phrase = options.phrase?.trim();
             if (!phrase) {
@@ -174,6 +176,7 @@ export class IdentityApi {
             const oldPrivateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(phrase);
             oldPublicKey = KeyManager.derivePublicKey(oldPrivateKey);
             signWithOldKey = (message) => signMessage(message, oldPrivateKey);
+            oldPrivateKeyForRing = oldPrivateKey;
         }
         else {
             const currentPublicKey = await KeyManager.getPublicKey();
@@ -182,6 +185,25 @@ export class IdentityApi {
             }
             oldPublicKey = currentPublicKey;
             signWithOldKey = (message) => SignatureService.sign(message);
+            oldPrivateKeyForRing = isWeb() ? null : await KeyManager.getPrivateKey();
+        }
+        // 2b. Keep the key being replaced in the retired ring BEFORE anything
+        //     changes (oxy ADR 0061 D7 as amended, Peable ADR 0002): coins keep
+        //     arriving under it after the swap, and the Peable wallet spends them
+        //     through the `publicKey` selector of `deriveScopedSeed` /
+        //     `signSocialReceive`. A device that cannot keep it does not rotate:
+        //     the phrase would become the only way to those coins. Native only —
+        //     on web no key is stored. Idempotent, so a retried rotation is fine.
+        if (!isWeb()) {
+            try {
+                if (!oldPrivateKeyForRing)
+                    throw new Error('no readable private key');
+                await retireIdentityKey({ privateKey: oldPrivateKeyForRing, publicKey: oldPublicKey });
+            }
+            catch (retainError) {
+                logger.warn('Could not keep the current key as a retired key; not rotating.', { component: 'oxy.identity', method: 'rotateKey' }, retainError);
+                throw new Error('Your current key could not be kept on this device, so it was not rotated. Nothing changed.');
+            }
         }
         // 3. Request a single-use rotate_key challenge (bearer).
         const { challenge } = await this.ctx.request('POST', '/auth/rotate/challenge', undefined, {
@@ -338,6 +360,23 @@ export class IdentityApi {
             keys.push(`GET:/u/${encodeURIComponent(userId)}/did.json`);
         this.ctx.http.invalidateCache({ keys, prefixes: ['GET:/users/me'] });
     }
+    /**
+     * The signed-in personal account's current root (`null` without one) and
+     * every root a rotation replaced, oldest first, all canonical (uncompressed,
+     * lowercase). Commons reads it to accept a previous recovery phrase only when
+     * it derives a key that WAS this account's root. A retired root is never any
+     * account's again. First-party only; a non-personal account is refused
+     * (`IDENTITY_NOT_PERSONAL_ACCOUNT`).
+     */
+    async keyHistory() {
+        const res = await this.ctx.request('GET', '/identity/key-history', undefined, {
+            cache: false,
+        });
+        const parsed = checkContract(identityKeyHistoryCheck, res);
+        if (!parsed)
+            throw new Error('identity/key-history returned an unexpected response shape');
+        return parsed;
+    }
 }
 /** `oxy.identity.links` — joining Commons' root to an account (ADR 0029 D3). */
 export class IdentityLinksApi {

package/dist/esm/crypto/index.js

@@ -20,6 +20,9 @@ export { generateOrganizationKey, organizationKeyFromPhrase, storeOrganizationKe
 // iOS keychain access groups (docs/identity/ios-keychain-access-groups.md, ADR 0062)
 export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFor, mayHoldKeychainItem, resolveKeychainAccess, keychainAccessGroupValue, keychainReadPlan, keychainDeletePlan, keychainWriteOption, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, groupedKeychainStore, } from '../utils/keychainAccessGroups.js';
 export { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
+// Retired identity keys: kept for spending after a rotation or replacement
+// (docs/adr/0061-organization-identity-key.md D7 as amended 2026-11-06)
+export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, } from './retiredKeys.js';
 export { SignatureService } from './signatureService.js';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase.js';
 // Low-level primitives (encrypted backup, device transfer)

package/dist/esm/crypto/keyManager.js

@@ -11,6 +11,7 @@ import { isDev, logger } from '../logger/index.js';
 import { deriveScopedSeedFromKey, signSocialReceiveDigest } from './identityDerivations.js';
 import { registerIdentitySignerStore } from './identitySigner.js';
 import { getOrganizationPrivateKey, isOrganizationAccountId } from './organizationKeys.js';
+import { forgetRetiredIdentityKeys, getRetiredPrivateKey, retiredKeyScope } from './retiredKeys.js';
 import { groupedKeychainStore, resolveKeychainAccess, } from '../utils/keychainAccessGroups.js';
 import { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
 import { RECOVERY_MNEMONIC_KEYCHAIN_SERVICE, RECOVERY_MNEMONIC_STORAGE_KEY, STORAGE_KEYS, V2_BACKUP_KEYCHAIN_SERVICE, V2_PRIMARY_KEYCHAIN_SERVICE, V2_STORAGE_KEYS, } from './keychainItems.js';
@@ -2049,6 +2050,13 @@ 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
         // silently, so leaving it would bring a deleted identity back on the next
@@ -2581,8 +2589,15 @@ 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.
      */
@@ -2590,6 +2605,18 @@ export class KeyManager {
         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);
         }
@@ -2635,7 +2662,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
@@ -2645,6 +2673,18 @@ export class KeyManager {
         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.
@@ -2668,6 +2708,34 @@ export class KeyManager {
             : ((await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey()));
         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
+     */
+    static _selectorKey(publicKey) {
+        return KeyManager.isValidPublicKey(publicKey) ? KeyManager.canonicalPublicKey(publicKey) : null;
+    }
+    static async _selectedPrivateKey(publicKey, accountId) {
+        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/dist/esm/crypto/retiredKeys.js

@@ -0,0 +1,361 @@
+/**
+ * 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 { loadCommonsIdentityBridge, loadSecureStore, } from '@oxy.so/protocol';
+import { deriveSecp256k1PublicKey, isValidSecp256k1PrivateKey, isValidSecp256k1PublicKey, normalizeSecp256k1PrivateKey, normalizeSecp256k1PublicKey, } from '@oxy.so/protocol/secp256k1';
+import { logger } from '../logger/index.js';
+import { groupedKeychainStore, resolveKeychainAccess } from '../utils/keychainAccessGroups.js';
+import { isAndroid, isIOS, isWeb } from '../utils/platform.js';
+import { registeredIdentitySignerStore } from './identitySigner.js';
+import { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
+import { isOrganizationAccountId } from './organizationKeys.js';
+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() {
+    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) {
+    const accountId = selector?.accountId;
+    if (accountId === undefined)
+        return PERSONAL_SCOPE;
+    return isOrganizationAccountId(accountId) ? accountId : null;
+}
+function canonicalPublicKey(publicKey) {
+    try {
+        const normalized = normalizeSecp256k1PublicKey(publicKey.trim());
+        return PUBLIC_KEY.test(normalized) ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}
+function publicKeyOf(privateKey) {
+    return deriveSecp256k1PublicKey(normalizeSecp256k1PrivateKey(privateKey));
+}
+function isHealthyPair(privateKey, publicKey) {
+    if (!isValidSecp256k1PrivateKey(privateKey) || !isValidSecp256k1PublicKey(publicKey)) {
+        return false;
+    }
+    try {
+        return publicKeyOf(privateKey) === normalizeSecp256k1PublicKey(publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+const privateKeyName = (scope, publicKey) => `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, forWrite) {
+    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() {
+    return isIOS() ? {} : { keychainService: INDEX_KEYCHAIN_SERVICE };
+}
+function isIndexEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const entry = value;
+    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) {
+    const raw = await store.getItemAsync(INDEX_STORAGE_KEY, indexOptions());
+    if (!raw)
+        return [];
+    try {
+        const parsed = 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, entries) {
+    const unique = new Map();
+    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) {
+    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() {
+    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, selector) {
+    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) {
+    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, selector) {
+    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, selector) {
+    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) {
+    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() {
+    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) {
+    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/dist/types/api/identity.d.ts

@@ -1,3 +1,4 @@
+import { type IdentityKeyHistory } from '@oxy.so/contracts/client';
 import type { AuthMethodsResponse, BackupStatusResponse, DidDocument, DomainVerificationInstructions, ExportBundle, IdentityLinkCreateResponse, IdentityLinkState, IdentityRootStatus, OxySignedRecordType, ReauthProof, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 import type { PendingIdentityResult } from '../crypto/recoveryPhrase';
@@ -176,6 +177,15 @@ export declare class IdentityApi {
      * user's derived DID document (which embeds auth methods + verified domains).
      */
     private invalidate;
+    /**
+     * The signed-in personal account's current root (`null` without one) and
+     * every root a rotation replaced, oldest first, all canonical (uncompressed,
+     * lowercase). Commons reads it to accept a previous recovery phrase only when
+     * it derives a key that WAS this account's root. A retired root is never any
+     * account's again. First-party only; a non-personal account is refused
+     * (`IDENTITY_NOT_PERSONAL_ACCOUNT`).
+     */
+    keyHistory(): Promise<IdentityKeyHistory>;
 }
 /** `oxy.identity.links` — joining Commons' root to an account (ADR 0029 D3). */
 export declare class IdentityLinksApi {

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

@@ -40,6 +40,29 @@ export interface IdentitySignerStore {
     writeOrganization?(accountId: string, privateKey: string, publicKey: string): Promise<boolean>;
     /** Drop that organization's pair. */
     clearOrganization?(accountId: string): Promise<void>;
+    /**
+     * The RETIRED key ring: keys a scope rotated away from (a personal rotation,
+     * or an organization key replacement, ADR 0061 D7), kept so the identity host
+     * can still derive and sign with them for the wallet when a request names
+     * their public key. Spending only: the host never signs anyone in with one.
+     *
+     * `scope` is `'personal'` or an organization's account id (24-hex or uuid);
+     * `publicKey` is the retired key's lowercase uncompressed SEC1 hex (130),
+     * which names its entry. The native side refuses anything else. Clearing the
+     * personal pair ({@link clear}) or an organization's never drops a ring.
+     * Optional so a store built before retired keys still type-checks; Commons
+     * offers all four or none.
+     */
+    readRetired?(scope: string, publicKey: string): Promise<{
+        privateKey: string;
+        publicKey: string;
+    } | null>;
+    /** Keep a retired pair in `scope`'s ring. Resolves whether a read-back confirmed it. */
+    writeRetired?(scope: string, privateKey: string, publicKey: string): Promise<boolean>;
+    /** The public keys in `scope`'s ring (healthy entries only, sorted); `[]` when none. */
+    listRetired?(scope: string): Promise<string[]>;
+    /** Drop one retired key from `scope`'s ring. */
+    clearRetired?(scope: string, publicKey: string): Promise<void>;
 }
 /** @internal */
 export declare function registerIdentitySignerStore(store: IdentitySignerStore | null): void;

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

@@ -23,6 +23,8 @@ export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFo
 export type { KeychainAccess, KeychainAccessGroupName, KeychainGroupOption, KeychainItemClass, KeychainRole, KeychainStoreLike, } from '../utils/keychainAccessGroups';
 export { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
 export type { KeychainGroupMigrationReport, KeychainItemMigrationOutcome, } from './keychainGroupMigration';
+export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, } from './retiredKeys';
+export type { RetiredIdentityKey, RetiredKeyPair, RetiredKeySelector } from './retiredKeys';
 export { SignatureService } from './signatureService';
 export type { SignedMessage, AuthChallenge } from './signatureService';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase';