@oxy.so/core 7.28.0 → 7.30.0

package/dist/esm/crypto/retiredKeys.js

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

package/dist/esm/crypto/secureStoreOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/session/index.js

@@ -72,6 +72,9 @@ export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthSt
 // Commons private identity key: an app that only needs a session must never be
 // handed the key that signs identity approvals.
 export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './sharedDeviceCredential.js';
+// Where the shared device credential (and an app's own items) live on iOS:
+// docs/identity/ios-keychain-access-groups.md, ADR 0062.
+export { KeychainAccessUnavailableError, keychainAccessGroupValue, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, resolveKeychainAccess, } from '../utils/keychainAccessGroups.js';
 // Identity-bound sessions (the identity vault). The pin is the durable
 // `{publicKey, accountId}` binding between this device's PRIMARY identity key
 // and the account it authenticates as; it is what keeps such a client from

package/dist/esm/utils/keychainAccessGroups.js

@@ -0,0 +1,231 @@
+/**
+ * iOS keychain access groups: which group each Oxy keychain item lives in, and
+ * which apps may read it (docs/identity/ios-keychain-access-groups.md, ADR 0062).
+ *
+ * | Group                         | Held by                      | Item class        |
+ * |-------------------------------|------------------------------|-------------------|
+ * | `<TEAM>.so.oxy.identity`      | Commons only (listed FIRST)  | `identity-secret` |
+ * | `<TEAM>.so.oxy.wallet`        | Commons, the Peable wallet   | `spending-key`    |
+ * | `<TEAM>.group.so.oxy.shared`  | every Oxy app                | `shared`          |
+ *
+ * - `identity-secret`: the personal root (primary and backup slots), the
+ *   personal and organization recovery phrases, the organization index. Only
+ *   Commons may read or write them.
+ * - `spending-key`: private keys an app other than Commons signs or derives
+ *   with in process — the personal key's shared slot and organization pairs
+ *   (`deriveScopedSeed`, `signSocialReceive`). Commons writes them; the Peable
+ *   wallet reads them.
+ * - `shared`: what every Oxy app may read: the shared public key and the
+ *   device-session credential.
+ *
+ * The ROLE of this binary comes from the keychain itself: an item written
+ * without a group lands in the app's default group, the first entry of its
+ * `keychain-access-groups` entitlement, and `@oxy.so/app-preset` lets only
+ * Commons put the identity group first and only the Peable wallet the wallet
+ * group. The same probe gives the team prefix, which `kSecAttrAccessGroup`
+ * needs and JavaScript cannot otherwise see.
+ *
+ * Android and web have no access groups: there every helper here answers the
+ * single-store behaviour (`ungrouped`), and Android's narrowing is Commons'
+ * identity host. An iOS build whose native module predates the probe is also
+ * `ungrouped` — exactly what that build's entitlements (one shared group) do.
+ *
+ * This module never imports the identity stack: services' device-session store
+ * and Peable's wallet storage use it too.
+ */
+import { loadKeychainDefaultAccessGroup } from '@oxy.so/protocol';
+import { isIOS } from './platform.js';
+/** The group names after the team prefix, exactly as the entitlements list them. */
+export const KEYCHAIN_ACCESS_GROUPS = {
+    identity: 'so.oxy.identity',
+    wallet: 'so.oxy.wallet',
+    shared: 'group.so.oxy.shared',
+};
+/** Thrown while the probe cannot answer (before first unlock). Transient. */
+export class KeychainAccessUnavailableError extends Error {
+    constructor(cause) {
+        super('The keychain cannot say which access groups this app holds right now.');
+        this.cause = cause;
+        this.name = 'KeychainAccessUnavailableError';
+    }
+}
+/**
+ * The single place each item class is assigned a group. A new kind of item
+ * (F1's retained keys, for one) picks its class and reuses everything below.
+ */
+export function keychainGroupFor(item) {
+    switch (item) {
+        case 'identity-secret':
+            return 'identity';
+        case 'spending-key':
+            return 'wallet';
+        case 'shared':
+            return 'shared';
+    }
+}
+/** Whether `role` holds the group `item` lives in. */
+export function mayHoldKeychainItem(role, item) {
+    switch (role) {
+        case 'holder':
+            return true;
+        case 'wallet':
+            return item !== 'identity-secret';
+        case 'member':
+            return item === 'shared';
+    }
+}
+/** Parse the default access group the probe reported. Exported for tests. */
+export function keychainAccessFromDefaultGroup(defaultGroup) {
+    const dot = defaultGroup.indexOf('.');
+    if (dot <= 0 || dot === defaultGroup.length - 1) {
+        // Not `<prefix>.<group>`: an unsigned simulator build. Nothing to split.
+        return { mode: 'ungrouped' };
+    }
+    const prefix = defaultGroup.slice(0, dot + 1);
+    const group = defaultGroup.slice(dot + 1);
+    const role = group === KEYCHAIN_ACCESS_GROUPS.identity
+        ? 'holder'
+        : group === KEYCHAIN_ACCESS_GROUPS.wallet
+            ? 'wallet'
+            : 'member';
+    return { mode: 'grouped', prefix, defaultGroup, role };
+}
+let resolvedAccess = null;
+/**
+ * This binary's keychain access, memoized once known. THROWS
+ * {@link KeychainAccessUnavailableError} while the probe cannot answer, which
+ * every caller already treats as "storage unavailable, retry".
+ */
+export async function resolveKeychainAccess() {
+    if (resolvedAccess) {
+        return resolvedAccess;
+    }
+    if (!isIOS()) {
+        // Not memoized: until `@oxy.so/services` registers the platform, a phone
+        // reads as "not iOS", and caching that would keep the whole process on the
+        // pre-split behaviour.
+        return { mode: 'ungrouped' };
+    }
+    let probe;
+    try {
+        probe = await loadKeychainDefaultAccessGroup();
+    }
+    catch (cause) {
+        throw new KeychainAccessUnavailableError(cause);
+    }
+    if (probe.state === 'unavailable') {
+        throw new KeychainAccessUnavailableError(probe.cause);
+    }
+    resolvedAccess =
+        probe.state === 'resolved'
+            ? keychainAccessFromDefaultGroup(probe.accessGroup)
+            : { mode: 'ungrouped' };
+    return resolvedAccess;
+}
+/** Forget the memoized access. Tests only. @internal */
+export function resetKeychainAccessForTests() {
+    resolvedAccess = null;
+}
+/** The full `kSecAttrAccessGroup` value of `group`, or `undefined` when ungrouped. */
+export function keychainAccessGroupValue(access, group) {
+    return access.mode === 'grouped' ? `${access.prefix}${KEYCHAIN_ACCESS_GROUPS[group]}` : undefined;
+}
+function option(value) {
+    return value === undefined ? {} : { accessGroup: value };
+}
+/**
+ * The option bags a READ of `item` tries, in order: its own group, then the
+ * shared group, where every item 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.
+ */
+export function 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 !== 'shared') {
+        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.
+ */
+export function keychainDeletePlan(access, item) {
+    return keychainReadPlan(access, item);
+}
+/**
+ * The option a WRITE of `item` carries. THROWS when this app may not hold the
+ * item: an identity secret written by any app but Commons would land in that
+ * app's default group, a second holder nobody knows about.
+ */
+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.`);
+    }
+    return option(keychainAccessGroupValue(access, keychainGroupFor(item)));
+}
+/**
+ * The plan for an app's OWN items (its session credential, its settings, an
+ * imported wallet's phrase) in Commons and the Peable wallet, whose default
+ * group the split changed: written to the default group explicitly — where a
+ * write without a group goes anyway — and read from it FIRST, then from every
+ * group (`{}`), where all of them were written before. Without the explicit
+ * order a read could return whichever of two copies the keychain met first.
+ * Deletes reach every group, as they always did.
+ *
+ * Every other app (`member`) and Android/web keep the calls they always made.
+ */
+export function ownKeychainItemPlan(access) {
+    if (access.mode === 'ungrouped' || access.role === 'member') {
+        return { read: [{}], write: {}, delete: [{}] };
+    }
+    return {
+        read: [option(access.defaultGroup), {}],
+        write: option(access.defaultGroup),
+        delete: [{}],
+    };
+}
+/** Read `key` through `plan`: the first non-null answer. A thrown read propagates. */
+export async function readThroughPlan(store, key, options, plan) {
+    for (const group of plan) {
+        const value = await store.getItemAsync(key, { ...options, ...group });
+        if (value !== null && value !== undefined) {
+            return value;
+        }
+    }
+    return null;
+}
+/** Delete `key` from every location in `plan`. A thrown delete propagates. */
+export async function deleteThroughPlan(store, key, options, plan) {
+    for (const group of plan) {
+        await store.deleteItemAsync(key, { ...options, ...group });
+    }
+}
+/**
+ * `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.
+ */
+export function groupedKeychainStore(store, access, item) {
+    const plan = keychainReadPlan(access, item);
+    const wrapped = {
+        getItemAsync: (key, options) => readThroughPlan(store, key, options ?? {}, plan),
+        setItemAsync: async (key, value, options) => {
+            const group = keychainWriteOption(access, item);
+            await store.setItemAsync(key, value, { ...(options ?? {}), ...group });
+        },
+        deleteItemAsync: (key, options) => deleteThroughPlan(store, key, options ?? {}, plan),
+    };
+    return Object.assign(Object.create(store), wrapped);
+}

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

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

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

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

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

@@ -19,6 +19,12 @@ 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 type { KeychainAccess, KeychainAccessGroupName, KeychainGroupOption, KeychainItemClass, KeychainRole, KeychainStoreLike, } from '../utils/keychainAccessGroups';
+export { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+export type { KeychainGroupMigrationReport, KeychainItemMigrationOutcome, } from './keychainGroupMigration';
+export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, } from './retiredKeys';
+export type { RetiredIdentityKey, RetiredKeyPair, RetiredKeySelector } from './retiredKeys';
 export { SignatureService } from './signatureService';
 export type { SignedMessage, AuthChallenge } from './signatureService';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase';