dorfl 0.14.2 → 0.15.0

package/dist/ci-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-handoff.d.ts","sourceRoot":"","sources":["../src/ci-handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAmBH,OAAO,EAMN,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,MAAM,wBAAwB,CAAC;AAEhC,uCAAuC;AACvC,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAC3C,sEAAsE;AACtE,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAC5C,sDAAsD;AACtD,eAAO,MAAM,eAAe,QAAQ,CAAC;AAYrC,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CA8B5D;AAgFD,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IACnC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC7B,GAAG;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAC,CA0BzB;AAkCD,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,6DAA6D;IAC7D,GAAG,EAAE,SAAS,CAAC;IACf,2EAA2E;IAC3E,MAAM,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAG,YAAY,CAAC;IACrD,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;CACpB,GAAG,WAAW,CAuFd"}

package/dist/ci-handoff.js

@@ -0,0 +1,277 @@
+/**
+ * **The CI handoff artifact on disk**: the writer (agent job) and the safe
+ * reader (apply job). The record format and its intent table are
+ * `ci-handoff-format.ts`.
+ *
+ * The artifact directory holds exactly:
+ *
+ *   - `handoff.json`: the record;
+ *   - `work.bundle`: for code-carrying intents only, `git bundle create
+ *     work.bundle <work-branch> ^<baseSha>`, exactly one ref;
+ *   - `lfs/<oid>`: the object of every LFS pointer the bundle's new commits
+ *     add or change (`ci-handoff-lfs.ts`; the reader here checks only their
+ *     names and sizes, the apply validation checks them against the pointers).
+ *
+ * The reader treats the directory as HOSTILE (the agent controls everything in
+ * its job): it must sit under `$RUNNER_TEMP`, only those names are read, a
+ * symlink or any other entry rejects the whole handoff, files are opened with
+ * `O_NOFOLLOW`, and every size limit is checked before anything is parsed. The
+ * bundle header is parsed here without running git on hostile bytes; the
+ * bundle's CONTENT (history, protected paths) is task
+ * `ci-split-apply-rejects-hostile-bundle`.
+ */
+import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { git } from './git.js';
+import { writeLfsObjects } from './ci-handoff-lfs.js';
+import { canonicalHandoffItem, handoffByteLimits, rejectHandoff as reject, validateHandoffRecord, } from './ci-handoff-format.js';
+/** The record file of the artifact. */
+export const HANDOFF_JSON = 'handoff.json';
+/** The git bundle of the work branch (code-carrying intents only). */
+export const HANDOFF_BUNDLE = 'work.bundle';
+/** The directory of LFS objects, one file per oid. */
+export const HANDOFF_LFS_DIR = 'lfs';
+/** The most a bundle header (signature, capabilities, prerequisites, one ref) may take. */
+const MAX_BUNDLE_HEADER_BYTES = 64 * 1024;
+const HEX_OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const LFS_OID = /^[0-9a-f]{64}$/;
+/**
+ * Parse the header of a git bundle (v2, or v3 with only `@object-format`)
+ * without running git, and require exactly one ref.
+ */
+export function parseBundleHeader(head) {
+    const end = head.indexOf('\n\n');
+    if (end === -1)
+        reject('bundle-format', 'no bundle header terminator');
+    const lines = head.subarray(0, end).toString('latin1').split('\n');
+    const signature = lines.shift();
+    const v3 = signature === '# v3 git bundle';
+    if (signature !== '# v2 git bundle' && !v3) {
+        reject('bundle-format', 'not a v2 or v3 git bundle');
+    }
+    const prerequisites = [];
+    const refs = [];
+    for (const l of lines) {
+        if (l.startsWith('@')) {
+            if (!v3 || !/^@object-format=(?:sha1|sha256)$/.test(l)) {
+                reject('bundle-format', 'unsupported bundle capability');
+            }
+        }
+        else if (l.startsWith('-')) {
+            const oid = l.slice(1).split(' ', 1)[0];
+            if (!HEX_OID.test(oid))
+                reject('bundle-format', 'bad prerequisite line');
+            prerequisites.push(oid);
+        }
+        else {
+            const m = /^([0-9a-f]{40}|[0-9a-f]{64}) (refs\/[\x21-\x7e]+)$/.exec(l);
+            if (m === null)
+                reject('bundle-format', 'bad bundle ref line');
+            refs.push({ tip: m[1], ref: m[2] });
+        }
+    }
+    if (refs.length !== 1) {
+        reject('bundle-refs', `the bundle carries ${refs.length} refs, not 1`);
+    }
+    return { ...refs[0], prerequisites };
+}
+// ---------------------------------------------------------------------------
+// Low-level safe reads
+// ---------------------------------------------------------------------------
+/** Open a path for reading, refusing a symlink at open time (`O_NOFOLLOW`). */
+function openNoFollow(path, name) {
+    try {
+        return openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch {
+        reject('symlink', `${name} could not be opened as a regular file`);
+    }
+}
+/**
+ * Read a regular file of at most `max` bytes (whole, or only its first
+ * `headOnly` bytes), refusing a symlink and re-checking the size on the open
+ * descriptor so a file swapped after the directory scan is still bounded.
+ */
+function readBounded(path, name, max, headOnly) {
+    const fd = openNoFollow(path, name);
+    try {
+        const st = fstatSync(fd);
+        if (!st.isFile())
+            reject('layout', `${name} is not a regular file`);
+        if (st.size > max)
+            reject('size', `${name} is over ${max} bytes`);
+        const want = headOnly ?? max + 1;
+        const buf = Buffer.alloc(Math.min(want, st.size + 1));
+        const n = readSync(fd, buf, 0, buf.length, 0);
+        if (headOnly === undefined && n > max) {
+            reject('size', `${name} is over ${max} bytes`);
+        }
+        return buf.subarray(0, n);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** `lstat` an entry; refuse a symlink or an entry of the wrong type. */
+function entryStat(path, name, want) {
+    const st = lstatSync(path);
+    if (st.isSymbolicLink())
+        reject('symlink', `${name} is a symlink`);
+    const ok = want === 'file' ? st.isFile() : st.isDirectory();
+    if (!ok) {
+        reject('layout', `${name} is not a ${want === 'file' ? 'file' : 'directory'}`);
+    }
+    return st;
+}
+function isStrictlyInside(root, path) {
+    const rel = relative(root, path);
+    return (rel !== '' &&
+        rel !== '..' &&
+        !rel.startsWith(`..${sep}`) &&
+        !isAbsolute(rel));
+}
+function checkBundlePresence(row, present) {
+    if (row.bundle.rule === 'required' && !present) {
+        reject('bundle-presence', `${row.kind} needs ${HANDOFF_BUNDLE}`);
+    }
+    if (row.bundle.rule === 'none' && present) {
+        reject('bundle-presence', `${row.kind} carries no ${HANDOFF_BUNDLE}`);
+    }
+}
+/**
+ * Write the handoff into `dir` (created, and required to be empty): validate
+ * the record exactly as the reader will, then write `handoff.json` and, for a
+ * code-carrying intent, `work.bundle` with exactly one ref, and `lfs/<oid>` for
+ * the object of every LFS pointer its new commits add or change (from the
+ * local store; one the store lacks is left out and returned in `lfsMissing`,
+ * and the apply job then rejects the handoff naming it). The record's item is
+ * written in its canonical form.
+ */
+export function writeHandoff(params) {
+    const { dir, rung, bundle } = params;
+    const item = canonicalHandoffItem(params.record.item);
+    const json = JSON.stringify({ ...params.record, item });
+    const { row } = validateHandoffRecord(JSON.parse(json), { item, rung });
+    checkBundlePresence(row, bundle !== undefined);
+    if (Buffer.byteLength(json) > handoffByteLimits().handoffJsonBytes) {
+        reject('size', `${HANDOFF_JSON} is over ${handoffByteLimits().handoffJsonBytes} bytes`);
+    }
+    mkdirSync(dir, { recursive: true });
+    if (readdirSync(dir).length > 0) {
+        reject('layout', `the handoff directory ${dir} is not empty`);
+    }
+    writeFileSync(join(dir, HANDOFF_JSON), json);
+    if (bundle === undefined)
+        return { lfsMissing: [] };
+    writeBundle(dir, bundle);
+    const { missing } = writeLfsObjects({
+        dir,
+        repo: bundle.repo,
+        ref: `refs/heads/${bundle.workBranch}`,
+        baseSha: bundle.baseSha,
+    });
+    return { lfsMissing: missing };
+}
+/** `git bundle create work.bundle refs/heads/<branch> ^<baseSha>`, then check it. */
+function writeBundle(dir, source) {
+    if (!HEX_OID.test(source.baseSha)) {
+        reject('bundle-format', 'baseSha is not a full commit id');
+    }
+    const ref = `refs/heads/${source.workBranch}`;
+    git(['check-ref-format', ref], source.repo);
+    const out = join(dir, HANDOFF_BUNDLE);
+    git(['bundle', 'create', out, ref, `^${source.baseSha}`], source.repo);
+    const header = parseBundleHeader(readBounded(out, HANDOFF_BUNDLE, Number.MAX_SAFE_INTEGER, MAX_BUNDLE_HEADER_BYTES));
+    if (header.ref !== ref) {
+        reject('bundle-refs', `the bundle carries ${header.ref}, not ${ref}`);
+    }
+    if (statSync(out).size > handoffByteLimits().bundleBytes) {
+        reject('size', `${HANDOFF_BUNDLE} is over ${handoffByteLimits().bundleBytes} bytes`);
+    }
+}
+/**
+ * Read and validate the handoff the agent job uploaded. `dir` is where the
+ * artifact was downloaded: a real directory strictly inside `runnerTemp`
+ * (`$RUNNER_TEMP`). Rejects ({@link HandoffRejected}) a symlink anywhere, any
+ * entry but `handoff.json`, `work.bundle` and `lfs/<64-hex oid>`, any size over
+ * the byte limits (`handoffByteLimits`), a record that fails `validateHandoffRecord`, a bundle
+ * the intent forbids or lacks, `lfs/` without a bundle, and a bundle whose
+ * header is malformed or carries other than one ref.
+ */
+export function readHandoff(params) {
+    const { dir, runnerTemp, trust } = params;
+    const rootStat = lstatSync(dir, { throwIfNoEntry: false });
+    if (rootStat === undefined) {
+        reject('layout', 'the handoff directory is missing');
+    }
+    if (rootStat.isSymbolicLink()) {
+        reject('symlink', 'the handoff directory is a symlink');
+    }
+    if (!rootStat.isDirectory()) {
+        reject('layout', 'the handoff path is not a directory');
+    }
+    if (!isStrictlyInside(realpathSync(runnerTemp), realpathSync(dir))) {
+        reject('location', 'the handoff directory is not under $RUNNER_TEMP');
+    }
+    let total = 0;
+    let hasJson = false;
+    let hasBundle = false;
+    let lfsTotal = 0;
+    const lfsObjects = [];
+    for (const name of readdirSync(dir)) {
+        const path = join(dir, name);
+        if (name === HANDOFF_JSON) {
+            total += entryStat(path, name, 'file').size;
+            hasJson = true;
+        }
+        else if (name === HANDOFF_BUNDLE) {
+            total += entryStat(path, name, 'file').size;
+            hasBundle = true;
+        }
+        else if (name === HANDOFF_LFS_DIR) {
+            entryStat(path, name, 'dir');
+            for (const oid of readdirSync(path)) {
+                const objName = `${HANDOFF_LFS_DIR}/${JSON.stringify(oid).slice(0, 80)}`;
+                if (!LFS_OID.test(oid))
+                    reject('layout', `unexpected entry ${objName}`);
+                const objPath = join(path, oid);
+                const size = entryStat(objPath, objName, 'file').size;
+                lfsTotal += size;
+                lfsObjects.push({ oid, path: objPath, size });
+            }
+        }
+        else {
+            reject('layout', `unexpected entry ${JSON.stringify(name).slice(0, 80)}`);
+        }
+    }
+    if (!hasJson)
+        reject('layout', `${HANDOFF_JSON} is missing`);
+    if (lfsTotal > handoffByteLimits().lfsBytes) {
+        reject('size', `the LFS objects are over ${handoffByteLimits().lfsBytes} bytes`);
+    }
+    total += lfsTotal;
+    if (total > handoffByteLimits().artifactBytes) {
+        reject('size', `the artifact is over ${handoffByteLimits().artifactBytes} bytes`);
+    }
+    if (lfsObjects.length > 0 && !hasBundle) {
+        reject('layout', `${HANDOFF_LFS_DIR}/ without ${HANDOFF_BUNDLE}`);
+    }
+    const raw = readBounded(join(dir, HANDOFF_JSON), HANDOFF_JSON, handoffByteLimits().handoffJsonBytes);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString('utf8'));
+    }
+    catch {
+        reject('json', `${HANDOFF_JSON} is not valid JSON`);
+    }
+    const { record, row } = validateHandoffRecord(parsed, trust);
+    checkBundlePresence(row, hasBundle);
+    let bundle;
+    if (hasBundle) {
+        const path = join(dir, HANDOFF_BUNDLE);
+        const head = readBounded(path, HANDOFF_BUNDLE, handoffByteLimits().bundleBytes, MAX_BUNDLE_HEADER_BYTES);
+        bundle = { path, size: lstatSync(path).size, ...parseBundleHeader(head) };
+    }
+    return { record, row, bundle, lfsObjects };
+}
+//# sourceMappingURL=ci-handoff.js.map

package/dist/ci-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-handoff.js","sourceRoot":"","sources":["../src/ci-handoff.ts"],"names":[],"mappings":"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"}

package/dist/ci-lock-outputs.d.ts

@@ -0,0 +1,93 @@
+/**
+ * **The lock job's `$GITHUB_OUTPUT` facts** (spec
+ * `ci-agent-job-without-write-token`).
+ *
+ * The lock job's outputs are the apply job's TRUSTED channel
+ * (`needs.lock.outputs.*`): they choose refs, rungs and artifact names. So the
+ * serializer emits only values that cannot carry attacker text: commit ids,
+ * enums, booleans, bounded integers (the agent timeout), provider-assigned
+ * comment ids and the dorfl-derived artifact name. Every key is known here with its type, and every
+ * value is re-checked at runtime (a TypeScript type does not stop a string read
+ * from an issue), so free text such as an issue title is REFUSED, never
+ * escaped.
+ */
+import type { IntegrationMode } from './config.js';
+import { type HandoffRung } from './ci-handoff-format.js';
+/** The facts a lock job publishes (task `ci-split-generate-workflows` lists them). */
+export interface LockOutputs {
+    /** Whether the lock job took the item's locks. */
+    acquired?: boolean;
+    /** `false` when the rung runs no agent (decision 11). */
+    needsAgent?: boolean;
+    /** The classified rung. */
+    rung?: HandoffRung;
+    /** The arbiter's `main` tip the item was classified against. */
+    baseSha?: string;
+    /** The lock ref's sha after the acquire. */
+    lockSha?: string;
+    /** The kept work branch's tip, when one exists (decision 7). */
+    continueTip?: string;
+    /** The artifact name (`handoffName`). */
+    handoffName?: string;
+    /** The agent job's timeout, from `dorfl.json` at `baseSha`. */
+    agentTimeoutMinutes?: number;
+    /** The intake origin trust. */
+    originTrust?: 'trusted' | 'untrusted';
+    /** The intake document mode. */
+    documentMode?: IntegrationMode;
+    /**
+     * The issue comment ids the lock job read (intake), as the issue provider
+     * reports them: a REST database id (a positive integer) or a GraphQL node id
+     * (`IC_kwDO...`, what `gh issue view --json comments` reports). A parsed
+     * integer id stays a number; a node id is a string.
+     */
+    seenCommentIds?: Array<number | string>;
+}
+/** A lock output the serializer will not emit. */
+export declare class LockOutputRefused extends Error {
+    constructor(message: string);
+}
+/** The largest agent timeout accepted (GitHub's self-hosted job maximum: 5 days). */
+export declare const MAX_AGENT_TIMEOUT_MINUTES = 7200;
+/** The most comment ids one output may list. */
+export declare const MAX_SEEN_COMMENT_IDS = 5000;
+/**
+ * Every lock output key, in output order. The generated lock job declares
+ * exactly these as its job `outputs` (task `ci-split-generate-workflows`), so
+ * `toJSON(needs.lock.outputs)` carries no key {@link parseLockOutputs} refuses.
+ */
+export declare const LOCK_OUTPUT_KEYS: ReadonlyArray<keyof LockOutputs>;
+/**
+ * Serialize lock facts as `$GITHUB_OUTPUT` lines (`key=value\n`, in a fixed
+ * order; an `undefined` fact is omitted). Throws {@link LockOutputRefused} for
+ * an unknown key or any value outside its type, so free text never reaches the
+ * trusted channel.
+ */
+export declare function serializeLockOutputs(facts: LockOutputs): string;
+/**
+ * The environment variable the agent and apply jobs receive the lock job's
+ * outputs in: the JSON object `toJSON(needs.lock.outputs)` (every value a
+ * string, an unset output an empty string), passed through `env:` like every
+ * other value that reaches a `run:` script.
+ */
+export declare const LOCK_OUTPUTS_ENV = "DORFL_LOCK_OUTPUTS";
+/**
+ * Parse the lock job's outputs as the agent and apply jobs receive them (a
+ * `key -> string` object), re-checking every value with the same rules
+ * {@link serializeLockOutputs} applied. An empty string is an unset output
+ * (GitHub renders an output the job never wrote as `''`). Throws
+ * {@link LockOutputRefused} for an unknown key or a malformed value.
+ */
+export declare function parseLockOutputs(raw: unknown): LockOutputs;
+/**
+ * Parse `$GITHUB_OUTPUT` lines as {@link serializeLockOutputs} writes them
+ * (`key=value`, one per line), for tests and local replays of the lock job.
+ */
+export declare function parseLockOutputLines(text: string): LockOutputs;
+/**
+ * Read the lock job's outputs from {@link LOCK_OUTPUTS_ENV}. Throws
+ * {@link LockOutputRefused} when it is missing or malformed: the agent and
+ * apply phases act on nothing but these trusted facts.
+ */
+export declare function readLockOutputsFromEnv(env: NodeJS.ProcessEnv): LockOutputs;
+//# sourceMappingURL=ci-lock-outputs.d.ts.map

package/dist/ci-lock-outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-lock-outputs.d.ts","sourceRoot":"","sources":["../src/ci-lock-outputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AACjD,OAAO,EAGN,KAAK,WAAW,EAChB,MAAM,wBAAwB,CAAC;AAEhC,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yDAAyD;IACzD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+BAA+B;IAC/B,WAAW,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IACtC,gCAAgC;IAChC,YAAY,CAAC,EAAE,eAAe,CAAC;IAC/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CACxC;AAED,kDAAkD;AAClD,qBAAa,iBAAkB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI3B;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C,gDAAgD;AAChD,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAyEzC;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAA0B,aAAa,CACnE,MAAM,WAAW,CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAa/D;AAMD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAuCrD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAc1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAS9D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,WAAW,CAc1E"}

package/dist/ci-lock-outputs.js

@@ -0,0 +1,223 @@
+/**
+ * **The lock job's `$GITHUB_OUTPUT` facts** (spec
+ * `ci-agent-job-without-write-token`).
+ *
+ * The lock job's outputs are the apply job's TRUSTED channel
+ * (`needs.lock.outputs.*`): they choose refs, rungs and artifact names. So the
+ * serializer emits only values that cannot carry attacker text: commit ids,
+ * enums, booleans, bounded integers (the agent timeout), provider-assigned
+ * comment ids and the dorfl-derived artifact name. Every key is known here with its type, and every
+ * value is re-checked at runtime (a TypeScript type does not stop a string read
+ * from an issue), so free text such as an issue title is REFUSED, never
+ * escaped.
+ */
+import { HANDOFF_NAME_RE, HANDOFF_RUNGS, } from './ci-handoff-format.js';
+/** A lock output the serializer will not emit. */
+export class LockOutputRefused extends Error {
+    constructor(message) {
+        super(`lock output refused: ${message}`);
+        this.name = 'LockOutputRefused';
+    }
+}
+/** The largest agent timeout accepted (GitHub's self-hosted job maximum: 5 days). */
+export const MAX_AGENT_TIMEOUT_MINUTES = 7200;
+/** The most comment ids one output may list. */
+export const MAX_SEEN_COMMENT_IDS = 5000;
+const SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+/**
+ * A GitHub GraphQL node id (`IC_kwDODKw3uc7tpgEC`): an upper-case type prefix,
+ * `_`, then URL-safe base64. Assigned by GitHub, never chosen by an issue
+ * author; the charset holds no `,` (the list separator), `=`, space or line
+ * break, so it cannot forge another output line.
+ */
+const NODE_ID_RE = /^[A-Z]{1,8}_[A-Za-z0-9_-]{1,80}$/;
+function refuse(key, why) {
+    throw new LockOutputRefused(`${key} ${why}`);
+}
+function boolean(key, v) {
+    if (typeof v !== 'boolean')
+        refuse(key, 'is not a boolean');
+    return String(v);
+}
+function sha(key, v) {
+    if (typeof v !== 'string' || !SHA_RE.test(v)) {
+        refuse(key, 'is not a full lower-case commit id');
+    }
+    return v;
+}
+function oneOf(values) {
+    return (key, v) => {
+        if (typeof v !== 'string' || !values.includes(v)) {
+            refuse(key, `is not one of ${values.join(', ')}`);
+        }
+        return v;
+    };
+}
+function integer(min, max) {
+    return (key, v) => {
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < min || v > max) {
+            refuse(key, `is not an integer in ${min}..${max}`);
+        }
+        return String(v);
+    };
+}
+/** Every key, in output order, with its value check. */
+const SCHEMA = {
+    acquired: boolean,
+    needsAgent: boolean,
+    rung: oneOf(HANDOFF_RUNGS),
+    baseSha: sha,
+    lockSha: sha,
+    continueTip: sha,
+    handoffName: (key, v) => {
+        if (typeof v !== 'string' || !HANDOFF_NAME_RE.test(v)) {
+            refuse(key, 'is not a dorfl handoff artifact name');
+        }
+        return v;
+    },
+    agentTimeoutMinutes: integer(1, MAX_AGENT_TIMEOUT_MINUTES),
+    originTrust: oneOf(['trusted', 'untrusted']),
+    documentMode: oneOf(['propose', 'merge']),
+    seenCommentIds: (key, v) => {
+        if (!Array.isArray(v) || v.length > MAX_SEEN_COMMENT_IDS) {
+            refuse(key, `is not a list of at most ${MAX_SEEN_COMMENT_IDS} ids`);
+        }
+        const check = integer(1, Number.MAX_SAFE_INTEGER);
+        return v
+            .map((id) => typeof id === 'string' && NODE_ID_RE.test(id) ? id : check(key, id))
+            .join(',');
+    },
+};
+/**
+ * Every lock output key, in output order. The generated lock job declares
+ * exactly these as its job `outputs` (task `ci-split-generate-workflows`), so
+ * `toJSON(needs.lock.outputs)` carries no key {@link parseLockOutputs} refuses.
+ */
+export const LOCK_OUTPUT_KEYS = Object.keys(SCHEMA);
+/**
+ * Serialize lock facts as `$GITHUB_OUTPUT` lines (`key=value\n`, in a fixed
+ * order; an `undefined` fact is omitted). Throws {@link LockOutputRefused} for
+ * an unknown key or any value outside its type, so free text never reaches the
+ * trusted channel.
+ */
+export function serializeLockOutputs(facts) {
+    for (const key of Object.keys(facts)) {
+        if (!Object.hasOwn(SCHEMA, key)) {
+            refuse(JSON.stringify(key).slice(0, 80), 'is not a lock output');
+        }
+    }
+    let out = '';
+    for (const [key, check] of Object.entries(SCHEMA)) {
+        const v = facts[key];
+        if (v === undefined)
+            continue;
+        out += `${key}=${check(key, v)}\n`;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Reading the facts back (the agent and apply jobs)
+// ---------------------------------------------------------------------------
+/**
+ * The environment variable the agent and apply jobs receive the lock job's
+ * outputs in: the JSON object `toJSON(needs.lock.outputs)` (every value a
+ * string, an unset output an empty string), passed through `env:` like every
+ * other value that reaches a `run:` script.
+ */
+export const LOCK_OUTPUTS_ENV = 'DORFL_LOCK_OUTPUTS';
+const PARSE = {
+    acquired: parseBoolean,
+    needsAgent: parseBoolean,
+    rung: (key, raw) => {
+        SCHEMA.rung(key, raw);
+        return raw;
+    },
+    baseSha: (key, raw) => sha(key, raw),
+    lockSha: (key, raw) => sha(key, raw),
+    continueTip: (key, raw) => sha(key, raw),
+    handoffName: (key, raw) => SCHEMA.handoffName(key, raw),
+    agentTimeoutMinutes: (key, raw) => {
+        const n = /^[0-9]{1,9}$/.test(raw) ? Number(raw) : Number.NaN;
+        SCHEMA.agentTimeoutMinutes(key, n);
+        return n;
+    },
+    originTrust: (key, raw) => SCHEMA.originTrust(key, raw),
+    documentMode: (key, raw) => SCHEMA.documentMode(key, raw),
+    seenCommentIds: (key, raw) => {
+        const ids = raw.split(',').map((part) => {
+            if (NODE_ID_RE.test(part))
+                return part;
+            if (!/^[0-9]{1,16}$/.test(part)) {
+                refuse(key, 'is not a comma-separated list of ids');
+            }
+            return Number(part);
+        });
+        SCHEMA.seenCommentIds(key, ids);
+        return ids;
+    },
+};
+function parseBoolean(key, raw) {
+    if (raw !== 'true' && raw !== 'false')
+        refuse(key, 'is not a boolean');
+    return raw === 'true';
+}
+/**
+ * Parse the lock job's outputs as the agent and apply jobs receive them (a
+ * `key -> string` object), re-checking every value with the same rules
+ * {@link serializeLockOutputs} applied. An empty string is an unset output
+ * (GitHub renders an output the job never wrote as `''`). Throws
+ * {@link LockOutputRefused} for an unknown key or a malformed value.
+ */
+export function parseLockOutputs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new LockOutputRefused('the lock outputs are not an object');
+    }
+    const facts = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!Object.hasOwn(PARSE, key)) {
+            refuse(JSON.stringify(key).slice(0, 80), 'is not a lock output');
+        }
+        if (value === '' || value === undefined || value === null)
+            continue;
+        if (typeof value !== 'string')
+            refuse(key, 'is not a string');
+        facts[key] = PARSE[key](key, value);
+    }
+    return facts;
+}
+/**
+ * Parse `$GITHUB_OUTPUT` lines as {@link serializeLockOutputs} writes them
+ * (`key=value`, one per line), for tests and local replays of the lock job.
+ */
+export function parseLockOutputLines(text) {
+    const raw = {};
+    for (const line of text.split('\n')) {
+        if (line === '')
+            continue;
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            throw new LockOutputRefused('a line is not key=value');
+        raw[line.slice(0, eq)] = line.slice(eq + 1);
+    }
+    return parseLockOutputs(raw);
+}
+/**
+ * Read the lock job's outputs from {@link LOCK_OUTPUTS_ENV}. Throws
+ * {@link LockOutputRefused} when it is missing or malformed: the agent and
+ * apply phases act on nothing but these trusted facts.
+ */
+export function readLockOutputsFromEnv(env) {
+    const raw = env[LOCK_OUTPUTS_ENV];
+    if (raw === undefined || raw.trim() === '') {
+        throw new LockOutputRefused(`${LOCK_OUTPUTS_ENV} is not set (the lock job's outputs, as JSON)`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new LockOutputRefused(`${LOCK_OUTPUTS_ENV} is not valid JSON`);
+    }
+    return parseLockOutputs(parsed);
+}
+//# sourceMappingURL=ci-lock-outputs.js.map

package/dist/ci-lock-outputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-lock-outputs.js","sourceRoot":"","sources":["../src/ci-lock-outputs.ts"],"names":[],"mappings":"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"}