@bridge_gpt/mcp-server 0.2.20 → 0.2.23

package/build/install-bridge.js

@@ -28,13 +28,34 @@
  * reload the just-written `.mcp.json`, and field derivation needs an agent
  * runtime the shell does not have.
  *
- * SECRET DISCIPLINE: the API key is NEVER printed or logged — not in stdout,
- * stderr, error messages, or --dry-run output (it is redacted to `<REDACTED>`).
- * The ONLY place the key is durably written is the per-host MCP config (Step 3,
- * gitignored) and the user-scoped credential store (Step 4).
+ * BOOTSTRAP-INVITE MODE (BAPI-606) — the one exception to "this command consumes
+ * a key, it does not create one". With `--invite` (or `BAPI_INVITE`) there is no
+ * API key yet, so the pre-flight ping of Step 2 CANNOT be made: the exchange is
+ * what mints the key, and it REPLACES that ping. The order becomes:
+ *
+ *   resolve bootstrap-invite token (no-echo prompt by DEFAULT — the delivered
+ *   one-liner is secret-free) → resolve repo name → scaffold → generate
+ *   `key_secret` (CSPRNG) and **fsync it to a pending credential record** →
+ *   `POST <base>/setup/bootstrap` {token, repo_name, key_secret} → ping with the
+ *   newly-minted key → write host configs → promote pending → `bapi:<repo>` →
+ *   spawn. Everything from the ping onward is the existing flow, unchanged.
+ *
+ * The persist-before-exchange ordering is LOAD-BEARING PROTOCOL (see the comment
+ * at the pending-preparation call site): the local `key_secret` is the ONLY proof
+ * that can replay a redemption, so a successful exchange with a failed local write
+ * would leave an unrecoverable admin key and a permanently spent invite.
+ *
+ * SECRET DISCIPLINE: THREE secrets now — the API key, the bootstrap-invite token,
+ * and the client-generated `key_secret`. NONE is ever printed or logged — not in
+ * stdout, stderr, error messages, or --dry-run output (they are redacted to
+ * `<REDACTED>`). The ONLY places a secret is durably written are the per-host MCP
+ * config (Step 3, gitignored) and the user-scoped credential store (Step 4 / the
+ * pending record). The bootstrap-invite token itself is NEVER written to disk —
+ * only a SHA-256 fingerprint of it, to key the pending record.
  */
-import { readFile, writeFile, mkdir, stat, rename, chmod, unlink } from "fs/promises";
+import { readFile, writeFile, mkdir, stat, rename, chmod, unlink, open } from "fs/promises";
 import { spawn } from "child_process";
+import { randomBytes as cryptoRandomBytes, createHash } from "crypto";
 import os from "os";
 import path from "path";
 import readline from "readline";
@@ -42,7 +63,7 @@ import { runInit, buildBridgeApiEntry } from "./init.js";
 import { VERSION } from "./version.generated.js";
 import { validateRepoName } from "./bridge-config.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
-import { upsertBapiCredential, getPrimaryCredentialStorePath, } from "./credential-store.js";
+import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, } from "./credential-store.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, } from "./start-tickets.js";
 /** Redaction sentinel — the API-key value is NEVER printed; this stands in. */
