@graphty/visual-review 0.2.1 → 0.2.2

package/trusted/lib/approval.mjs

@@ -0,0 +1,300 @@
+/**
+ * Passkey approvals of review records: the owner's device (Face ID or Touch ID, a passkey in
+ * iCloud Keychain) signs the SHA-256 of a review record, and this module checks that signature.
+ * The gate runs it on every record a pull request adds; the server runs it at Finish, immediately
+ * before the record is committed.
+ *
+ * WebAuthn's ES256 signature is over `authenticatorData || SHA-256(clientDataJSON)`, and the
+ * challenge inside clientDataJSON is the record's hash, so the signature covers the record. Only
+ * `node:crypto`, so the gate still runs from a checkout without an install.
+ */
+
+import { createHash, createPublicKey, verify } from "node:crypto";
+
+/** Where the registered public keys live, relative to the repository root. */
+export const PASSKEYS_FILE = "visual-review/passkeys.json";
+
+const B64U = /^[A-Za-z0-9_-]+$/;
+const HOST = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
+const FIELDS = ["credentialId", "authenticatorData", "clientDataJSON", "signature"];
+const UP = 0x01;
+const UV = 0x04;
+const AT = 0x40;
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest();
+const b64u = (s) => Buffer.from(s, "base64url");
+
+/**
+ * JSON with object keys sorted and no whitespace, so one record has exactly one byte form. A
+ * number JSON cannot write back as it was read (1e999 is Infinity, -0 is 0) throws, so two
+ * different records never hash the same.
+ * @param {unknown} value a JSON value
+ * @returns {string} its canonical text
+ */
+export function canonical(value) {
+    if (typeof value === "number" && (!Number.isFinite(value) || Object.is(value, -0))) {
+        throw new Error(`${value} has no canonical JSON form`);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => canonical(v ?? null)).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        const keys = Object.keys(value)
+            .filter((k) => value[k] !== undefined)
+            .sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+
+/**
+ * The bytes an approval signs: SHA-256 of the canonical record without its `approval`.
+ * @param {object} record the review record
+ * @returns {Buffer} 32 bytes
+ */
+export function recordHash(record) {
+    const rest = { ...record };
+    delete rest.approval;
+    return sha256(Buffer.from(canonical(rest), "utf8"));
+}
+
+/**
+ * Loads a key's SubjectPublicKeyInfo; only P-256 (ES256) is accepted.
+ * @param {string} spki base64url DER
+ * @returns {import("node:crypto").KeyObject} the key
+ */
+function loadKey(spki) {
+    const key = createPublicKey({ key: b64u(spki), format: "der", type: "spki" });
+    if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") {
+        throw new Error("the public key is not a P-256 (ES256) key");
+    }
+    return key;
+}
+
+/**
+ * Parses passkeys.json. One bad entry makes the whole file invalid, so the gate fails closed.
+ * @param {string} text the file
+ * @returns {{ id: string, publicKey: string, rpId: string, label?: string, registeredAt?: string }[]}
+ *     the keys
+ */
+export function parsePasskeys(text) {
+    const doc = JSON.parse(text);
+    if (doc?.version !== 1) {
+        throw new Error("version must be 1");
+    }
+    if (!Array.isArray(doc.keys)) {
+        throw new Error("keys must be an array");
+    }
+    const seen = new Set();
+    for (const [i, k] of doc.keys.entries()) {
+        const where = `keys[${i}]`;
+        if (typeof k?.id !== "string" || !B64U.test(k.id)) {
+            throw new Error(`${where}.id must be a non-empty base64url string`);
+        }
+        if (seen.has(k.id)) {
+            throw new Error(`${where}.id is a duplicate`);
+        }
+        seen.add(k.id);
+        if (typeof k.rpId !== "string" || !HOST.test(k.rpId)) {
+            throw new Error(`${where}.rpId must be a host name`);
+        }
+        if (typeof k.publicKey !== "string" || !B64U.test(k.publicKey)) {
+            throw new Error(`${where}.publicKey must be base64url`);
+        }
+        try {
+            loadKey(k.publicKey);
+        } catch (err) {
+            throw new Error(`${where}.publicKey: ${err.message}`);
+        }
+    }
+    return doc.keys;
+}
+
+/**
+ * Checks clientDataJSON and authenticatorData shared by registration and approval.
+ * @param {object} c the ceremony
+ * @param {any} c.clientData the parsed clientDataJSON
+ * @param {Buffer} c.authData authenticatorData
+ * @param {string} c.type webauthn.get or webauthn.create
+ * @param {string} c.challenge the expected challenge, base64url
+ * @param {string} c.rpId the relying party id
+ * @param {(origin: unknown) => boolean} c.originOk whether the origin is acceptable
+ * @returns {string | null} why not, or null
+ */
+function checkCeremony({ clientData, authData, type, challenge, rpId, originOk }) {
+    if (clientData?.type !== type) {
+        return `clientDataJSON.type is not ${type}`;
+    }
+    if (clientData.challenge !== challenge) {
+        return "the challenge does not match: it was signed for other contents than these";
+    }
+    if (clientData.crossOrigin === true) {
+        return "the approval was made in a cross-origin frame";
+    }
+    if (!originOk(clientData.origin)) {
+        return `the approval was made on ${JSON.stringify(clientData.origin)}, not on the review page's origin`;
+    }
+    if (authData.length < 37) {
+        return "authenticatorData is too short";
+    }
+    if (!authData.subarray(0, 32).equals(sha256(rpId))) {
+        return `authenticatorData is not for the rpId ${rpId}`;
+    }
+    if (!(authData[32] & UP)) {
+        return "the authenticator did not confirm user presence";
+    }
+    if (!(authData[32] & UV)) {
+        return "the authenticator did not verify the user (no Face ID, Touch ID or PIN)";
+    }
+    return null;
+}
+
+const jsonOf = (s) => {
+    try {
+        return JSON.parse(b64u(s).toString("utf8"));
+    } catch {
+        return undefined;
+    }
+};
+
+/**
+ * Whether a record's approval is a valid passkey signature over that record. Never throws.
+ * @param {object} record the review record, with `approval`
+ * @param {{ id: string, publicKey: string, rpId: string }[]} keys the keys to accept
+ * @param {{ origin?: string }} [options] the exact origin required (the server's); without it any
+ *     https origin whose host is exactly the key's rpId, on any port (servherd assigns the review
+ *     server's), never a subdomain
+ * @returns {string | null} why it fails, or null when it verifies
+ */
+export function verifyApproval(record, keys, { origin } = {}) {
+    const a = record?.approval;
+    if (typeof a !== "object" || a === null) {
+        return "the record has no passkey approval";
+    }
+    for (const f of FIELDS) {
+        if (typeof a[f] !== "string" || !B64U.test(a[f])) {
+            return `approval.${f} is not base64url`;
+        }
+    }
+    const key = keys.find((k) => k.id === a.credentialId);
+    if (!key) {
+        return "approval is from a key not in passkeys.json on the base branch";
+    }
+    const clientDataBytes = b64u(a.clientDataJSON);
+    const clientData = jsonOf(a.clientDataJSON);
+    if (clientData === undefined) {
+        return "approval.clientDataJSON is not JSON";
+    }
+    const authData = b64u(a.authenticatorData);
+    let challenge;
+    try {
+        challenge = recordHash(record).toString("base64url");
+    } catch (err) {
+        return `the record cannot be hashed: ${err.message}`;
+    }
+    const why = checkCeremony({
+        clientData,
+        authData,
+        type: "webauthn.get",
+        challenge,
+        rpId: key.rpId,
+        originOk: (o) => {
+            if (origin !== undefined) {
+                return o === origin;
+            }
+            try {
+                // u.origin === o refuses anything a browser never writes as an origin (a user, a path).
+                const u = new URL(String(o));
+                return u.origin === o && u.protocol === "https:" && u.hostname === key.rpId;
+            } catch {
+                return false;
+            }
+        },
+    });
+    if (why) {
+        return why;
+    }
+    let ok = false;
+    try {
+        ok = verify(
+            "sha256",
+            Buffer.concat([authData, sha256(clientDataBytes)]),
+            loadKey(key.publicKey),
+            b64u(a.signature),
+        );
+    } catch {
+        ok = false;
+    }
+    return ok ? null : "the approval's signature does not verify";
+}
+
+/**
+ * The gate's check of one record a pull request adds, once approvals are enforced.
+ * @param {object} record the parsed record
+ * @param {{ id: string, publicKey: string, rpId: string }[]} keys the base branch's keys
+ * @param {{ pr: number }} options the pull request the gate runs on
+ * @returns {string | null} why it fails, or null
+ */
+export function verifyRecord(record, keys, { pr }) {
+    if (typeof record !== "object" || record === null || Array.isArray(record)) {
+        return "not a review record";
+    }
+    if (record.version !== 2) {
+        return `a version ${JSON.stringify(record.version)} record has no passkey approval; review it again with Face ID`;
+    }
+    if (!Array.isArray(record.items) || !Array.isArray(record.rejects)) {
+        return "items and rejects must be arrays";
+    }
+    if (record.pr !== pr && record.pr !== null) {
+        return `the record is for pull request #${record.pr}, not #${pr}`;
+    }
+    return verifyApproval(record, keys);
+}
+
+/**
+ * The server's check of a `navigator.credentials.create` response. Attestation is not checked
+ * (Apple passkeys give "none"): the owner merging the key's pull request is the trust step.
+ * @param {{ credentialId: string, publicKey: string, algorithm: number, authenticatorData: string,
+ *     clientDataJSON: string }} input what the page sent
+ * @param {{ challenge: string, origin: string, rpId: string }} expected the server's challenge
+ *     (base64url), its origin and rpId
+ * @returns {string | null} why it fails, or null
+ */
+export function verifyRegistration(input, { challenge, origin, rpId }) {
+    for (const f of ["credentialId", "publicKey", "authenticatorData", "clientDataJSON"]) {
+        if (typeof input?.[f] !== "string" || !B64U.test(input[f])) {
+            return `${f} is not base64url`;
+        }
+    }
+    if (input.algorithm !== -7) {
+        return `algorithm ${input.algorithm} is not ES256 (-7)`;
+    }
+    const clientData = jsonOf(input.clientDataJSON);
+    if (clientData === undefined) {
+        return "clientDataJSON is not JSON";
+    }
+    const authData = b64u(input.authenticatorData);
+    const why = checkCeremony({
+        clientData,
+        authData,
+        type: "webauthn.create",
+        challenge,
+        rpId,
+        originOk: (o) => o === origin,
+    });
+    if (why) {
+        return why;
+    }
+    // The attested credential data names the credential: it must be the id sent.
+    const id = b64u(input.credentialId);
+    const length = authData.length >= 55 ? authData.readUInt16BE(53) : -1;
+    if (!(authData[32] & AT) || length !== id.length || !authData.subarray(55, 55 + length).equals(id)) {
+        return "authenticatorData does not hold this credential id";
+    }
+    try {
+        loadKey(input.publicKey);
+    } catch (err) {
+        return err.message;
+    }
+    return null;
+}

