@monster-orange/den 0.4.4 → 0.4.6

package/src/shared/edge/render.ts

@@ -220,6 +220,97 @@ export const EDGE_ORG_LABEL = "den.edge.org";
  * `den.edge.org` (0.3.0-dev.40): edgeUp and `edge down` touch an existing
  * edge only when its root is theirs.
  */
+/**
+ * The addresses the edge's entrypoints believe X-Forwarded-* headers from
+ * (SEC-2a, in place of `forwardedHeaders.insecure`): loopback and the
+ * Docker networks the edge and its own proxies run on (Docker's
+ * 172.16.0.0/12, Docker Desktop's VM network). From anyone else Traefik
+ * drops the client's headers and writes its own; either way the right-most
+ * X-Forwarded-For entry is the peer it saw, which is all Den believes.
+ */
+export const EDGE_FORWARDED_TRUSTED_IPS: readonly string[] = [
+  "127.0.0.1/32",
+  "::1/128",
+  "172.16.0.0/12",
+  "192.168.65.0/24",
+];
+
+/** An `args` entry that sets what Den owns: the entrypoints' header or PROXY trust. */
+const OWNED_ARG =
+  /^--entrypoints\.[^.=]+\.(forwardedheaders\.(insecure|trustedips)|proxyprotocol\.)/i;
+
+/** The `edge.args` entries Den drops (SEC-2a): forwarded-header or PROXY trust. */
+export function droppedEdgeArgs(cfg: Pick<EdgeConfig, "args">): string[] {
+  return cfg.args.filter((a) => OWNED_ARG.test(a));
+}
+
+/** The edge entrypoints' trust (SEC-2a): forwarded headers, and the PROXY protocol when set. */
+export function edgeTrustArgs(cfg: EdgeConfig): string[] {
+  const eps = ["web", ...(edgeHttps(cfg) ? ["websecure"] : [])];
+  const pp = cfg.proxyProtocolTrustedIps ?? [];
+  return eps.flatMap((ep) => [
+    `--entrypoints.${ep}.forwardedHeaders.trustedIPs=${EDGE_FORWARDED_TRUSTED_IPS.join(",")}`,
+    ...(pp.length
+      ? [`--entrypoints.${ep}.proxyProtocol.trustedIPs=${pp.join(",")}`]
+      : []),
+  ]);
+}
+
+/** The edge container's command (its Traefik static config). */
+export function edgeCommand(cfg: EdgeConfig): string[] {
+  const https = edgeHttps(cfg);
+  const proxy = dockerProxyName(cfg.org);
+  const labels = cfg.dockerLabels;
+  return [
+    "--entrypoints.web.address=:80",
+    ...(https ? ["--entrypoints.websecure.address=:443"] : []),
+    ...edgeTrustArgs(cfg),
+    "--providers.file.directory=/etc/edge/dynamic",
+    "--providers.file.watch=true",
+    ...(labels
+      ? [
+          "--providers.docker=true",
+          `--providers.docker.endpoint=tcp://${proxy}:2375`,
+          "--providers.docker.exposedbydefault=false",
+          `--providers.docker.network=${labels.network}`,
+        ]
+      : []),
+    "--api.dashboard=true",
+    "--ping=true",
+    "--log.level=WARN",
+    ...cfg.args.filter((a) => !OWNED_ARG.test(a)),
+  ];
+}
+
+/**
+ * What changed between a running edge's command and the one `edge up`
+ * renders now, as words for its one-line notice; [] when nothing did (or
+ * the running one isn't known).
+ */
+export function edgeCommandDrift(
+  running: readonly string[] | null,
+  rendered: readonly string[],
+): string[] {
+  if (!running) return [];
+  const a = new Set(running);
+  const b = new Set(rendered);
+  const changed = [
+    ...rendered.filter((x) => !a.has(x)),
+    ...running.filter((x) => !b.has(x)),
+  ];
+  if (!changed.length) return [];
+  const what = new Set<string>();
+  for (const c of changed)
+    what.add(
+      /forwardedheaders/i.test(c)
+        ? "forwarded-header trust"
+        : /proxyprotocol/i.test(c)
+          ? "PROXY protocol"
+          : "its command",
+    );
+  return [...what];
+}
+
 export function renderEdgeCompose(
   cfg: EdgeConfig,
   ownerRoot: string = cfg.stateDir,
@@ -239,24 +330,7 @@ export function renderEdgeCompose(
       restart: "unless-stopped",
       labels: { [EDGE_ROOT_LABEL]: ownerRoot, [EDGE_ORG_LABEL]: cfg.org },
       ...(labels ? { depends_on: ["docker-proxy"] } : {}),
-      command: [
-        "--entrypoints.web.address=:80",
-        ...(https ? ["--entrypoints.websecure.address=:443"] : []),
-        "--providers.file.directory=/etc/edge/dynamic",
-        "--providers.file.watch=true",
-        ...(labels
-          ? [
-              "--providers.docker=true",
-              `--providers.docker.endpoint=tcp://${proxy}:2375`,
-              "--providers.docker.exposedbydefault=false",
-              `--providers.docker.network=${labels.network}`,
-            ]
-          : []),
-        "--api.dashboard=true",
-        "--ping=true",
-        "--log.level=WARN",
-        ...cfg.args,
-      ],
+      command: edgeCommand(cfg),
       ...(cfg.ports
         ? {
             ports: [

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/port-pick.ts

@@ -0,0 +1,60 @@
+/**
+ * Picking a free localhost port for a new distribution's web server
+ * (`create`, ON-2), so a second Den on one machine doesn't collide with the
+ * first on DEFAULT_PORT.
+ *
+ * "In use" is checked without talking to whoever holds the port: a TCP
+ * connect that is closed as soon as it opens (no byte is sent), then a
+ * bind. Either one finding something there means in use.
+ */
+import * as net from "net";
+import { RESERVED_DEN_PORTS } from "./constants.js";
+
+/** Whether something holds `port` on localhost. Never sends a byte. */
+export function portInUse(port: number, host = "localhost"): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = net.connect({ host, port });
+    const done = (inUse: boolean | null) => {
+      sock.destroy();
+      if (inUse !== null) return resolve(inUse);
+      // Nothing accepted a connection: can we bind it ourselves?
+      const srv = net.createServer();
+      srv.once("error", () => resolve(true));
+      srv.listen({ port, host, exclusive: true }, () =>
+        srv.close(() => resolve(false)),
+      );
+    };
+    sock.setTimeout(1_000);
+    sock.once("connect", () => done(true));
+    // Something there that doesn't complete a handshake: in use.
+    sock.once("timeout", () => done(true));
+    sock.once("error", (e: NodeJS.ErrnoException) =>
+      done(e.code === "ECONNREFUSED" ? null : true),
+    );
+  });
+}
+
+export interface PickPortOptions {
+  /** The port wanted (the default); the search goes up from here. */
+  start: number;
+  /** Never chosen. */
+  reserved?: readonly number[];
+  /** How many ports above `start` to try. */
+  span?: number;
+  inUse?: (port: number) => Promise<boolean>;
+}
+
+/**
+ * `start` when it is free, else the first free port above it that is not
+ * reserved; null when none in the span is free.
+ */
+export async function pickFreePort(o: PickPortOptions): Promise<number | null> {
+  const reserved = o.reserved ?? RESERVED_DEN_PORTS;
+  const inUse = o.inUse ?? ((p: number) => portInUse(p));
+  const span = o.span ?? 100;
+  for (let p = o.start; p <= Math.min(o.start + span, 65535); p++) {
+    if (reserved.includes(p)) continue;
+    if (!(await inUse(p))) return p;
+  }
+  return null;
+}