@dogfood-lab/verify 1.4.0 → 1.6.0

package/validators/provenance-registry.test.js

@@ -0,0 +1,56 @@
+/**
+ * provenance-registry.test.js — provenance adapter coverage (peer of repo-binding.test.js)
+ *
+ * The forgery-vector tripwire in repo-binding.test.js asserts every
+ * `source.provider` enum member has a run_url PARSER. This file closes the other
+ * half of the same discipline: every provider must ALSO have a provenance
+ * ADAPTER in PROVENANCE_ADAPTERS. A provider with a parser but no adapter would
+ * be selectable at the binding layer yet un-confirmable at the provenance layer
+ * — submissions for it would fail closed with an opaque "no adapter" path. The
+ * coverage test reads the ACTUAL provider enum from the canonical submission
+ * schema, so adding a provider without an adapter goes RED in CI.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+import { PROVENANCE_ADAPTERS, provenanceForProvider, githubProvenance, gitlabProvenance } from './provenance.js';
+
+const require = createRequire(import.meta.url);
+const schemaPath = require.resolve(
+  '@dogfood-lab/schemas/json/dogfood-record-submission.schema.json'
+);
+const submissionSchema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+const PROVIDER_ENUM = submissionSchema.properties.source.properties.provider.enum;
+
+describe('provenance adapter coverage', () => {
+  it('exposes the provider enum it is meant to cover (sanity)', () => {
+    assert.ok(Array.isArray(PROVIDER_ENUM) && PROVIDER_ENUM.length > 0);
+    assert.ok(PROVIDER_ENUM.includes('github'));
+    assert.ok(PROVIDER_ENUM.includes('gitlab'));
+  });
+
+  it('has a provenance adapter factory for EVERY registered source.provider', () => {
+    const missing = PROVIDER_ENUM.filter(p => typeof PROVENANCE_ADAPTERS[p] !== 'function');
+    assert.deepEqual(
+      missing,
+      [],
+      `source.provider enum members without a PROVENANCE_ADAPTERS factory: ${missing.join(', ')}. ` +
+        'Add an adapter in validators/provenance.js or provenance falls closed for these providers ' +
+        'with no confirmation path.'
+    );
+  });
+
+  it('provenanceForProvider returns the matching factory', () => {
+    assert.equal(PROVENANCE_ADAPTERS.github, githubProvenance);
+    assert.equal(PROVENANCE_ADAPTERS.gitlab, gitlabProvenance);
+    assert.equal(provenanceForProvider('github'), githubProvenance);
+    assert.equal(provenanceForProvider('gitlab'), gitlabProvenance);
+  });
+
+  it('provenanceForProvider returns null for an unknown provider (no throw)', () => {
+    assert.equal(provenanceForProvider('bitbucket'), null);
+  });
+});

package/validators/provenance.js

@@ -2,9 +2,18 @@
  * Provenance adapters
  *
  * The verifier checks that a source run actually exists and matches claims.
- * Two adapters:
- * - stub: always confirms (for tests and local development)
- * - github: confirms via GitHub Actions API (for production)
+ * Adapters:
+ * - stub:      always confirms (for tests and local development)
+ * - github:    confirms via the GitHub Actions API (production)
+ * - gitlab:    confirms via the GitLab CI API (production)
+ *
+ * The two real adapters are PEERS — same hardening discipline (per-request
+ * timeout, 404-only-false, throw-on-operational, finished-state assertion, and
+ * the verify-A-001 commit-binding anti-forgery guard). Production code selects
+ * the adapter for a submission via {@link provenanceForProvider}, keyed on
+ * `source.provider`, so the provider enum, the run_url parsers
+ * (validators/repo-binding.js), and the adapters here stay in lockstep —
+ * coverage tests fail CI if any of the three drifts.
  */
 
 /**
@@ -16,6 +25,72 @@
  */
 export const GITHUB_PROVENANCE_TIMEOUT_MS = 30000;
 
