src/shadow.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/http.ts, src/jobs-schema.ts, src/jobs-transition.ts, src/signed-docs.ts, src/signed-requests.ts, src/store-guards.ts, src/time.ts. Imported by src/routes.ts.

Source

1import { createRemoteJWKSet, jwtVerify } from "jose";
2import type { Env } from "./env";
3import { ghFetch, resolveRepo } from "./github/client";
4import { textResponse } from "./http";
5import { HOUR_MS } from "./time";
6import { readJob } from "./jobs-transition";
7import { jobDocPath } from "./jobs-schema";
8import { splitSignedTask } from "./signed-docs";
9import { readBoundedText } from "./signed-requests";
10import { auditStatement } from "./store-guards";
11
12// THE SHADOW TEST (docs/work-queue.md, "The shadow test"; Grok design review 2026-10-23,
13// build step 8). On a capsid pull request that names its job, .github/workflows/shadow-test.yml
14// has a model read the job and the code at the base, never the diff, write one test of
15// what the job asks, and run it on the base and on the head. It blocks nothing and is
16// not in the study: the results are recorded so they can show, over many jobs, whether
17// a test written blind catches work that CI and the gates on complete let through.
18//
19// The workflow proves which workflow it is with its GitHub Actions OIDC token, so no key
20// is stored anywhere: the token's repository must be the capsid namespace's primary
21// repo, its workflow this file, its event a pull request, and the job it reads the one
22// that pull request's description names, in the capsid namespace.
23//
24//   GET  /shadow/job     the job's title and body, and the test already written for it
25//   POST /shadow/result  the test (kept for the job's later pushes) and its two results
26
27export const SHADOW_JOB_PATH = "/shadow/job";
28export const SHADOW_RESULT_PATH = "/shadow/result";
29const SHADOW_ACTION = "shadow-test";
30const NAMESPACE = "capsid";
31const ISSUER = "https://token.actions.githubusercontent.com";
32const AUDIENCE = "capsid-shadow";
33const WORKFLOW = ".github/workflows/shadow-test.yml";
34const MAX_TEST_BYTES = 64 * 1024;
35const MAX_RESULT_BYTES = 80 * 1024;
36const TEST_TTL_S = 30 * 24 * 3600;
37const RESULTS = ["failed", "passed", "error", "not-run"] as const;
38const testKey = (jobId: string) => `shadow:test:${jobId}`;
39
40// The key set's address comes from the issuer's discovery document, as OIDC defines,
41// and must be on the issuer's own host.
42let keys: ReturnType<typeof createRemoteJWKSet> | null = null;
43async function issuerKeys(): Promise<ReturnType<typeof createRemoteJWKSet>> {
44  if (keys) return keys;
45  const resp = await fetch(`${ISSUER}/.well-known/openid-configuration`);
46  if (!resp.ok) throw new Error(`the issuer's discovery document answered ${resp.status}`);
47  const uri = new URL(String(((await resp.json()) as { jwks_uri?: unknown }).jwks_uri));
48  if (uri.origin !== ISSUER) throw new Error("the issuer's key set is on another host");
49  keys = createRemoteJWKSet(uri, { cacheMaxAge: HOUR_MS });
50  return keys;
51}
52
53type Caller = { ok: true; pr: number; jobId: string; headSha: string } | { ok: false; response: Response };
54
55async function caller(request: Request, env: Env): Promise<Caller> {
56  const refuse = (status: number, why: string): Caller => ({ ok: false, response: textResponse(why, status) });
57  const token = /^Bearer (\S+)$/.exec(request.headers.get("Authorization") ?? "")?.[1];
58  if (!token) return refuse(401, "a GitHub Actions OIDC token is required");
59  let claims: Record<string, unknown>;
60  const claim = (name: string) => (typeof claims[name] === "string" ? (claims[name] as string) : "");
61  try {
62    ({ payload: claims } = await jwtVerify(token, await issuerKeys(), { issuer: ISSUER, audience: AUDIENCE, algorithms: ["RS256"], requiredClaims: ["exp"] }));
63  } catch {
64    return refuse(401, "the OIDC token does not verify");
65  }
66  const repo = (await resolveRepo(env, NAMESPACE)).full;
67  const pr = /^refs\/pull\/(\d+)\/merge$/.exec(claim("ref"))?.[1];
68  if (
69    claim("repository").toLowerCase() !== repo.toLowerCase() ||
70    claims.event_name !== "pull_request" ||
71    !claim("workflow_ref").toLowerCase().startsWith(`${repo}/${WORKFLOW}@`.toLowerCase()) ||
72    !pr
73  ) {
74    return refuse(403, `only ${WORKFLOW} on a pull request in ${repo} may read the shadow test's job`);
75  }
76  const [owner, name] = repo.split("/");
77  const resp = await ghFetch(env, owner, name, `/repos/${owner}/${name}/pulls/${pr}`);
78  if (!resp.ok) return refuse(502, `GitHub answered ${resp.status} for pull request ${pr}`);
79  const pull = (await resp.json()) as { body?: string | null; head?: { sha?: string } };
80  const jobId = /\bjob_[0-9a-f]{12}\b/.exec(pull.body ?? "")?.[0];
81  if (!jobId) return refuse(404, `pull request ${pr} names no job`);
82  const job = await readJob(env.DB, jobId);
83  if (!job || job.namespace !== NAMESPACE) return refuse(404, `${jobId} is not a ${NAMESPACE} job`);
84  return { ok: true, pr: Number(pr), jobId, headSha: pull.head?.sha ?? "" };
85}
86
87export async function handleShadowJob(request: Request, env: Env): Promise<Response> {
88  const who = await caller(request, env);
89  if (!who.ok) return who.response;
90  const job = (await readJob(env.DB, who.jobId))!;
91  const test = await env.APP_KV.get(testKey(who.jobId), "json");
92  // The body as its poster wrote it, without the signature frontmatter.
93  return Response.json({ job_id: job.id, title: job.title, body: splitSignedTask(job.body).body, test });
94}
95
96export async function handleShadowResult(request: Request, env: Env): Promise<Response> {
97  const who = await caller(request, env);
98  if (!who.ok) return who.response;
99  const raw = await readBoundedText(request, MAX_RESULT_BYTES);
100  if (!raw.ok) return textResponse(`the body is over ${MAX_RESULT_BYTES} bytes`, 413);
101  let r: { path?: unknown; test?: unknown; base?: unknown; head?: unknown };
102  try {
103    r = JSON.parse(raw.text);
104  } catch {
105    return textResponse("the body is not JSON", 400);
106  }
107  const path = typeof r.path === "string" && /^(test|test-integration)\/shadow\.test\.ts$/.test(r.path) ? r.path : null;
108  const test = typeof r.test === "string" && r.test.length > 0 && r.test.length <= MAX_TEST_BYTES ? r.test : null;
109  const result = (v: unknown) => (RESULTS as readonly unknown[]).includes(v) ? (v as (typeof RESULTS)[number]) : null;
110  const base = result(r.base);
111  const head = result(r.head);
112  if (!path || !test || !base || !head) return textResponse(`path, test, base and head are required; base and head are one of ${RESULTS.join(", ")}`, 400);
113  // The first test written for a job is the one kept: a later push runs it again rather
114  // than asking the model for another.
115  if ((await env.APP_KV.get(testKey(who.jobId))) === null) await env.APP_KV.put(testKey(who.jobId), JSON.stringify({ path, test }), { expirationTtl: TEST_TTL_S });
116  await auditStatement(env.DB, "system:shadow-test", SHADOW_ACTION, NAMESPACE, jobDocPath(who.jobId), {
117    job_id: who.jobId,
118    pr: who.pr,
119    head_sha: who.headSha,
120    path,
121    base,
122    head,
123  }).run();
124  return Response.json({ ok: true, job_id: who.jobId, base, head });
125}