create-website-build-kit 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Scaffold a production marketing site \u2014 Astro on Cloudflare Workers, with the gates, the migration playbook and the accessibility work already wired.",
   "keywords": [
     "astro",

package/template/CLAUDE.md

@@ -109,6 +109,13 @@ One shipped as body copy on a service page — *"⚠ CONFIRM: the old site adver
 Saturday at 9am…"* — past clean types, clean axe and clean tells. **The question is usually real:
 move it to `BUILD-STATE.md`, do not just delete it.**
 
+**`npm audit` reports a high, and it cannot be fixed.** One advisory, in accessibility *testing*
+tooling — `pa11y-ci → puppeteer → @puppeteer/browsers → extract-zip` — with **no patched version
+published**. Production dependencies report **zero**, nothing under `src/` imports it, and a
+production install does not pull it. `docs/dependencies.md` carries the chain, the three reasons
+it cannot be fixed here, and the wording to give a client who asks. Do not answer that question
+from memory, and never claim the site has "no vulnerabilities".
+
 **Evidence, not assertions.** `npm run a11y:evidence` writes a dated pack to
 `docs/a11y-evidence/` — commit it. It fills in the machine half and leaves the keyboard,
 screen-reader and forms passes **blank**, because no tool does those; a pack with them still

package/template/docs/dependencies.md

@@ -0,0 +1,102 @@
+# Why `npm audit` reports a high, and why it is not fixed
+
+Run `npm audit` on this site and it reports **high-severity findings that nothing can fix
+today**. That is expected, it is documented here rather than left to be rediscovered, and the
+answer to give a client who asks is at the bottom.
+
+Check it yourself before reading further:
+
+```bash
+npm audit --omit=dev     # production dependencies only
+npm audit                # everything, including build tooling
+```
+
+## The short version
+
+| | |
+| --- | --- |
+| Production dependencies | **0 findings** — nothing that reaches a built page is affected |
+| Development tooling | 1 advisory, reported by `npm audit` as several rows |
+| Advisory | [GHSA-jmr9-qjv8-65gv] — `extract-zip` unvalidated symlink path traversal, CVSS **8.1** |
+| Patched version | **none exists** |
+| Reachable from the site | **no** — nothing under `src/` imports it |
+
+⚠ **`npm audit` and GitHub disagree on the count, and both are right.** `npm audit` prints one
+row per affected package in the chain; GitHub's Dependabot prints one per *advisory*. Six rows,
+one problem. Do not read the larger number as six separate holes.
+
+## Where it comes from
+
+Accessibility testing is the whole chain. Each step declares the next:
+
+```
+pa11y-ci  →  pa11y ^9.1.1  →  puppeteer ^24.37.5  →  @puppeteer/browsers 2.13.2  →  extract-zip ^2.0.1
+```
+
+`extract-zip` is what unpacks the Chrome build that puppeteer downloads the first time you run
+`npm run a11y`.
+
+## Why it cannot be fixed here
+
+Three reasons, each checkable:
+
+1. **There is no patched release, and no version to override to.** The advisory's
+   `first_patched_version` is empty — but that is the advisory's word for it, so check the
+   registry instead: `npm view extract-zip versions` ends at **2.0.1**, which *is* the vulnerable
+   version. Nothing above it has ever been published, and the last release was **2023-03-04**.
+   An `overrides` entry in `package.json` is the usual escape hatch for a transitive pin; here
+   there is nothing to point it at.
+2. **`npm audit fix` changes nothing.** It reports `+0 ~0 -0 packages`. Confirm with
+   `npm audit fix --dry-run`.
+3. **`puppeteer` pins `@puppeteer/browsers` at an exact `2.13.2`**, not a range. Even forcing a
+   resolution cannot move it without replacing puppeteer itself, and `pa11y-ci` is already at
+   its latest release.
+
+The fix has to come from upstream. Until it does, the honest position is a documented known,
+not a silent one.
+
+## Why the exposure is not what the score suggests
+
+**CVSS 8.1 describes the vulnerability, not our exposure to it.** Exploiting it means feeding
+the extractor a malicious archive — in practice, a compromised Chrome download. That requires
+an attacker who already controls the archive puppeteer fetches, and the vector is marked as
+requiring user interaction.
+
+More to the point:
+
+- It is a **development** dependency. It is not bundled, imported, or served.
+- **Nothing under `src/` references pa11y or puppeteer.** Only three scripts do —
+  `check-a11y.mjs`, `a11y-evidence.mjs` and `md-to-pdf.mjs` — and none of them run in a
+  deploy.
+- A production install (`npm ci --omit=dev`) does not install it at all.
+
+⚠ **This is a reason it is low risk, not a reason it is fine.** If you ever start running the
+a11y scripts on untrusted input, or in CI with credentials worth stealing, re-evaluate rather
+than re-reading this paragraph.
+
+## What to tell a client who asks
+
+> The audit finding is in accessibility *testing* tooling, not in the website. It is not part
+> of what gets deployed, and the live site does not contain it. There is currently no fixed
+> version published by its maintainers; when there is, it will be picked up on the next
+> dependency update. The site's production dependencies report no findings.
+
+Every clause there is checkable with the two commands at the top. Do not soften it further, and
+do not claim the site is "not affected by any vulnerabilities" — that is a bigger claim than the
+evidence supports, and it is the kind of sentence that gets quoted back.
+
+## When this changes
+
+Re-check whenever `pa11y-ci` releases, and whenever an audit shows a *different* advisory —
+this note covers exactly one, and a second finding is a new decision, not this one repeating.
+
+```bash
+npm audit --omit=dev            # must stay at 0. If it is not, that is a real problem
+npm outdated pa11y-ci           # the chain moves when this does
+npm view extract-zip versions   # the day something above 2.0.1 appears, this note is obsolete
+```
+
+If a patched `extract-zip` ships and the chain picks it up, delete this file. A note describing
+a problem that no longer exists is worse than no note.
+
+[GHSA-jmr9-qjv8-65gv]: https://github.com/advisories/GHSA-jmr9-qjv8-65gv

package/template/scripts/recon.mjs

@@ -177,9 +177,20 @@ async function req(url, options = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 20000);
   const follow = options.redirect !== 'manual';
+  /*
+   * ⚠ 20, BECAUSE THAT IS WHAT fetch ITSELF ALLOWS. Following redirects by
+   *   hand is what lets every hop be checked, but the hop LIMIT is not a
+   *   security property — and picking a lower one silently changes results.
+   *
+   *   At a cap of 5, a page behind a longer chain came back as the 302 rather
+   *   than the 200 it used to: measured, old → 200, new → 302. In a migration
+   *   inventory that turns a live page into a redirect, which is the kind of
+   *   wrong that reads as fine.
+   */
+  const MAX_HOPS = 20;
   try {
     let res = await fetch(url, { ...options, redirect: 'manual', signal: controller.signal });
-    for (let hops = 0; follow && res.status >= 300 && res.status < 400 && res.headers.get('location') && hops < 5; hops++) {
+    for (let hops = 0; follow && res.status >= 300 && res.status < 400 && res.headers.get('location') && hops < MAX_HOPS; hops++) {
       const next = new URL(res.headers.get('location'), url).toString();
       const hopRefusal = blockedReason(next, { allowInternal });
       if (hopRefusal) return refuse(`${hopRefusal.reason} — reached by a redirect from ${url}`, next);