@hraness/dawg 0.0.0-stage → 0.3.0

package/src/auth/openrouter.ts

@@ -0,0 +1,206 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { isValidKey } from "./credentials.ts";
+
+/**
+ * OpenRouter's OAuth PKCE flow for apps
+ * (https://openrouter.ai/docs/use-cases/oauth-pkce): open
+ * `https://openrouter.ai/auth?callback_url=…&code_challenge=…&code_challenge_method=S256`,
+ * receive `?code=` on a localhost callback (any port is allowed), then
+ * exchange it with `POST /api/v1/auth/keys` for a user-controlled key.
+ */
+export const OPENROUTER_AUTH_URL = "https://openrouter.ai/auth";
+export const OPENROUTER_API_URL = "https://openrouter.ai/api/v1";
+export const OPENROUTER_KEYS_URL = "https://openrouter.ai/settings/keys";
+export const OAUTH_TIMEOUT_MS = 5 * 60_000;
+const MAX_EXCHANGE_BYTES = 16 * 1024;
+const CODE_PATTERN = /^[A-Za-z0-9._~-]{8,512}$/;
+
+type Fetcher = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type Pkce = Readonly<{
+  verifier: string;
+  challenge: string;
+  state: string;
+}>;
+
+function base64url(bytes: Buffer): string {
+  return bytes
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/** A 43-character verifier, its S256 challenge, and a CSRF state. */
+export function createPkce(
+  random: (size: number) => Buffer = randomBytes,
+): Pkce {
+  const verifier = base64url(random(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge, state: base64url(random(16)) };
+}
+
+export function authorizeUrl(
+  callbackUrl: string,
+  pkce: Pkce,
+  base = OPENROUTER_AUTH_URL,
+): string {
+  const url = new URL(base);
+  url.searchParams.set("callback_url", callbackUrl);
+  url.searchParams.set("code_challenge", pkce.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("key_label", "dawg");
+  url.searchParams.set("state", pkce.state);
+  return url.toString();
+}
+
+function sameSecret(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+const PAGE = (title: string, body: string) =>
+  `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font:16px system-ui;margin:3rem;max-width:32rem"><h1 style="font-size:1.4rem">${title}</h1><p>${body}</p></body>`;
+
+export type CallbackServer = Readonly<{
+  /** `http://127.0.0.1:<port>/callback`. */
+  url: string;
+  /** Resolves with the code once a request carries the right state. */
+  code: Promise<string>;
+  stop(): void;
+}>;
+
+/**
+ * A one-shot callback listener on 127.0.0.1 and an ephemeral port. Requests
+ * with a missing or wrong `state` are refused and do not end the wait.
+ */
+export function startCallbackServer(
+  state: string,
+  options: { signal?: AbortSignal; timeoutMs?: number } = {},
+): CallbackServer {
+  let settle: { resolve(code: string): void; reject(error: Error): void };
+  const code = new Promise<string>((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  code.catch(() => undefined);
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch(request) {
+      const url = new URL(request.url);
+      if (url.pathname !== "/callback")
+        return new Response("not found", { status: 404 });
+      const html = (status: number, title: string, body: string) =>
+        new Response(PAGE(title, body), {
+          status,
+          headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "referrer-policy": "no-referrer",
+          },
+        });
+      const got = url.searchParams.get("state") ?? "";
+      const value = url.searchParams.get("code") ?? "";
+      if (!sameSecret(got, state))
+        return html(
+          400,
+          "Sign-in not recognized",
+          "This link does not match the sign-in dawg started. Return to the terminal and try again.",
+        );
+      if (!CODE_PATTERN.test(value)) {
+        settle.reject(
+          new Error("OpenRouter did not return a code (access denied?)"),
+        );
+        return html(
+          400,
+          "Sign-in cancelled",
+          "No authorization code came back. You can close this tab.",
+        );
+      }
+      settle.resolve(value);
+      return html(
+        200,
+        "dawg is connected to OpenRouter",
+        "You can close this tab and return to the terminal.",
+      );
+    },
+  });
+  const timer = setTimeout(
+    () => settle.reject(new Error("timed out waiting for the browser")),
+    options.timeoutMs ?? OAUTH_TIMEOUT_MS,
+  );
+  const onAbort = () => settle.reject(new Error("sign-in cancelled"));
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const stop = () => {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+    // Graceful first so the browser still gets the "connected" page, then
+    // force-close any idle keep-alive sockets.
+    void server.stop(false);
+    setTimeout(() => void server.stop(true), 1_000).unref?.();
+  };
+  void code.then(stop, stop);
+  return { url: `http://127.0.0.1:${server.port}/callback`, code, stop };
+}
+
+/** `POST /api/v1/auth/keys` → the user's new key. */
+export async function exchangeCode(
+  code: string,
+  pkce: Pick<Pkce, "verifier">,
+  options: { fetcher?: Fetcher; baseUrl?: string } = {},
+): Promise<string> {
+  const fetcher = options.fetcher ?? fetch;
+  const base = (options.baseUrl ?? OPENROUTER_API_URL).replace(/\/$/, "");
+  const response = await fetcher(`${base}/auth/keys`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      code,
+      code_verifier: pkce.verifier,
+      code_challenge_method: "S256",
+    }),
+    signal: AbortSignal.timeout(20_000),
+  });
+  const text = (await response.text()).slice(0, MAX_EXCHANGE_BYTES);
+  if (!response.ok)
+    throw new Error(
+      response.status === 403
+        ? "OpenRouter refused the code (expired or already used)"
+        : `OpenRouter key exchange failed (${response.status})`,
+    );
+  let key: unknown;
+  try {
+    key = (JSON.parse(text) as { key?: unknown }).key;
+  } catch {
+    key = undefined;
+  }
+  if (!isValidKey(key)) throw new Error("OpenRouter returned no usable key");
+  return key;
+}
+
+export type KeyCheck = "valid" | "rejected" | "unverified";
+
+/** `GET /api/v1/key`: cheap, authenticated, and spends nothing. */
+export async function checkOpenRouterKey(
+  key: string,
+  options: { fetcher?: Fetcher; baseUrl?: string } = {},
+): Promise<KeyCheck> {
+  const fetcher = options.fetcher ?? fetch;
+  const base = (options.baseUrl ?? OPENROUTER_API_URL).replace(/\/$/, "");
+  try {
+    const response = await fetcher(`${base}/key`, {
+      headers: { authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(8_000),
+    });
+    await response.body?.cancel().catch(() => undefined);
+    if (response.ok) return "valid";
+    if (response.status === 401 || response.status === 403) return "rejected";
+    return "unverified";
+  } catch {
+    return "unverified";
+  }
+}

package/src/auth/picker.ts

@@ -0,0 +1,282 @@
+import { stdin, stdout } from "node:process";
+
+/**
+ * A small inline picker for the shell (`dawg login`, `dawg model`), in the
+ * style of the Codex CLI sign-in: ↑/↓ or j/k move, Enter chooses, 1-9 jump
+ * and choose, typing filters (when enabled), Esc or Ctrl-C cancels. It draws
+ * below the cursor and erases itself afterwards, so the scrollback keeps only
+ * the one-line result the caller prints.
+ */
+export type ChoiceItem = Readonly<{
+  label: string;
+  /** Right-hand muted text: a status, a price. */
+  detail?: string;
+  /** Section heading shown above the first row of each group. */
+  group?: string;
+  /** Rows that cannot be chosen still show (e.g. "not set up"). */
+  disabled?: boolean;
+  /** Marked with ● (the current model). */
+  current?: boolean;
+}>;
+
+export type ChooseOptions = Readonly<{
+  initial?: number;
+  /** Type-to-filter on label and detail. */
+  filter?: boolean;
+  /** Footer hint override. */
+  hint?: string;
+}>;
+
+export type PickerKey =
+  | { type: "up" }
+  | { type: "down" }
+  | { type: "enter" }
+  | { type: "cancel" }
+  | { type: "digit"; value: number }
+  | { type: "backspace" }
+  | { type: "text"; text: string };
+
+/** Split one raw stdin read into picker keys. */
+export function parsePickerKeys(data: string): PickerKey[] {
+  const keys: PickerKey[] = [];
+  let rest = data.replace(/\u001b\[20[01]~/g, "");
+  while (rest.length > 0) {
+    if (rest.startsWith("\u001b[A") || rest.startsWith("\u001bOA")) {
+      keys.push({ type: "up" });
+      rest = rest.slice(3);
+    } else if (rest.startsWith("\u001b[B") || rest.startsWith("\u001bOB")) {
+      keys.push({ type: "down" });
+      rest = rest.slice(3);
+    } else if (rest.startsWith("\u001b[")) {
+      // Other CSI sequences (left/right, home, …) are ignored.
+      const match = /^\u001b\[[0-9;]*[A-Za-z~]/.exec(rest);
+      rest = rest.slice(match ? match[0].length : 2);
+    } else {
+      const char = rest[0]!;
+      rest = rest.slice(1);
+      if (char === "\r" || char === "\n") keys.push({ type: "enter" });
+      else if (char === "\u001b" || char === "\u0003")
+        keys.push({ type: "cancel" });
+      else if (char === "\u007f" || char === "\b")
+        keys.push({ type: "backspace" });
+      else if (char === "\u0010") keys.push({ type: "up" });
+      else if (char === "\u000e") keys.push({ type: "down" });
+      else if (char >= " ") keys.push({ type: "text", text: char });
+    }
+  }
+  return keys;
+}
+
+/** The picker's pure state; `step` applies one key. */
+export class PickerModel {
+  index: number;
+  query = "";
+  constructor(
+    readonly items: readonly ChoiceItem[],
+    readonly options: ChooseOptions = {},
+  ) {
+    const visible = this.visible();
+    const initial = options.initial ?? 0;
+    const start = visible.indexOf(initial) >= 0 ? initial : (visible[0] ?? 0);
+    this.index = start;
+  }
+
+  /** Indices of rows matching the filter, in order. */
+  visible(): number[] {
+    const query = this.query.toLowerCase();
+    return this.items
+      .map((item, index) => ({ item, index }))
+      .filter(
+        ({ item }) =>
+          !query ||
+          item.label.toLowerCase().includes(query) ||
+          (item.detail ?? "").toLowerCase().includes(query) ||
+          (item.group ?? "").toLowerCase().includes(query),
+      )
+      .map(({ index }) => index);
+  }
+
+  /** `undefined` while picking, a row index when chosen, `null` on cancel. */
+  step(key: PickerKey): number | null | undefined {
+    const visible = this.visible();
+    const position = Math.max(0, visible.indexOf(this.index));
+    const move = (delta: number) => {
+      if (visible.length === 0) return;
+      for (let offset = 1; offset <= visible.length; offset += 1) {
+        const n = visible.length;
+        const next = visible[(((position + delta * offset) % n) + n) % n]!;
+        if (!this.items[next]?.disabled) {
+          this.index = next;
+          return;
+        }
+      }
+    };
+    switch (key.type) {
+      case "up":
+        move(-1);
+        return undefined;
+      case "down":
+        move(1);
+        return undefined;
+      case "enter":
+        return visible.includes(this.index) && !this.items[this.index]?.disabled
+          ? this.index
+          : undefined;
+      case "cancel":
+        if (this.query) {
+          this.query = "";
+          this.refocus();
+          return undefined;
+        }
+        return null;
+      case "backspace":
+        this.query = this.query.slice(0, -1);
+        this.refocus();
+        return undefined;
+      case "digit": {
+        const target = visible[key.value - 1];
+        if (target !== undefined && !this.items[target]?.disabled)
+          return target;
+        return undefined;
+      }
+      case "text":
+        if (/^[1-9]$/.test(key.text) && !this.query)
+          return this.step({ type: "digit", value: Number(key.text) });
+        if (!this.options.filter) {
+          if (key.text === "k") move(-1);
+          if (key.text === "j") move(1);
+          return undefined;
+        }
+        if (this.query.length < 40) this.query += key.text;
+        this.refocus();
+        return undefined;
+    }
+  }
+
+  private refocus(): void {
+    const visible = this.visible().filter(
+      (index) => !this.items[index]?.disabled,
+    );
+    if (!visible.includes(this.index) && visible.length > 0)
+      this.index = visible[0]!;
+  }
+
+  /** Plain lines (no colour); the renderer styles them. */
+  lines(
+    title: string,
+    maxRows = 14,
+  ): {
+    text: string;
+    kind: "title" | "group" | "row" | "selected" | "muted" | "hint";
+  }[] {
+    const out: {
+      text: string;
+      kind: "title" | "group" | "row" | "selected" | "muted" | "hint";
+    }[] = [
+      {
+        text: title + (this.query ? `  filter: ${this.query}` : ""),
+        kind: "title",
+      },
+    ];
+    const visible = this.visible();
+    if (visible.length === 0) out.push({ text: "  no matches", kind: "muted" });
+    const position = Math.max(0, visible.indexOf(this.index));
+    const first = Math.max(
+      0,
+      Math.min(visible.length - maxRows, position - Math.floor(maxRows / 2)),
+    );
+    let lastGroup: string | undefined;
+    visible.slice(first, first + maxRows).forEach((index, offset) => {
+      const item = this.items[index]!;
+      if (item.group && item.group !== lastGroup) {
+        out.push({ text: `  ${item.group}`, kind: "group" });
+      }
+      lastGroup = item.group;
+      const selected = index === this.index;
+      const number =
+        first + offset < 9 && !this.query ? `${first + offset + 1}.` : "  ";
+      const mark = item.current ? "●" : " ";
+      out.push({
+        text: `${selected ? "›" : " "} ${number} ${mark} ${item.label}${item.detail ? `  ${item.detail}` : ""}`,
+        kind: selected ? "selected" : item.disabled ? "muted" : "row",
+      });
+    });
+    out.push({
+      text:
+        this.options.hint ??
+        `  ↑/↓ move · enter choose · 1-9 pick${this.options.filter ? " · type to filter" : ""} · esc cancel`,
+      kind: "hint",
+    });
+    return out;
+  }
+}
+
+const ESC = "\u001b[";
+
+function style(kind: string, text: string, color: boolean): string {
+  if (!color) return text;
+  if (kind === "title") return `${ESC}1m${text}${ESC}0m`;
+  if (kind === "selected") return `${ESC}1;36m${text}${ESC}0m`;
+  if (kind === "group") return `${ESC}2;4m${text}${ESC}0m`;
+  if (kind === "muted" || kind === "hint") return `${ESC}2m${text}${ESC}0m`;
+  return text;
+}
+
+/**
+ * Run a picker on the real terminal. Resolves the chosen index, or
+ * `undefined` on Esc / Ctrl-C. Requires a TTY on stdin and stdout.
+ */
+export function chooseOnTerminal(
+  title: string,
+  items: readonly ChoiceItem[],
+  options: ChooseOptions = {},
+): Promise<number | undefined> {
+  const model = new PickerModel(items, options);
+  const color = !process.env.NO_COLOR && process.env.TERM !== "dumb";
+  const width = () => Math.max(20, (stdout.columns ?? 80) - 1);
+  let drawn = 0;
+  const draw = () => {
+    const lines = model.lines(
+      title,
+      Math.max(4, Math.min(14, (stdout.rows ?? 24) - 6)),
+    );
+    let out = drawn > 0 ? `\r${ESC}${drawn - 1}A` : "\r";
+    out += `${ESC}J`;
+    out += lines
+      .map((line) => style(line.kind, truncate(line.text, width()), color))
+      .join("\r\n");
+    drawn = lines.length;
+    stdout.write(`${ESC}?25l${out}`);
+  };
+  const erase = () => {
+    if (drawn > 0) stdout.write(`\r${ESC}${drawn - 1}A${ESC}J`);
+    stdout.write(`${ESC}?25h`);
+  };
+  return new Promise((resolve) => {
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    const finish = (result: number | undefined) => {
+      stdin.off("data", onData);
+      stdin.setRawMode?.(wasRaw);
+      stdin.pause();
+      erase();
+      resolve(result);
+    };
+    const onData = (chunk: Buffer) => {
+      for (const key of parsePickerKeys(chunk.toString("utf8"))) {
+        const result = model.step(key);
+        if (result === null) return finish(undefined);
+        if (result !== undefined) return finish(result);
+      }
+      draw();
+    };
+    stdin.on("data", onData);
+    draw();
+  });
+}
+
+function truncate(text: string, width: number): string {
+  const chars = [...text];
+  return chars.length > width ? `${chars.slice(0, width - 1).join("")}…` : text;
+}

package/src/auth/runner.ts

@@ -0,0 +1,207 @@
+/**
+ * The one place dawg starts helper CLIs (`vercel`, `security`, `xcb`).
+ * Everything above it takes a `CommandRunner`, so tests script the
+ * subprocesses instead of touching real accounts or the keychain.
+ */
+export type RunOptions = Readonly<{
+  /** Written to the child's stdin, then stdin is closed. */
+  stdin?: string;
+  /** Hand the terminal to the child (for `vercel login`). Output is not captured. */
+  inherit?: boolean;
+  timeoutMs?: number;
+  /** Aborting sends SIGTERM and still waits for the child to exit. */
+  signal?: AbortSignal;
+  /** Bound on captured stdout/stderr; excess is dropped. */
+  maxOutputBytes?: number;
+  env?: Readonly<Record<string, string | undefined>>;
+  /**
+   * Called with each decoded chunk as it arrives (progress parsing). Chunks
+   * keep flowing past `maxOutputBytes`; only the captured text is bounded.
+   */
+  onOutput?: (stream: "stdout" | "stderr", chunk: string) => void;
+}>;
+
+export type RunResult = Readonly<{
+  code: number;
+  stdout: string;
+  stderr: string;
+  /** True when the child was stopped by `signal` or `timeoutMs`. */
+  killed: boolean;
+}>;
+
+export type CommandRunner = Readonly<{
+  run(
+    command: string,
+    args: readonly string[],
+    options?: RunOptions,
+  ): Promise<RunResult>;
+  /** Absolute path of an executable on PATH, or undefined. */
+  which(command: string): string | undefined;
+}>;
+
+const DEFAULT_MAX_OUTPUT = 1024 * 1024;
+const KILL_GRACE_MS = 15_000;
+
+export const systemRunner: CommandRunner = {
+  which: (command) => Bun.which(command) ?? undefined,
+  async run(command, args, options = {}) {
+    const maxBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT;
+    const env = options.env ? { ...process.env, ...options.env } : process.env;
+    if (options.inherit) {
+      const child = Bun.spawn([command, ...args], {
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+        env,
+      });
+      const stop = watchKill(child, options);
+      try {
+        const code = await child.exited;
+        return { code, stdout: "", stderr: "", killed: stop.killed() };
+      } finally {
+        stop.dispose();
+      }
+    }
+    const child = Bun.spawn([command, ...args], {
+      stdin: options.stdin === undefined ? "ignore" : "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      env,
+    });
+    const stop = watchKill(child, options);
+    try {
+      if (options.stdin !== undefined && child.stdin) {
+        try {
+          child.stdin.write(options.stdin);
+          await child.stdin.end();
+        } catch {
+          // The child may exit before reading its input; its exit code reports why.
+        }
+      }
+      const tap = options.onOutput;
+      const [stdout, stderr, code] = await Promise.all([
+        readBounded(
+          child.stdout,
+          maxBytes,
+          tap && ((chunk) => tap("stdout", chunk)),
+        ),
+        readBounded(
+          child.stderr,
+          maxBytes,
+          tap && ((chunk) => tap("stderr", chunk)),
+        ),
+        child.exited,
+      ]);
+      return { code, stdout, stderr, killed: stop.killed() };
+    } finally {
+      stop.dispose();
+    }
+  },
+};
+
+function watchKill(
+  child: { kill(signal?: number | NodeJS.Signals): void },
+  options: RunOptions,
+): { killed(): boolean; dispose(): void } {
+  let killed = false;
+  let escalate: ReturnType<typeof setTimeout> | undefined;
+  const kill = () => {
+    if (killed) return;
+    killed = true;
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // Already exited.
+    }
+    // Callers still await exit; a child that ignores SIGTERM gets SIGKILL.
+    escalate = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // Already exited.
+      }
+    }, KILL_GRACE_MS);
+  };
+  const timer =
+    options.timeoutMs !== undefined
+      ? setTimeout(kill, options.timeoutMs)
+      : undefined;
+  if (options.signal?.aborted) kill();
+  options.signal?.addEventListener("abort", kill, { once: true });
+  return {
+    killed: () => killed,
+    dispose() {
+      if (timer) clearTimeout(timer);
+      if (escalate) clearTimeout(escalate);
+      options.signal?.removeEventListener("abort", kill);
+    },
+  };
+}
+
+async function readBounded(
+  stream: ReadableStream<Uint8Array> | undefined | null,
+  maxBytes: number,
+  tap?: (chunk: string) => void,
+): Promise<string> {
+  if (!stream) return "";
+  const decoder = new TextDecoder();
+  const tapDecoder = tap ? new TextDecoder() : undefined;
+  let text = "";
+  let bytes = 0;
+  for await (const chunk of stream) {
+    if (tap && tapDecoder) {
+      try {
+        tap(tapDecoder.decode(chunk, { stream: true }));
+      } catch {
+        // A progress parser must never stop the drain.
+      }
+    }
+    if (bytes >= maxBytes) continue; // Keep draining so the child never blocks.
+    const room = maxBytes - bytes;
+    const part = chunk.byteLength > room ? chunk.subarray(0, room) : chunk;
+    bytes += part.byteLength;
+    text += decoder.decode(part, { stream: true });
+  }
+  return text + decoder.decode();
+}
+
+/** A scripted runner for tests: each call is matched in order by a predicate. */
+export type ScriptedCall = Readonly<{
+  match: (command: string, args: readonly string[]) => boolean;
+  result?: Partial<RunResult>;
+  respond?: (
+    command: string,
+    args: readonly string[],
+    options: RunOptions,
+  ) => Promise<Partial<RunResult>> | Partial<RunResult>;
+}>;
+
+export function scriptedRunner(
+  script: readonly ScriptedCall[],
+  installed: readonly string[] = [],
+): CommandRunner & {
+  calls: { command: string; args: readonly string[]; options: RunOptions }[];
+} {
+  const calls: {
+    command: string;
+    args: readonly string[];
+    options: RunOptions;
+  }[] = [];
+  const remaining = [...script];
+  return {
+    calls,
+    which: (command) =>
+      installed.includes(command) ? `/usr/local/bin/${command}` : undefined,
+    async run(command, args, options = {}) {
+      calls.push({ command, args, options });
+      const index = remaining.findIndex((step) => step.match(command, args));
+      if (index < 0)
+        throw new Error(`unexpected command: ${command} ${args.join(" ")}`);
+      const [step] = remaining.splice(index, 1);
+      const partial = step!.respond
+        ? await step!.respond(command, args, options)
+        : (step!.result ?? {});
+      return { code: 0, stdout: "", stderr: "", killed: false, ...partial };
+    },
+  };
+}