@oxy.so/core 7.28.0 → 7.30.0

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

@@ -238,6 +238,13 @@ export declare class KeyManager {
      * Called internally when shared identity is created/deleted/imported
      */
     private static invalidateSharedCache;
+    /**
+     * iOS: write the personal key's cross-app slot — the private key to the
+     * wallet group (Commons and the Peable wallet), the public key to the shared
+     * group (every Oxy app). Throws in any app that may not hold the private key.
+     * @internal
+     */
+    private static _writeIosSharedSlot;
     /**
      * Lowercase and pad to canonical 64-hex-char form.
      *
@@ -717,7 +724,8 @@ export declare class KeyManager {
      * `HDKey.fromMasterSeed` and never touches the identity key.
      *
      * Key source (native only):
-     * - iOS: the shared identity in `group.so.oxy.shared`, then this device's
+     * - iOS: the shared slot's private key in the wallet keychain group (Commons
+     *   and the Peable wallet only; `null` in every other app), then this device's
      *   primary identity.
      * - Android: Commons (the one app with a signer store) uses its own primary
      *   identity; every other app asks Commons over IPC and never reads a local
@@ -731,13 +739,21 @@ export declare class KeyManager {
      * keychain group, or Commons' identity host. It never falls back to the
      * personal key.
      *
+     * With `opts.publicKey` the seed is derived from the key of that account
+     * (personal, or `accountId`'s) whose public key it names: the current key
+     * when it matches, else a RETIRED key Commons kept after a rotation or
+     * replacement (`./retiredKeys`, ADR 0061 D7 as amended). Spending only: a
+     * retired key never signs in. Never falls back to another key.
+     *
      * @param info Context/domain-binding label (distinct labels → independent seeds).
      * @param opts.accountId An organization's account id, for its key.
+     * @param opts.publicKey Selects one key of that account by its public key.
      * @returns 32 bytes of derived keying material, or `null` on web / when no
      *          identity key is available to this app.
      */
     static deriveScopedSeed(info: string, opts?: {
         accountId?: string;
+        publicKey?: string;
     }): Promise<Uint8Array | null>;
     /**
      * {@link deriveScopedSeed} over an ORGANIZATION key (ADR 0061 D6): Commons'
@@ -754,7 +770,8 @@ export declare class KeyManager {
      * compressed public key for the scriptSig.
      *
      * Key source: as {@link deriveScopedSeed}, including `opts.accountId` for an
-     * organization's key (ADR 0061 D6). On Android outside Commons the signature
+     * organization's key (ADR 0061 D6) and `opts.publicKey` for one key of the
+     * account, current or retired. On Android outside Commons the signature
      * comes from Commons, which allows it for the wallet app only.
      *
      * @returns the signature, or `null` on web / when no identity key is
@@ -762,7 +779,20 @@ export declare class KeyManager {
      */
     static signSocialReceive(index: number, digest: string, opts?: {
         accountId?: string;
+        publicKey?: string;
     }): Promise<CommonsSocialReceiveSignature | null>;
+    /**
+     * The private key of the account (personal, or `accountId`'s organization)
+     * whose public key is `publicKey`, from this app's own storage: the current
+     * key when it matches, else the retired ring. iOS and Commons only; `null`
+     * for a key this device does not hold. Never another key in its place. @internal
+     */
+    /**
+     * The selector in the identity host's encoding (lowercase uncompressed), so a
+     * compressed `#key-1` from a DID or a gateway row selects the same key. @internal
+     */
+    private static _selectorKey;
+    private static _selectedPrivateKey;
     /**
      * Get a shortened version of the public key for display
      * Format: first 8 chars...last 8 chars

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

@@ -0,0 +1,27 @@
+/** What happened to one item (or pair) in a run. */
+export type KeychainItemMigrationOutcome = 'absent' | 'moved' | 'conflict' | 'unhealthy' | '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.
+     */
+    state: 'not-applicable' | 'complete' | 'incomplete' | 'deferred';
+    /** Outcome per item label (`primary`, `phrase`, `organization-1`, …). */
+    items: Record<string, KeychainItemMigrationOutcome>;
+}
+/** Run the migration once. Exported for tests; production code awaits the gate. */
+export declare function runKeychainGroupMigration(): Promise<KeychainGroupMigrationReport>;
+/**
+ * The gate every Commons identity-storage access awaits. One run per process
+ * (`complete`, `incomplete` and `not-applicable` are kept; `incomplete` is
+ * retried on the next launch); a `deferred` run is forgotten, so the next
+ * access tries again once the keychain unlocks. Concurrent callers share one
+ * run. Never throws.
+ */
+export declare function ensureKeychainGroupsMigrated(): Promise<KeychainGroupMigrationReport>;
+/** Forget the memoized run. Tests only. @internal */
+export declare function resetKeychainGroupMigrationForTests(): void;

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

