@oxy.so/core 1.9.1 → 1.11.0

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

@@ -288,10 +288,7 @@ function OxyServicesUserMixin(Base) {
          *   `PostHydrationService`) and is unchanged.
          * - **Plain client (browser / React Native with a user session):** when no
          *   service credentials are configured, the chunk is fetched via
-         *   `makeRequest`, which attaches the configured user bearer. oxy-api's CSRF
-         *   middleware skips bearer-authenticated writes, and `makeRequest` only
-         *   fetches a CSRF token for cookie-only (no-bearer) state-changing requests,
-         *   so the user-bearer POST is sent without CSRF and succeeds. Previously
+         *   `makeRequest`, which attaches the configured user bearer. Previously
          *   this method always used the service path, so every client-side caller
          *   silently received `[]` because `getServiceToken()` had no credentials.
          *
@@ -318,7 +315,7 @@ function OxyServicesUserMixin(Base) {
             }
             // A backend that called configureServiceAuth() uses the bearer-service
             // path; any other caller (browser / RN with a user session) uses the
-            // user-bearer path. See the method doc for why the user path is CSRF-safe.
+            // user-bearer path.
             const useServiceAuth = Boolean(this._serviceApiKey && this._serviceApiSecret);
             // Run chunks concurrently; a single chunk failure must not sink the rest.
             const settled = await Promise.all(chunks.map(async (chunk) => {
@@ -862,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/cors.js

@@ -40,7 +40,6 @@ const DEFAULT_ALLOWED_HEADERS = [
     'X-Requested-With',
     'X-Oxy-User-Id',
     'X-Oxy-Internal',
-    'X-CSRF-Token',
     'X-Oxy-Edge-Region',
     'X-Oxy-Activity-Id',
 ];

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');
 }

package/dist/cjs/session/refresh.js

@@ -79,6 +79,7 @@ async function refreshDeviceSecretArm(deps) {
     const { oxy, store } = deps;
     const pin = deps.pin ?? null;
     return oxy.httpService.runSingleFlightDeviceSecretMint(async () => {
+        const epoch = oxy.httpService.getSessionEpoch();
         const persisted = await store.load();
         if (!persisted?.deviceId || !persisted?.deviceSecret) {
             return { status: 'no-secret' };
@@ -144,12 +145,26 @@ async function refreshDeviceSecretArm(deps) {
             expiresAt: mint.expiresAt,
             ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
         };
+        if (oxy.httpService.getSessionEpoch() !== epoch) {
+            // Signed out while minting. The server has rotated the secret, so a store
+            // that still holds the presented one must learn the rotation (the
+            // token-null lane keeps the store so a reload can restore); a store the
+            // sign-out cleared must NOT be refilled. Either way, plant nothing.
+            const current = await store.load();
+            if (current?.deviceId === persisted.deviceId && current.deviceSecret === persisted.deviceSecret) {
+                await store.save(next);
+            }
+            return { status: 'session-ended' };
+        }
         // Persist nextDeviceSecret (read-back-verified) BEFORE planting the token.
         // A failed durable persist must NOT plant.
         const persistedOk = await store.save(next);
         if (!persistedOk) {
             return { status: 'persist-failed' };
         }
+        if (oxy.httpService.getSessionEpoch() !== epoch) {
+            return { status: 'session-ended' };
+        }
         oxy.setTokens(mint.accessToken);
         return {
             status: 'ok',
@@ -187,6 +202,7 @@ async function refreshPersistedSession(deps) {
     const identity = deps.identity ?? null;
     // The shared keychain is never an identity-bound client's recovery path.
     const allowSharedKeyFallback = identity ? false : (deps.allowSharedKeyFallback ?? (0, platform_1.isNative)());
+    const epoch = oxy.httpService.getSessionEpoch();
     // Resolved per call: a re-established identity session can move the pin, and a
     // replaced/removed local key clears it (in which case arm 1 must NOT mint —
     // an unpinned mint would adopt whatever account the device switched to).
@@ -198,6 +214,8 @@ async function refreshPersistedSession(deps) {
     switch (arm1.status) {
         case 'ok':
             return arm1.token;
+        case 'session-ended':
+            return null;
         case 'transient':
             logger_1.logger.debug('Persisted deviceSecret mint failed (transient) — keeping store', { component: 'refresh', method: 'refreshPersistedSession' });
             return null;
@@ -236,10 +254,18 @@ async function refreshPersistedSession(deps) {
     if (identity) {
         return recoverIdentitySession(oxy, store, identity);
     }
-    if (allowSharedKeyFallback) {
+    // Never after a sign-out: the shared keychain holds an identity KEY, not a
+    // session, and using it here would sign the user straight back in.
+    if (allowSharedKeyFallback && !oxy.httpService.hasSessionEnded()) {
         try {
-            const session = await oxy.signInWithSharedIdentity();
+            // Planted here, not by the sign-in: a sign-out that lands while the
+            // challenge round-trips must win, or the shared keychain signs the user
+            // straight back in.
+            const session = await oxy.signInWithSharedIdentity({ plantTokens: false });
             if (session?.accessToken) {
+                if (oxy.httpService.getSessionEpoch() !== epoch) {
+                    return null;
+                }
                 // Repopulate the fast device-secret lane from the shared-key re-mint.
                 if (session.deviceId && session.deviceSecret) {
                     await store.save({
@@ -251,6 +277,10 @@ async function refreshPersistedSession(deps) {
                         expiresAt: session.expiresAt,
                     });
                 }
+                if (oxy.httpService.getSessionEpoch() !== epoch) {
+                    return null;
+                }
+                oxy.setTokens(session.accessToken);
                 return session.accessToken;
             }
         }

package/dist/cjs/utils/errorUtils.js

@@ -82,7 +82,7 @@ const nonEmptyString = (value) => typeof value === 'string' && value.trim().leng
  * - `{ error: '<CODE>', error_description }` — RFC 6749 §5.2 / RFC 6750 §3, the
  *   OAuth token and userinfo endpoints. `error_description` is the human text
  *   and `error` is the machine code, so both survive.
- * - `{ message, code }` — e.g. the API's CSRF rejections.
+ * - `{ message, code }` — e.g. the API's middleware rejections.
  * - `{ error: '<human message>' }` — legacy hand-rolled routes. With no sibling
  *   `message`/`error_description` the string is the message, not a code: a bare
  *   `error` string is not machine-readable enough to promote to `code`.