HTML Node Sanitisation & Sandbox

1. Front Matter

• Title: HTML Node Sanitisation & Sandbox

• Author: Joshua Uriel Tribiana

• Handover To: Clyde Ador (to do)

• Reviewers: JD Billate

• Created: 07-02-2026

• Status: Handover (To Do)

• References:

  • Feature: [3.10] HTML Node Sanitisation & Sandbox

2. Introduction & Goals

Problem Summary

Custom HTML nodes allow creators to embed rich and interactive content, but this also creates an XSS and script-execution attack surface. Sanitisation and sandbox controls are required to reduce risk while preserving useful embed functionality.

Goals

• Sanitize custom HTML content before rendering in preview and learner surfaces.

• Remove dangerous URL protocols and disallowed attributes.

• Restrict iframe behavior through sandbox controls.

• Preserve supported interactive content (forms, media, SVG, templates) for learning use cases.

Non-Goals

• Full untrusted-code isolation equivalent to a separate origin sandbox runtime.

• Perfect script containment when scripts are intentionally enabled.

• Server-side malware scanning or WAF-level inspection in this feature scope.

Glossary

• Code Node: Visual canvas node type that stores raw HTML in codeContent.

• Sanitisation: Tag and attribute filtering plus protocol checks before render.

• Sandbox: Browser restrictions applied to iframe execution context.

• Inline Script Execution Pipeline: Utility that extracts scripts and executes them after injecting sanitized HTML.

3. High-Level Architecture

SYSTEM DIAGRAM
 
                    CREATOR SIDE
+---------------------------+
| Creator Code Node Editor  |
+---------------------------+
              |
              v
+---------------------------+
| sanitizeHtml              |
+---------------------------+
              |
              v
+---------------------------+
| Preview Container         |
+---------------------------+
              |
              v
+---------------------------+
| executeHtmlWithScripts    |
+---------------------------+
 
 
                    LEARNER SIDE
+---------------------------+
| Learner Renderer          |
+---------------------------+
              |
              v
+---------------------------+
| sanitizeHtml              |
+---------------------------+
              |
              v
+---------------------------+
| Injected HTML Container   |
+---------------------------+
              |
              v
+---------------------------+
| executeHtmlWithScripts    |
+---------------------------+
 
 
                 FORM EDITOR PREVIEW
+---------------------------+
| Form Editor Preview       |
+---------------------------+
              |
              v
+---------------------------+
| iframe (srcDoc)           |
+---------------------------+
              |
              v
+---------------------------+
| sandbox (allow-scripts)   |
+---------------------------+
 
 
               CANVAS ARCHIVE FLOW
+---------------------------+
| Canvas Node              |
+---------------------------+
              |
              v
+---------------------------+
| Context Menu             |
| - Archive                |
+---------------------------+

Technologies Used

• Next.js / React / TypeScript

• Custom HTML sanitizer in lib/utils/sanitize-html.ts

• Script execution helper in lib/utils/execute-html-with-scripts.ts

• Monaco editor for authoring in code node and form editor

4. Detailed Design & Implementation

Data Model / Schema

No dedicated database table was added for this feature.

Relevant schema surface:

• CodeNodeData.codeContent in lib/schemas/nodes.schema.ts

Sanitisation Rules

The sanitizer in lib/utils/sanitize-html.ts applies:

• Allowed tag list (content, media, form, SVG, style, script)

• Allowed attribute list per tag plus global attributes

• URL protocol blocking for javascript:, data:, vbscript:

• Optional toggles:

• allowScripts

• allowIframes

• allowSvg

• Content length cap via maxContentLength (default 50,000 chars)

Sandbox Behavior

• Iframe attributes are filtered and sandbox can be normalized when sandbox attribute exists.

• Form editor preview uses explicit iframe sandboxing with sandbox="allow-scripts" in app/quest-editor/[questID]/(sections)/content/form-editor/page.tsx.

Script Execution Pipeline

The execution helper in lib/utils/execute-html-with-scripts.ts:

• Parses and removes script tags from HTML string.

• Injects sanitized HTML into a container.

• Loads external scripts sequentially.

• Executes inline scripts with an IIFE wrapper against a template container.

• Deduplicates external script URLs with an in-memory loadedScripts set.

Render Surfaces

• Creator preview path in components/quest-editor/visual-canvas/nodes/CodeNode.tsx

• Learner code renderer path in components/learner/renderers/CodeblockRenderer.tsx

• Learner quest detail content-card path in components/learner/quest-detail/content-cards/CodeblockCardContent.tsx

API Specification

No dedicated API endpoint is introduced by this feature. Sanitisation and sandbox behavior are applied in frontend render pipelines.

5. Infrastructure & Operations

Dependencies

• Browser DOMParser and DOM APIs for sanitisation and runtime execution.

• Existing quest content rendering stack.

• Existing code node data persistence.

Monitoring & Alerting

Current observability is limited to console logging on runtime failures:

• script load failures

• inline execution exceptions

• autoplay-related browser failures

No dedicated metrics or alerting channel is currently implemented for sanitisation/sandbox violations.

Deployment Plan

• No DB migration required.

• Safe rollout path:

1. Validate creator preview behavior for existing code nodes.

2. Validate learner render behavior on active quests.

3. Run security smoke test for blocked protocols and disallowed attributes.

4. Confirm regressions do not break existing template snippets.

6. Testing & Quality Assurance

Test Strategy

• Manual security regression tests:

• Event handler stripping (for script-disabled mode)

• Dangerous URL protocol stripping

• Disallowed tag/attribute removal

• Functional rendering tests:

• Embedded iframe content

• SVG rendering

• Interactive template scripts

• Cross-surface tests:

• Creator preview

• Learner renderer

• Quest detail code content cards

Known Limitations

• Scripts are explicitly allowed in key rendering paths (allowScripts: true) which reduces strict isolation.

• Sandbox normalization for iframes depends on presence of a sandbox attribute in source HTML.

• No CSP enforcement is documented in this feature layer for public share routes.

• Sanitisation is primarily client-side in current flow.

7. Maintenance & Support

Troubleshooting

• Custom HTML renders blank: verify content survives sanitizer filtering and does not exceed max length.

• Script not running: check external script URL reachability and browser console for load errors.

• Iframe blocked or broken: confirm iframe attributes and sandbox compatibility with the source provider.

• Unexpected style loss: ensure required tags/attributes are in allowlists.

Handover Tasks for Clyde Ador (To Do)

1. Validate allowlist coverage against product-approved embed patterns.

2. Decide final script policy for learner-facing surfaces (strict vs permissive).

3. Evaluate whether iframe sandbox should be enforced even when source HTML omits sandbox.

4. Add automated security-focused tests for sanitizer behavior.

5. Confirm whether CSP headers are required on public share surfaces as a companion hardening step.

Changelog

• 1.0 - Approved, Technical guide created for HTML Node Sanitisation & Sandbox. July 2026.