@paradigma-inc/flywheel 0.1.26 → 0.1.51

package/src/setup/shared/summary.mjs

@@ -0,0 +1,80 @@
+function uniqueSorted(values = []) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function aggregateFromAgentResults(agentResults = [], fieldName) {
+  return uniqueSorted(
+    agentResults.flatMap((result) =>
+      Array.isArray(result[fieldName]) ? result[fieldName] : [],
+    ),
+  );
+}
+
+export function aggregateSetupResult({
+  mode,
+  agentResults = [],
+  skippedSteps = [],
+  warnings = [],
+  reconciled = [],
+  nextSteps = [],
+} = {}) {
+  // "Skipped" hosts (for example unsupported CLI-mode hosts) should not fail
+  // the overall command; only explicit host-level failures should.
+  const anyFailed = agentResults.some((result) => result.success === false);
+
+  return {
+    mode,
+    agentResults,
+    touchedFiles: aggregateFromAgentResults(agentResults, "touchedFiles"),
+    skippedSteps: uniqueSorted([
+      ...skippedSteps,
+      ...aggregateFromAgentResults(agentResults, "skippedSteps"),
+    ]),
+    warnings: uniqueSorted([
+      ...warnings,
+      ...aggregateFromAgentResults(agentResults, "warnings"),
+    ]),
+    reconciled: uniqueSorted(reconciled),
+    nextSteps: uniqueSorted(nextSteps),
+    exitCode: anyFailed ? 4 : 0,
+  };
+}
+
+function renderAgentOutcome(agentResult) {
+  if (agentResult.success === false) {
+    return "failed";
+  }
+  if (
+    agentResult.status === "skipped" ||
+    (Array.isArray(agentResult.skippedSteps) &&
+      agentResult.skippedSteps.includes("unsupported-host"))
+  ) {
+    return "skipped";
+  }
+  return "success";
+}
+
+export function renderSetupSummary(setupResult) {
+  const lines = [
+    `Mode: ${setupResult.mode}`,
+    `Exit: ${setupResult.exitCode}`,
+  ];
+
+  for (const agentResult of setupResult.agentResults) {
+    lines.push(`Agent ${agentResult.agent}: ${renderAgentOutcome(agentResult)}`);
+  }
+
+  for (const filePath of setupResult.touchedFiles) {
+    lines.push(`Touched: ${filePath}`);
+  }
+
+  for (const reconciledLine of setupResult.reconciled || []) {
+    lines.push(`Reconciled: ${reconciledLine}`);
+  }
+
+  for (const nextStep of setupResult.nextSteps) {
+    lines.push(`Next: ${nextStep}`);
+  }
+
+  return lines;
+}

package/src/setup-auth.mjs

@@ -2,6 +2,8 @@ import crypto from "node:crypto";
 import http from "node:http";
 import { spawn } from "node:child_process";
 
+import { SetupInputUsageError } from "./setup/mode.mjs";
+
 const DEFAULT_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
 const MIN_POLL_DELAY_MS = 1000;
 const MAX_POLL_DELAY_MS = 10_000;