@@ -0,0 +1,41 @@
+/**
+ * The names of every identity item `KeyManager` and `./organizationKeys` keep
+ * in `expo-secure-store`, in one place so the access-group migration
+ * (`./keychainGroupMigration`) moves exactly what those modules read. Values
+ * are stable on-device identifiers: renaming one strands what is stored.
+ */
+/** Legacy (pre-v2) and shared-slot keys; the legacy ones have no keychain service. */
+export declare const STORAGE_KEYS: {
+    readonly PRIVATE_KEY: "oxy_identity_private_key";
+    readonly PUBLIC_KEY: "oxy_identity_public_key";
+    readonly BACKUP_PRIVATE_KEY: "oxy_identity_backup_private_key";
+    readonly BACKUP_PUBLIC_KEY: "oxy_identity_backup_public_key";
+    readonly BACKUP_TIMESTAMP: "oxy_identity_backup_timestamp";
+    readonly SHARED_PRIVATE_KEY: "oxy_shared_identity_private_key";
+    readonly SHARED_PUBLIC_KEY: "oxy_shared_identity_public_key";
+};
+export declare const V2_PRIMARY_KEYCHAIN_SERVICE = "oxy_identity";
+export declare const V2_BACKUP_KEYCHAIN_SERVICE = "oxy_identity_backup";
+export declare const V2_STORAGE_KEYS: {
+    readonly PRIVATE_KEY: "oxy_identity_private_key_v2";
+    readonly PUBLIC_KEY: "oxy_identity_public_key_v2";
+    readonly BACKUP_PRIVATE_KEY: "oxy_identity_backup_private_key_v2";
+    readonly BACKUP_PUBLIC_KEY: "oxy_identity_backup_public_key_v2";
+    readonly BACKUP_TIMESTAMP: "oxy_identity_backup_timestamp_v2";
+};
+export declare const RECOVERY_MNEMONIC_KEYCHAIN_SERVICE = "oxy_identity_mnemonic";
+export declare const RECOVERY_MNEMONIC_STORAGE_KEY = "oxy_identity_mnemonic_v1";
+/** Organization keys (ADR 0061 D6). On iOS the pair has no keychain service. */
+export declare const ORGANIZATION_ANDROID_KEYCHAIN_SERVICE = "oxy_org_identity";
+export declare const ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE = "oxy_org_identity_mnemonic";
+export declare const ORGANIZATION_INDEX_KEYCHAIN_SERVICE = "oxy_org_identity_index";
+export declare const ORGANIZATION_INDEX_STORAGE_KEY = "oxy_org_identity_index_v1";
+export declare const organizationPrivateKeyName: (accountId: string) => string;
+export declare const organizationPublicKeyName: (accountId: string) => string;
+export declare const organizationMnemonicName: (accountId: string) => string;
+/** Whether `value` is an account id an organization key can be stored under. */
+export declare function isOrganizationAccountId(value: string): boolean;
+/** The account ids in a stored organization index; anything malformed is skipped. */
+export declare function parseOrganizationIndex(raw: string | null): string[];
+/** The stored form of an organization index: unique, sorted. */
+export declare function serializeOrganizationIndex(ids: readonly string[]): string;

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

