@oxy.so/core 7.30.0 → 7.32.0

package/dist/esm/crypto/organizationKeys.js

@@ -32,7 +32,8 @@ 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 { prepareKeychainAccess } from './keychainGroupMigration.js';
+import { retireIdentityKey } from './retiredKeys.js';
 import { ORGANIZATION_ANDROID_KEYCHAIN_SERVICE as ANDROID_KEYCHAIN_SERVICE, ORGANIZATION_INDEX_KEYCHAIN_SERVICE as INDEX_KEYCHAIN_SERVICE, ORGANIZATION_INDEX_STORAGE_KEY as INDEX_STORAGE_KEY, ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE as MNEMONIC_KEYCHAIN_SERVICE, isOrganizationAccountId, organizationMnemonicName as mnemonicName, organizationPrivateKeyName as privateKeyName, organizationPublicKeyName as publicKeyName, serializeOrganizationIndex, } from './keychainItems.js';
 export { isOrganizationAccountId };
 const ORGANIZATION_PHRASE_WORDS = 24;
@@ -102,9 +103,7 @@ export async function organizationKeyFromPhrase(phrase) {
 async function secureStore(item) {
     const raw = await loadSecureStore();
     const access = await resolveKeychainAccess();
-    if (access.mode === 'grouped' && access.role === 'holder') {
-        await ensureKeychainGroupsMigrated();
-    }
+    await prepareKeychainAccess(access);
     return groupedKeychainStore(raw, access, item);
 }
 const pairStore = () => secureStore('spending-key');
@@ -195,8 +194,10 @@ async function readLocalPair(accountId) {
  * 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 async function storeOrganizationKey(accountId, key) {
     assertAccountId(accountId);
@@ -218,6 +219,18 @@ export async function storeOrganizationKey(accountId, key) {
         throw new Error('On Android only Commons holds organization keys; this app has no identity signer store for them.');
     }
     const store = await pairStore();
+    const previous = await heldPrivateKey(store, accountId);
+    if (previous) {
+        const previousPublic = deriveSecp256k1PublicKey(previous);
+        if (previousPublic !== publicKey) {
+            try {
+                await retireIdentityKey({ privateKey: previous, publicKey: previousPublic }, { accountId });
+            }
+            catch (error) {
+                throw new Error(`organization key: the key this device held could not be kept as a previous key, so it was not replaced (${error instanceof Error ? error.message : 'unknown'})`);
+            }
+        }
+    }
     await store.setItemAsync(privateKeyName(accountId), privateKey, pairOptions(store, true));
     await store.setItemAsync(publicKeyName(accountId), publicKey, pairOptions(store, false));
     if (signer?.writeOrganization &&
@@ -298,6 +311,21 @@ export async function listOrganizationKeys() {
         return [];
     return readIndex(await indexStore());
 }
+/**
+ * The private key this device holds for `accountId`, whatever its public half
+ * says (an unhealthy pair is still a key coins may sit under): the slot, then
+ * on Android the signer store's copy. `null` when there is none.
+ */
+async function heldPrivateKey(store, accountId) {
+    const local = await store.getItemAsync(privateKeyName(accountId), pairOptions(store, false));
+    if (local && isValidSecp256k1PrivateKey(local))
+        return normalizeSecp256k1PrivateKey(local);
+    const signer = isAndroid() ? registeredIdentitySignerStore() : null;
+    const mirrored = (await signer?.readOrganization?.(accountId)) ?? null;
+    return mirrored && isValidSecp256k1PrivateKey(mirrored.privateKey)
+        ? normalizeSecp256k1PrivateKey(mirrored.privateKey)
+        : null;
+}
 /** Forget an organization key on this device: its pair, its phrase, its signer copy and its index entry. */
 export async function deleteOrganizationKey(accountId) {
     assertAccountId(accountId);

package/dist/esm/crypto/retiredKeys.js

@@ -49,8 +49,8 @@ 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';
+import { isOrganizationAccountId } from './keychainItems.js';
+import { prepareKeychainAccess } from './keychainGroupMigration.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';
@@ -61,15 +61,15 @@ 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.
+ * Commons every access first awaits the access-group migration (`gate: false`
+ * is the migration itself, keeping a pre-split copy). On Android the grouping
+ * is a no-op and Commons' own services below apply.
  */
-async function ringStore() {
+async function ringStore(gate = true) {
     const raw = await loadSecureStore();
     const access = await resolveKeychainAccess();
-    if (access.mode === 'grouped' && access.role === 'holder') {
-        await ensureKeychainGroupsMigrated();
-    }
+    if (gate)
+        await prepareKeychainAccess(access);
     return groupedKeychainStore(raw, access, 'spending-key');
 }
 /** The ring a selector names: `personal`, or the organization's account id. */
@@ -161,13 +161,24 @@ function toListed(entry) {
         ? { 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() {
+/**
+ * Whether this app writes the ring: Commons only (Android: the signer store it
+ * registers; iOS: the keychain role `holder`). The Peable wallet holds the
+ * wallet group too, but only reads, derives and signs: a key the wallet could
+ * add to the ring is a key it could choose (R4-14).
+ */
+async 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.');
     }
+    if (isIOS()) {
+        const access = await resolveKeychainAccess();
+        if (access.mode === 'grouped' && access.role !== 'holder') {
+            throw new Error('On iOS only Commons writes retired keys; this app may only read them.');
+        }
+    }
 }
 /**
  * Keep `key` in the ring of `selector`'s account. Commons only. Idempotent: a
@@ -177,16 +188,27 @@ function assertMayWrite() {
  * caller about to replace the key can stop before anything is lost.
  */
 export async function retireIdentityKey(key, selector) {
+    await keepRetired(key, selector, true);
+}
+/**
+ * {@link retireIdentityKey} from inside the iOS access-group migration, which
+ * keeps a replaced pre-split copy before deleting it from the shared group and
+ * cannot await itself. @internal
+ */
+export async function retireIdentityKeyDuringMigration(key, selector) {
+    await keepRetired(key, selector, false);
+}
+async function keepRetired(key, selector, gate) {
     const scope = retiredKeyScope(selector);
     if (!scope)
         throw new Error('retired key: accountId must be a 24-hex or uuid account id');
-    assertMayWrite();
+    await 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();
+    const store = await ringStore(gate);
     await store.setItemAsync(privateKeyName(scope, publicKey), privateKey, privateOptions(store, true));
     const readBack = await store.getItemAsync(privateKeyName(scope, publicKey), privateOptions(store, false));
     if (readBack !== privateKey) {
@@ -284,7 +306,7 @@ export async function forgetRetiredIdentityKey(publicKey, selector) {
     const canonical = canonicalPublicKey(publicKey);
     if (!scope || !canonical)
         throw new Error('retired key: invalid selector or public key');
-    assertMayWrite();
+    await assertMayWrite();
     const store = await ringStore();
     await store.deleteItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
     const signer = isAndroid() ? registeredIdentitySignerStore() : null;
@@ -292,10 +314,12 @@ export async function forgetRetiredIdentityKey(publicKey, selector) {
     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.
+ * 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 async function forgetRetiredIdentityKeys(selector) {
     const scope = retiredKeyScope(selector);
@@ -342,6 +366,41 @@ export async function syncRetiredKeys() {
     }
     return mirrored;
 }
+/**
+ * Every retired key of `selector`'s ring WITH its private half, for the
+ * encrypted identity backup (`oxy.identity.backup.create`), which carries them
+ * under the CURRENT phrase so a lost phone costs no more than the current
+ * phrase does (R4-4). Commons only; an entry whose private half is missing or
+ * does not derive its public key is left out. Never log or transmit the result
+ * except inside that encrypted envelope.
+ */
+export async function exportRetiredIdentityKeys(selector) {
+    const scope = retiredKeyScope(selector);
+    if (!scope || isWeb())
+        return [];
+    await assertMayWrite();
+    const out = [];
+    for (const entry of await listRetiredIdentityKeys(selector)) {
+        const privateKey = await getRetiredPrivateKey(entry.publicKey, selector);
+        if (privateKey)
+            out.push({ privateKey, publicKey: entry.publicKey, retiredAt: entry.retiredAt });
+    }
+    return out;
+}
+/**
+ * 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 function retiredKeyFromPrivateKey(privateKeyHex) {
+    const trimmed = privateKeyHex.trim().toLowerCase().replace(/^0x/, '');
+    if (!/^[0-9a-f]{64}$/.test(trimmed) || !isValidSecp256k1PrivateKey(trimmed)) {
+        throw new Error('retired key: not a valid private key');
+    }
+    const privateKey = normalizeSecp256k1PrivateKey(trimmed);
+    return { privateKey, publicKey: publicKeyOf(privateKey) };
+}
 /**
  * The pair a previous recovery phrase derives (`seed[0:32]`, the personal-root
  * and organization-key derivation; 12–24 words). Stores nothing: the caller

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 = {
@@ -41,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) {
@@ -49,10 +66,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,8 +74,20 @@ export function keychainGroupFor(item) {
             return 'wallet';
         case 'shared':
             return 'shared';
+        case 'app':
+            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) {
@@ -71,11 +96,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.
@@ -83,12 +111,18 @@ export function keychainAccessFromDefaultGroup(defaultGroup) {
     }
     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';
-    return { mode: 'grouped', prefix, defaultGroup, role };
+    // 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, ...variant }
+        : { mode: 'grouped', prefix, defaultGroup, role, ...variant };
 }
 let resolvedAccess = null;
 /**
@@ -116,28 +150,101 @@ 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 */
+/** 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` 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);
+    }
+    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 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, 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') {
@@ -148,17 +255,29 @@ export function keychainReadPlan(access, item) {
     }
     const own = keychainGroupFor(item);
     const plan = [option(keychainAccessGroupValue(access, own))];
-    if (own !== 'shared') {
+    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
@@ -169,31 +288,56 @@ 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)));
 }
 /**
- * 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.
+ *
+ * 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.
  *
- * Every other app (`member`) and Android/web keep the calls they always made.
+ * 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) {
@@ -213,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);
 }