@oxy.so/core 7.31.0 → 7.32.0

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

@@ -4,6 +4,15 @@ 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`,
@@ -28,6 +37,8 @@ export type KeychainAccess = {
     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';
 };
@@ -47,6 +58,14 @@ export declare class KeychainAccessUnavailableError extends Error {
  */
 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;
 /**
@@ -60,7 +79,7 @@ export declare function keychainAccessFromDefaultGroup(defaultGroup: string, app
  * 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` for "no
@@ -68,17 +87,24 @@ export declare function resetKeychainAccessForTests(): void;
  * 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, 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}.
+ * 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[];
 /**
@@ -149,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.31.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",

package/src/api/identity.ts

@@ -47,6 +47,7 @@ import type { OxyContext } from '../client/context';
 import type { PendingIdentityResult } from '../crypto/recoveryPhrase';
 import { isAndroid, isWeb } from '../utils/platform';
 import { logger } from '../logger';
+import { extractErrorStatus } from '../utils/errorUtils';
 
 /** Short-TTL read cache for public identity reads. */
 const SHORT_TTL = 60 * 1000;
@@ -128,6 +129,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;
 }
 
 /**
@@ -476,11 +485,36 @@ export class IdentityApi {
       }
     }
 
+    // 8. The rotation deleted the encrypted backup (it was sealed under the
+    //    replaced phrase). Seal a new one under the new phrase, carrying the
+    //    retired ring — now with the key just replaced — so the coins under it
+    //    survive a lost phone as long as the NEW phrase does (R4-4). Always,
+    //    not only when one existed: after a rotation it is the only copy of the
+    //    replaced key off this phone. Best-effort: the rotation already succeeded.
+    let backupRefreshed: boolean | undefined;
+    if (!isWeb() && !localPersistFailed) {
+      try {
+        await this.backup.create(pending.phrase);
+        backupRefreshed = true;
+      } catch (backupError) {
+        backupRefreshed = false;
+        logger.warn(
+          'Key rotated, but the encrypted backup could not be re-created under the new phrase.',
+          { component: 'oxy.identity', method: 'rotateKey' },
+          backupError,
+        );
+      }
+    }
+
     this.invalidate(userId);
 
-    return localPersistFailed
-      ? { newPublicKey, newPhrase: pending.phrase, words: pending.words, localPersistFailed: true }
-      : { newPublicKey, newPhrase: pending.phrase, words: pending.words };
+    return {
+      newPublicKey,
+      newPhrase: pending.phrase,
+      words: pending.words,
+      ...(localPersistFailed ? { localPersistFailed: true as const } : {}),
+      ...(backupRefreshed === undefined ? {} : { backupRefreshed }),
+    };
   }
 
   /**
@@ -736,11 +770,29 @@ const BACKUP_ALGORITHM = 'xchacha20poly1305' as const;
  */
 const PUBLIC_KEY_HINT_LENGTH = 16;
 
-/** The decrypted backup payload. */
+/** One retired key carried in the backup (R4-4). */
+interface BackupRetiredKey {
+  privateKey: string;
+  publicKey: string;
+  retiredAt: number;
+}
+
+/**
+ * The decrypted backup payload. `retiredKeys` (since core 2026-11, optional,
+ * ignored by older readers) carries the person's retired ring, so the CURRENT
+ * phrase restores the keys their earlier coins sit under (ADR 0061 D7 as
+ * amended): a lost phone then costs no more than the current phrase does.
+ */
 interface BackupPayload {
   privateKey: string;
   publicKey: string;
   createdAt: string;
+  retiredKeys?: BackupRetiredKey[];
+}
+
+/** Whether a request error is the restore lookup's constant-shape 404. */
+function isNotFound(error: unknown): boolean {
+  return extractErrorStatus(error) === 404;
 }
 
 /** Encode bytes as lowercase hex (cross-platform, no Buffer dependency). */
@@ -806,7 +858,13 @@ export class IdentityBackupApi {
     const createdAt = new Date().toISOString();
     const publicKeyHint = publicKey.slice(0, PUBLIC_KEY_HINT_LENGTH);
 
-    const payload: BackupPayload = { privateKey, publicKey, createdAt };
+    const retiredKeys = await this.retiredKeysToCarry(publicKey);
+    const payload: BackupPayload = {
+      privateKey,
+      publicKey,
+      createdAt,
+      ...(retiredKeys.length > 0 ? { retiredKeys } : {}),
+    };
     const plaintext = new TextEncoder().encode(JSON.stringify(payload));
     const aad = buildBackupAad(BACKUP_ENVELOPE_VERSION, publicKeyHint);
     const { nonce, ciphertext } = encryptAead(backupKey, plaintext, aad);
@@ -827,6 +885,120 @@ export class IdentityBackupApi {
     });
   }
 