package/trusted/lib/github.mjs

@@ -57,6 +57,14 @@ export const ghRunner = (cwd) => withRetries((args, input) => exec("gh", args, {
 const TRANSIENT =
     /could not resolve host|no such host|error connecting to|connection (reset|refused|timed out)|i\/o timeout|TLS handshake timeout|HTTP 5\d\d|unexpected EOF|GOAWAY|stream error|context deadline exceeded|timed out after/i;
 
+/**
+ * The gh calls waiting to retry after a network failure, newest last, each with its error, which
+ * try it waits for and until when: the review page shows the newest, so a dropped DNS lookup reads
+ * as "retrying" and never as a hang.
+ * @type {Set<{ error: string, attempt: number, of: number, until: number }>}
+ */
+export const retrying = new Set();
+
 /**
  * Retries a gh runner's calls that failed on the network, after each delay in turn. A write
  * (`--input`) is never retried: GitHub may have applied it before the connection dropped. Every
@@ -79,7 +87,15 @@ export const withRetries =
                 if (!retry) {
                     throw err;
                 }
+                const wait = {
+                    error: err.message.split("\n")[0],
+                    attempt: i + 2,
+                    of: delays.length + 1,
+                    until: Date.now() + delays[i],
+                };
+                retrying.add(wait);
                 await new Promise((resolve) => setTimeout(resolve, delays[i]));
+                retrying.delete(wait);
             }
         }
     };
@@ -158,6 +174,29 @@ export async function visualJobs(gh, run, attempt, projects) {
 // Downloads in flight, by target directory: concurrent refreshes of one run await the same one.
 const downloading = new Map();
 
+// At most this many `gh run download` at once: every open pull request's captures start at once,
+// and dozens of parallel transfers only slow each other (and the one the reviewer is waiting for).
+const DOWNLOADS = 8;
+let active = 0;
+/** Downloads waiting for a slot, by target directory, in the order they start. */
+const queued = [];
+const pump = () => {
+    while (active < DOWNLOADS && queued.length > 0) {
+        active++;
+        queued.shift().start();
+    }
+};
+
+/**
+ * Moves the waiting downloads whose directory `wanted` picks to the front of the queue: the
+ * project the reviewer is opening downloads next, before the ones nobody is waiting for.
+ * @param {(dir: string) => boolean} wanted picks the directories to hurry
+ */
+export function hurry(wanted) {
+    const first = queued.filter((q) => wanted(q.dir));
+    queued.splice(0, queued.length, ...first, ...queued.filter((q) => !wanted(q.dir)));
+}
+
 /**
  * Downloads one artifact into `dir`, unless it is already there. It is extracted into a sibling
  * temporary directory and renamed into place only once its results.json is there, so `dir` either
@@ -192,6 +231,10 @@ function download(gh, runId, name, dir) {
                     rmSync(join(dirname(dir), f), { recursive: true, force: true });
                 }
             }
+            await new Promise((start) => {
+                queued.push({ dir, start });
+                pump();
+            });
             const part = mkdtempSync(`${dir}.part-`);
             try {
                 await gh(["run", "download", String(runId), "-n", name, "-D", part]);
@@ -200,6 +243,8 @@ function download(gh, runId, name, dir) {
                 }
             } finally {
                 rmSync(part, { recursive: true, force: true });
+                active--;
+                pump();
             }
         })().finally(() => downloading.delete(dir));
         downloading.set(dir, done);
@@ -218,11 +263,16 @@ function download(gh, runId, name, dir) {
  * @param {string[]} projects project ids
  * @param {string} tmp the download root
  * @param {string[]} [others] receives the projects the run captured that are not in `projects`
- * @returns {Promise<Record<string, { dir: string | null, attempt: number, error?: string,
- *     expired?: true } | null>>} null for a project with no artifact; `error` (and no `dir`) when
- *     its download failed; `expired` (and no `dir`) when GitHub deleted it and it is not on disk
+ * @param {(project: string, got: object | null) => void} [landed] told as each project's download
+ *     ends, with what the result holds for it, so a page can fill rows in one by one
+ * @param {(sizes: Record<string, number>) => void} [planned] told first, with the size in bytes
+ *     of each project's artifact, so a page can count the bytes still to come
+ * @returns {Promise<Record<string, { dir: string | null, attempt: number, bytes: number,
+ *     error?: string, expired?: true } | null>>} null for a project with no artifact; `error`
+ *     (and no `dir`) when its download failed; `expired` (and no `dir`) when GitHub deleted it and
+ *     it is not on disk
  */
-export async function downloadCaptures(gh, run, projects, tmp, others = []) {
+export async function downloadCaptures(gh, run, projects, tmp, others = [], landed = () => {}, planned = () => {}) {
     const { artifacts } = await api(gh, `repos/{owner}/{repo}/actions/runs/${run.id}/artifacts?per_page=100`);
     for (const a of artifacts) {
         const p = /^visual-(.+)-\d+$/.exec(a.name)?.[1];
@@ -230,32 +280,49 @@ export async function downloadCaptures(gh, run, projects, tmp, others = []) {
             others.push(p);
         }
     }
-    /** @type {Record<string, { dir: string | null, attempt: number, error?: string, expired?: true } | null>} */
+    const newest = Object.fromEntries(
+        projects.map((project) => {
+            const pattern = new RegExp(`^visual-${project}-(\\d+)$`);
+            const a = artifacts
+                .filter((x) => pattern.test(x.name))
+                .map((x) => ({
+                    name: x.name,
+                    expired: x.expired,
+                    bytes: x.size_in_bytes ?? 0,
+                    attempt: Number(pattern.exec(x.name)[1]),
+                }))
+                .sort((x, y) => y.attempt - x.attempt)[0];
+            return [project, a ?? null];
+        }),
+    );
+    planned(Object.fromEntries(Object.entries(newest).flatMap(([p, a]) => (a ? [[p, a.bytes]] : []))));
+    /** @type {Record<string, { dir: string | null, attempt: number, bytes: number, error?: string, expired?: true } | null>} */
     const out = {};
-    for (const project of projects) {
-        const pattern = new RegExp(`^visual-${project}-(\\d+)$`);
-        const newest = artifacts
-            .filter((a) => pattern.test(a.name))
-            .map((a) => ({ name: a.name, expired: a.expired, attempt: Number(pattern.exec(a.name)[1]) }))
-            .sort((a, b) => b.attempt - a.attempt)[0];
-        if (!newest) {
-            out[project] = null;
-            continue;
-        }
-        const dir = join(tmp, `${run.id}-${newest.attempt}`, project);
-        if (newest.expired) {
-            out[project] = existsSync(join(dir, "results.json"))
-                ? { dir, attempt: newest.attempt }
-                : { dir: null, attempt: newest.attempt, expired: true };
-            continue;
-        }
-        try {
-            await download(gh, run.id, newest.name, dir);
-            out[project] = { dir, attempt: newest.attempt };
-        } catch (err) {
-            out[project] = { dir: null, attempt: newest.attempt, error: err.message };
-        }
-    }
+    // Every project at once: the shared cap on downloads keeps the number of transfers sane.
+    await Promise.all(
+        projects.map(async (project) => {
+            const a = newest[project];
+            if (!a) {
+                out[project] = null;
+            } else {
+                const dir = join(tmp, `${run.id}-${a.attempt}`, project);
+                const got = { attempt: a.attempt, bytes: a.bytes };
+                if (a.expired) {
+                    out[project] = existsSync(join(dir, "results.json"))
+                        ? { dir, ...got }
+                        : { dir: null, ...got, expired: true };
+                } else {
+                    try {
+                        await download(gh, run.id, a.name, dir);
+                        out[project] = { dir, ...got };
+                    } catch (err) {
+                        out[project] = { dir: null, ...got, error: err.message };
+                    }
+                }
+            }
+            landed(project, out[project]);
+        }),
+    );
     return out;
 }