@oxy.so/core 7.29.0 → 7.31.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/session/authStateStore.js

@@ -46,6 +46,18 @@ export function matchesAuthState(actual, expected) {
  */
 export const AUTH_STATE_STORAGE_KEY = 'oxy.auth.v1';
 export const AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY = 'oxy.auth.automatic-identity-signin-suppressed.v1';
+/**
+ * What `ownKeychainItemPlan` (ADR 0062 D6) must know about a key a native
+ * session store keeps — this module's three and the identity pin: every Oxy app
+ * writes it under the same name, so on iOS a copy in the shared group may be
+ * another app's session and is never read as this app's. The sign-out marker
+ * can only withhold, so a shared copy of it still counts.
+ */
+export function nativeSessionItemNames(key) {
+    return key === AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY
+        ? 'every-oxy-app-withholding'
+        : 'every-oxy-app';
+}
 /**
  * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
  * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a

package/dist/esm/session/index.js

@@ -65,7 +65,7 @@ export { AccountDialogController, createAccountDialogController, } from './accou
 // device credential is `deviceId` + `deviceSecret`; the access token is re-minted
 // via `POST /session/device/token`.
 // ---------------------------------------------------------------------------
-export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './authStateStore.js';
+export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, nativeSessionItemNames, AUTH_STATE_STORAGE_KEY, AUTH_STATE_TOKEN_STORAGE_KEY, AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY, } from './authStateStore.js';
 // The shared NATIVE DeviceSession credential — how several official apps on one
 // device end up on ONE `DeviceSession` and therefore one active context. It is an
 // ordinary revocable `deviceId` + `deviceSecret`, deliberately NOT the

package/dist/esm/utils/keychainAccessGroups.js

@@ -7,6 +7,7 @@
  * | `<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`          |
+ * | `<TEAM>.<bundle id>`          | that app alone               | `app`             |
  *
  * - `identity-secret`: the personal root (primary and backup slots), the
  *   personal and organization recovery phrases, the organization index. Only
@@ -16,14 +17,21 @@
  *   (`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.
+ *   device-session credential (the one cross-app session join point).
+ * - `app`: an app's OWN items, readable by no other app: its session
+ *   credential (`oxy.auth.v1` and the rest of the SDK's session store), its
+ *   identity pin, its settings, the Peable wallet's imported phrases. The group
+ *   is the app's application identifier, which Apple makes every app a member
+ *   of; no app lists it and no other app can name it. Android's counterpart is
+ *   the app's own storage (ADR 0062 D6).
  *
  * 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.
+ * needs and JavaScript cannot otherwise see; a second probe proves the app's
+ * own group (`<prefix><bundle id>`) is writable.
  *
  * Android and web have no access groups: there every helper here answers the
  * single-store behaviour (`ungrouped`), and Android's narrowing is Commons'
@@ -33,7 +41,7 @@
  * 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 { loadKeychainApplicationAccessGroup, 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 = {
@@ -49,10 +57,6 @@ export class KeychainAccessUnavailableError extends Error {
         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':
@@ -61,6 +65,8 @@ export function keychainGroupFor(item) {
             return 'wallet';
         case 'shared':
             return 'shared';
+        case 'app':
+            return 'app';
     }
 }
 /** Whether `role` holds the group `item` lives in. */
@@ -71,11 +77,14 @@ export function mayHoldKeychainItem(role, item) {
         case 'wallet':
             return item !== 'identity-secret';
         case 'member':
-            return item === 'shared';
+            return item === 'shared' || item === 'app';
     }
 }
