Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/src/content/docs/guide/gh-aw.md
Original file line number Diff line number Diff line change
Expand Up @@ -1802,6 +1802,24 @@ then reapply them before the final compile. Never customize generated
ownership record, missing source/lock pair, or absent runtime resource and
prints the exact safe recovery commands.

The schema-v2 integrity manifest records two complete compiled lock digests per
workflow: `lock_sha256` for a per-workflow source annotation and
`package_lock_sha256` for a package-root annotation. gh-aw v0.89.21 emits
`bradygaster/squad/workflows@SHA` for direct package includes, but can emit
`bradygaster/squad/workflows/package/<workflow>.md@SHA` when installing dispatched
dependencies. Fresh and forced installs can therefore contain different mixtures.
The verifier selects one digest from the exact, ownership- and source-validated
annotation; it never tries both until one passes. Compiled source comments,
URLs, action pins, permissions and runtime bytes remain integrity-checked.
No additional fields are removed during lock normalization.

This fixes the post-merge installation failure in #2103: the old generator and
local-consumer tests covered only per-workflow annotations, while the native
installer also emitted package-root annotations. The difference was installation
provenance, not the squash commit identity or a generated timestamp. Old manifests
or manifests missing either digest are rejected; upgrade the entire package,
including the verifier and manifest, using the block above.

Use the complete upgrade block even when a failure appears limited to the
first-run bootstrap workflow. Updating only `squad-bootstrap.md` is unsupported
because it can leave its validator or the rest of the workflow set at a
Expand Down
131 changes: 128 additions & 3 deletions test/gh-aw-quality.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,13 @@
TRIGGER_PROBE,
TRIGGER_PROBE_DESTINATION,
WORKFLOW_NAMES,
buildContract,
checkSource,
materializeRuntime,
normalizeCompiledLock,
validateContract,
verifyInstall,
verifyCanonicalManifest,
} from '../workflows/shared/squad-install-verifier.mjs';

const WORKFLOWS_DIR = join(process.cwd(), 'workflows');
Expand Down Expand Up @@ -3780,9 +3782,13 @@
cpSync(join(process.cwd(), source), target);
}

function makeConsumer(revision = revisionA, materialize = true): string {
function makeConsumer(
revision = revisionA,
materialize = true,
sourceBinding: 'workflow' | 'package' | 'mixed' = 'workflow',
): string {
const root = createTestWorkspace('gh-aw-package-contract-');
const install = createFirstInstallFixture(revision);
const install = createFirstInstallFixture(revision, sourceBinding);
copyInto(root, CONTRACT_SOURCE, CONTRACT_DESTINATION);
const contract = JSON.parse(readFileSync(join(process.cwd(), CONTRACT_SOURCE), 'utf8'));
for (const workflow of contract.workflows) {
Expand Down Expand Up @@ -3873,7 +3879,7 @@
expect(readText(join(process.cwd(), workflow.source))).not.toMatch(/^resources:/m);
}
expect(existsSync(join(process.cwd(), 'aw.yml'))).toBe(false);
});
}, 120_000);

it('accepts a coherent consumer with the exact ownership cardinality', () => {
const root = makeConsumer();
Expand All @@ -3885,6 +3891,125 @@
expect(record.files).toHaveLength(OWNERSHIP_ENTRY_COUNT);
});

it.each(['workflow', 'package', 'mixed'] as const)(
'verifies %s source bindings at the immutable squash-merged revision',
sourceBinding => {
const revision = '6ec06cc79230cf71d55b484457e8f11190e20a49';
const root = makeConsumer(revision, true, sourceBinding);
execFileSync('git', ['init', '--quiet'], { cwd: root });
execFileSync('git', ['remote', 'add', 'origin', 'https://github.com/example/squad-consumer.git'], { cwd: root });
execFileSync('gh', ['aw', 'compile', '--strict', '--no-check-update'], { cwd: root, stdio: 'pipe' });
expect(verifyInstall(root, { expectedRevision: revision, strictCompile: true }).failures).toEqual([]);
const contract = JSON.parse(readFileSync(join(root, CONTRACT_DESTINATION), 'utf8'));
const review = contract.workflows.find((entry: { name: string }) => entry.name === 'squad-review');
expect(review.package_lock_sha256).not.toBe(review.lock_sha256);
expect(contract.schema_version).toBe(2);
},
120_000,
);

