ccdeck 3.44.0 → 3.46.0

package/src/server/forge-public-fetch.mjs

@@ -0,0 +1,228 @@
+// The road a forge read takes when it leaves the connection's own hosts.
+//
+// A job log's tail may follow a redirect to a host nobody typed: GitHub sends
+// it to a signed blob-storage address. forge-http.mjs lets such a hop go only
+// to a public https NAME, but a name is not where a socket goes: whoever runs
+// its DNS can answer 127.0.0.1, a LAN address or the cloud metadata address,
+// and answer differently the second time it is asked (DNS rebinding). So a
+// request to such a host is made here, not through fetch: the name is resolved
+// once, by `publicLookup`, every address it gave is checked, and the socket
+// connects to the checked address and nothing else. One answer that is not a
+// public address refuses the whole name.
+//
+// Refused: loopback, RFC 1918, link-local (169.254/16, fe80::/10), CGNAT
+// (100.64/10), unique-local (fc00::/7), multicast, the unspecified and
+// reserved ranges, the documentation and benchmarking ranges, and every IPv6
+// form that carries one of those IPv4 addresses (::ffff:a.b.c.d, ::a.b.c.d,
+// 64:ff9b::/96, 2002::/16).
+//
+// The connection's own hosts never come here: a self-hosted instance on the
+// LAN is where the user pointed the deck, and fetch keeps reading it.
+import { lookup as dnsLookup } from "node:dns";
+import { request } from "node:https";
+import { isIP } from "node:net";
+
+/** The error code a refused address carries; forge-http.mjs answers it as a
+ *  permission failure, never as the network's. */
+export const NOT_PUBLIC = "ERR_FORGE_NOT_PUBLIC";
+
+function notPublic(host) {
+  const err = new Error(`${host} is not a public address`);
+  err.code = NOT_PUBLIC;
+  return err;
+}
+
+function v4Public([a, b, c]) {
+  if (a === 0 || a === 10 || a === 127) return false;
+  if (a === 100 && b >= 64 && b <= 127) return false; // CGNAT
+  if (a === 169 && b === 254) return false; // link-local, cloud metadata
+  if (a === 172 && b >= 16 && b <= 31) return false;
+  if (a === 192 && b === 168) return false;
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return false; // IETF assignments, TEST-NET-1
+  if (a === 198 && (b === 18 || b === 19)) return false; // benchmarking
+  if (a === 198 && b === 51 && c === 100) return false; // TEST-NET-2
+  if (a === 203 && b === 0 && c === 113) return false; // TEST-NET-3
+  return a < 224; // multicast, reserved, broadcast
+}
+
+function v4Of(text) {
+  const parts = text.split(".").map(Number);
+  return parts.length === 4 && parts.every(n => Number.isInteger(n) && n >= 0 && n <= 255) ? parts : null;
+}
+
+/** An IPv6 address as its eight 16-bit groups, or null. */
+function v6Groups(text) {
+  let s = text.toLowerCase().split("%")[0];
+  const dotted = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(s);
+  if (dotted) {
+    const v4 = v4Of(dotted[2]);
+    if (!v4) return null;
+    s = `${dotted[1]}${((v4[0] << 8) | v4[1]).toString(16)}:${((v4[2] << 8) | v4[3]).toString(16)}`;
+  }
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  const fill = halves.length === 2 ? 8 - head.length - tail.length : 0;
+  if (fill < 0) return null;
+  const groups = [...head, ...Array(fill).fill("0"), ...tail].map(g => Number.parseInt(g, 16));
+  return groups.length === 8 && groups.every(g => Number.isInteger(g) && g >= 0 && g <= 0xffff) ? groups : null;
+}
+
+const embedded = (hi, lo) => [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff];
+
+/** Whether a socket may connect to `address` for a host nobody typed. Anything
+ *  that is not an IP address is not public. */
+export function isPublicAddress(address) {
+  const text = String(address ?? "").replace(/^\[|\]$/g, "");
+  const family = isIP(text);
+  if (family === 4) return v4Public(v4Of(text));
+  if (family !== 6) return false;
+  const g = v6Groups(text);
+  if (!g) return false;
+  // ::/96 (unspecified, loopback, IPv4-compatible) and ::ffff:0:0/96 (mapped).
+  if (g.slice(0, 5).every(x => x === 0) && (g[5] === 0 || g[5] === 0xffff)) {
+    if (g[5] === 0 && g[6] === 0 && g[7] <= 1) return false;
+    return v4Public(embedded(g[6], g[7]));
+  }
+  if (g[0] === 0x64 && g[1] === 0xff9b) {
+    // NAT64: the well-known prefix carries an IPv4 address; the local-use one is private.
+    return g[2] === 0 && g[3] === 0 && g[4] === 0 && g[5] === 0 && v4Public(embedded(g[6], g[7]));
+  }
+  if (g[0] === 0x2002) return v4Public(embedded(g[1], g[2])); // 6to4
+  if (g[0] === 0x0100 && g[1] === 0 && g[2] === 0 && g[3] === 0) return false; // discard-only
+  if (g[0] === 0x2001 && (g[1] === 0 || g[1] === 0xdb8)) return false; // Teredo, documentation
+  if ((g[0] & 0xfe00) === 0xfc00) return false; // unique-local
+  if ((g[0] & 0xffc0) === 0xfe80 || (g[0] & 0xffc0) === 0xfec0) return false; // link-local, site-local
+  if ((g[0] & 0xff00) === 0xff00) return false; // multicast
+  return true;
+}
+
+/**
+ * A `lookup` for a socket (the shape of dns.lookup) that resolves the name
+ * with `resolve` and hands the socket only public addresses. Every address
+ * the name has is checked, and one that is not public refuses the name: a
+ * socket that would try them in turn must not reach a private one.
+ */
+export function publicLookup(resolve = dnsLookup) {
+  return function lookup(hostname, options, callback) {
+    if (typeof options === "function") {
+      callback = options;
+      options = {};
+    }
+    const opts = typeof options === "number" ? { family: options } : { ...(options ?? {}) };
+    resolve(hostname, { ...opts, all: true }, (err, found, foundFamily) => {
+      if (err) return callback(err);
+      const list = (Array.isArray(found) ? found : typeof found === "string" ? [{ address: found, family: foundFamily }] : [])
+        .filter(a => a && typeof a.address === "string")
+        .map(a => ({ address: a.address, family: a.family === 4 || a.family === 6 ? a.family : isIP(a.address) }));
+      if (list.length === 0) {
+        const none = new Error(`${hostname} did not resolve`);
+        none.code = "ENOTFOUND";
+        return callback(none);
+      }
+      if (list.some(a => !isPublicAddress(a.address))) return callback(notPublic(hostname));
+      if (opts.all) return callback(null, list);
+      return callback(null, list[0].address, list[0].family);
+    });
+  };
+}
+
+/**
+ * fetch for a host nobody typed: https only, the name resolved by
+ * publicLookup and the socket connected to what it checked. It answers a
+ * Response as fetch does, never follows a redirect (forge-http.mjs decides
+ * every hop), and keeps no connection open for another request.
+ *
+ * @param {{ resolve?: typeof dnsLookup }} [opts]
+ * @returns {typeof fetch}
+ */
+export function publicFetch({ resolve = dnsLookup } = {}) {
+  const lookup = publicLookup(resolve);
+  return (url, { method = "GET", headers = {}, body, signal } = {}) => new Promise((done, fail) => {
+    let u;
+    try {
+      u = new URL(String(url));
+    } catch (err) {
+      fail(err);
+      return;
+    }
+    const host = u.hostname.replace(/^\[|\]$/g, "");
+    // A socket asks no lookup about an address, so an address is checked here.
+    if (u.protocol !== "https:" || u.username || u.password || (isIP(host) && !isPublicAddress(host))) {
+      fail(notPublic(host));
+      return;
+    }
+    const req = request({
+      host,
+      port: u.port || 443,
+      path: `${u.pathname}${u.search}`,
+      method,
+      headers,
+      lookup,
+      signal,
+      agent: false,
+    }, (res) => {
+      try {
+        done(responseOf(res, method));
+      } catch (err) {
+        res.destroy();
+        fail(err);
+      }
+    });
+    req.on("error", fail);
+    req.end(body ?? undefined);
+  });
+}
+
+/** An http.IncomingMessage as fetch's Response: its status, its headers and
+ *  its body as a stream, read as it arrives (a log tail keeps only its end). */
+export function responseOf(res, method = "GET") {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(res.headers)) {
+    if (Array.isArray(value)) for (const v of value) headers.append(name, v);
+    else if (value != null) headers.set(name, String(value));
+  }
+  const status = res.statusCode ?? 0;
+  const empty = method === "HEAD" || status === 204 || status === 205 || status === 304;
+  const response = new Response(empty ? null : streamOf(res), { status, statusText: res.statusMessage ?? "", headers });
+  if (empty) res.resume();
+  return response;
+}
+
+/** A Node stream as a web ReadableStream, paused while the reader is behind.
+ *  Not Readable.toWeb: on Node 18 it can throw "Controller is already closed"
+ *  out of a close event, where nothing catches it. Nothing here throws. */
+function streamOf(res) {
+  let settled = false;
+  const settle = (fn) => {
+    if (settled) return;
+    settled = true;
+    try { fn(); } catch { /* the reader has gone */ }
+  };
+  return new ReadableStream({
+    start(controller) {
+      res.on("data", (chunk) => {
+        if (settled) return;
+        try {
+          controller.enqueue(new Uint8Array(chunk));
+          if ((controller.desiredSize ?? 1) <= 0) res.pause();
+        } catch {
+          settled = true;
+          res.destroy();
+        }
+      });
+      res.on("end", () => settle(() => controller.close()));
+      res.on("error", (err) => settle(() => controller.error(err)));
+      // Closed before its end: the connection was cut.
+      res.on("close", () => settle(() => controller.error(Object.assign(new Error("answer cut off"), { code: "ECONNRESET" }))));
+    },
+    pull() {
+      res.resume();
+    },
+    cancel() {
+      settled = true;
+      res.destroy();
+    },
+  });
+}

