From 85211b927138d64ef78a031043af29af4657aec1 Mon Sep 17 00:00:00 2001
From: Chris Zuber <shgysk8zer0@gmail.com>
Date: Mon, 5 Jan 2026 14:00:33 -0800
Subject: [PATCH] Add Trusted Types policy and html template tag

Introduces a new `createPolicy()` function in `trusted-html.js` to create a Trusted Types policy for HTML sanitization, supporting both direct string and tagged template usage. Adds an `html` tagged template function to automatically escape interpolated values, updates exports, configuration, and tests, and bumps the package version to 1.0.2.
---
 CHANGELOG.md         |  5 +++++
 html.js              |  7 +++++++
 html.test.js         | 22 ++++++++++++++++++-
 http.config.js       |  2 +-
 index.js             |  1 +
 package-lock.json    |  4 ++--
 package.json         |  6 +++++-
 rollup.config.js     | 11 ++++++++++
 trusted-html.js      | 37 ++++++++++++++++++++++++++++++++
 trusted-html.test.js | 50 ++++++++++++++++++++++++++++++++++++++++++++
 10 files changed, 140 insertions(+), 5 deletions(-)
 create mode 100644 trusted-html.js
 create mode 100644 trusted-html.test.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f37f425..32ca651 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v1.0.2] - 2026-01-05
+
+### Added
+- Add `createPolicy()` to create a `TrustedTypePolicy` with a `createHTML()` that escapes untrusted input
+
 ## [v1.0.1] - 2026-01-05
 
 ### Added
diff --git a/html.js b/html.js
index c73ecc1..9068dac 100644
--- a/html.js
+++ b/html.js
@@ -22,6 +22,13 @@ const _str = (str, fallback = '') => (str?.toString?.() ?? fallback);
 export const escapeHTML = str => _str(str)
 	.replaceAll(HTML_UNSAFE_PATTERN, char => HTML_REPLACEMENTS[char]);
 
