spark-html-sri 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# ⚡ spark-html-sri
+
+Subresource Integrity for [spark-html](https://www.npmjs.com/package/spark-html)
+— auto-hash every built asset **and** verify URL-imported components at
+runtime. Same mental model as `<script integrity>`, applied to the whole
+app. Zero dependencies, zero bytes added to the spark-html core.
+
+```js
+// src/main.js — before mount()/router()
+import { sri } from 'spark-html-sri';
+sri();
+```
+
+```js
+// vite.config.js — after prerender()
+import spark from 'spark-html/vite';
+import prerender from 'spark-prerender/vite';
+import sriPlugin from 'spark-html-sri/vite';
+
+export default { plugins: [spark(), prerender(), sriPlugin()] };
+```
+
+## Install
+
+```bash
+npm install spark-html-sri
+```
+
+## What you get
+
+**Local files — fully automatic, zero config.** At build time the vite
+plugin hashes every JS/CSS file and every component fragment (SHA-384 by
+default), stamps `integrity` + `crossorigin="anonymous"` onto the
+`<script>`/`<link>` tags (the browser enforces those natively), and bakes
+a path → hash manifest into each page. At runtime `sri()` verifies every
+component fetch against that manifest before spark-html boots it. A
+tampered file — a compromised host, a poisoned cache — is rejected with a
+clear console error instead of running.
+
+**Remote URL imports** (`<div import="https://…">`) — **allow list + TOFU.**
+Only whitelisted origins can be imported at all:
+
+```js
+sri({
+  allow: ['cdn.jsdelivr.net', 'unpkg.com', 'esm.sh', 'raw.githubusercontent.com'], // the default
+});
+```
+
+For allowed origins, integrity is verified via **trust on first use**: the
+first fetch stores the content hash (in `localStorage`), and every later
+load must hash the same. A CDN compromised *after* your first visit serves
+bytes that no longer match — the component is blocked before it runs.
+Import pinned URLs (`…@1.2.3/card.html`) so legitimate updates are new
+URLs; if you import a mutable URL and it changes on purpose, call
+`resetTofu()` (or bump the URL).
+
+**Your API calls are untouched.** Only same-origin paths present in the
+build manifest and cross-origin `.html` component imports are governed —
+every other fetch passes straight through.
+
+## Dev vs production
+
+`enforce: 'auto'` (the default) **fails open on localhost** — violations
+warn in the console but nothing is blocked, so dev servers and HMR are
+never in your way — and **enforces everywhere else**. Set `enforce: true`
+or `false` to override.
+
+## Options
+
+```js
+sri({
+  manifest: { '/components/nav.html': 'sha384-…' }, // default: baked in by the vite plugin
+  allow: ['esm.sh'],          // remote hosts (subdomains included)
+  enforce: 'auto',            // true | false | 'auto' (auto = enforce unless localhost)
+  onViolation: (msg, url) => report(msg, url),
+});
+```
+
+```js
+sriPlugin({ algorithm: 'sha384' }); // 'sha256' | 'sha384' | 'sha512'
+```
+
+## API
+
+| Export | Meaning |
+|--------|---------|
+| `sri(options?)` | Install the fetch guard. Returns a restore function. |
+| `integrity(data, algo?)` | Compute an SRI string — `"sha384-…"`. |
+| `verify(data, integrityString)` | Check data against an SRI string (space-separated list allowed). |
+| `resetTofu()` | Forget every remembered remote-component hash. |
+| `DEFAULT_ALLOW` | The default remote allow list. |
+| `spark-html-sri/vite` | Build plugin — hash, stamp, bake the manifest. |
+
+## Why not put this in the core?
+
+The spark-html runtime has a frozen 13 kB budget. Verification lives here
+instead, as an opt-in wrapper around `fetch` — projects that don't use SRI
+pay zero bytes, and the core stays tiny.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "spark-html-sri",
+  "version": "0.1.0",
+  "description": "Subresource Integrity for spark-html — auto-hash built assets and components, verify at runtime, and make URL-imported components safe with an origin allow list + trust-on-first-use. Zero dependencies.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "homepage": "https://wilkinnovo.github.io/spark",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./vite": {
+      "types": "./src/vite.d.ts",
+      "default": "./src/vite.js"
+    }
+  },
+  "scripts": {
+    "test": "node test/sri.js"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilkinnovo/spark.git",
+    "directory": "packages/spark-html-sri"
+  },
+  "keywords": [
+    "spark-html",
+    "sri",
+    "subresource-integrity",
+    "integrity",
+    "security",
+    "tofu",
+    "vite-plugin"
+  ],
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,45 @@
+/** Remote origins allowed by default for URL-imported components. */
+export const DEFAULT_ALLOW: string[];
+
+export type SriAlgorithm = 'sha256' | 'sha384' | 'sha512';
+
+/** Compute an SRI string — `integrity('hi')` → `"sha384-…"`. */
+export function integrity(
+  data: string | Uint8Array | ArrayBuffer,
+  algo?: SriAlgorithm,
+): Promise<string>;
+
+/** Verify data against an SRI string (space-separated list allowed; any match passes). */
+export function verify(
+  data: string | Uint8Array | ArrayBuffer,
+  integrityString: string,
+): Promise<boolean>;
+
+export interface SriOptions {
+  /** path → SRI string. Default: the manifest the vite plugin baked into the page. */
+  manifest?: Record<string, string>;
+  /** Allowed remote hosts for URL imports (subdomains included). */
+  allow?: string[];
+  /** Block on failure. 'auto' (default) enforces everywhere except localhost. */
+  enforce?: boolean | 'auto';
+  /** Observe failures (fires whether or not the request was blocked). */
+  onViolation?: (message: string, url: string) => void;
+}
+
+/**
+ * Install the integrity guard around `fetch`. Call once from main.js,
+ * before mount()/router(). Returns a function that restores the original fetch.
+ */
+export function sri(options?: SriOptions): () => void;
+
+/** Forget every remembered remote-component hash (TOFU store). */
+export function resetTofu(): void;
+
+declare const _default: {
+  sri: typeof sri;
+  integrity: typeof integrity;
+  verify: typeof verify;
+  resetTofu: typeof resetTofu;
+  DEFAULT_ALLOW: string[];
+};
+export default _default;

