@oxy.so/core 7.29.0 → 7.30.0

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/package.json

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

@@ -74,6 +74,17 @@ 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';

package/src/crypto/keyManager.ts

@@ -32,6 +32,7 @@ import { isDev, logger } from '../logger';
 import { deriveScopedSeedFromKey, signSocialReceiveDigest } from './identityDerivations';
 import { type IdentitySignerStore, registerIdentitySignerStore } from './identitySigner';
 import { getOrganizationPrivateKey, isOrganizationAccountId } from './organizationKeys';
+import { forgetRetiredIdentityKeys, getRetiredPrivateKey, retiredKeyScope } from './retiredKeys';
 import {
   type KeychainItemClass,
   groupedKeychainStore,
@@ -2611,6 +2612,16 @@ export class KeyManager {
     if (force) {
       await KeyManager._bestEffortDeleteBackupsAllGenerations(store);
       await KeyManager._clearSharedSlot(store);
+      // The person's retired keys go with the identity they belonged to.
+      try {
+        await forgetRetiredIdentityKeys();
+      } catch (error) {
+        logger.warn(
+          'Failed to clear retired keys during delete',
+          { component: 'KeyManager' },
+          error,
+        );
+      }
     }
 
     // The device backup goes on EVERY delete, forced or not: it is restored
@@ -3229,18 +3240,37 @@ export 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 async deriveScopedSeed(
     info: string,
-    opts?: { accountId?: string },
+    opts?: { accountId?: string; publicKey?: string },
   ): Promise<Uint8Array | null> {
     if (isWebPlatform()) {
       return null;
     }
+    if (opts?.publicKey !== undefined) {
+      if (isAndroid() && !KeyManager.identitySignerStore) {
+        const selected = KeyManager._selectorKey(opts.publicKey);
+        if (!selected) return null;
+        const bridge = await loadCommonsIdentityBridge();
+        const seed =
+          (await bridge?.deriveRetiredScopedSeed?.(info, selected, opts.accountId)) ?? null;
+        return seed ? hexToBytes(seed) : null;
+      }
+      const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+      return selected ? deriveScopedSeedFromKey(selected, info) : null;
+    }
     if (opts?.accountId !== undefined) {
       return KeyManager._deriveOrganizationScopedSeed(info, opts.accountId);
     }
@@ -3292,7 +3322,8 @@ export 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
@@ -3301,11 +3332,24 @@ export class KeyManager {
   static async signSocialReceive(
     index: number,
     digest: string,
-    opts?: { accountId?: string },
+    opts?: { accountId?: string; publicKey?: string },
   ): Promise<CommonsSocialReceiveSignature | null> {
     if (isWebPlatform()) {
       return null;
     }
+    if (opts?.publicKey !== undefined) {
+      if (isAndroid() && !KeyManager.identitySignerStore) {
+        const selected = KeyManager._selectorKey(opts.publicKey);
+        if (!selected) return null;
+        const bridge = await loadCommonsIdentityBridge();
+        return (
+          (await bridge?.signRetiredSocialReceive?.(index, digest, selected, opts.accountId)) ??
+          null
+        );
+      }
+      const selected = await KeyManager._selectedPrivateKey(opts.publicKey, opts.accountId);
+      return selected ? signSocialReceiveDigest(selected, index, digest) : null;
+    }
     const accountId = opts?.accountId;
     if (accountId !== undefined) {
       // An organization key (ADR 0061 D6); never the personal one in its place.
@@ -3330,6 +3374,40 @@ export class KeyManager {
     return local ? signSocialReceiveDigest(local, index, digest) : 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(publicKey: string): string | null {
+    return KeyManager.isValidPublicKey(publicKey) ? KeyManager.canonicalPublicKey(publicKey) : null;
+  }
+
+  private static async _selectedPrivateKey(
+    publicKey: string,
+    accountId?: string,
+  ): Promise<string | null> {
+    if (retiredKeyScope({ accountId }) === null || !KeyManager.isValidPublicKey(publicKey)) {
+      return null;
+    }
+    const wanted = KeyManager.canonicalPublicKey(publicKey);
+    const current =
+      accountId !== undefined
+        ? await getOrganizationPrivateKey(accountId)
+        : isAndroid()
+          ? await KeyManager.getPrivateKey()
+          : ((await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey()));
+    if (current && KeyManager.canonicalPublicKey(KeyManager.derivePublicKey(current)) === wanted) {
+      return current;
+    }
+    return getRetiredPrivateKey(wanted, accountId !== undefined ? { accountId } : undefined);
+  }
+
   /**
    * Get a shortened version of the public key for display
    * Format: first 8 chars...last 8 chars