+  /**
+   * 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 async retiredKeysToCarry(currentPublicKey: string): Promise<BackupRetiredKey[]> {
+    if (isWeb()) return [];
+    const { exportRetiredIdentityKeys } = await import('../crypto/index');
+    let held: BackupRetiredKey[];
+    try {
+      held = await exportRetiredIdentityKeys();
+    } catch {
+      return []; // Not Commons: this app holds no ring to carry.
+    }
+    if (held.length === 0) return [];
+    const history = await this.ctx.request<unknown>('GET', '/identity/key-history', undefined, {
+      cache: false,
+    });
+    const parsed = checkContract(identityKeyHistoryCheck, history);
+    if (!parsed) throw new Error('identity/key-history returned an unexpected response shape');
+    const retired = new Set(parsed.retired.map((entry) => entry.publicKey.toLowerCase()));
+    const current = currentPublicKey.toLowerCase();
+    return held.filter(
+      (key) => key.publicKey.toLowerCase() !== current && retired.has(key.publicKey.toLowerCase()),
+    );
+  }
+
+  /**
+   * 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 async open(phrase: string, missingIsNull = false): Promise<BackupPayload | null> {
+    const { KeyManager, RecoveryPhraseService, decryptAead } = await import('../crypto/index');
+    const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
+    let envelope: EncryptedBackupEnvelope;
+    try {
+      envelope = await this.ctx.request<EncryptedBackupEnvelope>(
+        'GET',
+        `/identity/backup/${encodeURIComponent(lookupId)}`,
+        undefined,
+        { cache: false },
+      );
+    } catch (error) {
+      if (missingIsNull && isNotFound(error)) return null;
+      throw error;
+    }
+    if (envelope.algorithm !== BACKUP_ALGORITHM) {
+      throw new Error(`Unsupported backup algorithm: ${envelope.algorithm}`);
+    }
+    const aad = buildBackupAad(envelope.version, envelope.publicKeyHint);
+    const plaintext = decryptAead(
+      backupKey,
+      fromHex(envelope.nonce),
+      fromHex(envelope.ciphertext),
+      aad,
+    );
+    const payload = JSON.parse(new TextDecoder().decode(plaintext)) as BackupPayload;
+    if (!payload.privateKey || !payload.publicKey) {
+      throw new Error('Backup payload is missing key material');
+    }
+    const phrasePk = (await RecoveryPhraseService.derivePublicKeyFromPhrase(phrase)).toLowerCase();
+    const payloadPk = payload.publicKey.toLowerCase();
+    const privatePk = KeyManager.derivePublicKey(payload.privateKey).toLowerCase();
+    if (phrasePk !== payloadPk || privatePk !== payloadPk) {
+      throw new Error('Backup payload does not match the recovery phrase');
+    }
+    return payload;
+  }
+
+  /**
+   * 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 async keepCarriedRetiredKeys(payload: BackupPayload): Promise<number> {
+    const { KeyManager, retireIdentityKey } = await import('../crypto/index');
+    let kept = 0;
+    for (const key of Array.isArray(payload.retiredKeys) ? payload.retiredKeys : []) {
+      try {
+        if (typeof key?.privateKey !== 'string' || typeof key.publicKey !== 'string') continue;
+        if (key.publicKey.toLowerCase() === payload.publicKey.toLowerCase()) continue;
+        if (
+          KeyManager.derivePublicKey(key.privateKey).toLowerCase() !== key.publicKey.toLowerCase()
+        ) {
+          continue;
+        }
+        await retireIdentityKey({ privateKey: key.privateKey, publicKey: key.publicKey });
+        kept += 1;
+      } catch (error) {
+        logger.warn(
+          'Could not keep a retired key from the encrypted backup',
+          { component: 'oxy.identity', method: 'backup.restoreRetiredKeys' },
+          error,
+        );
+      }
+    }
+    return kept;
+  }
+
+  /**
+   * 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.
+   */
+  async restoreRetiredKeys(phrase: string): Promise<number> {
+    const payload = await this.open(phrase, true);
+    return payload ? this.keepCarriedRetiredKeys(payload) : 0;
+  }
+
   /**
    * Whether the signed-in user has a stored backup, plus its non-sensitive hint
    * and timestamp. Returns no ciphertext and no locator.
@@ -859,40 +1031,13 @@ export class IdentityBackupApi {
    *   fails authentication (tamper), or an existing identity blocks the import.
    */
   async restore(phrase: string, options?: { overwrite?: boolean }): Promise<string> {
-    const { KeyManager, RecoveryPhraseService, decryptAead } = await import('../crypto/index');
-    const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
-
-    const envelope = await this.ctx.request<EncryptedBackupEnvelope>(
-      'GET',
-      `/identity/backup/${encodeURIComponent(lookupId)}`,
-      undefined,
-      { cache: false },
-    );
-
-    if (envelope.algorithm !== BACKUP_ALGORITHM) {
-      throw new Error(`Unsupported backup algorithm: ${envelope.algorithm}`);
-    }
-
-    const aad = buildBackupAad(envelope.version, envelope.publicKeyHint);
-    const plaintext = decryptAead(
-      backupKey,
-      fromHex(envelope.nonce),
-      fromHex(envelope.ciphertext),
-      aad,
-    );
-    const payload = JSON.parse(new TextDecoder().decode(plaintext)) as BackupPayload;
-
-    if (!payload.privateKey || !payload.publicKey) {
-      throw new Error('Backup payload is missing key material');
-    }
-
-    const phrasePk = (await RecoveryPhraseService.derivePublicKeyFromPhrase(phrase)).toLowerCase();
-    const payloadPk = payload.publicKey.toLowerCase();
-    const privatePk = KeyManager.derivePublicKey(payload.privateKey).toLowerCase();
-    if (phrasePk !== payloadPk || privatePk !== payloadPk) {
-      throw new Error('Backup payload does not match the recovery phrase');
-    }
-
-    return KeyManager.importKeyPair(payload.privateKey, { overwrite: options?.overwrite === true });
+    const { KeyManager } = await import('../crypto/index');
+    const payload = await this.open(phrase);
+    if (!payload) throw new Error('No encrypted backup was found for this recovery phrase.');
+    const publicKey = await KeyManager.importKeyPair(payload.privateKey, {
+      overwrite: options?.overwrite === true,
+    });
+    await this.keepCarriedRetiredKeys(payload);
+    return publicKey;
   }
 }

