@oxy.so/core 1.10.0 → 1.11.0

package/dist/cjs/crypto/deviceBackup.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * The device backup of the self-custody identity: a copy that lives OUTSIDE this
+ * app's own keystore, so a keystore wipe cannot take it along with the keys.
+ *
+ * Why it exists (OxyHQ/oxy#1388): on Android every Oxy app shares the Linux UID
+ * `so.oxy.shared`, and the Android Keystore is per UID. Clearing the storage of
+ * ANY sibling app (`pm clear`, or Settings › Apps › Storage › Clear storage)
+ * wipes the Keystore of the whole UID. Every copy the SDK keeps in
+ * expo-secure-store (primary, backup slot, phrase slot) and in the androidx
+ * encrypted prefs (the cross-app shared slot) is wrapped by a key in that
+ * Keystore, so they all die together, and until now the only way back was the
+ * recovery phrase.
+ *
+ * `@oxy.so/core` never imports a native module, so the store is injected by the
+ * app that owns the identity ({@link KeyManager.setDeviceBackupStore}). Commons
+ * registers Android Block Store; every other app registers nothing, which keeps
+ * every code path below a no-op for them. The design and the threat model are in
+ * `docs/identity/device-backup.md`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEVICE_BACKUP_VERSION = void 0;
+exports.serializeDeviceBackup = serializeDeviceBackup;
+exports.parseDeviceBackup = parseDeviceBackup;
+/** The record format. Bump {@link DEVICE_BACKUP_VERSION} on a breaking change. */
+exports.DEVICE_BACKUP_VERSION = 1;
+function serializeDeviceBackup(record) {
+    const out = {
+        version: exports.DEVICE_BACKUP_VERSION,
+        privateKey: record.privateKey,
+        publicKey: record.publicKey,
+        updatedAt: record.updatedAt,
+    };
+    if (record.mnemonic) {
+        out.mnemonic = record.mnemonic;
+    }
+    return JSON.stringify(out);
+}
+/**
+ * Parse a stored record, or `null` for anything that is not a well-formed
+ * version-1 record. Checks SHAPE only; the caller still proves the key pair is
+ * healthy (well-formed, public derives from private) before trusting it.
+ */
+function parseDeviceBackup(raw) {
+    if (!raw) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return null;
+    }
+    const candidate = parsed;
+    if (candidate.version !== exports.DEVICE_BACKUP_VERSION ||
+        typeof candidate.privateKey !== 'string' ||
+        typeof candidate.publicKey !== 'string' ||
+        typeof candidate.updatedAt !== 'string') {
+        return null;
+    }
+    const record = {
+        version: exports.DEVICE_BACKUP_VERSION,
+        privateKey: candidate.privateKey,
+        publicKey: candidate.publicKey,
+        updatedAt: candidate.updatedAt,
+    };
+    if (typeof candidate.mnemonic === 'string' && candidate.mnemonic.length > 0) {
+        record.mnemonic = candidate.mnemonic;
+    }
+    return record;
+}

package/dist/cjs/crypto/keyManager.js

@@ -5,6 +5,39 @@
  * Handles secure generation, storage, and retrieval of cryptographic keys.
  * Private keys are stored securely using expo-secure-store and never leave the device.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyManager = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = void 0;
 const platform_1 = require("../utils/platform");
@@ -13,6 +46,7 @@ const secp256k1_1 = require("@oxy.so/protocol/secp256k1");
 const logger_1 = require("../logger");
 const kdf_1 = require("./kdf");
 const identityMarker_1 = require("./identityMarker");
