Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
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
53 changes: 53 additions & 0 deletions .github/workflows/expiry-watch.yml
Original file line number Diff line number Diff line change
@@ -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
4 changes: 3 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <n>` 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/<x>` 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.
Expand Down
61 changes: 58 additions & 3 deletions scripts/lib/checks.ts
Original file line number Diff line number Diff line change
@@ -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';
Expand All @@ -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).
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Expand All @@ -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[] = [];
Expand Down Expand Up @@ -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 },
Expand All @@ -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) },
];
}
14 changes: 11 additions & 3 deletions scripts/validate.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
#!/usr/bin/env tsx
// All checks runnable locally: npm run validate [-- --root <dir>] [-- --base <ref>]
// All checks runnable locally: npm run validate [-- --root <dir>] [-- --base <ref>] [-- --horizon-days <n>]
// Checks 1, 6 (append-only rules), 7 diff against <base> (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';
Expand All @@ -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 {
Expand All @@ -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) {
Expand All @@ -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');
Expand Down
49 changes: 47 additions & 2 deletions test/checks.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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');
});
});
4 changes: 2 additions & 2 deletions test/validate.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
});

Expand Down