@oxy.so/core 7.30.0 → 7.32.0

package/dist/cjs/utils/keychainAccessGroups.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeychainAccessUnavailableError = exports.KEYCHAIN_ACCESS_GROUPS = void 0;
+exports.KeychainAccessUnavailableError = exports.DEV_KEYCHAIN_GROUP_SUFFIX = exports.KEYCHAIN_ACCESS_GROUPS = void 0;
 exports.keychainGroupFor = keychainGroupFor;
+exports.mayWriteKeychainItem = mayWriteKeychainItem;
 exports.mayHoldKeychainItem = mayHoldKeychainItem;
 exports.keychainAccessFromDefaultGroup = keychainAccessFromDefaultGroup;
 exports.resolveKeychainAccess = resolveKeychainAccess;
 exports.resetKeychainAccessForTests = resetKeychainAccessForTests;
 exports.keychainAccessGroupValue = keychainAccessGroupValue;
+exports.setHolderSharedSecretFallback = setHolderSharedSecretFallback;
+exports.closeWalletSharedSecretFallback = closeWalletSharedSecretFallback;
 exports.keychainReadPlan = keychainReadPlan;
 exports.keychainDeletePlan = keychainDeletePlan;
 exports.keychainWriteOption = keychainWriteOption;
@@ -23,6 +26,7 @@ exports.groupedKeychainStore = groupedKeychainStore;
  * | `<TEAM>.so.oxy.identity`      | Commons only (listed FIRST)  | `identity-secret` |
  * | `<TEAM>.so.oxy.wallet`        | Commons, the Peable wallet   | `spending-key`    |
  * | `<TEAM>.group.so.oxy.shared`  | every Oxy app                | `shared`          |
+ * | `<TEAM>.<bundle id>`          | that app alone               | `app`             |
  *
  * - `identity-secret`: the personal root (primary and backup slots), the
  *   personal and organization recovery phrases, the organization index. Only
@@ -32,14 +36,21 @@ exports.groupedKeychainStore = groupedKeychainStore;
  *   (`deriveScopedSeed`, `signSocialReceive`). Commons writes them; the Peable
  *   wallet reads them.
  * - `shared`: what every Oxy app may read: the shared public key and the