package/src/server/forge-routes.mjs

@@ -0,0 +1,154 @@
+// The GitHub and GitLab panels' reads, as one route each (#2179).
+//
+// The integrations core (#2178) owns the address — /api/integrations/<kind>/
+// <connId>/… — the connection, and the token; it hands this file a client made
+// for that connection (github-api.mjs or gitlab-api.mjs, the same interface)
+// and the rest of the path. What is here is the part that is the same for both
+// forges: which sub-path is which read, what its parameters must look like
+// before anything is asked of the forge, and how an answer or a failure goes
+// back to the page.
+//
+// GET ONLY, AND EVERY PARAMETER CHECKED. The panels read; nothing here writes
+// to a forge, and a parameter that is not the shape it should be is a 400
+// before the forge hears of it — a repository path is a path, a number is a
+// positive integer, a filter is one of its words.
+//
+// ONE ENVELOPE FOR EVERY INTEGRATION. A failure answers { ok: false, error:
+// { kind, message, status?, retryAfter? } } — the same shape the Jira panel's
+// reads answer in (#2178) — with the HTTP status the kind implies: 401 for a
+// token refused or expired, 403 permission, 404 not found, 429 rate limit,
+// 502 for a forge that could not be reached or answered wrongly, 400 for a
+// parameter that is not the shape it should be. The page picks its recovery
+// from `kind`, never from the status.
+import { forgeErrorInfo } from "./forge-http.mjs";
+
+const STATUS_OF_KIND = {
+  auth: 401, expired: 401, permission: 403, "not-found": 404, "rate-limit": 429,
+  unreachable: 502, tls: 502, incompatible: 502, upstream: 502, invalid: 400,
+};
+
+/** The answer for a failure: the uniform envelope and the status its kind implies. */
+export function failure(info, status = STATUS_OF_KIND[info.kind] ?? 502) {
+  return { status, body: { ok: false, error: info } };
+}
+
+const REPO = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+){1,20}$/;
+// "~" joins the time and the run ids of GitHub's Actions list across
+// repositories (github-api.mjs listPipelines): without it that list stopped
+// at its first page.
+const CURSOR = /^[A-Za-z0-9_=+/.:~-]{1,512}$/;
+const JOB_ID = /^[A-Za-z0-9_-]{1,64}$/;
+
+class BadRequest extends Error {}
+
+function repo(params, required = true) {
+  const v = params.get("repo");
+  if (v == null || v === "") {
+    if (required) throw new BadRequest("repo is required");
+    return null;
+  }
+  if (v.length > 255 || !REPO.test(v) || v.split("/").some(s => s === "." || s === "..")) throw new BadRequest("repo is not a repository path");
+  return v;
+}
+
+// Up to fifteen digits: GitHub's workflow run ids are past ten billion already,
+// and fifteen still fits a JavaScript number exactly.
+function number(params, name = "number") {
+  const v = params.get(name);
+  if (!/^\d{1,15}$/.test(v ?? "") || Number(v) < 1) throw new BadRequest(`${name} is not a positive number`);
+  return Number(v);
+}
+
+// A pipeline's id as the clients hand them out: a number (a GitLab pipeline, an
+// Actions run), or on GitHub another app's check suite (`suite:<id>`) or a
+// commit's statuses (`status:<sha>`), which listChangePipelines lists beside
+// the runs.
+const PIPELINE_ID = /^(?:suite:\d{1,15}|status:[0-9a-f]{7,64})$/;
+
+function pipelineId(params) {
+  const v = params.get("id") ?? "";
+  return PIPELINE_ID.test(v) ? v : number(params, "id");
+}
+
+function oneOf(params, name, words, fallback) {
+  const v = params.get(name) ?? fallback;
+  if (!words.includes(v)) throw new BadRequest(`${name} must be one of ${words.join(", ")}`);
+  return v;
+}
+
+function cursor(params) {
+  const v = params.get("cursor");
+  if (v == null || v === "") return undefined;
+  if (!CURSOR.test(v)) throw new BadRequest("cursor is not a cursor");
+  return v;
+}
+
+function text(params, name, max) {
+  const v = params.get(name);
+  if (v == null) return undefined;
+  if (v.length > max) throw new BadRequest(`${name} is too long`);
+  return v;
+}
+
+/** Sub-path → the read it is. Each takes the query and the client. */
+const READS = {
+  "repos": (p, c) => c.listRepos({ search: text(p, "search", 100), cursor: cursor(p) }),
+  "branches": (p, c) => c.listBranches(repo(p), { cursor: cursor(p) }),
+  "branch": (p, c) => {
+    const name = text(p, "name", 255);
+    if (!name || /[\0\s]/.test(name)) throw new BadRequest("name is not a branch name");
+    return c.getBranch(repo(p), name);
+  },
+  "changes": (p, c) => c.listChanges({
+    repo: repo(p, false),
+    filter: oneOf(p, "filter", ["all", "mine", "review"], "all"),
+    state: oneOf(p, "state", ["open", "merged", "closed"], "open"),
+    sort: oneOf(p, "sort", ["created", "updated"], "created"),
+    cursor: cursor(p),
+  }),
+  "change-counts": (p, c) => c.countChanges({ repo: repo(p, false), filter: oneOf(p, "filter", ["all", "mine", "review"], "all") }),
+  "change": (p, c) => c.getChange(repo(p), number(p)),
+  "change/commits": (p, c) => c.listChangeCommits(repo(p), number(p), { cursor: cursor(p) }),
+  "change/pipelines": (p, c) => c.listChangePipelines(repo(p), number(p)),
+  "change/files": (p, c) => c.listChangeFiles(repo(p), number(p), { cursor: cursor(p) }),
+  "pipelines": (p, c) => c.listPipelines({ repo: repo(p, false), cursor: cursor(p) }),
+  "pipeline": (p, c) => c.getPipeline(repo(p), pipelineId(p)),
+  "job-log": (p, c) => {
+    const id = p.get("id") ?? "";
+    if (!JOB_ID.test(id)) throw new BadRequest("id is not a job id");
+    const lines = p.get("lines");
+    return c.jobLogTail(repo(p), id, { lines: lines && /^\d{1,6}$/.test(lines) ? Math.min(500, Math.max(10, Number(lines))) : 80 });
+  },
+  "issues": (p, c) => c.listIssues({ repo: repo(p, false), state: oneOf(p, "state", ["open", "closed"], "open"), cursor: cursor(p) }),
+  "issue": (p, c) => c.getIssue(repo(p), number(p)),
+  "issue/comments": (p, c) => c.listIssueComments(repo(p), number(p), { cursor: cursor(p) }),
+  "resolve": (p, c) => {
+    const q = text(p, "q", 500)?.trim();
+    if (!q) throw new BadRequest("q is required");
+    return c.resolveRef(q);
+  },
+};
+
+/** The sub-paths there are, for the core's route table and for tests. */
+export const FORGE_READS = Object.freeze(Object.keys(READS));
+
+/**
+ * One panel read.
+ *
+ * @param {object} client  a github-api.mjs or gitlab-api.mjs client for the connection
+ * @param {string} method  the request's method
+ * @param {string} subpath what follows /api/integrations/<kind>/<connId>/, without a leading slash
+ * @param {URLSearchParams} params
+ * @returns {Promise<{ status: number, body: object }>}
+ */
+export async function forgeRead(client, method, subpath, params) {
+  const read = Object.hasOwn(READS, subpath) ? READS[subpath] : null;
+  if (!read) return failure({ kind: "not-found", message: "no such read" });
+  if (method !== "GET") return failure({ kind: "upstream", message: "the panels only read" }, 405);
+  try {
+    return { status: 200, body: { ok: true, data: await read(params, client) } };
+  } catch (err) {
+    if (err instanceof BadRequest) return failure({ kind: "invalid", message: err.message });
+    return failure(forgeErrorInfo(err));
+  }
+}