@oxy.so/core 7.29.0 → 7.31.0

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

@@ -40,6 +40,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>;
 }
 /** @internal */
 export declare function registerIdentitySignerStore(store: IdentitySignerStore | null): void;

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

@@ -20,9 +20,11 @@ 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';
+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';

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

@@ -739,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'
@@ -762,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
@@ -770,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/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/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.29.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",
@@ -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.8.0",
+    "@oxy.so/contracts": "^6.12.0",
+    "@oxy.so/protocol": "^1.10.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

@@ -64,16 +64,29 @@ export {
 export type {
   KeychainAccess,
   KeychainAccessGroupName,
+  KeychainGroup,
   KeychainGroupOption,
   KeychainItemClass,
   KeychainRole,
   KeychainStoreLike,
+  OwnKeychainItemNames,
 } 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';