@oxy.so/core 7.30.0 → 7.32.0

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

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

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

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

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

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

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

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

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

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

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

@@ -70,6 +70,12 @@ export declare function retiredKeyScope(selector?: RetiredKeySelector): string |
  * caller about to replace the key can stop before anything is lost.
  */
 export declare function retireIdentityKey(key: RetiredKeyPair, selector?: RetiredKeySelector): Promise<void>;
+/**
+ * {@link retireIdentityKey} from inside the iOS access-group migration, which
+ * keeps a replaced pre-split copy before deleting it from the shared group and
+ * cannot await itself. @internal
+ */
+export declare function retireIdentityKeyDuringMigration(key: RetiredKeyPair, selector?: RetiredKeySelector): Promise<void>;
 /**
  * The retired keys of `selector`'s account this app can reach, oldest first.
  * iOS and Commons: the ring's index. Android elsewhere: Commons' identity host
@@ -93,10 +99,12 @@ export declare function getRetiredPrivateKey(publicKey: string, selector?: Retir
  */
 export declare function forgetRetiredIdentityKey(publicKey: string, selector?: RetiredKeySelector): Promise<void>;
 /**
- * Forget every retired key of one ring (the person's, or an organization's):
- * called when the identity itself is deleted from this device, so a phone
- * handed on keeps none of the person's old keys. Commons only. Resolves how
- * many it removed.
+ * Forget every retired key of one ring (the person's, or an organization's).
+ * Commons only, and only when the person deletes their Oxy ACCOUNT (Commons'
+ * delete-account flow), which tells them the coins go with it. Deleting the
+ * identity from this device — "Start over", a forced delete — never calls it:
+ * the ring is money, and the same person restoring their identity later must
+ * find it (R4-4). Resolves how many it removed.
  */
 export declare function forgetRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<number>;
 /**
@@ -106,6 +114,24 @@ export declare function forgetRetiredIdentityKeys(selector?: RetiredKeySelector)
  * Resolves how many it mirrored. Elsewhere 0.
  */
 export declare function syncRetiredKeys(): Promise<number>;
+/**
+ * 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 declare function exportRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<Array<RetiredKeyPair & {
+    retiredAt: number;
+}>>;
+/**
+ * The pair a previous key's raw PRIVATE KEY gives (64 hex, an optional `0x`),
+ * for a person whose old identity was imported as a private key and so has no
+ * phrase to re-enter. Stores nothing: the caller checks the public key against
+ * the account's key history and only then calls {@link retireIdentityKey}.
+ */
+export declare function retiredKeyFromPrivateKey(privateKeyHex: string): RetiredKeyPair;
 /**
  * The pair a previous recovery phrase derives (`seed[0:32]`, the personal-root
  * and organization-key derivation; 12–24 words). Stores nothing: the caller

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

@@ -4,14 +4,31 @@ export declare const KEYCHAIN_ACCESS_GROUPS: {
     readonly wallet: "so.oxy.wallet";
     readonly 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 declare const DEV_KEYCHAIN_GROUP_SUFFIX: ".dev";
 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 +36,9 @@ export type KeychainAccess = {
     prefix: string;
     defaultGroup: string;
     role: KeychainRole;
+    appGroup?: string;
+    /** {@link DEV_KEYCHAIN_GROUP_SUFFIX} for a dev build; absent for production. */
+    variant?: typeof DEV_KEYCHAIN_GROUP_SUFFIX;
 } | {
     mode: 'ungrouped';
 };
@@ -36,31 +56,55 @@ 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` 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 declare function mayWriteKeychainItem(role: KeychainRole, item: KeychainItemClass): boolean;
 /** 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
  * every caller already treats as "storage unavailable, retry".
  */
 export declare function resolveKeychainAccess(): Promise<KeychainAccess>;
-/** Forget the memoized access. Tests only. @internal */
+/** Forget the memoized access and the fallback state. 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 migration's switch for Commons' fallback. @internal */
+export declare function setHolderSharedSecretFallback(open: boolean): void;
+/** The wallet saw Commons' completion record: no shared fallback again in this process. @internal */
+export declare function closeWalletSharedSecretFallback(): void;
+/**
+ * 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 declare function keychainReadPlan(access: KeychainAccess, item: KeychainItemClass): KeychainGroupOption[];
 /**
- * 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 declare function keychainDeletePlan(access: KeychainAccess, item: KeychainItemClass): KeychainGroupOption[];
 /**
@@ -70,17 +114,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[];
@@ -97,8 +175,12 @@ export declare function readThroughPlan(store: KeychainStoreLike, key: string, o
 export declare function deleteThroughPlan(store: KeychainStoreLike, key: string, options: object, plan: readonly KeychainGroupOption[]): Promise<void>;
 /**
  * `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 declare function groupedKeychainStore<S extends KeychainStoreLike>(store: S, access: KeychainAccess, item: KeychainItemClass): S;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.30.0",
+  "version": "7.32.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",