From c52eb08cee39d93460a27be0e6e2e13e6b10e042 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 19:06:34 -0700 Subject: [PATCH 01/14] fix(gh-aw): bind first-install review identity Part of #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/gh-aw-review-guard.test.ts | 161 ++++++++++++++- test/gh-aw-review-workflow.test.ts | 250 ++++++++++++++++++++++-- workflows/package/squad-review.md | 43 +++- workflows/shared/squad-review-guard.mjs | 192 ++++++++++++++++-- workflows/squad-review.md | 43 +++- workflows/squad-workflows.manifest.json | 4 +- 6 files changed, 658 insertions(+), 35 deletions(-) diff --git a/test/gh-aw-review-guard.test.ts b/test/gh-aw-review-guard.test.ts index 5de59d7bd..faf5b5d5c 100644 --- a/test/gh-aw-review-guard.test.ts +++ b/test/gh-aw-review-guard.test.ts @@ -1,5 +1,6 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { createHash } from 'node:crypto'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { @@ -16,6 +17,13 @@ const SUBMITTED = '2026-09-28T12:01:01Z'; const FINISHED = '2026-09-28T12:02:00Z'; const MERGED = '2026-09-28T12:03:00Z'; const NOW = Date.parse('2026-09-28T12:04:00Z'); +const GUARD_SHA256 = createHash('sha256') + .update(readFileSync(join(process.cwd(), 'workflows/shared/squad-review-guard.mjs'))) + .digest('hex'); +const INSTALL_WORKFLOWS = [ + 'squad', 'squad-implement-worker', 'squad-review', 'squad-deps-worker', + 'squad-retro', 'squad-improvement-worker', 'squad-bootstrap', 'squad-command-router', +]; const workspaces: string[] = []; afterEach(() => { @@ -111,10 +119,161 @@ function fixture(relay = false) { comment.body = `${OVERRIDE_PREFIX}${JSON.stringify(override)}`; }; sync(); - return { env, attribution, registry, pr, verdict, review, run, jobs, override, comment, state, get, sync }; + return { + env, attribution, registry, pr, verdict, review, run, jobs, override, comment, + state, encode, get, sync, + }; +} + +function firstInstallProof(guardSha256 = GUARD_SHA256) { + const manifest = { + schema_version: 1, + package: 'bradygaster/squad/workflows', + revision_policy: { kind: 'immutable-git-commit' }, + workflows: INSTALL_WORKFLOWS.map(name => ({ + name, + destination: `.github/workflows/${name}.md`, + lock: `.github/workflows/${name}.lock.yml`, + source_sha256: 'c'.repeat(64), + })), + shared_runtime: [{ + path: 'shared/squad-review-guard.mjs', + destination: '.github/workflows/shared/squad-review-guard.mjs', + ownership: 'manifest', + sha256: guardSha256, + }], + }; + const required = [ + '.github/aw/squad-workflows.manifest.json', + '.github/workflows/shared/squad-review-guard.mjs', + ...INSTALL_WORKFLOWS.flatMap(name => [ + `.github/workflows/${name}.md`, + `.github/workflows/${name}.lock.yml`, + ]), + ]; + const provenance = { + schemaVersion: 1, + package: 'bradygaster/squad/workflows', + source: `bradygaster/squad/workflows@${HEAD}`, + resolvedCommit: HEAD, + files: required.map(destination => ({ destination, sha256: 'd'.repeat(64) })), + }; + provenance.files.find(entry => + entry.destination === '.github/workflows/shared/squad-review-guard.mjs')!.sha256 = guardSha256; + provenance.files.find(entry => + entry.destination === '.github/aw/squad-workflows.manifest.json')!.sha256 = + createHash('sha256').update(JSON.stringify(manifest)).digest('hex'); + return { manifest, provenance }; } describe('independent Squad review guard', () => { + it('uses reserved workflow-role attribution only for a proven clean package install', async () => { + const f = fixture(); + f.state.reviews = []; + const { manifest, provenance } = firstInstallProof(); + const get = async (route: string, fields?: Record) => { + if (route.endsWith('/contents/.squad-review.json')) { + throw Object.assign(new Error('Not Found'), { status: 404 }); + } + if (route.endsWith('/contents/.github/aw/squad-workflows.manifest.json')) { + expect(fields?.ref).toBe(HEAD); + return f.encode(manifest); + } + if (route.endsWith('/contents/.github/aw/packages')) { + expect(fields?.ref).toBe(HEAD); + return [{ + type: 'file', + name: 'bradygaster-squad-workflows-3632054824e8.json', + }]; + } + if (route.endsWith( + '/contents/.github/aw/packages/bradygaster-squad-workflows-3632054824e8.json', + )) return f.encode(provenance); + return f.get(route, fields); + }; + const options = { + firstInstall: true, + workflowSha: HEAD, + workflowGuardSha256: GUARD_SHA256, + workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${HEAD}`, + }; + await expect(reviewTarget(f.env, get, options)).resolves.toMatchObject({ + author_agent: '@squad/bootstrap-installation', + reviewer_agent: '@squad/bootstrap-review-workflow', + }); + + const workspace = mkdtempSync(join(tmpdir(), 'squad-review-install-')); + workspaces.push(workspace); + const path = join(workspace, 'output.json'); + writeFileSync(path, JSON.stringify({ items: [{ + type: 'submit_pull_request_review', event: 'COMMENT', body: 'Install topology reviewed.', + }] })); + await enforceReviewOutputs({ ...f.env, GH_AW_AGENT_OUTPUT: path }, get, options); + const output = JSON.parse(readFileSync(path, 'utf8')); + expect(output.items[0].body).toContain('"author_agent":"@squad/bootstrap-installation"'); + expect(output.items[0].body).toContain( + '"reviewer_agent":"@squad/bootstrap-review-workflow"', + ); + }); + + it('refuses arbitrary clean-base PRs and malformed first-install proof', async () => { + const f = fixture(); + const { manifest, provenance } = firstInstallProof(); + const missingAttribution = async (route: string, fields?: Record) => { + if (route.endsWith('/contents/.squad-review.json')) { + throw Object.assign(new Error('Not Found'), { status: 404 }); + } + if (route.endsWith('/contents/.github/aw/squad-workflows.manifest.json')) { + return f.encode(manifest); + } + if (route.endsWith('/contents/.github/aw/packages')) { + return [{ type: 'file', name: 'bradygaster-squad-workflows-3632054824e8.json' }]; + } + if (route.includes('/contents/.github/aw/packages/')) return f.encode(provenance); + return f.get(route, fields); + }; + const options = { + firstInstall: true, + workflowSha: HEAD, + workflowGuardSha256: GUARD_SHA256, + workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${HEAD}`, + }; + await expect(reviewTarget(f.env, missingAttribution)).rejects.toThrow('Not Found'); + await expect(reviewTarget(f.env, missingAttribution, { + ...options, workflowSha: BASE, + })).rejects.toThrow('outside an immutable clean first install'); + + manifest.workflows.pop(); + await expect(reviewTarget(f.env, missingAttribution, options)) + .rejects.toThrow('invalid committed first-install manifest'); + manifest.workflows = firstInstallProof().manifest.workflows; + provenance.source = `bradygaster/squad/workflows@${BASE}`; + await expect(reviewTarget(f.env, missingAttribution, options)) + .rejects.toThrow('invalid committed first-install package provenance'); + provenance.source = `bradygaster/squad/workflows@${HEAD}`; + provenance.files.pop(); + await expect(reviewTarget(f.env, missingAttribution, options)) + .rejects.toThrow('incomplete committed first-install topology'); + }); + + it('does not rescue malformed attribution or non-404 reads during first install', async () => { + const f = fixture(); + const options = { + firstInstall: true, + workflowSha: HEAD, + workflowGuardSha256: GUARD_SHA256, + workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${HEAD}`, + }; + f.attribution.schema = 'wrong'; + await expect(reviewTarget(f.env, f.get, options)).rejects.toThrow('malformed committed'); + await expect(reviewTarget(f.env, async (route, fields) => { + if (route.endsWith('/contents/.squad-review.json')) { + throw Object.assign(new Error('Forbidden'), { status: 403 }); + } + return f.get(route, fields); + }, options)).rejects.toThrow('Forbidden'); + }); + it('accepts a distinct, committed, current-head verdict and merged-head relay', async () => { for (const relay of [false, true]) { const f = fixture(relay); diff --git a/test/gh-aw-review-workflow.test.ts b/test/gh-aw-review-workflow.test.ts index bbccd9b61..2efb74ae7 100644 --- a/test/gh-aw-review-workflow.test.ts +++ b/test/gh-aw-review-workflow.test.ts @@ -1,6 +1,7 @@ import { afterAll, describe, expect, it } from 'vitest'; import { cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'; import { execFileSync, spawnSync } from 'node:child_process'; +import { createHash } from 'node:crypto'; import { dirname, resolve } from 'node:path'; import { fileURLToPath, pathToFileURL } from 'node:url'; import { extractSafeOutputsConfigJson } from './helpers/gh-aw-lock.js'; @@ -171,11 +172,20 @@ function assertCompiledGate(lock: string): void { expect(workflowCheckout.with.ref).toBe('${{ github.workflow_sha }}'); expect(steps[guard].with.script).toContain('if (existsSync(baseGuard))'); expect(steps[guard].with.script).toContain('else if (!existsSync(baseManifest))'); + expect(steps[guard].with.script).toContain('firstInstall = true'); + expect(steps[guard].with.script).toContain("createHash('sha256')"); + expect(steps[guard].with.script).toContain('workflowGuardSha256'); + expect(steps[guard].with.script).toContain( + 'workflowSource: process.env.GH_AW_WORKFLOW_SOURCE', + ); expect(steps[guard].with.script).toContain('missing from an established base installation'); const finalGate = review.steps.find((step: { name: string }) => step.name === 'Enforce independent current-head verdict'); expect(finalGate.with.script).toContain('if (existsSync(baseGuard))'); expect(finalGate.with.script).toContain('else if (!existsSync(baseManifest))'); + expect(finalGate.with.script).toContain('firstInstall = true'); + expect(finalGate.with.script).toContain("createHash('sha256')"); + expect(finalGate.with.script).toContain('workflowGuardSha256'); expect(finalGate.with.script).toContain('missing from an established base installation'); for (const step of review.steps) expect(step['continue-on-error']).toBeUndefined(); expect(review['continue-on-error']).toBeUndefined(); @@ -238,7 +248,7 @@ async function executeCompiledGuardLoader( import { createRequire } from 'node:module'; const require = createRequire(import.meta.url); const github = { request: async () => ({ data: {} }) }; - ${script} + ${script.replaceAll('${{ github.workflow_sha }}', head)} `); await import(`${pathToFileURL(runner).href}?run=${Date.now()}`); return readFileSync(output, 'utf8'); @@ -252,6 +262,175 @@ async function executeCompiledGuardLoader( } } +function executeCompiledSafeOutputContract( + script: string, + scenario: 'clean-install' | 'clean-arbitrary' | 'established-missing' | 'configured', +): { status: number | null; diagnostics: string; output?: string } { + const workspace = mkdtempSync(resolve(ROOT, '.squad-review-live-contract-')); + compileWorkspaces.push(workspace); + const workflowShared = resolve( + workspace, + '.squad-review-workflow', + '.github/workflows/shared', + ); + mkdirSync(dirname(workflowShared), { recursive: true }); + cpSync(resolve(ROOT, 'workflows/shared'), workflowShared, { recursive: true }); + const guardPath = resolve(workflowShared, 'squad-review-guard.mjs'); + const guardSha256 = createHash('sha256').update(readFileSync(guardPath)).digest('hex'); + if (scenario === 'established-missing' || scenario === 'configured') { + const baseShared = resolve(workspace, '.squad-review-base', '.github/workflows/shared'); + mkdirSync(dirname(baseShared), { recursive: true }); + cpSync(resolve(ROOT, 'workflows/shared'), baseShared, { recursive: true }); + const manifestPath = resolve( + workspace, + '.squad-review-base', + '.github/aw/squad-workflows.manifest.json', + ); + mkdirSync(dirname(manifestPath), { recursive: true }); + writeFileSync(manifestPath, '{}\n'); + } + + const head = 'a'.repeat(40); + const base = 'b'.repeat(40); + const workflowNames = [ + 'squad', 'squad-implement-worker', 'squad-review', 'squad-deps-worker', + 'squad-retro', 'squad-improvement-worker', 'squad-bootstrap', 'squad-command-router', + ]; + const manifest = { + schema_version: 1, + package: 'bradygaster/squad/workflows', + revision_policy: { kind: 'immutable-git-commit' }, + workflows: workflowNames.map(name => ({ + name, + destination: `.github/workflows/${name}.md`, + lock: `.github/workflows/${name}.lock.yml`, + source_sha256: 'c'.repeat(64), + })), + shared_runtime: [{ + path: 'shared/squad-review-guard.mjs', + destination: '.github/workflows/shared/squad-review-guard.mjs', + ownership: 'manifest', + sha256: guardSha256, + }], + }; + const required = [ + '.github/aw/squad-workflows.manifest.json', + '.github/workflows/shared/squad-review-guard.mjs', + ...workflowNames.flatMap(name => [ + `.github/workflows/${name}.md`, + `.github/workflows/${name}.lock.yml`, + ]), + ]; + const provenance = { + schemaVersion: 1, + package: 'bradygaster/squad/workflows', + source: `bradygaster/squad/workflows@${'c'.repeat(40)}`, + resolvedCommit: 'c'.repeat(40), + files: required.map(destination => ({ + destination, + sha256: destination === '.github/workflows/shared/squad-review-guard.mjs' + ? guardSha256 + : 'd'.repeat(64), + })), + }; + provenance.files.find(entry => + entry.destination === '.github/aw/squad-workflows.manifest.json')!.sha256 = + createHash('sha256').update(JSON.stringify(manifest)).digest('hex'); + const outputPath = resolve(workspace, 'agent-output.json'); + writeFileSync(outputPath, JSON.stringify({ items: [{ + type: 'submit_pull_request_review', + event: 'COMMENT', + body: 'No blocking installation findings.', + }] })); + const runner = resolve(workspace, 'runner.mjs'); + const compiledScript = script.replaceAll('${{ github.workflow_sha }}', head); + writeFileSync(runner, ` + import { createRequire } from 'node:module'; + const require = createRequire(import.meta.url); + const head = ${JSON.stringify(head)}; + const base = ${JSON.stringify(base)}; + const scenario = ${JSON.stringify(scenario)}; + const encode = value => ({ + type: 'file', + encoding: 'base64', + size: 1000, + content: Buffer.from(JSON.stringify(value)).toString('base64'), + }); + const attribution = { + schema: 'squad-review-author/v1', + repository: 'squad/example', + issue: 9, + author_agent: 'implementer', + reviewer_agent: 'reviewer', + }; + const registry = { + schema: 'squad-agent-provenance/v1', + schema_version: 1, + agents: { + implementer: { persistent_name: 'implementer', status: 'active' }, + reviewer: { persistent_name: 'reviewer', status: 'active' }, + }, + }; + const github = { + request: async (request, fields) => { + const route = request.replace(/^GET \\//, ''); + if (route.endsWith('/pulls/42')) return { data: { + number: 42, + state: 'open', + merged: false, + body: '', + head: { sha: head, ref: 'install-squad', repo: { full_name: 'squad/example' } }, + base: { sha: base, ref: 'dev', repo: { full_name: 'squad/example' } }, + } }; + if (route.endsWith('/contents/.squad-review.json')) { + if (scenario === 'configured') return { data: encode(attribution) }; + throw Object.assign(new Error('Not Found'), { status: 404 }); + } + if (route.endsWith('/contents/.squad/casting/registry.json')) { + return { data: encode(registry) }; + } + if (route.endsWith('/contents/.github/aw/squad-workflows.manifest.json')) { + return { data: encode(${JSON.stringify(manifest)}) }; + } + if (route.endsWith('/contents/.github/aw/packages')) { + if (scenario === 'clean-arbitrary') return { data: [] }; + return { data: [{ + type: 'file', + name: 'bradygaster-squad-workflows-3632054824e8.json', + }] }; + } + if (route.includes('/contents/.github/aw/packages/')) { + return { data: encode(${JSON.stringify(provenance)}) }; + } + if (route.endsWith('/reviews')) return { data: [] }; + throw new Error('Unexpected API route: ' + route + ' ' + JSON.stringify(fields)); + }, + }; + ${compiledScript} + `); + const result = spawnSync(process.execPath, [runner], { + cwd: workspace, + encoding: 'utf8', + env: { + ...process.env, + GITHUB_WORKSPACE: workspace, + GITHUB_EVENT_NAME: 'pull_request', + GITHUB_REPOSITORY: 'squad/example', + GITHUB_RUN_ID: '17', + GITHUB_RUN_ATTEMPT: '1', + GH_AW_AGENT_OUTPUT: outputPath, + SQUAD_REVIEW_PR: '42', + SQUAD_REVIEW_HEAD: head, + GH_AW_WORKFLOW_SOURCE: `bradygaster/squad/workflows/package/squad-review.md@${'c'.repeat(40)}`, + }, + }); + return { + status: result.status, + diagnostics: `${result.stdout}\n${result.stderr}`, + output: result.status === 0 ? readFileSync(outputPath, 'utf8') : undefined, + }; +} + describe('gh-aw enforcing Squad reviewer', () => { it('routes /squad review to the isolated workflow and supports automatic PR events', () => { const routerDispatch = yamlBlock(ROUTER_FRONTMATTER, 'dispatch-workflow'); @@ -441,13 +620,15 @@ describe('gh-aw enforcing Squad reviewer', () => { const { lock } = compileReviewer(); const stub = (source: string) => ` import { writeFileSync } from 'node:fs'; - export async function enforceReviewOutputs(env) { + export async function enforceReviewOutputs(env, get, options) { writeFileSync(process.env.SQUAD_TEST_GUARD_OUTPUT, - JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'safe outputs', head: env.SQUAD_REVIEW_HEAD })); + JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'safe outputs', + head: env.SQUAD_REVIEW_HEAD, options })); } - export async function assertClearingReview(env) { + export async function assertClearingReview(env, get, options) { writeFileSync(process.env.SQUAD_TEST_GUARD_OUTPUT, - JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'final verdict', head: env.SQUAD_REVIEW_HEAD })); + JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'final verdict', + head: env.SQUAD_REVIEW_HEAD, options })); } `; @@ -455,21 +636,33 @@ describe('gh-aw enforcing Squad reviewer', () => { const head = name === 'safe outputs' ? 'edd6fbf0f84334ff086ed2bc8bbfed5503fdd56f' : '9a898b5182ca432b62bef26dbf1f9022dd1d256b'; + const workflowGuard = stub('workflow'); + const workflowGuardSha256 = createHash('sha256').update(workflowGuard).digest('hex'); await expect(executeCompiledGuardLoader(script, { - workflowGuard: stub('workflow'), + workflowGuard, + head, + })).resolves.toBe(JSON.stringify({ + source: 'workflow', + operation: name, head, - })).resolves.toBe(JSON.stringify({ source: 'workflow', operation: name, head })); + options: { firstInstall: true, workflowSha: head, workflowGuardSha256 }, + })); await expect(executeCompiledGuardLoader(script, { baseGuard: stub('base'), baseManifest: true, - workflowGuard: stub('workflow'), + workflowGuard, head, - })).resolves.toBe(JSON.stringify({ source: 'base', operation: name, head })); + })).resolves.toBe(JSON.stringify({ + source: 'base', + operation: name, + head, + options: { firstInstall: false, workflowSha: head }, + })); await expect(executeCompiledGuardLoader(script, { baseManifest: true, - workflowGuard: stub('workflow'), + workflowGuard, head, })).rejects.toThrow( 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.', @@ -478,12 +671,47 @@ describe('gh-aw enforcing Squad reviewer', () => { await expect(executeCompiledGuardLoader(script, { baseGuard: 'this is not valid JavaScript', baseManifest: true, - workflowGuard: stub('workflow'), + workflowGuard, head, })).rejects.toThrow(); } }, 30000); + it('executes the live compiled identity contract for install and established reviews', () => { + const { lock } = compileReviewer(); + const safeOutputScript = compiledGuardScripts(lock) + .find(candidate => candidate.name === 'safe outputs')!.script; + + const cleanInstall = executeCompiledSafeOutputContract(safeOutputScript, 'clean-install'); + expect(cleanInstall.status, cleanInstall.diagnostics).toBe(0); + const cleanOutput = JSON.parse(cleanInstall.output!); + expect(cleanOutput.items[0].body).toContain( + '"author_agent":"@squad/bootstrap-installation"', + ); + expect(cleanOutput.items[0].body).toContain( + '"reviewer_agent":"@squad/bootstrap-review-workflow"', + ); + + const configured = executeCompiledSafeOutputContract(safeOutputScript, 'configured'); + expect(configured.status, configured.diagnostics).toBe(0); + const configuredOutput = JSON.parse(configured.output!); + expect(configuredOutput.items[0].body).toContain('"author_agent":"implementer"'); + expect(configuredOutput.items[0].body).toContain('"reviewer_agent":"reviewer"'); + + const establishedMissing = executeCompiledSafeOutputContract( + safeOutputScript, + 'established-missing', + ); + expect(establishedMissing.status).not.toBe(0); + expect(establishedMissing.diagnostics).toContain('Not Found'); + + const arbitraryClean = executeCompiledSafeOutputContract(safeOutputScript, 'clean-arbitrary'); + expect(arbitraryClean.status).not.toBe(0); + expect(arbitraryClean.diagnostics).toContain( + 'missing or duplicate first-install package provenance', + ); + }, 30000); + it('kills mutations of every important authority and provenance gate', () => { const mutations = [ REVIEWER.replace('tools:\n bash:', 'tools:\n edit:\n bash:'), diff --git a/workflows/package/squad-review.md b/workflows/package/squad-review.md index 4abbe4c70..0bb6b7f94 100644 --- a/workflows/package/squad-review.md +++ b/workflows/package/squad-review.md @@ -70,7 +70,8 @@ safe-outputs: SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }} with: script: | - const { existsSync } = require('node:fs'); + const { existsSync, readFileSync } = require('node:fs'); + const { createHash } = require('node:crypto'); const { pathToFileURL } = require('node:url'); const baseGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/workflows/shared/squad-review-guard.mjs`; @@ -79,18 +80,29 @@ safe-outputs: const workflowGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; let guardPath; + let firstInstall = false; if (existsSync(baseGuard)) { guardPath = baseGuard; } else if (!existsSync(baseManifest)) { guardPath = workflowGuard; + firstInstall = true; } else { throw new Error( 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.' ); } + const workflowGuardSha256 = firstInstall + ? createHash('sha256').update(readFileSync(workflowGuard)).digest('hex') + : undefined; const guard = await import(pathToFileURL(guardPath).href); await guard.enforceReviewOutputs(process.env, - async (route, fields) => (await github.request(`GET /${route}`, fields)).data); + async (route, fields) => (await github.request(`GET /${route}`, fields)).data, + { + firstInstall, + workflowSha: '${{ github.workflow_sha }}', + workflowGuardSha256, + workflowSource: process.env.GH_AW_WORKFLOW_SOURCE, + }); add-comment: max: 1 target: ${{ github.event.inputs.issue_number || github.event.pull_request.number }} @@ -150,7 +162,8 @@ jobs: SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} with: script: | - const { existsSync } = require('node:fs'); + const { existsSync, readFileSync } = require('node:fs'); + const { createHash } = require('node:crypto'); const { pathToFileURL } = require('node:url'); const baseGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/workflows/shared/squad-review-guard.mjs`; @@ -159,18 +172,24 @@ jobs: const workflowGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; let guardPath; + let firstInstall = false; if (existsSync(baseGuard)) { guardPath = baseGuard; } else if (!existsSync(baseManifest)) { guardPath = workflowGuard; + firstInstall = true; } else { throw new Error( 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.' ); } + const workflowGuardSha256 = firstInstall + ? createHash('sha256').update(readFileSync(workflowGuard)).digest('hex') + : undefined; const guard = await import(pathToFileURL(guardPath).href); await guard.assertClearingReview(process.env, - async (route, fields) => (await github.request(`GET /${route}`, fields)).data); + async (route, fields) => (await github.request(`GET /${route}`, fields)).data, + { firstInstall, workflowSha: '${{ github.workflow_sha }}', workflowGuardSha256 }); --- @@ -211,6 +230,22 @@ The deterministic output guard and final job repeat these checks. A refusal, missing verdict, stale head, or malformed provenance cannot clear the required `Squad Review / review` check. +A clean package-install PR is the only exception to the attribution-file +requirement. The deterministic guard recognizes it only when the PR base has +neither the installed review guard nor `.github/aw/squad-workflows.manifest.json`, +the guard is loaded from the immutable workflow commit, and the exact PR head +contains a valid `bradygaster/squad/workflows` installation manifest and package +provenance record. The source revision, complete eight-workflow topology, +manifest digest, and executing guard digest must agree. In that case only, +absent `.squad-review.json` binds the reserved synthetic attribution +`author_agent: @squad/bootstrap-installation` and +`reviewer_agent: @squad/bootstrap-review-workflow`. These values are outside +the configured stable-agent ID grammar and identify workflow roles, not a +human or committed Squad agent. A present malformed attribution, +an established installation missing attribution, or any non-404 read failure +remains a refusal. Never infer this exception from the PR title, body, branch, +author, or other mutable prose. + ## Provenance decision tree Classify provenance in this exact priority order. Never trust a title or author diff --git a/workflows/shared/squad-review-guard.mjs b/workflows/shared/squad-review-guard.mjs index c8386cd4b..2829bf1e4 100644 --- a/workflows/shared/squad-review-guard.mjs +++ b/workflows/shared/squad-review-guard.mjs @@ -1,4 +1,5 @@ import { readFileSync, writeFileSync } from 'node:fs'; +import { createHash } from 'node:crypto'; import { evaluateImplementDispatchInputs } from './squad-retro-provenance.mjs'; export const CHECK_NAME = 'Squad Review / review'; @@ -8,6 +9,20 @@ const WORKFLOW = '.github/workflows/squad-review.lock.yml'; const SHA = /^[0-9a-f]{40}$/; const ID = /^[a-z][a-z0-9-]*$/; const BOT = 'github-actions[bot]'; +const INSTALL_MANIFEST = '.github/aw/squad-workflows.manifest.json'; +const INSTALL_PACKAGES = '.github/aw/packages'; +const INSTALL_AUTHOR = '@squad/bootstrap-installation'; +const INSTALL_REVIEWER = '@squad/bootstrap-review-workflow'; +const INSTALL_WORKFLOWS = [ + 'squad', + 'squad-implement-worker', + 'squad-review', + 'squad-deps-worker', + 'squad-retro', + 'squad-improvement-worker', + 'squad-bootstrap', + 'squad-command-router', +]; function requireThat(condition, message) { if (!condition) throw new Error(`Squad review refused: ${message}`); @@ -88,15 +103,119 @@ async function list(get, route, field) { throw new Error('Squad review refused: evidence pagination exceeded bound'); } -async function committedJson(get, repository, path, ref) { +async function committedJsonEvidence(get, repository, path, ref, { allowMissing = false } = {}) { requireThat(SHA.test(ref), 'invalid committed evidence ref'); - const file = await get(`repos/${repository}/contents/${path}`, { ref }); + let file; + try { + file = await get(`repos/${repository}/contents/${path}`, { ref }); + } catch (error) { + if (allowMissing && error?.status === 404) return undefined; + throw error; + } requireThat(file?.type === 'file' && file.encoding === 'base64' && typeof file.content === 'string' && file.size <= 65536, `unreadable committed ${path}`); - return JSON.parse(Buffer.from(file.content, 'base64').toString('utf8')); + const content = Buffer.from(file.content, 'base64'); + return { + value: JSON.parse(content.toString('utf8')), + sha256: createHash('sha256').update(content).digest('hex'), + }; +} + +async function committedJson(get, repository, path, ref, options) { + return (await committedJsonEvidence(get, repository, path, ref, options))?.value; } -export async function reviewTarget(env, get, { relay = false } = {}) { +function validateFirstInstallManifest(value, guardSha256) { + const workflows = Array.isArray(value?.workflows) ? value.workflows : []; + const names = workflows.map(entry => entry?.name).sort(); + const guards = Array.isArray(value?.shared_runtime) + ? value.shared_runtime.filter(entry => entry?.path === 'shared/squad-review-guard.mjs') + : []; + const guard = guards[0]; + requireThat(value?.schema_version === 1 && + value.package === 'bradygaster/squad/workflows' && + value.revision_policy?.kind === 'immutable-git-commit' && + names.join('\0') === [...INSTALL_WORKFLOWS].sort().join('\0') && + workflows.every(entry => + entry?.destination === `.github/workflows/${entry.name}.md` && + entry?.lock === `.github/workflows/${entry.name}.lock.yml` && + typeof entry?.source_sha256 === 'string' && /^[0-9a-f]{64}$/.test(entry.source_sha256)) && + guards.length === 1 && + guard?.destination === '.github/workflows/shared/squad-review-guard.mjs' && + guard?.ownership === 'manifest' && guard?.sha256 === guardSha256, + 'invalid committed first-install manifest'); + return guard; +} + +async function validateFirstInstallPackage( + get, + repository, + ref, + manifest, + manifestSha256, + guardSha256, + workflowSource, +) { + const entries = await get(`repos/${repository}/contents/${INSTALL_PACKAGES}`, { ref }); + requireThat(Array.isArray(entries) && entries.length <= 64, + 'unreadable committed first-install package provenance'); + const packages = entries.filter(entry => + entry?.type === 'file' && + /^bradygaster-squad-workflows-[0-9a-f]{12}\.json$/.test(entry.name ?? '')); + requireThat(packages.length === 1, 'missing or duplicate first-install package provenance'); + const provenance = await committedJson( + get, + repository, + `${INSTALL_PACKAGES}/${packages[0].name}`, + ref, + ); + const revision = provenance?.resolvedCommit; + const sourceMatch = typeof workflowSource === 'string' + ? workflowSource.match( + /^bradygaster\/squad\/workflows\/package\/squad-review\.md@([0-9a-f]{40})$/, + ) + : undefined; + requireThat(provenance?.schemaVersion === 1 && + provenance.package === 'bradygaster/squad/workflows' && + SHA.test(revision ?? '') && + provenance.source === `bradygaster/squad/workflows@${revision}` && + Array.isArray(provenance.files) && + (workflowSource === undefined || sourceMatch?.[1] === revision), + 'invalid committed first-install package provenance'); + const files = new Map(provenance.files.map(entry => [entry?.destination, entry])); + requireThat(files.size === provenance.files.length, + 'duplicate committed first-install package paths'); + const required = [ + INSTALL_MANIFEST, + '.github/workflows/shared/squad-review-guard.mjs', + ...INSTALL_WORKFLOWS.flatMap(name => [ + `.github/workflows/${name}.md`, + `.github/workflows/${name}.lock.yml`, + ]), + ]; + requireThat(required.every(path => + files.get(path)?.destination === path && + typeof files.get(path)?.sha256 === 'string' && + /^[0-9a-f]{64}$/.test(files.get(path).sha256)), + 'incomplete committed first-install topology'); + requireThat( + files.get('.github/workflows/shared/squad-review-guard.mjs').sha256 === guardSha256 && + files.get(INSTALL_MANIFEST).sha256 === manifestSha256 && + manifest.package === provenance.package, + 'first-install package does not bind the executing guard'); +} + +export async function reviewTarget( + env, + get, + { + relay = false, + firstInstall = false, + workflowSha, + workflowGuardSha256, + workflowSource, + } = {}, +) { const repository = env.GITHUB_REPOSITORY; const number = Number(env.SQUAD_REVIEW_PR); requireThat(typeof repository === 'string' && /^[\w.-]+\/[\w.-]+$/.test(repository) && @@ -120,9 +239,53 @@ export async function reviewTarget(env, get, { relay = false } = {}) { requireThat(provenance.ok, 'malformed or duplicate implementation provenance'); issue = provenance.issue_number; } - const value = await committedJson(get, repository, '.squad-review.json', pr.head.sha); - const registry = await committedJson(get, repository, '.squad/casting/registry.json', pr.base.sha); - const attribution = validateAttribution(value, registry, repository, issue ?? value?.issue); + const value = await committedJson( + get, + repository, + '.squad-review.json', + pr.head.sha, + { allowMissing: firstInstall }, + ); + let attribution; + if (value === undefined) { + requireThat(firstInstall === true && relay === false && + env.GITHUB_EVENT_NAME === 'pull_request' && + SHA.test(workflowSha ?? '') && workflowSha === pr.head.sha && + typeof workflowGuardSha256 === 'string' && /^[0-9a-f]{64}$/.test(workflowGuardSha256), + 'missing committed attribution outside an immutable clean first install'); + const manifestEvidence = await committedJsonEvidence( + get, + repository, + INSTALL_MANIFEST, + pr.head.sha, + ); + const manifest = manifestEvidence.value; + validateFirstInstallManifest(manifest, workflowGuardSha256); + await validateFirstInstallPackage( + get, + repository, + pr.head.sha, + manifest, + manifestEvidence.sha256, + workflowGuardSha256, + workflowSource, + ); + attribution = { + schema: 'squad-review-author/v1', + repository, + issue: issue ?? number, + author_agent: INSTALL_AUTHOR, + reviewer_agent: INSTALL_REVIEWER, + }; + } else { + const registry = await committedJson( + get, + repository, + '.squad/casting/registry.json', + pr.base.sha, + ); + attribution = validateAttribution(value, registry, repository, issue ?? value?.issue); + } return { repository, pull_request: number, head_sha: pr.head.sha, author_agent: attribution.author_agent, reviewer_agent: attribution.reviewer_agent, pr, @@ -138,9 +301,11 @@ async function currentEvidence(target, get) { String(review.body ?? '').includes(VERDICT_PREFIX.trim())); } -export async function enforceReviewOutputs(env, get) { +export async function enforceReviewOutputs(env, get, options = {}) { requireThat(['pull_request', 'workflow_dispatch'].includes(env.GITHUB_EVENT_NAME), 'invalid event'); - const target = await reviewTarget(env, get); + requireThat(options.firstInstall !== true || typeof options.workflowSource === 'string', + 'first-install output binding requires immutable workflow source provenance'); + const target = await reviewTarget(env, get, options); const output = JSON.parse(readFileSync(env.GH_AW_AGENT_OUTPUT, 'utf8')); requireThat(Array.isArray(output.items), 'missing safe-output items'); const verdicts = output.items.filter(item => item.type === 'submit_pull_request_review'); @@ -183,13 +348,14 @@ export async function enforceReviewOutputs(env, get) { // not a native bot approval/rejection, drives the independent status check. item.event = 'COMMENT'; // Native review commit binding and a final live read prevent stale agent output passing. - await reviewTarget(env, get); + await reviewTarget(env, get, options); writeFileSync(env.GH_AW_AGENT_OUTPUT, JSON.stringify(output)); } -export async function assertClearingReview(env, get, { relay = false } = {}) { +export async function assertClearingReview(env, get, options = {}) { + const { relay = false } = options; requireThat(env.GITHUB_EVENT_NAME === 'pull_request', 'only PR runs can clear review'); - const target = await reviewTarget(env, get, { relay }); + const target = await reviewTarget(env, get, options); const candidates = await currentEvidence(target, get); requireThat(candidates.length === 1, 'missing or duplicate verdict evidence'); const review = candidates[0]; @@ -248,6 +414,6 @@ export async function assertClearingReview(env, get, { relay = false } = {}) { `repos/${target.repository}/collaborators/${comment.user.login}/permission`); requireThat(permission.permission === 'admin', 'override requires repository administrator'); } - await reviewTarget(env, get, { relay }); + await reviewTarget(env, get, options); return verdict; } diff --git a/workflows/squad-review.md b/workflows/squad-review.md index a9ce2e8ee..ce6acdb18 100644 --- a/workflows/squad-review.md +++ b/workflows/squad-review.md @@ -68,7 +68,8 @@ safe-outputs: SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }} with: script: | - const { existsSync } = require('node:fs'); + const { existsSync, readFileSync } = require('node:fs'); + const { createHash } = require('node:crypto'); const { pathToFileURL } = require('node:url'); const baseGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/workflows/shared/squad-review-guard.mjs`; @@ -77,18 +78,29 @@ safe-outputs: const workflowGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; let guardPath; + let firstInstall = false; if (existsSync(baseGuard)) { guardPath = baseGuard; } else if (!existsSync(baseManifest)) { guardPath = workflowGuard; + firstInstall = true; } else { throw new Error( 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.' ); } + const workflowGuardSha256 = firstInstall + ? createHash('sha256').update(readFileSync(workflowGuard)).digest('hex') + : undefined; const guard = await import(pathToFileURL(guardPath).href); await guard.enforceReviewOutputs(process.env, - async (route, fields) => (await github.request(`GET /${route}`, fields)).data); + async (route, fields) => (await github.request(`GET /${route}`, fields)).data, + { + firstInstall, + workflowSha: '${{ github.workflow_sha }}', + workflowGuardSha256, + workflowSource: process.env.GH_AW_WORKFLOW_SOURCE, + }); add-comment: max: 1 target: "${{ github.event.inputs.issue_number || github.event.pull_request.number }}" @@ -145,7 +157,8 @@ jobs: SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} with: script: | - const { existsSync } = require('node:fs'); + const { existsSync, readFileSync } = require('node:fs'); + const { createHash } = require('node:crypto'); const { pathToFileURL } = require('node:url'); const baseGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/workflows/shared/squad-review-guard.mjs`; @@ -154,18 +167,24 @@ jobs: const workflowGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; let guardPath; + let firstInstall = false; if (existsSync(baseGuard)) { guardPath = baseGuard; } else if (!existsSync(baseManifest)) { guardPath = workflowGuard; + firstInstall = true; } else { throw new Error( 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.' ); } + const workflowGuardSha256 = firstInstall + ? createHash('sha256').update(readFileSync(workflowGuard)).digest('hex') + : undefined; const guard = await import(pathToFileURL(guardPath).href); await guard.assertClearingReview(process.env, - async (route, fields) => (await github.request(`GET /${route}`, fields)).data); + async (route, fields) => (await github.request(`GET /${route}`, fields)).data, + { firstInstall, workflowSha: '${{ github.workflow_sha }}', workflowGuardSha256 }); --- # Squad Review @@ -205,6 +224,22 @@ The deterministic output guard and final job repeat these checks. A refusal, missing verdict, stale head, or malformed provenance cannot clear the required `Squad Review / review` check. +A clean package-install PR is the only exception to the attribution-file +requirement. The deterministic guard recognizes it only when the PR base has +neither the installed review guard nor `.github/aw/squad-workflows.manifest.json`, +the guard is loaded from the immutable workflow commit, and the exact PR head +contains a valid `bradygaster/squad/workflows` installation manifest and package +provenance record. The source revision, complete eight-workflow topology, +manifest digest, and executing guard digest must agree. In that case only, +absent `.squad-review.json` binds the reserved synthetic attribution +`author_agent: @squad/bootstrap-installation` and +`reviewer_agent: @squad/bootstrap-review-workflow`. These values are outside +the configured stable-agent ID grammar and identify workflow roles, not a +human or committed Squad agent. A present malformed attribution, +an established installation missing attribution, or any non-404 read failure +remains a refusal. Never infer this exception from the PR title, body, branch, +author, or other mutable prose. + ## Provenance decision tree Classify provenance in this exact priority order. Never trust a title or author diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 2bb0c4e5d..e5869bb37 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -28,7 +28,7 @@ "source": "workflows/package/squad-review.md", "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", - "source_sha256": "cae3f9ca8a32ca76cfd873941fafe38319fa53b35fb3478c2338732b8b9f63fd" + "source_sha256": "9a94aeed1f1b841c7581032361bfe0fc44e43e282ad10399c1c52176c66fd32a" }, { "name": "squad-deps-worker", @@ -73,7 +73,7 @@ "package_destination": ".github/workflows/shared/squad-review-guard.mjs", "destination": ".github/workflows/shared/squad-review-guard.mjs", "ownership": "manifest", - "sha256": "82ba4b8bc7262d53c0d849acd4468a0495827c60ed0f0715449aa4b8365c30b4" + "sha256": "5c62e45cc4d12a25e9a8d1a63dc274cef0fa811c3c0901a976a5e6d441c2c321" }, { "path": "shared/squad-install-verifier.mjs", From 37c788295b6b7c7a3cba62c3d7888ac9e05f03da Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 19:41:15 -0700 Subject: [PATCH 02/14] fix(gh-aw): verify clean-install package bytes Bind reserved first-install identities to immutable canonical package content, exact installed ownership bytes, and normalized compiled lock digests. Add live-loader mutation coverage for source, lock, canonical-content, and fetch failures.\n\nRefs #2103\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/gh-aw-quality.test.ts | 8 +- test/gh-aw-review-guard.test.ts | 221 ++++++++++------- test/gh-aw-review-workflow.test.ts | 182 +++++++++----- test/helpers/gh-aw-install-fixture.ts | 177 ++++++++++++++ workflows/package/squad-bootstrap.md | 2 +- workflows/package/squad-review.md | 30 ++- workflows/shared/squad-install-verifier.mjs | 100 +++++++- workflows/shared/squad-review-guard.mjs | 254 ++++++++++++++------ workflows/squad-bootstrap.md | 2 +- workflows/squad-review.md | 30 ++- workflows/squad-workflows.manifest.json | 28 ++- 11 files changed, 776 insertions(+), 258 deletions(-) create mode 100644 test/helpers/gh-aw-install-fixture.ts diff --git a/test/gh-aw-quality.test.ts b/test/gh-aw-quality.test.ts index 59cd432da..f05b2e6c1 100644 --- a/test/gh-aw-quality.test.ts +++ b/test/gh-aw-quality.test.ts @@ -16,6 +16,7 @@ import { execFileSync, execSync, spawnSync } from 'node:child_process'; import { createHash } from 'node:crypto'; import { minimatch } from 'minimatch'; import { POSIX_SHELL, NO_POSIX_SHELL_MESSAGE, requirePosixShell } from './posix-shell'; +import { createFirstInstallFixture } from './helpers/gh-aw-install-fixture.js'; import { extractRunBlocks, scanRunBlocks, @@ -3524,13 +3525,16 @@ describe('gh-aw: canonical package integrity contract', () => { function makeConsumer(revision = revisionA, materialize = true): string { const root = createTestWorkspace('gh-aw-package-contract-'); + const install = createFirstInstallFixture(revision); copyInto(root, CONTRACT_SOURCE, CONTRACT_DESTINATION); const contract = JSON.parse(readFileSync(join(process.cwd(), CONTRACT_SOURCE), 'utf8')); for (const workflow of contract.workflows) { - copyInto(root, workflow.source, workflow.destination); + const destination = join(root, workflow.destination); + mkdirSync(dirname(destination), { recursive: true }); + writeFileSync(destination, install.consumerFiles.get(workflow.destination)!); const lock = join(root, workflow.lock); mkdirSync(dirname(lock), { recursive: true }); - writeFileSync(lock, `# test lock for ${workflow.name}\n`); + writeFileSync(lock, install.consumerFiles.get(workflow.lock)!); } for (const resource of contract.shared_runtime) { copyInto(root, resource.source, resource.package_destination); diff --git a/test/gh-aw-review-guard.test.ts b/test/gh-aw-review-guard.test.ts index faf5b5d5c..2a79bbf8e 100644 --- a/test/gh-aw-review-guard.test.ts +++ b/test/gh-aw-review-guard.test.ts @@ -1,12 +1,16 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; -import { createHash } from 'node:crypto'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { assertClearingReview, CHECK_NAME, enforceReviewOutputs, OVERRIDE_PREFIX, reviewTarget, validateAttribution, validateVerdict, VERDICT_PREFIX, } from '../workflows/shared/squad-review-guard.mjs'; +import { + createFirstInstallFixture, + githubFile, + type InstallFixture, +} from './helpers/gh-aw-install-fixture.js'; const REPOSITORY = 'squad/example'; const HEAD = 'a'.repeat(40); @@ -17,13 +21,11 @@ const SUBMITTED = '2026-09-28T12:01:01Z'; const FINISHED = '2026-09-28T12:02:00Z'; const MERGED = '2026-09-28T12:03:00Z'; const NOW = Date.parse('2026-09-28T12:04:00Z'); -const GUARD_SHA256 = createHash('sha256') - .update(readFileSync(join(process.cwd(), 'workflows/shared/squad-review-guard.mjs'))) - .digest('hex'); -const INSTALL_WORKFLOWS = [ - 'squad', 'squad-implement-worker', 'squad-review', 'squad-deps-worker', - 'squad-retro', 'squad-improvement-worker', 'squad-bootstrap', 'squad-command-router', -]; +const FIRST_INSTALL = createFirstInstallFixture(HEAD); +const GUARD_PATH = '.github/workflows/shared/squad-review-guard.mjs'; +const GUARD_SHA256 = FIRST_INSTALL.provenance.files.find( + entry => entry.destination === GUARD_PATH, +)!.sha256; const workspaces: string[] = []; afterEach(() => { @@ -86,10 +88,13 @@ function fixture(relay = false) { reviews: [review], comments: [] as typeof comment[], permission: 'admin', missingManifest: false, calls: [] as string[], prReads: 0, changeAfterFirstRead: false, }; - const encode = (value: unknown) => ({ - type: 'file', encoding: 'base64', size: 1000, - content: Buffer.from(JSON.stringify(value)).toString('base64'), - }); + const encode = (value: unknown) => { + const content = Buffer.from(JSON.stringify(value)); + return { + type: 'file', encoding: 'base64', size: content.length, + content: content.toString('base64'), + }; + }; const get = async (route: string, fields?: Record) => { state.calls.push(route); if (route.endsWith('/pulls/42')) { @@ -125,72 +130,55 @@ function fixture(relay = false) { }; } -function firstInstallProof(guardSha256 = GUARD_SHA256) { - const manifest = { - schema_version: 1, - package: 'bradygaster/squad/workflows', - revision_policy: { kind: 'immutable-git-commit' }, - workflows: INSTALL_WORKFLOWS.map(name => ({ - name, - destination: `.github/workflows/${name}.md`, - lock: `.github/workflows/${name}.lock.yml`, - source_sha256: 'c'.repeat(64), - })), - shared_runtime: [{ - path: 'shared/squad-review-guard.mjs', - destination: '.github/workflows/shared/squad-review-guard.mjs', - ownership: 'manifest', - sha256: guardSha256, - }], - }; - const required = [ - '.github/aw/squad-workflows.manifest.json', - '.github/workflows/shared/squad-review-guard.mjs', - ...INSTALL_WORKFLOWS.flatMap(name => [ - `.github/workflows/${name}.md`, - `.github/workflows/${name}.lock.yml`, - ]), - ]; - const provenance = { - schemaVersion: 1, - package: 'bradygaster/squad/workflows', - source: `bradygaster/squad/workflows@${HEAD}`, - resolvedCommit: HEAD, - files: required.map(destination => ({ destination, sha256: 'd'.repeat(64) })), +function firstInstallProof(): InstallFixture { + return { + manifest: structuredClone(FIRST_INSTALL.manifest), + provenance: structuredClone(FIRST_INSTALL.provenance), + consumerFiles: new Map([...FIRST_INSTALL.consumerFiles].map( + ([path, content]) => [path, Buffer.from(content)], + )), + canonicalFiles: new Map([...FIRST_INSTALL.canonicalFiles].map( + ([path, content]) => [path, Buffer.from(content)], + )), }; - provenance.files.find(entry => - entry.destination === '.github/workflows/shared/squad-review-guard.mjs')!.sha256 = guardSha256; - provenance.files.find(entry => - entry.destination === '.github/aw/squad-workflows.manifest.json')!.sha256 = - createHash('sha256').update(JSON.stringify(manifest)).digest('hex'); - return { manifest, provenance }; +} + +async function firstInstallGet( + fixture: ReturnType, + proof: InstallFixture, + route: string, + fields?: Record, +) { + if (route.endsWith('/contents/.squad-review.json')) { + throw Object.assign(new Error('Not Found'), { status: 404 }); + } + if (route.endsWith('/contents/.github/aw/packages')) { + expect(fields?.ref).toBe(HEAD); + return [{ + type: 'file', + name: 'bradygaster-squad-workflows-3632054824e8.json', + }]; + } + if (route.endsWith( + '/contents/.github/aw/packages/bradygaster-squad-workflows-3632054824e8.json', + )) return fixture.encode(proof.provenance); + const marker = '/contents/'; + const path = route.slice(route.indexOf(marker) + marker.length); + const files = route.startsWith('repos/bradygaster/squad/') + ? proof.canonicalFiles + : proof.consumerFiles; + const content = files.get(path); + if (content) return githubFile(content); + return fixture.get(route, fields); } describe('independent Squad review guard', () => { it('uses reserved workflow-role attribution only for a proven clean package install', async () => { const f = fixture(); f.state.reviews = []; - const { manifest, provenance } = firstInstallProof(); - const get = async (route: string, fields?: Record) => { - if (route.endsWith('/contents/.squad-review.json')) { - throw Object.assign(new Error('Not Found'), { status: 404 }); - } - if (route.endsWith('/contents/.github/aw/squad-workflows.manifest.json')) { - expect(fields?.ref).toBe(HEAD); - return f.encode(manifest); - } - if (route.endsWith('/contents/.github/aw/packages')) { - expect(fields?.ref).toBe(HEAD); - return [{ - type: 'file', - name: 'bradygaster-squad-workflows-3632054824e8.json', - }]; - } - if (route.endsWith( - '/contents/.github/aw/packages/bradygaster-squad-workflows-3632054824e8.json', - )) return f.encode(provenance); - return f.get(route, fields); - }; + const proof = firstInstallProof(); + const get = (route: string, fields?: Record) => + firstInstallGet(f, proof, route, fields); const options = { firstInstall: true, workflowSha: HEAD, @@ -218,20 +206,9 @@ describe('independent Squad review guard', () => { it('refuses arbitrary clean-base PRs and malformed first-install proof', async () => { const f = fixture(); - const { manifest, provenance } = firstInstallProof(); - const missingAttribution = async (route: string, fields?: Record) => { - if (route.endsWith('/contents/.squad-review.json')) { - throw Object.assign(new Error('Not Found'), { status: 404 }); - } - if (route.endsWith('/contents/.github/aw/squad-workflows.manifest.json')) { - return f.encode(manifest); - } - if (route.endsWith('/contents/.github/aw/packages')) { - return [{ type: 'file', name: 'bradygaster-squad-workflows-3632054824e8.json' }]; - } - if (route.includes('/contents/.github/aw/packages/')) return f.encode(provenance); - return f.get(route, fields); - }; + const proof = firstInstallProof(); + const missingAttribution = (route: string, fields?: Record) => + firstInstallGet(f, proof, route, fields); const options = { firstInstall: true, workflowSha: HEAD, @@ -243,17 +220,23 @@ describe('independent Squad review guard', () => { ...options, workflowSha: BASE, })).rejects.toThrow('outside an immutable clean first install'); - manifest.workflows.pop(); + proof.manifest.workflows.pop(); + proof.canonicalFiles.set( + 'workflows/squad-workflows.manifest.json', + Buffer.from(`${JSON.stringify(proof.manifest, null, 2)}\n`), + ); await expect(reviewTarget(f.env, missingAttribution, options)) - .rejects.toThrow('invalid committed first-install manifest'); - manifest.workflows = firstInstallProof().manifest.workflows; - provenance.source = `bradygaster/squad/workflows@${BASE}`; + .rejects.toThrow('invalid immutable package manifest'); + const reset = firstInstallProof(); + proof.manifest = reset.manifest; + proof.canonicalFiles = reset.canonicalFiles; + proof.provenance.source = `bradygaster/squad/workflows@${BASE}`; await expect(reviewTarget(f.env, missingAttribution, options)) .rejects.toThrow('invalid committed first-install package provenance'); - provenance.source = `bradygaster/squad/workflows@${HEAD}`; - provenance.files.pop(); + proof.provenance.source = `bradygaster/squad/workflows@${HEAD}`; + proof.provenance.files.pop(); await expect(reviewTarget(f.env, missingAttribution, options)) - .rejects.toThrow('incomplete committed first-install topology'); + .rejects.toThrow('invalid committed first-install package provenance'); }); it('does not rescue malformed attribution or non-404 reads during first install', async () => { @@ -274,6 +257,60 @@ describe('independent Squad review guard', () => { }, options)).rejects.toThrow('Forbidden'); }); + it('hashes installed and immutable package bytes instead of trusting provenance claims', async () => { + const f = fixture(); + const options = { + firstInstall: true, + workflowSha: HEAD, + workflowGuardSha256: GUARD_SHA256, + workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${HEAD}`, + }; + const sourcePath = '.github/workflows/squad.md'; + const lockPath = '.github/workflows/squad.lock.yml'; + const canonicalPath = 'workflows/package/squad.md'; + + const changedSource = firstInstallProof(); + changedSource.consumerFiles.set( + sourcePath, + Buffer.concat([changedSource.consumerFiles.get(sourcePath)!, Buffer.from('\nattacker edit\n')]), + ); + await expect(reviewTarget( + f.env, + (route, fields) => firstInstallGet(f, changedSource, route, fields), + options, + )).rejects.toThrow(`installed bytes do not match ownership for ${sourcePath}`); + + const changedLock = firstInstallProof(); + changedLock.consumerFiles.set( + lockPath, + Buffer.concat([changedLock.consumerFiles.get(lockPath)!, Buffer.from('\nattacker edit\n')]), + ); + await expect(reviewTarget( + f.env, + (route, fields) => firstInstallGet(f, changedLock, route, fields), + options, + )).rejects.toThrow(`installed compiled lock mismatch for ${lockPath}`); + + const changedCanonical = firstInstallProof(); + changedCanonical.canonicalFiles.set( + canonicalPath, + Buffer.concat([changedCanonical.canonicalFiles.get(canonicalPath)!, Buffer.from('\nwrong\n')]), + ); + await expect(reviewTarget( + f.env, + (route, fields) => firstInstallGet(f, changedCanonical, route, fields), + options, + )).rejects.toThrow(`immutable package source digest mismatch for ${canonicalPath}`); + + const sourceFailure = firstInstallProof(); + await expect(reviewTarget(f.env, async (route, fields) => { + if (route === `repos/bradygaster/squad/contents/${canonicalPath}`) { + throw Object.assign(new Error('source fetch forbidden'), { status: 403 }); + } + return firstInstallGet(f, sourceFailure, route, fields); + }, options)).rejects.toThrow('source fetch forbidden'); + }); + it('accepts a distinct, committed, current-head verdict and merged-head relay', async () => { for (const relay of [false, true]) { const f = fixture(relay); diff --git a/test/gh-aw-review-workflow.test.ts b/test/gh-aw-review-workflow.test.ts index 2efb74ae7..0503fa107 100644 --- a/test/gh-aw-review-workflow.test.ts +++ b/test/gh-aw-review-workflow.test.ts @@ -5,6 +5,7 @@ import { createHash } from 'node:crypto'; import { dirname, resolve } from 'node:path'; import { fileURLToPath, pathToFileURL } from 'node:url'; import { extractSafeOutputsConfigJson } from './helpers/gh-aw-lock.js'; +import { createFirstInstallFixture } from './helpers/gh-aw-install-fixture.js'; import { parse } from 'yaml'; const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..'); @@ -18,6 +19,8 @@ const SHARED_BOOTSTRAP = read('workflows/shared/squad.md'); const REVIEWER_FRONTMATTER = frontmatter(REVIEWER); const ROUTER_FRONTMATTER = frontmatter(ROUTER); const compileWorkspaces: string[] = []; +const LIVE_INSTALL_REVISION = 'c'.repeat(40); +const LIVE_INSTALL = createFirstInstallFixture(LIVE_INSTALL_REVISION); function read(relativePath: string): string { return readFileSync(resolve(ROOT, relativePath), 'utf8').replace(/\r\n/g, '\n'); @@ -175,9 +178,8 @@ function assertCompiledGate(lock: string): void { expect(steps[guard].with.script).toContain('firstInstall = true'); expect(steps[guard].with.script).toContain("createHash('sha256')"); expect(steps[guard].with.script).toContain('workflowGuardSha256'); - expect(steps[guard].with.script).toContain( - 'workflowSource: process.env.GH_AW_WORKFLOW_SOURCE', - ); + expect(steps[guard].with.script).toContain('workflowSource'); + expect(steps[guard].with.script).toContain('workflowReview'); expect(steps[guard].with.script).toContain('missing from an established base installation'); const finalGate = review.steps.find((step: { name: string }) => step.name === 'Enforce independent current-head verdict'); @@ -186,6 +188,7 @@ function assertCompiledGate(lock: string): void { expect(finalGate.with.script).toContain('firstInstall = true'); expect(finalGate.with.script).toContain("createHash('sha256')"); expect(finalGate.with.script).toContain('workflowGuardSha256'); + expect(finalGate.with.script).toContain('workflowSource'); expect(finalGate.with.script).toContain('missing from an established base installation'); for (const step of review.steps) expect(step['continue-on-error']).toBeUndefined(); expect(review['continue-on-error']).toBeUndefined(); @@ -235,6 +238,10 @@ async function executeCompiledGuardLoader( const workflowPath = resolve(workspace, '.squad-review-workflow', guardPath); mkdirSync(dirname(workflowPath), { recursive: true }); writeFileSync(workflowPath, workflowGuard); + writeFileSync( + resolve(workspace, '.squad-review-workflow', '.github/workflows/squad-review.md'), + `---\nsource: bradygaster/squad/workflows/package/squad-review.md@${head}\n---\n`, + ); const previousWorkspace = process.env.GITHUB_WORKSPACE; const previousOutput = process.env.SQUAD_TEST_GUARD_OUTPUT; @@ -264,7 +271,15 @@ async function executeCompiledGuardLoader( function executeCompiledSafeOutputContract( script: string, - scenario: 'clean-install' | 'clean-arbitrary' | 'established-missing' | 'configured', + scenario: + | 'clean-install' + | 'clean-arbitrary' + | 'established-missing' + | 'configured' + | 'changed-source' + | 'changed-lock' + | 'canonical-mismatch' + | 'source-fetch-failure', ): { status: number | null; diagnostics: string; output?: string } { const workspace = mkdtempSync(resolve(ROOT, '.squad-review-live-contract-')); compileWorkspaces.push(workspace); @@ -275,8 +290,16 @@ function executeCompiledSafeOutputContract( ); mkdirSync(dirname(workflowShared), { recursive: true }); cpSync(resolve(ROOT, 'workflows/shared'), workflowShared, { recursive: true }); - const guardPath = resolve(workflowShared, 'squad-review-guard.mjs'); - const guardSha256 = createHash('sha256').update(readFileSync(guardPath)).digest('hex'); + const workflowReview = resolve( + workspace, + '.squad-review-workflow', + '.github/workflows/squad-review.md', + ); + mkdirSync(dirname(workflowReview), { recursive: true }); + writeFileSync( + workflowReview, + LIVE_INSTALL.consumerFiles.get('.github/workflows/squad-review.md')!, + ); if (scenario === 'established-missing' || scenario === 'configured') { const baseShared = resolve(workspace, '.squad-review-base', '.github/workflows/shared'); mkdirSync(dirname(baseShared), { recursive: true }); @@ -292,50 +315,39 @@ function executeCompiledSafeOutputContract( const head = 'a'.repeat(40); const base = 'b'.repeat(40); - const workflowNames = [ - 'squad', 'squad-implement-worker', 'squad-review', 'squad-deps-worker', - 'squad-retro', 'squad-improvement-worker', 'squad-bootstrap', 'squad-command-router', - ]; - const manifest = { - schema_version: 1, - package: 'bradygaster/squad/workflows', - revision_policy: { kind: 'immutable-git-commit' }, - workflows: workflowNames.map(name => ({ - name, - destination: `.github/workflows/${name}.md`, - lock: `.github/workflows/${name}.lock.yml`, - source_sha256: 'c'.repeat(64), - })), - shared_runtime: [{ - path: 'shared/squad-review-guard.mjs', - destination: '.github/workflows/shared/squad-review-guard.mjs', - ownership: 'manifest', - sha256: guardSha256, - }], - }; - const required = [ - '.github/aw/squad-workflows.manifest.json', - '.github/workflows/shared/squad-review-guard.mjs', - ...workflowNames.flatMap(name => [ - `.github/workflows/${name}.md`, - `.github/workflows/${name}.lock.yml`, - ]), - ]; - const provenance = { - schemaVersion: 1, - package: 'bradygaster/squad/workflows', - source: `bradygaster/squad/workflows@${'c'.repeat(40)}`, - resolvedCommit: 'c'.repeat(40), - files: required.map(destination => ({ - destination, - sha256: destination === '.github/workflows/shared/squad-review-guard.mjs' - ? guardSha256 - : 'd'.repeat(64), - })), - }; - provenance.files.find(entry => - entry.destination === '.github/aw/squad-workflows.manifest.json')!.sha256 = - createHash('sha256').update(JSON.stringify(manifest)).digest('hex'); + const consumerFiles = new Map([...LIVE_INSTALL.consumerFiles].map( + ([path, content]) => [path, Buffer.from(content)], + )); + const canonicalFiles = new Map([...LIVE_INSTALL.canonicalFiles].map( + ([path, content]) => [path, Buffer.from(content)], + )); + if (scenario === 'changed-source') { + consumerFiles.set( + '.github/workflows/squad.md', + Buffer.concat([consumerFiles.get('.github/workflows/squad.md')!, Buffer.from('\nchanged\n')]), + ); + } + if (scenario === 'changed-lock') { + consumerFiles.set( + '.github/workflows/squad.lock.yml', + Buffer.concat([ + consumerFiles.get('.github/workflows/squad.lock.yml')!, + Buffer.from('\nchanged\n'), + ]), + ); + } + if (scenario === 'canonical-mismatch') { + canonicalFiles.set( + 'workflows/package/squad.md', + Buffer.concat([canonicalFiles.get('workflows/package/squad.md')!, Buffer.from('\nchanged\n')]), + ); + } + const encodedConsumerFiles = Object.fromEntries([...consumerFiles].map( + ([path, content]) => [path, content.toString('base64')], + )); + const encodedCanonicalFiles = Object.fromEntries([...canonicalFiles].map( + ([path, content]) => [path, content.toString('base64')], + )); const outputPath = resolve(workspace, 'agent-output.json'); writeFileSync(outputPath, JSON.stringify({ items: [{ type: 'submit_pull_request_review', @@ -350,12 +362,18 @@ function executeCompiledSafeOutputContract( const head = ${JSON.stringify(head)}; const base = ${JSON.stringify(base)}; const scenario = ${JSON.stringify(scenario)}; - const encode = value => ({ - type: 'file', - encoding: 'base64', - size: 1000, - content: Buffer.from(JSON.stringify(value)).toString('base64'), - }); + const consumerFiles = ${JSON.stringify(encodedConsumerFiles)}; + const canonicalFiles = ${JSON.stringify(encodedCanonicalFiles)}; + const provenance = ${JSON.stringify(LIVE_INSTALL.provenance)}; + const encode = content => { + if (!Buffer.isBuffer(content)) content = Buffer.from(JSON.stringify(content)); + return { + type: 'file', + encoding: 'base64', + size: content.length, + content: content.toString('base64'), + }; + }; const attribution = { schema: 'squad-review-author/v1', repository: 'squad/example', @@ -390,7 +408,9 @@ function executeCompiledSafeOutputContract( return { data: encode(registry) }; } if (route.endsWith('/contents/.github/aw/squad-workflows.manifest.json')) { - return { data: encode(${JSON.stringify(manifest)}) }; + return { data: encode(Buffer.from(consumerFiles[ + '.github/aw/squad-workflows.manifest.json' + ], 'base64')) }; } if (route.endsWith('/contents/.github/aw/packages')) { if (scenario === 'clean-arbitrary') return { data: [] }; @@ -400,8 +420,17 @@ function executeCompiledSafeOutputContract( }] }; } if (route.includes('/contents/.github/aw/packages/')) { - return { data: encode(${JSON.stringify(provenance)}) }; + return { data: encode(provenance) }; + } + const marker = '/contents/'; + const path = route.slice(route.indexOf(marker) + marker.length); + const sourceRepository = route.startsWith('repos/bradygaster/squad/'); + if (sourceRepository && scenario === 'source-fetch-failure' && + path === 'workflows/package/squad.md') { + throw Object.assign(new Error('source fetch forbidden'), { status: 403 }); } + const files = sourceRepository ? canonicalFiles : consumerFiles; + if (files[path]) return { data: encode(Buffer.from(files[path], 'base64')) }; if (route.endsWith('/reviews')) return { data: [] }; throw new Error('Unexpected API route: ' + route + ' ' + JSON.stringify(fields)); }, @@ -421,7 +450,7 @@ function executeCompiledSafeOutputContract( GH_AW_AGENT_OUTPUT: outputPath, SQUAD_REVIEW_PR: '42', SQUAD_REVIEW_HEAD: head, - GH_AW_WORKFLOW_SOURCE: `bradygaster/squad/workflows/package/squad-review.md@${'c'.repeat(40)}`, + GH_AW_WORKFLOW_SOURCE: `bradygaster/squad/workflows/package/squad-review.md@${LIVE_INSTALL_REVISION}`, }, }); return { @@ -645,7 +674,12 @@ describe('gh-aw enforcing Squad reviewer', () => { source: 'workflow', operation: name, head, - options: { firstInstall: true, workflowSha: head, workflowGuardSha256 }, + options: { + firstInstall: true, + workflowSha: head, + workflowGuardSha256, + workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${head}`, + }, })); await expect(executeCompiledGuardLoader(script, { @@ -710,6 +744,34 @@ describe('gh-aw enforcing Squad reviewer', () => { expect(arbitraryClean.diagnostics).toContain( 'missing or duplicate first-install package provenance', ); + + const changedSource = executeCompiledSafeOutputContract(safeOutputScript, 'changed-source'); + expect(changedSource.status).not.toBe(0); + expect(changedSource.diagnostics).toContain( + 'installed bytes do not match ownership for .github/workflows/squad.md', + ); + + const changedLock = executeCompiledSafeOutputContract(safeOutputScript, 'changed-lock'); + expect(changedLock.status).not.toBe(0); + expect(changedLock.diagnostics).toContain( + 'installed compiled lock mismatch for .github/workflows/squad.lock.yml', + ); + + const canonicalMismatch = executeCompiledSafeOutputContract( + safeOutputScript, + 'canonical-mismatch', + ); + expect(canonicalMismatch.status).not.toBe(0); + expect(canonicalMismatch.diagnostics).toContain( + 'immutable package source digest mismatch for workflows/package/squad.md', + ); + + const sourceFetchFailure = executeCompiledSafeOutputContract( + safeOutputScript, + 'source-fetch-failure', + ); + expect(sourceFetchFailure.status).not.toBe(0); + expect(sourceFetchFailure.diagnostics).toContain('source fetch forbidden'); }, 30000); it('kills mutations of every important authority and provenance gate', () => { diff --git a/test/helpers/gh-aw-install-fixture.ts b/test/helpers/gh-aw-install-fixture.ts new file mode 100644 index 000000000..ba993bd7a --- /dev/null +++ b/test/helpers/gh-aw-install-fixture.ts @@ -0,0 +1,177 @@ +import { + cpSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { createHash } from 'node:crypto'; +import { execFileSync } from 'node:child_process'; +import { dirname, resolve } from 'node:path'; +import { + CONTRACT_DESTINATION, + CONTRACT_SOURCE, + PACKAGE_NAME, +} from '../../workflows/shared/squad-install-verifier.mjs'; + +interface ContractEntry { + source: string; + destination: string; + sha256: string; +} + +interface WorkflowEntry extends ContractEntry { + name: string; + lock: string; + source_sha256: string; + lock_sha256: string; +} + +interface RuntimeEntry extends ContractEntry { + path: string; + package_destination: string; + ownership: string; +} + +interface SkillEntry extends ContractEntry { + name: string; +} + +export interface InstallFixture { + manifest: { + workflows: WorkflowEntry[]; + shared_runtime: RuntimeEntry[]; + skills: SkillEntry[]; + }; + provenance: { + schemaVersion: number; + package: string; + source: string; + resolvedCommit: string; + installer: string; + files: ContractEntry[]; + }; + consumerFiles: Map; + canonicalFiles: Map; +} + +const fixtureCache = new Map(); + +function cloneFixture(fixture: InstallFixture): InstallFixture { + return { + manifest: structuredClone(fixture.manifest), + provenance: structuredClone(fixture.provenance), + consumerFiles: new Map([...fixture.consumerFiles].map( + ([path, content]) => [path, Buffer.from(content)], + )), + canonicalFiles: new Map([...fixture.canonicalFiles].map( + ([path, content]) => [path, Buffer.from(content)], + )), + }; +} + +function sha256(content: Buffer): string { + return createHash('sha256').update(content).digest('hex'); +} + +function withSource(content: Buffer, source: string, revision: string): Buffer { + const text = content.toString('utf8'); + const marker = '\n---\n'; + const end = text.indexOf(marker, 4); + if (!text.startsWith('---\n') || end < 0) throw new Error(`Invalid workflow source: ${source}`); + return Buffer.from( + `${text.slice(0, end)}\nsource: bradygaster/squad/${source}@${revision}${text.slice(end)}`, + ); +} + +export function githubFile(content: Buffer): { + type: string; + encoding: string; + size: number; + content: string; +} { + return { + type: 'file', + encoding: 'base64', + size: content.length, + content: content.toString('base64'), + }; +} + +export function createFirstInstallFixture(revision: string): InstallFixture { + const cached = fixtureCache.get(revision); + if (cached) return cloneFixture(cached); + const root = process.cwd(); + const manifestBytes = readFileSync(resolve(root, CONTRACT_SOURCE)); + const manifest = JSON.parse(manifestBytes.toString('utf8')); + const consumerFiles = new Map([[CONTRACT_DESTINATION, manifestBytes]]); + const canonicalFiles = new Map([[CONTRACT_SOURCE, manifestBytes]]); + const scratch = mkdtempSync(resolve(root, '.squad-install-fixture-')); + try { + const workflowRoot = resolve(scratch, '.github/workflows'); + mkdirSync(workflowRoot, { recursive: true }); + cpSync(resolve(root, 'workflows/shared'), resolve(workflowRoot, 'shared'), { recursive: true }); + + for (const entry of manifest.workflows as WorkflowEntry[]) { + const canonical = readFileSync(resolve(root, entry.source)); + canonicalFiles.set(entry.source, canonical); + const installed = withSource(canonical, entry.source, revision); + consumerFiles.set(entry.destination, installed); + const path = resolve(scratch, entry.destination); + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, installed); + } + execFileSync('git', ['init', '--quiet'], { cwd: scratch }); + execFileSync('gh', ['aw', 'compile', '--strict', '--no-check-update'], { + cwd: scratch, + stdio: 'pipe', + timeout: 120_000, + }); + for (const entry of manifest.workflows as WorkflowEntry[]) { + consumerFiles.set(entry.lock, readFileSync(resolve(scratch, entry.lock))); + } + + for (const entry of manifest.shared_runtime as RuntimeEntry[]) { + const canonical = readFileSync(resolve(root, entry.source)); + canonicalFiles.set(entry.source, canonical); + consumerFiles.set(entry.package_destination, canonical); + } + for (const entry of manifest.skills as SkillEntry[]) { + const canonical = readFileSync(resolve(root, entry.source)); + canonicalFiles.set(entry.source, canonical); + consumerFiles.set(entry.destination, canonical); + } + + const owned = [ + ...(manifest.workflows as WorkflowEntry[]).map( + ({ source, destination }) => ({ source, destination }), + ), + ...(manifest.shared_runtime as RuntimeEntry[]).map( + ({ source, package_destination: destination }) => ({ source, destination }), + ), + { source: CONTRACT_SOURCE, destination: CONTRACT_DESTINATION }, + ].sort((left, right) => left.destination.localeCompare(right.destination)); + const files = owned.map(entry => ({ + ...entry, + sha256: sha256(consumerFiles.get(entry.destination)!), + })); + const fixture = { + manifest, + provenance: { + schemaVersion: 1, + package: PACKAGE_NAME, + source: `${PACKAGE_NAME}@${revision}`, + resolvedCommit: revision, + installer: 'gh-aw v0.89.21 test', + files, + }, + consumerFiles, + canonicalFiles, + }; + fixtureCache.set(revision, fixture); + return cloneFixture(fixture); + } finally { + rmSync(scratch, { recursive: true, force: true }); + } +} diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index ef2a0cb15..303d23b10 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -151,7 +151,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "a8206bd6f8605915bd284b219a66db623eb2ee09a44a0ac51dd4304aed9d8b57" + check_hash "$install_verifier" "693e7f470637d54d9bd5fee1cb066005f71e98804971348a8510bd94a451f176" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/package/squad-review.md b/workflows/package/squad-review.md index 0bb6b7f94..9cdb14edd 100644 --- a/workflows/package/squad-review.md +++ b/workflows/package/squad-review.md @@ -79,6 +79,8 @@ safe-outputs: `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/aw/squad-workflows.manifest.json`; const workflowGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; + const workflowReview = + `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/squad-review.md`; let guardPath; let firstInstall = false; if (existsSync(baseGuard)) { @@ -94,6 +96,11 @@ safe-outputs: const workflowGuardSha256 = firstInstall ? createHash('sha256').update(readFileSync(workflowGuard)).digest('hex') : undefined; + const workflowSource = firstInstall + ? readFileSync(workflowReview, 'utf8').match( + /^source:\s+(bradygaster\/squad\/workflows\/package\/squad-review\.md@[0-9a-f]{40})$/m + )?.[1] + : undefined; const guard = await import(pathToFileURL(guardPath).href); await guard.enforceReviewOutputs(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data, @@ -101,7 +108,7 @@ safe-outputs: firstInstall, workflowSha: '${{ github.workflow_sha }}', workflowGuardSha256, - workflowSource: process.env.GH_AW_WORKFLOW_SOURCE, + workflowSource, }); add-comment: max: 1 @@ -171,6 +178,8 @@ jobs: `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/aw/squad-workflows.manifest.json`; const workflowGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; + const workflowReview = + `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/squad-review.md`; let guardPath; let firstInstall = false; if (existsSync(baseGuard)) { @@ -186,10 +195,20 @@ jobs: const workflowGuardSha256 = firstInstall ? createHash('sha256').update(readFileSync(workflowGuard)).digest('hex') : undefined; + const workflowSource = firstInstall + ? readFileSync(workflowReview, 'utf8').match( + /^source:\s+(bradygaster\/squad\/workflows\/package\/squad-review\.md@[0-9a-f]{40})$/m + )?.[1] + : undefined; const guard = await import(pathToFileURL(guardPath).href); await guard.assertClearingReview(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data, - { firstInstall, workflowSha: '${{ github.workflow_sha }}', workflowGuardSha256 }); + { + firstInstall, + workflowSha: '${{ github.workflow_sha }}', + workflowGuardSha256, + workflowSource, + }); --- @@ -235,8 +254,11 @@ requirement. The deterministic guard recognizes it only when the PR base has neither the installed review guard nor `.github/aw/squad-workflows.manifest.json`, the guard is loaded from the immutable workflow commit, and the exact PR head contains a valid `bradygaster/squad/workflows` installation manifest and package -provenance record. The source revision, complete eight-workflow topology, -manifest digest, and executing guard digest must agree. In that case only, +provenance record. Every installed workflow source, compiled lock, runtime +resource, skill, and manifest byte is fetched at the exact PR head and checked +against canonical content or normalized lock digests fetched from the immutable +package revision. The source revision, exact 8/17/1 topology, ownership shape, +and executing guard digest must agree. In that case only, absent `.squad-review.json` binds the reserved synthetic attribution `author_agent: @squad/bootstrap-installation` and `reviewer_agent: @squad/bootstrap-review-workflow`. These values are outside diff --git a/workflows/shared/squad-install-verifier.mjs b/workflows/shared/squad-install-verifier.mjs index cf2e6ec43..ea985fab0 100644 --- a/workflows/shared/squad-install-verifier.mjs +++ b/workflows/shared/squad-install-verifier.mjs @@ -32,6 +32,7 @@ export const TRIGGER_PROBE_DESTINATION = const SHA256_PATTERN = /^[0-9a-f]{64}$/; const REVISION_PATTERN = /^[0-9a-f]{40}$/; +const LOCK_REVISION_PLACEHOLDER = 'f'.repeat(40); function deepFreeze(value) { if (value && typeof value === 'object' && !Object.isFrozen(value)) { @@ -158,13 +159,18 @@ export function validateContract(contract) { assertArray(contract.workflows, WORKFLOW_TUPLES.length, 'Integrity contract workflows'); contract.workflows.forEach((entry, index) => { - assertKeys(entry, ['name', 'source', 'destination', 'lock', 'source_sha256'], `Workflow entry ${index}`); + assertKeys( + entry, + ['name', 'source', 'destination', 'lock', 'source_sha256', 'lock_sha256'], + `Workflow entry ${index}`, + ); const [name, source, destination, lock] = WORKFLOW_TUPLES[index]; if (entry.name !== name) throw new Error(`Workflow entry ${index} name must be ${name}.`); validatePathSyntax(entry.source, source, `Workflow ${name} source`); validatePathSyntax(entry.destination, destination, `Workflow ${name} destination`); validatePathSyntax(entry.lock, lock, `Workflow ${name} lock`); assertDigest(entry.source_sha256, `Workflow ${name} source_sha256`); + assertDigest(entry.lock_sha256, `Workflow ${name} lock_sha256`); }); assertArray(contract.shared_runtime, RUNTIME_TUPLES.length, 'Integrity contract shared_runtime'); @@ -320,7 +326,73 @@ function packageWorkflowSource(_root, name) { return `workflows/package/${name}.md`; } +function workflowWithSource(content, name, revision) { + const marker = '\n---\n'; + const end = content.indexOf(marker, 4); + if (!content.startsWith('---\n') || end < 0) { + throw new Error(`Generated package workflow has invalid frontmatter: ${name}`); + } + return `${content.slice(0, end)} +source: ${PACKAGE_NAME}/package/${name}.md@${revision}${content.slice(end)}`; +} + +export function normalizeCompiledLock(content, revision) { + if (!REVISION_PATTERN.test(revision)) { + throw new Error('Compiled lock revision must be a lowercase 40-character SHA.'); + } + const text = Buffer.isBuffer(content) ? content.toString('utf8') : String(content); + if (!text.includes(revision)) { + throw new Error('Compiled lock is not bound to the expected package revision.'); + } + const metadata = text.match( + /^(# gh-aw-metadata: \{[^\n]*"frontmatter_hash":")([0-9a-f]{64})("[^\n]*\})$/m, + ); + if (!metadata) throw new Error('Compiled lock has missing or malformed gh-aw metadata.'); + return text + .replace(metadata[0], `${metadata[1]}${'0'.repeat(64)}${metadata[3]}`) + .replaceAll(revision, LOCK_REVISION_PLACEHOLDER); +} + +function buildLockDigests(root, renderedWorkflows) { + const scratch = mkdtempSync(join(resolve(root), '.squad-gh-aw-lock-digests-')); + try { + const workflowRoot = resolve(scratch, '.github/workflows'); + mkdirSync(workflowRoot, { recursive: true }); + cpSync(resolve(root, 'workflows/shared'), resolve(workflowRoot, 'shared'), { recursive: true }); + for (const [name, content] of renderedWorkflows) { + writeFileSync( + resolve(workflowRoot, `${name}.md`), + workflowWithSource(content, name, LOCK_REVISION_PLACEHOLDER), + ); + } + spawnChecked('git', ['init', '--quiet'], scratch); + const ghAwBin = process.env.SQUAD_GH_AW_BIN; + const command = ghAwBin || 'gh'; + const args = ghAwBin + ? ['compile', '--strict', '--no-check-update'] + : ['aw', 'compile', '--strict', '--no-check-update']; + const result = spawnSync(command, args, { + cwd: scratch, + encoding: 'utf8', + env: process.env, + }); + if (result.error || result.status !== 0) { + throw result.error ?? new Error(`${command} failed:\n${result.stdout}${result.stderr}`); + } + return new Map(WORKFLOW_NAMES.map((name) => { + const lock = readRequired(scratch, `.github/workflows/${name}.lock.yml`); + return [name, sha256(normalizeCompiledLock(lock, LOCK_REVISION_PLACEHOLDER))]; + })); + } finally { + rmSync(scratch, { recursive: true, force: true }); + } +} + export function buildContract(root) { + const renderedWorkflows = new Map(WORKFLOW_NAMES.map( + name => [name, readFileSync(resolve(root, `workflows/package/${name}.md`), 'utf8')], + )); + const lockDigests = buildLockDigests(root, renderedWorkflows); return validateContract({ schema_version: 1, package: PACKAGE_NAME, @@ -329,10 +401,15 @@ export function buildContract(root) { revision_policy: { ...REVISION_POLICY }, workflows: WORKFLOW_TUPLES.map(([name, , destination, lock]) => { const source = packageWorkflowSource(root, name); - const content = source.startsWith('workflows/package/') - ? renderPackageWorkflow(root, name) - : readFileSync(resolve(root, source)); - return { name, source, destination, lock, source_sha256: sha256(content) }; + const content = renderedWorkflows.get(name); + return { + name, + source, + destination, + lock, + source_sha256: sha256(content), + lock_sha256: lockDigests.get(name), + }; }), shared_runtime: RUNTIME_TUPLES.map( ([path, source, package_destination, destination, ownership]) => ({ @@ -420,10 +497,13 @@ function updateEmbeddedDigests(root) { export function writeSource(root) { updateEmbeddedDigests(root); - for (const [path, content] of generatedFiles(root)) { + for (const name of WORKFLOW_NAMES) { + const path = resolve(root, `workflows/package/${name}.md`); mkdirSync(dirname(path), { recursive: true }); - writeFileSync(path, content); + writeFileSync(path, renderPackageWorkflow(root, name)); } + writeFileSync(resolve(root, PACKAGE_MANIFEST), renderManifest(root)); + writeFileSync(resolve(root, CONTRACT_SOURCE), stableJson(buildContract(root))); } export function checkSource(root) { @@ -565,6 +645,12 @@ function verifyInstalledBytes(root, contract, revision) { } } for (const entry of contract.workflows) readRequired(root, entry.lock); + for (const entry of contract.workflows) { + const normalized = normalizeCompiledLock(readRequired(root, entry.lock), revision); + if (sha256(normalized) !== entry.lock_sha256) { + throw new Error(`Installed digest mismatch for ${entry.lock}.`); + } + } } function verifyTriggerNamespace(root) { diff --git a/workflows/shared/squad-review-guard.mjs b/workflows/shared/squad-review-guard.mjs index 2829bf1e4..558d6d64b 100644 --- a/workflows/shared/squad-review-guard.mjs +++ b/workflows/shared/squad-review-guard.mjs @@ -1,6 +1,18 @@ import { readFileSync, writeFileSync } from 'node:fs'; import { createHash } from 'node:crypto'; import { evaluateImplementDispatchInputs } from './squad-retro-provenance.mjs'; +import { + CONTRACT_DESTINATION, + CONTRACT_SOURCE, + MIN_GH_AW_VERSION, + OWNERSHIP_ENTRY_COUNT, + PACKAGE_NAME, + RUNTIME_TUPLES, + SKILL_TUPLES, + WORKFLOW_TUPLES, + normalizeCompiledLock, + validateContract, +} from './squad-install-verifier.mjs'; export const CHECK_NAME = 'Squad Review / review'; export const VERDICT_PREFIX = 'Squad-Review-Verdict: '; @@ -9,20 +21,12 @@ const WORKFLOW = '.github/workflows/squad-review.lock.yml'; const SHA = /^[0-9a-f]{40}$/; const ID = /^[a-z][a-z0-9-]*$/; const BOT = 'github-actions[bot]'; -const INSTALL_MANIFEST = '.github/aw/squad-workflows.manifest.json'; +const INSTALL_MANIFEST = CONTRACT_DESTINATION; const INSTALL_PACKAGES = '.github/aw/packages'; const INSTALL_AUTHOR = '@squad/bootstrap-installation'; const INSTALL_REVIEWER = '@squad/bootstrap-review-workflow'; -const INSTALL_WORKFLOWS = [ - 'squad', - 'squad-implement-worker', - 'squad-review', - 'squad-deps-worker', - 'squad-retro', - 'squad-improvement-worker', - 'squad-bootstrap', - 'squad-command-router', -]; +const INSTALL_SOURCE_REPOSITORY = 'bradygaster/squad'; +const SHA256 = /^[0-9a-f]{64}$/; function requireThat(condition, message) { if (!condition) throw new Error(`Squad review refused: ${message}`); @@ -103,7 +107,13 @@ async function list(get, route, field) { throw new Error('Squad review refused: evidence pagination exceeded bound'); } -async function committedJsonEvidence(get, repository, path, ref, { allowMissing = false } = {}) { +async function committedFileEvidence( + get, + repository, + path, + ref, + { allowMissing = false, maximumSize = 2_000_000 } = {}, +) { requireThat(SHA.test(ref), 'invalid committed evidence ref'); let file; try { @@ -113,49 +123,68 @@ async function committedJsonEvidence(get, repository, path, ref, { allowMissing throw error; } requireThat(file?.type === 'file' && file.encoding === 'base64' && - typeof file.content === 'string' && file.size <= 65536, `unreadable committed ${path}`); + typeof file.content === 'string' && Number.isSafeInteger(file.size) && + file.size >= 0 && file.size <= maximumSize, `unreadable committed ${path}`); const content = Buffer.from(file.content, 'base64'); + requireThat(content.length === file.size, `truncated committed ${path}`); return { - value: JSON.parse(content.toString('utf8')), + content, sha256: createHash('sha256').update(content).digest('hex'), }; } +async function committedJsonEvidence(get, repository, path, ref, options) { + const evidence = await committedFileEvidence(get, repository, path, ref, options); + if (evidence === undefined) return undefined; + return { + ...evidence, + value: JSON.parse(evidence.content.toString('utf8')), + }; +} + async function committedJson(get, repository, path, ref, options) { return (await committedJsonEvidence(get, repository, path, ref, options))?.value; } -function validateFirstInstallManifest(value, guardSha256) { - const workflows = Array.isArray(value?.workflows) ? value.workflows : []; - const names = workflows.map(entry => entry?.name).sort(); - const guards = Array.isArray(value?.shared_runtime) - ? value.shared_runtime.filter(entry => entry?.path === 'shared/squad-review-guard.mjs') - : []; - const guard = guards[0]; - requireThat(value?.schema_version === 1 && - value.package === 'bradygaster/squad/workflows' && - value.revision_policy?.kind === 'immutable-git-commit' && - names.join('\0') === [...INSTALL_WORKFLOWS].sort().join('\0') && - workflows.every(entry => - entry?.destination === `.github/workflows/${entry.name}.md` && - entry?.lock === `.github/workflows/${entry.name}.lock.yml` && - typeof entry?.source_sha256 === 'string' && /^[0-9a-f]{64}$/.test(entry.source_sha256)) && - guards.length === 1 && - guard?.destination === '.github/workflows/shared/squad-review-guard.mjs' && - guard?.ownership === 'manifest' && guard?.sha256 === guardSha256, - 'invalid committed first-install manifest'); - return guard; +function sha256(content) { + return createHash('sha256').update(content).digest('hex'); } -async function validateFirstInstallPackage( - get, - repository, - ref, - manifest, - manifestSha256, - guardSha256, - workflowSource, -) { +function exactObjectKeys(value, expected, label) { + requireThat(exactKeys(value, expected), `invalid ${label} shape`); +} + +function expectedOwnership(manifest) { + return [ + ...manifest.workflows.map(({ source, destination }) => ({ source, destination })), + ...manifest.shared_runtime.map(({ source, package_destination: destination }) => ({ + source, + destination, + })), + { source: CONTRACT_SOURCE, destination: CONTRACT_DESTINATION }, + ].sort((left, right) => left.destination.localeCompare(right.destination)); +} + +function workflowSourceBytes(content, source, revision) { + const text = content.toString('utf8'); + const bindings = [ + `source: ${PACKAGE_NAME}@${revision}`, + `source: bradygaster/squad/${source}@${revision}`, + ]; + let canonical = text; + let matches = 0; + for (const binding of bindings) { + const marker = `\n${binding}\n---\n`; + if (canonical.includes(marker)) { + canonical = canonical.replace(marker, '\n---\n'); + matches++; + } + } + requireThat(matches === 1, `installed workflow source binding mismatch for ${source}`); + return Buffer.from(canonical); +} + +async function validateFirstInstallPackage(get, repository, ref, workflowSource, guardSha256) { const entries = await get(`repos/${repository}/contents/${INSTALL_PACKAGES}`, { ref }); requireThat(Array.isArray(entries) && entries.length <= 64, 'unreadable committed first-install package provenance'); @@ -175,33 +204,114 @@ async function validateFirstInstallPackage( /^bradygaster\/squad\/workflows\/package\/squad-review\.md@([0-9a-f]{40})$/, ) : undefined; - requireThat(provenance?.schemaVersion === 1 && - provenance.package === 'bradygaster/squad/workflows' && + exactObjectKeys( + provenance, + ['schemaVersion', 'package', 'source', 'resolvedCommit', 'installer', 'files'], + 'committed first-install package provenance', + ); + requireThat(provenance.schemaVersion === 1 && + provenance.package === PACKAGE_NAME && SHA.test(revision ?? '') && - provenance.source === `bradygaster/squad/workflows@${revision}` && - Array.isArray(provenance.files) && - (workflowSource === undefined || sourceMatch?.[1] === revision), + provenance.source === `${PACKAGE_NAME}@${revision}` && + typeof provenance.installer === 'string' && + new RegExp(`^gh-aw ${MIN_GH_AW_VERSION.replaceAll('.', '\\.')}(?:\\b|$)`) + .test(provenance.installer) && + Array.isArray(provenance.files) && provenance.files.length === OWNERSHIP_ENTRY_COUNT && + sourceMatch?.[1] === revision, 'invalid committed first-install package provenance'); - const files = new Map(provenance.files.map(entry => [entry?.destination, entry])); - requireThat(files.size === provenance.files.length, - 'duplicate committed first-install package paths'); - const required = [ + + const canonicalManifestEvidence = await committedFileEvidence( + get, + INSTALL_SOURCE_REPOSITORY, + CONTRACT_SOURCE, + revision, + ); + let manifest; + try { + manifest = JSON.parse(canonicalManifestEvidence.content.toString('utf8')); + validateContract(manifest); + } catch (error) { + throw new Error(`Squad review refused: invalid immutable package manifest: ${error.message}`); + } + const installedManifestEvidence = await committedFileEvidence( + get, + repository, INSTALL_MANIFEST, - '.github/workflows/shared/squad-review-guard.mjs', - ...INSTALL_WORKFLOWS.flatMap(name => [ - `.github/workflows/${name}.md`, - `.github/workflows/${name}.lock.yml`, - ]), - ]; - requireThat(required.every(path => - files.get(path)?.destination === path && - typeof files.get(path)?.sha256 === 'string' && - /^[0-9a-f]{64}$/.test(files.get(path).sha256)), - 'incomplete committed first-install topology'); + ref, + ); requireThat( - files.get('.github/workflows/shared/squad-review-guard.mjs').sha256 === guardSha256 && - files.get(INSTALL_MANIFEST).sha256 === manifestSha256 && - manifest.package === provenance.package, + installedManifestEvidence.content.equals(canonicalManifestEvidence.content), + 'installed manifest is not byte-identical to the immutable package manifest', + ); + + const expected = expectedOwnership(manifest); + const seen = new Set(); + const installedOwned = new Map(); + for (let index = 0; index < expected.length; index++) { + const owned = provenance.files[index]; + const trusted = expected[index]; + exactObjectKeys(owned, ['source', 'destination', 'sha256'], `ownership file ${index}`); + requireThat(owned.source === trusted.source && owned.destination === trusted.destination && + SHA256.test(owned.sha256), `moved or malformed ownership file ${index}`); + requireThat(!seen.has(owned.destination), `duplicate ownership destination ${owned.destination}`); + seen.add(owned.destination); + const evidence = await committedFileEvidence(get, repository, owned.destination, ref); + requireThat(evidence.sha256 === owned.sha256, + `installed bytes do not match ownership for ${owned.destination}`); + installedOwned.set(owned.destination, evidence); + } + + const canonicalSources = new Map(await Promise.all([ + ...manifest.workflows.map(entry => entry.source), + ...manifest.shared_runtime.map(entry => entry.source), + ...manifest.skills.map(entry => entry.source), + ].map(async source => [ + source, + await committedFileEvidence(get, INSTALL_SOURCE_REPOSITORY, source, revision), + ]))); + + for (const entry of manifest.workflows) { + const canonical = canonicalSources.get(entry.source); + requireThat(canonical.sha256 === entry.source_sha256, + `immutable package source digest mismatch for ${entry.source}`); + const installed = installedOwned.get(entry.destination); + const canonicalized = workflowSourceBytes(installed.content, entry.source, revision); + requireThat( + sha256(canonicalized) === canonical.sha256 || + sha256(Buffer.from(`${canonicalized.toString('utf8')}\n`)) === canonical.sha256, + `installed workflow content mismatch for ${entry.destination}`, + ); + const lock = await committedFileEvidence(get, repository, entry.lock, ref); + requireThat( + sha256(normalizeCompiledLock(lock.content, revision)) === entry.lock_sha256, + `installed compiled lock mismatch for ${entry.lock}`, + ); + } + + for (const entry of manifest.shared_runtime) { + const canonical = canonicalSources.get(entry.source); + requireThat(canonical.sha256 === entry.sha256, + `immutable runtime digest mismatch for ${entry.source}`); + const installed = installedOwned.get(entry.package_destination); + requireThat(installed.content.equals(canonical.content), + `installed runtime content mismatch for ${entry.package_destination}`); + } + + for (const entry of manifest.skills) { + const canonical = canonicalSources.get(entry.source); + requireThat(canonical.sha256 === entry.sha256, + `immutable skill digest mismatch for ${entry.source}`); + const installed = await committedFileEvidence(get, repository, entry.destination, ref); + requireThat(installed.content.equals(canonical.content), + `installed skill content mismatch for ${entry.destination}`); + } + + const guard = manifest.shared_runtime.find( + entry => entry.path === 'shared/squad-review-guard.mjs', + ); + requireThat(guard?.package_destination === '.github/workflows/shared/squad-review-guard.mjs' && + installedOwned.get(guard.package_destination)?.sha256 === guardSha256 && + canonicalSources.get(guard.source)?.sha256 === guardSha256, 'first-install package does not bind the executing guard'); } @@ -253,22 +363,12 @@ export async function reviewTarget( SHA.test(workflowSha ?? '') && workflowSha === pr.head.sha && typeof workflowGuardSha256 === 'string' && /^[0-9a-f]{64}$/.test(workflowGuardSha256), 'missing committed attribution outside an immutable clean first install'); - const manifestEvidence = await committedJsonEvidence( - get, - repository, - INSTALL_MANIFEST, - pr.head.sha, - ); - const manifest = manifestEvidence.value; - validateFirstInstallManifest(manifest, workflowGuardSha256); await validateFirstInstallPackage( get, repository, pr.head.sha, - manifest, - manifestEvidence.sha256, - workflowGuardSha256, workflowSource, + workflowGuardSha256, ); attribution = { schema: 'squad-review-author/v1', diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index 130efe8f8..b1c8fddf7 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -158,7 +158,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "a8206bd6f8605915bd284b219a66db623eb2ee09a44a0ac51dd4304aed9d8b57" + check_hash "$install_verifier" "693e7f470637d54d9bd5fee1cb066005f71e98804971348a8510bd94a451f176" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/squad-review.md b/workflows/squad-review.md index ce6acdb18..7e38a0f55 100644 --- a/workflows/squad-review.md +++ b/workflows/squad-review.md @@ -77,6 +77,8 @@ safe-outputs: `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/aw/squad-workflows.manifest.json`; const workflowGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; + const workflowReview = + `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/squad-review.md`; let guardPath; let firstInstall = false; if (existsSync(baseGuard)) { @@ -92,6 +94,11 @@ safe-outputs: const workflowGuardSha256 = firstInstall ? createHash('sha256').update(readFileSync(workflowGuard)).digest('hex') : undefined; + const workflowSource = firstInstall + ? readFileSync(workflowReview, 'utf8').match( + /^source:\s+(bradygaster\/squad\/workflows\/package\/squad-review\.md@[0-9a-f]{40})$/m + )?.[1] + : undefined; const guard = await import(pathToFileURL(guardPath).href); await guard.enforceReviewOutputs(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data, @@ -99,7 +106,7 @@ safe-outputs: firstInstall, workflowSha: '${{ github.workflow_sha }}', workflowGuardSha256, - workflowSource: process.env.GH_AW_WORKFLOW_SOURCE, + workflowSource, }); add-comment: max: 1 @@ -166,6 +173,8 @@ jobs: `${process.env.GITHUB_WORKSPACE}/.squad-review-base/.github/aw/squad-workflows.manifest.json`; const workflowGuard = `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/shared/squad-review-guard.mjs`; + const workflowReview = + `${process.env.GITHUB_WORKSPACE}/.squad-review-workflow/.github/workflows/squad-review.md`; let guardPath; let firstInstall = false; if (existsSync(baseGuard)) { @@ -181,10 +190,20 @@ jobs: const workflowGuardSha256 = firstInstall ? createHash('sha256').update(readFileSync(workflowGuard)).digest('hex') : undefined; + const workflowSource = firstInstall + ? readFileSync(workflowReview, 'utf8').match( + /^source:\s+(bradygaster\/squad\/workflows\/package\/squad-review\.md@[0-9a-f]{40})$/m + )?.[1] + : undefined; const guard = await import(pathToFileURL(guardPath).href); await guard.assertClearingReview(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data, - { firstInstall, workflowSha: '${{ github.workflow_sha }}', workflowGuardSha256 }); + { + firstInstall, + workflowSha: '${{ github.workflow_sha }}', + workflowGuardSha256, + workflowSource, + }); --- # Squad Review @@ -229,8 +248,11 @@ requirement. The deterministic guard recognizes it only when the PR base has neither the installed review guard nor `.github/aw/squad-workflows.manifest.json`, the guard is loaded from the immutable workflow commit, and the exact PR head contains a valid `bradygaster/squad/workflows` installation manifest and package -provenance record. The source revision, complete eight-workflow topology, -manifest digest, and executing guard digest must agree. In that case only, +provenance record. Every installed workflow source, compiled lock, runtime +resource, skill, and manifest byte is fetched at the exact PR head and checked +against canonical content or normalized lock digests fetched from the immutable +package revision. The source revision, exact 8/17/1 topology, ownership shape, +and executing guard digest must agree. In that case only, absent `.squad-review.json` binds the reserved synthetic attribution `author_agent: @squad/bootstrap-installation` and `reviewer_agent: @squad/bootstrap-review-workflow`. These values are outside diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index e5869bb37..06183ee89 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -14,56 +14,64 @@ "source": "workflows/package/squad.md", "destination": ".github/workflows/squad.md", "lock": ".github/workflows/squad.lock.yml", - "source_sha256": "17d7b124e5d3f06d8c1ea67a7330366b40f3e69d2209e8477fe4fa38a1ae38b0" + "source_sha256": "17d7b124e5d3f06d8c1ea67a7330366b40f3e69d2209e8477fe4fa38a1ae38b0", + "lock_sha256": "c8f1375aab790ef9ca7531fabdc5a80423865e3981db127b6e2cb994d32b7e87" }, { "name": "squad-implement-worker", "source": "workflows/package/squad-implement-worker.md", "destination": ".github/workflows/squad-implement-worker.md", "lock": ".github/workflows/squad-implement-worker.lock.yml", - "source_sha256": "ae710dd5c89360af540576dac378a0d0df129cce5a9bbf16f0615dfd86d0b21c" + "source_sha256": "ae710dd5c89360af540576dac378a0d0df129cce5a9bbf16f0615dfd86d0b21c", + "lock_sha256": "d6d2fa7f2bac5845c414cf42a9ea565d3663dba23d9208942fe142fca6b23bc3" }, { "name": "squad-review", "source": "workflows/package/squad-review.md", "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", - "source_sha256": "9a94aeed1f1b841c7581032361bfe0fc44e43e282ad10399c1c52176c66fd32a" + "source_sha256": "bc0010ecb866f37c3e4d47254c2f474cfbcd730c72ee9115bce266217d3f6665", + "lock_sha256": "6fa3247bc556328c706c52f79392b3f700c313438ce0c1789bd85cd32d7c1d2a" }, { "name": "squad-deps-worker", "source": "workflows/package/squad-deps-worker.md", "destination": ".github/workflows/squad-deps-worker.md", "lock": ".github/workflows/squad-deps-worker.lock.yml", - "source_sha256": "37c4ba60b85c5fc07bef322bbfd0f713472924d55cff9481ae76af7ec0c91fac" + "source_sha256": "37c4ba60b85c5fc07bef322bbfd0f713472924d55cff9481ae76af7ec0c91fac", + "lock_sha256": "d5a8c0b1eb7933bb4bb74499fd9de872b6d55045665f918c831658f8baa20f71" }, { "name": "squad-retro", "source": "workflows/package/squad-retro.md", "destination": ".github/workflows/squad-retro.md", "lock": ".github/workflows/squad-retro.lock.yml", - "source_sha256": "92bcfa39cc5fd3087b11612125e314959237c5b79460825453d1e493727a2562" + "source_sha256": "92bcfa39cc5fd3087b11612125e314959237c5b79460825453d1e493727a2562", + "lock_sha256": "067e0a2d87a1ef6f8e183c5167d0ccdbd993afe01dbd2259622317e18e981d67" }, { "name": "squad-improvement-worker", "source": "workflows/package/squad-improvement-worker.md", "destination": ".github/workflows/squad-improvement-worker.md", "lock": ".github/workflows/squad-improvement-worker.lock.yml", - "source_sha256": "01c89f8890f02c0ca884513aa10225787feaf3606ab604d5c0e85fbbccdb6c95" + "source_sha256": "01c89f8890f02c0ca884513aa10225787feaf3606ab604d5c0e85fbbccdb6c95", + "lock_sha256": "880b7673b022d6155870d87b70e6d6a2489eb7eefec64fcf3515041d5ca5c42e" }, { "name": "squad-bootstrap", "source": "workflows/package/squad-bootstrap.md", "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", - "source_sha256": "a7d9d072d4a626c1d35677fa323f3b7af7a66efe0eca4b3b94042eb1c656d3a7" + "source_sha256": "62ae7212d23e893c2f45adf7ad7a26b995f90e0e3cdc7b5e129dbec2f2445c82", + "lock_sha256": "32d9b9f7522a9eecae9912e206b08d7603f104a378bd3ee272f442ef87987c9c" }, { "name": "squad-command-router", "source": "workflows/package/squad-command-router.md", "destination": ".github/workflows/squad-command-router.md", "lock": ".github/workflows/squad-command-router.lock.yml", - "source_sha256": "cbce466a6cfe64c194b17672ea3363fe7c22cb6b4258c195cc93a2d294d0bf88" + "source_sha256": "cbce466a6cfe64c194b17672ea3363fe7c22cb6b4258c195cc93a2d294d0bf88", + "lock_sha256": "9c5bf2b28dc82a575c528ce73a75c38b54129d512341e10cdce2a6e12ceecb4b" } ], "shared_runtime": [ @@ -73,7 +81,7 @@ "package_destination": ".github/workflows/shared/squad-review-guard.mjs", "destination": ".github/workflows/shared/squad-review-guard.mjs", "ownership": "manifest", - "sha256": "5c62e45cc4d12a25e9a8d1a63dc274cef0fa811c3c0901a976a5e6d441c2c321" + "sha256": "03d31ed40a09ef2da5a90a1b63d62face40ffa5a9a2ad7ee86fd77388a10c13e" }, { "path": "shared/squad-install-verifier.mjs", @@ -81,7 +89,7 @@ "package_destination": ".github/workflows/shared/squad-install-verifier.mjs", "destination": ".github/workflows/shared/squad-install-verifier.mjs", "ownership": "manifest", - "sha256": "a8206bd6f8605915bd284b219a66db623eb2ee09a44a0ac51dd4304aed9d8b57" + "sha256": "693e7f470637d54d9bd5fee1cb066005f71e98804971348a8510bd94a451f176" }, { "path": "shared/squad-command-contract.mjs", From 0f3bad42773d5766863abdafca18d76625343516 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 19:51:15 -0700 Subject: [PATCH 03/14] fix(gh-aw): stabilize local install verification Rebind local-package workflow sources before compilation and normalize only compiler-declared repository-scattered schedules in trusted lock digests. Refs #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/gh-aw-quality.test.ts | 18 ++++++++++++++++++ workflows/package/squad-bootstrap.md | 2 +- workflows/shared/squad-install-verifier.mjs | 18 ++++++++++++++++++ workflows/squad-bootstrap.md | 2 +- workflows/squad-workflows.manifest.json | 8 ++++---- 5 files changed, 42 insertions(+), 6 deletions(-) diff --git a/test/gh-aw-quality.test.ts b/test/gh-aw-quality.test.ts index f05b2e6c1..e9eab11f1 100644 --- a/test/gh-aw-quality.test.ts +++ b/test/gh-aw-quality.test.ts @@ -36,6 +36,7 @@ import { WORKFLOW_NAMES, checkSource, materializeRuntime, + normalizeCompiledLock, validateContract, verifyInstall, } from '../workflows/shared/squad-install-verifier.mjs'; @@ -3616,6 +3617,23 @@ describe('gh-aw: canonical package integrity contract', () => { expect(record.files).toHaveLength(OWNERSHIP_ENTRY_COUNT); }); + it('normalizes only compiler-declared repository-scattered schedules', () => { + const metadata = `# gh-aw-metadata: {"frontmatter_hash":"${'a'.repeat(64)}"}`; + const lock = [ + metadata, + `source_revision: ${revisionA}`, + ' - cron: "17 4 * * 2" # Friendly format: weekly on Tuesday at 04:00 (scattered)', + ' - cron: "0 4 * * 2" # Fixed schedule', + ].join('\n'); + const normalized = normalizeCompiledLock(lock, revisionA); + + expect(normalized).toContain( + ' - cron: "" # Friendly format: weekly on Tuesday at 04:00 (scattered)', + ); + expect(normalized).toContain(' - cron: "0 4 * * 2" # Fixed schedule'); + expect(normalized).not.toContain(revisionA); + }); + it('accepts only the deterministic retained bootstrap trigger sentinel', () => { const root = makeConsumer(); const probePath = join(root, TRIGGER_PROBE_DESTINATION); diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index 303d23b10..1b4b69c5e 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -151,7 +151,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "693e7f470637d54d9bd5fee1cb066005f71e98804971348a8510bd94a451f176" + check_hash "$install_verifier" "f30d7f84f0dae50ae1beafccf9566df3457ab400c75f639ac029cdb637e6c1cb" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/shared/squad-install-verifier.mjs b/workflows/shared/squad-install-verifier.mjs index ea985fab0..19b485bd6 100644 --- a/workflows/shared/squad-install-verifier.mjs +++ b/workflows/shared/squad-install-verifier.mjs @@ -350,6 +350,10 @@ export function normalizeCompiledLock(content, revision) { if (!metadata) throw new Error('Compiled lock has missing or malformed gh-aw metadata.'); return text .replace(metadata[0], `${metadata[1]}${'0'.repeat(64)}${metadata[3]}`) + .replace( + /^(\s*-\s+cron:\s+)"[^"]+"(\s+# Friendly format: .+ \(scattered\))$/gm, + '$1""$2', + ) .replaceAll(revision, LOCK_REVISION_PLACEHOLDER); } @@ -811,6 +815,20 @@ export function materializeRuntime(root) { export function writeLocalTestOwnership(root, revision) { if (!REVISION_PATTERN.test(revision)) throw new Error('Local test revision must be a lowercase 40-character SHA.'); const { contract } = parseInstalledContract(root); + for (const entry of contract.workflows) { + const path = safePath(root, entry.destination); + const content = readRequired(root, entry.destination).toString('utf8'); + const end = content.indexOf('\n---\n', 4); + if (!content.startsWith('---\n') || end < 0) { + throw new Error(`Installed workflow has invalid frontmatter: ${entry.destination}`); + } + const frontmatter = content.slice(0, end); + const source = `source: bradygaster/squad/${entry.source}@${revision}`; + const rebound = /^source:\s*.+$/m.test(frontmatter) + ? `${frontmatter.replace(/^source:\s*.+$/m, source)}${content.slice(end)}` + : `${frontmatter}\n${source}${content.slice(end)}`; + writeFileSync(path, rebound); + } const files = expectedOwnership(contract).map((entry) => ({ ...entry, sha256: fileDigest(root, entry.destination), diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index b1c8fddf7..299c60ccb 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -158,7 +158,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "693e7f470637d54d9bd5fee1cb066005f71e98804971348a8510bd94a451f176" + check_hash "$install_verifier" "f30d7f84f0dae50ae1beafccf9566df3457ab400c75f639ac029cdb637e6c1cb" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 06183ee89..6015d32d4 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -47,7 +47,7 @@ "destination": ".github/workflows/squad-retro.md", "lock": ".github/workflows/squad-retro.lock.yml", "source_sha256": "92bcfa39cc5fd3087b11612125e314959237c5b79460825453d1e493727a2562", - "lock_sha256": "067e0a2d87a1ef6f8e183c5167d0ccdbd993afe01dbd2259622317e18e981d67" + "lock_sha256": "00771decb93b93d04ea9c9e6173c2338eef615e49df0a8ca12729680fa15fc52" }, { "name": "squad-improvement-worker", @@ -62,8 +62,8 @@ "source": "workflows/package/squad-bootstrap.md", "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", - "source_sha256": "62ae7212d23e893c2f45adf7ad7a26b995f90e0e3cdc7b5e129dbec2f2445c82", - "lock_sha256": "32d9b9f7522a9eecae9912e206b08d7603f104a378bd3ee272f442ef87987c9c" + "source_sha256": "f7e4b550ce6b0c2e5f8bd2ab6fec3abc1f533e0058062cc82bea66b55b334600", + "lock_sha256": "db0efc319e122dcd6cd0cdab97135fc26420d3db3bb6e5e139d21c79c821e5eb" }, { "name": "squad-command-router", @@ -89,7 +89,7 @@ "package_destination": ".github/workflows/shared/squad-install-verifier.mjs", "destination": ".github/workflows/shared/squad-install-verifier.mjs", "ownership": "manifest", - "sha256": "693e7f470637d54d9bd5fee1cb066005f71e98804971348a8510bd94a451f176" + "sha256": "f30d7f84f0dae50ae1beafccf9566df3457ab400c75f639ac029cdb637e6c1cb" }, { "path": "shared/squad-command-contract.mjs", From a5855f676f6457851c238b12ee4d6a40852a333b Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 20:16:18 -0700 Subject: [PATCH 04/14] fix(gh-aw): make first install a human trust boundary Part of #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/agents.md | 4 + docs/src/content/docs/guide/gh-aw.md | 40 ++- scripts/gh-aw-hosted-e2e.mjs | 65 +++++ test/gh-aw-bootstrap-workflow.test.ts | 3 + test/gh-aw-hosted-e2e.test.ts | 15 ++ test/gh-aw-review-guard.test.ts | 251 ++++++----------- test/gh-aw-review-workflow.test.ts | 345 +++--------------------- workflows/package/squad-bootstrap.md | 31 +++ workflows/package/squad-review.md | 120 ++------- workflows/shared/squad-review-guard.mjs | 279 +++++-------------- workflows/squad-bootstrap.md | 31 +++ workflows/squad-review.md | 120 ++------- workflows/squad-workflows.manifest.json | 10 +- 13 files changed, 433 insertions(+), 881 deletions(-) diff --git a/.github/agents.md b/.github/agents.md index e08e50acf..a167c8efa 100644 --- a/.github/agents.md +++ b/.github/agents.md @@ -33,6 +33,10 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas > Stop at the bootstrap PR; the human merges it. > `/squad` slash commands become active only after that merge reaches > the repository's default branch. +> The installation PR is a manual trust boundary: its PR-controlled workflow +> cannot mint a trusted Squad verdict. After merge, require the automatically +> opened Cast PR to pass `Squad Review / review` using the base-controlled guard +> before treating bootstrap or lifecycle automation as trusted. The quick start installs this workflow set: diff --git a/docs/src/content/docs/guide/gh-aw.md b/docs/src/content/docs/guide/gh-aw.md index 56d5bbf60..afb79ee1f 100644 --- a/docs/src/content/docs/guide/gh-aw.md +++ b/docs/src/content/docs/guide/gh-aw.md @@ -103,6 +103,22 @@ skill as one update unit. For an upgrade, resolve or select one reviewed commit and reinstall that same package as described in [Upgrading the workflows](#upgrading-the-workflows). +The bootstrap installation PR is an explicit human trust boundary. Because its +base branch does not yet contain the Squad review guard and manifest, no job, +check name, review comment, or workflow code introduced by that PR is accepted +as a trusted Squad verdict. The canonical workflow reports +`First-install manual boundary`, emits no `Squad-Review-Verdict:` record, and +requires a human to review the verifier/compile evidence before merging. + +After merge, the default-branch bootstrap workflow opens the draft Cast PR. +That PR is the activation canary: `Squad Review / review` must succeed using the +guard and manifest checked out from the Cast PR's exact base commit. The guard +also requires matching exact-head provenance in the PR body and a durable +GitHub Actions bot comment, so editable PR prose cannot rebind an old bootstrap +run to a changed branch head. Only after that base-controlled canary succeeds +should the Cast/bootstrap lifecycle be treated as trusted. Do not enable the +required check in a ruleset before this post-install canary has been observed. + Step 2 deliberately checks Issues before creating the bootstrap branch or installing any workflow. Squad commands are issue comments, and the merged bootstrap creates a research/proposals issue; without Issues, the installation @@ -426,8 +442,9 @@ Use this checklist for the initial bootstrap and after any workflow update: | Repository readiness | Confirm `.has_issues` is `true`; if it is `false`, enable it before installing workflows | GitHub Issues are available for `/squad` comments and the bootstrap research/proposals issue; insufficient administration permission stops the install before a bootstrap PR is created | | Install | Run the eight-workflow `gh aw add` command on a bootstrap branch | All eight `.md`/`.lock.yml` pairs exist, with shared imports, `.github/aw/`, installed skills, and `.gitattributes` included in the diff | | Compile | Review any first-install safe-update report, approve only the documented entries, then run `gh aw compile --strict` without approval | All eight workflows succeed, only documented warnings remain, and all sixteen source/lock files exist | -| Bootstrap review | Open the PR, request `@copilot`, wait for checks, and merge only after human approval | The default branch receives the complete generated install as one human-reviewable change | -| Automatic bootstrap | Merge the workflow-installation PR | The dedicated workflow creates one draft Cast PR and one linked research-proposals issue from the same validated payload | +| Bootstrap review | Open the installation PR, request `@copilot`, inspect verifier/compile evidence, and merge only after human approval | The run reports the explicit first-install manual boundary; no `Squad-Review-Verdict:` record or PR-controlled check is treated as trusted | +| Activation canary | Merge the workflow-installation PR and inspect the automatically opened draft Cast PR | `Squad Review / review` succeeds with reserved bootstrap roles only after loading the guard and manifest from the exact base commit and validating the default-branch bootstrap run | +| Automatic bootstrap | Continue only after the Cast PR activation canary succeeds | The dedicated workflow's draft Cast PR and linked research-proposals issue share the same validated base-controlled provenance | | Cast persistence | Review the Cast PR before merging | The PR contains `.squad/casting/policy.json`, `registry.json`, and `history.json`, plus the team, routing, charters, Copilot agent, and `meet-the-squad.md` | | Research backlog | Follow the proposal issue through research, triage, plan, and activate | The journey ends with assignable implementation issues; `/squad implement` is used only on those generated tasks | | Cast checks | Open the linked Cast PR and inspect its checks; if application CI is `action_required`, approve that workflow run and wait for it to finish | Copilot review and the repository's normal build, test, lint, and security checks complete before merge | @@ -1520,14 +1537,17 @@ Manual `/squad review` runs use `Squad Review / manual`; they cannot satisfy the PR check or clear relay evidence. Brady (or the consumer repository administrator) must install/merge the complete -generated bundle and observe a successful PR-triggered check before changing -rulesets. Record its actual check name and GitHub App ID from the check-runs -API. Enable the required context with that observed App ID on `dev` **only after -advisory soak** has met the evidence gate in #1734; promote to `main` after the -agreed soak. This change does not modify repository rulesets and does not claim -live soak evidence. Keep native human approving-review requirements enabled -independently, with stale approvals dismissed. The bot's `COMMENT` is not a -human approval. Do not use an unobserved guessed App ID or require the manual job. +generated bundle through the explicit human installation boundary, then observe +a successful PR-triggered check on the post-install draft Cast PR before +changing rulesets. The installation PR itself is not evidence: its workflow and +check name are controlled by that PR. Record the activation canary's actual +check name and GitHub App ID from the check-runs API. Enable the required context +with that observed App ID on `dev` **only after advisory soak** has met the +evidence gate in #1734; promote to `main` after the agreed soak. This change +does not modify repository rulesets and does not claim live soak evidence. Keep +native human approving-review requirements enabled independently, with stale +approvals dismissed. The bot's `COMMENT` is not a human approval. Do not use an +unobserved guessed App ID or require the manual job. Because rulesets apply to all PRs, existing human/Copilot PRs must add committed attribution before enabling the requirement. Fork review is not supported by this workflow; do not relax it with `pull_request_target`. diff --git a/scripts/gh-aw-hosted-e2e.mjs b/scripts/gh-aw-hosted-e2e.mjs index ecc3e24d7..33310fc29 100644 --- a/scripts/gh-aw-hosted-e2e.mjs +++ b/scripts/gh-aw-hosted-e2e.mjs @@ -564,6 +564,64 @@ export function waitForBootstrapOutputs( throw new Error('Timed out waiting for the draft Cast PR and bootstrap research issue.'); } +function waitForBaseControlledReviewCanary(target, castPr, evidence) { + const deadline = Date.now() + 20 * 60 * 1000; + while (Date.now() < deadline) { + const checks = ghJson([ + 'api', + '-H', 'Accept: application/vnd.github+json', + `repos/${target}/commits/${castPr.headSha}/check-runs`, + '--jq', '{check_runs:[.check_runs[] | {id,name,status,conclusion,app:{slug:.app.slug}}]}', + ]).check_runs; + const trustedChecks = checks.filter((check) => + check.name === 'Squad Review / review' && check.app?.slug === 'github-actions'); + if (trustedChecks.length > 1) { + throw new Error(`Expected one base-controlled Squad Review canary check; found ${trustedChecks.length}.`); + } + const reviews = ghJson([ + 'api', + `repos/${target}/pulls/${castPr.number}/reviews?per_page=100`, + ]); + const verdicts = reviews.filter((review) => + review.user?.login === ACTIONS_BOT_LOGIN && + review.commit_id === castPr.headSha && + String(review.body ?? '').includes('Squad-Review-Verdict:')); + if (verdicts.length > 1) { + throw new Error(`Expected one base-controlled Squad Review canary verdict; found ${verdicts.length}.`); + } + if (trustedChecks.length === 1 && trustedChecks[0].status === 'completed') { + const check = trustedChecks[0]; + if (check.conclusion !== 'success') { + throw new Error(`Base-controlled Squad Review canary failed for ${castPr.url}.`); + } + if (verdicts.length !== 1) { + throw new Error('Successful Squad Review canary check is missing its exact-head verdict.'); + } + const marker = String(verdicts[0].body).match(/^Squad-Review-Verdict: (\{[^\r\n]+\})$/m); + if (!marker) throw new Error('Squad Review canary verdict marker is malformed.'); + const verdict = JSON.parse(marker[1]); + if (verdict.schema !== 'squad-review-verdict/v1' + || verdict.repository !== target + || verdict.pull_request !== castPr.number + || verdict.head_sha !== castPr.headSha + || verdict.author_agent !== '@squad/base-controlled-bootstrap' + || verdict.reviewer_agent !== '@squad/base-controlled-review' + || verdict.result !== 'COMMENT') { + throw new Error('Squad Review canary verdict is not bound to the base-controlled bootstrap activation.'); + } + writeJson(resolve(evidence, 'base-controlled-review-canary.json'), { + pull_request: castPr, + check, + review: verdicts[0], + verdict, + }); + return { check, verdict }; + } + sleep(10_000); + } + throw new Error('Timed out waiting for the base-controlled Squad Review activation canary.'); +} + function createAndMergePr({ cwd, target, @@ -732,6 +790,11 @@ function hosted(args, repositoryRoot) { installation, installRun, ); + const reviewCanary = waitForBaseControlledReviewCanary( + targetState.target, + outputs.castPr, + evidence, + ); runChild('git', ['fetch', 'origin', targetState.info.default_branch], { cwd: checkout }); const probeBranch = `squad-e2e/probe-${process.env.GITHUB_RUN_ID ?? sourceSha.slice(0, 12)}`; @@ -785,6 +848,8 @@ function hosted(args, repositoryRoot) { source_sha: sourceSha, installation_pr: installation.number, installation_run: installRun.url, + review_canary_pr: outputs.castPr.number, + review_canary_check: reviewCanary.check.id, probe_pr: probeMerge.number, probe_run: probeRun.url, generated_cast_pr: outputs.castPr.url, diff --git a/test/gh-aw-bootstrap-workflow.test.ts b/test/gh-aw-bootstrap-workflow.test.ts index 73781f0d6..4ef39ee80 100644 --- a/test/gh-aw-bootstrap-workflow.test.ts +++ b/test/gh-aw-bootstrap-workflow.test.ts @@ -742,6 +742,9 @@ describe('automatic Squad bootstrap workflow', () => { expect(lock).toContain('SQUAD_BOOTSTRAP_REPOSITORY: ${{ github.repository }}'); expect(lock).toContain('SQUAD_BOOTSTRAP_RUN_ID: ${{ github.run_id }}'); expect(lock).toContain('squad:bootstrap-provenance'); + expect(lock).toContain('Base-controlled bootstrap provenance. Do not edit this comment.'); + expect(lock).toContain('github.rest.issues.createComment'); + expect(lock).toContain('github.rest.issues.updateComment'); expect(lock).toContain('pullRequestDetails.head.repo?.full_name !== provenance.repository'); expect(lock).toContain('body: `${provenanceMarker}\\n${prBodyWithoutProvenance}`'); expect(lock).toContain('body: markedIssueBody'); diff --git a/test/gh-aw-hosted-e2e.test.ts b/test/gh-aw-hosted-e2e.test.ts index 387e583c4..3f269dcfe 100644 --- a/test/gh-aw-hosted-e2e.test.ts +++ b/test/gh-aw-hosted-e2e.test.ts @@ -192,6 +192,9 @@ describe('Squad gh-aw hosted E2E controller', () => { expect(BOOTSTRAP_WORKFLOW).toContain(''); expect(BOOTSTRAP_WORKFLOW).toContain('pullRequestDetails.head.repo?.full_name !== provenance.repository'); expect(BOOTSTRAP_WORKFLOW).toContain('body: `${provenanceMarker}\\n${prBodyWithoutProvenance}`'); + expect(BOOTSTRAP_WORKFLOW).toContain( + 'Base-controlled bootstrap provenance. Do not edit this comment.', + ); expect(BOOTSTRAP_WORKFLOW).toContain('body: markedIssueBody'); }); @@ -204,6 +207,18 @@ describe('Squad gh-aw hosted E2E controller', () => { expect(SCRIPT).toContain('rmSync(checkout, { recursive: true, force: true })'); }); + it('requires a base-controlled review canary after the manual installation boundary', () => { + expect(SCRIPT).toContain('waitForBaseControlledReviewCanary'); + expect(SCRIPT).toContain("check.name === 'Squad Review / review'"); + expect(SCRIPT).toContain("check.app?.slug === 'github-actions'"); + expect(SCRIPT).toContain("'@squad/base-controlled-bootstrap'"); + expect(SCRIPT).toContain("'@squad/base-controlled-review'"); + expect(SCRIPT).toContain("verdict.result !== 'COMMENT'"); + expect(SCRIPT.indexOf('waitForBaseControlledReviewCanary')).toBeLessThan( + SCRIPT.indexOf("kind: 'squad-bootstrap-trigger-probe'"), + ); + }); + it('never executes candidate package or installed verifier with inherited credentials', () => { expect(SCRIPT).toContain( 'env: sanitizedEnvironment(options.env, { allowGitHubToken: options.allowGitHubToken === true })', diff --git a/test/gh-aw-review-guard.test.ts b/test/gh-aw-review-guard.test.ts index 2a79bbf8e..ae0ee1a73 100644 --- a/test/gh-aw-review-guard.test.ts +++ b/test/gh-aw-review-guard.test.ts @@ -6,11 +6,6 @@ import { assertClearingReview, CHECK_NAME, enforceReviewOutputs, OVERRIDE_PREFIX, reviewTarget, validateAttribution, validateVerdict, VERDICT_PREFIX, } from '../workflows/shared/squad-review-guard.mjs'; -import { - createFirstInstallFixture, - githubFile, - type InstallFixture, -} from './helpers/gh-aw-install-fixture.js'; const REPOSITORY = 'squad/example'; const HEAD = 'a'.repeat(40); @@ -21,11 +16,6 @@ const SUBMITTED = '2026-09-28T12:01:01Z'; const FINISHED = '2026-09-28T12:02:00Z'; const MERGED = '2026-09-28T12:03:00Z'; const NOW = Date.parse('2026-09-28T12:04:00Z'); -const FIRST_INSTALL = createFirstInstallFixture(HEAD); -const GUARD_PATH = '.github/workflows/shared/squad-review-guard.mjs'; -const GUARD_SHA256 = FIRST_INSTALL.provenance.files.find( - entry => entry.destination === GUARD_PATH, -)!.sha256; const workspaces: string[] = []; afterEach(() => { @@ -54,7 +44,9 @@ function fixture(relay = false) { }; const pr = { number: 42, state: relay ? 'closed' : 'open', merged: relay, merged_at: MERGED, + title: 'Implementation', body: '', + user: { login: 'human', type: 'User' }, head: { sha: HEAD, ref: 'squad/implement-9-fix', repo: { full_name: REPOSITORY, name: 'example' } }, base: { sha: BASE, ref: 'dev', repo: { full_name: REPOSITORY, name: 'example' } }, }; @@ -76,6 +68,11 @@ function fixture(relay = false) { run_started_at: START, updated_at: FINISHED, status: 'completed', conclusion: 'success', }; const jobs = [{ name: CHECK_NAME, conclusion: 'success', completed_at: FINISHED }]; + const bootstrapRun = { + event: 'push', path: '.github/workflows/squad-bootstrap.lock.yml', + repository: { full_name: REPOSITORY }, head_sha: BASE, head_branch: 'dev', + status: 'completed', conclusion: 'success', + }; const override = { schema: 'squad-review-override/v1', repository: REPOSITORY, pull_request: 42, head_sha: HEAD, review_id: 123, reason: 'Accepted false positive; linked human decision.', @@ -104,7 +101,9 @@ function fixture(relay = false) { } if (route.endsWith('/contents/.squad-review.json')) { expect(fields?.ref).toBe(HEAD); - if (state.missingManifest) throw new Error('404 missing committed attribution'); + if (state.missingManifest) { + throw Object.assign(new Error('Not Found'), { status: 404 }); + } return encode(attribution); } if (route.endsWith('/contents/.squad/casting/registry.json')) { @@ -113,6 +112,7 @@ function fixture(relay = false) { } if (route.endsWith('/reviews')) return state.reviews; if (route.endsWith('/actions/runs/17')) return run; + if (route.endsWith('/actions/runs/29')) return bootstrapRun; if (route.endsWith('/attempts/1')) return { ...run, run_attempt: 1, run_started_at: START }; if (/\/attempts\/[12]\/jobs$/.test(route)) return { jobs }; if (route.endsWith('/comments')) return state.comments; @@ -125,190 +125,113 @@ function fixture(relay = false) { }; sync(); return { - env, attribution, registry, pr, verdict, review, run, jobs, override, comment, + env, attribution, registry, pr, verdict, review, run, bootstrapRun, jobs, override, comment, state, encode, get, sync, }; } -function firstInstallProof(): InstallFixture { - return { - manifest: structuredClone(FIRST_INSTALL.manifest), - provenance: structuredClone(FIRST_INSTALL.provenance), - consumerFiles: new Map([...FIRST_INSTALL.consumerFiles].map( - ([path, content]) => [path, Buffer.from(content)], - )), - canonicalFiles: new Map([...FIRST_INSTALL.canonicalFiles].map( - ([path, content]) => [path, Buffer.from(content)], - )), - }; -} - -async function firstInstallGet( - fixture: ReturnType, - proof: InstallFixture, - route: string, - fields?: Record, -) { - if (route.endsWith('/contents/.squad-review.json')) { - throw Object.assign(new Error('Not Found'), { status: 404 }); - } - if (route.endsWith('/contents/.github/aw/packages')) { - expect(fields?.ref).toBe(HEAD); - return [{ - type: 'file', - name: 'bradygaster-squad-workflows-3632054824e8.json', - }]; - } - if (route.endsWith( - '/contents/.github/aw/packages/bradygaster-squad-workflows-3632054824e8.json', - )) return fixture.encode(proof.provenance); - const marker = '/contents/'; - const path = route.slice(route.indexOf(marker) + marker.length); - const files = route.startsWith('repos/bradygaster/squad/') - ? proof.canonicalFiles - : proof.consumerFiles; - const content = files.get(path); - if (content) return githubFile(content); - return fixture.get(route, fields); +function makeBootstrap(f: ReturnType) { + f.state.missingManifest = true; + f.pr.title = '[squad] Cast your Squad'; + f.pr.user = { login: 'github-actions[bot]', type: 'Bot' }; + f.pr.head.ref = 'squad/bootstrap-cast'; + f.pr.body = ``; + f.state.comments.push({ + user: { login: 'github-actions[bot]', type: 'Bot' }, + created_at: START, + updated_at: START, + body: `${f.pr.body}\nBase-controlled bootstrap provenance. Do not edit this comment.`, + }); + f.verdict.author_agent = '@squad/base-controlled-bootstrap'; + f.verdict.reviewer_agent = '@squad/base-controlled-review'; + f.sync(); } describe('independent Squad review guard', () => { - it('uses reserved workflow-role attribution only for a proven clean package install', async () => { + it('uses reserved workflow roles only for the base-controlled post-install bootstrap PR', async () => { const f = fixture(); + makeBootstrap(f); f.state.reviews = []; - const proof = firstInstallProof(); - const get = (route: string, fields?: Record) => - firstInstallGet(f, proof, route, fields); - const options = { - firstInstall: true, - workflowSha: HEAD, - workflowGuardSha256: GUARD_SHA256, - workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${HEAD}`, - }; - await expect(reviewTarget(f.env, get, options)).resolves.toMatchObject({ - author_agent: '@squad/bootstrap-installation', - reviewer_agent: '@squad/bootstrap-review-workflow', + await expect(reviewTarget(f.env, f.get)).resolves.toMatchObject({ + author_agent: '@squad/base-controlled-bootstrap', + reviewer_agent: '@squad/base-controlled-review', }); - const workspace = mkdtempSync(join(tmpdir(), 'squad-review-install-')); + const workspace = mkdtempSync(join(tmpdir(), 'squad-review-bootstrap-')); workspaces.push(workspace); const path = join(workspace, 'output.json'); writeFileSync(path, JSON.stringify({ items: [{ - type: 'submit_pull_request_review', event: 'COMMENT', body: 'Install topology reviewed.', + type: 'submit_pull_request_review', event: 'COMMENT', body: 'Bootstrap Cast reviewed.', }] })); - await enforceReviewOutputs({ ...f.env, GH_AW_AGENT_OUTPUT: path }, get, options); + await enforceReviewOutputs({ ...f.env, GH_AW_AGENT_OUTPUT: path }, f.get); const output = JSON.parse(readFileSync(path, 'utf8')); - expect(output.items[0].body).toContain('"author_agent":"@squad/bootstrap-installation"'); + expect(output.items[0].body).toContain('"author_agent":"@squad/base-controlled-bootstrap"'); expect(output.items[0].body).toContain( - '"reviewer_agent":"@squad/bootstrap-review-workflow"', + '"reviewer_agent":"@squad/base-controlled-review"', ); }); - it('refuses arbitrary clean-base PRs and malformed first-install proof', async () => { + it('refuses arbitrary first-install PRs even when they contain package-shaped claims', async () => { const f = fixture(); - const proof = firstInstallProof(); - const missingAttribution = (route: string, fields?: Record) => - firstInstallGet(f, proof, route, fields); - const options = { - firstInstall: true, - workflowSha: HEAD, - workflowGuardSha256: GUARD_SHA256, - workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${HEAD}`, - }; - await expect(reviewTarget(f.env, missingAttribution)).rejects.toThrow('Not Found'); - await expect(reviewTarget(f.env, missingAttribution, { - ...options, workflowSha: BASE, - })).rejects.toThrow('outside an immutable clean first install'); + f.state.missingManifest = true; + f.pr.title = 'ci: add Squad agentic workflow'; + f.pr.body = `Package: bradygaster/squad/workflows@${HEAD}`; + await expect(reviewTarget(f.env, f.get)) + .rejects.toThrow('missing or duplicate base-controlled bootstrap PR provenance'); + }); - proof.manifest.workflows.pop(); - proof.canonicalFiles.set( - 'workflows/squad-workflows.manifest.json', - Buffer.from(`${JSON.stringify(proof.manifest, null, 2)}\n`), - ); - await expect(reviewTarget(f.env, missingAttribution, options)) - .rejects.toThrow('invalid immutable package manifest'); - const reset = firstInstallProof(); - proof.manifest = reset.manifest; - proof.canonicalFiles = reset.canonicalFiles; - proof.provenance.source = `bradygaster/squad/workflows@${BASE}`; - await expect(reviewTarget(f.env, missingAttribution, options)) - .rejects.toThrow('invalid committed first-install package provenance'); - proof.provenance.source = `bradygaster/squad/workflows@${HEAD}`; - proof.provenance.files.pop(); - await expect(reviewTarget(f.env, missingAttribution, options)) - .rejects.toThrow('invalid committed first-install package provenance'); + it.each([ + ['branch', (f: ReturnType) => { f.pr.head.ref = 'attacker/bootstrap'; }], + ['title', (f: ReturnType) => { f.pr.title = 'Trusted bootstrap'; }], + ['author', (f: ReturnType) => { f.pr.user.login = 'attacker'; }], + ['head', (f: ReturnType) => { + f.pr.body = f.pr.body.replace(HEAD, BASE); + }], + ['base run', (f: ReturnType) => { f.bootstrapRun.head_sha = HEAD; }], + ['workflow', (f: ReturnType) => { + f.bootstrapRun.path = '.github/workflows/attacker.yml'; + }], + ['comment', (f: ReturnType) => { + f.state.comments[0].body = f.state.comments[0].body.replace(HEAD, BASE); + }], + ['comment author', (f: ReturnType) => { + f.state.comments[0].user.login = 'attacker'; + }], + ])('refuses a bootstrap activation with mutated %s provenance', async (_label, mutate) => { + const f = fixture(); + makeBootstrap(f); + mutate(f); + await expect(reviewTarget(f.env, f.get)).rejects.toThrow(); }); - it('does not rescue malformed attribution or non-404 reads during first install', async () => { + it('requires successful base-controlled bootstrap completion at the clearing gate', async () => { + const f = fixture(); + makeBootstrap(f); + f.bootstrapRun.status = 'in_progress'; + f.bootstrapRun.conclusion = null; + await expect(reviewTarget(f.env, f.get)).resolves.toMatchObject({ + author_agent: '@squad/base-controlled-bootstrap', + }); + await expect(assertClearingReview(f.env, f.get)) + .rejects.toThrow('base-controlled bootstrap run did not complete successfully'); + }); + + it('does not rescue malformed attribution or non-404 reads', async () => { const f = fixture(); - const options = { - firstInstall: true, - workflowSha: HEAD, - workflowGuardSha256: GUARD_SHA256, - workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${HEAD}`, - }; f.attribution.schema = 'wrong'; - await expect(reviewTarget(f.env, f.get, options)).rejects.toThrow('malformed committed'); + await expect(reviewTarget(f.env, f.get)).rejects.toThrow('malformed committed'); await expect(reviewTarget(f.env, async (route, fields) => { if (route.endsWith('/contents/.squad-review.json')) { throw Object.assign(new Error('Forbidden'), { status: 403 }); } return f.get(route, fields); - }, options)).rejects.toThrow('Forbidden'); - }); - - it('hashes installed and immutable package bytes instead of trusting provenance claims', async () => { - const f = fixture(); - const options = { - firstInstall: true, - workflowSha: HEAD, - workflowGuardSha256: GUARD_SHA256, - workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${HEAD}`, - }; - const sourcePath = '.github/workflows/squad.md'; - const lockPath = '.github/workflows/squad.lock.yml'; - const canonicalPath = 'workflows/package/squad.md'; - - const changedSource = firstInstallProof(); - changedSource.consumerFiles.set( - sourcePath, - Buffer.concat([changedSource.consumerFiles.get(sourcePath)!, Buffer.from('\nattacker edit\n')]), - ); - await expect(reviewTarget( - f.env, - (route, fields) => firstInstallGet(f, changedSource, route, fields), - options, - )).rejects.toThrow(`installed bytes do not match ownership for ${sourcePath}`); - - const changedLock = firstInstallProof(); - changedLock.consumerFiles.set( - lockPath, - Buffer.concat([changedLock.consumerFiles.get(lockPath)!, Buffer.from('\nattacker edit\n')]), - ); - await expect(reviewTarget( - f.env, - (route, fields) => firstInstallGet(f, changedLock, route, fields), - options, - )).rejects.toThrow(`installed compiled lock mismatch for ${lockPath}`); - - const changedCanonical = firstInstallProof(); - changedCanonical.canonicalFiles.set( - canonicalPath, - Buffer.concat([changedCanonical.canonicalFiles.get(canonicalPath)!, Buffer.from('\nwrong\n')]), - ); - await expect(reviewTarget( - f.env, - (route, fields) => firstInstallGet(f, changedCanonical, route, fields), - options, - )).rejects.toThrow(`immutable package source digest mismatch for ${canonicalPath}`); - - const sourceFailure = firstInstallProof(); - await expect(reviewTarget(f.env, async (route, fields) => { - if (route === `repos/bradygaster/squad/contents/${canonicalPath}`) { - throw Object.assign(new Error('source fetch forbidden'), { status: 403 }); - } - return firstInstallGet(f, sourceFailure, route, fields); - }, options)).rejects.toThrow('source fetch forbidden'); + })).rejects.toThrow('Forbidden'); }); it('accepts a distinct, committed, current-head verdict and merged-head relay', async () => { diff --git a/test/gh-aw-review-workflow.test.ts b/test/gh-aw-review-workflow.test.ts index 0503fa107..6e7334ca5 100644 --- a/test/gh-aw-review-workflow.test.ts +++ b/test/gh-aw-review-workflow.test.ts @@ -1,11 +1,9 @@ import { afterAll, describe, expect, it } from 'vitest'; import { cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'; import { execFileSync, spawnSync } from 'node:child_process'; -import { createHash } from 'node:crypto'; import { dirname, resolve } from 'node:path'; import { fileURLToPath, pathToFileURL } from 'node:url'; import { extractSafeOutputsConfigJson } from './helpers/gh-aw-lock.js'; -import { createFirstInstallFixture } from './helpers/gh-aw-install-fixture.js'; import { parse } from 'yaml'; const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..'); @@ -19,8 +17,6 @@ const SHARED_BOOTSTRAP = read('workflows/shared/squad.md'); const REVIEWER_FRONTMATTER = frontmatter(REVIEWER); const ROUTER_FRONTMATTER = frontmatter(ROUTER); const compileWorkspaces: string[] = []; -const LIVE_INSTALL_REVISION = 'c'.repeat(40); -const LIVE_INSTALL = createFirstInstallFixture(LIVE_INSTALL_REVISION); function read(relativePath: string): string { return readFileSync(resolve(ROOT, relativePath), 'utf8').replace(/\r\n/g, '\n'); @@ -108,6 +104,8 @@ function assertReviewerContract(workflow: string): void { expect(workflow).toContain('inlined-imports: true'); expect(workflow).toContain('await guard.enforceReviewOutputs'); expect(workflow).toContain('await guard.assertClearingReview'); + expect(workflow).toContain('The workflow-installation PR is an explicit human trust boundary.'); + expect(workflow).toContain('Trusted review starts on the automatic post-merge Cast PR.'); expect(workflow).toContain('Human approval remains mandatory.'); } @@ -169,27 +167,23 @@ function assertCompiledGate(lock: string): void { expect(steps[guard]['continue-on-error']).toBeUndefined(); const baseCheckout = steps.find((step: { name: string }) => step.name === 'Checkout base commit for review guard'); - const workflowCheckout = steps.find((step: { name: string }) => - step.name === 'Checkout workflow commit for first-install review guard'); expect(baseCheckout.with.ref).toBe('${{ github.event.pull_request.base.sha || github.workflow_sha }}'); - expect(workflowCheckout.with.ref).toBe('${{ github.workflow_sha }}'); - expect(steps[guard].with.script).toContain('if (existsSync(baseGuard))'); - expect(steps[guard].with.script).toContain('else if (!existsSync(baseManifest))'); - expect(steps[guard].with.script).toContain('firstInstall = true'); - expect(steps[guard].with.script).toContain("createHash('sha256')"); - expect(steps[guard].with.script).toContain('workflowGuardSha256'); - expect(steps[guard].with.script).toContain('workflowSource'); - expect(steps[guard].with.script).toContain('workflowReview'); - expect(steps[guard].with.script).toContain('missing from an established base installation'); + expect(steps.some((step: { name: string }) => + step.name.includes('workflow commit'))).toBe(false); + expect(steps[guard].with.script).toContain('!existsSync(baseGuard) || !existsSync(baseManifest)'); + expect(steps[guard].with.script).toContain('First-install manual boundary'); + expect(steps[guard].with.script).toContain('pathToFileURL(baseGuard)'); + expect(steps[guard].with.script).not.toContain('github.workflow_sha'); + expect(steps[guard].with.script).not.toContain('.squad-review-workflow'); + expect(steps[guard].with.script).not.toContain('Squad-Review-Verdict:'); const finalGate = review.steps.find((step: { name: string }) => step.name === 'Enforce independent current-head verdict'); - expect(finalGate.with.script).toContain('if (existsSync(baseGuard))'); - expect(finalGate.with.script).toContain('else if (!existsSync(baseManifest))'); - expect(finalGate.with.script).toContain('firstInstall = true'); - expect(finalGate.with.script).toContain("createHash('sha256')"); - expect(finalGate.with.script).toContain('workflowGuardSha256'); - expect(finalGate.with.script).toContain('workflowSource'); - expect(finalGate.with.script).toContain('missing from an established base installation'); + expect(finalGate.with.script).toContain('!existsSync(baseGuard) || !existsSync(baseManifest)'); + expect(finalGate.with.script).toContain('First-install manual boundary'); + expect(finalGate.with.script).toContain('pathToFileURL(baseGuard)'); + expect(finalGate.with.script).not.toContain('github.workflow_sha'); + expect(finalGate.with.script).not.toContain('.squad-review-workflow'); + expect(finalGate.with.script).not.toContain('Squad-Review-Verdict:'); for (const step of review.steps) expect(step['continue-on-error']).toBeUndefined(); expect(review['continue-on-error']).toBeUndefined(); } @@ -213,9 +207,8 @@ async function executeCompiledGuardLoader( { baseGuard, baseManifest = false, - workflowGuard, head = 'a'.repeat(40), - }: { baseGuard?: string; baseManifest?: boolean; workflowGuard: string; head?: string }, + }: { baseGuard?: string; baseManifest?: boolean; head?: string }, ): Promise { const workspace = mkdtempSync(resolve(ROOT, '.squad-review-loader-')); compileWorkspaces.push(workspace); @@ -235,14 +228,6 @@ async function executeCompiledGuardLoader( mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, '{}\n'); } - const workflowPath = resolve(workspace, '.squad-review-workflow', guardPath); - mkdirSync(dirname(workflowPath), { recursive: true }); - writeFileSync(workflowPath, workflowGuard); - writeFileSync( - resolve(workspace, '.squad-review-workflow', '.github/workflows/squad-review.md'), - `---\nsource: bradygaster/squad/workflows/package/squad-review.md@${head}\n---\n`, - ); - const previousWorkspace = process.env.GITHUB_WORKSPACE; const previousOutput = process.env.SQUAD_TEST_GUARD_OUTPUT; const previousHead = process.env.SQUAD_REVIEW_HEAD; @@ -255,7 +240,7 @@ async function executeCompiledGuardLoader( import { createRequire } from 'node:module'; const require = createRequire(import.meta.url); const github = { request: async () => ({ data: {} }) }; - ${script.replaceAll('${{ github.workflow_sha }}', head)} + ${script} `); await import(`${pathToFileURL(runner).href}?run=${Date.now()}`); return readFileSync(output, 'utf8'); @@ -269,197 +254,6 @@ async function executeCompiledGuardLoader( } } -function executeCompiledSafeOutputContract( - script: string, - scenario: - | 'clean-install' - | 'clean-arbitrary' - | 'established-missing' - | 'configured' - | 'changed-source' - | 'changed-lock' - | 'canonical-mismatch' - | 'source-fetch-failure', -): { status: number | null; diagnostics: string; output?: string } { - const workspace = mkdtempSync(resolve(ROOT, '.squad-review-live-contract-')); - compileWorkspaces.push(workspace); - const workflowShared = resolve( - workspace, - '.squad-review-workflow', - '.github/workflows/shared', - ); - mkdirSync(dirname(workflowShared), { recursive: true }); - cpSync(resolve(ROOT, 'workflows/shared'), workflowShared, { recursive: true }); - const workflowReview = resolve( - workspace, - '.squad-review-workflow', - '.github/workflows/squad-review.md', - ); - mkdirSync(dirname(workflowReview), { recursive: true }); - writeFileSync( - workflowReview, - LIVE_INSTALL.consumerFiles.get('.github/workflows/squad-review.md')!, - ); - if (scenario === 'established-missing' || scenario === 'configured') { - const baseShared = resolve(workspace, '.squad-review-base', '.github/workflows/shared'); - mkdirSync(dirname(baseShared), { recursive: true }); - cpSync(resolve(ROOT, 'workflows/shared'), baseShared, { recursive: true }); - const manifestPath = resolve( - workspace, - '.squad-review-base', - '.github/aw/squad-workflows.manifest.json', - ); - mkdirSync(dirname(manifestPath), { recursive: true }); - writeFileSync(manifestPath, '{}\n'); - } - - const head = 'a'.repeat(40); - const base = 'b'.repeat(40); - const consumerFiles = new Map([...LIVE_INSTALL.consumerFiles].map( - ([path, content]) => [path, Buffer.from(content)], - )); - const canonicalFiles = new Map([...LIVE_INSTALL.canonicalFiles].map( - ([path, content]) => [path, Buffer.from(content)], - )); - if (scenario === 'changed-source') { - consumerFiles.set( - '.github/workflows/squad.md', - Buffer.concat([consumerFiles.get('.github/workflows/squad.md')!, Buffer.from('\nchanged\n')]), - ); - } - if (scenario === 'changed-lock') { - consumerFiles.set( - '.github/workflows/squad.lock.yml', - Buffer.concat([ - consumerFiles.get('.github/workflows/squad.lock.yml')!, - Buffer.from('\nchanged\n'), - ]), - ); - } - if (scenario === 'canonical-mismatch') { - canonicalFiles.set( - 'workflows/package/squad.md', - Buffer.concat([canonicalFiles.get('workflows/package/squad.md')!, Buffer.from('\nchanged\n')]), - ); - } - const encodedConsumerFiles = Object.fromEntries([...consumerFiles].map( - ([path, content]) => [path, content.toString('base64')], - )); - const encodedCanonicalFiles = Object.fromEntries([...canonicalFiles].map( - ([path, content]) => [path, content.toString('base64')], - )); - const outputPath = resolve(workspace, 'agent-output.json'); - writeFileSync(outputPath, JSON.stringify({ items: [{ - type: 'submit_pull_request_review', - event: 'COMMENT', - body: 'No blocking installation findings.', - }] })); - const runner = resolve(workspace, 'runner.mjs'); - const compiledScript = script.replaceAll('${{ github.workflow_sha }}', head); - writeFileSync(runner, ` - import { createRequire } from 'node:module'; - const require = createRequire(import.meta.url); - const head = ${JSON.stringify(head)}; - const base = ${JSON.stringify(base)}; - const scenario = ${JSON.stringify(scenario)}; - const consumerFiles = ${JSON.stringify(encodedConsumerFiles)}; - const canonicalFiles = ${JSON.stringify(encodedCanonicalFiles)}; - const provenance = ${JSON.stringify(LIVE_INSTALL.provenance)}; - const encode = content => { - if (!Buffer.isBuffer(content)) content = Buffer.from(JSON.stringify(content)); - return { - type: 'file', - encoding: 'base64', - size: content.length, - content: content.toString('base64'), - }; - }; - const attribution = { - schema: 'squad-review-author/v1', - repository: 'squad/example', - issue: 9, - author_agent: 'implementer', - reviewer_agent: 'reviewer', - }; - const registry = { - schema: 'squad-agent-provenance/v1', - schema_version: 1, - agents: { - implementer: { persistent_name: 'implementer', status: 'active' }, - reviewer: { persistent_name: 'reviewer', status: 'active' }, - }, - }; - const github = { - request: async (request, fields) => { - const route = request.replace(/^GET \\//, ''); - if (route.endsWith('/pulls/42')) return { data: { - number: 42, - state: 'open', - merged: false, - body: '', - head: { sha: head, ref: 'install-squad', repo: { full_name: 'squad/example' } }, - base: { sha: base, ref: 'dev', repo: { full_name: 'squad/example' } }, - } }; - if (route.endsWith('/contents/.squad-review.json')) { - if (scenario === 'configured') return { data: encode(attribution) }; - throw Object.assign(new Error('Not Found'), { status: 404 }); - } - if (route.endsWith('/contents/.squad/casting/registry.json')) { - return { data: encode(registry) }; - } - if (route.endsWith('/contents/.github/aw/squad-workflows.manifest.json')) { - return { data: encode(Buffer.from(consumerFiles[ - '.github/aw/squad-workflows.manifest.json' - ], 'base64')) }; - } - if (route.endsWith('/contents/.github/aw/packages')) { - if (scenario === 'clean-arbitrary') return { data: [] }; - return { data: [{ - type: 'file', - name: 'bradygaster-squad-workflows-3632054824e8.json', - }] }; - } - if (route.includes('/contents/.github/aw/packages/')) { - return { data: encode(provenance) }; - } - const marker = '/contents/'; - const path = route.slice(route.indexOf(marker) + marker.length); - const sourceRepository = route.startsWith('repos/bradygaster/squad/'); - if (sourceRepository && scenario === 'source-fetch-failure' && - path === 'workflows/package/squad.md') { - throw Object.assign(new Error('source fetch forbidden'), { status: 403 }); - } - const files = sourceRepository ? canonicalFiles : consumerFiles; - if (files[path]) return { data: encode(Buffer.from(files[path], 'base64')) }; - if (route.endsWith('/reviews')) return { data: [] }; - throw new Error('Unexpected API route: ' + route + ' ' + JSON.stringify(fields)); - }, - }; - ${compiledScript} - `); - const result = spawnSync(process.execPath, [runner], { - cwd: workspace, - encoding: 'utf8', - env: { - ...process.env, - GITHUB_WORKSPACE: workspace, - GITHUB_EVENT_NAME: 'pull_request', - GITHUB_REPOSITORY: 'squad/example', - GITHUB_RUN_ID: '17', - GITHUB_RUN_ATTEMPT: '1', - GH_AW_AGENT_OUTPUT: outputPath, - SQUAD_REVIEW_PR: '42', - SQUAD_REVIEW_HEAD: head, - GH_AW_WORKFLOW_SOURCE: `bradygaster/squad/workflows/package/squad-review.md@${LIVE_INSTALL_REVISION}`, - }, - }); - return { - status: result.status, - diagnostics: `${result.stdout}\n${result.stderr}`, - output: result.status === 0 ? readFileSync(outputPath, 'utf8') : undefined, - }; -} - describe('gh-aw enforcing Squad reviewer', () => { it('routes /squad review to the isolated workflow and supports automatic PR events', () => { const routerDispatch = yamlBlock(ROUTER_FRONTMATTER, 'dispatch-workflow'); @@ -645,19 +439,19 @@ describe('gh-aw enforcing Squad reviewer', () => { expect(lock).toContain('GH_AW_HEAD_SHA: ${{ github.event.pull_request.head.sha }}'); }, 30000); - it('executes the compiled first-install fallback without weakening established base control', async () => { + it('loads review authority only from the base and makes first install a manual boundary', async () => { const { lock } = compileReviewer(); const stub = (source: string) => ` import { writeFileSync } from 'node:fs'; - export async function enforceReviewOutputs(env, get, options) { + export async function enforceReviewOutputs(env) { writeFileSync(process.env.SQUAD_TEST_GUARD_OUTPUT, JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'safe outputs', - head: env.SQUAD_REVIEW_HEAD, options })); + head: env.SQUAD_REVIEW_HEAD })); } - export async function assertClearingReview(env, get, options) { + export async function assertClearingReview(env) { writeFileSync(process.env.SQUAD_TEST_GUARD_OUTPUT, JSON.stringify({ source: ${JSON.stringify(source)}, operation: 'final verdict', - head: env.SQUAD_REVIEW_HEAD, options })); + head: env.SQUAD_REVIEW_HEAD })); } `; @@ -665,113 +459,42 @@ describe('gh-aw enforcing Squad reviewer', () => { const head = name === 'safe outputs' ? 'edd6fbf0f84334ff086ed2bc8bbfed5503fdd56f' : '9a898b5182ca432b62bef26dbf1f9022dd1d256b'; - const workflowGuard = stub('workflow'); - const workflowGuardSha256 = createHash('sha256').update(workflowGuard).digest('hex'); await expect(executeCompiledGuardLoader(script, { - workflowGuard, - head, - })).resolves.toBe(JSON.stringify({ - source: 'workflow', - operation: name, head, - options: { - firstInstall: true, - workflowSha: head, - workflowGuardSha256, - workflowSource: `bradygaster/squad/workflows/package/squad-review.md@${head}`, - }, - })); + })).rejects.toThrow('First-install manual boundary'); await expect(executeCompiledGuardLoader(script, { baseGuard: stub('base'), baseManifest: true, - workflowGuard, head, })).resolves.toBe(JSON.stringify({ source: 'base', operation: name, head, - options: { firstInstall: false, workflowSha: head }, })); await expect(executeCompiledGuardLoader(script, { baseManifest: true, - workflowGuard, head, - })).rejects.toThrow( - 'Squad Review guard is missing from an established base installation. Refusing workflow-source fallback.', - ); + })).rejects.toThrow('First-install manual boundary'); await expect(executeCompiledGuardLoader(script, { baseGuard: 'this is not valid JavaScript', baseManifest: true, - workflowGuard, head, })).rejects.toThrow(); } }, 30000); - it('executes the live compiled identity contract for install and established reviews', () => { + it('does not embed a PR-controlled guard, verdict, or trusted fallback in emitted loaders', () => { const { lock } = compileReviewer(); - const safeOutputScript = compiledGuardScripts(lock) - .find(candidate => candidate.name === 'safe outputs')!.script; - - const cleanInstall = executeCompiledSafeOutputContract(safeOutputScript, 'clean-install'); - expect(cleanInstall.status, cleanInstall.diagnostics).toBe(0); - const cleanOutput = JSON.parse(cleanInstall.output!); - expect(cleanOutput.items[0].body).toContain( - '"author_agent":"@squad/bootstrap-installation"', - ); - expect(cleanOutput.items[0].body).toContain( - '"reviewer_agent":"@squad/bootstrap-review-workflow"', - ); - - const configured = executeCompiledSafeOutputContract(safeOutputScript, 'configured'); - expect(configured.status, configured.diagnostics).toBe(0); - const configuredOutput = JSON.parse(configured.output!); - expect(configuredOutput.items[0].body).toContain('"author_agent":"implementer"'); - expect(configuredOutput.items[0].body).toContain('"reviewer_agent":"reviewer"'); - - const establishedMissing = executeCompiledSafeOutputContract( - safeOutputScript, - 'established-missing', - ); - expect(establishedMissing.status).not.toBe(0); - expect(establishedMissing.diagnostics).toContain('Not Found'); - - const arbitraryClean = executeCompiledSafeOutputContract(safeOutputScript, 'clean-arbitrary'); - expect(arbitraryClean.status).not.toBe(0); - expect(arbitraryClean.diagnostics).toContain( - 'missing or duplicate first-install package provenance', - ); - - const changedSource = executeCompiledSafeOutputContract(safeOutputScript, 'changed-source'); - expect(changedSource.status).not.toBe(0); - expect(changedSource.diagnostics).toContain( - 'installed bytes do not match ownership for .github/workflows/squad.md', - ); - - const changedLock = executeCompiledSafeOutputContract(safeOutputScript, 'changed-lock'); - expect(changedLock.status).not.toBe(0); - expect(changedLock.diagnostics).toContain( - 'installed compiled lock mismatch for .github/workflows/squad.lock.yml', - ); - - const canonicalMismatch = executeCompiledSafeOutputContract( - safeOutputScript, - 'canonical-mismatch', - ); - expect(canonicalMismatch.status).not.toBe(0); - expect(canonicalMismatch.diagnostics).toContain( - 'immutable package source digest mismatch for workflows/package/squad.md', - ); - - const sourceFetchFailure = executeCompiledSafeOutputContract( - safeOutputScript, - 'source-fetch-failure', - ); - expect(sourceFetchFailure.status).not.toBe(0); - expect(sourceFetchFailure.diagnostics).toContain('source fetch forbidden'); + for (const { script } of compiledGuardScripts(lock)) { + expect(script).toContain('pathToFileURL(baseGuard)'); + expect(script).not.toContain('.squad-review-workflow'); + expect(script).not.toContain('workflowGuard'); + expect(script).not.toContain('Squad-Review-Verdict:'); + expect(script).not.toContain('@squad/bootstrap-installation'); + } }, 30000); it('kills mutations of every important authority and provenance gate', () => { @@ -808,6 +531,8 @@ describe('gh-aw enforcing Squad reviewer', () => { REVIEWER.replace('await guard.enforceReviewOutputs', 'void guard.enforceReviewOutputs'), REVIEWER.replace('await guard.assertClearingReview', 'void guard.assertClearingReview'), REVIEWER.replace("&& 'Squad Review / review'", "&& 'Other check'"), + REVIEWER.replace('pathToFileURL(baseGuard)', "pathToFileURL('.squad-review-workflow/guard.mjs')"), + REVIEWER.replace('No trusted Squad verdict was emitted.', 'Squad-Review-Verdict: trusted'), REVIEWER.replace(' if: always()\n', ' if: success()\n'), REVIEWER.replace(' needs: [agent, safe_outputs]', ' needs: [agent]'), ]; diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index 1b4b69c5e..c77b61c8d 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -482,6 +482,37 @@ safe-outputs: pull_number: pullRequest.number, body: `${provenanceMarker}\n${prBodyWithoutProvenance}`, }); + const provenanceComments = (await github.paginate( + github.rest.issues.listComments, + { + ...context.repo, + issue_number: pullRequest.number, + per_page: 100, + }, + )).filter((comment) => + String(comment.body || '').startsWith(' @@ -249,24 +184,23 @@ The deterministic output guard and final job repeat these checks. A refusal, missing verdict, stale head, or malformed provenance cannot clear the required `Squad Review / review` check. -A clean package-install PR is the only exception to the attribution-file -requirement. The deterministic guard recognizes it only when the PR base has -neither the installed review guard nor `.github/aw/squad-workflows.manifest.json`, -the guard is loaded from the immutable workflow commit, and the exact PR head -contains a valid `bradygaster/squad/workflows` installation manifest and package -provenance record. Every installed workflow source, compiled lock, runtime -resource, skill, and manifest byte is fetched at the exact PR head and checked -against canonical content or normalized lock digests fetched from the immutable -package revision. The source revision, exact 8/17/1 topology, ownership shape, -and executing guard digest must agree. In that case only, -absent `.squad-review.json` binds the reserved synthetic attribution -`author_agent: @squad/bootstrap-installation` and -`reviewer_agent: @squad/bootstrap-review-workflow`. These values are outside -the configured stable-agent ID grammar and identify workflow roles, not a -human or committed Squad agent. A present malformed attribution, -an established installation missing attribution, or any non-404 read failure -remains a refusal. Never infer this exception from the PR title, body, branch, -author, or other mutable prose. +The workflow-installation PR is an explicit human trust boundary. Its base does +not contain the Squad guard or manifest, so no code, job name, check result, or +review record emitted by that PR is a trusted Squad verdict. The loader refuses +workflow-source fallback and emits no `Squad-Review-Verdict:` record. Merge the +installation only through explicit human review of the generated package. + +Trusted review starts on the automatic post-merge Cast PR. The guard is then +loaded only from the exact PR base commit, where the installed manifest also +exists. That base-controlled guard permits missing `.squad-review.json` only +for the exact `squad/bootstrap-cast` PR created by the base-controlled bootstrap +workflow. It verifies the GitHub Actions bot author, canonical title and branch, +matching provenance in the PR body and a durable bot-authored PR comment, exact +base/head SHAs, and the referenced default-branch `squad-bootstrap.lock.yml` +push run. It binds the reserved roles +`@squad/base-controlled-bootstrap` and `@squad/base-controlled-review`; the +clearing gate additionally requires that bootstrap run to finish successfully. +All other missing, malformed, or non-404 attribution evidence is refused. ## Provenance decision tree diff --git a/workflows/shared/squad-review-guard.mjs b/workflows/shared/squad-review-guard.mjs index 558d6d64b..618bfb54a 100644 --- a/workflows/shared/squad-review-guard.mjs +++ b/workflows/shared/squad-review-guard.mjs @@ -1,32 +1,19 @@ import { readFileSync, writeFileSync } from 'node:fs'; -import { createHash } from 'node:crypto'; import { evaluateImplementDispatchInputs } from './squad-retro-provenance.mjs'; -import { - CONTRACT_DESTINATION, - CONTRACT_SOURCE, - MIN_GH_AW_VERSION, - OWNERSHIP_ENTRY_COUNT, - PACKAGE_NAME, - RUNTIME_TUPLES, - SKILL_TUPLES, - WORKFLOW_TUPLES, - normalizeCompiledLock, - validateContract, -} from './squad-install-verifier.mjs'; export const CHECK_NAME = 'Squad Review / review'; export const VERDICT_PREFIX = 'Squad-Review-Verdict: '; export const OVERRIDE_PREFIX = 'Squad-Review-Override: '; const WORKFLOW = '.github/workflows/squad-review.lock.yml'; +const BOOTSTRAP_WORKFLOW = '.github/workflows/squad-bootstrap.lock.yml'; const SHA = /^[0-9a-f]{40}$/; const ID = /^[a-z][a-z0-9-]*$/; const BOT = 'github-actions[bot]'; -const INSTALL_MANIFEST = CONTRACT_DESTINATION; -const INSTALL_PACKAGES = '.github/aw/packages'; -const INSTALL_AUTHOR = '@squad/bootstrap-installation'; -const INSTALL_REVIEWER = '@squad/bootstrap-review-workflow'; -const INSTALL_SOURCE_REPOSITORY = 'bradygaster/squad'; -const SHA256 = /^[0-9a-f]{64}$/; +const BOOTSTRAP_BRANCH = 'squad/bootstrap-cast'; +const BOOTSTRAP_TITLE = '[squad] Cast your Squad'; +const BOOTSTRAP_AUTHOR = '@squad/base-controlled-bootstrap'; +const BOOTSTRAP_REVIEWER = '@squad/base-controlled-review'; +const BOOTSTRAP_PREFIX = ''), + `missing or duplicate base-controlled ${label}`); + const value = JSON.parse(lines[0].slice(BOOTSTRAP_PREFIX.length, -4)); + requireThat(exactKeys( + value, + ['schema', 'repository', 'run_id', 'install_sha', 'cast_sha'], + ) && value.schema === 1, `malformed base-controlled ${label}`); + return value; } -async function validateFirstInstallPackage(get, repository, ref, workflowSource, guardSha256) { - const entries = await get(`repos/${repository}/contents/${INSTALL_PACKAGES}`, { ref }); - requireThat(Array.isArray(entries) && entries.length <= 64, - 'unreadable committed first-install package provenance'); - const packages = entries.filter(entry => - entry?.type === 'file' && - /^bradygaster-squad-workflows-[0-9a-f]{12}\.json$/.test(entry.name ?? '')); - requireThat(packages.length === 1, 'missing or duplicate first-install package provenance'); - const provenance = await committedJson( - get, - repository, - `${INSTALL_PACKAGES}/${packages[0].name}`, - ref, - ); - const revision = provenance?.resolvedCommit; - const sourceMatch = typeof workflowSource === 'string' - ? workflowSource.match( - /^bradygaster\/squad\/workflows\/package\/squad-review\.md@([0-9a-f]{40})$/, - ) - : undefined; - exactObjectKeys( - provenance, - ['schemaVersion', 'package', 'source', 'resolvedCommit', 'installer', 'files'], - 'committed first-install package provenance', - ); - requireThat(provenance.schemaVersion === 1 && - provenance.package === PACKAGE_NAME && - SHA.test(revision ?? '') && - provenance.source === `${PACKAGE_NAME}@${revision}` && - typeof provenance.installer === 'string' && - new RegExp(`^gh-aw ${MIN_GH_AW_VERSION.replaceAll('.', '\\.')}(?:\\b|$)`) - .test(provenance.installer) && - Array.isArray(provenance.files) && provenance.files.length === OWNERSHIP_ENTRY_COUNT && - sourceMatch?.[1] === revision, - 'invalid committed first-install package provenance'); - - const canonicalManifestEvidence = await committedFileEvidence( - get, - INSTALL_SOURCE_REPOSITORY, - CONTRACT_SOURCE, - revision, - ); - let manifest; - try { - manifest = JSON.parse(canonicalManifestEvidence.content.toString('utf8')); - validateContract(manifest); - } catch (error) { - throw new Error(`Squad review refused: invalid immutable package manifest: ${error.message}`); - } - const installedManifestEvidence = await committedFileEvidence( - get, - repository, - INSTALL_MANIFEST, - ref, +async function validateBootstrapAttribution(get, repository, pr, requireRunSuccess) { + const provenance = bootstrapRecord(pr.body, 'bootstrap PR provenance'); + const comments = await list(get, `repos/${repository}/issues/${pr.number}/comments`); + const provenanceComments = comments.filter(comment => + comment.user?.login === BOT && + comment.user?.type === 'Bot' && + String(comment.body ?? '').startsWith(BOOTSTRAP_PREFIX)); + requireThat(provenanceComments.length === 1, + 'missing or duplicate bot-authenticated bootstrap provenance comment'); + const commentProvenance = bootstrapRecord( + provenanceComments[0].body, + 'bootstrap comment provenance', ); + requireThat(JSON.stringify(commentProvenance) === JSON.stringify(provenance), + 'bootstrap PR and bot-authenticated comment provenance differ'); requireThat( - installedManifestEvidence.content.equals(canonicalManifestEvidence.content), - 'installed manifest is not byte-identical to the immutable package manifest', + pr.title === BOOTSTRAP_TITLE && + pr.head.ref === BOOTSTRAP_BRANCH && + pr.user?.login === BOT && + pr.user?.type === 'Bot' && + provenance.repository === repository && + /^[1-9]\d*$/.test(provenance.run_id ?? '') && + provenance.install_sha === pr.base.sha && + provenance.cast_sha === pr.head.sha, + 'invalid base-controlled bootstrap pull request', ); - - const expected = expectedOwnership(manifest); - const seen = new Set(); - const installedOwned = new Map(); - for (let index = 0; index < expected.length; index++) { - const owned = provenance.files[index]; - const trusted = expected[index]; - exactObjectKeys(owned, ['source', 'destination', 'sha256'], `ownership file ${index}`); - requireThat(owned.source === trusted.source && owned.destination === trusted.destination && - SHA256.test(owned.sha256), `moved or malformed ownership file ${index}`); - requireThat(!seen.has(owned.destination), `duplicate ownership destination ${owned.destination}`); - seen.add(owned.destination); - const evidence = await committedFileEvidence(get, repository, owned.destination, ref); - requireThat(evidence.sha256 === owned.sha256, - `installed bytes do not match ownership for ${owned.destination}`); - installedOwned.set(owned.destination, evidence); - } - - const canonicalSources = new Map(await Promise.all([ - ...manifest.workflows.map(entry => entry.source), - ...manifest.shared_runtime.map(entry => entry.source), - ...manifest.skills.map(entry => entry.source), - ].map(async source => [ - source, - await committedFileEvidence(get, INSTALL_SOURCE_REPOSITORY, source, revision), - ]))); - - for (const entry of manifest.workflows) { - const canonical = canonicalSources.get(entry.source); - requireThat(canonical.sha256 === entry.source_sha256, - `immutable package source digest mismatch for ${entry.source}`); - const installed = installedOwned.get(entry.destination); - const canonicalized = workflowSourceBytes(installed.content, entry.source, revision); - requireThat( - sha256(canonicalized) === canonical.sha256 || - sha256(Buffer.from(`${canonicalized.toString('utf8')}\n`)) === canonical.sha256, - `installed workflow content mismatch for ${entry.destination}`, - ); - const lock = await committedFileEvidence(get, repository, entry.lock, ref); - requireThat( - sha256(normalizeCompiledLock(lock.content, revision)) === entry.lock_sha256, - `installed compiled lock mismatch for ${entry.lock}`, - ); - } - - for (const entry of manifest.shared_runtime) { - const canonical = canonicalSources.get(entry.source); - requireThat(canonical.sha256 === entry.sha256, - `immutable runtime digest mismatch for ${entry.source}`); - const installed = installedOwned.get(entry.package_destination); - requireThat(installed.content.equals(canonical.content), - `installed runtime content mismatch for ${entry.package_destination}`); - } - - for (const entry of manifest.skills) { - const canonical = canonicalSources.get(entry.source); - requireThat(canonical.sha256 === entry.sha256, - `immutable skill digest mismatch for ${entry.source}`); - const installed = await committedFileEvidence(get, repository, entry.destination, ref); - requireThat(installed.content.equals(canonical.content), - `installed skill content mismatch for ${entry.destination}`); - } - - const guard = manifest.shared_runtime.find( - entry => entry.path === 'shared/squad-review-guard.mjs', + const run = await get(`repos/${repository}/actions/runs/${provenance.run_id}`); + requireThat( + run.event === 'push' && + run.path === BOOTSTRAP_WORKFLOW && + run.repository?.full_name === repository && + run.head_sha === pr.base.sha && + run.head_branch === pr.base.ref && + (!requireRunSuccess || (run.status === 'completed' && run.conclusion === 'success')), + requireRunSuccess + ? 'base-controlled bootstrap run did not complete successfully' + : 'bootstrap provenance is not bound to the base-controlled workflow run', ); - requireThat(guard?.package_destination === '.github/workflows/shared/squad-review-guard.mjs' && - installedOwned.get(guard.package_destination)?.sha256 === guardSha256 && - canonicalSources.get(guard.source)?.sha256 === guardSha256, - 'first-install package does not bind the executing guard'); + return { + schema: 'squad-review-author/v1', + repository, + issue: pr.number, + author_agent: BOOTSTRAP_AUTHOR, + reviewer_agent: BOOTSTRAP_REVIEWER, + }; } export async function reviewTarget( @@ -320,10 +197,7 @@ export async function reviewTarget( get, { relay = false, - firstInstall = false, - workflowSha, - workflowGuardSha256, - workflowSource, + requireBootstrapRunSuccess = false, } = {}, ) { const repository = env.GITHUB_REPOSITORY; @@ -354,29 +228,18 @@ export async function reviewTarget( repository, '.squad-review.json', pr.head.sha, - { allowMissing: firstInstall }, + { allowMissing: true }, ); let attribution; if (value === undefined) { - requireThat(firstInstall === true && relay === false && - env.GITHUB_EVENT_NAME === 'pull_request' && - SHA.test(workflowSha ?? '') && workflowSha === pr.head.sha && - typeof workflowGuardSha256 === 'string' && /^[0-9a-f]{64}$/.test(workflowGuardSha256), - 'missing committed attribution outside an immutable clean first install'); - await validateFirstInstallPackage( + requireThat(relay === false && env.GITHUB_EVENT_NAME === 'pull_request', + 'missing committed attribution outside base-controlled bootstrap activation'); + attribution = await validateBootstrapAttribution( get, repository, - pr.head.sha, - workflowSource, - workflowGuardSha256, + pr, + requireBootstrapRunSuccess, ); - attribution = { - schema: 'squad-review-author/v1', - repository, - issue: issue ?? number, - author_agent: INSTALL_AUTHOR, - reviewer_agent: INSTALL_REVIEWER, - }; } else { const registry = await committedJson( get, @@ -403,8 +266,6 @@ async function currentEvidence(target, get) { export async function enforceReviewOutputs(env, get, options = {}) { requireThat(['pull_request', 'workflow_dispatch'].includes(env.GITHUB_EVENT_NAME), 'invalid event'); - requireThat(options.firstInstall !== true || typeof options.workflowSource === 'string', - 'first-install output binding requires immutable workflow source provenance'); const target = await reviewTarget(env, get, options); const output = JSON.parse(readFileSync(env.GH_AW_AGENT_OUTPUT, 'utf8')); requireThat(Array.isArray(output.items), 'missing safe-output items'); @@ -455,7 +316,10 @@ export async function enforceReviewOutputs(env, get, options = {}) { export async function assertClearingReview(env, get, options = {}) { const { relay = false } = options; requireThat(env.GITHUB_EVENT_NAME === 'pull_request', 'only PR runs can clear review'); - const target = await reviewTarget(env, get, options); + const target = await reviewTarget(env, get, { + ...options, + requireBootstrapRunSuccess: true, + }); const candidates = await currentEvidence(target, get); requireThat(candidates.length === 1, 'missing or duplicate verdict evidence'); const review = candidates[0]; @@ -514,6 +378,9 @@ export async function assertClearingReview(env, get, options = {}) { `repos/${target.repository}/collaborators/${comment.user.login}/permission`); requireThat(permission.permission === 'admin', 'override requires repository administrator'); } - await reviewTarget(env, get, options); + await reviewTarget(env, get, { + ...options, + requireBootstrapRunSuccess: true, + }); return verdict; } diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index 299c60ccb..f30ee0eca 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -473,6 +473,37 @@ safe-outputs: pull_number: pullRequest.number, body: `${provenanceMarker}\n${prBodyWithoutProvenance}`, }); + const provenanceComments = (await github.paginate( + github.rest.issues.listComments, + { + ...context.repo, + issue_number: pullRequest.number, + per_page: 100, + }, + )).filter((comment) => + String(comment.body || '').startsWith(''); + expect(BOOTSTRAP_WORKFLOW).toContain( + "const provenancePrefix = '<' + '!-- squad:bootstrap-provenance ';", + ); + expect(BOOTSTRAP_WORKFLOW).toContain( + 'const provenanceMarker = `${provenancePrefix}${JSON.stringify(provenance)} -->`;', + ); + expect(BOOTSTRAP_WORKFLOW).not.toContain( + '', + ); expect(BOOTSTRAP_WORKFLOW).toContain('pullRequestDetails.head.repo?.full_name !== provenance.repository'); expect(BOOTSTRAP_WORKFLOW).toContain('body: `${provenanceMarker}\\n${prBodyWithoutProvenance}`'); expect(BOOTSTRAP_WORKFLOW).toContain( diff --git a/test/gh-aw-quality.test.ts b/test/gh-aw-quality.test.ts index e9eab11f1..20d47fffa 100644 --- a/test/gh-aw-quality.test.ts +++ b/test/gh-aw-quality.test.ts @@ -3585,11 +3585,23 @@ describe('gh-aw: canonical package integrity contract', () => { const ciRuntimeCount = readText(join(process.cwd(), '.github/workflows/squad-ci.yml')).match( /find \.github\/workflows\/shared -type f ! -name 'squad-bootstrap-trigger-probe\.json' \| wc -l \| tr -d ' '\)" = (\d+)/, ); + const ci = readText(join(process.cwd(), '.github/workflows/squad-ci.yml')); expect(contract.workflows.map((entry: { name: string }) => entry.name)).toEqual(WORKFLOW_NAMES); expect(contract.shared_runtime).toHaveLength(RUNTIME_TUPLES.length); expect(contract.shared_runtime).toHaveLength(17); expect(ciRuntimeCount?.[1], 'strict compile CI runtime cardinality must match the package manifest') .toBe(String(contract.shared_runtime.length)); + const seedStart = ci.indexOf('mkdir -p .github/workflows'); + const addStart = ci.indexOf('gh aw add --force "$GITHUB_WORKSPACE/workflows"'); + expect(seedStart, 'clean-consumer CI must seed all dispatched peers before gh aw add compiles') + .toBeGreaterThan(-1); + expect(addStart).toBeGreaterThan(seedStart); + expect(ci.slice(seedStart, addStart)).toContain( + `for workflow in ${WORKFLOW_NAMES.join(' ')}; do`, + ); + expect(ci.slice(seedStart, addStart)).toContain( + '"$GITHUB_WORKSPACE/workflows/package/${workflow}.md"', + ); expect(contract.shared_runtime).toContainEqual(expect.objectContaining({ path: 'shared/squad-review-guard.mjs', destination: '.github/workflows/shared/squad-review-guard.mjs', diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index c77b61c8d..1bb570e84 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -474,9 +474,10 @@ safe-outputs: || pullRequestDetails.head.repo?.full_name !== provenance.repository) { throw new Error('Trusted bootstrap provenance inputs or Cast PR head identity are invalid.'); } - const provenanceMarker = ``; + const provenancePrefix = '<' + '!-- squad:bootstrap-provenance '; + const provenanceMarker = `${provenancePrefix}${JSON.stringify(provenance)} -->`; const prBodyWithoutProvenance = String(pullRequestDetails.body || payload.pr_body) - .replace(/^\r?\n?/gm, ''); + .replace(new RegExp(`^${provenancePrefix}.* -->\\r?\\n?`, 'gm'), ''); await github.rest.pulls.update({ ...context.repo, pull_number: pullRequest.number, @@ -490,7 +491,7 @@ safe-outputs: per_page: 100, }, )).filter((comment) => - String(comment.body || '').startsWith('`; + const provenancePrefix = '<' + '!-- squad:bootstrap-provenance '; + const provenanceMarker = `${provenancePrefix}${JSON.stringify(provenance)} -->`; const prBodyWithoutProvenance = String(pullRequestDetails.body || payload.pr_body) - .replace(/^\r?\n?/gm, ''); + .replace(new RegExp(`^${provenancePrefix}.* -->\\r?\\n?`, 'gm'), ''); await github.rest.pulls.update({ ...context.repo, pull_number: pullRequest.number, @@ -481,7 +482,7 @@ safe-outputs: per_page: 100, }, )).filter((comment) => - String(comment.body || '').startsWith(''; const PROVENANCE_MARKER_PATTERN = /^$/gm; const ACTIONS_BOT_LOGIN = 'github-actions[bot]'; +const ACTIONS_BOT_ID = 41898282; const SAFE_CHILD_ENV = Object.freeze([ 'CI', 'GH_CONFIG_DIR', @@ -584,6 +585,8 @@ function waitForBaseControlledReviewCanary(target, castPr, evidence) { ]); const verdicts = reviews.filter((review) => review.user?.login === ACTIONS_BOT_LOGIN && + review.user?.id === ACTIONS_BOT_ID && + review.user?.type === 'Bot' && review.commit_id === castPr.headSha && String(review.body ?? '').includes('Squad-Review-Verdict:')); if (verdicts.length > 1) { @@ -603,10 +606,13 @@ function waitForBaseControlledReviewCanary(target, castPr, evidence) { if (verdict.schema !== 'squad-review-verdict/v1' || verdict.repository !== target || verdict.pull_request !== castPr.number + || verdict.base_sha !== castPr.baseSha || verdict.head_sha !== castPr.headSha || verdict.author_agent !== '@squad/base-controlled-bootstrap' || verdict.reviewer_agent !== '@squad/base-controlled-review' - || verdict.result !== 'COMMENT') { + || verdict.result !== 'COMMENT' + || verdict.event !== 'pull_request' + || verdict.workflow_path !== '.github/workflows/squad-review.lock.yml') { throw new Error('Squad Review canary verdict is not bound to the base-controlled bootstrap activation.'); } writeJson(resolve(evidence, 'base-controlled-review-canary.json'), { diff --git a/test/gh-aw-review-guard.test.ts b/test/gh-aw-review-guard.test.ts index ae0ee1a73..cdb309577 100644 --- a/test/gh-aw-review-guard.test.ts +++ b/test/gh-aw-review-guard.test.ts @@ -52,11 +52,12 @@ function fixture(relay = false) { }; const verdict = { schema: 'squad-review-verdict/v1', repository: REPOSITORY, pull_request: 42, - head_sha: HEAD, author_agent: 'implementer', reviewer_agent: 'reviewer', + base_sha: BASE, head_sha: HEAD, author_agent: 'implementer', reviewer_agent: 'reviewer', result: 'COMMENT', timestamp: ISSUED, run_id: 17, run_attempt: 1, event: 'pull_request', + workflow_path: '.github/workflows/squad-review.lock.yml', }; const review = { - id: 123, user: { login: 'github-actions[bot]' }, commit_id: HEAD, + id: 123, user: { login: 'github-actions[bot]', id: 41898282, type: 'Bot' }, commit_id: HEAD, state: 'COMMENTED', submitted_at: SUBMITTED, body: '', }; @@ -270,11 +271,13 @@ describe('independent Squad review guard', () => { it.each([ ['schema', 'other'], ['repository', 'other/repo'], ['pull_request', 41], - ['head_sha', BASE], ['author_agent', 'reviewer'], ['reviewer_agent', 'implementer'], + ['base_sha', HEAD], ['head_sha', BASE], ['author_agent', 'reviewer'], + ['reviewer_agent', 'implementer'], ['result', 'APPROVE'], ['result', ''], ['timestamp', 'bad'], ['timestamp', '2026-09-28T12:05:00Z'], ['timestamp', '2026-09-28T11:00:00Z'], ['timestamp', '2026-02-30T12:01:00Z'], ['run_id', 0], ['run_id', '17'], ['run_attempt', 0], ['event', 'workflow_dispatch'], + ['workflow_path', '.github/workflows/attacker.yml'], ])('refuses verdict mutation %s=%s at the real relay', async (key, value) => { const f = fixture(true); Object.assign(f.verdict, { [key]: value }); @@ -300,6 +303,7 @@ describe('independent Squad review guard', () => { 'failed-run', 'failed-check', 'missing-check', 'duplicate-check', 'wrong-check', 'manual-run', 'wrong-workflow', 'wrong-run-repo', 'wrong-run-sha', 'wrong-run-pr', 'wrong-run-attempt', 'wrong-run-title', 'verdict-before-run', + 'wrong-bot-id', 'wrong-bot-type', ])('fails closed for %s', async mutation => { const f = fixture(true); switch (mutation) { @@ -337,6 +341,8 @@ describe('independent Squad review guard', () => { case 'wrong-run-attempt': f.run.run_attempt = 0; break; case 'wrong-run-title': f.run.display_title = 'Squad review \u2014 PR #43'; break; case 'verdict-before-run': f.run.run_started_at = FINISHED; break; + case 'wrong-bot-id': f.review.user.id = 1; break; + case 'wrong-bot-type': f.review.user.type = 'User'; break; } await expect(assertClearingReview(f.env, f.get, { relay: true })).rejects.toThrow(); }); @@ -444,7 +450,7 @@ describe('independent Squad review guard', () => { expect(output.items[0].body).toContain('"result":"REQUEST_CHANGES"'); }); - it('never mints clearing evidence on a manual run', async () => { + it('refuses manual runs before reading or writing review output', async () => { const f = fixture(); f.state.reviews = []; const workspace = mkdtempSync(join(tmpdir(), 'squad-review-manual-')); @@ -453,16 +459,13 @@ describe('independent Squad review guard', () => { writeFileSync(path, JSON.stringify({ items: [{ type: 'submit_pull_request_review', event: 'REQUEST_CHANGES', body: 'Diagnostic.', }] })); - await enforceReviewOutputs({ + await expect(enforceReviewOutputs({ ...f.env, GITHUB_EVENT_NAME: 'workflow_dispatch', GH_AW_AGENT_OUTPUT: path, - }, f.get); - const output = JSON.parse(readFileSync(path, 'utf8')); - expect(output.items[0].event).toBe('COMMENT'); - expect(output.items[0].body).not.toContain(VERDICT_PREFIX); - expect(output.items[0].body).toContain('diagnostic only'); + }, f.get)).rejects.toThrow('only PR runs'); + expect(JSON.parse(readFileSync(path, 'utf8')).items[0].body).toBe('Diagnostic.'); }); - it('deduplicates only a validated existing verdict, never a marker-shaped claim', async () => { + it('deduplicates only evidence from the exact run attempt', async () => { const f = fixture(); const workspace = mkdtempSync(join(tmpdir(), 'squad-review-dedup-')); workspaces.push(workspace); @@ -474,6 +477,13 @@ describe('independent Squad review guard', () => { type: 'submit_pull_request_review', event: 'COMMENT', body: 'Duplicate.', }] })); await expect(enforceReviewOutputs(env, f.get)).rejects.toThrow('already has a verdict'); + f.verdict.run_attempt = 2; + f.sync(); + writeFileSync(path, JSON.stringify({ items: [{ + type: 'submit_pull_request_review', event: 'COMMENT', body: 'New attempt.', + }] })); + await expect(enforceReviewOutputs(env, f.get)).resolves.toBeUndefined(); + expect(readFileSync(path, 'utf8')).toContain('\\"run_attempt\\":1'); f.review.body = `${VERDICT_PREFIX}{broken`; writeFileSync(path, JSON.stringify({ items: [{ type: 'noop' }] })); await expect(enforceReviewOutputs(env, f.get)).rejects.toThrow(); diff --git a/test/gh-aw-review-workflow.test.ts b/test/gh-aw-review-workflow.test.ts index 6e7334ca5..0a68a576c 100644 --- a/test/gh-aw-review-workflow.test.ts +++ b/test/gh-aw-review-workflow.test.ts @@ -91,7 +91,10 @@ function assertReviewerContract(workflow: string): void { expect(submitReview).not.toContain('APPROVE'); expect(concurrency).toContain('cancel-in-progress: true'); expect(trigger).not.toMatch(/^\s+forks:/m); + expect(trigger).not.toContain('workflow_dispatch:'); expect(yaml).toContain('github.event.pull_request.head.repo.full_name == github.repository'); + expect(yaml).not.toContain('github.workflow_sha'); + expect(yaml).not.toContain('github.event.inputs'); expect(workflow).toContain('Squad-Review-Head: {40-character lowercase head SHA}'); expect(rows).toEqual([ '1:One validated durable worker marker:Squad-authored', @@ -147,9 +150,9 @@ afterAll(() => { function assertCompiledGate(lock: string): void { const workflow = parse(lock); const { jobs } = workflow; - expect(workflow['run-name']).toBe('Squad review — PR #${{ github.event.inputs.issue_number || github.event.pull_request.number }}'); + expect(workflow['run-name']).toBe('Squad review — PR #${{ github.event.pull_request.number }}'); const review = jobs.review; - expect(review.name).toBe("${{ github.event_name == 'pull_request' && 'Squad Review / review' || 'Squad Review / manual' }}"); + expect(review.name).toBe('Squad Review / review'); expect(review.if).toBe('always()'); expect(review.needs).toEqual(expect.arrayContaining(['agent', 'safe_outputs'])); const execution = review.steps.find((step: { name: string }) => step.name === 'Require successful PR review execution'); @@ -167,7 +170,7 @@ function assertCompiledGate(lock: string): void { expect(steps[guard]['continue-on-error']).toBeUndefined(); const baseCheckout = steps.find((step: { name: string }) => step.name === 'Checkout base commit for review guard'); - expect(baseCheckout.with.ref).toBe('${{ github.event.pull_request.base.sha || github.workflow_sha }}'); + expect(baseCheckout.with.ref).toBe('${{ github.event.pull_request.base.sha }}'); expect(steps.some((step: { name: string }) => step.name.includes('workflow commit'))).toBe(false); expect(steps[guard].with.script).toContain('!existsSync(baseGuard) || !existsSync(baseManifest)'); @@ -207,8 +210,9 @@ async function executeCompiledGuardLoader( { baseGuard, baseManifest = false, + dispatchGuard, head = 'a'.repeat(40), - }: { baseGuard?: string; baseManifest?: boolean; head?: string }, + }: { baseGuard?: string; baseManifest?: boolean; dispatchGuard?: string; head?: string }, ): Promise { const workspace = mkdtempSync(resolve(ROOT, '.squad-review-loader-')); compileWorkspaces.push(workspace); @@ -228,6 +232,17 @@ async function executeCompiledGuardLoader( mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, '{}\n'); } + if (dispatchGuard !== undefined) { + const path = resolve( + workspace, + '.github', + 'workflows', + 'shared', + 'squad-review-guard.mjs', + ); + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, dispatchGuard); + } const previousWorkspace = process.env.GITHUB_WORKSPACE; const previousOutput = process.env.SQUAD_TEST_GUARD_OUTPUT; const previousHead = process.env.SQUAD_REVIEW_HEAD; @@ -255,32 +270,23 @@ async function executeCompiledGuardLoader( } describe('gh-aw enforcing Squad reviewer', () => { - it('routes /squad review to the isolated workflow and supports automatic PR events', () => { + it('keeps review automatic and makes /squad review a non-dispatching rerun guide', () => { const routerDispatch = yamlBlock(ROUTER_FRONTMATTER, 'dispatch-workflow'); const reviewTrigger = yamlBlock(REVIEWER_FRONTMATTER, 'on'); const relay = ROUTER.match(/## skill: `squad-review-relay`([\s\S]*?)(?=\n## skill:)/)?.[1] ?? ''; - const relayPayload = JSON.parse(relay.match(/```json\n([\s\S]*?)\n```/)?.[1] ?? '{}') as { - workflow_name?: string; - inputs?: Record; - issue_number?: string; - }; - expect(listInBlock(routerDispatch, 'workflows')).toContain('squad-review'); + expect(listInBlock(routerDispatch, 'workflows')).not.toContain('squad-review'); + expect(ROUTER_FRONTMATTER).toContain('actions: read'); expect(ROUTER).toContain('| `/squad review` | Review Relay |'); expect(REVIEWER).not.toContain('slash_command:'); - expect(reviewTrigger).toMatch(/workflow_dispatch:\n\s+inputs:/); expect(reviewTrigger).toMatch(/pull_request:\n\s+types: \[opened, reopened, ready_for_review, synchronize\]/); - expect(relayPayload).toEqual({ - workflow_name: 'squad-review', - inputs: { - issue_number: '{pull-request-number}', - expected_head_sha: '{current-head-sha}', - request_origin: 'manual', - }, - }); - expect(relayPayload.issue_number).toBeUndefined(); - expect(relay).not.toContain('"pr_number"'); - expect(relay).toContain('Never call the generic'); + expect(reviewTrigger).not.toContain('workflow_dispatch:'); + expect(relay).toContain('.github/workflows/squad-review.lock.yml'); + expect(relay).toContain('exact current head'); + expect(relay).toContain('require exactly one job named `Squad Review / review`'); + expect(relay).toContain('This command did not rerun it.'); + expect(relay).toContain('no automatic review run exists for the exact head'); + expect(relay).not.toContain('dispatch-workflow'); }); it('limits slash commands to issue and pull request conversation surfaces', () => { @@ -392,13 +398,13 @@ describe('gh-aw enforcing Squad reviewer', () => { const concurrency = yamlBlock(REVIEWER_FRONTMATTER, 'concurrency'); expect(concurrency).toContain( - 'group: "squad-review-${{ github.event.inputs.issue_number || github.event.pull_request.number || github.run_id }}"', + 'group: "squad-review-${{ github.event.pull_request.number }}"', ); expect(concurrency).toContain('cancel-in-progress: true'); expect(REVIEWER_FRONTMATTER).not.toMatch(/^\s+forks:/m); expect(REVIEWER).toContain('If an existing bot review contains a `Squad-Review-Verdict:` record'); - expect(REVIEWER).toContain('Never re-review an unchanged head'); - expect(REVIEWER).toContain('Re-fetch the pull request immediately before emitting'); + expect(REVIEWER).toContain('Evidence from a different run or attempt cannot deduplicate'); + expect(REVIEWER).toMatch(/Re-fetch the pull request\s+immediately before emitting/); }); it('covers acceptance, routing, protected files, tests, and changesets', () => { @@ -431,7 +437,7 @@ describe('gh-aw enforcing Squad reviewer', () => { expect(safeOutputs.submit_pull_request_review).toMatchObject({ max: 1, allowed_events: ['COMMENT', 'REQUEST_CHANGES'], - commit_id: '${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }}', + commit_id: '${{ github.event.pull_request.head.sha }}', }); expect(safeOutputs).not.toHaveProperty('dispatch_workflow'); expect(safeOutputs).not.toHaveProperty('create_issue'); @@ -460,12 +466,14 @@ describe('gh-aw enforcing Squad reviewer', () => { ? 'edd6fbf0f84334ff086ed2bc8bbfed5503fdd56f' : '9a898b5182ca432b62bef26dbf1f9022dd1d256b'; await expect(executeCompiledGuardLoader(script, { + dispatchGuard: stub('dispatch-ref'), head, })).rejects.toThrow('First-install manual boundary'); await expect(executeCompiledGuardLoader(script, { baseGuard: stub('base'), baseManifest: true, + dispatchGuard: stub('dispatch-ref'), head, })).resolves.toBe(JSON.stringify({ source: 'base', @@ -517,6 +525,14 @@ describe('gh-aw enforcing Squad reviewer', () => { REVIEWER.replace('invalid provenance. Fail closed with', 'invalid provenance. Continue with'), REVIEWER.replace('Every same-repository PR (including', 'Some PRs (including'), REVIEWER.replace('inlined-imports: true', 'inlined-imports: false'), + REVIEWER.replace( + 'on:\n pull_request:', + 'on:\n workflow_dispatch:\n pull_request:', + ), + REVIEWER.replace( + 'ref: ${{ github.event.pull_request.base.sha }}', + 'ref: ${{ github.workflow_sha }}', + ), REVIEWER.replaceAll('Squad-Review-Head: {40-character lowercase head SHA}', 'Reviewed head SHA'), ]; @@ -530,7 +546,7 @@ describe('gh-aw enforcing Squad reviewer', () => { const mutations = [ REVIEWER.replace('await guard.enforceReviewOutputs', 'void guard.enforceReviewOutputs'), REVIEWER.replace('await guard.assertClearingReview', 'void guard.assertClearingReview'), - REVIEWER.replace("&& 'Squad Review / review'", "&& 'Other check'"), + REVIEWER.replace(' name: Squad Review / review', ' name: Other check'), REVIEWER.replace('pathToFileURL(baseGuard)', "pathToFileURL('.squad-review-workflow/guard.mjs')"), REVIEWER.replace('No trusted Squad verdict was emitted.', 'Squad-Review-Verdict: trusted'), REVIEWER.replace(' if: always()\n', ' if: success()\n'), diff --git a/workflows/package/squad-review.md b/workflows/package/squad-review.md index 9eab2043d..26eba8df9 100644 --- a/workflows/package/squad-review.md +++ b/workflows/package/squad-review.md @@ -1,31 +1,17 @@ --- name: Squad Review -run-name: "Squad review — PR #${{ github.event.inputs.issue_number || github.event.pull_request.number }}" +run-name: "Squad review — PR #${{ github.event.pull_request.number }}" description: Independently reviews agent-authored pull requests without editing or remediating private: false inlined-imports: true on: - workflow_dispatch: - inputs: - issue_number: - description: Pull request number to review - required: true - type: string - expected_head_sha: - description: Pull request head SHA observed by the /squad review relay - required: true - type: string - request_origin: - description: Review request origin - required: true - type: string pull_request: types: - opened - reopened - ready_for_review - synchronize -if: github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) +if: github.event.pull_request.head.repo.full_name == github.repository permissions: contents: read copilot-requests: write @@ -33,9 +19,8 @@ permissions: pull-requests: read actions: read concurrency: - group: squad-review-${{ github.event.inputs.issue_number || github.event.pull_request.number || github.run_id }} + group: squad-review-${{ github.event.pull_request.number }} cancel-in-progress: true - job-discriminator: ${{ github.run_id }} network: allowed: - defaults @@ -53,15 +38,15 @@ safe-outputs: - name: Checkout base commit for review guard uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: - ref: ${{ github.event.pull_request.base.sha || github.workflow_sha }} + ref: ${{ github.event.pull_request.base.sha }} persist-credentials: false path: .squad-review-base - name: Bind review output to committed agent identities and current head uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 env: GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }} - SQUAD_REVIEW_PR: ${{ github.event.pull_request.number || github.event.inputs.issue_number }} - SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }} + SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} + SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} with: script: | const { existsSync } = require('node:fs'); @@ -80,20 +65,20 @@ safe-outputs: async (route, fields) => (await github.request(`GET /${route}`, fields)).data); add-comment: max: 1 - target: ${{ github.event.inputs.issue_number || github.event.pull_request.number }} + target: ${{ github.event.pull_request.number }} create-pull-request-review-comment: max: 10 - target: ${{ github.event.inputs.issue_number || github.event.pull_request.number }} + target: ${{ github.event.pull_request.number }} submit-pull-request-review: max: 1 - target: ${{ github.event.inputs.issue_number || github.event.pull_request.number }} + target: ${{ github.event.pull_request.number }} allowed-events: - COMMENT - REQUEST_CHANGES - commit-id: ${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }} + commit-id: ${{ github.event.pull_request.head.sha }} jobs: review: - name: ${{ github.event_name == 'pull_request' && 'Squad Review / review' || 'Squad Review / manual' }} + name: Squad Review / review if: always() needs: - agent @@ -107,23 +92,19 @@ jobs: steps: - name: Require successful PR review execution env: - EVENT_NAME: ${{ github.event_name }} AGENT_RESULT: ${{ needs.agent.result }} OUTPUT_RESULT: ${{ needs.safe_outputs.result }} run: | set -euo pipefail - if [ "$EVENT_NAME" != pull_request ]; then exit 0; fi test "$AGENT_RESULT" = success test "$OUTPUT_RESULT" = success - name: Checkout base commit for final verdict gate - if: github.event_name == 'pull_request' uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: ref: ${{ github.event.pull_request.base.sha }} persist-credentials: false path: .squad-review-base - name: Enforce independent current-head verdict - if: github.event_name == 'pull_request' uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 env: SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} @@ -160,19 +141,19 @@ this workflow. ## Trigger and target gate 1. Resolve the pull request number from - `${{ github.event.inputs.issue_number || github.event.pull_request.number }}`. + `${{ github.event.pull_request.number }}`. If it is absent or not a positive integer, call `noop` and stop. 2. Fetch the pull request from `${{ github.repository }}` and record its current 40-character lowercase head SHA. -3. For `workflow_dispatch`, require `request_origin` to equal `manual` and - `expected_head_sha` to equal the current head SHA. A missing, malformed, or - stale value, or a head repository other than `${{ github.repository }}`, is a - refusal: call `noop` and stop. This is the `/squad review` path relayed by - `workflows/squad.md`. -4. For `pull_request`, require the head repository to equal +3. Require the head repository to equal `${{ github.repository }}`. Forks and any event other than `opened`, `reopened`, `ready_for_review` or `synchronize` are refused with `noop`. +This workflow has no `workflow_dispatch` trigger. `/squad review` is an operator +aid that points to GitHub's **Re-run jobs** action for the existing automatic +run. Never execute reviewer code, guards, manifests, or safe-output handlers +from a manually selected ref. + Read `.squad-review.json` at the exact PR head SHA and the committed `.squad/casting/registry.json` at the PR base SHA. The attribution schema is `squad-review-author/v1` with `repository`, positive integer `issue`, @@ -240,11 +221,13 @@ machine-readable review marker is a standalone final line: `Squad-Review-Head: {40-character lowercase head SHA}` If an existing bot review contains a `Squad-Review-Verdict:` record for the -current head SHA, call `noop` and stop. The deterministic gate validates it; -an arbitrary comment or the legacy head marker is not clearing evidence. -Never re-review an unchanged head, including duplicate -`synchronize` deliveries. Re-fetch the pull request immediately before emitting -outputs; if its head SHA changed, call `noop` and let the newer run review it. +current head SHA and this exact workflow run ID and attempt, call `noop` and +stop. Evidence from a different run or attempt cannot deduplicate or clear this +run. The deterministic gate validates the event, workflow path, PR, base, head, +run, attempt, and GitHub Actions bot identity; an arbitrary comment or the +legacy head marker is not clearing evidence. Re-fetch the pull request +immediately before emitting outputs; if its head SHA changed, call `noop` and +let the newer run review it. ## Review procedure @@ -279,12 +262,11 @@ Submit exactly one review: Do not emit `Squad-Review-Verdict:` or `Squad-Review-Override:` yourself. The trusted safe-output guard adds the repository, PR, head SHA, stable -author/reviewer IDs, result, timestamp and workflow-run binding. Only -`pull_request` runs mint this evidence; manual `/squad review` is diagnostic -and does not satisfy the required check. A valid `REQUEST_CHANGES` keeps the -check red unless an administrator posts the documented SHA- and review-scoped -override and reruns the PR workflow. Overrides cannot repair invalid identity -or missing evidence. Never approve or merge on behalf of a human. +author/reviewer IDs, result, timestamp and exact automatic workflow-run binding. +Manual dispatch does not exist. A valid `REQUEST_CHANGES` keeps the check red +unless an administrator posts the documented SHA- and review-scoped override +and reruns the same PR workflow. Overrides cannot repair invalid identity or +missing evidence. Never approve or merge on behalf of a human. Keep the body concise. State the provenance classification, linked issue scope, and blocking themes. End with these two standalone lines, substituting the diff --git a/workflows/package/squad.md b/workflows/package/squad.md index 67cbe1ac1..7623c0e6c 100644 --- a/workflows/package/squad.md +++ b/workflows/package/squad.md @@ -472,7 +472,6 @@ safe-outputs: workflows: - squad-implement-worker - squad-deps-worker - - squad-review - squad-retro - squad-improvement-worker max: 3 @@ -740,6 +739,7 @@ on: type: string if: github.event_name != 'issues' || github.actor != 'github-actions[bot]' || github.event.issue.title != '[Research Proposals] Agent-discovered repo opportunities' || !contains(github.event.issue.body, '') permissions: + actions: read contents: read copilot-requests: write issues: read @@ -2228,32 +2228,37 @@ and includes the verified PR number, URL, and CI-approval guidance. ## skill: `squad-review-relay` --- -description: Relay `/squad review` on a pull request to the independent reviewer. +description: Guide an operator to rerun the automatic independent review. --- This mode is only valid from a pull request comment or pull request review comment. Resolve the pull request number and current 40-character lowercase head SHA from GitHub's API, not from user text. If either cannot be established, post one `add-comment` explaining that `/squad review` must target a pull -request, then stop without dispatching. - -Use only the typed `dispatch-workflow` safe-output. Never call the generic -`dispatch_workflow` tool. Emit exactly one dispatch: - -```json -{ - "workflow_name": "squad-review", - "inputs": { - "issue_number": "{pull-request-number}", - "expected_head_sha": "{current-head-sha}", - "request_origin": "manual" - } -} -``` +request, then stop. + +List workflow runs for `.github/workflows/squad-review.lock.yml`. Keep only +`pull_request` runs associated with this pull request and exact current head +SHA. Select the newest run by creation time, breaking ties by numeric run ID, +then fetch its jobs and require exactly one job named `Squad Review / review`. +If no matching run or check exists, emit exactly one `add-comment` stating that +no automatic review run exists for the exact head and that a new PR event +(`synchronize`, reopen, or ready-for-review) is required. Stop without implying +that a rerun occurred. + +Otherwise emit exactly one `add-comment` on the pull request that includes the +selected run URL, run ID, attempt, status, conclusion, exact head SHA, and this +instruction: + +> Squad Review is automatic and cannot be dispatched from a branch. In the +> selected automatic run, open `Squad Review / review` and choose **Re-run +> jobs**. This command did not rerun it. Only the new attempt of that exact +> `pull_request` run can publish verdict evidence for PR #{pull-request-number} +> at head `{current-head-sha}`. Do not review the diff in this router, emit a verdict, edit files, create an -issue, or dispatch any other workflow. The independent reviewer owns all -provenance, deduplication, and review decisions. +issue, or dispatch a workflow. The independent reviewer owns all provenance, +deduplication, and review decisions. ## skill: `squad-retro-relay` --- diff --git a/workflows/shared/squad-review-guard.mjs b/workflows/shared/squad-review-guard.mjs index 036534d68..f11878742 100644 --- a/workflows/shared/squad-review-guard.mjs +++ b/workflows/shared/squad-review-guard.mjs @@ -9,6 +9,7 @@ const BOOTSTRAP_WORKFLOW = '.github/workflows/squad-bootstrap.lock.yml'; const SHA = /^[0-9a-f]{40}$/; const ID = /^[a-z][a-z0-9-]*$/; const BOT = 'github-actions[bot]'; +const BOT_ID = 41898282; const BOOTSTRAP_BRANCH = 'squad/bootstrap-cast'; const BOOTSTRAP_TITLE = '[squad] Cast your Squad'; const BOOTSTRAP_AUTHOR = '@squad/base-controlled-bootstrap'; @@ -61,18 +62,24 @@ export function validateAttribution(value, registry, repository, issue) { export function validateVerdict(value, expected, review, now = Date.now()) { requireThat(exactKeys(value, [ - 'schema', 'repository', 'pull_request', 'head_sha', 'author_agent', 'reviewer_agent', - 'result', 'timestamp', 'run_id', 'run_attempt', 'event', + 'schema', 'repository', 'pull_request', 'base_sha', 'head_sha', 'author_agent', + 'reviewer_agent', 'result', 'timestamp', 'run_id', 'run_attempt', 'event', + 'workflow_path', ]) && value.schema === 'squad-review-verdict/v1', 'invalid verdict shape'); - for (const key of ['repository', 'pull_request', 'head_sha', 'author_agent', 'reviewer_agent']) { + for (const key of [ + 'repository', 'pull_request', 'base_sha', 'head_sha', 'author_agent', 'reviewer_agent', + ]) { requireThat(value[key] === expected[key], `verdict ${key} mismatch`); } - requireThat(SHA.test(value.head_sha) && value.author_agent !== value.reviewer_agent, + requireThat(SHA.test(value.base_sha) && SHA.test(value.head_sha) && + value.author_agent !== value.reviewer_agent, 'invalid SHA or self review'); requireThat(['COMMENT', 'REQUEST_CHANGES'].includes(value.result) && value.event === 'pull_request' && Number.isSafeInteger(value.run_id) && value.run_id > 0 && - Number.isSafeInteger(value.run_attempt) && value.run_attempt > 0, 'invalid verdict result or run'); - requireThat(review.user?.login === BOT && review.commit_id === value.head_sha && + Number.isSafeInteger(value.run_attempt) && value.run_attempt > 0 && + value.workflow_path === WORKFLOW, 'invalid verdict result or run'); + requireThat(review.user?.login === BOT && review.user?.id === BOT_ID && + review.user?.type === 'Bot' && review.commit_id === value.head_sha && review.state === 'COMMENTED', 'review author, commit, or native result mismatch'); const issued = timestamp(value.timestamp); @@ -250,7 +257,7 @@ export async function reviewTarget( attribution = validateAttribution(value, registry, repository, issue ?? value?.issue); } return { - repository, pull_request: number, head_sha: pr.head.sha, + repository, pull_request: number, base_sha: pr.base.sha, head_sha: pr.head.sha, author_agent: attribution.author_agent, reviewer_agent: attribution.reviewer_agent, pr, }; } @@ -265,15 +272,19 @@ async function currentEvidence(target, get) { } export async function enforceReviewOutputs(env, get, options = {}) { - requireThat(['pull_request', 'workflow_dispatch'].includes(env.GITHUB_EVENT_NAME), 'invalid event'); + requireThat(env.GITHUB_EVENT_NAME === 'pull_request', 'only PR runs can emit review output'); const target = await reviewTarget(env, get, options); const output = JSON.parse(readFileSync(env.GH_AW_AGENT_OUTPUT, 'utf8')); requireThat(Array.isArray(output.items), 'missing safe-output items'); const verdicts = output.items.filter(item => item.type === 'submit_pull_request_review'); const existing = await currentEvidence(target, get); - requireThat(existing.length <= 1, 'duplicate verdict evidence'); - if (existing.length === 1) { - validateVerdict(record(existing[0].body, VERDICT_PREFIX), target, existing[0]); + const currentRun = existing.filter(review => { + const verdict = validateVerdict(record(review.body, VERDICT_PREFIX), target, review); + return String(verdict.run_id) === env.GITHUB_RUN_ID && + String(verdict.run_attempt) === env.GITHUB_RUN_ATTEMPT; + }); + requireThat(currentRun.length <= 1, 'duplicate verdict evidence for this run'); + if (currentRun.length === 1) { requireThat(verdicts.length === 0, 'unchanged head already has a verdict'); return; } @@ -282,17 +293,11 @@ export async function enforceReviewOutputs(env, get, options = {}) { requireThat(['COMMENT', 'REQUEST_CHANGES'].includes(item.event) && typeof item.body === 'string' && !item.body.includes('Squad-Review-Verdict') && !item.body.includes('Squad-Review-Override'), 'invalid review output'); - // Manual runs remain useful review diagnostics, but never mint clearing evidence. - if (env.GITHUB_EVENT_NAME === 'workflow_dispatch') { - item.body += `\n\nManual Squad verdict: ${item.event} (diagnostic only).`; - item.event = 'COMMENT'; - writeFileSync(env.GH_AW_AGENT_OUTPUT, JSON.stringify(output)); - return; - } const value = { schema: 'squad-review-verdict/v1', repository: target.repository, pull_request: target.pull_request, + base_sha: target.base_sha, head_sha: target.head_sha, author_agent: target.author_agent, reviewer_agent: target.reviewer_agent, @@ -301,6 +306,7 @@ export async function enforceReviewOutputs(env, get, options = {}) { run_id: Number(env.GITHUB_RUN_ID), run_attempt: Number(env.GITHUB_RUN_ATTEMPT), event: 'pull_request', + workflow_path: WORKFLOW, }; requireThat(Number.isSafeInteger(value.run_id) && value.run_id > 0 && Number.isSafeInteger(value.run_attempt) && value.run_attempt > 0, 'invalid workflow identity'); @@ -320,11 +326,21 @@ export async function assertClearingReview(env, get, options = {}) { ...options, requireBootstrapRunSuccess: true, }); - const candidates = await currentEvidence(target, get); - requireThat(candidates.length === 1, 'missing or duplicate verdict evidence'); - const review = candidates[0]; + const candidates = (await currentEvidence(target, get)).map(review => ({ + review, + verdict: validateVerdict( + record(review.body, VERDICT_PREFIX), + target, + review, + relay ? timestamp(target.pr.merged_at) : Date.now(), + ), + })); + const bound = relay ? candidates : candidates.filter(({ verdict }) => + String(verdict.run_id) === env.GITHUB_RUN_ID && + String(verdict.run_attempt) === env.GITHUB_RUN_ATTEMPT); + requireThat(bound.length === 1, 'missing or duplicate verdict evidence for this run'); + const { review, verdict } = bound[0]; const cutoff = relay ? timestamp(target.pr.merged_at) : Date.now(); - const verdict = validateVerdict(record(review.body, VERDICT_PREFIX), target, review, cutoff); const run = await get(`repos/${target.repository}/actions/runs/${verdict.run_id}`); requireThat(run.event === 'pull_request' && run.path === WORKFLOW && run.repository?.full_name === target.repository && run.head_sha === target.head_sha && @@ -334,12 +350,12 @@ export async function assertClearingReview(env, get, options = {}) { (run.pull_requests.length === 0 || run.pull_requests.some(pr => pr.number === target.pull_request && pr.head?.sha === target.head_sha && pr.base?.repo?.name === target.pr.base.repo.name)), 'verdict is not bound to this PR workflow run'); - requireThat(relay || String(verdict.run_id) === env.GITHUB_RUN_ID || - (run.status === 'completed' && run.conclusion === 'success'), - 'rerun the original PR review workflow to clear its failed verdict'); const attempt = run.run_attempt === verdict.run_attempt ? run : await get(`repos/${target.repository}/actions/runs/${verdict.run_id}/attempts/${verdict.run_attempt}`); - requireThat(attempt.run_attempt === verdict.run_attempt && + requireThat(attempt.event === 'pull_request' && attempt.path === WORKFLOW && + attempt.repository?.full_name === target.repository && + attempt.head_sha === target.head_sha && + attempt.run_attempt === verdict.run_attempt && timestamp(attempt.run_started_at) <= timestamp(verdict.timestamp) && (attempt.status !== 'completed' || timestamp(review.submitted_at) <= timestamp(attempt.updated_at)), 'verdict outside workflow run'); diff --git a/workflows/squad-review.md b/workflows/squad-review.md index d7520925b..96f8f02bb 100644 --- a/workflows/squad-review.md +++ b/workflows/squad-review.md @@ -1,30 +1,13 @@ --- name: Squad Review -run-name: "Squad review — PR #${{ github.event.inputs.issue_number || github.event.pull_request.number }}" +run-name: "Squad review — PR #${{ github.event.pull_request.number }}" description: Independently reviews agent-authored pull requests without editing or remediating private: false inlined-imports: true on: - workflow_dispatch: - inputs: - issue_number: - description: Pull request number to review - required: true - type: string - expected_head_sha: - description: Pull request head SHA observed by the /squad review relay - required: true - type: string - request_origin: - description: Review request origin - required: true - type: string pull_request: types: [opened, reopened, ready_for_review, synchronize] -if: >- - github.event_name == 'workflow_dispatch' || - (github.event_name == 'pull_request' && - github.event.pull_request.head.repo.full_name == github.repository) +if: github.event.pull_request.head.repo.full_name == github.repository permissions: contents: read copilot-requests: write @@ -32,9 +15,8 @@ permissions: pull-requests: read actions: read concurrency: - group: "squad-review-${{ github.event.inputs.issue_number || github.event.pull_request.number || github.run_id }}" + group: "squad-review-${{ github.event.pull_request.number }}" cancel-in-progress: true - job-discriminator: ${{ github.run_id }} network: allowed: - defaults @@ -51,15 +33,15 @@ safe-outputs: - name: Checkout base commit for review guard uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - ref: ${{ github.event.pull_request.base.sha || github.workflow_sha }} + ref: ${{ github.event.pull_request.base.sha }} persist-credentials: false path: .squad-review-base - name: Bind review output to committed agent identities and current head uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 env: GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }} - SQUAD_REVIEW_PR: ${{ github.event.pull_request.number || github.event.inputs.issue_number }} - SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }} + SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} + SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} with: script: | const { existsSync } = require('node:fs'); @@ -78,19 +60,18 @@ safe-outputs: async (route, fields) => (await github.request(`GET /${route}`, fields)).data); add-comment: max: 1 - target: "${{ github.event.inputs.issue_number || github.event.pull_request.number }}" + target: "${{ github.event.pull_request.number }}" create-pull-request-review-comment: max: 10 - target: "${{ github.event.inputs.issue_number || github.event.pull_request.number }}" + target: "${{ github.event.pull_request.number }}" submit-pull-request-review: max: 1 - target: "${{ github.event.inputs.issue_number || github.event.pull_request.number }}" + target: "${{ github.event.pull_request.number }}" allowed-events: [COMMENT, REQUEST_CHANGES] - commit-id: "${{ github.event.pull_request.head.sha || github.event.inputs.expected_head_sha }}" + commit-id: "${{ github.event.pull_request.head.sha }}" jobs: review: - # A manual run must never publish the required context, including a skipped one. - name: "${{ github.event_name == 'pull_request' && 'Squad Review / review' || 'Squad Review / manual' }}" + name: Squad Review / review if: always() needs: [agent, safe_outputs] runs-on: ubuntu-latest @@ -102,23 +83,19 @@ jobs: steps: - name: Require successful PR review execution env: - EVENT_NAME: ${{ github.event_name }} AGENT_RESULT: ${{ needs.agent.result }} OUTPUT_RESULT: ${{ needs.safe_outputs.result }} run: | set -euo pipefail - if [ "$EVENT_NAME" != pull_request ]; then exit 0; fi test "$AGENT_RESULT" = success test "$OUTPUT_RESULT" = success - name: Checkout base commit for final verdict gate - if: github.event_name == 'pull_request' uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: ${{ github.event.pull_request.base.sha }} persist-credentials: false path: .squad-review-base - name: Enforce independent current-head verdict - if: github.event_name == 'pull_request' uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 env: SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} @@ -154,19 +131,19 @@ this workflow. ## Trigger and target gate 1. Resolve the pull request number from - `${{ github.event.inputs.issue_number || github.event.pull_request.number }}`. + `${{ github.event.pull_request.number }}`. If it is absent or not a positive integer, call `noop` and stop. 2. Fetch the pull request from `${{ github.repository }}` and record its current 40-character lowercase head SHA. -3. For `workflow_dispatch`, require `request_origin` to equal `manual` and - `expected_head_sha` to equal the current head SHA. A missing, malformed, or - stale value, or a head repository other than `${{ github.repository }}`, is a - refusal: call `noop` and stop. This is the `/squad review` path relayed by - `workflows/squad.md`. -4. For `pull_request`, require the head repository to equal +3. Require the head repository to equal `${{ github.repository }}`. Forks and any event other than `opened`, `reopened`, `ready_for_review` or `synchronize` are refused with `noop`. +This workflow has no `workflow_dispatch` trigger. `/squad review` is an operator +aid that points to GitHub's **Re-run jobs** action for the existing automatic +run. Never execute reviewer code, guards, manifests, or safe-output handlers +from a manually selected ref. + Read `.squad-review.json` at the exact PR head SHA and the committed `.squad/casting/registry.json` at the PR base SHA. The attribution schema is `squad-review-author/v1` with `repository`, positive integer `issue`, @@ -234,11 +211,13 @@ machine-readable review marker is a standalone final line: `Squad-Review-Head: {40-character lowercase head SHA}` If an existing bot review contains a `Squad-Review-Verdict:` record for the -current head SHA, call `noop` and stop. The deterministic gate validates it; -an arbitrary comment or the legacy head marker is not clearing evidence. -Never re-review an unchanged head, including duplicate -`synchronize` deliveries. Re-fetch the pull request immediately before emitting -outputs; if its head SHA changed, call `noop` and let the newer run review it. +current head SHA and this exact workflow run ID and attempt, call `noop` and +stop. Evidence from a different run or attempt cannot deduplicate or clear this +run. The deterministic gate validates the event, workflow path, PR, base, head, +run, attempt, and GitHub Actions bot identity; an arbitrary comment or the +legacy head marker is not clearing evidence. Re-fetch the pull request +immediately before emitting outputs; if its head SHA changed, call `noop` and +let the newer run review it. ## Review procedure @@ -273,12 +252,11 @@ Submit exactly one review: Do not emit `Squad-Review-Verdict:` or `Squad-Review-Override:` yourself. The trusted safe-output guard adds the repository, PR, head SHA, stable -author/reviewer IDs, result, timestamp and workflow-run binding. Only -`pull_request` runs mint this evidence; manual `/squad review` is diagnostic -and does not satisfy the required check. A valid `REQUEST_CHANGES` keeps the -check red unless an administrator posts the documented SHA- and review-scoped -override and reruns the PR workflow. Overrides cannot repair invalid identity -or missing evidence. Never approve or merge on behalf of a human. +author/reviewer IDs, result, timestamp and exact automatic workflow-run binding. +Manual dispatch does not exist. A valid `REQUEST_CHANGES` keeps the check red +unless an administrator posts the documented SHA- and review-scoped override +and reruns the same PR workflow. Overrides cannot repair invalid identity or +missing evidence. Never approve or merge on behalf of a human. Keep the body concise. State the provenance classification, linked issue scope, and blocking themes. End with these two standalone lines, substituting the diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 037a79baf..2fa5be42a 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -14,8 +14,8 @@ "source": "workflows/package/squad.md", "destination": ".github/workflows/squad.md", "lock": ".github/workflows/squad.lock.yml", - "source_sha256": "17d7b124e5d3f06d8c1ea67a7330366b40f3e69d2209e8477fe4fa38a1ae38b0", - "lock_sha256": "c8f1375aab790ef9ca7531fabdc5a80423865e3981db127b6e2cb994d32b7e87" + "source_sha256": "68110664fa20d4efbee19fd75bb8f2406f1cbfcb1df3dddeb2419251a5355d17", + "lock_sha256": "2195655666fb474ba57d8729aef822b77e501e35deebb96b3d121875311eeaa5" }, { "name": "squad-implement-worker", @@ -30,8 +30,8 @@ "source": "workflows/package/squad-review.md", "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", - "source_sha256": "ff7cbcf07cb4ef3cb9cca40dc4f4f4d5ae0796172c7ea07d2902a1d733bf8f70", - "lock_sha256": "6429829963430903ebeb616b82341d708e6af4282a05af32df3c013d5704b311" + "source_sha256": "8ffefbf5b0b16b0623612446790bb3e0ca7c9b89de674e81b7e95ac9e008c0fd", + "lock_sha256": "5d0ee03e894805eb63aaa8258ddc447f3e734d2d8a18ff3f89a12d418a722b90" }, { "name": "squad-deps-worker", @@ -81,7 +81,7 @@ "package_destination": ".github/workflows/shared/squad-review-guard.mjs", "destination": ".github/workflows/shared/squad-review-guard.mjs", "ownership": "manifest", - "sha256": "277003226e699bc3de3b3072a64016155d3fc047ac3759dd90624b25b0cc07fa" + "sha256": "2a18ddd8a57c255e966ad2a1baa211f7d07277b1b4a15738a8dfb1211a67e18a" }, { "path": "shared/squad-install-verifier.mjs", diff --git a/workflows/squad.md b/workflows/squad.md index a2ea0d56c..42830e74e 100644 --- a/workflows/squad.md +++ b/workflows/squad.md @@ -32,6 +32,7 @@ if: >- github.event.issue.title != '[Research Proposals] Agent-discovered repo opportunities' || !contains(github.event.issue.body, '') permissions: + actions: read contents: read copilot-requests: write issues: read @@ -423,7 +424,7 @@ safe-outputs: max: 20 target: "*" dispatch-workflow: - workflows: [squad-implement-worker, squad-deps-worker, squad-review, squad-retro, squad-improvement-worker] + workflows: [squad-implement-worker, squad-deps-worker, squad-retro, squad-improvement-worker] max: 3 --- @@ -1124,32 +1125,37 @@ and includes the verified PR number, URL, and CI-approval guidance. ## skill: `squad-review-relay` --- -description: Relay `/squad review` on a pull request to the independent reviewer. +description: Guide an operator to rerun the automatic independent review. --- This mode is only valid from a pull request comment or pull request review comment. Resolve the pull request number and current 40-character lowercase head SHA from GitHub's API, not from user text. If either cannot be established, post one `add-comment` explaining that `/squad review` must target a pull -request, then stop without dispatching. - -Use only the typed `dispatch-workflow` safe-output. Never call the generic -`dispatch_workflow` tool. Emit exactly one dispatch: - -```json -{ - "workflow_name": "squad-review", - "inputs": { - "issue_number": "{pull-request-number}", - "expected_head_sha": "{current-head-sha}", - "request_origin": "manual" - } -} -``` +request, then stop. + +List workflow runs for `.github/workflows/squad-review.lock.yml`. Keep only +`pull_request` runs associated with this pull request and exact current head +SHA. Select the newest run by creation time, breaking ties by numeric run ID, +then fetch its jobs and require exactly one job named `Squad Review / review`. +If no matching run or check exists, emit exactly one `add-comment` stating that +no automatic review run exists for the exact head and that a new PR event +(`synchronize`, reopen, or ready-for-review) is required. Stop without implying +that a rerun occurred. + +Otherwise emit exactly one `add-comment` on the pull request that includes the +selected run URL, run ID, attempt, status, conclusion, exact head SHA, and this +instruction: + +> Squad Review is automatic and cannot be dispatched from a branch. In the +> selected automatic run, open `Squad Review / review` and choose **Re-run +> jobs**. This command did not rerun it. Only the new attempt of that exact +> `pull_request` run can publish verdict evidence for PR #{pull-request-number} +> at head `{current-head-sha}`. Do not review the diff in this router, emit a verdict, edit files, create an -issue, or dispatch any other workflow. The independent reviewer owns all -provenance, deduplication, and review decisions. +issue, or dispatch a workflow. The independent reviewer owns all provenance, +deduplication, and review decisions. ## skill: `squad-retro-relay` --- From 6c567c9beff3d9ec6f532b359e1684d5cb670652 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 21:41:35 -0700 Subject: [PATCH 07/14] fix(gh-aw): attest review from base context Part of #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/agents.md | 5 +- docs/src/content/docs/guide/gh-aw.md | 57 +++++---- scripts/gh-aw-hosted-e2e.mjs | 28 ++++- test/gh-aw-review-guard.test.ts | 89 ++++++++++++-- test/gh-aw-review-workflow.test.ts | 92 ++++++++++++--- workflows/package/squad-review.md | 148 +++++++++++++++++++++--- workflows/package/squad.md | 23 ++-- workflows/shared/squad-review-guard.mjs | 72 +++++++++--- workflows/squad-review.md | 145 ++++++++++++++++++++--- workflows/squad-workflows.manifest.json | 10 +- workflows/squad.md | 23 ++-- 11 files changed, 578 insertions(+), 114 deletions(-) diff --git a/.github/agents.md b/.github/agents.md index a167c8efa..3d1d6ee5e 100644 --- a/.github/agents.md +++ b/.github/agents.md @@ -35,8 +35,9 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas > the repository's default branch. > The installation PR is a manual trust boundary: its PR-controlled workflow > cannot mint a trusted Squad verdict. After merge, require the automatically -> opened Cast PR to pass `Squad Review / review` using the base-controlled guard -> before treating bootstrap or lifecycle automation as trusted. +> opened Cast PR to pass the exact-head `Squad Review / review` attestation from +> the base-controlled `pull_request_target` authority before treating bootstrap +> or lifecycle automation as trusted. The quick start installs this workflow set: diff --git a/docs/src/content/docs/guide/gh-aw.md b/docs/src/content/docs/guide/gh-aw.md index 33fd59f38..d59215ca4 100644 --- a/docs/src/content/docs/guide/gh-aw.md +++ b/docs/src/content/docs/guide/gh-aw.md @@ -112,7 +112,8 @@ requires a human to review the verifier/compile evidence before merging. After merge, the default-branch bootstrap workflow opens the draft Cast PR. That PR is the activation canary: `Squad Review / review` must succeed using the -guard and manifest checked out from the Cast PR's exact base commit. The guard +base-controlled `pull_request_target` workflow plus the guard and manifest +checked out from the Cast PR's exact base commit. The guard also requires matching exact-head provenance in the PR body and a durable GitHub Actions bot comment, so editable PR prose cannot rebind an old bootstrap run to a changed branch head. Only after that base-controlled canary succeeds @@ -1448,10 +1449,12 @@ The implementation worker performs an internal self-review before opening a PR: After the PR is opened, `squad-review` provides an independent review. Every same-repository pull request triggers review on `opened`, `reopened`, `ready_for_review` and `synchronize`; fork pull requests are refused. The -workflow has no `workflow_dispatch` trigger, so a contributor-selected ref -cannot execute reviewer code or safe-output handlers. Comment `/squad review` -to receive instructions for opening the existing `Squad Review / review` run -for the current head and using GitHub's **Re-run jobs** action. +workflow runs as `pull_request_target` from immutable default-branch context, +sets `checkout: false`, and has no `workflow_dispatch` trigger. It never checks +out or executes pull request files, actions, scripts, guards, or manifests; the +agent reads the diff through GitHub APIs. Comment `/squad review` to receive +instructions for opening the existing base-controlled run and using GitHub's +**Re-run all jobs** action. The reviewer classifies provenance in this priority order: @@ -1485,9 +1488,11 @@ labels, and GitHub logins do not establish independent logical agent identity. This is auditable logical attribution, not proof of a separate account or model. Registry migration and legitimate attribution changes require human review. -The trusted guard reads attribution from the exact PR head commit, never the -agent's working tree. A `Squad-Review-Verdict:` JSON record binds repository, PR, -head SHA, both agent IDs, verdict, UTC timestamp, and workflow run/attempt. +The trusted guard reads attribution from the exact PR head commit through the +GitHub API, never by checking out or executing the PR. A +`Squad-Review-Verdict:` JSON record binds repository, PR, base SHA, head SHA, +immutable workflow SHA, both agent IDs, verdict, UTC timestamp, and the +`pull_request_target` workflow run/attempt. Exactly one current-head record is required. The legacy `Squad-Review-Head: ` marker remains human-readable but is not authorization. Per-PR concurrency cancels stale runs; both output and final gate re-fetch the @@ -1506,8 +1511,13 @@ exactly one pull request review. It returns: The trusted writer publishes these logical verdicts in a native `COMMENT` review: GitHub does not permit an account to approve or request changes on its -own PR. The separate status check enforces `REQUEST_CHANGES`; no additional bot -accounts or Apps are needed. +own PR. The native `Squad Review Authority / attest` job proves that the base-controlled +workflow executed. Its publisher creates `Squad Review / review` on the exact +PR head with a `squad-review-check/v1` attestation linked to that run. A +PR-controlled workflow may create advisory output with the same display name, +but it cannot satisfy the relay without the successful native authority job and +exact event/base/head/run/App binding. The status check enforces +`REQUEST_CHANGES`; no additional bot accounts or Apps are needed. The reviewer has no file-editing, issue-creation, pull-request-creation, remediation, merge, or `APPROVE` authority. Its verdict @@ -1521,35 +1531,39 @@ The lifecycle is: ``` The epic relay repeats the guard before running the agent and before processing -any outputs. It requires a clearing verdict and the successful required job -from that PR review run, completed **before merge**, for the merged PR's -**head SHA**, not the merge commit. Bypassing a missing Squad review at merge +any outputs. It requires a clearing verdict, the successful native authority +job from the base-controlled run, and the exact-head published check completed +**before merge** for the merged PR's **head SHA**, not the merge commit. +Bypassing a missing Squad review at merge cannot silently advance the epic. Missing evidence stops the run with an explicit error; it never dispatches the next wave. ### Required check rollout (repository administrator) The stable literal check name is **`Squad Review / review`**. -`inlined-imports: true` makes the compiled job directly addressable. There is no manual reviewer run. `/squad review` only explains how to rerun the -existing automatic PR run, and only that exact run ID and attempt can satisfy +existing automatic `pull_request_target` run, and only that exact base-controlled +run ID, attempt, native authority job, and exact-head attestation can satisfy its emitted verdict and check. Brady (or the consumer repository administrator) must install/merge the complete generated bundle through the explicit human installation boundary, then observe -a successful PR-triggered check on the post-install draft Cast PR before +a successful base-controlled `pull_request_target` check on the post-install +draft Cast PR before changing rulesets. The installation PR itself is not evidence: its workflow and check name are controlled by that PR. Record the activation canary's actual -check name and GitHub App ID from the check-runs API. Enable the required context -with that observed App ID on `dev` **only after advisory soak** has met the +check name, external ID, details URL, attestation summary, and GitHub App ID +from the check-runs API. Enable the required context with that observed App ID +on `dev` **only after advisory soak** has met the evidence gate in #1734; promote to `main` after the agreed soak. This change does not modify repository rulesets and does not claim live soak evidence. Keep native human approving-review requirements enabled independently, with stale approvals dismissed. The bot's `COMMENT` is not a human approval. Do not use an unobserved guessed App ID or require the manual job. Because rulesets apply to all PRs, existing human/Copilot PRs must add committed -attribution before enabling the requirement. Fork review is not supported by -this workflow; do not relax it with `pull_request_target`. +attribution before enabling the requirement. Fork review remains unsupported; +the workflow rejects foreign head repositories even though its base-controlled +trigger is `pull_request_target`. ### Auditable human override @@ -1562,7 +1576,8 @@ native review ID, and a meaningful reason): Squad-Review-Override: {"schema":"squad-review-override/v1","repository":"owner/repo","pull_request":456,"head_sha":"0123456789abcdef0123456789abcdef01234567","review_id":789,"reason":"False positive: explanation and evidence for accepting this risk."} ``` -Then rerun the original **PR-triggered workflow**, not the manual dispatcher. +Then rerun the original base-controlled **`pull_request_target` workflow**, not +the manual dispatcher. The gate checks the human account type and live administrator permission, record shape, exact SHA/review binding, creation time after the verdict and before merge, and absence of edits or duplicate override records. Do not edit diff --git a/scripts/gh-aw-hosted-e2e.mjs b/scripts/gh-aw-hosted-e2e.mjs index 18ea8f8d5..b17ea1eff 100644 --- a/scripts/gh-aw-hosted-e2e.mjs +++ b/scripts/gh-aw-hosted-e2e.mjs @@ -572,10 +572,16 @@ function waitForBaseControlledReviewCanary(target, castPr, evidence) { 'api', '-H', 'Accept: application/vnd.github+json', `repos/${target}/commits/${castPr.headSha}/check-runs`, - '--jq', '{check_runs:[.check_runs[] | {id,name,status,conclusion,app:{slug:.app.slug}}]}', + '--jq', '{check_runs:[.check_runs[] | {id,name,status,conclusion,head_sha,external_id,details_url,completed_at,output:{summary:.output.summary},app:{id:.app.id,slug:.app.slug}}]}', ]).check_runs; + const externalId = + `squad-review-authority/v1:${target}:${castPr.number}:${castPr.baseSha}:${castPr.headSha}`; const trustedChecks = checks.filter((check) => - check.name === 'Squad Review / review' && check.app?.slug === 'github-actions'); + check.name === 'Squad Review / review' && + check.external_id === externalId && + check.head_sha === castPr.headSha && + check.app?.id === 15368 && + check.app?.slug === 'github-actions'); if (trustedChecks.length > 1) { throw new Error(`Expected one base-controlled Squad Review canary check; found ${trustedChecks.length}.`); } @@ -611,15 +617,31 @@ function waitForBaseControlledReviewCanary(target, castPr, evidence) { || verdict.author_agent !== '@squad/base-controlled-bootstrap' || verdict.reviewer_agent !== '@squad/base-controlled-review' || verdict.result !== 'COMMENT' - || verdict.event !== 'pull_request' + || verdict.event !== 'pull_request_target' + || verdict.workflow_sha !== castPr.baseSha || verdict.workflow_path !== '.github/workflows/squad-review.lock.yml') { throw new Error('Squad Review canary verdict is not bound to the base-controlled bootstrap activation.'); } + const attestation = JSON.parse(check.output?.summary ?? ''); + if (attestation.schema !== 'squad-review-check/v1' + || attestation.repository !== target + || attestation.pull_request !== castPr.number + || attestation.base_sha !== castPr.baseSha + || attestation.head_sha !== castPr.headSha + || attestation.workflow_sha !== castPr.baseSha + || attestation.run_id !== verdict.run_id + || attestation.event !== 'pull_request_target' + || attestation.workflow_path !== '.github/workflows/squad-review.lock.yml' + || attestation.authority_job !== 'Squad Review Authority / attest' + || check.details_url !== `https://github.com/${target}/actions/runs/${verdict.run_id}`) { + throw new Error('Squad Review canary check is not bound to the base-controlled authority run.'); + } writeJson(resolve(evidence, 'base-controlled-review-canary.json'), { pull_request: castPr, check, review: verdicts[0], verdict, + attestation, }); return { check, verdict }; } diff --git a/test/gh-aw-review-guard.test.ts b/test/gh-aw-review-guard.test.ts index cdb309577..fee6f1dd6 100644 --- a/test/gh-aw-review-guard.test.ts +++ b/test/gh-aw-review-guard.test.ts @@ -27,9 +27,11 @@ afterEach(() => { function fixture(relay = false) { vi.spyOn(Date, 'now').mockReturnValue(NOW); const env = { - GITHUB_EVENT_NAME: 'pull_request', GITHUB_REPOSITORY: REPOSITORY, + GITHUB_EVENT_NAME: 'pull_request_target', GITHUB_REPOSITORY: REPOSITORY, + GITHUB_SERVER_URL: 'https://github.com', GITHUB_RUN_ID: '17', GITHUB_RUN_ATTEMPT: '1', - SQUAD_REVIEW_PR: '42', SQUAD_REVIEW_HEAD: HEAD, SQUAD_REVIEW_DEFAULT_BRANCH: 'dev', + SQUAD_REVIEW_PR: '42', SQUAD_REVIEW_HEAD: HEAD, + SQUAD_REVIEW_WORKFLOW_SHA: BASE, SQUAD_REVIEW_DEFAULT_BRANCH: 'dev', }; const attribution = { schema: 'squad-review-author/v1', repository: REPOSITORY, issue: 9, @@ -53,8 +55,9 @@ function fixture(relay = false) { const verdict = { schema: 'squad-review-verdict/v1', repository: REPOSITORY, pull_request: 42, base_sha: BASE, head_sha: HEAD, author_agent: 'implementer', reviewer_agent: 'reviewer', - result: 'COMMENT', timestamp: ISSUED, run_id: 17, run_attempt: 1, event: 'pull_request', - workflow_path: '.github/workflows/squad-review.lock.yml', + result: 'COMMENT', timestamp: ISSUED, run_id: 17, run_attempt: 1, + event: 'pull_request_target', workflow_path: '.github/workflows/squad-review.lock.yml', + workflow_sha: BASE, }; const review = { id: 123, user: { login: 'github-actions[bot]', id: 41898282, type: 'Bot' }, commit_id: HEAD, @@ -62,13 +65,43 @@ function fixture(relay = false) { body: '', }; const run = { - event: 'pull_request', path: '.github/workflows/squad-review.lock.yml', + event: 'pull_request_target', path: '.github/workflows/squad-review.lock.yml', display_title: 'Squad review \u2014 PR #42', - repository: { full_name: REPOSITORY }, head_sha: HEAD, run_attempt: 1, + repository: { full_name: REPOSITORY }, head_sha: BASE, run_attempt: 1, pull_requests: [{ number: 42, head: { sha: HEAD }, base: { repo: { name: 'example' } } }], run_started_at: START, updated_at: FINISHED, status: 'completed', conclusion: 'success', }; - const jobs = [{ name: CHECK_NAME, conclusion: 'success', completed_at: FINISHED }]; + const jobs = [{ + name: 'Squad Review Authority / attest', + conclusion: 'success', + completed_at: FINISHED, + }]; + const checkRuns = [{ + id: 88, + name: CHECK_NAME, + external_id: `squad-review-authority/v1:${REPOSITORY}:42:${BASE}:${HEAD}`, + head_sha: HEAD, + status: 'completed', + conclusion: 'success', + completed_at: FINISHED, + details_url: `https://github.com/${REPOSITORY}/actions/runs/17`, + app: { id: 15368, slug: 'github-actions' }, + output: { + summary: JSON.stringify({ + schema: 'squad-review-check/v1', + repository: REPOSITORY, + pull_request: 42, + base_sha: BASE, + head_sha: HEAD, + workflow_sha: BASE, + run_id: 17, + run_attempt: 1, + event: 'pull_request_target', + workflow_path: '.github/workflows/squad-review.lock.yml', + authority_job: 'Squad Review Authority / attest', + }), + }, + }]; const bootstrapRun = { event: 'push', path: '.github/workflows/squad-bootstrap.lock.yml', repository: { full_name: REPOSITORY }, head_sha: BASE, head_branch: 'dev', @@ -100,6 +133,9 @@ function fixture(relay = false) { if (state.changeAfterFirstRead && state.prReads > 1) pr.head.sha = BASE; return structuredClone(pr); } + if (route === `repos/${REPOSITORY}`) { + return { full_name: REPOSITORY, default_branch: 'dev' }; + } if (route.endsWith('/contents/.squad-review.json')) { expect(fields?.ref).toBe(HEAD); if (state.missingManifest) { @@ -116,6 +152,7 @@ function fixture(relay = false) { if (route.endsWith('/actions/runs/29')) return bootstrapRun; if (route.endsWith('/attempts/1')) return { ...run, run_attempt: 1, run_started_at: START }; if (/\/attempts\/[12]\/jobs$/.test(route)) return { jobs }; + if (route.endsWith(`/commits/${HEAD}/check-runs`)) return { check_runs: checkRuns }; if (route.endsWith('/comments')) return state.comments; if (route.endsWith('/permission')) return { permission: state.permission }; throw new Error(`Unexpected API route: ${route}`); @@ -126,7 +163,8 @@ function fixture(relay = false) { }; sync(); return { - env, attribution, registry, pr, verdict, review, run, bootstrapRun, jobs, override, comment, + env, attribution, registry, pr, verdict, review, run, bootstrapRun, jobs, checkRuns, + override, comment, state, encode, get, sync, }; } @@ -244,6 +282,22 @@ describe('independent Squad review guard', () => { } }); + it('refuses PR-controlled shaped review, job, check, and artifact evidence', async () => { + const f = fixture(true); + f.run.event = 'pull_request'; + f.run.head_sha = HEAD; + f.jobs[0].name = CHECK_NAME; + f.checkRuns[0].external_id = + `squad-review-authority/v1:${REPOSITORY}:42:${BASE}:${HEAD}`; + f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + event: 'pull_request', + workflow_sha: HEAD, + }); + await expect(assertClearingReview(f.env, f.get, { relay: true })) + .rejects.toThrow('not bound to this PR workflow run'); + }); + it.each([ ['schema', 'other'], ['repository', 'other/repo'], ['issue', 10], ['issue', '9'], ['author_agent', 'missing'], ['reviewer_agent', 'missing'], @@ -277,7 +331,7 @@ describe('independent Squad review guard', () => { ['timestamp', '2026-09-28T12:05:00Z'], ['timestamp', '2026-09-28T11:00:00Z'], ['timestamp', '2026-02-30T12:01:00Z'], ['run_id', 0], ['run_id', '17'], ['run_attempt', 0], ['event', 'workflow_dispatch'], - ['workflow_path', '.github/workflows/attacker.yml'], + ['workflow_path', '.github/workflows/attacker.yml'], ['workflow_sha', HEAD], ])('refuses verdict mutation %s=%s at the real relay', async (key, value) => { const f = fixture(true); Object.assign(f.verdict, { [key]: value }); @@ -301,6 +355,7 @@ describe('independent Squad review guard', () => { 'wrong-branch', 'duplicate-marker', 'stale-head', 'foreign-head', 'foreign-base', 'head-race', 'not-merged', 'wrong-base', 'merge-before-review', 'merge-before-check', 'failed-run', 'failed-check', 'missing-check', 'duplicate-check', 'wrong-check', + 'forged-check', 'wrong-check-app', 'wrong-check-attestation', 'manual-run', 'wrong-workflow', 'wrong-run-repo', 'wrong-run-sha', 'wrong-run-pr', 'wrong-run-attempt', 'wrong-run-title', 'verdict-before-run', 'wrong-bot-id', 'wrong-bot-type', @@ -336,13 +391,19 @@ describe('independent Squad review guard', () => { case 'manual-run': f.run.event = 'workflow_dispatch'; break; case 'wrong-workflow': f.run.path = '.github/workflows/other.yml'; break; case 'wrong-run-repo': f.run.repository.full_name = 'other/repo'; break; - case 'wrong-run-sha': f.run.head_sha = BASE; break; + case 'wrong-run-sha': f.run.head_sha = HEAD; break; case 'wrong-run-pr': f.run.pull_requests[0].number = 43; break; case 'wrong-run-attempt': f.run.run_attempt = 0; break; case 'wrong-run-title': f.run.display_title = 'Squad review \u2014 PR #43'; break; case 'verdict-before-run': f.run.run_started_at = FINISHED; break; case 'wrong-bot-id': f.review.user.id = 1; break; case 'wrong-bot-type': f.review.user.type = 'User'; break; + case 'forged-check': f.checkRuns[0].external_id = 'forged'; break; + case 'wrong-check-app': f.checkRuns[0].app.id = 1; break; + case 'wrong-check-attestation': f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + event: 'pull_request', + }); break; } await expect(assertClearingReview(f.env, f.get, { relay: true })).rejects.toThrow(); }); @@ -350,7 +411,7 @@ describe('independent Squad review guard', () => { it('does not accept a manual gate or the merge commit as the reviewed head', async () => { const f = fixture(true); await expect(assertClearingReview({ ...f.env, GITHUB_EVENT_NAME: 'workflow_dispatch' }, f.get, { relay: true })) - .rejects.toThrow('only PR runs'); + .rejects.toThrow('only base-controlled PR target runs'); await expect(reviewTarget({ ...f.env, SQUAD_REVIEW_HEAD: BASE }, f.get, { relay: true })) .rejects.toThrow('head changed'); }); @@ -371,6 +432,10 @@ describe('independent Squad review guard', () => { f.state.comments = [f.comment]; f.state.comments.push({ ...f.comment, body: `${OVERRIDE_PREFIX}${JSON.stringify({ ...f.override, head_sha: BASE })}` }); f.run.run_attempt = 2; + f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + run_attempt: 2, + }); await expect(assertClearingReview(f.env, f.get, { relay: true })).resolves.toEqual(f.verdict); expect(f.state.calls.some(route => route.endsWith('/attempts/2/jobs'))).toBe(true); }); @@ -461,7 +526,7 @@ describe('independent Squad review guard', () => { }] })); await expect(enforceReviewOutputs({ ...f.env, GITHUB_EVENT_NAME: 'workflow_dispatch', GH_AW_AGENT_OUTPUT: path, - }, f.get)).rejects.toThrow('only PR runs'); + }, f.get)).rejects.toThrow('only base-controlled PR target runs'); expect(JSON.parse(readFileSync(path, 'utf8')).items[0].body).toBe('Diagnostic.'); }); diff --git a/test/gh-aw-review-workflow.test.ts b/test/gh-aw-review-workflow.test.ts index 0a68a576c..5a9759a42 100644 --- a/test/gh-aw-review-workflow.test.ts +++ b/test/gh-aw-review-workflow.test.ts @@ -92,8 +92,14 @@ function assertReviewerContract(workflow: string): void { expect(concurrency).toContain('cancel-in-progress: true'); expect(trigger).not.toMatch(/^\s+forks:/m); expect(trigger).not.toContain('workflow_dispatch:'); + expect(trigger).toMatch(/pull_request_target:/); + expect(trigger).not.toMatch(/^\s+pull_request:/m); + expect(yaml).toContain('checkout: false'); + expect(yaml).toContain('strict: false'); expect(yaml).toContain('github.event.pull_request.head.repo.full_name == github.repository'); - expect(yaml).not.toContain('github.workflow_sha'); + expect(yaml).toContain('SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }}'); + expect(yaml).toContain('ref: ${{ github.event.pull_request.base.sha }}'); + expect(yaml).not.toContain('ref: ${{ github.workflow_sha }}'); expect(yaml).not.toContain('github.event.inputs'); expect(workflow).toContain('Squad-Review-Head: {40-character lowercase head SHA}'); expect(rows).toEqual([ @@ -107,6 +113,9 @@ function assertReviewerContract(workflow: string): void { expect(workflow).toContain('inlined-imports: true'); expect(workflow).toContain('await guard.enforceReviewOutputs'); expect(workflow).toContain('await guard.assertClearingReview'); + expect(workflow).toContain('Squad Review Authority / attest'); + expect(workflow).toContain('Publish exact-head required check'); + expect(workflow).toContain("run.event !== 'pull_request_target'"); expect(workflow).toContain('The workflow-installation PR is an explicit human trust boundary.'); expect(workflow).toContain('Trusted review starts on the automatic post-merge Cast PR.'); expect(workflow).toContain('Human approval remains mandatory.'); @@ -150,9 +159,11 @@ afterAll(() => { function assertCompiledGate(lock: string): void { const workflow = parse(lock); const { jobs } = workflow; + expect(workflow.on).toHaveProperty('pull_request_target'); + expect(workflow.on).not.toHaveProperty('pull_request'); expect(workflow['run-name']).toBe('Squad review — PR #${{ github.event.pull_request.number }}'); const review = jobs.review; - expect(review.name).toBe('Squad Review / review'); + expect(review.name).toBe('Squad Review Authority / attest'); expect(review.if).toBe('always()'); expect(review.needs).toEqual(expect.arrayContaining(['agent', 'safe_outputs'])); const execution = review.steps.find((step: { name: string }) => step.name === 'Require successful PR review execution'); @@ -160,6 +171,7 @@ function assertCompiledGate(lock: string): void { expect(execution.run).toContain('test "$OUTPUT_RESULT" = success'); expect(review.steps.at(-1).with.script).toContain('await guard.assertClearingReview'); expect(review.steps.at(-1).env.SQUAD_REVIEW_HEAD).toBe('${{ github.event.pull_request.head.sha }}'); + expect(review.steps.at(-1).env.SQUAD_REVIEW_WORKFLOW_SHA).toBe('${{ github.workflow_sha }}'); const steps = jobs.safe_outputs.steps; const guard = steps.findIndex((step: { name: string }) => step.name === 'Bind review output to committed agent identities and current head'); const process = steps.findIndex((step: { name: string }) => step.name === 'Process Safe Outputs'); @@ -189,6 +201,27 @@ function assertCompiledGate(lock: string): void { expect(finalGate.with.script).not.toContain('Squad-Review-Verdict:'); for (const step of review.steps) expect(step['continue-on-error']).toBeUndefined(); expect(review['continue-on-error']).toBeUndefined(); + const publish = jobs.publish; + expect(publish.name).toBe('Publish Squad Review required check'); + expect(publish.if).toBe('always()'); + expect(publish.needs).toEqual(expect.arrayContaining(['agent', 'safe_outputs', 'review'])); + expect(publish.permissions).toMatchObject({ + actions: 'read', + checks: 'write', + contents: 'read', + 'pull-requests': 'read', + }); + const publishStep = publish.steps.find((step: { name: string }) => + step.name === 'Publish exact-head required check'); + expect(publishStep.with.script).toContain("const checkName = 'Squad Review / review'"); + expect(publishStep.with.script).toContain("run.event !== 'pull_request_target'"); + expect(publishStep.with.script).toContain('run.head_sha !== workflowSha'); + expect(publishStep.with.script).toContain('authorityJobs.length !== 1'); + expect(publishStep.with.script).toContain("external_id: externalId"); + expect(publishStep.with.script).toContain("head_sha: headSha"); + expect(publishStep.with.script).not.toContain('github.event.pull_request.head.ref'); + expect(lock).not.toContain('Checkout PR branch'); + expect(lock).not.toMatch(/uses:\s+\.\/\.github\/actions\//); } function compiledGuardScripts(lock: string): Array<{ name: string; script: string }> { @@ -279,13 +312,13 @@ describe('gh-aw enforcing Squad reviewer', () => { expect(ROUTER_FRONTMATTER).toContain('actions: read'); expect(ROUTER).toContain('| `/squad review` | Review Relay |'); expect(REVIEWER).not.toContain('slash_command:'); - expect(reviewTrigger).toMatch(/pull_request:\n\s+types: \[opened, reopened, ready_for_review, synchronize\]/); + expect(reviewTrigger).toMatch(/pull_request_target:\n\s+types: \[opened, reopened, ready_for_review, synchronize\]/); expect(reviewTrigger).not.toContain('workflow_dispatch:'); expect(relay).toContain('.github/workflows/squad-review.lock.yml'); - expect(relay).toContain('exact current head'); - expect(relay).toContain('require exactly one job named `Squad Review / review`'); - expect(relay).toContain('This command did not rerun it.'); - expect(relay).toContain('no automatic review run exists for the exact head'); + expect(relay).toContain('exact current PR head'); + expect(relay).toMatch(/require\s+exactly one job named `Squad Review Authority \/ attest`/); + expect(relay).toMatch(/command did not rerun it\./); + expect(relay).toMatch(/no base-controlled automatic review run exists for\s+the exact head/); expect(relay).not.toContain('dispatch-workflow'); }); @@ -443,6 +476,8 @@ describe('gh-aw enforcing Squad reviewer', () => { expect(safeOutputs).not.toHaveProperty('create_issue'); expect(safeOutputs).not.toHaveProperty('create_pull_request'); expect(lock).toContain('GH_AW_HEAD_SHA: ${{ github.event.pull_request.head.sha }}'); + expect(lock).toContain('pull_request_target:'); + expect(lock).not.toContain('Checkout PR branch'); }, 30000); it('loads review authority only from the base and makes first install a manual boundary', async () => { @@ -505,9 +540,30 @@ describe('gh-aw enforcing Squad reviewer', () => { } }, 30000); + it('rejects compiled PR-head checkout, local action, and PR-trigger authority mutations', () => { + const mutations = [ + REVIEWER.replace( + 'ref: ${{ github.event.pull_request.base.sha }}', + 'ref: ${{ github.event.pull_request.head.sha }}', + ), + REVIEWER.replace( + "uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0", + 'uses: ./.github/actions/pr-controlled', + ), + REVIEWER.replace('pull_request_target:', 'pull_request:'), + ]; + for (const [index, mutation] of mutations.entries()) { + expect(mutation, `compiled adversarial mutation ${index} must change the source`) + .not.toBe(REVIEWER); + const { lock } = compileReviewer(mutation); + expect(() => assertCompiledGate(lock), `compiled adversarial mutation ${index}`) + .toThrow(); + } + }, 60000); + it('kills mutations of every important authority and provenance gate', () => { const mutations = [ - REVIEWER.replace('tools:\n bash:', 'tools:\n edit:\n bash:'), + REVIEWER.replace('tools:\n github:', 'tools:\n edit:\n github:'), REVIEWER.replace( 'safe-outputs:\n', 'safe-outputs:\n dispatch-workflow:\n workflows: [squad-retro]\n max: 1\n', @@ -526,18 +582,20 @@ describe('gh-aw enforcing Squad reviewer', () => { REVIEWER.replace('Every same-repository PR (including', 'Some PRs (including'), REVIEWER.replace('inlined-imports: true', 'inlined-imports: false'), REVIEWER.replace( - 'on:\n pull_request:', - 'on:\n workflow_dispatch:\n pull_request:', + 'on:\n pull_request_target:', + 'on:\n workflow_dispatch:\n pull_request_target:', ), REVIEWER.replace( 'ref: ${{ github.event.pull_request.base.sha }}', 'ref: ${{ github.workflow_sha }}', ), + REVIEWER.replace('checkout: false', 'checkout: true'), + REVIEWER.replace('pull_request_target:', 'pull_request:'), REVIEWER.replaceAll('Squad-Review-Head: {40-character lowercase head SHA}', 'Reviewed head SHA'), ]; - for (const mutation of mutations) { - expect(() => assertReviewerContract(mutation)).toThrow(); + for (const [index, mutation] of mutations.entries()) { + expect(() => assertReviewerContract(mutation), `source mutation ${index}`).toThrow(); } }); @@ -546,11 +604,19 @@ describe('gh-aw enforcing Squad reviewer', () => { const mutations = [ REVIEWER.replace('await guard.enforceReviewOutputs', 'void guard.enforceReviewOutputs'), REVIEWER.replace('await guard.assertClearingReview', 'void guard.assertClearingReview'), - REVIEWER.replace(' name: Squad Review / review', ' name: Other check'), + REVIEWER.replace(' name: Squad Review Authority / attest', ' name: Other check'), REVIEWER.replace('pathToFileURL(baseGuard)', "pathToFileURL('.squad-review-workflow/guard.mjs')"), REVIEWER.replace('No trusted Squad verdict was emitted.', 'Squad-Review-Verdict: trusted'), REVIEWER.replace(' if: always()\n', ' if: success()\n'), REVIEWER.replace(' needs: [agent, safe_outputs]', ' needs: [agent]'), + REVIEWER.replace( + "run.event !== 'pull_request_target'", + "run.event !== 'pull_request'", + ), + REVIEWER.replace( + "uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0", + "uses: ./.github/actions/pr-controlled", + ), ]; for (const mutation of mutations) { expect(mutation).not.toBe(REVIEWER); diff --git a/workflows/package/squad-review.md b/workflows/package/squad-review.md index 26eba8df9..0e20310f3 100644 --- a/workflows/package/squad-review.md +++ b/workflows/package/squad-review.md @@ -4,14 +4,16 @@ run-name: "Squad review — PR #${{ github.event.pull_request.number }}" description: Independently reviews agent-authored pull requests without editing or remediating private: false inlined-imports: true +strict: false on: - pull_request: + pull_request_target: types: - opened - reopened - ready_for_review - synchronize if: github.event.pull_request.head.repo.full_name == github.repository +checkout: false permissions: contents: read copilot-requests: write @@ -25,7 +27,6 @@ network: allowed: - defaults tools: - bash: true github: min-integrity: approved mode: gh-proxy @@ -47,6 +48,7 @@ safe-outputs: GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }} SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: script: | const { existsSync } = require('node:fs'); @@ -78,7 +80,7 @@ safe-outputs: commit-id: ${{ github.event.pull_request.head.sha }} jobs: review: - name: Squad Review / review + name: Squad Review Authority / attest if: always() needs: - agent @@ -109,6 +111,7 @@ jobs: env: SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: script: | const { existsSync } = require('node:fs'); @@ -125,6 +128,116 @@ jobs: const guard = await import(pathToFileURL(baseGuard).href); await guard.assertClearingReview(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data); + publish: + name: Publish Squad Review required check + if: always() + needs: + - agent + - safe_outputs + - review + runs-on: ubuntu-latest + permissions: + actions: read + checks: write + contents: read + pull-requests: read + steps: + - name: Publish exact-head required check + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 + env: + AUTHORITY_RESULT: ${{ needs.review.result }} + SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} + SQUAD_REVIEW_BASE: ${{ github.event.pull_request.base.sha }} + SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} + with: + script: | + const checkName = 'Squad Review / review'; + const authorityJob = 'Squad Review Authority / attest'; + const repository = process.env.GITHUB_REPOSITORY; + const [owner, repo] = repository.split('/'); + const pullRequest = Number(process.env.SQUAD_REVIEW_PR); + const baseSha = process.env.SQUAD_REVIEW_BASE; + const headSha = process.env.SQUAD_REVIEW_HEAD; + const workflowSha = process.env.SQUAD_REVIEW_WORKFLOW_SHA; + const runId = Number(process.env.GITHUB_RUN_ID); + const runAttempt = Number(process.env.GITHUB_RUN_ATTEMPT); + if (!Number.isSafeInteger(pullRequest) || pullRequest < 1 || + !/^[0-9a-f]{40}$/.test(baseSha) || !/^[0-9a-f]{40}$/.test(headSha) || + workflowSha !== baseSha || !Number.isSafeInteger(runId) || runId < 1 || + !Number.isSafeInteger(runAttempt) || runAttempt < 1) { + core.setFailed('Invalid base-controlled Squad review check context.'); + return; + } + const run = (await github.rest.actions.getWorkflowRun({ + owner, repo, run_id: runId, + })).data; + if (run.event !== 'pull_request_target' || + run.path !== '.github/workflows/squad-review.lock.yml' || + run.head_sha !== workflowSha || + run.repository.full_name !== repository) { + core.setFailed('Squad review check is not bound to the base-controlled workflow run.'); + return; + } + const jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRunAttempt, { + owner, repo, run_id: runId, attempt_number: runAttempt, per_page: 100, + }); + const authorityJobs = jobs.filter(job => job.name === authorityJob); + if (authorityJobs.length !== 1) { + core.setFailed('Missing or duplicate base-controlled Squad review authority job.'); + return; + } + const succeeded = process.env.AUTHORITY_RESULT === 'success' && + authorityJobs[0].conclusion === 'success'; + const externalId = + `squad-review-authority/v1:${repository}:${pullRequest}:${baseSha}:${headSha}`; + const existing = await github.paginate(github.rest.checks.listForRef, { + owner, repo, ref: headSha, check_name: checkName, per_page: 100, + }); + const owned = existing.filter(check => check.external_id === externalId); + if (owned.length > 1) { + core.setFailed('Duplicate exact-head Squad review authority checks.'); + return; + } + const detailsUrl = + `${process.env.GITHUB_SERVER_URL}/${repository}/actions/runs/${runId}`; + const output = { + title: succeeded + ? 'Base-controlled Squad review passed' + : 'Base-controlled Squad review did not pass', + summary: JSON.stringify({ + schema: 'squad-review-check/v1', + repository, + pull_request: pullRequest, + base_sha: baseSha, + head_sha: headSha, + workflow_sha: workflowSha, + run_id: runId, + run_attempt: runAttempt, + event: 'pull_request_target', + workflow_path: '.github/workflows/squad-review.lock.yml', + authority_job: authorityJob, + }), + }; + const request = { + owner, repo, name: checkName, head_sha: headSha, + status: 'completed', + conclusion: succeeded ? 'success' : 'failure', + details_url: detailsUrl, + external_id: externalId, + output, + }; + if (owned.length === 1) { + await github.rest.checks.update({ + ...request, + check_run_id: owned[0].id, + }); + } else { + await github.rest.checks.create(request); + } + if (!succeeded) { + core.setFailed('Base-controlled Squad review authority did not succeed.'); + } --- @@ -149,7 +262,10 @@ this workflow. `${{ github.repository }}`. Forks and any event other than `opened`, `reopened`, `ready_for_review` or `synchronize` are refused with `noop`. -This workflow has no `workflow_dispatch` trigger. `/squad review` is an operator +This base-controlled `pull_request_target` workflow has no `workflow_dispatch` +trigger and never checks out or executes pull request content. The agent reads +the pull request diff and repository evidence only through GitHub APIs. +`/squad review` is an operator aid that points to GitHub's **Re-run jobs** action for the existing automatic run. Never execute reviewer code, guards, manifests, or safe-output handlers from a manually selected ref. @@ -161,15 +277,17 @@ Read `.squad-review.json` at the exact PR head SHA and the committed `persistent_name` entries in that registry, and must differ. Act as that `reviewer_agent`, reading its base-commit charter. Missing or malformed attribution is a refusal, never a fallback to a display name or GitHub login. -The deterministic output guard and final job repeat these checks. A refusal, -missing verdict, stale head, or malformed provenance cannot clear the required -`Squad Review / review` check. +The deterministic output guard and authority job repeat these checks. The +publisher creates `Squad Review / review` on the exact PR head only after the +native `Squad Review Authority / attest` job in the same base-controlled run +succeeds. A refusal, missing verdict, stale head, malformed provenance, or +same-named PR-controlled check cannot clear the authority contract. The workflow-installation PR is an explicit human trust boundary. Its base does -not contain the Squad guard or manifest, so no code, job name, check result, or -review record emitted by that PR is a trusted Squad verdict. The loader refuses -workflow-source fallback and emits no `Squad-Review-Verdict:` record. Merge the -installation only through explicit human review of the generated package. +not contain this workflow, guard, or manifest, so no trusted automatic Squad +review runs. No code, job name, check result, or review record emitted by that +PR is a trusted Squad verdict. Merge the installation only through explicit +human review of the generated package. Trusted review starts on the automatic post-merge Cast PR. The guard is then loaded only from the exact PR base commit, where the installed manifest also @@ -223,9 +341,11 @@ machine-readable review marker is a standalone final line: If an existing bot review contains a `Squad-Review-Verdict:` record for the current head SHA and this exact workflow run ID and attempt, call `noop` and stop. Evidence from a different run or attempt cannot deduplicate or clear this -run. The deterministic gate validates the event, workflow path, PR, base, head, -run, attempt, and GitHub Actions bot identity; an arbitrary comment or the -legacy head marker is not clearing evidence. Re-fetch the pull request +run. The deterministic gate validates the `pull_request_target` event, immutable +workflow SHA, workflow path, PR, base, head, run, attempt, native authority job, +exact-head published check, and GitHub Actions App/bot identity; an arbitrary +comment, PR-controlled workflow, same-named check, or legacy head marker is not +clearing evidence. Re-fetch the pull request immediately before emitting outputs; if its head SHA changed, call `noop` and let the newer run review it. diff --git a/workflows/package/squad.md b/workflows/package/squad.md index 7623c0e6c..411000183 100644 --- a/workflows/package/squad.md +++ b/workflows/package/squad.md @@ -2238,11 +2238,17 @@ post one `add-comment` explaining that `/squad review` must target a pull request, then stop. List workflow runs for `.github/workflows/squad-review.lock.yml`. Keep only -`pull_request` runs associated with this pull request and exact current head -SHA. Select the newest run by creation time, breaking ties by numeric run ID, -then fetch its jobs and require exactly one job named `Squad Review / review`. -If no matching run or check exists, emit exactly one `add-comment` stating that -no automatic review run exists for the exact head and that a new PR event +`pull_request_target` runs associated with this pull request whose workflow +head SHA equals the pull request's exact base SHA. Select the newest run by +creation time, breaking ties by numeric run ID, then fetch its jobs and require +exactly one job named `Squad Review Authority / attest`. Also fetch check runs +for the exact current PR head and require exactly one `Squad Review / review` +check whose external ID, details URL, GitHub Actions App identity, and +`squad-review-check/v1` summary bind that base-controlled run, PR, base SHA, +head SHA, run ID, and attempt. A same-named check without that binding is +advisory only. If no matching run or authority check exists, emit exactly one +`add-comment` stating that no base-controlled automatic review run exists for +the exact head and that a new PR event (`synchronize`, reopen, or ready-for-review) is required. Stop without implying that a rerun occurred. @@ -2251,9 +2257,10 @@ selected run URL, run ID, attempt, status, conclusion, exact head SHA, and this instruction: > Squad Review is automatic and cannot be dispatched from a branch. In the -> selected automatic run, open `Squad Review / review` and choose **Re-run -> jobs**. This command did not rerun it. Only the new attempt of that exact -> `pull_request` run can publish verdict evidence for PR #{pull-request-number} +> selected base-controlled automatic run, choose **Re-run all jobs**. This +> command did not rerun it. Only the new attempt of that exact +> `pull_request_target` run can publish verdict evidence and the exact-head +> `Squad Review / review` check for PR #{pull-request-number} > at head `{current-head-sha}`. Do not review the diff in this router, emit a verdict, edit files, create an diff --git a/workflows/shared/squad-review-guard.mjs b/workflows/shared/squad-review-guard.mjs index f11878742..d2a97a76d 100644 --- a/workflows/shared/squad-review-guard.mjs +++ b/workflows/shared/squad-review-guard.mjs @@ -5,11 +5,16 @@ export const CHECK_NAME = 'Squad Review / review'; export const VERDICT_PREFIX = 'Squad-Review-Verdict: '; export const OVERRIDE_PREFIX = 'Squad-Review-Override: '; const WORKFLOW = '.github/workflows/squad-review.lock.yml'; +const AUTHORITY_JOB = 'Squad Review Authority / attest'; +const CHECK_SCHEMA = 'squad-review-check/v1'; +const CHECK_EXTERNAL_ID = 'squad-review-authority/v1'; const BOOTSTRAP_WORKFLOW = '.github/workflows/squad-bootstrap.lock.yml'; const SHA = /^[0-9a-f]{40}$/; const ID = /^[a-z][a-z0-9-]*$/; const BOT = 'github-actions[bot]'; const BOT_ID = 41898282; +const ACTIONS_APP_ID = 15368; +const ACTIONS_APP_SLUG = 'github-actions'; const BOOTSTRAP_BRANCH = 'squad/bootstrap-cast'; const BOOTSTRAP_TITLE = '[squad] Cast your Squad'; const BOOTSTRAP_AUTHOR = '@squad/base-controlled-bootstrap'; @@ -64,7 +69,7 @@ export function validateVerdict(value, expected, review, now = Date.now()) { requireThat(exactKeys(value, [ 'schema', 'repository', 'pull_request', 'base_sha', 'head_sha', 'author_agent', 'reviewer_agent', 'result', 'timestamp', 'run_id', 'run_attempt', 'event', - 'workflow_path', + 'workflow_path', 'workflow_sha', ]) && value.schema === 'squad-review-verdict/v1', 'invalid verdict shape'); for (const key of [ 'repository', 'pull_request', 'base_sha', 'head_sha', 'author_agent', 'reviewer_agent', @@ -75,9 +80,11 @@ export function validateVerdict(value, expected, review, now = Date.now()) { value.author_agent !== value.reviewer_agent, 'invalid SHA or self review'); requireThat(['COMMENT', 'REQUEST_CHANGES'].includes(value.result) && - value.event === 'pull_request' && Number.isSafeInteger(value.run_id) && value.run_id > 0 && + value.event === 'pull_request_target' && + Number.isSafeInteger(value.run_id) && value.run_id > 0 && Number.isSafeInteger(value.run_attempt) && value.run_attempt > 0 && - value.workflow_path === WORKFLOW, 'invalid verdict result or run'); + value.workflow_path === WORKFLOW && value.workflow_sha === expected.workflow_sha, + 'invalid verdict result or run'); requireThat(review.user?.login === BOT && review.user?.id === BOT_ID && review.user?.type === 'Bot' && review.commit_id === value.head_sha && review.state === 'COMMENTED', @@ -212,11 +219,17 @@ export async function reviewTarget( requireThat(typeof repository === 'string' && /^[\w.-]+\/[\w.-]+$/.test(repository) && /^[1-9]\d*$/.test(env.SQUAD_REVIEW_PR ?? '') && Number.isSafeInteger(number), 'invalid target'); const pr = await get(`repos/${repository}/pulls/${number}`); + const repo = await get(`repos/${repository}`); requireThat(pr.number === number && pr.head?.repo?.full_name === repository && pr.base?.repo?.full_name === repository && SHA.test(pr.head.sha) && SHA.test(pr.base.sha), 'foreign repository or invalid PR'); + requireThat(repo?.full_name === repository && typeof repo.default_branch === 'string' && + pr.base.ref === repo.default_branch, 'review target must use the repository default branch'); requireThat(SHA.test(env.SQUAD_REVIEW_HEAD ?? '') && pr.head.sha === env.SQUAD_REVIEW_HEAD, 'PR head changed or expected SHA missing'); + requireThat(SHA.test(env.SQUAD_REVIEW_WORKFLOW_SHA ?? '') && + env.SQUAD_REVIEW_WORKFLOW_SHA === pr.base.sha, + 'workflow source is not the exact PR base commit'); requireThat(relay ? pr.merged === true && pr.state === 'closed' && pr.base.ref === env.SQUAD_REVIEW_DEFAULT_BRANCH @@ -239,7 +252,7 @@ export async function reviewTarget( ); let attribution; if (value === undefined) { - requireThat(relay === false && env.GITHUB_EVENT_NAME === 'pull_request', + requireThat(relay === false && env.GITHUB_EVENT_NAME === 'pull_request_target', 'missing committed attribution outside base-controlled bootstrap activation'); attribution = await validateBootstrapAttribution( get, @@ -258,6 +271,7 @@ export async function reviewTarget( } return { repository, pull_request: number, base_sha: pr.base.sha, head_sha: pr.head.sha, + workflow_sha: env.SQUAD_REVIEW_WORKFLOW_SHA, author_agent: attribution.author_agent, reviewer_agent: attribution.reviewer_agent, pr, }; } @@ -272,7 +286,8 @@ async function currentEvidence(target, get) { } export async function enforceReviewOutputs(env, get, options = {}) { - requireThat(env.GITHUB_EVENT_NAME === 'pull_request', 'only PR runs can emit review output'); + requireThat(env.GITHUB_EVENT_NAME === 'pull_request_target', + 'only base-controlled PR target runs can emit review output'); const target = await reviewTarget(env, get, options); const output = JSON.parse(readFileSync(env.GH_AW_AGENT_OUTPUT, 'utf8')); requireThat(Array.isArray(output.items), 'missing safe-output items'); @@ -305,8 +320,9 @@ export async function enforceReviewOutputs(env, get, options = {}) { timestamp: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'), run_id: Number(env.GITHUB_RUN_ID), run_attempt: Number(env.GITHUB_RUN_ATTEMPT), - event: 'pull_request', + event: 'pull_request_target', workflow_path: WORKFLOW, + workflow_sha: target.workflow_sha, }; requireThat(Number.isSafeInteger(value.run_id) && value.run_id > 0 && Number.isSafeInteger(value.run_attempt) && value.run_attempt > 0, 'invalid workflow identity'); @@ -321,7 +337,8 @@ export async function enforceReviewOutputs(env, get, options = {}) { export async function assertClearingReview(env, get, options = {}) { const { relay = false } = options; - requireThat(env.GITHUB_EVENT_NAME === 'pull_request', 'only PR runs can clear review'); + requireThat(env.GITHUB_EVENT_NAME === 'pull_request_target', + 'only base-controlled PR target runs can clear review'); const target = await reviewTarget(env, get, { ...options, requireBootstrapRunSuccess: true, @@ -342,8 +359,8 @@ export async function assertClearingReview(env, get, options = {}) { const { review, verdict } = bound[0]; const cutoff = relay ? timestamp(target.pr.merged_at) : Date.now(); const run = await get(`repos/${target.repository}/actions/runs/${verdict.run_id}`); - requireThat(run.event === 'pull_request' && run.path === WORKFLOW && - run.repository?.full_name === target.repository && run.head_sha === target.head_sha && + requireThat(run.event === 'pull_request_target' && run.path === WORKFLOW && + run.repository?.full_name === target.repository && run.head_sha === target.workflow_sha && run.run_attempt >= verdict.run_attempt && run.display_title === `Squad review \u2014 PR #${target.pull_request}` && Array.isArray(run.pull_requests) && @@ -352,9 +369,9 @@ export async function assertClearingReview(env, get, options = {}) { 'verdict is not bound to this PR workflow run'); const attempt = run.run_attempt === verdict.run_attempt ? run : await get(`repos/${target.repository}/actions/runs/${verdict.run_id}/attempts/${verdict.run_attempt}`); - requireThat(attempt.event === 'pull_request' && attempt.path === WORKFLOW && + requireThat(attempt.event === 'pull_request_target' && attempt.path === WORKFLOW && attempt.repository?.full_name === target.repository && - attempt.head_sha === target.head_sha && + attempt.head_sha === target.workflow_sha && attempt.run_attempt === verdict.run_attempt && timestamp(attempt.run_started_at) <= timestamp(verdict.timestamp) && (attempt.status !== 'completed' || @@ -363,9 +380,36 @@ export async function assertClearingReview(env, get, options = {}) { requireThat(run.status === 'completed' && run.conclusion === 'success', 'review run did not succeed'); const jobs = await list(get, `repos/${target.repository}/actions/runs/${verdict.run_id}/attempts/${run.run_attempt}/jobs`, 'jobs'); - const checks = jobs.filter(job => job.name === CHECK_NAME); - requireThat(checks.length === 1 && checks[0].conclusion === 'success' && - timestamp(checks[0].completed_at) <= cutoff, 'required review check did not pass before merge'); + const authorityJobs = jobs.filter(job => job.name === AUTHORITY_JOB); + requireThat(authorityJobs.length === 1 && authorityJobs[0].conclusion === 'success' && + timestamp(authorityJobs[0].completed_at) <= cutoff, + 'base-controlled review authority job did not pass before merge'); + const checkRuns = await list(get, + `repos/${target.repository}/commits/${target.head_sha}/check-runs`, 'check_runs'); + const externalId = + `${CHECK_EXTERNAL_ID}:${target.repository}:${target.pull_request}:${target.base_sha}:${target.head_sha}`; + const checks = checkRuns.filter(check => check.name === CHECK_NAME && + check.external_id === externalId); + requireThat(checks.length === 1, 'missing or duplicate exact-head authority check'); + const check = checks[0]; + requireThat(check.head_sha === target.head_sha && check.status === 'completed' && + check.conclusion === 'success' && check.app?.id === ACTIONS_APP_ID && + check.app?.slug === ACTIONS_APP_SLUG && + check.details_url === + `${env.GITHUB_SERVER_URL ?? 'https://github.com'}/${target.repository}/actions/runs/${verdict.run_id}`, + 'required review check is not attributable to GitHub Actions authority'); + const summary = JSON.parse(check.output?.summary ?? ''); + requireThat(exactKeys(summary, [ + 'schema', 'repository', 'pull_request', 'base_sha', 'head_sha', 'workflow_sha', + 'run_id', 'run_attempt', 'event', 'workflow_path', 'authority_job', + ]) && summary.schema === CHECK_SCHEMA && summary.repository === target.repository && + summary.pull_request === target.pull_request && summary.base_sha === target.base_sha && + summary.head_sha === target.head_sha && summary.workflow_sha === target.workflow_sha && + summary.run_id === verdict.run_id && summary.run_attempt === run.run_attempt && + summary.event === 'pull_request_target' && summary.workflow_path === WORKFLOW && + summary.authority_job === AUTHORITY_JOB && + timestamp(check.completed_at) <= cutoff, + 'required review check attestation is invalid'); } if (verdict.result === 'REQUEST_CHANGES') { const comments = await list(get, `repos/${target.repository}/issues/${target.pull_request}/comments`); diff --git a/workflows/squad-review.md b/workflows/squad-review.md index 96f8f02bb..7b7bed358 100644 --- a/workflows/squad-review.md +++ b/workflows/squad-review.md @@ -4,10 +4,12 @@ run-name: "Squad review — PR #${{ github.event.pull_request.number }}" description: Independently reviews agent-authored pull requests without editing or remediating private: false inlined-imports: true +strict: false on: - pull_request: + pull_request_target: types: [opened, reopened, ready_for_review, synchronize] if: github.event.pull_request.head.repo.full_name == github.repository +checkout: false permissions: contents: read copilot-requests: write @@ -21,7 +23,6 @@ network: allowed: - defaults tools: - bash: true github: min-integrity: approved mode: gh-proxy @@ -42,6 +43,7 @@ safe-outputs: GH_AW_AGENT_OUTPUT: ${{ steps.setup-agent-output-env.outputs.GH_AW_AGENT_OUTPUT }} SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: script: | const { existsSync } = require('node:fs'); @@ -71,7 +73,7 @@ safe-outputs: commit-id: "${{ github.event.pull_request.head.sha }}" jobs: review: - name: Squad Review / review + name: Squad Review Authority / attest if: always() needs: [agent, safe_outputs] runs-on: ubuntu-latest @@ -100,6 +102,7 @@ jobs: env: SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: script: | const { existsSync } = require('node:fs'); @@ -116,6 +119,113 @@ jobs: const guard = await import(pathToFileURL(baseGuard).href); await guard.assertClearingReview(process.env, async (route, fields) => (await github.request(`GET /${route}`, fields)).data); + publish: + name: Publish Squad Review required check + if: always() + needs: [agent, safe_outputs, review] + runs-on: ubuntu-latest + permissions: + actions: read + checks: write + contents: read + pull-requests: read + steps: + - name: Publish exact-head required check + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + AUTHORITY_RESULT: ${{ needs.review.result }} + SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} + SQUAD_REVIEW_BASE: ${{ github.event.pull_request.base.sha }} + SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} + SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} + with: + script: | + const checkName = 'Squad Review / review'; + const authorityJob = 'Squad Review Authority / attest'; + const repository = process.env.GITHUB_REPOSITORY; + const [owner, repo] = repository.split('/'); + const pullRequest = Number(process.env.SQUAD_REVIEW_PR); + const baseSha = process.env.SQUAD_REVIEW_BASE; + const headSha = process.env.SQUAD_REVIEW_HEAD; + const workflowSha = process.env.SQUAD_REVIEW_WORKFLOW_SHA; + const runId = Number(process.env.GITHUB_RUN_ID); + const runAttempt = Number(process.env.GITHUB_RUN_ATTEMPT); + if (!Number.isSafeInteger(pullRequest) || pullRequest < 1 || + !/^[0-9a-f]{40}$/.test(baseSha) || !/^[0-9a-f]{40}$/.test(headSha) || + workflowSha !== baseSha || !Number.isSafeInteger(runId) || runId < 1 || + !Number.isSafeInteger(runAttempt) || runAttempt < 1) { + core.setFailed('Invalid base-controlled Squad review check context.'); + return; + } + const run = (await github.rest.actions.getWorkflowRun({ + owner, repo, run_id: runId, + })).data; + if (run.event !== 'pull_request_target' || + run.path !== '.github/workflows/squad-review.lock.yml' || + run.head_sha !== workflowSha || + run.repository.full_name !== repository) { + core.setFailed('Squad review check is not bound to the base-controlled workflow run.'); + return; + } + const jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRunAttempt, { + owner, repo, run_id: runId, attempt_number: runAttempt, per_page: 100, + }); + const authorityJobs = jobs.filter(job => job.name === authorityJob); + if (authorityJobs.length !== 1) { + core.setFailed('Missing or duplicate base-controlled Squad review authority job.'); + return; + } + const succeeded = process.env.AUTHORITY_RESULT === 'success' && + authorityJobs[0].conclusion === 'success'; + const externalId = + `squad-review-authority/v1:${repository}:${pullRequest}:${baseSha}:${headSha}`; + const existing = await github.paginate(github.rest.checks.listForRef, { + owner, repo, ref: headSha, check_name: checkName, per_page: 100, + }); + const owned = existing.filter(check => check.external_id === externalId); + if (owned.length > 1) { + core.setFailed('Duplicate exact-head Squad review authority checks.'); + return; + } + const detailsUrl = + `${process.env.GITHUB_SERVER_URL}/${repository}/actions/runs/${runId}`; + const output = { + title: succeeded + ? 'Base-controlled Squad review passed' + : 'Base-controlled Squad review did not pass', + summary: JSON.stringify({ + schema: 'squad-review-check/v1', + repository, + pull_request: pullRequest, + base_sha: baseSha, + head_sha: headSha, + workflow_sha: workflowSha, + run_id: runId, + run_attempt: runAttempt, + event: 'pull_request_target', + workflow_path: '.github/workflows/squad-review.lock.yml', + authority_job: authorityJob, + }), + }; + const request = { + owner, repo, name: checkName, head_sha: headSha, + status: 'completed', + conclusion: succeeded ? 'success' : 'failure', + details_url: detailsUrl, + external_id: externalId, + output, + }; + if (owned.length === 1) { + await github.rest.checks.update({ + ...request, + check_run_id: owned[0].id, + }); + } else { + await github.rest.checks.create(request); + } + if (!succeeded) { + core.setFailed('Base-controlled Squad review authority did not succeed.'); + } --- # Squad Review @@ -139,7 +249,10 @@ this workflow. `${{ github.repository }}`. Forks and any event other than `opened`, `reopened`, `ready_for_review` or `synchronize` are refused with `noop`. -This workflow has no `workflow_dispatch` trigger. `/squad review` is an operator +This base-controlled `pull_request_target` workflow has no `workflow_dispatch` +trigger and never checks out or executes pull request content. The agent reads +the pull request diff and repository evidence only through GitHub APIs. +`/squad review` is an operator aid that points to GitHub's **Re-run jobs** action for the existing automatic run. Never execute reviewer code, guards, manifests, or safe-output handlers from a manually selected ref. @@ -151,15 +264,17 @@ Read `.squad-review.json` at the exact PR head SHA and the committed `persistent_name` entries in that registry, and must differ. Act as that `reviewer_agent`, reading its base-commit charter. Missing or malformed attribution is a refusal, never a fallback to a display name or GitHub login. -The deterministic output guard and final job repeat these checks. A refusal, -missing verdict, stale head, or malformed provenance cannot clear the required -`Squad Review / review` check. +The deterministic output guard and authority job repeat these checks. The +publisher creates `Squad Review / review` on the exact PR head only after the +native `Squad Review Authority / attest` job in the same base-controlled run +succeeds. A refusal, missing verdict, stale head, malformed provenance, or +same-named PR-controlled check cannot clear the authority contract. The workflow-installation PR is an explicit human trust boundary. Its base does -not contain the Squad guard or manifest, so no code, job name, check result, or -review record emitted by that PR is a trusted Squad verdict. The loader refuses -workflow-source fallback and emits no `Squad-Review-Verdict:` record. Merge the -installation only through explicit human review of the generated package. +not contain this workflow, guard, or manifest, so no trusted automatic Squad +review runs. No code, job name, check result, or review record emitted by that +PR is a trusted Squad verdict. Merge the installation only through explicit +human review of the generated package. Trusted review starts on the automatic post-merge Cast PR. The guard is then loaded only from the exact PR base commit, where the installed manifest also @@ -213,9 +328,11 @@ machine-readable review marker is a standalone final line: If an existing bot review contains a `Squad-Review-Verdict:` record for the current head SHA and this exact workflow run ID and attempt, call `noop` and stop. Evidence from a different run or attempt cannot deduplicate or clear this -run. The deterministic gate validates the event, workflow path, PR, base, head, -run, attempt, and GitHub Actions bot identity; an arbitrary comment or the -legacy head marker is not clearing evidence. Re-fetch the pull request +run. The deterministic gate validates the `pull_request_target` event, immutable +workflow SHA, workflow path, PR, base, head, run, attempt, native authority job, +exact-head published check, and GitHub Actions App/bot identity; an arbitrary +comment, PR-controlled workflow, same-named check, or legacy head marker is not +clearing evidence. Re-fetch the pull request immediately before emitting outputs; if its head SHA changed, call `noop` and let the newer run review it. diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 2fa5be42a..d466d8352 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -14,8 +14,8 @@ "source": "workflows/package/squad.md", "destination": ".github/workflows/squad.md", "lock": ".github/workflows/squad.lock.yml", - "source_sha256": "68110664fa20d4efbee19fd75bb8f2406f1cbfcb1df3dddeb2419251a5355d17", - "lock_sha256": "2195655666fb474ba57d8729aef822b77e501e35deebb96b3d121875311eeaa5" + "source_sha256": "bb7f231c852dfb73c5d1a6ba5e9f23f9f7c9fc5af9e1f1021c4c5213fd9389f9", + "lock_sha256": "f2e62f0ded2b937c99dcdab321f1ea2f886ff2f0537a324af4342908466a2bcf" }, { "name": "squad-implement-worker", @@ -30,8 +30,8 @@ "source": "workflows/package/squad-review.md", "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", - "source_sha256": "8ffefbf5b0b16b0623612446790bb3e0ca7c9b89de674e81b7e95ac9e008c0fd", - "lock_sha256": "5d0ee03e894805eb63aaa8258ddc447f3e734d2d8a18ff3f89a12d418a722b90" + "source_sha256": "50194fc024e745a4eb432553ceaeab9cde7621bf368984a9c4b03364017a3ae2", + "lock_sha256": "b1a16520aff0409507dd420433a56570b37b993688decd4ef5479c3e8e6d5ab9" }, { "name": "squad-deps-worker", @@ -81,7 +81,7 @@ "package_destination": ".github/workflows/shared/squad-review-guard.mjs", "destination": ".github/workflows/shared/squad-review-guard.mjs", "ownership": "manifest", - "sha256": "2a18ddd8a57c255e966ad2a1baa211f7d07277b1b4a15738a8dfb1211a67e18a" + "sha256": "541ff7d4add94a81b2d1333327933fc96ea99783e5e5efe571f6e9840c866c7f" }, { "path": "shared/squad-install-verifier.mjs", diff --git a/workflows/squad.md b/workflows/squad.md index 42830e74e..f5c43b20d 100644 --- a/workflows/squad.md +++ b/workflows/squad.md @@ -1135,11 +1135,17 @@ post one `add-comment` explaining that `/squad review` must target a pull request, then stop. List workflow runs for `.github/workflows/squad-review.lock.yml`. Keep only -`pull_request` runs associated with this pull request and exact current head -SHA. Select the newest run by creation time, breaking ties by numeric run ID, -then fetch its jobs and require exactly one job named `Squad Review / review`. -If no matching run or check exists, emit exactly one `add-comment` stating that -no automatic review run exists for the exact head and that a new PR event +`pull_request_target` runs associated with this pull request whose workflow +head SHA equals the pull request's exact base SHA. Select the newest run by +creation time, breaking ties by numeric run ID, then fetch its jobs and require +exactly one job named `Squad Review Authority / attest`. Also fetch check runs +for the exact current PR head and require exactly one `Squad Review / review` +check whose external ID, details URL, GitHub Actions App identity, and +`squad-review-check/v1` summary bind that base-controlled run, PR, base SHA, +head SHA, run ID, and attempt. A same-named check without that binding is +advisory only. If no matching run or authority check exists, emit exactly one +`add-comment` stating that no base-controlled automatic review run exists for +the exact head and that a new PR event (`synchronize`, reopen, or ready-for-review) is required. Stop without implying that a rerun occurred. @@ -1148,9 +1154,10 @@ selected run URL, run ID, attempt, status, conclusion, exact head SHA, and this instruction: > Squad Review is automatic and cannot be dispatched from a branch. In the -> selected automatic run, open `Squad Review / review` and choose **Re-run -> jobs**. This command did not rerun it. Only the new attempt of that exact -> `pull_request` run can publish verdict evidence for PR #{pull-request-number} +> selected base-controlled automatic run, choose **Re-run all jobs**. This +> command did not rerun it. Only the new attempt of that exact +> `pull_request_target` run can publish verdict evidence and the exact-head +> `Squad Review / review` check for PR #{pull-request-number} > at head `{current-head-sha}`. Do not review the diff in this router, emit a verdict, edit files, create an From 57dbc69fda2e394ddb83286c44d4ac10805a0382 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 21:54:39 -0700 Subject: [PATCH 08/14] test(gh-aw): expose installed lock digest mismatch Part of #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- workflows/package/squad-bootstrap.md | 2 +- workflows/shared/squad-install-verifier.mjs | 7 +++++-- workflows/squad-bootstrap.md | 2 +- workflows/squad-workflows.manifest.json | 6 +++--- 4 files changed, 10 insertions(+), 7 deletions(-) diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index 1bb570e84..0ef7eceef 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -151,7 +151,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "f30d7f84f0dae50ae1beafccf9566df3457ab400c75f639ac029cdb637e6c1cb" + check_hash "$install_verifier" "47b911d3d56821bf8c2f3345ca4394786212cf11d8ed0078ba45324a42e8ec3e" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/shared/squad-install-verifier.mjs b/workflows/shared/squad-install-verifier.mjs index 19b485bd6..0742369e1 100644 --- a/workflows/shared/squad-install-verifier.mjs +++ b/workflows/shared/squad-install-verifier.mjs @@ -651,8 +651,11 @@ function verifyInstalledBytes(root, contract, revision) { for (const entry of contract.workflows) readRequired(root, entry.lock); for (const entry of contract.workflows) { const normalized = normalizeCompiledLock(readRequired(root, entry.lock), revision); - if (sha256(normalized) !== entry.lock_sha256) { - throw new Error(`Installed digest mismatch for ${entry.lock}.`); + const observedDigest = sha256(normalized); + if (observedDigest !== entry.lock_sha256) { + throw new Error( + `Installed digest mismatch for ${entry.lock}: expected ${entry.lock_sha256}, observed ${observedDigest}.`, + ); } } } diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index 60205aab5..76c14c9ef 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -158,7 +158,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "f30d7f84f0dae50ae1beafccf9566df3457ab400c75f639ac029cdb637e6c1cb" + check_hash "$install_verifier" "47b911d3d56821bf8c2f3345ca4394786212cf11d8ed0078ba45324a42e8ec3e" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index d466d8352..3f851cdc1 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -62,8 +62,8 @@ "source": "workflows/package/squad-bootstrap.md", "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", - "source_sha256": "31628b7c0e22760b96c55bcb66c6fbf509a7ff22c3836cd94e75245b401179fc", - "lock_sha256": "dea141934a5b9df12629ce08679a262eed953a75cad270c83d5e85c111bf8917" + "source_sha256": "88d6b77f3fbba2742a87c71a508bfab279d6615ac2ce92d9a5a834562df83e97", + "lock_sha256": "1aa405862591145c15c152813127d473f6cbb4d3eddf3d0733c5299001520afe" }, { "name": "squad-command-router", @@ -89,7 +89,7 @@ "package_destination": ".github/workflows/shared/squad-install-verifier.mjs", "destination": ".github/workflows/shared/squad-install-verifier.mjs", "ownership": "manifest", - "sha256": "f30d7f84f0dae50ae1beafccf9566df3457ab400c75f639ac029cdb637e6c1cb" + "sha256": "47b911d3d56821bf8c2f3345ca4394786212cf11d8ed0078ba45324a42e8ec3e" }, { "path": "shared/squad-command-contract.mjs", From b34f9523544c7fd9e50af75469bc03ac87882a4f Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 22:33:33 -0700 Subject: [PATCH 09/14] fix(gh-aw): dedicate review check identity Part of #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/agents.md | 5 +- .../skills/gh-aw-enlistment/SKILL.md | 46 ++++-- docs/src/content/docs/guide/gh-aw.md | 67 +++++++-- .../skills/gh-aw-enlistment/SKILL.md | 46 ++++-- .../skills/gh-aw-enlistment/SKILL.md | 46 ++++-- scripts/gh-aw-hosted-e2e.mjs | 125 +++++++++++++++- templates/skills/gh-aw-enlistment/SKILL.md | 46 ++++-- test/gh-aw-enlistment-skill.test.ts | 3 +- test/gh-aw-hosted-e2e.test.ts | 93 +++++++++++- test/gh-aw-review-guard.test.ts | 47 +++++- test/gh-aw-review-workflow.test.ts | 135 +++++++++++++++++- test/standalone-release-workflow.test.ts | 2 + workflows/package/squad-bootstrap.md | 2 +- workflows/package/squad-review.md | 62 ++++++-- workflows/shared/squad-install-verifier.mjs | 17 +++ workflows/shared/squad-review-guard.mjs | 19 ++- workflows/skills/gh-aw-enlistment/SKILL.md | 46 ++++-- workflows/squad-bootstrap.md | 2 +- workflows/squad-review.md | 62 ++++++-- workflows/squad-workflows.manifest.json | 14 +- 20 files changed, 777 insertions(+), 108 deletions(-) diff --git a/.github/agents.md b/.github/agents.md index 3d1d6ee5e..44593c3ab 100644 --- a/.github/agents.md +++ b/.github/agents.md @@ -37,7 +37,10 @@ GitHub Agentic Workflows (`gh-aw`) are composable AI workflows triggered by slas > cannot mint a trusted Squad verdict. After merge, require the automatically > opened Cast PR to pass the exact-head `Squad Review / review` attestation from > the base-controlled `pull_request_target` authority before treating bootstrap -> or lifecycle automation as trusted. +> or lifecycle automation as trusted. That check must be published by a +> dedicated GitHub App token minted only inside the exact-default-branch +> `squad-review-authority` environment. Missing or misconfigured reviewer +> credentials fail closed; the workflow never falls back to `github.token`. The quick start installs this workflow set: diff --git a/.squad-templates/skills/gh-aw-enlistment/SKILL.md b/.squad-templates/skills/gh-aw-enlistment/SKILL.md index bd6c10e53..9005f105e 100644 --- a/.squad-templates/skills/gh-aw-enlistment/SKILL.md +++ b/.squad-templates/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/docs/src/content/docs/guide/gh-aw.md b/docs/src/content/docs/guide/gh-aw.md index d59215ca4..0c9cfabe7 100644 --- a/docs/src/content/docs/guide/gh-aw.md +++ b/docs/src/content/docs/guide/gh-aw.md @@ -298,17 +298,21 @@ source/lock pairs, and one coherent 40-character revision. On a clean repository, `gh aw add` reports these expected safe-update changes: -- Restricted secrets: `SQUAD_GITHUB_APP_PRIVATE_KEY` and `SQUAD_GITHUB_TOKEN` +- Restricted secrets: `SQUAD_GITHUB_APP_PRIVATE_KEY`, `SQUAD_GITHUB_TOKEN`, and + `SQUAD_REVIEW_APP_PRIVATE_KEY` - Action: `bradygaster/squad/.github/actions/squad-init` > **These are referenced names, not prerequisites.** `gh aw add` lists the secrets > the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and you do not -> need to create either one to enlist a repository. Single-repo activation runs on -> the built-in `github.token`. Configure these only for cross-repo access or +> to supply them during compilation. `SQUAD_GITHUB_APP_PRIVATE_KEY` and +> `SQUAD_GITHUB_TOKEN` remain optional activation credentials; single-repo +> activation can use the built-in `github.token`. Configure those only for cross-repo access or > elevated permissions — see [enhanced permissions with a GitHub > App](#optional-enhanced-permissions-with-a-github-app) and [PAT -> fallback](#optional-pat-fallback). +> fallback](#optional-pat-fallback). `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: +> it belongs only in the branch-restricted `squad-review-authority` environment +> described below. Trusted required-check publication intentionally fails closed +> until that external prerequisite is provisioned. Review the report before approving it. If it contains only those documented entries, complete the first-install approval with: @@ -432,6 +436,47 @@ a Personal Access Token: **Auth precedence:** GitHub App token → `SQUAD_GITHUB_TOKEN` → `github.token`. +### Required: dedicated review authority App + +The required `Squad Review / review` check must not use `github.token`. +`github.token` checks are owned by the shared GitHub Actions App +(`id: 15368`, slug: `github-actions`), which is also available to ordinary +same-repository PR workflows. The reviewer instead mints a short-lived token +for a dedicated GitHub App inside a protected environment and has no fallback. + +Before expecting the post-install Cast canary to pass: + +1. Create a dedicated GitHub App with repository **Checks: read and write** and + read access to Actions, contents, metadata, and pull requests. Install it + only on the consumer repository. +2. Create the Actions environment **`squad-review-authority`**. +3. Configure a custom deployment branch policy containing exactly the + repository default branch. Do not allow wildcard, feature, release, tag, or + additional branch policies; a PR workflow must not be able to request this + environment from its own ref. +4. Store these reviewer-specific values in that environment, not as + repository-level Actions secrets or variables: + + | Setting | Type | Purpose | + |---------|------|---------| + | `SQUAD_REVIEW_APP_ID` | Variable | Dedicated App numeric ID; must not be `15368` | + | `SQUAD_REVIEW_APP_SLUG` | Variable | Dedicated App slug; must not be `github-actions` | + | `SQUAD_REVIEW_APP_OWNER` | Variable | Repository owner where the App is installed | + | `SQUAD_REVIEW_APP_PRIVATE_KEY` | Secret | Dedicated App private key | + +The publisher validates the configured ID and slug, mints an installation token +inside the environment, publishes with that token, and validates the App +identity returned by the Checks API. Missing environment protection, missing +credentials, token-mint failure, Actions App identity, or any ID/slug mismatch +fails closed. An ordinary `github.token` may create a same-named check owned by +the Actions App, but it cannot update the dedicated App's check and cannot +satisfy an integration-bound ruleset. + +Before rollout, verify the four reviewer-specific names are absent from +repository-level Actions secrets and variables. GitHub expression contexts can +otherwise fall back to a repository-scoped value with the same name. The hosted +controller treats that overlap as a hard configuration error. + --- ## Supported-path validation checklist @@ -1551,15 +1596,21 @@ generated bundle through the explicit human installation boundary, then observe a successful base-controlled `pull_request_target` check on the post-install draft Cast PR before changing rulesets. The installation PR itself is not evidence: its workflow and -check name are controlled by that PR. Record the activation canary's actual +check name are controlled by that PR. The Cast canary remains intentionally red +until the [dedicated review authority App](#required-dedicated-review-authority-app) +and exact-default-branch environment policy are provisioned. Record the +activation canary's actual check name, external ID, details URL, attestation summary, and GitHub App ID -from the check-runs API. Enable the required context with that observed App ID +and slug from the check-runs API. The attestation's `publisher_app_id` and +`publisher_app_slug` must equal the check's returned App identity and must not +be `15368`/`github-actions`. Enable the required context with that observed App ID on `dev` **only after advisory soak** has met the evidence gate in #1734; promote to `main` after the agreed soak. This change does not modify repository rulesets and does not claim live soak evidence. Keep native human approving-review requirements enabled independently, with stale approvals dismissed. The bot's `COMMENT` is not a human approval. Do not use an -unobserved guessed App ID or require the manual job. +unobserved guessed App ID, a user-supplied integration ID, an Actions-owned +same-name check, or the manual job. Because rulesets apply to all PRs, existing human/Copilot PRs must add committed attribution before enabling the requirement. Fork review remains unsupported; the workflow rejects foreign head repositories even though its base-controlled diff --git a/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md b/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md index bd6c10e53..9005f105e 100644 --- a/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md +++ b/packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md b/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md index bd6c10e53..9005f105e 100644 --- a/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md +++ b/packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/scripts/gh-aw-hosted-e2e.mjs b/scripts/gh-aw-hosted-e2e.mjs index b17ea1eff..e58960d0f 100644 --- a/scripts/gh-aw-hosted-e2e.mjs +++ b/scripts/gh-aw-hosted-e2e.mjs @@ -39,6 +39,9 @@ const RESEARCH_MARKER = ''; const PROVENANCE_MARKER_PATTERN = /^$/gm; const ACTIONS_BOT_LOGIN = 'github-actions[bot]'; const ACTIONS_BOT_ID = 41898282; +const ACTIONS_APP_ID = 15368; +const ACTIONS_APP_SLUG = 'github-actions'; +const REVIEW_AUTHORITY_ENVIRONMENT = 'squad-review-authority'; const SAFE_CHILD_ENV = Object.freeze([ 'CI', 'GH_CONFIG_DIR', @@ -367,6 +370,113 @@ export function guardedTargetMutation({ return mutate(); } +export function validateReviewAuthorityEnvironment( + environment, + branchPolicies, + secretNames, + variables, + repositorySecretNames, + repositoryVariableNames, + defaultBranch, + targetOwner, +) { + if (environment?.name !== REVIEW_AUTHORITY_ENVIRONMENT + || environment.deployment_branch_policy?.custom_branch_policies !== true + || environment.deployment_branch_policy?.protected_branches !== false) { + throw new Error( + 'Dedicated review authority environment must use an exact custom default-branch policy.', + ); + } + if (!Array.isArray(branchPolicies) + || branchPolicies.length !== 1 + || branchPolicies[0]?.type !== 'branch' + || branchPolicies[0]?.name !== defaultBranch) { + throw new Error( + 'Dedicated review authority environment must allow only the repository default branch.', + ); + } + if (!secretNames.includes('SQUAD_REVIEW_APP_PRIVATE_KEY')) { + throw new Error('Dedicated review authority environment is missing its reviewer App private key.'); + } + const reviewerNames = new Set([ + 'SQUAD_REVIEW_APP_ID', + 'SQUAD_REVIEW_APP_SLUG', + 'SQUAD_REVIEW_APP_OWNER', + 'SQUAD_REVIEW_APP_PRIVATE_KEY', + ]); + if (repositorySecretNames.some((name) => reviewerNames.has(name)) + || repositoryVariableNames.some((name) => reviewerNames.has(name))) { + throw new Error('Reviewer App credentials must not exist at repository scope.'); + } + const values = Object.fromEntries(variables.map(({ name, value }) => [name, value])); + const appId = Number(values.SQUAD_REVIEW_APP_ID); + const appSlug = values.SQUAD_REVIEW_APP_SLUG; + const appOwner = values.SQUAD_REVIEW_APP_OWNER; + if (!Number.isSafeInteger(appId) || appId < 1 || appId === ACTIONS_APP_ID + || typeof appSlug !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(appSlug) + || appSlug === ACTIONS_APP_SLUG || appOwner !== targetOwner) { + throw new Error('Dedicated review authority App variables are missing or misconfigured.'); + } + return { id: appId, slug: appSlug, owner: appOwner }; +} + +function reviewAuthorityEnvironment(target, defaultBranch) { + const [targetOwner] = target.split('/'); + const environment = ghJson([ + 'api', `repos/${target}/environments/${REVIEW_AUTHORITY_ENVIRONMENT}`, + ]); + const branchPolicies = ghJson([ + 'api', '--paginate', '--slurp', + `repos/${target}/environments/${REVIEW_AUTHORITY_ENVIRONMENT}/deployment-branch-policies?per_page=100`, + ]).flat().flatMap((page) => page.branch_policies ?? []); + const secretNames = ghJson([ + 'api', + `repos/${target}/environments/${REVIEW_AUTHORITY_ENVIRONMENT}/secrets?per_page=100`, + '--jq', '[.secrets[].name]', + ]); + const variables = ghJson([ + 'api', + `repos/${target}/environments/${REVIEW_AUTHORITY_ENVIRONMENT}/variables?per_page=100`, + '--jq', '[.variables[] | {name,value}]', + ]); + const repositorySecretNames = ghJson([ + 'api', `repos/${target}/actions/secrets?per_page=100`, + '--jq', '[.secrets[].name]', + ]); + const repositoryVariableNames = ghJson([ + 'api', `repos/${target}/actions/variables?per_page=100`, + '--jq', '[.variables[].name]', + ]); + return validateReviewAuthorityEnvironment( + environment, + branchPolicies, + secretNames, + variables, + repositorySecretNames, + repositoryVariableNames, + defaultBranch, + targetOwner, + ); +} + +export function observedRequiredCheck(check, attestation) { + if (check?.name !== 'Squad Review / review' + || !Number.isSafeInteger(check.app?.id) + || check.app.id < 1 + || check.app.id === ACTIONS_APP_ID + || typeof check.app?.slug !== 'string' + || check.app.slug === ACTIONS_APP_SLUG + || attestation?.publisher_app_id !== check.app.id + || attestation?.publisher_app_slug !== check.app.slug) { + throw new Error('Required-check rollout must use the observed dedicated App identity.'); + } + return { + context: check.name, + integration_id: check.app.id, + integration_slug: check.app.slug, + }; +} + export function authorizeTarget(args, sourceInfo, contract, github = githubAdapter) { const target = requireArg(args, 'target'); const expectedRepositoryId = Number(requireArg(args, 'target_repository_id')); @@ -404,8 +514,9 @@ export function authorizeTarget(args, sourceInfo, contract, github = githubAdapt || workflowPermissions.can_approve_pull_request_reviews !== true) { throw new Error('Target Actions permissions do not match the supported secure configuration.'); } + const reviewApp = reviewAuthorityEnvironment(target, info.default_branch); const baseline = assertPristineTarget(target, info.default_branch, contract, github); - return { target, info, workflowPermissions, actor, baseline }; + return { target, info, workflowPermissions, actor, reviewApp, baseline }; } function waitForBootstrapRun(target, headSha, startedAt, evidence) { @@ -565,7 +676,7 @@ export function waitForBootstrapOutputs( throw new Error('Timed out waiting for the draft Cast PR and bootstrap research issue.'); } -function waitForBaseControlledReviewCanary(target, castPr, evidence) { +function waitForBaseControlledReviewCanary(target, castPr, expectedApp, evidence) { const deadline = Date.now() + 20 * 60 * 1000; while (Date.now() < deadline) { const checks = ghJson([ @@ -580,8 +691,8 @@ function waitForBaseControlledReviewCanary(target, castPr, evidence) { check.name === 'Squad Review / review' && check.external_id === externalId && check.head_sha === castPr.headSha && - check.app?.id === 15368 && - check.app?.slug === 'github-actions'); + check.app?.id === expectedApp.id && + check.app?.slug === expectedApp.slug); if (trustedChecks.length > 1) { throw new Error(`Expected one base-controlled Squad Review canary check; found ${trustedChecks.length}.`); } @@ -633,11 +744,16 @@ function waitForBaseControlledReviewCanary(target, castPr, evidence) { || attestation.event !== 'pull_request_target' || attestation.workflow_path !== '.github/workflows/squad-review.lock.yml' || attestation.authority_job !== 'Squad Review Authority / attest' + || attestation.publisher_app_id !== expectedApp.id + || attestation.publisher_app_slug !== expectedApp.slug + || check.app?.id === ACTIONS_APP_ID + || check.app?.slug === ACTIONS_APP_SLUG || check.details_url !== `https://github.com/${target}/actions/runs/${verdict.run_id}`) { throw new Error('Squad Review canary check is not bound to the base-controlled authority run.'); } writeJson(resolve(evidence, 'base-controlled-review-canary.json'), { pull_request: castPr, + observed_required_check: observedRequiredCheck(check, attestation), check, review: verdicts[0], verdict, @@ -821,6 +937,7 @@ function hosted(args, repositoryRoot) { const reviewCanary = waitForBaseControlledReviewCanary( targetState.target, outputs.castPr, + targetState.reviewApp, evidence, ); diff --git a/templates/skills/gh-aw-enlistment/SKILL.md b/templates/skills/gh-aw-enlistment/SKILL.md index bd6c10e53..9005f105e 100644 --- a/templates/skills/gh-aw-enlistment/SKILL.md +++ b/templates/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/test/gh-aw-enlistment-skill.test.ts b/test/gh-aw-enlistment-skill.test.ts index fdcaf5c1d..5d400576e 100644 --- a/test/gh-aw-enlistment-skill.test.ts +++ b/test/gh-aw-enlistment-skill.test.ts @@ -115,10 +115,11 @@ describe('gh-aw-enlistment skill', () => { // Every backtick-delimited token in the region — order-independent exact set. const tokens = [...region.matchAll(/`([^`]+)`/g)].map(m => m[1]); - expect(tokens.slice().sort(), 'allowlist tokens must be exactly the three documented entries').toEqual( + expect(tokens.slice().sort(), 'allowlist tokens must be exactly the four documented entries').toEqual( [ 'SQUAD_GITHUB_APP_PRIVATE_KEY', 'SQUAD_GITHUB_TOKEN', + 'SQUAD_REVIEW_APP_PRIVATE_KEY', 'bradygaster/squad/.github/actions/squad-init', ].sort() ); diff --git a/test/gh-aw-hosted-e2e.test.ts b/test/gh-aw-hosted-e2e.test.ts index cb90b147e..9728a0bf7 100644 --- a/test/gh-aw-hosted-e2e.test.ts +++ b/test/gh-aw-hosted-e2e.test.ts @@ -6,8 +6,10 @@ import { parse } from 'yaml'; import { assertPristineTarget, guardedTargetMutation, + observedRequiredCheck, sanitizedEnvironment, selectBootstrapOutputs, + validateReviewAuthorityEnvironment, waitForBootstrapOutputs, } from '../scripts/gh-aw-hosted-e2e.mjs'; import { @@ -218,7 +220,10 @@ describe('Squad gh-aw hosted E2E controller', () => { it('requires a base-controlled review canary after the manual installation boundary', () => { expect(SCRIPT).toContain('waitForBaseControlledReviewCanary'); expect(SCRIPT).toContain("check.name === 'Squad Review / review'"); - expect(SCRIPT).toContain("check.app?.slug === 'github-actions'"); + expect(SCRIPT).toContain('check.app?.id === expectedApp.id'); + expect(SCRIPT).toContain('check.app?.slug === expectedApp.slug'); + expect(SCRIPT).toContain('observed_required_check'); + expect(SCRIPT).toContain('integration_id: check.app.id'); expect(SCRIPT).toContain("'@squad/base-controlled-bootstrap'"); expect(SCRIPT).toContain("'@squad/base-controlled-review'"); expect(SCRIPT).toContain("verdict.result !== 'COMMENT'"); @@ -227,6 +232,92 @@ describe('Squad gh-aw hosted E2E controller', () => { ); }); + it('requires a branch-restricted environment with reviewer-only App credentials', () => { + const environment = { + name: 'squad-review-authority', + deployment_branch_policy: { + custom_branch_policies: true, + protected_branches: false, + }, + }; + const policies = [{ type: 'branch', name: 'main' }]; + const secrets = ['SQUAD_REVIEW_APP_PRIVATE_KEY']; + const variables = [ + { name: 'SQUAD_REVIEW_APP_ID', value: '424242' }, + { name: 'SQUAD_REVIEW_APP_SLUG', value: 'squad-review-authority' }, + { name: 'SQUAD_REVIEW_APP_OWNER', value: 'owner' }, + ]; + expect(validateReviewAuthorityEnvironment( + environment, + policies, + secrets, + variables, + [], + [], + 'main', + 'owner', + )).toEqual({ id: 424242, slug: 'squad-review-authority', owner: 'owner' }); + + const invalid = [ + [undefined, policies, secrets, variables, [], []], + [{ ...environment, deployment_branch_policy: null }, policies, secrets, variables, [], []], + [environment, [], secrets, variables, [], []], + [environment, [{ type: 'branch', name: '*' }], secrets, variables, [], []], + [environment, [...policies, { type: 'branch', name: 'release' }], secrets, variables, [], []], + [environment, policies, [], variables, [], []], + [environment, policies, secrets, + variables.filter(({ name }) => name !== 'SQUAD_REVIEW_APP_ID'), [], []], + [environment, policies, secrets, variables.map(variable => + variable.name === 'SQUAD_REVIEW_APP_ID' ? { ...variable, value: '15368' } : variable), [], []], + [environment, policies, secrets, variables.map(variable => + variable.name === 'SQUAD_REVIEW_APP_SLUG' + ? { ...variable, value: 'github-actions' } + : variable), [], []], + [environment, policies, secrets, variables.map(variable => + variable.name === 'SQUAD_REVIEW_APP_OWNER' + ? { ...variable, value: 'attacker' } + : variable), [], []], + [environment, policies, secrets, variables, ['SQUAD_REVIEW_APP_PRIVATE_KEY'], []], + [environment, policies, secrets, variables, [], ['SQUAD_REVIEW_APP_ID']], + ] as const; + for (const args of invalid) { + expect(() => validateReviewAuthorityEnvironment( + args[0], + args[1], + args[2], + args[3], + args[4], + args[5], + 'main', + 'owner', + )).toThrow(); + } + }); + + it('derives ruleset integration only from the observed dedicated canary check', () => { + const check = { + name: 'Squad Review / review', + app: { id: 424242, slug: 'squad-review-authority' }, + }; + const attestation = { + publisher_app_id: 424242, + publisher_app_slug: 'squad-review-authority', + }; + expect(observedRequiredCheck(check, attestation)).toEqual({ + context: 'Squad Review / review', + integration_id: 424242, + integration_slug: 'squad-review-authority', + }); + expect(() => observedRequiredCheck( + { ...check, app: { id: 15368, slug: 'github-actions' } }, + { publisher_app_id: 15368, publisher_app_slug: 'github-actions' }, + )).toThrow(); + expect(() => observedRequiredCheck(check, { + ...attestation, + publisher_app_id: 1, + })).toThrow(); + }); + it('never executes candidate package or installed verifier with inherited credentials', () => { expect(SCRIPT).toContain( 'env: sanitizedEnvironment(options.env, { allowGitHubToken: options.allowGitHubToken === true })', diff --git a/test/gh-aw-review-guard.test.ts b/test/gh-aw-review-guard.test.ts index fee6f1dd6..42cddf84a 100644 --- a/test/gh-aw-review-guard.test.ts +++ b/test/gh-aw-review-guard.test.ts @@ -16,6 +16,8 @@ const SUBMITTED = '2026-09-28T12:01:01Z'; const FINISHED = '2026-09-28T12:02:00Z'; const MERGED = '2026-09-28T12:03:00Z'; const NOW = Date.parse('2026-09-28T12:04:00Z'); +const REVIEW_APP_ID = 424242; +const REVIEW_APP_SLUG = 'squad-review-authority'; const workspaces: string[] = []; afterEach(() => { @@ -85,7 +87,7 @@ function fixture(relay = false) { conclusion: 'success', completed_at: FINISHED, details_url: `https://github.com/${REPOSITORY}/actions/runs/17`, - app: { id: 15368, slug: 'github-actions' }, + app: { id: REVIEW_APP_ID, slug: REVIEW_APP_SLUG }, output: { summary: JSON.stringify({ schema: 'squad-review-check/v1', @@ -99,6 +101,8 @@ function fixture(relay = false) { event: 'pull_request_target', workflow_path: '.github/workflows/squad-review.lock.yml', authority_job: 'Squad Review Authority / attest', + publisher_app_id: REVIEW_APP_ID, + publisher_app_slug: REVIEW_APP_SLUG, }), }, }]; @@ -282,6 +286,27 @@ describe('independent Squad review guard', () => { } }); + it('ignores an ordinary-token forged check and accepts only the dedicated App check', async () => { + const f = fixture(true); + f.checkRuns.unshift({ + ...structuredClone(f.checkRuns[0]), + id: 87, + app: { id: 15368, slug: 'github-actions' }, + output: { + summary: JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + publisher_app_id: 15368, + publisher_app_slug: 'github-actions', + }), + }, + }); + await expect(assertClearingReview(f.env, f.get, { relay: true })) + .resolves.toEqual(f.verdict); + f.checkRuns.splice(1); + await expect(assertClearingReview(f.env, f.get, { relay: true })) + .rejects.toThrow('missing or duplicate exact-head authority check'); + }); + it('refuses PR-controlled shaped review, job, check, and artifact evidence', async () => { const f = fixture(true); f.run.event = 'pull_request'; @@ -355,7 +380,8 @@ describe('independent Squad review guard', () => { 'wrong-branch', 'duplicate-marker', 'stale-head', 'foreign-head', 'foreign-base', 'head-race', 'not-merged', 'wrong-base', 'merge-before-review', 'merge-before-check', 'failed-run', 'failed-check', 'missing-check', 'duplicate-check', 'wrong-check', - 'forged-check', 'wrong-check-app', 'wrong-check-attestation', + 'forged-check', 'actions-app-check', 'wrong-check-app', 'wrong-check-app-slug', + 'wrong-check-attestation', 'wrong-attested-app-id', 'wrong-attested-app-slug', 'manual-run', 'wrong-workflow', 'wrong-run-repo', 'wrong-run-sha', 'wrong-run-pr', 'wrong-run-attempt', 'wrong-run-title', 'verdict-before-run', 'wrong-bot-id', 'wrong-bot-type', @@ -399,7 +425,24 @@ describe('independent Squad review guard', () => { case 'wrong-bot-id': f.review.user.id = 1; break; case 'wrong-bot-type': f.review.user.type = 'User'; break; case 'forged-check': f.checkRuns[0].external_id = 'forged'; break; + case 'actions-app-check': + f.checkRuns[0].app = { id: 15368, slug: 'github-actions' }; + f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + publisher_app_id: 15368, + publisher_app_slug: 'github-actions', + }); + break; case 'wrong-check-app': f.checkRuns[0].app.id = 1; break; + case 'wrong-check-app-slug': f.checkRuns[0].app.slug = 'other-review-app'; break; + case 'wrong-attested-app-id': f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + publisher_app_id: 1, + }); break; + case 'wrong-attested-app-slug': f.checkRuns[0].output.summary = JSON.stringify({ + ...JSON.parse(f.checkRuns[0].output.summary), + publisher_app_slug: 'other-review-app', + }); break; case 'wrong-check-attestation': f.checkRuns[0].output.summary = JSON.stringify({ ...JSON.parse(f.checkRuns[0].output.summary), event: 'pull_request', diff --git a/test/gh-aw-review-workflow.test.ts b/test/gh-aw-review-workflow.test.ts index 5a9759a42..ee6bc7700 100644 --- a/test/gh-aw-review-workflow.test.ts +++ b/test/gh-aw-review-workflow.test.ts @@ -126,6 +126,84 @@ interface CompiledContract { safeOutputs: Record>; } +async function executePublisher( + script: string, + { + publishedApp, + existing = [], + updateError, + }: { + publishedApp: { id: number; slug: string }; + existing?: Array>; + updateError?: Error; + }, +): Promise<{ failures: string[]; created: number; updated: number; deleted: number }> { + const failures: string[] = []; + let created = 0; + let updated = 0; + let deleted = 0; + const listJobs = async () => undefined; + const listChecks = async () => undefined; + const github = { + paginate: async (method: unknown) => method === listJobs + ? [{ name: 'Squad Review Authority / attest', conclusion: 'success' }] + : existing, + rest: { + actions: { + getWorkflowRun: async () => ({ data: { + event: 'pull_request_target', + path: '.github/workflows/squad-review.lock.yml', + head_sha: 'b'.repeat(40), + repository: { full_name: 'squad/example' }, + } }), + listJobsForWorkflowRunAttempt: listJobs, + }, + checks: { + listForRef: listChecks, + create: async () => { + created++; + return { data: { id: 88, app: publishedApp } }; + }, + update: async () => { + updated++; + if (updateError) throw updateError; + return { data: { id: 88, app: publishedApp } }; + }, + delete: async () => { + deleted++; + return { data: {} }; + }, + }, + }, + }; + const core = { setFailed: (message: string) => failures.push(message) }; + const previous = { ...process.env }; + Object.assign(process.env, { + AUTHORITY_RESULT: 'success', + GITHUB_REPOSITORY: 'squad/example', + GITHUB_RUN_ID: '17', + GITHUB_RUN_ATTEMPT: '1', + GITHUB_SERVER_URL: 'https://github.com', + SQUAD_REVIEW_APP_ID: '424242', + SQUAD_REVIEW_APP_SLUG: 'squad-review-authority', + SQUAD_REVIEW_PR: '42', + SQUAD_REVIEW_BASE: 'b'.repeat(40), + SQUAD_REVIEW_HEAD: 'a'.repeat(40), + SQUAD_REVIEW_WORKFLOW_SHA: 'b'.repeat(40), + }); + try { + const run = new Function( + 'github', + 'core', + `return (async () => {\n${script}\n})();`, + ) as (github: unknown, core: unknown) => Promise; + await run(github, core); + } finally { + process.env = previous; + } + return { failures, created, updated, deleted }; +} + function compileReviewer(workflow = REVIEWER): CompiledContract { const workspace = mkdtempSync(resolve(ROOT, '.squad-review-contract-')); compileWorkspaces.push(workspace); @@ -205,20 +283,39 @@ function assertCompiledGate(lock: string): void { expect(publish.name).toBe('Publish Squad Review required check'); expect(publish.if).toBe('always()'); expect(publish.needs).toEqual(expect.arrayContaining(['agent', 'safe_outputs', 'review'])); + expect(publish.environment).toBe('squad-review-authority'); expect(publish.permissions).toMatchObject({ actions: 'read', - checks: 'write', contents: 'read', 'pull-requests': 'read', }); + expect(publish.permissions.checks).toBeUndefined(); + const validateStep = publish.steps.find((step: { name: string }) => + step.name === 'Validate dedicated reviewer App configuration'); + expect(validateStep.env.SQUAD_REVIEW_APP_ID).toBe('${{ vars.SQUAD_REVIEW_APP_ID }}'); + expect(validateStep.env.SQUAD_REVIEW_APP_SLUG).toBe('${{ vars.SQUAD_REVIEW_APP_SLUG }}'); + expect(validateStep.env.SQUAD_REVIEW_APP_OWNER).toBe('${{ vars.SQUAD_REVIEW_APP_OWNER }}'); + expect(validateStep.env.SQUAD_REVIEW_APP_PRIVATE_KEY) + .toBe('${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }}'); + expect(validateStep.run).toContain('test "${SQUAD_REVIEW_APP_ID}" != "15368"'); + expect(validateStep.run).toContain('test "${SQUAD_REVIEW_APP_SLUG}" != "github-actions"'); + const mintStep = publish.steps.find((step: { name: string }) => + step.name === 'Mint dedicated reviewer App token'); + expect(mintStep.uses).toMatch(/^actions\/create-github-app-token@[0-9a-f]{40}$/); + expect(mintStep['continue-on-error']).toBeUndefined(); const publishStep = publish.steps.find((step: { name: string }) => step.name === 'Publish exact-head required check'); + expect(publishStep.with['github-token']) + .toBe('${{ steps.squad-review-app-token.outputs.token }}'); expect(publishStep.with.script).toContain("const checkName = 'Squad Review / review'"); expect(publishStep.with.script).toContain("run.event !== 'pull_request_target'"); expect(publishStep.with.script).toContain('run.head_sha !== workflowSha'); expect(publishStep.with.script).toContain('authorityJobs.length !== 1'); expect(publishStep.with.script).toContain("external_id: externalId"); expect(publishStep.with.script).toContain("head_sha: headSha"); + expect(publishStep.with.script).toContain('published.data.app?.id !== expectedAppId'); + expect(publishStep.with.script).toContain('publisher_app_id: expectedAppId'); + expect(publishStep.with.script).toContain('publisher_app_slug: expectedAppSlug'); expect(publishStep.with.script).not.toContain('github.event.pull_request.head.ref'); expect(lock).not.toContain('Checkout PR branch'); expect(lock).not.toMatch(/uses:\s+\.\/\.github\/actions\//); @@ -303,6 +400,42 @@ async function executeCompiledGuardLoader( } describe('gh-aw enforcing Squad reviewer', () => { + it('rejects ordinary-token publication and accepts the dedicated App identity', async () => { + const { lock } = compileReviewer(); + const workflow = parse(lock); + const publishStep = workflow.jobs.publish.steps.find((step: { name: string }) => + step.name === 'Publish exact-head required check'); + const ordinary = await executePublisher(publishStep.with.script, { + publishedApp: { id: 15368, slug: 'github-actions' }, + }); + expect(ordinary).toEqual({ + failures: ['Squad review check was not published by the configured dedicated GitHub App.'], + created: 1, + updated: 0, + deleted: 1, + }); + const dedicated = await executePublisher(publishStep.with.script, { + publishedApp: { id: 424242, slug: 'squad-review-authority' }, + }); + expect(dedicated).toEqual({ failures: [], created: 1, updated: 0, deleted: 0 }); + }); + + it('cannot update the dedicated App check with an ordinary workflow token', async () => { + const { lock } = compileReviewer(); + const workflow = parse(lock); + const publishStep = workflow.jobs.publish.steps.find((step: { name: string }) => + step.name === 'Publish exact-head required check'); + await expect(executePublisher(publishStep.with.script, { + publishedApp: { id: 15368, slug: 'github-actions' }, + existing: [{ + id: 88, + external_id: `squad-review-authority/v1:squad/example:42:${'b'.repeat(40)}:${'a'.repeat(40)}`, + app: { id: 424242, slug: 'squad-review-authority' }, + }], + updateError: Object.assign(new Error('Resource not accessible by integration'), { status: 403 }), + })).rejects.toMatchObject({ status: 403 }); + }); + it('keeps review automatic and makes /squad review a non-dispatching rerun guide', () => { const routerDispatch = yamlBlock(ROUTER_FRONTMATTER, 'dispatch-workflow'); const reviewTrigger = yamlBlock(REVIEWER_FRONTMATTER, 'on'); diff --git a/test/standalone-release-workflow.test.ts b/test/standalone-release-workflow.test.ts index cd0f44125..68f7eb2cf 100644 --- a/test/standalone-release-workflow.test.ts +++ b/test/standalone-release-workflow.test.ts @@ -707,6 +707,8 @@ describe('automated package publication', () => { expect(ghAwGuide).toContain('`.vscode/settings.json`'); expect(ghAwGuide).toContain('SQUAD_GITHUB_APP_PRIVATE_KEY'); expect(ghAwGuide).toContain('SQUAD_GITHUB_TOKEN'); + expect(ghAwGuide).toContain('SQUAD_REVIEW_APP_PRIVATE_KEY'); + expect(ghAwGuide).toContain('squad-review-authority'); expect(ghAwGuide).toContain('both slash-command and `github-actions[bot]`'); expect(ghAwGuide).toContain('The completion comment links the created Cast PR'); expect(ghAwGuide).toContain('application CI is `action_required`'); diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index 0ef7eceef..216ffc9a8 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -151,7 +151,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "47b911d3d56821bf8c2f3345ca4394786212cf11d8ed0078ba45324a42e8ec3e" + check_hash "$install_verifier" "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/package/squad-review.md b/workflows/package/squad-review.md index 0e20310f3..7ad1673bf 100644 --- a/workflows/package/squad-review.md +++ b/workflows/package/squad-review.md @@ -136,33 +136,63 @@ jobs: - safe_outputs - review runs-on: ubuntu-latest + environment: squad-review-authority permissions: actions: read - checks: write contents: read pull-requests: read steps: + - name: Validate dedicated reviewer App configuration + env: + SQUAD_REVIEW_APP_ID: ${{ vars.SQUAD_REVIEW_APP_ID }} + SQUAD_REVIEW_APP_SLUG: ${{ vars.SQUAD_REVIEW_APP_SLUG }} + SQUAD_REVIEW_APP_OWNER: ${{ vars.SQUAD_REVIEW_APP_OWNER }} + SQUAD_REVIEW_APP_PRIVATE_KEY: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }} + run: | + set -euo pipefail + test "${SQUAD_REVIEW_APP_ID}" != "15368" + test "${SQUAD_REVIEW_APP_SLUG}" != "github-actions" + [[ "${SQUAD_REVIEW_APP_ID}" =~ ^[1-9][0-9]*$ ]] + [[ "${SQUAD_REVIEW_APP_SLUG}" =~ ^[a-z0-9][a-z0-9-]*$ ]] + [[ "${SQUAD_REVIEW_APP_OWNER}" =~ ^[A-Za-z0-9_.-]+$ ]] + test -n "${SQUAD_REVIEW_APP_PRIVATE_KEY}" + - name: Mint dedicated reviewer App token + id: squad-review-app-token + uses: actions/create-github-app-token@v3.2.0 + with: + app-id: ${{ vars.SQUAD_REVIEW_APP_ID }} + private-key: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }} + owner: ${{ vars.SQUAD_REVIEW_APP_OWNER }} - name: Publish exact-head required check uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 env: AUTHORITY_RESULT: ${{ needs.review.result }} + SQUAD_REVIEW_APP_ID: ${{ vars.SQUAD_REVIEW_APP_ID }} + SQUAD_REVIEW_APP_SLUG: ${{ vars.SQUAD_REVIEW_APP_SLUG }} SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} SQUAD_REVIEW_BASE: ${{ github.event.pull_request.base.sha }} SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: + github-token: ${{ steps.squad-review-app-token.outputs.token }} script: | const checkName = 'Squad Review / review'; const authorityJob = 'Squad Review Authority / attest'; const repository = process.env.GITHUB_REPOSITORY; const [owner, repo] = repository.split('/'); + const expectedAppId = Number(process.env.SQUAD_REVIEW_APP_ID); + const expectedAppSlug = process.env.SQUAD_REVIEW_APP_SLUG; const pullRequest = Number(process.env.SQUAD_REVIEW_PR); const baseSha = process.env.SQUAD_REVIEW_BASE; const headSha = process.env.SQUAD_REVIEW_HEAD; const workflowSha = process.env.SQUAD_REVIEW_WORKFLOW_SHA; const runId = Number(process.env.GITHUB_RUN_ID); const runAttempt = Number(process.env.GITHUB_RUN_ATTEMPT); - if (!Number.isSafeInteger(pullRequest) || pullRequest < 1 || + if (!Number.isSafeInteger(expectedAppId) || expectedAppId < 1 || + expectedAppId === 15368 || + !/^[a-z0-9][a-z0-9-]*$/.test(expectedAppSlug) || + expectedAppSlug === 'github-actions' || + !Number.isSafeInteger(pullRequest) || pullRequest < 1 || !/^[0-9a-f]{40}$/.test(baseSha) || !/^[0-9a-f]{40}$/.test(headSha) || workflowSha !== baseSha || !Number.isSafeInteger(runId) || runId < 1 || !Number.isSafeInteger(runAttempt) || runAttempt < 1) { @@ -194,7 +224,10 @@ jobs: const existing = await github.paginate(github.rest.checks.listForRef, { owner, repo, ref: headSha, check_name: checkName, per_page: 100, }); - const owned = existing.filter(check => check.external_id === externalId); + const owned = existing.filter(check => + check.external_id === externalId && + check.app?.id === expectedAppId && + check.app?.slug === expectedAppSlug); if (owned.length > 1) { core.setFailed('Duplicate exact-head Squad review authority checks.'); return; @@ -217,6 +250,8 @@ jobs: event: 'pull_request_target', workflow_path: '.github/workflows/squad-review.lock.yml', authority_job: authorityJob, + publisher_app_id: expectedAppId, + publisher_app_slug: expectedAppSlug, }), }; const request = { @@ -227,13 +262,24 @@ jobs: external_id: externalId, output, }; - if (owned.length === 1) { - await github.rest.checks.update({ + const published = owned.length === 1 + ? await github.rest.checks.update({ ...request, check_run_id: owned[0].id, - }); - } else { - await github.rest.checks.create(request); + }) + : await github.rest.checks.create(request); + if (published.data.app?.id !== expectedAppId || + published.data.app?.slug !== expectedAppSlug) { + try { + await github.rest.checks.delete({ + owner, repo, check_run_id: published.data.id, + }); + } finally { + core.setFailed( + 'Squad review check was not published by the configured dedicated GitHub App.' + ); + } + return; } if (!succeeded) { core.setFailed('Base-controlled Squad review authority did not succeed.'); diff --git a/workflows/shared/squad-install-verifier.mjs b/workflows/shared/squad-install-verifier.mjs index 0742369e1..6b7ad970e 100644 --- a/workflows/shared/squad-install-verifier.mjs +++ b/workflows/shared/squad-install-verifier.mjs @@ -516,6 +516,7 @@ export function checkSource(root) { const digests = expectedEmbeddedDigests(root); const dispatcher = readFileSync(resolve(root, 'workflows/squad.md'), 'utf8'); const bootstrap = readFileSync(resolve(root, 'workflows/squad-bootstrap.md'), 'utf8'); + const reviewer = readFileSync(resolve(root, 'workflows/squad-review.md'), 'utf8'); if (!dispatcher.includes(`validator_expected_sha256="${digests.cast}"`)) { failures.push('Generated Cast validator digest is stale in workflows/squad.md.'); } @@ -534,6 +535,22 @@ export function checkSource(root) { failures.push(`Generated package file is stale: ${relative(root, path)} (run: npm run gh-aw:integrity:write)`); } } + for (const required of [ + 'environment: squad-review-authority', + 'SQUAD_REVIEW_APP_PRIVATE_KEY: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }}', + 'github-token: ${{ steps.squad-review-app-token.outputs.token }}', + 'published.data.app?.id !== expectedAppId', + "expectedAppId === 15368", + "expectedAppSlug === 'github-actions'", + ]) { + if (!reviewer.includes(required)) { + failures.push(`Dedicated review authority contract is missing: ${required}`); + } + } + const publishJob = reviewer.match(/\n publish:\n([\s\S]*?)\n---\n/)?.[1] ?? ''; + if (publishJob.includes('checks: write')) { + failures.push('Dedicated review publisher must not grant checks:write to github.token.'); + } } catch (error) { failures.push(error instanceof Error ? error.message : String(error)); } diff --git a/workflows/shared/squad-review-guard.mjs b/workflows/shared/squad-review-guard.mjs index d2a97a76d..e7a11cbc1 100644 --- a/workflows/shared/squad-review-guard.mjs +++ b/workflows/shared/squad-review-guard.mjs @@ -15,6 +15,7 @@ const BOT = 'github-actions[bot]'; const BOT_ID = 41898282; const ACTIONS_APP_ID = 15368; const ACTIONS_APP_SLUG = 'github-actions'; +const APP_SLUG = /^[a-z0-9][a-z0-9-]*$/; const BOOTSTRAP_BRANCH = 'squad/bootstrap-cast'; const BOOTSTRAP_TITLE = '[squad] Cast your Squad'; const BOOTSTRAP_AUTHOR = '@squad/base-controlled-bootstrap'; @@ -389,27 +390,35 @@ export async function assertClearingReview(env, get, options = {}) { const externalId = `${CHECK_EXTERNAL_ID}:${target.repository}:${target.pull_request}:${target.base_sha}:${target.head_sha}`; const checks = checkRuns.filter(check => check.name === CHECK_NAME && - check.external_id === externalId); + check.external_id === externalId && + Number.isSafeInteger(check.app?.id) && + check.app.id > 0 && + check.app.id !== ACTIONS_APP_ID && + typeof check.app?.slug === 'string' && + APP_SLUG.test(check.app.slug) && + check.app.slug !== ACTIONS_APP_SLUG); requireThat(checks.length === 1, 'missing or duplicate exact-head authority check'); const check = checks[0]; requireThat(check.head_sha === target.head_sha && check.status === 'completed' && - check.conclusion === 'success' && check.app?.id === ACTIONS_APP_ID && - check.app?.slug === ACTIONS_APP_SLUG && + check.conclusion === 'success' && check.details_url === `${env.GITHUB_SERVER_URL ?? 'https://github.com'}/${target.repository}/actions/runs/${verdict.run_id}`, - 'required review check is not attributable to GitHub Actions authority'); + 'required review check is not attributable to the dedicated GitHub App'); const summary = JSON.parse(check.output?.summary ?? ''); requireThat(exactKeys(summary, [ 'schema', 'repository', 'pull_request', 'base_sha', 'head_sha', 'workflow_sha', 'run_id', 'run_attempt', 'event', 'workflow_path', 'authority_job', + 'publisher_app_id', 'publisher_app_slug', ]) && summary.schema === CHECK_SCHEMA && summary.repository === target.repository && summary.pull_request === target.pull_request && summary.base_sha === target.base_sha && summary.head_sha === target.head_sha && summary.workflow_sha === target.workflow_sha && summary.run_id === verdict.run_id && summary.run_attempt === run.run_attempt && summary.event === 'pull_request_target' && summary.workflow_path === WORKFLOW && summary.authority_job === AUTHORITY_JOB && + summary.publisher_app_id === check.app.id && + summary.publisher_app_slug === check.app.slug && timestamp(check.completed_at) <= cutoff, - 'required review check attestation is invalid'); + 'required review check attestation or dedicated App identity is invalid'); } if (verdict.result === 'REQUEST_CHANGES') { const comments = await list(get, `repos/${target.repository}/issues/${target.pull_request}/comments`); diff --git a/workflows/skills/gh-aw-enlistment/SKILL.md b/workflows/skills/gh-aw-enlistment/SKILL.md index 54707c13a..a2bf36c08 100644 --- a/workflows/skills/gh-aw-enlistment/SKILL.md +++ b/workflows/skills/gh-aw-enlistment/SKILL.md @@ -182,17 +182,17 @@ uses a moving branch reference. On a clean repo, `gh aw add` reports these expected safe updates and **nothing else**: -- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`** and **`SQUAD_GITHUB_TOKEN`** +- Restricted secrets: **`SQUAD_GITHUB_APP_PRIVATE_KEY`**, + **`SQUAD_GITHUB_TOKEN`**, and **`SQUAD_REVIEW_APP_PRIVATE_KEY`** - Action: **`bradygaster/squad/.github/actions/squad-init`** -> **These are referenced names, not prerequisites.** `gh aw add` lists the secrets -> the workflows *reference* so you can approve that surface — it is not asking you -> to supply them. Both secrets are optional, they need not exist, and neither is -> required to enlist a repository. Single-repo activation runs on the built-in -> `github.token`. Configure them only for cross-repo access or elevated -> permissions. Auth precedence: GitHub App token, then the PAT, then -> `github.token`. Never block an enlistment waiting for a credential. +> **Compilation approval is not credential provisioning.** `gh aw add` lists +> referenced names so you can approve the surface. `SQUAD_GITHUB_APP_PRIVATE_KEY` +> and `SQUAD_GITHUB_TOKEN` remain optional activation credentials. +> `SQUAD_REVIEW_APP_PRIVATE_KEY` is different: trusted check publication requires +> it in the exact-default-branch `squad-review-authority` environment. Never put +> reviewer credentials at repository scope and never fall back to `github.token`. If — and only if — the report contains exactly those documented entries, complete the one-time approval: @@ -284,7 +284,27 @@ gh pr checks --watch `main`. - Request Copilot review, address feedback, and wait for required checks. -### 9. Never auto-merge — and explain what comes next +### 9. Verify the external review-authority prerequisite when API access permits + +Before claiming trusted review is ready, query the repository environment. It +must be named `squad-review-authority`, use custom deployment branch policies, +allow exactly the captured `${default_branch}`, contain the environment secret +`SQUAD_REVIEW_APP_PRIVATE_KEY`, and define environment variables +`SQUAD_REVIEW_APP_ID`, `SQUAD_REVIEW_APP_SLUG`, and +`SQUAD_REVIEW_APP_OWNER`. The App ID/slug must differ from +`15368`/`github-actions`. All four reviewer-specific names must also be absent +from repository-level Actions secrets and variables; repository fallback does +not satisfy this gate. + +If the authenticated account cannot read environment configuration, or any +requirement is absent, report the exact external prerequisite and do not claim +the required check is trusted. The installation PR remains a human boundary; +after it merges, the Cast canary intentionally fails closed until an +administrator provisions the environment and reruns the base-controlled +review. Configure a ruleset only from the canary check's observed App +integration ID, never from user input or a guessed value. + +### 10. Never auto-merge — and explain what comes next - **Never** merge the bootstrap PR yourself. Merge happens **only** after human approval. @@ -346,8 +366,9 @@ gh pr edit --add-reviewer @copilot # then wait for review + checks; DO NOT mer ### ✓ Correct: STOP on an undocumented safe-update entry ```text -gh aw add reports a third secret: `ACME_DEPLOY_KEY`. -→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN) +gh aw add reports an additional secret: `ACME_DEPLOY_KEY`. +→ This is NOT in the allowlist (SQUAD_GITHUB_APP_PRIVATE_KEY, SQUAD_GITHUB_TOKEN, + SQUAD_REVIEW_APP_PRIVATE_KEY) and is NOT the squad-init action. Do NOT run `--approve`. Halt, report "unexpected safe-update entry: ACME_DEPLOY_KEY", and wait. ``` @@ -381,7 +402,8 @@ gh pr merge --squash # auto-merge before human review. NEVER. - ❌ **Blanket staging** (`git add .` / `-A` / `git commit -a`). Stage only `.gitattributes`, `.github/aw/`, `.github/workflows/`, `.github/skills/`, by path. - ❌ **Approving unknown safe updates.** Approve ONLY `SQUAD_GITHUB_APP_PRIVATE_KEY`, - `SQUAD_GITHUB_TOKEN`, and `bradygaster/squad/.github/actions/squad-init`. Anything + `SQUAD_GITHUB_TOKEN`, `SQUAD_REVIEW_APP_PRIVATE_KEY`, and + `bradygaster/squad/.github/actions/squad-init`. Anything else is a STOP. - ❌ **Treating `--approve` as the final compile.** Always finish with a plain `gh aw compile --strict` (no `--approve`). diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index 76c14c9ef..ca9ee3058 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -158,7 +158,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "47b911d3d56821bf8c2f3345ca4394786212cf11d8ed0078ba45324a42e8ec3e" + check_hash "$install_verifier" "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/squad-review.md b/workflows/squad-review.md index 7b7bed358..84e34a0a3 100644 --- a/workflows/squad-review.md +++ b/workflows/squad-review.md @@ -124,33 +124,63 @@ jobs: if: always() needs: [agent, safe_outputs, review] runs-on: ubuntu-latest + environment: squad-review-authority permissions: actions: read - checks: write contents: read pull-requests: read steps: + - name: Validate dedicated reviewer App configuration + env: + SQUAD_REVIEW_APP_ID: ${{ vars.SQUAD_REVIEW_APP_ID }} + SQUAD_REVIEW_APP_SLUG: ${{ vars.SQUAD_REVIEW_APP_SLUG }} + SQUAD_REVIEW_APP_OWNER: ${{ vars.SQUAD_REVIEW_APP_OWNER }} + SQUAD_REVIEW_APP_PRIVATE_KEY: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }} + run: | + set -euo pipefail + test "${SQUAD_REVIEW_APP_ID}" != "15368" + test "${SQUAD_REVIEW_APP_SLUG}" != "github-actions" + [[ "${SQUAD_REVIEW_APP_ID}" =~ ^[1-9][0-9]*$ ]] + [[ "${SQUAD_REVIEW_APP_SLUG}" =~ ^[a-z0-9][a-z0-9-]*$ ]] + [[ "${SQUAD_REVIEW_APP_OWNER}" =~ ^[A-Za-z0-9_.-]+$ ]] + test -n "${SQUAD_REVIEW_APP_PRIVATE_KEY}" + - name: Mint dedicated reviewer App token + id: squad-review-app-token + uses: actions/create-github-app-token@v3.2.0 + with: + app-id: ${{ vars.SQUAD_REVIEW_APP_ID }} + private-key: ${{ secrets.SQUAD_REVIEW_APP_PRIVATE_KEY }} + owner: ${{ vars.SQUAD_REVIEW_APP_OWNER }} - name: Publish exact-head required check uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 env: AUTHORITY_RESULT: ${{ needs.review.result }} + SQUAD_REVIEW_APP_ID: ${{ vars.SQUAD_REVIEW_APP_ID }} + SQUAD_REVIEW_APP_SLUG: ${{ vars.SQUAD_REVIEW_APP_SLUG }} SQUAD_REVIEW_PR: ${{ github.event.pull_request.number }} SQUAD_REVIEW_BASE: ${{ github.event.pull_request.base.sha }} SQUAD_REVIEW_HEAD: ${{ github.event.pull_request.head.sha }} SQUAD_REVIEW_WORKFLOW_SHA: ${{ github.workflow_sha }} with: + github-token: ${{ steps.squad-review-app-token.outputs.token }} script: | const checkName = 'Squad Review / review'; const authorityJob = 'Squad Review Authority / attest'; const repository = process.env.GITHUB_REPOSITORY; const [owner, repo] = repository.split('/'); + const expectedAppId = Number(process.env.SQUAD_REVIEW_APP_ID); + const expectedAppSlug = process.env.SQUAD_REVIEW_APP_SLUG; const pullRequest = Number(process.env.SQUAD_REVIEW_PR); const baseSha = process.env.SQUAD_REVIEW_BASE; const headSha = process.env.SQUAD_REVIEW_HEAD; const workflowSha = process.env.SQUAD_REVIEW_WORKFLOW_SHA; const runId = Number(process.env.GITHUB_RUN_ID); const runAttempt = Number(process.env.GITHUB_RUN_ATTEMPT); - if (!Number.isSafeInteger(pullRequest) || pullRequest < 1 || + if (!Number.isSafeInteger(expectedAppId) || expectedAppId < 1 || + expectedAppId === 15368 || + !/^[a-z0-9][a-z0-9-]*$/.test(expectedAppSlug) || + expectedAppSlug === 'github-actions' || + !Number.isSafeInteger(pullRequest) || pullRequest < 1 || !/^[0-9a-f]{40}$/.test(baseSha) || !/^[0-9a-f]{40}$/.test(headSha) || workflowSha !== baseSha || !Number.isSafeInteger(runId) || runId < 1 || !Number.isSafeInteger(runAttempt) || runAttempt < 1) { @@ -182,7 +212,10 @@ jobs: const existing = await github.paginate(github.rest.checks.listForRef, { owner, repo, ref: headSha, check_name: checkName, per_page: 100, }); - const owned = existing.filter(check => check.external_id === externalId); + const owned = existing.filter(check => + check.external_id === externalId && + check.app?.id === expectedAppId && + check.app?.slug === expectedAppSlug); if (owned.length > 1) { core.setFailed('Duplicate exact-head Squad review authority checks.'); return; @@ -205,6 +238,8 @@ jobs: event: 'pull_request_target', workflow_path: '.github/workflows/squad-review.lock.yml', authority_job: authorityJob, + publisher_app_id: expectedAppId, + publisher_app_slug: expectedAppSlug, }), }; const request = { @@ -215,13 +250,24 @@ jobs: external_id: externalId, output, }; - if (owned.length === 1) { - await github.rest.checks.update({ + const published = owned.length === 1 + ? await github.rest.checks.update({ ...request, check_run_id: owned[0].id, - }); - } else { - await github.rest.checks.create(request); + }) + : await github.rest.checks.create(request); + if (published.data.app?.id !== expectedAppId || + published.data.app?.slug !== expectedAppSlug) { + try { + await github.rest.checks.delete({ + owner, repo, check_run_id: published.data.id, + }); + } finally { + core.setFailed( + 'Squad review check was not published by the configured dedicated GitHub App.' + ); + } + return; } if (!succeeded) { core.setFailed('Base-controlled Squad review authority did not succeed.'); diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 3f851cdc1..7c6ab32ba 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -30,8 +30,8 @@ "source": "workflows/package/squad-review.md", "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", - "source_sha256": "50194fc024e745a4eb432553ceaeab9cde7621bf368984a9c4b03364017a3ae2", - "lock_sha256": "b1a16520aff0409507dd420433a56570b37b993688decd4ef5479c3e8e6d5ab9" + "source_sha256": "27adf384cbe16c11ec89f4ecd76c9087a409c911ab9760575a3254b1d21dfb56", + "lock_sha256": "c3ed91988744077da65cbbc8a77a6d262bf4dca3bbfc593ab520283c3e9ced6b" }, { "name": "squad-deps-worker", @@ -62,8 +62,8 @@ "source": "workflows/package/squad-bootstrap.md", "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", - "source_sha256": "88d6b77f3fbba2742a87c71a508bfab279d6615ac2ce92d9a5a834562df83e97", - "lock_sha256": "1aa405862591145c15c152813127d473f6cbb4d3eddf3d0733c5299001520afe" + "source_sha256": "9df28d8e4094b66e7ddf4aed1ff3626efaa65c1dcd3815984d70573b40af640d", + "lock_sha256": "9a23ee0bd51cd7dd69b91538872a3fce0fb2376423ce8ac56c7c9f6f5b7f4b1b" }, { "name": "squad-command-router", @@ -81,7 +81,7 @@ "package_destination": ".github/workflows/shared/squad-review-guard.mjs", "destination": ".github/workflows/shared/squad-review-guard.mjs", "ownership": "manifest", - "sha256": "541ff7d4add94a81b2d1333327933fc96ea99783e5e5efe571f6e9840c866c7f" + "sha256": "6685f7e16b4ee13958bcdddf2a868a287f76b26913b0c17c4a943b398bbb4938" }, { "path": "shared/squad-install-verifier.mjs", @@ -89,7 +89,7 @@ "package_destination": ".github/workflows/shared/squad-install-verifier.mjs", "destination": ".github/workflows/shared/squad-install-verifier.mjs", "ownership": "manifest", - "sha256": "47b911d3d56821bf8c2f3345ca4394786212cf11d8ed0078ba45324a42e8ec3e" + "sha256": "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" }, { "path": "shared/squad-command-contract.mjs", @@ -217,7 +217,7 @@ "name": "gh-aw-enlistment", "source": "workflows/skills/gh-aw-enlistment/SKILL.md", "destination": ".github/skills/gh-aw-enlistment/SKILL.md", - "sha256": "697f16b5dd4dab722e39c631511b9ba274143b4ec676dbe6d5304f2835f62bfd" + "sha256": "2123f535c9fa5863d85fbed89ec5820579222eb39d279ffe1dea9a79a13fbadb" } ], "bootstrap": { From f7dbff7e37aaf0881de624dff9f85f67e2c4acf3 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 22:34:54 -0700 Subject: [PATCH 10/14] chore: record dedicated review app change Part of #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .changeset/dedicated-review-app.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/dedicated-review-app.md diff --git a/.changeset/dedicated-review-app.md b/.changeset/dedicated-review-app.md new file mode 100644 index 000000000..30e809777 --- /dev/null +++ b/.changeset/dedicated-review-app.md @@ -0,0 +1,6 @@ +--- +"@bradygaster/squad-cli": patch +"@bradygaster/squad-sdk": patch +--- + +Require a dedicated, branch-restricted GitHub App identity for authoritative Squad review checks. From f88755ccc47f86a2ff6cb40a73ff731d218d3914 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 23:29:42 -0700 Subject: [PATCH 11/14] fix(gh-aw): normalize compiler setup pin Closes #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/gh-aw-quality.test.ts | 67 ++++++++++++++++++++- workflows/package/squad-bootstrap.md | 2 +- workflows/shared/squad-install-verifier.mjs | 41 +++++++++++++ workflows/squad-bootstrap.md | 2 +- workflows/squad-workflows.manifest.json | 20 +++--- 5 files changed, 119 insertions(+), 13 deletions(-) diff --git a/test/gh-aw-quality.test.ts b/test/gh-aw-quality.test.ts index 20d47fffa..afa44ba8f 100644 --- a/test/gh-aw-quality.test.ts +++ b/test/gh-aw-quality.test.ts @@ -3630,9 +3630,21 @@ describe('gh-aw: canonical package integrity contract', () => { }); it('normalizes only compiler-declared repository-scattered schedules', () => { - const metadata = `# gh-aw-metadata: {"frontmatter_hash":"${'a'.repeat(64)}"}`; + const setupPin = '924af5fdc64061cfbf66fb584c8b07e2ac230c60'; + const metadata = `# gh-aw-metadata: ${JSON.stringify({ + frontmatter_hash: 'a'.repeat(64), + compiler_version: 'v0.89.21', + })}`; const lock = [ metadata, + `# gh-aw-manifest: ${JSON.stringify({ + actions: [{ + repo: 'github/gh-aw-actions/setup', + sha: setupPin, + version: 'v0.89.21', + }], + })}`, + `uses: github/gh-aw-actions/setup@${setupPin}`, `source_revision: ${revisionA}`, ' - cron: "17 4 * * 2" # Friendly format: weekly on Tuesday at 04:00 (scattered)', ' - cron: "0 4 * * 2" # Fixed schedule', @@ -3646,6 +3658,59 @@ describe('gh-aw: canonical package integrity contract', () => { expect(normalized).not.toContain(revisionA); }); + it('normalizes only the approved gh-aw setup tag to its exact compiler pin', () => { + const setupPin = '924af5fdc64061cfbf66fb584c8b07e2ac230c60'; + const compiled = (setupRef: string, permissions = 'checks: read') => [ + `# gh-aw-metadata: ${JSON.stringify({ + schema_version: 'v4', + frontmatter_hash: 'a'.repeat(64), + body_hash: 'b'.repeat(64), + compiler_version: 'v0.89.21', + strict: true, + })}`, + `# gh-aw-manifest: ${JSON.stringify({ + version: 1, + secrets: ['SQUAD_REVIEW_APP_PRIVATE_KEY'], + actions: [{ + repo: 'github/gh-aw-actions/setup', + sha: setupRef, + version: 'v0.89.21', + }], + })}`, + `# - github/gh-aw-actions/setup@${setupRef}${setupRef === setupPin ? ' # v0.89.21' : ''}`, + `source_revision: ${revisionA}`, + 'permissions:', + ` ${permissions}`, + 'environment: squad-review-authority', + 'github-token: ${{ steps.squad-review-app-token.outputs.token }}', + `uses: github/gh-aw-actions/setup@${setupRef}${setupRef === setupPin ? ' # v0.89.21' : ''}`, + ].join('\n'); + const macOS = normalizeCompiledLock(compiled(setupPin), revisionA); + const linux = normalizeCompiledLock(compiled('v0.89.21'), revisionA); + + expect(linux).toBe(macOS); + expect(linux).toContain(`github/gh-aw-actions/setup@${setupPin}`); + expect(linux).not.toContain('github/gh-aw-actions/setup@v0.89.21'); + expect(() => normalizeCompiledLock(compiled('c'.repeat(40)), revisionA)) + .toThrow(/approved compiler pin/); + expect(normalizeCompiledLock(compiled(setupPin, 'checks: write'), revisionA)) + .not.toBe(macOS); + expect(normalizeCompiledLock( + compiled(setupPin).replace( + 'environment: squad-review-authority', + 'environment: unrestricted', + ), + revisionA, + )).not.toBe(macOS); + expect(normalizeCompiledLock( + compiled(setupPin).replace( + 'github-token: ${{ steps.squad-review-app-token.outputs.token }}', + 'github-token: ${{ github.token }}', + ), + revisionA, + )).not.toBe(macOS); + }); + it('accepts only the deterministic retained bootstrap trigger sentinel', () => { const root = makeConsumer(); const probePath = join(root, TRIGGER_PROBE_DESTINATION); diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index 216ffc9a8..f95e0defd 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -151,7 +151,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" + check_hash "$install_verifier" "09f806f17c7ff2ddd207484a536e13f41071c4ed584ab37be415755979bec1c4" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/shared/squad-install-verifier.mjs b/workflows/shared/squad-install-verifier.mjs index 6b7ad970e..84450d6d3 100644 --- a/workflows/shared/squad-install-verifier.mjs +++ b/workflows/shared/squad-install-verifier.mjs @@ -33,6 +33,9 @@ export const TRIGGER_PROBE_DESTINATION = const SHA256_PATTERN = /^[0-9a-f]{64}$/; const REVISION_PATTERN = /^[0-9a-f]{40}$/; const LOCK_REVISION_PLACEHOLDER = 'f'.repeat(40); +const GH_AW_SETUP_PINS = Object.freeze({ + 'v0.89.21': '924af5fdc64061cfbf66fb584c8b07e2ac230c60', +}); function deepFreeze(value) { if (value && typeof value === 'object' && !Object.isFrozen(value)) { @@ -348,8 +351,46 @@ export function normalizeCompiledLock(content, revision) { /^(# gh-aw-metadata: \{[^\n]*"frontmatter_hash":")([0-9a-f]{64})("[^\n]*\})$/m, ); if (!metadata) throw new Error('Compiled lock has missing or malformed gh-aw metadata.'); + const compilerVersion = JSON.parse(metadata[0].slice('# gh-aw-metadata: '.length)) + .compiler_version; + const setupPin = GH_AW_SETUP_PINS[compilerVersion]; + if (!setupPin) { + throw new Error(`Compiled lock uses unsupported gh-aw compiler version: ${compilerVersion}.`); + } + const manifest = text.match(/^(# gh-aw-manifest: )(\{[^\n]*\})$/m); + if (!manifest) throw new Error('Compiled lock has missing or malformed gh-aw manifest.'); + const manifestValue = JSON.parse(manifest[2]); + const setupActions = manifestValue.actions?.filter( + action => action.repo === 'github/gh-aw-actions/setup', + ) ?? []; + if (setupActions.length !== 1) { + throw new Error('Compiled lock must declare exactly one gh-aw setup action.'); + } + const setupAction = setupActions[0]; + if (setupAction.version !== compilerVersion) { + throw new Error('Compiled lock gh-aw setup action version does not match its compiler.'); + } + if (![compilerVersion, setupPin].includes(setupAction.sha)) { + throw new Error('Compiled lock gh-aw setup action does not match the approved compiler pin.'); + } + setupAction.sha = setupPin; + const setupRefs = [ + ...text.matchAll(/github\/gh-aw-actions\/setup@([^\s#'"]+)/g), + ].map(match => match[1]); + if (setupRefs.some(ref => ![compilerVersion, setupPin].includes(ref))) { + throw new Error('Compiled lock contains an unapproved gh-aw setup action reference.'); + } return text .replace(metadata[0], `${metadata[1]}${'0'.repeat(64)}${metadata[3]}`) + .replace(manifest[0], `${manifest[1]}${JSON.stringify(manifestValue)}`) + .replaceAll( + `github/gh-aw-actions/setup@${compilerVersion}`, + `github/gh-aw-actions/setup@${setupPin}`, + ) + .replaceAll( + `github/gh-aw-actions/setup@${setupPin} # ${compilerVersion}`, + `github/gh-aw-actions/setup@${setupPin}`, + ) .replace( /^(\s*-\s+cron:\s+)"[^"]+"(\s+# Friendly format: .+ \(scattered\))$/gm, '$1""$2', diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index ca9ee3058..535e7e494 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -158,7 +158,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" + check_hash "$install_verifier" "09f806f17c7ff2ddd207484a536e13f41071c4ed584ab37be415755979bec1c4" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 7c6ab32ba..3c93f37d7 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -15,7 +15,7 @@ "destination": ".github/workflows/squad.md", "lock": ".github/workflows/squad.lock.yml", "source_sha256": "bb7f231c852dfb73c5d1a6ba5e9f23f9f7c9fc5af9e1f1021c4c5213fd9389f9", - "lock_sha256": "f2e62f0ded2b937c99dcdab321f1ea2f886ff2f0537a324af4342908466a2bcf" + "lock_sha256": "98b174e188340159ee581b02cf6463d5a0e3ad60ad16c0c59a53133e3ca65b3d" }, { "name": "squad-implement-worker", @@ -23,7 +23,7 @@ "destination": ".github/workflows/squad-implement-worker.md", "lock": ".github/workflows/squad-implement-worker.lock.yml", "source_sha256": "ae710dd5c89360af540576dac378a0d0df129cce5a9bbf16f0615dfd86d0b21c", - "lock_sha256": "d6d2fa7f2bac5845c414cf42a9ea565d3663dba23d9208942fe142fca6b23bc3" + "lock_sha256": "ff1d336b2ee99a51c7b7f1b87dcc03dbcaec069cde5fc962f1da30189a99f9d6" }, { "name": "squad-review", @@ -31,7 +31,7 @@ "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", "source_sha256": "27adf384cbe16c11ec89f4ecd76c9087a409c911ab9760575a3254b1d21dfb56", - "lock_sha256": "c3ed91988744077da65cbbc8a77a6d262bf4dca3bbfc593ab520283c3e9ced6b" + "lock_sha256": "a29203c21a6af2c9ce4dbf838a8d61f0fe39f9d6fe08b371d54167c2f74177a4" }, { "name": "squad-deps-worker", @@ -39,7 +39,7 @@ "destination": ".github/workflows/squad-deps-worker.md", "lock": ".github/workflows/squad-deps-worker.lock.yml", "source_sha256": "37c4ba60b85c5fc07bef322bbfd0f713472924d55cff9481ae76af7ec0c91fac", - "lock_sha256": "d5a8c0b1eb7933bb4bb74499fd9de872b6d55045665f918c831658f8baa20f71" + "lock_sha256": "858c9247b26ff786cca81052ff3c6bb18168e8fb50cd72e8b0e5c4b42bfd38ad" }, { "name": "squad-retro", @@ -47,7 +47,7 @@ "destination": ".github/workflows/squad-retro.md", "lock": ".github/workflows/squad-retro.lock.yml", "source_sha256": "92bcfa39cc5fd3087b11612125e314959237c5b79460825453d1e493727a2562", - "lock_sha256": "00771decb93b93d04ea9c9e6173c2338eef615e49df0a8ca12729680fa15fc52" + "lock_sha256": "03f31bf1cbe276c686ae7899307180b2231e1c0ff25edd1afc40151ec29c105d" }, { "name": "squad-improvement-worker", @@ -55,15 +55,15 @@ "destination": ".github/workflows/squad-improvement-worker.md", "lock": ".github/workflows/squad-improvement-worker.lock.yml", "source_sha256": "01c89f8890f02c0ca884513aa10225787feaf3606ab604d5c0e85fbbccdb6c95", - "lock_sha256": "880b7673b022d6155870d87b70e6d6a2489eb7eefec64fcf3515041d5ca5c42e" + "lock_sha256": "583d505966d9591088c7a482f08d23c410b0c1e6bbf7396ae871c0a87c8ecba6" }, { "name": "squad-bootstrap", "source": "workflows/package/squad-bootstrap.md", "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", - "source_sha256": "9df28d8e4094b66e7ddf4aed1ff3626efaa65c1dcd3815984d70573b40af640d", - "lock_sha256": "9a23ee0bd51cd7dd69b91538872a3fce0fb2376423ce8ac56c7c9f6f5b7f4b1b" + "source_sha256": "de21c6e2baed831a573596d85e2ccdd70a28fe5b1fe275797055c44609a999d0", + "lock_sha256": "b46648d07dae93a51958349a052f85c900eb50075d1c0bbf841234493af93112" }, { "name": "squad-command-router", @@ -71,7 +71,7 @@ "destination": ".github/workflows/squad-command-router.md", "lock": ".github/workflows/squad-command-router.lock.yml", "source_sha256": "cbce466a6cfe64c194b17672ea3363fe7c22cb6b4258c195cc93a2d294d0bf88", - "lock_sha256": "9c5bf2b28dc82a575c528ce73a75c38b54129d512341e10cdce2a6e12ceecb4b" + "lock_sha256": "bb604c0fd7d061e37a5ac9bf1a39d5162e8e149ef25e061d5eee447447c3be1c" } ], "shared_runtime": [ @@ -89,7 +89,7 @@ "package_destination": ".github/workflows/shared/squad-install-verifier.mjs", "destination": ".github/workflows/shared/squad-install-verifier.mjs", "ownership": "manifest", - "sha256": "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" + "sha256": "09f806f17c7ff2ddd207484a536e13f41071c4ed584ab37be415755979bec1c4" }, { "path": "shared/squad-command-contract.mjs", From abb42262167344295917a20482a65903e9bf5f3a Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 28 Sep 2026 23:39:12 -0700 Subject: [PATCH 12/14] fix(ci): align gh-aw compiler pin Closes #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/squad-ci.yml | 2 +- test/gh-aw-quality.test.ts | 74 +++------------------ workflows/package/squad-bootstrap.md | 2 +- workflows/shared/squad-install-verifier.mjs | 41 ------------ workflows/squad-bootstrap.md | 2 +- workflows/squad-workflows.manifest.json | 20 +++--- 6 files changed, 23 insertions(+), 118 deletions(-) diff --git a/.github/workflows/squad-ci.yml b/.github/workflows/squad-ci.yml index add8744d4..a26578d1b 100644 --- a/.github/workflows/squad-ci.yml +++ b/.github/workflows/squad-ci.yml @@ -173,7 +173,7 @@ jobs: # than skipping — a skipped gate is indistinguishable from no gate. This # includes the shell input security contract gate (#1834) and the compile # contract (#1732). - run: gh extension install --pin v0.87.10 github/gh-aw + run: gh extension install --pin v0.89.21 github/gh-aw env: GH_TOKEN: ${{ github.token }} - name: Build diff --git a/test/gh-aw-quality.test.ts b/test/gh-aw-quality.test.ts index afa44ba8f..8a38e7557 100644 --- a/test/gh-aw-quality.test.ts +++ b/test/gh-aw-quality.test.ts @@ -27,6 +27,7 @@ import { import { CONTRACT_DESTINATION, CONTRACT_SOURCE, + MIN_GH_AW_VERSION, OWNERSHIP_ENTRY_COUNT, PACKAGE_NAME, RUNTIME_TUPLES, @@ -3630,21 +3631,9 @@ describe('gh-aw: canonical package integrity contract', () => { }); it('normalizes only compiler-declared repository-scattered schedules', () => { - const setupPin = '924af5fdc64061cfbf66fb584c8b07e2ac230c60'; - const metadata = `# gh-aw-metadata: ${JSON.stringify({ - frontmatter_hash: 'a'.repeat(64), - compiler_version: 'v0.89.21', - })}`; + const metadata = `# gh-aw-metadata: {"frontmatter_hash":"${'a'.repeat(64)}"}`; const lock = [ metadata, - `# gh-aw-manifest: ${JSON.stringify({ - actions: [{ - repo: 'github/gh-aw-actions/setup', - sha: setupPin, - version: 'v0.89.21', - }], - })}`, - `uses: github/gh-aw-actions/setup@${setupPin}`, `source_revision: ${revisionA}`, ' - cron: "17 4 * * 2" # Friendly format: weekly on Tuesday at 04:00 (scattered)', ' - cron: "0 4 * * 2" # Fixed schedule', @@ -3658,57 +3647,14 @@ describe('gh-aw: canonical package integrity contract', () => { expect(normalized).not.toContain(revisionA); }); - it('normalizes only the approved gh-aw setup tag to its exact compiler pin', () => { - const setupPin = '924af5fdc64061cfbf66fb584c8b07e2ac230c60'; - const compiled = (setupRef: string, permissions = 'checks: read') => [ - `# gh-aw-metadata: ${JSON.stringify({ - schema_version: 'v4', - frontmatter_hash: 'a'.repeat(64), - body_hash: 'b'.repeat(64), - compiler_version: 'v0.89.21', - strict: true, - })}`, - `# gh-aw-manifest: ${JSON.stringify({ - version: 1, - secrets: ['SQUAD_REVIEW_APP_PRIVATE_KEY'], - actions: [{ - repo: 'github/gh-aw-actions/setup', - sha: setupRef, - version: 'v0.89.21', - }], - })}`, - `# - github/gh-aw-actions/setup@${setupRef}${setupRef === setupPin ? ' # v0.89.21' : ''}`, - `source_revision: ${revisionA}`, - 'permissions:', - ` ${permissions}`, - 'environment: squad-review-authority', - 'github-token: ${{ steps.squad-review-app-token.outputs.token }}', - `uses: github/gh-aw-actions/setup@${setupRef}${setupRef === setupPin ? ' # v0.89.21' : ''}`, - ].join('\n'); - const macOS = normalizeCompiledLock(compiled(setupPin), revisionA); - const linux = normalizeCompiledLock(compiled('v0.89.21'), revisionA); - - expect(linux).toBe(macOS); - expect(linux).toContain(`github/gh-aw-actions/setup@${setupPin}`); - expect(linux).not.toContain('github/gh-aw-actions/setup@v0.89.21'); - expect(() => normalizeCompiledLock(compiled('c'.repeat(40)), revisionA)) - .toThrow(/approved compiler pin/); - expect(normalizeCompiledLock(compiled(setupPin, 'checks: write'), revisionA)) - .not.toBe(macOS); - expect(normalizeCompiledLock( - compiled(setupPin).replace( - 'environment: squad-review-authority', - 'environment: unrestricted', - ), - revisionA, - )).not.toBe(macOS); - expect(normalizeCompiledLock( - compiled(setupPin).replace( - 'github-token: ${{ steps.squad-review-app-token.outputs.token }}', - 'github-token: ${{ github.token }}', - ), - revisionA, - )).not.toBe(macOS); + it('pins every CI compiler install to the package minimum gh-aw version', () => { + const ci = readText(join(process.cwd(), '.github/workflows/squad-ci.yml')); + const pins = [...ci.matchAll( + /gh extension install(?: --force)? --pin (v[0-9.]+) github\/gh-aw/g, + )].map(match => match[1]); + + expect(pins).toHaveLength(2); + expect(new Set(pins)).toEqual(new Set([MIN_GH_AW_VERSION])); }); it('accepts only the deterministic retained bootstrap trigger sentinel', () => { diff --git a/workflows/package/squad-bootstrap.md b/workflows/package/squad-bootstrap.md index f95e0defd..216ffc9a8 100644 --- a/workflows/package/squad-bootstrap.md +++ b/workflows/package/squad-bootstrap.md @@ -151,7 +151,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "09f806f17c7ff2ddd207484a536e13f41071c4ed584ab37be415755979bec1c4" + check_hash "$install_verifier" "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/shared/squad-install-verifier.mjs b/workflows/shared/squad-install-verifier.mjs index 84450d6d3..6b7ad970e 100644 --- a/workflows/shared/squad-install-verifier.mjs +++ b/workflows/shared/squad-install-verifier.mjs @@ -33,9 +33,6 @@ export const TRIGGER_PROBE_DESTINATION = const SHA256_PATTERN = /^[0-9a-f]{64}$/; const REVISION_PATTERN = /^[0-9a-f]{40}$/; const LOCK_REVISION_PLACEHOLDER = 'f'.repeat(40); -const GH_AW_SETUP_PINS = Object.freeze({ - 'v0.89.21': '924af5fdc64061cfbf66fb584c8b07e2ac230c60', -}); function deepFreeze(value) { if (value && typeof value === 'object' && !Object.isFrozen(value)) { @@ -351,46 +348,8 @@ export function normalizeCompiledLock(content, revision) { /^(# gh-aw-metadata: \{[^\n]*"frontmatter_hash":")([0-9a-f]{64})("[^\n]*\})$/m, ); if (!metadata) throw new Error('Compiled lock has missing or malformed gh-aw metadata.'); - const compilerVersion = JSON.parse(metadata[0].slice('# gh-aw-metadata: '.length)) - .compiler_version; - const setupPin = GH_AW_SETUP_PINS[compilerVersion]; - if (!setupPin) { - throw new Error(`Compiled lock uses unsupported gh-aw compiler version: ${compilerVersion}.`); - } - const manifest = text.match(/^(# gh-aw-manifest: )(\{[^\n]*\})$/m); - if (!manifest) throw new Error('Compiled lock has missing or malformed gh-aw manifest.'); - const manifestValue = JSON.parse(manifest[2]); - const setupActions = manifestValue.actions?.filter( - action => action.repo === 'github/gh-aw-actions/setup', - ) ?? []; - if (setupActions.length !== 1) { - throw new Error('Compiled lock must declare exactly one gh-aw setup action.'); - } - const setupAction = setupActions[0]; - if (setupAction.version !== compilerVersion) { - throw new Error('Compiled lock gh-aw setup action version does not match its compiler.'); - } - if (![compilerVersion, setupPin].includes(setupAction.sha)) { - throw new Error('Compiled lock gh-aw setup action does not match the approved compiler pin.'); - } - setupAction.sha = setupPin; - const setupRefs = [ - ...text.matchAll(/github\/gh-aw-actions\/setup@([^\s#'"]+)/g), - ].map(match => match[1]); - if (setupRefs.some(ref => ![compilerVersion, setupPin].includes(ref))) { - throw new Error('Compiled lock contains an unapproved gh-aw setup action reference.'); - } return text .replace(metadata[0], `${metadata[1]}${'0'.repeat(64)}${metadata[3]}`) - .replace(manifest[0], `${manifest[1]}${JSON.stringify(manifestValue)}`) - .replaceAll( - `github/gh-aw-actions/setup@${compilerVersion}`, - `github/gh-aw-actions/setup@${setupPin}`, - ) - .replaceAll( - `github/gh-aw-actions/setup@${setupPin} # ${compilerVersion}`, - `github/gh-aw-actions/setup@${setupPin}`, - ) .replace( /^(\s*-\s+cron:\s+)"[^"]+"(\s+# Friendly format: .+ \(scattered\))$/gm, '$1""$2', diff --git a/workflows/squad-bootstrap.md b/workflows/squad-bootstrap.md index 535e7e494..ca9ee3058 100644 --- a/workflows/squad-bootstrap.md +++ b/workflows/squad-bootstrap.md @@ -158,7 +158,7 @@ pre-agent-steps: node --check "$path" >/dev/null } # BEGIN GENERATED RESOURCE DIGESTS - check_hash "$install_verifier" "09f806f17c7ff2ddd207484a536e13f41071c4ed584ab37be415755979bec1c4" + check_hash "$install_verifier" "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685" check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad" # END GENERATED RESOURCE DIGESTS diff --git a/workflows/squad-workflows.manifest.json b/workflows/squad-workflows.manifest.json index 3c93f37d7..7c6ab32ba 100644 --- a/workflows/squad-workflows.manifest.json +++ b/workflows/squad-workflows.manifest.json @@ -15,7 +15,7 @@ "destination": ".github/workflows/squad.md", "lock": ".github/workflows/squad.lock.yml", "source_sha256": "bb7f231c852dfb73c5d1a6ba5e9f23f9f7c9fc5af9e1f1021c4c5213fd9389f9", - "lock_sha256": "98b174e188340159ee581b02cf6463d5a0e3ad60ad16c0c59a53133e3ca65b3d" + "lock_sha256": "f2e62f0ded2b937c99dcdab321f1ea2f886ff2f0537a324af4342908466a2bcf" }, { "name": "squad-implement-worker", @@ -23,7 +23,7 @@ "destination": ".github/workflows/squad-implement-worker.md", "lock": ".github/workflows/squad-implement-worker.lock.yml", "source_sha256": "ae710dd5c89360af540576dac378a0d0df129cce5a9bbf16f0615dfd86d0b21c", - "lock_sha256": "ff1d336b2ee99a51c7b7f1b87dcc03dbcaec069cde5fc962f1da30189a99f9d6" + "lock_sha256": "d6d2fa7f2bac5845c414cf42a9ea565d3663dba23d9208942fe142fca6b23bc3" }, { "name": "squad-review", @@ -31,7 +31,7 @@ "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", "source_sha256": "27adf384cbe16c11ec89f4ecd76c9087a409c911ab9760575a3254b1d21dfb56", - "lock_sha256": "a29203c21a6af2c9ce4dbf838a8d61f0fe39f9d6fe08b371d54167c2f74177a4" + "lock_sha256": "c3ed91988744077da65cbbc8a77a6d262bf4dca3bbfc593ab520283c3e9ced6b" }, { "name": "squad-deps-worker", @@ -39,7 +39,7 @@ "destination": ".github/workflows/squad-deps-worker.md", "lock": ".github/workflows/squad-deps-worker.lock.yml", "source_sha256": "37c4ba60b85c5fc07bef322bbfd0f713472924d55cff9481ae76af7ec0c91fac", - "lock_sha256": "858c9247b26ff786cca81052ff3c6bb18168e8fb50cd72e8b0e5c4b42bfd38ad" + "lock_sha256": "d5a8c0b1eb7933bb4bb74499fd9de872b6d55045665f918c831658f8baa20f71" }, { "name": "squad-retro", @@ -47,7 +47,7 @@ "destination": ".github/workflows/squad-retro.md", "lock": ".github/workflows/squad-retro.lock.yml", "source_sha256": "92bcfa39cc5fd3087b11612125e314959237c5b79460825453d1e493727a2562", - "lock_sha256": "03f31bf1cbe276c686ae7899307180b2231e1c0ff25edd1afc40151ec29c105d" + "lock_sha256": "00771decb93b93d04ea9c9e6173c2338eef615e49df0a8ca12729680fa15fc52" }, { "name": "squad-improvement-worker", @@ -55,15 +55,15 @@ "destination": ".github/workflows/squad-improvement-worker.md", "lock": ".github/workflows/squad-improvement-worker.lock.yml", "source_sha256": "01c89f8890f02c0ca884513aa10225787feaf3606ab604d5c0e85fbbccdb6c95", - "lock_sha256": "583d505966d9591088c7a482f08d23c410b0c1e6bbf7396ae871c0a87c8ecba6" + "lock_sha256": "880b7673b022d6155870d87b70e6d6a2489eb7eefec64fcf3515041d5ca5c42e" }, { "name": "squad-bootstrap", "source": "workflows/package/squad-bootstrap.md", "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", - "source_sha256": "de21c6e2baed831a573596d85e2ccdd70a28fe5b1fe275797055c44609a999d0", - "lock_sha256": "b46648d07dae93a51958349a052f85c900eb50075d1c0bbf841234493af93112" + "source_sha256": "9df28d8e4094b66e7ddf4aed1ff3626efaa65c1dcd3815984d70573b40af640d", + "lock_sha256": "9a23ee0bd51cd7dd69b91538872a3fce0fb2376423ce8ac56c7c9f6f5b7f4b1b" }, { "name": "squad-command-router", @@ -71,7 +71,7 @@ "destination": ".github/workflows/squad-command-router.md", "lock": ".github/workflows/squad-command-router.lock.yml", "source_sha256": "cbce466a6cfe64c194b17672ea3363fe7c22cb6b4258c195cc93a2d294d0bf88", - "lock_sha256": "bb604c0fd7d061e37a5ac9bf1a39d5162e8e149ef25e061d5eee447447c3be1c" + "lock_sha256": "9c5bf2b28dc82a575c528ce73a75c38b54129d512341e10cdce2a6e12ceecb4b" } ], "shared_runtime": [ @@ -89,7 +89,7 @@ "package_destination": ".github/workflows/shared/squad-install-verifier.mjs", "destination": ".github/workflows/shared/squad-install-verifier.mjs", "ownership": "manifest", - "sha256": "09f806f17c7ff2ddd207484a536e13f41071c4ed584ab37be415755979bec1c4" + "sha256": "4f385df488cc65165e398e499663c015ce63851cb9c938f4c3dd0af38d25f991" }, { "path": "shared/squad-command-contract.mjs", From 332efec9ba2b37deef9056a1f82a3012637e3a2f Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Tue, 29 Sep 2026 00:05:00 -0700 Subject: [PATCH 13/14] test(ci): enforce structural gh-aw compiler pins Closes #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/gh-aw-quality.test.ts | 149 ++++++++++++++++++++++++++++++++++--- 1 file changed, 139 insertions(+), 10 deletions(-) diff --git a/test/gh-aw-quality.test.ts b/test/gh-aw-quality.test.ts index 8a38e7557..4bd14e33f 100644 --- a/test/gh-aw-quality.test.ts +++ b/test/gh-aw-quality.test.ts @@ -15,6 +15,7 @@ import { tmpdir } from 'node:os'; import { execFileSync, execSync, spawnSync } from 'node:child_process'; import { createHash } from 'node:crypto'; import { minimatch } from 'minimatch'; +import { isMap, isSeq, parseDocument, type YAMLMap } from 'yaml'; import { POSIX_SHELL, NO_POSIX_SHELL_MESSAGE, requirePosixShell } from './posix-shell'; import { createFirstInstallFixture } from './helpers/gh-aw-install-fixture.js'; import { @@ -3515,6 +3516,144 @@ describe('gh-aw: activation roster guard counts only data rows (#1605)', () => { }); }); +describe('gh-aw: CI compiler pin contract', () => { + const ci = readText(join(process.cwd(), '.github/workflows/squad-ci.yml')); + const installs = [ + { + job: 'test', + name: 'Install gh-aw extension', + commands: [`gh extension install --pin ${MIN_GH_AW_VERSION} github/gh-aw`], + }, + { + job: 'gh-aw-compile', + name: `Install gh-aw ${MIN_GH_AW_VERSION} (pinned)`, + commands: [ + `gh extension install --force --pin ${MIN_GH_AW_VERSION} github/gh-aw`, + `test "$(gh aw --version 2>&1 | awk '{print $NF}')" = ${MIN_GH_AW_VERSION}`, + ], + }, + ] as const; + + function assertCompilerPins(source: string): void { + const workflow = parseDocument(source); + expect(workflow.errors).toEqual([]); + const jobs = workflow.get('jobs'); + if (!isMap(jobs)) throw new Error('CI must define jobs'); + const installSteps: Array<{ job: unknown; name: unknown; commands: string[] }> = []; + for (const { key, value } of jobs.items) { + if (!isMap(value)) throw new Error('CI job must be a mapping'); + const steps = value.get('steps'); + if (steps === undefined) continue; // Reusable workflow jobs have no steps. + if (!isSeq(steps)) throw new Error('CI steps must be a sequence'); + for (const step of steps.items) { + if (!isMap(step)) throw new Error('CI step must be a mapping'); + const run = step.get('run'); + if (run === undefined) continue; + if (typeof run !== 'string') throw new Error('CI run must be a string'); + const commands = run.split('\n').map(line => line.replace( + /'[^']*'|"(?:\\.|[^"\\])*"|\\.|(^|\s)#.*$/g, + (token, comment) => comment === undefined ? token : '', + ).trim()).filter(Boolean); + const name = step.get('name'); + // Include named slots even if their install was removed or replaced by output. + // Unexpected install-like scripts fail closed; never accept a shell wrapper + // merely because it contains the pinned command as a substring. + if (installs.some(install => install.name === name) || commands.some(line => + !/^(?:echo|printf)(?:\s+(?:'[^']*'|"[^"$`]*"))+$/.test(line) && + /\bgh\s+(?:extension|ext)\s+install\b.*\bgithub\/gh-aw\b/.test(line))) { + installSteps.push({ job: String(key), name, commands }); + } + } + } + expect(installSteps).toEqual(installs); + } + + function mutateInstall(job: string, change: (step: YAMLMap) => void): string { + const workflow = parseDocument(ci); + const steps = workflow.getIn(['jobs', job, 'steps']); + if (!isSeq(steps)) throw new Error(`Missing steps for ${job}`); + const name = installs.find(install => install.job === job)?.name; + const step = steps.items.find(step => isMap(step) && step.get('name') === name); + if (!isMap(step)) throw new Error(`Missing install step for ${job}`); + change(step); + return workflow.toString(); + } + + it('pins every CI compiler install to the package minimum gh-aw version', () => { + assertCompilerPins(ci); + }); + + it('ignores YAML comments, shell comment lines, and non-run strings', () => { + const workflow = parseDocument(ci); + workflow.setIn(['env', 'INSTALL_EXAMPLE'], 'gh extension install github/gh-aw'); + workflow.addIn(['jobs', 'changes', 'steps'], { + name: installs[0].commands[0], + run: `echo '${installs[0].commands[0]}'\nprintf "%s" "gh extension install github/gh-aw"`, + }); + const source = mutateInstall('test', step => { + step.set('run', `# gh extension install github/gh-aw\n\n${installs[0].commands[0]} # pinned\n`); + step.setIn(['env', 'PIN_EXAMPLE'], installs[1].commands[0]); + }); + assertCompilerPins(`# gh extension install github/gh-aw\n${source}`); + assertCompilerPins(workflow.toString()); + }); + + describe.each(installs)('$job install step', ({ job, commands }) => { + it.each([ + ['unpinned', 'gh extension install github/gh-aw'], + ['wrong version', commands[0].replace(MIN_GH_AW_VERSION, 'v0.0.0')], + ['duplicate command', `${commands[0]}\n${commands[0]}`], + ['comment-only pin', `# ${commands[0]}\ngh extension install github/gh-aw`], + ['inline comment pin', `gh extension install github/gh-aw # ${commands[0]}`], + ['echoed pin', `echo "${commands[0]}"`], + ['shell wrapper', `bash -c '${commands[0]}'`], + ['conditional command', `false && ${commands[0]}`], + ['preceding command', `echo preparing\n${commands[0]}`], + ['appended command', `${commands[0]}; gh extension install github/gh-aw`], + ['heredoc text', `cat <<'INSTALL'\n${commands[0]}\nINSTALL`], + ])('rejects %s', (_label, command) => { + const source = mutateInstall(job, step => { + step.set('run', [command, ...commands.slice(1)].join('\n')); + }); + expect(() => assertCompilerPins(source)).toThrow(); + }); + + it('rejects an install moved to an unexpected step', () => { + const source = mutateInstall(job, step => step.set('name', 'Unexpected install')); + expect(() => assertCompilerPins(source)).toThrow(); + }); + + it('rejects an install moved to an unexpected job', () => { + const workflow = parseDocument(ci); + const original = workflow.getIn(['jobs', job]); + workflow.deleteIn(['jobs', job]); + workflow.setIn(['jobs', 'unexpected-job'], original); + expect(() => assertCompilerPins(workflow.toString())).toThrow(); + }); + + it('rejects a missing install step', () => { + const source = mutateInstall(job, step => step.delete('run')); + expect(() => assertCompilerPins(source)).toThrow(); + }); + + it.each([ + ['duplicate step', job, commands[0]], + ['extra pinned install', 'changes', commands[0]], + ['extra unpinned install', 'changes', 'gh extension install github/gh-aw'], + ['extra wrapped install', 'changes', `bash -c '${commands[0]}'`], + ['extra install after quoted hash', 'changes', `echo "#"; ${commands[0]}`], + ['extra install in output substitution', 'changes', `echo "$(${commands[0]})"`], + ])('rejects %s', (_label, targetJob, command) => { + const workflow = parseDocument(ci); + workflow.addIn(['jobs', targetJob, 'steps'], { + name: 'Extra install', + run: command, + }); + expect(() => assertCompilerPins(workflow.toString())).toThrow(); + }); + }); +}); + describe('gh-aw: canonical package integrity contract', () => { const revisionA = 'a'.repeat(40); const revisionB = 'b'.repeat(40); @@ -3647,16 +3786,6 @@ describe('gh-aw: canonical package integrity contract', () => { expect(normalized).not.toContain(revisionA); }); - it('pins every CI compiler install to the package minimum gh-aw version', () => { - const ci = readText(join(process.cwd(), '.github/workflows/squad-ci.yml')); - const pins = [...ci.matchAll( - /gh extension install(?: --force)? --pin (v[0-9.]+) github\/gh-aw/g, - )].map(match => match[1]); - - expect(pins).toHaveLength(2); - expect(new Set(pins)).toEqual(new Set([MIN_GH_AW_VERSION])); - }); - it('accepts only the deterministic retained bootstrap trigger sentinel', () => { const root = makeConsumer(); const probePath = join(root, TRIGGER_PROBE_DESTINATION); From a6385a7dfddc03cf797cadc0d3ccc095ce686b04 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Tue, 29 Sep 2026 00:43:10 -0700 Subject: [PATCH 14/14] test(ci): reject continued and dynamic compiler installers Closes #2103 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- test/gh-aw-quality.test.ts | 130 +++++++++++++++++++++++++++++++++++-- 1 file changed, 123 insertions(+), 7 deletions(-) diff --git a/test/gh-aw-quality.test.ts b/test/gh-aw-quality.test.ts index 4bd14e33f..5830eb496 100644 --- a/test/gh-aw-quality.test.ts +++ b/test/gh-aw-quality.test.ts @@ -3534,6 +3534,72 @@ describe('gh-aw: CI compiler pin contract', () => { }, ] as const; + // This is a deliberately bounded recognizer, not a general shell parser. + // Unsupported here-documents fail closed; only literal cat-to-stdout is inert. + function shellCommands(run: string): string[] { + const commands: string[] = []; + let command = ''; + let quote = ''; + let wordStart = true; + for (let i = 0; i < run.length; i++) { + const char = run[i]; + if (char === '\\' && quote !== "'") { + const next = run[++i]; + if (next === undefined) throw new Error('Dangling shell escape'); + if (next !== '\n' || quote) { + command += char + next; + wordStart = false; + } + } else if (char === quote) { + quote = ''; + command += char; + } else if (!quote && (char === "'" || char === '"')) { + quote = char; + command += char; + wordStart = false; + } else if (!quote && char === '#' && wordStart) { + while (i + 1 < run.length && run[i + 1] !== '\n') i++; + } else if (!quote && char === '\n') { + const heredoc = command.match(/^cat <<(['"])([A-Za-z_][A-Za-z0-9_]*)\1$/); + if (heredoc) { + const end = run.indexOf(`\n${heredoc[2]}\n`, i); + if (end === -1) throw new Error('Unterminated literal heredoc'); + command += run.slice(i, end + heredoc[2].length + 1); + i = end + heredoc[2].length + 1; + } + if (command.trim()) commands.push(command.trim()); + command = ''; + wordStart = true; + } else { + command += char; + if (!quote) wordStart = /[\s;|&()<>]/.test(char); + } + } + if (quote) throw new Error('Unterminated shell quote'); + if (command.trim()) commands.push(command.trim()); + return commands; + } + + function isInstallerOrAmbiguous(command: string): boolean { + if (/^cat <<(['"])([A-Za-z_][A-Za-z0-9_]*)\1\n[\s\S]*\n\2$/.test(command)) return false; + if (/^(?:echo|printf)(?:\s+(?:'[^']*'|"(?:\\[\s\S]|[^"\\$`])*"))+$/.test(command)) return false; + // Remove word-splicing quotes/escapes for detection only, never for approval. + // A repository operand alone is enough: dynamic command/argument construction + // must not evade detection merely by hiding "gh extension install". + const visible = command.replace(/['"\\]/g, ''); + const syntax = command.replace(/'[^']*'|"(?:\\[\s\S]|[^"\\])*"|\\[\s\S]/g, + token => token.startsWith('"') && /[$`]/.test(token) ? '$' : 'literal'); + const dynamicCommand = '(?![A-Za-z_]\\w*=)[^\\s;&|()]*[$`]'; + return /github\/gh-aw|\bgh\s+(?:extension|ext)\b/.test(visible) || + /\bgh\s+[^\s]*[$`]/.test(visible) || + new RegExp(`(?:^|[;&|(){}\\n])\\s*(?:(?:if|then|else|do|!|command|exec|env|sudo|--?[\\w-]+|[A-Za-z_]\\w*=[^()\\s]+)\\s+)*${dynamicCommand}`).test(syntax) || + new RegExp(`(?:\\$\\(|\`)\\s*${dynamicCommand}`).test(visible) || + /\b(?:command|exec|env|sudo)\s[^;\n]*[$`]/.test(syntax) || + /(?:^|[;&|()\n])\s*(?:eval|source|\.)\s/.test(syntax) || + /\b(?:bash|sh|zsh|ksh)\s+.*(?:-[a-z]*c\b|[$`])/.test(visible) || + /< { const run = step.get('run'); if (run === undefined) continue; if (typeof run !== 'string') throw new Error('CI run must be a string'); - const commands = run.split('\n').map(line => line.replace( - /'[^']*'|"(?:\\.|[^"\\])*"|\\.|(^|\s)#.*$/g, - (token, comment) => comment === undefined ? token : '', - ).trim()).filter(Boolean); + const commands = shellCommands(`${run}\n`); const name = step.get('name'); // Include named slots even if their install was removed or replaced by output. // Unexpected install-like scripts fail closed; never accept a shell wrapper // merely because it contains the pinned command as a substring. - if (installs.some(install => install.name === name) || commands.some(line => - !/^(?:echo|printf)(?:\s+(?:'[^']*'|"[^"$`]*"))+$/.test(line) && - /\bgh\s+(?:extension|ext)\s+install\b.*\bgithub\/gh-aw\b/.test(line))) { + if (installs.some(install => install.name === name) || commands.some(isInstallerOrAmbiguous)) { installSteps.push({ job: String(key), name, commands }); } } @@ -3598,6 +3659,26 @@ describe('gh-aw: CI compiler pin contract', () => { assertCompilerPins(workflow.toString()); }); + it.each([ + ['continued comment', '# gh extension \\\necho "install github/gh-aw"'], + ['single-quoted backslash', "printf '%s' 'gh extension \\\ninstall github/gh-aw'"], + ['double-quoted backslash', 'echo "gh extension \\\ninstall github/gh-aw"'], + ['escaped backslash', String.raw`echo "gh extension \\"`], + ['literal heredoc', "cat <<'INSTALL'\ngh extension \\\ninstall github/gh-aw\nINSTALL"], + ['heredoc quote and comment text', "cat <<'INSTALL'\n' \" # \\\n$(gh extension install github/gh-aw)\nINSTALL"], + ])('ignores inert %s without folding literal text', (_label, run) => { + const workflow = parseDocument(ci); + workflow.addIn(['jobs', 'changes', 'steps'], { name: 'Literal example', run }); + assertCompilerPins(workflow.toString()); + if (!run.startsWith('#')) expect(shellCommands(`${run}\n`)).toEqual([run]); + }); + + it('accepts an unquoted continuation of the standalone approved command', () => { + assertCompilerPins(mutateInstall('test', step => { + step.set('run', installs[0].commands[0].replace('extension ', 'extension \\\n')); + })); + }); + describe.each(installs)('$job install step', ({ job, commands }) => { it.each([ ['unpinned', 'gh extension install github/gh-aw'], @@ -3611,6 +3692,10 @@ describe('gh-aw: CI compiler pin contract', () => { ['preceding command', `echo preparing\n${commands[0]}`], ['appended command', `${commands[0]}; gh extension install github/gh-aw`], ['heredoc text', `cat <<'INSTALL'\n${commands[0]}\nINSTALL`], + ['quoted continuation', `'${commands[0].replace('extension ', 'extension \\\n')}'`], + ['escaped backslash is not continuation', commands[0].replace('extension ', 'extension \\\\\n')], + ['comment backslash is not continuation', commands[0].replace('extension ', 'extension # comment \\\n')], + ['space after backslash is not continuation', commands[0].replace('extension ', 'extension \\ \n')], ])('rejects %s', (_label, command) => { const source = mutateInstall(job, step => { step.set('run', [command, ...commands.slice(1)].join('\n')); @@ -3643,6 +3728,37 @@ describe('gh-aw: CI compiler pin contract', () => { ['extra wrapped install', 'changes', `bash -c '${commands[0]}'`], ['extra install after quoted hash', 'changes', `echo "#"; ${commands[0]}`], ['extra install in output substitution', 'changes', `echo "$(${commands[0]})"`], + ['continued installer', 'changes', 'gh extension \\\ninstall github/gh-aw'], + ['continued command word', 'changes', 'g\\\nh ext\\\nension install github/gh-aw'], + ['continued repository', 'changes', 'gh extension install github/gh-\\\naw'], + ['continued wrapper', 'changes', 'command gh extension \\\ninstall github/gh-aw'], + ['continued conditional', 'changes', 'if true; then gh extension \\\ninstall github/gh-aw; fi'], + ['continued substitution', 'changes', 'echo "$(gh extension \\\ninstall github/gh-aw)"'], + ['backtick substitution', 'changes', 'echo "`gh extension install github/gh-aw`"'], + ['quoted word splicing', 'changes', `g'h' exten"sion" install github/gh-"aw"`], + ['dynamic command', 'changes', 'cli=gh\n"$cli" extension install github/gh-aw'], + ['dynamic arguments', 'changes', 'gh "$verb" "$action" "$repository"'], + ['partly dynamic subcommand', 'changes', 'gh exten"$suffix" "$action" "$repository"'], + ['partly dynamic executable', 'changes', 'g"$suffix" "$verb" "$action" "$repository"'], + ['fully dynamic command', 'changes', '"$INSTALLER"'], + ['dynamic command in group', 'changes', '{ "$INSTALLER"; }'], + ['dynamic command in substitution', 'changes', 'echo "$("$INSTALLER")"'], + ['dynamic command in backticks', 'changes', 'echo "`$INSTALLER`"'], + ['dynamic command after assignment', 'changes', 'ENV=value "$INSTALLER"'], + ['dynamic env wrapper', 'changes', 'env -i "$INSTALLER"'], + ['dynamic wrapper with option operand', 'changes', 'env -u PATH "$INSTALLER"'], + ['dynamic shell wrapper', 'changes', 'bash -c "$INSTALLER"'], + ['eval wrapper', 'changes', 'eval "$INSTALLER"'], + ['unquoted heredoc substitution', 'changes', 'cat < { const workflow = parseDocument(ci); workflow.addIn(['jobs', targetJob, 'steps'], {