@coldtea/pr-lens-cli 0.6.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldtea/pr-lens-cli",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "The PR Lens command line: turn a pull request diff into a schema-valid graph with your own model key, render it, and compose the comment.",
   "license": "MIT",
   "author": "Coldtea AI",
@@ -40,8 +40,8 @@
   "dependencies": {
     "yaml": "^2.8.1",
     "zod": "^4.4.3",
-    "@coldtea/pr-lens-renderer": "^0.2.5",
-    "@coldtea/pr-lens-schema": "^0.3.0"
+    "@coldtea/pr-lens-schema": "^0.4.0",
+    "@coldtea/pr-lens-renderer": "^0.2.6"
   },
   "devDependencies": {
     "@types/node": "^20.19.0",

package/src/account.ts

@@ -0,0 +1,302 @@
+/**
+ * Sign-in is the OAuth 2.0 device grant (RFC 8628), the one flow that works
+ * over SSH and in containers. Its wire codes are the RFC's, not this CLI's.
+ */
+import { z } from "zod";
+import { createHash } from "node:crypto";
+import { assertNever } from "@coldtea/pr-lens-schema";
+
+import { CLI_VERSION } from "./version.js";
+import { PrLensCliError } from "./errors.js";
+
+const REQUEST_TIMEOUT_MS = 30_000;
+
+const hostOf = (api: string): string => new URL(api).host;
+
+const unavailable = (
+  api: string,
+  details: string,
+  status?: number,
+): PrLensCliError =>
+  new PrLensCliError(
+    "APP_UNAVAILABLE",
+    status === undefined
+      ? `${hostOf(api)} did not answer`
+      : `${hostOf(api)} answered ${status}`,
+    details,
+  );
+
+type Answer = { status: number; body: unknown };
+
+const parseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+const send = async (
+  api: string,
+  path: string,
+  init: { method: "GET" | "POST" | "DELETE"; token?: string; body?: unknown },
+): Promise<Answer> => {
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    "user-agent": `pr-lens-cli/${CLI_VERSION}`,
+  };
+  if (init.token !== undefined) headers.authorization = `Bearer ${init.token}`;
+  if (init.body !== undefined) headers["content-type"] = "application/json";
+
+  const response = await fetch(`${api}${path}`, {
+    method: init.method,
+    headers,
+    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+    // A redirect would carry the token to whatever host answered.
+    redirect: "manual",
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  }).catch(() => {
+    // The runtime's message leaks addresses and internals.
+    throw unavailable(api, "check the address and the connection, then try again");
+  });
+
+  if (response.status >= 300 && response.status < 400)
+    throw unavailable(api, "this address redirects, and the sign-in routes must answer directly", response.status);
+
+  const text = await response.text().catch(() => {
+    throw unavailable(api, "the answer was cut off; check the connection, then try again", response.status);
+  });
+
+  return { status: response.status, body: parseJson(text) };
+};
+
+/** Refusals outside the device flow use the app's own envelope. */
+const Refusal = z.object({
+  error: z.looseObject({ code: z.string(), message: z.string() }),
+});
+
+const Started = z.object({
+  device_code: z.string().min(1),
+  user_code: z.string().min(1),
+  verification_uri: z.string().min(1),
+  verification_uri_complete: z.string().min(1).optional(),
+  expires_in: z.number().int().positive(),
+  interval: z.number().int().nonnegative().optional(),
+});
+
+export type StartedSignIn = {
+  deviceCode: string;
+  userCode: string;
+  /** Carries the code, so nobody types it. */
+  approveUrl: string;
+  expiresInSeconds: number;
+  intervalSeconds: number;
+};
+
+/** RFC 8628 §3.2: the floor, and the default when none is served. */
+export const DEFAULT_INTERVAL_SECONDS = 5;
+
+/** The install id goes with the request: the approving browser may be on a phone and cannot know which machine asked. */
+export const startSignIn = async (
+  api: string,
+  installId: string,
+  client: string,
+  name: string,
+): Promise<StartedSignIn> => {
+  const answer = await send(api, "/api/device/code", {
+    method: "POST",
+    body: { install_id: installId, client, name },
+  });
+
+  if (answer.status !== 200) {
+    const refused = Refusal.safeParse(answer.body);
+    const code = refused.success ? refused.data.error.code : undefined;
+    // Twenty codes an hour per address. Usually a retry after a typo, so say what to do next.
+    throw code === "RATE_LIMITED"
+      ? new PrLensCliError(
+          "APP_UNAVAILABLE",
+          `${hostOf(api)} has handed this machine enough sign-in codes for now`,
+          "it goes by the hour, so a short wait clears it; the sign-in you already have is unaffected",
+        )
+      : unavailable(
+          api,
+          refused.success ? refused.data.error.message : "the answer was not in the shape the sign-in expects",
+          answer.status,
+        );
+  }
+
+  const started = Started.safeParse(answer.body);
+  if (!started.success)
+    throw unavailable(api, "the answer was not in the shape the sign-in expects", answer.status);
+
+  return {
+    deviceCode: started.data.device_code,
+    userCode: started.data.user_code,
+    approveUrl: started.data.verification_uri_complete ?? started.data.verification_uri,
+    expiresInSeconds: started.data.expires_in,
+    intervalSeconds: started.data.interval ?? DEFAULT_INTERVAL_SECONDS,
+  };
+};
+
+/** `claimed` is an app extension (RFC 6749 §5.1 allows it); optional so a sign-in never fails over it. */
+const Granted = z.object({
+  access_token: z.string().min(1),
+  claimed: z.coerce.number().int().min(0).optional(),
+});
+
+const Pending = z.object({
+  error: z.enum(["authorization_pending", "slow_down", "access_denied", "expired_token"]),
+  interval: z.number().int().nonnegative().optional(),
+});
+
+export type PollOutcome =
+  | { type: "token"; token: string; claimed: number | undefined }
+  | { type: "pending" }
+  | { type: "slow_down"; intervalSeconds: number | undefined }
+  | { type: "denied" }
+  | { type: "expired" };
+
+export const pollSignIn = async (api: string, deviceCode: string): Promise<PollOutcome> => {
+  const answer = await send(api, "/api/device/token", {
+    method: "POST",
+    body: { device_code: deviceCode, grant_type: "urn:ietf:params:oauth:grant-type:device_code" },
+  });
+
+  if (answer.status === 200) {
+    const granted = Granted.safeParse(answer.body);
+    if (!granted.success)
+      throw unavailable(api, "the sign-in was approved and the answer carried no token", answer.status);
+    return { type: "token", token: granted.data.access_token, claimed: granted.data.claimed };
+  }
+
+  const pending = Pending.safeParse(answer.body);
+  if (!pending.success)
+    // Includes `invalid_request`, which waiting will not fix.
+    throw unavailable(api, "the answer was not one the device flow defines", answer.status);
+
+  switch (pending.data.error) {
+    case "authorization_pending":
+      return { type: "pending" };
+    case "slow_down":
+      return { type: "slow_down", intervalSeconds: pending.data.interval };
+    case "access_denied":
+      return { type: "denied" };
+    case "expired_token":
+      return { type: "expired" };
+    default:
+      return assertNever(pending.data.error, "Unhandled device flow answer");
+  }
+};
+
+/**
+ * Must match the app's hash. Duplicated on purpose: asking the app for ours
+ * would put the install id in a URL.
+ */
+export const installHash = (installId: string): string =>
+  createHash("sha256").update(installId, "utf8").digest("hex");
+
+const Machines = z.object({
+  machines: z.array(z.object({ id: z.string(), revoked: z.boolean() })),
+});
+
+/** `unknown`: this machine has no install id to look up. */
+export type MachineState = "linked" | "revoked" | "unlinked" | "unknown";
+
+export type SignInCheck =
+  | { type: "live"; machine: MachineState }
+  | { type: "rejected" }
+  /** The app could not be asked; says nothing about the credential. */
+  | { type: "unknown"; why: string };
+
+/**
+ * `/api/machines` also answers whether this machine is linked. A store without
+ * accounts reads as `unknown`, never as a revoked credential.
+ */
+export const checkSignIn = async (
+  api: string,
+  token: string,
+  ourInstallId: string | undefined,
+): Promise<SignInCheck> => {
+  let answer: Answer;
+  try {
+    answer = await send(api, "/api/machines", { method: "GET", token });
+  } catch (error) {
+    if (!(error instanceof PrLensCliError)) throw error;
+    return { type: "unknown", why: error.message };
+  }
+
+  if (answer.status === 401 || answer.status === 403) return { type: "rejected" };
+
+  const machines = Machines.safeParse(answer.body);
+  if (!machines.success)
+    return { type: "unknown", why: `${hostOf(api)} answered ${answer.status}, which this CLI cannot read` };
+
+  if (ourInstallId === undefined) return { type: "live", machine: "unknown" };
+
+  const ours = installHash(ourInstallId);
+  const machine = machines.data.machines.find((entry) => entry.id === ours);
+
+  return {
+    type: "live",
+    machine: machine === undefined ? "unlinked" : machine.revoked ? "revoked" : "linked",
+  };
+};
+
+const Account = z.object({ email: z.string().min(3) });
+
+/** Undefined on any failure: the sign-in already succeeded and the email is only for the greeting. */
+export const whoAmI = async (api: string, token: string): Promise<string | undefined> => {
+  try {
+    const answer = await send(api, "/api/account", { method: "GET", token });
+    const account = Account.safeParse(answer.body);
+    return answer.status === 200 && account.success ? account.data.email : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Unlike `whoAmI`, keeps a dead token (`ended`) apart from an unreachable store
+ * (`unknown`), which the sign-in flow will report itself.
+ */
+export type Session =
+  | { type: "active"; email: string }
+  | { type: "ended" }
+  | { type: "unknown" };
+
+export const checkSession = async (api: string, token: string): Promise<Session> => {
+  let answer: Awaited<ReturnType<typeof send>>;
+  try {
+    answer = await send(api, "/api/account", { method: "GET", token });
+  } catch {
+    return { type: "unknown" };
+  }
+
+  // Any other status is an outage, not evidence about the credential.
+  if (answer.status === 401 || answer.status === 403) return { type: "ended" };
+
+  const account = Account.safeParse(answer.body);
+  return answer.status === 200 && account.success
+    ? { type: "active", email: account.data.email }
+    : { type: "unknown" };
+};
+
+export type SignOut = "ended" | "already" | { type: "unreachable"; why: string };
+
+/**
+ * Ends the session and leaves the machine linked (`DELETE /api/machines/{id}`
+ * would unlink it). Unreachable is not thrown: the caller forgets the token
+ * locally either way.
+ */
+export const endSession = async (api: string, token: string): Promise<SignOut> => {
+  try {
+    const answer = await send(api, "/api/session", { method: "DELETE", token });
+    if (answer.status === 200) return "ended";
+    // No such route, or the token was already dead.
+    if (answer.status === 404 || answer.status === 401) return "already";
+    return { type: "unreachable", why: `${hostOf(api)} answered ${answer.status}` };
+  } catch (error) {
+    if (!(error instanceof PrLensCliError)) throw error;
+    return { type: "unreachable", why: error.message };
+  }
+};

package/src/auth.ts

@@ -0,0 +1,183 @@
+/**
+ * The sign-in credential on disk, one file per store so a token never reaches
+ * the wrong one. A file per origin also means two shells signing in at once
+ * can only race on the same origin, where the last write wins correctly.
+ * `0600` on the file, `0700` on the directory: the file names reveal which
+ * stores this person signs in to.
+ */
+import { dirname } from "node:path";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { assertNever } from "@coldtea/pr-lens-schema";
+
+import { PrLensCliError } from "./errors.js";
+import { writeSecretJsonFile } from "./io.js";
+import { originPath } from "./config-home.js";
+
+const CREDENTIALS = "auth";
+
+/**
+ * Read with `||`, never `??`: the Action sets it to "" when no token was
+ * given, since Actions cannot omit an `env` key conditionally.
+ */
+export const TOKEN_ENV = "PR_LENS_TOKEN";
+
+const ACCOUNT_TOKEN = /^prl_u_[A-Za-z0-9_-]{22}$/;
+
+export const authPath = (
+  env: Record<string, string | undefined>,
+  api: string,
+): string | undefined => originPath(env, CREDENTIALS, api);
+
+export type Credential = { token: string; signedInAt: string | undefined };
+
+/**
+ * An unreadable file is kept apart from a missing one and never deleted here:
+ * it may hold a working token. Only `auth logout` removes it.
+ */
+export type CredentialRead =
+  | { type: "credential"; path: string; credential: Credential }
+  | { type: "none" }
+  | { type: "unreadable"; path: string; why: string };
+
+const describe = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const missing = (error: unknown): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  "code" in error &&
+  error.code === "ENOENT";
+
+const credentialIn = (text: string): Credential | undefined => {
+  const contents = ((): unknown => {
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      return undefined;
+    }
+  })();
+  if (typeof contents !== "object" || contents === null) return undefined;
+
+  const { token, signedInAt } = contents as {
+    token?: unknown;
+    signedInAt?: unknown;
+  };
+  if (typeof token !== "string" || !ACCOUNT_TOKEN.test(token)) return undefined;
+
+  return {
+    token,
+    signedInAt: typeof signedInAt === "string" ? signedInAt : undefined,
+  };
+};
+
+export const readCredential = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<CredentialRead> => {
+  const path = authPath(env, api);
+  if (path === undefined) return { type: "none" };
+
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    return missing(error)
+      ? { type: "none" }
+      : { type: "unreadable", path, why: describe(error) };
+  }
+
+  const credential = credentialIn(text);
+  return credential === undefined
+    ? { type: "unreadable", path, why: "it holds no token this CLI can read" }
+    : { type: "credential", path, credential };
+};
+
+/** Every failure answers undefined, so a push never starts failing over an account. */
+export const readToken = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<string | undefined> => {
+  const given = env[TOKEN_ENV];
+  if (given) return given;
+
+  const stored = await readCredential(env, api);
+  return stored.type === "credential" ? stored.credential.token : undefined;
+};
+
+/**
+ * For account commands, which must tell an unreadable file apart from being
+ * signed out rather than advise signing in again.
+ */
+export const requireToken = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<string> => {
+  const given = env[TOKEN_ENV];
+  if (given) return given;
+
+  const host = new URL(api).host;
+  const stored = await readCredential(env, api);
+  switch (stored.type) {
+    case "credential":
+      return stored.credential.token;
+    case "unreadable":
+      throw new PrLensCliError(
+        "UNREADABLE_FILE",
+        `the sign-in for ${host} cannot be read`,
+        [
+          `${stored.path}: ${stored.why}`,
+          "pr-lens auth logout clears it, and then auth login writes a fresh one",
+        ].join("\n"),
+      );
+    case "none":
+      throw new PrLensCliError(
+        "AUTH_REQUIRED",
+        `not signed in to ${host}`,
+        "pr-lens auth login",
+      );
+    default:
+      return assertNever(stored, "Unhandled credential read");
+  }
+};
+
+export const writeCredential = async (
+  env: Record<string, string | undefined>,
+  api: string,
+  token: string,
+  now: string,
+): Promise<string> => {
+  const path = authPath(env, api);
+  if (path === undefined)
+    throw new PrLensCliError(
+      "UNREADABLE_FILE",
+      "there is no home directory to keep this sign-in in",
+      "set HOME, or XDG_CONFIG_HOME, to somewhere this machine can write",
+    );
+
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  return writeSecretJsonFile(path, { api, token, signedInAt: now });
+};
+
+/**
+ * The only place that removes the file, readable or not. No read first: a
+ * sign-in from another shell in between would be thrown away unseen.
+ */
+export const forgetCredential = async (
+  env: Record<string, string | undefined>,
+  api: string,
+): Promise<boolean> => {
+  const path = authPath(env, api);
+  if (path === undefined) return false;
+
+  try {
+    await rm(path);
+    return true;
+  } catch (error) {
+    if (missing(error)) return false;
+    throw new PrLensCliError(
+      "UNREADABLE_FILE",
+      `cannot remove ${path}`,
+      describe(error),
+    );
+  }
+};