package/src/index.js

@@ -0,0 +1,205 @@
+/**
+ * spark-html-sri — Subresource Integrity for spark-html apps.
+ *
+ * Two halves, one mental model (`<script integrity>` — familiar to every
+ * web developer):
+ *
+ * **Local files** — fully automatic, zero config. The vite plugin
+ * (spark-html-sri/vite) hashes every built JS/CSS/component fragment,
+ * injects `integrity` + `crossorigin` into `<script>`/`<link>` tags, and
+ * bakes a manifest into each page. At runtime `sri()` verifies every
+ * component fetch against that manifest before spark-html boots it.
+ *
+ * **Remote URL imports** (`<div import="https://…">`) — whitelist + TOFU.
+ * Only allowed origins may be imported; for those, the first fetch stores
+ * the content hash (trust on first use) and every later load must match.
+ * A CDN compromised after your first visit serves a component that no
+ * longer hashes — it's rejected before it runs.
+ *
+ *   import { sri } from 'spark-html-sri';
+ *   sri();                                     // defaults for everything
+ *   sri({ allow: ['esm.sh'], enforce: true }); // tighten
+ *
+ * Fail open in dev (localhost warns, never blocks), enforce in production.
+ * Nothing here touches the spark-html core — apps that don't use SRI pay
+ * zero bytes.
+ */
+
+/** Remote origins allowed by default for URL-imported components. */
+export const DEFAULT_ALLOW = ['cdn.jsdelivr.net', 'unpkg.com', 'esm.sh', 'raw.githubusercontent.com'];
+
+const TOFU_KEY = 'spark-sri:tofu';
+const ALGOS = { sha256: 'SHA-256', sha384: 'SHA-384', sha512: 'SHA-512' };
+
+function subtle() {
+  const s = globalThis.crypto && globalThis.crypto.subtle;
+  if (!s) throw new Error('[spark-sri] WebCrypto unavailable (secure context required)');
+  return s;
+}
+
+function toBytes(data) {
+  if (typeof data === 'string') return new TextEncoder().encode(data);
+  return data instanceof Uint8Array ? data : new Uint8Array(data);
+}
+
+function b64(buf) {
+  let s = '';
+  const bytes = new Uint8Array(buf);
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s);
+}
+
+/**
+ * Compute an SRI string — `integrity('hi')` → `"sha384-…"`.
+ * @param {string|Uint8Array|ArrayBuffer} data
+ * @param {'sha256'|'sha384'|'sha512'} [algo='sha384']
+ */
+export async function integrity(data, algo = 'sha384') {
+  const name = ALGOS[algo];
+  if (!name) throw new Error(`[spark-sri] unknown algorithm "${algo}"`);
+  const digest = await subtle().digest(name, toBytes(data));
+  return `${algo}-${b64(digest)}`;
+}
+
+/**
+ * Verify data against an SRI string. Like the platform, a space-separated
+ * list is accepted and ANY match passes.
+ * @returns {Promise<boolean>}
+ */
+export async function verify(data, integrityString) {
+  if (!integrityString) return false;
+  for (const token of String(integrityString).trim().split(/\s+/)) {
+    const algo = token.slice(0, token.indexOf('-'));
+    if (!ALGOS[algo]) continue;
+    if ((await integrity(data, algo)) === token) return true;
+  }
+  return false;
+}
+
+// ── runtime fetch guard ─────────────────────────────────────────────────
+
+function readInlineManifest() {
+  if (typeof document === 'undefined') return null;
+  const el = document.querySelector('script[type="application/json"][data-spark-sri]');
+  if (!el) return null;
+  try { return JSON.parse(el.textContent); } catch { return null; }
+}
+
+function loadTofu() {
+  try { return JSON.parse(localStorage.getItem(TOFU_KEY)) || {}; } catch { return {}; }
+}
+function saveTofu(map) {
+  try { localStorage.setItem(TOFU_KEY, JSON.stringify(map)); } catch { /* private mode etc. */ }
+}
+
+function isLocalhost() {
+  if (typeof location === 'undefined') return true;
+  return ['localhost', '127.0.0.1', '[::1]', ''].includes(location.hostname);
+}
+
+function hostAllowed(host, allow) {
+  return allow.some((a) => host === a || host.endsWith('.' + a));
+}
+
+function blockedResponse(reason) {
+  return new Response(`/* blocked by spark-html-sri: ${reason} */`, {
+    status: 424,
+    statusText: 'integrity check failed',
+  });
+}
+
+/**
+ * Install the integrity guard around `fetch`. Call once from main.js,
+ * BEFORE mount()/router() so component fetches flow through it.
+ *
+ * - Same-origin URLs listed in the manifest are hash-verified.
+ * - Cross-origin `.html` component imports must come from an allowed
+ *   origin and (after the first load) keep hashing the same (TOFU).
+ * - Everything else — your API calls, images, other origins' JSON —
+ *   passes through untouched.
+ *
+ * @param {object} [options]
+ * @param {Record<string,string>} [options.manifest] path → SRI string. Default: the
+ *   manifest the vite plugin baked into the page (absent in dev — nothing to verify).
+ * @param {string[]} [options.allow] Allowed remote hosts for URL imports
+ *   (default: jsdelivr/unpkg/esm.sh/raw.githubusercontent — subdomains included).
+ * @param {boolean|'auto'} [options.enforce='auto'] Block on failure. 'auto'
+ *   enforces everywhere except localhost (fail open in dev).
+ * @param {(msg: string, url: string) => void} [options.onViolation] Observe failures.
+ * @returns {() => void} restore the original fetch.
+ */
+export function sri(options = {}) {
+  if (typeof globalThis.fetch !== 'function') return () => {};
+  const manifest = options.manifest || readInlineManifest() || {};
+  const allow = options.allow || DEFAULT_ALLOW;
+  const enforce = options.enforce === 'auto' || options.enforce === undefined
+    ? !isLocalhost()
+    : !!options.enforce;
+
+  const violate = (msg, url) => {
+    console[enforce ? 'error' : 'warn'](`[spark-sri] ${msg} — ${url}${enforce ? '' : ' (dev: allowed)'}`);
+    if (options.onViolation) { try { options.onViolation(msg, url); } catch { /* observer only */ } }
+  };
+
+  const origFetch = globalThis.fetch;
+  const tofu = loadTofu();
+
+  const guarded = async function (input, init) {
+    const method = ((init && init.method) || (input && input.method) || 'GET').toUpperCase();
+    const rawUrl = typeof input === 'string' ? input : (input && input.url) || String(input);
+    let url;
+    try { url = new URL(rawUrl, typeof location !== 'undefined' ? location.href : undefined); } catch { url = null; }
+    if (!url || method !== 'GET' || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
+      return origFetch.call(this, input, init);
+    }
+
+    const sameOrigin = typeof location === 'undefined' || url.origin === location.origin;
+
+    // Same-origin: verify only what the build manifest covers.
+    if (sameOrigin) {
+      const expected = manifest[url.pathname];
+      if (!expected) return origFetch.call(this, input, init);
+      const res = await origFetch.call(this, input, init);
+      if (!res.ok) return res;
+      const bytes = new Uint8Array(await res.clone().arrayBuffer());
+      if (await verify(bytes, expected)) return res;
+      violate('integrity mismatch (build manifest)', url.href);
+      return enforce ? blockedResponse('integrity mismatch') : res;
+    }
+
+    // Cross-origin: only component imports (.html) are governed.
+    if (!url.pathname.endsWith('.html')) return origFetch.call(this, input, init);
+
+    if (!hostAllowed(url.hostname, allow)) {
+      violate(`origin "${url.hostname}" is not in the allow list`, url.href);
+      if (enforce) return blockedResponse(`origin ${url.hostname} not allowed`);
+      return origFetch.call(this, input, init);
+    }
+
+    const res = await origFetch.call(this, input, init);
+    if (!res.ok) return res;
+    const bytes = new Uint8Array(await res.clone().arrayBuffer());
+    const known = tofu[url.href];
+    if (!known) {
+      // Trust on first use — remember what this URL looked like.
+      tofu[url.href] = await integrity(bytes);
+      saveTofu(tofu);
+      return res;
+    }
+    if (await verify(bytes, known)) return res;
+    violate('remote component changed since first use (TOFU mismatch)', url.href);
+    return enforce ? blockedResponse('TOFU mismatch') : res;
+  };
+
+  globalThis.fetch = guarded;
+  return () => {
+    if (globalThis.fetch === guarded) globalThis.fetch = origFetch;
+  };
+}
+
+/** Forget every remembered remote-component hash (TOFU store). */
+export function resetTofu() {
+  try { localStorage.removeItem(TOFU_KEY); } catch { /* ignore */ }
+}
+
+export default { sri, integrity, verify, resetTofu, DEFAULT_ALLOW };

