@monster-orange/den 0.4.3 → 0.4.5

package/src/ui/server/device-flows.ts

@@ -0,0 +1,274 @@
+/**
+ * SEC-2a: the device flows the server runs for the browser. The page asks
+ * for one (Sign in with GitHub on the signed-out page, or Link your GitHub
+ * account in Settings › Access); the server starts it with GitHub, polls
+ * GitHub itself at GitHub's interval, and the page polls the server for the
+ * outcome by the flow's id (a random handle only the page that started it
+ * holds).
+ *
+ *  - The device code never leaves the server; the user code goes to that
+ *    page only. The token lives for one `GET /user` call and is dropped.
+ *  - At most `max` flows (default 3) are pending at once: another start is
+ *    refused (`busy`) until one ends. A pending flow ends at GitHub's
+ *    expiry; a finished one is forgotten a minute later, or when the page
+ *    claims it.
+ *  - What an identity means is the caller's (`decide`): for a sign-in,
+ *    whether it is the owner; for a link, storing it as the owner.
+ *
+ * Clock and timers are injected, so a test drives every step.
+ */
+import { randomBytes } from "crypto";
+import { GITHUB_DEVICE_PAGE } from "../../shared/github-app.js";
+import type {
+  GithubDeviceClient,
+  GithubIdentity,
+} from "../../shared/github-device.js";
+
+export type FlowPurpose = "signin" | "link";
+export type FlowState =
+  | "pending"
+  | "ok"
+  | "refused"
+  | "expired"
+  | "denied"
+  | "error";
+
+/** What the page is told about a flow (never the device code). */
+export interface FlowView {
+  id: string;
+  purpose: FlowPurpose;
+  state: FlowState;
+  userCode: string;
+  verificationUri: string;
+  expiresAt: number;
+  /** ok or refused: the GitHub login that approved it. */
+  login?: string;
+  /** error: what went wrong (no secret in it). */
+  message?: string;
+}
+
+interface Flow extends FlowView {
+  deviceCode: string;
+  intervalMs: number;
+  errors: number;
+  /** ok: who approved it (the id, for the caller). */
+  identity?: GithubIdentity;
+  /** When a finished flow is forgotten. */
+  forgetAt?: number;
+  cancel?: () => void;
+}
+
+export type Schedule = (fn: () => void, ms: number) => () => void;
+
+const defaultSchedule: Schedule = (fn, ms) => {
+  const t = setTimeout(fn, ms);
+  t.unref?.();
+  return () => clearTimeout(t);
+};
+
+/** How long a finished flow waits for its page to claim it. */
+export const FINISHED_KEEP_MS = 60_000;
+/** The most pending flows at once (SEC-2a: "rate-limit concurrent device flows"). */
+export const MAX_PENDING_FLOWS = 3;
+const MAX_ERRORS = 5;
+
+export class DeviceFlows {
+  private readonly flows = new Map<string, Flow>();
+  private readonly client: GithubDeviceClient;
+  private readonly clientId: () => string;
+  private readonly now: () => number;
+  private readonly schedule: Schedule;
+  private readonly max: number;
+  private readonly minIntervalMs: number;
+  private readonly onExpiringToken?: () => void;
+  private readonly decide: (
+    purpose: FlowPurpose,
+    identity: GithubIdentity,
+  ) => "ok" | "refused";
+
+  constructor(opts: {
+    client: GithubDeviceClient;
+    clientId: () => string;
+    decide: (
+      purpose: FlowPurpose,
+      identity: GithubIdentity,
+    ) => "ok" | "refused";
+    now?: () => number;
+    schedule?: Schedule;
+    max?: number;
+    /** The floor between polls (GitHub's interval is never shortened). */
+    minIntervalMs?: number;
+    /**
+     * A token answer carried expires_in or a refresh_token: the app has
+     * token expiry on (a misconfiguration). Called with no token.
+     */
+    onExpiringToken?: () => void;
+  }) {
+    this.onExpiringToken = opts.onExpiringToken;
+    this.client = opts.client;
+    this.clientId = opts.clientId;
+    this.decide = opts.decide;
+    this.now = opts.now ?? Date.now;
+    this.schedule = opts.schedule ?? defaultSchedule;
+    this.max = opts.max ?? MAX_PENDING_FLOWS;
+    this.minIntervalMs = opts.minIntervalMs ?? 1000;
+  }
+
+  /** Pending flows now. */
+  pending(): number {
+    this.sweep();
+    return [...this.flows.values()].filter((f) => f.state === "pending").length;
+  }
+
+  /**
+   * Start a flow with GitHub. `busy` past the cap; `no_client_id` when none
+   * is configured; a GitHub failure throws (its message names no secret).
+   */
+  async start(
+    purpose: FlowPurpose,
+  ): Promise<FlowView | { error: "busy" | "no_client_id" }> {
+    const clientId = this.clientId();
+    if (!clientId) return { error: "no_client_id" };
+    if (this.pending() >= this.max) return { error: "busy" };
+    // Held as pending while GitHub answers, so a burst can't pass the cap.
+    const id = randomBytes(24).toString("base64url");
+    const placeholder: Flow = {
+      id,
+      purpose,
+      state: "pending",
+      userCode: "",
+      verificationUri: GITHUB_DEVICE_PAGE,
+      expiresAt: this.now() + 60_000,
+      deviceCode: "",
+      intervalMs: this.minIntervalMs,
+      errors: 0,
+    };
+    this.flows.set(id, placeholder);
+    let code;
+    try {
+      code = await this.client.start(clientId);
+    } catch (e) {
+      this.flows.delete(id);
+      throw e;
+    }
+    const flow: Flow = {
+      ...placeholder,
+      userCode: code.userCode,
+      deviceCode: code.deviceCode,
+      expiresAt: this.now() + code.expiresIn * 1000,
+      intervalMs: Math.max(code.interval * 1000, this.minIntervalMs),
+    };
+    this.flows.set(id, flow);
+    this.arm(flow);
+    return view(flow);
+  }
+
+  /** A flow's view, or null when there is none (or it was forgotten). */
+  get(id: string, purpose?: FlowPurpose): FlowView | null {
+    this.sweep();
+    const f = this.flows.get(id);
+    if (!f || (purpose && f.purpose !== purpose)) return null;
+    return view(f);
+  }
+
+  /**
+   * The identity of a finished, approved flow, once: the flow is forgotten,
+   * so a second claim gets null (a sign-in makes one session).
+   */
+  claim(id: string, purpose: FlowPurpose): GithubIdentity | null {
+    this.sweep();
+    const f = this.flows.get(id);
+    if (!f || f.purpose !== purpose || f.state !== "ok" || !f.identity)
+      return null;
+    this.flows.delete(id);
+    return f.identity;
+  }
+
+  /** Stop every flow (the server is stopping). */
+  stopAll(): void {
+    for (const f of this.flows.values()) f.cancel?.();
+    this.flows.clear();
+  }
+
+  private arm(f: Flow): void {
+    f.cancel = this.schedule(() => void this.tick(f.id), f.intervalMs);
+  }
+
+  private finish(
+    f: Flow,
+    state: Exclude<FlowState, "pending">,
+    extra: Partial<Flow> = {},
+  ): void {
+    Object.assign(f, extra, {
+      state,
+      deviceCode: "",
+      forgetAt: this.now() + FINISHED_KEEP_MS,
+    });
+    f.cancel?.();
+    f.cancel = undefined;
+  }
+
+  private async tick(id: string): Promise<void> {
+    const f = this.flows.get(id);
+    if (!f || f.state !== "pending") return;
+    if (this.now() >= f.expiresAt) return this.finish(f, "expired");
+    const r = await this.client.poll(this.clientId(), f.deviceCode);
+    if (this.flows.get(id) !== f || f.state !== "pending") return;
+    switch (r.kind) {
+      case "pending":
+        return this.arm(f);
+      case "slow_down":
+        f.intervalMs = Math.max(
+          r.interval !== undefined ? r.interval * 1000 : f.intervalMs + 5000,
+          this.minIntervalMs,
+        );
+        return this.arm(f);
+      case "expired":
+        return this.finish(f, "expired");
+      case "denied":
+        return this.finish(f, "denied");
+      case "error":
+        if (++f.errors >= MAX_ERRORS)
+          return this.finish(f, "error", { message: r.message });
+        return this.arm(f);
+      case "token": {
+        if (r.expiring) this.onExpiringToken?.();
+        let identity: GithubIdentity;
+        try {
+          // The token is used for this one call and dropped with `r`.
+          identity = await this.client.user(r.token);
+        } catch (e) {
+          return this.finish(f, "error", { message: (e as Error).message });
+        }
+        const outcome = this.decide(f.purpose, identity);
+        return this.finish(f, outcome, {
+          login: identity.login,
+          ...(outcome === "ok" ? { identity } : {}),
+        });
+      }
+    }
+  }
+
+  /** Expire pending flows past their time; forget old finished ones. */
+  private sweep(): void {
+    const now = this.now();
+    for (const [id, f] of this.flows) {
+      if (f.state === "pending" && f.deviceCode && now >= f.expiresAt)
+        this.finish(f, "expired");
+      if (f.forgetAt !== undefined && now >= f.forgetAt) this.flows.delete(id);
+    }
+  }
+}
+
+function view(f: Flow): FlowView {
+  return {
+    id: f.id,
+    purpose: f.purpose,
+    state: f.state,
+    userCode: f.userCode,
+    verificationUri: f.verificationUri,
+    expiresAt: f.expiresAt,
+    ...(f.login !== undefined ? { login: f.login } : {}),
+    ...(f.message !== undefined ? { message: f.message } : {}),
+  };
+}

