@futurelastic/colab-handbook 1.21.0-rc.9 → 1.22.0-rc.1
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/audit/audit.mjs +17 -0
- package/package.json +1 -1
- package/tools/lib/checklist.js +12 -3
- package/tools/lib/factories.js +329 -0
package/audit/audit.mjs
CHANGED
|
@@ -141,6 +141,8 @@ const migrationGrant = require("../tools/lib/migration-grant.js");
|
|
|
141
141
|
const ciGrantLib = require("../tools/lib/ci-grant.js");
|
|
142
142
|
// #407: the optional `trust-humans` list — read through the same module every grant reader uses.
|
|
143
143
|
const trustHumansLib = require("../tools/lib/trust-humans.js");
|
|
144
|
+
// #739: `.github/factories.yml` — the trust file for several teams on one repository.
|
|
145
|
+
const factoriesLib = require("../tools/lib/factories.js");
|
|
144
146
|
// #403: the `live-env:` key — read through the same module `colab gate-hermetic` uses.
|
|
145
147
|
const hermeticLib = require("../tools/lib/hermetic.js");
|
|
146
148
|
// #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
|
|
@@ -1551,6 +1553,21 @@ function auditRepoInner(target, ctx) {
|
|
|
1551
1553
|
if (!tr.valid) fail(tr.reason);
|
|
1552
1554
|
}
|
|
1553
1555
|
|
|
1556
|
+
// ---- .github/factories.yml (#739) -----------------------------------------
|
|
1557
|
+
// The trust file several teams ("factories") share one repository through. Absent = nothing
|
|
1558
|
+
// (one team, no cross-factory rule). tools/lib/factories.js parseFactories is the one reading.
|
|
1559
|
+
// An invalid file fails: every reader then answers "nobody" (fail closed), so each cross-factory
|
|
1560
|
+
// rule the file was meant to turn on stops matching anyone — loud here, not at the next claim.
|
|
1561
|
+
{
|
|
1562
|
+
const text = src.readFile(factoriesLib.PATH);
|
|
1563
|
+
if (text === null || text === undefined) info.factories = null;
|
|
1564
|
+
else {
|
|
1565
|
+
const fr = factoriesLib.parseFactories(text);
|
|
1566
|
+
info.factories = fr.valid ? Object.keys(fr.doc.factories) : null;
|
|
1567
|
+
for (const why of fr.findings) fail(`${factoriesLib.PATH}: ${why}`);
|
|
1568
|
+
}
|
|
1569
|
+
}
|
|
1570
|
+
|
|
1554
1571
|
// ---- live-env (#403) ------------------------------------------------------
|
|
1555
1572
|
// `live-env: none` is the one declaration that skips code-wrap A3's hermetic second test run
|
|
1556
1573
|
// (`colab gate-hermetic`). tools/lib/hermetic.js parseLiveEnv is the one reading. An invalid
|
package/package.json
CHANGED
package/tools/lib/checklist.js
CHANGED
|
@@ -31,9 +31,18 @@ const ANY_HEADING_RE = /^#{1,6}\s+\S/;
|
|
|
31
31
|
/** A GitHub checklist line: `- [ ] …` or `- [x] …` (case-insensitive on the mark). */
|
|
32
32
|
const ITEM_RE = /^-\s*\[([ xX])\]\s*(.+)$/;
|
|
33
33
|
|
|
34
|
-
/** `Remainder: #M` — the
|
|
35
|
-
* the `Filed-by:` / `Group:` / `Because:` trailers this repo already writes onto issues.
|
|
36
|
-
|
|
34
|
+
/** `Remainder: #M` — the declaration that hands unticked boxes to a follow-up issue, same shape as
|
|
35
|
+
* the `Filed-by:` / `Group:` / `Because:` trailers this repo already writes onto issues.
|
|
36
|
+
*
|
|
37
|
+
* Read ANYWHERE in a text, not only at the start of a line (#737): no rule says the declaration
|
|
38
|
+
* must start a line, and the two common forms people actually write were both missed — at the end
|
|
39
|
+
* of the unticked item it hands off (`- [ ] measure X … — Remainder: #M`) and inside a sentence or
|
|
40
|
+
* in bold (`item 4 moved to **Remainder: #M**`, `**Remainder:** #M`). Measured: a graded,
|
|
41
|
+
* CI-green branch sat refused for ~16 h until the same trailer was restated on its own line.
|
|
42
|
+
* The left edge still has to be a word boundary (`xRemainder:` does not count), and `#M` must be
|
|
43
|
+
* digits, so the `Remainder: #M` placeholder in prose and refusal messages never matches.
|
|
44
|
+
* Emphasis markers (`*`, `_`) are allowed on either side of the colon. */
|
|
45
|
+
const REMAINDER_RE = /(?<![A-Za-z0-9])Remainder[*_]*:[*_]*\s*#(\d+)\b/i;
|
|
37
46
|
|
|
38
47
|
/**
|
|
39
48
|
* The raw text of the `## Plan` section (between its heading and the next heading, or the end of
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* `.github/factories.yml` (#739, epic #738): the trust file that lets several independent teams
|
|
4
|
+
* ("factories") work on one repository with nothing shared but its forge.
|
|
5
|
+
*
|
|
6
|
+
* WHAT IT HOLDS. Who the teams are and what each may prove:
|
|
7
|
+
*
|
|
8
|
+
* version: 1
|
|
9
|
+
* steward: core # the factory that owns intake, trunk health and release
|
|
10
|
+
* forge: github.com # the repository's one home forge (a host name)
|
|
11
|
+
* factories:
|
|
12
|
+
* core: # a MAP keyed by factory id — never a list of factory objects
|
|
13
|
+
* tier: steward # steward · partner · outside
|
|
14
|
+
* machines: [box-a, box-b] # machine ids, unique across the whole file
|
|
15
|
+
* key: ssh-ed25519 AAAA… # ONE SSH public key: signs claim commits and verdict markers
|
|
16
|
+
* humans: [operator-a] # logins that count as a human for grants
|
|
17
|
+
* slices: [slice:core] # labels; each owned by exactly one factory
|
|
18
|
+
* steward-areas: [CONVENTIONS.md, .github/**] # paths whose change needs one steward verdict
|
|
19
|
+
*
|
|
20
|
+
* WHERE IT IS READ FROM is the caller's job, and the rule is the one `trust-humans:` follows: the
|
|
21
|
+
* TRUNK's committed copy, never the branch being judged — a branch that could edit this file could
|
|
22
|
+
* grant itself a factory, a machine or a key. Nothing here reads git.
|
|
23
|
+
*
|
|
24
|
+
* FAIL CLOSED. A malformed file is `valid: false` and every lookup answers "nobody": a reader that
|
|
25
|
+
* fell back to "no factories file" would silently drop every cross-factory rule the adopter
|
|
26
|
+
* declared the file to turn on.
|
|
27
|
+
*
|
|
28
|
+
* THE SIGNATURE FORMATS (mechanics: tools/docs/factories.md; why: docs/adr/739-*.md).
|
|
29
|
+
* claim commit an SSH-signed git commit, checked with `git verify-commit` against
|
|
30
|
+
* allowedSigners(doc, 'git') — the principal is the factory id.
|
|
31
|
+
* verdict marker `<!-- colab:verdict phase=<p> v=<v> head=<sha40> factory=<id> sig=<b64> -->`;
|
|
32
|
+
* `sig` is an SSH signature (namespace `colab-verdict`) over verdictPayload(),
|
|
33
|
+
* never over the comment body. `forge`, `repo` and `issue` in the payload come
|
|
34
|
+
* from the VERIFIER's own context, so a marker copied elsewhere fails.
|
|
35
|
+
*
|
|
36
|
+
* PURE: text or a parsed doc in, a verdict out. No git, no network, no ssh-keygen.
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
const yaml = require('./yaml.js');
|
|
40
|
+
const { LOGIN_RE } = require('./trust-humans.js');
|
|
41
|
+
|
|
42
|
+
/** Where the file lives, relative to the repository root. */
|
|
43
|
+
const PATH = '.github/factories.yml';
|
|
44
|
+
const VERSION = 1;
|
|
45
|
+
const TIERS = ['steward', 'partner', 'outside'];
|
|
46
|
+
const TOP_KEYS = ['version', 'steward', 'forge', 'factories', 'steward-areas'];
|
|
47
|
+
const FACTORY_KEYS = ['tier', 'machines', 'key', 'humans', 'slices'];
|
|
48
|
+
|
|
49
|
+
const FACTORY_ID_RE = /^[a-z0-9][a-z0-9-]{0,38}$/;
|
|
50
|
+
const MACHINE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
|
|
51
|
+
const FORGE_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:[0-9]{1,5})?$/;
|
|
52
|
+
const SLICE_RE = /^slice:[a-z0-9][a-z0-9._-]*$/;
|
|
53
|
+
/** One OpenSSH public key line: type, base64 blob, optional comment. */
|
|
54
|
+
const SSH_KEY_RE = /^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com) [A-Za-z0-9+/]+={0,2}( [^\s]+)?$/;
|
|
55
|
+
|
|
56
|
+
// ── the shared vocabulary (CONVENTIONS.md §5, *Factories*) ──────────────────────────────────
|
|
57
|
+
// Prose is the source; these are the machine copy. Not in tools/lib/codec yet — that is a closed
|
|
58
|
+
// public surface, and nothing writes these strings yet; the first writer (#743) moves what it writes.
|
|
59
|
+
const FACTORY_LABEL_PREFIX = 'factory:';
|
|
60
|
+
const SLICE_LABEL_PREFIX = 'slice:';
|
|
61
|
+
const QUEUE_READY_LABEL = 'queue:ready';
|
|
62
|
+
const REVIEW_LABEL_PREFIX = 'review:';
|
|
63
|
+
const AUDIT_STATUS_CONTEXT = 'audit';
|
|
64
|
+
/** `review/<check>@<factory>` — the commit-status context one factory's reviewer posts. */
|
|
65
|
+
function reviewStatusContext(check, factory) { return `review/${check}@${factory}`; }
|
|
66
|
+
|
|
67
|
+
// ── signatures ──────────────────────────────────────────────────────────────────────────────
|
|
68
|
+
const VERDICT_NAMESPACE = 'colab-verdict';
|
|
69
|
+
const CLAIM_NAMESPACE = 'git';
|
|
70
|
+
const PAYLOAD_HEADER = 'colab-verdict/1';
|
|
71
|
+
/** The signed fields, in signing order. `forge`/`repo` come from the verifier, the rest from the marker. */
|
|
72
|
+
const PAYLOAD_FIELDS = ['forge', 'repo', 'issue', 'phase', 'verdict', 'head', 'factory'];
|
|
73
|
+
const VERDICTS = ['pass', 'rework', 'blocked', 'escalate'];
|
|
74
|
+
|
|
75
|
+
function isList(v) { return Array.isArray(v); }
|
|
76
|
+
function str(v) { return typeof v === 'string' ? v.trim() : v; }
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Two factories under one id are merged silently by the YAML subset parser (last one wins), which
|
|
80
|
+
* would hide exactly the clash the validator exists to report. So the raw text is read once more:
|
|
81
|
+
* the direct children of `factories:` and the top-level keys, each seen at most once.
|
|
82
|
+
*/
|
|
83
|
+
function duplicateKeys(text) {
|
|
84
|
+
const out = [];
|
|
85
|
+
const lines = String(text).split(/\r?\n/).map((l) => l.replace(/(^|\s)#.*$/, '').replace(/\s+$/, ''))
|
|
86
|
+
.filter((l) => l.trim() !== '');
|
|
87
|
+
const top = new Map();
|
|
88
|
+
let inFactories = false;
|
|
89
|
+
let childIndent = null;
|
|
90
|
+
const children = new Map();
|
|
91
|
+
for (const l of lines) {
|
|
92
|
+
const indent = l.match(/^ */)[0].length;
|
|
93
|
+
const m = l.trim().match(/^([^:\s][^:]*):/);
|
|
94
|
+
if (indent === 0) {
|
|
95
|
+
inFactories = false;
|
|
96
|
+
if (m) {
|
|
97
|
+
top.set(m[1], (top.get(m[1]) || 0) + 1);
|
|
98
|
+
if (m[1] === 'factories') { inFactories = true; childIndent = null; }
|
|
99
|
+
}
|
|
100
|
+
continue;
|
|
101
|
+
}
|
|
102
|
+
if (!inFactories || !m) continue;
|
|
103
|
+
if (childIndent === null) childIndent = indent;
|
|
104
|
+
if (indent === childIndent) children.set(m[1], (children.get(m[1]) || 0) + 1);
|
|
105
|
+
}
|
|
106
|
+
for (const [k, n] of top) if (n > 1) out.push(`top-level key \`${k}\` appears ${n} times`);
|
|
107
|
+
for (const [k, n] of children) if (n > 1) out.push(`factory \`${k}\` is declared ${n} times — one id, one factory`);
|
|
108
|
+
return out;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** A list field → its trimmed strings, or a finding. `allowEmpty` for `humans`. */
|
|
112
|
+
function listOf(v, what, re, allowEmpty, findings) {
|
|
113
|
+
if (v === null || v === undefined) {
|
|
114
|
+
if (allowEmpty) return [];
|
|
115
|
+
findings.push(`${what} is missing`);
|
|
116
|
+
return [];
|
|
117
|
+
}
|
|
118
|
+
if (!isList(v)) { findings.push(`${what} must be a list, got ${JSON.stringify(v)}`); return []; }
|
|
119
|
+
if (!allowEmpty && v.length === 0) { findings.push(`${what} is an empty list`); return []; }
|
|
120
|
+
const out = [];
|
|
121
|
+
for (const raw of v) {
|
|
122
|
+
const s = str(raw);
|
|
123
|
+
if (typeof s !== 'string' || !re.test(s)) findings.push(`${what} has an invalid entry ${JSON.stringify(raw)}`);
|
|
124
|
+
else out.push(s);
|
|
125
|
+
}
|
|
126
|
+
return out;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* The file's text → `{ valid, findings, doc }`.
|
|
131
|
+
* doc — `{ version, steward, forge, factories: { <id>: { tier, machines, key, humans, slices } },
|
|
132
|
+
* stewardAreas }`, normalised; present even when invalid, for a reader that wants to
|
|
133
|
+
* print what it saw. Never act on it when `valid` is false.
|
|
134
|
+
* Every finding names the field and, for a clash, both factories.
|
|
135
|
+
*/
|
|
136
|
+
function parseFactories(text) {
|
|
137
|
+
const findings = [];
|
|
138
|
+
let raw;
|
|
139
|
+
try { raw = yaml.parse(String(text == null ? '' : text)); } catch (e) {
|
|
140
|
+
return { valid: false, findings: [`${PATH} could not be parsed: ${e.message}`], doc: null };
|
|
141
|
+
}
|
|
142
|
+
findings.push(...duplicateKeys(text));
|
|
143
|
+
if (!raw || typeof raw !== 'object' || isList(raw)) {
|
|
144
|
+
return { valid: false, findings: [`${PATH} must be a map of keys`], doc: null };
|
|
145
|
+
}
|
|
146
|
+
for (const k of Object.keys(raw)) if (!TOP_KEYS.includes(k)) findings.push(`unknown key \`${k}\``);
|
|
147
|
+
|
|
148
|
+
if (raw.version !== VERSION) findings.push(`version must be ${VERSION}, got ${JSON.stringify(raw.version ?? null)}`);
|
|
149
|
+
const forge = str(raw.forge);
|
|
150
|
+
if (typeof forge !== 'string' || !FORGE_RE.test(forge)) findings.push(`forge must be a host name (e.g. github.com), got ${JSON.stringify(raw.forge ?? null)}`);
|
|
151
|
+
|
|
152
|
+
const factories = {};
|
|
153
|
+
const fs = raw.factories;
|
|
154
|
+
if (!fs || typeof fs !== 'object' || isList(fs)) {
|
|
155
|
+
findings.push('factories must be a map keyed by factory id (not a list of factory objects)');
|
|
156
|
+
} else {
|
|
157
|
+
for (const [id, f] of Object.entries(fs)) {
|
|
158
|
+
const where = `factories.${id}`;
|
|
159
|
+
if (!FACTORY_ID_RE.test(id)) findings.push(`${where}: a factory id is lowercase letters, digits and hyphens`);
|
|
160
|
+
if (!f || typeof f !== 'object' || isList(f)) { findings.push(`${where} must be a map`); continue; }
|
|
161
|
+
for (const k of Object.keys(f)) if (!FACTORY_KEYS.includes(k)) findings.push(`${where}: unknown key \`${k}\``);
|
|
162
|
+
const tier = str(f.tier);
|
|
163
|
+
if (!TIERS.includes(tier)) findings.push(`${where}.tier must be one of ${TIERS.join(' · ')}, got ${JSON.stringify(f.tier ?? null)}`);
|
|
164
|
+
const key = str(f.key);
|
|
165
|
+
if (typeof key !== 'string' || !SSH_KEY_RE.test(key)) findings.push(`${where}.key must be one SSH public key line (type, base64, optional comment)`);
|
|
166
|
+
factories[id] = {
|
|
167
|
+
tier: TIERS.includes(tier) ? tier : null,
|
|
168
|
+
machines: listOf(f.machines, `${where}.machines`, MACHINE_ID_RE, false, findings),
|
|
169
|
+
key: typeof key === 'string' && SSH_KEY_RE.test(key) ? key : null,
|
|
170
|
+
humans: listOf(f.humans, `${where}.humans`, LOGIN_RE, true, findings).map((h) => h.toLowerCase()),
|
|
171
|
+
slices: listOf(f.slices, `${where}.slices`, SLICE_RE, true, findings),
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
if (Object.keys(factories).length === 0) findings.push('factories declares no factory');
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
// Across the file: a machine and a slice each belong to exactly one factory.
|
|
178
|
+
for (const [field, noun] of [['machines', 'machine'], ['slices', 'slice']]) {
|
|
179
|
+
const owner = new Map();
|
|
180
|
+
for (const [id, f] of Object.entries(factories)) {
|
|
181
|
+
for (const v of f[field]) {
|
|
182
|
+
const prev = owner.get(v);
|
|
183
|
+
if (prev && prev !== id) findings.push(`${noun} \`${v}\` is claimed by both \`${prev}\` and \`${id}\` — each ${noun} belongs to one factory`);
|
|
184
|
+
else if (prev === id) findings.push(`${noun} \`${v}\` is listed twice in \`${id}\``);
|
|
185
|
+
else owner.set(v, id);
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
const keyOwner = new Map();
|
|
190
|
+
for (const [id, f] of Object.entries(factories)) {
|
|
191
|
+
if (!f.key) continue;
|
|
192
|
+
const blob = f.key.split(' ')[1];
|
|
193
|
+
if (keyOwner.has(blob)) findings.push(`factories \`${keyOwner.get(blob)}\` and \`${id}\` share one key — a key identifies one factory`);
|
|
194
|
+
else keyOwner.set(blob, id);
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
const steward = str(raw.steward);
|
|
198
|
+
const stewards = Object.entries(factories).filter(([, f]) => f.tier === 'steward').map(([id]) => id);
|
|
199
|
+
if (typeof steward !== 'string' || !factories[steward]) findings.push(`steward must name a declared factory, got ${JSON.stringify(raw.steward ?? null)}`);
|
|
200
|
+
else if (factories[steward].tier !== 'steward') findings.push(`steward \`${steward}\` must have tier steward`);
|
|
201
|
+
if (stewards.length > 1) findings.push(`exactly one factory has tier steward, found ${stewards.map((s) => `\`${s}\``).join(', ')}`);
|
|
202
|
+
|
|
203
|
+
const stewardAreas = listOf(raw['steward-areas'], 'steward-areas', /^\S+$/, true, findings);
|
|
204
|
+
|
|
205
|
+
const doc = { version: raw.version, steward: steward || null, forge: forge || null, factories, stewardAreas };
|
|
206
|
+
return { valid: findings.length === 0, findings, doc };
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/** A parsed result, or null — the guard every lookup shares: invalid answers nobody. */
|
|
210
|
+
function usable(parsed) { return parsed && parsed.valid && parsed.doc ? parsed.doc : null; }
|
|
211
|
+
|
|
212
|
+
/** The factory a machine id belongs to, or null (unknown machine, or an invalid file). */
|
|
213
|
+
function factoryOfMachine(parsed, machine) {
|
|
214
|
+
const doc = usable(parsed);
|
|
215
|
+
if (!doc) return null;
|
|
216
|
+
for (const [id, f] of Object.entries(doc.factories)) if (f.machines.includes(machine)) return id;
|
|
217
|
+
return null;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** The factory owning a slice label (`slice:<name>`), or null. */
|
|
221
|
+
function factoryOfSlice(parsed, label) {
|
|
222
|
+
const doc = usable(parsed);
|
|
223
|
+
if (!doc) return null;
|
|
224
|
+
for (const [id, f] of Object.entries(doc.factories)) if (f.slices.includes(label)) return id;
|
|
225
|
+
return null;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/** Whether `login` counts as a human of `factory` (case-insensitive, as logins are). */
|
|
229
|
+
function isHumanOf(parsed, factory, login) {
|
|
230
|
+
const doc = usable(parsed);
|
|
231
|
+
const f = doc && doc.factories[factory];
|
|
232
|
+
return !!(f && login && f.humans.includes(String(login).toLowerCase()));
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* An OpenSSH allowed_signers file for one namespace: one line per factory, principal = factory id.
|
|
237
|
+
* Feed it to `ssh-keygen -Y verify -f` (verdicts, namespace `colab-verdict`) or set it as
|
|
238
|
+
* `gpg.ssh.allowedSignersFile` for `git verify-commit` (claim commits, namespace `git`).
|
|
239
|
+
* An invalid file yields an EMPTY list — nothing verifies, which is the fail-closed answer.
|
|
240
|
+
*/
|
|
241
|
+
function allowedSigners(parsed, namespace) {
|
|
242
|
+
const doc = usable(parsed);
|
|
243
|
+
if (!doc) return '';
|
|
244
|
+
return Object.entries(doc.factories)
|
|
245
|
+
.map(([id, f]) => `${id} namespaces="${namespace}" ${f.key.split(' ').slice(0, 2).join(' ')}\n`)
|
|
246
|
+
.join('');
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
const FIELD_VALUE_RE = /^[^\s=]+$/;
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* The canonical payload a verdict signature covers — the exact bytes, as a string:
|
|
253
|
+
*
|
|
254
|
+
* colab-verdict/1\n
|
|
255
|
+
* forge=<forge>\n repo=<owner/name>\n issue=<N>\n phase=<phase>\n verdict=<v>\n head=<sha40>\n factory=<id>\n
|
|
256
|
+
*
|
|
257
|
+
* (one field per line, no spaces, LF endings, a trailing LF). `ctx` = `{ forge, repo }` from the
|
|
258
|
+
* verifier's own context — the factories file's `forge` and the repository it is reading — never
|
|
259
|
+
* from the comment. `fields` = `{ issue, phase, verdict, head, factory }`: `issue` is the issue the
|
|
260
|
+
* comment sits on (the verifier's context again — the marker does not carry it), the rest from the
|
|
261
|
+
* marker.
|
|
262
|
+
* Throws on a field that cannot be encoded unambiguously; a signer and a verifier that disagree
|
|
263
|
+
* about bytes would make every signature fail, so there is no lenient mode.
|
|
264
|
+
*/
|
|
265
|
+
function verdictPayload(fields, ctx) {
|
|
266
|
+
const all = { forge: ctx && ctx.forge, repo: ctx && ctx.repo, ...(fields || {}) };
|
|
267
|
+
all.issue = all.issue == null ? all.issue : String(all.issue);
|
|
268
|
+
if (!/^[1-9][0-9]*$/.test(all.issue || '')) throw new TypeError(`verdictPayload: issue must be a positive integer, got ${JSON.stringify(all.issue)}`);
|
|
269
|
+
if (!/^[0-9a-f]{40}$/.test(all.head || '')) throw new TypeError(`verdictPayload: head must be a full 40-hex commit sha, got ${JSON.stringify(all.head)}`);
|
|
270
|
+
if (!VERDICTS.includes(all.verdict)) throw new TypeError(`verdictPayload: verdict must be one of ${VERDICTS.join(', ')}, got ${JSON.stringify(all.verdict)}`);
|
|
271
|
+
if (!FACTORY_ID_RE.test(all.factory || '')) throw new TypeError(`verdictPayload: factory ${JSON.stringify(all.factory)} is not a factory id`);
|
|
272
|
+
if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(all.repo || '')) throw new TypeError(`verdictPayload: repo must be owner/name, got ${JSON.stringify(all.repo)}`);
|
|
273
|
+
for (const k of PAYLOAD_FIELDS) {
|
|
274
|
+
if (typeof all[k] !== 'string' || !FIELD_VALUE_RE.test(all[k])) throw new TypeError(`verdictPayload: ${k} must be a non-empty value with no space or "=", got ${JSON.stringify(all[k])}`);
|
|
275
|
+
}
|
|
276
|
+
return `${PAYLOAD_HEADER}\n${PAYLOAD_FIELDS.map((k) => `${k}=${all[k]}`).join('\n')}\n`;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/** An armored SSH signature (`-----BEGIN SSH SIGNATURE-----` …) → the one-line `sig=` value. */
|
|
280
|
+
function sigFromArmor(armored) {
|
|
281
|
+
const body = String(armored || '').split(/\r?\n/).filter((l) => l && !/^-----(BEGIN|END) SSH SIGNATURE-----$/.test(l)).join('');
|
|
282
|
+
if (!/^[A-Za-z0-9+/]+={0,2}$/.test(body)) throw new TypeError('sigFromArmor: not an armored SSH signature');
|
|
283
|
+
return body;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/** The one-line `sig=` value → the armored form `ssh-keygen -Y verify -s` reads (70-column lines). */
|
|
287
|
+
function armorFromSig(sig) {
|
|
288
|
+
const s = String(sig || '');
|
|
289
|
+
const lines = s.match(/.{1,70}/g) || [];
|
|
290
|
+
return `-----BEGIN SSH SIGNATURE-----\n${lines.join('\n')}\n-----END SSH SIGNATURE-----\n`;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
const MARKER_RE = /^<!-- colab:verdict ((?:[a-z][a-z0-9_-]*=[^\s=]+=* ?)+)-->$/;
|
|
294
|
+
|
|
295
|
+
/** `{ phase, verdict, head, factory, sig, extra? }` → the marker. `extra` fields ride UNSIGNED. */
|
|
296
|
+
function encodeVerdictMarker({ phase, verdict, head, factory, sig, extra = {} }) {
|
|
297
|
+
const parts = [`phase=${phase}`, `v=${verdict}`, `head=${head}`, `factory=${factory}`];
|
|
298
|
+
for (const [k, v] of Object.entries(extra)) parts.push(`${k}=${v}`);
|
|
299
|
+
parts.push(`sig=${sig}`);
|
|
300
|
+
for (const p of parts) if (!/^[a-z][a-z0-9_-]*=[^\s=]+=*$/.test(p)) throw new TypeError(`encodeVerdictMarker: field ${JSON.stringify(p)} cannot be encoded`);
|
|
301
|
+
return `<!-- colab:verdict ${parts.join(' ')} -->`;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* One marker line → `{ phase, verdict, head, factory, sig, signed, extra }`, or null.
|
|
306
|
+
* `signed` is true only when it carries both `factory` and `sig` — an unsigned marker (the form
|
|
307
|
+
* written before #739) still decodes, and must never be read as any factory's word.
|
|
308
|
+
*/
|
|
309
|
+
function decodeVerdictMarker(line) {
|
|
310
|
+
const m = MARKER_RE.exec(String(line || '').trim());
|
|
311
|
+
if (!m) return null;
|
|
312
|
+
const f = {};
|
|
313
|
+
for (const tok of m[1].trim().split(' ')) {
|
|
314
|
+
const i = tok.indexOf('=');
|
|
315
|
+
f[tok.slice(0, i)] = tok.slice(i + 1);
|
|
316
|
+
}
|
|
317
|
+
const known = new Set(['phase', 'v', 'head', 'factory', 'sig']);
|
|
318
|
+
const extra = Object.fromEntries(Object.entries(f).filter(([k]) => !known.has(k)));
|
|
319
|
+
return { phase: f.phase || null, verdict: f.v || null, head: f.head || null, factory: f.factory || null,
|
|
320
|
+
sig: f.sig || null, signed: !!(f.factory && f.sig), extra };
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
module.exports = {
|
|
324
|
+
PATH, VERSION, TIERS, VERDICTS,
|
|
325
|
+
FACTORY_LABEL_PREFIX, SLICE_LABEL_PREFIX, QUEUE_READY_LABEL, REVIEW_LABEL_PREFIX, AUDIT_STATUS_CONTEXT,
|
|
326
|
+
VERDICT_NAMESPACE, CLAIM_NAMESPACE, PAYLOAD_HEADER, PAYLOAD_FIELDS,
|
|
327
|
+
reviewStatusContext, parseFactories, factoryOfMachine, factoryOfSlice, isHumanOf, allowedSigners,
|
|
328
|
+
verdictPayload, sigFromArmor, armorFromSig, encodeVerdictMarker, decodeVerdictMarker,
|
|
329
|
+
};
|