+/**
+ * Default per-request timeout for the GitLab provenance fetch. Same rationale
+ * as the GitHub guard — a hung gitlab.com/api call must not block ingest.
+ */
+export const GITLAB_PROVENANCE_TIMEOUT_MS = 30000;
+
+/**
+ * Default RETRY budget for a transient provider fault (HTTP 429 rate-limit or a
+ * 5xx provider outage). PROACT-VERIFY-001: a single 429/5xx during a momentary
+ * blip used to fail the whole submission as an operational incident even though
+ * one retry would have confirmed the run. We retry a BOUNDED number of times
+ * with exponential backoff (honoring `Retry-After` when the provider sends it),
+ * then THROW on exhaustion so a genuinely-down provider still surfaces as an
+ * operational signal — never a false 'confirmed'. 404 is NOT retried (the run is
+ * genuinely absent, a single immediate rejection).
+ *
+ * `retries` is the number of ADDITIONAL attempts after the first, so the default
+ * 2 means up to 3 total requests. It is an opts field (like `timeoutMs`) so it
+ * stays test-injectable and the offline stub path is unaffected.
+ */
+export const PROVENANCE_RETRIES = 2;
+
+/**
+ * Base backoff between retry attempts, in ms. Attempt N waits
+ * `PROVENANCE_BACKOFF_MS * 2^(N-1)` (250 → 500 → …), unless the provider sent a
+ * `Retry-After` header, which takes precedence. Injectable via opts so tests run
+ * without real delay.
+ */
+export const PROVENANCE_BACKOFF_MS = 250;
+
+/** HTTP statuses worth retrying: 429 rate-limit + the 5xx provider-outage band. */
+function isRetryableStatus(status) {
+  return status === 429 || (status >= 500 && status <= 599);
+}
+
+/**
+ * Resolve the wait before the next attempt. A `Retry-After` header (delay in
+ * seconds, or an HTTP-date) is honored when present and parseable; otherwise
+ * fall back to exponential backoff. `attempt` is 1-based (1 = wait before the
+ * 2nd request).
+ *
+ * @param {Response} resp - The non-ok response carrying a possible Retry-After.
+ * @param {number} attempt - 1-based retry index.
+ * @param {number} backoffMs - Base backoff.
+ * @returns {number} Milliseconds to wait (never negative).
+ */
+function nextBackoffMs(resp, attempt, backoffMs) {
+  const header = resp?.headers?.get?.('retry-after');
+  if (header != null && header !== '') {
+    const asSeconds = Number(header);
+    if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+      return Math.round(asSeconds * 1000);
+    }
+    const asDate = Date.parse(header);
+    if (!Number.isNaN(asDate)) {
+      return Math.max(0, asDate - Date.now());
+    }
+  }
+  return backoffMs * 2 ** (attempt - 1);
+}
+
+/** Default sleep: a real timer. Injectable via `opts.sleepImpl` for tests. */
+function defaultSleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 /**
  * Stub provenance adapter. Always confirms.
  * Use in tests and local development.
@@ -47,8 +122,20 @@ export const rejectingProvenance = {
 export function githubProvenance(token, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? GITHUB_PROVENANCE_TIMEOUT_MS;
   const fetchImpl = opts.fetchImpl ?? fetch;
+  const retries = opts.retries ?? PROVENANCE_RETRIES;
+  const backoffMs = opts.backoffMs ?? PROVENANCE_BACKOFF_MS;
+  const sleep = opts.sleepImpl ?? defaultSleep;
   return {
-    async confirm(source) {
+    /**
+     * @param {object} source - submission.source (provider-scoped run claim)
+     * @param {{ refCommitSha?: string }} [expected] - cross-field invariants the
+     *   verifier binds at the call site. `refCommitSha` is the PERSISTED
+     *   `submission.ref.commit_sha` — the commit the record will attest to. When
+     *   present it is checked MANDATORILY against the confirmed run head, so a
+     *   submitter cannot point a real run at an arbitrary persisted commit
+     *   (verify-A-001).
+     */
+    async confirm(source, expected = {}) {
       if (source.provider !== 'github') {
         throw new Error(`unsupported provider: ${source.provider}`);
       }
@@ -72,35 +159,57 @@ export function githubProvenance(token, opts = {}) {
 
       const apiUrl = `https://api.github.com/repos/${owner}/${repo}/actions/runs/${provider_run_id}`;
 
-      // Per-request timeout. Without this, a hung GitHub API call (rate-limit
-      // throttle, regional outage, slow connection) blocks ingest indefinitely.
-      // AbortController fires AbortError on timeout — we re-throw with a clear
-      // message so the verifier records it in rejection_reasons instead of
-      // silently treating it as 'provenance returned false.'
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), timeoutMs);
-
+      // PROACT-VERIFY-001: bounded retry over transient provider faults (429
+      // rate-limit, 5xx outage). Each attempt carries its own per-request
+      // AbortController timeout — without it a hung GitHub API call blocks ingest
+      // indefinitely. We retry up to `retries` extra times with exponential
+      // backoff (honoring Retry-After), then THROW on exhaustion so a
+      // genuinely-down provider surfaces as an operational signal — never a
+      // false 'confirmed'. 404 is NOT retried (run genuinely absent). The
+      // earlier non-retry behavior (single 429/5xx → immediate throw) failed a
+      // submission on a momentary blip that one retry would have confirmed.
       let run;