package/src/crypto/identityMarker.ts

@@ -185,6 +185,21 @@ export async 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 async function readIdentityMarkerStrict(): Promise<IdentityMarker | null> {
+  const storage = await getStorage();
+  if (!storage) {
+    throw new Error('The identity marker storage is unavailable.');
+  }
+  return deserialize(await storage.getItem(IDENTITY_MARKER_STORAGE_KEY));
+}
+
 /**
  * Write (create/replace) the marker. Returns `true` when it durably landed,
  * `false` when storage was unavailable or the write threw. Callers treat a

package/src/crypto/index.ts

@@ -51,6 +51,8 @@ export {
   KeychainAccessUnavailableError,
   keychainGroupFor,
   mayHoldKeychainItem,
+  mayWriteKeychainItem,
+  DEV_KEYCHAIN_GROUP_SUFFIX,
   resolveKeychainAccess,
   keychainAccessGroupValue,
   keychainReadPlan,
@@ -71,7 +73,10 @@ export type {
   KeychainStoreLike,
   OwnKeychainItemNames,
 } from '../utils/keychainAccessGroups';
-export { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+export {
+  ensureKeychainGroupsMigrated,
+  getPreSplitExposure,
+} from './keychainGroupMigration';
 export type {
   KeychainGroupMigrationReport,
   KeychainItemMigrationOutcome,
@@ -85,6 +90,8 @@ export {
   forgetRetiredIdentityKeys,
   syncRetiredKeys,
   retiredKeyFromPhrase,
+  retiredKeyFromPrivateKey,
+  exportRetiredIdentityKeys,
 } from './retiredKeys';
 export type { RetiredIdentityKey, RetiredKeyPair, RetiredKeySelector } from './retiredKeys';
 export { SignatureService } from './signatureService';

package/src/crypto/keyManager.ts

@@ -32,13 +32,13 @@ 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 { getRetiredPrivateKey, retiredKeyScope } from './retiredKeys';
 import {
   type KeychainItemClass,
   groupedKeychainStore,
   resolveKeychainAccess,
 } from '../utils/keychainAccessGroups';
-import { ensureKeychainGroupsMigrated } from './keychainGroupMigration';
+import { prepareKeychainAccess } from './keychainGroupMigration';
 import {
   RECOVERY_MNEMONIC_KEYCHAIN_SERVICE,
   RECOVERY_MNEMONIC_STORAGE_KEY,
@@ -300,9 +300,7 @@ async function loadRawSecureStore(): Promise<ExpoSecureStoreLike> {
 async function keychainItemStore(item: KeychainItemClass): Promise<ExpoSecureStoreLike> {
   const raw = await loadRawSecureStore();
   const access = await resolveKeychainAccess();
-  if (access.mode === 'grouped' && access.role === 'holder') {
-    await ensureKeychainGroupsMigrated();
-  }
+  await prepareKeychainAccess(access);
   return groupedKeychainStore(raw, access, item);
 }
 
@@ -2612,16 +2610,12 @@ 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 retired ring is NOT cleared (R4-4): it is money under the person's
+      // previous keys, and "Start over" or a forced delete must not cost it.
+      // The same person restoring their identity finds it again; a different
+      // identity on this phone cannot use it (each entry is checked against
+      // that account's key history before use). Only deleting the Oxy ACCOUNT
+      // clears it, explicitly (`forgetRetiredIdentityKeys`, Commons' flow).
     }
 
     // The device backup goes on EVERY delete, forced or not: it is restored