it('keeps both compiled digest variants stable across equivalent trees with different commit identities', () => {
const trees: string[] = [];
const commits: string[] = [];
for (const message of ['PR head', 'Squash merge']) {
const root = createTestWorkspace('gh-aw-commit-identity-');
cpSync(WORKFLOWS_DIR, join(root, 'workflows'), { recursive: true });
const git = (args: string[]) => execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
git(['init', '--quiet']);
git(['add', 'workflows']);
git(['-c', 'user.name=Contract Test', '-c', 'user.email=test@example.invalid', 'commit', '--quiet', '-m', message]);
trees.push(git(['rev-parse', 'HEAD^{tree}']));
const revision = git(['rev-parse', 'HEAD']);
commits.push(revision);
expect(buildContract(root)).toEqual(JSON.parse(readFileSync(join(root, CONTRACT_SOURCE), 'utf8')));

Check failure on line 3924 in test/gh-aw-quality.test.ts

View workflow job for this annotation

GitHub Actions / test

test/gh-aw-quality.test.ts > gh-aw: canonical package integrity contract > keeps both compiled digest variants stable across equivalent trees with different commit identities

AssertionError: expected { schema_version: 2, …(8) } to deeply equal { schema_version: 2, …(8) } - Expected + Received @@ -161,74 +161,74 @@ { "destination": ".github/workflows/squad.md", "lock": ".github/workflows/squad.lock.yml", "lock_sha256": "85aa7c5cbda5453d71af43897088fc06bdb0771c4ae825d88721c4e12e4feaf1", "name": "squad", - "package_lock_sha256": "99d5bc838fd05c4d4bdf67c7796c0b0888250154ac26fdeb99b101f8f46cb7b3", + "package_lock_sha256": "bf54175720e6e9ab3fe5d5e3054c28f3a69595c95cdf50e56f9b30988158270f", "source": "workflows/package/squad.md", "source_sha256": "e3cc1b34c38d345eb5c843d4c4cf4966d7bbdc8c78c567cd3fe44aa84abd0fe7", }, { "destination": ".github/workflows/squad-implement-worker.md", "lock": ".github/workflows/squad-implement-worker.lock.yml", "lock_sha256": "d6d2fa7f2bac5845c414cf42a9ea565d3663dba23d9208942fe142fca6b23bc3", "name": "squad-implement-worker", - "package_lock_sha256": "3339eb39837e326d32bdf5c0b4bb147987da26f28c06e3e943d2da27f43fe0e6", + "package_lock_sha256": "f3941fa390aaab7d5bc32d83e8c0c07a3a430e7487f664a64b64b0459d91fdf9", "source": "workflows/package/squad-implement-worker.md", "source_sha256": "ae710dd5c89360af540576dac378a0d0df129cce5a9bbf16f0615dfd86d0b21c", }, { "destination": ".github/workflows/squad-review.md", "lock": ".github/workflows/squad-review.lock.yml", "lock_sha256": "944dd43831110142a9bb9832ff38d5eb4c0e4df14347781c869fbbccfc0d901f", "name": "squad-review", - "package_lock_sha256": "c8a3666ef09a340e9f9c06899b49b95c256979ff6c5c99d671e069b7bcfe3b13", + "package_lock_sha256": "73049d813ec84ff574c5088b476f92afc1cbf8181316c3db9b8da730e1f98ff4", "source": "workflows/package/squad-review.md", "source_sha256": "545ba959d0e4cfc0ba4cc507c2ed2c0d4b2044ca3b9e20a746c8b39cdc100bef", }, { "destination": ".github/workflows/squad-deps-worker.md", "lock": ".github/workflows/squad-deps-worker.lock.yml", "lock_sha256": "d5a8c0b1eb7933bb4bb74499fd9de872b6d55045665f918c831658f8baa20f71", "name": "squad-deps-worker", - "package_lock_sha256": "98ab08bc22051ef37070dda04e96b4ada333b093696d94e932ac8bdb5860f44d", + "package_lock_sha256": "bae8df8f7516eb52f7718ed681b72b60355d71d0f8a756ca182f1121358800f8", "source": "workflows/package/squad-deps-worker.md", "source_sha256": "37c4ba60b85c5fc07bef322bbfd0f713472924d55cff9481ae76af7ec0c91fac", }, { "destination": ".github/workflows/squad-retro.md", "lock": ".github/workflows/squad-retro.lock.yml", "lock_sha256": "00771decb93b93d04ea9c9e6173c2338eef615e49df0a8ca12729680fa15fc52", "name": "squad-retro", - "package_lock_sha256": "f9373648d67ce3ef43b941d58cc8ef5d9de1296e85be509e4e0ac0d8788d7b1b", + "package_lock_sha256": "f23c01d5f8268cb5d384c6a5044d29eb501096b4dac8e9e44a0129805e74247b", "source": "workflows/package/squad-retro.md", "source_sha256": "92bcfa39cc5fd3087b11612125e314959237c5b79460825453d1e493727a2562", }, { "destination": ".github/workflows/squad-improvement-worker.md", "lock": ".github/workflows/squad-improvement-worker.lock.yml", "lock_sha256": "880b7673b022d6155870d87b70e6d6a2489eb7eefec64fcf3515041d5ca5c42e", "name": "squad-improvement-worker", - "package_lock_sha256": "c4d2153cb66bc18e4445d31aad19331adaa06788810a51182558510e1867d263", + "package_lock_sha256": "d3b867472f148374d0fa8b7a51c5159adcb1148b94bdf11a1a8a8e2f11e6209c", "source": "workflows/package/squad-improvement-worker.md", "source_sha256": "01c89f8890f02c0ca884513aa10225787feaf3606ab604d5c0e85fbbccdb6c95", }, { "destination": ".github/workflows/squad-bootstrap.md", "lock": ".github/workflows/squad-bootstrap.lock.yml", "lock_sha256": "a21a2a1508b98445d6ab0a3cd28db246af51b1c096e7f702a093c3b4070e9a0a", "name": "sq
for (const sourceBinding of ['workflow', 'package'] as const) {
expect(verifyInstall(makeConsumer(revision, true, sourceBinding), {
expectedRevision: revision,
}).failures).toEqual([]);
}
}
expect(trees[0]).toBe(trees[1]);
expect(commits[0]).not.toBe(commits[1]);
}, 120_000);

function updateOwnedDigest(root: string, destination: string): void {
const path = join(root, '.github/aw/packages/bradygaster-squad-workflows-test.json');
const record = JSON.parse(readFileSync(path, 'utf8'));
const entry = record.files.find((file: { destination: string }) => file.destination === destination);
entry.sha256 = createHash('sha256').update(readFileSync(join(root, destination))).digest('hex');
writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`);
}

it.each(['workflow', 'package'] as const)('rejects %s source and compiled provenance mutations', sourceBinding => {
const source = `${PACKAGE_NAME}${sourceBinding === 'workflow' ? '/package/squad-review.md' : ''}@${revisionA}`;
const sourcePath = '.github/workflows/squad-review.md';
const lockPath = '.github/workflows/squad-review.lock.yml';
const mutations: Array<[string, (text: string) => string]> = [
['wrong owner', text => text.replaceAll('bradygaster/squad', 'attacker/squad')],
['wrong repo', text => text.replaceAll('bradygaster/squad', 'bradygaster/other')],
['wrong package', text => text.replaceAll('/workflows', '/other')],
['wrong workflow', text => text.replaceAll(source, `${PACKAGE_NAME}/package/squad.md@${revisionA}`)],
['wrong revision', text => text.replaceAll(revisionA, revisionB)],
['unexpected suffix', text => text.replaceAll(source, `${source}/extra`)],
['missing annotation', text => text.replace(`source: ${source}\n`, '')],
['duplicate annotation', text => text.replace(`source: ${source}\n`, `source: ${source}\nsource: ${source}\n`)],
];
for (const [label, mutate] of mutations) {
const root = makeConsumer(revisionA, true, sourceBinding);
const original = readFileSync(join(root, sourcePath), 'utf8');
const modified = mutate(original);
expect(modified, label).not.toBe(original);
writeFileSync(join(root, sourcePath), modified);
updateOwnedDigest(root, sourcePath);
expect(verifyInstall(root).failures.join('\n'), label).toMatch(/source binding|digest mismatch/);
}

const lockMutations: Array<[string, (text: string) => string]> = [
...mutations.slice(0, 6),
['wrong URL', text => text.replace('/bradygaster/squad/blob/', '/attacker/squad/blob/')],
['mixed annotation', text => text.replace(`GH_AW_WORKFLOW_SOURCE: "${source}"`, 'GH_AW_WORKFLOW_SOURCE: "unknown"')],
['missing annotation', text => text.replace(` GH_AW_INFO_FRONTMATTER_SOURCE: "${source}"\n`, '')],
['duplicate annotation', text => text.replace(`GH_AW_WORKFLOW_SOURCE: "${source}"`, `GH_AW_WORKFLOW_SOURCE: "${source}"\n GH_AW_WORKFLOW_SOURCE: "${source}"`)],
['action tamper', text => text.replace('uses: actions/github-script@', 'uses: attacker/github-script@')],
['permission tamper', text => text.replace('contents: read', 'contents: write')],
['payload tamper', text => text.replace('await guard.assertClearingReview', 'await guard.skipClearingReview')],
];
for (const [label, mutate] of lockMutations) {
const root = makeConsumer(revisionA, true, sourceBinding);
const original = readFileSync(join(root, lockPath), 'utf8');
const modified = mutate(original);
expect(modified, label).not.toBe(original);
writeFileSync(join(root, lockPath), modified);
expect(verifyInstall(root).failures.length, label).toBeGreaterThan(0);
}

const root = makeConsumer(revisionA, true, sourceBinding);
const other = createFirstInstallFixture(revisionA, sourceBinding === 'workflow' ? 'package' : 'workflow');
writeFileSync(join(root, lockPath), other.consumerFiles.get(lockPath)!);
expect(verifyInstall(root).failures.join('\n')).toContain(`Installed digest mismatch for ${lockPath}`);

Check failure on line 3989 in test/gh-aw-quality.test.ts

View workflow job for this annotation

GitHub Actions / test

test/gh-aw-quality.test.ts > gh-aw: canonical package integrity contract > rejects package source and compiled provenance mutations

AssertionError: expected 'Installed digest mismatch for .github…' to contain 'Installed digest mismatch for .github…' Expected: "Installed digest mismatch for .github/workflows/squad-review.lock.yml" Received: "Installed digest mismatch for .github/workflows/squad.lock.yml: expected 99d5bc838fd05c4d4bdf67c7796c0b0888250154ac26fdeb99b101f8f46cb7b3, observed bf54175720e6e9ab3fe5d5e3054c28f3a69595c95cdf50e56f9b30988158270f." ❯ test/gh-aw-quality.test.ts:3989:53
}, 120_000);

it('rejects old schemas, absent variants, runtime tampering and canonical manifest drift', () => {
const mutations: Array<(contract: any) => void> = [
contract => { contract.schema_version = 1; },
contract => { delete contract.workflows[0].package_lock_sha256; },
contract => { contract.workflows[0].package_lock_sha256 = 'invalid'; },
];
for (const mutate of mutations) {
expect(mutateContract(makeConsumer(), mutate).length).toBeGreaterThan(0);
}
const root = makeConsumer();
const runtime = '.github/workflows/shared/squad-review-guard.mjs';
writeFileSync(join(root, runtime), '// tampered\n');
updateOwnedDigest(root, runtime);
expect(verifyInstall(root).failures.join('\n')).toContain(`Installed digest mismatch for ${runtime}`);

const drift = makeConsumer();
const manifestPath = join(drift, CONTRACT_DESTINATION);
writeFileSync(manifestPath, `${readFileSync(manifestPath, 'utf8')}\n`);
expect(() => verifyCanonicalManifest(process.cwd(), drift)).toThrow(/not byte-identical/);
});

it('normalizes only compiler-declared repository-scattered schedules', () => {
const metadata = `# gh-aw-metadata: {"frontmatter_hash":"${'a'.repeat(64)}"}`;
const lock = [
Expand Down
17 changes: 12 additions & 5 deletions test/helpers/gh-aw-install-fixture.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ interface WorkflowEntry extends ContractEntry {
lock: string;
source_sha256: string;
lock_sha256: string;
package_lock_sha256: string;
}

interface RuntimeEntry extends ContractEntry {
Expand Down Expand Up @@ -99,8 +100,12 @@ export function githubFile(content: Buffer): {
};
}

export function createFirstInstallFixture(revision: string): InstallFixture {
const cached = fixtureCache.get(revision);
export function createFirstInstallFixture(
revision: string,
sourceBinding: 'workflow' | 'package' | 'mixed' = 'workflow',
): InstallFixture {
const cacheKey = `${revision}:${sourceBinding}`;
const cached = fixtureCache.get(cacheKey);
if (cached) return cloneFixture(cached);
const root = process.cwd();
const manifestBytes = readFileSync(resolve(root, CONTRACT_SOURCE));
Expand All @@ -113,10 +118,12 @@ export function createFirstInstallFixture(revision: string): InstallFixture {
mkdirSync(workflowRoot, { recursive: true });
cpSync(resolve(root, 'workflows/shared'), resolve(workflowRoot, 'shared'), { recursive: true });

for (const entry of manifest.workflows as WorkflowEntry[]) {
for (const [index, entry] of (manifest.workflows as WorkflowEntry[]).entries()) {
const canonical = readFileSync(resolve(root, entry.source));
canonicalFiles.set(entry.source, canonical);
const installed = withSource(canonical, entry.source, revision);
const source = sourceBinding === 'package' || (sourceBinding === 'mixed' && index % 2 === 0)
? 'workflows' : entry.source;
const installed = withSource(canonical, source, revision);
consumerFiles.set(entry.destination, installed);
const path = resolve(scratch, entry.destination);
mkdirSync(dirname(path), { recursive: true });
Expand Down Expand Up @@ -169,7 +176,7 @@ export function createFirstInstallFixture(revision: string): InstallFixture {
consumerFiles,
canonicalFiles,
};
fixtureCache.set(revision, fixture);
fixtureCache.set(cacheKey, fixture);
return cloneFixture(fixture);
} finally {
rmSync(scratch, { recursive: true, force: true });
Expand Down
2 changes: 1 addition & 1 deletion workflows/package/squad-bootstrap.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ pre-agent-steps:
node --check "$path" >/dev/null
}
# BEGIN GENERATED RESOURCE DIGESTS
check_hash "$install_verifier" "71418638e37a53f570b13919bf5b232f5999be217dac4efc6b76e91918f85f16"
check_hash "$install_verifier" "7e4d2cd8402b2f3ec5cd8b9edbc3ef530a71e03f5d9621464b4afae65366b8b5"
check_hash "$cast_validator" "0988e04aeef316f4d7a0107c902bbbcf6538b8899b9fffba5f62150717967685"
check_hash "$bootstrap_validator" "d449b9204f7fad133ff7133c1a30c9381c87e3c0c9d481352819ca93ea1a1dad"
# END GENERATED RESOURCE DIGESTS
Expand Down
Loading
Loading