@bridge_gpt/mcp-server 0.2.23 → 0.2.25

package/build/connect-github-api.js

@@ -0,0 +1,365 @@
+/**
+ * Bridge API access + polling primitives for the sessionless GitHub connect flow
+ * (BAPI-631).
+ *
+ * Split out from `connect-github.ts` so the standalone command and `install-bridge`
+ * share one implementation of the request contract, the lifecycle vocabulary, and the
+ * polling policy — rather than each growing its own slightly-different copy.
+ *
+ * Two rules shape everything here:
+ *
+ * 1. **Nothing secret is ever returned in a message.** Failures collapse to coarse,
+ *    enumerated categories. Fetch exception text, response bodies, headers, the state
+ *    nonce, the install URL, and the API key never reach a string a caller might print.
+ * 2. **A malformed success is a failure.** Responses are validated against explicit
+ *    unions; a 200 whose body does not match is rejected rather than guessed at, so a
+ *    server change can never be silently reinterpreted as a connection outcome.
+ */
+/** Statuses that end the flow — polling past one of these is pointless. */
+const TERMINAL_STATUSES = new Set([
+    "staged",
+    "awaiting-organization-approval",
+    "connected",
+    "expired",
+    "invalid",
+    "verification-failed",
+    "no-repositories",
+    "conflict",
+    "failed",
+]);
+const ALL_STATUSES = new Set([
+    "waiting",
+    ...TERMINAL_STATUSES,
+]);
+/** Per-request timeout. Generous enough for a cold server, short enough to retry. */
+const REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * POST JSON to a Bridge endpoint.
+ *
+ * The state nonce travels in the BODY, never the query string: query strings land in
+ * server access logs, proxy logs, and browser history in a way request bodies do not.
+ */
+async function postJson(deps, path, payload) {
+    let resp;
+    try {
+        resp = await deps.fetch(`${deps.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": deps.apiKey,
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        // Deliberately does not forward `e`: fetch exception text can echo the URL, which
+        // carries the state nonce.
+        const isTimeout = e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");
+        return { ok: false, kind: isTimeout ? "timeout" : "network" };
+    }
+    let body = null;
+    try {
+        body = await resp.json();
+    }
+    catch {
+        /* Non-JSON body. The status still classifies the outcome. */
+    }
+    return {
+        ok: true,
+        value: { status: resp.status, body, retryAfter: resp.headers.get("Retry-After") },
+    };
+}
+/** Map a non-2xx status to a coarse category. */
+function classifyStatus(status) {
+    if (status === 401 || status === 403)
+        return "unauthorized";
+    if (status === 404)
+        return "not-found";
+    return "server";
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function asNullableString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+// ---------------------------------------------------------------------------
+// Retry-After
+// ---------------------------------------------------------------------------
+/**
+ * Parse a `Retry-After` header to milliseconds.
+ *
+ * Handles both RFC forms — delta-seconds and an HTTP-date — and clamps the result to
+ * `remainingMs` so a server (or a bogus far-future date) can never push a wait past the
+ * caller's own deadline. Returns null for absent/unparseable/negative values.
+ */
+export function parseRetryAfterMs(header, remainingMs, nowMs) {
+    if (!header)
+        return null;
+    const trimmed = header.trim();
+    if (!trimmed)
+        return null;
+    const clamp = (ms) => {
+        if (!Number.isFinite(ms) || ms < 0)
+            return null;
+        return Math.min(ms, Math.max(0, remainingMs));
+    };
+    // delta-seconds
+    if (/^\d+$/.test(trimmed)) {
+        return clamp(Number(trimmed) * 1_000);
+    }
+    // HTTP-date
+    const parsed = Date.parse(trimmed);
+    if (Number.isNaN(parsed))
+        return null;
+    return clamp(parsed - nowMs);
+}
+// ---------------------------------------------------------------------------
+// Endpoints
+// ---------------------------------------------------------------------------
+/** Mint a CLI-origin connection code and its install URL. */
+export async function mintGithubConnection(deps, repoName) {
+    const res = await postJson(deps, "/setup/github/cli/connection-code", {
+        repo_name: repoName,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const state = asString(body?.state);
+    const installUrl = asString(body?.install_url);
+    const ttlSeconds = body?.ttl_seconds;
+    if (!body || !state || !installUrl || typeof ttlSeconds !== "number") {
+        return { ok: false, kind: "malformed" };
+    }
+    return { ok: true, value: { state, installUrl, ttlSeconds } };
+}
+function parseCandidates(value) {
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const raw of value) {
+        const rec = asRecord(raw);
+        const id = asString(rec?.github_repository_id);
+        const name = asString(rec?.github_repo_name);
+        // A candidate without a usable identity is a malformed response, not a candidate to
+        // silently drop — dropping it would show the user an incomplete picker.
+        if (!rec || !id || !name)
+            return null;
+        out.push({
+            github_repository_id: id,
+            github_repo_name: name,
+            github_repo_full_name: asNullableString(rec.github_repo_full_name),
+            owner: asNullableString(rec.owner),
+        });
+    }
+    return out;
+}
+/** Read one connection code's current lifecycle state. */
+export async function fetchGithubConnectionStatus(deps, repoName, state, nowMs = Date.now()) {
+    const res = await postJson(deps, "/setup/github/cli/status", {
+        repo_name: repoName,
+        state,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const status = asString(body?.status);
+    if (!body || !status || !ALL_STATUSES.has(status)) {
+        return { ok: false, kind: "malformed" };
+    }
+    const candidates = parseCandidates(body.candidates ?? []);
+    if (candidates === null)
+        return { ok: false, kind: "malformed" };
+    return {
+        ok: true,
+        value: {
+            status: status,
+            candidates,
+            githubRepoName: asNullableString(body.github_repo_name),
+            // A single read has no deadline of its own to clamp against; the poller applies
+            // its own bound. POLL_DEADLINE_MS is the widest a caller could honor.
+            retryAfterMs: parseRetryAfterMs(res.value.retryAfter, POLL_DEADLINE_MS, nowMs),
+        },
+    };
+}
+/** Bind one chosen repository. Sends no installation id — the server owns that. */
+export async function confirmGithubConnection(deps, repoName, state, githubRepositoryId) {
+    const res = await postJson(deps, "/setup/github/cli/confirm", {
+        repo_name: repoName,
+        state,
+        github_repository_id: githubRepositoryId,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const name = asString(body?.github_repo_name);
+    if (!body || body.status !== "connected" || !name) {
+        return { ok: false, kind: "malformed" };
+    }
+    return {
+        ok: true,
+        value: {
+            githubRepoName: name,
+            githubRepoFullName: asNullableString(body.github_repo_full_name),
+        },
+    };
+}
+/**
+ * Read whether GitHub is already configured for a project.
+ *
+ * Uses the existing authenticated install-manifest/capability surface — read-only, and
+ * unrelated to any in-flight connection attempt. `unavailable` is a real answer and is
+ * deliberately distinct from `unconfigured`: callers must be able to skip rather than
+ * fabricate "not configured" from a probe that simply failed.
+ */
+export async function fetchGithubConfigurationState(deps, repoName) {
+    let resp;
+    try {
+        resp = await deps.fetch(`${deps.baseUrl}/jira/config/install-manifest?repo_name=${encodeURIComponent(repoName)}`, {
+            headers: { "X-API-Key": deps.apiKey },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch {
+        return "unavailable";
+    }
+    if (resp.status !== 200)
+        return "unavailable";
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch {
+        return "unavailable";
+    }
+    const integrations = asRecord(body)?.integrations;
+    if (!Array.isArray(integrations))
+        return "unavailable";
+    for (const raw of integrations) {
+        const rec = asRecord(raw);
+        if (rec?.id !== "github_app")
+            continue;
+        if (typeof rec.is_configured !== "boolean")
+            return "unavailable";
+        return rec.is_configured ? "configured" : "unconfigured";
+    }
+    // The checklist is provider-scoped: GitHub is legitimately absent for a Bitbucket
+    // project. Absent is not "unconfigured" — there is nothing here to connect.
+    return "unavailable";
+}
+/**
+ * Slightly longer than the server's 15-minute code TTL, so an expiry is reported by the
+ * server as `expired` rather than guessed at by a local timeout.
+ */
+export const POLL_DEADLINE_MS = 15.5 * 60 * 1_000;
+/** Back off gently: quick early (the common case is fast), then settle. */
+const POLL_DELAYS_MS = [2_000, 3_000, 5_000];
+const MAX_JITTER_MS = 400;
+/**
+ * TRANSPORT faults worth retrying — the request never produced a response at all.
+ *
+ * Deliberately does NOT list "server": `postJson` only ever reports these two kinds,
+ * because any HTTP response (500 included) comes back as `ok: true` with a status. HTTP
+ * statuses are classified by {@link isRetryableStatus} instead; conflating the two is
+ * what previously let a plain 500 kill a poll.
+ */
+const RETRYABLE_TRANSPORT = new Set([
+    "network",
+    "timeout",
+]);
+/**
+ * Is this HTTP status worth retrying rather than surfacing?
+ *
+ * Every 5xx, not just 502/503: a 500 from a transient server-side hiccup (the /cli/status
+ * handler raises a bare 500 on a DB read failure) and a 504 gateway timeout are exactly
+ * as transient as a dropped packet, and the user's alternative is restarting the whole
+ * mint → browser → poll flow. 429 is retried because it is literally a request to retry.
+ * 4xx is terminal: the request itself is the problem, so repeating it cannot help.
+ */
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+/**
+ * Poll until a terminal status, an unrecoverable failure, or the deadline.
+ *
+ * Terminal statuses return immediately — including the failure ones. Waiting out a
+ * 15-minute deadline on a code the server already called `expired` would be theatre.
+ *
+ * Transient transport faults (network blips, timeouts, 502/503) are retried, because a
+ * dropped packet is not a failed connection. `Retry-After` is honored when the server
+ * sends it, including on a 429.
+ */
+export async function pollGithubConnection(deps, poll, repoName, state) {
+    const started = poll.now();
+    let attempt = 0;
+    for (;;) {
+        const elapsed = poll.now() - started;
+        const remaining = POLL_DEADLINE_MS - elapsed;
+        if (remaining <= 0)
+            return { ok: false, kind: "deadline" };
+        const res = await postJson(deps, "/setup/github/cli/status", {
+            repo_name: repoName,
+            state,
+        });
+        let waitMs = null;
+        if (!res.ok) {
+            if (!RETRYABLE_TRANSPORT.has(res.kind))
+                return { ok: false, kind: res.kind };
+        }
+        else if (res.value.status === 200) {
+            const body = asRecord(res.value.body);
+            const status = asString(body?.status);
+            if (!body || !status || !ALL_STATUSES.has(status)) {
+                return { ok: false, kind: "malformed" };
+            }
+            const candidates = parseCandidates(body.candidates ?? []);
+            if (candidates === null)
+                return { ok: false, kind: "malformed" };
+            const typed = status;
+            if (TERMINAL_STATUSES.has(typed)) {
+                return {
+                    ok: true,
+                    value: {
+                        status: typed,
+                        candidates,
+                        githubRepoName: asNullableString(body.github_repo_name),
+                        retryAfterMs: null,
+                    },
+                };
+            }
+            // `waiting` — honor server pacing if offered.
+            waitMs = parseRetryAfterMs(res.value.retryAfter, remaining, poll.now());
+        }
+        else if (isRetryableStatus(res.value.status)) {
+            waitMs = parseRetryAfterMs(res.value.retryAfter, remaining, poll.now());
+        }
+        else {
+            return { ok: false, kind: classifyStatus(res.value.status) };
+        }
+        if (waitMs === null) {
+            const base = POLL_DELAYS_MS[Math.min(attempt, POLL_DELAYS_MS.length - 1)];
+            waitMs = base + Math.floor(poll.jitter() * MAX_JITTER_MS);
+        }
+        attempt += 1;
+        // Never sleep past the deadline.
+        const capped = Math.min(waitMs, Math.max(0, POLL_DEADLINE_MS - (poll.now() - started)));
+        if (capped <= 0)
+            return { ok: false, kind: "deadline" };
+        await poll.sleep(capped);
+    }
+}