@linkedclaw/cli 0.1.6 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkedclaw/cli",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "LinkedClaw command-line interface",
   "type": "module",
   "bin": {
@@ -14,10 +14,10 @@
     "js-yaml": "^4.1.0",
     "open": "^10.1.0",
     "ws": "^8.0.0",
-    "@linkedclaw/consumer-runtime": "^0.9.3",
     "@linkedclaw/consumer": "^0.9.2",
-    "@linkedclaw/provider": "^0.9.1",
-    "@linkedclaw/provider-runtime": "^0.9.1"
+    "@linkedclaw/consumer-runtime": "^0.10.0",
+    "@linkedclaw/provider-runtime": "^0.9.1",
+    "@linkedclaw/provider": "^0.9.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/auth/decide.ts

@@ -0,0 +1,48 @@
+/**
+ * Heuristics for picking the loopback flow vs forcing the device flow.
+ *
+ * We try loopback first by default — it's lower-friction (just a click
+ * in the browser; no code typing). When the environment looks like it
+ * can't reach a localhost server in the user's browser (SSH, SSH-tunneled
+ * dev, headless Linux, container, codespace), we switch to device flow
+ * before even attempting loopback.
+ *
+ * On any loopback failure (browser launch error, callback never received
+ * within timeout, port-bind failure), the caller can fall through to the
+ * device flow as a recoverable backup.
+ */
+import { existsSync } from "node:fs";
+import { hostname, platform } from "node:os";
+
+export interface DetectedClient {
+  label: string;
+  packageVersion: string;
+}
+
+export function detectLabel(packageVersion: string): string {
+  const host = hostname();
+  return truncate(
+    `linkedclaw-cli/${packageVersion} on ${platform()} (host: ${host})`,
+    120,
+  );
+}
+
+function truncate(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n - 1) + "…";
+}
+
+export function isHeadless(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.SSH_CLIENT || env.SSH_TTY) return true;
+  if (env.CODESPACES === "true") return true;
+  if (env.LINKEDCLAW_FORCE_DEVICE_FLOW === "1") return true;
+
+  // Container hint — Docker, podman.
+  if (existsSync("/.dockerenv") || existsSync("/run/.containerenv")) return true;
+
+  // Linux desktop check: with no DISPLAY/WAYLAND_DISPLAY assume headless.
+  if (platform() === "linux") {
+    if (!env.DISPLAY && !env.WAYLAND_DISPLAY) return true;
+  }
+
+  return false;
+}

package/src/auth/device.ts

