@yefengr/remote-pi 0.9.7 → 0.9.9

package/dist/pairing/storage.js

@@ -1,391 +1,273 @@
-import { mkdir, readFile, writeFile, chmod, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { chmod, open, readFile, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { generateEd25519Keypair } from "./crypto.js";
+import { ensurePrivateIdentityDirectory, withIdentityLock, } from "./identity-lock.js";
+import { NapiKeyringBackend, nativeBindingUnavailable, } from "./identity-keyring.js";
 import { listPeers } from "./owner_storage.js";
 export { addPeer, listPeers, listOwnerPubkeys, snapshotOwnerPubkeys, conditionalRemovePeer, conditionalRollbackPeer, removePeer, } from "./owner_storage.js";
-/**
- * Pi-secret storage (plan/27 Wave E1).
- *
- * The Ed25519 long-term identity of this Pi lives in the platform keyring
- * via `@napi-rs/keyring` (Keychain on macOS, libsecret on Linux desktop,
- * Credential Manager on Windows — DPAPI-backed). When the keyring is
- * unavailable (headless Linux without a D-Bus session, Docker containers,
- * VPS without GNOME Keyring/KWallet running) we fall back to a
- * file-backed store at `~/.pi/remote/identity.json` with `0o600`
- * permissions and the parent dir at `0o700`.
- *
- * **Migration**: previous builds used `keytar` against service
- * `dev.remotepi.mac`. This module reads from the old service if the new
- * service is empty, copies the entry to the new service `dev.remotepi.pi`,
- * and deletes the old one. Both keytar and `@napi-rs/keyring` address the
- * same OS-level credential store on every supported platform, so the read
- * succeeds without keeping the deprecated `keytar` dependency.
- */
-const NEW_SERVICE = "dev.remotepi.pi"; // platform-neutral
-const OLD_SERVICE = "dev.remotepi.mac"; // legacy keytar service (pre-2026-05-25)
+export { _setKeyringOperationTimeoutForTest, _setNativeBindingErrorForTest, KeyringMutationTimeoutError, KeyringReadTimeoutError, } from "./identity-keyring.js";
+export { IdentityLockTimeoutError } from "./identity-lock.js";
+const NEW_SERVICE = "dev.remotepi.pi";
+const OLD_SERVICE = "dev.remotepi.mac";
 const ACCOUNT = "longterm-ed25519";
-/**
- * The keyring read can THROW transiently rather than permanently — most
- * notably a macOS Keychain that's still locked right after login/wake (the
- * machine sat idle for days). Treating that throw as "backend unavailable"
- * and minting a fresh identity silently orphans the paired key (the
- * "lost pairing after a week idle" failure). So we retry the read a few times
- * before ever concluding the keyring is truly unavailable. Overridable for
- * tests via `_setKeyringRetryForTest`. */
-let _keyringReadAttempts = 3;
-let _keyringRetryDelayMs = 300;
-/** Raised when the keyring is unreadable on a platform where it's a core OS
- *  service (macOS Keychain, Windows Credential Manager) AND no prior file
- *  identity exists. We refuse to generate a NEW identity here because that
- *  would break existing pairing — the caller surfaces this so the user can
- *  unlock the keychain and retry instead of silently re-pairing. */
+const PI_DIR = join(homedir(), ".pi", "remote");
+const IDENTITY_FILE = join(PI_DIR, "identity.json");
+const IDENTITY_LOCK_FILE = join(PI_DIR, "identity.lock");
+let keyringReadAttempts = 3;
+let keyringRetryDelayMs = 300;
+let identityLockWaitTimeoutMs = 15_000;
+let identityLockPollIntervalMs = 50;
 export class KeyringUnavailableError extends Error {
     constructor(cause) {
         super("Platform keyring is unreadable and no file-backed identity exists. " +
-            "Refusing to generate a NEW identity (that would break existing " +
-            "pairing). Unlock your keychain / start your secret service and retry. " +
+            "Refusing to generate a NEW identity (that would break existing pairing). " +
+            "Unlock your keychain / start your secret service and retry. " +
             "Set REMOTE_PI_ALLOW_FILE_IDENTITY=1 to force a file-backed identity. " +
             `Cause: ${String(cause)}`);
         this.name = "KeyringUnavailableError";
     }
 }
-/** Raised when no identity can be resolved (keyring unreadable, no identity
- *  file) BUT `peers.json` already lists paired devices. Minting a fresh key
- *  here would make those existing pairings unusable — see issues #95 / #69. */
 export class PairedIdentityMissingError extends Error {
     constructor(pairedCount, cause) {
-        super(`No identity could be read, but ${pairedCount} device(s) are already ` +
-            "paired. Refusing to generate a NEW identity — that would revoke every " +
-            "paired device. This usually means this process cannot reach the same " +
-            "keyring as the session that paired (for example, a headless process vs. " +
-            "your desktop session). Fix the process keyring access, or pin the " +
-            "identity by copying the paired keypair to ~/.pi/remote/identity.json " +
-            "(0600), which both contexts read first. " +
+        super(`No identity could be read, but ${pairedCount} device(s) are already paired. ` +
+            "Refusing to generate a NEW identity - that would revoke every paired device. " +
+            "Fix this process's keyring access, or pin the established identity to " +
+            "~/.pi/remote/identity.json (0600). " +
             `Cause: ${String(cause)}`);
         this.name = "PairedIdentityMissingError";
     }
 }
-const PI_DIR = join(homedir(), ".pi", "remote");
-const IDENTITY_FILE = join(PI_DIR, "identity.json");
-/**
- * Per-operation timeout for native keyring calls (gnome-keyring / libsecret
- * via @napi-rs/keyring). A healthy secret service settles in milliseconds; 3s
- * is generous. The point is NOT speed — it is converting a HANG into a thrown
- * error. The native getPassword()/setPassword() can block indefinitely when
- * gnome-keyring waits on a GUI authorization prompt that cannot be shown in
- * a headless / tmux / non-interactive context. A hang never settles, so
- * without this guard the promise never rejects and the retry + file-fallback
- * logic in getOrCreateEd25519Keypair() is unreachable — freezing the entire
- * /remote-pi pair bootstrap. Raising a real error here lets that fallback
- * chain run as designed.
- */
-const KEYRING_OP_TIMEOUT_MS = 3_000;
-function _withTimeout(p, op, ms = KEYRING_OP_TIMEOUT_MS) {
-    return Promise.race([
-        p,
-        new Promise((_, reject) => setTimeout(() => reject(new Error(`keyring ${op} timed out after ${ms}ms`)), ms)),
-    ]);
-}
-/**
- * Lazily loaded `@napi-rs/keyring` binding — issue #113.
- *
- * A STATIC `import { AsyncEntry } from "@napi-rs/keyring"` is evaluated when
- * the extension module is loaded, so a native binding that cannot be resolved
- * takes the WHOLE extension down at load time ("Failed to load extension …:
- * Cannot find native binding"). That happens on a Bun-compiled `pi`: the
- * loader's first branch (`require("./keyring.<triple>.node")`) is fine, but its
- * fallback (`require("@napi-rs/keyring-<triple>")`, a bare package whose `main`
- * IS the .node file) resolves under Node and not under Bun — and the message it
- * prints then blames npm's optional-dependency bug, sending users off to delete
- * node_modules and losing their other pi packages.
- *
- * Loading on first use turns that fatal load error into an ordinary backend
- * failure, which the existing retry + file-identity fallback already handles.
- */
-let _asyncEntryCtor = null;
-let _nativeBindingError = null;
-async function _loadAsyncEntry() {
-    if (_asyncEntryCtor)
-        return _asyncEntryCtor;
-    if (_nativeBindingError)
-        throw _nativeBindingError;
-    try {
-        const mod = await import("@napi-rs/keyring");
-        _asyncEntryCtor = mod.AsyncEntry;
-        return _asyncEntryCtor;
+export class IdentityFileError extends Error {
+    identityPath;
+    category;
+    constructor(identityPath, category) {
+        super(`Identity file at ${identityPath} is unsafe to use (${category}). Refusing to replace it.`);
+        this.name = "IdentityFileError";
+        this.identityPath = identityPath;
+        this.category = category;
     }
-    catch (err) {
-        _nativeBindingError = err;
-        throw err;
-    }
-}
-/**
- * Did the native binding fail to LOAD (as opposed to an operation failing)?
- *
- * A load failure is deterministic and platform-wide: no retry, no unlock, no
- * amount of waiting brings the keyring back in this process. So it must NOT be
- * treated like a transiently locked Keychain — on macOS/Windows that would
- * throw `KeyringUnavailableError` and leave the user with no working path at
- * all. The file-identity fallback (with its loud warning) is the only usable
- * route here, exactly as on headless Linux.
- */
-function _nativeBindingUnavailable() {
-    return _nativeBindingError !== null;
 }
-/** Test-only: force (or clear with `null`) a memoized binding-load failure, so
- *  the Bun/no-native-binding branch is reachable without a Bun host. */
-export function _setNativeBindingErrorForTest(err) {
-    _asyncEntryCtor = null;
-    _nativeBindingError = err;
-}
-class NapiKeyringBackend {
-    async read(service, account) {
-        const AsyncEntry = await _loadAsyncEntry();
-        const entry = new AsyncEntry(service, account);
-        return _withTimeout(entry.getPassword(), `read(${service})`); // undefined on no-entry
-    }
-    async write(service, account, value) {
-        const AsyncEntry = await _loadAsyncEntry();
-        const entry = new AsyncEntry(service, account);
-        await _withTimeout(entry.setPassword(value), `write(${service})`);
-    }
-    async delete(service, account) {
-        let entry;
-        try {
-            const AsyncEntry = await _loadAsyncEntry();
-            entry = new AsyncEntry(service, account);
-        }
-        catch {
-            return false;
-        }
-        try {
-            return await _withTimeout(entry.deleteCredential(), `delete(${service})`);
-        }
-        catch {
-            return false;
-        }
+export class KeyringIdentityError extends Error {
+    service;
+    constructor(service) {
+        super(`Stored identity in platform keyring service ${service} is invalid. Refusing to replace it.`);
+        this.name = "KeyringIdentityError";
+        this.service = service;
     }
 }
-let _backend = null;
-function _getBackend() {
-    if (!_backend)
-        _backend = new NapiKeyringBackend();
-    return _backend;
+let backend = null;
+let keyringExpectedOverride = null;
+function getBackend() {
+    if (!backend)
+        backend = new NapiKeyringBackend();
+    return backend;
 }
-/** Test-only: swap (or clear with `null`) the keyring backend. */
-export function _setKeyStoreBackendForTest(backend) {
-    _backend = backend;
+export function _setKeyStoreBackendForTest(value) {
+    backend = value;
 }
-/**
- * Is the platform keyring a CORE OS service we should expect to be present?
- * macOS (Keychain) and Windows (Credential Manager) always have one, so a read
- * that throws there is transient/locked, NOT "headless" — we must not mint a
- * new identity. On Linux/other the secret service may be genuinely absent
- * (headless, no D-Bus), so the documented file fallback applies. Overridable
- * for tests via `_setKeyringExpectedForTest`. */
-let _keyringExpectedOverride = null;
-function _keyringExpectedAvailable() {
-    if (_keyringExpectedOverride !== null)
-        return _keyringExpectedOverride;
-    // Binding never loaded (Bun-built pi, issue #113) → there is no keyring on
-    // this platform *for this process*, whatever the OS normally offers.
-    if (_nativeBindingUnavailable())
+function keyringExpectedAvailable() {
+    if (keyringExpectedOverride !== null)
+        return keyringExpectedOverride;
+    if (nativeBindingUnavailable())
         return false;
     return process.platform === "darwin" || process.platform === "win32";
 }
-/** Test-only: force `_keyringExpectedAvailable()` (so a darwin test host can
- *  exercise the Linux/headless branch and vice-versa). `null` restores the
- *  real platform check. */
 export function _setKeyringExpectedForTest(value) {
-    _keyringExpectedOverride = value;
+    keyringExpectedOverride = value;
 }
-/** Test-only: shrink retry attempts/delay so the persistent-failure path is
- *  fast. `null`/omitted restores defaults. */
 export function _setKeyringRetryForTest(attempts, delayMs) {
-    _keyringReadAttempts = attempts ?? 3;
-    _keyringRetryDelayMs = delayMs ?? 300;
+    keyringReadAttempts = attempts ?? 3;
+    keyringRetryDelayMs = delayMs ?? 300;
+}
+export function _setIdentityLockTimingForTest(waitTimeoutMs, pollIntervalMs) {
+    identityLockWaitTimeoutMs = waitTimeoutMs ?? 15_000;
+    identityLockPollIntervalMs = pollIntervalMs ?? 50;
 }
-function _sleep(ms) {
-    return ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
+function sleep(ms) {
+    return ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
 }
-function _serialize(kp) {
+function serialize(kp) {
     const payload = {
         pk: Buffer.from(kp.publicKey).toString("base64"),
         sk: Buffer.from(kp.secretKey).toString("base64"),
     };
     return JSON.stringify(payload);
 }
-function _deserialize(stored) {
+function decodeCanonicalBase64(value, field) {
+    if (typeof value !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+        throw new Error(`invalid ${field}`);
+    }
+    const decoded = Buffer.from(value, "base64");
+    if (decoded.toString("base64") !== value)
+        throw new Error(`invalid ${field}`);
+    return decoded;
+}
+function deserializeUnsafe(stored) {
     const parsed = JSON.parse(stored);
-    return {
-        publicKey: Buffer.from(parsed.pk, "base64"),
-        secretKey: Buffer.from(parsed.sk, "base64"),
-    };
+    const publicKey = decodeCanonicalBase64(parsed.pk, "pk");
+    const secretKey = decodeCanonicalBase64(parsed.sk, "sk");
+    if (publicKey.length !== 32 || (secretKey.length !== 32 && secretKey.length !== 64))
+        throw new Error("invalid key length");
+    return { publicKey, secretKey };
+}
+function deserializeKeyringIdentity(stored, service) {
+    try {
+        return deserializeUnsafe(stored);
+    }
+    catch {
+        throw new KeyringIdentityError(service);
+    }
+}
+function isNodeErrorWithCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error &&
+        error.code === code;
 }
-// ── File fallback (headless Linux) ──────────────────────────────────────────
-async function _readKeypairFromFile() {
+async function readKeypairFromFile() {
+    let raw;
     try {
-        const raw = await readFile(IDENTITY_FILE, "utf8");
-        return _deserialize(raw);
+        raw = await readFile(IDENTITY_FILE, "utf8");
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "ENOENT"))
+            return null;
+        throw new IdentityFileError(IDENTITY_FILE, "read_failed");
+    }
+    try {
+        return deserializeUnsafe(raw);
     }
     catch {
-        return null;
+        throw new IdentityFileError(IDENTITY_FILE, "invalid_format");
     }
 }
-async function _writeKeypairToFile(kp) {
-    await mkdir(PI_DIR, { recursive: true, mode: 0o700 });
-    // Best-effort tighten of the dir in case it pre-existed with looser
-    // permissions (mkdir's mode is only applied to NEW dirs).
+async function syncIdentityDirectory() {
+    if (process.platform === "win32")
+        return;
+    const directory = await open(PI_DIR, "r");
     try {
-        await chmod(PI_DIR, 0o700);
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
     }
-    catch { /* not fatal */ }
-    await writeFile(IDENTITY_FILE, _serialize(kp), { mode: 0o600 });
+}
+async function writeKeypairToFile(kp) {
+    await ensurePrivateIdentityDirectory(PI_DIR);
+    const temporaryPath = join(PI_DIR, `.identity.json.${process.pid}.${randomUUID()}.tmp`);
+    let handle = null;
+    let published = false;
     try {
+        handle = await open(temporaryPath, "wx", 0o600);
+        await handle.writeFile(serialize(kp), "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = null;
+        await rename(temporaryPath, IDENTITY_FILE);
+        published = true;
         await chmod(IDENTITY_FILE, 0o600);
+        await syncIdentityDirectory();
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        if (!published) {
+            await unlink(temporaryPath).catch((error) => {
+                if (!isNodeErrorWithCode(error, "ENOENT"))
+                    throw error;
+            });
+        }
     }
-    catch { /* not fatal */ }
 }
-// ── Public API ──────────────────────────────────────────────────────────────
-/**
- * Returns the Pi-secret Ed25519 keypair, generating + persisting one on
- * first call. Resolution order:
- *   1. Existing file `~/.pi/remote/identity.json`, if present — it WINS over
- *      the keyring. A file identity is only ever written by the headless/
- *      degraded fallback (step 4) or an explicit `REMOTE_PI_ALLOW_FILE_IDENTITY`
- *      opt-in, so its mere presence means this machine established its identity
- *      as a file and the browser PWA paired against THAT pubkey. If the
- *      platform keyring later becomes readable (D-Bus/libsecret installed, a
- *      desktop session, or a stale/other entry from another install), reading
- *      it first would mask the file identity — returning a DIFFERENT key, or
- *      (when the keyring is empty) minting a fresh one and persisting it —
- *      silently breaking the existing pairing. So when both exist, file wins.
- *   2. New keyring service `dev.remotepi.pi` (read retried — a transiently
- *      locked Keychain throws; we don't treat that as "no key")
- *   3. Old keyring service `dev.remotepi.mac` (migrate → step 2, delete old)
- *   4. Generate a fresh keypair, BUT only when it's safe to: either both
- *      keyring reads succeeded and returned nothing (genuine first run), or
- *      the keyring is genuinely unavailable on a platform without a core one
- *      (headless Linux → a file identity is minted here). On macOS/Windows a
- *      persistent read failure with no file identity throws
- *      `KeyringUnavailableError` instead of minting a new key — generating
- *      there silently breaks existing pairing (the "lost pairing after idle"
- *      bug). `REMOTE_PI_ALLOW_FILE_IDENTITY=1` opts back into a file identity
- *      for headless macOS/Windows hosts.
- *
- * Idempotent: subsequent calls return the same identity. The migration
- * runs at most once per machine (the old entry is deleted after copy).
- */
-export async function getOrCreateEd25519Keypair() {
-    const backend = _getBackend();
-    // ── Path 0: an existing file-backed identity wins ──────────────────────
-    // `~/.pi/remote/identity.json` is only ever written by the headless/degraded
-    // fallback below (or an operator who set REMOTE_PI_ALLOW_FILE_IDENTITY=1) —
-    // never on a keyring-backed install. So its presence means THIS machine
-    // paired against the file key, and the keyring (readable or not, matching or
-    // not) must not be allowed to mask it. Short-circuit before touching the
-    // keyring so a keyring that later comes online can't return a different key,
-    // nor mint a fresh one over the file identity. No file → normal keyring
-    // resolution below; a headless first run still reaches Path B and mints one.
-    const existingFile = await _readKeypairFromFile();
-    if (existingFile)
-        return existingFile;
-    // ── Path A: keyring (retried) ──────────────────────────────────────────
-    // A throw here means the keyring op FAILED — but on macOS/Windows that is
-    // almost always a transiently locked Keychain (idle/just-woke machine), not
-    // a missing backend. `read` returns `undefined` for "no such entry" (the
-    // genuine first-run signal). So we retry on throw, and only a throw that
-    // SURVIVES every attempt drops us to Path B.
+async function assertGenerationIsSafe(forceFile, cause) {
+    if (forceFile)
+        return;
+    const paired = await listPeers();
+    if (paired.length > 0)
+        throw new PairedIdentityMissingError(paired.length, cause);
+}
+async function resolveKeyringReads(store) {
     let keyringError;
-    for (let attempt = 0; attempt < _keyringReadAttempts; attempt++) {
+    for (let attempt = 0; attempt < keyringReadAttempts; attempt++) {
         try {
-            const existing = await backend.read(NEW_SERVICE, ACCOUNT);
+            const existing = await store.read(NEW_SERVICE, ACCOUNT);
             if (existing)
-                return _deserialize(existing);
-            const legacy = await backend.read(OLD_SERVICE, ACCOUNT);
-            if (legacy) {
-                const kp = _deserialize(legacy);
-                await backend.write(NEW_SERVICE, ACCOUNT, legacy);
-                await backend.delete(OLD_SERVICE, ACCOUNT);
-                // Silent migration: writing the chat surface would be premature
-                // (Pi SDK isn't bound yet at this point in boot) and console
-                // output bleeds outside the TUI. The presence of an entry under
-                // NEW_SERVICE is itself the audit signal — re-running migration
-                // is idempotent and harmless.
-                return kp;
-            }
-            // Both reads SUCCEEDED and returned nothing → genuine first run on a
-            // working keyring. Generate and save to the new service.
-            const fresh = generateEd25519Keypair();
-            await backend.write(NEW_SERVICE, ACCOUNT, _serialize(fresh));
-            return fresh;
+                return { resolution: { kind: "new", stored: existing }, error: undefined };
+            const legacy = await store.read(OLD_SERVICE, ACCOUNT);
+            if (legacy)
+                return { resolution: { kind: "legacy", stored: legacy }, error: undefined };
+            return { resolution: { kind: "empty" }, error: undefined };
         }
-        catch (err) {
-            keyringError = err;
-            if (attempt < _keyringReadAttempts - 1) {
-                // Linear backoff — a locked Keychain usually frees within seconds.
-                await _sleep(_keyringRetryDelayMs * (attempt + 1));
+        catch (error) {
+            keyringError = error;
+            if (attempt < keyringReadAttempts - 1) {
+                await sleep(keyringRetryDelayMs * (attempt + 1));
             }
         }
     }
-    // ── Path B: keyring threw on every attempt ─────────────────────────────
-    // Path 0 already returned any pre-existing file identity; this defensive
-    // re-check catches a file written concurrently by another Pi process during
-    // the keyring-retry window (still: use it, never regenerate).
-    const fromFile = await _readKeypairFromFile();
+    return { resolution: null, error: keyringError };
+}
+async function getOrCreateUnderLock() {
+    const existingFile = await readKeypairFromFile();
+    if (existingFile)
+        return existingFile;
+    const store = getBackend();
+    const { resolution, error: keyringError } = await resolveKeyringReads(store);
+    const forceFile = process.env.REMOTE_PI_ALLOW_FILE_IDENTITY === "1";
+    if (resolution?.kind === "new") {
+        return deserializeKeyringIdentity(resolution.stored, NEW_SERVICE);
+    }
+    if (resolution?.kind === "legacy") {
+        const keypair = deserializeKeyringIdentity(resolution.stored, OLD_SERVICE);
+        await store.write(NEW_SERVICE, ACCOUNT, resolution.stored);
+        await store.delete(OLD_SERVICE, ACCOUNT);
+        return keypair;
+    }
+    if (resolution?.kind === "empty") {
+        await assertGenerationIsSafe(forceFile, undefined);
+        const fresh = generateEd25519Keypair();
+        await store.write(NEW_SERVICE, ACCOUNT, serialize(fresh));
+        return fresh;
+    }
+    const fromFile = await readKeypairFromFile();
     if (fromFile)
         return fromFile;
-    // No file identity AND the keyring is unreadable. CRITICAL FORK:
-    //
-    //  - On a platform without a guaranteed keyring (headless Linux, no D-Bus),
-    //    minting a file-backed identity is the documented, correct first-run
-    //    behavior.
-    //  - On macOS/Windows the keyring is a core OS service, so a persistent read
-    //    failure means it's LOCKED/denied — NOT that we're a fresh install.
-    //    Generating a new key here is exactly what silently broke pairing after
-    //    a week idle, and the new key then masks the real Keychain identity via
-    //    the file. So we FAIL LOUD instead, unless the operator explicitly
-    //    opts into a file identity.
-    const forceFile = process.env.REMOTE_PI_ALLOW_FILE_IDENTITY === "1";
-    if (_keyringExpectedAvailable() && !forceFile) {
+    if (keyringExpectedAvailable() && !forceFile) {
         throw new KeyringUnavailableError(keyringError);
     }
-    // Issues #95 / #69 — minting a NEW identity when Owners are already paired
-    // is destructive on every platform. A separate process can resolve a
-    // different secret store than the interactive process which created the machine key; a fresh
-    // identity would no longer authenticate as the paired Host. Keep peers.json
-    // intact and fail loudly so the operator can restore access or pin the
-    // established identity to the file-backed store.
-    if (!forceFile) {
-        const paired = await listPeers();
-        if (paired.length > 0) {
-            throw new PairedIdentityMissingError(paired.length, keyringError);
-        }
-    }
-    console.warn(_nativeBindingUnavailable()
-        // Issue #113: the @napi-rs/keyring native binding could not be loaded at
-        // all (typically a Bun-compiled pi). Name it explicitly — the error the
-        // loader prints blames npm's optional-dependency bug and sends people off
-        // to delete node_modules, which takes their other pi packages with it.
+    await assertGenerationIsSafe(forceFile, keyringError);
+    console.warn(nativeBindingUnavailable()
         ? "[remote-pi] @napi-rs/keyring native binding could not be loaded in this " +
-            `runtime; using file-backed identity at ${IDENTITY_FILE} (0600) instead. ` +
-            "This is expected on a Bun-built pi. Paired devices keyed to a previous " +
-            `keyring identity must be re-paired. ${String(keyringError)}`
+            `runtime; using file-backed identity at ${IDENTITY_FILE} (0600) instead. ${String(keyringError)}`
         : "[remote-pi] keyring unavailable; using file-backed identity at " +
             `${IDENTITY_FILE}. ${String(keyringError)}`);
     const fresh = generateEd25519Keypair();
-    await _writeKeypairToFile(fresh);
+    await writeKeypairToFile(fresh);
     return fresh;
 }
-// ── Test-only helpers ────────────────────────────────────────────────────────
-/** Test-only: expose the identity-file path so tests can clean it. */
+/**
+ * Returns the stable Host identity. Existing file identity wins; otherwise all
+ * keyring reads, migration, generation, and persistence run under the fixed
+ * cross-process identity lock. Every source is read again after lock acquisition.
+ */
+export async function getOrCreateEd25519Keypair() {
+    const existingFile = await readKeypairFromFile();
+    if (existingFile)
+        return existingFile;
+    return withIdentityLock(PI_DIR, getOrCreateUnderLock, {
+        waitTimeoutMs: identityLockWaitTimeoutMs,
+        pollIntervalMs: identityLockPollIntervalMs,
+    });
+}
 export const _IDENTITY_FILE_FOR_TEST = IDENTITY_FILE;
-/** Test-only: expose unlink for cleanup. */
+export const _IDENTITY_LOCK_FILE_FOR_TEST = IDENTITY_LOCK_FILE;
 export const _unlinkIdentityFileForTest = async () => {
     try {
         await unlink(IDENTITY_FILE);
     }
-    catch { /* fine if missing */ }
+    catch (error) {
+        if (!isNodeErrorWithCode(error, "ENOENT"))
+            throw error;
+    }
 };
 //# sourceMappingURL=storage.js.map