@oxy.so/core 7.29.0 → 7.31.0

package/dist/cjs/utils/keychainAccessGroups.js

@@ -23,6 +23,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 +33,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'
@@ -66,10 +74,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,6 +82,8 @@ function keychainGroupFor(item) {
             return 'wallet';
         case 'shared':
             return 'shared';
+        case 'app':
+            return 'app';
     }
 }
 /** Whether `role` holds the group `item` lives in. */
@@ -88,11 +94,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.
@@ -105,7 +114,9 @@ function keychainAccessFromDefaultGroup(defaultGroup) {
         : group === exports.KEYCHAIN_ACCESS_GROUPS.wallet
             ? 'wallet'
             : 'member';
-    return { mode: 'grouped', prefix, defaultGroup, role };
+    return appGroup?.startsWith(prefix)
+        ? { mode: 'grouped', prefix, defaultGroup, role, appGroup }
+        : { mode: 'grouped', prefix, defaultGroup, role };
 }
 let resolvedAccess = null;
 /**
@@ -133,28 +144,62 @@ 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 */
 function resetKeychainAccessForTests() {
     resolvedAccess = null;
 }
-/** 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);
+    }
+    return `${access.prefix}${exports.KEYCHAIN_ACCESS_GROUPS[group]}`;
 }
 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, 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}.
  */
 function keychainReadPlan(access, item) {
     if (access.mode === 'ungrouped') {
@@ -165,7 +210,8 @@ function keychainReadPlan(access, item) {
     }
     const own = keychainGroupFor(item);
     const plan = [option(keychainAccessGroupValue(access, own))];
-    if (own !== 'shared') {
+    if (own === 'identity' || own === 'wallet') {
+        // Where the split moved these items from.
         plan.push(option(keychainAccessGroupValue(access, 'shared')));
     }
     return plan;
@@ -192,25 +238,50 @@ function keychainWriteOption(access, item) {
     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.
  *
- * Every other app (`member`) and Android/web keep the calls they always made.
+ * 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.
+ *
+ * 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) {

package/dist/esm/api/identity.js

@@ -18,6 +18,7 @@
  * AEAD, signatures) load on first use, never with the client itself.
  */
 import { checkContract, IDENTITY_PROOF_ACTIONS, identityLinkCreateResponseCheck, identityLinkStateCheck, } from '@oxy.so/contracts/client';
+import { identityKeyHistoryCheck } from '@oxy.so/contracts/client';
 import { isAndroid, isWeb } from '../utils/platform.js';
 import { logger } from '../logger/index.js';
 /** Short-TTL read cache for public identity reads. */
@@ -158,7 +159,7 @@ export class IdentityApi {
         if (!userId) {
             throw new Error('No authenticated user — sign in before rotating your key.');
         }
-        const { KeyManager, RecoveryPhraseService, SignatureService, signMessage } = await import('../crypto/index.js');
+        const { KeyManager, RecoveryPhraseService, SignatureService, signMessage, retireIdentityKey } = await import('../crypto/index.js');
         // 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.
         const pending = options.pendingIdentity ?? (await RecoveryPhraseService.derivePendingIdentity());
@@ -166,6 +167,7 @@ export class IdentityApi {
         // 2. Resolve the OLD signing capability from the chosen proof mode.
         let oldPublicKey;
         let signWithOldKey;
+        let oldPrivateKeyForRing;
         if (options.proof === 'phrase') {
             const phrase = options.phrase?.trim();
             if (!phrase) {
@@ -174,6 +176,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();
@@ -182,6 +185,25 @@ 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).
         const { challenge } = await this.ctx.request('POST', '/auth/rotate/challenge', undefined, {
@@ -338,6 +360,23 @@ export class IdentityApi {
             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() {
+        const res = await this.ctx.request('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). */
 export class IdentityLinksApi {

package/dist/esm/crypto/index.js

@@ -20,6 +20,9 @@ export { generateOrganizationKey, organizationKeyFromPhrase, storeOrganizationKe
 // 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';
+// 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 { SignatureService } from './signatureService.js';
 export { RecoveryPhraseService, BACKUP_KDF_ENCRYPTION_INFO } from './recoveryPhrase.js';
 // Low-level primitives (encrypted backup, device transfer)

package/dist/esm/crypto/keyManager.js

@@ -11,6 +11,7 @@ import { isDev, logger } from '../logger/index.js';
 import { deriveScopedSeedFromKey, signSocialReceiveDigest } from './identityDerivations.js';
 import { registerIdentitySignerStore } from './identitySigner.js';
 import { getOrganizationPrivateKey, isOrganizationAccountId } from './organizationKeys.js';
+import { forgetRetiredIdentityKeys, getRetiredPrivateKey, retiredKeyScope } from './retiredKeys.js';
 import { groupedKeychainStore, resolveKeychainAccess, } from '../utils/keychainAccessGroups.js';
 import { ensureKeychainGroupsMigrated } from './keychainGroupMigration.js';
 import { RECOVERY_MNEMONIC_KEYCHAIN_SERVICE, RECOVERY_MNEMONIC_STORAGE_KEY, STORAGE_KEYS, V2_BACKUP_KEYCHAIN_SERVICE, V2_PRIMARY_KEYCHAIN_SERVICE, V2_STORAGE_KEYS, } from './keychainItems.js';
@@ -2049,6 +2050,13 @@ 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
         // silently, so leaving it would bring a deleted identity back on the next
@@ -2581,8 +2589,15 @@ 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.
      */
@@ -2590,6 +2605,18 @@ export class KeyManager {
         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);
         }
@@ -2635,7 +2662,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
@@ -2645,6 +2673,18 @@ export class KeyManager {
         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.
@@ -2668,6 +2708,34 @@ export class KeyManager {
             : ((await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey()));
         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
+     */
+    static _selectorKey(publicKey) {
+        return KeyManager.isValidPublicKey(publicKey) ? KeyManager.canonicalPublicKey(publicKey) : null;
+    }
+    static async _selectedPrivateKey(publicKey, accountId) {
+        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