@oxy.so/core 7.30.0 → 7.31.0

package/dist/cjs/session/authStateStore.js

@@ -20,6 +20,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AUTH_STATE_TOKEN_STORAGE_KEY = exports.AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY = exports.AUTH_STATE_STORAGE_KEY = void 0;
 exports.matchesAuthState = matchesAuthState;
+exports.nativeSessionItemNames = nativeSessionItemNames;
 exports.createMemoryAuthStateStore = createMemoryAuthStateStore;
 exports.createWebAuthStateStore = createWebAuthStateStore;
 exports.createNativeAuthStateStore = createNativeAuthStateStore;
@@ -53,6 +54,18 @@ function matchesAuthState(actual, expected) {
  */
 exports.AUTH_STATE_STORAGE_KEY = 'oxy.auth.v1';
 exports.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.
+ */
+function nativeSessionItemNames(key) {
+    return key === exports.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/cjs/session/index.js

@@ -8,8 +8,8 @@
  * the API with a token it already has never needs it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.resolveKeychainAccess = exports.deleteThroughPlan = exports.readThroughPlan = exports.ownKeychainItemPlan = exports.keychainAccessGroupValue = exports.KeychainAccessUnavailableError = exports.readLocalDeviceCredential = exports.publishProvenDeviceCredential = exports.normalizeSharedDeviceSessionRead = exports.decideSharedDevicePublish = exports.decideSharedDeviceJoin = exports.createSharedMirroringAuthStateStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.resolveAccountDelegationAccess = exports.canSwitchIntoAccount = exports.isSwitchTargetAccount = exports.deviceComparisonCode = exports.showsPrincipalHeaders = exports.buildSwitcherRows = exports.resolveDeviceContext = exports.resolveActiveContext = exports.projectDevicePrincipals = exports.directoryHandle = exports.directoryDisplayName = exports.canActivateContext = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.DeviceManager = void 0;
-exports.runColdBoot = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = void 0;
+exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.resolveKeychainAccess = exports.deleteThroughPlan = exports.readThroughPlan = exports.ownKeychainItemPlan = exports.keychainAccessGroupValue = exports.KeychainAccessUnavailableError = exports.readLocalDeviceCredential = exports.publishProvenDeviceCredential = exports.normalizeSharedDeviceSessionRead = exports.decideSharedDevicePublish = exports.decideSharedDeviceJoin = exports.createSharedMirroringAuthStateStore = exports.AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY = exports.AUTH_STATE_TOKEN_STORAGE_KEY = exports.AUTH_STATE_STORAGE_KEY = exports.nativeSessionItemNames = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.resolveAccountDelegationAccess = exports.canSwitchIntoAccount = exports.isSwitchTargetAccount = exports.deviceComparisonCode = exports.showsPrincipalHeaders = exports.buildSwitcherRows = exports.resolveDeviceContext = exports.resolveActiveContext = exports.projectDevicePrincipals = exports.directoryHandle = exports.directoryDisplayName = exports.canActivateContext = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.DeviceManager = void 0;
+exports.runColdBoot = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = void 0;
 // Session code reaches the identity key (identity-bound sessions), so the
 // crypto shim goes first — see `../crypto/polyfill`.
 require("../crypto/polyfill");
@@ -95,7 +95,10 @@ var authStateStore_1 = require("./authStateStore");
 Object.defineProperty(exports, "createWebAuthStateStore", { enumerable: true, get: function () { return authStateStore_1.createWebAuthStateStore; } });
 Object.defineProperty(exports, "createNativeAuthStateStore", { enumerable: true, get: function () { return authStateStore_1.createNativeAuthStateStore; } });
 Object.defineProperty(exports, "createMemoryAuthStateStore", { enumerable: true, get: function () { return authStateStore_1.createMemoryAuthStateStore; } });
+Object.defineProperty(exports, "nativeSessionItemNames", { enumerable: true, get: function () { return authStateStore_1.nativeSessionItemNames; } });
 Object.defineProperty(exports, "AUTH_STATE_STORAGE_KEY", { enumerable: true, get: function () { return authStateStore_1.AUTH_STATE_STORAGE_KEY; } });
+Object.defineProperty(exports, "AUTH_STATE_TOKEN_STORAGE_KEY", { enumerable: true, get: function () { return authStateStore_1.AUTH_STATE_TOKEN_STORAGE_KEY; } });
+Object.defineProperty(exports, "AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY", { enumerable: true, get: function () { return authStateStore_1.AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY; } });
 // 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/cjs/utils/keychainAccessGroups.js

@@ -23,6 +23,7 @@ exports.groupedKeychainStore = groupedKeychainStore;
  * | `<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
@@ -32,14 +33,21 @@ exports.groupedKeychainStore = groupedKeychainStore;
  *   (`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'
@@ -66,10 +74,6 @@ class KeychainAccessUnavailableError extends Error {
     }
 }
 exports.KeychainAccessUnavailableError = 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.
- */
 function keychainGroupFor(item) {
     switch (item) {
         case 'identity-secret':
@@ -78,6 +82,8 @@ function keychainGroupFor(item) {
             return 'wallet';
         case 'shared':
             return 'shared';
+        case 'app':
+            return 'app';
     }
 }
 /** Whether `role` holds the group `item` lives in. */
@@ -88,11 +94,14 @@ 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. */
-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.
+ */
+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.
@@ -105,7 +114,9 @@ function keychainAccessFromDefaultGroup(defaultGroup) {
         : group === exports.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;
 /**
@@ -133,28 +144,62 @@ 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 (0, protocol_1.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 */
 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}).
+ */
 function keychainAccessGroupValue(access, group) {
-    return access.mode === 'grouped' ? `${access.prefix}${exports.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}${exports.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}.
  */
 function keychainReadPlan(access, item) {
     if (access.mode === 'ungrouped') {
@@ -165,7 +210,8 @@ 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;
@@ -192,25 +238,50 @@ 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.
  */
-function ownKeychainItemPlan(access) {
-    if (access.mode === 'ungrouped' || access.role === 'member') {
+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. */
 async function readThroughPlan(store, key, options, plan) {

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/crypto/index.d.ts

@@ -20,7 +20,7 @@ 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 type { KeychainAccess, KeychainAccessGroupName, KeychainGroup, KeychainGroupOption, KeychainItemClass, KeychainRole, KeychainStoreLike, OwnKeychainItemNames, } from '../utils/keychainAccessGroups';
 export { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
 export type { KeychainGroupMigrationReport, KeychainItemMigrationOutcome, } from './keychainGroupMigration';
 export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, } from './retiredKeys';

package/dist/types/session/authStateStore.d.ts

@@ -16,6 +16,7 @@
  *
  * ESM-safe (no `require()`).
  */
+import type { OwnKeychainItemNames } from '../utils/keychainAccessGroups';
 /**
  * The persisted session credential set for a single origin.
  *
@@ -124,6 +125,14 @@ export interface NativeKeyValueStorage {
  */
 export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
 export declare 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 declare function nativeSessionItemNames(key: string): OwnKeychainItemNames;
 /**
  * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
  * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a

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

@@ -25,12 +25,12 @@ export { resolveAccountDelegationAccess } from './accountDelegationAccess';
 export type { AccountDelegationAccess, AccountDelegationNode, } from './accountDelegationAccess';
 export { AccountDialogController, createAccountDialogController, } from './accountDialogController';
 export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, ContextChoiceOutcome, SignInFailureReason, SignInFlowPhase, SignInFlowState, SignInProgress, } from './accountDialogController';
-export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './authStateStore';
+export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, nativeSessionItemNames, AUTH_STATE_STORAGE_KEY, AUTH_STATE_TOKEN_STORAGE_KEY, AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY, } from './authStateStore';
 export type { PersistedAuthState, AuthStateStore, AuthStateWriteGuard, NativeKeyValueStorage, } from './authStateStore';
 export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './sharedDeviceCredential';
 export type { SharedDeviceCredential, SharedDeviceCredentialRead, SharedDeviceCredentialStore, SharedDeviceJoinDecision, SharedDeviceJoinSkipReason, SharedDevicePublishDecision, SharedDevicePublishOutcome, SharedDevicePublishSkipReason, } from './sharedDeviceCredential';
 export { KeychainAccessUnavailableError, keychainAccessGroupValue, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, resolveKeychainAccess, } from '../utils/keychainAccessGroups';
-export type { KeychainAccess, KeychainGroupOption } from '../utils/keychainAccessGroups';
+export type { KeychainAccess, KeychainGroupOption, OwnKeychainItemNames, } from '../utils/keychainAccessGroups';
 export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './identityPin';
 export type { IdentityPin, IdentityPinStore } from './identityPin';
 export { resolveIdentityPin, establishIdentitySession, } from './identitySession';

package/dist/types/utils/keychainAccessGroups.d.ts

@@ -5,13 +5,21 @@ export declare const KEYCHAIN_ACCESS_GROUPS: {
     readonly shared: "group.so.oxy.shared";
 };
 export type KeychainAccessGroupName = keyof typeof KEYCHAIN_ACCESS_GROUPS;
+/**
+ * Every group an item class can be assigned: the three Oxy groups, or `app`,
+ * this app's own group, whose name is the app's and so is not a constant.
+ */
+export type KeychainGroup = KeychainAccessGroupName | 'app';
 /** What a keychain item IS, which decides its group. See the table above. */
-export type KeychainItemClass = 'identity-secret' | 'spending-key' | 'shared';
+export type KeychainItemClass = 'identity-secret' | 'spending-key' | 'shared' | 'app';
 /** Which holder this binary is, from its default access group. */
 export type KeychainRole = 'holder' | 'wallet' | 'member';
 /**
  * - `grouped`: iOS with the probe answered. `prefix` ends with its dot
- *   (`ABCDE12345.`); `defaultGroup` is the full default group string.
+ *   (`ABCDE12345.`); `defaultGroup` is the full default group string;
+ *   `appGroup`, when the native module proved it, this app's own group
+ *   (`ABCDE12345.so.oxy.mention`). Absent on a native build that predates that
+ *   probe: see {@link ownKeychainItemPlan} for what such a build does.
  * - `ungrouped`: Android, web, or an iOS native build without the probe.
  */
 export type KeychainAccess = {
@@ -19,6 +27,7 @@ export type KeychainAccess = {
     prefix: string;
     defaultGroup: string;
     role: KeychainRole;
+    appGroup?: string;
 } | {
     mode: 'ungrouped';
 };
@@ -36,11 +45,15 @@ export declare class KeychainAccessUnavailableError extends Error {
  * 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 declare function keychainGroupFor(item: KeychainItemClass): KeychainAccessGroupName;
+export declare function keychainGroupFor(item: Exclude<KeychainItemClass, 'app'>): KeychainAccessGroupName;
+export declare function keychainGroupFor(item: KeychainItemClass): KeychainGroup;
 /** Whether `role` holds the group `item` lives in. */
 export declare function mayHoldKeychainItem(role: KeychainRole, item: KeychainItemClass): boolean;
-/** Parse the default access group the probe reported. Exported for tests. */
-export declare function keychainAccessFromDefaultGroup(defaultGroup: string): KeychainAccess;
+/**
+ * Parse the default access group the probe reported, and the app's own group
+ * when the second probe proved it. Exported for tests.
+ */
+export declare function keychainAccessFromDefaultGroup(defaultGroup: string, appGroup?: string): KeychainAccess;
 /**
  * This binary's keychain access, memoized once known. THROWS
  * {@link KeychainAccessUnavailableError} while the probe cannot answer, which
@@ -49,13 +62,18 @@ export declare function keychainAccessFromDefaultGroup(defaultGroup: string): Ke
 export declare function resolveKeychainAccess(): Promise<KeychainAccess>;
 /** Forget the memoized access. Tests only. @internal */
 export declare function resetKeychainAccessForTests(): void;
-/** The full `kSecAttrAccessGroup` value of `group`, or `undefined` when ungrouped. */
-export declare function keychainAccessGroupValue(access: KeychainAccess, group: KeychainAccessGroupName): string | undefined;
 /**
- * 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 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 declare function keychainAccessGroupValue(access: KeychainAccess, group: KeychainGroup): string | undefined;
+/**
+ * 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 declare function keychainReadPlan(access: KeychainAccess, item: KeychainItemClass): KeychainGroupOption[];
 /**
@@ -70,17 +88,51 @@ export declare function keychainDeletePlan(access: KeychainAccess, item: Keychai
  */
 export declare function keychainWriteOption(access: KeychainAccess, item: KeychainItemClass): KeychainGroupOption;
 /**
- * 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.
+ * Who else writes an own item's NAME, which decides whose an earlier copy of
+ * it can be.
+ *
+ * - `this-app`: no other app uses the name (the Peable wallet's own items). A
+ *   copy anywhere this app can read is its own.
+ * - `every-oxy-app`: every Oxy app writes the same name (the SDK's session
+ *   store: `oxy.auth.v1`, the warm token, the identity pin). Before the
+ *   app group, every iOS app but Commons and the Peable wallet wrote it to the
+ *   ONE copy in the shared group, so a copy there may be another app's
+ *   session, or Commons' vault session. Only this app's own locations are
+ *   read, written or deleted; the shared copy is left to the apps still
+ *   running a build that uses it.
+ * - `every-oxy-app-withholding`: as `every-oxy-app`, for a value whose only
+ *   effect is to WITHHOLD (the explicit sign-out marker). A shared copy still
+ *   counts — honouring another app's marker can keep this app from signing in
+ *   automatically, never sign it in — and its delete reaches that copy, as a
+ *   release always did before.
+ */
+export type OwnKeychainItemNames = 'this-app' | 'every-oxy-app' | 'every-oxy-app-withholding';
+/**
+ * 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 declare function ownKeychainItemPlan(access: KeychainAccess): {
+export declare function ownKeychainItemPlan(access: KeychainAccess, names?: OwnKeychainItemNames): {
     read: KeychainGroupOption[];
     write: KeychainGroupOption;
     delete: KeychainGroupOption[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.30.0",
+  "version": "7.31.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -182,7 +182,7 @@
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
     "@oxy.so/contracts": "^6.12.0",
-    "@oxy.so/protocol": "^1.9.0",
+    "@oxy.so/protocol": "^1.10.0",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^2.4.0",
     "buffer": "^6.0.3",

package/src/crypto/index.ts

@@ -64,10 +64,12 @@ export {
 export type {
   KeychainAccess,
   KeychainAccessGroupName,
+  KeychainGroup,
   KeychainGroupOption,
   KeychainItemClass,
   KeychainRole,
   KeychainStoreLike,
+  OwnKeychainItemNames,
 } from '../utils/keychainAccessGroups';
 export { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
 export type {

package/src/crypto/keychainGroupMigration.ts

@@ -110,7 +110,12 @@ type Unit =
       merge?: (shared: string, target: string) => string | null;
     };
 
-const slot = (key: string, item: KeychainItemClass, service?: string, deviceOnly = true): Slot => ({
+const slot = (
+  key: string,
+  item: Exclude<KeychainItemClass, 'app'>,
+  service?: string,
+  deviceOnly = true,
+): Slot => ({
   key,
   service,
   group: keychainGroupFor(item),

package/src/session/authStateStore.ts

@@ -18,6 +18,7 @@
  */
 
 import { logger } from '../logger';
+import type { OwnKeychainItemNames } from '../utils/keychainAccessGroups';
 
 /**
  * The persisted session credential set for a single origin.
@@ -150,6 +151,19 @@ 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: string): OwnKeychainItemNames {
+  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/src/session/index.ts

@@ -134,7 +134,10 @@ export {
   createWebAuthStateStore,
   createNativeAuthStateStore,
   createMemoryAuthStateStore,
+  nativeSessionItemNames,
   AUTH_STATE_STORAGE_KEY,
+  AUTH_STATE_TOKEN_STORAGE_KEY,
+  AUTOMATIC_IDENTITY_SIGNIN_SUPPRESSED_KEY,
 } from './authStateStore';
 export type {
   PersistedAuthState,
@@ -176,7 +179,11 @@ export {
   deleteThroughPlan,
   resolveKeychainAccess,
 } from '../utils/keychainAccessGroups';
-export type { KeychainAccess, KeychainGroupOption } from '../utils/keychainAccessGroups';
+export type {
+  KeychainAccess,
+  KeychainGroupOption,
+  OwnKeychainItemNames,
+} from '../utils/keychainAccessGroups';
 
 // Identity-bound sessions (the identity vault). The pin is the durable
 // `{publicKey, accountId}` binding between this device's PRIMARY identity key

package/src/utils/keychainAccessGroups.ts

@@ -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,12 @@
  * This module never imports the identity stack: services' device-session store
  * and Peable's wallet storage use it too.
  */
-import { type KeychainDefaultAccessGroup, loadKeychainDefaultAccessGroup } from '@oxy.so/protocol';
+import {
+  type KeychainApplicationAccessGroup,
+  type KeychainDefaultAccessGroup,
+  loadKeychainApplicationAccessGroup,
+  loadKeychainDefaultAccessGroup,
+} from '@oxy.so/protocol';
 import { isIOS } from './platform';
 
 /** The group names after the team prefix, exactly as the entitlements list them. */
@@ -45,19 +58,34 @@ export const KEYCHAIN_ACCESS_GROUPS = {
 
 export type KeychainAccessGroupName = keyof typeof KEYCHAIN_ACCESS_GROUPS;
 
+/**
+ * Every group an item class can be assigned: the three Oxy groups, or `app`,
+ * this app's own group, whose name is the app's and so is not a constant.
+ */
+export type KeychainGroup = KeychainAccessGroupName | 'app';
+
 /** What a keychain item IS, which decides its group. See the table above. */
-export type KeychainItemClass = 'identity-secret' | 'spending-key' | 'shared';
+export type KeychainItemClass = 'identity-secret' | 'spending-key' | 'shared' | 'app';
 
 /** Which holder this binary is, from its default access group. */
 export type KeychainRole = 'holder' | 'wallet' | 'member';
 
 /**
  * - `grouped`: iOS with the probe answered. `prefix` ends with its dot
- *   (`ABCDE12345.`); `defaultGroup` is the full default group string.
+ *   (`ABCDE12345.`); `defaultGroup` is the full default group string;
+ *   `appGroup`, when the native module proved it, this app's own group
+ *   (`ABCDE12345.so.oxy.mention`). Absent on a native build that predates that
+ *   probe: see {@link ownKeychainItemPlan} for what such a build does.
  * - `ungrouped`: Android, web, or an iOS native build without the probe.
  */
 export type KeychainAccess =
-  | { mode: 'grouped'; prefix: string; defaultGroup: string; role: KeychainRole }
+  | {
+      mode: 'grouped';
+      prefix: string;
+      defaultGroup: string;
+      role: KeychainRole;
+      appGroup?: string;
+    }
   | { mode: 'ungrouped' };
 
 /** The `expo-secure-store` option this module sets (its real name since 58). */
@@ -77,7 +105,9 @@ export class KeychainAccessUnavailableError extends Error {
  * 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: KeychainItemClass): KeychainAccessGroupName {
+export function keychainGroupFor(item: Exclude<KeychainItemClass, 'app'>): KeychainAccessGroupName;
+export function keychainGroupFor(item: KeychainItemClass): KeychainGroup;
+export function keychainGroupFor(item: KeychainItemClass): KeychainGroup {
   switch (item) {
     case 'identity-secret':
       return 'identity';
@@ -85,6 +115,8 @@ export function keychainGroupFor(item: KeychainItemClass): KeychainAccessGroupNa
       return 'wallet';
     case 'shared':
       return 'shared';
+    case 'app':
+      return 'app';
   }
 }
 
@@ -96,12 +128,18 @@ export function mayHoldKeychainItem(role: KeychainRole, item: KeychainItemClass)
     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: string): KeychainAccess {
+/**
+ * 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: string,
+  appGroup?: string,
+): KeychainAccess {
   const dot = defaultGroup.indexOf('.');
   if (dot <= 0 || dot === defaultGroup.length - 1) {
     // Not `<prefix>.<group>`: an unsigned simulator build. Nothing to split.
@@ -115,7 +153,9 @@ export function keychainAccessFromDefaultGroup(defaultGroup: string): KeychainAc
       : 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: KeychainAccess | null = null;
@@ -144,10 +184,31 @@ export async function resolveKeychainAccess(): Promise<KeychainAccess> {
   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: KeychainApplicationAccessGroup;
+  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;
 }
 
@@ -156,12 +217,26 @@ export function resetKeychainAccessForTests(): void {
   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: KeychainAccess,
-  group: KeychainAccessGroupName,
+  group: KeychainGroup,
 ): string | undefined {
-  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: string | undefined): KeychainGroupOption {
@@ -169,10 +244,11 @@ function option(value: string | undefined): KeychainGroupOption {
 }
 
 /**
- * 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: KeychainAccess,
@@ -186,7 +262,8 @@ export function keychainReadPlan(
   }
   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;
@@ -224,29 +301,79 @@ export function keychainWriteOption(
 }
 
 /**
- * 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.
+ * Who else writes an own item's NAME, which decides whose an earlier copy of
+ * it can be.
  *
- * Every other app (`member`) and Android/web keep the calls they always made.
+ * - `this-app`: no other app uses the name (the Peable wallet's own items). A
+ *   copy anywhere this app can read is its own.
+ * - `every-oxy-app`: every Oxy app writes the same name (the SDK's session
+ *   store: `oxy.auth.v1`, the warm token, the identity pin). Before the
+ *   app group, every iOS app but Commons and the Peable wallet wrote it to the
+ *   ONE copy in the shared group, so a copy there may be another app's
+ *   session, or Commons' vault session. Only this app's own locations are
+ *   read, written or deleted; the shared copy is left to the apps still
+ *   running a build that uses it.
+ * - `every-oxy-app-withholding`: as `every-oxy-app`, for a value whose only
+ *   effect is to WITHHOLD (the explicit sign-out marker). A shared copy still
+ *   counts — honouring another app's marker can keep this app from signing in
+ *   automatically, never sign it in — and its delete reaches that copy, as a
+ *   release always did before.
  */
-export function ownKeychainItemPlan(access: KeychainAccess): {
+export type OwnKeychainItemNames = 'this-app' | 'every-oxy-app' | 'every-oxy-app-withholding';
+
+/**
+ * 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.
+ *
+ * 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: KeychainAccess,
+  names: OwnKeychainItemNames = 'this-app',
+): {
   read: KeychainGroupOption[];
   write: KeychainGroupOption;
   delete: KeychainGroupOption[];
 } {
-  if (access.mode === 'ungrouped' || access.role === 'member') {
+  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() };
+    }
+  }
 }
 
 /** The subset of `expo-secure-store` a grouped store wraps. */