- *   device-session credential.
+ *   device-session credential (the one cross-app session join point).
+ * - `app`: an app's OWN items, readable by no other app: its session
+ *   credential (`oxy.auth.v1` and the rest of the SDK's session store), its
+ *   identity pin, its settings, the Peable wallet's imported phrases. The group
+ *   is the app's application identifier, which Apple makes every app a member
+ *   of; no app lists it and no other app can name it. Android's counterpart is
+ *   the app's own storage (ADR 0062 D6).
  *
  * The ROLE of this binary comes from the keychain itself: an item written
  * without a group lands in the app's default group, the first entry of its
  * `keychain-access-groups` entitlement, and `@oxy.so/app-preset` lets only
  * Commons put the identity group first and only the Peable wallet the wallet
  * group. The same probe gives the team prefix, which `kSecAttrAccessGroup`
- * needs and JavaScript cannot otherwise see.
+ * needs and JavaScript cannot otherwise see; a second probe proves the app's
+ * own group (`<prefix><bundle id>`) is writable.
  *
  * Android and web have no access groups: there every helper here answers the
  * single-store behaviour (`ungrouped`), and Android's narrowing is Commons'
@@ -57,6 +68,15 @@ exports.KEYCHAIN_ACCESS_GROUPS = {
     wallet: 'so.oxy.wallet',
     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.
+ */
+exports.DEV_KEYCHAIN_GROUP_SUFFIX = '.dev';
 /** Thrown while the probe cannot answer (before first unlock). Transient. */
 class KeychainAccessUnavailableError extends Error {
     constructor(cause) {
@@ -66,10 +86,6 @@ class KeychainAccessUnavailableError extends Error {
     }
 }
 exports.KeychainAccessUnavailableError = KeychainAccessUnavailableError;
-/**
- * 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.
- */
 function keychainGroupFor(item) {
     switch (item) {
         case 'identity-secret':
@@ -78,8 +94,20 @@ function keychainGroupFor(item) {
             return 'wallet';
         case 'shared':
             return 'shared';
+        case 'app':
+            return 'app';
     }
 }
+/**
+ * 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.)
+ */
+function mayWriteKeychainItem(role, item) {
+    return role === 'holder' || item === 'shared' || item === 'app';
+}
 /** Whether `role` holds the group `item` lives in. */
 function mayHoldKeychainItem(role, item) {
     switch (role) {
@@ -88,11 +116,14 @@ function mayHoldKeychainItem(role, item) {
         case 'wallet':
             return item !== 'identity-secret';
         case 'member':
-            return item === 'shared';
+            return item === 'shared' || item === 'app';
     }
 }
-/** Parse the default access group the probe reported. Exported for tests. */
-function keychainAccessFromDefaultGroup(defaultGroup) {
+/**
+ * Parse the default access group the probe reported, and the app's own group
+ * when the second probe proved it. Exported for tests.
+ */
+function keychainAccessFromDefaultGroup(defaultGroup, appGroup) {
     const dot = defaultGroup.indexOf('.');
     if (dot <= 0 || dot === defaultGroup.length - 1) {
         // Not `<prefix>.<group>`: an unsigned simulator build. Nothing to split.
@@ -100,12 +131,18 @@ function keychainAccessFromDefaultGroup(defaultGroup) {
     }
     const prefix = defaultGroup.slice(0, dot + 1);
     const group = defaultGroup.slice(dot + 1);
-    const role = group === exports.KEYCHAIN_ACCESS_GROUPS.identity
+    const dev = group.endsWith(exports.DEV_KEYCHAIN_GROUP_SUFFIX);
+    const base = dev ? group.slice(0, -exports.DEV_KEYCHAIN_GROUP_SUFFIX.length) : group;
+    const role = base === exports.KEYCHAIN_ACCESS_GROUPS.identity
         ? 'holder'
-        : group === exports.KEYCHAIN_ACCESS_GROUPS.wallet
+        : base === exports.KEYCHAIN_ACCESS_GROUPS.wallet
             ? 'wallet'
             : 'member';
-    return { mode: 'grouped', prefix, defaultGroup, role };
+    // A `.dev` suffix on anything but a restricted group is not a variant.
+    const variant = dev && role !== 'member' ? { variant: exports.DEV_KEYCHAIN_GROUP_SUFFIX } : {};
+    return appGroup?.startsWith(prefix)
+        ? { mode: 'grouped', prefix, defaultGroup, role, appGroup, ...variant }
+        : { mode: 'grouped', prefix, defaultGroup, role, ...variant };
 }
 let resolvedAccess = null;
 /**
@@ -133,28 +170,101 @@ async function resolveKeychainAccess() {
     if (probe.state === 'unavailable') {
         throw new KeychainAccessUnavailableError(probe.cause);
     }
-    resolvedAccess =
-        probe.state === 'resolved'
-            ? keychainAccessFromDefaultGroup(probe.accessGroup)
-            : { mode: 'ungrouped' };
+    if (probe.state !== 'resolved') {
+        resolvedAccess = { mode: 'ungrouped' };
+        return resolvedAccess;
+    }
+    const access = keychainAccessFromDefaultGroup(probe.accessGroup);
+    if (access.mode === 'ungrouped') {
+        resolvedAccess = access;
+        return resolvedAccess;
+    }
+    // The app's own group. A thrown probe is NOT degraded to "no app group": this
+    // process would then write the app's items to the old place while the next
+    // one reads the new place first, and see a stale value.
+    let own;
+    try {
+        own = await (0, protocol_1.loadKeychainApplicationAccessGroup)(access.prefix);
+    }
+    catch (cause) {
+        throw new KeychainAccessUnavailableError(cause);
+    }
+    if (own.state === 'unavailable') {
+        throw new KeychainAccessUnavailableError(own.cause);
+    }
+    resolvedAccess = keychainAccessFromDefaultGroup(probe.accessGroup, own.state === 'resolved' ? own.accessGroup : undefined);
     return resolvedAccess;
 }
-/** Forget the memoized access. Tests only. @internal */
+/** Forget the memoized access and the fallback state. Tests only. @internal */
 function resetKeychainAccessForTests() {
     resolvedAccess = null;
+    holderSharedFallback = false;
+    walletSharedFallbackClosed = false;
 }
-/** The full `kSecAttrAccessGroup` value of `group`, or `undefined` when ungrouped. */
+/**
+ * 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}).
+ */
 function keychainAccessGroupValue(access, group) {
-    return access.mode === 'grouped' ? `${access.prefix}${exports.KEYCHAIN_ACCESS_GROUPS[group]}` : undefined;
+    if (access.mode === 'ungrouped') {
+        return undefined;
+    }
+    if (group === 'app') {
+        // Commons' and the Peable wallet's default groups are theirs (no other app
+        // writes its own items there), so a build without the app-group probe
+        // keeps its own items there, as ADR 0062 D3 put them. Every other app's
+        // default is the shared group: no group, the calls it always made.
+        return access.appGroup ?? (access.role === 'member' ? undefined : access.defaultGroup);
+    }
+    const variant = group === 'shared' ? '' : (access.variant ?? '');
+    return `${access.prefix}${exports.KEYCHAIN_ACCESS_GROUPS[group]}${variant}`;
+}
+/**
+ * Whether a SECRET read may still fall back to the pre-split shared group
+ * (R4-7). Every Oxy app can write that group, and keychain items survive an
+ * uninstall, so a secret found there is one Commons did not necessarily write.
+ *
+ * - Commons (`holder`): CLOSED, except while its one-shot migration has proved
+ *   the shared copies are its own (they carry the key its sandbox marker
+ *   records) and could not move them all yet; the migration opens it for that
+ *   launch only ({@link setHolderSharedSecretFallback}).
+ * - The Peable wallet: open until Commons' migration has finished (the
+ *   completion record Commons mirrors into the wallet group), because until
+ *   then an upgraded phone's keys are still in the shared group; closed for
+ *   good once it has seen that record ({@link closeWalletSharedSecretFallback}).
+ */
+let holderSharedFallback = false;
+let walletSharedFallbackClosed = false;
+/** The migration's switch for Commons' fallback. @internal */
+function setHolderSharedSecretFallback(open) {
+    holderSharedFallback = open;
+}
+/** The wallet saw Commons' completion record: no shared fallback again in this process. @internal */
+function closeWalletSharedSecretFallback() {
+    walletSharedFallbackClosed = true;
+}
+function sharedFallbackOpen(access) {
+    switch (access.role) {
+        case 'holder':
+            return holderSharedFallback;
+        case 'wallet':
+            return !walletSharedFallbackClosed;
+        case 'member':
+            return false;
+    }
 }
 function option(value) {
     return value === undefined ? {} : { accessGroup: value };
 }
 /**
- * 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 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}.
  */
 function keychainReadPlan(access, item) {
     if (access.mode === 'ungrouped') {
@@ -165,17 +275,29 @@ function keychainReadPlan(access, item) {
     }
     const own = keychainGroupFor(item);
     const plan = [option(keychainAccessGroupValue(access, own))];
-    if (own !== 'shared') {
+    if ((own === 'identity' || own === 'wallet') && sharedFallbackOpen(access)) {
         plan.push(option(keychainAccessGroupValue(access, 'shared')));
     }
     return plan;
 }
 /**
- * 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.
  */
 function keychainDeletePlan(access, item) {
-    return keychainReadPlan(access, item);
+    if (access.mode === 'ungrouped') {
+        return [{}];
+    }
+    if (!mayHoldKeychainItem(access.role, item)) {
+        return [];
+    }
+    const own = keychainGroupFor(item);
+    const plan = [option(keychainAccessGroupValue(access, own))];
+    if (own === 'identity' || own === 'wallet') {
+        plan.push(option(keychainAccessGroupValue(access, 'shared')));
+    }
+    return plan;
 }
 /**
  * The option a WRITE of `item` carries. THROWS when this app may not hold the
@@ -186,31 +308,56 @@ function keychainWriteOption(access, item) {
     if (access.mode === 'ungrouped') {
         return {};
     }
-    if (!mayHoldKeychainItem(access.role, item)) {
-        throw new Error(`This app (keychain role "${access.role}") may not hold a ${item} keychain item; only Commons writes the identity.`);
+    if (!mayWriteKeychainItem(access.role, item)) {
+        throw new Error(`This app (keychain role "${access.role}") may not write a ${item} keychain item; only Commons writes the identity and the keys the wallet spends.`);
     }
     return option(keychainAccessGroupValue(access, keychainGroupFor(item)));
 }
 /**
- * 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.
+ * 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.
  */
-function ownKeychainItemPlan(access) {
-    if (access.mode === 'ungrouped' || access.role === 'member') {
+function ownKeychainItemPlan(access, names = 'this-app') {
+    if (access.mode === 'ungrouped') {
         return { read: [{}], write: {}, delete: [{}] };
     }
-    return {
-        read: [option(access.defaultGroup), {}],
-        write: option(access.defaultGroup),
-        delete: [{}],
-    };
+    const own = keychainAccessGroupValue(access, keychainGroupFor('app'));
+    if (own === undefined) {
+        return { read: [{}], write: {}, delete: [{}] };
+    }
+    const earlier = access.role !== 'member' && own !== access.defaultGroup ? [option(access.defaultGroup)] : [];
+    const mine = [option(own), ...earlier];
+    switch (names) {
+        case 'this-app':
+            return { read: [...mine, {}], write: option(own), delete: [{}] };
+        case 'every-oxy-app':
+            return { read: mine, write: option(own), delete: [...mine].reverse() };
+        case 'every-oxy-app-withholding': {
+            const read = [...mine, option(keychainAccessGroupValue(access, 'shared'))];
+            return { read, write: option(own), delete: [...read].reverse() };
+        }
+    }
 }
 /** Read `key` through `plan`: the first non-null answer. A thrown read propagates. */
 async function readThroughPlan(store, key, options, plan) {
@@ -230,19 +377,29 @@ async function deleteThroughPlan(store, key, options, plan) {
 }
 /**
  * `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.
  */
 function groupedKeychainStore(store, access, item) {
-    const plan = keychainReadPlan(access, item);
+    const sharedCopy = access.mode === 'grouped' && (item === 'identity-secret' || item === 'spending-key')
+        ? option(keychainAccessGroupValue(access, 'shared'))
+        : null;
     const wrapped = {
-        getItemAsync: (key, options) => readThroughPlan(store, key, options ?? {}, plan),
+        getItemAsync: (key, options) => readThroughPlan(store, key, options ?? {}, keychainReadPlan(access, item)),
         setItemAsync: async (key, value, options) => {
             const group = keychainWriteOption(access, item);
             await store.setItemAsync(key, value, { ...(options ?? {}), ...group });
+            if (sharedCopy) {
+                const { keychainAccessible: _accessible, ...rest } = (options ?? {});
+                await store.deleteItemAsync(key, { ...rest, ...sharedCopy });
+            }
         },
-        deleteItemAsync: (key, options) => deleteThroughPlan(store, key, options ?? {}, plan),
+        deleteItemAsync: (key, options) => deleteThroughPlan(store, key, options ?? {}, keychainDeletePlan(access, item)),
     };
     return Object.assign(Object.create(store), wrapped);
 }

package/dist/esm/api/identity.js

@@ -21,6 +21,7 @@ import { checkContract, IDENTITY_PROOF_ACTIONS, identityLinkCreateResponseCheck,
 import { identityKeyHistoryCheck } from '@oxy.so/contracts/client';
 import { isAndroid, isWeb } from '../utils/platform.js';
 import { logger } from '../logger/index.js';
+import { extractErrorStatus } from '../utils/errorUtils.js';
 /** Short-TTL read cache for public identity reads. */
 const SHORT_TTL = 60 * 1000;
 /**
@@ -316,10 +317,31 @@ 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;
+        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 } : {}),
+            ...(backupRefreshed === undefined ? {} : { backupRefreshed }),
+        };
     }
     /**
      * The signed-in user's signed, open-format data-export bundle
@@ -508,6 +530,10 @@ const BACKUP_ALGORITHM = 'xchacha20poly1305';
  * to recognise WHICH identity a backup belongs to, but only a prefix.
  */
 const PUBLIC_KEY_HINT_LENGTH = 16;
+/** Whether a request error is the restore lookup's constant-shape 404. */
+function isNotFound(error) {
+    return extractErrorStatus(error) === 404;
+}
 /** Encode bytes as lowercase hex (cross-platform, no Buffer dependency). */
 function toHex(bytes) {
     let out = '';
@@ -567,7 +593,13 @@ export class IdentityBackupApi {
         const publicKey = KeyManager.derivePublicKey(privateKey);
         const createdAt = new Date().toISOString();
         const publicKeyHint = publicKey.slice(0, PUBLIC_KEY_HINT_LENGTH);
-        const payload = { privateKey, publicKey, createdAt };
+        const retiredKeys = await this.retiredKeysToCarry(publicKey);
+        const payload = {
+            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);
@@ -585,6 +617,107 @@ export class IdentityBackupApi {
             cache: false,
         });
     }
+    /**
+     * 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.
+     */
+    async retiredKeysToCarry(currentPublicKey) {
+        if (isWeb())
+            return [];
+        const { exportRetiredIdentityKeys } = await import('../crypto/index.js');
+        let held;
+        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('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.
+     */
+    async open(phrase, missingIsNull = false) {
+        const { KeyManager, RecoveryPhraseService, decryptAead } = await import('../crypto/index.js');
+        const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
+        let envelope;
+        try {
+            envelope = await this.ctx.request('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));
+        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.
+     */
+    async keepCarriedRetiredKeys(payload) {
+        const { KeyManager, retireIdentityKey } = await import('../crypto/index.js');
+        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) {
+        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.
@@ -615,24 +748,14 @@ export class IdentityBackupApi {
      *   fails authentication (tamper), or an existing identity blocks the import.
      */
     async restore(phrase, options) {
-        const { KeyManager, RecoveryPhraseService, decryptAead } = await import('../crypto/index.js');
-        const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(phrase);
-        const envelope = await this.ctx.request('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));
-        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.js');
+        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/dist/esm/crypto/identityMarker.js

@@ -145,6 +145,20 @@ export async function readIdentityMarker() {
         return 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() {
+    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/dist/esm/crypto/index.js

@@ -18,11 +18,11 @@ export { readIdentityMarker, updateIdentityMarker } from './identityMarker.js';
 // Organization keys on the device (docs/adr/0061-organization-identity-key.md D6)
 export { generateOrganizationKey, organizationKeyFromPhrase, storeOrganizationKey, getOrganizationPublicKey, getOrganizationPrivateKey, getOrganizationRecoveryPhrase, listOrganizationKeys, deleteOrganizationKey, syncOrganizationKeys, isOrganizationAccountId, isHealthyOrganizationKeyPair, } from './organizationKeys.js';
 // 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.js';
-export { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
+export { KEYCHAIN_ACCESS_GROUPS, KeychainAccessUnavailableError, keychainGroupFor, mayHoldKeychainItem, mayWriteKeychainItem, DEV_KEYCHAIN_GROUP_SUFFIX, resolveKeychainAccess, keychainAccessGroupValue, keychainReadPlan, keychainDeletePlan, keychainWriteOption, ownKeychainItemPlan, readThroughPlan, deleteThroughPlan, groupedKeychainStore, } from '../utils/keychainAccessGroups.js';
+export { ensureKeychainGroupsMigrated, getPreSplitExposure, } from './keychainGroupMigration.js';
 // 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.js';
+export { retireIdentityKey, listRetiredIdentityKeys, forgetRetiredIdentityKey, forgetRetiredIdentityKeys, syncRetiredKeys, retiredKeyFromPhrase, retiredKeyFromPrivateKey, exportRetiredIdentityKeys, } from './retiredKeys.js';
 export { SignatureService } from './signatureService.js';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase.js';
 // Low-level primitives (encrypted backup, device transfer)