@praxso/attested 0.0.0-stage → 0.1.1

package/dist/util.js

@@ -0,0 +1,214 @@
+import { createHash } from 'node:crypto';
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, extname, sep } from 'node:path';
+import { execFileSync } from 'node:child_process';
+export class AttestedError extends Error {
+}
+// Largest evidence file (trace, video, screenshot, report) that is hashed into a receipt.
+export const MAX_EVIDENCE_BYTES = 512 * 1024 * 1024;
+// Opens a regular file without following a symlink in its last component.
+function openFile(path, what = 'file') {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (err) {
+        if (err.code === 'ELOOP')
+            throw new AttestedError(`attested: ${what} ${path} is a symlink; refusing to read it`);
+        throw err;
+    }
+    if (!fstatSync(fd).isFile()) {
+        closeSync(fd);
+        throw new AttestedError(`attested: ${what} ${path} is not a regular file; refusing to read it`);
+    }
+    return fd;
+}
+// Writes an output file without following a symlink: a committed `attested/receipt.json -> ../elsewhere` (or a
+// symlinked output directory) would otherwise make a run overwrite a file outside the project. The data goes to a
+// fresh temp file in the same directory, then rename() replaces the target itself, never what a link points at.
+export function writeOutput(path, data) {
+    const dir = dirname(path);
+    if (isLink(dir))
+        throw new AttestedError(`attested: output directory ${dir} is a symlink; refusing to write through it`);
+    if (isLink(path))
+        throw new AttestedError(`attested: output ${path} is a symlink; refusing to write through it`);
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(tmp, data, { flag: 'wx' });
+        renameSync(tmp, path);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+function isLink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+// Hashes in chunks, so a large evidence file is never held in memory; refuses files over `max` bytes.
+export function sha256File(path, max = MAX_EVIDENCE_BYTES) {
+    const fd = openFile(path);
+    try {
+        const size = fstatSync(fd).size;
+        if (size > max)
+            throw new AttestedError(`attested: ${path} is ${size} bytes, over the ${max}-byte limit for evidence files`);
+        const hash = createHash('sha256');
+        const chunk = Buffer.alloc(1024 * 1024);
+        let bytes = 0;
+        for (let n; (n = readSync(fd, chunk, 0, chunk.length, null)) > 0;) {
+            bytes += n;
+            if (bytes > max)
+                throw new AttestedError(`attested: ${path} grew past the ${max}-byte limit for evidence files while hashing`);
+            hash.update(chunk.subarray(0, n));
+        }
+        return { sha256: hash.digest('hex'), bytes };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+// `path` (a file or directory under `root`) must not be a symlink and must resolve inside `root`, including through
+// symlinked parent directories. Returns false when it does not exist; throws when it escapes.
+export function checkInside(root, path, what) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch {
+        return false;
+    }
+    if (st.isSymbolicLink())
+        throw new AttestedError(`attested: ${what} ${path} is a symlink; refusing to read it`);
+    const rel = relative(realpathSync(root), realpathSync(path));
+    if (rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel))
+        throw new AttestedError(`attested: ${what} ${path} resolves outside ${root}; refusing to read it`);
+    return true;
+}
+// Reads `path` (under `root`) through one descriptor: opened first, then checked with checkInside and required to be the
+// same file the path names now, and read with `max` enforced on the bytes actually read. What is checked, read, and
+// hashed is one object, even if the path is replaced or the file grows meanwhile. Returns null when it does not exist.
+// `afterOpen` is a test seam for changing the file between opening and validation.
+export function readInside(root, path, max, what, afterOpen) {
+    let fd;
+    try {
+        fd = openFile(path, what);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    try {
+        afterOpen?.();
+        if (!checkInside(root, path, what))
+            throw new AttestedError(`attested: ${what} ${path} was removed while being read; refusing to read it`);
+        const st = fstatSync(fd);
+        const now = lstatSync(path);
+        if (st.dev !== now.dev || st.ino !== now.ino)
+            throw new AttestedError(`attested: ${what} ${path} was replaced while being read; refusing to read it`);
+        const chunks = [];
+        const chunk = Buffer.alloc(1024 * 1024);
+        let bytes = 0;
+        for (let n; (n = readSync(fd, chunk, 0, chunk.length, null)) > 0;) {
+            bytes += n;
+            if (bytes > max)
+                throw new AttestedError(`attested: ${what} ${path} is over the ${max}-byte limit`);
+            chunks.push(Buffer.from(chunk.subarray(0, n)));
+        }
+        return Buffer.concat(chunks);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function walk(dir) {
+    let out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries.sort()) {
+        const p = join(dir, name);
+        // lstat, not stat: a symlink in a results directory must not pull in files from outside it.
+        const st = lstatSync(p);
+        if (st.isDirectory())
+            out = out.concat(walk(p));
+        else if (st.isFile())
+            out.push(p);
+    }
+    return out;
+}
+export function classify(path) {
+    const ext = extname(path).toLowerCase();
+    if (ext === '.zip')
+        return 'trace';
+    if (ext === '.webm' || ext === '.mp4')
+        return 'video';
+    if (ext === '.png' || ext === '.jpg' || ext === '.jpeg')
+        return 'screenshot';
+    return 'report';
+}
+export function relPath(root, p) {
+    return relative(root, p).split('\\').join('/');
+}
+export function git(args, cwd) {
+    try {
+        return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function gitHead(cwd) {
+    return git(['rev-parse', 'HEAD'], cwd);
+}
+export function gitDirty(cwd) {
+    const out = git(['status', '--porcelain', '--untracked-files=normal'], cwd);
+    return out === null ? false : out.length > 0;
+}
+export function gitRef(cwd) {
+    if (process.env.GITHUB_REF)
+        return process.env.GITHUB_REF;
+    const ref = git(['symbolic-ref', '-q', 'HEAD'], cwd);
+    return ref || null;
+}
+export function inActions() {
+    return process.env.GITHUB_ACTIONS === 'true';
+}
+export function runUrl() {
+    const { GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID, GITHUB_RUN_ATTEMPT } = process.env;
+    if (!GITHUB_SERVER_URL || !GITHUB_REPOSITORY || !GITHUB_RUN_ID)
+        return null;
+    const attempt = GITHUB_RUN_ATTEMPT ? `/attempts/${GITHUB_RUN_ATTEMPT}` : '';
+    return `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}${attempt}`;
+}
+export function warn(msg) {
+    process.stderr.write(`attested: warning: ${msg}\n`);
+}
+export function info(msg) {
+    process.stderr.write(`attested: ${msg}\n`);
+}
+// The webhook payload of the current workflow run, or null outside Actions.
+export function readEvent() {
+    const path = process.env.GITHUB_EVENT_PATH;
+    if (!path || !existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+// `owner/repo/.github/workflows/x.yml` from GITHUB_WORKFLOW_REF, the form `gh attestation verify --signer-workflow` takes.
+export function signerWorkflow() {
+    const ref = process.env.GITHUB_WORKFLOW_REF;
+    return ref ? ref.split('@')[0] : null;
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@praxso/attested",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Signed, verifiable test receipts for agent-authored pull requests: wraps Playwright or any CTRF test run into an in-toto receipt signed with Sigstore via GitHub artifact attestations.",
+  "keywords": [
+    "attestation",
+    "in-toto",
+    "sigstore",
+    "slsa",
+    "ctrf",
+    "playwright",
+    "github-actions",
+    "provenance",
+    "ai-agents",
+    "coding-agents",
+    "test-results",
+    "supply-chain"
+  ],
+  "homepage": "https://github.com/Praxso/attested#readme",
+  "bugs": {
+    "url": "https://github.com/Praxso/attested/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Praxso/attested.git",
+    "directory": "packages/cli"
+  },
+  "license": "Apache-2.0",
+  "author": "Praxso",
+  "type": "module",
+  "bin": {
+    "attested": "./bin/attested.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs"
+  }
 }