@oxy.so/core 7.29.0 → 7.30.0

package/dist/cjs/api/identity.js

@@ -56,6 +56,7 @@ exports.signOwnChainRecord = signOwnChainRecord;
  * AEAD, signatures) load on first use, never with the client itself.
  */
 const client_1 = require("@oxy.so/contracts/client");
+const client_2 = require("@oxy.so/contracts/client");
 const platform_1 = require("../utils/platform");
 const logger_1 = require("../logger");
 /** Short-TTL read cache for public identity reads. */
@@ -196,7 +197,7 @@ class IdentityApi {
         if (!userId) {
             throw new Error('No authenticated user — sign in before rotating your key.');
         }
-        const { KeyManager, RecoveryPhraseService, SignatureService, signMessage } = await Promise.resolve().then(() => __importStar(require('../crypto/index')));
+        const { KeyManager, RecoveryPhraseService, SignatureService, signMessage, retireIdentityKey } = await Promise.resolve().then(() => __importStar(require('../crypto/index')));
         // 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());
@@ -204,6 +205,7 @@ 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) {
@@ -212,6 +214,7 @@ 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();
@@ -220,6 +223,25 @@ class IdentityApi {
             }
             oldPublicKey = currentPublicKey;
             signWithOldKey = (message) => SignatureService.sign(message);
+            oldPrivateKeyForRing = (0, platform_1.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 (!(0, platform_1.isWeb)()) {
+            try {
+                if (!oldPrivateKeyForRing)
+                    throw new Error('no readable private key');
+                await retireIdentityKey({ privateKey: oldPrivateKeyForRing, publicKey: oldPublicKey });
+            }
+            catch (retainError) {
+                logger_1.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, {
@@ -376,6 +398,23 @@ 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 = (0, client_1.checkContract)(client_2.identityKeyHistoryCheck, res);
+        if (!parsed)
+            throw new Error('identity/key-history returned an unexpected response shape');
+        return parsed;
+    }
 }
 exports.IdentityApi = IdentityApi;
 /** `oxy.identity.links` — joining Commons' root to an account (ADR 0029 D3). */

package/dist/cjs/crypto/index.js

@@ -12,8 +12,8 @@
  * common chunk, which is the cost the lazy loading exists to avoid.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.solveRegistrationPow = exports.deriveIdentityLinkCode = exports.signIdentityProof = exports.digestIdentityPayload = exports.authChallengeDigest = exports.signSocialReceiveDigest = exports.deriveScopedSeedFromKey = exports.MAX_SOCIAL_RECEIVE_INDEX = exports.SOCIAL_RECEIVE_CHAIN_CODE_KEY = exports.SCOPED_SEED_KDF_SALT = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.BACKUP_KDF_ENCRYPTION_INFO = exports.RecoveryPhraseService = exports.SignatureService = exports.ensureKeychainGroupsMigrated = exports.groupedKeychainStore = exports.deleteThroughPlan = exports.readThroughPlan = exports.ownKeychainItemPlan = exports.keychainWriteOption = exports.keychainDeletePlan = exports.keychainReadPlan = exports.keychainAccessGroupValue = exports.resolveKeychainAccess = exports.mayHoldKeychainItem = exports.keychainGroupFor = exports.KeychainAccessUnavailableError = exports.KEYCHAIN_ACCESS_GROUPS = exports.isHealthyOrganizationKeyPair = exports.isOrganizationAccountId = exports.syncOrganizationKeys = exports.deleteOrganizationKey = exports.listOrganizationKeys = exports.getOrganizationRecoveryPhrase = exports.getOrganizationPrivateKey = exports.getOrganizationPublicKey = exports.storeOrganizationKey = exports.organizationKeyFromPhrase = exports.generateOrganizationKey = exports.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = void 0;
-exports.verifySignature = exports.signMessage = exports.loadCommonsIdentityBridge = exports.canonicalize = exports.createContentHasher = void 0;
+exports.deriveScopedSeedFromKey = exports.MAX_SOCIAL_RECEIVE_INDEX = exports.SOCIAL_RECEIVE_CHAIN_CODE_KEY = exports.SCOPED_SEED_KDF_SALT = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.BACKUP_KDF_ENCRYPTION_INFO = exports.RecoveryPhraseService = exports.SignatureService = exports.retiredKeyFromPhrase = exports.syncRetiredKeys = exports.forgetRetiredIdentityKeys = exports.forgetRetiredIdentityKey = exports.listRetiredIdentityKeys = exports.retireIdentityKey = exports.ensureKeychainGroupsMigrated = exports.groupedKeychainStore = exports.deleteThroughPlan = exports.readThroughPlan = exports.ownKeychainItemPlan = exports.keychainWriteOption = exports.keychainDeletePlan = exports.keychainReadPlan = exports.keychainAccessGroupValue = exports.resolveKeychainAccess = exports.mayHoldKeychainItem = exports.keychainGroupFor = exports.KeychainAccessUnavailableError = exports.KEYCHAIN_ACCESS_GROUPS = exports.isHealthyOrganizationKeyPair = exports.isOrganizationAccountId = exports.syncOrganizationKeys = exports.deleteOrganizationKey = exports.listOrganizationKeys = exports.getOrganizationRecoveryPhrase = exports.getOrganizationPrivateKey = exports.getOrganizationPublicKey = exports.storeOrganizationKey = exports.organizationKeyFromPhrase = exports.generateOrganizationKey = exports.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = void 0;
+exports.verifySignature = exports.signMessage = exports.loadCommonsIdentityBridge = exports.canonicalize = exports.createContentHasher = exports.solveRegistrationPow = exports.deriveIdentityLinkCode = exports.signIdentityProof = exports.digestIdentityPayload = exports.authChallengeDigest = exports.signSocialReceiveDigest = void 0;
 // MUST stay the first import: the shim has to exist before any module below
 // evaluates or draws randomness (see `./polyfill`).
 require("./polyfill");
@@ -55,6 +55,15 @@ Object.defineProperty(exports, "deleteThroughPlan", { enumerable: true, get: fun
 Object.defineProperty(exports, "groupedKeychainStore", { enumerable: true, get: function () { return keychainAccessGroups_1.groupedKeychainStore; } });
 var keychainGroupMigration_1 = require("./keychainGroupMigration");
 Object.defineProperty(exports, "ensureKeychainGroupsMigrated", { enumerable: true, get: function () { return keychainGroupMigration_1.ensureKeychainGroupsMigrated; } });
+// Retired identity keys: kept for spending after a rotation or replacement
+// (docs/adr/0061-organization-identity-key.md D7 as amended 2026-11-06)
+var retiredKeys_1 = require("./retiredKeys");
+Object.defineProperty(exports, "retireIdentityKey", { enumerable: true, get: function () { return retiredKeys_1.retireIdentityKey; } });
+Object.defineProperty(exports, "listRetiredIdentityKeys", { enumerable: true, get: function () { return retiredKeys_1.listRetiredIdentityKeys; } });
+Object.defineProperty(exports, "forgetRetiredIdentityKey", { enumerable: true, get: function () { return retiredKeys_1.forgetRetiredIdentityKey; } });
+Object.defineProperty(exports, "forgetRetiredIdentityKeys", { enumerable: true, get: function () { return retiredKeys_1.forgetRetiredIdentityKeys; } });
+Object.defineProperty(exports, "syncRetiredKeys", { enumerable: true, get: function () { return retiredKeys_1.syncRetiredKeys; } });
+Object.defineProperty(exports, "retiredKeyFromPhrase", { enumerable: true, get: function () { return retiredKeys_1.retiredKeyFromPhrase; } });
 var signatureService_1 = require("./signatureService");
 Object.defineProperty(exports, "SignatureService", { enumerable: true, get: function () { return signatureService_1.SignatureService; } });
 var recoveryPhrase_1 = require("./recoveryPhrase");

package/dist/cjs/crypto/keyManager.js

@@ -47,6 +47,7 @@ const logger_1 = require("../logger");
 const identityDerivations_1 = require("./identityDerivations");
 const identitySigner_1 = require("./identitySigner");
 const organizationKeys_1 = require("./organizationKeys");
+const retiredKeys_1 = require("./retiredKeys");
 const keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
 const keychainGroupMigration_1 = require("./keychainGroupMigration");
 const keychainItems_1 = require("./keychainItems");
@@ -2088,6 +2089,13 @@ 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 (0, retiredKeys_1.forgetRetiredIdentityKeys)();
+            }
+            catch (error) {
+                logger_1.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
@@ -2620,8 +2628,15 @@ 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.
      */
@@ -2629,6 +2644,18 @@ class KeyManager {
         if (isWebPlatform()) {
             return null;
         }
+        if (opts?.publicKey !== undefined) {
+            if ((0, platform_1.isAndroid)() && !KeyManager.identitySignerStore) {
+                const selected = KeyManager._selectorKey(opts.publicKey);
+                if (!selected)
+                    return null;
+                const bridge = await (0, protocol_1.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 ? (0, identityDerivations_1.deriveScopedSeedFromKey)(selected, info) : null;
+        }
         if (opts?.accountId !== undefined) {
             return KeyManager._deriveOrganizationScopedSeed(info, opts.accountId);
         }
@@ -2674,7 +2701,8 @@ 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
@@ -2684,6 +2712,18 @@ class KeyManager {
         if (isWebPlatform()) {
             return null;
         }
+        if (opts?.publicKey !== undefined) {
+            if ((0, platform_1.isAndroid)() && !KeyManager.identitySignerStore) {
+                const selected = KeyManager._selectorKey(opts.publicKey);
+                if (!selected)
+                    return null;
+                const bridge = await (0, protocol_1.loadCommonsIdentityBridge)();
+                return ((await bridge?.signRetiredSocialReceive?.(index, digest, selected, opts.accountId)) ??
+                    null);
+            }
+            const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+            return selected ? (0, identityDerivations_1.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.
@@ -2707,6 +2747,34 @@ class KeyManager {
             : ((await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey()));
         return local ? (0, identityDerivations_1.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 ((0, retiredKeys_1.retiredKeyScope)({ accountId }) === null || !KeyManager.isValidPublicKey(publicKey)) {
+            return null;
+        }
+        const wanted = KeyManager.canonicalPublicKey(publicKey);
+        const current = accountId !== undefined
+            ? await (0, organizationKeys_1.getOrganizationPrivateKey)(accountId)
+            : (0, platform_1.isAndroid)()
+                ? await KeyManager.getPrivateKey()
+                : ((await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey()));
+        if (current && KeyManager.canonicalPublicKey(KeyManager.derivePublicKey(current)) === wanted) {
+            return current;
+        }
+        return (0, retiredKeys_1.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/cjs/crypto/retiredKeys.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retiredKeyScope = retiredKeyScope;
+exports.retireIdentityKey = retireIdentityKey;
+exports.listRetiredIdentityKeys = listRetiredIdentityKeys;
+exports.getRetiredPrivateKey = getRetiredPrivateKey;
+exports.forgetRetiredIdentityKey = forgetRetiredIdentityKey;
+exports.forgetRetiredIdentityKeys = forgetRetiredIdentityKeys;
+exports.syncRetiredKeys = syncRetiredKeys;
+exports.retiredKeyFromPhrase = retiredKeyFromPhrase;
+const bip39_1 = require("@scure/bip39");
+const english_js_1 = require("@scure/bip39/wordlists/english.js");
+const protocol_1 = require("@oxy.so/protocol");
+const secp256k1_1 = require("@oxy.so/protocol/secp256k1");
+const logger_1 = require("../logger");
+const keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
+const platform_1 = require("../utils/platform");
+const identitySigner_1 = require("./identitySigner");
+const keychainGroupMigration_1 = require("./keychainGroupMigration");
+const organizationKeys_1 = require("./organizationKeys");
+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 (0, protocol_1.loadSecureStore)();
+    const access = await (0, keychainAccessGroups_1.resolveKeychainAccess)();
+    if (access.mode === 'grouped' && access.role === 'holder') {
+        await (0, keychainGroupMigration_1.ensureKeychainGroupsMigrated)();
+    }
+    return (0, keychainAccessGroups_1.groupedKeychainStore)(raw, access, 'spending-key');
+}
+/** The ring a selector names: `personal`, or the organization's account id. */
+function retiredKeyScope(selector) {
+    const accountId = selector?.accountId;
+    if (accountId === undefined)
+        return PERSONAL_SCOPE;
+    return (0, organizationKeys_1.isOrganizationAccountId)(accountId) ? accountId : null;
+}
+function canonicalPublicKey(publicKey) {
+    try {
+        const normalized = (0, secp256k1_1.normalizeSecp256k1PublicKey)(publicKey.trim());
+        return PUBLIC_KEY.test(normalized) ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}
+function publicKeyOf(privateKey) {
+    return (0, secp256k1_1.deriveSecp256k1PublicKey)((0, secp256k1_1.normalizeSecp256k1PrivateKey)(privateKey));
+}
+function isHealthyPair(privateKey, publicKey) {
+    if (!(0, secp256k1_1.isValidSecp256k1PrivateKey)(privateKey) || !(0, secp256k1_1.isValidSecp256k1PublicKey)(publicKey)) {
+        return false;
+    }
+    try {
+        return publicKeyOf(privateKey) === (0, secp256k1_1.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 ((0, platform_1.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 (0, platform_1.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 || (0, organizationKeys_1.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_1.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 ((0, platform_1.isWeb)())
+        throw new Error('retired key: only a native device holds one');
+    if ((0, platform_1.isAndroid)() && !(0, identitySigner_1.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.
+ */
+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 = (0, secp256k1_1.normalizeSecp256k1PrivateKey)(key.privateKey);
+    const publicKey = (0, secp256k1_1.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 = (0, platform_1.isAndroid)() ? (0, identitySigner_1.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.
+ */
+async function listRetiredIdentityKeys(selector) {
+    const scope = retiredKeyScope(selector);
+    if (!scope || (0, platform_1.isWeb)())
+        return [];
+    try {
+        if ((0, platform_1.isAndroid)() && !(0, identitySigner_1.registeredIdentitySignerStore)()) {
+            const bridge = await (0, protocol_1.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 (!(0, platform_1.isIOS)() && !(0, platform_1.isAndroid)())
+            return [];
+        const store = await ringStore();
+        return (await readIndex(store)).filter((entry) => entry.scope === scope).map(toListed);
+    }
+    catch (error) {
+        logger_1.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.
+ */
+async function getRetiredPrivateKey(publicKey, selector) {
+    const scope = retiredKeyScope(selector);
+    const canonical = canonicalPublicKey(publicKey);
+    if (!scope || !canonical || (0, platform_1.isWeb)())
+        return null;
+    try {
+        if ((0, platform_1.isAndroid)()) {
+            const signer = (0, identitySigner_1.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 (0, secp256k1_1.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)
+                ? (0, secp256k1_1.normalizeSecp256k1PrivateKey)(mirrored.privateKey)
+                : null;
+        }
+        if (!(0, platform_1.isIOS)())
+            return null;
+        const store = await ringStore();
+        const value = await store.getItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
+        return value && isHealthyPair(value, canonical) ? (0, secp256k1_1.normalizeSecp256k1PrivateKey)(value) : null;
+    }
+    catch (error) {
+        logger_1.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).
+ */
+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 = (0, platform_1.isAndroid)() ? (0, identitySigner_1.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.
+ */
+async function forgetRetiredIdentityKeys(selector) {
+    const scope = retiredKeyScope(selector);
+    if (!scope || (0, platform_1.isWeb)())
+        return 0;
+    if ((0, platform_1.isAndroid)() && !(0, identitySigner_1.registeredIdentitySignerStore)())
+        return 0;
+    const store = await ringStore();
+    const index = await readIndex(store);
+    const signer = (0, platform_1.isAndroid)() ? (0, identitySigner_1.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.
+ */
+async function syncRetiredKeys() {
+    const signer = (0, platform_1.isAndroid)() ? (0, identitySigner_1.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, (0, secp256k1_1.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}.
+ */
+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 || !(0, bip39_1.validateMnemonic)(normalized, english_js_1.wordlist)) {
+        throw new Error('retired key: not a valid recovery phrase');
+    }
+    const seed = await (0, bip39_1.mnemonicToSeed)(normalized);
+    const privateKey = Array.from(seed.subarray(0, 32), (b) => b.toString(16).padStart(2, '0')).join('');
+    return { privateKey, publicKey: publicKeyOf(privateKey) };
+}