@linzumi/cli 0.0.5-beta → 0.0.6-beta

package/src/localForwarding.ts

@@ -0,0 +1,500 @@
+/*
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-forwarding-and-editor-plan.md
+  Relationship: Implements the local side of bounded HTTP preview forwarding,
+  enforcing explicit allowed ports before the runner contacts loopback.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-subdomain-forwarding-epr.md
+  Relationship: Implements the runner side of local WebSocket forwarding for
+  isolated preview subdomains.
+*/
+import { gzipSync } from "node:zlib";
+import { type JsonObject, type JsonValue, isJsonObject } from "./protocol";
+import type { PhoenixClient } from "./phoenix";
+
+const maxForwardBodyBytes = 64 * 1024 * 1024;
+const gzipForwardThresholdBytes = 32 * 1024;
+
+export type ForwardHttpRequestControl = {
+  readonly type: "forward_http_request";
+  readonly requestId: string;
+  readonly port: number;
+  readonly method: string;
+  readonly path: string;
+  readonly queryString?: string;
+  readonly headers?: JsonValue;
+  readonly bodyBase64?: string;
+};
+
+export type ForwardHttpResponsePayload = JsonObject;
+
+type RequestBodyDecision =
+  | { readonly ok: true; readonly body: Uint8Array | undefined }
+  | { readonly ok: false; readonly error: string };
+
+export type ForwardWebSocketOpenControl = {
+  readonly type: "forward_websocket_open";
+  readonly socketId: string;
+  readonly port: number;
+  readonly path: string;
+  readonly queryString?: string;
+  readonly headers?: JsonValue;
+};
+
+export type ForwardWebSocketSendControl = {
+  readonly type: "forward_websocket_send";
+  readonly socketId: string;
+  readonly opcode: "text" | "binary" | "ping" | "pong";
+  readonly bodyBase64: string;
+};
+
+export type ForwardWebSocketCloseControl = {
+  readonly type: "forward_websocket_close";
+  readonly socketId: string;
+};
+
+export type ForwardWebSocketControl =
+  | ForwardWebSocketOpenControl
+  | ForwardWebSocketSendControl
+  | ForwardWebSocketCloseControl;
+
+export type ForwardWebSocketManager = {
+  readonly handle: (control: ForwardWebSocketControl) => void;
+  readonly close: () => void;
+};
+
+export async function handleForwardHttpRequest(
+  control: ForwardHttpRequestControl,
+  allowedPorts: readonly number[],
+): Promise<ForwardHttpResponsePayload> {
+  if (!allowedPorts.includes(control.port)) {
+    return forwardError(control.requestId, "forward_port_not_allowed");
+  }
+
+  const bodyDecision = requestBody(control);
+
+  if (!bodyDecision.ok) {
+    return forwardError(control.requestId, bodyDecision.error);
+  }
+
+  try {
+    const request = {
+      method: control.method,
+      headers: requestHeaders(control.headers),
+      ...(bodyDecision.body === undefined ? {} : { body: bodyDecision.body }),
+    };
+    const response = await fetchWithHttpsFallback(
+      control.port,
+      control.path,
+      control.queryString,
+      request,
+    );
+    const upstreamBuffer = Buffer.from(await response.arrayBuffer());
+    const patchedBody = patchForwardBody(
+      control.path,
+      response.headers,
+      upstreamBuffer,
+    );
+    const preparedResponse = prepareResponseBodyForChannel(
+      control,
+      response.headers,
+      patchedBody,
+    );
+
+    if (preparedResponse.body.byteLength > maxForwardBodyBytes) {
+      return forwardError(control.requestId, "forward_response_too_large");
+    }
+
+    return {
+      requestId: control.requestId,
+      ok: true,
+      status: response.status,
+      headers: preparedResponse.headers,
+      bodyBase64: preparedResponse.body.toString("base64"),
+    };
+  } catch (_error) {
+    return forwardError(control.requestId, "forward_target_unavailable");
+  }
+}
+
+export function isForwardHttpRequestControl(control: {
+  readonly type: string;
+}): control is ForwardHttpRequestControl {
+  return control.type === "forward_http_request";
+}
+
+export function isForwardWebSocketControl(control: {
+  readonly type: string;
+}): control is ForwardWebSocketControl {
+  return (
+    control.type === "forward_websocket_open" ||
+    control.type === "forward_websocket_send" ||
+    control.type === "forward_websocket_close"
+  );
+}
+
+export function createForwardWebSocketManager(
+  kandan: Pick<PhoenixClient, "push">,
+  topic: string,
+  allowedPorts: () => readonly number[],
+): ForwardWebSocketManager {
+  const sockets = new Map<string, WebSocket>();
+
+  const pushEvent = (payload: JsonObject) =>
+    kandan
+      .push(topic, "forward:websocket_event", payload)
+      .catch(() => undefined);
+
+  const closeSocket = (socketId: string) => {
+    const socket = sockets.get(socketId);
+    sockets.delete(socketId);
+    socket?.close();
+  };
+
+  return {
+    handle: (control) => {
+      switch (control.type) {
+        case "forward_websocket_open": {
+          if (!allowedPorts().includes(control.port)) {
+            void pushEvent({
+              socketId: control.socketId,
+              type: "error",
+              error: "forward_port_not_allowed",
+            });
+            return;
+          }
+
+          openLocalWebSocket(control, sockets, pushEvent, "ws");
+          return;
+        }
+        case "forward_websocket_send": {
+          const socket = sockets.get(control.socketId);
+          if (socket === undefined || socket.readyState !== WebSocket.OPEN) {
+            void pushEvent({
+              socketId: control.socketId,
+              type: "error",
+              error: "websocket_not_open",
+            });
+            return;
+          }
+
+          const body = Buffer.from(control.bodyBase64, "base64");
+          switch (control.opcode) {
+            case "text":
+              socket.send(body.toString());
+              return;
+            case "binary":
+            case "ping":
+            case "pong":
+              socket.send(body);
+              return;
+          }
+        }
+        case "forward_websocket_close":
+          closeSocket(control.socketId);
+          return;
+      }
+    },
+    close: () => {
+      for (const socketId of sockets.keys()) {
+        closeSocket(socketId);
+      }
+    },
+  };
+}
+
+function openLocalWebSocket(
+  control: ForwardWebSocketOpenControl,
+  sockets: Map<string, WebSocket>,
+  pushEvent: (payload: JsonObject) => Promise<void | JsonValue>,
+  scheme: "ws" | "wss",
+): void {
+  let opened = false;
+  const websocket = new WebSocket(
+    localForwardUrl(
+      scheme === "ws" ? "http" : "https",
+      control.port,
+      control.path,
+      control.queryString,
+    ).replace(/^http/, scheme),
+  );
+  sockets.set(control.socketId, websocket);
+  websocket.addEventListener("open", () => {
+    opened = true;
+    void pushEvent({ socketId: control.socketId, type: "open" });
+  });
+  websocket.addEventListener("message", (event) => {
+    const body =
+      typeof event.data === "string"
+        ? Buffer.from(event.data)
+        : Buffer.from(event.data as ArrayBuffer);
+    void pushEvent({
+      socketId: control.socketId,
+      type: "message",
+      opcode: typeof event.data === "string" ? "text" : "binary",
+      bodyBase64: body.toString("base64"),
+    });
+  });
+  websocket.addEventListener("close", (event) => {
+    sockets.delete(control.socketId);
+    void pushEvent({
+      socketId: control.socketId,
+      type: "close",
+      code: event.code,
+      reason: event.reason,
+    });
+  });
+  websocket.addEventListener("error", () => {
+    sockets.delete(control.socketId);
+    if (!opened && scheme === "ws") {
+      openLocalWebSocket(control, sockets, pushEvent, "wss");
+      return;
+    }
+
+    void pushEvent({
+      socketId: control.socketId,
+      type: "error",
+      error: "websocket_error",
+    });
+  });
+}
+
+function localForwardUrl(
+  scheme: "http" | "https",
+  port: number,
+  path: string,
+  queryString: string | undefined,
+): string {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const url = new URL(`${scheme}://127.0.0.1:${port}${normalizedPath}`);
+
+  if (queryString !== undefined && queryString.trim() !== "") {
+    url.search = queryString;
+  }
+
+  return url.toString();
+}
+
+async function fetchWithHttpsFallback(
+  port: number,
+  path: string,
+  queryString: string | undefined,
+  request: RequestInit,
+): Promise<Response> {
+  try {
+    return await fetch(
+      localForwardUrl("http", port, path, queryString),
+      request,
+    );
+  } catch (httpError) {
+    try {
+      return await fetch(
+        localForwardUrl("https", port, path, queryString),
+        request,
+      );
+    } catch (_httpsError) {
+      throw httpError;
+    }
+  }
+}
+
+function requestBody(
+  control: ForwardHttpRequestControl,
+): RequestBodyDecision {
+  if (control.method === "GET" || control.method === "HEAD") {
+    return { ok: true, body: undefined };
+  }
+
+  if (control.bodyBase64 === undefined || control.bodyBase64 === "") {
+    return { ok: true, body: undefined };
+  }
+
+  const body = decodeBase64Body(control.bodyBase64);
+
+  if (body === undefined) {
+    return { ok: false, error: "invalid_forward_request" };
+  }
+
+  if (body.byteLength > maxForwardBodyBytes) {
+    return { ok: false, error: "forward_body_too_large" };
+  }
+
+  return { ok: true, body };
+}
+
+function decodeBase64Body(value: string): Uint8Array | undefined {
+  const normalized = value.trim();
+
+  if (
+    normalized.length % 4 === 1 ||
+    !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)
+  ) {
+    return undefined;
+  }
+
+  const body = Buffer.from(normalized, "base64");
+  const canonicalBody = body.toString("base64").replace(/=+$/, "");
+  const canonicalInput = normalized.replace(/=+$/, "");
+
+  return canonicalBody === canonicalInput ? body : undefined;
+}
+
+function requestHeaders(headers: JsonValue | undefined): Headers {
+  const result = new Headers();
+
+  if (!Array.isArray(headers)) {
+    return result;
+  }
+
+  for (const header of headers) {
+    if (isHeader(header)) {
+      result.set(header.name, header.value);
+    }
+  }
+
+  return result;
+}
+
+function responseHeaders(headers: Headers): JsonValue[] {
+  return Array.from(headers.entries())
+    .filter(([name]) => !blockedForwardHeaderNames.has(name.toLowerCase()))
+    .slice(0, 40)
+    .map(([name, value]) => ({ name, value }));
+}
+
+function patchForwardBody(path: string, headers: Headers, body: Buffer): Buffer {
+  if (!codeServerWorkbenchScript(path, headers)) {
+    return body;
+  }
+
+  return Buffer.from(
+    body
+      .toString("utf8")
+      .replace(
+        "message:h(3783,null,\"code-server\")",
+        "message:h(3783,null,\"Kandan\")",
+      ),
+  );
+}
+
+function prepareResponseBodyForChannel(
+  control: ForwardHttpRequestControl,
+  headers: Headers,
+  body: Buffer,
+): { readonly body: Buffer; readonly headers: JsonValue[] } {
+  const forwardedHeaders = responseHeaders(headers);
+
+  if (!shouldGzipResponse(control, headers, body)) {
+    return { body, headers: forwardedHeaders };
+  }
+
+  return {
+    body: gzipSync(body),
+    headers: [
+      ...forwardedHeaders,
+      { name: "content-encoding", value: "gzip" },
+      { name: "vary", value: "accept-encoding" },
+    ],
+  };
+}
+
+function shouldGzipResponse(
+  control: ForwardHttpRequestControl,
+  headers: Headers,
+  body: Buffer,
+): boolean {
+  if (
+    control.method === "HEAD" ||
+    body.byteLength < gzipForwardThresholdBytes ||
+    !clientAcceptsGzip(control.headers)
+  ) {
+    return false;
+  }
+
+  return compressibleResponse(control.path, headers);
+}
+
+function clientAcceptsGzip(headers: JsonValue | undefined): boolean {
+  if (!Array.isArray(headers)) {
+    return false;
+  }
+
+  return headers.some(
+    header =>
+      isWireHeader(header) &&
+      header.name.toLowerCase() === "accept-encoding" &&
+      header.value
+        .toLowerCase()
+        .split(",")
+        .map(value => value.trim())
+        .some(value => value === "gzip" || value.startsWith("gzip;")),
+  );
+}
+
+function compressibleResponse(path: string, headers: Headers): boolean {
+  const contentType = headers.get("content-type")?.toLowerCase() ?? "";
+
+  if (
+    contentType.startsWith("text/") ||
+    contentType.includes("javascript") ||
+    contentType.includes("json") ||
+    contentType.includes("xml")
+  ) {
+    return true;
+  }
+
+  return /\.(?:css|html|js|json|map|mjs|svg|txt)$/i.test(path);
+}
+
+function codeServerWorkbenchScript(path: string, headers: Headers): boolean {
+  return (
+    path.endsWith("/out/vs/code/browser/workbench/workbench.js") &&
+    (headers.get("content-type") ?? "").toLowerCase().includes("javascript")
+  );
+}
+
+function isHeader(
+  value: JsonValue,
+): value is { readonly name: string; readonly value: string } {
+  return (
+    isWireHeader(value) &&
+    !blockedForwardHeaderNames.has(value.name.toLowerCase())
+  );
+}
+
+function isWireHeader(
+  value: JsonValue,
+): value is { readonly name: string; readonly value: string } {
+  return (
+    isJsonObject(value) &&
+    typeof value.name === "string" &&
+    typeof value.value === "string"
+  );
+}
+
+function forwardError(
+  requestId: string,
+  error: string,
+): ForwardHttpResponsePayload {
+  return {
+    requestId,
+    ok: false,
+    error,
+  };
+}
+
+const blockedForwardHeaderNames = new Set([
+  "accept-encoding",
+  "connection",
+  "content-encoding",
+  "content-length",
+  "host",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);

package/src/oauth.ts

@@ -11,6 +11,7 @@ export type LocalRunnerOAuthOptions = {
   readonly kandanUrl: string;
   readonly workspaceSlug?: string | undefined;
   readonly channelSlug?: string | undefined;
+  readonly onboarding?: "start" | undefined;
   readonly callbackHost?: string | undefined;
   readonly openAuthorizationUrl?: ((url: string) => Promise<void> | void) | undefined;
 };
@@ -18,6 +19,15 @@ export type LocalRunnerOAuthOptions = {
 export type LocalRunnerOAuthToken = {
   readonly accessToken: string;
   readonly expiresInSeconds?: number | undefined;
+  readonly workspaceSlug?: string | undefined;
+  readonly channelSlug?: string | undefined;
+};
+
+export type LocalRunnerStartTarget = {
+  readonly workspaceSlug: string;
+  readonly channelSlug: string;
+  readonly workspaceName: string;
+  readonly channelName: string;
 };
 
 export async function acquireLocalRunnerToken(
@@ -41,6 +51,7 @@ export async function acquireLocalRunnerTokenDetails(
     state,
     workspaceSlug: options.workspaceSlug,
     channelSlug: options.channelSlug,
+    onboarding: options.onboarding,
   });
 
   process.stderr.write(`Authorize the local Codex runner:\n${authorizeUrl}\n`);
@@ -103,6 +114,52 @@ export async function validateLocalRunnerToken(args: {
   }
 }
 
+export async function fetchLocalRunnerStartTarget(args: {
+  readonly kandanUrl: string;
+  readonly accessToken: string;
+}): Promise<LocalRunnerStartTarget> {
+  const response = await fetch(
+    new URL(
+      "/api/v2/local-codex-runner/onboarding/start",
+      kandanHttpBaseUrl(args.kandanUrl),
+    ),
+    {
+      method: "GET",
+      headers: { authorization: `Bearer ${args.accessToken}` },
+    },
+  );
+  const body: unknown = await response.json();
+
+  if (!response.ok || typeof body !== "object" || body === null) {
+    throw new Error(`local runner start target failed with HTTP ${response.status}`);
+  }
+
+  const workspace = "workspace" in body ? body.workspace : undefined;
+  const channel = "channel" in body ? body.channel : undefined;
+  const workspaceName = "workspace_name" in body ? body.workspace_name : undefined;
+  const channelName = "channel_name" in body ? body.channel_name : undefined;
+
+  if (
+    typeof workspace !== "string" ||
+    workspace.trim() === "" ||
+    typeof channel !== "string" ||
+    channel.trim() === "" ||
+    typeof workspaceName !== "string" ||
+    workspaceName.trim() === "" ||
+    typeof channelName !== "string" ||
+    channelName.trim() === ""
+  ) {
+    throw new Error("local runner start target response was incomplete");
+  }
+
+  return {
+    workspaceSlug: workspace,
+    channelSlug: channel,
+    workspaceName,
+    channelName,
+  };
+}
+
 export function kandanHttpBaseUrl(kandanUrl: string): string {
   const parsed = new URL(kandanUrl);
 
@@ -173,6 +230,7 @@ function authorizationUrl(args: {
   readonly state: string;
   readonly workspaceSlug?: string | undefined;
   readonly channelSlug?: string | undefined;
+  readonly onboarding?: "start" | undefined;
 }): string {
   const url = new URL("/api/v2/local-codex-runner/oauth/authorize", args.httpBaseUrl);
   url.searchParams.set("redirect_uri", args.redirectUri);
@@ -186,6 +244,10 @@ function authorizationUrl(args: {
     url.searchParams.set("channel", args.channelSlug);
   }
 
+  if (args.onboarding !== undefined) {
+    url.searchParams.set("onboarding", args.onboarding);
+  }
+
   return url.toString();
 }
 
@@ -222,9 +284,17 @@ async function exchangeCodeForToken(args: {
   return {
     accessToken: token,
     expiresInSeconds: typeof expiresIn === "number" ? expiresIn : undefined,
+    workspaceSlug: stringBodyField(body, "workspace"),
+    channelSlug: stringBodyField(body, "channel"),
   };
 }
 
+function stringBodyField(body: object, key: string): string | undefined {
+  const value = key in body ? body[key as keyof typeof body] : undefined;
+
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
 function startCallbackServer(args: {
   readonly host: string;
 }): Promise<{
@@ -236,9 +306,11 @@ function startCallbackServer(args: {
     let resolveCallback:
       | ((value: { readonly code: string; readonly state: string }) => void)
       | undefined;
+    let rejectCallback: ((reason?: unknown) => void) | undefined;
     const callbackPromise = new Promise<{ readonly code: string; readonly state: string }>(
-      (callbackResolve) => {
+      (callbackResolve, callbackReject) => {
         resolveCallback = callbackResolve;
+        rejectCallback = callbackReject;
       },
     );
 
@@ -249,14 +321,30 @@ function startCallbackServer(args: {
         const url = new URL(request.url);
         const code = url.searchParams.get("code");
         const state = url.searchParams.get("state");
+        const error = url.searchParams.get("error");
+
+        if (error !== null && error.trim() !== "") {
+          rejectCallback?.(new Error(`local runner OAuth failed: ${error}`));
+          return oauthResultHtml({
+            title: "Linzumi CLI was not authorized",
+            body: "You denied the request. You can close this tab and rerun linzumi start when you are ready.",
+            status: 403,
+          });
+        }
 
         if (code === null || state === null || code.trim() === "" || state.trim() === "") {
-          return new Response("Missing local runner authorization code.", { status: 400 });
+          return oauthResultHtml({
+            title: "Authorization callback was incomplete",
+            body: "Kandan did not send the local runner authorization code. Return to your terminal and try again.",
+            status: 400,
+          });
         }
 
         resolveCallback?.({ code, state });
-        return new Response("Kandan local Codex runner authorized. You can close this tab.", {
-          headers: { "content-type": "text/plain; charset=utf-8" },
+        return oauthResultHtml({
+          title: "Linzumi CLI is connected",
+          body: "You can close this tab and return to the terminal. Kandan will finish starting the local runner.",
+          status: 200,
         });
       },
     });
@@ -271,6 +359,49 @@ function startCallbackServer(args: {
   });
 }
 
+function oauthResultHtml(args: {
+  readonly title: string;
+  readonly body: string;
+  readonly status: number;
+}): Response {
+  return new Response(
+    `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(args.title)}</title>
+    <style>
+      :root { color-scheme: light dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: #f6f7f9; color: #13161c; }
+      main { width: min(520px, calc(100vw - 32px)); border: 1px solid #d9dde5; border-radius: 12px; background: #fff; padding: 30px; box-shadow: 0 24px 70px rgba(18, 25, 38, 0.12); }
+      h1 { margin: 0 0 10px; font-size: 24px; line-height: 1.2; }
+      p { margin: 0; color: #465160; line-height: 1.55; }
+      @media (prefers-color-scheme: dark) {
+        body { background: #0f131a; color: #f3f5f8; }
+        main { background: #171c25; border-color: #2b3442; box-shadow: 0 24px 70px rgba(0, 0, 0, 0.4); }
+        p { color: #aab4c2; }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>${escapeHtml(args.title)}</h1>
+      <p>${escapeHtml(args.body)}</p>
+    </main>
+  </body>
+</html>`,
+    {
+      status: args.status,
+      headers: { "content-type": "text/html; charset=utf-8" },
+    },
+  );
+}
+
+function escapeHtml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
 function openBrowser(url: string): Promise<void> {
   const command =
     process.platform === "darwin"