boxwood 2.0.0 → 2.1.0

package/.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(node test:*)",
       "Bash(mkdir:*)",
-      "Bash(npm test:*)"
+      "Bash(npm test:*)",
+      "Bash(mv:*)"
     ],
     "deny": []
   }

package/README.md

@@ -114,7 +114,76 @@ console.log(html)
 // <div><h1>Hello, World!</h1><p>Welcome to Boxwood</p></div>
 ```
 
-For Express apps, use [express-boxwood](https://www.npmjs.com/package/express-boxwood).
+### Express Integration
+
+Boxwood includes built-in Express support:
+
+```js
+import express from 'express'
+import engine from 'boxwood/adapters/express'
+import crypto from 'crypto'
+
+const app = express()
+
+// Register Boxwood as template engine
+app.engine('js', engine())
+app.set('views', './views')
+app.set('view engine', 'js')
+
+// CSP (Content Security Policy) nonce for inline scripts
+// A nonce is a unique random value generated for each request that allows
+// specific inline scripts to execute while blocking potential XSS attacks
+app.use((req, res, next) => {
+  // Generate a cryptographically secure random nonce
+  res.locals.nonce = crypto.randomBytes(16).toString('base64')
+  
+  // Set CSP header - only scripts with this exact nonce can execute
+  res.setHeader(
+    'Content-Security-Policy',
+    `script-src 'nonce-${res.locals.nonce}' 'strict-dynamic';`
+  )
+  next()
+})
+
+// Render templates - nonce is automatically injected into all inline scripts
+app.get('/', (req, res) => {
+  res.render('home', { title: 'Welcome' })
+  // Boxwood automatically adds nonce="${res.locals.nonce}" to script tags
+})
+```
+
+The Express adapter automatically:
+- Handles template caching in production
+- Hot reloads templates in development
+- Injects CSP nonces from `res.locals.nonce` into all inline scripts and styles
+
+#### Understanding CSP Nonces
+
+A Content Security Policy (CSP) nonce is a security feature that helps prevent Cross-Site Scripting (XSS) attacks:
+
+1. **Without CSP**: Any injected `<script>` tag can execute, making XSS attacks possible
+2. **With CSP nonce**: Only scripts with the correct nonce attribute can run
+3. **How it works**:
+   - Server generates a unique random nonce for each request
+   - Server adds this nonce to the CSP header: `script-src 'nonce-abc123'`
+   - Server adds the same nonce to legitimate scripts: `<script nonce="abc123">`
+   - Browser only executes scripts that have the matching nonce
+   - Attackers can't guess the nonce, so injected scripts are blocked
+
+Example output:
+```html
+<!-- HTTP Header -->
+Content-Security-Policy: script-src 'nonce-rAnd0m123' 'strict-dynamic';
+
+<!-- Generated HTML -->
+<script nonce="rAnd0m123">
+  console.log("This legitimate script will execute")
+</script>
+
+<script>
+  console.log("This injected script will be blocked!")
+</script>
+```
 
 ## Features
 

package/adapters/express/index.js

@@ -0,0 +1,49 @@
+const NODE_ENV = process.env.NODE_ENV || "development"
+const { compile } = require("../..")
+
+function purge(path) {
+  const name = require.resolve(path)
+  const dependency = require.cache[name]
+  if (dependency && dependency.children) {
+    dependency.children.forEach((child) => {
+      delete require.cache[child.id]
+      purge(child.id)
+    })
+    delete require.cache[name]
+  }
+}
+
+function engine(options = {}) {
+  const env = options.env || NODE_ENV
+  const cache = new Map()
+  async function compileFile(path) {
+    if (env === "development") {
+      purge(path)
+      const { template } = await compile(path)
+      return template
+    }
+    if (cache.has(path)) return cache.get(path)
+    const { template } = await compile(path)
+    cache.set(path, template)
+    return template
+  }
+
+  async function render(path, options, callback) {
+    try {
+      const template = await compileFile(path)
+      // Automatically inject nonce from res.locals if available
+      const templateOptions = options && options._locals && options._locals.nonce
+        ? { ...options, nonce: options._locals.nonce }
+        : options
+      const html = template(templateOptions)
+      if (callback) return callback(null, html)
+      return html
+    } catch (error) {
+      if (callback) return callback(error)
+      return error.message
+    }
+  }
+  return render
+}
+
+module.exports = engine

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "boxwood",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Compile HTML templates into JS",
   "main": "index.js",
   "types": "index.d.ts",
+  "exports": {
+    ".": "./index.js",
+    "./adapters/express": "./adapters/express/index.js"
+  },
   "scripts": {
     "test": "node --test --test-reporter=dot \"test/**/*.test.js\" \"test/**/*.spec.js\"",
     "test:debug": "node --test --test-reporter=spec \"test/**/*.test.js\" \"test/**/*.spec.js\"",