@praxso/attested 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @praxso/attested
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Signed, verifiable test receipts for agent-authored pull requests.
+
+`attested` wraps an ordinary Playwright run, or any test run that writes a [CTRF](https://ctrf.io) report, and turns it into an [in-toto](https://github.com/in-toto/attestation) receipt: the result, the failing tests, the exact commit, and the sha256 of every trace, video, and screenshot. In GitHub Actions the receipt is signed with Sigstore keyless signing through `actions/attest`, and anyone can check it with `gh attestation verify`.
+
+No custom runner, no hosted service, no images posted anywhere. Evidence stays in the workflow artifact of the run that produced it; only digests travel in the receipt.
+
+## Install
+
+```bash
+npm install --save-dev @praxso/attested
+```
+
+Requires Node 22 or newer.
+
+## Use
+
+```bash
+npx attested run -- npx playwright test
+```
+
+```bash
+npx attested attest
+```
+
+`run` executes your test command, requires a CTRF report, and writes `attested/receipt.json`. On a red run it also writes `attested/packet.json`, a redacted failure packet under 12 KB that a coding agent can act on. `attest` prepares the predicate for the `actions/attest` step in your workflow. `check` posts a text-only GitHub check run.
+
+Workflow setup, the `attested verify` required check, and the organization ruleset that makes it unforgeable are documented in the repository: https://github.com/Praxso/attested
+
+## Agents
+
+The MCP server is a separate package, [`@praxso/attested-mcp`](https://www.npmjs.com/package/@praxso/attested-mcp).
+
+## License
+
+Apache-2.0

package/bin/attested.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Committed launcher so the bin shim exists before `pnpm build` runs.
+// pnpm does not create a bin shim for a workspace package whose bin target is
+// missing at install time, and dist/ only exists after the build.
+import('../dist/index.js').catch((err) => {
+  process.stderr.write(`attested: not built (${err.message}); run \`pnpm build\` first\n`);
+  process.exit(1);
+});

package/dist/assemble.js

@@ -0,0 +1,112 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, rmSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { buildPacket, serializePacket } from './packet.js';
+import { buildReceipt, testResultFromCtrf, toolInfo, validateCtrf } from './receipt.js';
+import { clean } from './redact.js';
+import { AttestedError, checkInside, classify, info, readInside, relPath, runUrl, sha256File, walk, writeOutput } from './util.js';
+// Largest ctrf.json that is parsed. CTRF for tens of thousands of tests is a few MB.
+export const MAX_CTRF_BYTES = 32 * 1024 * 1024;
+const SUMMARY_FIELDS = ['tests', 'passed', 'failed', 'skipped', 'pending', 'other', 'flaky', 'start', 'stop', 'duration'];
+// The CTRF metadata copied into the receipt: allowlisted fields only, strings redacted and bounded, counts numeric.
+// The ctrf.json subject itself is never rewritten; only these copies are.
+export function ctrfMeta(ctrf) {
+    const str = (v, max) => (typeof v === 'string' ? clean(v, max) : null);
+    const t = ctrf.results.tool;
+    const tool = t && typeof t === 'object' ? { name: str(t.name, 100), version: str(t.version, 50) } : null;
+    const s = ctrf.results.summary;
+    let summary = null;
+    if (s && typeof s === 'object') {
+        summary = {};
+        for (const k of SUMMARY_FIELDS) {
+            const v = s[k];
+            if (typeof v === 'number' && Number.isFinite(v))
+                summary[k] = v;
+        }
+    }
+    return { specVersion: str(ctrf.specVersion, 32), tool, summary };
+}
+// Longest file path or configuration name written into the signed predicate.
+const MAX_PUBLIC_PATH = 1000;
+// A path as it is written into the signed, public predicate. Paths must stay exact so the evidence can be checked
+// against them, so a path that redaction would change (it looks like it holds a secret or an email) or that is too
+// long is refused rather than rewritten.
+export function publicPath(root, file, who) {
+    const path = relPath(root, file);
+    if (clean(path, MAX_PUBLIC_PATH) !== path)
+        throw new AttestedError(`${who}: refusing to publish the path ${clean(path, 200)}: it is over ${MAX_PUBLIC_PATH} characters or looks like it contains a secret or an email; rename it`);
+    return path;
+}
+// Everything the receipt says about the run, computed from files under `root` only: the CTRF report, the output dir,
+// and the test config. Used by `attested run` (root = the project) and by `attested attest --from-results`
+// (root = a downloaded results directory, which is treated strictly as data).
+export function assemble(root, o) {
+    const ctrfPath = resolve(root, o.ctrf);
+    if (!checkInside(root, ctrfPath, 'CTRF report'))
+        throw new AttestedError(`${o.who}: CTRF report not found at ${o.ctrf} (configure the CTRF reporter or pass --ctrf)`);
+    const size = statSync(ctrfPath).size;
+    if (size > MAX_CTRF_BYTES)
+        throw new AttestedError(`${o.who}: ${o.ctrf} is ${size} bytes, over the ${MAX_CTRF_BYTES}-byte limit for CTRF reports`);
+    // One descriptor: the bytes parsed are the bytes hashed into the subject, whatever happens to the path meanwhile.
+    const bytes = readInside(root, ctrfPath, MAX_CTRF_BYTES, 'CTRF report');
+    if (!bytes)
+        throw new AttestedError(`${o.who}: CTRF report not found at ${o.ctrf}`);
+    let ctrf;
+    try {
+        ctrf = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new AttestedError(`${o.who}: ${o.ctrf} is not valid JSON`);
+    }
+    const invalid = validateCtrf(ctrf);
+    if (invalid)
+        throw new AttestedError(`${o.who}: ${o.ctrf} is not a CTRF report (${invalid})`);
+    const subject = { sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length };
+    const artifacts = [{ path: publicPath(root, ctrfPath, o.who), ...subject, kind: 'report' }];
+    const outputDir = resolve(root, o.outputDir);
+    if (checkInside(root, outputDir, 'output directory')) {
+        for (const file of walk(outputDir))
+            artifacts.push({ path: publicPath(root, file, o.who), ...sha256File(file), kind: classify(file) });
+    }
+    const configuration = [];
+    const configPath = o.config ?? ['playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs'].find((p) => checkInside(root, resolve(root, p), 'test config')) ?? null;
+    if (configPath && checkInside(root, resolve(root, configPath), 'test config'))
+        configuration.push({ name: publicPath(root, resolve(root, configPath), o.who), digest: { sha256: sha256File(resolve(root, configPath)).sha256 } });
+    if (process.env.GITHUB_WORKFLOW_REF)
+        configuration.push({ name: clean(process.env.GITHUB_WORKFLOW_REF, MAX_PUBLIC_PATH), digest: { gitCommit: process.env.GITHUB_SHA ?? '' } });
+    const testResult = testResultFromCtrf(ctrf, configuration, runUrl());
+    const packet = testResult.result === 'FAILED' ? buildPacket(ctrf, artifacts, root, o.rerun) : null;
+    return { ctrf, subject, artifacts, testResult, packet };
+}
+// Write the packet (on red), the receipt, the predicate, and the in-toto Test Result predicate.
+export function writeReceipt(a, out, rest) {
+    const artifacts = [...a.artifacts];
+    rmSync(out.packet, { force: true });
+    if (a.packet) {
+        mkdirSync(dirname(out.packet), { recursive: true });
+        writeOutput(out.packet, serializePacket(a.packet));
+        // The packet's digest sits next to the evidence it points at.
+        artifacts.push({ path: out.packetArtifactPath, ...sha256File(out.packet), kind: 'packet' });
+        info(`failure packet: ${out.packetArtifactPath} (${a.packet.failingTests.length} failure groups${a.packet.truncated ? ', truncated' : ''})`);
+    }
+    const predicate = {
+        testResult: a.testResult,
+        source: rest.source,
+        target: rest.target,
+        artifacts,
+        tool: toolInfo(),
+        ctrf: ctrfMeta(a.ctrf),
+        createdAt: rest.createdAt,
+    };
+    const receipt = buildReceipt(a.subject.sha256, predicate);
+    mkdirSync(dirname(out.receipt), { recursive: true });
+    writeOutput(out.receipt, JSON.stringify(receipt, null, 2) + '\n');
+    writeOutput(out.predicate, JSON.stringify(predicate, null, 2) + '\n');
+    // Second, pure in-toto Test Result statement for interoperability.
+    writeOutput(out.testResultPredicate, JSON.stringify(a.testResult, null, 2) + '\n');
+    const tr = a.testResult;
+    info(`receipt: ${relPath(process.cwd(), out.receipt)} (${tr.result}, ${tr.passedTests.length} passed, ${tr.failedTests.length} failed, ${artifacts.length} artifacts)`);
+    if (tr.failedTests.length)
+        info(`failed: ${tr.failedTests.join('; ')}`);
+    return receipt;
+}

package/dist/attest.js

@@ -0,0 +1,94 @@
+import { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { assemble, writeReceipt } from './assemble.js';
+import { DEFAULTS, PREDICATE_TYPE, TEST_RESULT_PREDICATE_TYPE } from './constants.js';
+import { AttestedError, inActions, info, readEvent, relPath, sha256File, warn, writeOutput } from './util.js';
+export function defaultAttestOptions() {
+    return {
+        receipt: DEFAULTS.receipt, ctrf: DEFAULTS.ctrf, predicate: DEFAULTS.predicate, testResultPredicate: DEFAULTS.testResultPredicate,
+        fromResults: null, out: 'signed/attested', outputDir: DEFAULTS.outputDir, config: null, rerun: null,
+    };
+}
+function emitOutputs(subjectPath, sha256, predicatePath, testResultPath) {
+    setOutput('subject-path', subjectPath);
+    setOutput('subject-sha256', sha256);
+    setOutput('predicate-path', predicatePath);
+    setOutput('predicate-type', PREDICATE_TYPE);
+    setOutput('test-result-predicate-path', testResultPath);
+    setOutput('test-result-predicate-type', TEST_RESULT_PREDICATE_TYPE);
+    info(`prepared predicate for actions/attest: subject ctrf.json sha256:${sha256}, type ${PREDICATE_TYPE}`);
+}
+// The results directory (attested/ctrf.json, test-results/, the test config) was written by PR code and is only read
+// and hashed here. Everything about the source comes from the event context of this job, never from those files.
+export function attestFromResults(opts) {
+    const root = resolve(opts.fromResults);
+    if (!existsSync(root) && !isSymlink(root))
+        throw new AttestedError(`attested attest: results directory ${opts.fromResults} not found`);
+    if (isSymlink(root))
+        throw new AttestedError(`attested attest: results directory ${opts.fromResults} is a symlink; refusing to read it`);
+    if (!statSync(root).isDirectory())
+        throw new AttestedError(`attested attest: results directory ${opts.fromResults} is not a directory`);
+    const commit = process.env.GITHUB_SHA;
+    if (!commit)
+        throw new AttestedError('attested attest: --from-results needs GITHUB_SHA (the commit the test job checked out) from the workflow context');
+    const a = assemble(root, { ctrf: opts.ctrf, outputDir: opts.outputDir, config: opts.config, rerun: opts.rerun ?? 'see the attested run job', who: 'attested attest' });
+    const out = resolve(opts.out);
+    mkdirSync(out, { recursive: true });
+    const subjectPath = join(out, 'ctrf.json');
+    copyFileSync(resolve(root, opts.ctrf), subjectPath);
+    if (sha256File(subjectPath).sha256 !== a.subject.sha256)
+        throw new AttestedError('attested attest: ctrf.json changed while copying; refusing to attest');
+    const paths = { receipt: join(out, 'receipt.json'), predicate: join(out, 'predicate.json'), testResultPredicate: join(out, 'test-result.json'), packet: join(out, 'packet.json') };
+    writeReceipt(a, { ...paths, packetArtifactPath: relPath(dirname(out), paths.packet) }, {
+        source: { commit, headCommit: readEvent()?.pull_request?.head?.sha ?? null, dirty: null, ref: process.env.GITHUB_REF ?? null },
+        target: { buildSha: null, url: null },
+        createdAt: new Date().toISOString(),
+    });
+    if (!inActions())
+        warn('not running in GitHub Actions: receipt is UNSIGNED and no attestation was created.');
+    emitOutputs(subjectPath, a.subject.sha256, paths.predicate, paths.testResultPredicate);
+    return 0;
+}
+function isSymlink(p) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function setOutput(name, value) {
+    const file = process.env.GITHUB_OUTPUT;
+    if (file)
+        appendFileSync(file, `${name}=${value}\n`);
+    else
+        info(`output ${name}=${value}`);
+}
+export function attest(opts) {
+    if (opts.fromResults)
+        return attestFromResults(opts);
+    const cwd = process.cwd();
+    const receiptPath = resolve(cwd, opts.receipt);
+    const ctrfPath = resolve(cwd, opts.ctrf);
+    if (!existsSync(receiptPath))
+        throw new AttestedError(`attested attest: receipt not found at ${opts.receipt}; run \`attested run\` first`);
+    if (!existsSync(ctrfPath))
+        throw new AttestedError(`attested attest: CTRF report not found at ${opts.ctrf}`);
+    const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+    const actual = sha256File(ctrfPath).sha256;
+    const expected = receipt.subject[0]?.digest.sha256;
+    if (actual !== expected) {
+        throw new AttestedError(`attested attest: ${opts.ctrf} changed since \`attested run\` (sha256 ${actual} != ${expected}); refusing to attest`);
+    }
+    if (!inActions()) {
+        // The receipt carries no signed/unsigned claim; `gh attestation verify` is the only answer to that question.
+        warn('not running in GitHub Actions: receipt is UNSIGNED and no attestation was created. Push to GitHub to get a Sigstore-signed attestation.');
+        return 0;
+    }
+    // In Actions, signing is delegated to the actions/attest step that follows.
+    // The predicate file was written by `attested run`; we re-emit it from the receipt so the two cannot drift.
+    writeOutput(resolve(cwd, opts.predicate), JSON.stringify(receipt.predicate, null, 2) + '\n');
+    writeOutput(resolve(cwd, opts.testResultPredicate), JSON.stringify(receipt.predicate.testResult, null, 2) + '\n');
+    emitOutputs(ctrfPath, actual, resolve(cwd, opts.predicate), resolve(cwd, opts.testResultPredicate));
+    return 0;
+}

package/dist/check.js

@@ -0,0 +1,152 @@
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { DEFAULTS, PREDICATE_TYPE, TOOL_NAME } from './constants.js';
+import { AttestedError, info, readEvent, runUrl, signerWorkflow } from './util.js';
+export function defaultCheckOptions() {
+    return { receipt: DEFAULTS.receipt, packet: DEFAULTS.packet, artifactUrl: null, artifactName: null, evidenceName: null, attestationUrl: null };
+}
+// Selects the statement `attested verify` accepts from `gh attestation verify --format json`: the certificate names
+// this run and ref, and the predicate's commit or PR head is the head the check is attached to. Null (jq -e fails) when none.
+const STATEMENT_JQ = `[.[].verificationResult | select(.signature.certificate.sourceRepositoryRef == $ref and ((.signature.certificate.runInvocationURI // "") | test("/actions/runs/" + $run + "(/attempts/[0-9]+)?$"))) | .statement | select(.predicateType == "${PREDICATE_TYPE}" and (.predicate.source.commit == $head or .predicate.source.headCommit == $head))] | first`;
+const SUM_LINE = '"\\(.sha256)  \\(.path)"';
+function shellQuote(s) {
+    return /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+export function conclusionFor(result) {
+    if (result === 'PASSED')
+        return 'success';
+    if (result === 'FAILED')
+        return 'failure';
+    return 'neutral';
+}
+// The sha the check run is attached to: the PR head on pull_request (GITHUB_SHA is the synthetic merge commit there).
+export function checkHeadSha() {
+    const ev = readEvent();
+    return ev?.pull_request?.head?.sha ?? process.env.GITHUB_SHA ?? null;
+}
+// On a pull_request from a fork, GITHUB_TOKEN is read-only and cannot create check runs.
+export function isForkPullRequest() {
+    const ev = readEvent();
+    const head = ev?.pull_request?.head?.repo?.full_name;
+    const base = ev?.pull_request?.base?.repo?.full_name ?? process.env.GITHUB_REPOSITORY;
+    return Boolean(head && base && head !== base);
+}
+export function buildSummary(receipt, packet, opts) {
+    const p = receipt.predicate;
+    const tr = p.testResult;
+    const s = (p.ctrf.summary ?? {});
+    const repo = process.env.GITHUB_REPOSITORY ?? '<owner>/<repo>';
+    const signer = signerWorkflow() ?? `${repo}/.github/workflows/attested.yml`;
+    const digest = receipt.subject[0]?.digest.sha256 ?? '';
+    const lines = [];
+    const counts = `${s.tests ?? tr.passedTests.length + tr.failedTests.length + tr.warnedTests.length} tests: ${tr.passedTests.length} passed, ${tr.failedTests.length} failed, ${tr.warnedTests.length} other`;
+    const title = `${tr.result}: ${counts}`;
+    lines.push(`### ${TOOL_NAME}: ${tr.result}`, '', '| | |', '|---|---|');
+    lines.push(`| Verdict | **${tr.result}** |`);
+    const head = p.source.headCommit;
+    lines.push(`| Commit tested | \`${p.source.commit ?? 'unknown'}\`${head && head !== p.source.commit ? ` (PR head \`${head}\`)` : ''} |`);
+    lines.push(`| Target build | ${p.target.buildSha ? `\`${p.target.buildSha}\` at ${p.target.url}` : 'none (no --target-url)'} |`);
+    lines.push(`| Tests | ${counts} |`);
+    lines.push(`| Subject | \`ctrf.json\` sha256 \`${digest}\` |`);
+    lines.push(`| Evidence | ${opts.artifactUrl ? `[workflow artifact](${opts.artifactUrl})` : 'workflow artifact'} (traces, videos, screenshots; access follows this repository's visibility; never posted to the PR) |`);
+    if (opts.attestationUrl)
+        lines.push(`| Attestation | ${opts.attestationUrl} |`);
+    const url = runUrl();
+    if (url)
+        lines.push(`| Run | ${url} |`);
+    lines.push('', 'Verify this receipt yourself:', '', '```bash');
+    const runId = process.env.GITHUB_RUN_ID;
+    const ref = process.env.GITHUB_REF;
+    const headSha = checkHeadSha();
+    if (runId && opts.artifactName)
+        lines.push(`gh run download ${runId} --repo ${repo} --name ${opts.artifactName} --dir attested-receipt`);
+    const verify = `gh attestation verify attested-receipt/attested/ctrf.json --repo ${repo} --predicate-type ${PREDICATE_TYPE} --signer-workflow ${signer}`;
+    // The accepted statement is the one `attested verify` would accept: signed in this run, on this ref, for this head.
+    // Every later check reads the statement, never the downloaded receipt.json, which is unsigned.
+    const pinned = Boolean(runId && ref && headSha);
+    if (pinned) {
+        lines.push(`${verify} --format json > attested-verify.json`);
+        lines.push(`jq -e --arg run ${runId} --arg ref ${shellQuote(ref)} --arg head ${headSha} '${STATEMENT_JQ}' attested-verify.json > attested-statement.json`);
+    }
+    else {
+        lines.push(verify);
+    }
+    lines.push('```');
+    // The evidence travels in its own artifact. Its name defaults to the bundled workflow's (results-<sha> beside
+    // attested-<sha>), as the signer workflow above defaults to the bundled attested.yml.
+    const evidence = opts.evidenceName ?? (opts.artifactName?.startsWith('attested-') ? `results-${opts.artifactName.slice('attested-'.length)}` : null);
+    if (pinned && evidence) {
+        lines.push('', 'Get the evidence (screenshots, videos, traces) and check each file against the fingerprints in the signed statement:', '', '```bash');
+        lines.push(`gh run download ${runId} --repo ${repo} --name ${evidence} --dir attested-evidence`);
+        // The sign job writes the failure packet into the receipt artifact, so packet entries are checked there.
+        lines.push(`(cd attested-evidence && jq -r '.predicate.artifacts[] | select(.kind != "packet") | ${SUM_LINE}' ../attested-statement.json | shasum -a 256 -c)`);
+        if (p.artifacts?.some((a) => a.kind === 'packet')) {
+            lines.push(`(cd attested-receipt && jq -r '.predicate.artifacts[] | select(.kind == "packet") | ${SUM_LINE}' ../attested-statement.json | shasum -a 256 -c)`);
+        }
+        lines.push('```');
+        lines.push('', "Artifacts follow this repository's artifact retention (90 days by default); the receipt's digests and signature outlast them.");
+    }
+    if (tr.failedTests.length && packet) {
+        lines.push('', 'Failure packet (`attested/packet.json`):', '', '```json', packet.trimEnd(), '```');
+    }
+    else if (tr.failedTests.length) {
+        lines.push('', 'Failed tests:', '', ...tr.failedTests.map((t) => `- ${t}`));
+    }
+    return { title, summary: lines.join('\n') + '\n' };
+}
+function toLogAndSummary(summary) {
+    process.stdout.write(summary);
+    const file = process.env.GITHUB_STEP_SUMMARY;
+    if (file)
+        appendFileSync(file, summary);
+}
+export async function check(opts) {
+    const cwd = process.cwd();
+    const receiptPath = resolve(cwd, opts.receipt);
+    if (!existsSync(receiptPath))
+        throw new AttestedError(`attested check: receipt not found at ${opts.receipt}; run \`attested run\` first`);
+    const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+    const packetPath = resolve(cwd, opts.packet);
+    const packet = existsSync(packetPath) ? readFileSync(packetPath, 'utf8') : null;
+    const conclusion = conclusionFor(receipt.predicate.testResult.result);
+    const { title, summary } = buildSummary(receipt, packet, opts);
+    const token = process.env.GITHUB_TOKEN;
+    const repo = process.env.GITHUB_REPOSITORY;
+    const headSha = checkHeadSha();
+    if (isForkPullRequest()) {
+        toLogAndSummary(summary);
+        process.stdout.write(`::notice title=attested check::forked pull request: GITHUB_TOKEN is read-only, so no check run was created; the summary above is the same content (conclusion ${conclusion}).\n`);
+        return 0;
+    }
+    if (!token || !repo || !headSha) {
+        toLogAndSummary(summary);
+        info(`no GITHUB_TOKEN/GITHUB_REPOSITORY/head sha: printed the check summary instead of creating a check run (conclusion ${conclusion})`);
+        return 0;
+    }
+    const api = process.env.GITHUB_API_URL ?? 'https://api.github.com';
+    const body = {
+        name: TOOL_NAME,
+        head_sha: headSha,
+        status: 'completed',
+        conclusion,
+        details_url: runUrl() ?? undefined,
+        // Text only. The `images` field is never used: evidence stays in the workflow artifact, as visible as the repository's Actions artifacts (PixelLeak rule).
+        output: { title, summary },
+    };
+    const res = await fetch(`${api}/repos/${repo}/check-runs`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (res.status === 403) {
+        toLogAndSummary(summary);
+        process.stdout.write(`::notice title=attested check::GITHUB_TOKEN cannot create check runs here (HTTP 403; add \`checks: write\`, or this is a fork); the summary above is the same content (conclusion ${conclusion}).\n`);
+        return 0;
+    }
+    if (!res.ok)
+        throw new AttestedError(`attested check: creating the check run failed: HTTP ${res.status} ${(await res.text()).slice(0, 300)}`);
+    const created = (await res.json());
+    toLogAndSummary(summary);
+    info(`check run "${TOOL_NAME}" (${conclusion}) on ${headSha}: ${created.html_url ?? ''}`);
+    return 0;
+}

package/dist/constants.js

@@ -0,0 +1,17 @@
+// Single place to rename the project or move the predicate URI.
+export const TOOL_NAME = 'attested';
+// Must equal packages/cli/package.json version; test/version.test.mjs enforces it.
+export const TOOL_VERSION = '0.1.1';
+export const PREDICATE_TYPE = 'https://praxso.ai/attested/v0.1';
+export const TEST_RESULT_PREDICATE_TYPE = 'https://in-toto.io/attestation/test-result/v0.1';
+export const STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
+export const SUBJECT_NAME = 'ctrf.json';
+export const DEFAULTS = {
+    ctrf: 'attested/ctrf.json',
+    outputDir: 'test-results',
+    receipt: 'attested/receipt.json',
+    predicate: 'attested/predicate.json',
+    testResultPredicate: 'attested/test-result.json',
+    packet: 'attested/packet.json',
+    healthPath: '/healthz',
+};