spiderlint 0.0.0 → 0.143.0

package/dist/crawl/svcb.js

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+const KEYS = ["mandatory", "alpn", "no-default-alpn", "port", "ipv4hint", "ech", "ipv6hint"];
+// An uncompressed domain name at `offset`, as §2.2 requires, and the offset past it.
+function name(data, offset) {
+    const labels = [];
+    for (let length = data.readUInt8(offset); length > 0; length = data.readUInt8(offset)) {
+        if (length > 63)
+            throw new Error(`SVCB target label length ${length} is a compression pointer`);
+        labels.push(data.toString("latin1", offset + 1, offset + 1 + length));
+        offset += 1 + length;
+    }
+    return [labels.length === 0 ? "." : labels.join("."), offset + 1];
+}
+// `width`-byte chunks of `value`, each rendered by `render`.
+function chunks(value, width, render) {
+    if (value.length % width !== 0)
+        throw new Error(`SVCB address hint of ${value.length} bytes`);
+    return Array.from({ length: value.length / width }, (_, index) => render(value.subarray(index * width, (index + 1) * width)));
+}
+// Length-prefixed strings, the wire form of `alpn`.
+function strings(value) {
+    const out = [];
+    for (let offset = 0; offset < value.length; offset += 1 + value.readUInt8(offset))
+        out.push(value.toString("latin1", offset + 1, offset + 1 + value.readUInt8(offset)));
+    return out;
+}
+// The RFC 5952 text form of a 16-byte IPv6 address, as the URL parser canonicalises it.
+function ipv6(bytes) {
+    const groups = Array.from({ length: 8 }, (_, index) => bytes.readUInt16BE(index * 2).toString(16)).join(":");
+    return new URL(`http://[${groups}]/`).hostname.slice(1, -1);
+}
+// Each known SvcParamKey’s value, by key number (RFC 9460 §14.3.2).
+const DECODERS = {
+    0: (value) => ({ mandatory: Array.from({ length: value.length / 2 }, (_, index) => KEYS[value.readUInt16BE(index * 2)] ?? `key${value.readUInt16BE(index * 2)}`) }),
+    1: (value) => ({ alpn: strings(value) }),
+    2: () => ({ "no-default-alpn": true }),
+    3: (value) => ({ port: value.readUInt16BE(0) }),
+    4: (value) => ({ ipv4hint: chunks(value, 4, (bytes) => [...bytes].join(".")) }),
+    5: () => ({ ech: true }),
+    6: (value) => ({ ipv6hint: chunks(value, 16, ipv6) }),
+};
+// The RDATA of a type 64 or 65 record: priority, target, then key-ordered parameters.
+export function parseSvcb(data) {
+    const [target, start] = name(data, 2);
+    const record = { priority: data.readUInt16BE(0), target };
+    for (let offset = start; offset < data.length;) {
+        const key = data.readUInt16BE(offset);
+        const value = data.subarray(offset + 4, offset + 4 + data.readUInt16BE(offset + 2));
+        offset += 4 + value.length;
+        const decode = DECODERS[key];
+        if (decode)
+            Object.assign(record, decode(value));
+        else
+            (record.unknown ??= []).push(key);
+    }
+    return record;
+}

package/dist/crawl/tls-hello.js

@@ -0,0 +1,297 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { createDecipheriv, createECDH, createHash, createHmac, createPublicKey, diffieHellman, generateKeyPairSync, randomBytes } from "node:crypto";
+import { isIP } from "node:net";
+// Wire versions by Node’s protocol name.
+export const VERSIONS = { SSLv3: 0x03_00, TLSv1: 0x03_01, "TLSv1.1": 0x03_02, "TLSv1.2": 0x03_03, "TLSv1.3": 0x03_04 };
+// The suite a client adds when it retries at a lower version (RFC 7507).
+export const FALLBACK_SCSV = 0x56_00;
+// The alert a server supporting RFC 7507 answers a needless fallback with.
+export const INAPPROPRIATE_FALLBACK = 86;
+// The one TLS 1.3 suite every server implements (RFC 8446 §9.1), which `openHandshake` decrypts.
+export const TLS13_MANDATORY = 0x13_01;
+// SSLv2 cipher kinds, by the name OpenSSL gives them.
+export const SSL2_KINDS = {
+    0x01_00_80: "SSL_CK_RC4_128_WITH_MD5",
+    0x02_00_80: "SSL_CK_RC4_128_EXPORT40_WITH_MD5",
+    0x03_00_80: "SSL_CK_RC2_128_CBC_WITH_MD5",
+    0x04_00_80: "SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5",
+    0x05_00_80: "SSL_CK_IDEA_128_CBC_WITH_MD5",
+    0x06_00_40: "SSL_CK_DES_64_CBC_WITH_MD5",
+    0x07_00_c0: "SSL_CK_DES_192_EDE3_CBC_WITH_MD5",
+};
+const HANDSHAKE = 22;
+const ALERT = 21;
+const APPLICATION = 23;
+const X25519 = 29;
+const SECP256R1 = 23;
+// The ServerHello random that marks a HelloRetryRequest (RFC 8446 §4.1.3).
+const RETRY = Buffer.from("cf21ad74e59a6111be1d8c021e65b891c2a211167abb8c5e079e09e2c8a8339c", "hex");
+// The DER prefix turning a raw x25519 key into a SubjectPublicKeyInfo.
+const X25519_SPKI = Buffer.from("302a300506032b656e032100", "hex");
+// Every signature scheme a server may sign with, so none refuses for want of one.
+const SIGNATURES = [0x04_03, 0x05_03, 0x06_03, 0x08_07, 0x08_08, 0x08_04, 0x08_05, 0x08_06, 0x08_09, 0x08_0a, 0x08_0b, 0x08_1a, 0x08_1b, 0x08_1c, 0x04_01, 0x05_01, 0x06_01, 0x03_03, 0x03_01, 0x04_02, 0x05_02, 0x06_02, 0x02_03, 0x02_01, 0x02_02];
+function u8(value) {
+    return Buffer.from([value]);
+}
+function u16(value) {
+    const bytes = Buffer.alloc(2);
+    bytes.writeUInt16BE(value);
+    return bytes;
+}
+function u24(value) {
+    const bytes = Buffer.alloc(3);
+    bytes.writeUIntBE(value, 0, 3);
+    return bytes;
+}
+// `body` behind its length in `width` bytes.
+function vector(width, body) {
+    return Buffer.concat([[u8, u16, u24][width - 1]?.(body.length) ?? Buffer.alloc(0), body]);
+}
+function extension(type, body) {
+    return Buffer.concat([u16(type), vector(2, body)]);
+}
+// A vector of 16-bit values.
+function list16(values) {
+    return vector(2, Buffer.concat(values.map((value) => u16(value))));
+}
+// The `server_name` body naming `host`.
+function serverName(host) {
+    const name = vector(2, Buffer.from(host));
+    return vector(2, Buffer.concat([u8(0), name]));
+}
+// The `key_share` body carrying `shares`.
+function keyShareList(shares) {
+    const entries = shares.map((share) => Buffer.concat([u16(share.group), vector(2, share.key)]));
+    return vector(2, Buffer.concat(entries));
+}
+// The extensions of a hello; SSLv3 sends none, TLS 1.3 swaps renegotiation and heartbeat for versions and key shares.
+function extensionsOf(hello, version) {
+    if (version === VERSIONS.SSLv3)
+        return [];
+    const isModern = version === VERSIONS["TLSv1.3"];
+    return [
+        ...(isIP(hello.host) === 0 ? [extension(0, serverName(hello.host))] : []),
+        extension(5, Buffer.from([1, 0, 0, 0, 0])),
+        extension(10, list16(hello.groups)),
+        extension(11, Buffer.from([1, 0])),
+        ...(version >= VERSIONS["TLSv1.2"] ? [extension(13, list16(SIGNATURES))] : []),
+        ...(isModern ? [extension(43, Buffer.from([2, 3, 4])), extension(51, keyShareList(hello.shares ?? []))] : [extension(15, u8(1)), extension(0xff_01, u8(0))]),
+    ];
+}
+// One ClientHello record, padded out of the 256–511 byte range some load balancers drop (RFC 7685).
+export function clientHello(hello) {
+    const version = VERSIONS[hello.protocol];
+    const isModern = version === VERSIONS["TLSv1.3"];
+    const session = vector(1, isModern ? randomBytes(32) : Buffer.alloc(0));
+    const compression = vector(1, Buffer.from(!isModern && hello.compression ? [1, 0] : [0]));
+    const head = Buffer.concat([u16(Math.min(version, VERSIONS["TLSv1.2"])), randomBytes(32), session, list16(hello.suites), compression]);
+    const extensions = extensionsOf(hello, version);
+    const length = 4 + head.length + 2 + extensions.reduce((sum, entry) => sum + entry.length, 0);
+    const padding = Buffer.alloc(Math.max(0, 512 - length - 4));
+    if (version !== VERSIONS.SSLv3 && length >= 256 && length < 512)
+        extensions.push(extension(21, padding));
+    const body = version === VERSIONS.SSLv3 ? head : Buffer.concat([head, vector(2, Buffer.concat(extensions))]);
+    const message = Buffer.concat([u8(1), vector(3, body)]);
+    return Buffer.concat([u8(HANDSHAKE), u16(Math.min(version, VERSIONS.TLSv1)), vector(2, message)]);
+}
+// An SSLv2 CLIENT-HELLO offering every cipher kind.
+export function sslv2Hello() {
+    const kinds = Buffer.concat(Object.keys(SSL2_KINDS).map((kind) => u24(Number(kind))));
+    const body = Buffer.concat([u8(1), u16(0x00_02), u16(kinds.length), u16(0), u16(16), kinds, randomBytes(16)]);
+    return Buffer.concat([u16(0x80_00 | body.length), body]);
+}
+// Fresh x25519 and secp256r1 key shares, and the TLS 1.3 client that can decrypt the answer to the hello carrying them.
+export function keyShares() {
+    const x25519 = generateKeyPairSync("x25519");
+    const p256 = createECDH("prime256v1");
+    p256.generateKeys();
+    const shares = [
+        { group: X25519, key: x25519.publicKey.export({ format: "der", type: "spki" }).subarray(-32) },
+        { group: SECP256R1, key: p256.getPublicKey() },
+    ];
+    const agree = (group, share) => {
+        if (group === SECP256R1)
+            return p256.computeSecret(share);
+        if (group !== X25519)
+            return;
+        const publicKey = createPublicKey({ key: Buffer.concat([X25519_SPKI, share]), format: "der", type: "spki" });
+        return diffieHellman({ privateKey: x25519.privateKey, publicKey });
+    };
+    return { shares, client: (hello) => ({ hello: hello.subarray(5), agree }) };
+}
+function sha256(data) {
+    return createHash("sha256").update(data).digest();
+}
+function hmac(key, data) {
+    return createHmac("sha256", key).update(data).digest();
+}
+// HKDF-Expand-Label over SHA-256 (RFC 8446 §7.1).
+function expandLabel(secret, label, context, length) {
+    const name = Buffer.from(`tls13 ${label}`);
+    const info = Buffer.concat([u16(length), vector(1, name), vector(1, context)]);
+    const blocks = [];
+    for (let block = Buffer.alloc(0), index = 1; blocks.length * 32 < length; index++) {
+        block = hmac(secret, Buffer.concat([block, info, u8(index)]));
+        blocks.push(block);
+    }
+    return Buffer.concat(blocks).subarray(0, length);
+}
+// The server handshake traffic decrypter of TLS_AES_128_GCM_SHA256, from the shared secret and the ClientHello…ServerHello transcript.
+export function openHandshake(secret, transcript) {
+    const empty = Buffer.alloc(0);
+    const early = hmac(Buffer.alloc(32), Buffer.alloc(32));
+    const handshake = hmac(expandLabel(early, "derived", sha256(empty), 32), secret);
+    const traffic = expandLabel(handshake, "s hs traffic", sha256(transcript), 32);
+    const [key, iv] = [expandLabel(traffic, "key", empty, 16), expandLabel(traffic, "iv", empty, 12)];
+    let sequence = 0n;
+    return (header, sealed) => {
+        const nonce = Buffer.from(iv);
+        nonce.writeBigUInt64BE(nonce.readBigUInt64BE(4) ^ sequence++, 4);
+        const decipher = createDecipheriv("aes-128-gcm", key, nonce);
+        decipher.setAAD(header);
+        decipher.setAuthTag(sealed.subarray(-16));
+        return Buffer.concat([decipher.update(sealed.subarray(0, -16)), decipher.final()]);
+    };
+}
+// The ServerHello’s version, suite, compression and extensions into `flight`.
+function readServerHello(body, flight) {
+    flight.version = body.readUInt16BE(0);
+    if (body.subarray(2, 34).equals(RETRY))
+        flight.retry = true;
+    let at = 35 + (body[34] ?? 0);
+    flight.suite = body.readUInt16BE(at);
+    flight.compression = body[at + 2];
+    at += 3;
+    flight.extensions = [];
+    const end = at + 2 <= body.length ? at + 2 + body.readUInt16BE(at) : at;
+    for (at += 2; at + 4 <= end; at += 4 + body.readUInt16BE(at + 2)) {
+        const type = body.readUInt16BE(at);
+        const data = body.subarray(at + 4, at + 4 + body.readUInt16BE(at + 2));
+        flight.extensions.push(type);
+        if (type === 43)
+            flight.version = data.readUInt16BE(0);
+        else if (type === 51)
+            flight.group = data.readUInt16BE(0);
+        if (type === 51 && !flight.retry)
+            flight.share = data.subarray(4, 4 + data.readUInt16BE(2));
+    }
+}
+// The OCSP response of a CertificateStatus body, when it carries one.
+function readStatus(body) {
+    return body[0] === 1 ? body.subarray(4, 4 + body.readUIntBE(1, 3)) : undefined;
+}
+// The certificates of a Certificate message, and in TLS 1.3 the leaf’s stapled OCSP response.
+function readCertificates(body, flight) {
+    const isModern = flight.version === VERSIONS["TLSv1.3"];
+    let at = isModern ? 1 + (body[0] ?? 0) : 0;
+    const end = at + 3 + body.readUIntBE(at, 3);
+    const certificates = [];
+    for (at += 3; at + 3 <= end;) {
+        const size = body.readUIntBE(at, 3);
+        certificates.push(body.subarray(at + 3, at + 3 + size));
+        at += 3 + size;
+        if (!isModern)
+            continue;
+        const extensionsEnd = at + 2 + body.readUInt16BE(at);
+        for (let entry = at + 2; entry + 4 <= extensionsEnd; entry += 4 + body.readUInt16BE(entry + 2)) {
+            const data = body.subarray(entry + 4, entry + 4 + body.readUInt16BE(entry + 2));
+            if (certificates.length === 1 && body.readUInt16BE(entry) === 5)
+                flight.ocsp = readStatus(data);
+        }
+        at = extensionsEnd;
+    }
+    flight.certificates = certificates;
+}
+// An SSLv2 SERVER-HELLO: its certificate and the cipher kinds it offers.
+function readSsl2(data) {
+    const length = ((data[0] ?? 0) & 0x7f) * 256 + (data[1] ?? 0);
+    if (data.length < 2 + length)
+        return { complete: false };
+    const body = data.subarray(2, 2 + length);
+    const [certificate, kinds] = [body.readUInt16BE(5), body.readUInt16BE(7)];
+    const list = body.subarray(11 + certificate, 11 + certificate + kinds);
+    const offered = Array.from({ length: Math.floor(list.length / 3) }, (_, index) => list.readUIntBE(index * 3, 3));
+    return { complete: true, version: 0x00_02, certificates: [body.subarray(11, 11 + certificate)], kinds: offered };
+}
+// One handshake message into `flight`.
+function readMessage(type, body, flight) {
+    switch (type) {
+        case 2: {
+            readServerHello(body, flight);
+            break;
+        }
+        case 11: {
+            readCertificates(body, flight);
+            break;
+        }
+        case 12: {
+            flight.keyExchange = body;
+            break;
+        }
+        case 22: {
+            flight.ocsp = readStatus(body);
+            break;
+        }
+    }
+}
+// Whether a message of `type` ends what the server says before the client speaks.
+function isLast(type, flight) {
+    return type === 14 || (type === 2 && flight.retry === true) || (type === 11 && flight.version === VERSIONS["TLSv1.3"]);
+}
+// The server’s answer so far, read afresh from every byte received; `client` decrypts a TLS 1.3 flight up to its Certificate.
+export function readFlight(data, client) {
+    if (data.length >= 3 && ((data[0] ?? 0) & 0x80) !== 0 && data[2] === 4)
+        return readSsl2(data);
+    const flight = { complete: false };
+    let open;
+    let stream = Buffer.alloc(0);
+    let at = 0;
+    try {
+        for (let offset = 0; offset + 5 <= data.length;) {
+            const header = data.subarray(offset, offset + 5);
+            const body = data.subarray(offset + 5, offset + 5 + header.readUInt16BE(3));
+            if (body.length < header.readUInt16BE(3))
+                break;
+            offset += 5 + body.length;
+            let [type, content] = [header[0], body];
+            if (type === APPLICATION && open) {
+                const inner = open(header, body);
+                const end = inner.findLastIndex((byte) => byte !== 0);
+                [type, content] = [inner[end], inner.subarray(0, end)];
+            }
+            if (type === ALERT)
+                return { ...flight, complete: true, alert: content[1] };
+            if (type !== HANDSHAKE)
+                continue;
+            stream = Buffer.concat([stream, content]);
+            for (; at + 4 <= stream.length && at + 4 + stream.readUIntBE(at + 1, 3) <= stream.length; at += 4 + stream.readUIntBE(at + 1, 3)) {
+                const message = stream.subarray(at, at + 4 + stream.readUIntBE(at + 1, 3));
+                readMessage(message[0] ?? 0, message.subarray(4), flight);
+                if (isLast(message[0] ?? 0, flight))
+                    return { ...flight, complete: true };
+                if (message[0] !== 2 || flight.version !== VERSIONS["TLSv1.3"])
+                    continue;
+                const secret = client && flight.suite === TLS13_MANDATORY && flight.share && flight.group !== undefined ? client.agree(flight.group, flight.share) : undefined;
+                if (!secret || !client)
+                    return { ...flight, complete: true };
+                open = openHandshake(secret, Buffer.concat([client.hello, message]));
+            }
+        }
+    }
+    catch (error) {
+        return { ...flight, complete: true, error: error instanceof Error ? error.message : String(error) };
+    }
+    return flight;
+}
+// The prime size of a DHE ServerKeyExchange, in bits.
+export function dhBits(keyExchange) {
+    const prime = keyExchange.subarray(2, 2 + keyExchange.readUInt16BE(0));
+    const first = prime.findIndex((byte) => byte !== 0);
+    return first === -1 ? 0 : (prime.length - first) * 8 - Math.clz32(prime[first] ?? 0) + 24;
+}
+// The named curve of an ECDHE ServerKeyExchange.
+export function curve(keyExchange) {
+    return keyExchange[0] === 3 ? keyExchange.readUInt16BE(1) : undefined;
+}

package/dist/crawl/tls-probe.js

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { isIP } from "node:net";
+import { setTimeout as sleep } from "node:timers/promises";
+import { connect } from "node:tls";
+import { tlsFacts } from "../facts/transport.js";
+import { log } from "../logger.js";
+import { delay, reason } from "./fetch.js";
+import { guardedLookup, isPrivate, PrivateAddress } from "./guard.js";
+const ATTEMPTS = 2;
+const TIMEOUT_MS = 10_000;
+const ALPN = ["h2", "http/1.1"];
+// One handshake to `host` at `address`, read and closed; the certificate is judged, never enforced.
+async function handshake(host, port, address, isPrivateAllowed) {
+    if (!isPrivateAllowed && address && isPrivate(address))
+        throw new PrivateAddress(`${address} is a private address`);
+    const servername = isIP(host) === 0 ? host : undefined;
+    return new Promise((resolve, reject) => {
+        const socket = connect({ host: address ?? host, port, ...(servername && { servername }), ALPNProtocols: ALPN, rejectUnauthorized: false, timeout: TIMEOUT_MS, ...(!isPrivateAllowed && { lookup: guardedLookup }) });
+        socket.once("secureConnect", () => {
+            resolve(tlsFacts(socket));
+            socket.end();
+        });
+        socket.once("timeout", () => socket.destroy(new Error(`TLS handshake with ${host}:${port} timed out`)));
+        socket.once("error", reject);
+    });
+}
+// Handshakes once per (host, port, address) a browser crawl connected to, for the cipher, ALPN, SAN and fingerprint Chromium does not report.
+export class TlsProber {
+    #answers = new Map();
+    #isPrivateAllowed;
+    constructor(isPrivateAllowed) {
+        this.#isPrivateAllowed = isPrivateAllowed;
+    }
+    // One probe with a retry after a failure other than a refused address.
+    async #retrying(host, port, address) {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                const facts = await handshake(host, port, address, this.#isPrivateAllowed);
+                log.debug({ host, port, address, attempt, protocol: facts?.protocol, alpn: facts?.alpn }, "TLS probed");
+                return facts;
+            }
+            catch (error) {
+                const isLast = attempt === ATTEMPTS - 1 || error instanceof PrivateAddress;
+                log[isLast ? "warn" : "debug"]({ host, port, address, attempt, error: reason(error) }, "TLS probe failed");
+                if (isLast)
+                    return undefined;
+                await sleep(delay(attempt));
+            }
+        }
+    }
+    // Handshakes sent, one per distinct key.
+    get probes() {
+        return this.#answers.size;
+    }
+    // The TLS facts of `url`’s host at `address`, undefined off `https:` or once both attempts fail.
+    facts(url, address) {
+        if (url.protocol !== "https:")
+            return Promise.resolve(undefined);
+        const port = Number(url.port || 443);
+        const host = url.hostname.replaceAll(/^\[|\]$/g, "");
+        const key = `${host}:${port}@${address ?? ""}`;
+        const known = this.#answers.get(key);
+        if (known)
+            return known;
+        const answer = this.#retrying(host, port, address);
+        this.#answers.set(key, answer);
+        return answer;
+    }
+}

package/dist/facts/browser.js

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { isIP } from "node:net";
+import { log } from "../logger.js";
+import { cookieFacts, redirectHop } from "./transport.js";
+const DAY = 86_400_000;
+// Playwright resource types that map onto a resource kind; the main document is never one.
+const KINDS = { script: "script", stylesheet: "style", image: "image", font: "font", document: "iframe", manifest: "manifest" };
+// Where the init script keeps each `document.cookie` write for the crawler to read back.
+const WRITES = "__spiderlintCookieWrites";
+// Wraps the `document.cookie` setter before any page script runs, keeping each write with its value cut out.
+export const COOKIE_WRITES = `(() => { const cookie = Object.getOwnPropertyDescriptor(Document.prototype, "cookie"); if (!cookie?.get || !cookie.set) return; const writes = []; Object.defineProperty(globalThis, "${WRITES}", { value: writes }); Object.defineProperty(Document.prototype, "cookie", { configurable: true, enumerable: cookie.enumerable, get: cookie.get, set(value) { writes.push(String(value).replace(/^([^=;]*)=[^;]*/, "$1=")); cookie.set.call(this, value); } }); })();`;
+// Cookies the page’s scripts wrote through `document.cookie`, read as Set-Cookie lines, deletions aside; values never leave the page.
+export async function scriptCookies(page) {
+    const writes = (await page.evaluate(`globalThis.${WRITES} ?? []`));
+    const cookies = cookieFacts([...new Set(writes)]).filter((cookie) => (cookie["max-age"] ?? 1) > 0);
+    log.debug({ url: page.url(), writes: writes.length, cookies: cookies.length }, "script cookie writes read");
+    return cookies;
+}
+// Header pairs as the facts document holds them: lower-cased names, repeated ones as arrays.
+export function headerFacts(pairs) {
+    const out = {};
+    for (const { name, value } of pairs) {
+        const key = name.toLowerCase();
+        const had = out[key];
+        out[key] = had === undefined ? value : [had, value].flat();
+    }
+    return out;
+}
+// Milliseconds between two Resource Timing marks, absent when either was not reached.
+function span(from, to) {
+    return from >= 0 && to >= from ? Math.round(to - from) : undefined;
+}
+// Chromium’s Resource Timing marks renamed to the phases got reports.
+export function timingFacts(timing) {
+    const isSecure = timing.secureConnectionStart >= 0;
+    const phases = {
+        dns: span(timing.domainLookupStart, timing.domainLookupEnd),
+        tcp: span(timing.connectStart, isSecure ? timing.secureConnectionStart : timing.connectEnd),
+        tls: isSecure ? span(timing.secureConnectionStart, timing.connectEnd) : undefined,
+        ttfb: span(timing.requestStart, timing.responseStart),
+        download: span(timing.responseStart, timing.responseEnd),
+        total: span(0, timing.responseEnd),
+    };
+    return Object.fromEntries(Object.entries(phases).filter(([, value]) => value !== undefined));
+}
+// Every URL the navigation passed through after the first, with the status and headers of the response that sent it there.
+export async function redirectFacts(request) {
+    const hops = [];
+    for (let hop = request, from = hop.redirectedFrom(); from; hop = from, from = from.redirectedFrom()) {
+        const response = await from.response();
+        const headers = response ? headerFacts(await response.headersArray()) : undefined;
+        hops.unshift(response && headers ? redirectHop(hop.url(), response.status(), headers) : { url: hop.url() });
+    }
+    return hops;
+}
+// The address Chromium connected to, with the family Node’s sockets report.
+export function remoteFacts(address) {
+    if (!address)
+        return undefined;
+    const ip = address.ipAddress.replaceAll(/^\[|\]$/g, "");
+    const version = isIP(ip);
+    return { address: ip, ...(version > 0 && { family: `IPv${version}` }) };
+}
+// Chromium’s `TLS 1.3` spelled as Node’s `TLSv1.3`; QUIC always runs TLS 1.3 (RFC 9001 §4.2).
+function protocolName(protocol) {
+    return protocol === "QUIC" ? "TLSv1.3" : protocol.replace(/^TLS (\d\.\d)$/, "TLSv$1");
+}
+// A navigation Chromium completed was authorized; cipher, ALPN and fingerprint stay absent, the protocol does not say them.
+export function tlsFacts(details, now = Date.now()) {
+    if (!details?.protocol)
+        return undefined;
+    const notBefore = details.validFrom === undefined ? undefined : new Date(details.validFrom * 1000).toISOString();
+    const notAfter = details.validTo === undefined ? undefined : new Date(details.validTo * 1000).toISOString();
+    return {
+        protocol: protocolName(details.protocol),
+        authorized: true,
+        cert: {
+            ...(details.subjectName && { subject: details.subjectName }),
+            ...(details.issuer && { issuer: details.issuer }),
+            ...(notBefore && { "not-before": notBefore }),
+            ...(notAfter && { "not-after": notAfter, "days-left": Math.floor((Date.parse(notAfter) - now) / DAY) }),
+            san: [],
+        },
+    };
+}
+// What the network log adds to the static census: observed entries flagged, runtime-only ones appended, at most `max`.
+export function observedResources(declared, requests, page, max) {
+    const found = new Map(declared.map((resource) => [`${resource.kind} ${resource.url}`, resource]));
+    for (const request of requests) {
+        const kind = KINDS[request.resourceType()];
+        const isMainFrame = request.frame().parentFrame() === null;
+        if (!kind || (kind === "iframe" && isMainFrame) || !URL.canParse(request.url()))
+            continue;
+        const url = new URL(request.url());
+        url.hash = "";
+        if (!/^https?:$/.test(url.protocol))
+            continue;
+        const key = `${kind} ${url.href}`;
+        const known = found.get(key);
+        found.set(key, { ...(known ?? { url: url.href, kind, origin: url.origin === page.origin ? "same" : "cross" }), observed: true });
+    }
+    return found.values().take(max).toArray();
+}
+// Body bytes on the wire; Chromium’s size goes negative on some responses, where Content-Length stands in, else `fallback`.
+export async function wireSize(request, fallback = 0) {
+    const { responseBodySize } = await request.sizes();
+    if (responseBodySize >= 0)
+        return responseBodySize;
+    const response = await request.response();
+    const declared = Number((await response?.headerValue("content-length")) ?? NaN);
+    log.debug({ url: request.url(), responseBodySize, declared, fallback }, "wire size unknown, using Content-Length or fallback");
+    return Number.isSafeInteger(declared) ? declared : fallback;
+}
+// Bytes the network log received per resource kind, keyed as `browser.weight` names them; failed requests weigh nothing.
+export async function weightFacts(requests) {
+    const weight = {};
+    for (const request of requests) {
+        const kind = KINDS[request.resourceType()];
+        if (request.failure() || (kind !== "script" && kind !== "style" && kind !== "image" && kind !== "font"))
+            continue;
+        weight[kind] = (weight[kind] ?? 0) + (await wireSize(request));
+    }
+    return weight;
+}
+// HTTP version per protocol Chromium’s network log names.
+const HOP_VERSIONS = { h3: "3.0", h2: "2.0", "http/1.1": "1.1" };
+// Chromium’s TLS completed by the probe when both saw one certificate, and the HTTP version: the measured hop, else QUIC is 3, the probe’s ALPN, plain text 1.1.
+export function withProbe(url, seen, security, probed, hop) {
+    if (security === undefined)
+        return { ...(seen && { tls: seen }), version: HOP_VERSIONS[hop ?? ""] ?? "1.1" };
+    const isSame = probed !== undefined && (seen === undefined || (seen.cert.subject === probed.cert.subject && seen.cert["not-after"] === probed.cert["not-after"]));
+    log.debug({ url, security, hop, isProbed: probed !== undefined, isSame, subject: seen?.cert.subject, probedSubject: probed?.cert.subject }, "probed TLS compared");
+    const tls = isSame ? { ...probed, ...(seen?.protocol && { protocol: seen.protocol }) } : seen;
+    const version = HOP_VERSIONS[hop ?? ""] ?? (security === "QUIC" ? "3.0" : isSame ? (probed.alpn === "h2" ? "2.0" : "1.1") : undefined);
+    return { ...(tls && { tls }), ...(version && { version }) };
+}

package/dist/facts/byline.js

@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { log } from "../logger.js";
+const isNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+// Every JSON-LD node, through arrays and `@graph`, in document order.
+const nodesOf = (value) => (Array.isArray(value) ? value.flatMap((item) => nodesOf(item)) : isNode(value) ? [value, ...nodesOf(value["@graph"])] : []);
+// A schema.org `author` as a name: a string, a node’s `name`, or the first of a list.
+const nameOf = (value) => (typeof value === "string" ? value : Array.isArray(value) ? nameOf(value[0]) : isNode(value) && typeof value.name === "string" ? value.name : undefined);
+// Author and publication date the way a link preview resolves them: JSON-LD first, then the head tags.
+export function bylineFacts(html) {
+    const nodes = nodesOf(html.jsonld);
+    const author = nodes.map((node) => nameOf(node.author)).find(Boolean) ?? html.property["article:author"] ?? html.meta.author ?? html.property["og:author"] ?? html.meta["og:author"];
+    const published = nodes.map((node) => node.datePublished).find((value) => typeof value === "string") ?? html.property["article:published_time"];
+    log.debug({ nodes: nodes.length, author, published }, "byline resolved");
+    return { ...(author?.trim() && { author }), ...(published?.trim() && { published }) };
+}

package/dist/facts/co2.js

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { log } from "../logger.js";
+// The model every estimate names, so two runs compare: Sustainable Web Design v4 through CO2.js 0.19.0.
+const MODEL = { model: "swd", version: 4, library: "@tgwf/co2 0.19.0" };
+// The estimator once loaded; absent until a run needs it.
+const loaded = {};
+// Loads CO2.js once, only for a run whose rules read `co2`.
+export async function loadEstimator() {
+    const module = loaded.estimator ? undefined : await import("@tgwf/co2");
+    if (module)
+        loaded.estimator = new module.co2({ model: MODEL.model, version: MODEL.version, rating: true });
+    log.debug({ ...MODEL, isFresh: module !== undefined }, "co2 estimator loaded");
+}
+// Grams of CO2e per view of a page: its own transfer size plus each distinct resource it loaded, hosting counted as not green until the green check lands.
+export function co2Facts(page) {
+    if (!loaded.estimator)
+        return undefined;
+    const sizes = new Map((page.resources ?? []).flatMap((resource) => (resource.http?.size.body === undefined ? [] : [[resource.url, resource.http.size.body]])));
+    const resources = sizes.values().reduce((sum, bytes) => sum + bytes, 0);
+    const bytes = page.http.size.body + resources;
+    const { total, rating } = loaded.estimator.perVisit(bytes, false);
+    const grams = Math.round(total * 10_000) / 10_000;
+    log.debug({ url: page.url.href, bytes, resources: sizes.size, grams, rating }, "co2 estimated");
+    return { ...MODEL, bytes, resources: sizes.size, grams, rating };
+}