@monster-orange/den 0.4.4 → 0.4.5

package/src/shared/edge/runtime.ts

@@ -7,7 +7,10 @@ import * as net from "net";
 import * as path from "path";
 import { must, sh } from "./exec.js";
 import {
+  droppedEdgeArgs,
   EDGE_ROOT_LABEL,
+  edgeCommand,
+  edgeCommandDrift,
   edgeNames,
   renderEdgeCompose,
   renderEdgeDynamic,
@@ -226,9 +229,58 @@ export function assertEdgeOwnedHere(
   );
 }
 
+/** A container's command (`docker inspect .Config.Cmd`), or null. */
+export function runningEdgeCommand(name: string): string[] | null {
+  const r = sh("docker", [
+    "inspect",
+    "--type",
+    "container",
+    "-f",
+    "{{json .Config.Cmd}}",
+    name,
+  ]);
+  if (r.code !== 0) return null;
+  try {
+    const v: unknown = JSON.parse(r.out);
+    return Array.isArray(v) && v.every((x) => typeof x === "string")
+      ? (v as string[])
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What `edge up` says before it writes compose.yml (SEC-2a): the `edge.args`
+ * it drops (Den owns the entrypoints' trust), and, when the running edge's
+ * command differs from the new one, that it recreates the edge once and
+ * why. Pure: `running` is the running container's command, or null.
+ */
+export function edgeUpNotices(
+  cfg: EdgeConfig,
+  running: readonly string[] | null,
+): string[] {
+  const out: string[] = [];
+  const dropped = droppedEdgeArgs(cfg);
+  if (dropped.length)
+    out.push(
+      `edge.args: ignoring ${dropped.join(", ")}: Den sets the entrypoints' ` +
+        "forwarded-header trust itself (its own networks and loopback), and " +
+        "PROXY protocol trust from edge.proxy_protocol.trusted_ips. Remove it " +
+        "from the config to silence this.",
+    );
+  const drift = edgeCommandDrift(running, edgeCommand(cfg));
+  if (drift.length)
+    out.push(
+      `${edgeNames(cfg.org).container}'s settings changed (${drift.join(", ")}): ` +
+        "recreating it once. Routes drop only while it restarts.",
+    );
+  return out;
+}
+
 export async function edgeUp(
   cfg: EdgeConfig,
-  opts: { takeOver?: boolean } = {},
+  opts: { takeOver?: boolean; log?: (line: string) => void } = {},
 ) {
   // Before anything is written or started: an edge of this name that
   // another state dir owns is never replaced.
@@ -261,6 +313,10 @@ export async function edgeUp(
   const included = syncIncluded(cfg);
   write(path.join(cfg.stateDir, "dynamic", GENERATED), renderEdgeDynamic(cfg));
   const compose = path.join(cfg.stateDir, "compose.yml");
+  // SEC-2a: say what changed before compose recreates the edge for it.
+  const log = opts.log ?? ((l: string) => console.log(l));
+  for (const line of edgeUpNotices(cfg, runningEdgeCommand(n.container)))
+    log(line);
   write(compose, renderEdgeCompose(cfg, realOrSelf(cfg.stateDir)));
   must("docker", ["compose", "-f", compose, "up", "-d", "--remove-orphans"]);
   return { certs, included };

package/src/shared/edge/types.ts

@@ -73,6 +73,16 @@ export interface EdgeConfig {
   mounts: Record<string, string>;
   /** Extra external Docker networks the edge joins. */
   networks: string[];
-  /** Extra Traefik static-config arguments. */
+  /**
+   * Extra Traefik static-config arguments. Den owns the entrypoints'
+   * forwarded-header and PROXY-protocol trust (SEC-2a): an argument that
+   * sets either is dropped, with a warning at `edge up`.
+   */
   args: string[];
+  /**
+   * `edge.proxy_protocol.trusted_ips` (SEC-2a): the front proxies (IPs or
+   * CIDRs) whose PROXY protocol header the entrypoints believe, so a TCP
+   * passthrough in front can pass on the real client. Empty: none.
+   */
+  proxyProtocolTrustedIps?: string[];
 }

package/src/shared/github-app.ts

@@ -0,0 +1,94 @@
+/**
+ * SEC-2a: the MO "Den" GitHub App, as Den uses it (SEC-2 spec, "The MO Den
+ * GitHub App"). Den uses only its public client id, through the device flow,
+ * acting as the person: no client secret and no private key, ever. With the
+ * app's "Expire user authorization tokens" off, no refresh (which would need
+ * the secret) is ever needed, so Den never asks for `offline_access`.
+ *
+ * `web.github_client_id` (config/den.yml, or config/local/user.yml) replaces
+ * the default below; it is the one place the MO app's id lives.
+ */
+
+/**
+ * The "Monster Orange Den" GitHub App's client id (owner Monster-Orange,
+ * slug monster-orange-den). Public by design: it ships in Den. A
+ * distribution sets its own app with `web.github_client_id`; an empty
+ * value there turns Sign in with GitHub off.
+ */
+export const MO_DEN_GITHUB_CLIENT_ID = "Iv23liKL12gnN6WvRV5b";
+
+/** What a person reads when the app issues expiring tokens (never the token). */
+export function expiringTokenWarning(): string {
+  return (
+    "The GitHub App issues expiring user tokens (its answer carried expires_in " +
+    "or a refresh_token). Sign-in still works: Den uses the token once and never " +
+    "keeps it. To fix it, switch off \u201cExpire user authorization tokens\u201d in " +
+    "the app's settings (GitHub \u203a Settings \u203a Developer settings \u203a GitHub Apps)."
+  );
+}
+
+/** Where a person enters the device code. */
+export const GITHUB_DEVICE_PAGE = "https://github.com/login/device";
+
+/**
+ * Tests only: a fake GitHub on loopback (`http://localhost:<port>`), for the
+ * device-flow endpoints and `GET /user` alike. Ignored unless it is plain
+ * http on localhost or 127.0.0.1, so it can never point Den at another host.
+ */
+export const GITHUB_TEST_BASE_ENV = "DEN_TEST_GITHUB_URL";
+
+export interface GithubEndpoints {
+  deviceCode: string;
+  accessToken: string;
+  user: string;
+  /** A test's fake GitHub is in use (GITHUB_TEST_BASE_ENV). */
+  fake: boolean;
+}
+
+/** A loopback http base URL, without a trailing slash, or null. */
+function loopbackBase(raw: string | undefined): string | null {
+  if (!raw) return null;
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== "http:") return null;
+    if (u.hostname !== "localhost" && u.hostname !== "127.0.0.1") return null;
+    return u.origin;
+  } catch {
+    return null;
+  }
+}
+
+/** GitHub's device-flow and user endpoints (or a test's fake GitHub). */
+export function githubEndpoints(
+  env: NodeJS.ProcessEnv = process.env,
+): GithubEndpoints {
+  const fake = loopbackBase(env[GITHUB_TEST_BASE_ENV]);
+  if (fake)
+    return {
+      deviceCode: `${fake}/login/device/code`,
+      accessToken: `${fake}/login/oauth/access_token`,
+      user: `${fake}/user`,
+      fake: true,
+    };
+  return {
+    deviceCode: "https://github.com/login/device/code",
+    accessToken: "https://github.com/login/oauth/access_token",
+    user: "https://api.github.com/user",
+    fake: false,
+  };
+}
+
+/** The client id in use: `web.github_client_id`, else the MO app's. */
+export function githubClientId(configured: string | undefined): string {
+  return (configured ?? MO_DEN_GITHUB_CLIENT_ID).trim();
+}
+
+/** What a GitHub button says while no client id is configured. */
+export function noClientIdMessage(cli: string): string {
+  return (
+    "Sign in with GitHub needs a GitHub App client id, and none is configured. " +
+    "Set web.github_client_id in config/local/user.yml (or the distribution's " +
+    `config), then restart the server (\`${cli} web restart\`). The app's setup ` +
+    "is in docs/distributions.md, “Signing in with GitHub”."
+  );
+}

package/src/shared/github-device.ts

@@ -0,0 +1,286 @@
+/**
+ * SEC-2a: GitHub's device flow, for a GitHub App with only its public client
+ * id (no secret), and `GET /user` for who approved it.
+ *
+ *  1. POST /login/device/code (client_id): a device code (kept here), a
+ *     user code (shown to the person), how long both last, and the poll
+ *     interval. No scope is asked for: identity needs none, and
+ *     `offline_access` would force an expiring token.
+ *  2. POST /login/oauth/access_token (client_id, device_code, grant_type
+ *     device_code) every `interval` seconds until it answers a token, or
+ *     `authorization_pending` (keep going), `slow_down` (wait longer),
+ *     `expired_token` or `access_denied` (stop).
+ *  3. GET /user with the token: its numeric `id` and `login`, nothing else.
+ *     The caller drops the token right after.
+ *
+ * A token answer with `expires_in` or a `refresh_token` means the app has
+ * "Expire user authorization tokens" on: the result says so (`expiring`),
+ * for the caller's one warning; the sign-in still completes.
+ *
+ * Every call is one request on a fresh connection (no keep-alive), with a
+ * timeout. Nothing here logs; a token, device code or user code is never in
+ * an error message.
+ */
+import * as http from "http";
+import * as https from "https";
+import { githubEndpoints, type GithubEndpoints } from "./github-app.js";
+
+export interface DeviceCode {
+  deviceCode: string;
+  userCode: string;
+  /** Seconds the codes last. */
+  expiresIn: number;
+  /** Seconds between polls. */
+  interval: number;
+}
+
+export type PollResult =
+  | {
+      kind: "token";
+      token: string;
+      /**
+       * The answer carried `expires_in` or a `refresh_token`: the app has
+       * "Expire user authorization tokens" on, a misconfiguration (Den
+       * never refreshes; it uses the token once). Never the token itself.
+       */
+      expiring: boolean;
+    }
+  | { kind: "pending" }
+  | { kind: "slow_down"; interval?: number }
+  | { kind: "expired" }
+  | { kind: "denied" }
+  | { kind: "error"; message: string };
+
+export interface GithubIdentity {
+  id: number;
+  login: string;
+}
+
+/** The three calls, swappable in a unit test. */
+export interface GithubDeviceClient {
+  start(clientId: string): Promise<DeviceCode>;
+  poll(clientId: string, deviceCode: string): Promise<PollResult>;
+  user(token: string): Promise<GithubIdentity>;
+}
+
+const TIMEOUT_MS = 15_000;
+const UA = "den-device-flow";
+
+function request(
+  url: string,
+  opts: { method: string; headers: Record<string, string>; body?: string },
+): Promise<{ status: number; body: string }> {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const lib = u.protocol === "https:" ? https : http;
+    const req = lib.request(
+      u,
+      {
+        method: opts.method,
+        agent: false,
+        timeout: TIMEOUT_MS,
+        headers: {
+          "user-agent": UA,
+          connection: "close",
+          ...opts.headers,
+          ...(opts.body !== undefined
+            ? { "content-length": String(Buffer.byteLength(opts.body)) }
+            : {}),
+        },
+      },
+      (res) => {
+        let out = "";
+        res.setEncoding("utf-8");
+        res.on("data", (d: string) => (out += d));
+        res.on("end", () =>
+          resolve({ status: res.statusCode ?? 0, body: out }),
+        );
+      },
+    );
+    req.on("timeout", () => req.destroy(new Error("GitHub did not answer")));
+    req.on("error", (e) =>
+      reject(new Error(`GitHub unreachable: ${e.message}`)),
+    );
+    req.end(opts.body);
+  });
+}
+
+function parse(body: string): Record<string, unknown> {
+  try {
+    const v = JSON.parse(body) as unknown;
+    return v && typeof v === "object" ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+const form = (o: Record<string, string>) => new URLSearchParams(o).toString();
+const FORM_HEADERS = {
+  accept: "application/json",
+  "content-type": "application/x-www-form-urlencoded",
+};
+
+/** The real GitHub (or a test's fake one, githubEndpoints). */
+export function githubDeviceClient(
+  ep: GithubEndpoints = githubEndpoints(),
+): GithubDeviceClient {
+  return {
+    async start(clientId) {
+      const r = await request(ep.deviceCode, {
+        method: "POST",
+        headers: FORM_HEADERS,
+        body: form({ client_id: clientId }),
+      });
+      const j = parse(r.body);
+      if (
+        r.status !== 200 ||
+        typeof j.device_code !== "string" ||
+        typeof j.user_code !== "string"
+      ) {
+        const why =
+          typeof j.error === "string"
+            ? j.error === "device_flow_disabled"
+              ? "the GitHub App's device flow is off (tick “Enable Device Flow”)"
+              : j.error === "unauthorized_client" ||
+                  j.error === "incorrect_client_credentials"
+                ? "GitHub doesn't know this client id (web.github_client_id)"
+                : `GitHub answered ${j.error}`
+            : `GitHub answered ${r.status}`;
+        throw new Error(why);
+      }
+      return {
+        deviceCode: j.device_code,
+        userCode: j.user_code,
+        expiresIn: Number(j.expires_in) > 0 ? Number(j.expires_in) : 900,
+        interval: Number(j.interval) >= 0 ? Number(j.interval) : 5,
+      };
+    },
+    async poll(clientId, deviceCode) {
+      let r: { status: number; body: string };
+      try {
+        r = await request(ep.accessToken, {
+          method: "POST",
+          headers: FORM_HEADERS,
+          body: form({
+            client_id: clientId,
+            device_code: deviceCode,
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          }),
+        });
+      } catch (e) {
+        return { kind: "error", message: (e as Error).message };
+      }
+      const j = parse(r.body);
+      if (typeof j.access_token === "string" && j.access_token)
+        return {
+          kind: "token",
+          token: j.access_token,
+          expiring: j.expires_in !== undefined || j.refresh_token !== undefined,
+        };
+      switch (j.error) {
+        case "authorization_pending":
+          return { kind: "pending" };
+        case "slow_down":
+          return {
+            kind: "slow_down",
+            ...(Number(j.interval) > 0 ? { interval: Number(j.interval) } : {}),
+          };
+        case "expired_token":
+          return { kind: "expired" };
+        case "access_denied":
+          return { kind: "denied" };
+        default:
+          return {
+            kind: "error",
+            message:
+              typeof j.error === "string"
+                ? `GitHub answered ${j.error}`
+                : `GitHub answered ${r.status}`,
+          };
+      }
+    },
+    async user(token) {
+      const r = await request(ep.user, {
+        method: "GET",
+        headers: {
+          accept: "application/vnd.github+json",
+          authorization: `Bearer ${token}`,
+          "x-github-api-version": "2022-11-28",
+        },
+      });
+      const j = parse(r.body);
+      if (
+        r.status !== 200 ||
+        typeof j.id !== "number" ||
+        !Number.isSafeInteger(j.id) ||
+        typeof j.login !== "string"
+      )
+        throw new Error(`GitHub's /user answered ${r.status}`);
+      return { id: j.id, login: j.login };
+    },
+  };
+}
+
+/** `github:<numeric id>`: how Den names a GitHub account. */
+export function githubPrincipal(id: number): `github:${number}` {
+  return `github:${id}`;
+}
+
+export type DeviceFlowOutcome =
+  | { kind: "ok"; identity: GithubIdentity; expiringToken?: boolean }
+  | { kind: "expired" }
+  | { kind: "denied" }
+  | { kind: "error"; message: string };
+
+/**
+ * The whole flow in one call (the CLI's `web owner link`): start, show the
+ * code (`onCode`), poll at GitHub's interval (`sleep`, injected in a test),
+ * read the identity, drop the token. `minIntervalMs` is the floor between
+ * polls (GitHub's own interval is never shorter than it says).
+ */
+export async function runDeviceFlow(opts: {
+  clientId: string;
+  client?: GithubDeviceClient;
+  onCode: (code: DeviceCode) => void;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  minIntervalMs?: number;
+}): Promise<DeviceFlowOutcome> {
+  const client = opts.client ?? githubDeviceClient();
+  const sleep =
+    opts.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now ?? Date.now;
+  const code = await client.start(opts.clientId);
+  opts.onCode(code);
+  const deadline = now() + code.expiresIn * 1000;
+  const floor = opts.minIntervalMs ?? 1000;
+  let interval = Math.max(code.interval * 1000, floor);
+  let errors = 0;
+  for (;;) {
+    await sleep(interval);
+    if (now() >= deadline) return { kind: "expired" };
+    const r = await client.poll(opts.clientId, code.deviceCode);
+    if (r.kind === "token") {
+      // The token lives only for this one call.
+      const identity = await client.user(r.token);
+      return {
+        kind: "ok",
+        identity,
+        ...(r.expiring ? { expiringToken: true } : {}),
+      };
+    }
+    if (r.kind === "pending") continue;
+    if (r.kind === "slow_down") {
+      interval = Math.max(
+        r.interval !== undefined ? r.interval * 1000 : interval + 5000,
+        floor,
+      );
+      continue;
+    }
+    if (r.kind === "error") {
+      if (++errors >= 5) return { kind: "error", message: r.message };
+      continue;
+    }
+    return r;
+  }
+}

package/src/shared/secrets/onepassword.ts

@@ -52,11 +52,34 @@ export class OnePasswordProvider implements SecretsProvider {
     }
   }
 
+  /** Overwrite the field; an item that isn't there yet is created (a Password item). */
   async set(ref: SecretRef, value: string): Promise<void> {
-    const args = ["item", "edit", ref.item];
-    if (ref.vault) args.push("--vault", ref.vault);
-    args.push(`${ref.field}[password]=${value}`);
-    await execFileAsync("op", args, { timeout: this.timeout });
+    const vault = ref.vault ? ["--vault", ref.vault] : [];
+    const field = `${ref.field}[password]=${value}`;
+    try {
+      await execFileAsync("op", ["item", "edit", ref.item, ...vault, field], {
+        timeout: this.timeout,
+      });
+    } catch (err) {
+      try {
+        await execFileAsync(
+          "op",
+          [
+            "item",
+            "create",
+            "--category",
+            "password",
+            "--title",
+            ref.item,
+            ...vault,
+            field,
+          ],
+          { timeout: this.timeout },
+        );
+      } catch {
+        throw err;
+      }
+    }
   }
 
   async preflight(): Promise<PreflightResult> {

package/src/shared/web-owner.ts

@@ -0,0 +1,91 @@
+/**
+ * SEC-2a: the owner's GitHub identity. `<state dir>/web-owner.json`, mode
+ * 0600: `{ v: 1, owner: "github:<numeric id>", login, linkedAt }`. The id
+ * is what sign-in compares; the login is for display only (a login can be
+ * renamed, the id can't). No token is ever stored: the device flow's token
+ * is dropped right after `GET /user`.
+ *
+ * Written by `<cli> web owner link` and Settings › Access; removed by
+ * `web owner unlink`. Re-read whenever it changes on disk.
+ */
+import { randomBytes } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { getStateDir } from "./paths.js";
+
+export const WEB_OWNER_FILE = "web-owner.json";
+
+export interface WebOwner {
+  /** `github:<numeric id>`. */
+  owner: `github:${number}`;
+  /** The GitHub login at link time, for display. */
+  login: string;
+  /** ISO time it was linked. */
+  linkedAt: string;
+}
+
+export function webOwnerPath(stateDir: string = getStateDir()): string {
+  return path.join(stateDir, WEB_OWNER_FILE);
+}
+
+const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+
+/** The linked owner, or null (none, or a file that isn't one). */
+export function readWebOwner(
+  stateDir: string = getStateDir(),
+): WebOwner | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(fs.readFileSync(webOwnerPath(stateDir), "utf-8"));
+  } catch {
+    return null;
+  }
+  const o = raw as Partial<WebOwner> | null;
+  if (
+    !o ||
+    typeof o.owner !== "string" ||
+    !/^github:[1-9][0-9]{0,15}$/.test(o.owner) ||
+    typeof o.login !== "string" ||
+    !LOGIN.test(o.login)
+  )
+    return null;
+  return {
+    owner: o.owner,
+    login: o.login,
+    linkedAt: typeof o.linkedAt === "string" ? o.linkedAt : "",
+  };
+}
+
+/** Link `id` (`login` for display) as the owner: atomic, 0600. */
+export function writeWebOwner(
+  identity: { id: number; login: string },
+  stateDir: string = getStateDir(),
+  now: Date = new Date(),
+): WebOwner {
+  if (!Number.isSafeInteger(identity.id) || identity.id <= 0)
+    throw new Error("a GitHub account id is a positive integer");
+  if (!LOGIN.test(identity.login))
+    throw new Error("that is not a GitHub login");
+  const rec: WebOwner = {
+    owner: `github:${identity.id}`,
+    login: identity.login,
+    linkedAt: now.toISOString(),
+  };
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const file = webOwnerPath(stateDir);
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify({ v: 1, ...rec })}\n`, {
+    mode: 0o600,
+  });
+  fs.renameSync(tmp, file);
+  return rec;
+}
+
+/** Unlink the owner; the one it was, or null when none was linked. */
+export function clearWebOwner(
+  stateDir: string = getStateDir(),
+): WebOwner | null {
+  const was = readWebOwner(stateDir);
+  fs.rmSync(webOwnerPath(stateDir), { force: true });
+  return was;
+}