knodin 0.5.0

package/dist/src/release-attestation.js

@@ -0,0 +1,533 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { canonicalizeUpdateMetadata } from "./update-trust.js";
+export const RELEASE_CHANNELS = [
+    "public-npm",
+    "docusign-artifactory",
+    "github-saas",
+    "homebrew",
+    "ghes",
+];
+const SHA256 = /^[a-f0-9]{64}$/;
+const SHA512 = /^[a-f0-9]{128}$/;
+const COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SAFE_FILE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,255}$/;
+const REPOSITORY = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}$/;
+const RUN_ID = /^\d{1,32}$/;
+const CYCLONEDX_SPEC_VERSION = /^1\.[4-6]$/;
+const MAX_RELEASE_ARTIFACT_BYTES = 512 * 1_024 * 1_024;
+const MAX_RELEASE_EVIDENCE_BYTES = 16 * 1_024 * 1_024;
+const RELEASE_CHANNEL_HOSTS = {
+    "public-npm": "registry.npmjs.org",
+    "docusign-artifactory": "artifactory-corp.docusignhq.com",
+    "github-saas": "github.com",
+    homebrew: "github.com",
+    ghes: "github.docusignhq.com",
+};
+function fail(message) {
+    throw new Error(`invalid release attestation: ${message}`);
+}
+function record(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail(`${label} must be an object`);
+    return value;
+}
+function onlyKeys(value, allowed, label) {
+    const permitted = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!permitted.has(key))
+            fail(`${label} contains unsupported field ${key}`);
+    }
+}
+function text(value, label, maximum = 1_024) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum)
+        fail(`${label} must be a non-empty bounded string`);
+    return value;
+}
+function integer(value, label, maximum = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > maximum)
+        fail(`${label} must be a bounded non-negative integer`);
+    return value;
+}
+function instant(value, label) {
+    const candidate = text(value, label, 64);
+    const parsed = new Date(candidate);
+    if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== candidate)
+        fail(`${label} must be a canonical UTC instant`);
+    return candidate;
+}
+function digest(algorithm, bytes) {
+    return createHash(algorithm).update(bytes).digest("hex");
+}
+function digestMatches(expected, actual) {
+    const left = Buffer.from(expected, "hex");
+    const right = Buffer.from(actual, "hex");
+    return left.byteLength === right.byteLength && timingSafeEqual(left, right);
+}
+function boundedBytes(bytes, label, maximum) {
+    if (!(bytes instanceof Uint8Array))
+        fail(`${label} must be bytes`);
+    if (bytes.byteLength === 0 || bytes.byteLength > maximum)
+        fail(`${label} exceeds its non-empty byte budget`);
+}
+function jsonRecord(bytes, label) {
+    try {
+        return record(JSON.parse(Buffer.from(bytes).toString("utf-8")), label);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("invalid release attestation:"))
+            throw error;
+        return fail(`${label} must be valid JSON`);
+    }
+}
+function safeEvidencePath(value, label) {
+    if (!SAFE_FILE.test(value) || value === "." || value === "..")
+        fail(`${label} must be a safe file name`);
+    return value;
+}
+function httpsUrl(value, label) {
+    const candidate = text(value, label, 2_048);
+    let parsed;
+    try {
+        parsed = new URL(candidate);
+    }
+    catch {
+        return fail(`${label} must be an HTTPS URL`);
+    }
+    if (parsed.protocol !== "https:" ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        parsed.hash !== "" ||
+        parsed.port !== "")
+        fail(`${label} must be a canonical HTTPS URL without credentials, a fragment, or a port`);
+    if (parsed.search !== "")
+        fail(`${label} must not contain a query that could disclose credentials`);
+    return parsed.toString();
+}
+function validateIdentity(verification, build, label) {
+    const value = record(verification, `${label} verification`);
+    onlyKeys(value, ["verified", "attestationId", "attestationUrl", "issuer", "identity", "verifiedAt"], `${label} verification`);
+    if (typeof verification.verified !== "boolean")
+        fail(`${label} verified must be boolean`);
+    const attestationId = text(verification.attestationId, `${label} attestation ID`, 256);
+    const attestationUrl = new URL(httpsUrl(verification.attestationUrl, `${label} attestation URL`));
+    const expectedPath = `/${build.repository}/attestations/${encodeURIComponent(attestationId)}`;
+    if (attestationUrl.hostname !== "github.com" || attestationUrl.pathname !== expectedPath)
+        fail(`${label} attestation URL does not match its repository and attestation ID`);
+    if (verification.issuer !== "https://token.actions.githubusercontent.com")
+        fail(`${label} has an unapproved signature issuer`);
+    const expectedIdentity = `https://github.com/${build.repository}/${build.workflow}@${build.workflowRef}`;
+    if (verification.identity !== expectedIdentity)
+        fail(`${label} signature identity does not match build`);
+    instant(verification.verifiedAt, `${label} verification time`);
+}
+function validateBuild(build, tag) {
+    const value = record(build, "build");
+    onlyKeys(value, ["repository", "workflow", "workflowRef", "runId", "runAttempt"], "build");
+    if (!REPOSITORY.test(build.repository))
+        fail("build repository must be an owner/name slug");
+    if (!/^\.github\/workflows\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.ya?ml$/.test(build.workflow))
+        fail("build workflow must be a repository workflow path");
+    if (build.workflowRef !== `refs/tags/${tag}`)
+        fail("build workflow ref must equal the release tag");
+    if (!RUN_ID.test(build.runId))
+        fail("build run ID must be decimal");
+    integer(build.runAttempt, "build run attempt", 1_000);
+    if (build.runAttempt < 1)
+        fail("build run attempt must be positive");
+    return { ...build };
+}
+function artifactEvidence(name, bytes) {
+    safeEvidencePath(name, "artifact name");
+    boundedBytes(bytes, "artifact", MAX_RELEASE_ARTIFACT_BYTES);
+    const sha512 = digest("sha512", bytes);
+    return {
+        name,
+        length: bytes.byteLength,
+        sha256: digest("sha256", bytes),
+        sha512,
+        npmIntegrity: `sha512-${Buffer.from(sha512, "hex").toString("base64")}`,
+    };
+}
+function channelEvidence(observation, artifact, version, sourceCommit) {
+    if (!observation?.artifactBytes) {
+        return { evidence: { status: "missing" }, failure: "channel evidence is missing" };
+    }
+    boundedBytes(observation.artifactBytes, `${observation.channel} artifact`, MAX_RELEASE_ARTIFACT_BYTES);
+    const location = httpsUrl(observation.location, `${observation.channel} location`);
+    if (new URL(location).hostname !== RELEASE_CHANNEL_HOSTS[observation.channel])
+        fail(`${observation.channel} location must use its approved host`);
+    const observed = {
+        status: "verified",
+        artifactLength: observation.artifactBytes.byteLength,
+        artifactSha256: digest("sha256", observation.artifactBytes),
+        version: text(observation.version, `${observation.channel} version`, 128),
+        sourceCommit: text(observation.sourceCommit, `${observation.channel} source commit`, 64),
+        publishedAt: instant(observation.publishedAt, `${observation.channel} publication time`),
+        location,
+    };
+    if (!SEMVER.test(observed.version ?? ""))
+        fail(`${observation.channel} channel version must be a semantic version`);
+    if (!COMMIT.test(observed.sourceCommit ?? ""))
+        fail(`${observation.channel} channel source commit must be a full lowercase digest`);
+    if (observed.artifactLength !== artifact.length ||
+        !digestMatches(observed.artifactSha256 ?? "", artifact.sha256)) {
+        observed.status = "mismatch";
+        return { evidence: observed, failure: "artifact digest or length differs" };
+    }
+    if (observed.version !== version) {
+        observed.status = "mismatch";
+        return { evidence: observed, failure: "version differs" };
+    }
+    if (observed.sourceCommit !== sourceCommit) {
+        observed.status = "mismatch";
+        return { evidence: observed, failure: "source commit differs" };
+    }
+    return { evidence: observed };
+}
+function derivedStatus(channels, provenanceVerified, sbomVerified, artifact, version, sourceCommit) {
+    const failures = [];
+    if (!provenanceVerified)
+        failures.push("build provenance signature is not verified");
+    if (!sbomVerified)
+        failures.push("SBOM signature is not verified");
+    let mismatch = false;
+    for (const channel of RELEASE_CHANNELS) {
+        const evidence = channels[channel];
+        if (evidence.status === "missing")
+            failures.push(`${channel}: channel evidence is missing`);
+        if (evidence.status === "mismatch") {
+            mismatch = true;
+            let reason = "channel evidence is malformed";
+            if (evidence.artifactLength !== artifact.length ||
+                !evidence.artifactSha256 ||
+                !digestMatches(evidence.artifactSha256, artifact.sha256))
+                reason = "artifact digest or length differs";
+            else if (evidence.version !== version)
+                reason = "version differs";
+            else if (evidence.sourceCommit !== sourceCommit)
+                reason = "source commit differs";
+            failures.push(`${channel}: ${reason}`);
+        }
+    }
+    return {
+        status: releaseStatus(mismatch, failures),
+        failures,
+    };
+}
+function releaseStatus(mismatch, failures) {
+    if (mismatch)
+        return "quarantined";
+    if (failures.length === 0)
+        return "verified";
+    return "incomplete";
+}
+function validateBuildEvidenceInput(input) {
+    if (!SEMVER.test(input.version))
+        fail("version must be a semantic version");
+    if (input.tag !== `v${input.version}`)
+        fail("tag must equal v plus the semantic version");
+    if (!COMMIT.test(input.sourceCommit))
+        fail("source commit must be a full lowercase digest");
+    const generatedAt = instant(input.generatedAt, "generation time");
+    const build = validateBuild(input.build, input.tag);
+    const expectedArtifactName = `knodin-${input.version}.tgz`;
+    if (input.artifact.name !== expectedArtifactName)
+        fail(`artifact name must be ${expectedArtifactName}`);
+    const artifact = artifactEvidence(input.artifact.name, input.artifact.bytes);
+    boundedBytes(input.provenance.bytes, "build provenance", MAX_RELEASE_EVIDENCE_BYTES);
+    jsonRecord(input.provenance.bytes, "build provenance");
+    safeEvidencePath(input.provenance.path, "build provenance path");
+    validateIdentity(input.provenance.verification, build, "build provenance");
+    boundedBytes(input.sbom.bytes, "SBOM", MAX_RELEASE_EVIDENCE_BYTES);
+    const sbomJson = jsonRecord(input.sbom.bytes, "SBOM");
+    if (sbomJson.bomFormat !== "CycloneDX")
+        fail("SBOM must use CycloneDX");
+    const specVersion = text(sbomJson.specVersion, "SBOM specification version", 16);
+    if (!CYCLONEDX_SPEC_VERSION.test(specVersion))
+        fail("SBOM must use a supported CycloneDX specification version");
+    safeEvidencePath(input.sbom.path, "SBOM path");
+    boundedBytes(input.sbom.attestationBytes, "SBOM attestation", MAX_RELEASE_EVIDENCE_BYTES);
+    jsonRecord(input.sbom.attestationBytes, "SBOM attestation");
+    safeEvidencePath(input.sbom.attestationPath, "SBOM attestation path");
+    validateIdentity(input.sbom.verification, build, "SBOM");
+    return { generatedAt, build, artifact, specVersion };
+}
+function collectChannelEvidence(input, artifact) {
+    const observations = new Map();
+    for (const observation of input.channels) {
+        if (!RELEASE_CHANNELS.includes(observation.channel))
+            fail(`unknown release channel ${observation.channel}`);
+        if (observations.has(observation.channel))
+            fail(`duplicate release channel ${observation.channel}`);
+        observations.set(observation.channel, observation);
+    }
+    const channels = {};
+    const failures = new Map();
+    for (const channel of RELEASE_CHANNELS) {
+        const outcome = channelEvidence(observations.get(channel), artifact, input.version, input.sourceCommit);
+        channels[channel] = outcome.evidence;
+        if (outcome.failure)
+            failures.set(channel, outcome.failure);
+    }
+    return { channels, failures };
+}
+function validateRollbackInput(input) {
+    if (!SEMVER.test(input.rollback.version) || input.rollback.version === input.version)
+        fail("rollback version must be a different semantic version");
+    safeEvidencePath(input.rollback.targetPath, "rollback target path");
+    if (!SHA256.test(input.rollback.artifactSha256))
+        fail("rollback digest must be lowercase SHA-256");
+}
+export function buildReleaseAttestation(input) {
+    const { generatedAt, build, artifact, specVersion } = validateBuildEvidenceInput(input);
+    const { channels, failures: channelFailures } = collectChannelEvidence(input, artifact);
+    validateRollbackInput(input);
+    const derived = derivedStatus(channels, input.provenance.verification.verified, input.sbom.verification.verified, artifact, input.version, input.sourceCommit);
+    for (const [channel, reason] of channelFailures) {
+        const generic = derived.failures.findIndex((failure) => failure.startsWith(`${channel}:`));
+        if (generic >= 0)
+            derived.failures[generic] = `${channel}: ${reason}`;
+    }
+    return {
+        schemaVersion: 1,
+        status: derived.status,
+        version: input.version,
+        tag: input.tag,
+        sourceCommit: input.sourceCommit,
+        generatedAt,
+        build,
+        artifact,
+        provenance: {
+            path: input.provenance.path,
+            length: input.provenance.bytes.byteLength,
+            sha256: digest("sha256", input.provenance.bytes),
+            verification: { ...input.provenance.verification },
+        },
+        sbom: {
+            format: "CycloneDX",
+            specVersion,
+            path: input.sbom.path,
+            length: input.sbom.bytes.byteLength,
+            sha256: digest("sha256", input.sbom.bytes),
+            attestationPath: input.sbom.attestationPath,
+            attestationLength: input.sbom.attestationBytes.byteLength,
+            attestationSha256: digest("sha256", input.sbom.attestationBytes),
+            verification: { ...input.sbom.verification },
+        },
+        channels,
+        rollback: { ...input.rollback },
+        failures: derived.failures,
+    };
+}
+export function canonicalizeReleaseAttestation(value) {
+    return canonicalizeUpdateMetadata(value);
+}
+function validateDigest(value, label, expression) {
+    const candidate = text(value, label, expression === SHA512 ? 128 : 64);
+    if (!expression.test(candidate))
+        fail(`${label} must be a lowercase digest`);
+    return candidate;
+}
+function validateArtifact(value) {
+    const artifact = record(value, "artifact");
+    onlyKeys(artifact, ["name", "length", "sha256", "sha512", "npmIntegrity"], "artifact");
+    const sha512 = validateDigest(artifact.sha512, "artifact SHA-512", SHA512);
+    const npmIntegrity = text(artifact.npmIntegrity, "npm integrity", 256);
+    const expectedIntegrity = `sha512-${Buffer.from(sha512, "hex").toString("base64")}`;
+    if (npmIntegrity !== expectedIntegrity)
+        fail("npm integrity does not match artifact SHA-512");
+    return {
+        name: safeEvidencePath(text(artifact.name, "artifact name", 256), "artifact name"),
+        length: integer(artifact.length, "artifact length", MAX_RELEASE_ARTIFACT_BYTES),
+        sha256: validateDigest(artifact.sha256, "artifact SHA-256", SHA256),
+        sha512,
+        npmIntegrity,
+    };
+}
+function validateChannelEvidence(value, channel, artifact, version, sourceCommit) {
+    const evidence = record(value, `${channel} channel`);
+    onlyKeys(evidence, [
+        "status",
+        "artifactLength",
+        "artifactSha256",
+        "version",
+        "sourceCommit",
+        "publishedAt",
+        "location",
+    ], `${channel} channel`);
+    if (evidence.status === "missing") {
+        if (Object.keys(evidence).length !== 1)
+            fail(`${channel} missing evidence contains observations`);
+        return { status: "missing" };
+    }
+    if (evidence.status !== "verified" && evidence.status !== "mismatch")
+        fail(`${channel} has an invalid status`);
+    const location = httpsUrl(evidence.location, `${channel} location`);
+    if (new URL(location).hostname !== RELEASE_CHANNEL_HOSTS[channel])
+        fail(`${channel} location must use its approved host`);
+    const result = {
+        status: evidence.status,
+        artifactLength: integer(evidence.artifactLength, `${channel} artifact length`, MAX_RELEASE_ARTIFACT_BYTES),
+        artifactSha256: validateDigest(evidence.artifactSha256, `${channel} artifact SHA-256`, SHA256),
+        version: text(evidence.version, `${channel} version`, 128),
+        sourceCommit: text(evidence.sourceCommit, `${channel} source commit`, 64),
+        publishedAt: instant(evidence.publishedAt, `${channel} publication time`),
+        location,
+    };
+    if (!SEMVER.test(result.version ?? ""))
+        fail(`${channel} channel version must be semantic`);
+    if (!COMMIT.test(result.sourceCommit ?? ""))
+        fail(`${channel} channel source commit must be a full lowercase digest`);
+    const shouldMatch = result.artifactLength === artifact.length &&
+        digestMatches(result.artifactSha256 ?? "", artifact.sha256) &&
+        result.version === version &&
+        result.sourceCommit === sourceCommit;
+    if ((result.status === "verified") !== shouldMatch)
+        fail(`${channel} status does not match its artifact, version, and source evidence`);
+    return result;
+}
+function validateVerification(value, build, label) {
+    const verification = record(value, `${label} verification`);
+    validateIdentity(verification, build, label);
+    return { ...verification };
+}
+function validateAttestationHeader(attestation) {
+    if (attestation.schemaVersion !== 1)
+        fail("schema version must be 1");
+    const version = text(attestation.version, "version", 128);
+    if (!SEMVER.test(version))
+        fail("version must be a semantic version");
+    const tag = text(attestation.tag, "tag", 129);
+    if (tag !== `v${version}`)
+        fail("tag must equal v plus the semantic version");
+    const sourceCommit = text(attestation.sourceCommit, "source commit", 64);
+    if (!COMMIT.test(sourceCommit))
+        fail("source commit must be a full lowercase digest");
+    const generatedAt = instant(attestation.generatedAt, "generation time");
+    const build = validateBuild(record(attestation.build, "build"), tag);
+    const artifact = validateArtifact(attestation.artifact);
+    if (artifact.name !== `knodin-${version}.tgz`)
+        fail("artifact name does not match version");
+    return { version, tag, sourceCommit, generatedAt, build, artifact };
+}
+export function verifyReleaseAttestation(value, bytes) {
+    const attestation = record(value, "release attestation");
+    onlyKeys(attestation, [
+        "schemaVersion",
+        "status",
+        "version",
+        "tag",
+        "sourceCommit",
+        "generatedAt",
+        "build",
+        "artifact",
+        "provenance",
+        "sbom",
+        "channels",
+        "rollback",
+        "failures",
+    ], "release attestation");
+    const { version, tag, sourceCommit, generatedAt, build, artifact } = validateAttestationHeader(attestation);
+    const provenanceRecord = record(attestation.provenance, "provenance");
+    onlyKeys(provenanceRecord, ["path", "length", "sha256", "verification"], "provenance");
+    const provenance = {
+        path: safeEvidencePath(text(provenanceRecord.path, "provenance path", 256), "provenance path"),
+        length: integer(provenanceRecord.length, "provenance length", MAX_RELEASE_EVIDENCE_BYTES),
+        sha256: validateDigest(provenanceRecord.sha256, "provenance SHA-256", SHA256),
+        verification: validateVerification(provenanceRecord.verification, build, "build provenance"),
+    };
+    const sbomRecord = record(attestation.sbom, "SBOM");
+    onlyKeys(sbomRecord, [
+        "format",
+        "specVersion",
+        "path",
+        "length",
+        "sha256",
+        "attestationPath",
+        "attestationLength",
+        "attestationSha256",
+        "verification",
+    ], "SBOM");
+    if (sbomRecord.format !== "CycloneDX")
+        fail("SBOM format must be CycloneDX");
+    const sbom = {
+        format: "CycloneDX",
+        specVersion: text(sbomRecord.specVersion, "SBOM specification version", 16),
+        path: safeEvidencePath(text(sbomRecord.path, "SBOM path", 256), "SBOM path"),
+        length: integer(sbomRecord.length, "SBOM length", MAX_RELEASE_EVIDENCE_BYTES),
+        sha256: validateDigest(sbomRecord.sha256, "SBOM SHA-256", SHA256),
+        attestationPath: safeEvidencePath(text(sbomRecord.attestationPath, "SBOM attestation path", 256), "SBOM attestation path"),
+        attestationLength: integer(sbomRecord.attestationLength, "SBOM attestation length", MAX_RELEASE_EVIDENCE_BYTES),
+        attestationSha256: validateDigest(sbomRecord.attestationSha256, "SBOM attestation SHA-256", SHA256),
+        verification: validateVerification(sbomRecord.verification, build, "SBOM"),
+    };
+    if (!CYCLONEDX_SPEC_VERSION.test(sbom.specVersion))
+        fail("SBOM must use a supported CycloneDX specification version");
+    boundedBytes(bytes.artifact, "artifact", MAX_RELEASE_ARTIFACT_BYTES);
+    boundedBytes(bytes.provenance, "provenance", MAX_RELEASE_EVIDENCE_BYTES);
+    boundedBytes(bytes.sbom, "SBOM", MAX_RELEASE_EVIDENCE_BYTES);
+    boundedBytes(bytes.sbomAttestation, "SBOM attestation", MAX_RELEASE_EVIDENCE_BYTES);
+    if (bytes.artifact.byteLength !== artifact.length ||
+        !digestMatches(digest("sha256", bytes.artifact), artifact.sha256) ||
+        !digestMatches(digest("sha512", bytes.artifact), artifact.sha512))
+        fail("artifact digest or length mismatch");
+    if (bytes.provenance.byteLength !== provenance.length ||
+        !digestMatches(digest("sha256", bytes.provenance), provenance.sha256))
+        fail("provenance digest or length mismatch");
+    if (bytes.sbom.byteLength !== sbom.length ||
+        !digestMatches(digest("sha256", bytes.sbom), sbom.sha256))
+        fail("SBOM digest or length mismatch");
+    if (bytes.sbomAttestation.byteLength !== sbom.attestationLength ||
+        !digestMatches(digest("sha256", bytes.sbomAttestation), sbom.attestationSha256))
+        fail("SBOM attestation digest or length mismatch");
+    const sbomJson = jsonRecord(bytes.sbom, "SBOM");
+    if (sbomJson.bomFormat !== sbom.format || sbomJson.specVersion !== sbom.specVersion)
+        fail("SBOM format metadata does not match its bytes");
+    jsonRecord(bytes.provenance, "provenance");
+    jsonRecord(bytes.sbomAttestation, "SBOM attestation");
+    const channelRecord = record(attestation.channels, "channels");
+    onlyKeys(channelRecord, RELEASE_CHANNELS, "channels");
+    const channels = {};
+    for (const channel of RELEASE_CHANNELS) {
+        if (!(channel in channelRecord))
+            fail(`channels is missing ${channel}`);
+        channels[channel] = validateChannelEvidence(channelRecord[channel], channel, artifact, version, sourceCommit);
+    }
+    const rollbackRecord = record(attestation.rollback, "rollback");
+    onlyKeys(rollbackRecord, ["version", "targetPath", "artifactSha256"], "rollback");
+    const rollback = {
+        version: text(rollbackRecord.version, "rollback version", 128),
+        targetPath: safeEvidencePath(text(rollbackRecord.targetPath, "rollback target path", 256), "rollback target path"),
+        artifactSha256: validateDigest(rollbackRecord.artifactSha256, "rollback artifact SHA-256", SHA256),
+    };
+    if (!SEMVER.test(rollback.version) || rollback.version === version)
+        fail("rollback version must be a different semantic version");
+    if (!Array.isArray(attestation.failures) || attestation.failures.length > 100)
+        fail("failures must be a bounded array");
+    const failures = attestation.failures.map((failure, index) => text(failure, `failure ${index}`, 512));
+    const derived = derivedStatus(channels, provenance.verification.verified, sbom.verification.verified, artifact, version, sourceCommit);
+    const serializedStatus = attestation.status;
+    if (serializedStatus !== derived.status)
+        fail("attestation status does not match its evidence");
+    // Failure details are descriptive evidence. Require the same set so a producer
+    // cannot conceal an incomplete or quarantined channel behind a truthful status.
+    if (failures.length !== derived.failures.length ||
+        failures.some((failure, index) => failure !== derived.failures[index]))
+        fail("attestation failures do not match its evidence");
+    return {
+        schemaVersion: 1,
+        status: derived.status,
+        version,
+        tag,
+        sourceCommit,
+        generatedAt,
+        build,
+        artifact,
+        provenance,
+        sbom,
+        channels,
+        rollback,
+        failures,
+    };
+}

