@localnerve/trusted-types-bootstrap 0.1.0-rc.1

package/LICENSE.md

@@ -0,0 +1,11 @@
+Copyright 2026 Alex Grant, LocalNerve, LLC
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,157 @@
+# Trusted Types Bootstrap
+
+> Page-level Trusted Types bootstrap for web apps — one import + one config call replaces the per-app inline bootstrap script
+
+[![npm version](https://badge.fury.io/js/@localnerve%2Ftrusted-types-bootstrap.svg)](https://badge.fury.io/js/@localnerve%2Ftrusted-types-bootstrap)
+
+Every web app that enforces `require-trusted-types-for 'script'` re-implements the same boilerplate inline bootstrap script: detect whether CSP is enforced, register the reserved `default` policy (escaping `createHTML`, same-origin-only `createScriptURL`, no `createScript`), optionally register app-named policies for static-markup passthrough, install a passthrough shim for browsers without Trusted Types, and log `securitypolicyviolation` events.
+
+This package turns that boilerplate into a shared, parameterized export: **one import + one config call**, with the logic identical for any app — only the named policies and allowed script origins vary per project. The core (escape, same-origin guard, shim, orchestration) is tiny and dependency-free; the DOMPurify-backed sanitize tier is an opt-in sub-path so apps without rich content never pay for it.
+
+  * [Why This Exists](#why-this-exists)
+  * [Usage](#usage)
+  * [API](#api)
+  * [Sanitize Sub-Path](#sanitize-sub-path)
+  * [Relationship to Other Packages](#relationship-to-other-packages)
+  * [Development](#development)
+
+## Why This Exists
+
+1. **Stop re-creating the same ~90-line inline bootstrap in every web app** — drift risk across projects, duplicated review effort
+2. **Zero cost for apps that don't need rich content** — the core escape guard + shim is a few KB and has no runtime dependencies
+3. **Opt-in sanitize tier** — DOMPurify-backed "allow some safe HTML" support lives in a separate entry point (`/sanitize`) that only lands in bundles of apps that import it
+4. **Compatible with computed allowlists** — named policies are declared at the call site (in your app's inline script), so [`@localnerve/trusted-types-rules`](https://github.com/localnerve/trusted-types-rules#readme) keeps detecting them via AST analysis for the CSP `trusted-types` directive — no special handling needed
+5. **ESM-first, tree-shakeable** for bundlers (Rollup/webpack)
+
+## Usage
+
+The bootstrap must run **before any other app code** — keep it as the page's first inline script so policies exist when sinks are first hit. In production builds that meta tag is present and policies register; in dev builds (no meta tag) nothing registers and plain strings pass through, exactly like a browser without Trusted Types.
+
+```js
+// your page's FIRST inline script
+import { bootstrapTrustedTypes } from '@localnerve/trusted-types-bootstrap';
+
+bootstrapTrustedTypes({
+  // 'auto' (default): enforce only when a CSP meta tag is present (prod builds).
+  // true/false to override.
+  enforce: 'auto',
+
+  // Origins allowed by the default policy's createScriptURL. Default: same-origin
+  // only. Extra entries are full origins, e.g. 'https://cdn.example.com'.
+  scriptURLOrigins: ['self'],
+
+  // App-named policies to register alongside `default`. Keys must appear in the
+  // CSP trusted-types allowlist (computed by @localnerve/trusted-types-rules).
+  policies: {
+    'jam-app-static': 'staticHtml',   // pass-through createHTML: author-controlled markup only
+  },
+
+  // optional per-policy form: custom hooks and/or a helper callback invoked
+  // after the policy is registered (e.g. to attach a convenience global)
+  // policies: {
+  //   'jam-app-static': {
+  //     hooks: { createHTML: input => String(input) },
+  //     helper: w => {
+  //       w.trustedStaticHtml = html => w.trustedTypes.getPolicy('jam-app-static').createHTML(html);
+  //     }
+  //   }
+  // },
+
+  logViolations: true,          // console.warn on securitypolicyviolation (dev aid)
+  shimWhenUnavailable: true     // passthrough shim for browsers without TT
+});
+```
+
+The `default` policy's behavior contract:
+
+* `createHTML` applies the industry-standard **6-char escape** (`& < > " ' \`` → `&amp; &lt; &gt; &quot; &#x27; &#x60;`) — safe in both element-content and attribute contexts, so markup sinks render inert text instead of executing injected tags
+* `createScriptURL` only allows origins in `scriptURLOrigins` (default same-origin), so code can never be loaded from another origin (`<script src>`, Workers, dynamic `import()`)
+* **no** `createScript` hook — `eval()` / `new Function()` remain blocked by CSP
+
+Custom-element / web-component policies are unaffected: components register their own named policies at their own load time (via [`@localnerve/web-component-build`](https://github.com/localnerve/web-component-build#trusted-types-helpers) helpers), exactly as they do today.
+
+## API
+
+This library exports:
+
+```js
+export function bootstrapTrustedTypes (config): Boolean
+export function defaultPolicyHooks (options): Object
+export function setWindow (target)
+export { escapeHtml, shimTrustedTypes }
+```
+
+### bootstrapTrustedTypes(config)
+Bootstraps page-level Trusted Types. Returns `true` when policies were registered, `false` in passthrough mode (dev builds / browsers without TT). Throws if no window/document is available.
+
+Config options:
+
+* **enforce** {'auto'|Boolean} — default `'auto'`. `'auto'`: enforce only when a CSP meta tag (`meta[http-equiv="Content-Security-Policy"]`) is present, i.e. production builds; dev builds with no meta register nothing so plain strings pass through. `true`/`false` override detection.
+* **scriptURLOrigins** {Array\<String\>} — origins allowed by the default policy's `createScriptURL`. Default `['self']` (same-origin only). Extra entries are full origins, e.g. `'https://cdn.example.com'`.
+* **policies** {Object} — app-named policies to register alongside `default`. Keys must appear in the CSP `trusted-types` allowlist. Values are one of:
+  * `'staticHtml'` — pass-through preset: `createHTML` returns the input unchanged (author-controlled markup only; must never receive user-influenced data), plus a same-origin `createScriptURL`
+  * an **hooks object** — `{ createHTML, createScriptURL, createScript }` passed straight to `trustedTypes.createPolicy`
+  * `{ hooks, helper }` — hooks as above, plus an optional `helper(window)` callback invoked after registration (e.g. to attach a convenience global)
+* **logViolations** {Boolean} — default `true`. `console.warn` on `securitypolicyviolation` events. Cheap development aid; the event never fires in a healthy prod environment.
+* **shimWhenUnavailable** {Boolean} — default `true`. When enforcing but the browser has no Trusted Types (it ignores `require-trusted-types-for` anyway), install the passthrough shim so unconditional `trustedTypes.createPolicy(...)` calls elsewhere never throw and plain strings pass through as before.
+
+### defaultPolicyHooks(options)
+Returns the hook object for the reserved `default` policy, for apps that want to register policies manually (e.g. with their own timing or a custom policy name set). Accepts `{ scriptURLOrigins }` as in the config above. No `createScript` hook is included.
+
+### escapeHtml(input)
+Applies the industry-standard 6-character escape — `& < > " ' \`` → `&amp; &lt; &gt; &quot; &#x27; &#x60;` — for safe interpolation into HTML markup, in element content **and** attribute values. Output is byte-identical to [`he.escape`](https://github.com/mathiasbynens/he) for all inputs where `he` does not throw; `null`/`undefined` yield `''`. Exported here so build-time or computed contexts can use the same escape the runtime `default` policy applies.
+
+### shimTrustedTypes(window)
+Installs the passthrough shim on a window (see [lib/shim.js](lib/shim.js)): `trustedTypes.createPolicy` returns plain-string pass-through hooks, and `document.createElement('script').src = x` never throws (the setter coerces to string). Idempotent — does nothing when `trustedTypes` already exists.
+
+### setWindow(target)
+Overrides the window reference used for policy registration (resolved at call time, defaulting to `globalThis`). Primarily a test hook; apps do not need it.
+
+## Sanitize Sub-Path
+
+The **escape tier** (default behavior) is strict: six characters escaped, nothing else rendered as markup. For rendering **untrusted rich content** (user-supplied posts, importable documents) you want the **sanitize tier**: DOMPurify strips dangerous markup while preserving an allow-list of safe HTML. It lives behind a separate entry point so only apps that import it pay the ~11 KB gzip cost:
+
+```js
+// Only this module imports dompurify (~11 KB gzip). Apps without rich content
+// never pay for it.
+import { createSanitizerPolicy } from '@localnerve/trusted-types-bootstrap/sanitize';
+
+const policy = createSanitizerPolicy('app-rich', {
+  USE_PROFILES: { html: true },   // DOMPurify config passthrough
+  ALLOWED_TAGS: ['b', 'i', 'em', 'strong']
+});
+
+// at the sink:
+el.innerHTML = policy.createHTML(dirtyHtml);
+```
+
+* **createSanitizerPolicy(name, dompurifyConfig)** — creates a named policy whose `createHTML` calls `DOMPurify.sanitize(input, { ...config, TRUSTED_TYPES_POLICY: null })`. The `TRUSTED_TYPES_POLICY: null` is forced internally (any caller-supplied value is ignored) so DOMPurify does **not** create its internal `dompurify` policy — which would break a computed CSP allowlist. Returns `null` when Trusted Types is unavailable; fall back to plain-string passthrough or use the exported `purify` instance directly.
+* **purify** — a `DOMPurify` instance bound to the current window, for sanitizing without a policy (e.g. dev builds without enforcement).
+
+The policy name is the first argument and must be in the CSP allowlist, detected by `@localnerve/trusted-types-rules` as usual since it is declared at this call site.
+
+## Relationship to Other Packages
+
+| Package | Scope | TT role |
+| --- | --- | --- |
+| [`@localnerve/web-component-build`](https://github.com/localnerve/web-component-build) | web component build pipeline | **Component-level** runtime helpers (`escapeHtml`, `getTrustedPolicy`, `trustedHtml`) inlined into each component's bundle; components register their own named policy. |
+| `@localnerve/trusted-types-bootstrap` (this) | app/page-level bootstrap | Registers the app's `default` + named policies, shim, violation logging. One call per app. |
+| [`@localnerve/trusted-types-rules`](https://github.com/localnerve/trusted-types-rules) | build-time audit | Computes the CSP `trusted-types` allowlist from built JS (AST). Consumes output of both above; no special handling needed. |
+
+The 6-char escape exists in two places by design: wcb's `escapeHtml` (component-level, build-time-inlined) and this package's core (app-level, runtime). They must stay byte-identical — a shared test vector (`ESCAPE_VECTORS` in [`__tests__/escape.spec.js`](__tests__/escape.spec.js), verified against `he.escape`) guards that drift.
+
+## Development
+
+```sh
+npm install
+npm test        # node --test with coverage (lcov written to coverage/)
+npm run lint    # eslint
+```
+
+Tests run under Node (see `.nvmrc`); the browser path is exercised with jsdom plus a fake `trustedTypes` recorder — jsdom has no native Trusted Types, and policy registration through `createPolicy` + hooks is exactly the API surface this package relies on.
+
+## License
+
+BSD-3-Clause — see [LICENSE.md](LICENSE.md).
+
+Copyright (c) 2026 Alex Grant (@localnerve), LocalNerve LLC

package/index.js

@@ -0,0 +1,141 @@
+/**
+ * Page-level Trusted Types bootstrap.
+ * 
+ * One import + one config call replaces the per-app inline bootstrap script:
+ * registers the reserved `default` policy (escaping createHTML, allowlisted
+ * createScriptURL, no createScript), optional app-named policies, a passthrough
+ * shim for browsers without Trusted Types, and securitypolicyviolation logging.
+ * 
+ * The default config replicates jam-build's inline bootstrap exactly:
+ * - `enforce: 'auto'` registers policies only when a CSP meta tag is present
+ *   (production builds); dev builds with no meta register nothing so plain
+ *   strings pass through.
+ * - Named policies are declared at the call site, so
+ *   @localnerve/trusted-types-rules keeps detecting them via AST analysis for
+ *   the computed CSP `trusted-types` allowlist.
+ * 
+ * This module must run before any other app code (e.g. as the page's first
+ * inline script) so policies exist when sinks are first hit.
+ * 
+ * Copyright (c) 2026 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+
+import { escapeHtml } from './lib/escape.js';
+import { shimTrustedTypes } from './lib/shim.js';
+
+// window is resolved at call time (not import time) so bundlers and tests can
+// control it; setWindow() overrides the global reference (used by tests).
+let win = typeof globalThis !== 'undefined' ? globalThis : null;
+
+/**
+ * Override the window reference used for policy registration.
+ * 
+ * @param {Window} target - The window to register policies on (or null to reset to globalThis).
+ */
+export function setWindow (target) {
+  win = target === undefined ? (typeof globalThis !== 'undefined' ? globalThis : null) : target;
+}
+
+/**
+ * Hooks for the reserved `default` policy.
+ * 
+ * - createHTML: industry-standard 6-char escape, safe in element-content and
+ *   attribute contexts.
+ * - createScriptURL: only origins in scriptURLOrigins pass (default same-origin).
+ * - No createScript hook: eval() / new Function() stay blocked by CSP.
+ * 
+ * @param {Object} [options] - Options.
+ * @param {Array<String>} [options.scriptURLOrigins] - Origins allowed by createScriptURL. 'self' means same-origin (default). Extra entries are full origins, e.g. 'https://cdn.example.com'.
+ * @returns {Object} The policy hooks object.
+ */
+export function defaultPolicyHooks (options = {}) {
+  const origins = options.scriptURLOrigins || ['self'];
+  return {
+    createHTML: input => escapeHtml(input),
+    createScriptURL: (input, opts) => {
+      const url = new URL(String(input), opts?.baseUrl || win?.location?.href || 'http://localhost/');
+      const allowed = origins.some(o => o === 'self' ? url.origin === win.location.origin : url.origin === o);
+      if (!allowed) {
+        throw new TypeError('Trusted Types: script URL rejected by default policy: ' + url);
+      }
+      return url.href;
+    }
+  };
+}
+
+/**
+ * Build the hook object for a named policy from its config entry.
+ * 
+ * @param {Object|String} spec - Either a hooks object ({createHTML, createScriptURL, createScript}) or 'staticHtml' for the pass-through preset (author-controlled markup only; must never receive user-influenced data).
+ * @returns {Object} The policy hooks object.
+ */
+function namedPolicyHooks (spec) {
+  if (typeof spec === 'string') {
+    if (spec !== 'staticHtml') {
+      throw new TypeError('trusted-types-bootstrap: unknown preset "' + spec + '"');
+    }
+    return {
+      createHTML: input => String(input),
+      createScriptURL: input => new URL(String(input), win.location.href).href
+    };
+  }
+  return spec;
+}
+
+/**
+ * Bootstrap page-level Trusted Types.
+ * 
+ * @param {Object} [config] - Configuration.
+ * @param {'auto'|Boolean} [config.enforce='auto'] - 'auto' (default): enforce only when a CSP meta tag (meta[http-equiv="Content-Security-Policy"]) is present, i.e. production builds. true/false override detection.
+ * @param {Array<String>} [config.scriptURLOrigins] - Origins allowed by the default policy's createScriptURL. Default ['self'] (same-origin only).
+ * @param {Object} [config.policies] - App-named policies to register alongside `default`. Keys must appear in the CSP trusted-types allowlist (computed by @localnerve/trusted-types-rules). Values: 'staticHtml' preset, a hooks object, or {hooks, helper}.
+ * @param {Boolean} [config.logViolations=true] - console.warn on securitypolicyviolation events (development aid; cheap and the event never fires in healthy prod).
+ * @param {Boolean} [config.shimWhenUnavailable=true] - Install the passthrough shim when the browser has no Trusted Types, so unconditional createPolicy calls never throw.
+ */
+export function bootstrapTrustedTypes (config = {}) {
+  const {
+    enforce = 'auto',
+    scriptURLOrigins,
+    policies = {},
+    logViolations = true,
+    shimWhenUnavailable = true
+  } = config;
+
+  if (!win || typeof win.document === 'undefined') {
+    throw new TypeError('trusted-types-bootstrap: no window/document available');
+  }
+
+  const hasTT = 'trustedTypes' in win;
+  const cspEnforced = !!win.document.querySelector('meta[http-equiv="Content-Security-Policy"]');
+  const shouldEnforce = enforce === 'auto' ? cspEnforced : Boolean(enforce);
+
+  if (logViolations) {
+    win.addEventListener('securitypolicyviolation', e => console.warn(
+      'CSP violation:', e.violatedDirective, e.blockedURI || ''
+    ));
+  }
+
+  if (!shouldEnforce) return false; // passthrough (dev / no CSP meta): nothing to register
+
+  if (!hasTT) {
+    // enforcing, but the browser has no Trusted Types (it ignores
+    // require-trusted-types-for anyway): shim so unconditional createPolicy
+    // calls elsewhere never throw and plain strings pass through as before.
+    if (shimWhenUnavailable) shimTrustedTypes(win);
+    return false;
+  }
+
+  win.trustedTypes.createPolicy('default', defaultPolicyHooks({ scriptURLOrigins }));
+
+  for (const [name, value] of Object.entries(policies)) {
+    const hooks = typeof value === 'object' && value !== null ? value.hooks : value;
+    const helper = typeof value === 'object' && value !== null ? value.helper : null;
+    win.trustedTypes.createPolicy(name, namedPolicyHooks(hooks));
+    if (typeof helper === 'function') helper(win);
+  }
+
+  return true;
+}
+
+export { escapeHtml, shimTrustedTypes };

package/lib/escape.js

@@ -0,0 +1,33 @@
+/**
+ * Industry-standard HTML escaping - single source of truth for this package.
+ * 
+ * MUST stay byte-identical to @localnerve/web-component-build's escapeHtml
+ * (the component-level, build-time-inlined copy). The shared test vector in
+ * __tests__/escape.spec.js guards against drift between the two.
+ * 
+ * Copyright (c) 2026 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+
+/**
+ * Escape a value for safe interpolation into HTML markup (text or attribute).
+ *
+ * Applies the industry-standard escape of all six characters that can break
+ * out of a text or attribute context: & < > " ' and backtick. Escaping quotes
+ * and the backtick (not just &lt;/&gt;) is what makes the result safe to reuse
+ * inside an attribute value, not only element content. Output is byte-identical
+ * to he.escape() for all inputs where he does not throw (null/undefined).
+ *
+ * @param {Any} input - The value to escape
+ * @returns {String} The escaped string. null/undefined yield ''.
+ */
+export function escapeHtml (input) {
+  if (input === null || typeof input === 'undefined') return '';
+  return String(input)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;')
+    .replace(/`/g, '&#x60;');
+}

package/lib/sanitize.js

@@ -0,0 +1,47 @@
+/**
+ * Opt-in DOMPurify-backed sanitizer policy.
+ * 
+ * Only this module imports dompurify (~11 KB gzip minified); apps that never
+ * import the `/sanitize` sub-path do not pay for it (separate entry point,
+ * tree-shakeable). Use this tier to render untrusted rich content (user posts,
+ * imported documents) - never plain escaping for rich markup.
+ * 
+ * TT integration: sanitize() is called inside this policy's own createHTML with
+ * TRUSTED_TYPES_POLICY: null so DOMPurify does NOT create its internal
+ * `dompurify` policy (which would break a computed CSP allowlist).
+ * 
+ * Copyright (c) 2026 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+
+import DOMPurify from 'dompurify';
+
+/**
+ * Create a named Trusted Types policy that sanitizes input with DOMPurify.
+ * 
+ * The policy name must appear in the CSP `trusted-types` allowlist (detected
+ * by @localnerve/trusted-types-rules as usual - it is declared at this call site).
+ * 
+ * @param {String} name - The policy name (CSP-allowlisted).
+ * @param {Object} [config] - DOMPurify configuration passthrough, e.g. {USE_PROFILES: {html: true}, ALLOWED_TAGS: ['b', 'i']}. TRUSTED_TYPES_POLICY is always forced to null; any value passed for it is ignored.
+ * @returns {TrustedTypePolicy|null} The policy when Trusted Types is available, otherwise null (callers should fall back to DOMPurify.sanitize directly, or a passthrough string).
+ */
+export function createSanitizerPolicy (name, config = {}) {
+  const w = typeof window !== 'undefined' ? window : null;
+  if (!w || !('trustedTypes' in w)) return null;
+
+  const dompurify = DOMPurify(w); // bind to the app's window
+
+  return w.trustedTypes.createPolicy(name, {
+    createHTML: input => dompurify.sanitize(String(input), {
+      ...config,
+      TRUSTED_TYPES_POLICY: null
+    })
+  });
+}
+
+/**
+ * DOMPurify instance bound to the current window. Exposed so callers can also
+ * sanitize without a policy (e.g. in dev builds without enforcement).
+ */
+export const purify = typeof window !== 'undefined' ? DOMPurify(window) : null;

package/lib/shim.js

@@ -0,0 +1,55 @@
+/**
+ * Passthrough shim for browsers without Trusted Types support.
+ * 
+ * Browsers without Trusted Types ignore `require-trusted-types-for`, so plain
+ * strings pass through all sinks as before; the shim exists purely so code that
+ * calls `trustedTypes.createPolicy(...)` unconditionally (e.g. this package's
+ * policy registration, or web components built with wcb) never throws in those
+ * browsers.
+ * 
+ * Copyright (c) 2026 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+
+/**
+ * Install a passthrough Trusted Types shim on a window.
+ *
+ * - `trustedTypes.createPolicy` returns plain-string pass-through hooks, so
+ *   policy registration is a no-op with the same call signature as the real API.
+ * - `document.createElement('script').src = x` never throws: the setter coerces
+ *   to a string, guarding against a sink ever receiving an unexpected type.
+ *
+ * @param {Window} w - The window object to patch.
+ */
+export function shimTrustedTypes (w) {
+  if ('trustedTypes' in w) return; // already available: nothing to shim
+
+  const tt = {
+    createPolicy: () => ({
+      createHTML: s => String(s),
+      createScript: s => String(s),
+      createScriptURL: s => String(s)
+    })
+  };
+  Object.defineProperty(w, 'trustedTypes', { value: tt, writable: true });
+
+  // keep <script src> assignment from throwing on a non-string in case a sink
+  // ever receives an unexpected type; everything else passes through untouched
+  const origCreateElement = w.document.createElement.bind(w.document);
+  w.document.createElement = (tagName, ...rest) => {
+    const el = origCreateElement(tagName, ...rest);
+    if (/^script$/i.test(tagName)) {
+      Object.defineProperty(el, 'src', {
+        set (v) {
+          try {
+            el.setAttribute('src', String(v));
+          } catch { /* ignore */ }
+        },
+        get () {
+          return el.getAttribute('src');
+        }
+      });
+    }
+    return el;
+  };
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@localnerve/trusted-types-bootstrap",
+  "version": "0.1.0-rc.1",
+  "description": "Page-level Trusted Types bootstrap for web apps: one import + config call replaces the per-app inline bootstrap script. Optional DOMPurify-backed sanitizer policy sub-path.",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./sanitize": "./lib/sanitize.js"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "pretest": "node -e \"const fs=require('fs');fs.rmSync('./coverage',{recursive:true,force:true});fs.mkdirSync('./coverage',{recursive:true})\"",
+    "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-coverage-exclude=\"__tests__/**\" ./__tests__/*.spec.js"
+  },
+  "files": [
+    "index.js",
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/localnerve/trusted-types-bootstrap.git"
+  },
+  "keywords": [
+    "trusted types",
+    "csp",
+    "content security policy",
+    "xss",
+    "sanitize",
+    "web security",
+    "bootstrap"
+  ],
+  "author": {
+    "name": "Alex Grant",
+    "email": "alex@localnerve.com",
+    "url": "https://www.localnerve.com"
+  },
+  "maintainers": [
+    {
+      "name": "Alex Grant",
+      "email": "alex@localnerve.com",
+      "url": "https://www.localnerve.com"
+    }
+  ],
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/localnerve/trusted-types-bootstrap/issues"
+  },
+  "homepage": "https://github.com/localnerve/trusted-types-bootstrap#readme",
+  "dependencies": {
+    "dompurify": "^3.4.14"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.9.1",
+    "eslint-plugin-n": "^18.3.0",
+    "globals": "^17.12.0",
+    "he": "^1.2.0",
+    "jsdom": "^30.0.1"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/localnerve"
+    },
+    {
+      "type": "paypal",
+      "url": "https://www.paypal.com/ncp/payment/DHCB5GUYMGX5U"
+    }
+  ],
+  "engines": {
+    "node": ">=22"
+  }
+}