@oxy.so/core 7.32.0 → 7.33.0

package/dist/esm/crypto/keyManager.js

@@ -11,7 +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 { getRetiredPrivateKey, retiredKeyScope } from './retiredKeys.js';
+import { getRetiredPrivateKey, retiredKeyScope, unmirrorPersonalRetiredKeys } from './retiredKeys.js';
 import { groupedKeychainStore, resolveKeychainAccess, } from '../utils/keychainAccessGroups.js';
 import { prepareKeychainAccess } 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';
@@ -749,12 +749,30 @@ export class KeyManager {
      * `signSocialReceive`) is fresh, so a cached key here would let a caller
      * compare a new seed against an old key.
      *
+     * iOS, in an app that holds the private key (Commons, the Peable wallet:
+     * keychain roles `holder` and `wallet`): DERIVED from the private key in the
+     * wallet group, never read from the public-key item, which sits in the shared
+     * group every Oxy app can write (R5-1); `null` when that app holds no private
+     * key. Every other iOS app reads the public-key item: it holds nothing it
+     * could derive from, and it never spends. Money code uses
+     * {@link getIdentityPublicKeyForMoney}.
+     *
      * @returns Shared public key or null if no shared identity exists
      */
     static async getSharedPublicKey() {
         if (isWebPlatform()) {
             return null;
         }
+        if (isIOS() && (await KeyManager._holdsSpendingKeys())) {
+            // Not cached: a rotation in Commons changes it under the wallet.
+            try {
+                const privateKey = await KeyManager.getSharedPrivateKey();
+                return privateKey ? KeyManager.derivePublicKey(privateKey) : null;
+            }
+            catch {
+                return null;
+            }
+        }
         // Return cached value if available (iOS only; see above).
         if (!isAndroid() && KeyManager.cachedSharedPublicKey !== null) {
             return KeyManager.cachedSharedPublicKey;
@@ -787,6 +805,68 @@ export class KeyManager {
             return null;
         }
     }
+    /**
+     * Whether this iOS app holds spending keys (keychain role `holder` or
+     * `wallet`), so a public key it uses for money must be derived from them.
+     * Throws while the keychain cannot say. @internal
+     */
+    static async _holdsSpendingKeys() {
+        const access = await resolveKeychainAccess();
+        return access.mode === 'grouped' && access.role !== 'member';
+    }
+    /**
+     * THE public key of the identity a money holder (the Peable wallet, Commons)
+     * receives and spends with: the personal key, or with `opts.accountId` that
+     * organization's (ADR 0061 D6). It is the public half of exactly the private
+     * key {@link deriveScopedSeed} and {@link signSocialReceive} use, so an
+     * address shown from it is one this app can spend (R5-1).
+     *
+     * - iOS (Commons, the Peable wallet): DERIVED from the private key in the
+     *   restricted keychain groups (personal: the wallet group's slot, then
+     *   Commons' primary; organization: its pair). Never the shared group's
+     *   public-key item, which every Oxy app can write. `null` when no private
+     *   key is held, and in every other iOS app.
+     * - Android: inside Commons derived from its own key; elsewhere Commons'
+     *   identity host (`describe`), which answers from Commons' own signer
+     *   store over signature-protected IPC.
+     * - Web: `null`.
+     *
+     * Compare the answer with the account's published `#key-1` before showing a
+     * receive address (Peable ADR 0002). Lowercase uncompressed (`04…`).
+     */
+    static async getIdentityPublicKeyForMoney(opts) {
+        if (isWebPlatform()) {
+            return null;
+        }
+        const accountId = opts?.accountId;
+        if (accountId !== undefined) {
+            if (!isOrganizationAccountId(accountId))
+                return null;
+            if (isAndroid() && !KeyManager.identitySignerStore) {
+                const bridge = await loadCommonsIdentityBridge();
+                const description = (await bridge?.describe(accountId)) ?? null;
+                return description?.accountId === accountId && description.publicKey
+                    ? KeyManager.canonicalPublicKey(description.publicKey)
+                    : null;
+            }
+            const organizationKey = await getOrganizationPrivateKey(accountId);
+            return organizationKey ? KeyManager.derivePublicKey(organizationKey) : null;
+        }
+        if (isAndroid()) {
+            if (KeyManager.identitySignerStore) {
+                const local = await KeyManager.getPrivateKey();
+                return local ? KeyManager.derivePublicKey(local) : null;
+            }
+            const bridge = await loadCommonsIdentityBridge();
+            const publicKey = (await bridge?.describe())?.publicKey ?? null;
+            return publicKey ? KeyManager.canonicalPublicKey(publicKey) : null;
+        }
+        if (!isIOS()) {
+            return null;
+        }
+        const privateKey = (await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey());
+        return privateKey ? KeyManager.derivePublicKey(privateKey) : null;
+    }
     /**
      * The shared private key, where this app may hold it: iOS only.
      *
@@ -2050,18 +2130,26 @@ export class KeyManager {
             await KeyManager._clearSharedSlot(store);
             // The retired ring is NOT cleared (R4-4): it is money under the person's
             // previous keys, and "Start over" or a forced delete must not cost it.
-            // The same person restoring their identity finds it again; a different
-            // identity on this phone cannot use it (each entry is checked against
-            // that account's key history before use). Only deleting the Oxy ACCOUNT
-            // clears it, explicitly (`forgetRetiredIdentityKeys`, Commons' flow).
+            // Every personal entry is bound to its owner's account id (R5-2), so the
+            // same person signing in again finds it, and a different person on this
+            // phone never lists, derives from or signs with it. Only deleting the Oxy
+            // ACCOUNT clears it, explicitly (`forgetRetiredIdentityKeys`).
         }
         // 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
         // launch. Best-effort, like the other recovery sources.
         await KeyManager._clearDeviceBackup();
         // Same for the Android signer store: Commons' identity host must stop
-        // answering for a deleted identity, forced or not.
+        // answering for a deleted identity, forced or not — its personal retired
+        // keys included (R5-2): they stay in Commons' own ring, bound to their
+        // owner, but the host must not hand them to the next person on the phone.
         await KeyManager._clearIdentitySigner();
+        try {
+            await unmirrorPersonalRetiredKeys();
+        }
+        catch (error) {
+            logger.warn('Failed to withdraw the personal retired keys from the identity host', { component: 'KeyManager' }, error);
+        }
         // Clear the marker AFTER key deletion succeeds — a marker must never outlive
         // its identity (a leftover marker would route a truly-absent device to
         // `recovery` instead of `welcome`).
@@ -2590,11 +2678,16 @@ export class KeyManager {
      * (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.
+     * retired key never signs in. Never falls back to another key. A PERSONAL
+     * retired key is reached only with `opts.ownerAccountId`, the signed-in
+     * person's account id, and only when the ring keeps it for that account
+     * (R5-2); on Android outside Commons the identity host holds only the
+     * personal keys of the person Commons is signed in as.
      *
      * @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.
+     * @param opts.ownerAccountId The person's account id, for a personal retired key.
      * @returns 32 bytes of derived keying material, or `null` on web / when no
      *          identity key is available to this app.
      */
@@ -2611,7 +2704,7 @@ export class KeyManager {
                 const seed = (await bridge?.deriveRetiredScopedSeed?.(info, selected, opts.accountId)) ?? null;
                 return seed ? hexToBytes(seed) : null;
             }
-            const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+            const selected = await KeyManager._selectedPrivateKey({ ...opts, publicKey: opts.publicKey });
             return selected ? deriveScopedSeedFromKey(selected, info) : null;
         }
         if (opts?.accountId !== undefined) {
@@ -2679,7 +2772,7 @@ export class KeyManager {
                 return ((await bridge?.signRetiredSocialReceive?.(index, digest, selected, opts.accountId)) ??
                     null);
             }
-            const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+            const selected = await KeyManager._selectedPrivateKey({ ...opts, publicKey: opts.publicKey });
             return selected ? signSocialReceiveDigest(selected, index, digest) : null;
         }
         const accountId = opts?.accountId;
