Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
94 commits
Select commit Hold shift + click to select a range
cdeadd6
fix(automation): validate Dependabot PRs through a narrow allowlist
dDevAhmed Nov 16, 2026
ccfcfd9
test(automation): add strict Dependabot PR policy helper
dDevAhmed Nov 16, 2026
d8076d5
test(automation): cover Dependabot PR guard allowlist
dDevAhmed Nov 16, 2026
6edd225
docs(automation): document narrow Dependabot PR policy
dDevAhmed Nov 16, 2026
340dba4
fix(automation): restrict action updates to SHA-only changes
dDevAhmed Nov 16, 2026
335989c
test(automation): reject action identity replacement
dDevAhmed Nov 16, 2026
7018c60
docs(automation): clean Dependabot policy formatting
dDevAhmed Nov 16, 2026
50bd76e
style(automation): normalize blank lines in PR guard workflow
dDevAhmed Nov 16, 2026
92cc12e
fix(automation): correct pinned action reference parser
dDevAhmed Nov 16, 2026
d2a6599
fix(automation): bind action updates to same workflow file
dDevAhmed Nov 16, 2026
4c6510f
test(automation): reject Dependabot PRs outside main
dDevAhmed Nov 16, 2026
630ec81
fix(automation): scope Dependabot exception to main
dDevAhmed Nov 16, 2026
096234f
fix(automation): enforce exact Dependabot scope and action identity
dDevAhmed Nov 16, 2026
2a997dd
test(automation): cover strict Dependabot scope boundaries
dDevAhmed Nov 16, 2026
0431485
fix(automation): validate Dependabot base branch
dDevAhmed Nov 16, 2026
b09e10d
style: format Dependabot guard policy tests
dDevAhmed Nov 16, 2026
0a41160
style: align policy test descriptions with formatter
dDevAhmed Nov 16, 2026
6c004c5
style: keep action patch fixtures formatter-friendly
dDevAhmed Nov 16, 2026
b0ca483
style: format pinned action fixtures
dDevAhmed Nov 16, 2026
063d359
style: format action fixture helper
dDevAhmed Nov 16, 2026
531dc3b
style: normalize compact missing-patch fixture
dDevAhmed Nov 16, 2026
059670e
fix(security): bound dependency range parsing
dDevAhmed Nov 16, 2026
05ca49a
test(security): cover oversized dependency range input
dDevAhmed Nov 16, 2026
89ea46b
fix: validate workflow action updates per diff hunk
dDevAhmed Nov 17, 2026
02c5397
fix: correct workflow action patch matcher
dDevAhmed Nov 17, 2026
2025b5e
test: cover sequence actions and identity swaps
dDevAhmed Nov 17, 2026
cb8d997
test: fix workflow patch fixtures
dDevAhmed Nov 17, 2026
0a9ff4b
chore: remove obsolete workflow matcher
dDevAhmed Nov 17, 2026
63c4335
test: assert fail-closed workflow patch rejection
dDevAhmed Nov 17, 2026
a767533
style: format workflow guard assertions
dDevAhmed Nov 17, 2026
50a7ded
style: wrap long policy assertion
dDevAhmed Nov 17, 2026
ee42f75
fix(automation): reject malformed dependency section changes
dDevAhmed Nov 18, 2026
91e3068
test(automation): cover dependency section shape changes
dDevAhmed Nov 18, 2026
77e2e69
test(automation): align malformed-section rejection assertion
dDevAhmed Nov 18, 2026
5491f9d
test(automation): exercise dependency section shape rejection
dDevAhmed Nov 18, 2026
bc17aee
test(automation): reach malformed dependency section shape guard
dDevAhmed Nov 18, 2026
c2a6433
style(tests): format dependency guard assertions
dDevAhmed Nov 18, 2026
480b9e2
fix(automation): tighten dependency and workflow diff validation
dDevAhmed Nov 18, 2026
ceda78b
build(deps): declare yaml parser for workflow guard
dDevAhmed Nov 18, 2026
583dc8f
build(deps): sync yaml parser lockfile declaration
dDevAhmed Nov 18, 2026
ad9a1da
fix(automation): validate action updates against parsed workflow YAML
dDevAhmed Nov 18, 2026
1090dac
fix(automation): supply trusted workflow revisions to bot guard
dDevAhmed Nov 18, 2026
df6be3a
build(deps): avoid adding a parser runtime dependency
dDevAhmed Nov 18, 2026
499eae7
build(deps): keep lockfile aligned without parser dependency
dDevAhmed Nov 18, 2026
3cbb18f
fix(automation): validate pinned action changes outside YAML block sc…
dDevAhmed Nov 18, 2026
1237070
test(automation): validate action updates against workflow source
dDevAhmed Nov 18, 2026
d781ac5
test(automation): cover workflow source and dependency range guards
dDevAhmed Nov 18, 2026
326ce39
fix(automation): validate lockfile changes against updated dependency…
dDevAhmed Nov 18, 2026
70fc062
fix(automation): provide base and head lockfiles to bot guard
dDevAhmed Nov 18, 2026
2df7e81
test(automation): enforce lockfile dependency closure
dDevAhmed Nov 18, 2026
bb07479
test(automation): type lockfile validation fixtures
dDevAhmed Nov 18, 2026
f8dd80e
fix(automation): correct workflow path matcher syntax
dDevAhmed Nov 18, 2026
138d914
fix(automation): verify registry integrity for changed lock entries
dDevAhmed Nov 18, 2026
379ff56
test(automation): reject untrusted lockfile package origins
dDevAhmed Nov 18, 2026
ab4a3fb
fix(automation): reject malformed lockfile package metadata
dDevAhmed Nov 18, 2026
e7c7ba6
style(automation): remove unused lockfile loop variables
dDevAhmed Nov 18, 2026
7609924
test(automation): type lockfile package map fixture
dDevAhmed Nov 18, 2026
1e18354
test(automation): narrow lockfile fixture package access
dDevAhmed Nov 18, 2026
a02787f
fix(automation): exclude quoted YAML scalars from action updates
dDevAhmed Nov 18, 2026
df0b5d0
test(automation): reject quoted scalar action lookalikes
dDevAhmed Nov 18, 2026
70c9709
fix(automation): require semver lockfile package versions
dDevAhmed Nov 18, 2026
28ab628
fix(automation): correct lockfile semver expression
dDevAhmed Nov 18, 2026
2bafee6
test(automation): reject invalid package versions in lock entries
dDevAhmed Nov 18, 2026
efdf59a
style: fix PR guard test formatting
dDevAhmed Nov 18, 2026
62ec466
style: format PR guard policy tests
dDevAhmed Nov 18, 2026
715a7a3
fix(tests): correct Prettier indentation in PR guard tests
dDevAhmed Nov 18, 2026
556a121
fix(tests): format multiline PR guard test callbacks
dDevAhmed Nov 18, 2026
4bfd0e5
fix(security): pin Dependabot guard to PR merge base
dDevAhmed Nov 18, 2026
91c8732
fix(ci): read merge base from compare response
dDevAhmed Nov 18, 2026
1d2e055
chore(ci): export canonical guard test formatting
dDevAhmed Nov 18, 2026
d239ccb
chore(ci): remove temporary formatter export step
dDevAhmed Nov 18, 2026
240ceef
fix(security): validate npm lockfile versions and dependency graph
dDevAhmed Nov 18, 2026
832aa63
test(security): cover npm lockfile graph invariants
dDevAhmed Nov 18, 2026
1b57f71
fix(security): verify lockfile artifacts against npm registry metadata
dDevAhmed Nov 18, 2026
4ae9b45
fix(security): verify Dependabot artifacts against npm registry
dDevAhmed Nov 18, 2026
0284109
build(security): declare YAML parser for guard validation
dDevAhmed Nov 18, 2026
ee02d1d
build(security): lock YAML parser dependency
dDevAhmed Nov 18, 2026
32da847
fix(security): parse workflow YAML and mask only action references
dDevAhmed Nov 18, 2026
6f92f10
fix(security): preserve source offsets when masking YAML action pins
dDevAhmed Nov 18, 2026
f08bf50
test(security): cover YAML action paths and version comments
dDevAhmed Nov 18, 2026
1bea79c
test(security): correct YAML source fixtures
dDevAhmed Nov 18, 2026
25bbcf4
build(security): install trusted YAML parser for guard
dDevAhmed Nov 18, 2026
51ac9d1
fix(security): correct semver range parser escapes
dDevAhmed Nov 18, 2026
fa8f8c8
test(security): assert direct dependency range failure
dDevAhmed Nov 18, 2026
ed39008
test(security): align lockfile rejection assertions
dDevAhmed Nov 18, 2026
de96066
fix(security): validate dev flags for all changed lock entries
dDevAhmed Nov 18, 2026
831c7c0
test(security): model npm dev graph flags in fixtures
dDevAhmed Nov 18, 2026
1b24231
test(security): align lock fixture tarballs with package versions
dDevAhmed Nov 18, 2026
85fae86
fix(security): tolerate absent optional and peer lock edges
dDevAhmed Nov 18, 2026
39fe2cc
fix(security): resolve npm package names from lock paths
dDevAhmed Nov 18, 2026
84aae10
test(security): reject arbitrary workflow comment changes
dDevAhmed Nov 18, 2026
d0eb213
chore(ci): export canonical formatting for guard test
dDevAhmed Nov 18, 2026
9e2ac9a
style(test): apply canonical Prettier formatting
dDevAhmed Nov 18, 2026
64b48ad
chore(ci): remove temporary Prettier export step
dDevAhmed Nov 18, 2026
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
232 changes: 182 additions & 50 deletions .github/workflows/wave-pr-guard.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,23 @@ jobs:
guard:
name: Wave PR scope and ownership
runs-on: ubuntu-latest
timeout-minutes: 5
timeout-minutes: 10
steps:
- name: Checkout trusted base revision
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.base.sha }}
persist-credentials: false