@@ -38,15 +40,36 @@ function resolveErrorMessage(payload, fallback) {
   if (!payload || typeof payload !== "object") {
     return fallback;
   }
+  // Preference order: the actionable, user-facing field first, then the
+  // short error code, then generic fields. Both top-level (direct OAuth
+  // shape) and FastAPI's `detail`-wrapped shape are consulted so the
+  // device-flow `access_denied` response
+  //   { "detail": { "error": "access_denied", "error_description": ... } }
+  // surfaces its real reason instead of the generic fallback.
+  const pickString = (value) =>
+    typeof value === "string" && value.trim() ? value.trim() : null;
+
+  const candidates = [
+    pickString(payload.error_description),
+    pickString(payload.reason),
+    pickString(payload.message),
+    pickString(payload.error),
+  ];
+
   const detail = payload.detail;
-  if (typeof detail === "string" && detail.trim()) {
-    return detail.trim();
+  if (typeof detail === "string") {
+    candidates.push(pickString(detail));
+  } else if (detail && typeof detail === "object") {
+    candidates.push(
+      pickString(detail.error_description),
+      pickString(detail.reason),
+      pickString(detail.message),
+      pickString(detail.error),
+    );
   }
-  if (detail && typeof detail === "object") {
-    const message = detail.message;
-    if (typeof message === "string" && message.trim()) {
-      return message.trim();
-    }
+
+  for (const candidate of candidates) {
+    if (candidate) return candidate;
   }
   return fallback;
 }
@@ -67,40 +90,57 @@ function nonEmptyString(value) {
   return candidate ? candidate : null;
 }
 
-async function redeemSetupExchangeToken({
-  baseUrl,
-  exchangeToken,
-  state,
-  redirectUri,
-}) {
-  const redeemUrl = new URL(
-    "/api/auth/mcp-api-keys/setup-exchange/redeem",
-    baseUrl,
-  );
-  const response = await fetch(redeemUrl, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      "Idempotency-Key": `setup-redeem:${state}`,
-    },
-    body: JSON.stringify({
-      exchange_token: exchangeToken,
-      state,
-      redirect_uri: redirectUri,
-    }),
-  });
-  const payload = await parseJsonResponse(response);
-  if (!response.ok) {
-    const detail = resolveErrorMessage(payload, "Setup exchange redemption failed.");
-    throw new Error(detail);
-  }
-  const key = nonEmptyString(payload?.key);
-  if (!key) {
-    throw new Error("Setup exchange response missing API key.");
+export function normalizeSetupAuthMode(value) {
+  const normalized = String(value || "auto")
+    .trim()
+    .toLowerCase();
+  if (
+    normalized === "auto" ||
+    normalized === "loopback" ||
+    normalized === "device"
+  ) {
+    return normalized;
   }
-  return { apiKey: key };
+  throw new Error("Auth mode must be one of: auto, loopback, device.");
 }
 
+// FLY-416: removed — legacy /setup-exchange/redeem replaced by RFC 8628 device
+// flow; /setup-exchange/redeem was unauthenticated (5-minute TTL only). Kept
+// as comment for one release cycle; delete in a follow-up.
+// async function redeemSetupExchangeToken({
+//   baseUrl,
+//   exchangeToken,
+//   state,
+//   redirectUri,
+// }) {
+//   const redeemUrl = new URL(
+//     "/api/auth/mcp-api-keys/setup-exchange/redeem",
+//     baseUrl,
+//   );
+//   const response = await fetch(redeemUrl, {
+//     method: "POST",
+//     headers: {
+//       "content-type": "application/json",
+//       "Idempotency-Key": `setup-redeem:${state}`,
+//     },
+//     body: JSON.stringify({
+//       exchange_token: exchangeToken,
+//       state,
+//       redirect_uri: redirectUri,
+//     }),
+//   });
+//   const payload = await parseJsonResponse(response);
+//   if (!response.ok) {
+//     const detail = resolveErrorMessage(payload, "Setup exchange redemption failed.");
+//     throw new Error(detail);
+//   }
+//   const key = nonEmptyString(payload?.key);
+//   if (!key) {
+//     throw new Error("Setup exchange response missing API key.");
+//   }
+//   return { apiKey: key };
+// }
+
 async function startSetupDeviceSession({
   baseUrl,
   keyName,
@@ -233,163 +273,238 @@ function launchBrowser(openUrl, url) {
 }
 
 export function resolveSetupAuthMode({ requestedMode, env = process.env }) {
-  const normalizedRequested = String(requestedMode || "auto")
-    .trim()
-    .toLowerCase();
+  // FLY-416: loopback mode is retired (legacy /setup-exchange/redeem is
+  // removed server-side). When the caller explicitly asks for "loopback"
+  // we still normalise it so downstream logic can surface a deterministic
+  // FLY-416 error from `acquireApiKeyViaBrowserBridge`. For any other mode
+  // (including `auto`), return "device" — the RFC 8628 device flow now
+  // handles both local and SSH sessions.
+  const normalizedRequested = normalizeSetupAuthMode(requestedMode);
+  void env;
 
   if (normalizedRequested === "device" || normalizedRequested === "loopback") {
     return normalizedRequested;
   }
-
-  const isRemoteShell =
-    nonEmptyString(env.SSH_CONNECTION) ||
-    nonEmptyString(env.SSH_CLIENT) ||
-    nonEmptyString(env.SSH_TTY);
-  return isRemoteShell ? "device" : "loopback";
+  return "device";
 }
 
-export async function acquireApiKeyViaBrowserBridge({
+export async function resolveSetupApiKey({
+  options = {},
   baseUrl,
-  keyName,
-  timeoutMs = DEFAULT_AUTH_TIMEOUT_MS,
-  openUrl = openUrlInBrowser,
-}) {
-  const state = crypto.randomUUID();
-
-  return await new Promise((resolve, reject) => {
-    let settled = false;
-    let timeout = null;
-    let server = null;
-    let callbackUrl = "";
-
-    const cleanup = () => {
-      if (timeout) {
-        clearTimeout(timeout);
-        timeout = null;
-      }
-      if (server) {
-        server.close();
-        server.closeAllConnections?.();
-        server.closeIdleConnections?.();
-        server = null;
-      }
-    };
-
-    const fail = (error) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(error);
+  resolveAuthMode = resolveSetupAuthMode,
+  acquireDeviceFlow = acquireApiKeyViaDeviceFlow,
+  acquireBrowserBridge = acquireApiKeyViaBrowserBridge,
+  keyNameFactory = () => `flywheel-setup-${crypto.randomBytes(3).toString("hex")}`,
+} = {}) {
+  // Check the value, not just property presence: callers like runCliSetupMode
+  // always forward `{apiKey, authMode}` to share one helper shape, so the
+  // property is present even when the user did not pass --api-key. Using
+  // Object.hasOwn here would treat the implicit `undefined` as an explicit
+  // empty key and throw, blocking the default device/loopback auth path.
+  if (options.apiKey !== undefined && options.apiKey !== null) {
+    const normalizedApiKey = String(options.apiKey).trim();
+    if (normalizedApiKey.length === 0) {
+      // Tagged as a usage error so callers (runCliSetupMode's catch in
+      // particular) can propagate it instead of reshaping it into a
+      // per-host setup failure. This keeps --mode cli and --mode mcp
+      // consistent: both exit 1 with the same validation message.
+      throw new SetupInputUsageError("--api-key cannot be empty.");
+    }
+    return {
+      apiKey: normalizedApiKey,
+      authMode: null,
     };
+  }
 
-    const succeed = (result) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      resolve(result);
-    };
+  const requestedAuthMode = normalizeSetupAuthMode(options.authMode || "auto");
+  const resolvedAuthMode = resolveAuthMode({
+    requestedMode: requestedAuthMode,
+  });
 
-    server = http.createServer(async (req, res) => {
-      const reqUrl = new URL(req.url || "/", "http://127.0.0.1");
-      if (reqUrl.pathname !== "/callback") {
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("Not Found");
-        return;
-      }
-
-      const callbackState = (reqUrl.searchParams.get("state") || "").trim();
-      const exchangeToken = (
-        reqUrl.searchParams.get("exchange_token") || ""
-      ).trim();
-      const error = (reqUrl.searchParams.get("error") || "").trim();
-
-      if (callbackState !== state) {
-        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
-        res.end(
-          renderCallbackPage({
-            ok: false,
-            message: "State mismatch. Please retry setup.",
-          }),
-        );
-        fail(new Error("Setup callback state mismatch."));
-        return;
-      }
-
-      if (error) {
-        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
-        res.end(renderCallbackPage({ ok: false, message: error }));
-        fail(new Error(error));
-        return;
-      }
-
-      if (!exchangeToken) {
-        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
-        res.end(
-          renderCallbackPage({
-            ok: false,
-            message: "No setup exchange token was returned.",
-          }),
-        );
-        fail(new Error("Setup callback missing exchange token."));
-        return;
-      }
-
-      let redeemed;
-      try {
-        redeemed = await redeemSetupExchangeToken({
+  const keyName = keyNameFactory();
+  const authResult =
+    resolvedAuthMode === "device"
+      ? await acquireDeviceFlow({
+          baseUrl,
+          keyName,
+          verificationBaseUrl: baseUrl,
+        })
+      : await acquireBrowserBridge({
           baseUrl,
-          exchangeToken,
-          state,
-          redirectUri: callbackUrl,
+          keyName,
         });
-      } catch (err) {
-        const message =
-          err instanceof Error ? err.message : "Failed to redeem setup exchange.";
-        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
-        res.end(renderCallbackPage({ ok: false, message }));
-        fail(new Error(message));
-        return;
-      }
-
-      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-      res.end(
-        renderCallbackPage({
-          ok: true,
-          message: "Flywheel MCP was authorized successfully.",
-        }),
-      );
-      succeed({ apiKey: redeemed.apiKey });
-    });
-
-    server.once("error", (error) => {
-      fail(error);
-    });
-
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        fail(new Error("Failed to allocate local callback port."));
-        return;
-      }
 
-      callbackUrl = `http://127.0.0.1:${address.port}/callback`;
-      const setupUrl = new URL("/auth/mcp/setup", baseUrl);
-      setupUrl.searchParams.set("state", state);
-      setupUrl.searchParams.set("redirect_uri", callbackUrl);
-      setupUrl.searchParams.set("name", keyName);
-
-      console.log("Opening browser for Flywheel login and key creation...");
-      console.log(`If it does not open, use this URL:\n${setupUrl.toString()}\n`);
+  const normalizedResultApiKey = String(authResult?.apiKey || "").trim();
+  if (!normalizedResultApiKey) {
+    throw new Error("Authentication response did not include an API key.");
+  }
 
-      launchBrowser(openUrl, setupUrl.toString());
-    });
+  return {
+    apiKey: normalizedResultApiKey,
+    authMode: resolvedAuthMode,
+  };
+}
 
-    timeout = setTimeout(() => {
-      fail(new Error("Timed out waiting for browser authorization."));
-    }, timeoutMs);
-  });
+// FLY-416: loopback / browser-bridge flow routed through the now-inerted
+// /setup-exchange/redeem server endpoint. The RFC 8628 device flow (see
+// `acquireApiKeyViaDeviceFlow`) replaces it. The exported symbol stays so
+// existing callers still resolve at import time, but invoking it throws a
+// FLY-416 error instructing operators to use device or auto mode.
+export async function acquireApiKeyViaBrowserBridge(_args) {
+  // Keep the remediation flag in lockstep with `src/cli.mjs` — it advertises
+  // `--auth-mode <mode>`, not `--auth`. Pointing operators at the wrong flag
+  // makes this error a dead end.
+  throw new Error(
+    "FLY-416: loopback (browser-bridge) auth has been removed. " +
+      "Re-run with --auth-mode device (or --auth-mode auto) to use the " +
+      "RFC 8628 device flow. See docs/flywheel/CLI_STAGING_ACCESS.md for " +
+      "the full CLI auth contract.",
+  );
 }
 
+// FLY-416: legacy loopback implementation (commented — delete in a follow-up):
+// export async function acquireApiKeyViaBrowserBridge({
+//   baseUrl,
+//   keyName,
+//   timeoutMs = DEFAULT_AUTH_TIMEOUT_MS,
+//   openUrl = openUrlInBrowser,
+// }) {
+//   const state = crypto.randomUUID();
+//
+//   return await new Promise((resolve, reject) => {
+//     let settled = false;
+//     let timeout = null;
+//     let server = null;
+//     let callbackUrl = "";
+//
+//     const cleanup = () => {
+//       if (timeout) {
+//         clearTimeout(timeout);
+//         timeout = null;
+//       }
+//       if (server) {
+//         server.close();
+//         server.closeAllConnections?.();
+//         server.closeIdleConnections?.();
+//         server = null;
+//       }
+//     };
+//
+//     const fail = (error) => {
+//       if (settled) return;
+//       settled = true;
+//       cleanup();
+//       reject(error);
+//     };
+//
+//     const succeed = (result) => {
+//       if (settled) return;
+//       settled = true;
+//       cleanup();
+//       resolve(result);
+//     };
+//
+//     server = http.createServer(async (req, res) => {
+//       const reqUrl = new URL(req.url || "/", "http://127.0.0.1");
+//       if (reqUrl.pathname !== "/callback") {
+//         res.writeHead(404, { "Content-Type": "text/plain" });
+//         res.end("Not Found");
+//         return;
+//       }
+//
+//       const callbackState = (reqUrl.searchParams.get("state") || "").trim();
+//       const exchangeToken = (
+//         reqUrl.searchParams.get("exchange_token") || ""
+//       ).trim();
+//       const error = (reqUrl.searchParams.get("error") || "").trim();
+//
+//       if (callbackState !== state) {
+//         res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+//         res.end(
+//           renderCallbackPage({
+//             ok: false,
+//             message: "State mismatch. Please retry setup.",
+//           }),
+//         );
+//         fail(new Error("Setup callback state mismatch."));
+//         return;
+//       }
+//
+//       if (error) {
+//         res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+//         res.end(renderCallbackPage({ ok: false, message: error }));
+//         fail(new Error(error));
+//         return;
+//       }
+//
+//       if (!exchangeToken) {
+//         res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+//         res.end(
+//           renderCallbackPage({
+//             ok: false,
+//             message: "No setup exchange token was returned.",
+//           }),
+//         );
+//         fail(new Error("Setup callback missing exchange token."));
+//         return;
+//       }
+//
+//       let redeemed;
+//       try {
+//         redeemed = await redeemSetupExchangeToken({
+//           baseUrl,
+//           exchangeToken,
+//           state,
+//           redirectUri: callbackUrl,
+//         });
+//       } catch (err) {
+//         const message =
+//           err instanceof Error ? err.message : "Failed to redeem setup exchange.";
+//         res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+//         res.end(renderCallbackPage({ ok: false, message }));
+//         fail(new Error(message));
+//         return;
+//       }
+//
+//       res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+//       res.end(
+//         renderCallbackPage({
+//           ok: true,
+//           message: "Flywheel MCP was authorized successfully.",
+//         }),
+//       );
+//       succeed({ apiKey: redeemed.apiKey });
+//     });
+//
+//     server.once("error", (error) => {
+//       fail(error);
+//     });
+//
+//     server.listen(0, "127.0.0.1", () => {
+//       const address = server.address();
+//       if (!address || typeof address === "string") {
+//         fail(new Error("Failed to allocate local callback port."));
+//         return;
+//       }
+//
+//       callbackUrl = `http://127.0.0.1:${address.port}/callback`;
+//       const setupUrl = new URL("/auth/mcp/setup", baseUrl);
+//       setupUrl.searchParams.set("state", state);
+//       setupUrl.searchParams.set("redirect_uri", callbackUrl);
+//       setupUrl.searchParams.set("name", keyName);
+//
+//       console.log("Opening browser for Flywheel login and key creation...");
+//       console.log(`If it does not open, use this URL:\n${setupUrl.toString()}\n`);
+//
+//       launchBrowser(openUrl, setupUrl.toString());
+//     });
+//
+//     timeout = setTimeout(() => {
+//       fail(new Error("Timed out waiting for browser authorization."));
+//     }, timeoutMs);
+//   });
+// }
+
 export async function acquireApiKeyViaDeviceFlow({
   baseUrl,
   keyName,