Security Hardening: XSS Protection (v1.1.0) (#10)

## Overview
Adds built-in XSS protection with attribute sanitization, URL scheme
validation, and same-origin enforcement for template includes.

## What's New
- 🔒 **Default XSS Protection**: Blocks dangerous attributes (`on*`,
`srcdoc`), validates URL schemes, enforces same-origin
- 📦 **Dual Bundle**: `faintly.js` (2736b) + `faintly.security.js` (646b)
= 3382 bytes gzipped (under 6KB limit)
- 🔧 **Configurable**: Disable with `security: false`, customize with
config, or provide custom hooks
- 🛡️ **Template Security**: Initial template fetch now protected by
same-origin check
- 🚀 **Performance**: Security initialized once per render, no overhead
in directives

## Security Features
### Attribute Sanitization
- Blocks event handlers: `/^on/i` pattern (onclick, onerror, etc.)
- Blocks dangerous attributes: `srcdoc`
- Validates URL schemes in `href`, `src`, `action`, `formaction`,
`xlink:href`
- Allows: `http:`, `https:`, `mailto:`, `tel:` (relative URLs always
allowed)

### Template Include Protection
- Enforces same-origin for all template includes
- Protects initial template fetch in `resolveTemplate()`
- Blocks cross-origin URLs early with clear warnings

## Documentation
- ✅ Comprehensive README security section with examples
- ✅ AGENTS.md updated with security module guidelines
- ✅ Strong warnings about user-supplied data in context

## Testing
- ✅ **94 tests passed, 0 skipped**
- ✅ **100% code coverage maintained**
- ✅ All existing tests pass (backward compatible)
- ✅ TDD approach for all security features

## Architecture
- Security initialization in `renderElement()` (single point, happens
once)
- `initializeSecurity()` exported for tests calling directives directly
- Directives use `context.security` directly (clean separation)
- Security module dynamically loaded on first use (tree-shakeable)

## Backward Compatibility
✅ **Fully backward compatible** - existing code works unchanged
- Security enabled by default (transparent to users)
- `security: false` or `security: 'unsafe'` to disable
- Custom security hooks supported

## Breaking Changes
None. This is a minor version bump (`1.0.1` → `1.1.0`).

## Bundle Size
- Core: 2736 bytes gzipped (under 4KB limit)
- Security: 646 bytes gzipped
- **Total: 3382 bytes gzipped** (well under 6KB limit)

## Commits
1. Phase 1: Clean slate with directives.js security integration
2. Implement shouldAllowAttribute with TDD approach
3. Remove inline comments from DEFAULT_CONFIG
4. Unskip default security test for processAttributes
5. Refactor to allowedTemplatePaths and unskip all tests
6. Simplify allowIncludePath to same-origin only
7. Add comprehensive security documentation to README
8. Update AGENTS.md with security module documentation
9. Refactor security initialization to renderElement
10. Bump version to 1.1.0 for security feature release

Author: shsteimer

AGENTS.md

@@ -5,6 +5,7 @@ Authoritative guide for AI/code agents contributing to this repository.
 ### Project purpose
 - **What this is**: A small, dependency-free HTML templating/DOM rendering library for AEM Edge Delivery Services blocks (and other HTML fragments).
 - **Public API**: `renderBlock(element, context?)`, `renderElement(element, context?)` exported from `src/index.js` and bundled to `dist/faintly.js`.
+- **Security**: Built-in XSS protection via `src/faintly.security.js`, bundled to `dist/faintly.security.js` (dynamically loaded by default).
 
 ### Environment
 - **Node**: 20 (CI uses Node 20).
@@ -43,41 +44,60 @@ Authoritative guide for AI/code agents contributing to this repository.
   - Keep modules small and readable; avoid deep nesting; avoid unnecessary try/catch.
 
 ### Build and artifacts
-- Bundling uses `esbuild` to produce a single ESM file at `dist/faintly.js` for browser usage.
-- CI enforces a gzipped bundle size limit of **5KB (5120 bytes)**. Keep additions small; avoid adding heavy dependencies.
-- If you change source under `src/`, run `npm run build` so `dist/faintly.js` is up to date.
+- Bundling uses `esbuild` to produce two ESM bundles for browser usage:
+  - `dist/faintly.js` (core library, gzipped limit: **4KB / 4096 bytes**)
+  - `dist/faintly.security.js` (security module, separate to allow tree-shaking)
+- CI enforces a **combined gzipped size limit of 6KB (6144 bytes)** for both files.
+- Keep additions small; avoid adding heavy dependencies.
+- If you change source under `src/`, run `npm run build` so `dist/` artifacts are up to date.
 
 ### CI behavior (GitHub Actions)
 - Workflow: `.github/workflows/main.yaml` runs on pull requests (open/sync/reopen).
 - Steps: checkout → Node 20 → `npm ci` → `npm run lint` → `npm test` → `npm run build:strict`.
 - The workflow will attempt to commit updated `dist/` artifacts back to the PR branch if they changed.
 
 ### Repo layout
-- `src/`: library source (`index.js`, `render.js`, `directives.js`, `expressions.js`, `templates.js`).
-- `dist/`: built artifact (`faintly.js`).
-- `test/`: unit/perf tests, fixtures, snapshots, and utilities.
-- `coverage/`: coverage output when tests are run with coverage.
+- `src/`: library source
+  - Core: `index.js`, `render.js`, `directives.js`, `expressions.js`, `templates.js`
+  - Security: `faintly.security.js`
+- `dist/`: built artifacts (`faintly.js`, `faintly.security.js`)
+- `test/`: unit/perf tests, fixtures, snapshots, and utilities
+  - `test/security/`: tests for security module
+- `coverage/`: coverage output when tests are run with coverage
 
 ### Contribution checklist for agents
 1. Install deps with `npm ci`.
 2. Make focused edits under `src/` and relevant tests under `test/`.
 3. Run `npm run lint:fix` then `npm run lint` and resolve any remaining issues.
 4. Run `npm test` and ensure coverage stays at 100%.
-5. Run `npm run build:strict` and verify `dist/faintly.js` updates (if source changed).
-6. Ensure gzipped size of `dist/faintly.js` remains <= 5120 bytes (CI will enforce).
+5. Run `npm run build:strict` and verify `dist/` artifacts update (if source changed).
+6. Ensure combined gzipped size remains <= 6144 bytes (CI will enforce).
 7. Update `README.md` if you change public behavior or usage.
 8. Commit changes; open a PR. CI will validate and may commit updated `dist/` to the PR branch.
 
 ### Public API and usage (for context)
-- Consumers copy `dist/faintly.js` into their AEM project and use:
+- Consumers copy `dist/faintly.js` and `dist/faintly.security.js` into their AEM project and use:
   - `renderBlock(block, context?)`
   - `renderElement(element, context?)`
-- See `README.md` for examples, directives, and expression syntax.
+- Security is **enabled by default** and dynamically loads `faintly.security.js` on first use.
+- See `README.md` for examples, directives, expression syntax, and security configuration.
 
 ### Guardrails and constraints
 - Keep the bundle tiny; avoid adding runtime deps.
 - Maintain 100% test coverage; do not reduce thresholds or exclude more files.
 - Respect ESM and `.js` extension import rule.
 - Do not introduce Node-only APIs into browser code paths.
 
+### Security module (`src/faintly.security.js`)
+- Provides default XSS protection: attribute sanitization, URL scheme validation, same-origin enforcement.
+- Exported as a separate bundle (`dist/faintly.security.js`) for tree-shaking in opt-out scenarios.
+- Dynamically imported by `directives.js` when `context.security` is undefined.
+- Users can disable (`security: false`), provide custom hooks, or override default configuration.
+- When modifying security:
+  - **Test thoroughly** - security bugs have serious consequences.
+  - Use TDD approach with comprehensive test coverage.
+  - Document changes in `README.md` security section.
+  - Consider backwards compatibility for existing users.
+  - Be conservative about what is allowed by default.
+
 

README.md

@@ -10,9 +10,9 @@ I've experimented with other existing libraries (ejs templates, etc.) but wanted
 
 ## Getting Started
 
-1. copy the /dist/faintly.js file to the scripts directory of your project
-2. in the folder for your block, add a `blockName.html` file for the block template
-3. in your block javascript, call the `renderBlock` function:
+1. Copy the `/dist/faintly.js` and `/dist/faintly.security.js` files to the scripts directory of your project
+2. In the folder for your block, add a `blockName.html` file for the block template
+3. In your block javascript, call the `renderBlock` function:
 
 ```
 import { renderBlock } from '../scripts/faintly.js';
@@ -55,6 +55,7 @@ The rendering context is a javascript object used to provide data to the templat
 * template
    * path - the path to the template being rendered
    * name - the template name, if there is one
+* security - security configuration (see Security section below)
 
 When in a repeat loop, it will also include:
 
@@ -70,6 +71,105 @@ When in a repeat loop, it will also include:
 > [!NOTE]  
 > Because element attributes are case-insensitive, context names are converted to lower case. e.g. `data-fly-test.myTest` will be set in the context as `mytest`.
 
+## Security
+
+Faintly includes built-in security features to help protect against XSS (Cross-Site Scripting) attacks. By default, security is **enabled** and provides:
+
+* **Attribute sanitization** - Blocks dangerous attributes like event handlers (`onclick`, `onerror`, etc.) and `srcdoc`
+* **URL scheme validation** - Restricts URLs in attributes like `href` and `src` to safe schemes (`http:`, `https:`, `mailto:`, `tel:`)
+* **Same-origin enforcement** - Template includes are restricted to same-origin URLs only
+
+### Default Security
+
+When you call `renderBlock()` without a security context, default security is automatically applied:
+
+```javascript
+await renderBlock(block); // Default security enabled
+```
+
+The default security module (`dist/faintly.security.js`) is dynamically loaded on first use.
+
+### Custom Security
+
+For more control, you can provide a custom security object with `shouldAllowAttribute` and `allowIncludePath` hooks:
+
+```javascript
+await renderBlock(block, {
+  security: {
+    shouldAllowAttribute(attrName, value) {
+      // Return true to allow the attribute, false to block it
+      // Your custom logic here
+      return true;
+    },
+    allowIncludePath(templatePath) {
+      // Return true to allow the template include, false to block it
+      // Your custom logic here
+      return true;
+    },
+  },
+});
+```
+
+You can also use the default security module and override specific configuration:
+
+```javascript
+import createSecurity from './scripts/faintly.security.js';
+
+await renderBlock(block, {
+  security: createSecurity({
+    // Add 'data:' URLs to allowed schemes
+    allowedUrlSchemes: ['http:', 'https:', 'mailto:', 'tel:', 'data:'],
+    // Block additional attributes
+    blockedAttributes: ['srcdoc', 'sandbox'],
+  }),
+});
+```
+
+### Security Configuration Options
+
+The default security module accepts the following configuration:
+
+* `blockedAttributePatterns` (Array<RegExp>) - Regex patterns for blocked attribute names (default: `/^on/i` blocks all event handlers)
+* `blockedAttributes` (Array<string>) - Specific attribute names to block (default: `['srcdoc']`)
+* `urlAttributes` (Array<string>) - Attributes that contain URLs to validate (default: `['href', 'src', 'action', 'formaction', 'xlink:href']`)
+* `allowedUrlSchemes` (Array<string>) - Allowed URL schemes; relative URLs are always allowed (default: `['http:', 'https:', 'mailto:', 'tel:']`)
+
+
+### Disabling Security (Unsafe Mode)
+
+You can disable security if needed. **THIS IS NOT RECOMMENDED**
+
+
+> [!CAUTION]  
+> **THIS IS NOT RECOMMENDED**  and bypasses all XSS protection.
+
+```javascript
+await renderBlock(block, {
+  security: false, // or 'unsafe'
+});
+```
+
+
+### Trust Boundaries
+
+It's important to understand what Faintly's security does and doesn't protect:
+
+**Protected:**
+- ✅ Dangerous attributes (event handlers, `srcdoc`)
+- ✅ Malicious URL schemes (`javascript:`, `data:` by default)
+- ✅ Cross-origin template includes
+
+**Trusted (by design):**
+- The rendering context you provide is fully trusted
+- Templates fetched from your same-origin are trusted
+- DOM Node objects provided in context are inserted directly
+
+> [!WARNING]  
+> **Be extremely careful when adding user-supplied data to the rendering context.** URL parameters, form inputs, cookies, and other user-controlled data should be validated and sanitized before adding to the context. The context is fully trusted, so untrusted data placed in it can bypass security protections.
+
+> [!TIP]  
+> Security works best in layers. Faintly's security helps prevent common XSS vectors, but you should also: validate and sanitize user input before adding it to context, use Content Security Policy headers, and follow secure coding practices.
+
 ## Directives
 
 Faintly supports the following directives.
@@ -101,4 +201,4 @@ For `data-fly-include`, HTML text, and normal attributes, wrap your expression i
 
 Escaping: use a leading backslash to prevent evaluation of an expression in text/attributes, e.g. `\${some.value}` will remain literal `${some.value}`.
 
-In all other `data-fly-*` attributes, just set the expression directly as the attribute value, no wrapping needed.
+In all other `data-fly-*` attributes, just set the expression directly as the attribute value, no wrapping needed.

dist/faintly.js

@@ -3,6 +3,12 @@ var dp = new DOMParser();
 async function resolveTemplate(context) {
   context.template = context.template || {};
   context.template.path = context.template.path || `${context.codeBasePath}/blocks/${context.blockName}/${context.blockName}.html`;
+  if (context.security && context.template.path) {
+    const allowed = context.security.allowIncludePath(context.template.path, context);
+    if (!allowed) {
+      throw new Error(`Template fetch blocked by security policy: ${context.template.path}`);
+    }
+  }
   const templateId = `faintly-template-${context.template.path}#${context.template.name || ""}`.toLowerCase().replace(/[^0-9a-z]/g, "-");
   let template = document.getElementById(templateId);
   if (!template) {
@@ -69,10 +75,13 @@ async function processAttributesDirective(el, context) {
   el.removeAttribute("data-fly-attributes");
   if (attrsData) {
     Object.entries(attrsData).forEach(([k, v]) => {
+      const name = String(k);
       if (v === void 0) {
-        el.removeAttribute(k);
+        el.removeAttribute(name);
+      } else if (context.security.shouldAllowAttribute(name, v, context)) {
+        el.setAttribute(name, v);
       } else {
-        el.setAttribute(k, v);
+        el.removeAttribute(name);
       }
     });
   }
@@ -81,7 +90,13 @@ async function processAttributes(el, context) {
   await processAttributesDirective(el, context);
   const attrPromises = el.getAttributeNames().filter((attrName) => !attrName.startsWith("data-fly-")).map(async (attrName) => {
     const { updated, updatedText } = await resolveExpressions(el.getAttribute(attrName), context);
-    if (updated) el.setAttribute(attrName, updatedText);
+    if (updated) {
+      if (context.security.shouldAllowAttribute(attrName, updatedText, context)) {
+        el.setAttribute(attrName, updatedText);
+      } else {
+        el.removeAttribute(attrName);
+      }
+    }
   });
   await Promise.all(attrPromises);
 }
@@ -161,6 +176,13 @@ async function processInclude(el, context) {
     templatePath = path;
     templateName = name;
   }
+  if (templatePath) {
+    const allowed = context.security.allowIncludePath(templatePath, context);
+    if (!allowed) {
+      el.removeAttribute("data-fly-include");
+      return true;
+    }
+  }
   const includeContext = {
     ...context,
     template: {
@@ -217,11 +239,31 @@ async function renderTemplate(template, context) {
   processUnwraps(templateClone.content);
   return templateClone;
 }
+async function initializeSecurity(context) {
+  const { security } = context;
+  if (security === false || security === "unsafe") {
+    return {
+      shouldAllowAttribute: (() => true),
+      allowIncludePath: (() => true)
+    };
+  }
+  if (!security) {
+    const securityMod = await import("./faintly.security.js");
+    if (securityMod && securityMod.default) {
+      return securityMod.default();
+    }
+  }
+  return {
+    shouldAllowAttribute: security.shouldAllowAttribute || (() => true),
+    allowIncludePath: security.allowIncludePath || (() => true)
+  };
+}
 async function renderElementWithTemplate(el, template, context) {
   const rendered = await renderTemplate(template, context);
   el.replaceChildren(rendered.content);
 }
 async function renderElement(el, context) {
+  context.security = await initializeSecurity(context);
   const template = await resolveTemplate(context);
   await renderElementWithTemplate(el, template, context);
 }

dist/faintly.security.js

@@ -0,0 +1,60 @@
+// src/faintly.security.js
+var DEFAULT_CONFIG = {
+  blockedAttributePatterns: [/^on/i],
+  blockedAttributes: ["srcdoc"],
+  urlAttributes: ["href", "src", "action", "formaction", "xlink:href"],
+  allowedUrlSchemes: ["http:", "https:", "mailto:", "tel:"]
+};
+function isBlockedAttribute(attrName, blockedAttributePatterns, blockedAttributes) {
+  const name = attrName.toLowerCase();
+  return blockedAttributes.includes(name) || blockedAttributePatterns.some((pattern) => pattern.test(name));
+}
+function extractUrlScheme(value) {
+  const v = value.trim();
+  if (!v) return window.location.protocol;
+  const colonIndex = v.indexOf(":");
+  const slashIndex = v.indexOf("/");
+  if (colonIndex === -1 || slashIndex !== -1 && colonIndex > slashIndex) {
+    return window.location.protocol;
+  }
+  const url = new URL(v, window.location.origin);
+  return url.protocol;
+}
+function isUrlAttribute(attrName, urlAttributes) {
+  return urlAttributes.includes(attrName.toLowerCase());
+}
+function createSecurity(config = {}) {
+  const mergedConfig = {
+    ...DEFAULT_CONFIG,
+    ...config
+  };
+  const {
+    blockedAttributePatterns,
+    blockedAttributes,
+    urlAttributes,
+    allowedUrlSchemes
+  } = mergedConfig;
+  return {
+    shouldAllowAttribute(attrName, value) {
+      if (isBlockedAttribute(attrName, blockedAttributePatterns, blockedAttributes)) {
+        return false;
+      }
+      if (isUrlAttribute(attrName, urlAttributes)) {
+        const scheme = extractUrlScheme(value);
+        return allowedUrlSchemes.includes(scheme);
+      }
+      return true;
+    },
+    allowIncludePath(templatePath) {
+      if (!templatePath) {
+        return true;
+      }
+      const templateUrl = new URL(templatePath, window.location.origin);
+      return templateUrl.origin === window.location.origin;
+    }
+  };
+}
+export {
+  DEFAULT_CONFIG,
+  createSecurity as default
+};

package.json

@@ -1,6 +1,6 @@
 {
   "name": "faintly",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "HTML Markup Transformation Library for AEM Blocks",
   "main": "src/index.js",
   "scripts": {