@oxy.so/core 7.31.0 → 7.33.0

package/dist/esm/utils/keychainAccessGroups.js

@@ -49,6 +49,15 @@ export const KEYCHAIN_ACCESS_GROUPS = {
     wallet: 'so.oxy.wallet',
     shared: 'group.so.oxy.shared',
 };
+/**
+ * The suffix a DEVELOPMENT build's restricted groups carry (`so.oxy.commons.dev`,
+ * `to.peable.app.dev`: `so.oxy.identity.dev`, `so.oxy.wallet.dev`). A dev build
+ * sits beside the production app on the same phone, is signed by the same team
+ * and runs JavaScript from a dev server, so it never shares a restricted group
+ * with production (`@oxy.so/app-preset` enforces the entitlements). The shared
+ * group has no variant: it holds nothing secret.
+ */
+export const DEV_KEYCHAIN_GROUP_SUFFIX = '.dev';
 /** Thrown while the probe cannot answer (before first unlock). Transient. */
 export class KeychainAccessUnavailableError extends Error {
     constructor(cause) {
@@ -69,6 +78,16 @@ export function keychainGroupFor(item) {
             return 'app';
     }
 }
+/**
+ * Whether `role` may WRITE `item`. Only Commons writes a secret: the Peable
+ * wallet reads, derives and signs with spending keys (and the retired ring)
+ * but never adds one — a key the wallet could add is one the wallet could
+ * choose. (The keychain itself lets every app in the wallet group write it;
+ * this is the SDK's half, and readers check what they find, ADR 0062.)
+ */
+export function mayWriteKeychainItem(role, item) {
+    return role === 'holder' || item === 'shared' || item === 'app';
+}
 /** Whether `role` holds the group `item` lives in. */
 export function mayHoldKeychainItem(role, item) {
     switch (role) {
@@ -92,14 +111,18 @@ export function keychainAccessFromDefaultGroup(defaultGroup, appGroup) {
     }
     const prefix = defaultGroup.slice(0, dot + 1);
     const group = defaultGroup.slice(dot + 1);
-    const role = group === KEYCHAIN_ACCESS_GROUPS.identity
+    const dev = group.endsWith(DEV_KEYCHAIN_GROUP_SUFFIX);
+    const base = dev ? group.slice(0, -DEV_KEYCHAIN_GROUP_SUFFIX.length) : group;
+    const role = base === KEYCHAIN_ACCESS_GROUPS.identity
         ? 'holder'
-        : group === KEYCHAIN_ACCESS_GROUPS.wallet
+        : base === KEYCHAIN_ACCESS_GROUPS.wallet
             ? 'wallet'
             : 'member';
+    // A `.dev` suffix on anything but a restricted group is not a variant.
+    const variant = dev && role !== 'member' ? { variant: DEV_KEYCHAIN_GROUP_SUFFIX } : {};
     return appGroup?.startsWith(prefix)
-        ? { mode: 'grouped', prefix, defaultGroup, role, appGroup }
-        : { mode: 'grouped', prefix, defaultGroup, role };
+        ? { mode: 'grouped', prefix, defaultGroup, role, appGroup, ...variant }
+        : { mode: 'grouped', prefix, defaultGroup, role, ...variant };
 }
 let resolvedAccess = null;
 /**
@@ -152,9 +175,11 @@ export async function resolveKeychainAccess() {
     resolvedAccess = keychainAccessFromDefaultGroup(probe.accessGroup, own.state === 'resolved' ? own.accessGroup : undefined);
     return resolvedAccess;
 }
-/** Forget the memoized access. Tests only. @internal */
+/** Forget the memoized access and the fallback state. Tests only. @internal */
 export function resetKeychainAccessForTests() {
     resolvedAccess = null;
+    holderSharedFallback = false;
+    walletSharedFallbackClosed = false;
 }
 /**
  * The full `kSecAttrAccessGroup` value of `group`, or `undefined` for "no
@@ -172,17 +197,54 @@ export function keychainAccessGroupValue(access, group) {
         // default is the shared group: no group, the calls it always made.
         return access.appGroup ?? (access.role === 'member' ? undefined : access.defaultGroup);
     }
-    return `${access.prefix}${KEYCHAIN_ACCESS_GROUPS[group]}`;
+    const variant = group === 'shared' ? '' : (access.variant ?? '');
+    return `${access.prefix}${KEYCHAIN_ACCESS_GROUPS[group]}${variant}`;
+}
+/**
+ * Whether a SECRET read may still fall back to the pre-split shared group
+ * (R4-7). Every Oxy app can write that group, and keychain items survive an
+ * uninstall, so a secret found there is one Commons did not necessarily write.
+ *
+ * - Commons (`holder`): CLOSED, except while its one-shot migration has proved
+ *   the shared copies are its own (they carry the key its sandbox marker
+ *   records) and could not move them all yet; the migration opens it for that
+ *   launch only ({@link setHolderSharedSecretFallback}).
+ * - The Peable wallet: open until Commons' migration has finished (the
+ *   completion record Commons mirrors into the wallet group), because until
+ *   then an upgraded phone's keys are still in the shared group; closed for
+ *   good once it has seen that record ({@link closeWalletSharedSecretFallback}).
+ */
+let holderSharedFallback = false;
+let walletSharedFallbackClosed = false;
+/** The migration's switch for Commons' fallback. @internal */
+export function setHolderSharedSecretFallback(open) {
+    holderSharedFallback = open;
+}
+/** The wallet saw Commons' completion record: no shared fallback again in this process. @internal */
+export function closeWalletSharedSecretFallback() {
+    walletSharedFallbackClosed = true;
+}
+function sharedFallbackOpen(access) {
+    switch (access.role) {
+        case 'holder':
+            return holderSharedFallback;
+        case 'wallet':
+            return !walletSharedFallbackClosed;
+        case 'member':
+            return false;
+    }
 }
 function option(value) {
     return value === undefined ? {} : { accessGroup: value };
 }
 /**
- * The option bags a READ of `item` tries, in order: its own group, then, for
- * an identity secret or a spending key, the shared group, where those lived
- * before the split (release 4 of the doc drops that fallback). Empty when this
- * app may not hold the item: the caller answers `null` without touching the
- * keychain. An app's own items (`app`) take {@link ownKeychainItemPlan}.
+ * The option bags a READ of `item` tries, in order: its own group, then — for
+ * an identity secret or a spending key, and only while
+ * {@link sharedFallbackOpen} says so — the shared group, where those lived
+ * before the split. Empty when this app may not hold the item: the caller
+ * answers `null` without touching the keychain. Evaluated per read: the
+ * fallback closes during a process's life. An app's own items (`app`) take
+ * {@link ownKeychainItemPlan}.
  */
 export function keychainReadPlan(access, item) {
     if (access.mode === 'ungrouped') {
@@ -193,18 +255,29 @@ export function keychainReadPlan(access, item) {
     }
     const own = keychainGroupFor(item);
     const plan = [option(keychainAccessGroupValue(access, own))];
-    if (own === 'identity' || own === 'wallet') {
-        // Where the split moved these items from.
+    if ((own === 'identity' || own === 'wallet') && sharedFallbackOpen(access)) {
         plan.push(option(keychainAccessGroupValue(access, 'shared')));
     }
     return plan;
 }
 /**
- * Every place a DELETE of `item` must reach: the read plan, so a delete never
- * leaves a pre-split copy behind in the shared group.
+ * Every place a DELETE of `item` must reach: its own group AND the shared
+ * group, whatever the read fallback says, so a delete never leaves a copy
+ * behind where every Oxy app can read it.
  */
 export function keychainDeletePlan(access, item) {
-    return keychainReadPlan(access, item);
+    if (access.mode === 'ungrouped') {
+        return [{}];
+    }
+    if (!mayHoldKeychainItem(access.role, item)) {
+        return [];
+    }
+    const own = keychainGroupFor(item);
+    const plan = [option(keychainAccessGroupValue(access, own))];
+    if (own === 'identity' || own === 'wallet') {
+        plan.push(option(keychainAccessGroupValue(access, 'shared')));
+    }
+    return plan;
 }
 /**
  * The option a WRITE of `item` carries. THROWS when this app may not hold the
@@ -215,8 +288,8 @@ export function keychainWriteOption(access, item) {
     if (access.mode === 'ungrouped') {
         return {};
     }
-    if (!mayHoldKeychainItem(access.role, item)) {
-        throw new Error(`This app (keychain role "${access.role}") may not hold a ${item} keychain item; only Commons writes the identity.`);
+    if (!mayWriteKeychainItem(access.role, item)) {
+        throw new Error(`This app (keychain role "${access.role}") may not write a ${item} keychain item; only Commons writes the identity and the keys the wallet spends.`);
     }
     return option(keychainAccessGroupValue(access, keychainGroupFor(item)));
 }
@@ -284,19 +357,29 @@ export async function deleteThroughPlan(store, key, options, plan) {
 }
 /**
  * `store` with every call routed to `item`'s groups for this app: reads walk
- * the read plan, writes carry the write option (throwing for a role that may
- * not hold the item), deletes reach every location. The constants of the
- * wrapped store are kept, so `store.WHEN_UNLOCKED_THIS_DEVICE_ONLY` still reads.
+ * the read plan (evaluated per read), writes carry the write option (throwing
+ * for a role that may not write the item), deletes reach every location. A
+ * secret WRITE also deletes the item's copy in the shared group (R4-6): a value
+ * Commons writes replaces whatever any app could read there, and a copy that
+ * cannot be removed fails the write instead of staying readable. The constants
+ * of the wrapped store are kept, so `store.WHEN_UNLOCKED_THIS_DEVICE_ONLY` still
+ * reads.
  */
 export function groupedKeychainStore(store, access, item) {
-    const plan = keychainReadPlan(access, item);
+    const sharedCopy = access.mode === 'grouped' && (item === 'identity-secret' || item === 'spending-key')
+        ? option(keychainAccessGroupValue(access, 'shared'))
+        : null;
     const wrapped = {
-        getItemAsync: (key, options) => readThroughPlan(store, key, options ?? {}, plan),
+        getItemAsync: (key, options) => readThroughPlan(store, key, options ?? {}, keychainReadPlan(access, item)),
         setItemAsync: async (key, value, options) => {
             const group = keychainWriteOption(access, item);
             await store.setItemAsync(key, value, { ...(options ?? {}), ...group });
+            if (sharedCopy) {
+                const { keychainAccessible: _accessible, ...rest } = (options ?? {});
+                await store.deleteItemAsync(key, { ...rest, ...sharedCopy });
+            }
         },
-        deleteItemAsync: (key, options) => deleteThroughPlan(store, key, options ?? {}, plan),
+        deleteItemAsync: (key, options) => deleteThroughPlan(store, key, options ?? {}, keychainDeletePlan(access, item)),
     };
     return Object.assign(Object.create(store), wrapped);
 }

package/dist/types/api/identity.d.ts

@@ -67,6 +67,14 @@ export interface RotateKeyResult {
      * should surface a recovery prompt. Omitted on full success.
      */
     localPersistFailed?: true;
+    /**
+     * Whether the encrypted identity backup was re-created under the NEW phrase,
+     * carrying the retired ring with the key just replaced (R4-4). The server
+     * deletes the old backup in the rotation's transaction; `false` (native, the
+     * upload failed) means the caller should offer "Create backup" again, or the
+     * replaced key lives only on this phone. Absent on web.
+     */
+    backupRefreshed?: boolean;
 }
 /**
  * Derive a user's Oxy DID from their stable account id.
@@ -268,6 +276,34 @@ export declare class IdentityBackupApi {
      * from SecureStore.
      */
     create(phrase: string): Promise<BackupStatusResponse>;
+    /**
+     * The retired ring this device holds for the person, limited to keys Oxy's
+     * key history names as THIS account's retired keys (the ring's iOS group is
+     * writable by the wallet app too, and a previous person's ring can outlive a
+     * "Start over"). Empty where no ring is held (web, any app but Commons).
+     * Throws when the history cannot be read while a ring exists, so a backup
+     * never silently drops keys it should carry.
+     */
+    private retiredKeysToCarry;
+    /**
+     * Fetch and open the backup the phrase locates, checking it is the phrase's
+     * own identity. With `missingIsNull`, `null` when there is none (404);
+     * otherwise the request's own error propagates.
+     */
+    private open;
+    /**
+     * Keep every retired key a backup carries in this device's ring. Each pair
+     * must be healthy and must not be the current key; the envelope itself is
+     * authenticated by the phrase. Commons only (the ring refuses elsewhere).
+     * Resolves how many keys are now held; a key that fails is skipped.
+     */
+    private keepCarriedRetiredKeys;
+    /**
+     * Restore ONLY the retired keys the phrase's backup carries into this
+     * device's ring (Commons, after a phrase import or a silent device-backup
+     * restore). Resolves how many were kept; 0 when there is no backup.
+     */
+    restoreRetiredKeys(phrase: string): Promise<number>;
     /**
      * Whether the signed-in user has a stored backup, plus its non-sensitive hint
      * and timestamp. Returns no ciphertext and no locator.

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

@@ -66,6 +66,14 @@ export interface WriteIdentityMarkerInput {
  * rest.
  */
 export declare function readIdentityMarker(): Promise<IdentityMarker | null>;
+/**
+ * Read the marker, THROWING when the storage cannot answer (instead of the
+ * fail-open `null` of {@link readIdentityMarker}). For a caller that must not
+ * mistake "unreadable" for "never written": the iOS keychain migration, which
+ * adopts a pre-split secret only when this marker vouches for it, and records
+ * once that there is nothing to adopt.
+ */
+export declare function readIdentityMarkerStrict(): Promise<IdentityMarker | null>;
 /**
  * Write (create/replace) the marker. Returns `true` when it durably landed,
  * `false` when storage was unavailable or the write threw. Callers treat a

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

@@ -19,11 +19,11 @@ export type { IdentityDeviceBackupStore } from './deviceBackup';
 export type { IdentitySignerStore } from './identitySigner';
 export { generateOrganizationKey, organizationKeyFromPhrase, storeOrganizationKey, getOrganizationPublicKey, getOrganizationPrivateKey, getOrganizationRecoveryPhrase, listOrganizationKeys, deleteOrganizationKey, syncOrganizationKeys, isOrganizationAccountId, isHealthyOrganizationKeyPair, } from './organizationKeys';
 export type { OrganizationKeyPair, GeneratedOrganizationKey, StoredOrganizationKey, } from './organizationKeys';
-export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFor, mayHoldKeychainItem, resolveKeychainAccess, keychainAccessGroupValue, keychainReadPlan, keychainDeletePlan, keychainWriteOption, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, groupedKeychainStore, } from '../utils/keychainAccessGroups';
+export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFor, mayHoldKeychainItem, mayWriteKeychainItem, DEV_KEYCHAIN_GROUP_SUFFIX, resolveKeychainAccess, keychainAccessGroupValue, keychainReadPlan, keychainDeletePlan, keychainWriteOption, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, groupedKeychainStore, } from '../utils/keychainAccessGroups';
 export type { KeychainAccess, KeychainAccessGroupName, KeychainGroup, KeychainGroupOption, KeychainItemClass, KeychainRole, KeychainStoreLike, OwnKeychainItemNames, } from '../utils/keychainAccessGroups';
-export { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+export { ensureKeychainGroupsMigrated, getPreSplitExposure, } from './keychainGroupMigration';
 export type { KeychainGroupMigrationReport, KeychainItemMigrationOutcome, } from './keychainGroupMigration';
-export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, } 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';

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

@@ -290,9 +290,46 @@ export declare 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 getSharedPublicKey(): Promise<string | 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
+     */
+    private static _holdsSpendingKeys;
+    /**
+     * 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 getIdentityPublicKeyForMoney(opts?: {
+        accountId?: string;
+    }): Promise<string | null>;
     /**
      * The shared private key, where this app may hold it: iOS only.
      *
@@ -743,17 +780,23 @@ export declare 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.
      */
     static deriveScopedSeed(info: string, opts?: {
         accountId?: string;
         publicKey?: string;
+        ownerAccountId?: string;
     }): Promise<Uint8Array | null>;
     /**
      * {@link deriveScopedSeed} over an ORGANIZATION key (ADR 0061 D6): Commons'
@@ -780,6 +823,7 @@ export declare class KeyManager {
     static signSocialReceive(index: number, digest: string, opts?: {
         accountId?: string;
         publicKey?: string;
+        ownerAccountId?: string;
     }): Promise<CommonsSocialReceiveSignature | null>;
     /**
      * The private key of the account (personal, or `accountId`'s organization)

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

@@ -1,20 +1,42 @@
+import { type KeychainAccess } from '../utils/keychainAccessGroups';
 /** What happened to one item (or pair) in a run. */
-export type KeychainItemMigrationOutcome = 'absent' | 'moved' | 'conflict' | 'unhealthy' | 'failed' | 'deferred';
+export type KeychainItemMigrationOutcome = 'absent' | 'moved' | 'retired' | 'discarded' | 'failed' | 'deferred';
 export interface KeychainGroupMigrationReport {
     /**
      * - `not-applicable`: not Commons on a split-aware iOS build; nothing to move.
-     * - `complete`: nothing secret is left in the shared group.
-     * - `incomplete`: something stayed (`conflict`, `unhealthy` or `failed`);
-     *   retried next launch.
-     * - `deferred`: the keychain could not be read (locked); retried on the next
-     *   storage access.
+     * - `complete`: the completion record exists; the shared group is never
+     *   read again for a secret.
+     * - `incomplete`: a copy or delete failed; retried next launch.
+     * - `deferred`: the keychain or the marker could not be read (locked);
+     *   retried on the next storage access.
      */
     state: 'not-applicable' | 'complete' | 'incomplete' | 'deferred';
     /** Outcome per item label (`primary`, `phrase`, `organization-1`, …). */
     items: Record<string, KeychainItemMigrationOutcome>;
+    /** Whether this device's marker vouched for the shared copies (absent before a run). */
+    proven?: boolean;
 }
 /** Run the migration once. Exported for tests; production code awaits the gate. */
 export declare function runKeychainGroupMigration(): Promise<KeychainGroupMigrationReport>;
+/**
+ * What every keychain-backed identity access awaits first, by role: Commons
+ * runs (or has run) the migration; the Peable wallet checks once whether
+ * Commons' completion record is in the wallet group, and from then on never
+ * falls back to the shared group for a secret. Never throws.
+ */
+export declare function prepareKeychainAccess(access: KeychainAccess): Promise<void>;
+/**
+ * Commons: whether this device's identity keys sat in the shared keychain
+ * group before the split, where every Oxy iOS app could read them. `publicKey`
+ * is the personal key that was exposed (recommend a rotation while it is still
+ * the current key), `organizations` the organization accounts whose key was.
+ * `null` when nothing was exposed, the migration has not finished, or this is
+ * not Commons on iOS.
+ */
+export declare function getPreSplitExposure(): Promise<{
+    publicKey: string | null;
+    organizations: string[];
+} | null>;
 /**
  * The gate every Commons identity-storage access awaits. One run per process
  * (`complete`, `incomplete` and `not-applicable` are kept; `incomplete` is

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

@@ -60,8 +60,10 @@ export declare function organizationKeyFromPhrase(phrase: string): Promise<Organ
  * it; on iOS only Commons holds the groups it writes (any other app throws).
  *
  * Refuses a pair whose public key does not derive from its private key, and a
- * phrase that does not derive the pair. Overwrites whatever this device held for
- * the organization (a replaced key is the caller's decision, ADR 0061 D7).
+ * phrase that does not derive the pair. A DIFFERENT key this device already
+ * held for the organization is first kept in the organization's retired ring
+ * (ADR 0061 D7 as amended; R4-12): coins under it still need it. When that
+ * cannot be confirmed nothing is overwritten and this throws.
  */
 export declare function storeOrganizationKey(accountId: string, key: StoredOrganizationKey): Promise<void>;
 /**

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

@@ -41,10 +41,32 @@
  *
  * This module imports nothing from `./keyManager` (which imports it).
  */
-/** Whose ring: the person's (`accountId` absent) or an organization's. */
+/**
+ * Whose ring: the person's (`accountId` absent) or an organization's.
+ *
+ * The personal ring is BOUND TO ITS OWNER (R5-2): every personal entry records
+ * the Oxy account id of the person whose key it was, and a personal read
+ * reaches only the entries of `ownerAccountId`. A phone outlives the person on
+ * it ("Start over" keeps the ring: it is money, recoverable from that account's
+ * backup), so the next person on the phone must never list, derive from or
+ * sign with a previous person's keys. A personal read without `ownerAccountId`
+ * reaches nothing. An entry whose owner is not known (a key the access-group
+ * migration kept, an entry written before 7.33.0) is QUARANTINED: invisible to
+ * every reader until Commons binds it with {@link claimRetiredIdentityKeys},
+ * which requires the account's key history to name it.
+ */
 export interface RetiredKeySelector {
     /** An organization's account id; absent for the personal ring. */
     accountId?: string;
+    /**
+     * The person's Oxy account id, for the PERSONAL ring: whose entries are
+     * reached. Ignored for an organization's ring (its owner is `accountId`).
+     */
+    ownerAccountId?: string;
+}
+/** Thrown when the ring's index cannot be read as the ring: never treated as empty (R5-9). */
+export declare class RetiredKeyRingUnreadableError extends Error {
+    constructor(reason: string);
 }
 /** One retired key as the ring lists it: public data only. */
 export interface RetiredIdentityKey {
@@ -63,19 +85,53 @@ export interface RetiredKeyPair {
 /** The ring a selector names: `personal`, or the organization's account id. */
 export declare function retiredKeyScope(selector?: RetiredKeySelector): string | null;
 /**
- * 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 declare function retireIdentityKey(key: RetiredKeyPair, selector?: RetiredKeySelector): Promise<void>;
+/**
+ * {@link retireIdentityKey} from inside the iOS access-group migration, which
+ * 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 declare function retireIdentityKeyDuringMigration(key: RetiredKeyPair, selector?: RetiredKeySelector): Promise<void>;
+/**
+ * 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 declare function claimRetiredIdentityKeys(ownerAccountId: string, publicKeys: readonly string[]): Promise<number>;
+/**
+ * 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 declare function countQuarantinedRetiredKeys(): Promise<number>;
 /**
  * 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 declare function listRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<RetiredIdentityKey[]>;
 /**
@@ -93,19 +149,54 @@ export declare function getRetiredPrivateKey(publicKey: string, selector?: Retir
  */
 export declare function forgetRetiredIdentityKey(publicKey: string, selector?: RetiredKeySelector): Promise<void>;
 /**
- * Forget every retired key of one ring (the person's, or an organization's):
- * called when the identity itself is deleted from this device, so a phone
- * handed on keeps none of the person's old keys. Commons only. Resolves how
- * many it removed.
+ * Forget every retired key of one ring (the person's, or an organization's).
+ * Commons only, and only when the person deletes their Oxy ACCOUNT (Commons'
+ * delete-account flow), which tells them the coins go with it. Deleting the
+ * identity from this device — "Start over", a forced delete — never calls it:
+ * the ring is money, and the same person restoring their identity later must
+ * find it (R4-4). Resolves how many it removed.
  */
 export declare function forgetRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<number>;
 /**
- * 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 declare function syncRetiredKeys(ownerAccountId?: string): Promise<number>;
+/**
+ * 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 declare function exportRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<Array<RetiredKeyPair & {
+    retiredAt: number;
+}>>;
+/**
+ * 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 declare function unmirrorPersonalRetiredKeys(): Promise<void>;
+/**
+ * The pair a previous key's raw PRIVATE KEY gives (64 hex, an optional `0x`),
+ * for a person whose old identity was imported as a private key and so has no
+ * phrase to re-enter. Stores nothing: the caller checks the public key against
+ * the account's key history and only then calls {@link retireIdentityKey}.
  */
-export declare function syncRetiredKeys(): Promise<number>;
+export declare function retiredKeyFromPrivateKey(privateKeyHex: string): RetiredKeyPair;
 /**
  * The pair a previous recovery phrase derives (`seed[0:32]`, the personal-root
  * and organization-key derivation; 12–24 words). Stores nothing: the caller