@bridge_gpt/mcp-server 0.2.21 → 0.2.23

package/build/credential-store.js

@@ -7,12 +7,20 @@
  *   3. `~/.bridge/credentials.json` (only when the primary path is absent).
  *
  * The file is keyed by a logical target `bapi:<repoName>`. The resolver NEVER
- * creates or initializes credential files. The writer ({@link upsertBapiCredential})
- * is the ONLY mutation primitive: it upserts a single key into the user-scoped
- * primary store via explicit install/migration code paths, preserves every
- * other entry, and never touches project/worktree config files (those remain
- * secret-free). No code path here places secret values in thrown errors,
- * returned error strings, or stderr warnings.
+ * creates or initializes credential files. The mutation primitives — the
+ * best-effort {@link upsertBapiCredential} and the fail-closed bootstrap-invite
+ * pending-state operations ({@link prepareBootstrapPendingCredential},
+ * {@link repointBootstrapPendingCredential}, {@link promoteBootstrapPendingCredential})
+ * — are the ONLY writers: they mutate the user-scoped primary store from explicit
+ * install/migration code paths, preserve every other entry, and never touch
+ * project/worktree config files (those remain secret-free). Every mutation runs
+ * under {@link withCredentialStoreLock}, so two concurrent writers cannot
+ * last-writer-win and drop a sibling credential. No code path here places secret
+ * values in thrown errors, returned error strings, or stderr warnings.
+ *
+ * Resolution order is unchanged by the bootstrap-invite work: a
+ * `bootstrap-pending:<repo>` entry is a distinct logical target and is NEVER read
+ * by {@link resolveBapiCredentials} — only a promoted `bapi:<repo>` credential is.
  *
  * Two-runtime credential rule: the MCP server process env and a Bash-spawned
  * CLI (e.g. `start-tickets`) env are DIFFERENT runtime surfaces. A secret in
@@ -299,6 +307,495 @@ function defaultTempSuffix() {
     tempSuffixCounter += 1;
     return `${process.pid}.${tempSuffixCounter}`;
 }