package/src/canvas/api.ts

@@ -85,6 +85,8 @@ const Refusal = z.discriminatedUnion("code", [
     retryAt: z.string(),
   }),
   z.object({ code: z.literal("TOO_LARGE"), message: z.string() }),
+  z.object({ code: z.literal("UNAUTHENTICATED"), message: z.string() }),
+  z.object({ code: z.literal("ALREADY_OWNED"), message: z.string() }),
 ]);
 
 type Request = {
@@ -93,6 +95,8 @@ type Request = {
   /** Undefined when minting, so a 404 there is not blamed on a canvas. */
   canvas: string | undefined;
   token?: string;
+  /** Lets a later sign-in claim what this machine pushed. */
+  install?: string;
   ifMatch?: number;
   body?: unknown;
 };
@@ -112,6 +116,25 @@ const unavailable = (
     details,
   );
 
+/** Untrusted server content, so printable and short. */
+const LOCATION_SHOWN = 200;
+
+/** Printing the target turns an `http://` for `https://` typo into a fix. */
+const redirected = (api: string, response: Response): PrLensCliError => {
+  const location = response.headers
+    .get("location")
+    ?.replace(/[^\x20-\x7e]/g, "")
+    .slice(0, LOCATION_SHOWN);
+
+  return unavailable(
+    api,
+    response.status,
+    location === undefined || location === ""
+      ? "the canvas API answers at the address it is given, and this one redirects"
+      : `the canvas API answers at the address it is given; this one points at ${location}, so pass that as --api`,
+  );
+};
+
 const parseJson = (text: string): unknown => {
   try {
     return JSON.parse(text);
@@ -170,6 +193,21 @@ const refusal = (
         `${hostOf(api)} is rate limiting this client until ${error.retryAt}`,
         error.message,
       );
+    case "UNAUTHENTICATED":
+      return new PrLensCliError(
+        "AUTH_REQUIRED",
+        `${hostOf(api)} did not accept this sign-in`,
+        [error.message, "pr-lens auth login signs this machine in again"].join(
+          "\n",
+        ),
+      );
+    case "ALREADY_OWNED":
+      // The caller holds the write token, so naming the case leaks nothing.
+      return new PrLensCliError(
+        "CANVAS_OWNED",
+        `${request.canvas ?? "that canvas"} belongs to another account on ${hostOf(api)}`,
+        "the first claim wins, and somebody else's landed first",
+      );
     case "INVALID_REQUEST":
     case "TOO_LARGE":
       return unavailable(api, status, error.message);
@@ -191,6 +229,9 @@ const call = async <T>(
   if (request.token !== undefined)
     headers.authorization = `Bearer ${request.token}`;
 
+  if (request.install !== undefined)
+    headers["x-pr-lens-install"] = request.install;
+
   if (request.ifMatch !== undefined)
     headers["if-match"] = String(request.ifMatch);
 
@@ -200,6 +241,9 @@ const call = async <T>(
     method: request.method,
     headers,
     body: request.body === undefined ? undefined : JSON.stringify(request.body),
+    // A cross-origin redirect keeps every header but `authorization`, which
+    // would leak the install id to another host.
+    redirect: "manual",
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   }).catch(() => {
     // The runtime's message names addresses and internals; keep it out.
@@ -210,6 +254,10 @@ const call = async <T>(
     );
   });
 
+  // A 3xx body is not an error envelope.
+  if (response.status >= 300 && response.status < 400)
+    throw redirected(api, response);
+
   // A body can fail after the headers arrived.
   const text = await response.text().catch(() => {
     throw unavailable(
@@ -234,8 +282,17 @@ const call = async <T>(
 
 const canvasPath = (id: string): string => `/api/canvas/${id}`;
 
-export const mintCanvas = (api: string): Promise<Minted> =>
-  call(api, { method: "POST", path: "/api/canvas", canvas: undefined }, Minted);
+/** The bearer is how CI attributes a mint: a runner's install id is never linked. */
+export const mintCanvas = (
+  api: string,
+  install: string | undefined,
+  token: string | undefined,
+): Promise<Minted> =>
+  call(
+    api,
+    { method: "POST", path: "/api/canvas", canvas: undefined, install, token },
+    Minted,
+  );
 
 export const fetchCanvas = async (
   api: string,
@@ -322,3 +379,58 @@ export const deleteCanvas = (
     { method: "DELETE", path: canvasPath(id), canvas: id, token },
     z.object({ id: z.literal(id), deleted: z.literal(true) }),
   );
+
+/** An unreadable revision must not read as an empty canvas. */
+const Preview = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("drawn"), title: z.string().min(1) }),
+  z.object({ type: z.literal("not_drawn") }),
+  z.object({ type: z.literal("unreadable") }),
+]);
+
+const Owned = z.object({
+  id: z.string(),
+  rev: z.number().int(),
+  preview: Preview,
+});
+
+const Owning = z.object({ canvases: z.array(Owned) });
+
+export type CanvasPreview = z.infer<typeof Preview>;
+export type OwnedCanvas = z.infer<typeof Owned>;
+
+/**
+ * Carries no write tokens: the app keeps only their hashes. A store without
+ * accounts 404s here, which reads as unavailable, not as a missing canvas.
+ */
+export const listOwnedCanvases = (
+  api: string,
+  token: string,
+): Promise<OwnedCanvas[]> =>
+  call(
+    api,
+    { method: "GET", path: "/api/canvases", canvas: undefined, token },
+    Owning,
+  ).then(({ canvases }) => canvases);
+
+/**
+ * The account token takes the header, so the write tokens go in the body.
+ * The caller mints the next token so a lost answer can be replayed.
+ */
+export const claimCanvas = (
+  api: string,
+  id: string,
+  accountToken: string,
+  writeToken: string,
+  nextWriteToken: string,
+): Promise<Rotated> =>
+  call(
+    api,
+    {
+      method: "POST",
+      path: `${canvasPath(id)}/claim`,
+      canvas: id,
+      token: accountToken,
+      body: { writeToken, nextWriteToken },
+    },
+    Rotated,
+  );