-      try {
-        const resp = await fetchImpl(apiUrl, {
-          headers: {
-            Authorization: `Bearer ${token}`,
-            Accept: 'application/vnd.github+json',
-            'X-GitHub-Api-Version': '2022-11-28'
-          },
-          signal: controller.signal
-        });
-
-        if (!resp.ok) return false;
-
-        run = await resp.json();
-      } catch (err) {
-        if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
-          throw new Error(`provenance: GitHub API timeout after ${timeoutMs}ms`);
+      for (let attempt = 0; ; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+        let resp;
+        try {
+          resp = await fetchImpl(apiUrl, {
+            headers: {
+              Authorization: `Bearer ${token}`,
+              Accept: 'application/vnd.github+json',
+              'X-GitHub-Api-Version': '2022-11-28'
+            },
+            signal: controller.signal
+          });
+        } catch (err) {
+          if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
+            throw new Error(`provenance: GitHub API timeout after ${timeoutMs}ms`);
+          }
+          // Genuine transport error (DNS, connection refused) — no run to
+          // confirm. Reserve `return false` for this case (mirrors GitLab).
+          return false;
+        } finally {
+          clearTimeout(timer);
         }
-        return false;
-      } finally {
-        clearTimeout(timer);
+
+        if (resp.ok) {
+          run = await resp.json();
+          break;
+        }
+
+        // verify-A-002: only 404 means the run is genuinely absent — a real
+        // submission-bad rejection, never retried. 429/5xx are transient
+        // OPERATIONAL signals: retry within budget. 401/403 (expired/insufficient
+        // token) are NOT transient — throw immediately. On exhausted retries the
+        // last 429/5xx throws so a real outage still surfaces (operational).
+        if (resp.status === 404) return false;
+        if (isRetryableStatus(resp.status) && attempt < retries) {
+          await sleep(nextBackoffMs(resp, attempt + 1, backoffMs));
+          continue;
+        }
+        throw new Error(`provenance: GitHub API returned ${resp.status}`);
       }
 
       if (run.id !== Number(provider_run_id)) return false;