@@ -0,0 +1,203 @@
+/**
+ * Device authorization grant flow (RFC 8628).
+ *
+ *   1. POST /api/v1/auth/device/code
+ *      → cloud creates pending device-flow grant, returns {device_code,
+ *        user_code, verification_uri, verification_uri_complete,
+ *        expires_in, interval}.
+ *   2. CLI prints the user_code + URL, optionally opens the URL in a
+ *      browser.
+ *   3. CLI polls POST /api/v1/auth/device/poll {device_code}
+ *      until the response flips from {status:"pending"} to
+ *      {status:"approved", api_key:"lc_…"}.
+ *   4. On HTTP 400 (expired_token | access_denied | invalid_grant) we
+ *      surface the corresponding DeviceFlowError and exit non-zero.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+
+export class DeviceFlowError extends Error {
+  constructor(message: string, public code: string) {
+    super(message);
+    this.name = "DeviceFlowError";
+  }
+}
+
+export interface DeviceFlowResult {
+  apiKey: string;
+  userId: string;
+  handle: string | null;
+  scope: string;
+  keyId: string;
+}
+
+export interface DeviceCodeResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete: string;
+  expires_in: number;
+  interval: number;
+}
+
+export interface DeviceFlowOptions {
+  cloudUrl: string;
+  clientLabel: string;
+  requestedScope: string;
+  openBrowser?: (url: string) => Promise<void>;
+  onUserPrompt: (info: DeviceCodeResponse) => void;
+  // for tests
+  pollOverride?: (deviceCode: string) => Promise<unknown>;
+}
+
+export async function runDeviceFlow(opts: DeviceFlowOptions): Promise<DeviceFlowResult> {
+  const init = await issueDeviceCode(opts.cloudUrl, {
+    client_label: opts.clientLabel,
+    requested_scope: opts.requestedScope,
+  });
+
+  // Best-effort browser launch; failures are silent — user has the URL printed.
+  if (opts.openBrowser) {
+    try {
+      await opts.openBrowser(init.verification_uri_complete);
+    } catch {
+      // ignore — code was already printed to terminal
+    }
+  }
+  opts.onUserPrompt(init);
+
+  const deadline = Date.now() + init.expires_in * 1000;
+  let interval = init.interval;
+
+  while (Date.now() < deadline) {
+    const before = Date.now();
+    const result = await pollOnce(
+      opts.cloudUrl,
+      init.device_code,
+      opts.pollOverride,
+    );
+    if (result.kind === "approved") {
+      return {
+        apiKey: result.api_key,
+        userId: result.user_id,
+        handle: result.handle ?? null,
+        scope: result.scope,
+        keyId: result.key_id,
+      };
+    }
+    if (result.kind === "slow_down") {
+      interval = Math.min(interval * 2, 30);
+    }
+    const elapsed = Date.now() - before;
+    const wait = Math.max(0, interval * 1000 - elapsed);
+    await sleep(wait);
+  }
+  throw new DeviceFlowError(
+    "Login window expired. Run `linkedclaw login` to retry.",
+    "expired_token",
+  );
+}
+
+interface PollPending {
+  kind: "pending";
+}
+interface PollSlowDown {
+  kind: "slow_down";
+}
+interface PollApproved {
+  kind: "approved";
+  api_key: string;
+  user_id: string;
+  handle: string | null;
+  scope: string;
+  key_id: string;
+}
+
+type PollResult = PollPending | PollSlowDown | PollApproved;
+
+async function pollOnce(
+  cloudUrl: string,
+  deviceCode: string,
+  override?: (deviceCode: string) => Promise<unknown>,
+): Promise<PollResult> {
+  const raw = override
+    ? await override(deviceCode)
+    : await rawPoll(cloudUrl, deviceCode);
+  return interpretPoll(raw);
+}
+
+async function rawPoll(cloudUrl: string, deviceCode: string): Promise<unknown> {
+  const resp = await fetch(`${cloudUrl}/api/v1/auth/device/poll`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ device_code: deviceCode }),
+  });
+  if (resp.status === 400) {
+    let detail = "invalid_grant";
+    try {
+      const j = (await resp.json()) as { detail?: string };
+      if (j.detail) detail = j.detail;
+    } catch {
+      // ignore
+    }
+    if (detail === "slow_down") return { __slow: true };
+    throw new DeviceFlowError(_humanize(detail), detail);
+  }
+  if (resp.status !== 200) {
+    throw new DeviceFlowError(`Poll failed: HTTP ${resp.status}`, "http_error");
+  }
+  return await resp.json();
+}
+
+function interpretPoll(raw: unknown): PollResult {
+  if (raw && typeof raw === "object" && "__slow" in raw) {
+    return { kind: "slow_down" };
+  }
+  const obj = (raw ?? {}) as Record<string, unknown>;
+  if (obj.status === "pending") return { kind: "pending" };
+  if (obj.status === "approved") {
+    return {
+      kind: "approved",
+      api_key: String(obj.api_key),
+      user_id: String(obj.user_id),
+      handle: (obj.handle as string | null) ?? null,
+      scope: String(obj.scope),
+      key_id: String(obj.key_id),
+    };
+  }
+  throw new DeviceFlowError(`Unexpected poll status: ${obj.status}`, "protocol_error");
+}
+
+function _humanize(code: string): string {
+  switch (code) {
+    case "expired_token":
+      return "Login window expired. Run `linkedclaw login` to retry.";
+    case "access_denied":
+      return "Authorization denied by user.";
+    case "invalid_grant":
+      return "Authorization session is no longer valid.";
+    default:
+      return code;
+  }
+}
+
+async function issueDeviceCode(
+  cloudUrl: string,
+  body: Record<string, unknown>,
+): Promise<DeviceCodeResponse> {
+  const resp = await fetch(`${cloudUrl}/api/v1/auth/device/code`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (resp.status !== 201) {
+    let detail = `${resp.status}`;
+    try {
+      const j = (await resp.json()) as { detail?: string };
+      if (j.detail) detail = j.detail;
+    } catch {
+      // ignore
+    }
+    throw new DeviceFlowError(`/auth/device/code ${resp.status}: ${detail}`, "init_failed");
+  }
+  return (await resp.json()) as DeviceCodeResponse;
+}

package/src/auth/loopback.ts

@@ -0,0 +1,239 @@
+/**
+ * Loopback OAuth flow with PKCE (RFC 7636 + RFC 8252 §7.3).
+ *
+ * Steps:
+ *   1. POST /api/v1/auth/oauth/initiate → cloud creates pending grant,
+ *      returns authorize_url + grant_id + expires_in.
+ *   2. Bind a TCP listener on 127.0.0.1:<random free port>; build a
+ *      redirect_uri pointing at it.
+ *   3. Open the user's browser to authorize_url.
+ *   4. User clicks Approve in portal; portal redirects browser to
+ *      redirect_uri?code=...&state=....
+ *   5. Local listener receives the GET, captures `code`, replies with a
+ *      simple "you can close this tab" HTML, then shuts down.
+ *   6. POST /api/v1/auth/oauth/token { grant_type, code, code_verifier }
+ *      → cloud verifies PKCE, mints lc_… key, returns it.
+ *
+ * Errors are wrapped in LoopbackError so callers can distinguish
+ * recoverable (fall back to device flow) from non-recoverable.
+ */
+import { createServer, Server } from "node:http";
+import { AddressInfo } from "node:net";
+
+import { deriveChallenge, generateState, generateVerifier } from "./pkce.js";
+
+export class LoopbackError extends Error {
+  constructor(message: string, public recoverable: boolean) {
+    super(message);
+    this.name = "LoopbackError";
+  }
+}
+
+export interface LoopbackResult {
+  apiKey: string;
+  userId: string;
+  handle: string | null;
+  scope: string;
+  keyId: string;
+}
+
+export interface LoopbackOptions {
+  cloudUrl: string;
+  clientLabel: string;
+  requestedScope: string;
+  timeoutMs?: number;
+  openBrowser: (url: string) => Promise<void>;
+  onUserPrompt?: (verificationUrl: string) => void;
+}
+
+const SUCCESS_HTML = `<!doctype html>
+<html><head><meta charset="utf-8"><title>LinkedClaw — Authorized</title></head>
+<body style="font-family:system-ui,sans-serif;text-align:center;padding:48px">
+<h2>✅ Authorized</h2>
+<p>You can close this tab and return to your terminal.</p>
+</body></html>`;
+
+const ERROR_HTML = (msg: string) => `<!doctype html>
+<html><head><meta charset="utf-8"><title>LinkedClaw — Error</title></head>
+<body style="font-family:system-ui,sans-serif;text-align:center;padding:48px">
+<h2>❌ Authorization failed</h2>
+<p>${msg}</p>
+<p>Return to your terminal — the CLI will retry or fall back automatically.</p>
+</body></html>`;
+
+export async function runLoopback(opts: LoopbackOptions): Promise<LoopbackResult> {
+  const verifier = generateVerifier();
+  const challenge = deriveChallenge(verifier);
+  const state = generateState();
+
+  // 1. Bind a free port. `port: 0` lets the OS pick.
+  const server = createServer();
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.removeListener("error", reject);
+      resolve();
+    });
+  });
+  const port = (server.address() as AddressInfo).port;
+  const redirectUri = `http://127.0.0.1:${port}/cb`;
+
+  let initResp: { grant_id: string; authorize_url: string; expires_in: number };
+  try {
+    initResp = await initiate(opts.cloudUrl, {
+      client_label: opts.clientLabel,
+      requested_scope: opts.requestedScope,
+      redirect_uri: redirectUri,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      state,
+    });
+  } catch (err) {
+    server.close();
+    throw new LoopbackError(
+      `Failed to start authorization: ${(err as Error).message}`,
+      // network failure shouldn't fall through to device flow — it'll fail there too.
+      false,
+    );
+  }
+
+  // 2. Try to launch the browser. On failure, fall through.
+  try {
+    await opts.openBrowser(initResp.authorize_url);
+  } catch {
+    server.close();
+    throw new LoopbackError(
+      "Could not open browser; switching to device flow.",
+      true,
+    );
+  }
+  if (opts.onUserPrompt) opts.onUserPrompt(initResp.authorize_url);
+
+  // 3. Wait for the callback.
+  const timeoutMs = opts.timeoutMs ?? 60_000;
+  const callbackParams = await waitForCallback(server, timeoutMs).catch((err) => {
+    server.close();
+    throw err;
+  });
+  server.close();
+
+  if (callbackParams.error) {
+    throw new LoopbackError(`Authorization denied: ${callbackParams.error}`, false);
+  }
+  if (!callbackParams.code) {
+    throw new LoopbackError("Authorization callback missing code.", true);
+  }
+  if (callbackParams.state !== state) {
+    throw new LoopbackError("Authorization callback state mismatch.", false);
+  }
+
+  // 4. Exchange code for key.
+  const tokenResp = await exchangeToken(opts.cloudUrl, {
+    grant_type: "authorization_code",
+    code: callbackParams.code,
+    code_verifier: verifier,
+  });
+  return {
+    apiKey: tokenResp.api_key,
+    userId: tokenResp.user_id,
+    handle: tokenResp.handle ?? null,
+    scope: tokenResp.scope,
+    keyId: tokenResp.key_id,
+  };
+}
+
+interface CallbackParams {
+  code?: string;
+  state?: string;
+  error?: string;
+}
+
+function waitForCallback(server: Server, timeoutMs: number): Promise<CallbackParams> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new LoopbackError("Browser callback timed out.", true));
+    }, timeoutMs);
+
+    server.on("request", (req, res) => {
+      const url = new URL(req.url ?? "/", `http://127.0.0.1`);
+      if (url.pathname !== "/cb") {
+        res.statusCode = 404;
+        res.end();
+        return;
+      }
+      const params: CallbackParams = {
+        code: url.searchParams.get("code") ?? undefined,
+        state: url.searchParams.get("state") ?? undefined,
+        error: url.searchParams.get("error") ?? undefined,
+      };
+      const html = params.error
+        ? ERROR_HTML(params.error)
+        : params.code
+        ? SUCCESS_HTML
+        : ERROR_HTML("Missing code parameter");
+      res.statusCode = params.code ? 200 : 400;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(html);
+
+      clearTimeout(timer);
+      resolve(params);
+    });
+  });
+}
+
+async function initiate(
+  cloudUrl: string,
+  body: Record<string, unknown>,
+): Promise<{ grant_id: string; authorize_url: string; expires_in: number }> {
+  const resp = await fetch(`${cloudUrl}/api/v1/auth/oauth/initiate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (resp.status !== 201) {
+    const detail = await safeDetail(resp);
+    throw new Error(`/auth/oauth/initiate ${resp.status}: ${detail}`);
+  }
+  return (await resp.json()) as {
+    grant_id: string;
+    authorize_url: string;
+    expires_in: number;
+  };
+}
+
+async function exchangeToken(
+  cloudUrl: string,
+  body: Record<string, unknown>,
+): Promise<{
+  api_key: string;
+  user_id: string;
+  handle: string | null;
+  scope: string;
+  key_id: string;
+}> {
+  const resp = await fetch(`${cloudUrl}/api/v1/auth/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (resp.status !== 200) {
+    const detail = await safeDetail(resp);
+    throw new LoopbackError(`Token exchange failed: ${detail}`, false);
+  }
+  return (await resp.json()) as {
+    api_key: string;
+    user_id: string;
+    handle: string | null;
+    scope: string;
+    key_id: string;
+  };
+}
+
+async function safeDetail(resp: Response): Promise<string> {
+  try {
+    const j = (await resp.json()) as { detail?: string };
+    return j.detail ?? `${resp.status}`;
+  } catch {
+    return `${resp.status}`;
+  }
+}

package/src/auth/pkce.ts

@@ -0,0 +1,22 @@
+/**
+ * RFC 7636 PKCE helpers.
+ *
+ * generateVerifier: returns a base64url-encoded random 64-byte string,
+ *   trimmed to a 43–128 char `code_verifier` per RFC 7636 §4.1.
+ * deriveChallenge:  returns BASE64URL(SHA256(verifier)), the `code_challenge`
+ *   we send to the cloud /auth/oauth/initiate alongside `code_challenge_method: "S256"`.
+ */
+import { createHash, randomBytes } from "node:crypto";
+
+export function generateVerifier(): string {
+  // 64 raw bytes → ~86 base64url chars. Spec range is [43,128].
+  return randomBytes(64).toString("base64url");
+}
+
+export function deriveChallenge(verifier: string): string {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+
+export function generateState(): string {
+  return randomBytes(16).toString("base64url");
+}

package/src/commands/auth.ts

@@ -2,24 +2,110 @@ import { Command } from "commander";
 import { configPath, readFileConfig, writeFileConfig, DEFAULT_CLOUD_URL } from "../config.js";
 import { buildContext } from "../context.js";
 import { runCommand, readLine } from "../output.js";
+import { detectLabel, isHeadless } from "../auth/decide.js";
+import { LoopbackError, runLoopback } from "../auth/loopback.js";
+import { runDeviceFlow } from "../auth/device.js";
+
+const CLI_VERSION = "0.2.0";
 
 export function registerAuthCommands(program: Command): void {
   program
     .command("login")
-    .description("Store API key in ~/.linkedclaw/config.yaml")
-    .option("--api-key <key>", "API key (otherwise read from stdin)")
+    .description(
+      "Authenticate via browser (loopback PKCE; falls back to device code if headless).",
+    )
+    .option("--api-key <key>", "Skip browser; store key directly")
+    .option("--paste", "Skip browser; prompt for key on stdin")
+    .option("--device", "Force device flow (skip loopback)")
+    .option("--scope <scope>", "Requested scope: full | read | invoke", "full")
+    .option("--label <label>", "Client label override (default: auto-detected)")
     .option("--cloud-url <url>", "Override cloud URL")
     .action(async (opts) => {
       await runCommand(async () => {
-        let apiKey = opts.apiKey as string | undefined;
-        if (!apiKey) {
-          apiKey = await readLine("Paste API key: ");
-        }
-        if (!apiKey) throw new Error("empty api key");
         const prev = readFileConfig();
-        const next = { ...prev, apiKey, ...(opts.cloudUrl ? { cloudUrl: opts.cloudUrl } : {}) };
-        writeFileConfig(next);
-        return { ok: true, path: configPath() };
+        const cloudUrl =
+          (opts.cloudUrl as string | undefined) ??
+          (prev.cloudUrl as string | undefined) ??
+          process.env.LINKEDCLAW_CLOUD_URL ??
+          DEFAULT_CLOUD_URL;
+
+        if (opts.apiKey || opts.paste) {
+          let apiKey = opts.apiKey as string | undefined;
+          if (!apiKey) apiKey = await readLine("Paste API key: ");
+          if (!apiKey) throw new Error("empty api key");
+          writeFileConfig({ ...prev, apiKey, cloudUrl });
+          return { ok: true, mode: "paste", path: configPath() };
+        }
+
+        const clientLabel = (opts.label as string | undefined) ?? detectLabel(CLI_VERSION);
+        const requestedScope = (opts.scope as string | undefined) ?? "full";
+
+        const openBrowser = async (url: string): Promise<void> => {
+          const open = (await import("open")).default;
+          await open(url);
+        };
+
+        const forceDevice = Boolean(opts.device) || isHeadless();
+
+        if (!forceDevice) {
+          try {
+            const result = await runLoopback({
+              cloudUrl,
+              clientLabel,
+              requestedScope,
+              openBrowser,
+              onUserPrompt: (url) => {
+                process.stderr.write(
+                  `Opened browser to ${url}\nApprove the request to continue.\n`,
+                );
+              },
+            });
+            writeFileConfig({ ...prev, apiKey: result.apiKey, cloudUrl });
+            return {
+              ok: true,
+              mode: "loopback",
+              path: configPath(),
+              user_id: result.userId,
+              handle: result.handle,
+              scope: result.scope,
+              key_id: result.keyId,
+            };
+          } catch (err) {
+            if (err instanceof LoopbackError && err.recoverable) {
+              process.stderr.write(`${err.message}\n`);
+              // fall through to device flow
+            } else {
+              throw err;
+            }
+          }
+        }
+
+        const result = await runDeviceFlow({
+          cloudUrl,
+          clientLabel,
+          requestedScope,
+          openBrowser,
+          onUserPrompt: (info) => {
+            process.stderr.write(
+              `\n🔓 LinkedClaw login\n\n` +
+                `Open this URL in your browser:\n  ${info.verification_uri_complete}\n\n` +
+                `Or visit ${info.verification_uri} and enter:\n  ${info.user_code}\n\n` +
+                `Waiting for approval... (${Math.floor(info.expires_in / 60)}m ${
+                  info.expires_in % 60
+                }s remaining)\n`,
+            );
+          },
+        });
+        writeFileConfig({ ...prev, apiKey: result.apiKey, cloudUrl });
+        return {
+          ok: true,
+          mode: "device",
+          path: configPath(),
+          user_id: result.userId,
+          handle: result.handle,
+          scope: result.scope,
+          key_id: result.keyId,
+        };
       });
     });
 

package/test/auth-decide.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { detectLabel, isHeadless } from "../src/auth/decide.js";
+
+describe("isHeadless", () => {
+  it("returns true when SSH_TTY is set", () => {
+    expect(isHeadless({ SSH_TTY: "/dev/pts/0" } as NodeJS.ProcessEnv)).toBe(true);
+  });
+
+  it("returns true when SSH_CLIENT is set", () => {
+    expect(isHeadless({ SSH_CLIENT: "1.2.3.4 1234 22" } as NodeJS.ProcessEnv)).toBe(true);
+  });
+
+  it("returns true when CODESPACES is true", () => {
+    expect(isHeadless({ CODESPACES: "true" } as NodeJS.ProcessEnv)).toBe(true);
+  });
+
+  it("returns true when LINKEDCLAW_FORCE_DEVICE_FLOW is 1", () => {
+    expect(isHeadless({ LINKEDCLAW_FORCE_DEVICE_FLOW: "1" } as NodeJS.ProcessEnv)).toBe(true);
+  });
+
+  it("returns false on local desktop env (with DISPLAY or non-Linux)", () => {
+    // On Mac (the dev box this runs on), platform is darwin → not headless.
+    expect(isHeadless({} as NodeJS.ProcessEnv)).toBe(false);
+  });
+});
+
+describe("detectLabel", () => {
+  it("includes the version, platform, and host", () => {
+    const label = detectLabel("0.2.0");
+    expect(label).toMatch(/^linkedclaw-cli\/0\.2\.0 on /);
+    expect(label).toContain("(host:");
+  });
+
+  it("truncates at 120 chars", () => {
+    const label = detectLabel("0.2.0");
+    expect(label.length).toBeLessThanOrEqual(120);
+  });
+});