@@ -2718,7 +2811,8 @@ export class KeyManager {
     static _selectorKey(publicKey) {
         return KeyManager.isValidPublicKey(publicKey) ? KeyManager.canonicalPublicKey(publicKey) : null;
     }
-    static async _selectedPrivateKey(publicKey, accountId) {
+    static async _selectedPrivateKey(opts) {
+        const { publicKey, accountId, ownerAccountId } = opts;
         if (retiredKeyScope({ accountId }) === null || !KeyManager.isValidPublicKey(publicKey)) {
             return null;
         }
@@ -2731,7 +2825,11 @@ export class KeyManager {
         if (current && KeyManager.canonicalPublicKey(KeyManager.derivePublicKey(current)) === wanted) {
             return current;
         }
-        return getRetiredPrivateKey(wanted, accountId !== undefined ? { accountId } : undefined);
+        return getRetiredPrivateKey(wanted, accountId !== undefined
+            ? { accountId }
+            : ownerAccountId !== undefined
+                ? { ownerAccountId }
+                : undefined);
     }
     /**
      * Get a shortened version of the public key for display

package/dist/esm/crypto/retiredKeys.js

@@ -51,6 +51,13 @@ import { isAndroid, isIOS, isWeb } from '../utils/platform.js';
 import { registeredIdentitySignerStore } from './identitySigner.js';
 import { isOrganizationAccountId } from './keychainItems.js';
 import { prepareKeychainAccess } from './keychainGroupMigration.js';
+/** Thrown when the ring's index cannot be read as the ring: never treated as empty (R5-9). */
+export class RetiredKeyRingUnreadableError extends Error {
+    constructor(reason) {
+        super(`retired key ring: ${reason}`);
+        this.name = 'RetiredKeyRingUnreadableError';
+    }
+}
 const PERSONAL_SCOPE = 'personal';
 /** Android, Commons-local: its own Keystore-backed slot, shared with no other key. */
 const ANDROID_KEYCHAIN_SERVICE = 'oxy_retired_identity';
@@ -119,6 +126,24 @@ function privateOptions(store, forWrite) {
 function indexOptions() {
     return isIOS() ? {} : { keychainService: INDEX_KEYCHAIN_SERVICE };
 }
+const ACCOUNT_ID = /^(?:[0-9a-f]{24}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+/** A well-formed Oxy account id (24-hex or uuid), else `null`. */
+function ownerOf(ownerAccountId) {
+    return ownerAccountId !== undefined && ACCOUNT_ID.test(ownerAccountId)
+        ? ownerAccountId.toLowerCase()
+        : null;
+}
+/**
+ * Whether `entry` may be reached by a reader of `scope` acting for `owner`: an
+ * organization's entries by its own scope, a personal entry only by its owner.
+ */
+function isVisible(entry, scope, owner) {
+    if (entry.scope !== scope)
+        return false;
+    if (scope !== PERSONAL_SCOPE)
+        return true;
+    return owner !== null && entry.owner === owner;
+}
 function isIndexEntry(value) {
     if (typeof value !== 'object' || value === null)
         return false;
@@ -128,23 +153,31 @@ function isIndexEntry(value) {
         typeof entry.publicKey === 'string' &&
         PUBLIC_KEY.test(entry.publicKey) &&
         typeof entry.retiredAt === 'number' &&
-        Number.isFinite(entry.retiredAt));
+        Number.isFinite(entry.retiredAt) &&
+        (entry.owner === undefined || (typeof entry.owner === 'string' && ACCOUNT_ID.test(entry.owner))));
 }
+/**
+ * The ring's index. STRICT (R5-6, R5-9): an index that does not parse, or that
+ * holds an entry this version cannot read, THROWS
+ * {@link RetiredKeyRingUnreadableError} instead of reading as empty, so no
+ * writer overwrites it (losing every entry) and no backup is sealed without
+ * the keys it names. A thrown keychain read propagates.
+ */
 async function readIndex(store) {
     const raw = await store.getItemAsync(INDEX_STORAGE_KEY, indexOptions());
     if (!raw)
         return [];
+    let parsed;
     try {
-        const parsed = JSON.parse(raw);
-        return Array.isArray(parsed) ? parsed.filter(isIndexEntry) : [];
+        parsed = JSON.parse(raw);
     }
-    catch (error) {
-        logger.warn('Retired key index unreadable; treating as empty', {
-            component: 'RetiredKeys',
-            error: error instanceof Error ? error.name : 'unknown',
-        });
-        return [];
+    catch {
+        throw new RetiredKeyRingUnreadableError('the index does not parse');
+    }
+    if (!Array.isArray(parsed) || !parsed.every(isIndexEntry)) {
+        throw new RetiredKeyRingUnreadableError('the index holds an entry this version cannot read');
     }
+    return parsed.map((entry) => entry.owner === undefined ? entry : { ...entry, owner: entry.owner.toLowerCase() });
 }
 async function writeIndex(store, entries) {
     const unique = new Map();
@@ -157,6 +190,7 @@ async function writeIndex(store, entries) {
     await store.setItemAsync(INDEX_STORAGE_KEY, JSON.stringify(sorted), indexOptions());
 }
 function toListed(entry) {
+    // The owner is the reader's own id; it is not repeated.
     return entry.scope === PERSONAL_SCOPE
         ? { publicKey: entry.publicKey, retiredAt: entry.retiredAt }
         : { publicKey: entry.publicKey, accountId: entry.scope, retiredAt: entry.retiredAt };
@@ -181,19 +215,29 @@ async function assertMayWrite() {
     }
 }
 /**
- * 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
+ * Keep `key` in the ring of `selector`'s account. Commons only. A PERSONAL key
+ * needs `selector.ownerAccountId`, the person whose key it was (R5-2): the
+ * signed-in account at a rotation, the account whose key history or backup
+ * named it. Idempotent: a key already kept stays, with its first date; a
+ * quarantined entry of the same key is bound to that owner; an entry bound to
+ * a DIFFERENT owner is refused. 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 === PERSONAL_SCOPE && ownerOf(selector?.ownerAccountId) === null) {
+        throw new Error('retired key: a personal key needs ownerAccountId, the account it belongs to');
+    }
     await keepRetired(key, selector, true);
 }
 /**
  * {@link retireIdentityKey} from inside the iOS access-group migration, which
- * keeps a replaced pre-split copy before deleting it from the shared group and
- * cannot await itself. @internal
+ * keeps a pre-split copy before deleting it from the shared group and cannot
+ * await itself. A personal key without `ownerAccountId` is kept QUARANTINED:
+ * held (it may be money) but reached by nobody until
+ * {@link claimRetiredIdentityKeys} binds it. @internal
  */
 export async function retireIdentityKeyDuringMigration(key, selector) {
     await keepRetired(key, selector, false);
@@ -202,6 +246,7 @@ async function keepRetired(key, selector, gate) {
     const scope = retiredKeyScope(selector);
     if (!scope)
         throw new Error('retired key: accountId must be a 24-hex or uuid account id');
+    const owner = scope === PERSONAL_SCOPE ? ownerOf(selector?.ownerAccountId) : null;
     await assertMayWrite();
     if (!isHealthyPair(key.privateKey, key.publicKey)) {
         throw new Error('retired key: the public key does not derive from the private key');
@@ -209,51 +254,114 @@ async function keepRetired(key, selector, gate) {
     const privateKey = normalizeSecp256k1PrivateKey(key.privateKey);
     const publicKey = normalizeSecp256k1PublicKey(key.publicKey);
     const store = await ringStore(gate);
+    // Strict: an unreadable index stops the write before the key is touched.
+    const before = await readIndex(store);
+    const existing = before.find((entry) => entry.scope === scope && entry.publicKey === publicKey);
+    if (existing?.owner !== undefined && owner !== null && existing.owner !== owner) {
+        throw new Error('retired key: this key is kept for a different account');
+    }
     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 index = await readIndex(store);
+    const kept = index.find((entry) => entry.scope === scope && entry.publicKey === publicKey);
+    if (!kept) {
+        await writeIndex(store, [
+            ...index,
+            owner === null
+                ? { scope, publicKey, retiredAt: Date.now() }
+                : { scope, publicKey, retiredAt: Date.now(), owner },
+        ]);
+    }
+    else if (kept.owner === undefined && owner !== null) {
+        await writeIndex(store, index.map((entry) => (entry === kept ? { ...entry, owner } : entry)));
+    }
+    // The identity host answers only from the signer store, which holds the
+    // organizations' rings and the CURRENT person's personal entries; a
+    // quarantined entry is never mirrored.
     const signer = isAndroid() ? registeredIdentitySignerStore() : null;
-    if (signer?.writeRetired && !(await signer.writeRetired(scope, privateKey, publicKey))) {
+    if (signer?.writeRetired &&
+        (scope !== PERSONAL_SCOPE || owner !== null) &&
+        !(await signer.writeRetired(scope, privateKey, publicKey))) {
         throw new Error(`The identity signer store (${signer.name}) did not confirm the retired key.`);
     }
+}
+/**
+ * Bind the QUARANTINED personal entries whose public key `publicKeys` names to
+ * `ownerAccountId` (R5-2, R5-3). Commons only, with the signed-in person's
+ * account id and that account's key history from Oxy
+ * (`oxy.identity.keyHistory()`: retired and current public keys): a key the
+ * account's own history names is that account's. Entries bound to anyone, and
+ * keys the history does not name, are left as they are. Resolves how many it
+ * bound; call {@link syncRetiredKeys} after it on Android.
+ */
+export async function claimRetiredIdentityKeys(ownerAccountId, publicKeys) {
+    const owner = ownerOf(ownerAccountId);
+    if (owner === null)
+        throw new Error('retired key: ownerAccountId must be an account id');
+    if (isWeb())
+        return 0;
+    await assertMayWrite();
+    const named = new Set(publicKeys.map((key) => canonicalPublicKey(key)).filter((key) => key !== null));
+    const store = await ringStore();
     const index = await readIndex(store);
-    if (!index.some((entry) => entry.scope === scope && entry.publicKey === publicKey)) {
-        await writeIndex(store, [...index, { scope, publicKey, retiredAt: Date.now() }]);
-    }
+    let bound = 0;
+    const next = index.map((entry) => {
+        if (entry.scope !== PERSONAL_SCOPE || entry.owner !== undefined)
+            return entry;
+        if (!named.has(entry.publicKey))
+            return entry;
+        bound += 1;
+        return { ...entry, owner };
+    });
+    if (bound > 0)
+        await writeIndex(store, next);
+    return bound;
+}
+/**
+ * How many personal entries are quarantined (no known owner). Commons shows
+ * them as "keys from before" the person can claim by adding the phrase, and
+ * {@link claimRetiredIdentityKeys} binds the ones the account's history names.
+ */
+export async function countQuarantinedRetiredKeys() {
+    if (isWeb() || (isAndroid() && !registeredIdentitySignerStore()))
+        return 0;
+    const store = await ringStore();
+    return (await readIndex(store)).filter((entry) => entry.scope === PERSONAL_SCOPE && entry.owner === undefined).length;
 }
 /**
  * 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.
+ * The personal ring answers only `selector.ownerAccountId`'s entries (none
+ * without it; R5-2). iOS and Commons: the ring's index. Android elsewhere:
+ * Commons' identity host (the wallet only), which holds only the personal
+ * entries of the person Commons is signed in as and 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, and check every entry against the account's key history.
+ *
+ * STRICT (R5-6): a ring that cannot be read throws (the keychain's error, or
+ * {@link RetiredKeyRingUnreadableError}); it never reads as empty.
  */
 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',
-        });
+    const owner = ownerOf(selector?.ownerAccountId);
+    if (scope === PERSONAL_SCOPE && owner === null)
         return [];
+    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) => isVisible(entry, scope, owner)).map(toListed);
 }
 /**
  * The private half of a retired key, where this app may hold it: Commons (both
@@ -267,12 +375,18 @@ export async function getRetiredPrivateKey(publicKey, selector) {
     const canonical = canonicalPublicKey(publicKey);
     if (!scope || !canonical || isWeb())
         return null;
+    const owner = ownerOf(selector?.ownerAccountId);
+    if (scope === PERSONAL_SCOPE && owner === null)
+        return null;
     try {
         if (isAndroid()) {
             const signer = registeredIdentitySignerStore();
             if (!signer)
                 return null;
             const store = await ringStore();
+            if (!(await readIndex(store)).some((entry) => isVisible(entry, scope, owner) && entry.publicKey === canonical)) {
+                return null;
+            }
             const local = await store.getItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
             if (local && isHealthyPair(local, canonical))
                 return normalizeSecp256k1PrivateKey(local);
@@ -285,6 +399,11 @@ export async function getRetiredPrivateKey(publicKey, selector) {
         if (!isIOS())
             return null;
         const store = await ringStore();
+        // The index decides who may reach a key (R5-2); a key it does not list for
+        // this reader is not theirs, whatever item exists.
+        if (!(await readIndex(store)).some((entry) => isVisible(entry, scope, owner) && entry.publicKey === canonical)) {
+            return null;
+        }
         const value = await store.getItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
         return value && isHealthyPair(value, canonical) ? normalizeSecp256k1PrivateKey(value) : null;
     }
@@ -306,8 +425,12 @@ export async function forgetRetiredIdentityKey(publicKey, selector) {
     const canonical = canonicalPublicKey(publicKey);
     if (!scope || !canonical)
         throw new Error('retired key: invalid selector or public key');
+    const owner = ownerOf(selector?.ownerAccountId);
     await assertMayWrite();
     const store = await ringStore();
+    const visible = (await readIndex(store)).some((entry) => isVisible(entry, scope, owner) && entry.publicKey === canonical);
+    if (!visible)
+        throw new Error('retired key: not a key of this account');
     await store.deleteItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
     const signer = isAndroid() ? registeredIdentitySignerStore() : null;
     await signer?.clearRetired?.(scope, canonical);
@@ -327,33 +450,47 @@ export async function forgetRetiredIdentityKeys(selector) {
         return 0;
     if (isAndroid() && !registeredIdentitySignerStore())
         return 0;
+    const owner = ownerOf(selector?.ownerAccountId);
+    if (scope === PERSONAL_SCOPE && owner === null)
+        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)
+        if (!isVisible(entry, scope, owner))
             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));
+    await writeIndex(store, index.filter((entry) => !isVisible(entry, scope, owner)));
     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.
+ * Commons on Android: make the identity signer store hold exactly what the
+ * identity host may answer — every organization ring, and the personal entries
+ * of `ownerAccountId` (the person Commons is signed in as) — so the host
+ * answers for them after that file was rebuilt (its self-heal leaves it
+ * empty), and never for a previous person's keys (R5-2): every other personal
+ * entry is removed from the signer store (its own slot keeps it). Without
+ * `ownerAccountId` no personal entry is mirrored. Call on every boot and after
+ * every sign-in, beside `syncOrganizationKeys`. Resolves how many it mirrored.
+ * Elsewhere 0.
  */
-export async function syncRetiredKeys() {
+export async function syncRetiredKeys(ownerAccountId) {
     const signer = isAndroid() ? registeredIdentitySignerStore() : null;
     if (!signer?.writeRetired || !signer.readRetired)
         return 0;
+    const owner = ownerOf(ownerAccountId);
     const store = await ringStore();
+    const index = await readIndex(store);
+    const allowed = new Set(index.filter((entry) => isVisible(entry, PERSONAL_SCOPE, owner)).map((e) => e.publicKey));
+    await clearPersonalMirror(signer, index, allowed);
     let mirrored = 0;
-    for (const entry of await readIndex(store)) {
+    for (const entry of index) {
+        if (entry.scope === PERSONAL_SCOPE && !isVisible(entry, PERSONAL_SCOPE, owner))
+            continue;
         const privateKey = await store.getItemAsync(privateKeyName(entry.scope, entry.publicKey), privateOptions(store, false));
         if (!privateKey || !isHealthyPair(privateKey, entry.publicKey))
             continue;
@@ -367,12 +504,14 @@ export async function syncRetiredKeys() {
     return mirrored;
 }
 /**
- * Every retired key of `selector`'s ring WITH its private half, for the
- * encrypted identity backup (`oxy.identity.backup.create`), which carries them
- * under the CURRENT phrase so a lost phone costs no more than the current
- * phrase does (R4-4). Commons only; an entry whose private half is missing or
- * does not derive its public key is left out. Never log or transmit the result
- * except inside that encrypted envelope.
+ * Every retired key of `selector`'s ring (personal: `ownerAccountId`'s entries)
+ * WITH its private half, for the encrypted identity backup
+ * (`oxy.identity.backup.create`), which carries them under the CURRENT phrase
+ * so a lost phone costs no more than the current phrase does (R4-4). Commons
+ * only. STRICT (R5-6): an unreadable ring, or a listed entry whose private
+ * half is missing or does not derive its public key, THROWS — a backup is
+ * never sealed without a key the ring says it holds. Never log or transmit the
+ * result except inside that encrypted envelope.
  */
 export async function exportRetiredIdentityKeys(selector) {
     const scope = retiredKeyScope(selector);
@@ -381,12 +520,57 @@ export async function exportRetiredIdentityKeys(selector) {
     await assertMayWrite();
     const out = [];
     for (const entry of await listRetiredIdentityKeys(selector)) {
-        const privateKey = await getRetiredPrivateKey(entry.publicKey, selector);
-        if (privateKey)
-            out.push({ privateKey, publicKey: entry.publicKey, retiredAt: entry.retiredAt });
+        const privateKey = await readRetiredStrict(entry.publicKey, scope);
+        out.push({ privateKey, publicKey: entry.publicKey, retiredAt: entry.retiredAt });
     }
     return out;
 }
+/** A listed entry's private half, or a throw: Commons' own slot, then (Android) the signer copy. */
+async function readRetiredStrict(publicKey, scope) {
+    const store = await ringStore();
+    const local = await store.getItemAsync(privateKeyName(scope, publicKey), privateOptions(store, false));
+    if (local && isHealthyPair(local, publicKey))
+        return normalizeSecp256k1PrivateKey(local);
+    const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+    const mirrored = (await signer?.readRetired?.(scope, publicKey)) ?? null;
+    if (mirrored && isHealthyPair(mirrored.privateKey, publicKey)) {
+        return normalizeSecp256k1PrivateKey(mirrored.privateKey);
+    }
+    throw new RetiredKeyRingUnreadableError('a listed key has no readable private half');
+}
+/**
+ * Commons on Android, when the identity leaves this device ("Start over", a
+ * forced delete): remove every PERSONAL entry from the identity signer store,
+ * so the identity host answers no other app with them before the next person
+ * signs in (R5-2). Commons' own slot and index keep them (money, bound to
+ * their owner). Elsewhere a no-op.
+ */
+export async function unmirrorPersonalRetiredKeys() {
+    const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+    if (!signer?.clearRetired)
+        return;
+    let index = [];
+    try {
+        index = await readIndex(await ringStore());
+    }
+    catch {
+        // The signer store's own list below still reaches every mirrored entry.
+    }
+    await clearPersonalMirror(signer, index, new Set());
+}
+/** Remove from the signer store every personal entry not in `allowed`: the index's and the store's own list. */
+async function clearPersonalMirror(signer, index, allowed) {
+    if (!signer.clearRetired)
+        return;
+    const mirrored = new Set(index.filter((entry) => entry.scope === PERSONAL_SCOPE).map((entry) => entry.publicKey));
+    for (const publicKey of (await signer.listRetired?.(PERSONAL_SCOPE)) ?? []) {
+        mirrored.add(publicKey.toLowerCase());
+    }
+    for (const publicKey of mirrored) {
+        if (!allowed.has(publicKey))
+            await signer.clearRetired(PERSONAL_SCOPE, publicKey);
+    }
+}
 /**
  * The pair a previous key's raw PRIVATE KEY gives (64 hex, an optional `0x`),
  * for a person whose old identity was imported as a private key and so has no

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

@@ -23,7 +23,7 @@ export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFo
 export type { KeychainAccess, KeychainAccessGroupName, KeychainGroup, KeychainGroupOption, KeychainItemClass, KeychainRole, KeychainStoreLike, OwnKeychainItemNames, } from '../utils/keychainAccessGroups';
 export { ensureKeychainGroupsMigrated, getPreSplitExposure, } from './keychainGroupMigration';
 export type { KeychainGroupMigrationReport, KeychainItemMigrationOutcome, } from './keychainGroupMigration';
-export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, retiredKeyFromPrivateKey, exportRetiredIdentityKeys, } from './retiredKeys';
+export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, retiredKeyFromPrivateKey, exportRetiredIdentityKeys, claimRetiredIdentityKeys, countQuarantinedRetiredKeys, unmirrorPersonalRetiredKeys, RetiredKeyRingUnreadableError, } from './retiredKeys';
 export type { RetiredIdentityKey, RetiredKeyPair, RetiredKeySelector } from './retiredKeys';
 export { SignatureService } from './signatureService';
 export type { SignedMessage, AuthChallenge } from './signatureService';