@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/_lib/provenance_verify.ts

@@ -0,0 +1,272 @@
+/**
+ * Tie a published version's provenance attestation to THIS package's OIDC
+ * publish workflow.
+ *
+ * The gate this replaces read `dist.attestations.provenance.predicateType` out
+ * of the packument and accepted anything starting with the SLSA provenance
+ * URL. That is a presence check wearing a verification's clothes: any workflow
+ * in any repository with `id-token: write` produces a document that passes it,
+ * so an attacker who can publish from their own CI already satisfies it. The
+ * step that opened this file (`road-to-an-update-that-installs-itself-only-when-it-is-safe`
+ * 2.1) named exactly that gap — *"does not verify the attestation's signature
+ * or tie it to `publish-npm.yml`"* — and this module closes the second half.
+ *
+ * **The first half is only partly closed here, and the distinction is
+ * load-bearing.** `provenance_matches_publish` parses an UNSIGNED reading of
+ * the DSSE payload. `verify_attestation_signature` below checks the envelope's
+ * signature against the certificate the bundle carries, and requires the
+ * payload it verified to name the same workflow — but checks no trust root
+ * (see its own note). The registry-key half is `npm audit signatures`, which
+ * verifies against npm's own trusted keys and is run by the caller as a
+ * separate step; these functions are only meaningful WITH it, and the caller
+ * says so where it composes them.
+ *
+ * Why not verify the signature in-process: it needs a sigstore/cosign
+ * verification path, which is a dependency this package does not carry and
+ * which the hook and pack byte budgets would both have to absorb. Shelling out
+ * to the npm client — already a hard dependency of an upgrade — buys the same
+ * property for nothing.
+ */
+
+/**
+ * The workflow path every legitimate release of this package is built by.
+ *
+ * A literal rather than a read of `.github/workflows/`: the question is which
+ * workflow the REGISTRY says produced the tarball, and answering it from the
+ * local tree would let a checkout vouch for itself.
+ */
+export const EXPECTED_WORKFLOW_REF = '.github/workflows/publish-npm.yml';
+
+/** The repository every legitimate release of this package is built from. */
+export const EXPECTED_REPOSITORY = 'https://github.com/event4u-app/agent-config';
+
+function asRecord(v: unknown): Record<string, unknown> | null {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+/** Decode the DSSE payload of the first attestation; `null` when unreadable. */
+function decode_payload(doc: unknown): Record<string, unknown> | null {
+    const list = asRecord(doc)?.['attestations'];
+    if (!Array.isArray(list) || list.length === 0) return null;
+    for (const entry of list) {
+        const payload = asRecord(asRecord(asRecord(entry)?.['bundle'])?.['dsseEnvelope'])?.['payload'];
+        if (typeof payload !== 'string' || payload === '') continue;
+        try {
+            const parsed: unknown = JSON.parse(Buffer.from(payload, 'base64').toString('utf8'));
+            const rec = asRecord(parsed);
+            if (rec !== null) return rec;
+        } catch {
+            // A payload that is not base64 JSON is not evidence of anything.
+            // Keep looking: npm may serve several attestations and only one of
+            // them has to be the provenance statement.
+        }
+    }
+    return null;
+}
+
+function external_workflow(doc: unknown): Record<string, unknown> | null {
+    const payload = decode_payload(doc);
+    if (payload === null) return null;
+    const predicate = asRecord(payload['predicate']);
+    const external = asRecord(asRecord(predicate?.['buildDefinition'])?.['externalParameters']);
+    return asRecord(external?.['workflow']);
+}
+
+/**
+ * The workflow path named by the attestation, or `null` when the document
+ * carries none that can be read.
+ */
+export function attestation_workflow_ref(doc: unknown): string | null {
+    const path_value = external_workflow(doc)?.['path'];
+    return typeof path_value === 'string' && path_value !== '' ? path_value : null;
+}
+
+/** The repository named by the attestation, or `null`. */
+export function attestation_repository(doc: unknown): string | null {
+    const repo = external_workflow(doc)?.['repository'];
+    return typeof repo === 'string' && repo !== '' ? repo : null;
+}
+
+/**
+ * Does this attestation say the tarball was built by this package's publish
+ * workflow, in this package's repository?
+ *
+ * Both halves are required and both reject on absence: a document that names
+ * no workflow is not a document that names the right one. Repository is
+ * compared with the trailing `.git` and any trailing slash removed, because
+ * the same remote is written both ways and neither spelling is an attacker
+ * signal.
+ */
+export function provenance_matches_publish(doc: unknown): boolean {
+    return payload_names_publish(decode_payload(doc));
+}
+
+/** The workflow and repository check, over one already-decoded payload. */
+function payload_names_publish(payload: Record<string, unknown> | null): boolean {
+    const predicate = asRecord(payload?.['predicate']);
+    const workflow = asRecord(asRecord(asRecord(predicate?.['buildDefinition'])?.['externalParameters'])?.['workflow']);
+    if (workflow?.['path'] !== EXPECTED_WORKFLOW_REF) return false;
+    const repo = workflow['repository'];
+    if (typeof repo !== 'string' || repo === '') return false;
+    return repo.replace(/\.git$/, '').replace(/\/$/, '') === EXPECTED_REPOSITORY;
+}
+
+/**
+ * Does the certificate's SAN carry the workflow identity as a whole URI entry?
+ * Anchored: the entry is the expected workflow followed by `@<ref>`, never a
+ * SAN that merely contains the string.
+ */
+function san_names_workflow(san: string): boolean {
+    return san.split(/,\s*/).some((e) => e.startsWith(`URI:${SAN_WORKFLOW_MARKER}@`));
+}
+
+// --- the signature half -------------------------------------------------------
+
+/**
+ * What the clauses below do and do not establish.
+ *
+ * The header above says the signature half is not closed here. It is now
+ * HALF-closed, and the half that is missing is stated first so nothing below
+ * reads as more than it is.
+ *
+ * **Closed:** the DSSE envelope's signature is verified against the public key
+ * of the certificate the bundle itself carries, over the DSSE
+ * pre-authentication encoding — so a payload edited after signing is caught,
+ * and a bundle whose signature does not belong to its own certificate is
+ * caught. And the certificate's own SAN is required to name the expected
+ * workflow, so a bundle whose PAYLOAD claims `publish-npm.yml` while its
+ * certificate was issued to some other identity is caught. Before this, both
+ * were a base64 decode and a string compare.
+ *
+ * **Not closed, and this is the residue:** there is no trust root. Nothing
+ * here checks that the certificate was issued by Fulcio, and nothing checks a
+ * Rekor inclusion proof. An attacker who can serve a registry response can mint
+ * a self-signed certificate carrying the expected SAN, sign their own payload
+ * with it, and pass every check in this file. Closing that needs a sigstore
+ * verification path with pinned roots — a dependency decision, not a line in
+ * this function, and it is registered as the `dsse-trust-root` blocker on
+ * `road-to-an-update-that-installs-itself-only-when-it-is-safe`.
+ *
+ * So the honest statement of what the provenance gate is worth today: it
+ * defeats a partial compromise — a mis-scoped workflow, an edited payload, a
+ * bundle reused from another build — and it does not defeat a forged bundle
+ * from someone who already controls what the install reads.
+ */
+
+/** Why the signature does not verify, or `null` when it does. */
+export type SignatureVerdict = string | null;
+
+/** The SAN extension OID the Fulcio leaf carries the workflow identity in. */
+const SAN_WORKFLOW_MARKER = `${EXPECTED_REPOSITORY}/${EXPECTED_WORKFLOW_REF}`;
+
+/**
+ * The DSSE pre-authentication encoding — the exact bytes a DSSE signature is
+ * taken over.
+ *
+ * `DSSEv1 SP len(payloadType) SP payloadType SP len(payload) SP payload`, with
+ * both lengths in BYTES rather than characters. Built as a Buffer throughout
+ * because the payload is arbitrary bytes and a string round-trip would mangle
+ * any that are not valid UTF-8.
+ */
+export function dssePae(payloadType: string, payload: Buffer): Buffer {
+    const type = Buffer.from(payloadType, 'utf8');
+    return Buffer.concat([
+        Buffer.from(`DSSEv1 ${String(type.length)} `, 'utf8'),
+        type,
+        Buffer.from(` ${String(payload.length)} `, 'utf8'),
+        payload,
+    ]);
+}
+
+interface Envelope {
+    readonly payloadType: string;
+    readonly payload: Buffer;
+    readonly sig: Buffer;
+    readonly certDer: Buffer;
+}
+
+function readEnvelope(entry: unknown): Envelope | null {
+    const bundle = asRecord(asRecord(entry)?.['bundle']);
+    const dsse = asRecord(bundle?.['dsseEnvelope']);
+    if (dsse === null) return null;
+    const payloadB64 = dsse['payload'];
+    const payloadType = dsse['payloadType'];
+    const sigs = dsse['signatures'];
+    if (typeof payloadB64 !== 'string' || typeof payloadType !== 'string' || !Array.isArray(sigs) || sigs.length === 0) return null;
+    const sigB64 = asRecord(sigs[0])?.['sig'];
+    if (typeof sigB64 !== 'string' || sigB64 === '') return null;
+
+    const material = asRecord(bundle?.['verificationMaterial']);
+    // Both shapes sigstore has used: a single certificate, and a chain.
+    const single = asRecord(material?.['certificate'])?.['rawBytes'];
+    const chain = asRecord(material?.['x509CertificateChain'])?.['certificates'];
+    const first = Array.isArray(chain) ? asRecord(chain[0])?.['rawBytes'] : undefined;
+    const certB64 = typeof single === 'string' ? single : typeof first === 'string' ? first : null;
+    if (certB64 === null || certB64 === '') return null;
+
+    return {
+        payloadType,
+        payload: Buffer.from(payloadB64, 'base64'),
+        sig: Buffer.from(sigB64, 'base64'),
+        certDer: Buffer.from(certB64, 'base64'),
+    };
+}
+
+/**
+ * Verify the first readable attestation's DSSE signature against its own
+ * certificate, and require that certificate to name this package's workflow.
+ *
+ * Returns a reason on every failure rather than a boolean, because the caller
+ * prints it: a refusal a user cannot act on is a refusal they route around.
+ * `crypto` is imported lazily so a caller that never verifies a signature does
+ * not pay for the module — this runs on an install path, never in a hook.
+ */
+export async function verify_attestation_signature(doc: unknown): Promise<SignatureVerdict> {
+    const list = asRecord(doc)?.['attestations'];
+    if (!Array.isArray(list) || list.length === 0) return 'the attestation bundle carries no attestations';
+    const crypto = await import('node:crypto');
+
+    let lastReason = 'no attestation carried a readable DSSE envelope';
+    for (const entry of list) {
+        const env = readEnvelope(entry);
+        if (env === null) continue;
+        let cert: InstanceType<typeof crypto.X509Certificate>;
+        try {
+            cert = new crypto.X509Certificate(env.certDer);
+        } catch {
+            lastReason = 'the signing certificate could not be parsed';
+            continue;
+        }
+        // The certificate's own identity, not the payload's claim about it.
+        const san = cert.subjectAltName ?? '';
+        if (!san_names_workflow(san)) {
+            lastReason = `the signing certificate names ${san === '' ? 'no identity' : san}, not ${SAN_WORKFLOW_MARKER}`;
+            continue;
+        }
+        let ok = false;
+        try {
+            ok = crypto.verify(null, dssePae(env.payloadType, env.payload), cert.publicKey, env.sig);
+        } catch {
+            ok = false;
+        }
+        if (!ok) {
+            lastReason = 'the DSSE signature does not verify against the certificate in the bundle';
+            continue;
+        }
+        // The payload this signature covers must itself name the workflow:
+        // otherwise a valid signature on one entry vouches for a claim made in
+        // another, which is all the unsigned check reads.
+        let verified: Record<string, unknown> | null = null;
+        try {
+            verified = asRecord(JSON.parse(env.payload.toString('utf8')));
+        } catch {
+            verified = null;
+        }
+        if (!payload_names_publish(verified)) {
+            lastReason = 'the signed payload does not name this package\'s publish workflow';
+            continue;
+        }
+        return null;
+    }
+    return lastReason;
+}

package/src/scripts/_lib/quota_parked.ts

@@ -42,6 +42,8 @@ export interface QuotaParkedMarker {
     /** Providers whose plan quota was exhausted, sorted and deduplicated. */
     readonly providers: string[];
     readonly parked_at: string;
+    /** Who established the exhaustion: the council's own seat gate, or the host's `StopFailure`. */
+    readonly source: 'council' | 'host';
 }
 
 /** Filesystem-safe path for a run's marker. Mirrors `billing_grant.grantFile`. */
@@ -58,21 +60,26 @@ export function markerFile(repoRoot: string, runId: string): string {
  *
  * Idempotent on the timestamp: a second park inside one run keeps the original
  * `parked_at` and merges the provider set, so "when did this run first hit the
- * cliff" survives a round that parks twice.
+ * cliff" survives a round that parks twice. A host park is the exception: it
+ * sets its own `source` and refreshes `parked_at`, since the host's rate window
+ * starts at its own signal, not at an earlier council park.
  */
 export function writeQuotaParked(
     repoRoot: string,
     runId: string,
     providers: readonly string[],
     now: () => Date = () => new Date(),
+    source: 'council' | 'host' = 'council',
 ): QuotaParkedMarker {
     const file = markerFile(repoRoot, runId);
     const existing = readMarker(file);
+    const host = source === 'host';
     const merged = [...new Set([...(existing?.providers ?? []), ...providers])].sort();
     const marker: QuotaParkedMarker = {
         run_id: runId,
         providers: merged,
-        parked_at: existing?.parked_at ?? now().toISOString(),
+        parked_at: (host ? null : existing?.parked_at) ?? now().toISOString(),
+        source: host ? source : (existing?.source ?? source),
     };
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
@@ -102,20 +109,27 @@ export function clearQuotaParked(repoRoot: string, runId: string): void {
  * per parked run, so the scan is cheap by construction.
  */
 export function findQuotaParked(repoRoot: string, sessionId: string): QuotaParkedMarker | null {
-    const direct = readMarker(markerFile(repoRoot, sessionId));
-    if (direct !== null) return direct;
-    let names: string[];
+    return readMarker(markerFile(repoRoot, sessionId)) ?? allMarkers(repoRoot).find((m) => m.run_id === sessionId) ?? null;
+}
+
+/** The plan's rolling rate window; a host marker older than this no longer describes it. */
+export const HOST_RATE_WINDOW_MS = 5 * 3_600_000;
+
+/** True when a host-sourced marker was parked inside the rate window ending at `nowMs`. */
+export function recentHostMarker(repoRoot: string, nowMs: number = Date.now(), windowMs: number = HOST_RATE_WINDOW_MS): boolean {
+    return allMarkers(repoRoot).some((m) => {
+        const age = nowMs - Date.parse(m.parked_at);
+        return m.source === 'host' && age >= 0 && age < windowMs;
+    });
+}
+
+function allMarkers(repoRoot: string): QuotaParkedMarker[] {
+    const dir = path.join(repoRoot, QUOTA_PARKED_DIR_REL);
     try {
-        names = fs.readdirSync(path.join(repoRoot, QUOTA_PARKED_DIR_REL));
+        return fs.readdirSync(dir).flatMap((n) => (n.endsWith('.json') ? (readMarker(path.join(dir, n)) ?? []) : []));
     } catch {
-        return null;
-    }
-    for (const name of names) {
-        if (!name.endsWith('.json')) continue;
-        const m = readMarker(path.join(repoRoot, QUOTA_PARKED_DIR_REL, name));
-        if (m !== null && m.run_id === sessionId) return m;
+        return [];
     }
-    return null;
 }
 
 function readMarker(file: string): QuotaParkedMarker | null {
@@ -126,7 +140,8 @@ function readMarker(file: string): QuotaParkedMarker | null {
         if (typeof o['run_id'] !== 'string' || typeof o['parked_at'] !== 'string') return null;
         if (!Array.isArray(o['providers'])) return null;
         const providers = o['providers'].filter((p): p is string => typeof p === 'string');
-        return { run_id: o['run_id'], providers, parked_at: o['parked_at'] };
+        const source = o['source'] === 'host' ? 'host' : 'council';
+        return { run_id: o['run_id'], providers, parked_at: o['parked_at'], source };
     } catch {
         return null;
     }

package/src/scripts/_lib/ratification_artifact.ts

@@ -84,6 +84,18 @@ export interface RatificationArtifact {
     verdict: RatificationVerdict;
     /** `merge`, or an ISO-8601 instant. Never a bare "later". */
     effective_after: string;
+    /**
+     * The digest of the gated content this record reviewed, or `null` on a
+     * record that carries none.
+     *
+     * Not in {@link RATIFICATION_FIELDS}: those six are required of every
+     * record, and the 23 records on the trunk predate this field. What makes
+     * it required in practice is the CALLER — `check_kernel_edit_ratified`
+     * passes an expected digest on every run, and a record with no `subject`
+     * then fails `subject-absent`. A record is only ever read as part of the
+     * diff it ships in, so nothing on the trunk is re-judged.
+     */
+    subject: string | null;
 }
 
 export interface RatificationProblem {
@@ -103,7 +115,10 @@ export interface RatificationProblem {
         | 'unknown-seat-verdict'
         | 'seat-dissent'
         | 'providers-exceed-seats'
-        | 'header-not-derived';
+        | 'header-not-derived'
+        | 'subject-absent'
+        | 'subject-malformed'
+        | 'subject-mismatch';
     message: string;
 }
 
@@ -322,6 +337,16 @@ export interface RatificationReading {
     problems: RatificationProblem[];
 }
 
+/**
+ * A `subject` digest: the lower-case hex sha-256 `subjectDigest` produces.
+ *
+ * Shape is checked apart from equality on purpose. A typo'd digest and a
+ * digest that moved because a gated file was edited after the review are
+ * different failures, and a reader that reported both as "mismatch" would
+ * send an author looking for an edit that never happened.
+ */
+export const SUBJECT_RE = /^[0-9a-f]{64}$/u;
+
 /** `merge`, or an ISO-8601 instant with a timezone. */
 const EFFECTIVE_AFTER_RE =
     /^(merge|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))$/;
@@ -364,10 +389,18 @@ export function readProviders(fm: AdrFrontmatter): string[] {
  * Pass `null` when it could not be established — the diversity rule then does
  * not fire, and the caller says so, because an unmeasured count is not
  * evidence that diversity was unavailable.
+ *
+ * `expectedSubject` is the digest of the gated content the record is being
+ * read against, recomputed from the tree by the caller. Pass `null` to read a
+ * record's shape without binding it to any content — which is what a reader
+ * that is not judging a diff does. Pass a digest and the record must carry
+ * `subject`, and carry that one: a record whose `subject` is absent or
+ * different did not review this content, whatever its verdict says.
  */
 export function readRatification(
     text: string,
     configuredProviders: number | null,
+    expectedSubject: string | null = null,
 ): RatificationReading {
     const problems: RatificationProblem[] = [];
     const fm = readAdrFrontmatter(text);
@@ -427,6 +460,35 @@ export function readRatification(
 
     problems.push(...seatProblems(readSeats(fm, text), providers, verdict));
 
+    // The content binding. Shape first, then equality, so a malformed digest is
+    // never reported as content that moved.
+    const subject = scalarOf(fm, 'subject');
+    if (subject !== null && !SUBJECT_RE.test(subject)) {
+        problems.push({
+            code: 'subject-malformed',
+            message:
+                `subject \`${subject}\` is not a sha-256 hex digest (${String(SUBJECT_RE)}) — ` +
+                'print it with `ratification_subject`',
+        });
+    } else if (expectedSubject !== null) {
+        if (subject === null) {
+            problems.push({
+                code: 'subject-absent',
+                message:
+                    'missing `subject:` — a record names who reviewed; without a digest it does not ' +
+                    `name WHAT, so the gated content may have changed since. Expected \`${expectedSubject}\``,
+            });
+        } else if (subject !== expectedSubject) {
+            problems.push({
+                code: 'subject-mismatch',
+                message:
+                    `subject \`${subject}\` is not the digest of this diff's gated content ` +
+                    `(\`${expectedSubject}\`) — the record reviewed different content, so it does not ` +
+                    'answer for this change',
+            });
+        }
+    }
+
     // Diversity, against the REQUIRED count.
     //
     // Round 1 refused the previous shape: the count came from the user-global
@@ -465,6 +527,7 @@ export function readRatification(
             providers,
             verdict: verdict as RatificationVerdict,
             effective_after: effective as string,
+            subject,
         },
         problems: [],
     };