+/**
+ * Tagged template function that automatically escapes interpolated values.
+ * @example html`<div class="${className}">${content}</div>`
+ */
+export function html(strings, ...values) {
+	return String.raw(strings, ...values.map(escapeHTML));
+}
 
 /**
  * Escapes characters that are unsafe or prohibited in HTML attribute names.
diff --git a/html.test.js b/html.test.js
index bfda068..6b95ef1 100644
--- a/html.test.js
+++ b/html.test.js
@@ -1,6 +1,6 @@
 import assert from 'node:assert';
 import { describe, test, before } from 'node:test';
-import { escapeHTML, escapeAttrName, stringifyAttr } from './html.js';
+import { escapeHTML, escapeAttrName, stringifyAttr, html } from './html.js';
 
 // Mock DOM Attr class for Node environment
 class MockAttr {
@@ -114,3 +114,23 @@ describe('Security Escaping Utils', () => {
 		});
 	});
 });
+
+describe('html tagged template', () => {
+	test('escapes interpolated values', () => {
+		const malicious = '<script>';
+		const output = html`<div>${malicious}</div>`;
+		assert.strictEqual(output, '<div>&lt;script&gt;</div>');
+	});
+
+	test('does not escape static template parts', () => {
+		const output = html`<span title="static"></span>`;
+		assert.strictEqual(output, '<span title="static"></span>');
+	});
+
+	test('handles multiple interpolations', () => {
+		const a = '<';
+		const b = '>';
+		const output = html`Start ${a} Middle ${b} End`;
+		assert.strictEqual(output, 'Start &lt; Middle &gt; End');
+	});
+});
diff --git a/http.config.js b/http.config.js
index 43ca2ec..c641d52 100644
--- a/http.config.js
+++ b/http.config.js
@@ -7,7 +7,7 @@ addScriptSrc(
 	'https://unpkg.com/@shgysk8zer0/',
 );
 
-addTrustedTypePolicy('aegis-sanitizer#html');
+addTrustedTypePolicy('aegis-sanitizer#html', 'default');
 
 export default {
 	routes: {
diff --git a/index.js b/index.js
index 1466b2f..0a145cd 100644
--- a/index.js
+++ b/index.js
@@ -1,2 +1,3 @@
 export { HTML_UNSAFE_PATTERN, ATTR_NAME_UNSAFE_PATTERN, HTML_REPLACEMENTS, escapeHTML, escapeAttrName, stringifyAttr } from './html.js';
+export { createPolicy } from './trusted-html.js';
 export { escapeCSS } from './css.js';
diff --git a/package-lock.json b/package-lock.json
index c221a1a..828ed5f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@aegisjsproject/escape",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@aegisjsproject/escape",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "funding": [
         {
           "type": "librepay",
diff --git a/package.json b/package.json
index 1c254f2..ed31340 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@aegisjsproject/escape",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "String escaping utilities for HTML and DOM attributes.",
   "keywords": [
     "security",
@@ -23,6 +23,10 @@
       "import": "./html.js",
       "require": "./html.cjs"
     },
+    "./trusted-html": {
+      "import": "./trusted-html.js",
+      "require": "./trusted-html.cjs"
+    },
     "./css": {
       "import": "./css.js",
       "require": "./css.cjs"
diff --git a/rollup.config.js b/rollup.config.js
index abb7aab..db41dea 100644
--- a/rollup.config.js
+++ b/rollup.config.js
@@ -22,6 +22,17 @@ export default [{
 		plugins: [terser()],
 		sourcemap: true,
 	}],
+}, {
+	input: 'trusted-html.js',
+	output: [{
+		file: 'trusted-html.cjs',
+		format: 'cjs',
+	}, {
+		file: 'trusted-html.min.js',
+		format: 'module',
+		plugins: [terser()],
+		sourcemap: true,
+	}],
 }, {
 	input: 'css.js',
 	output: [{
diff --git a/trusted-html.js b/trusted-html.js
new file mode 100644
index 0000000..6aa06fd
--- /dev/null
+++ b/trusted-html.js
@@ -0,0 +1,37 @@
+import { escapeHTML } from './html.js';
+
+const SUPPORTS_TRUSTED_TYPES = 'trustedTypes' in globalThis;
+const isTrustedHTML = SUPPORTS_TRUSTED_TYPES ? globalThis.trustedTypes.isHTML : () => false;
+
+function createHTML(strings, ...values) {
+	if (! Array.isArray(strings) || ! Array.isArray(strings.raw)) {
+		return Array.isArray(strings)
+			? strings.map(escapeHTML).join('')
+			: escapeHTML(strings);
+	} else {
+		return String.raw(strings, ...values.map(val => isTrustedHTML(val) ? val : escapeHTML(val)));
+	}
+}
+
+/**
+ * Creates a Trusted Types policy (or a compliant fallback) for sanitizing HTML.
+ * The returned policy's `createHTML` method is overloaded to handle both direct string arguments
+ * and tagged template literals.
+ *
+ * @param {string} [name="aegis-escape#html"] - The policy name. Must match your CSP `trusted-types` directive.
+ * @returns {TrustedTypePolicy} A native Policy object or a frozen fallback matching the interface.
+ *
+ * @example
+ * const policy = createPolicy();
+ *
+ * // 1. As a regular method:
+ * policy.createHTML('<div>Hello</div>');
+ *
+ * // 2. As a tagged template:
+ * policy.createHTML`<div>${userContent}</div>`;
+ */
+export function createPolicy(name = 'aegis-escape#html') {
+	return SUPPORTS_TRUSTED_TYPES
+		? globalThis.trustedTypes.createPolicy(name, { createHTML })
+		: Object.freeze({ name, createHTML });
+}
diff --git a/trusted-html.test.js b/trusted-html.test.js
new file mode 100644
index 0000000..b5a4e5e
--- /dev/null
+++ b/trusted-html.test.js
@@ -0,0 +1,50 @@
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+import { createPolicy } from './trusted-html.js';
+
+const policy = createPolicy('default');
+const html = policy.createHTML;
+
+describe('Trusted HTML Policy (Node/Fallback Mode)', () => {
+
+	test('Tag Usage: escapes unsafe values', () => {
+		const unsafe = '<img src=x onerror=alert(1)>';
+		const result = html`<div>${unsafe}</div>`;
+
+		assert.strictEqual(result, '<div>&lt;img src=x onerror=alert(1)&gt;</div>');
+	});
+
+	test('Direct Usage: escapes input string', () => {
+		const result = html('<script>alert(1)</script>');
+		assert.strictEqual(result, '&lt;script&gt;alert(1)&lt;/script&gt;');
+	});
+
+	test('Array Usage: joins and escapes list items', () => {
+		// Essential to ensure arrays are not stringified with commas
+		const items = ['<br>', '<b>bold</b>'];
+		const result = html`Items: ${items}`;
+
+		assert.strictEqual(result, 'Items: &lt;br&gt;,&lt;b&gt;bold&lt;/b&gt;');
+	});
+
+	test('Security: enforces Double Escaping in fallback mode', () => {
+		/* * CRITICAL SECURITY CHECK:
+		 * Since we are in Node (no TrustedTypes), the output of `html` is just a string.
+		 * If we nest this string into another template, it MUST be escaped again.
+		 * If it wasn't, we would be vulnerable to "fake trust".
+		 */
+		const inner = html`<span>Safe</span>`;
+		// inner is string: "<span>Safe</span>"
+
+		const outer = html`<div>${inner}</div>`;
+		// outer sees a string, so it escapes it: "<div>&lt;span&gt;Safe&lt;/span&gt;</div>"
+
+		assert.strictEqual(outer, '<div>&lt;span&gt;Safe&lt;/span&gt;</div>');
+	});
+
+	test('Interface: returns a policy-like object', () => {
+		// Ensures the return value matches the TrustedTypePolicy interface shape
+		assert.strictEqual(typeof policy.createHTML, 'function');
+		assert.strictEqual(policy.name, 'default');
+	});
+});