Merge pull request #78 from marklynch/claude/package-repo-options-bc13ra

Author: marklynch

README.md

@@ -392,6 +392,7 @@ The page offers the **5 most recent releases** in a version picker, defaulting t
 The page source lives in `installer/`:
 
 - `installer/index.html` — the installer page. Static; it reads `versions.json` at runtime to build the picker, so it needs no build step.
+- `installer/app.js` — the page's script. Kept out of the HTML so the page's CSP can be `script-src 'self'` with no `'unsafe-inline'`.
 - `installer/manifest.template.json` — the ESP Web Tools manifest, with `__VERSION__` / `__BINARY__` placeholders stamped once per offered version.
 - `installer/build-site.sh` — assembles the deployable site.
 - `installer/preview.sh` — builds it and serves it locally.
@@ -402,6 +403,20 @@ Releases without a `pool-controller-full-*.bin` asset are skipped, and the scrip
 
 A deploy always publishes the newest 5 releases regardless of which tag triggered it, so re-running an old tag's build can't roll the public installer back to that version.
 
+### Vendored flasher
+
+ESP Web Tools is **vendored into the site**, not loaded from a CDN. The page holds a live Web Serial port and writes a full flash image, so the JavaScript it loads decides which bytes reach the device — that code is pinned and verified rather than resolved at page load from a third-party origin. A floating `@10` CDN range would mean every visitor executing whatever was published to npm most recently, with no review and no deploy step in between.
+
+`build-site.sh` downloads the exact `EWT_VERSION` tarball from the npm registry, checks it against the registry's published `dist.integrity` hash pinned in `EWT_INTEGRITY`, and unpacks it to `ewt/`. A mismatch aborts the build. To upgrade, bump both:
+
+```bash
+curl -s https://registry.npmjs.org/esp-web-tools/<version> | jq -r .dist.integrity
+```
+
+then re-test flashing on real hardware before merging.
+
+With every asset same-origin, the page sets a `default-src 'none'` CSP allowing `script-src 'self'` and no external origins, so nothing off-origin can inject code into the flashing page.
+
 **One-time setup:** in Settings → Pages, set the source to **GitHub Actions**. Setting it to "Deploy from a branch" cannot work — that serves the sources raw, with no `manifest.json` and no binary, and the page fails with *"Failed to download manifest"*. (`installer/` is named that way rather than `docs/` precisely so it isn't offered as a branch publishing directory.)
 
 ### Deploy triggers

installer/app.js

@@ -0,0 +1,57 @@
+// versions.json is generated by installer/build-site.sh, newest release first,
+// with one manifest and one firmware binary per version. ESP Web Tools reads
+// the manifest when the button is clicked, so switching versions is just a
+// matter of re-pointing the button's manifest attribute.
+//
+// Kept in its own file rather than inline so the page's Content-Security-Policy
+// can be script-src 'self' with no 'unsafe-inline'.
+const select = document.getElementById('version');
+const installer = document.getElementById('installer');
+const notes = document.getElementById('notes');
+const older = document.getElementById('older');
+const olderLatest = document.getElementById('older-latest');
+
+function apply(entry, latest) {
+  installer.setAttribute('manifest', './' + entry.manifest);
+  notes.href = entry.notes;
+  olderLatest.textContent = latest;
+  older.hidden = entry.version === latest;
+}
+
+fetch('./versions.json')
+  .then((r) => {
+    if (!r.ok) throw new Error('versions.json: HTTP ' + r.status);
+    return r.json();
+  })
+  .then((data) => {
+    const list = data.versions || [];
+    if (!list.length) throw new Error('no versions listed');
+
+    select.textContent = '';
+    for (const entry of list) {
+      const opt = document.createElement('option');
+      opt.value = entry.version;
+      opt.textContent =
+        entry.version +
+        (entry.version === data.latest ? ' (latest)' : '') +
+        (entry.published ? ' — ' + entry.published : '');
+      select.append(opt);
+    }
+    select.disabled = list.length < 2;
+    select.value = data.latest;
+    apply(list.find((e) => e.version === data.latest) || list[0], data.latest);
+
+    select.addEventListener('change', () => {
+      const entry = list.find((e) => e.version === select.value);
+      if (entry) apply(entry, data.latest);
+    });
+  })
+  .catch(() => {
+    // Leave the button on manifest.json, which build-site.sh always writes as
+    // a copy of the latest release's manifest, so installing still works.
+    select.textContent = '';
+    const opt = document.createElement('option');
+    opt.textContent = 'latest';
+    select.append(opt);
+    select.disabled = true;
+  });

installer/build-site.sh

@@ -19,6 +19,22 @@ OUT=""
 LOCAL_BIN=""
 LOCAL_VERSION=""
 
+# ESP Web Tools is vendored into the site rather than loaded from a CDN. The
+# page holds a live Web Serial port and writes a full flash image, so whatever
+# JavaScript it loads decides which bytes reach the device — that code must be
+# pinned and verified, not resolved at page load from a third-party origin.
+#
+# EWT_INTEGRITY is the npm registry's published dist.integrity for this exact
+# version. Published npm versions are immutable, so a mismatch means the
+# tarball was tampered with in transit or the registry was compromised; either
+# way the build fails rather than shipping it.
+#
+# To upgrade: bump EWT_VERSION, then take the new hash from
+#   curl -s https://registry.npmjs.org/esp-web-tools/<version> | jq -r .dist.integrity
+# and re-test flashing before merging.
+EWT_VERSION="10.4.0"
+EWT_INTEGRITY="sha512-3pwkeFFm5Fj7UQo8SJNYK5RXrtNCpq6X9QoI6bMT4GBZWgrJqjn0YvM9ihG74BtMoSFYXfmDtkehuxe50PTMPQ=="
+
 while [ $# -gt 0 ]; do
   case "$1" in
     --out) OUT="$2"; shift 2 ;;
@@ -112,7 +128,36 @@ with open(os.path.join(out, "versions.json"), "w") as f:
 PY
 
 cp "$SRC/index.html" "$OUT/index.html"
+cp "$SRC/app.js" "$OUT/app.js"
 # Kept so a direct link to manifest.json still resolves to the current release.
 cp "$OUT/manifest-${LATEST}.json" "$OUT/manifest.json"
 
+# --- Vendor ESP Web Tools ---------------------------------------------------
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+echo "Fetching esp-web-tools ${EWT_VERSION} …"
+curl -fsSL --retry 3 \
+  "https://registry.npmjs.org/esp-web-tools/-/esp-web-tools-${EWT_VERSION}.tgz" \
+  -o "$TMP/ewt.tgz"
+
+ACTUAL=$(python3 -c '
+import base64, hashlib, sys
+print("sha512-" + base64.b64encode(hashlib.sha512(open(sys.argv[1], "rb").read()).digest()).decode())
+' "$TMP/ewt.tgz")
+
+if [ "$ACTUAL" != "$EWT_INTEGRITY" ]; then
+  echo "esp-web-tools integrity check FAILED — refusing to build." >&2
+  echo "  expected: $EWT_INTEGRITY" >&2
+  echo "  actual:   $ACTUAL" >&2
+  exit 1
+fi
+
+tar xzf "$TMP/ewt.tgz" -C "$TMP" package/dist/web
+mkdir -p "$OUT/ewt"
+cp -R "$TMP/package/dist/web/." "$OUT/ewt/"
+# The page loads this entry point; the rest are its lazily imported chunks.
+test -s "$OUT/ewt/install-button.js"
+echo "  vendored esp-web-tools ${EWT_VERSION} (integrity verified)"
+
 echo "Built $OUT — latest ${LATEST}, $(grep -c '"version"' "$OUT/versions.json") version(s)."

installer/index.html

@@ -3,6 +3,16 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
+<!-- Everything the page needs is served from this origin: the flasher is
+     vendored into ewt/ by installer/build-site.sh, the page script is app.js,
+     and the manifests and firmware binaries sit alongside them. No external
+     origin can supply code to a page that writes firmware over Web Serial.
+     style-src allows inline because the page styles are in a <style> block and
+     ESP Web Tools falls back to injecting <style> where adoptedStyleSheets is
+     unavailable; blob: is allowed for connect because the flasher's dialog
+     creates object URLs. frame-ancestors is omitted: it is ignored in a meta
+     CSP and needs a real header. -->
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' blob:; form-action 'self'; base-uri 'none'">
 <title>Pool Controller — Web Installer</title>
 <meta name="description" content="Flash the Connect 10 pool controller firmware to an ESP32-C6 straight from your browser.">
 <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%231565C0' d='M2,15C3.67,14.25 5.33,13.5 7,13.17V5A3,3 0 0,1 10,2C11.31,2 12.42,2.83 12.83,4H10A1,1 0 0,0 9,5V6H14V5A3,3 0 0,1 17,2C18.31,2 19.42,2.83 19.83,4H17A1,1 0 0,0 16,5V14.94C18,14.62 20,13 22,13V15C19.78,15 17.56,17 15.33,17C13.11,17 10.89,15 8.67,15C6.44,15 4.22,16 2,17V15M14,8H9V10H14V8M14,12H9V13C10.67,13.16 12.33,14.31 14,14.79V12M2,19C4.22,18 6.44,17 8.67,17C10.89,17 13.11,19 15.33,19C17.56,19 19.78,17 22,17V19C19.78,19 17.56,21 15.33,21C13.11,21 10.89,19 8.67,19C6.44,19 4.22,20 2,21V19Z'/%3E%3C/svg%3E">
@@ -178,62 +188,7 @@ <h2>Project links</h2>
   </footer>
 </main>
 
-<script type="module" src="https://unpkg.com/esp-web-tools@10/dist/web/install-button.js"></script>
-<script>
-  // versions.json is generated by installer/build-site.sh, newest release first,
-  // with one manifest and one firmware binary per version. ESP Web Tools reads
-  // the manifest when the button is clicked, so switching versions is just a
-  // matter of re-pointing the button's manifest attribute.
-  const select = document.getElementById('version');
-  const installer = document.getElementById('installer');
-  const notes = document.getElementById('notes');
-  const older = document.getElementById('older');
-  const olderLatest = document.getElementById('older-latest');
-
-  function apply(entry, latest) {
-    installer.setAttribute('manifest', './' + entry.manifest);
-    notes.href = entry.notes;
-    olderLatest.textContent = latest;
-    older.hidden = entry.version === latest;
-  }
-
-  fetch('./versions.json')
-    .then((r) => {
-      if (!r.ok) throw new Error('versions.json: HTTP ' + r.status);
-      return r.json();
-    })
-    .then((data) => {
-      const list = data.versions || [];
-      if (!list.length) throw new Error('no versions listed');
-
-      select.textContent = '';
-      for (const entry of list) {
-        const opt = document.createElement('option');
-        opt.value = entry.version;
-        opt.textContent =
-          entry.version +
-          (entry.version === data.latest ? ' (latest)' : '') +
-          (entry.published ? ' — ' + entry.published : '');
-        select.append(opt);
-      }
-      select.disabled = list.length < 2;
-      select.value = data.latest;
-      apply(list.find((e) => e.version === data.latest) || list[0], data.latest);
-
-      select.addEventListener('change', () => {
-        const entry = list.find((e) => e.version === select.value);
-        if (entry) apply(entry, data.latest);
-      });
-    })
-    .catch(() => {
-      // Leave the button on manifest.json, which build-site.sh always writes as
-      // a copy of the latest release's manifest, so installing still works.
-      select.textContent = '';
-      const opt = document.createElement('option');
-      opt.textContent = 'latest';
-      select.append(opt);
-      select.disabled = true;
-    });
-</script>
+<script type="module" src="./ewt/install-button.js"></script>
+<script src="./app.js"></script>
 </body>
 </html>