diff --git a/.github/workflows/expiry-watch.yml b/.github/workflows/expiry-watch.yml new file mode 100644 index 0000000..cc6394d --- /dev/null +++ b/.github/workflows/expiry-watch.yml @@ -0,0 +1,53 @@ +# Expiry watch (#133): the security.txt `Expires` date and the PGP key lapse silently, so this +# runs the same validate checks daily with a 5-day horizon and keeps exactly one issue open +# while anything is due. No calendar entries — the tracker is the reminder. Read-only otherwise. +name: expiry-watch + +on: + schedule: + - cron: '17 6 * * *' + workflow_dispatch: + +permissions: + contents: read + issues: write + +jobs: + watch: + name: expiry-watch + runs-on: ubuntu-26.04 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version-file: .nvmrc + cache: npm + + - run: npm ci + + - name: expiry checks (5-day horizon) + id: check + run: | + set +e + npm run validate -- --base HEAD --horizon-days 5 > report.txt 2>&1 + echo "status=$?" >> "$GITHUB_OUTPUT" + cat report.txt + + - name: open, refresh or close the tracking issue + env: + GH_TOKEN: ${{ github.token }} + STATUS: ${{ steps.check.outputs.status }} + run: | + title="Security contact expiry due within 5 days" + number=$(gh issue list --state open --label type:chore --search "in:title \"$title\"" --json number --jq '.[0].number // empty') + if [ "$STATUS" = "0" ]; then + [ -n "$number" ] && gh issue close "$number" --comment "Renewed: the expiry checks pass again." + exit 0 + fi + body=$(printf 'The daily expiry watch found something due or already lapsed. Renew it in place (security.txt `Expires`, or extend and republish the key in `.well-known/pgp-security.asc`); the issue closes itself on the next green run.\n\n```\n%s\n```\n' "$(grep -E '^(FAIL| )' report.txt)") + if [ -n "$number" ]; then + gh issue edit "$number" --body "$body" + else + gh issue create --title "$title" --label type:chore --body "$body" + fi diff --git a/CLAUDE.md b/CLAUDE.md index 232c7d3..f08f8e0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -116,7 +116,9 @@ section for the full explanation). code): `pgp-security.asc` (public key only — never a private one) and `security.txt` (RFC 9116). The worker types them and caps their cache at a day. An unnumbered validate check fails the build when `Expires` is missing, past, or over a year out — renew it in place, it is - not under `published/`. **Nothing emitted into `site/` may start with a dot**: + not under `published/`. A sibling `pgp-key` check (needs `gpg`) fails on an expired, revoked, or + unparseable key. `--horizon-days ` makes both fail n days early; `expiry-watch.yml` runs that daily + (5 days) and keeps one `type:chore` issue open while anything is due (#133) — no calendar entries. **Nothing emitted into `site/` may start with a dot**: `upload-pages-artifact` tars with `--exclude=.[^/]*`, so the build writes `site/well-known/` and the Worker rewrites `/.well-known/` onto it (#110). A build test asserts the site is dot-free, and `deploy.yml` smoke-tests after deploying — a green deploy alone proved nothing. diff --git a/scripts/lib/checks.ts b/scripts/lib/checks.ts index 872ea12..67db4d0 100644 --- a/scripts/lib/checks.ts +++ b/scripts/lib/checks.ts @@ -1,3 +1,4 @@ +import { execFileSync } from 'node:child_process'; import { readFileSync } from 'node:fs'; import { dirname, join } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -15,6 +16,7 @@ const addFormats = (addFormatsModule as unknown as { default?: typeof addFormats const SCHEMA_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'schema', 'dictionary-entry.schema.json'); /** RFC 9116 recommends an expiry under a year; past it, tooling treats the contact as stale. */ const SECURITY_TXT_MAX_MONTHS = 12; +const DAY_MS = 86_400_000; /** * Internal references that must be version-pinned to a published file (R5, plan §2.3). @@ -187,7 +189,7 @@ export function checkPinning(repo: RepoModel): ValidationIssue[] { * it as an unmonitored contact — and a static file rots silently, so the ratchet (plan §2.7) * turns "remember to renew it" into a check that refuses the next PR instead. */ -export function checkSecurityTxt(root: string, now: Date = new Date()): ValidationIssue[] { +export function checkSecurityTxt(root: string, now: Date = new Date(), horizonDays = 0): ValidationIssue[] { const check = 'security.txt'; const file = '.well-known/security.txt'; const path = join(root, file); @@ -213,6 +215,8 @@ export function checkSecurityTxt(root: string, now: Date = new Date()): Validati issues.push({ check, file, message: `Expires "${expires}" is not a valid timestamp` }); } else if (at <= now) { issues.push({ check, file, message: `Expires ${at.toISOString()} has passed — renew it; an expired security.txt reads as an unmonitored contact` }); + } else if (at.getTime() <= now.getTime() + horizonDays * DAY_MS) { + issues.push({ check, file, message: `Expires ${at.toISOString()}, within the ${horizonDays}-day horizon — renew it before it lapses` }); } else { const ceiling = new Date(now); ceiling.setMonth(ceiling.getMonth() + SECURITY_TXT_MAX_MONTHS); @@ -232,6 +236,56 @@ export function checkSecurityTxt(root: string, now: Date = new Date()): Validati return issues; } +/** + * Expiry of the published PGP key (#133). Takes `gpg --with-colons` output so the logic is pure + * and testable; `checkPgpKey` is the thin wrapper that shells out. A primary key or subkey that + * is revoked, expired, or inside the horizon is reported; a key with no expiry is fine. + */ +export function pgpKeyExpiryIssues(colons: string, now: Date, horizonDays = 0): string[] { + const messages: string[] = []; + let keys = 0; + for (const line of colons.split('\n')) { + const f = line.split(':'); + if (f[0] !== 'pub' && f[0] !== 'sub') continue; + keys++; + const label = `${f[0] === 'pub' ? 'primary key' : 'subkey'} ${f[4]}`; + if (f[1] === 'r') { + messages.push(`${label} is revoked`); + continue; + } + if (f[6] === '') continue; + const at = new Date(Number(f[6]) * 1000); + if (at <= now) messages.push(`${label} expired ${at.toISOString()} — publish a renewed key`); + else if (at.getTime() <= now.getTime() + horizonDays * DAY_MS) { + messages.push(`${label} expires ${at.toISOString()}, within the ${horizonDays}-day horizon — extend it and republish`); + } + } + if (keys === 0) messages.push('contains no parseable public key'); + return messages; +} + +export function checkPgpKey(root: string, now: Date = new Date(), horizonDays = 0): ValidationIssue[] { + const check = 'pgp-key'; + const file = '.well-known/pgp-security.asc'; + const path = join(root, file); + try { + readFileSync(path); + } catch { + return []; // absent is fine, as for security.txt + } + let colons: string; + try { + colons = execFileSync('gpg', ['--batch', '--no-tty', '--show-keys', '--with-colons', path], { + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'pipe'], + }); + } catch (err) { + const missing = (err as NodeJS.ErrnoException).code === 'ENOENT'; + return [{ check, file, message: missing ? 'gpg is not installed, so the key cannot be checked' : 'gpg could not read the key' }]; + } + return pgpKeyExpiryIssues(colons, now, horizonDays).map((message) => ({ check, file, message })); +} + /** Check 1 — immutability (R6): only additions are allowed under published/. */ export function checkImmutability(diff: DiffEntry[]): ValidationIssue[] { const issues: ValidationIssue[] = []; @@ -312,7 +366,7 @@ export interface CheckResult { * Run all validate.ts checks (1–6, plus the unnumbered security.txt guard). Checks 1 and 6 need * a git context. Check 7 (two-yes gate) lives in CI only. */ -export function runChecks(repo: RepoModel, git?: GitContext): CheckResult[] { +export function runChecks(repo: RepoModel, git?: GitContext, horizonDays = 0): CheckResult[] { const noGit = 'no git context (base unresolvable or root is not a work-tree top level)'; return [ { name: 'load', issues: repo.errors }, @@ -328,6 +382,7 @@ export function runChecks(repo: RepoModel, git?: GitContext): CheckResult[] { : { name: 'check 6 — move purity', issues: [], skipped: noGit }, // Deliberately unnumbered: 1–6 are the entry rules and 7 is the CI two-yes gate. This one // guards the repo's own security contact, not the dictionary (#109). - { name: 'security.txt — RFC 9116 freshness', issues: checkSecurityTxt(repo.root) }, + { name: 'security.txt — RFC 9116 freshness', issues: checkSecurityTxt(repo.root, new Date(), horizonDays) }, + { name: 'pgp-key — expiry', issues: checkPgpKey(repo.root, new Date(), horizonDays) }, ]; } diff --git a/scripts/validate.ts b/scripts/validate.ts index fe96de5..3e54f01 100644 --- a/scripts/validate.ts +++ b/scripts/validate.ts @@ -1,5 +1,5 @@ #!/usr/bin/env tsx -// All checks runnable locally: npm run validate [-- --root ] [-- --base ] +// All checks runnable locally: npm run validate [-- --root ] [-- --base ] [-- --horizon-days ] // Checks 1, 6 (append-only rules), 7 diff against (default: main; CI passes the // PR base SHA). Check 8 (two-yes gate) lives in pr-checks.yml — it needs the GitHub API. import { pathToFileURL } from 'node:url'; @@ -9,6 +9,8 @@ import { createGitContext, isGitContext } from './lib/git.ts'; export interface ValidateOptions { base?: string; + /** Also fail expiry checks that fall due within this many days (the scheduled watch uses it). */ + horizonDays?: number; } export interface ValidationRun { @@ -25,7 +27,7 @@ export function runValidation(root: string, options: ValidateOptions = {}): Vali if (!git) lines.push(`note ${(ctx as { unavailable: string }).unavailable}`); let ok = true; - for (const { name, issues, skipped } of runChecks(repo, git)) { + for (const { name, issues, skipped } of runChecks(repo, git, options.horizonDays)) { if (skipped) { lines.push(`skip ${name} — ${skipped}`); } else if (issues.length === 0) { @@ -48,7 +50,13 @@ function main(): void { const args = process.argv.slice(2); const root = flagValue(args, '--root') ?? process.cwd(); const base = flagValue(args, '--base'); - const { ok, lines } = runValidation(root, { base }); + const horizon = flagValue(args, '--horizon-days'); + const horizonDays = horizon === undefined ? undefined : Number(horizon); + if (horizonDays !== undefined && !(horizonDays >= 0)) { + console.error(`validate: --horizon-days must be a non-negative number, got "${horizon}"`); + process.exit(2); + } + const { ok, lines } = runValidation(root, { base, horizonDays }); for (const line of lines) console.log(line); if (!ok) { console.error('\nvalidate: FAILED'); diff --git a/test/checks.test.ts b/test/checks.test.ts index 9185790..aeb83cd 100644 --- a/test/checks.test.ts +++ b/test/checks.test.ts @@ -3,7 +3,7 @@ import assert from 'node:assert/strict'; import { dirname, join } from 'node:path'; import { fileURLToPath } from 'node:url'; import { loadRepo, type RepoModel, type ValidationIssue } from '../scripts/lib/repo.ts'; -import { checkSchema, checkIdentity, checkReplaces, checkPinning, checkSecurityTxt, runChecks } from '../scripts/lib/checks.ts'; +import { checkSchema, checkIdentity, checkReplaces, checkPinning, checkSecurityTxt, checkPgpKey, pgpKeyExpiryIssues, runChecks } from '../scripts/lib/checks.ts'; import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; @@ -90,7 +90,7 @@ test('check 5 — isDefinedBy and replaces are exempt from pinning', () => { test('runChecks aggregates load errors and all checks 1–6', () => { const results = runChecks(load('red-yaml')); - assert.equal(results.length, 8); + assert.equal(results.length, 9); const loadResult = results.find((r) => r.name === 'load'); assert.ok(loadResult && loadResult.issues.length === 1); const failing = results.filter((r) => r.issues.length > 0); @@ -177,3 +177,48 @@ test('security.txt — an Encryption URL pointing at a key we do not ship fails' assert.match(issues[0].message, /pgp-security\.asc, which is not present/); }); }); + +// ------------------------------------------------------------------ expiry watch (#133) + +test('security.txt — an expiry inside the horizon fails, outside it passes', () => { + withRoot({ 'security.txt': GOOD.replace('2027-06-01', '2026-10-01'), 'pgp-security.asc': 'x' }, (root) => { + assert.deepEqual(checkSecurityTxt(root, NOW), []); + const issues = checkSecurityTxt(root, NOW, 60); + assert.equal(issues.length, 1); + assert.match(issues[0].message, /within the 60-day horizon/); + assert.deepEqual(checkSecurityTxt(root, NOW, 10), []); + }); +}); + +const epoch = (iso: string): number => Date.parse(iso) / 1000; +const keyLines = (primary: string, sub: string, validity = 'u'): string => + `pub:${validity}:4096:1:AAAA:1:${primary}:::u:::scESC::::::23::0:\nfpr:::::::::FFFF:\nsub:${validity}:4096:1:BBBB:1:${sub}:::::e::::::23:\n`; + +test('pgp key — healthy, no-expiry, and horizon cases', () => { + const healthy = keyLines(String(epoch('2028-06-01')), String(epoch('2028-06-01'))); + assert.deepEqual(pgpKeyExpiryIssues(healthy, NOW, 60), []); + assert.deepEqual(pgpKeyExpiryIssues(keyLines('', ''), NOW, 60), []); + const soon = keyLines(String(epoch('2028-06-01')), String(epoch('2026-10-01'))); + assert.deepEqual(pgpKeyExpiryIssues(soon, NOW), []); + const messages = pgpKeyExpiryIssues(soon, NOW, 60); + assert.equal(messages.length, 1); + assert.match(messages[0], /subkey BBBB expires .* within the 60-day horizon/); +}); + +test('pgp key — expired, revoked and unparseable keys fail', () => { + const expired = keyLines(String(epoch('2026-09-01')), String(epoch('2028-06-01'))); + assert.match(pgpKeyExpiryIssues(expired, NOW)[0], /primary key AAAA expired/); + assert.match(pgpKeyExpiryIssues(keyLines('', '', 'r'), NOW)[0], /primary key AAAA is revoked/); + assert.deepEqual(pgpKeyExpiryIssues('', NOW), ['contains no parseable public key']); +}); + +test('pgp key — the repo\'s own key passes today; absent and garbage files behave', () => { + const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..'); + assert.deepEqual(checkPgpKey(repoRoot, new Date()), []); + assert.deepEqual(checkPgpKey(join(fixtures, 'green'), NOW), []); + withRoot({ 'pgp-security.asc': 'not a key' }, (root) => { + const issues = checkPgpKey(root, NOW); + assert.equal(issues.length, 1); + assert.equal(issues[0].file, '.well-known/pgp-security.asc'); + }); +}); diff --git a/test/validate.test.ts b/test/validate.test.ts index 5a67e83..3c14db6 100644 --- a/test/validate.test.ts +++ b/test/validate.test.ts @@ -10,9 +10,9 @@ test('runValidation reports OK for the green tree', () => { const { ok, lines } = runValidation(join(fixtures, 'green')); assert.equal(ok, true); assert.equal(lines.filter((l) => l.startsWith('FAIL')).length, 0); - // load + checks 2–5 + the security.txt guard pass (a fixture tree carries none, which is + // load + checks 2–5 + the security.txt and PGP key guards pass (a fixture tree carries none, which is // green); checks 1 and 6 are skipped (fixture trees have no git context) - assert.equal(lines.filter((l) => l.startsWith('ok')).length, 6); + assert.equal(lines.filter((l) => l.startsWith('ok')).length, 7); assert.equal(lines.filter((l) => l.startsWith('skip')).length, 2); });