@@ -112,6 +221,14 @@ export function githubProvenance(token, opts = {}) {
       // underlying CI evidence exists. Rejects 'queued' / 'in_progress' / 'waiting'.
       if (run.status !== 'completed') return false;
 
+      // verify-A-001: bind the persisted commit to the confirmed run. The record
+      // attests to submission.ref.commit_sha (index.js persists submission.ref
+      // verbatim), so the run head MUST equal it. Without this, a submitter who
+      // owns a real completed run could set ref.commit_sha to any 40-hex sha and
+      // earn a provenance_confirmed 'pass' for a commit the run never executed.
+      // Mandatory whenever the binding is supplied — not gated on the optional
+      // source.commit_sha.
+      if (expected.refCommitSha && run.head_sha !== expected.refCommitSha) return false;
       if (source.commit_sha && run.head_sha !== source.commit_sha) return false;
       if (source.repo && run.repository?.full_name !== source.repo) return false;
 
@@ -119,3 +236,186 @@ export function githubProvenance(token, opts = {}) {
     }
   };
 }
+
+/**
+ * Terminal GitLab pipeline/job states. Provenance confirms the pipeline RAN to a
+ * terminal state — it is NOT a pass/fail gate (pass/fail is carried by ci_checks
+ * and scenario verdicts, exactly as in githubProvenance, which accepts a
+ * `completed` run regardless of conclusion). 'success', 'failed', 'canceled',
+ * and 'skipped' are terminal; 'running'/'pending'/'created'/'preparing'/
+ * 'waiting_for_resource'/'scheduled'/'manual' are not.
+ */
+const GITLAB_FINISHED_STATES = new Set(['success', 'failed', 'canceled', 'cancelled', 'skipped']);
+
+/**
+ * GitLab CI provenance adapter — peer of {@link githubProvenance}.
+ *
+ * Confirms a GitLab pipeline (or job) exists and matches the claimed project,
+ * commit, and finished state. Mirrors githubProvenance's hardening exactly:
+ *   - per-request AbortController timeout (throws `provenance: GitLab API timeout`)
+ *   - returns false ONLY on HTTP 404 (run genuinely absent)
+ *   - THROWS on 401/403/429/5xx as OPERATIONAL (`provenance: GitLab API returned N`)
+ *     so parseRejectionReason classifies it operational, not submission-bad
+ *   - asserts a finished/terminal pipeline state ({@link GITLAB_FINISHED_STATES})
+ *   - binds the pipeline sha (or job commit.id) to the PERSISTED commit
+ *     (expected.refCommitSha — the verify-A-001 anti-forgery guard) MANDATORILY,
+ *     and binds the run_url project path to source.repo
+ *
+ * The run_url shape decides which endpoint is queried:
+ *   PIPELINE → GET /api/v4/projects/:id/pipelines/:pipeline_id  (commit at .sha)
+ *   JOB      → GET /api/v4/projects/:id/jobs/:job_id            (commit at .commit.id)
+ * `:id` is the URL-encoded `group/project` (or nested `group/subgroup/project`)
+ * path — GitLab accepts the URL-encoded path in place of a numeric project id.
+ *
+ * @param {string} token - GitLab token with `read_api` scope (sent as PRIVATE-TOKEN).
+ * @param {{ timeoutMs?: number, fetchImpl?: typeof fetch, apiBase?: string }} [opts]
+ *   `apiBase` overrides the API origin for self-hosted GitLab (default
+ *   'https://gitlab.com'); tests inject `fetchImpl` so no network is hit.
+ * @returns {object} Provenance adapter
+ */
+export function gitlabProvenance(token, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? GITLAB_PROVENANCE_TIMEOUT_MS;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const apiBase = (opts.apiBase ?? 'https://gitlab.com').replace(/\/+$/, '');
+  const retries = opts.retries ?? PROVENANCE_RETRIES;
+  const backoffMs = opts.backoffMs ?? PROVENANCE_BACKOFF_MS;
+  const sleep = opts.sleepImpl ?? defaultSleep;
+  return {
+    /**
+     * @param {object} source - submission.source (provider-scoped run claim)
+     * @param {{ refCommitSha?: string }} [expected] - see githubProvenance.confirm.
+     *   `refCommitSha` (the persisted submission.ref.commit_sha) is checked
+     *   MANDATORILY against the confirmed pipeline/job commit (verify-A-001).
+     */
+    async confirm(source, expected = {}) {
+      if (source.provider !== 'gitlab') {
+        throw new Error(`unsupported provider: ${source.provider}`);
+      }
+
+      const { provider_run_id, run_url } = source;
+      if (!provider_run_id || !run_url) {
+        return false;
+      }
+
+      // Decode the project path + run kind + id from the run_url.
+      //   JOB:      https://<host>/<project-path>/-/jobs/<id>
+      //   PIPELINE: https://<host>/<project-path>/-/pipelines/<id>
+      // <project-path> may be a nested namespace (group/subgroup/project).
+      const match = run_url.match(
+        /^https:\/\/[^/]+\/(.+?)\/-\/(jobs|pipelines)\/(\d+)(?:[/?#].*)?$/
+      );
+      if (!match) return false;
+
+      const [, projectPath, runKind, urlRunId] = match;
+
+      // run id in URL must match the claimed provider_run_id.
+      if (urlRunId !== String(provider_run_id)) return false;
+
+      // Bind the project path to source.repo BEFORE the network call — a forged
+      // project claim is a cheap, offline rejection. For GitLab, submission.repo
+      // is the full project path (which may contain nested-subgroup slashes).
+      if (source.repo && projectPath !== source.repo) return false;
+
+      const projectId = encodeURIComponent(projectPath);
+      const endpoint = runKind === 'jobs'
+        ? `${apiBase}/api/v4/projects/${projectId}/jobs/${provider_run_id}`
+        : `${apiBase}/api/v4/projects/${projectId}/pipelines/${provider_run_id}`;
+
+      // PROACT-VERIFY-001: bounded retry over transient provider faults — same
+      // discipline as githubProvenance. Each attempt carries its own per-request
+      // AbortController timeout. 429/5xx retry within budget (exponential backoff,
+      // honoring Retry-After), then THROW on exhaustion so a real outage still
+      // surfaces as operational — never a false 'confirmed'. 404 is a single
+      // immediate rejection; 401/403 throw immediately (not transient).
+      let run;
+      for (let attempt = 0; ; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+        let resp;
+        try {
+          resp = await fetchImpl(endpoint, {
+            headers: {
+              'PRIVATE-TOKEN': token,
+              Accept: 'application/json'
+            },
+            signal: controller.signal
+          });
+        } catch (err) {
+          if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
+            throw new Error(`provenance: GitLab API timeout after ${timeoutMs}ms`);
+          }
+          // Genuine transport error (DNS, connection refused) — no run to confirm.
+          return false;
+        } finally {
+          clearTimeout(timer);
+        }
+
+        if (resp.ok) {
+          run = await resp.json();
+          break;
+        }
+
+        // Mirror verify-A-002: 404 = pipeline/job genuinely absent (submission-bad,
+        // never retried). 429/5xx = transient operational fault, retry within
+        // budget. 401/403 = non-transient operational, throw immediately.
+        if (resp.status === 404) return false;
+        if (isRetryableStatus(resp.status) && attempt < retries) {
+          await sleep(nextBackoffMs(resp, attempt + 1, backoffMs));
+          continue;
+        }
+        throw new Error(`provenance: GitLab API returned ${resp.status}`);
+      }
+
+      // id in the response must match the claimed run id.
+      if (run.id !== Number(provider_run_id)) return false;
+
+      // Contract: confirm the pipeline/job reached a TERMINAL state. Like
+      // githubProvenance's `status === 'completed'`, this is not a pass/fail
+      // gate — a terminal 'failed'/'canceled' still confirms the run executed.
+      if (!GITLAB_FINISHED_STATES.has(run.status)) return false;
+
+      // The confirmed commit: a pipeline carries it at `.sha`; a job at
+      // `.commit.id`. Either must be present for a binding to be possible.
+      const runCommit = runKind === 'jobs' ? run.commit?.id : run.sha;
+      if (!runCommit) return false;
+
+      // verify-A-001: bind the PERSISTED commit to the confirmed run. Mandatory
+      // whenever the binding is supplied — a submitter who owns a real finished
+      // pipeline must not be able to attest an arbitrary commit.
+      if (expected.refCommitSha && runCommit !== expected.refCommitSha) return false;
+      if (source.commit_sha && runCommit !== source.commit_sha) return false;
+
+      return true;
+    }
+  };
+}
+
+/**
+ * Provider → provenance-adapter-factory registry, keyed on `source.provider`.
+ *
+ * Each factory has the signature `(token, opts?) => { confirm(source, expected?) }`.
+ * This registry is the lockstep partner of `RUN_URL_PARSERS` in
+ * validators/repo-binding.js: a provider in the `source.provider` schema enum
+ * MUST have BOTH a run_url parser (so the anti-forgery repo-binding decodes it)
+ * AND a provenance adapter (so its runs are confirmable). Two coverage tests —
+ * validators/repo-binding.test.js and validators/provenance-registry.test.js —
+ * read the actual enum and fail CI if either side is missing for a provider.
+ *
+ * @type {Record<string, (token: string, opts?: object) => { confirm: Function }>}
+ */
+export const PROVENANCE_ADAPTERS = {
+  github: githubProvenance,
+  gitlab: gitlabProvenance,
+};
+
+/**
+ * Resolve the provenance-adapter factory for a `source.provider`.
+ *
+ * @param {string} provider The `source.provider` token (e.g. 'github', 'gitlab').
+ * @returns {((token: string, opts?: object) => { confirm: Function }) | null}
+ *   The adapter factory, or `null` when the provider has no registered adapter.
+ */
+export function provenanceForProvider(provider) {
+  return PROVENANCE_ADAPTERS[provider] ?? null;
+}

package/validators/repo-binding.js

@@ -0,0 +1,92 @@
+/**
+ * Cross-field repo-binding parsers (verify-B-001).
+ *
+ * The anti-forgery guard in verify/index.js binds `submission.repo` to the
+ * owner/repo encoded in `submission.source.run_url`, so a submitter cannot
+ * claim `repo='victim/repo'` while supplying a real run_url from their own
+ * repo (the verify-A-001 vector). That guard only works if it can decode the
+ * run_url for the submission's PROVIDER.
+ *
+ * Pre-fix the GitHub run_url regex was inlined in index.js behind `if (m)`.
+ * A second provider in the `source.provider` enum would fall through `m ===
+ * null` and the binding would SILENTLY no-op — reopening the forgery vector
+ * for the new provider with no error and no test failure.
+ *
+ * The fix keys the parsers by provider. `RUN_URL_PARSERS` MUST stay in lockstep
+ * with the `source.provider` enum in dogfood-record-submission.schema.json —
+ * a guard-coverage test (repo-binding.test.js) asserts exactly that, so adding
+ * a provider to the schema without adding a parser here fails CI instead of
+ * silently disabling the binding for the new provider.
+ */
+
+/**
+ * @typedef {object} RunUrlRepo
+ * @property {string} owner Repository owner/org.
+ * @property {string} repo  Repository name.
+ */
+
+/**
+ * Per-provider run_url → { owner, repo } parser.
+ *
+ * Each parser returns `null` when the URL does not match the provider's run_url
+ * shape (malformed/foreign URL). A malformed URL is NOT a binding failure —
+ * the schema validator already rejects a malformed source.run_url — so the
+ * guard treats a `null` parse as "nothing to bind against" and lets the schema
+ * layer own the rejection.
+ *
+ * @type {Record<string, (runUrl: string) => RunUrlRepo | null>}
+ */
+export const RUN_URL_PARSERS = {
+  // Format: https://github.com/{owner}/{repo}/actions/runs/{id}
+  github(runUrl) {
+    const m = runUrl.match(
+      /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/actions\/runs\/\d+$/
+    );
+    return m ? { owner: m[1], repo: m[2] } : null;
+  },
+
+  // GitLab run_url shapes (gitlab.com AND self-hosted hosts):
+  //   JOB:      https://<host>/<namespace>/<project>/-/jobs/<id>
+  //   PIPELINE: https://<host>/<namespace>/<project>/-/pipelines/<id>
+  // The project path is everything between the host and the `/-/` run segment.
+  //
+  // NESTED-SUBGROUP MAPPING (load-bearing decision, kept consistent with how
+  // submission.repo is expressed for GitLab): GitLab namespaces can nest —
+  // `group/subgroup/project`. We map owner = the FULL namespace (everything
+  // before the last path segment, slashes preserved) and repo = the LAST segment
+  // (the project). So `${owner}/${repo}` reconstructs the full project path. For
+  // a flat `group/project` this degenerates to owner='group', repo='project'
+  // (same shape as GitHub). The repo-binding guard then compares
+  // `${owner}/${repo}` against submission.repo, so for GitLab submission.repo is
+  // the FULL project path — which may contain more than one slash for nested
+  // subgroups, unlike GitHub's strict two-segment org/repo.
+  //
+  // A single-segment path (no namespace + project, just `<project>/-/jobs/<id>`)
+  // returns null — it cannot be split into owner + repo and is not a valid
+  // GitLab project URL.
+  gitlab(runUrl) {
+    const m = runUrl.match(
+      /^https:\/\/[^/]+\/(.+?)\/-\/(?:jobs|pipelines)\/\d+(?:[/?#].*)?$/
+    );
+    if (!m) return null;
+    const segments = m[1].split('/');
+    if (segments.length < 2) return null; // need at least namespace + project
+    const repo = segments.pop();
+    const owner = segments.join('/');
+    return { owner, repo };
+  },
+};
+
+/**
+ * Decode the owner/repo a run_url attests to, for the given provider.
+ *
+ * @param {string} provider The `source.provider` token (e.g. 'github').
+ * @param {string} runUrl   The `source.run_url`.
+ * @returns {RunUrlRepo | null} `{ owner, repo }`, or `null` when the provider
+ *   has no parser or the URL does not match the provider's shape.
+ */
+export function parseRunUrlRepo(provider, runUrl) {
+  const parser = RUN_URL_PARSERS[provider];
+  if (!parser) return null;
+  return parser(runUrl);
+}

package/validators/repo-binding.test.js

@@ -0,0 +1,118 @@
+/**
+ * repo-binding.test.js — verify-B-001 (Stage C, MED)
+ *
+ * The cross-field anti-forgery guard in verify/index.js binds submission.repo
+ * to the owner/repo decoded from source.run_url. That decode is provider-keyed
+ * (RUN_URL_PARSERS in repo-binding.js). The forgery vector (verify-A-001)
+ * reopens silently if a provider is added to the submission schema's
+ * `source.provider` enum without a corresponding parser branch: the guard would
+ * see `parseRunUrlRepo(provider, url) === null`, skip the comparison, and accept
+ * a forged repo with no error and no other test failure.
+ *
+ * The coverage test below is the tripwire: it reads the ACTUAL `source.provider`
+ * enum from the canonical submission schema and asserts every member has a
+ * parser. Add a provider to the schema and forget the parser → this test goes
+ * red in CI before the binding can ship disabled.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+import { RUN_URL_PARSERS, parseRunUrlRepo } from './repo-binding.js';
+
+const require = createRequire(import.meta.url);
+const schemaPath = require.resolve(
+  '@dogfood-lab/schemas/json/dogfood-record-submission.schema.json'
+);
+const submissionSchema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+const PROVIDER_ENUM = submissionSchema.properties.source.properties.provider.enum;
+
+describe('repo-binding guard coverage (verify-B-001)', () => {
+  it('exposes the provider enum it is meant to cover (sanity)', () => {
+    assert.ok(Array.isArray(PROVIDER_ENUM) && PROVIDER_ENUM.length > 0);
+    assert.ok(PROVIDER_ENUM.includes('github'));
+  });
+
+  it('has a run_url parser for EVERY registered source.provider', () => {
+    const missing = PROVIDER_ENUM.filter(p => typeof RUN_URL_PARSERS[p] !== 'function');
+    assert.deepEqual(
+      missing,
+      [],
+      `source.provider enum members without a RUN_URL_PARSERS branch: ${missing.join(', ')}. ` +
+        'Add a parser in validators/repo-binding.js or the anti-forgery repo binding ' +
+        'silently no-ops for these providers (verify-A-001 / verify-B-001).'
+    );
+  });
+
+  describe('github parser', () => {
+    it('decodes owner/repo from a well-formed run_url', () => {
+      const bound = parseRunUrlRepo(
+        'github',
+        'https://github.com/acme/widget/actions/runs/12345'
+      );
+      assert.deepEqual(bound, { owner: 'acme', repo: 'widget' });
+    });
+
+    it('returns null for a foreign/malformed run_url', () => {
+      assert.equal(parseRunUrlRepo('github', 'https://example.com/x'), null);
+    });
+  });
+
+  describe('gitlab parser', () => {
+    it('decodes owner/repo from a JOB run_url', () => {
+      const bound = parseRunUrlRepo(
+        'gitlab',
+        'https://gitlab.com/acme/widget/-/jobs/987654'
+      );
+      assert.deepEqual(bound, { owner: 'acme', repo: 'widget' });
+    });
+
+    it('decodes owner/repo from a PIPELINE run_url', () => {
+      const bound = parseRunUrlRepo(
+        'gitlab',
+        'https://gitlab.com/acme/widget/-/pipelines/424242'
+      );
+      assert.deepEqual(bound, { owner: 'acme', repo: 'widget' });
+    });
+
+    it('maps nested subgroups: owner = full namespace, repo = last segment', () => {
+      // GitLab supports nested subgroups (group/subgroup/project). The mapping
+      // decision (documented in repo-binding.js): owner = everything before the
+      // LAST path segment (the full namespace, slashes preserved), repo = the
+      // last segment. Reconstructing `${owner}/${repo}` yields the full project
+      // path, which is what submission.repo carries for GitLab.
+      const bound = parseRunUrlRepo(
+        'gitlab',
+        'https://gitlab.com/acme/team-a/widget/-/pipelines/1'
+      );
+      assert.deepEqual(bound, { owner: 'acme/team-a', repo: 'widget' });
+      assert.equal(`${bound.owner}/${bound.repo}`, 'acme/team-a/widget');
+    });
+
+    it('parses self-hosted GitLab hosts (owner/repo = path before /-/)', () => {
+      const bound = parseRunUrlRepo(
+        'gitlab',
+        'https://gitlab.example.com/acme/widget/-/jobs/55'
+      );
+      assert.deepEqual(bound, { owner: 'acme', repo: 'widget' });
+    });
+
+    it('returns null for a foreign/malformed run_url', () => {
+      assert.equal(parseRunUrlRepo('gitlab', 'https://example.com/x'), null);
+    });
+
+    it('returns null when the URL has no /-/ run segment', () => {
+      assert.equal(parseRunUrlRepo('gitlab', 'https://gitlab.com/acme/widget'), null);
+    });
+
+    it('returns null for a single-segment path (no namespace + project)', () => {
+      assert.equal(parseRunUrlRepo('gitlab', 'https://gitlab.com/widget/-/jobs/1'), null);
+    });
+  });
+
+  it('returns null for a provider with no parser (no throw)', () => {
+    assert.equal(parseRunUrlRepo('bitbucket', 'https://bitbucket.org/a/b/pipelines/1'), null);
+  });
+});