package/src/vite.d.ts

@@ -0,0 +1,18 @@
+import type { SriAlgorithm } from './index.js';
+
+export interface SriVitePluginOptions {
+  /** Hash algorithm for assets and the manifest (default 'sha384'). */
+  algorithm?: SriAlgorithm;
+}
+
+/**
+ * Vite plugin: hashes every built JS/CSS/component fragment, stamps
+ * integrity + crossorigin onto script/link tags, and bakes the manifest
+ * into each page. Put it after prerender() in `plugins`.
+ */
+export default function sparkSri(options?: SriVitePluginOptions): {
+  name: string;
+  apply: 'build';
+  configResolved(config: unknown): void;
+  closeBundle: { order: 'post'; handler(): Promise<void> };
+};

package/src/vite.js

@@ -0,0 +1,117 @@
+/**
+ * spark-html-sri/vite — hash the build, stamp the pages.
+ *
+ * Runs in closeBundle (order post, after spark-prerender has written its
+ * per-route HTML — put it after prerender() in `plugins`). For every page:
+ *
+ *  1. hashes every .js/.css in the output and adds `integrity` +
+ *     `crossorigin="anonymous"` to the <script src> / <link rel=stylesheet>
+ *     tags that reference them — the browser enforces these natively;
+ *  2. hashes every component fragment (.html without <head>) into a
+ *     manifest and bakes it into the page as
+ *     <script type="application/json" data-spark-sri>…</script> — the
+ *     sri() runtime picks it up with zero config.
+ *
+ *   import sriPlugin from 'spark-html-sri/vite';
+ *   plugins: [spark(), prerender(), sriPlugin()]
+ */
+import { join, resolve, relative, sep } from 'node:path';
+import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+
+async function walk(dir) {
+  const out = [];
+  for (const name of await readdir(dir)) {
+    const full = join(dir, name);
+    const s = await stat(full);
+    if (s.isDirectory()) out.push(...await walk(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+function sriHash(buf, algo) {
+  return `${algo}-${createHash(algo).update(buf).digest('base64')}`;
+}
+
+// Attribute-order-agnostic tag rewriting: find <script src>/<link stylesheet>
+// tags, resolve their URL against the manifest, splice the attributes in.
+function stampTags(html, lookup) {
+  return html
+    .replace(/<script\b[^>]*\bsrc\s*=\s*"([^"]+)"[^>]*>/g, (tag, src) => stamp(tag, src, lookup))
+    .replace(/<link\b[^>]*\brel\s*=\s*"stylesheet"[^>]*>/g, (tag) => {
+      const href = (tag.match(/\bhref\s*=\s*"([^"]+)"/) || [])[1];
+      return href ? stamp(tag, href, lookup) : tag;
+    });
+}
+
+function stamp(tag, url, lookup) {
+  if (/\bintegrity\s*=/.test(tag)) return tag;           // already stamped
+  if (/^(https?:)?\/\//.test(url)) return tag;           // remote — not ours to hash
+  const hash = lookup(url.split(/[?#]/)[0]);
+  if (!hash) return tag;
+  const attrs = ` integrity="${hash}"` + (/\bcrossorigin\b/.test(tag) ? '' : ' crossorigin="anonymous"');
+  return tag.replace(/\s*\/?>$/, (end) => `${attrs}${end}`);
+}
+
+/**
+ * @param {object} [options]
+ * @param {'sha256'|'sha384'|'sha512'} [options.algorithm='sha384']
+ */
+export default function sparkSri(options = {}) {
+  const algo = options.algorithm || 'sha384';
+  let outDir = 'dist';
+  let base = '/';
+  return {
+    name: 'spark-html-sri',
+    apply: 'build',
+    configResolved(viteConfig) {
+      if (viteConfig && viteConfig.build && viteConfig.build.outDir) outDir = viteConfig.build.outDir;
+      if (viteConfig && viteConfig.base) base = viteConfig.base;
+    },
+    closeBundle: {
+      order: 'post',
+      async handler() {
+        const root = resolve(outDir);
+        if (!existsSync(root)) return;
+        const baseDir = base.endsWith('/') ? base : base + '/';
+
+        const files = await walk(root);
+        const manifest = {};   // served pathname → sri string
+        const pages = [];
+        for (const file of files) {
+          const pathname = baseDir + relative(root, file).split(sep).join('/');
+          if (/\.(js|css)$/.test(file)) {
+            manifest[pathname] = sriHash(await readFile(file), algo);
+          } else if (file.endsWith('.html')) {
+            const html = await readFile(file, 'utf8');
+            if (/<\/head>/i.test(html)) pages.push({ file, html });
+            else manifest[pathname] = sriHash(Buffer.from(html), algo); // component fragment
+          }
+        }
+
+        const json = JSON.stringify(manifest);
+        let stamped = 0;
+        for (const { file, html } of pages) {
+          if (html.includes('data-spark-sri')) continue;  // idempotent
+          // Resolve a tag's URL to a manifest key: absolute pathnames match
+          // directly; relative ones resolve against the page's directory.
+          const pageDir = baseDir + relative(root, join(file, '..')).split(sep).join('/');
+          const lookup = (url) => {
+            if (url.startsWith('/')) return manifest[url] || manifest[baseDir.replace(/\/$/, '') + url];
+            const dir = pageDir === baseDir + '.' ? baseDir : pageDir + '/';
+            return manifest[dir.replace(/\/\.\//, '/') + url.replace(/^\.\//, '')];
+          };
+          let out = stampTags(html, lookup);
+          out = out.replace(/<\/head>/i, `<script type="application/json" data-spark-sri>${json}</script>\n</head>`);
+          await writeFile(file, out, 'utf8');
+          stamped++;
+        }
+        if (stamped) {
+          console.log(`[spark-html-sri] ${Object.keys(manifest).length} asset(s) hashed, ${stamped} page(s) stamped`);
+        }
+      },
+    },
+  };
+}