+// ---------------------------------------------------------------------------
+// Locking + durable (fsync'd) replacement (BAPI-606)
+// ---------------------------------------------------------------------------
+/** Poll interval while waiting for a contended lock. */
+const LOCK_POLL_INTERVAL_MS = 50;
+/** Bounded wait before a held lock is treated as abandoned. */
+const LOCK_TIMEOUT_MS = 5_000;
+/** Lock path, adjacent to the primary store. Never carries secret material. */
+export function getCredentialStoreLockPath(deps) {
+    return `${getPrimaryCredentialStorePath(deps)}.lock`;
+}
+/**
+ * Acquire the exclusive credential-store lock: an atomically created (`wx`) lock
+ * file beside the store, with a bounded wait.
+ *
+ * When `deps.open` is absent there is no lock primitive available, so the caller
+ * runs unlocked — exactly the pre-BAPI-606 behavior, preserved so existing
+ * builders and in-memory test doubles keep working.
+ *
+ * Stale-lock recovery: a lock still held after {@link LOCK_TIMEOUT_MS} (orders of
+ * magnitude longer than a legitimate sub-millisecond read-modify-write) is
+ * treated as abandoned by a crashed process and stolen exactly once. The
+ * alternative — refusing forever — wedges every future install behind a lock file
+ * no user knows to delete.
+ */
+async function acquireCredentialStoreLock(deps) {
+    const open = deps.open;
+    if (!open)
+        return { ok: true, release: async () => { } };
+    const lockPath = getCredentialStoreLockPath(deps);
+    const isPosix = deps.platform !== "win32";
+    const now = deps.now ?? (() => Date.now());
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const release = async () => {
+        if (!deps.unlink)
+            return;
+        try {
+            await deps.unlink(lockPath);
+        }
+        catch {
+            /* releasing a lock that is already gone must never fail the caller */
+        }
+    };
+    const tryAcquire = async () => {
+        try {
+            const handle = await open(lockPath, "wx", isPosix ? 0o600 : undefined);
+            await handle.close();
+            return { ok: true };
+        }
+        catch (err) {
+            const code = err && typeof err === "object" ? err.code : undefined;
+            return { ok: false, contended: code === "EEXIST" };
+        }
+    };
+    try {
+        await deps.mkdir(path.dirname(lockPath), { recursive: true });
+    }
+    catch {
+        return { ok: false, error: `Unable to prepare the credentials directory for ${lockPath}.` };
+    }
+    const deadline = now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        const attempt = await tryAcquire();
+        if (attempt.ok)
+            return { ok: true, release };
+        if (!attempt.contended) {
+            return { ok: false, error: `Unable to acquire the credentials lock at ${lockPath}.` };
+        }
+        if (now() >= deadline)
+            break;
+        await sleep(LOCK_POLL_INTERVAL_MS);
+    }
+    // Bounded wait exhausted — steal the abandoned lock, once.
+    await release();
+    const stolen = await tryAcquire();
+    if (stolen.ok)
+        return { ok: true, release };
+    return {
+        ok: false,
+        error: `Timed out waiting for the credentials lock at ${lockPath} (another install may be running).`,
+    };
+}
+/**
+ * Serialize a credential-store read-modify-write against the shared lock. The
+ * lock is always released, and `onLockError` maps an acquisition failure into the
+ * caller's own (secret-free) result shape.
+ */
+export async function withCredentialStoreLock(deps, fn, onLockError) {
+    const lock = await acquireCredentialStoreLock(deps);
+    if (!lock.ok)
+        return onLockError(lock.error);
+    try {
+        return await fn();
+    }
+    finally {
+        await lock.release();
+    }
+}
+/**
+ * Replace the primary store DURABLY: temp file (mode 0600) → write → **fsync** →
+ * close → chmod → rename, then a best-effort fsync of the containing directory.
+ *
+ * The file fsync is fail-closed: if it rejects, the write is reported as failed
+ * and the prior store is left intact. That is the whole point of this primitive —
+ * {@link upsertBapiCredential}'s temp-write + rename is durable *enough* for a
+ * best-effort routing credential, but not for a protocol proof that must survive a
+ * crash (the bootstrap-invite pending secret). The directory fsync is best-effort:
+ * platforms that cannot open a directory (win32) must not weaken the file fsync.
+ */
+export async function durablyReplaceCredentialStoreJson(primaryPath, value, deps) {
+    const open = deps.open;
+    if (!open) {
+        return {
+            ok: false,
+            kind: "durable-unavailable",
+            error: `Cannot durably write ${primaryPath}: no file-handle primitive is available to fsync the write.`,
+        };
+    }
+    const dir = path.dirname(primaryPath);
+    const suffix = (deps.tempSuffix ?? defaultTempSuffix)();
+    const tempPath = path.join(dir, `${path.basename(primaryPath)}.${suffix}.tmp`);
+    const json = formatCredentialStoreJson(value);
+    const isPosix = deps.platform !== "win32";
+    let handle;
+    try {
+        await deps.mkdir(dir, { recursive: true });
+        handle = await open(tempPath, "w", isPosix ? 0o600 : undefined);
+        await handle.writeFile(json, { encoding: "utf-8" });
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        if (isPosix)
+            await deps.chmod(tempPath, 0o600);
+        await deps.rename(tempPath, primaryPath);
+    }
+    catch {
+        if (handle) {
+            try {
+                await handle.close();
+            }
+            catch {
+                /* a close failure must not mask the real write error */
+            }
+        }
+        if (deps.unlink) {
+            try {
+                await deps.unlink(tempPath);
+            }
+            catch {
+                /* best-effort temp cleanup only; the prior store is untouched */
+            }
+        }
+        // Never surface the raw I/O message — it can echo the written contents.
+        return {
+            ok: false,
+            kind: "write-error",
+            error: `Failed to durably write the credentials file at ${primaryPath}.`,
+        };
+    }
+    try {
+        const dirHandle = await open(dir, "r");
+        try {
+            await dirHandle.sync();
+        }
+        finally {
+            await dirHandle.close();
+        }
+    }
+    catch {
+        /* directory fsync is unsupported on some platforms; the file fsync above is
+           the load-bearing one and already succeeded. */
+    }
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Bootstrap-invite pending state (BAPI-606)
+// ---------------------------------------------------------------------------
+/**
+ * Logical target for a bootstrap-invite secret that has been generated and
+ * durably saved but NOT yet redeemed. It is a separate top-level key from
+ * `bapi:<repo>`, so the resolver never serves an unredeemed secret as a
+ * credential, and a failed redemption never leaves a broken `bapi:<repo>` entry.
+ */
+export const BOOTSTRAP_PENDING_TARGET_PREFIX = "bootstrap-pending:";
+/** Secret name holding the client-generated `key_secret` inside a pending record. */
+export const BOOTSTRAP_PENDING_SECRET_FIELD = "BAPI_API_KEY";
+/** Secret name holding the invite FINGERPRINT (a SHA-256 hex digest, not the token). */
+export const BOOTSTRAP_PENDING_FINGERPRINT_FIELD = "BOOTSTRAP_INVITE_FINGERPRINT";
+/** Pending target for a repo: `bootstrap-pending:<repo>`. */
+export function getBootstrapPendingTarget(repoName) {
+    return `${BOOTSTRAP_PENDING_TARGET_PREFIX}${(repoName ?? "").trim()}`;
+}
+/** `bapi:<repo>` target (no lowercasing/canonicalization — mirrors the upsert). */
+function getBapiTarget(repoName) {
+    return `bapi:${(repoName ?? "").trim()}`;
+}
+/** Load the primary store for mutation, seeding from the legacy fallback on first write. */
+async function loadStoreForMutation(deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const primary = await readCredentialStoreJsonIfPresent(primaryPath, deps);
+    if (primary.state === "error") {
+        return { ok: false, kind: primary.kind, error: primary.error };
+    }
+    if (primary.state === "present") {
+        return { ok: true, base: { ...primary.value } };
+    }
+    const seeded = await mergeFallbackCredentialStoreOnFirstPrimaryWrite(deps);
+    return { ok: true, base: seeded.base };
+}
+/** Does a real (non-empty) `BAPI_API_KEY` already exist for `bapi:<repo>`? */
+function hasExistingBapiKey(store, repoName) {
+    const entry = store[getBapiTarget(repoName)];
+    return (!!entry && typeof entry.BAPI_API_KEY === "string" && entry.BAPI_API_KEY.trim().length > 0);
+}
+/** Read a pending record whose fingerprint matches; `null` when absent/mismatched. */
+function readMatchingPending(store, repoName, inviteFingerprint) {
+    const entry = store[getBootstrapPendingTarget(repoName)];
+    if (!entry)
+        return null;
+    const secret = entry[BOOTSTRAP_PENDING_SECRET_FIELD];
+    const fingerprint = entry[BOOTSTRAP_PENDING_FINGERPRINT_FIELD];
+    if (typeof secret !== "string" || secret.trim().length === 0)
+        return null;
+    if (fingerprint !== inviteFingerprint)
+        return null;
+    return { keySecret: secret };
+}
+/**
+ * Does `bootstrap-pending:<repo>` hold a secret belonging to a DIFFERENT invite?
+ *
+ * `readMatchingPending` returning `null` conflates two very different states —
+ * "no record" (safe to write) and "some OTHER invite's record" (must not be
+ * touched). Every writer therefore asks this question separately, because that
+ * other record is the ONLY proof that can replay its redemption: if its exchange
+ * already succeeded, overwriting it strands an admin key that no one can recover.
+ *
+ * Deliberately NOT gated on `allowOverwriteExistingCredential` — `--force` is
+ * consent to replace this repo's own `bapi:<repo>` credential, never consent to
+ * strand a key minted under someone else's invite.
+ *
+ * A record with no usable secret has nothing at stake and is not a conflict; a
+ * record carrying a secret but no matching fingerprint is (we cannot prove it is
+ * ours, so we fail closed).
+ */
+function hasConflictingPending(store, repoName, inviteFingerprint) {
+    const entry = store[getBootstrapPendingTarget(repoName)];
+    if (!entry)
+        return false;
+    const secret = entry[BOOTSTRAP_PENDING_SECRET_FIELD];
+    if (typeof secret !== "string" || secret.trim().length === 0)
+        return false;
+    return entry[BOOTSTRAP_PENDING_FINGERPRINT_FIELD] !== inviteFingerprint;
+}
+/** One wording for the conflict, so `prepare` and `repoint` cannot drift apart. */
+function pendingConflictError(target, primaryPath) {
+    return (`A pending bootstrap-invite credential for a DIFFERENT invite already exists at ${target} ` +
+        `in ${primaryPath}. It is the only proof that can replay that redemption, so it will not be ` +
+        "overwritten. Complete that redemption first, or — only if you are certain its invite was " +
+        "never exchanged — remove the entry from the store by hand.");
+}
+/**
+ * Generate (or REUSE) the bootstrap `key_secret` and durably persist it as a
+ * pending record — the caller must do this BEFORE calling the exchange.
+ *
+ * Reuse is what makes a retry idempotent: re-POSTing the exact same `key_secret`
+ * hits the server's replay branch and returns the same project and the same key.
+ * So a matching pending record (same invite fingerprint + repo) is reused
+ * verbatim and the CSPRNG is not invoked at all.
+ *
+ * A fresh record is written through {@link durablyReplaceCredentialStoreJson}, so
+ * a failed write or fsync produces a failure result and NO success value — the
+ * caller cannot proceed to the exchange with a secret that is not on disk.
+ */
+export async function prepareBootstrapPendingCredential(params, deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const repoName = (params.repoName ?? "").trim();
+    const fingerprint = (params.inviteFingerprint ?? "").trim();
+    const target = getBootstrapPendingTarget(repoName);
+    if (repoName.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-repo",
+            error: "Cannot prepare a bootstrap-invite credential: a non-empty repo name is required.",
+        };
+    }
+    if (fingerprint.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-fingerprint",
+            error: "Cannot prepare a bootstrap-invite credential: the invite fingerprint was empty.",
+        };
+    }
+    return withCredentialStoreLock(deps, async () => {
+        const loaded = await loadStoreForMutation(deps);
+        if (!loaded.ok) {
+            return { ok: false, path: primaryPath, target, kind: loaded.kind, error: loaded.error };
+        }
+        const base = loaded.base;
+        // Check the FINAL credential target before generating or writing anything:
+        // a redemption that would clobber an existing bapi:<repo> must stop here,
+        // while nothing has been consumed and nothing has been written.
+        if (hasExistingBapiKey(base, repoName) && !params.allowOverwriteExistingCredential) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target: getBapiTarget(repoName),
+                kind: "credential-conflict",
+                error: `A credential already exists for ${getBapiTarget(repoName)} in ${primaryPath}.`,
+            };
+        }
+        const existing = readMatchingPending(base, repoName, fingerprint);
+        if (existing) {
+            // Reuse verbatim — this exact value is the replay proof. Do not regenerate.
+            return { ok: true, path: primaryPath, target, keySecret: existing.keySecret, reused: true };
+        }
+        // Not ours, but someone's: redeeming a second invite against a repo that
+        // still holds a pending record for a first one would overwrite that record —
+        // and if the first exchange already succeeded, its admin key becomes
+        // unrecoverable. Stop before the CSPRNG runs and before anything is written.
+        if (hasConflictingPending(base, repoName, fingerprint)) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "pending-conflict",
+                error: pendingConflictError(target, primaryPath),
+            };
+        }
+        const keySecret = params.generateKeySecret();
+        const next = {
+            ...base,
+            [target]: {
+                ...(base[target] ?? {}),
+                [BOOTSTRAP_PENDING_SECRET_FIELD]: keySecret,
+                [BOOTSTRAP_PENDING_FINGERPRINT_FIELD]: fingerprint,
+            },
+        };
+        const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
+        if (!written.ok) {
+            return { ok: false, path: primaryPath, target, kind: written.kind, error: written.error };
+        }
+        return { ok: true, path: primaryPath, target, keySecret, reused: false };
+    }, (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error }));
+}
+/**
+ * Atomically move a pending record to a different repo name, preserving the exact
+ * same `key_secret` — used when the server answers `409 repo_name_taken` and the
+ * user picks a new name. Regenerating the secret here would silently discard the
+ * replay proof for the (still unconsumed) invite.
+ *
+ * On any failure the ORIGINAL pending record is left intact: the store is
+ * replaced in one durable write or not at all.
+ */
+export async function repointBootstrapPendingCredential(params, deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const fromRepo = (params.fromRepoName ?? "").trim();
+    const toRepo = (params.toRepoName ?? "").trim();
+    const fingerprint = (params.inviteFingerprint ?? "").trim();
+    const target = getBootstrapPendingTarget(toRepo);
+    if (fromRepo.length === 0 || toRepo.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-repo",
+            error: "Cannot re-point a bootstrap-invite credential: a non-empty repo name is required.",
+        };
+    }
+    return withCredentialStoreLock(deps, async () => {
+        const loaded = await loadStoreForMutation(deps);
+        if (!loaded.ok) {
+            return { ok: false, path: primaryPath, target, kind: loaded.kind, error: loaded.error };
+        }
+        const base = loaded.base;
+        const pending = readMatchingPending(base, fromRepo, fingerprint);
+        if (!pending) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "pending-missing",
+                error: `No pending bootstrap-invite credential for ${getBootstrapPendingTarget(fromRepo)} in ${primaryPath}.`,
+            };
+        }
+        if (toRepo === fromRepo) {
+            return { ok: true, path: primaryPath, target, keySecret: pending.keySecret };
+        }
+        if (hasExistingBapiKey(base, toRepo) && !params.allowOverwriteExistingCredential) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target: getBapiTarget(toRepo),
+                kind: "credential-conflict",
+                error: `A credential already exists for ${getBapiTarget(toRepo)} in ${primaryPath}.`,
+            };
+        }
+        // Refuse to clobber a pending record at the destination that belongs to a
+        // DIFFERENT invite — that would destroy another redemption's replay proof.
+        const destination = base[getBootstrapPendingTarget(toRepo)];
+        if (hasConflictingPending(base, toRepo, fingerprint)) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "pending-conflict",
+                error: pendingConflictError(target, primaryPath),
+            };
+        }
+        const next = { ...base };
+        delete next[getBootstrapPendingTarget(fromRepo)];
+        next[target] = {
+            ...(destination ?? {}),
+            [BOOTSTRAP_PENDING_SECRET_FIELD]: pending.keySecret,
+            [BOOTSTRAP_PENDING_FINGERPRINT_FIELD]: fingerprint,
+        };
+        const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
+        if (!written.ok) {
+            return { ok: false, path: primaryPath, target, kind: written.kind, error: written.error };
+        }
+        return { ok: true, path: primaryPath, target, keySecret: pending.keySecret };
+    }, (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error }));
+}
+/**
+ * Promote a pending record to the real `bapi:<repo>` credential — ONLY after the
+ * exchange returned 200. Removing the pending entry and writing `BAPI_API_KEY`
+ * happen in one durable replacement, so the secret is never absent from the store.
+ *
+ * The `bapi:<repo>` overwrite check is re-run HERE, under the lock, rather than
+ * trusting the preflight check in {@link prepareBootstrapPendingCredential}: a
+ * concurrent install could have written that credential in between.
+ *
+ * A failed promotion leaves the pending record intact, so the same replay proof is
+ * still available to a later run.
+ */
+export async function promoteBootstrapPendingCredential(params, deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const repoName = (params.repoName ?? "").trim();
+    const fingerprint = (params.inviteFingerprint ?? "").trim();
+    const target = getBapiTarget(repoName);
+    if (repoName.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-repo",
+            error: "Cannot promote a bootstrap-invite credential: a non-empty repo name is required.",
+        };
+    }
+    return withCredentialStoreLock(deps, async () => {
+        const loaded = await loadStoreForMutation(deps);
+        if (!loaded.ok) {
+            return { ok: false, path: primaryPath, target, kind: loaded.kind, error: loaded.error };
+        }
+        const base = loaded.base;
+        const pending = readMatchingPending(base, repoName, fingerprint);
+        if (!pending) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "pending-missing",
+                error: `No pending bootstrap-invite credential for ${getBootstrapPendingTarget(repoName)} in ${primaryPath}.`,
+            };
+        }
+        const hadKey = hasExistingBapiKey(base, repoName);
+        if (hadKey && !params.allowOverwriteExistingCredential) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "credential-conflict",
+                error: `A credential already exists for ${target} in ${primaryPath}.`,
+            };
+        }
+        const next = { ...base };
+        delete next[getBootstrapPendingTarget(repoName)];
+        // Preserve sibling secret names under bapi:<repo>; replace ONLY BAPI_API_KEY.
+        next[target] = { ...(base[target] ?? {}), BAPI_API_KEY: pending.keySecret };
+        const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
+        if (!written.ok) {
+            return { ok: false, path: primaryPath, target, kind: written.kind, error: written.error };
+        }
+        return { ok: true, path: primaryPath, target, action: hadKey ? "updated" : "created" };
+    }, (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error }));
+}
 /**
  * Upsert `BAPI_API_KEY` for `bapi:<repoName>` into the user-scoped PRIMARY
  * credential store, atomically (temp file + rename) and secret-safely.
@@ -338,66 +835,69 @@ export async function upsertBapiCredential(repoName, apiKey, deps) {
             error: `Cannot store BAPI_API_KEY for ${target}: the provided key was empty.`,
         };
     }
-    // Load the existing primary; if absent, seed from the legacy fallback store.
-    // NOTE: this load → merge → temp-write → rename sequence is NOT locked. It is
-    // safe because the writer only ever runs single-shot from the explicit
-    // install/migration paths; two genuinely concurrent upserts could last-writer-win
-    // and drop a sibling key. If a concurrent caller is ever added, introduce a lock.
-    const primary = await readCredentialStoreJsonIfPresent(primaryPath, deps);
-    let base;
-    let migratedFallback = false;
-    if (primary.state === "error") {
-        return { ok: false, path: primaryPath, target, kind: primary.kind, error: primary.error };
-    }
-    if (primary.state === "present") {
-        base = { ...primary.value };
-    }
-    else {
-        const seeded = await mergeFallbackCredentialStoreOnFirstPrimaryWrite(deps);
-        base = seeded.base;
-        migratedFallback = seeded.migratedFallback;
-    }
-    const existingEntry = base[target];
-    const hadKey = !!existingEntry &&
-        typeof existingEntry.BAPI_API_KEY === "string" &&
-        existingEntry.BAPI_API_KEY.length > 0;
-    const action = hadKey ? "updated" : "created";
-    // Preserve sibling secret names; replace ONLY BAPI_API_KEY.
-    const nextEntry = { ...(existingEntry ?? {}), BAPI_API_KEY: trimmedKey };
-    const next = { ...base, [target]: nextEntry };
-    const dir = path.dirname(primaryPath);
-    const suffix = (deps.tempSuffix ?? defaultTempSuffix)();
-    const tempPath = path.join(dir, `${path.basename(primaryPath)}.${suffix}.tmp`);
-    const json = formatCredentialStoreJson(next);
-    const isPosix = deps.platform !== "win32";
-    try {
-        await deps.mkdir(dir, { recursive: true });
-        const writeOptions = isPosix
-            ? { encoding: "utf-8", mode: 0o600 }
-            : { encoding: "utf-8" };
-        await deps.writeFile(tempPath, json, writeOptions);
-        if (isPosix) {
-            await deps.chmod(tempPath, 0o600);
+    // The load → merge → temp-write → rename sequence below is a read-modify-write:
+    // two concurrent upserts could last-writer-win and drop a sibling key. BAPI-606
+    // added concurrent callers (the bootstrap-invite pending/promote operations), so
+    // it now runs under the shared credential-store lock. When `deps.open` is absent
+    // (older builders / in-memory test doubles) there is no lock primitive available
+    // and the body runs exactly as it did before — unlocked and best-effort.
+    return withCredentialStoreLock(deps, async () => {
+        const primary = await readCredentialStoreJsonIfPresent(primaryPath, deps);
+        let base;
+        let migratedFallback = false;
+        if (primary.state === "error") {
+            return { ok: false, path: primaryPath, target, kind: primary.kind, error: primary.error };
         }
-        await deps.rename(tempPath, primaryPath);
-    }
-    catch {
-        // Best-effort temp cleanup; never surface the secret or the raw I/O message.
-        if (deps.unlink) {
-            try {
-                await deps.unlink(tempPath);
+        if (primary.state === "present") {
+            base = { ...primary.value };
+        }
+        else {
+            const seeded = await mergeFallbackCredentialStoreOnFirstPrimaryWrite(deps);
+            base = seeded.base;
+            migratedFallback = seeded.migratedFallback;
+        }
+        const existingEntry = base[target];
+        const hadKey = !!existingEntry &&
+            typeof existingEntry.BAPI_API_KEY === "string" &&
+            existingEntry.BAPI_API_KEY.length > 0;
+        const action = hadKey ? "updated" : "created";
+        // Preserve sibling secret names; replace ONLY BAPI_API_KEY.
+        const nextEntry = { ...(existingEntry ?? {}), BAPI_API_KEY: trimmedKey };
+        const next = { ...base, [target]: nextEntry };
+        const dir = path.dirname(primaryPath);
+        const suffix = (deps.tempSuffix ?? defaultTempSuffix)();
+        const tempPath = path.join(dir, `${path.basename(primaryPath)}.${suffix}.tmp`);
+        const json = formatCredentialStoreJson(next);
+        const isPosix = deps.platform !== "win32";
+        try {
+            await deps.mkdir(dir, { recursive: true });
+            const writeOptions = isPosix
+                ? { encoding: "utf-8", mode: 0o600 }
+                : { encoding: "utf-8" };
+            await deps.writeFile(tempPath, json, writeOptions);
+            if (isPosix) {
+                await deps.chmod(tempPath, 0o600);
             }
-            catch {
-                /* cleanup failure must not mask the primary write error */
+            await deps.rename(tempPath, primaryPath);
+        }
+        catch {
+            // Best-effort temp cleanup; never surface the secret or the raw I/O message.
+            if (deps.unlink) {
+                try {
+                    await deps.unlink(tempPath);
+                }
+                catch {
+                    /* cleanup failure must not mask the primary write error */
+                }
             }
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "write-error",
+                error: `Failed to write credentials file at ${primaryPath}.`,
+            };
         }
-        return {
-            ok: false,
-            path: primaryPath,
-            target,
-            kind: "write-error",
-            error: `Failed to write credentials file at ${primaryPath}.`,
-        };
-    }
-    return { ok: true, path: primaryPath, target, action, migratedFallback };
+        return { ok: true, path: primaryPath, target, action, migratedFallback };
+    }, (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error }));
 }