package/src/ui/server/edge-exposure.ts

@@ -1,6 +1,7 @@
 /**
- * The edge counts as local (0.4.3): with no sign-in through the edge, who
- * can reach the edge can use terminals. When Den can tell the edge is
+ * The edge counts as local (0.4.3) when it shows the client is this
+ * machine; since 0.4.5 any other client signs in (unless
+ * web.edge_unattested: local). When Den can tell the edge is
  * reachable beyond this machine it says so, once in web.log and in a
  * banner on every page (the shell, dismissible per browser).
  *
@@ -16,8 +17,19 @@ import { execFile } from "child_process";
 import { promises as dns } from "dns";
 import { isLoopbackAddress } from "./request-guard.js";
 
-export const EDGE_EXPOSED_MESSAGE =
-  "Your edge is reachable from other machines; anyone who can reach it can use terminals. Auth is coming.";
+/**
+ * The warning, by `web.edge_unattested` (SEC-2a): with `signin` (the
+ * default) a browser the edge can't place as this machine signs in first;
+ * with `local` it is let in, as in 0.4.3.
+ */
+export function edgeExposedMessage(unattested: "local" | "signin"): string {
+  return unattested === "local"
+    ? "Your edge is reachable from other machines, and web.edge_unattested is local: anyone it can't place can use terminals. Remove the key to have them sign in."
+    : "Your edge is reachable from other machines. A browser it can't place as this one signs in first (Sign in with GitHub, or a pairing link).";
+}
+
+/** 0.4.5's default wording (web.edge_unattested: signin). */
+export const EDGE_EXPOSED_MESSAGE = edgeExposedMessage("signin");
 
 export interface ExposureDeps {
   /** Every address a hostname resolves to (none when it doesn't). */

package/src/ui/server/github-routes.ts

@@ -0,0 +1,321 @@
+/**
+ * SEC-2a's routes: Sign in with GitHub (the signed-out page), the owner's
+ * link (Settings › Access, `web owner …`), and Pair a device.
+ *
+ *   POST /api/github/signin            start a sign-in (sign-in free; an
+ *                                      allowed Origin, no CSRF token)
+ *   GET  /api/github/signin/<id>       its outcome; approved by the owner:
+ *                                      the session cookie, once
+ *   GET  /api/web/owner                who the owner is
+ *   POST /api/web/owner/link           start linking the owner (shell-grade)
+ *   GET  /api/web/owner/link/<id>      its code and outcome
+ *   POST /api/web/owner/unlink         unlink the owner (shell-grade)
+ *   GET  /api/web/pair                 the edge hostnames a link can be for
+ *   POST /api/web/pair { host }        a one-time sign-in link for one
+ *
+ * The token GitHub hands back is used once, for `GET /user`, and dropped
+ * (device-flows.ts). Nothing here logs a code, a token or a cookie.
+ */
+import type * as http from "http";
+import { githubPrincipal } from "../../shared/github-device.js";
+import {
+  clearWebOwner,
+  readWebOwner,
+  writeWebOwner,
+} from "../../shared/web-owner.js";
+import type { DeviceFlows, FlowView } from "./device-flows.js";
+
+export interface GithubRouteDeps {
+  flows: DeviceFlows;
+  /** The configured client id ("" when none). */
+  clientId: () => string;
+  /** The app issued an expiring token (its token expiry is on): a misconfiguration. */
+  tokensExpire?: () => boolean;
+  cli: string;
+  sendJson: (res: http.ServerResponse, body: unknown, status?: number) => void;
+  readBody: (req: http.IncomingMessage) => Promise<string>;
+  /** A new browser session for this request; its Set-Cookie line. */
+  signIn: (
+    req: http.IncomingMessage,
+    via: "github" | "link",
+    login?: string,
+  ) => string;
+  /** The edge hostnames that route here, and the URL a browser uses for each. */
+  edgeRoutes: () => { host: string; url: string }[];
+  /** A one-time sign-in link at `origin` (60 s), or null with no secret. */
+  mintLink: (origin: string) => { url: string; expiresAt: number } | null;
+  log: (line: string) => void;
+  /** Where the owner file lives (the server's state dir). */
+  stateDir: () => string;
+}
+
+const SIGNIN_PATH = /^\/api\/github\/signin\/([A-Za-z0-9_-]{16,64})$/;
+const LINK_PATH = /^\/api\/web\/owner\/link\/([A-Za-z0-9_-]{16,64})$/;
+
+/** What an identity means for a flow: the owner's sign-in, or the owner's link. */
+export function decideFlow(
+  stateDir: () => string,
+  log: (line: string) => void,
+): (
+  purpose: "signin" | "link",
+  identity: { id: number; login: string },
+) => "ok" | "refused" {
+  return (purpose, identity) => {
+    const owner = readWebOwner(stateDir());
+    if (purpose === "signin") {
+      const ok = owner?.owner === githubPrincipal(identity.id);
+      log(
+        ok
+          ? `  ✓ signed in with GitHub (@${identity.login})`
+          : `  ✗ GitHub sign-in refused: @${identity.login} isn't this Den's owner`,
+      );
+      return ok ? "ok" : "refused";
+    }
+    if (owner) return "refused";
+    writeWebOwner(identity, stateDir());
+    log(`  ✓ owner linked: @${identity.login}`);
+    return "ok";
+  };
+}
+
+/** A flow as the page sees it: the code and where to enter it, while it waits. */
+function flowJson(v: FlowView): Record<string, unknown> {
+  return {
+    id: v.id,
+    state: v.state,
+    ...(v.state === "pending"
+      ? {
+          userCode: v.userCode,
+          verificationUri: v.verificationUri,
+          expiresAt: new Date(v.expiresAt).toISOString(),
+        }
+      : {}),
+    ...(v.login ? { login: v.login } : {}),
+  };
+}
+
+function finishedMessage(v: FlowView, cli: string): string | undefined {
+  switch (v.state) {
+    case "refused":
+      return v.purpose === "signin"
+        ? `@${v.login} isn't allowed on this Den. Ask the owner to add you.`
+        : `An owner is linked already; \`${cli} web owner unlink\` first.`;
+    case "expired":
+      return "The code expired before it was approved. Start again.";
+    case "denied":
+      return "The request was cancelled on GitHub.";
+    case "error":
+      return v.message ?? "GitHub couldn't be reached.";
+    default:
+      return undefined;
+  }
+}
+
+async function startFlow(
+  deps: GithubRouteDeps,
+  res: http.ServerResponse,
+  purpose: "signin" | "link",
+): Promise<void> {
+  let r;
+  try {
+    r = await deps.flows.start(purpose);
+  } catch (e) {
+    return deps.sendJson(
+      res,
+      { ok: false, code: "github_unreachable", error: (e as Error).message },
+      502,
+    );
+  }
+  if ("error" in r)
+    return r.error === "busy"
+      ? deps.sendJson(
+          res,
+          {
+            ok: false,
+            code: "busy",
+            error:
+              "Too many GitHub sign-ins are in progress. Try again in a few minutes.",
+          },
+          429,
+        )
+      : deps.sendJson(
+          res,
+          {
+            ok: false,
+            code: "no_client_id",
+            error: `Sign in with GitHub needs a GitHub App client id: set web.github_client_id in config/local/user.yml and restart (\`${deps.cli} web restart\`).`,
+          },
+          409,
+        );
+  return deps.sendJson(res, { ok: true, ...flowJson(r) });
+}
+
+/** Whether `pathname` is one of these routes' (index.ts dispatches them here). */
+export function isGithubRoute(pathname: string): boolean {
+  return /^\/api\/(github\/|web\/owner(\/|$)|web\/pair$)/.test(pathname);
+}
+
+/** Handles a SEC-2a route; false when `pathname` is none of them. */
+export async function handleGithubRoutes(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+  deps: GithubRouteDeps,
+): Promise<boolean> {
+  const method = (req.method ?? "GET").toUpperCase();
+  res.setHeader("Cache-Control", "no-store");
+
+  // ── Sign in with GitHub ──────────────────────────────────────────────
+  if (pathname === "/api/github/signin" && method === "POST") {
+    if (!readWebOwner(deps.stateDir())) {
+      deps.sendJson(
+        res,
+        {
+          ok: false,
+          code: "no_owner",
+          error: `This Den has no owner yet. On the machine it runs on, run \`${deps.cli} web owner link\`.`,
+        },
+        409,
+      );
+      return true;
+    }
+    await startFlow(deps, res, "signin");
+    return true;
+  }
+  const s = SIGNIN_PATH.exec(pathname);
+  if (s && (method === "GET" || method === "HEAD")) {
+    const v = deps.flows.get(s[1], "signin");
+    if (!v) {
+      deps.sendJson(
+        res,
+        {
+          ok: false,
+          state: "gone",
+          code: "not_found",
+          error: "That sign-in ended. Start again.",
+        },
+        404,
+      );
+      return true;
+    }
+    if (v.state === "ok") {
+      if (!deps.flows.claim(v.id, "signin")) {
+        deps.sendJson(res, { ok: false, state: "gone" }, 404);
+        return true;
+      }
+      res.setHeader("Set-Cookie", deps.signIn(req, "github", v.login));
+      deps.sendJson(res, { ok: true, state: "ok", login: v.login });
+      return true;
+    }
+    const message = finishedMessage(v, deps.cli);
+    deps.sendJson(res, {
+      ok: v.state === "pending",
+      ...flowJson(v),
+      ...(message ? { error: message } : {}),
+    });
+    return true;
+  }
+
+  // ── The owner ────────────────────────────────────────────────────────
+  if (pathname === "/api/web/owner" && method === "GET") {
+    const o = readWebOwner(deps.stateDir());
+    deps.sendJson(res, {
+      owner: o ? { id: o.owner, login: o.login, linkedAt: o.linkedAt } : null,
+      clientId: deps.clientId() !== "",
+      // The app's "Expire user authorization tokens" is on (seen since start).
+      tokenExpiry: deps.tokensExpire?.() ?? false,
+    });
+    return true;
+  }
+  if (pathname === "/api/web/owner/link" && method === "POST") {
+    const o = readWebOwner(deps.stateDir());
+    if (o) {
+      deps.sendJson(
+        res,
+        {
+          ok: false,
+          code: "already_linked",
+          error: `This Den's owner is @${o.login} already; unlink first (\`${deps.cli} web owner unlink\`).`,
+        },
+        409,
+      );
+      return true;
+    }
+    await startFlow(deps, res, "link");
+    return true;
+  }
+  const l = LINK_PATH.exec(pathname);
+  if (l && (method === "GET" || method === "HEAD")) {
+    const v = deps.flows.get(l[1], "link");
+    if (!v) {
+      deps.sendJson(res, { ok: false, state: "gone", code: "not_found" }, 404);
+      return true;
+    }
+    if (v.state === "ok") deps.flows.claim(v.id, "link");
+    const message = finishedMessage(v, deps.cli);
+    deps.sendJson(res, {
+      ok: v.state === "pending" || v.state === "ok",
+      ...flowJson(v),
+      ...(message ? { error: message } : {}),
+    });
+    return true;
+  }
+  if (pathname === "/api/web/owner/unlink" && method === "POST") {
+    const was = clearWebOwner(deps.stateDir());
+    if (was) deps.log(`  owner unlinked (was @${was.login})`);
+    deps.sendJson(res, { ok: true, was: was ? was.login : null });
+    return true;
+  }
+
+  // ── Pair a device ────────────────────────────────────────────────────
+  if (pathname === "/api/web/pair" && method === "GET") {
+    deps.sendJson(res, { hosts: deps.edgeRoutes().map((r) => r.host) });
+    return true;
+  }
+  if (pathname === "/api/web/pair" && method === "POST") {
+    let body: { host?: unknown } = {};
+    try {
+      body = (JSON.parse((await deps.readBody(req)) || "{}") ??
+        {}) as typeof body;
+    } catch {
+      deps.sendJson(
+        res,
+        { ok: false, error: "the body must be JSON: { host }" },
+        400,
+      );
+      return true;
+    }
+    const want = String(body.host ?? "")
+      .trim()
+      .toLowerCase();
+    const routes = deps.edgeRoutes();
+    const hit = routes.find((r) => r.host === want);
+    if (!hit) {
+      deps.sendJson(
+        res,
+        {
+          ok: false,
+          code: "unknown_host",
+          error: routes.length
+            ? `${want || "(none)"} isn't an edge hostname that routes here (${routes.map((r) => r.host).join(", ")}).`
+            : "No edge hostname routes to this server: add one to edge.routes or edge.aliases, then `edge up`.",
+        },
+        400,
+      );
+      return true;
+    }
+    const link = deps.mintLink(hit.url);
+    if (!link) {
+      deps.sendJson(res, { ok: false, error: "web.secret is missing" }, 500);
+      return true;
+    }
+    deps.sendJson(res, {
+      ok: true,
+      host: hit.host,
+      url: link.url,
+      expiresAt: new Date(link.expiresAt).toISOString(),
+    });
+    return true;
+  }
+  return false;
+}

package/src/ui/server/http-errors.ts

@@ -298,6 +298,16 @@ export interface ErrorPageData {
     cmd: string;
     localhost?: string;
     expired?: boolean;
+    /**
+     * SEC-2a: Sign in with GitHub. `state` ready, or why it can't be offered
+     * (no client id configured, no owner linked); `owner` the command that
+     * links one; `message` what to set while no client id is configured.
+     */
+    github?: {
+      state: "ready" | "no_client_id" | "no_owner";
+      owner: string;
+      message?: string;
+    };
   };
 }