-/** Parse the default access group the probe reported. Exported for tests. */
-export function keychainAccessFromDefaultGroup(defaultGroup) {
+/**
+ * Parse the default access group the probe reported, and the app's own group
+ * when the second probe proved it. Exported for tests.
+ */
+export function keychainAccessFromDefaultGroup(defaultGroup, appGroup) {
     const dot = defaultGroup.indexOf('.');
     if (dot <= 0 || dot === defaultGroup.length - 1) {
         // Not `<prefix>.<group>`: an unsigned simulator build. Nothing to split.
@@ -88,7 +97,9 @@ export function keychainAccessFromDefaultGroup(defaultGroup) {
         : group === KEYCHAIN_ACCESS_GROUPS.wallet
             ? 'wallet'
             : 'member';
-    return { mode: 'grouped', prefix, defaultGroup, role };
+    return appGroup?.startsWith(prefix)
+        ? { mode: 'grouped', prefix, defaultGroup, role, appGroup }
+        : { mode: 'grouped', prefix, defaultGroup, role };
 }
 let resolvedAccess = null;
 /**
@@ -116,28 +127,62 @@ export async function resolveKeychainAccess() {
     if (probe.state === 'unavailable') {
         throw new KeychainAccessUnavailableError(probe.cause);
     }
-    resolvedAccess =
-        probe.state === 'resolved'
-            ? keychainAccessFromDefaultGroup(probe.accessGroup)
-            : { mode: 'ungrouped' };
+    if (probe.state !== 'resolved') {
+        resolvedAccess = { mode: 'ungrouped' };
+        return resolvedAccess;
+    }
+    const access = keychainAccessFromDefaultGroup(probe.accessGroup);
+    if (access.mode === 'ungrouped') {
+        resolvedAccess = access;
+        return resolvedAccess;
+    }
+    // The app's own group. A thrown probe is NOT degraded to "no app group": this
+    // process would then write the app's items to the old place while the next
+    // one reads the new place first, and see a stale value.
+    let own;
+    try {
+        own = await loadKeychainApplicationAccessGroup(access.prefix);
+    }
+    catch (cause) {
+        throw new KeychainAccessUnavailableError(cause);
+    }
+    if (own.state === 'unavailable') {
+        throw new KeychainAccessUnavailableError(own.cause);
+    }
+    resolvedAccess = keychainAccessFromDefaultGroup(probe.accessGroup, own.state === 'resolved' ? own.accessGroup : undefined);
     return resolvedAccess;
 }
 /** Forget the memoized access. Tests only. @internal */
 export function resetKeychainAccessForTests() {
     resolvedAccess = null;
 }
-/** The full `kSecAttrAccessGroup` value of `group`, or `undefined` when ungrouped. */
+/**
+ * The full `kSecAttrAccessGroup` value of `group`, or `undefined` for "no
+ * group" (the app's default): always when ungrouped, and for `app` on a build
+ * that cannot place items there (see {@link ownKeychainItemPlan}).
+ */
 export function keychainAccessGroupValue(access, group) {
-    return access.mode === 'grouped' ? `${access.prefix}${KEYCHAIN_ACCESS_GROUPS[group]}` : undefined;
+    if (access.mode === 'ungrouped') {
+        return undefined;
+    }
+    if (group === 'app') {
+        // Commons' and the Peable wallet's default groups are theirs (no other app
+        // writes its own items there), so a build without the app-group probe
+        // keeps its own items there, as ADR 0062 D3 put them. Every other app's
+        // 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]}`;
 }
 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.
+ * 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}.
  */
 export function keychainReadPlan(access, item) {
     if (access.mode === 'ungrouped') {
@@ -148,7 +193,8 @@ export function keychainReadPlan(access, item) {
     }
     const own = keychainGroupFor(item);
     const plan = [option(keychainAccessGroupValue(access, own))];
-    if (own !== 'shared') {
+    if (own === 'identity' || own === 'wallet') {
+        // Where the split moved these items from.
         plan.push(option(keychainAccessGroupValue(access, 'shared')));
     }
     return plan;
@@ -175,25 +221,50 @@ export function keychainWriteOption(access, item) {
     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.
+ * The plan for an app's OWN items (class `app`, ADR 0062 D6): written to the
+ * app's own group (`<prefix><bundle id>`), which no other app can read, and
+ * read from it FIRST. Then:
+ *
+ * - from where this app kept them before: Commons' and the Peable wallet's
+ *   default group (D3), which no other app writes its own items to;
+ * - for `this-app` names, from every group (`{}`), where they were before the
+ *   split; deletes reach every group;
+ * - for `every-oxy-app` names, nowhere else (see {@link OwnKeychainItemNames}),
+ *   and deletes reach exactly the read locations, earlier ones first, so a
+ *   failed delete never leaves an older copy as the only one;
+ * - for `every-oxy-app-withholding` names, the shared group last on read and
+ *   first on delete.
  *
- * Every other app (`member`) and Android/web keep the calls they always made.
+ * Nothing is copied or deleted to migrate: the next write lands in the app
+ * group and the read order makes it win, so a crash or a failure at any step
+ * leaves the value the app had.
+ *
+ * A native build whose module predates the app-group probe (`appGroup`
+ * absent) keeps its items where that build put them: Commons and the wallet in
+ * their default group, every other app the calls it always made (the one
+ * shared item, until that app's next native build). Android and web: no
+ * options.
  */
-export function ownKeychainItemPlan(access) {
-    if (access.mode === 'ungrouped' || access.role === 'member') {
+export function ownKeychainItemPlan(access, names = 'this-app') {
+    if (access.mode === 'ungrouped') {
         return { read: [{}], write: {}, delete: [{}] };
     }
-    return {
-        read: [option(access.defaultGroup), {}],
-        write: option(access.defaultGroup),
-        delete: [{}],
-    };
+    const own = keychainAccessGroupValue(access, keychainGroupFor('app'));
+    if (own === undefined) {
+        return { read: [{}], write: {}, delete: [{}] };
+    }
+    const earlier = access.role !== 'member' && own !== access.defaultGroup ? [option(access.defaultGroup)] : [];
+    const mine = [option(own), ...earlier];
+    switch (names) {
+        case 'this-app':
+            return { read: [...mine, {}], write: option(own), delete: [{}] };
+        case 'every-oxy-app':
+            return { read: mine, write: option(own), delete: [...mine].reverse() };
+        case 'every-oxy-app-withholding': {
+            const read = [...mine, option(keychainAccessGroupValue(access, 'shared'))];
+            return { read, write: option(own), delete: [...read].reverse() };
+        }
+    }
 }
 /** Read `key` through `plan`: the first non-null answer. A thrown read propagates. */
 export async function readThroughPlan(store, key, options, plan) {

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 {