@oxy.so/core 7.28.0 → 7.29.0

package/dist/cjs/crypto/keychainGroupMigration.js

@@ -0,0 +1,353 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runKeychainGroupMigration = runKeychainGroupMigration;
+exports.ensureKeychainGroupsMigrated = ensureKeychainGroupsMigrated;
+exports.resetKeychainGroupMigrationForTests = resetKeychainGroupMigrationForTests;
+/**
+ * Commons, iOS: move every identity item out of the shared keychain group
+ * into the group it belongs to (docs/identity/ios-keychain-access-groups.md
+ * "Migrating existing items", ADR 0062).
+ *
+ * Before the split Commons listed one access group, the shared one, so every
+ * item it wrote landed there — the root key, both phrases, organization keys.
+ * Each item is moved by VERIFY-BEFORE-DELETE:
+ *
+ *   1. read it from the shared group (an explicit `accessGroup`);
+ *   2. write it to its new group;
+ *   3. read it back from there and check it: a pair must be healthy (the
+ *      public key derives from the private one), any value byte-identical;
+ *   4. only then delete it from the shared group.
+ *
+ * INVARIANT: at every instant each item has at least one readable copy, and a
+ * copy is never overwritten with a different value. A failure at any step
+ * leaves the shared copy where it is; the next run (the next accessor call
+ * for a thrown read, the next launch otherwise) resumes from whatever state
+ * the last one reached:
+ *
+ * - shared only            → copy, verify, delete;
+ * - shared and new, equal  → (a crash after the copy) verify, delete;
+ * - new only               → done;
+ * - shared and new DIFFER  → `conflict`: both stay. The new group was written
+ *   after the split, so it is current, but the shared copy may be a replaced
+ *   key that still receives money, and no step here may destroy one.
+ * - a pair that is not healthy → `unhealthy`: left in place, never moved.
+ *
+ * Every read the rest of the SDK makes goes through `keychainReadPlan` (its
+ * group, then the shared group), so it finds an item wherever this run left it.
+ * `ensureKeychainGroupsMigrated` is awaited by every KeyManager and
+ * organization-key storage access in Commons, so no write of theirs can
+ * interleave with a copy here (a copy racing a rotation could otherwise put
+ * the replaced key back).
+ *
+ * Nothing is logged but item labels and outcomes; never a value.
+ */
+const secp256k1_1 = require("@oxy.so/protocol/secp256k1");
+const protocol_1 = require("@oxy.so/protocol");
+const logger_1 = require("../logger");
+const keychainAccessGroups_1 = require("../utils/keychainAccessGroups");
+const keychainItems_1 = require("./keychainItems");
+const slot = (key, item, service, deviceOnly = true) => ({
+    key,
+    service,
+    group: (0, keychainAccessGroups_1.keychainGroupFor)(item),
+    deviceOnly,
+});
+function isHealthyPair(privateKey, publicKey) {
+    if (!privateKey || !publicKey)
+        return false;
+    try {
+        return ((0, secp256k1_1.deriveSecp256k1PublicKey)((0, secp256k1_1.normalizeSecp256k1PrivateKey)(privateKey)) ===
+            (0, secp256k1_1.normalizeSecp256k1PublicKey)(publicKey));
+    }
+    catch {
+        return false;
+    }
+}
+class Deferred extends Error {
+}
+class Mover {
+    constructor(store, access) {
+        this.store = store;
+        this.access = access;
+    }
+    options(s, group, write = false) {
+        return {
+            ...(s.service ? { keychainService: s.service } : {}),
+            accessGroup: (0, keychainAccessGroups_1.keychainAccessGroupValue)(this.access, group),
+            ...(write && s.deviceOnly
+                ? { keychainAccessible: this.store.WHEN_UNLOCKED_THIS_DEVICE_ONLY }
+                : {}),
+        };
+    }
+    /** A read that throws means the keychain is unavailable: the whole run defers. */
+    async read(s, group) {
+        try {
+            return (await this.store.getItemAsync(s.key, this.options(s, group))) ?? null;
+        }
+        catch (error) {
+            throw new Deferred(error instanceof Error ? error.message : 'keychain read threw');
+        }
+    }
+    /**
+     * Write `value` where the new group had nothing, then read it back; `true`
+     * only when the new group holds exactly `value`. A copy that reads back as
+     * something else is removed again (best effort), because reads look in the
+     * new group FIRST and must not find it there.
+     */
+    async copy(s, value, replacing = false) {
+        try {
+            await this.store.setItemAsync(s.key, value, this.options(s, s.group, true));
+            if ((await this.store.getItemAsync(s.key, this.options(s, s.group))) === value) {
+                return true;
+            }
+        }
+        catch {
+            return false;
+        }
+        if (replacing) {
+            // A merge overwrote what was there; keep whatever is there now.
+            return false;
+        }
+        try {
+            await this.store.deleteItemAsync(s.key, this.options(s, s.group));
+        }
+        catch {
+            // The next run reads it as a conflict and leaves both; the shared copy is intact.
+        }
+        return false;
+    }
+    async deleteShared(s) {
+        try {
+            await this.store.deleteItemAsync(s.key, this.options(s, 'shared'));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async moveValue(unit) {
+        const { slot: s } = unit;
+        const shared = await this.read(s, 'shared');
+        if (shared === null)
+            return 'absent';
+        const target = await this.read(s, s.group);
+        let keep = target ?? shared;
+        if (target !== null && target !== shared) {
+            const merged = unit.merge?.(shared, target) ?? null;
+            if (merged === null)
+                return 'conflict';
+            keep = merged;
+        }
+        if (target !== keep && !(await this.copy(s, keep, target !== null)))
+            return 'failed';
+        // Verify the copy that is about to become the only one.
+        if ((await this.read(s, s.group)) !== keep)
+            return 'failed';
+        return (await this.deleteShared(s)) ? 'moved' : 'failed';
+    }
+    async movePair(unit) {
+        const halves = [unit.privateSlot, unit.publicSlot];
+        // A half whose group IS the shared group stays: it is read, never moved.
+        const movable = halves.filter((h) => h.group !== 'shared');
+        const shared = await Promise.all(halves.map((h) => this.read(h, 'shared')));
+        if (movable.every((h) => shared[halves.indexOf(h)] === null))
+            return 'absent';
+        const target = await Promise.all(halves.map((h, i) => (h.group === 'shared' ? shared[i] : this.read(h, h.group))));
+        for (const h of movable) {
+            const i = halves.indexOf(h);
+            if (shared[i] !== null && target[i] !== null && shared[i] !== target[i])
+                return 'conflict';
+        }
+        const finalPair = halves.map((_, i) => target[i] ?? shared[i]);
+        if (!isHealthyPair(finalPair[0], finalPair[1]))
+            return 'unhealthy';
+        for (const h of movable) {
+            const i = halves.indexOf(h);
+            const value = shared[i];
+            if (value !== null && target[i] === null && !(await this.copy(h, value)))
+                return 'failed';
+        }
+        const readBack = await Promise.all(halves.map((h, i) => (h.group === 'shared' ? shared[i] : this.read(h, h.group))));
+        if (readBack.some((v, i) => v !== finalPair[i]) || !isHealthyPair(readBack[0], readBack[1])) {
+            return 'failed';
+        }
+        for (const h of movable) {
+            if (shared[halves.indexOf(h)] !== null && !(await this.deleteShared(h)))
+                return 'failed';
+        }
+        return 'moved';
+    }
+    move(unit) {
+        return unit.kind === 'pair' ? this.movePair(unit) : this.moveValue(unit);
+    }
+}
+/** The personal items, in the order they move. */
+function personalUnits() {
+    const v2 = (key, service, deviceOnly) => slot(key, 'identity-secret', service, deviceOnly);
+    const legacy = (key, deviceOnly) => slot(key, 'identity-secret', undefined, deviceOnly);
+    return [
+        {
+            label: 'primary',
+            kind: 'pair',
+            privateSlot: v2(keychainItems_1.V2_STORAGE_KEYS.PRIVATE_KEY, keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE, true),
+            publicSlot: v2(keychainItems_1.V2_STORAGE_KEYS.PUBLIC_KEY, keychainItems_1.V2_PRIMARY_KEYCHAIN_SERVICE, false),
+        },
+        {
+            label: 'backup',
+            kind: 'pair',
+            privateSlot: v2(keychainItems_1.V2_STORAGE_KEYS.BACKUP_PRIVATE_KEY, keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE, true),
+            publicSlot: v2(keychainItems_1.V2_STORAGE_KEYS.BACKUP_PUBLIC_KEY, keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE, false),
+        },
+        {
+            label: 'backup-timestamp',
+            kind: 'value',
+            slot: v2(keychainItems_1.V2_STORAGE_KEYS.BACKUP_TIMESTAMP, keychainItems_1.V2_BACKUP_KEYCHAIN_SERVICE, false),
+        },
+        {
+            label: 'legacy-primary',
+            kind: 'pair',
+            privateSlot: legacy(keychainItems_1.STORAGE_KEYS.PRIVATE_KEY, true),
+            publicSlot: legacy(keychainItems_1.STORAGE_KEYS.PUBLIC_KEY, false),
+        },
+        {
+            label: 'legacy-backup',
+            kind: 'pair',
+            privateSlot: legacy(keychainItems_1.STORAGE_KEYS.BACKUP_PRIVATE_KEY, true),
+            publicSlot: legacy(keychainItems_1.STORAGE_KEYS.BACKUP_PUBLIC_KEY, false),
+        },
+        {
+            label: 'legacy-backup-timestamp',
+            kind: 'value',
+            slot: legacy(keychainItems_1.STORAGE_KEYS.BACKUP_TIMESTAMP, false),
+        },
+        {
+            label: 'phrase',
+            kind: 'value',
+            slot: slot(keychainItems_1.RECOVERY_MNEMONIC_STORAGE_KEY, 'identity-secret', keychainItems_1.RECOVERY_MNEMONIC_KEYCHAIN_SERVICE),
+        },
+        {
+            // The private key moves to the wallet group; its public key stays shared.
+            label: 'shared-slot',
+            kind: 'pair',
+            privateSlot: slot(keychainItems_1.STORAGE_KEYS.SHARED_PRIVATE_KEY, 'spending-key'),
+            publicSlot: slot(keychainItems_1.STORAGE_KEYS.SHARED_PUBLIC_KEY, 'shared', undefined, false),
+        },
+    ];
+}
+const INDEX_SLOT = slot(keychainItems_1.ORGANIZATION_INDEX_STORAGE_KEY, 'identity-secret', keychainItems_1.ORGANIZATION_INDEX_KEYCHAIN_SERVICE, false);
+/** Union of two indexes; never drops an id either side lists. */
+function mergeIndexes(shared, target) {
+    return (0, keychainItems_1.serializeOrganizationIndex)([
+        ...(0, keychainItems_1.parseOrganizationIndex)(shared),
+        ...(0, keychainItems_1.parseOrganizationIndex)(target),
+    ]);
+}
+/** Run the migration once. Exported for tests; production code awaits the gate. */
+async function runKeychainGroupMigration() {
+    let access;
+    try {
+        access = await (0, keychainAccessGroups_1.resolveKeychainAccess)();
+    }
+    catch {
+        return { state: 'deferred', items: {} };
+    }
+    if (access.mode !== 'grouped' || access.role !== 'holder') {
+        return { state: 'not-applicable', items: {} };
+    }
+    let store;
+    try {
+        store = await (0, protocol_1.loadSecureStore)();
+    }
+    catch {
+        return { state: 'deferred', items: {} };
+    }
+    const mover = new Mover(store, access);
+    const items = {};
+    try {
+        for (const unit of personalUnits()) {
+            items[unit.label] = await mover.move(unit);
+        }
+        // Organizations: every id either copy of the index names.
+        const ids = new Set([
+            ...(0, keychainItems_1.parseOrganizationIndex)(await mover.read(INDEX_SLOT, 'shared')),
+            ...(0, keychainItems_1.parseOrganizationIndex)(await mover.read(INDEX_SLOT, INDEX_SLOT.group)),
+        ]);
+        let n = 0;
+        for (const accountId of [...ids].sort()) {
+            n += 1;
+            items[`organization-${n}`] = await mover.move({
+                label: `organization-${n}`,
+                kind: 'pair',
+                privateSlot: slot((0, keychainItems_1.organizationPrivateKeyName)(accountId), 'spending-key'),
+                publicSlot: slot((0, keychainItems_1.organizationPublicKeyName)(accountId), 'spending-key', undefined, false),
+            });
+            items[`organization-${n}-phrase`] = await mover.move({
+                label: `organization-${n}-phrase`,
+                kind: 'value',
+                slot: slot((0, keychainItems_1.organizationMnemonicName)(accountId), 'identity-secret', keychainItems_1.ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE),
+            });
+        }
+        // The index last: it is how a later run finds the organizations above.
+        items['organization-index'] = await mover.move({
+            label: 'organization-index',
+            kind: 'value',
+            slot: INDEX_SLOT,
+            merge: mergeIndexes,
+        });
+    }
+    catch (error) {
+        if (error instanceof Deferred) {
+            return { state: 'deferred', items };
+        }
+        throw error;
+    }
+    const settled = Object.values(items).every((o) => o === 'absent' || o === 'moved');
+    const report = {
+        state: settled ? 'complete' : 'incomplete',
+        items,
+    };
+    if (!settled) {
+        logger_1.logger.warn('Keychain access-group migration left items in the shared group', {
+            component: 'KeychainGroupMigration',
+            items: Object.entries(items)
+                .filter(([, o]) => o !== 'absent' && o !== 'moved')
+                .map(([label, o]) => `${label}:${o}`)
+                .join(','),
+        });
+    }
+    return report;
+}
+let settledReport = null;
+let inFlight = null;
+/**
+ * The gate every Commons identity-storage access awaits. One run per process
+ * (`complete`, `incomplete` and `not-applicable` are kept; `incomplete` is
+ * retried on the next launch); a `deferred` run is forgotten, so the next
+ * access tries again once the keychain unlocks. Concurrent callers share one
+ * run. Never throws.
+ */
+function ensureKeychainGroupsMigrated() {
+    if (settledReport) {
+        return Promise.resolve(settledReport);
+    }
+    if (!inFlight) {
+        inFlight = runKeychainGroupMigration()
+            .catch((error) => {
+            logger_1.logger.warn('Keychain access-group migration threw; retrying on the next access', { component: 'KeychainGroupMigration' }, error);
+            return { state: 'deferred', items: {} };
+        })
+            .then((report) => {
+            if (report.state !== 'deferred') {
+                settledReport = report;
+            }
+            inFlight = null;
+            return report;
+        });
+    }
+    return inFlight;
+}
+/** Forget the memoized run. Tests only. @internal */
+function resetKeychainGroupMigrationForTests() {
+    settledReport = null;
+    inFlight = null;
+}

package/dist/cjs/crypto/keychainItems.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * The names of every identity item `KeyManager` and `./organizationKeys` keep
+ * in `expo-secure-store`, in one place so the access-group migration
+ * (`./keychainGroupMigration`) moves exactly what those modules read. Values
+ * are stable on-device identifiers: renaming one strands what is stored.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.organizationMnemonicName = exports.organizationPublicKeyName = exports.organizationPrivateKeyName = exports.ORGANIZATION_INDEX_STORAGE_KEY = exports.ORGANIZATION_INDEX_KEYCHAIN_SERVICE = exports.ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE = exports.ORGANIZATION_ANDROID_KEYCHAIN_SERVICE = exports.RECOVERY_MNEMONIC_STORAGE_KEY = exports.RECOVERY_MNEMONIC_KEYCHAIN_SERVICE = exports.V2_STORAGE_KEYS = exports.V2_BACKUP_KEYCHAIN_SERVICE = exports.V2_PRIMARY_KEYCHAIN_SERVICE = exports.STORAGE_KEYS = void 0;
+exports.isOrganizationAccountId = isOrganizationAccountId;
+exports.parseOrganizationIndex = parseOrganizationIndex;
+exports.serializeOrganizationIndex = serializeOrganizationIndex;
+/** Legacy (pre-v2) and shared-slot keys; the legacy ones have no keychain service. */
+exports.STORAGE_KEYS = {
+    PRIVATE_KEY: 'oxy_identity_private_key',
+    PUBLIC_KEY: 'oxy_identity_public_key',
+    BACKUP_PRIVATE_KEY: 'oxy_identity_backup_private_key',
+    BACKUP_PUBLIC_KEY: 'oxy_identity_backup_public_key',
+    BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp',
+    // The personal key's cross-app slot: the private key in the wallet group, the
+    // public key in the shared group (iOS only), no keychain service.
+    SHARED_PRIVATE_KEY: 'oxy_shared_identity_private_key',
+    SHARED_PUBLIC_KEY: 'oxy_shared_identity_public_key',
+};
+exports.V2_PRIMARY_KEYCHAIN_SERVICE = 'oxy_identity';
+exports.V2_BACKUP_KEYCHAIN_SERVICE = 'oxy_identity_backup';
+exports.V2_STORAGE_KEYS = {
+    PRIVATE_KEY: 'oxy_identity_private_key_v2',
+    PUBLIC_KEY: 'oxy_identity_public_key_v2',
+    BACKUP_PRIVATE_KEY: 'oxy_identity_backup_private_key_v2',
+    BACKUP_PUBLIC_KEY: 'oxy_identity_backup_public_key_v2',
+    BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp_v2',
+};
+exports.RECOVERY_MNEMONIC_KEYCHAIN_SERVICE = 'oxy_identity_mnemonic';
+exports.RECOVERY_MNEMONIC_STORAGE_KEY = 'oxy_identity_mnemonic_v1';
+/** Organization keys (ADR 0061 D6). On iOS the pair has no keychain service. */
+exports.ORGANIZATION_ANDROID_KEYCHAIN_SERVICE = 'oxy_org_identity';
+exports.ORGANIZATION_MNEMONIC_KEYCHAIN_SERVICE = 'oxy_org_identity_mnemonic';
+exports.ORGANIZATION_INDEX_KEYCHAIN_SERVICE = 'oxy_org_identity_index';
+exports.ORGANIZATION_INDEX_STORAGE_KEY = 'oxy_org_identity_index_v1';
+const organizationPrivateKeyName = (accountId) => `oxy_org_identity_private_key.${accountId}`;
+exports.organizationPrivateKeyName = organizationPrivateKeyName;
+const organizationPublicKeyName = (accountId) => `oxy_org_identity_public_key.${accountId}`;
+exports.organizationPublicKeyName = organizationPublicKeyName;
+const organizationMnemonicName = (accountId) => `oxy_org_identity_mnemonic.${accountId}`;
+exports.organizationMnemonicName = organizationMnemonicName;
+/** Same set the server's account ids come from: a legacy 24-hex id or a lowercase uuid. */
+const ACCOUNT_ID = /^(?:[0-9a-f]{24}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+/** Whether `value` is an account id an organization key can be stored under. */
+function isOrganizationAccountId(value) {
+    return ACCOUNT_ID.test(value);
+}
+/** The account ids in a stored organization index; anything malformed is skipped. */
+function parseOrganizationIndex(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed)
+            ? parsed.filter((id) => typeof id === 'string' && isOrganizationAccountId(id))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The stored form of an organization index: unique, sorted. */
+function serializeOrganizationIndex(ids) {
+    return JSON.stringify([...new Set(ids)].sort());
+}