@@ -8,8 +8,10 @@
  * other Oxy apps reach it the way they reach the personal identity, by
  * derivation and never by the key:
  *
- * - iOS: the keychain access group `group.so.oxy.shared`, like the personal
- *   shared slot. Only Commons writes it.
+ * - iOS: the pair in the wallet keychain group (`<TEAM>.so.oxy.wallet`), which
+ *   only Commons and the Peable wallet hold; the phrase and the index in the
+ *   identity group, Commons only (docs/identity/ios-keychain-access-groups.md).
+ *   Only Commons writes them; every other app reads nothing.
  * - Android: Commons' own expo-secure-store slot, mirrored into the identity
  *   signer store (`./identitySigner`) that Commons' identity host answers
  *   `accountId` requests from. Every other app asks Commons over IPC
@@ -17,11 +19,13 @@
  *
  * The phrase is kept only in Commons, on the device that created or imported
  * it, so an owner can show it to another owner (ADR 0061 D5); it never reaches
- * the keychain group, an IPC answer or a log.
+ * the wallet or shared group, an IPC answer or a log.
  *
  * This module imports nothing from `./keyManager` (which imports it): the
  * signer store comes from `./identitySigner`'s registry.
  */
+import { isOrganizationAccountId } from './keychainItems';
+export { isOrganizationAccountId };
 /** A secp256k1 pair: private key 64 hex, public key lowercase uncompressed (`04…`, 130 hex). */
 export interface OrganizationKeyPair {
     privateKey: string;
@@ -35,8 +39,6 @@ export interface GeneratedOrganizationKey extends OrganizationKeyPair {
 export interface StoredOrganizationKey extends OrganizationKeyPair {
     mnemonic?: string;
 }
-/** Whether `value` is an account id an organization key can be stored under. */
-export declare function isOrganizationAccountId(value: string): boolean;
 /** True only when both halves are well-formed AND the public key derives from the private one. */
 export declare function isHealthyOrganizationKeyPair(privateKey: string | null | undefined, publicKey: string | null | undefined): boolean;
 /**
@@ -55,7 +57,7 @@ export declare function organizationKeyFromPhrase(phrase: string): Promise<Organ
 /**
  * Keep an organization key on this device. Commons only: on Android it needs
  * the identity signer store Commons registers, so the identity host can serve
- * it; on iOS only Commons calls it (the keychain group is shared).
+ * 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
@@ -64,15 +66,15 @@ export declare function organizationKeyFromPhrase(phrase: string): Promise<Organ
 export declare function storeOrganizationKey(accountId: string, key: StoredOrganizationKey): Promise<void>;
 /**
  * The organization's public key as THIS device can reach it, or `null`.
- * iOS: the keychain group. Android: Commons' own slot inside Commons, and
+ * iOS: the wallet keychain group (Commons, the Peable wallet). Android: Commons' own slot inside Commons, and
  * Commons' identity host (`describe` with `accountId`) everywhere else. Compare
  * it with the organization's DID `#key-1` before receiving (Peable ADR 0002).
  */
 export declare function getOrganizationPublicKey(accountId: string): Promise<string | null>;
 /**
  * The organization's private key, where this app may hold it: Commons (both
- * platforms) and, on iOS, the keychain group. `null` on Android outside
- * Commons. Use it to sign within the app only; never transmit it.
+ * platforms) and, on iOS, the Peable wallet through the wallet keychain group.
+ * `null` everywhere else. Use it to sign within the app only; never transmit it.
  */
 export declare function getOrganizationPrivateKey(accountId: string): Promise<string | null>;
 /** The organization's phrase, if this device created or imported it with one. Commons only. */

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

@@ -0,0 +1,116 @@
+/**
+ * Retired identity keys: the keys an account HAD, kept on the device for
+ * spending only (oxy ADR 0061 D7 as amended 2026-11-06, Peable ADR 0002).
+ *
+ * The Peable wallet derives from the account's identity key (`deriveScopedSeed`
+ * for its HD wallet, `signSocialReceive` for its social-receive addresses), and
+ * coins keep arriving under a key after it is replaced: payments already
+ * broadcast settle against the key they were reserved under, and late payers
+ * and `@username` senders hold old addresses. So a personal rotation
+ * (`oxy.identity.rotateKey`) and an organization replacement keep the replaced
+ * private key here, in a ring per account — `personal`, and one per
+ * organization account id — instead of deleting it.
+ *
+ * A retired key is NEVER a way to sign in, publish, receive a new reservation or
+ * rotate: nothing here signs a challenge, and the identity host refuses
+ * `proveIdentity` / `describe` for one. It is reached exactly as the current key
+ * is, by derivation and never by export, through the `publicKey` selector of
+ * `KeyManager.deriveScopedSeed` / `signSocialReceive`:
+ *
+ * - iOS: the private key in the wallet keychain group (ADR 0062's
+ *   `spending-key`: Commons and the Peable wallet only), beside the current
+ *   private keys; the ring's index (public keys and dates only) in the same
+ *   group, so the wallet can list it. Only Commons writes either.
+ * - Android: Commons' own expo-secure-store slot, mirrored into the identity
+ *   signer store (`./identitySigner`) that Commons' identity host answers
+ *   `keyPublicKey` requests from (wallet only). Every other app asks over IPC
+ *   (`loadCommonsIdentityBridge`) and never gets the key.
+ *
+ * A retired phrase is not kept: the person wrote it down, and a phrase is a
+ * second copy of the key that buys the wallet nothing.
+ *
+ * A key enters the ring only from Commons: the key being replaced (rotation,
+ * organization replacement), or a previous recovery phrase the person adds,
+ * which Commons accepts only when Oxy's key history names it as one of the
+ * account's retired keys. Never into the current slot.
+ *
+ * Security: a retired key that was compromised is also the attacker's. The
+ * ring makes the coins under it spendable from Peable again; it cannot make
+ * them safe. A rotation forced by a compromise must be followed at once by the
+ * wallet's "move to your current key" sweep, which races the attacker.
+ *
+ * This module imports nothing from `./keyManager` (which imports it).
+ */
+/** Whose ring: the person's (`accountId` absent) or an organization's. */
+export interface RetiredKeySelector {
+    /** An organization's account id; absent for the personal ring. */
+    accountId?: string;
+}
+/** One retired key as the ring lists it: public data only. */
+export interface RetiredIdentityKey {
+    /** Lowercase uncompressed secp256k1 public key (`04…`, 130 hex). */
+    publicKey: string;
+    /** The organization it was the key of; absent for a personal root. */
+    accountId?: string;
+    /** Unix milliseconds when this device kept it. */
+    retiredAt: number;
+}
+/** A pair to keep in the ring. */
+export interface RetiredKeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+/** The ring a selector names: `personal`, or the organization's account id. */
+export declare function retiredKeyScope(selector?: RetiredKeySelector): string | null;
+/**
+ * Keep `key` in the ring of `selector`'s account. Commons only. Idempotent: a
+ * key already kept stays, with its first date. Refuses a pair whose public key
+ * does not derive from its private key. Resolves once every copy confirmed it
+ * (Android: the signer store's read-back too), and throws otherwise, so a
+ * caller about to replace the key can stop before anything is lost.
+ */
+export declare function retireIdentityKey(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
+ * (the wallet only), which leaves out the scope's current key. After an
+ * interrupted rotation the local list can include the current key: compare
+ * with the DID's `#key-1` before treating an entry as retired.
+ */
+export declare function listRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<RetiredIdentityKey[]>;
+/**
+ * The private half of a retired key, where this app may hold it: Commons (both
+ * platforms) and, on iOS, the keychain group. `null` on Android outside Commons
+ * (ask the identity host instead) and for a key not in the ring. Sign within
+ * the app only; never transmit it. @internal — `KeyManager` reads it for the
+ * `publicKey` selector.
+ */
+export declare function getRetiredPrivateKey(publicKey: string, selector?: RetiredKeySelector): Promise<string | null>;
+/**
+ * Forget a retired key on this device: its private half, its signer copy and
+ * its index entry. Commons only, and only on the person's explicit request
+ * (their coins under it are then spendable only with its phrase again).
+ */
+export 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.
+ */
+export declare function forgetRetiredIdentityKeys(selector?: RetiredKeySelector): Promise<number>;
+/**
+ * Commons on Android: copy every retired key into the identity signer store
+ * again, so the identity host answers for it after that file was rebuilt (its
+ * self-heal leaves it empty). Call on every boot, beside `syncOrganizationKeys`.
+ * Resolves how many it mirrored. Elsewhere 0.
+ */
+export declare function syncRetiredKeys(): Promise<number>;
+/**
+ * The pair a previous recovery phrase derives (`seed[0:32]`, the personal-root
+ * and organization-key derivation; 12–24 words). Stores nothing: the caller
+ * checks the public key against the account's key history (personal:
+ * `oxy.identity.keyHistory()`; organization: `oxy.accounts.identityKey.get`)
+ * and only then calls {@link retireIdentityKey}.
+ */
+export declare function retiredKeyFromPhrase(phrase: string): Promise<RetiredKeyPair>;

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

@@ -0,0 +1,15 @@
+export interface OxySecureStoreOptions {
+    /** Keychain service name (Android keystore alias / iOS `kSecAttrService`). */
+    keychainService?: string;
+    /** Item accessibility: the `ExpoSecureStoreLike` constant, e.g. `WHEN_UNLOCKED_THIS_DEVICE_ONLY`. */
+    keychainAccessible?: number;
+    /** Prompt shown for biometric-protected items. */
+    authenticationPrompt?: string;
+    /** Whether Face ID / Touch ID is required to read the item. */
+    requireAuthentication?: boolean;
+    /**
+     * iOS `kSecAttrAccessGroup`: the FULL, team-prefixed entitlement value. Set
+     * only through `../utils/keychainAccessGroups`, never by hand.
+     */
+    accessGroup?: string;
+}

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

@@ -29,6 +29,8 @@ export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthSt
 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 { 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

@@ -0,0 +1,104 @@
+/** The group names after the team prefix, exactly as the entitlements list them. */
+export declare const KEYCHAIN_ACCESS_GROUPS: {
+    readonly identity: "so.oxy.identity";
+    readonly wallet: "so.oxy.wallet";
+    readonly shared: "group.so.oxy.shared";
+};
+export type KeychainAccessGroupName = keyof typeof KEYCHAIN_ACCESS_GROUPS;
+/** What a keychain item IS, which decides its group. See the table above. */
+export type KeychainItemClass = 'identity-secret' | 'spending-key' | 'shared';
+/** 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.
+ * - `ungrouped`: Android, web, or an iOS native build without the probe.
+ */
+export type KeychainAccess = {
+    mode: 'grouped';
+    prefix: string;
+    defaultGroup: string;
+    role: KeychainRole;
+} | {
+    mode: 'ungrouped';
+};
+/** The `expo-secure-store` option this module sets (its real name since 58). */
+export interface KeychainGroupOption {
+    accessGroup?: string;
+}
+/** Thrown while the probe cannot answer (before first unlock). Transient. */
+export declare class KeychainAccessUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "KeychainAccessUnavailableError";
+    constructor(cause?: unknown | undefined);
+}
+/**
+ * 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;
+/** 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;
+/**
+ * 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 */
+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.
+ */
+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.
+ */
+export declare function keychainDeletePlan(access: KeychainAccess, item: KeychainItemClass): KeychainGroupOption[];
+/**
+ * The option a WRITE of `item` carries. THROWS when this app may not hold the
+ * item: an identity secret written by any app but Commons would land in that
+ * app's default group, a second holder nobody knows about.
+ */
+export 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.
+ *
+ * Every other app (`member`) and Android/web keep the calls they always made.
+ */
+export declare function ownKeychainItemPlan(access: KeychainAccess): {
+    read: KeychainGroupOption[];
+    write: KeychainGroupOption;
+    delete: KeychainGroupOption[];
+};
+/** The subset of `expo-secure-store` a grouped store wraps. */
+export interface KeychainStoreLike {
+    getItemAsync(key: string, options?: object): Promise<string | null>;
+    setItemAsync(key: string, value: string, options?: object): Promise<void>;
+    deleteItemAsync(key: string, options?: object): Promise<void>;
+}
+/** Read `key` through `plan`: the first non-null answer. A thrown read propagates. */
+export declare function readThroughPlan(store: KeychainStoreLike, key: string, options: object, plan: readonly KeychainGroupOption[]): Promise<string | null>;
+/** Delete `key` from every location in `plan`. A thrown delete propagates. */
+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.
+ */
+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.28.0",
+  "version": "7.30.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -181,8 +181,8 @@
   "dependencies": {
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
-    "@oxy.so/contracts": "^6.11.0",
-    "@oxy.so/protocol": "^1.7.0",
+    "@oxy.so/contracts": "^6.12.0",
+    "@oxy.so/protocol": "^1.9.0",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^2.4.0",
     "buffer": "^6.0.3",

package/src/api/identity.ts

@@ -23,6 +23,7 @@ import {
   identityLinkCreateResponseCheck,
   identityLinkStateCheck,
 } from '@oxy.so/contracts/client';
+import { identityKeyHistoryCheck, type IdentityKeyHistory } from '@oxy.so/contracts/client';
 import type {
   AuthMethodsResponse,
   BackupStatusResponse,
@@ -283,9 +284,8 @@ export class IdentityApi {
       throw new Error('No authenticated user — sign in before rotating your key.');
     }
 
-    const { KeyManager, RecoveryPhraseService, SignatureService, signMessage } = await import(
-      '../crypto/index'
-    );
+    const { KeyManager, RecoveryPhraseService, SignatureService, signMessage, retireIdentityKey } =
+      await import('../crypto/index');
 
     // 1. The NEW identity (in memory only). The UI may pre-derive + pre-show
     //    it and pass it back here so the phrase shown === the phrase committed.
@@ -296,6 +296,7 @@ export class IdentityApi {
     // 2. Resolve the OLD signing capability from the chosen proof mode.
     let oldPublicKey: string;
     let signWithOldKey: (message: string) => Promise<string>;
+    let oldPrivateKeyForRing: string | null;
     if (options.proof === 'phrase') {
       const phrase = options.phrase?.trim();
       if (!phrase) {
@@ -304,6 +305,7 @@ export class IdentityApi {
       const oldPrivateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(phrase);
       oldPublicKey = KeyManager.derivePublicKey(oldPrivateKey);
       signWithOldKey = (message) => signMessage(message, oldPrivateKey);
+      oldPrivateKeyForRing = oldPrivateKey;
     } else {
       const currentPublicKey = await KeyManager.getPublicKey();
       if (!currentPublicKey) {
@@ -313,6 +315,30 @@ export class IdentityApi {
       }
       oldPublicKey = currentPublicKey;
       signWithOldKey = (message) => SignatureService.sign(message);
+      oldPrivateKeyForRing = isWeb() ? null : await KeyManager.getPrivateKey();
+    }
+
+    // 2b. Keep the key being replaced in the retired ring BEFORE anything
+    //     changes (oxy ADR 0061 D7 as amended, Peable ADR 0002): coins keep
+    //     arriving under it after the swap, and the Peable wallet spends them
+    //     through the `publicKey` selector of `deriveScopedSeed` /
+    //     `signSocialReceive`. A device that cannot keep it does not rotate:
+    //     the phrase would become the only way to those coins. Native only —
+    //     on web no key is stored. Idempotent, so a retried rotation is fine.
+    if (!isWeb()) {
+      try {
+        if (!oldPrivateKeyForRing) throw new Error('no readable private key');
+        await retireIdentityKey({ privateKey: oldPrivateKeyForRing, publicKey: oldPublicKey });
+      } catch (retainError) {
+        logger.warn(
+          'Could not keep the current key as a retired key; not rotating.',
+          { component: 'oxy.identity', method: 'rotateKey' },
+          retainError,
+        );
+        throw new Error(
+          'Your current key could not be kept on this device, so it was not rotated. Nothing changed.',
+        );
+      }
     }
 
     // 3. Request a single-use rotate_key challenge (bearer).
@@ -502,6 +528,23 @@ export class IdentityApi {
     if (userId) keys.push(`GET:/u/${encodeURIComponent(userId)}/did.json`);
     this.ctx.http.invalidateCache({ keys, prefixes: ['GET:/users/me'] });
   }
+
+  /**
+   * The signed-in personal account's current root (`null` without one) and
+   * every root a rotation replaced, oldest first, all canonical (uncompressed,
+   * lowercase). Commons reads it to accept a previous recovery phrase only when
+   * it derives a key that WAS this account's root. A retired root is never any
+   * account's again. First-party only; a non-personal account is refused
+   * (`IDENTITY_NOT_PERSONAL_ACCOUNT`).
+   */
+  async keyHistory(): Promise<IdentityKeyHistory> {
+    const res = await this.ctx.request<unknown>('GET', '/identity/key-history', undefined, {
+      cache: false,
+    });
+    const parsed = checkContract(identityKeyHistoryCheck, res);
+    if (!parsed) throw new Error('identity/key-history returned an unexpected response shape');
+    return parsed;
+  }
 }
 
 /** `oxy.identity.links` — joining Commons' root to an account (ADR 0029 D3). */

package/src/crypto/identitySigner.ts

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

package/src/crypto/index.ts

@@ -45,6 +45,46 @@ export type {
   GeneratedOrganizationKey,
   StoredOrganizationKey,
 } from './organizationKeys';
+// iOS keychain access groups (docs/identity/ios-keychain-access-groups.md, ADR 0062)
+export {
+  KEYCHAIN_ACCESS_GROUPS,
+  KeychainAccessUnavailableError,
+  keychainGroupFor,
+  mayHoldKeychainItem,
+  resolveKeychainAccess,
+  keychainAccessGroupValue,
+  keychainReadPlan,
+  keychainDeletePlan,
+  keychainWriteOption,
+  ownKeychainItemPlan,
+  readThroughPlan,
+  deleteThroughPlan,
+  groupedKeychainStore,
+} from '../utils/keychainAccessGroups';
+export type {
+  KeychainAccess,
+  KeychainAccessGroupName,
+  KeychainGroupOption,
+  KeychainItemClass,
+  KeychainRole,
+  KeychainStoreLike,
+} from '../utils/keychainAccessGroups';
+export { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+export type {
+  KeychainGroupMigrationReport,
+  KeychainItemMigrationOutcome,
+} from './keychainGroupMigration';
+// Retired identity keys: kept for spending after a rotation or replacement
+// (docs/adr/0061-organization-identity-key.md D7 as amended 2026-11-06)
+export {
+  retireIdentityKey,
+  listRetiredIdentityKeys,
+  forgetRetiredIdentityKey,
+  forgetRetiredIdentityKeys,
+  syncRetiredKeys,
+  retiredKeyFromPhrase,
+} from './retiredKeys';
+export type { RetiredIdentityKey, RetiredKeyPair, RetiredKeySelector } from './retiredKeys';
 export { SignatureService } from './signatureService';
 export type { SignedMessage, AuthChallenge } from './signatureService';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase';