@praxso/attested 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,143 @@
+import { attest, defaultAttestOptions } from './attest.js';
+import { check, defaultCheckOptions } from './check.js';
+import { defaultRunOptions, run } from './run.js';
+import { AttestedError } from './util.js';
+import { TOOL_VERSION } from './constants.js';
+const USAGE = `attested ${TOOL_VERSION}
+
+Usage:
+  attested run [options] -- <test command>
+  attested attest [options]
+  attested check [options]
+
+run options:
+  --ctrf <path>          CTRF report the test command writes (default attested/ctrf.json)
+  --output-dir <dir>     Playwright output dir to hash (default test-results)
+  --config <path>        test config file to record (default: playwright.config.*)
+  --expect-sha <sha>     refuse to run unless HEAD equals <sha>
+  --allow-dirty          allow a dirty working tree
+  --target-url <url>     fail before tests unless <url>/healthz reports sha == --expect-sha (or HEAD)
+  --health-path <path>   health path for --target-url (default /healthz)
+  --receipt <path>       where to write the receipt (default attested/receipt.json)
+  --packet <path>        where to write the failure packet on red (default attested/packet.json)
+
+attest options:
+  --receipt <path>, --ctrf <path>
+  --from-results <dir>   build and prepare the receipt from a downloaded results directory (attested/ctrf.json,
+                         test-results/, test config), treated as data; source comes from GITHUB_SHA and the event
+  --out <dir>            where --from-results writes ctrf.json, receipt, predicates, packet (default signed/attested)
+  --output-dir <dir>, --config <path>, --rerun <command>   (with --from-results)
+
+check options (posts the "attested" check run; needs GITHUB_TOKEN with checks: write):
+  --artifact-url <url>       link to the uploaded workflow artifact
+  --artifact-name <name>     workflow artifact name, for the paste-able verify command
+  --evidence-name <name>     artifact holding the traces, videos and screenshots, for the paste-able download
+                             command (default: results-<sha> when --artifact-name is attested-<sha>)
+  --attestation-url <url>    link to the receipt attestation
+  --receipt <path>, --packet <path>
+`;
+function takeValue(args, i, flag) {
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith('--'))
+        throw new AttestedError(`${flag} needs a value`);
+    return v;
+}
+// Like takeValue, but an empty string (an unset workflow output) means "not given".
+function optValue(args, i, flag) {
+    const v = args[i + 1];
+    if (v === undefined)
+        throw new AttestedError(`${flag} needs a value`);
+    return v === '' ? null : v;
+}
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === '--help' || cmd === '-h') {
+        process.stdout.write(USAGE);
+        return cmd ? 0 : 2;
+    }
+    if (cmd === '--version') {
+        process.stdout.write(TOOL_VERSION + '\n');
+        return 0;
+    }
+    if (cmd === 'run') {
+        const o = defaultRunOptions();
+        o.argv = argv;
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === '--') {
+                o.command = rest.slice(i + 1);
+                break;
+            }
+            else if (a === '--ctrf')
+                o.ctrf = takeValue(rest, i++, a);
+            else if (a === '--output-dir')
+                o.outputDir = takeValue(rest, i++, a);
+            else if (a === '--config')
+                o.config = takeValue(rest, i++, a);
+            else if (a === '--expect-sha')
+                o.expectSha = takeValue(rest, i++, a);
+            else if (a === '--allow-dirty')
+                o.allowDirty = true;
+            else if (a === '--target-url')
+                o.targetUrl = takeValue(rest, i++, a);
+            else if (a === '--health-path')
+                o.healthPath = takeValue(rest, i++, a);
+            else if (a === '--receipt')
+                o.receipt = takeValue(rest, i++, a);
+            else if (a === '--packet')
+                o.packet = takeValue(rest, i++, a);
+            else
+                throw new AttestedError(`unknown option ${a}`);
+        }
+        return run(o);
+    }
+    if (cmd === 'attest') {
+        const o = defaultAttestOptions();
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === '--receipt')
+                o.receipt = takeValue(rest, i++, a);
+            else if (a === '--ctrf')
+                o.ctrf = takeValue(rest, i++, a);
+            else if (a === '--from-results')
+                o.fromResults = takeValue(rest, i++, a);
+            else if (a === '--out')
+                o.out = takeValue(rest, i++, a);
+            else if (a === '--output-dir')
+                o.outputDir = takeValue(rest, i++, a);
+            else if (a === '--config')
+                o.config = takeValue(rest, i++, a);
+            else if (a === '--rerun')
+                o.rerun = takeValue(rest, i++, a);
+            else
+                throw new AttestedError(`unknown option ${a}`);
+        }
+        return attest(o);
+    }
+    if (cmd === 'check') {
+        const o = defaultCheckOptions();
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === '--receipt')
+                o.receipt = takeValue(rest, i++, a);
+            else if (a === '--packet')
+                o.packet = takeValue(rest, i++, a);
+            else if (a === '--artifact-url')
+                o.artifactUrl = optValue(rest, i++, a);
+            else if (a === '--artifact-name')
+                o.artifactName = optValue(rest, i++, a);
+            else if (a === '--evidence-name')
+                o.evidenceName = optValue(rest, i++, a);
+            else if (a === '--attestation-url')
+                o.attestationUrl = optValue(rest, i++, a);
+            else
+                throw new AttestedError(`unknown option ${a}`);
+        }
+        return check(o);
+    }
+    throw new AttestedError(`unknown command ${cmd}\n${USAGE}`);
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`attested: error: ${err instanceof AttestedError ? err.message : err.stack}\n`);
+    process.exit(err instanceof AttestedError ? 2 : 1);
+});

package/dist/packet.js

@@ -0,0 +1,277 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { inflateRawSync } from 'node:zlib';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { TOOL_NAME } from './constants.js';
+import { testNameOf } from './receipt.js';
+import { ANSI, clean, clip, stripUrl } from './redact.js';
+import { relPath, warn } from './util.js';
+export { redact, stripUrl } from './redact.js';
+// The failure packet: deterministic, model-free, at most 12 KB. Written on red so an agent can fix without opening traces.
+export const PACKET_MAX_BYTES = 12 * 1024;
+const MAX_FRAMES = 20;
+const MAX_MESSAGE = 1500;
+// Bounds on every other string in the packet, so that after capPacket drops every list entry the rest always fits.
+const MAX_NAME = 300;
+const MAX_PATH = 300;
+const MAX_FRAME = 300;
+const MAX_METHOD = 16;
+const MAX_RERUN = 500;
+const MAX_EVIDENCE = 10;
+// Trace zips come from an untrusted results directory: bound what is read and what is inflated.
+export const MAX_TRACE_ZIP_BYTES = 256 * 1024 * 1024;
+export const MAX_TRACE_ENTRY_BYTES = 32 * 1024 * 1024;
+export const MAX_TRACE_TOTAL_BYTES = 128 * 1024 * 1024;
+// --- minimal zip reader (Playwright trace.zip), stored and deflate entries only --------------
+// `budget.left` is the number of inflated bytes still allowed across all traces; entries past it are skipped with a warning.
+export function readZip(path, want, budget = { left: MAX_TRACE_TOTAL_BYTES }) {
+    const out = new Map();
+    let buf;
+    try {
+        if (statSync(path).size > MAX_TRACE_ZIP_BYTES) {
+            warn(`trace ${path} is larger than ${MAX_TRACE_ZIP_BYTES} bytes; skipped`);
+            return out;
+        }
+        buf = readFileSync(path);
+    }
+    catch {
+        return out;
+    }
+    let eocd = -1;
+    for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65557); i--)
+        if (buf.readUInt32LE(i) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    if (eocd < 0)
+        return out;
+    const entries = buf.readUInt16LE(eocd + 10);
+    let p = buf.readUInt32LE(eocd + 16);
+    for (let n = 0; n < entries && buf.readUInt32LE(p) === 0x02014b50; n++) {
+        const method = buf.readUInt16LE(p + 10);
+        const csize = buf.readUInt32LE(p + 20);
+        const nameLen = buf.readUInt16LE(p + 28);
+        const extraLen = buf.readUInt16LE(p + 30);
+        const commentLen = buf.readUInt16LE(p + 32);
+        const local = buf.readUInt32LE(p + 42);
+        const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+        p += 46 + nameLen + extraLen + commentLen;
+        if (!want(name))
+            continue;
+        const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
+        const data = buf.subarray(start, start + csize);
+        // Once the shared budget is spent, the remaining entries are not inflated at all.
+        if (budget.left <= 0) {
+            warn(`trace ${path}: the ${MAX_TRACE_TOTAL_BYTES}-byte budget across all traces is spent; remaining entries skipped`);
+            break;
+        }
+        const limit = Math.min(MAX_TRACE_ENTRY_BYTES, budget.left);
+        try {
+            let text;
+            if (method === 0)
+                text = data;
+            else if (method === 8)
+                text = inflateRawSync(data, { maxOutputLength: limit + 1 });
+            else
+                continue;
+            if (text.length > limit)
+                throw new RangeError('limit');
+            budget.left -= text.length;
+            out.set(name, text.toString('utf8'));
+        }
+        catch (err) {
+            // Over the limit (zlib reports ERR_BUFFER_TOO_LARGE) or unreadable: skip the entry.
+            // A rejected entry may have been inflated up to limit + 1 bytes before it was refused: charge that work too.
+            budget.left = Math.max(0, budget.left - (limit + 1));
+            if (err instanceof RangeError || err.code === 'ERR_BUFFER_TOO_LARGE') {
+                warn(`trace ${path}: entry ${clean(name, MAX_PATH)} inflates past ${limit} bytes (per entry ${MAX_TRACE_ENTRY_BYTES}, all traces ${MAX_TRACE_TOTAL_BYTES}); skipped`);
+            }
+        }
+    }
+    return out;
+}
+function jsonl(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip */ }
+    }
+    return out;
+}
+// Console errors/warnings and failed requests from Playwright trace zips. Order of `seq` is trace order across traces.
+export function readTraces(paths) {
+    const cons = new Map();
+    const net = new Map();
+    let seq = 0;
+    const budget = { left: MAX_TRACE_TOTAL_BYTES };
+    for (const path of paths) {
+        if (budget.left <= 0)
+            break;
+        let files;
+        // Trace zips can come from an untrusted results artifact: a malformed one is skipped, never fatal.
+        try {
+            files = readZip(path, (n) => n.endsWith('.trace') || n.endsWith('.network'), budget);
+        }
+        catch {
+            continue;
+        }
+        for (const name of [...files.keys()].sort()) {
+            for (const ev of jsonl(files.get(name))) {
+                seq++;
+                if (ev.type === 'console' && (ev.messageType === 'error' || ev.messageType === 'warning')) {
+                    const level = ev.messageType;
+                    const message = clean(ev.text ?? '', 300);
+                    const key = `${level}\u0000${message}`;
+                    const e = cons.get(key) ?? { level, message, count: 0, lastSeen: 0 };
+                    e.count++;
+                    e.lastSeen = seq;
+                    cons.set(key, e);
+                }
+                else if (ev.type === 'event' && ev.method === 'pageError') {
+                    const err = ev.params?.error?.error ?? ev.params?.error ?? {};
+                    const message = clean(`${err.name ?? 'Error'}: ${err.message ?? ''}`, 300);
+                    const key = `error\u0000${message}`;
+                    const e = cons.get(key) ?? { level: 'error', message, count: 0, lastSeen: 0 };
+                    e.count++;
+                    e.lastSeen = seq;
+                    cons.set(key, e);
+                }
+                else if (ev.type === 'resource-snapshot' && ev.snapshot?.request) {
+                    const raw = Number(ev.snapshot.response?.status ?? -1);
+                    const status = Number.isInteger(raw) && raw >= -1 && raw < 1000 ? raw : -1;
+                    const failed = status >= 400 || status <= 0 || Boolean(ev.snapshot.response?._failureText);
+                    if (!failed)
+                        continue;
+                    let path = String(ev.snapshot.request.url ?? '');
+                    try {
+                        path = new URL(path).pathname;
+                    }
+                    catch {
+                        path = stripUrl(path);
+                    }
+                    const method = clean(ev.snapshot.request.method ?? 'GET', MAX_METHOD);
+                    path = clean(path, MAX_PATH);
+                    const key = `${method} ${path} ${status}`;
+                    const e = net.get(key) ?? { method, path, status, count: 0, lastSeen: 0 };
+                    e.count++;
+                    e.lastSeen = seq;
+                    net.set(key, e);
+                }
+            }
+        }
+    }
+    return { console: [...cons.values()], network: [...net.values()] };
+}
+// --- packet ------------------------------------------------------------------------------------
+function shellQuote(a) {
+    return /^[A-Za-z0-9_\/.,:=@%+-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`;
+}
+export function rerunCommand(argv) {
+    return clean(['attested', ...argv].map(shellQuote).join(' '), MAX_RERUN);
+}
+function lineOf(t, file, stack) {
+    if (typeof t.line === 'number')
+        return Number.isInteger(t.line) && t.line >= 0 && t.line < 1e9 ? t.line : null;
+    if (!file)
+        return null;
+    for (const f of stack) {
+        const m = f.includes(file) ? /:(\d{1,9}):\d+\)?$/.exec(f) : null;
+        if (m)
+            return Number(m[1]);
+    }
+    return null;
+}
+// Attachments with a string path; anything else in an untrusted CTRF report is ignored.
+function attachmentsOf(t) {
+    return Array.isArray(t.attachments) ? t.attachments.filter((a) => typeof a?.path === 'string' && a.path !== '') : [];
+}
+export function buildPacket(ctrf, artifacts, cwd, rerun) {
+    const tests = (ctrf.results.tests ?? []).filter((t) => t.status === 'failed');
+    const byPath = new Map(artifacts.map((a) => [a.path, a]));
+    const rel = (p) => relPath(cwd, isAbsolute(p) ? p : resolve(cwd, p));
+    // Attachment paths are absolute on the machine that ran the tests. When the packet is built elsewhere (the sign job,
+    // from a downloaded results directory), match them to artifacts by suffix and infer that machine's project root.
+    const lookup = (p) => byPath.get(rel(p)) ?? artifacts.find((a) => p.split('\\').join('/').endsWith('/' + a.path));
+    let srcRoot = cwd;
+    find: for (const t of tests) {
+        for (const a of attachmentsOf(t)) {
+            if (!byPath.has(rel(a.path))) {
+                const art = lookup(a.path);
+                if (art)
+                    srcRoot = a.path.slice(0, a.path.length - art.path.length - 1);
+            }
+            break find;
+        }
+    }
+    const traces = [];
+    const groups = new Map();
+    for (const t of tests) {
+        const raw = String(t.trace ?? t.message ?? '').replace(ANSI, '');
+        const stack = raw.split('\n').map((l) => l.trim()).filter((l) => l.startsWith('at ')).slice(0, MAX_FRAMES)
+            .map((f) => clean(f.split(srcRoot + '/').join(''), MAX_FRAME));
+        const message = clean(t.message ?? '', MAX_MESSAGE, true);
+        const file = typeof t.filePath === 'string' && t.filePath ? clean(relative(srcRoot, t.filePath).split('\\').join('/'), MAX_PATH) : null;
+        const evidence = [];
+        for (const a of attachmentsOf(t)) {
+            const art = lookup(a.path);
+            if (!art || !['trace', 'video', 'screenshot'].includes(art.kind))
+                continue;
+            if (evidence.length < MAX_EVIDENCE)
+                evidence.push({ kind: art.kind, path: clean(art.path, MAX_PATH), sha256: art.sha256 });
+            if (art.kind === 'trace' && existsSync(resolve(cwd, art.path)))
+                traces.push(resolve(cwd, art.path));
+        }
+        const name = clean(testNameOf(t), MAX_NAME);
+        // Identical failures (same file, line, and message) collapse into one entry with a count.
+        const key = `${file}\u0000${lineOf(t, file, stack)}\u0000${message}`;
+        const g = groups.get(key);
+        if (g) {
+            g.count++;
+            continue;
+        }
+        groups.set(key, { name, file, line: lineOf(t, file, stack), message, stack, count: 1, evidence });
+    }
+    const { console: cons, network } = readTraces([...new Set(traces)]);
+    const byRecent = (xs) => xs.sort((a, b) => b.lastSeen - a.lastSeen).map(({ lastSeen, ...rest }) => rest);
+    const packet = {
+        tool: TOOL_NAME,
+        result: 'FAILED',
+        failingTests: [...groups.values()].sort((a, b) => a.name.localeCompare(b.name)),
+        console: byRecent(cons),
+        network: byRecent(network),
+        rerun: clean(rerun, MAX_RERUN),
+        truncated: false,
+    };
+    return capPacket(packet);
+}
+export function serializePacket(p) {
+    return JSON.stringify(p, null, 2) + '\n';
+}
+// Enforce the 12 KB cap: cut stacks to 5 frames, then drop from the end of the longest list
+// (tests are alphabetical, console and network most recent first), recording what was cut.
+export function capPacket(p) {
+    if (Buffer.byteLength(serializePacket(p)) <= PACKET_MAX_BYTES)
+        return p;
+    const cut = { tests: 0, console: 0, network: 0, frames: false };
+    p.truncated = cut;
+    for (const t of p.failingTests)
+        if (t.stack.length > 5) {
+            t.stack = t.stack.slice(0, 5);
+            cut.frames = true;
+        }
+    while (Buffer.byteLength(serializePacket(p)) > PACKET_MAX_BYTES) {
+        const lists = [['tests', p.failingTests], ['console', p.console], ['network', p.network]];
+        const [name, list] = [...lists].sort((a, b) => b[1].length - a[1].length)[0];
+        if (list.length === 0)
+            break;
+        list.pop();
+        cut[name]++;
+    }
+    // Every remaining field is bounded above, so this only trims the rerun command if a caller passed an unbounded one.
+    if (Buffer.byteLength(serializePacket(p)) > PACKET_MAX_BYTES)
+        p.rerun = clip(p.rerun, 200);
+    return p;
+}

package/dist/receipt.js

@@ -0,0 +1,61 @@
+import { PREDICATE_TYPE, STATEMENT_TYPE, SUBJECT_NAME, TOOL_NAME, TOOL_VERSION } from './constants.js';
+import { clean } from './redact.js';
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// Why `ctrf` cannot be judged, or null when it can. `results` must be an object with a `tests` array whose entries all
+// carry a string name and status, and `summary`, when present, must be an object. An empty `tests` array is valid.
+export function validateCtrf(ctrf) {
+    if (!isObject(ctrf) || !isObject(ctrf.results))
+        return 'missing "results"';
+    const { tests, summary } = ctrf.results;
+    if (!Array.isArray(tests))
+        return '"results.tests" is not an array';
+    const bad = tests.findIndex((t) => !isObject(t) || typeof t.name !== 'string' || typeof t.status !== 'string');
+    if (bad >= 0)
+        return `"results.tests[${bad}]" has no string name and status`;
+    if (summary !== undefined && !isObject(summary))
+        return '"results.summary" is not an object';
+    return null;
+}
+export function testNameOf(t) {
+    const prefix = t.suite ?? t.filePath;
+    return prefix ? `${prefix} > ${t.name}` : t.name;
+}
+// Test names in the receipt are signed and public with the repository: redacted and bounded like the packet's.
+const MAX_TEST_NAME = 300;
+const nameOf = (t) => clean(testNameOf(t), MAX_TEST_NAME);
+export function testResultFromCtrf(ctrf, configuration, url) {
+    const tests = Array.isArray(ctrf.results.tests) ? ctrf.results.tests.filter((t) => t && typeof t === 'object') : [];
+    // A passed test that CTRF marks flaky (passed on a retry) is warned, not passed.
+    const flaky = (t) => t.status === 'passed' && t.flaky === true;
+    const passedTests = tests.filter((t) => t.status === 'passed' && !flaky(t)).map(nameOf);
+    // CTRF's statuses are passed, failed, skipped, pending and other. Anything else (a reporter's own "timedOut" or
+    // "interrupted", or garbage) is counted as a failure rather than waved through as a warning.
+    const known = new Set(['passed', 'failed', 'skipped', 'pending', 'other']);
+    const failedTests = tests.filter((t) => t.status === 'failed' || !known.has(t.status)).map(nameOf);
+    // CTRF has no "warned" status; flaky/other/skipped/pending land here so nothing is silently dropped.
+    const warnedTests = tests.filter((t) => known.has(t.status) && t.status !== 'failed' && (t.status !== 'passed' || flaky(t)))
+        .map((t) => `${nameOf(t)} [${flaky(t) ? 'flaky' : clean(t.status, 20)}]`);
+    const summary = ctrf.results.summary ?? {};
+    const summaryFlaky = typeof summary.flaky === 'number' && summary.flaky > 0;
+    // FAILED if either the summary or any individual test reports a failure. A summary failed count that is present but
+    // not the number 0 counts as a failure, so a malformed summary cannot hide one.
+    // A run in which no test passed (an empty report, a crashed reporter, everything skipped) is not evidence that
+    // anything works, so it is FAILED, not PASSED or WARNED.
+    const failed = failedTests.length > 0 || (summary.failed !== undefined && summary.failed !== 0) || tests.every((t) => t.status !== 'passed');
+    const result = failed ? 'FAILED' : warnedTests.length > 0 || summaryFlaky ? 'WARNED' : 'PASSED';
+    const tr = { result, configuration, passedTests, warnedTests, failedTests };
+    if (url)
+        tr.url = url;
+    return tr;
+}
+export function buildReceipt(subjectSha256, predicate) {
+    return {
+        _type: STATEMENT_TYPE,
+        subject: [{ name: SUBJECT_NAME, digest: { sha256: subjectSha256 } }],
+        predicateType: PREDICATE_TYPE,
+        predicate,
+    };
+}
+export function toolInfo() {
+    return { name: TOOL_NAME, version: TOOL_VERSION };
+}

package/dist/redact.js

@@ -0,0 +1,48 @@
+// Redaction and bounds for every string that leaves the machine in a receipt, packet, or check summary.
+// Kept separate from packet.ts so receipt.ts can use it without an import cycle.
+export const ANSI = /\u001b\[[0-9;?]*[ -\/]*[@-~]/g;
+const SECRET_PATTERNS = [
+    // PEM / OpenSSH private keys, including a block cut off before its END line.
+    [/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g, '[REDACTED PRIVATE KEY]'],
+    // Credentials in any URL's userinfo (postgres://u:pw@, redis://:pw@, https://u:pw@), before the email pattern sees them.
+    [/\b([a-z][a-z0-9+.-]*:\/\/)[^\s\/@"'<>]*:[^\s\/@"'<>]*@/gi, '$1[REDACTED]@'],
+    // Webhook URLs whose path is the secret.
+    [/\bhttps?:\/\/(?:hooks\.slack\.com\/services|(?:discord|discordapp)\.com\/api\/webhooks)\/[^\s"'<>)\]]+/gi, '[REDACTED WEBHOOK]'],
+    [/\b(set-cookie|cookie)(\s*:\s*)[^\r\n]+/gi, '$1$2[REDACTED]'],
+    [/\b(bearer|basic|token)\s+[A-Za-z0-9\-._~+\/]{8,}=*/gi, '$1 [REDACTED]'],
+    [/\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|sk-[A-Za-z0-9_-]{16,}|[sr]k_(?:live|test)_[A-Za-z0-9]{10,}|(?:AKIA|ASIA)[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{35}|npm_[A-Za-z0-9]{36}|glpat-[A-Za-z0-9_-]{20,}|eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,})\b/g, '[REDACTED]'],
+    [/\b([A-Za-z0-9_-]*(?:key|token|secret|password|passwd|pwd|auth|session|signature|credential)[A-Za-z0-9_-]*)(["']?\s*[=:]\s*["']?)(?!(?:bearer|basic|token)\s|\[REDACTED)[^\s"'&,;)}\]]+/gi, '$1$2[REDACTED]'],
+    [/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '[EMAIL]'],
+];
+// Control characters (newlines included) would let an untrusted string start a new log line, and with it a GitHub
+// Actions workflow command such as ::add-mask:: or ::warning::. Every bounded string is one line.
+const CONTROL = /[\u0000-\u001f\u007f]+/g;
+// The one exception: a failure message keeps its newlines (an expected/received diff), because it is only ever
+// serialized as JSON, never printed to a log.
+const CONTROL_EXCEPT_NEWLINE = /[\u0000-\u0009\u000b-\u001f\u007f]+/g;
+const URL_RE = /\b(https?|wss?):\/\/[^\s"'<>)\]]+/gi;
+// Drop the query string and fragment of a URL.
+export function stripUrl(u) {
+    return u.replace(/[?#].*$/, '');
+}
+// Strip ANSI, URL queries and fragments, and anything shaped like a secret or an email.
+export function redact(text) {
+    let out = text.replace(ANSI, '');
+    // Private keys span lines, so they go before URL stripping and the line-bounded patterns.
+    out = out.replace(SECRET_PATTERNS[0][0], SECRET_PATTERNS[0][1]).replace(URL_RE, (u) => stripUrl(u));
+    for (const [re, rep] of SECRET_PATTERNS.slice(1))
+        out = out.replace(re, rep);
+    return out;
+}
+export function clip(text, max) {
+    return text.length > max ? `${text.slice(0, max)}… [${text.length - max} chars cut]` : text;
+}
+// Redact, then clip: the bounded form of an untrusted string. A huge input is cut to a little over `max` before the
+// patterns run, so their cost stays bounded; everything past `max` is dropped either way.
+export function clean(text, max, keepNewlines = false) {
+    const s = String(text ?? '');
+    const line = (t) => t.replace(keepNewlines ? CONTROL_EXCEPT_NEWLINE : CONTROL, ' ');
+    if (s.length <= max + 256)
+        return clip(line(redact(s)), max);
+    return `${line(redact(s.slice(0, max + 256))).slice(0, max)}… [${s.length - max} chars cut]`;
+}

package/dist/run.js

@@ -0,0 +1,110 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { DEFAULTS } from './constants.js';
+import { assemble, writeReceipt } from './assemble.js';
+import { clean, stripUrl } from './redact.js';
+import { rerunCommand } from './packet.js';
+import { AttestedError, gitDirty, gitHead, gitRef, info, readEvent, relPath } from './util.js';
+export function defaultRunOptions() {
+    return {
+        command: [],
+        ctrf: DEFAULTS.ctrf,
+        outputDir: DEFAULTS.outputDir,
+        receipt: DEFAULTS.receipt,
+        predicate: DEFAULTS.predicate,
+        testResultPredicate: DEFAULTS.testResultPredicate,
+        config: null,
+        expectSha: null,
+        allowDirty: false,
+        targetUrl: null,
+        healthPath: DEFAULTS.healthPath,
+        packet: DEFAULTS.packet,
+        argv: [],
+    };
+}
+// A target URL as written into the receipt: no credentials, query, or fragment; redacted and bounded.
+export function publicUrl(u) {
+    return clean(stripUrl(u).replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/i, '$1'), 300);
+}
+// Probe <url><healthPath> and require a `sha` field equal to expectedSha. Any failure is fatal:
+// a receipt must not claim tests ran against a deployment it cannot identify.
+async function probeTarget(url, healthPath, expectedSha) {
+    // A path only: `new URL('https://other.host/x', url)` would send the probe to another host.
+    if (!healthPath.startsWith('/') || healthPath.startsWith('//'))
+        throw new AttestedError(`attested: --health-path must be a path starting with "/", got ${clean(healthPath, 200)}`);
+    const target = new URL(healthPath, url).toString();
+    let res;
+    let text;
+    try {
+        res = await fetch(target, { signal: AbortSignal.timeout(5000) });
+        text = await res.text();
+    }
+    catch (err) {
+        throw new AttestedError(`attested run: target ${target} is unreachable (${err.message}); refusing to run tests`);
+    }
+    if (!res.ok)
+        throw new AttestedError(`attested run: target ${target} returned HTTP ${res.status}; refusing to run tests`);
+    let body = text;
+    try {
+        body = JSON.parse(text);
+    }
+    catch { /* keep text */ }
+    const buildSha = typeof body === 'object' && body !== null && typeof body.sha === 'string'
+        ? (body.sha) : null;
+    if (!buildSha)
+        throw new AttestedError(`attested run: target ${target} did not report a build sha (expected JSON with a "sha" field); refusing to run tests`);
+    if (buildSha !== expectedSha) {
+        throw new AttestedError(`attested run: target ${target} is built from ${buildSha}, expected ${expectedSha}; refusing to run tests`);
+    }
+    // Allowlisted fields only: the health body can carry anything, so it is never copied into the receipt.
+    return { buildSha, url: publicUrl(url), health: { probed: publicUrl(target), status: res.status } };
+}
+export async function run(opts) {
+    const cwd = process.cwd();
+    if (opts.command.length === 0)
+        throw new AttestedError('attested run: no test command given (use `attested run -- <command>`)');
+    // Fail-closed checks happen before any test runs.
+    const head = gitHead(cwd);
+    if (opts.expectSha) {
+        if (!head)
+            throw new AttestedError('attested run: --expect-sha given but HEAD could not be resolved');
+        if (head !== opts.expectSha)
+            throw new AttestedError(`attested run: HEAD is ${head}, expected ${opts.expectSha}; refusing to run tests`);
+    }
+    const dirty = gitDirty(cwd);
+    if (dirty && !opts.allowDirty) {
+        throw new AttestedError('attested run: working tree is dirty; commit or pass --allow-dirty');
+    }
+    // --target-url is fail-closed: the deployment must report the sha we are about to test.
+    let target = { buildSha: null, url: null };
+    if (opts.targetUrl) {
+        const expected = opts.expectSha ?? head;
+        if (!expected)
+            throw new AttestedError('attested run: --target-url needs --expect-sha or a git HEAD to compare the build sha against');
+        target = await probeTarget(opts.targetUrl, opts.healthPath, expected);
+        info(`target ${opts.targetUrl} reports build ${target.buildSha}`);
+    }
+    const ctrfPath = resolve(cwd, opts.ctrf);
+    rmSync(ctrfPath, { force: true });
+    mkdirSync(dirname(ctrfPath), { recursive: true });
+    info(`running: ${opts.command.join(' ')}`);
+    const started = new Date().toISOString();
+    const child = spawnSync(opts.command[0], opts.command.slice(1), { stdio: 'inherit', cwd, env: process.env });
+    const exitCode = child.status ?? 1;
+    info(`test command exited with ${exitCode}`);
+    const a = assemble(cwd, { ctrf: opts.ctrf, outputDir: opts.outputDir, config: opts.config, rerun: rerunCommand(opts.argv), who: 'attested run' });
+    const packet = resolve(cwd, opts.packet);
+    writeReceipt(a, {
+        receipt: resolve(cwd, opts.receipt),
+        predicate: resolve(cwd, opts.predicate),
+        testResultPredicate: resolve(cwd, opts.testResultPredicate),
+        packet,
+        packetArtifactPath: relPath(cwd, packet),
+    }, {
+        source: { commit: head, headCommit: readEvent()?.pull_request?.head?.sha ?? null, dirty, ref: gitRef(cwd) },
+        target,
+        createdAt: started,
+    });
+    return exitCode;
+}