+const deviceBackup_1 = require("./deviceBackup");
 /**
  * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
  * is invoked while a valid identity already exists on the device.
@@ -242,6 +276,19 @@ async function getSecureRandomBytes(length) {
     }
 }
 class KeyManager {
+    /**
+     * Register (or, with `null`, unregister) where the identity's device backup is
+     * kept. Call once at startup, before the first identity read, ONLY from the
+     * app that holds the self-custody identity: the backup is a full copy of the
+     * private key, and it belongs to exactly one app.
+     *
+     * From then on every create, import, rotation and restore refreshes the
+     * backup, a forced delete clears it, and {@link attemptIdentityRecovery}
+     * restores from it when the keystore copies are gone.
+     */
+    static setDeviceBackupStore(store) {
+        KeyManager.deviceBackupStore = store;
+    }
     /**
      * Invalidate cached identity state
      * Called internally when identity is created/deleted/imported
@@ -1230,6 +1277,138 @@ class KeyManager {
         // persist (a subsequent healthy read re-backfills it). Rollback paths above
         // return before reaching here, so they never touch the marker.
         await KeyManager._syncMarkerAfterPersist(canonicalPublic, origin);
+        // Mirror the durable identity into the keystore-independent device backup,
+        // so a wipe of this UID's keystore can be undone without the phrase. Every
+        // identity change (create, import, rotation, restore) flows through here.
+        // Best-effort like the marker: `ensureDeviceBackup` retries on next launch.
+        await KeyManager._writeDeviceBackup(canonicalPrivate, canonicalPublic);
+    }
+    /**
+     * Write the device backup for `(privateKey, publicKey)`, keeping the phrase an
+     * existing record already carries for the SAME identity. `mnemonic` replaces
+     * it, and must already be verified against `publicKey` by the caller.
+     * Best-effort: never throws, returns whether the store now holds this pair.
+     *
+     * @internal
+     */
+    static async _writeDeviceBackup(privateKey, publicKey, mnemonic) {
+        const store = KeyManager.deviceBackupStore;
+        if (!store) {
+            return false;
+        }
+        try {
+            let existing = null;
+            try {
+                existing = (0, deviceBackup_1.parseDeviceBackup)(await store.read());
+            }
+            catch {
+                existing = null;
+            }
+            const sameIdentity = existing?.publicKey === publicKey;
+            const keptMnemonic = mnemonic ?? (sameIdentity ? existing?.mnemonic : undefined);
+            if (sameIdentity && existing?.privateKey === privateKey && existing?.mnemonic === keptMnemonic) {
+                return true; // Already current; do not churn the store.
+            }
+            await store.write((0, deviceBackup_1.serializeDeviceBackup)({
+                version: deviceBackup_1.DEVICE_BACKUP_VERSION,
+                privateKey,
+                publicKey,
+                mnemonic: keptMnemonic,
+                updatedAt: new Date().toISOString(),
+            }));
+            return true;
+        }
+        catch (error) {
+            logger_1.logger.warn(`Failed to write the identity device backup (${store.name}); retried on next launch`, { component: 'KeyManager' }, error);
+            return false;
+        }
+    }
+    /** Remove the device backup. Best-effort: never throws. @internal */
+    static async _clearDeviceBackup() {
+        const store = KeyManager.deviceBackupStore;
+        if (!store) {
+            return;
+        }
+        try {
+            await store.clear();
+        }
+        catch (error) {
+            logger_1.logger.warn(`Failed to clear the identity device backup (${store.name})`, { component: 'KeyManager' }, error);
+        }
+    }
+    /** True when `phrase` is a valid BIP-39 phrase that derives `publicKey`. @internal */
+    static async _phraseDerivesPublicKey(phrase, publicKey) {
+        try {
+            // Imported lazily: `./recoveryPhrase` imports this module, and the phrase
+            // derivation is frozen there, so it is reused rather than copied.
+            const { RecoveryPhraseService } = await Promise.resolve().then(() => __importStar(require('./recoveryPhrase')));
+            const derived = await RecoveryPhraseService.derivePublicKeyFromPhrase(phrase);
+            return derived.toLowerCase() === publicKey.toLowerCase();
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The primary pair when it reads back healthy, else `null`. Never throws. @internal */
+    static async _readHealthyPrimary() {
+        try {
+            const direct = await KeyManager._readPrimaryDirect();
+            if (KeyManager._isHealthyPair(direct.privateKey, direct.publicKey) && direct.privateKey && direct.publicKey) {
+                return {
+                    privateKey: KeyManager.canonicalPrivateKey(direct.privateKey),
+                    publicKey: direct.publicKey.toLowerCase(),
+                };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Make sure the device backup holds the identity on this device, writing it
+     * when it is missing or stale. Commons calls this once per launch once the
+     * identity reads back healthy: it backfills identities created before the
+     * device backup existed, and repairs a backup whose last write failed (a
+     * failed write after a key rotation would otherwise leave the OLD key there).
+     *
+     * Carries the stored recovery phrase along only when it provably derives the
+     * current key. Resolves `true` when the backup is current, `false` when there
+     * is no store, no healthy identity, or the write failed. Never throws.
+     */
+    static async ensureDeviceBackup() {
+        if (isWebPlatform() || !KeyManager.deviceBackupStore) {
+            return false;
+        }
+        const primary = await KeyManager._readHealthyPrimary();
+        if (!primary) {
+            return false;
+        }
+        let existing = null;
+        try {
+            existing = (0, deviceBackup_1.parseDeviceBackup)(await KeyManager.deviceBackupStore.read());
+        }
+        catch {
+            existing = null;
+        }
+        const pairCurrent = existing?.publicKey === primary.publicKey && existing?.privateKey === primary.privateKey;
+        if (pairCurrent && existing?.mnemonic) {
+            return true; // The common launch: one read, no write, no phrase derivation.
+        }
+        let mnemonic;
+        try {
+            const stored = await KeyManager.getRecoveryMnemonic();
+            if (stored && (await KeyManager._phraseDerivesPublicKey(stored, primary.publicKey))) {
+                mnemonic = stored;
+            }
+        }
+        catch {
+            mnemonic = undefined;
+        }
+        if (pairCurrent && !mnemonic) {
+            return true;
+        }
+        return KeyManager._writeDeviceBackup(primary.privateKey, primary.publicKey, mnemonic);
     }
     /**
      * Write/refresh the identity marker after a successful persist. A same-identity
@@ -1548,6 +1727,15 @@ class KeyManager {
             }
             throw new IdentityUnavailableError('Failed to persist recovery mnemonic.', error);
         }
+        // The phrase slot above dies with the keystore too, so the device backup
+        // carries the phrase as well — but only one that derives the identity on
+        // this device. Best-effort: never fails the store.
+        if (KeyManager.deviceBackupStore) {
+            const primary = await KeyManager._readHealthyPrimary();
+            if (primary && (await KeyManager._phraseDerivesPublicKey(mnemonic, primary.publicKey))) {
+                await KeyManager._writeDeviceBackup(primary.privateKey, primary.publicKey, mnemonic.trim().toLowerCase());
+            }
+        }
     }
     /**
      * Read the stored recovery mnemonic for re-reveal in Settings.
@@ -1810,6 +1998,10 @@ class KeyManager {
             await KeyManager._bestEffortDeleteBackupsAllGenerations(store);
             await KeyManager._clearSharedSlot(store);
         }
+        // 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
+        // launch. Best-effort, like the other recovery sources.
+        await KeyManager._clearDeviceBackup();
         // Clear the marker AFTER key deletion succeeds — a marker must never outlive
         // its identity (a leftover marker would route a truly-absent device to
         // `recovery` instead of `welcome`).
@@ -2020,19 +2212,29 @@ class KeyManager {
         }
     }
     /**
-     * Recovery ladder — restore a `lost` identity from an independent,
-     * `key_v1`-surviving source WITHOUT the user re-entering their recovery phrase.
+     * Recovery ladder — restore an identity whose keys are gone from an
+     * independent source WITHOUT the user re-entering their recovery phrase.
      *
-     * Gated on {@link getIdentityStatus} being `lost` (marker present, keys empty):
-     *   - `present` / `absent` → `not-lost` (nothing to recover / nothing lost)
-     *   - `unavailable`        → `unavailable` (keychain locked; retry later)
-     *
-     * Rungs, tried in order, each fully validated (well-formed + derive-match +
-     * `publicKey === marker.publicKey`, so a source holding a DIFFERENT account is
-     * SKIPPED, never restored):
-     *   1. the v2 backup slot (independent keychain key from the primary), then
+     * For a `lost` verdict (marker present, keys empty) the rungs are tried in
+     * order, each fully validated (well-formed + derive-match + `publicKey ===
+     * marker.publicKey`, so a source holding a DIFFERENT account is SKIPPED, never
+     * restored):
+     *   1. the v2 backup slot (independent keychain key from the primary),
      *   2. the cross-app shared slot (Android bridge `getShared` / iOS keychain
-     *      group) — the copy that survives a primary+backup `key_v1` death.
+     *      group) — the copy that survives a primary+backup `key_v1` death,
+     *   3. the device backup ({@link setDeviceBackupStore}; Android Block Store in
+     *      Commons) — the only copy that survives a wipe of the whole shared-UID
+     *      Android Keystore, which takes rungs 1 and 2 with it (oxy#1388).
+     *
+     * For an `absent` verdict (no keys AND no marker: this app's own data was
+     * cleared, or it was reinstalled) only rung 3 applies: a device backup there
+     * means an identity lived on this device and was never deleted (every delete
+     * clears the backup), so it is restored instead of letting onboarding create a
+     * new identity over it. Without a registered store the result stays
+     * `not-lost`, exactly as before.
+     *
+     * `present` → `not-lost`; `unavailable` (keychain locked) → `unavailable`.
+     * Everything here is on-device: no network, so it works offline.
      *
      * On success it re-persists via {@link _persistIdentityAtomic} (origin
      * `'restore'`) and invalidates the cache so routing re-reads `present`. When no
@@ -2043,12 +2245,24 @@ class KeyManager {
             return { recovered: false, reason: 'not-lost' };
         }
         const status = await KeyManager.getIdentityStatus({ bypassCache: true });
-        if (status.state === 'present' || status.state === 'absent') {
+        if (status.state === 'present') {
             return { recovered: false, reason: 'not-lost' };
         }
         if (status.state === 'unavailable') {
             return { recovered: false, reason: 'unavailable' };
         }
+        if (status.state === 'absent') {
+            if (!KeyManager.deviceBackupStore) {
+                return { recovered: false, reason: 'not-lost' };
+            }
+            const candidate = await KeyManager._readDeviceBackupCandidate();
+            if (!candidate) {
+                return { recovered: false, reason: 'not-lost' };
+            }
+            return (await KeyManager._commitDeviceBackupRecovery(candidate))
+                ? { recovered: true, source: 'device-backup', publicKey: candidate.publicKey }
+                : { recovered: false, reason: 'no-sources' };
+        }
         // status.state === 'lost'
         const expectedPublic = status.marker.publicKey.toLowerCase();
         let sawMismatch = false;
@@ -2076,10 +2290,63 @@ class KeyManager {
                 sawMismatch = true;
             }
         }
+        // Rung 3: device backup, outside this UID's keystore.
+        const deviceCandidate = await KeyManager._readDeviceBackupCandidate();
+        if (deviceCandidate) {
+            if (deviceCandidate.publicKey === expectedPublic) {
+                if (await KeyManager._commitDeviceBackupRecovery(deviceCandidate)) {
+                    return { recovered: true, source: 'device-backup', publicKey: deviceCandidate.publicKey };
+                }
+            }
+            else {
+                sawMismatch = true;
+            }
+        }
         // A source existed but identified a DIFFERENT account — never silently
         // switched. Report `mismatch` so the UI can require explicit confirmation.
         return { recovered: false, reason: sawMismatch ? 'mismatch' : 'no-sources' };
     }
+    /** Read the device backup as a healthy, canonical candidate, or null. Never throws. @internal */
+    static async _readDeviceBackupCandidate() {
+        const store = KeyManager.deviceBackupStore;
+        if (!store) {
+            return null;
+        }
+        try {
+            const record = (0, deviceBackup_1.parseDeviceBackup)(await store.read());
+            if (!record || !KeyManager._isHealthyPair(record.privateKey, record.publicKey)) {
+                return null;
+            }
+            return {
+                ...record,
+                privateKey: KeyManager.canonicalPrivateKey(record.privateKey),
+                publicKey: record.publicKey.toLowerCase(),
+            };
+        }
+        catch (error) {
+            logger_1.logger.warn(`Recovery: failed to read the device backup (${store.name})`, { component: 'KeyManager' }, error);
+            return null;
+        }
+    }
+    /**
+     * Persist a device-backup candidate, then put its phrase back in the
+     * re-reveal slot (which died with the keystore) when it derives the key.
+     * @internal
+     */
+    static async _commitDeviceBackupRecovery(record) {
+        if (!(await KeyManager._commitRecovery(record.privateKey, record.publicKey))) {
+            return false;
+        }
+        if (record.mnemonic && (await KeyManager._phraseDerivesPublicKey(record.mnemonic, record.publicKey))) {
+            try {
+                await KeyManager.storeRecoveryMnemonic(record.mnemonic);
+            }
+            catch (error) {
+                logger_1.logger.warn('Recovery: restored the identity but not its phrase slot', { component: 'KeyManager' }, error);
+            }
+        }
+        return true;
+    }
     /** Read the active-layout backup slot as a healthy candidate, or null. @internal */
     static async _readBackupCandidate() {
         try {
@@ -2272,4 +2539,10 @@ KeyManager.identityChangeListeners = new Set();
  */
 KeyManager.slotMigrationPromise = null;
 KeyManager.slotMigrationResult = null;
+/**
+ * The keystore-independent device backup, registered by the app that owns the
+ * identity (Commons). `null` in every other app, which makes every device
+ * backup path a no-op there. See `./deviceBackup`.
+ */
+KeyManager.deviceBackupStore = null;
 exports.default = KeyManager;

package/dist/cjs/mixins/OxyServices.linkedAccounts.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesLinkedAccountsMixin = OxyServicesLinkedAccountsMixin;
+function OxyServicesLinkedAccountsMixin(Base) {
+    return class extends Base {
+        /**
+         * Begin linking an external account for the current user.
+         *
+         * @param network - `'activitypub'` (any Mastodon-API server) or `'atproto'` (Bluesky).
+         * @param options - `instance` for ActivityPub (`mastodon.social`, or
+         *   `@user@mastodon.social`), `handle` for atproto; `clientId` + `returnTo`
+         *   to be sent back to your app afterwards.
+         * @returns The URL to open, and when the attempt expires (ten minutes).
+         */
+        async startLinkedAccount(network, options) {
+            try {
+                return await this.makeRequest('POST', `/linked-accounts/${encodeURIComponent(network)}/start`, options, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Finish a link with the `link_code` the callback appended to `returnTo`.
+         * Must be the user who started the flow: for anyone else the API answers
+         * 403 and burns the code. 409 when the account is already someone else's
+         * link. Repeating it within the code's five minutes returns the same link.
+         */
+        async completeLinkedAccount(code) {
+            try {
+                const response = await this.makeRequest('POST', '/linked-accounts/complete', { code }, { cache: false });
+                return response.linkedAccount;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** The current user's live linked accounts, oldest first. */
+        async listLinkedAccounts() {
+            try {
+                const response = await this.makeRequest('GET', '/linked-accounts', undefined, {
+                    cache: false,
+                });
+                return response.linkedAccounts;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Unlink one of the current user's accounts. An ActivityPub link stops being
+         * published as an `alsoKnownAs` alias, and the external account can then be
+         * linked to another Oxy account.
+         */
+        async revokeLinkedAccount(linkedAccountId) {
+            try {
+                await this.makeRequest('DELETE', `/linked-accounts/${encodeURIComponent(linkedAccountId)}`, undefined, {
+                    cache: false,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * SERVICE: a user's live linked accounts, each with the federated shadow
+         * user Oxy already holds for it (`federatedUserId`). Requires a service
+         * credential whose application holds the privileged `linked-accounts:read`.
+         */
+        async getLinkedAccountsForUser(userId) {
+            try {
+                return await this.makeServiceRequest('GET', `/linked-accounts/by-user/${encodeURIComponent(userId)}`);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.user.js

@@ -859,7 +859,11 @@ function OxyServicesUserMixin(Base) {
             }
         }
         /**
-         * Create notification
+         * Create a notification (`POST /notifications`; the API requires a service
+         * token whose application holds `notifications:write`). `type` is one of
+         * `OXY_NOTIFICATION_TYPES` from `@oxy.so/contracts` — `system` for a message
+         * from an Oxy service about the recipient's own account, with the recipient
+         * as actor and their profile as the entity.
          */
         async createNotification(data) {
             try {

package/dist/cjs/mixins/index.js

@@ -38,6 +38,7 @@ const OxyServices_nodes_1 = require("./OxyServices.nodes");
 const OxyServices_followGraph_1 = require("./OxyServices.followGraph");
 const OxyServices_inference_1 = require("./OxyServices.inference");
 const OxyServices_deviceBoot_1 = require("./OxyServices.deviceBoot");
+const OxyServices_linkedAccounts_1 = require("./OxyServices.linkedAccounts");
 /**
  * Mixin pipeline - applied in order from first to last.
  *
@@ -107,6 +108,9 @@ const MIXIN_PIPELINE = [
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServices_deviceBoot_1.OxyServicesDeviceBootMixin,
+    // Linked external accounts (Mastodon-API, Bluesky) proven by OAuth; the
+    // service read uses the auth mixin's `makeServiceRequest`.
+    OxyServices_linkedAccounts_1.OxyServicesLinkedAccountsMixin,
     // Device-to-device identity transfer ("add a device"): E2E-encrypted key
     // clone over a short-lived relay (b3 Feature 2).
     // Utility (last, can use all above)

package/dist/cjs/server/securityHeaders.js

@@ -353,6 +353,9 @@ function buildOxyPagesHeaders(options = {}) {
     if (options.hsts !== false) {
         lines.push('  Strict-Transport-Security: max-age=31536000; includeSubDomains; preload');
     }
+    if (options.sensitive) {
+        lines.push('  Cache-Control: public, max-age=0, must-revalidate, no-transform');
+    }
     lines.push('');
     return lines.join('\n');
 }