@cassiomc1/forgeloop 2.1.0 → 2.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -7
- package/completions/_forgeloop +6 -1
- package/completions/forgeloop.bash +11 -1
- package/completions/forgeloop.fish +40 -1
- package/docs/AGENT_PROTOCOL_SUMMARY.md +6 -1
- package/docs/CLI_REFERENCE.md +88 -3
- package/docs/CODE_ATTESTATION.md +7 -0
- package/docs/RELEASE_CHECKLIST.md +39 -6
- package/docs/TROUBLESHOOTING.md +8 -0
- package/package.json +1 -1
- package/src/cli.js +26 -0
- package/src/commands/assess.js +36 -0
- package/src/commands/evidence-export.js +17 -0
- package/src/commands/evidence-verify.js +36 -0
- package/src/commands/sync-pull.js +46 -0
- package/src/commands/sync-push.js +49 -0
- package/src/core/assessment/facts.js +146 -0
- package/src/core/assessment/plan.js +133 -0
- package/src/core/cli-command-definitions.js +70 -0
- package/src/core/command-executors.js +26 -3
- package/src/core/error-codes.js +52 -0
- package/src/core/evidence/bundle-format.js +72 -0
- package/src/core/evidence/export.js +179 -0
- package/src/core/evidence/markdown.js +40 -0
- package/src/core/evidence/verify.js +179 -0
- package/src/core/integration-invocation-policy.js +4 -2
- package/src/core/sync/remote.js +124 -0
- package/src/core/sync/snapshot.js +129 -0
package/src/core/error-codes.js
CHANGED
|
@@ -11,6 +11,12 @@ import {
|
|
|
11
11
|
E_VERIFICATION_ISOLATION_UNAVAILABLE,
|
|
12
12
|
} from "./verification-execution.js";
|
|
13
13
|
|
|
14
|
+
export const E_SYNC_CONFIG = "E_SYNC_CONFIG";
|
|
15
|
+
export const E_SYNC_UNAUTHORIZED = "E_SYNC_UNAUTHORIZED";
|
|
16
|
+
export const E_SYNC_CONFLICT = "E_SYNC_CONFLICT";
|
|
17
|
+
export const E_SYNC_REMOTE = "E_SYNC_REMOTE";
|
|
18
|
+
export const E_SYNC_SNAPSHOT_INVALID = "E_SYNC_SNAPSHOT_INVALID";
|
|
19
|
+
export const E_SYNC_TOO_LARGE = "E_SYNC_TOO_LARGE";
|
|
14
20
|
export const E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED = "E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED";
|
|
15
21
|
export const E_REPOSITORY_INDEX_ENGINE_MISSING = "E_REPOSITORY_INDEX_ENGINE_MISSING";
|
|
16
22
|
export const E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED = "E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED";
|
|
@@ -89,6 +95,8 @@ export const E_ATTESTATION_MANIFEST_STALE = "E_ATTESTATION_MANIFEST_STALE";
|
|
|
89
95
|
export const E_ATTESTATION_CONTENT_MISMATCH = "E_ATTESTATION_CONTENT_MISMATCH";
|
|
90
96
|
export const E_ATTESTATION_SCOPE_MISMATCH = "E_ATTESTATION_SCOPE_MISMATCH";
|
|
91
97
|
export const E_ATTESTATION_COVERAGE_GAP = "E_ATTESTATION_COVERAGE_GAP";
|
|
98
|
+
export const E_EVIDENCE_BUNDLE_INVALID = "E_EVIDENCE_BUNDLE_INVALID";
|
|
99
|
+
export const E_EVIDENCE_EXPORT_UNAVAILABLE = "E_EVIDENCE_EXPORT_UNAVAILABLE";
|
|
92
100
|
export const E_ATTESTATION_COVERAGE_CONFLICT = "E_ATTESTATION_COVERAGE_CONFLICT";
|
|
93
101
|
export const E_ATTESTATION_STATEMENT_MISSING = "E_ATTESTATION_STATEMENT_MISSING";
|
|
94
102
|
export const E_ATTESTATION_STATEMENT_INVALID = "E_ATTESTATION_STATEMENT_INVALID";
|
|
@@ -241,6 +249,8 @@ const EXTENSION_PUBLIC_ERROR_CODES = Object.freeze(Object.fromEntries([
|
|
|
241
249
|
E_ATTESTATION_CONTENT_MISMATCH,
|
|
242
250
|
E_ATTESTATION_SCOPE_MISMATCH,
|
|
243
251
|
E_ATTESTATION_COVERAGE_GAP,
|
|
252
|
+
E_EVIDENCE_BUNDLE_INVALID,
|
|
253
|
+
E_EVIDENCE_EXPORT_UNAVAILABLE,
|
|
244
254
|
E_ATTESTATION_COVERAGE_CONFLICT,
|
|
245
255
|
E_ATTESTATION_STATEMENT_MISSING,
|
|
246
256
|
E_ATTESTATION_STATEMENT_INVALID,
|
|
@@ -663,6 +673,39 @@ const REPOSITORY_INDEX_ERROR_METADATA = Object.freeze(Object.fromEntries([
|
|
|
663
673
|
safeResolution,
|
|
664
674
|
})])));
|
|
665
675
|
|
|
676
|
+
const CLOUD_SYNC_ERROR_METADATA = Object.freeze(Object.fromEntries([
|
|
677
|
+
[E_SYNC_CONFIG, [
|
|
678
|
+
"Cloud sync is missing FORGELOOP_SYNC_TOKEN or a FORGELOOP_SYNC_KEY of at least 16 characters, or --remote or --repo is invalid.",
|
|
679
|
+
"Set both environment variables and pass an https --remote and an owner/name --repo, or a GitHub git origin.",
|
|
680
|
+
]],
|
|
681
|
+
[E_SYNC_UNAUTHORIZED, [
|
|
682
|
+
"The sync remote rejected FORGELOOP_SYNC_TOKEN, or the token is not allowed for this repository.",
|
|
683
|
+
"Use a token whose SHA-256 hash the remote owner configured for this repository.",
|
|
684
|
+
]],
|
|
685
|
+
[E_SYNC_CONFLICT, [
|
|
686
|
+
"The remote snapshot changed since this machine last pushed or pulled, so the push was refused instead of overwriting it.",
|
|
687
|
+
"Run forgeloop sync-pull --writers-quiesced --replace-active to adopt the remote state, then continue and push again.",
|
|
688
|
+
]],
|
|
689
|
+
[E_SYNC_REMOTE, [
|
|
690
|
+
"The sync remote is unreachable, has no snapshot for this repository, or refused the request.",
|
|
691
|
+
"Check --remote and network access, push a first snapshot, or retry later.",
|
|
692
|
+
]],
|
|
693
|
+
[E_SYNC_SNAPSHOT_INVALID, [
|
|
694
|
+
"The remote snapshot could not be decrypted with FORGELOOP_SYNC_KEY, belongs to another repository, or its contents failed integrity checks.",
|
|
695
|
+
"Use the same FORGELOOP_SYNC_KEY as the pushing machine; never restore a snapshot that fails these checks.",
|
|
696
|
+
]],
|
|
697
|
+
[E_SYNC_TOO_LARGE, [
|
|
698
|
+
"The encrypted snapshot exceeds the 4 MiB sync limit.",
|
|
699
|
+
"Sync a project with less retained state; cloud sync does not split snapshots.",
|
|
700
|
+
]],
|
|
701
|
+
].map(([code, [meaning, safeResolution]]) => [code, Object.freeze({
|
|
702
|
+
code,
|
|
703
|
+
category: "cloud-sync",
|
|
704
|
+
classification: "PUBLIC_STABLE",
|
|
705
|
+
meaning,
|
|
706
|
+
safeResolution,
|
|
707
|
+
})])));
|
|
708
|
+
|
|
666
709
|
const PERSISTENT_TRANSPORT_ERROR_METADATA = Object.freeze(Object.fromEntries([
|
|
667
710
|
[E_PERSISTENT_TRANSPORT_FRAME_INVALID, [
|
|
668
711
|
"The local persistent-search byte stream did not contain a complete valid JSON frame.",
|
|
@@ -720,6 +763,7 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
|
|
|
720
763
|
...STRUCTURAL_QUALITY_ERROR_METADATA,
|
|
721
764
|
...ADVISORY_CONTEXT_AND_HANDOFF_ERROR_METADATA,
|
|
722
765
|
...REPOSITORY_INDEX_ERROR_METADATA,
|
|
766
|
+
...CLOUD_SYNC_ERROR_METADATA,
|
|
723
767
|
...PERSISTENT_TRANSPORT_ERROR_METADATA,
|
|
724
768
|
E_PREFLIGHT_NOT_READY: Object.freeze({
|
|
725
769
|
code: "E_PREFLIGHT_NOT_READY",
|
|
@@ -1754,6 +1798,8 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
|
|
|
1754
1798
|
E_ATTESTATION_CONTENT_MISMATCH,
|
|
1755
1799
|
E_ATTESTATION_SCOPE_MISMATCH,
|
|
1756
1800
|
E_ATTESTATION_COVERAGE_GAP,
|
|
1801
|
+
E_EVIDENCE_BUNDLE_INVALID,
|
|
1802
|
+
E_EVIDENCE_EXPORT_UNAVAILABLE,
|
|
1757
1803
|
E_ATTESTATION_COVERAGE_CONFLICT,
|
|
1758
1804
|
E_ATTESTATION_STATEMENT_MISSING,
|
|
1759
1805
|
E_ATTESTATION_STATEMENT_INVALID,
|
|
@@ -1854,6 +1900,12 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
|
|
|
1854
1900
|
E_BASELINE_RECORD_DURING_ACTIVE_TASK,
|
|
1855
1901
|
E_POLICY_INITIALIZATION_FAILED,
|
|
1856
1902
|
E_INIT_KIT_CONFLICT,
|
|
1903
|
+
E_SYNC_CONFIG,
|
|
1904
|
+
E_SYNC_UNAUTHORIZED,
|
|
1905
|
+
E_SYNC_CONFLICT,
|
|
1906
|
+
E_SYNC_REMOTE,
|
|
1907
|
+
E_SYNC_SNAPSHOT_INVALID,
|
|
1908
|
+
E_SYNC_TOO_LARGE,
|
|
1857
1909
|
E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED,
|
|
1858
1910
|
E_REPOSITORY_INDEX_ENGINE_MISSING,
|
|
1859
1911
|
E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED,
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { canonicalFingerprint } from "../artifacts.js";
|
|
3
|
+
import { E_EVIDENCE_BUNDLE_INVALID } from "../error-codes.js";
|
|
4
|
+
|
|
5
|
+
// Portable evidence bundle: what a completed task can prove to a verifier that
|
|
6
|
+
// has only the repository checkout. Signed content is the exact attestation
|
|
7
|
+
// statement text; everything else is either bound to it (the code manifest) or
|
|
8
|
+
// informational (the summary).
|
|
9
|
+
|
|
10
|
+
export const EVIDENCE_BUNDLE_SCHEMA_VERSION = 1;
|
|
11
|
+
export const EVIDENCE_BUNDLE_KIND = "forgeloop-evidence-bundle";
|
|
12
|
+
export const DEFAULT_EVIDENCE_DIRECTORY = ".forgeloop-evidence";
|
|
13
|
+
|
|
14
|
+
export const EVIDENCE_REDACTIONS = Object.freeze([
|
|
15
|
+
"absolute-paths",
|
|
16
|
+
"command-argv",
|
|
17
|
+
"command-output",
|
|
18
|
+
"environment",
|
|
19
|
+
"ledger-events",
|
|
20
|
+
]);
|
|
21
|
+
|
|
22
|
+
const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
|
|
23
|
+
|
|
24
|
+
export function evidenceError(code, message, details = {}) {
|
|
25
|
+
return Object.assign(new Error(message), { code, ...details });
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function assertEvidenceTaskId(taskId) {
|
|
29
|
+
if (typeof taskId !== "string" || !TASK_ID_PATTERN.test(taskId)) {
|
|
30
|
+
throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, `Invalid evidence task ID: ${taskId}`);
|
|
31
|
+
}
|
|
32
|
+
return taskId;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export function evidenceBundlePath(directory, taskId) {
|
|
36
|
+
return `${directory.replace(/\/+$/u, "")}/${assertEvidenceTaskId(taskId)}.json`;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export function evidenceBundleDigest(bundle) {
|
|
40
|
+
const { digest: _digest, ...body } = bundle;
|
|
41
|
+
return createHash("sha256").update(JSON.stringify(body)).digest("hex");
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export function sealEvidenceBundle(body) {
|
|
45
|
+
return { ...body, digest: evidenceBundleDigest(body) };
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function serializeEvidenceBundle(bundle) {
|
|
49
|
+
return `${JSON.stringify(bundle, null, 2)}\n`;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function requireField(condition, message) {
|
|
53
|
+
if (!condition) throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, message);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function parseEvidenceBundle(text, expectedTaskId = null) {
|
|
57
|
+
let bundle;
|
|
58
|
+
try { bundle = JSON.parse(text); } catch { throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, "Evidence bundle is not valid JSON"); }
|
|
59
|
+
requireField(bundle && typeof bundle === "object" && !Array.isArray(bundle), "Evidence bundle must be an object");
|
|
60
|
+
requireField(bundle.schemaVersion === EVIDENCE_BUNDLE_SCHEMA_VERSION, `Unsupported evidence bundle schemaVersion: ${bundle.schemaVersion}`);
|
|
61
|
+
requireField(bundle.kind === EVIDENCE_BUNDLE_KIND, "Evidence bundle kind is not forgeloop-evidence-bundle");
|
|
62
|
+
assertEvidenceTaskId(bundle.taskId);
|
|
63
|
+
requireField(expectedTaskId === null || bundle.taskId === expectedTaskId, `Evidence bundle taskId ${bundle.taskId} does not match its file name`);
|
|
64
|
+
requireField(typeof bundle.statement?.text === "string", "Evidence bundle is missing the statement text");
|
|
65
|
+
requireField(bundle.manifest && typeof bundle.manifest === "object", "Evidence bundle is missing the code manifest");
|
|
66
|
+
requireField(bundle.manifestFingerprint === canonicalFingerprint(bundle.manifest), "Evidence bundle manifest fingerprint does not match its manifest");
|
|
67
|
+
requireField(bundle.signature === null || (typeof bundle.signature?.bundleText === "string" && typeof bundle.signature?.provider === "string"), "Evidence bundle signature is malformed");
|
|
68
|
+
requireField(typeof bundle.digest === "string" && bundle.digest === evidenceBundleDigest(bundle), "Evidence bundle digest does not match its content");
|
|
69
|
+
let statement;
|
|
70
|
+
try { statement = JSON.parse(bundle.statement.text); } catch { throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, "Evidence bundle statement text is not valid JSON"); }
|
|
71
|
+
return { bundle, statement };
|
|
72
|
+
}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import { mkdir, readFile } from "node:fs/promises";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { canonicalFingerprint, readJsonArtifact } from "../artifacts.js";
|
|
4
|
+
import { readAttestationStatement } from "../attestation.js";
|
|
5
|
+
import { resolveAttestationBundlePath } from "../attachment-paths.js";
|
|
6
|
+
import { readCodeManifest } from "../code-manifest.js";
|
|
7
|
+
import { validateEventLedger } from "../events.js";
|
|
8
|
+
import { E_EVIDENCE_EXPORT_UNAVAILABLE } from "../error-codes.js";
|
|
9
|
+
import { assertSafePath, ensureWithin, writeFileAtomic } from "../filesystem.js";
|
|
10
|
+
import { withSigningStatementFile } from "../signing/statement-file.js";
|
|
11
|
+
import { taskArtifactPath, taskAttestationStatementPath } from "../task-paths.js";
|
|
12
|
+
import { getPackageRoot } from "../templates.js";
|
|
13
|
+
import { withProjectReadSnapshot } from "../../storage/project-read-snapshot.js";
|
|
14
|
+
import { withOperationalAttachmentFile } from "../../storage/operational-attachments.js";
|
|
15
|
+
import {
|
|
16
|
+
DEFAULT_EVIDENCE_DIRECTORY,
|
|
17
|
+
EVIDENCE_BUNDLE_KIND,
|
|
18
|
+
EVIDENCE_BUNDLE_SCHEMA_VERSION,
|
|
19
|
+
EVIDENCE_REDACTIONS,
|
|
20
|
+
assertEvidenceTaskId,
|
|
21
|
+
evidenceBundlePath,
|
|
22
|
+
evidenceError,
|
|
23
|
+
sealEvidenceBundle,
|
|
24
|
+
serializeEvidenceBundle,
|
|
25
|
+
} from "./bundle-format.js";
|
|
26
|
+
|
|
27
|
+
async function packageVersion(packageRoot) {
|
|
28
|
+
return JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8")).version;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
async function readStatementText(target, taskId) {
|
|
32
|
+
return withSigningStatementFile(target, taskAttestationStatementPath(taskId), (filename) => readFile(filename, "utf8"));
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
async function readSignatureText(target, taskId) {
|
|
36
|
+
let bundlePath;
|
|
37
|
+
try { bundlePath = resolveAttestationBundlePath(target, taskId); } catch { return null; }
|
|
38
|
+
try {
|
|
39
|
+
return await withOperationalAttachmentFile(target, bundlePath, taskId, (filename) => readFile(filename, "utf8"));
|
|
40
|
+
} catch {
|
|
41
|
+
return null;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
async function readOptional(target, relativePath, schemaName, packageRoot) {
|
|
46
|
+
try { return (await readJsonArtifact(target, relativePath, schemaName, packageRoot)).value; } catch { return null; }
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function checkSummary(receipt) {
|
|
50
|
+
return (Array.isArray(receipt?.checks) ? receipt.checks : []).map((check) => ({
|
|
51
|
+
id: check.id,
|
|
52
|
+
requirement: typeof check.requirement === "string" ? check.requirement : null,
|
|
53
|
+
status: check.status,
|
|
54
|
+
exitCode: Number.isInteger(check.exitCode) ? check.exitCode : null,
|
|
55
|
+
})).sort((left, right) => String(left.id).localeCompare(String(right.id)));
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const PHASE_BOUNDARIES = Object.freeze([
|
|
59
|
+
["planning", "TASK_RECEIVED", "EXECUTION_STARTED"],
|
|
60
|
+
["executing", "EXECUTION_STARTED", "VERIFICATION_STARTED"],
|
|
61
|
+
["verifying", "VERIFICATION_STARTED", "REVIEW_STARTED"],
|
|
62
|
+
["reviewing", "REVIEW_STARTED", "COMPLETION_VALIDATED"],
|
|
63
|
+
]);
|
|
64
|
+
|
|
65
|
+
function firstAt(events, name) {
|
|
66
|
+
const value = events.find((event) => event.event === name)?.at;
|
|
67
|
+
const time = value ? Date.parse(value) : Number.NaN;
|
|
68
|
+
return Number.isFinite(time) ? time : null;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// Informational lifecycle metrics from the task ledger. Self-reported and not
|
|
72
|
+
// cryptographically bound; harness and model are not recorded by the ledger.
|
|
73
|
+
export function lifecycleMetrics(events, receipt) {
|
|
74
|
+
const received = firstAt(events, "TASK_RECEIVED");
|
|
75
|
+
const completed = firstAt(events, "COMPLETION_VALIDATED");
|
|
76
|
+
const phaseDurationsMs = {};
|
|
77
|
+
for (const [phase, start, end] of PHASE_BOUNDARIES) {
|
|
78
|
+
const from = firstAt(events, start);
|
|
79
|
+
const to = firstAt(events, end);
|
|
80
|
+
if (from !== null && to !== null && to >= from) phaseDurationsMs[phase] = to - from;
|
|
81
|
+
}
|
|
82
|
+
const checks = Array.isArray(receipt?.checks) ? receipt.checks : [];
|
|
83
|
+
return {
|
|
84
|
+
bound: false,
|
|
85
|
+
receivedAt: received === null ? null : new Date(received).toISOString(),
|
|
86
|
+
completedAt: completed === null ? null : new Date(completed).toISOString(),
|
|
87
|
+
durationMs: received !== null && completed !== null && completed >= received ? completed - received : null,
|
|
88
|
+
phaseDurationsMs,
|
|
89
|
+
verificationCycles: events.filter((event) => event.event === "VERIFICATION_STARTED").length,
|
|
90
|
+
diagnoses: events.filter((event) => event.event === "DIAGNOSIS_RECORDED").length,
|
|
91
|
+
checksPassed: checks.filter((check) => check.status === "passed").length,
|
|
92
|
+
checksFailed: checks.filter((check) => check.status === "failed").length,
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
async function readLedgerEvents(target, taskId, packageRoot) {
|
|
97
|
+
try {
|
|
98
|
+
const ledger = await validateEventLedger(target, packageRoot, { taskId });
|
|
99
|
+
return ledger.valid ? ledger.events : [];
|
|
100
|
+
} catch {
|
|
101
|
+
return [];
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function informationalSummary(contract, receipt) {
|
|
106
|
+
return {
|
|
107
|
+
bound: false,
|
|
108
|
+
note: "Informational projection of the contract and receipt; only the statement and manifest are cryptographically bound.",
|
|
109
|
+
objective: typeof contract?.objective === "string" ? contract.objective : null,
|
|
110
|
+
successCriteria: Array.isArray(contract?.successCriteria) ? contract.successCriteria.map(String) : [],
|
|
111
|
+
checks: checkSummary(receipt),
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
async function collectEvidence(target, taskId, packageRoot) {
|
|
116
|
+
let manifest;
|
|
117
|
+
let statement;
|
|
118
|
+
try {
|
|
119
|
+
manifest = await readCodeManifest({ target, packageRoot, taskId });
|
|
120
|
+
statement = await readAttestationStatement({ target, packageRoot, taskId });
|
|
121
|
+
} catch (error) {
|
|
122
|
+
throw evidenceError(E_EVIDENCE_EXPORT_UNAVAILABLE, `Task ${taskId} has no exportable attestation (${error.code ?? "unknown"}); complete it with attestation mode required and run attestation-create first`);
|
|
123
|
+
}
|
|
124
|
+
if (statement.value.predicate?.verification?.completion !== "VALID") {
|
|
125
|
+
throw evidenceError(E_EVIDENCE_EXPORT_UNAVAILABLE, `Task ${taskId} attestation does not record a VALID completion`);
|
|
126
|
+
}
|
|
127
|
+
const statementText = await readStatementText(target, taskId);
|
|
128
|
+
if (canonicalFingerprint(JSON.parse(statementText)) !== canonicalFingerprint(statement.value)) {
|
|
129
|
+
throw evidenceError(E_EVIDENCE_EXPORT_UNAVAILABLE, "Attestation statement bytes changed while exporting");
|
|
130
|
+
}
|
|
131
|
+
return {
|
|
132
|
+
manifest: manifest.value,
|
|
133
|
+
statementText,
|
|
134
|
+
signatureText: await readSignatureText(target, taskId),
|
|
135
|
+
contract: await readOptional(target, taskArtifactPath(taskId, "contract"), "current-contract", packageRoot),
|
|
136
|
+
receipt: await readOptional(target, taskArtifactPath(taskId, "receipt"), "execution-receipt", packageRoot),
|
|
137
|
+
events: await readLedgerEvents(target, taskId, packageRoot),
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function assertRedacted(text, target) {
|
|
142
|
+
const absolute = path.resolve(target);
|
|
143
|
+
if (text.includes(absolute) || text.includes(absolute.replaceAll("\\", "/"))) {
|
|
144
|
+
throw evidenceError(E_EVIDENCE_EXPORT_UNAVAILABLE, "Evidence bundle would contain the absolute project path; refusing to export");
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
export async function exportEvidenceBundle({ target, taskId, packageRoot = getPackageRoot(), directory = DEFAULT_EVIDENCE_DIRECTORY } = {}) {
|
|
149
|
+
assertEvidenceTaskId(taskId);
|
|
150
|
+
const evidence = await withProjectReadSnapshot(target, () => collectEvidence(target, taskId, packageRoot));
|
|
151
|
+
const bundle = sealEvidenceBundle({
|
|
152
|
+
schemaVersion: EVIDENCE_BUNDLE_SCHEMA_VERSION,
|
|
153
|
+
kind: EVIDENCE_BUNDLE_KIND,
|
|
154
|
+
taskId,
|
|
155
|
+
forgeloopVersion: await packageVersion(packageRoot),
|
|
156
|
+
statement: { text: evidence.statementText },
|
|
157
|
+
manifest: evidence.manifest,
|
|
158
|
+
manifestFingerprint: canonicalFingerprint(evidence.manifest),
|
|
159
|
+
signature: evidence.signatureText === null ? null : { provider: "sigstore", bundleText: evidence.signatureText },
|
|
160
|
+
summary: informationalSummary(evidence.contract, evidence.receipt),
|
|
161
|
+
metrics: lifecycleMetrics(evidence.events, evidence.receipt),
|
|
162
|
+
redactions: [...EVIDENCE_REDACTIONS],
|
|
163
|
+
});
|
|
164
|
+
const text = serializeEvidenceBundle(bundle);
|
|
165
|
+
assertRedacted(text, target);
|
|
166
|
+
const relativePath = evidenceBundlePath(directory, taskId);
|
|
167
|
+
await mkdir(path.dirname(ensureWithin(target, relativePath)), { recursive: true });
|
|
168
|
+
await assertSafePath(target, relativePath);
|
|
169
|
+
await writeFileAtomic(ensureWithin(target, relativePath), text);
|
|
170
|
+
return {
|
|
171
|
+
schemaVersion: 1,
|
|
172
|
+
taskId,
|
|
173
|
+
path: relativePath,
|
|
174
|
+
digest: bundle.digest,
|
|
175
|
+
coveredPaths: bundle.manifest.entries.length,
|
|
176
|
+
signed: bundle.signature !== null,
|
|
177
|
+
redactions: bundle.redactions,
|
|
178
|
+
};
|
|
179
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
// Markdown projection of an evidence verification for CI step summaries and
|
|
2
|
+
// pull-request check runs. It never adds facts beyond the verification result.
|
|
3
|
+
|
|
4
|
+
const STATUS_LABEL = Object.freeze({
|
|
5
|
+
ATTESTED: "Verified and signed",
|
|
6
|
+
INTEGRITY_ONLY: "Consistent, unsigned",
|
|
7
|
+
NONE: "Not verified",
|
|
8
|
+
});
|
|
9
|
+
|
|
10
|
+
const escapeCell = (value) => String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
|
|
11
|
+
|
|
12
|
+
function bundleRows(result) {
|
|
13
|
+
if (result.bundles.length === 0) return ["No evidence bundles changed in this range."];
|
|
14
|
+
return [
|
|
15
|
+
"| Task | Integrity | Signature | Matching entries |",
|
|
16
|
+
"| --- | --- | --- | --- |",
|
|
17
|
+
...result.bundles.map((bundle) => `| \`${escapeCell(bundle.taskId)}\` | ${bundle.integrity} | ${bundle.signature.status} | ${bundle.matchingEntries}/${bundle.entries} |`),
|
|
18
|
+
];
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function listSection(title, items) {
|
|
22
|
+
if (items.length === 0) return [];
|
|
23
|
+
return ["", `### ${title}`, "", ...items.map((item) => `- ${item}`)];
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export function formatEvidenceMarkdown(result) {
|
|
27
|
+
const icon = result.status === "VALID" ? "✅" : "❌";
|
|
28
|
+
return [
|
|
29
|
+
`## ${icon} ForgeLoop evidence: ${STATUS_LABEL[result.level] ?? result.level}`,
|
|
30
|
+
"",
|
|
31
|
+
`Status \`${result.status}\`, level \`${result.level}\`: ${result.coveredPaths}/${result.changedPaths} changed paths covered.`,
|
|
32
|
+
"",
|
|
33
|
+
...bundleRows(result),
|
|
34
|
+
...listSection("Uncovered paths", result.uncoveredPaths.map((value) => `\`${escapeCell(value)}\``)),
|
|
35
|
+
...listSection("Superseded entries", result.superseded.map((item) => `\`${escapeCell(item.path)}\` from \`${item.taskId}\`, covered by ${item.supersededBy.map((id) => `\`${id}\``).join(", ")}`)),
|
|
36
|
+
...listSection("Errors", result.errors.map((error) => `\`${error.code}\`: ${escapeCell(error.message)}`)),
|
|
37
|
+
...listSection("Warnings", result.warnings),
|
|
38
|
+
"",
|
|
39
|
+
].join("\n");
|
|
40
|
+
}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import { mkdtemp, rm, writeFile } from "node:fs/promises";
|
|
2
|
+
import os from "node:os";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { validateAttestationStatement } from "../attestation.js";
|
|
5
|
+
import { assertAttestationStatementBindings, verifyCodeManifestContent } from "../attestation-verifier.js";
|
|
6
|
+
import { validateCodeManifest } from "../code-manifest.js";
|
|
7
|
+
import { E_ATTESTATION_CONTENT_MISMATCH, E_ATTESTATION_COVERAGE_GAP, E_ATTESTATION_UNSIGNED, E_EVIDENCE_BUNDLE_INVALID } from "../error-codes.js";
|
|
8
|
+
import { resolveRevisionProvider } from "../revision/provider.js";
|
|
9
|
+
import { REVISION_PROVIDERS } from "../revision/registry.js";
|
|
10
|
+
import { createSigstoreSigningProvider } from "../signing/sigstore.js";
|
|
11
|
+
import { getPackageRoot } from "../templates.js";
|
|
12
|
+
import { DEFAULT_EVIDENCE_DIRECTORY, parseEvidenceBundle } from "./bundle-format.js";
|
|
13
|
+
|
|
14
|
+
export const EVIDENCE_LEVELS = Object.freeze({ ATTESTED: "ATTESTED", INTEGRITY_ONLY: "INTEGRITY_ONLY", NONE: "NONE" });
|
|
15
|
+
export const UNSIGNED_WARNING = "Unsigned evidence bundles prove internal consistency with the committed code, not that ForgeLoop produced them; require signatures to use this check as a trust gate.";
|
|
16
|
+
|
|
17
|
+
const normalize = (value) => String(value).replaceAll("\\", "/").replace(/^\.\//u, "");
|
|
18
|
+
const entryPaths = (entry) => [entry.path, entry.sourcePath].filter(Boolean).map(normalize);
|
|
19
|
+
|
|
20
|
+
function isExcluded(value, directory, exclusions) {
|
|
21
|
+
if (value === ".forgeloop" || value.startsWith(".forgeloop/")) return true;
|
|
22
|
+
if (value === directory || value.startsWith(`${directory}/`)) return true;
|
|
23
|
+
return exclusions.some((pattern) => {
|
|
24
|
+
const normalized = normalize(pattern);
|
|
25
|
+
if (normalized.endsWith("/**")) return value === normalized.slice(0, -3) || value.startsWith(normalized.slice(0, -2));
|
|
26
|
+
return value === normalized;
|
|
27
|
+
});
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
async function resolveProvider(target, revisionProvider) {
|
|
31
|
+
return typeof revisionProvider === "string"
|
|
32
|
+
? resolveRevisionProvider({ target, providerName: revisionProvider, registry: REVISION_PROVIDERS })
|
|
33
|
+
: revisionProvider;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function changedBundlePaths(changedEntries, directory) {
|
|
37
|
+
return [...new Set(changedEntries
|
|
38
|
+
.filter((entry) => entry.kind !== "DELETED" && entry.operation !== "DELETED")
|
|
39
|
+
.map((entry) => normalize(entry.path))
|
|
40
|
+
.filter((value) => value.startsWith(`${directory}/`) && value.endsWith(".json")))].sort();
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
async function verifySignature({ statementText, signature, signer, policy }) {
|
|
44
|
+
if (!signature) return { status: "UNSIGNED" };
|
|
45
|
+
const directory = await mkdtemp(path.join(os.tmpdir(), "forgeloop-evidence-signature-"));
|
|
46
|
+
try {
|
|
47
|
+
await writeFile(path.join(directory, "statement.json"), statementText);
|
|
48
|
+
await writeFile(path.join(directory, "statement.sigstore.json"), signature.bundleText);
|
|
49
|
+
const result = await signer.verify({ target: directory, statementPath: "statement.json", bundlePath: "statement.sigstore.json", policy });
|
|
50
|
+
return { status: result.status, ...(result.code ? { code: result.code } : {}), ...(result.message ? { message: result.message } : {}) };
|
|
51
|
+
} finally {
|
|
52
|
+
await rm(directory, { recursive: true, force: true });
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
async function verifyEntries({ target, manifest, provider, headRevision }) {
|
|
57
|
+
const entries = [];
|
|
58
|
+
for (const entry of manifest.entries) {
|
|
59
|
+
try {
|
|
60
|
+
await verifyCodeManifestContent({ target, manifest: { ...manifest, entries: [entry] }, revisionProvider: provider, revision: headRevision });
|
|
61
|
+
entries.push({ paths: entryPaths(entry), digest: entry.sha256 ?? entry.providerContentId ?? entry.kind, matches: true });
|
|
62
|
+
} catch (error) {
|
|
63
|
+
if (error.code !== E_ATTESTATION_CONTENT_MISMATCH) throw error;
|
|
64
|
+
entries.push({ paths: entryPaths(entry), digest: entry.sha256 ?? entry.providerContentId ?? entry.kind, matches: false });
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
return entries;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
async function loadBundle(context, bundlePath) {
|
|
71
|
+
const { target, provider, headRevision, packageRoot, signer, policy } = context;
|
|
72
|
+
const expectedTaskId = path.posix.basename(bundlePath, ".json");
|
|
73
|
+
const record = { path: bundlePath, taskId: expectedTaskId, integrity: "INVALID", signature: { status: "NOT_CHECKED" }, entries: [] };
|
|
74
|
+
try {
|
|
75
|
+
const bytes = await provider.readContent({ target, revision: headRevision, path: bundlePath });
|
|
76
|
+
const { bundle, statement } = parseEvidenceBundle(Buffer.from(bytes).toString("utf8"), expectedTaskId);
|
|
77
|
+
await validateAttestationStatement(statement, packageRoot);
|
|
78
|
+
const manifest = await validateCodeManifest(bundle.manifest, packageRoot);
|
|
79
|
+
assertAttestationStatementBindings(statement, manifest, bundle.taskId, bundle.manifestFingerprint);
|
|
80
|
+
record.entries = await verifyEntries({ target, manifest, provider, headRevision });
|
|
81
|
+
record.integrity = "VALID";
|
|
82
|
+
record.signature = await verifySignature({ statementText: bundle.statement.text, signature: bundle.signature, signer, policy });
|
|
83
|
+
} catch (error) {
|
|
84
|
+
if (error.code?.startsWith("E_REVISION_")) throw error;
|
|
85
|
+
record.error = { code: error.code?.startsWith("E_") ? error.code : E_EVIDENCE_BUNDLE_INVALID, message: error.message };
|
|
86
|
+
}
|
|
87
|
+
return record;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function coverageFor(changedPaths, bundles) {
|
|
91
|
+
const covering = new Map();
|
|
92
|
+
for (const bundle of bundles.filter((item) => item.integrity === "VALID")) {
|
|
93
|
+
for (const entry of bundle.entries.filter((item) => item.matches)) {
|
|
94
|
+
for (const value of entry.paths) covering.set(value, [...(covering.get(value) ?? []), bundle.taskId]);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
const errors = [];
|
|
98
|
+
const superseded = [];
|
|
99
|
+
for (const bundle of bundles.filter((item) => item.integrity === "VALID")) {
|
|
100
|
+
for (const entry of bundle.entries.filter((item) => !item.matches)) {
|
|
101
|
+
for (const value of entry.paths) {
|
|
102
|
+
if (covering.has(value)) superseded.push({ path: value, taskId: bundle.taskId, supersededBy: [...new Set(covering.get(value))].sort() });
|
|
103
|
+
else errors.push({ code: E_ATTESTATION_CONTENT_MISMATCH, taskId: bundle.taskId, path: value, message: `Evidence for ${value} does not match the head revision and no other bundle covers it` });
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
const uncoveredPaths = changedPaths.filter((value) => !covering.has(value));
|
|
108
|
+
return { covering, errors, superseded, uncoveredPaths };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function signerPolicyFrom(signerPolicy) {
|
|
112
|
+
return Object.fromEntries(["identity", "issuer", "trustedRoot"].filter((key) => signerPolicy[key]).map((key) => [key, signerPolicy[key]]));
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function signatureErrors(bundles) {
|
|
116
|
+
return bundles.filter((bundle) => bundle.signature.status !== "VALID").map((bundle) => ({
|
|
117
|
+
code: bundle.signature.code ?? E_ATTESTATION_UNSIGNED,
|
|
118
|
+
taskId: bundle.taskId,
|
|
119
|
+
message: bundle.signature.message ?? `Evidence for task ${bundle.taskId} has no valid signature`,
|
|
120
|
+
}));
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
function overallLevel(status, usedBundles) {
|
|
124
|
+
if (status !== "VALID") return EVIDENCE_LEVELS.NONE;
|
|
125
|
+
return usedBundles.length > 0 && usedBundles.every((bundle) => bundle.signature.status === "VALID") ? EVIDENCE_LEVELS.ATTESTED : EVIDENCE_LEVELS.INTEGRITY_ONLY;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
export async function verifyEvidenceRange({
|
|
129
|
+
target,
|
|
130
|
+
packageRoot = getPackageRoot(),
|
|
131
|
+
revisionProvider = "git",
|
|
132
|
+
baseRevision,
|
|
133
|
+
headRevision,
|
|
134
|
+
directory = DEFAULT_EVIDENCE_DIRECTORY,
|
|
135
|
+
requireCompleteCoverage = true,
|
|
136
|
+
requireSignature = false,
|
|
137
|
+
signerPolicy = {},
|
|
138
|
+
signingProvider = null,
|
|
139
|
+
exclusions = [],
|
|
140
|
+
} = {}) {
|
|
141
|
+
const evidenceDirectory = normalize(directory).replace(/\/+$/u, "");
|
|
142
|
+
const provider = await resolveProvider(target, revisionProvider);
|
|
143
|
+
const changedEntries = await provider.getChangedEntries({ target, baseRevision, headRevision });
|
|
144
|
+
const changedPaths = [...new Set(changedEntries.flatMap(entryPaths))].filter((value) => !isExcluded(value, evidenceDirectory, exclusions)).sort();
|
|
145
|
+
const policy = signerPolicyFrom(signerPolicy);
|
|
146
|
+
const context = { target, provider, headRevision, packageRoot, signer: signingProvider ?? createSigstoreSigningProvider(), policy };
|
|
147
|
+
const bundles = [];
|
|
148
|
+
for (const bundlePath of changedBundlePaths(changedEntries, evidenceDirectory)) bundles.push(await loadBundle(context, bundlePath));
|
|
149
|
+
const coverage = coverageFor(changedPaths, bundles);
|
|
150
|
+
const errors = [
|
|
151
|
+
...bundles.filter((bundle) => bundle.error).map((bundle) => ({ ...bundle.error, taskId: bundle.taskId, path: bundle.path })),
|
|
152
|
+
...coverage.errors,
|
|
153
|
+
];
|
|
154
|
+
if (requireCompleteCoverage && coverage.uncoveredPaths.length > 0) {
|
|
155
|
+
errors.push({ code: E_ATTESTATION_COVERAGE_GAP, message: `Changed paths are not covered by evidence: ${coverage.uncoveredPaths.join(", ")}`, paths: coverage.uncoveredPaths });
|
|
156
|
+
}
|
|
157
|
+
const usedBundles = bundles.filter((bundle) => bundle.integrity === "VALID");
|
|
158
|
+
if (requireSignature) errors.push(...signatureErrors(usedBundles));
|
|
159
|
+
const status = errors.length === 0 ? "VALID" : "INVALID";
|
|
160
|
+
const level = overallLevel(status, usedBundles);
|
|
161
|
+
return {
|
|
162
|
+
schemaVersion: 1,
|
|
163
|
+
kind: "forgeloop-evidence-verification",
|
|
164
|
+
status,
|
|
165
|
+
level,
|
|
166
|
+
revisionProvider: provider.name ?? "unknown",
|
|
167
|
+
baseRevision: baseRevision ?? null,
|
|
168
|
+
headRevision: headRevision ?? null,
|
|
169
|
+
evidenceDirectory,
|
|
170
|
+
changedPaths: changedPaths.length,
|
|
171
|
+
coveredPaths: changedPaths.length - coverage.uncoveredPaths.length,
|
|
172
|
+
uncoveredPaths: coverage.uncoveredPaths,
|
|
173
|
+
superseded: coverage.superseded,
|
|
174
|
+
bundles: bundles.map(({ entries, ...bundle }) => ({ ...bundle, entries: entries.length, matchingEntries: entries.filter((entry) => entry.matches).length })),
|
|
175
|
+
signature: { required: requireSignature, ...policy },
|
|
176
|
+
warnings: level === EVIDENCE_LEVELS.INTEGRITY_ONLY ? [UNSIGNED_WARNING] : [],
|
|
177
|
+
errors,
|
|
178
|
+
};
|
|
179
|
+
}
|
|
@@ -26,7 +26,7 @@ export const INTEGRATION_RISK_CLASSES = Object.freeze({
|
|
|
26
26
|
|
|
27
27
|
const READ_ONLY_COMMANDS = Object.freeze(new Set([
|
|
28
28
|
"storage-migration-status",
|
|
29
|
-
"protocol-info", "decision-status", "decision-show", "context-plan", "model-route", "semantic-plan", "test-inventory", "status", "next", "continuity", "reconcile-continuity",
|
|
29
|
+
"protocol-info", "decision-status", "decision-show", "context-plan", "model-route", "semantic-plan", "test-inventory", "assess", "evidence-verify", "status", "next", "continuity", "reconcile-continuity",
|
|
30
30
|
"task-list", "task-show", "task-lock-status", "progress", "audit", "report",
|
|
31
31
|
"inspect", "validate-state", "validate-protocol", "validate-receipt",
|
|
32
32
|
"policy-status", "policy-diff", "rule-verify", "policy",
|
|
@@ -45,7 +45,7 @@ const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
|
|
|
45
45
|
"record-terminal-result", "complete",
|
|
46
46
|
"record-intervention", "record-hypothesis-disposition",
|
|
47
47
|
"usage-record",
|
|
48
|
-
"workspace-bind", "handoff-create", "handoff-accept", "responsibility-set", "verify-scope", "attestation-create",
|
|
48
|
+
"workspace-bind", "handoff-create", "handoff-accept", "responsibility-set", "verify-scope", "attestation-create", "evidence-export",
|
|
49
49
|
]));
|
|
50
50
|
|
|
51
51
|
const STATIC_RISK_CLASSES = Object.freeze({
|
|
@@ -77,6 +77,8 @@ const STATIC_RISK_CLASSES = Object.freeze({
|
|
|
77
77
|
"storage-migrate": INTEGRATION_RISK_CLASSES.MAINTENANCE,
|
|
78
78
|
"storage-backup": INTEGRATION_RISK_CLASSES.MAINTENANCE,
|
|
79
79
|
"storage-restore": INTEGRATION_RISK_CLASSES.MAINTENANCE,
|
|
80
|
+
"sync-push": INTEGRATION_RISK_CLASSES.MAINTENANCE,
|
|
81
|
+
"sync-pull": INTEGRATION_RISK_CLASSES.MAINTENANCE,
|
|
80
82
|
"storage-restore-resume": INTEGRATION_RISK_CLASSES.MAINTENANCE,
|
|
81
83
|
activate: INTEGRATION_RISK_CLASSES.MAINTENANCE,
|
|
82
84
|
"task-migrate": INTEGRATION_RISK_CLASSES.MAINTENANCE,
|