@oxy.so/core 7.28.0 → 7.30.0

package/dist/cjs/crypto/retiredKeys.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retiredKeyScope = retiredKeyScope;
+exports.retireIdentityKey = retireIdentityKey;
+exports.listRetiredIdentityKeys = listRetiredIdentityKeys;
+exports.getRetiredPrivateKey = getRetiredPrivateKey;
+exports.forgetRetiredIdentityKey = forgetRetiredIdentityKey;
+exports.forgetRetiredIdentityKeys = forgetRetiredIdentityKeys;
+exports.syncRetiredKeys = syncRetiredKeys;
+exports.retiredKeyFromPhrase = retiredKeyFromPhrase;
+const bip39_1 = require("@scure/bip39");
+const english_js_1 = require("@scure/bip39/wordlists/english.js");
+const protocol_1 = require("@oxy.so/protocol");
+const secp256k1_1 = require("@oxy.so/protocol/secp256k1");
+const logger_1 = require("../logger");
+const keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
+const platform_1 = require("../utils/platform");
+const identitySigner_1 = require("./identitySigner");
+const keychainGroupMigration_1 = require("./keychainGroupMigration");
+const organizationKeys_1 = require("./organizationKeys");
+const PERSONAL_SCOPE = 'personal';
+/** Android, Commons-local: its own Keystore-backed slot, shared with no other key. */
+const ANDROID_KEYCHAIN_SERVICE = 'oxy_retired_identity';
+const INDEX_KEYCHAIN_SERVICE = 'oxy_retired_identity_index';
+const INDEX_STORAGE_KEY = 'oxy_retired_identity_index_v1';
+const PUBLIC_KEY = /^04[0-9a-f]{128}$/;
+/**
+ * The secure store for the ring. On iOS every item is a `spending-key`
+ * (ADR 0062): the private keys AND the index live in the wallet group, which
+ * only Commons and the Peable wallet can read, never the shared one. In
+ * Commons every access first awaits the access-group migration. On Android
+ * the grouping is a no-op and Commons' own services below apply.
+ */
+async function ringStore() {
+    const raw = await (0, protocol_1.loadSecureStore)();
+    const access = await (0, keychainAccessGroups_1.resolveKeychainAccess)();
+    if (access.mode === 'grouped' && access.role === 'holder') {
+        await (0, keychainGroupMigration_1.ensureKeychainGroupsMigrated)();
+    }
+    return (0, keychainAccessGroups_1.groupedKeychainStore)(raw, access, 'spending-key');
+}
+/** The ring a selector names: `personal`, or the organization's account id. */
+function retiredKeyScope(selector) {
+    const accountId = selector?.accountId;
+    if (accountId === undefined)
+        return PERSONAL_SCOPE;
+    return (0, organizationKeys_1.isOrganizationAccountId)(accountId) ? accountId : null;
+}
+function canonicalPublicKey(publicKey) {
+    try {
+        const normalized = (0, secp256k1_1.normalizeSecp256k1PublicKey)(publicKey.trim());
+        return PUBLIC_KEY.test(normalized) ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}
+function publicKeyOf(privateKey) {
+    return (0, secp256k1_1.deriveSecp256k1PublicKey)((0, secp256k1_1.normalizeSecp256k1PrivateKey)(privateKey));
+}
+function isHealthyPair(privateKey, publicKey) {
+    if (!(0, secp256k1_1.isValidSecp256k1PrivateKey)(privateKey) || !(0, secp256k1_1.isValidSecp256k1PublicKey)(publicKey)) {
+        return false;
+    }
+    try {
+        return publicKeyOf(privateKey) === (0, secp256k1_1.normalizeSecp256k1PublicKey)(publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+const privateKeyName = (scope, publicKey) => `oxy_retired_identity_private_key.${scope}.${publicKey}`;
+/** The options of a private half: on iOS none but accessibility (the group comes from {@link ringStore}). */
+function privateOptions(store, forWrite) {
+    if ((0, platform_1.isIOS)()) {
+        return forWrite ? { keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY } : {};
+    }
+    return forWrite
+        ? {
+            keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+            keychainService: ANDROID_KEYCHAIN_SERVICE,
+        }
+        : { keychainService: ANDROID_KEYCHAIN_SERVICE };
+}
+/** The index: public keys and dates, beside the private halves. */
+function indexOptions() {
+    return (0, platform_1.isIOS)() ? {} : { keychainService: INDEX_KEYCHAIN_SERVICE };
+}
+function isIndexEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const entry = value;
+    return (typeof entry.scope === 'string' &&
+        (entry.scope === PERSONAL_SCOPE || (0, organizationKeys_1.isOrganizationAccountId)(entry.scope)) &&
+        typeof entry.publicKey === 'string' &&
+        PUBLIC_KEY.test(entry.publicKey) &&
+        typeof entry.retiredAt === 'number' &&
+        Number.isFinite(entry.retiredAt));
+}
+async function readIndex(store) {
+    const raw = await store.getItemAsync(INDEX_STORAGE_KEY, indexOptions());
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.filter(isIndexEntry) : [];
+    }
+    catch (error) {
+        logger_1.logger.warn('Retired key index unreadable; treating as empty', {
+            component: 'RetiredKeys',
+            error: error instanceof Error ? error.name : 'unknown',
+        });
+        return [];
+    }
+}
+async function writeIndex(store, entries) {
+    const unique = new Map();
+    for (const entry of entries) {
+        const id = `${entry.scope}.${entry.publicKey}`;
+        if (!unique.has(id))
+            unique.set(id, entry);
+    }
+    const sorted = [...unique.values()].sort((a, b) => a.retiredAt - b.retiredAt || a.publicKey.localeCompare(b.publicKey));
+    await store.setItemAsync(INDEX_STORAGE_KEY, JSON.stringify(sorted), indexOptions());
+}
+function toListed(entry) {
+    return entry.scope === PERSONAL_SCOPE
+        ? { publicKey: entry.publicKey, retiredAt: entry.retiredAt }
+        : { publicKey: entry.publicKey, accountId: entry.scope, retiredAt: entry.retiredAt };
+}
+/** Whether this app writes the ring: Commons (Android: the signer store it registers; iOS: native). */
+function assertMayWrite() {
+    if ((0, platform_1.isWeb)())
+        throw new Error('retired key: only a native device holds one');
+    if ((0, platform_1.isAndroid)() && !(0, identitySigner_1.registeredIdentitySignerStore)()?.writeRetired) {
+        throw new Error('On Android only Commons holds retired keys; this app has no identity signer store for them.');
+    }
+}
+/**
+ * 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.
+ */
+async function retireIdentityKey(key, selector) {
+    const scope = retiredKeyScope(selector);
+    if (!scope)
+        throw new Error('retired key: accountId must be a 24-hex or uuid account id');
+    assertMayWrite();
+    if (!isHealthyPair(key.privateKey, key.publicKey)) {
+        throw new Error('retired key: the public key does not derive from the private key');
+    }
+    const privateKey = (0, secp256k1_1.normalizeSecp256k1PrivateKey)(key.privateKey);
+    const publicKey = (0, secp256k1_1.normalizeSecp256k1PublicKey)(key.publicKey);
+    const store = await ringStore();
+    await store.setItemAsync(privateKeyName(scope, publicKey), privateKey, privateOptions(store, true));
+    const readBack = await store.getItemAsync(privateKeyName(scope, publicKey), privateOptions(store, false));
+    if (readBack !== privateKey) {
+        throw new Error('retired key: the keychain did not confirm the key');
+    }
+    const signer = (0, platform_1.isAndroid)() ? (0, identitySigner_1.registeredIdentitySignerStore)() : null;
+    if (signer?.writeRetired && !(await signer.writeRetired(scope, privateKey, publicKey))) {
+        throw new Error(`The identity signer store (${signer.name}) did not confirm the retired key.`);
+    }
+    const index = await readIndex(store);
+    if (!index.some((entry) => entry.scope === scope && entry.publicKey === publicKey)) {
+        await writeIndex(store, [...index, { scope, publicKey, retiredAt: Date.now() }]);
+    }
+}
+/**
+ * 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.
+ */
+async function listRetiredIdentityKeys(selector) {
+    const scope = retiredKeyScope(selector);
+    if (!scope || (0, platform_1.isWeb)())
+        return [];
+    try {
+        if ((0, platform_1.isAndroid)() && !(0, identitySigner_1.registeredIdentitySignerStore)()) {
+            const bridge = await (0, protocol_1.loadCommonsIdentityBridge)();
+            const keys = (await bridge?.listRetiredKeys?.(selector?.accountId)) ?? null;
+            return (keys ?? []).map((publicKey) => scope === PERSONAL_SCOPE
+                ? { publicKey, retiredAt: 0 }
+                : { publicKey, accountId: scope, retiredAt: 0 });
+        }
+        if (!(0, platform_1.isIOS)() && !(0, platform_1.isAndroid)())
+            return [];
+        const store = await ringStore();
+        return (await readIndex(store)).filter((entry) => entry.scope === scope).map(toListed);
+    }
+    catch (error) {
+        logger_1.logger.warn('Failed to list retired keys', {
+            component: 'RetiredKeys',
+            error: error instanceof Error ? error.name : 'unknown',
+        });
+        return [];
+    }
+}
+/**
+ * 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.
+ */
+async function getRetiredPrivateKey(publicKey, selector) {
+    const scope = retiredKeyScope(selector);
+    const canonical = canonicalPublicKey(publicKey);
+    if (!scope || !canonical || (0, platform_1.isWeb)())
+        return null;
+    try {
+        if ((0, platform_1.isAndroid)()) {
+            const signer = (0, identitySigner_1.registeredIdentitySignerStore)();
+            if (!signer)
+                return null;
+            const store = await ringStore();
+            const local = await store.getItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
+            if (local && isHealthyPair(local, canonical))
+                return (0, secp256k1_1.normalizeSecp256k1PrivateKey)(local);
+            // The signer store is a rung: a wiped expo-secure-store slot still has it.
+            const mirrored = (await signer.readRetired?.(scope, canonical)) ?? null;
+            return mirrored && isHealthyPair(mirrored.privateKey, canonical)
+                ? (0, secp256k1_1.normalizeSecp256k1PrivateKey)(mirrored.privateKey)
+                : null;
+        }
+        if (!(0, platform_1.isIOS)())
+            return null;
+        const store = await ringStore();
+        const value = await store.getItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
+        return value && isHealthyPair(value, canonical) ? (0, secp256k1_1.normalizeSecp256k1PrivateKey)(value) : null;
+    }
+    catch (error) {
+        logger_1.logger.warn('Failed to read a retired key', {
+            component: 'RetiredKeys',
+            error: error instanceof Error ? error.name : 'unknown',
+        });
+        return 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).
+ */
+async function forgetRetiredIdentityKey(publicKey, selector) {
+    const scope = retiredKeyScope(selector);
+    const canonical = canonicalPublicKey(publicKey);
+    if (!scope || !canonical)
+        throw new Error('retired key: invalid selector or public key');
+    assertMayWrite();
+    const store = await ringStore();
+    await store.deleteItemAsync(privateKeyName(scope, canonical), privateOptions(store, false));
+    const signer = (0, platform_1.isAndroid)() ? (0, identitySigner_1.registeredIdentitySignerStore)() : null;
+    await signer?.clearRetired?.(scope, canonical);
+    await writeIndex(store, (await readIndex(store)).filter((entry) => !(entry.scope === scope && entry.publicKey === canonical)));
+}
+/**
+ * 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.
+ */
+async function forgetRetiredIdentityKeys(selector) {
+    const scope = retiredKeyScope(selector);
+    if (!scope || (0, platform_1.isWeb)())
+        return 0;
+    if ((0, platform_1.isAndroid)() && !(0, identitySigner_1.registeredIdentitySignerStore)())
+        return 0;
+    const store = await ringStore();
+    const index = await readIndex(store);
+    const signer = (0, platform_1.isAndroid)() ? (0, identitySigner_1.registeredIdentitySignerStore)() : null;
+    let removed = 0;
+    for (const entry of index) {
+        if (entry.scope !== scope)
+            continue;
+        await store.deleteItemAsync(privateKeyName(scope, entry.publicKey), privateOptions(store, false));
+        await signer?.clearRetired?.(scope, entry.publicKey);
+        removed += 1;
+    }
+    await writeIndex(store, index.filter((entry) => entry.scope !== scope));
+    return removed;
+}
+/**
+ * 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.
+ */
+async function syncRetiredKeys() {
+    const signer = (0, platform_1.isAndroid)() ? (0, identitySigner_1.registeredIdentitySignerStore)() : null;
+    if (!signer?.writeRetired || !signer.readRetired)
+        return 0;
+    const store = await ringStore();
+    let mirrored = 0;
+    for (const entry of await readIndex(store)) {
+        const privateKey = await store.getItemAsync(privateKeyName(entry.scope, entry.publicKey), privateOptions(store, false));
+        if (!privateKey || !isHealthyPair(privateKey, entry.publicKey))
+            continue;
+        const current = await signer.readRetired(entry.scope, entry.publicKey);
+        if (current?.publicKey.toLowerCase() === entry.publicKey)
+            continue;
+        if (await signer.writeRetired(entry.scope, (0, secp256k1_1.normalizeSecp256k1PrivateKey)(privateKey), entry.publicKey)) {
+            mirrored += 1;
+        }
+    }
+    return mirrored;
+}
+/**
+ * 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}.
+ */
+async function retiredKeyFromPhrase(phrase) {
+    const normalized = phrase.trim().toLowerCase().split(/\s+/).join(' ');
+    const words = normalized.split(' ').length;
+    if (words < 12 || words > 24 || words % 3 !== 0 || !(0, bip39_1.validateMnemonic)(normalized, english_js_1.wordlist)) {
+        throw new Error('retired key: not a valid recovery phrase');
+    }
+    const seed = await (0, bip39_1.mnemonicToSeed)(normalized);
+    const privateKey = Array.from(seed.subarray(0, 32), (b) => b.toString(16).padStart(2, '0')).join('');
+    return { privateKey, publicKey: publicKeyOf(privateKey) };
+}

package/dist/cjs/crypto/secureStoreOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/session/index.js

@@ -8,7 +8,8 @@
  * the API with a token it already has never needs it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runColdBoot = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.readLocalDeviceCredential = exports.publishProvenDeviceCredential = exports.normalizeSharedDeviceSessionRead = exports.decideSharedDevicePublish = exports.decideSharedDeviceJoin = exports.createSharedMirroringAuthStateStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.resolveAccountDelegationAccess = exports.canSwitchIntoAccount = exports.isSwitchTargetAccount = exports.deviceComparisonCode = exports.showsPrincipalHeaders = exports.buildSwitcherRows = exports.resolveDeviceContext = exports.resolveActiveContext = exports.projectDevicePrincipals = exports.directoryHandle = exports.directoryDisplayName = exports.canActivateContext = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.DeviceManager = void 0;
+exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.resolveKeychainAccess = exports.deleteThroughPlan = exports.readThroughPlan = exports.ownKeychainItemPlan = exports.keychainAccessGroupValue = exports.KeychainAccessUnavailableError = exports.readLocalDeviceCredential = exports.publishProvenDeviceCredential = exports.normalizeSharedDeviceSessionRead = exports.decideSharedDevicePublish = exports.decideSharedDeviceJoin = exports.createSharedMirroringAuthStateStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.resolveAccountDelegationAccess = exports.canSwitchIntoAccount = exports.isSwitchTargetAccount = exports.deviceComparisonCode = exports.showsPrincipalHeaders = exports.buildSwitcherRows = exports.resolveDeviceContext = exports.resolveActiveContext = exports.projectDevicePrincipals = exports.directoryHandle = exports.directoryDisplayName = exports.canActivateContext = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.DeviceManager = void 0;
+exports.runColdBoot = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = void 0;
 // Session code reaches the identity key (identity-bound sessions), so the
 // crypto shim goes first — see `../crypto/polyfill`.
 require("../crypto/polyfill");
@@ -107,6 +108,15 @@ Object.defineProperty(exports, "decideSharedDevicePublish", { enumerable: true,
 Object.defineProperty(exports, "normalizeSharedDeviceSessionRead", { enumerable: true, get: function () { return sharedDeviceCredential_1.normalizeSharedDeviceSessionRead; } });
 Object.defineProperty(exports, "publishProvenDeviceCredential", { enumerable: true, get: function () { return sharedDeviceCredential_1.publishProvenDeviceCredential; } });
 Object.defineProperty(exports, "readLocalDeviceCredential", { enumerable: true, get: function () { return sharedDeviceCredential_1.readLocalDeviceCredential; } });
+// Where the shared device credential (and an app's own items) live on iOS:
+// docs/identity/ios-keychain-access-groups.md, ADR 0062.
+var keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
+Object.defineProperty(exports, "KeychainAccessUnavailableError", { enumerable: true, get: function () { return keychainAccessGroups_1.KeychainAccessUnavailableError; } });
+Object.defineProperty(exports, "keychainAccessGroupValue", { enumerable: true, get: function () { return keychainAccessGroups_1.keychainAccessGroupValue; } });
+Object.defineProperty(exports, "ownKeychainItemPlan", { enumerable: true, get: function () { return keychainAccessGroups_1.ownKeychainItemPlan; } });
+Object.defineProperty(exports, "readThroughPlan", { enumerable: true, get: function () { return keychainAccessGroups_1.readThroughPlan; } });
+Object.defineProperty(exports, "deleteThroughPlan", { enumerable: true, get: function () { return keychainAccessGroups_1.deleteThroughPlan; } });
+Object.defineProperty(exports, "resolveKeychainAccess", { enumerable: true, get: function () { return keychainAccessGroups_1.resolveKeychainAccess; } });
 // Identity-bound sessions (the identity vault). The pin is the durable
 // `{publicKey, accountId}` binding between this device's PRIMARY identity key
 // and the account it authenticates as; it is what keeps such a client from

package/dist/cjs/utils/keychainAccessGroups.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeychainAccessUnavailableError = exports.KEYCHAIN_ACCESS_GROUPS = void 0;
+exports.keychainGroupFor = keychainGroupFor;
+exports.mayHoldKeychainItem = mayHoldKeychainItem;
+exports.keychainAccessFromDefaultGroup = keychainAccessFromDefaultGroup;
+exports.resolveKeychainAccess = resolveKeychainAccess;
+exports.resetKeychainAccessForTests = resetKeychainAccessForTests;
+exports.keychainAccessGroupValue = keychainAccessGroupValue;
+exports.keychainReadPlan = keychainReadPlan;
+exports.keychainDeletePlan = keychainDeletePlan;
+exports.keychainWriteOption = keychainWriteOption;
+exports.ownKeychainItemPlan = ownKeychainItemPlan;
+exports.readThroughPlan = readThroughPlan;
+exports.deleteThroughPlan = deleteThroughPlan;
+exports.groupedKeychainStore = groupedKeychainStore;
+/**
+ * iOS keychain access groups: which group each Oxy keychain item lives in, and
+ * which apps may read it (docs/identity/ios-keychain-access-groups.md, ADR 0062).
+ *
+ * | Group                         | Held by                      | Item class        |
+ * |-------------------------------|------------------------------|-------------------|
+ * | `<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`          |
+ *
+ * - `identity-secret`: the personal root (primary and backup slots), the
+ *   personal and organization recovery phrases, the organization index. Only
+ *   Commons may read or write them.
+ * - `spending-key`: private keys an app other than Commons signs or derives
+ *   with in process — the personal key's shared slot and organization pairs
+ *   (`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.
+ *
+ * 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.
+ *
+ * Android and web have no access groups: there every helper here answers the
+ * single-store behaviour (`ungrouped`), and Android's narrowing is Commons'
+ * identity host. An iOS build whose native module predates the probe is also
+ * `ungrouped` — exactly what that build's entitlements (one shared group) do.
+ *
+ * This module never imports the identity stack: services' device-session store
+ * and Peable's wallet storage use it too.
+ */
+const protocol_1 = require("@oxy.so/protocol");
+const platform_1 = require("./platform");
+/** The group names after the team prefix, exactly as the entitlements list them. */
+exports.KEYCHAIN_ACCESS_GROUPS = {
+    identity: 'so.oxy.identity',
+    wallet: 'so.oxy.wallet',
+    shared: 'group.so.oxy.shared',
+};
+/** Thrown while the probe cannot answer (before first unlock). Transient. */
+class KeychainAccessUnavailableError extends Error {
+    constructor(cause) {
+        super('The keychain cannot say which access groups this app holds right now.');
+        this.cause = cause;
+        this.name = 'KeychainAccessUnavailableError';
+    }
+}
+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':
+            return 'identity';
+        case 'spending-key':
+            return 'wallet';
+        case 'shared':
+            return 'shared';
+    }
+}
+/** Whether `role` holds the group `item` lives in. */
+function mayHoldKeychainItem(role, item) {
+    switch (role) {
+        case 'holder':
+            return true;
+        case 'wallet':
+            return item !== 'identity-secret';
+        case 'member':
+            return item === 'shared';
+    }
+}
+/** Parse the default access group the probe reported. Exported for tests. */
+function keychainAccessFromDefaultGroup(defaultGroup) {
+    const dot = defaultGroup.indexOf('.');
+    if (dot <= 0 || dot === defaultGroup.length - 1) {
+        // Not `<prefix>.<group>`: an unsigned simulator build. Nothing to split.
+        return { mode: 'ungrouped' };
+    }
+    const prefix = defaultGroup.slice(0, dot + 1);
+    const group = defaultGroup.slice(dot + 1);
+    const role = group === exports.KEYCHAIN_ACCESS_GROUPS.identity
+        ? 'holder'
+        : group === exports.KEYCHAIN_ACCESS_GROUPS.wallet
+            ? 'wallet'
+            : 'member';
+    return { mode: 'grouped', prefix, defaultGroup, role };
+}
+let resolvedAccess = null;
+/**
+ * This binary's keychain access, memoized once known. THROWS
+ * {@link KeychainAccessUnavailableError} while the probe cannot answer, which
+ * every caller already treats as "storage unavailable, retry".
+ */
+async function resolveKeychainAccess() {
+    if (resolvedAccess) {
+        return resolvedAccess;
+    }
+    if (!(0, platform_1.isIOS)()) {
+        // Not memoized: until `@oxy.so/services` registers the platform, a phone
+        // reads as "not iOS", and caching that would keep the whole process on the
+        // pre-split behaviour.
+        return { mode: 'ungrouped' };
+    }
+    let probe;
+    try {
+        probe = await (0, protocol_1.loadKeychainDefaultAccessGroup)();
+    }
+    catch (cause) {
+        throw new KeychainAccessUnavailableError(cause);
+    }
+    if (probe.state === 'unavailable') {
+        throw new KeychainAccessUnavailableError(probe.cause);
+    }
+    resolvedAccess =
+        probe.state === 'resolved'
+            ? keychainAccessFromDefaultGroup(probe.accessGroup)
+            : { mode: 'ungrouped' };
+    return resolvedAccess;
+}
+/** Forget the memoized access. Tests only. @internal */
+function resetKeychainAccessForTests() {
+    resolvedAccess = null;
+}
+/** The full `kSecAttrAccessGroup` value of `group`, or `undefined` when ungrouped. */
+function keychainAccessGroupValue(access, group) {
+    return access.mode === 'grouped' ? `${access.prefix}${exports.KEYCHAIN_ACCESS_GROUPS[group]}` : undefined;
+}
+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.
+ */
+function 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 !== 'shared') {
+        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.
+ */
+function keychainDeletePlan(access, item) {
+    return keychainReadPlan(access, item);
+}
+/**
+ * The option a WRITE of `item` carries. THROWS when this app may not hold the
+ * item: an identity secret written by any app but Commons would land in that
+ * app's default group, a second holder nobody knows about.
+ */
+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.`);
+    }
+    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.
+ *
+ * Every other app (`member`) and Android/web keep the calls they always made.
+ */
+function ownKeychainItemPlan(access) {
+    if (access.mode === 'ungrouped' || access.role === 'member') {
+        return { read: [{}], write: {}, delete: [{}] };
+    }
+    return {
+        read: [option(access.defaultGroup), {}],
+        write: option(access.defaultGroup),
+        delete: [{}],
+    };
+}
+/** Read `key` through `plan`: the first non-null answer. A thrown read propagates. */
+async function readThroughPlan(store, key, options, plan) {
+    for (const group of plan) {
+        const value = await store.getItemAsync(key, { ...options, ...group });
+        if (value !== null && value !== undefined) {
+            return value;
+        }
+    }
+    return null;
+}
+/** Delete `key` from every location in `plan`. A thrown delete propagates. */
+async function deleteThroughPlan(store, key, options, plan) {
+    for (const group of plan) {
+        await store.deleteItemAsync(key, { ...options, ...group });
+    }
+}
+/**
+ * `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.
+ */
+function groupedKeychainStore(store, access, item) {
+    const plan = keychainReadPlan(access, item);
+    const wrapped = {
+        getItemAsync: (key, options) => readThroughPlan(store, key, options ?? {}, plan),
+        setItemAsync: async (key, value, options) => {
+            const group = keychainWriteOption(access, item);
+            await store.setItemAsync(key, value, { ...(options ?? {}), ...group });
+        },
+        deleteItemAsync: (key, options) => deleteThroughPlan(store, key, options ?? {}, plan),
+    };
+    return Object.assign(Object.create(store), wrapped);
+}