src/provenance.ts

Functions

Imports

It imports src/job-touches.ts. Imported by src/deploy-outcomes.ts, src/jobs-claim.ts, src/jobs-holder.ts, src/stale-canon.ts, src/status.ts, src/watcher-detect.ts, src/whats-next.ts, src/workers-builds.ts.

Source

1import { actorKind } from "./job-touches";
2
3// PROVENANCE TAGS (OWASP hardening item 1). Text that
4// Capsid relays from outside it, into a job body or a message a driver reads, is wrapped
5// in a labelled fence so a reader can tell data from instruction:
6//
7//   ~~~external source=<kind> ref=<id>
8//   ...the relayed text...
9//   ~~~
10//
11// Tagged at the source, not detected: the places Capsid itself relays outside text are
12// few and enumerable (the watcher's evidence, a reviewer's words, and the claims export's
13// provenance field). `post` then refuses a body whose external fence is unbalanced or
14// lacks a source. It does NOT refuse text a human typed that looks like an instruction:
15// there is no reliable pattern, and a refusal nobody can predict teaches people to route
16// around the queue.
17
18const FENCE = "~~~";
19const OPEN = `${FENCE}external`;
20const SOURCE = /^[a-z][a-z0-9-]{0,31}$/;
21const MAX_REF = 120;
22
23/** `text` inside an external fence. A line of the text that would close or open a fence
24 *  is escaped with a backslash, so relayed text cannot end its own fence and speak outside
25 *  it. `maxText` cuts a long relay, marked, so a block reason stays inside its cap. */
26export function externalFence(source: string, ref: string, text: string, maxText = 4000): string {
27  if (!SOURCE.test(source)) throw new Error(`external fence source '${source}' must be lowercase letters, digits and hyphens`);
28  const cleanRef = ref.replace(/\s+/g, " ").trim().slice(0, MAX_REF) || "none";
29  const cut = text.length > maxText ? `${text.slice(0, maxText)} [truncated]` : text;
30  const body = cut.replace(/^([ \t]{0,3})(~{3,})/gm, (_match, indent: string, tildes: string) => `${indent}\\${tildes}`);
31  return `${OPEN} source=${source} ref=${cleanRef}\n${body}\n${FENCE}`;
32}
33
34/** Why a body's external fences are malformed, or null when they are well formed or
35 *  there are none. A fence needs a `source=<kind>`, may not open inside another, and must
36 *  close. A bare `~~~` outside an external fence is an ordinary code fence and is left
37 *  alone. */
38export function externalFenceProblem(text: string): string | null {
39  let openedAt = 0;
40  const lines = text.split(/\r?\n/);
41  for (let i = 0; i < lines.length; i++) {
42    const line = lines[i];
43    if (line.startsWith(OPEN)) {
44      if (openedAt) return `line ${i + 1} opens an external fence inside the one opened at line ${openedAt}`;
45      const source = /(?:^|\s)source=(\S+)/.exec(line)?.[1];
46      if (!source || !SOURCE.test(source)) return `the external fence at line ${i + 1} has no valid source=<kind> (lowercase letters, digits and hyphens)`;
47      openedAt = i + 1;
48    } else if (openedAt && /^~{3,}\s*$/.test(line)) {
49      openedAt = 0;
50    }
51  }
52  return openedAt ? `the external fence opened at line ${openedAt} is never closed` : null;
53}
54
55/** Who a posted job came from: the actor's kind from the one mapping every touch uses,
56 *  with the watcher named, since it is the one automatic poster. Recorded in the post's
57 *  audit row, not asserted by the caller. */
58export function jobOrigin(actor: string): string {
59  return actor === "agent:watcher" ? "watcher" : actorKind(actor);
60}