@@ -92,33 +113,60 @@ export function getInstallBridgeUsage() {
         "  --api-key <key>   Bridge API key. Falls back to the BAPI_API_KEY env var,",
         "                    then an interactive (no-echo) prompt. Generate one in the",
         "                    Bridge API web UI Security page — this command consumes a",
-        "                    key, it does not create one. NEVER printed or logged.",
+        "                    key, it does not create one (--invite is the one exception:",
+        "                    it CREATES the project and its first admin key). NEVER",
+        "                    printed or logged.",
         "  --repo <name>     Repository name. Falls back to BAPI_REPO_NAME, then an",
         "                    inferred default you confirm interactively. MUST match the",
         "                    server-side repo registration (it keys the credential",
         "                    store as bapi:<repo>). Required (no inference) when stdin",
-        "                    is non-interactive.",
+        "                    is non-interactive. With --invite it is the name your NEW",
+        "                    project is created under (globally unique).",
+        "",
+        "Bootstrap-invite onboarding (no web UI, no pre-existing key):",
+        "  --invite [token]  Redeem a bootstrap invite: creates the project and mints",
+        "                    your own admin API key in one command. Mutually exclusive",
+        "                    with --api-key (in this mode the key is created, not",
+        "                    consumed).",
+        "",
+        "                    Run it WITHOUT a value — `install-bridge --invite` — and the",
+        "                    token is read from an interactive prompt with echo",
+        "                    suppressed, then sent only in the request body. This is the",
+        "                    default and the recommended path: 'a copy/paste one-liner'",
+        "                    and 'the token never touches shell history' are",
+        "                    contradictory, so the one-liner your operator sends you is",
+        "                    SECRET-FREE and the CLI asks for the token.",
+        "",
+        "                    Passing the token inline (--invite <token>, --invite=<token>)",
+        "                    or via BAPI_INVITE is for SCRIPTING ONLY: both forms EXPOSE",
+        "                    THE TOKEN to your shell history and to the process list.",
         "",
         "Flags:",
         "  --force                       Overwrite an existing real BAPI_API_KEY in a",
-        "                                host config without prompting.",
+        "                                host config (or in the credential store) without",
+        "                                prompting.",
         "  --dry-run                     Preview every step (scaffold targets, config",
         "                                files + keys with the key REDACTED, ping",
         "                                target, credential target, spawn command)",
         "                                without writing, pinging, or spawning anything.",
+        "                                With --invite it also never calls the exchange",
+        "                                endpoint and never generates or stores a secret.",
         "  --agent claude|cursor-agent   Agent to launch for the agentic remainder",
         "                                (default: claude).",
         "  -h, --help                    Show this help.",
         "",
         "Environment: BAPI_BASE_URL (default https://bridgegpt-api.com) and BAPI_DOCS_DIR",
         "(default docs/tmp) are read from the environment with the shown fallbacks.",
+        "BAPI_INVITE supplies the bootstrap-invite token non-interactively (scripting",
+        "only — it is exposed to shell history; prefer the prompt).",
     ].join("\n");
 }
 /**
  * Parse argv strictly. Supports `--api-key`, `--repo`, `--agent` (each with a
- * `--flag value` or `--flag=value` form), the boolean `--force` / `--dry-run`,
- * and `-h`/`--help`. Unknown flags and positional args are rejected. The API key
- * value is captured but never echoed (no error message includes it).
+ * `--flag value` or `--flag=value` form), the OPTIONAL-value `--invite`, the
+ * boolean `--force` / `--dry-run`, and `-h`/`--help`. Unknown flags and positional
+ * args are rejected. The API-key and bootstrap-invite values are captured but
+ * never echoed (no error message includes either).
  */
 export function parseInstallBridgeArgs(argv) {
     if (argv.includes("-h") || argv.includes("--help")) {
@@ -129,6 +177,11 @@ export function parseInstallBridgeArgs(argv) {
     let force = false;
     let dryRun = false;
     let agentName = DEFAULT_AGENT_NAME;
+    let invite;
+    // Track SUPPLIED-ness separately from the values: `--invite` is legitimately
+    // valueless (prompt path) and `--api-key ""` is still a contradiction with it.
+    let inviteSupplied = false;
+    let apiKeySupplied = false;
     /** Read a `--flag value` or `--flag=value` value, advancing the index. */
     const readValue = (arg, flag, i) => {
         if (arg.startsWith(`${flag}=`)) {
@@ -154,9 +207,27 @@ export function parseInstallBridgeArgs(argv) {
             if ("error" in r)
                 return { status: "error", message: r.error };
             apiKey = r.value;
+            apiKeySupplied = true;
             i = r.nextIndex;
             continue;
         }
+        if (arg === "--invite" || arg.startsWith("--invite=")) {
+            inviteSupplied = true;
+            if (arg.startsWith("--invite=")) {
+                invite = arg.slice("--invite=".length);
+            }
+            else {
+                // OPTIONAL value: a bare `--invite` selects bootstrap-invite mode and the
+                // token is prompted for (no echo). Only a following non-flag token is
+                // consumed as the value — a bootstrap-invite token never starts with '-'.
+                const next = argv[i + 1];
+                if (typeof next === "string" && !next.startsWith("-")) {
+                    invite = next;
+                    i += 1;
+                }
+            }
+            continue;
+        }
         if (arg === "--repo" || arg.startsWith("--repo=")) {
             const r = readValue(arg, "--repo", i);
             if ("error" in r)
@@ -187,38 +258,92 @@ export function parseInstallBridgeArgs(argv) {
             message: `Unexpected positional argument: '${arg}'. install-bridge does not accept positional arguments.`,
         };
     }
-    return { status: "ok", options: { apiKey, repo, force, dryRun, agentName } };
+    // Mutually exclusive by construction: bootstrap-invite mode CREATES the key, so
+    // consuming one is a contradiction. Names the flags only — never their values.
+    if (inviteSupplied && apiKeySupplied) {
+        return {
+            status: "error",
+            message: "--invite and --api-key are mutually exclusive: a bootstrap invite creates your API key, " +
+                "it does not consume an existing one.",
+        };
+    }
+    return {
+        status: "ok",
+        options: { apiKey, repo, force, dryRun, agentName, invite, inviteMode: inviteSupplied },
+    };
 }
-/** No-echo secret prompt on stderr (so it never lands in piped stdout). */
-function promptSecretViaReadline(promptText) {
+/**
+ * No-echo secret prompt on stderr (so it never lands in piped stdout).
+ *
+ * `input`/`output` are injectable for tests ONLY — production always uses the real
+ * stdin/stderr. They exist because this function is the one piece of the install
+ * flow that talks to a live terminal, and stubbing it out at the deps seam left the
+ * terminal behavior itself (prompt visibility, echo suppression) fully unverified.
+ */
+export function promptSecretViaReadline(promptText, input = process.stdin, output = process.stderr) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stderr,
+            input,
+            output,
             terminal: true,
         });
-        // Suppress echo of typed characters: override the internal writer so only the
-        // prompt (written explicitly below) is shown, never the keystrokes.
+        // The prompt MUST be owned by readline (passed to `question` below), never
+        // written to stderr by hand. On every redraw readline emits cursorTo(0) +
+        // clearScreenDown straight to `output`, bypassing the `_writeToOutput` hook
+        // — so a hand-written prompt is erased on the first redraw, leaving a blank
+        // line with muted echo that is indistinguishable from a hang.
+        //
+        // Echo suppression therefore works by reprinting the prompt and swallowing
+        // everything else: readline redraws the line as `prompt + typed input`, so a
+        // write containing the prompt is a redraw (reprint the prompt alone, drop the
+        // secret) and any other write is a keystroke echo (drop it).
         const mutable = rl;
         let muted = false;
         mutable._writeToOutput = (s) => {
-            if (!muted)
-                process.stderr.write(s);
+            if (!muted) {
+                output.write(s);
+            }
+            else if (s.includes(promptText)) {
+                output.write(promptText);
+            }
         };
-        process.stderr.write(promptText);
-        muted = true;
-        rl.question("", (answer) => {
+        // `close` fires without an answer when stdin hits EOF (piped/closed input).
+        // Resolving empty lets the caller emit its real "no key entered" error; left
+        // unresolved this promise deadlocks the top-level await and Node exits 13
+        // with only an "unsettled top-level await" warning.
+        //
+        // `answered` is load-bearing: `rl.close()` emits `close` SYNCHRONOUSLY, so on
+        // the happy path this handler runs before `resolve(answer)` below and would
+        // otherwise settle the promise empty — silently discarding the typed key.
+        let answered = false;
+        rl.on("close", () => {
+            if (!answered)
+                resolve("");
+        });
+        rl.question(promptText, (answer) => {
+            answered = true;
             rl.close();
-            process.stderr.write("\n");
+            output.write("\n");
             resolve(answer.trim());
         });
+        // Only mute AFTER `question` has drawn the prompt at full visibility.
+        muted = true;
     });
 }
 /** Echoed single-line prompt on stderr (used for repo confirmation / value). */
 function promptLineViaReadline(promptText) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        // See promptSecretViaReadline: EOF must resolve rather than deadlock the
+        // top-level await, and `answered` guards the synchronous `close` from
+        // discarding a real answer.
+        let answered = false;
+        rl.on("close", () => {
+            if (!answered)
+                resolve("");
+        });
         rl.question(promptText, (answer) => {
+            answered = true;
             rl.close();
             resolve(answer.trim());
         });
@@ -237,6 +362,9 @@ function spawnPrewarmDefault(command, args, env) {
     return new Promise((resolve) => {
         const sanitizedEnv = { ...env };
         delete sanitizedEnv.BAPI_API_KEY;
+        // The bootstrap-invite token is likewise never needed by a `--version` probe
+        // and must not reach an npm lifecycle script.
+        delete sanitizedEnv.BAPI_INVITE;
         try {
             const child = spawn(command, args, {
                 shell: false,
@@ -278,12 +406,24 @@ export function createDefaultInstallBridgeDeps() {
         rename: (a, b) => rename(a, b),
         chmod: (p, m) => chmod(p, m),
         unlink: (p) => unlink(p),
+        open: async (p, flags, mode) => {
+            const handle = await open(p, flags, mode);
+            return {
+                writeFile: (data) => handle.writeFile(data, { encoding: "utf-8" }),
+                sync: () => handle.sync(),
+                close: () => handle.close(),
+            };
+        },
+        randomBytes: (size) => cryptoRandomBytes(size),
         promptSecret: isTTY ? promptSecretViaReadline : undefined,
         promptLine: isTTY ? promptLineViaReadline : undefined,
         fetch: (...args) => fetch(...args),
         spawnPrewarm: spawnPrewarmDefault,
         runInit,
         upsertCredential: upsertBapiCredential,
+        prepareBootstrapPending: prepareBootstrapPendingCredential,
+        repointBootstrapPending: repointBootstrapPendingCredential,
+        promoteBootstrapPending: promoteBootstrapPendingCredential,
         buildShellCommand: buildGenericAgentShellCommand,
         spawnTerminalTab: getDefaultSpawnTerminalTabForPlatform(process.platform),
         startTicketsDeps: createDefaultStartTicketsDeps(),
@@ -316,6 +456,45 @@ export async function resolveApiKey(options, deps) {
             "(no interactive terminal is available to prompt for it).",
     };
 }
+/**
+ * Resolve the BOOTSTRAP-INVITE token: `--invite <token>` → `BAPI_INVITE` env →
+ * interactive no-echo prompt. Fails (secret-free) when none is available and
+ * stdin is non-interactive.
+ *
+ * The order mirrors {@link resolveApiKey}, but the EMPHASIS is inverted, and that
+ * inversion is the point: "a copy/paste one-liner" and "the token never touches
+ * shell history" are contradictory — both `--invite <token>` and
+ * `BAPI_INVITE=… npx …` land in shell history and in `ps`. So the one-liner an
+ * operator hands an invitee is SECRET-FREE (`install-bridge --invite`), and the
+ * no-echo prompt below is the DEFAULT path rather than a last-resort fallback. The
+ * token then travels only in the exchange request body. The inline/env forms remain
+ * for scripting and are documented as history-exposing.
+ *
+ * The token value is never echoed: not in the prompt, not in any error here.
+ */
+export async function resolveInviteToken(options, deps) {
+    if (typeof options.invite === "string" && options.invite.trim().length > 0) {
+        return { ok: true, value: options.invite.trim() };
+    }
+    const fromEnv = deps.env.BAPI_INVITE;
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+        return { ok: true, value: fromEnv.trim() };
+    }
+    if (deps.isTTY && deps.promptSecret) {
+        const entered = (await deps.promptSecret("Bootstrap invite token (input hidden): ")).trim();
+        if (entered.length > 0) {
+            return { ok: true, value: entered };
+        }
+        return { ok: false, error: "No bootstrap invite token entered." };
+    }
+    return {
+        ok: false,
+        error: "A bootstrap invite token is required. Pass --invite <token> or set the BAPI_INVITE " +
+            "environment variable (no interactive terminal is available to prompt for it). Note that " +
+            "both forms expose the token to your shell history and process list — prefer running " +
+            "'install-bridge --invite' interactively.",
+    };
+}
 /**
  * Resolve the repo name: `--repo` → `BAPI_REPO_NAME` env → inferred default
  * (from .bridge/config, else the cwd basename) confirmed interactively. Fails
@@ -518,11 +697,152 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
         message: `Connectivity check failed (HTTP ${resp.status}). Verify your repo, API key, and BAPI_BASE_URL.`,
     };
 }
+// ---------------------------------------------------------------------------
+// Bootstrap-invite exchange (BAPI-606) — replaces the pre-flight ping in invite mode
+// ---------------------------------------------------------------------------
+/** Bytes of CSPRNG entropy behind `key_secret` (server requires exactly 32). */
+export const BOOTSTRAP_KEY_SECRET_BYTES = 32;
+/**
+ * Generate the client-side `key_secret`: exactly 32 CSPRNG bytes, base64url,
+ * which yields exactly the 43 unpadded characters the server validates. The
+ * length is EXACT, not a floor — the server rejects 42 and 44, because ">= 43"
+ * had no upper bound and an over-72-byte input is a bcrypt-truncation hazard.
+ *
+ * The returned value is a SECRET. It is never logged, never previewed, and never
+ * placed in an error.
+ */
+export function generateBootstrapKeySecret(randomBytes) {
+    return randomBytes(BOOTSTRAP_KEY_SECRET_BYTES).toString("base64url");
+}
 /**
- * Render the --dry-run preview lines. The API key is ALWAYS redacted — the
- * spawnCommand and config preview never embed the secret.
+ * SHA-256 hex digest of the bootstrap-invite token — the key under which the
+ * pending record is stored. The TOKEN ITSELF IS NEVER WRITTEN TO DISK; only this
+ * one-way fingerprint, so a retry can recognize "same invite, same repo" and reuse
+ * the exact pending `key_secret` (the replay proof).
+ */
+export function fingerprintBootstrapInvite(token) {
+    return createHash("sha256").update(token, "utf-8").digest("hex");
+}
+/** The exchange endpoint: `<base>/setup/bootstrap`. No query string — ever. */
+export function buildBootstrapExchangeUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap`;
+}
+/**
+ * POST the bootstrap-invite exchange. The token and `key_secret` travel ONLY in
+ * the JSON request body (never a query string, never a header, never a log line).
+ * Bounded by the same 10s timeout as the connectivity ping.
+ */
+export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, keySecret) {
+    const url = buildBootstrapExchangeUrl(baseUrl);
+    let resp;
+    try {
+        resp = await deps.fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ token, repo_name: repoName, key_secret: keySecret }),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (err) {
+        // The message may contain the request (some fetch impls echo it), so it is
+        // deliberately NOT interpolated here.
+        void err;
+        return {
+            ok: false,
+            kind: "failed",
+            message: `Could not reach the Bridge API at ${baseUrl} to redeem the bootstrap invite. Check ` +
+                "BAPI_BASE_URL and your network, then re-run — the invite has not been used, and the " +
+                "re-run will reuse the same locally-stored secret.",
+        };
+    }
+    if (resp.ok) {
+        let repo;
+        try {
+            const body = (await resp.json());
+            repo = body?.repo_name;
+        }
+        catch {
+            return {
+                ok: false,
+                kind: "failed",
+                message: "The Bridge API returned an unreadable response to the bootstrap exchange.",
+            };
+        }
+        // Validate the authoritative name before it reaches a path, a config target, or
+        // the credential store.
+        const validated = validateRepoName(repo);
+        if (!validated.ok) {
+            return {
+                ok: false,
+                kind: "failed",
+                message: "The Bridge API returned an unexpected repo name for the bootstrap exchange.",
+            };
+        }
+        return { ok: true, repoName: validated.value };
+    }
+    if (resp.status === 409) {
+        return {
+            ok: false,
+            kind: "repo-name-taken",
+            message: `The repo name '${repoName}' is already taken (HTTP 409). Repo names are globally unique.`,
+        };
+    }
+    if (resp.status === 401) {
+        return { ok: false, kind: "invalid-invite", message: `The Bridge API rejected the bootstrap invite (HTTP ${resp.status}).` };
+    }
+    return {
+        ok: false,
+        kind: "failed",
+        message: `The bootstrap exchange failed (HTTP ${resp.status}). Verify BAPI_BASE_URL and try again.`,
+    };
+}
+/**
+ * The 401 message for a run that had to GENERATE a fresh secret — i.e. no local
+ * pending record existed. Besides a simply-wrong token, this is exactly what a lost
+ * `~/.config/bridge` looks like after a successful redemption: the retry sends a
+ * NEW secret, so the server's replay branch cannot match and correctly answers 401
+ * (letting a different secret replace the key would turn a spent token back into a
+ * bearer credential).
+ *
+ * The recovery is therefore NOT "re-run" and NOT "re-mint" — re-running sends
+ * another new secret and gets 401 again, and a fresh invite cannot reuse the repo
+ * name, which is globally unique and now taken by the project already created. Do
+ * not suggest either.
+ */
+export const BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE = [
+    "The Bridge API rejected the bootstrap invite (HTTP 401).",
+    "",
+    "Either the invite is invalid, expired, or revoked — or it was ALREADY redeemed from this",
+    "machine and the local secret has since been lost (e.g. ~/.config/bridge was deleted).",
+    "",
+    "If it was already redeemed, you cannot recover it yourself:",
+    "  • Re-running will NOT work: each run without the original local secret sends a new one,",
+    "    which cannot match what the server stored, so it will keep returning 401.",
+    "  • A new bootstrap invite will NOT work either: your repo name is globally unique and is",
+    "    now taken by the project you already created, so it cannot be redeemed again.",
+    "",
+    "Ask your Bridge API operator to recover it for you: they revoke the orphaned key",
+    "(DELETE /setup/keys/{id}) and issue a replacement key for the EXISTING project",
+    "(POST /setup/keys), then send you that key. Run install-bridge with --api-key <that key>.",
+].join("\n");
+/**
+ * The 401 message for a run that REUSED an existing pending secret — the replay
+ * proof was sent and still rejected, so the invite itself is not usable.
+ */
+export const BOOTSTRAP_INVITE_REJECTED_MESSAGE = "The Bridge API rejected the bootstrap invite (HTTP 401). The invite is invalid, expired, or " +
+    "revoked — ask your Bridge API operator for a new one. (Your locally-stored secret was sent " +
+    "unchanged, so this is not a lost-secret problem.)";
+/**
+ * Render the --dry-run preview lines. Every secret is ALWAYS redacted — the
+ * spawnCommand, config preview, and (in bootstrap-invite mode) the exchange body
+ * never embed the API key, the invite token, or the generated `key_secret`.
+ *
+ * The plan itself holds no secret and no invite fingerprint, so this function
+ * CANNOT leak one: in bootstrap-invite mode it is called before any secret exists.
  */
 export function buildDryRunPreview(plan) {
+    if (plan.bootstrapInvite)
+        return buildBootstrapDryRunPreview(plan);
     return [
         "install-bridge --dry-run (no writes, no network, no spawns)",
         `Repo name:        ${plan.repoName}`,
@@ -543,6 +863,40 @@ export function buildDryRunPreview(plan) {
         `Step 5 — spawn agent session: ${plan.spawnCommand}`,
     ];
 }
+/**
+ * Bootstrap-invite dry-run preview. A --dry-run must not consume the invite OR
+ * LEAVE STATE BEHIND: skipping the HTTP call is not enough — a preview that wrote
+ * a pending `key_secret` would have left credential material on disk for a
+ * redemption that never happened. So the caller returns here BEFORE the CSPRNG
+ * runs and before anything is written.
+ */
+function buildBootstrapDryRunPreview(plan) {
+    const pendingTarget = `bootstrap-pending:${plan.repoName}`;
+    return [
+        "install-bridge --invite --dry-run (no writes, no network, no spawns, no secret generated)",
+        `Repo name:        ${plan.repoName} (created by the exchange; globally unique)`,
+        `Base URL:         ${plan.baseUrl}`,
+        `Docs dir:         ${plan.docsDir}`,
+        `Agent:            ${plan.agentName}`,
+        "",
+        "Step 1 — scaffold (runInit): commands, agents, pipelines, .bridge/config, secret-free MCP placeholders.",
+        `Step 2a — generate key_secret (32 CSPRNG bytes) and fsync it to ${pendingTarget} at ${plan.credentialStorePath}`,
+        "          BEFORE the exchange. If that write fails the run ABORTS and no invite is spent.",
+        `Step 2b — redeem the bootstrap invite (replaces the pre-flight ping — there is no key yet):`,
+        `          POST ${plan.exchangeUrl}`,
+        `          body: {"token": "${REDACTED_API_KEY}", "repo_name": "${plan.repoName}", "key_secret": "${REDACTED_API_KEY}"}`,
+        `Step 2c — connectivity ping with the newly-minted key (before any durable key write): GET ${plan.pingUrl} (X-API-Key: ${REDACTED_API_KEY})`,
+        "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned):",
+        ...plan.configTargets.map((t) => `  ${t}: BAPI_REPO_NAME=${plan.repoName}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${plan.baseUrl}, BAPI_DOCS_DIR=${plan.docsDir}`),
+        ...(plan.manualEditors.length > 0
+            ? [`  ${plan.manualEditors.join(" + ")}: detected (global config) — manual setup instructions would be printed.`]
+            : []),
+        `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY / BAPI_INVITE removed): ${plan.prewarmCommand}`,
+        MCP_TIMEOUT_GUIDANCE,
+        `Step 4 — promote ${pendingTarget} → ${plan.credentialTarget} at ${plan.credentialStorePath} (only after the exchange succeeds)`,
+        `Step 5 — spawn agent session: ${plan.spawnCommand}`,
+    ];
+}
 /**
  * Detect global-config editors that install-bridge cannot safely write into
  * (their configs live outside the project). Windsurf is detected from the
@@ -621,21 +975,50 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 1;
     }
     const options = parsed.options;
+    // Bootstrap-invite mode: `--invite` (with or without a value), or a non-empty
+    // BAPI_INVITE. Everything below branches on this ONE flag; an invocation without
+    // it is the unchanged consume-a-key flow.
+    const bootstrapInviteMode = options.inviteMode === true || (deps.env.BAPI_INVITE ?? "").trim().length > 0;
     // ---- Resolve inputs (may prompt when interactive) ----
-    // Resolve the API key first so a fully-empty non-interactive invocation fails
-    // with the (more security-relevant) missing-key message before the repo one.
-    const keyResult = await resolveApiKey(options, deps);
-    if (!keyResult.ok) {
-        errorLog(`Error: ${keyResult.error}`);
-        return 1;
+    // Resolve the credential input first so a fully-empty non-interactive invocation
+    // fails with the (more security-relevant) missing-secret message before the repo
+    // one. In bootstrap-invite mode there is no API key to resolve — the exchange
+    // MINTS it — so resolveApiKey is skipped entirely.
+    let apiKey = "";
+    let inviteToken = "";
+    if (bootstrapInviteMode) {
+        const inviteResult = await resolveInviteToken(options, deps);
+        if (!inviteResult.ok) {
+            errorLog(`Error: ${inviteResult.error}`);
+            return 1;
+        }
+        inviteToken = inviteResult.value;
+    }
+    else {
+        const keyResult = await resolveApiKey(options, deps);
+        if (!keyResult.ok) {
+            errorLog(`Error: ${keyResult.error}`);
+            return 1;
+        }
+        apiKey = keyResult.value;
     }
-    const apiKey = keyResult.value;
     const repoResult = await resolveRepoName(options, deps);
     if (!repoResult.ok) {
         errorLog(`Error: ${repoResult.error}`);
         return 1;
     }
-    const repoName = repoResult.value;
+    let repoName = repoResult.value;
+    // Invite mode creates the project, so the name must be valid BEFORE any pending
+    // state or exchange. (Normal mode's name is already registered server-side, so
+    // its behavior is deliberately left untouched.)
+    if (bootstrapInviteMode) {
+        const validated = validateRepoName(repoName);
+        if (!validated.ok) {
+            errorLog(`Error: invalid repo name — ${validated.error}.`);
+            return 1;
+        }
+        repoName = validated.value;
+    }
     const baseUrl = deps.env.BAPI_BASE_URL ?? DEFAULT_BAPI_BASE_URL;
     const docsDir = deps.env.BAPI_DOCS_DIR ?? DEFAULT_BAPI_DOCS_DIR;
     const agent = resolveAgentSpec(options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
@@ -659,16 +1042,34 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         pingUrl: buildPingUrl(baseUrl, repoName),
         prewarmCommand: buildPrewarmCommandPreview(),
         spawnCommand,
+        ...(bootstrapInviteMode
+            ? { bootstrapInvite: true, exchangeUrl: buildBootstrapExchangeUrl(baseUrl) }
+            : {}),
     };
     // ---- --dry-run: preview every step, strictly no side effects ----
+    // Positioned BEFORE the CSPRNG, the pending write, the exchange, the scaffold,
+    // the config writes, the pre-warm, and the spawn: in bootstrap-invite mode a
+    // preview must neither consume the invite NOR leave a pending secret on disk.
     if (options.dryRun) {
         for (const line of buildDryRunPreview(plan))
             log(line);
         return 0;
     }
-    const entry = buildInstallBridgeServerEntry(deps.cwd, repoName, apiKey, baseUrl, docsDir);
+    const credentialWriteDeps = {
+        env: deps.env,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        mkdir: deps.mkdir,
+        writeFile: (p, d, o) => deps.writeFile(p, d, o),
+        rename: deps.rename,
+        chmod: deps.chmod,
+        unlink: deps.unlink,
+        open: deps.open,
+    };
     // ---- Overwrite consent: a real existing key requires --force or a prompt ----
     const hasRealKey = await detectExistingRealKey(deps, targets);
+    let overwriteConsent = options.force;
     if (hasRealKey && !options.force) {
         if (deps.isTTY && deps.promptLine) {
             const answer = (await deps.promptLine("A host config already contains a BAPI_API_KEY. Overwrite it? [y/N]: ")).trim().toLowerCase();
@@ -676,6 +1077,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 errorLog("Aborted: existing API key left unchanged (re-run with --force to overwrite).");
                 return 1;
             }
+            overwriteConsent = true;
         }
         else {
             errorLog("Error: a host config already contains a BAPI_API_KEY. Re-run with --force to overwrite it " +
@@ -686,18 +1088,165 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // ---- Step 1 — scaffold (secret-free placeholders only) ----
     log("Step 1/5 — scaffolding project (commands, agents, pipelines, config placeholders)…");
     await deps.runInit(deps.cwd);
-    // ---- Step 2 — verify connectivity BEFORE writing the key anywhere durable ----
+    // ---- Step 2 — mint (invite mode) or verify (normal mode) the credential ----
+    let inviteFingerprint = "";
+    if (bootstrapInviteMode) {
+        // ===================================================================
+        // LOAD-BEARING ORDERING — NOT DEFENSIVE POLISH. DO NOT "TIDY" THIS.
+        //
+        // The key_secret is generated HERE, fsynced to a pending record HERE, and
+        // only THEN sent to the exchange. That order is the protocol:
+        //
+        //   * The locally-stored key_secret is the ONLY proof that can replay a
+        //     redemption. The server's replay branch matches on (repo_name, bcrypt of
+        //     key_secret); it never returns a recoverable credential.
+        //   * So a successful exchange followed by a failed local write = an
+        //     unrecoverable admin key AND a permanently spent invite. The user cannot
+        //     re-run (a new secret gets a correct 401) and cannot re-mint (the repo
+        //     name is now globally taken by the project they just created); only an
+        //     operator can dig them out.
+        //
+        // Therefore the write is FAIL-CLOSED: if it does not land (including its
+        // fsync), we abort with a non-zero exit and NEVER call fetch. Nothing is
+        // consumed. Moving this persist after the exchange — the "natural" order —
+        // reintroduces exactly the bug above. (Contrast Step 4 in normal mode, which
+        // is deliberately fail-open: there, the key already exists server-side and a
+        // persist failure only degrades start-tickets routing.)
+        // ===================================================================
+        inviteFingerprint = fingerprintBootstrapInvite(inviteToken);
+        log("Step 2/5 — redeeming the bootstrap invite…");
+        let prepared = await deps.prepareBootstrapPending({
+            repoName,
+            inviteFingerprint,
+            generateKeySecret: () => generateBootstrapKeySecret(deps.randomBytes),
+            allowOverwriteExistingCredential: overwriteConsent,
+        }, credentialWriteDeps);
+        // An existing bapi:<repo> credential is never clobbered without consent. The
+        // gate mirrors the host-config gate above: --force, else an interactive prompt,
+        // else a hard non-interactive failure — all BEFORE the exchange.
+        if (!prepared.ok && prepared.kind === "credential-conflict") {
+            if (deps.isTTY && deps.promptLine) {
+                const answer = (await deps.promptLine(`The credential store already holds a key for ${prepared.target}. Overwrite it? [y/N]: `)).trim().toLowerCase();
+                if (answer !== "y" && answer !== "yes") {
+                    errorLog("Aborted: existing credential left unchanged (re-run with --force to overwrite).");
+                    return 1;
+                }
+                overwriteConsent = true;
+                prepared = await deps.prepareBootstrapPending({
+                    repoName,
+                    inviteFingerprint,
+                    generateKeySecret: () => generateBootstrapKeySecret(deps.randomBytes),
+                    allowOverwriteExistingCredential: true,
+                }, credentialWriteDeps);
+            }
+            else {
+                errorLog(`Error: ${prepared.error} Re-run with --force to overwrite it (refusing to overwrite a ` +
+                    "credential non-interactively without consent).");
+                return 1;
+            }
+        }
+        // A pending record left by a DIFFERENT invite is that redemption's only replay
+        // proof. Unlike the credential conflict above there is no consent path — not
+        // even --force — so re-running is not the fix and must not be advised.
+        if (!prepared.ok && prepared.kind === "pending-conflict") {
+            errorLog(`Error: ${prepared.error} This invite has NOT been used, and re-running will not clear ` +
+                "the conflict.");
+            return 1;
+        }
+        if (!prepared.ok) {
+            // Fail closed: the exchange has NOT been called, so the invite is unspent.
+            errorLog(`Error: could not durably store the bootstrap credential (${prepared.kind}). ${prepared.error} ` +
+                "The bootstrap invite has NOT been used — fix the problem and re-run.");
+            return 1;
+        }
+        const keySecret = prepared.keySecret;
+        const reusedPendingSecret = prepared.reused;
+        log(`  saved the pending credential for ${prepared.target} (fsynced before the exchange)`);
+        // The exchange REPLACES the pre-flight ping: in invite mode there is no key to
+        // ping with — this call is what mints it.
+        let exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+        // 409 repo_name_taken: the server ROLLED BACK, so the invite is NOT consumed and
+        // the SAME token can be retried under a new name — with the SAME pending secret,
+        // re-pointed to that name.
+        while (!exchange.ok && exchange.kind === "repo-name-taken") {
+            if (!deps.isTTY || !deps.promptLine) {
+                errorLog(`Error: ${exchange.message} Re-run with a different --repo (the bootstrap invite has NOT ` +
+                    "been used).");
+                return 1;
+            }
+            errorLog(exchange.message);
+            const answer = (await deps.promptLine("Choose a different repo name: ")).trim();
+            const validated = validateRepoName(answer);
+            if (!validated.ok) {
+                errorLog(`Error: invalid repo name — ${validated.error}.`);
+                return 1;
+            }
+            const nextRepo = validated.value;
+            const repointed = await deps.repointBootstrapPending({
+                fromRepoName: repoName,
+                toRepoName: nextRepo,
+                inviteFingerprint,
+                allowOverwriteExistingCredential: overwriteConsent,
+            }, credentialWriteDeps);
+            if (!repointed.ok) {
+                errorLog(`Error: could not re-point the pending bootstrap credential to '${nextRepo}' ` +
+                    `(${repointed.kind}). ${repointed.error} The bootstrap invite has NOT been used.`);
+                return 1;
+            }
+            repoName = nextRepo;
+            // Same token, same key_secret — never regenerated inside the rename loop.
+            exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+        }
+        if (!exchange.ok) {
+            if (exchange.kind === "invalid-invite") {
+                errorLog(reusedPendingSecret
+                    ? BOOTSTRAP_INVITE_REJECTED_MESSAGE
+                    : BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE);
+            }
+            else {
+                errorLog(`Error: ${exchange.message}`);
+            }
+            // The pending record is deliberately LEFT INTACT: it is the replay proof for a
+            // retry (network failure / transient error), and destroying it would be the
+            // unrecoverable case above.
+            return 1;
+        }
+        // The server-returned name is authoritative from here on: config, ping,
+        // credential target, and the spawned session all key off it.
+        if (exchange.repoName !== repoName) {
+            const repointed = await deps.repointBootstrapPending({
+                fromRepoName: repoName,
+                toRepoName: exchange.repoName,
+                inviteFingerprint,
+                allowOverwriteExistingCredential: overwriteConsent,
+            }, credentialWriteDeps);
+            if (!repointed.ok) {
+                errorLog(`Error: the project was created as '${exchange.repoName}' but the pending credential could ` +
+                    `not be re-pointed to it (${repointed.kind}). ${repointed.error}`);
+                return 1;
+            }
+            repoName = exchange.repoName;
+        }
+        log(`  bootstrap invite redeemed — project '${repoName}' is ready`);
+        // The minted key. From here the flow rejoins the existing path unchanged.
+        apiKey = keySecret;
+    }
+    // ---- Step 2 (cont.) — verify connectivity BEFORE writing the key anywhere durable ----
     // R5: ping before persisting anything durably. Pinging before writeHostConfigs
     // (and the credential store) means a bad key on a first-time install halts
     // WITHOUT leaving an invalid key in the config — which would otherwise trip the
-    // overwrite-consent gate on every retry (a trapped state).
-    log("Step 2/5 — verifying connectivity…");
+    // overwrite-consent gate on every retry (a trapped state). In invite mode this
+    // runs AFTER the exchange, with the just-minted key; the pending record is the one
+    // deliberate write that precedes it, for the protocol reason above.
+    if (!bootstrapInviteMode)
+        log("Step 2/5 — verifying connectivity…");
     const ping = await verifyConnectivity(deps, baseUrl, repoName, apiKey);
     if (!ping.ok) {
         errorLog(`Error: ${ping.message}`);
         return 1;
     }
     log("  connectivity OK");
+    const entry = buildInstallBridgeServerEntry(deps.cwd, repoName, apiKey, baseUrl, docsDir);
     // ---- Step 3 — write per-host MCP config with real values ----
     log("Step 3/5 — writing per-host MCP config…");
     const written = await writeHostConfigs(deps, targets, entry);
@@ -726,40 +1275,49 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         errorLog(`Warning: could not pre-warm the version-pinned launcher bucket${prewarm.warning ? ` (${prewarm.warning})` : ""}. ` +
             `The first MCP launch may pay a one-time cold install and could be slow. ${MCP_TIMEOUT_GUIDANCE}`);
     }
-    // ---- Step 4 — persist routing credential (non-blocking / fail-open) ----
-    log("Step 4/5 — persisting routing credential…");
-    try {
-        const writeDeps = {
-            env: deps.env,
-            homedir: deps.homedir,
-            platform: deps.platform,
-            readFile: deps.readFile,
-            mkdir: deps.mkdir,
-            writeFile: (p, d, o) => deps.writeFile(p, d, o),
-            rename: deps.rename,
-            chmod: deps.chmod,
-            unlink: deps.unlink,
-        };
-        const result = await deps.upsertCredential(repoName, apiKey, writeDeps);
-        if (result.ok) {
-            log(`  stored routing credential for ${result.target} at ${result.path}`);
+    // ---- Step 4 — persist the credential ----
+    if (bootstrapInviteMode) {
+        // FAIL-CLOSED (unlike normal mode below). The pending secret IS the minted admin
+        // key — if it never lands under bapi:<repo>, the user has a live key they cannot
+        // resolve. Promotion removes the pending record and writes the credential in one
+        // durable replacement; on failure the pending record survives so a re-run replays
+        // the same redemption. The agent session is NOT spawned until this succeeds.
+        log("Step 4/5 — promoting the bootstrap credential…");
+        const promoted = await deps.promoteBootstrapPending({ repoName, inviteFingerprint, allowOverwriteExistingCredential: overwriteConsent }, credentialWriteDeps);
+        if (!promoted.ok) {
+            errorLog(`Error: the project and API key were created, but the credential could not be stored ` +
+                `(${promoted.kind}). ${promoted.error} Your key is still saved locally as a pending ` +
+                "record — re-run install-bridge with the same bootstrap invite to finish (the redemption " +
+                "will replay and return the same key).");
+            return 1;
         }
-        else {
-            log(`  warning: could not persist the routing credential (${result.kind}). ` +
-                `start-tickets model routing may not resolve the key for ${plan.credentialTarget} ` +
-                "and will fail open to the premium/Opus tier (the most expensive) — " +
-                "set BAPI_API_KEY in the shell or re-run install-bridge, then verify with " +
+        log(`  stored routing credential for ${promoted.target} at ${promoted.path}`);
+    }
+    else {
+        // ---- persist routing credential (non-blocking / fail-open) ----
+        log("Step 4/5 — persisting routing credential…");
+        try {
+            const result = await deps.upsertCredential(repoName, apiKey, credentialWriteDeps);
+            if (result.ok) {
+                log(`  stored routing credential for ${result.target} at ${result.path}`);
+            }
+            else {
+                log(`  warning: could not persist the routing credential (${result.kind}). ` +
+                    `start-tickets model routing may not resolve the key for bapi:${repoName} ` +
+                    "and will fail open to the premium/Opus tier (the most expensive) — " +
+                    "set BAPI_API_KEY in the shell or re-run install-bridge, then verify with " +
+                    "'npx -y @bridge_gpt/mcp-server doctor'.");
+            }
+        }
+        catch {
+            // Fail-open: persistence is best-effort (mirrors Stage 6). The secret is never
+            // included in the warning.
+            log("  warning: could not persist the routing credential (unexpected error). " +
+                "start-tickets model routing may need BAPI_API_KEY in the shell and will fail open " +
+                "to the premium/Opus tier (the most expensive) until fixed — verify with " +
                 "'npx -y @bridge_gpt/mcp-server doctor'.");
         }
     }
-    catch {
-        // Fail-open: persistence is best-effort (mirrors Stage 6). The secret is never
-        // included in the warning.
-        log("  warning: could not persist the routing credential (unexpected error). " +
-            "start-tickets model routing may need BAPI_API_KEY in the shell and will fail open " +
-            "to the premium/Opus tier (the most expensive) until fixed — verify with " +
-            "'npx -y @bridge_gpt/mcp-server doctor'.");
-    }
     // ---- Step 5 — spawn a fresh agent session for the agentic remainder ----
     log(`Step 5/5 — opening a ${agent.name} session for /install-bridge + /learn-repository…`);
     const terminal = detectTerminal(undefined, deps.env);