package/dist/src/repair-progress-worker.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { clearLine as clearTerminalLine, moveCursor as moveTerminalCursor, cursorTo as moveTerminalCursorTo, } from "node:readline";
+import ora from "ora";
+import { normalizeTerminalDimension } from "./init-progress.js";
+import { formatRepairProgress } from "./repair-progress.js";
+const terminalEnabled = process.stderr.isTTY === true || process.env.RECKON_FORCE_PROGRESS_TTY === "1";
+const progressStream = {
+    isTTY: terminalEnabled,
+    columns: normalizeTerminalDimension(process.stderr.columns, 80),
+    rows: normalizeTerminalDimension(process.stderr.rows, 24),
+    write: process.stderr.write.bind(process.stderr),
+    cursorTo: (x, y, callback) => moveTerminalCursorTo(process.stderr, x, y, callback),
+    moveCursor: (dx, dy, callback) => moveTerminalCursor(process.stderr, dx, dy, callback),
+    clearLine: (direction, callback) => clearTerminalLine(process.stderr, direction, callback),
+    once: process.stderr.once.bind(process.stderr),
+    removeListener: process.stderr.removeListener.bind(process.stderr),
+};
+const spinner = ora({
+    text: "[repair:starting] Opening local graph database (0s elapsed)",
+    stream: progressStream,
+    isEnabled: terminalEnabled,
+    discardStdin: false,
+});
+let buffer = "";
+let stopped = false;
+let exiting = false;
+let startedAt = 0;
+let current = "[repair:starting] Opening local graph database";
+let clock;
+let deferredStop;
+const MINIMUM_VISIBLE_MS = 150;
+function refreshText() {
+    const elapsed = Math.max(0, Math.floor((Date.now() - startedAt) / 1_000));
+    spinner.text = `${current} (${elapsed}s elapsed)`;
+}
+function start() {
+    if (spinner.isSpinning)
+        return;
+    startedAt = Date.now();
+    refreshText();
+    spinner.start();
+    // A healthy graph can finish before Ora's first interval tick. Render once
+    // synchronously so even fast repairs provide real interactive feedback.
+    spinner.render();
+    clock = setInterval(refreshText, 250);
+}
+function finishStop(exitAfter) {
+    if (!stopped) {
+        stopped = true;
+        if (deferredStop)
+            clearTimeout(deferredStop);
+        if (clock)
+            clearInterval(clock);
+        spinner.stop();
+    }
+    if (exitAfter && !exiting) {
+        exiting = true;
+        const exitTimer = setTimeout(() => process.exit(0), 100);
+        process.stderr.write("\r\x1b[2K", () => {
+            clearTimeout(exitTimer);
+            process.exit(0);
+        });
+    }
+}
+function stop(exitAfter = false) {
+    const remaining = MINIMUM_VISIBLE_MS - (Date.now() - startedAt);
+    if (exitAfter && spinner.isSpinning && remaining > 0) {
+        if (!deferredStop)
+            deferredStop = setTimeout(() => {
+                deferredStop = undefined;
+                finishStop(true);
+            }, remaining);
+        return;
+    }
+    finishStop(exitAfter);
+}
+function handle(line) {
+    if (!line)
+        return;
+    const message = JSON.parse(line);
+    if (message.type === "start")
+        start();
+    else if (message.type === "progress") {
+        if (!spinner.isSpinning)
+            start();
+        current = formatRepairProgress(message.event);
+        refreshText();
+    }
+    else
+        stop(true);
+}
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    for (;;) {
+        const newline = buffer.indexOf("\n");
+        if (newline < 0)
+            break;
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        try {
+            handle(line);
+        }
+        catch {
+            // Progress transport is observational; malformed input cannot affect repair.
+        }
+    }
+});
+process.stdin.on("end", () => {
+    if (buffer) {
+        try {
+            handle(buffer);
+        }
+        catch { }
+    }
+    stop(true);
+});
+process.on("SIGTERM", () => {
+    stop();
+    process.exit(0);
+});