paperclip/.github/scripts/get-bot-token.mjs
brandonburr 96feaa331a
feat(commitperclip): add automated PR quality and security gates (#6469)
Fixes #6470

## Thinking Path

> - Paperclip is an open-source AI agent platform receiving a high
volume of community PRs — currently 2,398 open
> - The contributor experience is broken: PRs sit for months with no
feedback, contributors don't know why they're stuck, and maintainers
spend review time on PRs that are missing basics
> - Common problems: no linked issue, no test coverage, incomplete PR
template, manually-edited lockfile — all catchable before human review
> - At the same time, accepting untrusted PRs from unknown contributors
is a real attack surface: malicious packages, secret injection,
tampering with CI scripts, and code touching the sensitive paths from
the April security advisories
> - This PR adds automated gates that run on every PR: quality failures
get a clear comment telling contributors exactly what to fix, security
concerns are silently flagged as draft advisories and block merge via a
pending check run
> - The benefit is a dramatically faster feedback loop for good-faith
contributors and a meaningful security layer for the maintainers
reviewing them

## What Changed

- **`.github/workflows/commitperclip-review.yml`** — new workflow using
`pull_request_target` (runs in base branch context, has secrets, never
executes PR code). Runs quality gates + security gates on every PR
open/update.
- **`.github/dependabot.yml`** — weekly automated dependency
vulnerability PRs for npm and GitHub Actions.
- **`.github/scripts/get-bot-token.mjs`** — generates a short-lived
commitperclip installation token from `COMMITPERCLIP_KEY` secret.
- **`.github/scripts/run-quality-gates.mjs`** — orchestrates 5 quality
gates, posts/updates a single consolidated comment on the PR.
- **`.github/scripts/check-pr-template.mjs`** — validates all 5 required
template sections, Thinking Path depth (≥3 sentences), Model Used not
placeholder.
- **`.github/scripts/check-pr-linked-issue.mjs`** — requires `Fixes
#NNN` or issue URL in PR body.
- **`.github/scripts/check-pr-test-coverage.mjs`** — requires at least
one test file in the diff.
- **`.github/scripts/check-pr-lockfile.mjs`** — blocks manual
`pnpm-lock.yaml` edits (only the refresh bot may change it).
- **`.github/scripts/check-pr-dependencies.mjs`** — informational
comment when new npm packages are added.
- **`.github/scripts/check-pr-security.mjs`** — 6 silent security
checks: secret patterns, CI workflow tampering, build script changes,
supply chain (new packages in lockfile), suspicious test patterns
(outbound network/shell exec/env var reads), and changes to the 9
sensitive path prefixes from the April advisories. When any fire:
creates a draft security advisory + sets `security-review` check to
`in_progress` (blocks merge). When clean: sets `security-review` to
`success`.
- **`actions/dependency-review-action@v4`** — per-PR dependency
vulnerability check (fails if new dep has known CVE).
- **44 unit tests** across all gate modules (`node:test`, no external
deps).

## Verification

Run all unit tests locally:
```bash
node --test .github/scripts/tests/*.test.mjs
```
Expected: 44 pass, 0 fail.

End-to-end: open a PR missing the template, linked issue, and test files
→ commitperclip posts a consolidated comment listing all failures. Open
a PR with all gates satisfied → ` All checks passing` comment posted,
all check runs green.

## Risks

**`pull_request_target` security model:** This workflow runs in base
branch context and has access to secrets. It explicitly checks out `ref:
master` (never PR code) and reads the PR diff via GitHub API only — no
PR code is ever executed. This is the correct pattern for running
secret-bearing checks on fork PRs; deviating from it (e.g. checking out
the PR branch) would be a security vulnerability.

**False positives on security gates:** The sensitive-path gate flags any
PR touching the 9 path prefixes from the April advisories. Legitimate
fixes to those paths will trigger draft advisories. This is intentional
— those paths warrant a human look regardless. The `security-review`
check can be manually resolved by a maintainer once reviewed.

**commitperclip not yet installed:** Until the app is installed on this
repo and the `COMMITPERCLIP_KEY` secret is added, the workflow will fail
on the token generation step. The quality gate comment won't post, but
Dependency Review will still run independently.

## Model Used

Claude Sonnet 4.5, 200k context window, extended thinking enabled, tool
use: read/edit files, bash execution, GitHub API calls

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass (44/44)
- [x] I have added or updated tests where applicable (44 unit tests
across all gate modules)
- [ ] If this change affects the UI, I have included before/after
screenshots (N/A — CI only)
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---

## One-time setup needed from you, Dotta

1. **Install commitperclip app** on this repo:
https://github.com/apps/commitperclip/installations/new
2. **Add `COMMITPERCLIP_KEY`** as a repository secret (Actions →
Secrets) — ask @brandonburr for the key
3. **Add `security_advisories: write` and `checks: write`** to the
commitperclip app permissions (commit-capital org → Settings → Apps →
commitperclip → Permissions)
4. **Install Socket.dev** from GitHub Marketplace for supply chain
scanning
5. **Branch protection** (optional but recommended): require
`commitperclip-review` and `security-review` checks to pass before merge

## Dashboard integration note

The `commitperclip-review` check run result maps cleanly to your PR
triage dashboard. A single filter on your Worker:

```javascript
const gatesCheck = checkRuns.find(r => r.name === 'commitperclip-review');
if (gatesCheck?.conclusion === 'failure') return null; // filter from queue
```

For security flags: `GET
/repos/paperclipai/paperclip/security-advisories?state=draft` — advisory
titles include `PR #NNN` for cross-referencing. PRs with a matching
draft advisory have `security-review` in `in_progress` state (grey
spinner, can't merge via branch protection).

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Devin Foley <devin@devinfoley.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-06-01 09:52:53 -07:00

113 lines
3.7 KiB
JavaScript

#!/usr/bin/env node
/**
* get-bot-token.mjs
* Generates a short-lived GitHub installation token for the commitperclip app.
* Reads COMMITPERCLIP_KEY env var (PEM content of private key).
* Prints the token to stdout.
*
* Also exports: generateJWT(privateKey), ghFetch(path, token, options)
* These are used by all other gate scripts.
*/
import { createSign } from 'node:crypto';
import { fileURLToPath } from 'node:url';
const APP_ID = '3718661';
const OWNER_PATTERN = /^[a-zA-Z0-9_.-]+$/;
const REPO_PATTERN = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/;
export function generateJWT(privateKey) {
const now = Math.floor(Date.now() / 1000);
const payload = { iat: now - 10, exp: now + 60, iss: APP_ID };
const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');
const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
const data = `${header}.${body}`;
const sig = createSign('RSA-SHA256').update(data).sign(privateKey, 'base64url');
return `${data}.${sig}`;
}
export async function ghFetch(path, token, options = {}) {
const res = await fetch(`https://api.github.com${path}`, {
...options,
headers: {
Authorization: `Bearer ${token}`,
Accept: 'application/vnd.github+json',
'X-GitHub-Api-Version': '2022-11-28',
...options.headers,
},
});
const text = await res.text();
if (!res.ok) throw new Error(`GitHub API ${options.method ?? 'GET'} ${path}${res.status}: ${text}`);
return JSON.parse(text);
}
export async function resolveInstallationId(fetchInstallation, token, repo, owner) {
if (repo) {
if (!REPO_PATTERN.test(repo)) {
throw new Error('ERROR: GH_REPO/GITHUB_REPOSITORY must be in owner/repo format.');
}
const installation = await fetchInstallation(`/repos/${repo}/installation`, token);
return installation.id;
}
const installations = await fetchInstallation('/app/installations', token);
if (!installations.length) {
throw new Error(
'ERROR: No installations found for commitperclip. Install URL: https://github.com/apps/commitperclip/installations/new'
);
}
if (owner) {
if (!OWNER_PATTERN.test(owner)) {
throw new Error('ERROR: GITHUB_REPOSITORY_OWNER must be a valid GitHub owner name.');
}
const match = installations.find(
installation => installation.account?.login?.toLowerCase() === owner.toLowerCase()
);
if (match) {
return match.id;
}
}
if (installations.length === 1) {
return installations[0].id;
}
throw new Error(
'ERROR: Multiple commitperclip installations found. Set GH_REPO or GITHUB_REPOSITORY so the correct installation can be selected.'
);
}
async function main() {
const privateKey = process.env.COMMITPERCLIP_KEY;
if (!privateKey) {
console.error('ERROR: COMMITPERCLIP_KEY env var not set.');
console.error('Add to ~/.bash_profile: export COMMITPERCLIP_KEY="$(cat ~/.config/commitperclip/private-key.pem)"');
process.exit(1);
}
const jwt = generateJWT(privateKey);
const repo = process.env.GH_REPO ?? process.env.GITHUB_REPOSITORY;
const owner = process.env.GITHUB_REPOSITORY_OWNER ?? repo?.split('/')[0];
const installationId = await resolveInstallationId(ghFetch, jwt, repo, owner);
const { token } = await ghFetch(
`/app/installations/${installationId}/access_tokens`,
jwt,
{ method: 'POST', headers: { 'Content-Type': 'application/json' } }
);
if (!token) {
console.error('ERROR: Failed to get installation token from GitHub API.');
process.exit(1);
}
process.stdout.write(token);
}
if (process.argv[1] === fileURLToPath(import.meta.url)) {
main().catch(e => { console.error(e.message); process.exit(1); });
}