- name: Setup trusted Node.js toolchain
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: '22.13.0'
package-manager-cache: false

- name: Install dependencies from trusted base lockfile
run: npm ci --ignore-scripts --no-audit --no-fund

- name: Validate linked Wave issue and protected scope
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
with:
Expand All @@ -28,58 +43,172 @@ jobs:
core.info('Skipping contributor-only Wave checks for trusted maintainer PR.');
return;
}
const { data: collaborator } = await github.rest.repos.getCollaboratorPermissionLevel({
owner, repo, username: pr.user.login,

const isDependabot = pr.user.login === 'dependabot[bot]';
// Pin the comparison to the event's immutable head SHA. The merge
// base, file list, and file contents must describe the same diff.
const comparison = await github.rest.repos.compareCommitsWithBasehead({
owner,
repo,
basehead: pr.base.ref + '...' + pr.head.sha,
});
const trustedPermissions = new Set(['admin', 'maintain', 'write']);
if (trustedPermissions.has(collaborator.permission)) {
core.info('Skipping contributor-only Wave checks for repository collaborator PR.');
return;
if (!comparison.data.merge_base_commit?.sha) {
throw new Error('Could not establish an immutable PR merge-base comparison');
}
const refs = [...body.matchAll(/(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi)].map((m) => Number(m[1]));
const uniqueRefs = [...new Set(refs)];
if (uniqueRefs.length !== 1) {
core.setFailed('Wave contributor PRs must use exactly one closing reference such as Closes #123.');
return;
}
const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: uniqueRefs[0] });
const labels = new Set(issue.labels.map((label) => label.name));
if (!labels.has('Stellar Wave')) {
core.setFailed('#' + uniqueRefs[0] + ' is not a Stellar Wave issue.');
return;
}
if (issue.state !== 'open') {
core.setFailed('Linked Wave issue is not open.');
return;
const mergeBaseSha = comparison.data.merge_base_commit.sha;
const files = comparison.data.files || [];
if (comparison.data.total_commits > 0 && files.length === 300) {
throw new Error('PR file comparison reached GitHub’s 300-file limit; failing closed');
}
const changedPaths = (file) => [file.previous_filename, file.filename].filter(Boolean);
let labels = new Set();
let linkedIssueNumber = null;

const dependencySection = (issue.body || '').split(/## Dependencies/i)[1] || '';
const dependencyText = dependencySection.split(/\n---|\n## /)[0];
const dependencyIds = [...new Set(dependencyText.match(/SW-\d{3}/g) || [])];
if (dependencyIds.length) {
const openIssues = await github.paginate(github.rest.issues.listForRepo, {
owner, repo, state: 'open', per_page: 100,
if (isDependabot) {
const { classifyDependabotPR } = require('./scripts/pr-guard-policy.cjs');
let basePackage;
let headPackage;
let baseLock;
let headLock;
if (files.some((file) => file.filename === 'package.json')) {
const readJsonAtRef = async (path, ref) => {
const { data } = await github.rest.repos.getContent({
owner, repo, path, ref,
});
if (Array.isArray(data) || data.type !== 'file' || data.encoding !== 'base64') {
throw new Error('Could not read ' + path + ' as a base64 file at ' + ref);
}
return JSON.parse(Buffer.from(data.content, 'base64').toString('utf8'));
};
basePackage = await readJsonAtRef('package.json', mergeBaseSha);
headPackage = await readJsonAtRef('package.json', pr.head.sha);
baseLock = await readJsonAtRef('package-lock.json', mergeBaseSha);
headLock = await readJsonAtRef('package-lock.json', pr.head.sha);
}
const registryMetadata = {};
if (headLock?.packages && baseLock?.packages) {
const changedLockEntries = Object.entries(headLock.packages)
.filter(([path, after]) => path && after && (
!baseLock.packages[path] ||
baseLock.packages[path].version !== after.version
));
if (changedLockEntries.length > 200) {
throw new Error('Too many changed lockfile artifacts to verify safely');
}
for (const [packagePath, entry] of changedLockEntries) {
const segments = packagePath.split('/node_modules/').pop().split('/');
const packageName = segments[0].startsWith('@')
? segments[0] + '/' + (segments[1] || '')
: segments[0];
const version = entry.version;
if (typeof version !== 'string') {
throw new Error('Changed lockfile package has no resolved version');
}
const registryUrl = 'https://registry.npmjs.org/' +
encodeURIComponent(packageName) + '/' + encodeURIComponent(version);
const response = await fetch(registryUrl, {
headers: { accept: 'application/vnd.npm.install-v1+json' },
signal: AbortSignal.timeout(10000),
});
if (!response.ok) {
throw new Error('Could not verify ' + packageName + '@' + version + ' against npm registry');
}
const metadata = await response.json();
if (metadata.name !== packageName || metadata.version !== version) {
throw new Error('npm registry returned mismatched package identity');
}
registryMetadata[packageName + '@' + version] = {
resolved: metadata.dist?.tarball,
integrity: metadata.dist?.integrity,
};
}
}
const workflowContents = {};
for (const file of files.filter((item) => /^\.github\/workflows\//.test(item.filename))) {
const readWorkflowAtRef = async (ref) => {
const { data } = await github.rest.repos.getContent({
owner, repo, path: file.filename, ref,
});
if (Array.isArray(data) || data.type !== 'file' || data.encoding !== 'base64') {
throw new Error('Could not read workflow as a base64 file at ' + ref);
}
return Buffer.from(data.content, 'base64').toString('utf8');
};
workflowContents[file.filename] = {
base: await readWorkflowAtRef(mergeBaseSha),
head: await readWorkflowAtRef(pr.head.sha),
};
}
const decision = classifyDependabotPR({
login: pr.user.login,
title: pr.title,
baseRef: pr.base.ref,
files,
basePackage,
headPackage,
workflowContents,
baseLock,
headLock,
registryMetadata,
});
const openWaveIds = new Set(
openIssues
.filter((item) => !item.pull_request && /^SW-\d{3}\b/.test(item.title))
.map((item) => item.title.match(/^SW-\d{3}/)[0]),
);
const unresolved = dependencyIds.filter((id) => openWaveIds.has(id));
if (unresolved.length) {
core.setFailed('Linked issue still has unresolved dependencies: ' + unresolved.join(', '));
if (!decision.allowed) {
core.setFailed('Dependabot PR rejected by narrow bot policy: ' + decision.reason);
return;
}
core.info('Validated narrowly scoped Dependabot update (' + decision.kind + '). Issue assignment is not required for this bot-only path; CODEOWNERS and required checks remain mandatory.');
} else {
const { data: collaborator } = await github.rest.repos.getCollaboratorPermissionLevel({
owner, repo, username: pr.user.login,
});
const trustedPermissions = new Set(['admin', 'maintain', 'write']);
if (trustedPermissions.has(collaborator.permission)) {
core.info('Skipping contributor-only Wave checks for repository collaborator PR.');
return;
}
}

if (!issue.assignees.some((a) => a.login === pr.user.login)) {
core.setFailed('PR author must be accepted through Drips and assigned to the linked Wave issue before merge.');
return;
const refs = [...body.matchAll(/(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi)].map((m) => Number(m[1]));
const uniqueRefs = [...new Set(refs)];
if (uniqueRefs.length !== 1) {
core.setFailed('Wave contributor PRs must use exactly one closing reference such as Closes #123.');
return;
}
const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: uniqueRefs[0] });
labels = new Set(issue.labels.map((label) => label.name));
if (!labels.has('Stellar Wave')) {
core.setFailed('#' + uniqueRefs[0] + ' is not a Stellar Wave issue.');
return;
}
if (issue.state !== 'open') {
core.setFailed('Linked Wave issue is not open.');
return;
}

const dependencySection = (issue.body || '').split(/## Dependencies/i)[1] || '';
const dependencyText = dependencySection.split(/\n---|\n## /)[0];
const dependencyIds = [...new Set(dependencyText.match(/SW-\d{3}/g) || [])];
if (dependencyIds.length) {
const openIssues = await github.paginate(github.rest.issues.listForRepo, {
owner, repo, state: 'open', per_page: 100,
});
const openWaveIds = new Set(
openIssues
.filter((item) => !item.pull_request && /^SW-\d{3}\b/.test(item.title))
.map((item) => item.title.match(/^SW-\d{3}/)[0]),
);
const unresolved = dependencyIds.filter((id) => openWaveIds.has(id));
if (unresolved.length) {
core.setFailed('Linked issue still has unresolved dependencies: ' + unresolved.join(', '));
return;
}
}

if (!issue.assignees.some((a) => a.login === pr.user.login)) {
core.setFailed('PR author must be accepted through Drips and assigned to the linked Wave issue before merge.');
return;
}
linkedIssueNumber = issue.number;
}

const files = await github.paginate(github.rest.pulls.listFiles, {
owner, repo, pull_number: pr.number, per_page: 100,
});
const protectedPatterns = [
/^\.github\/workflows\//, /^\.github\/CODEOWNERS$/, /^\.changeset\//,
/^docs\/adr\//, /^docs\/architecture\//,
Expand All @@ -88,10 +217,10 @@ jobs:
/^src\/dev\/(?:orchestrator|environment)\.ts$/,
/^(?:package|package-lock)\.json$/, /^SECURITY\.md$/,
];
const protectedFiles = files.map((f) => f.filename)
const protectedFiles = [...new Set(files.flatMap(changedPaths))]
.filter((name) => protectedPatterns.some((pattern) => pattern.test(name)));

const currentNames = new Set(files.map((file) => file.filename));
const currentNames = new Set(files.flatMap(changedPaths));
const openPulls = await github.paginate(github.rest.pulls.list, {
owner, repo, state: 'open', per_page: 100,
});
Expand All @@ -102,7 +231,7 @@ jobs:
owner, repo, pull_number: other.number, per_page: 100,
});
const overlap = otherFiles
.map((file) => file.filename)
.flatMap(changedPaths)
.filter((name) => currentNames.has(name))
.filter((name) =>
protectedPatterns.some((pattern) => pattern.test(name)) ||
Expand All @@ -115,16 +244,19 @@ jobs:
return;
}

if (protectedFiles.length && !labels.has('protected-surface')) {
if (!isDependabot && protectedFiles.length && !labels.has('protected-surface')) {
core.setFailed('PR touches protected surfaces not declared by the linked issue: ' + protectedFiles.join(', '));
return;
}
if (!/##\s+(?:Testing|Tests)/i.test(body)) {
if (!isDependabot && !/##\s+(?:Testing|Tests)/i.test(body)) {
core.setFailed('PR body must include a Testing/Tests section.');
return;
}
if (!/##\s+Security/i.test(body)) {
if (!isDependabot && !/##\s+Security/i.test(body)) {
core.setFailed('PR body must include a Security section.');
return;
}
core.info('Validated Wave issue #' + issue.number + ' for PR #' + pr.number + '.');
core.info(isDependabot
? 'Validated Dependabot PR #' + pr.number + ' with normal conflict, required-check, and code-owner merge controls retained.'
: 'Validated Wave issue #' + linkedIssueNumber + ' for PR #' + pr.number + '.');

11 changes: 11 additions & 0 deletions docs/contributing/repository-ruleset.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,3 +113,14 @@ Before considering the ruleset complete, verify:
Whenever workflow names, job names, CODEOWNERS boundaries, or security policy change, review this document and the actual GitHub ruleset together.

A renamed required job can block all merges if the ruleset still points to the old status-check name. Ruleset changes therefore require the same care as CI/security workflow changes.

## Automated Dependency Pull Requests

Dependabot is exempt only from the contributor-specific Stellar Wave issue/Drips assignment requirements, and only for two narrowly defined update classes:

- npm updates that modify exactly `package.json` and `package-lock.json`, changing existing dependency version ranges only;
- GitHub Actions updates that modify workflow YAML files and change only immutable, 40-character-SHA `uses:` references.

The Contributor PR Guard validates this allowlist and continues to run protected-file overlap detection. It rejects source, migration, release, permission, script, unrelated workflow, and other out-of-scope changes from the bot.

This exception does **not** grant merge permission. Normal CI/security checks, branch protection, CODEOWNERS review, stale-approval dismissal, and conversation resolution remain mandatory. Dependabot PRs must never receive write-token or auto-merge privileges through this exception.
3 changes: 2 additions & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@
"prettier": "3.9.8",
"typescript": "6.0.3",
"typescript-eslint": "8.70.0",
"vitest": "5.0.1"
"vitest": "5.0.1",
"yaml": "2.9.0"
},
"license": "MIT",
"repository": {
Expand Down
Loading
Loading