HTML Node Sanitisation & Sandbox | WyzQuests Documentation

Feature Owner: Joshua Uriel Tribiana
Module: Develop (Content Production)
Priority: P0
Week 12 Sprint: ( Hand Off ) To Do
Date: 07/02/2026

EXECUTIVE SUMMARY

What is this feature?
This feature provides sanitization and sandbox controls for custom HTML rendered from Code nodes. It filters unsafe tags, attributes, and protocols, and applies runtime controls so creator-authored HTML can be previewed and consumed by learners with reduced XSS risk.

Why does it matter?
Custom HTML is a high-risk surface because it can carry script and iframe payloads. If this layer is weak, learner-facing and shared quest views can become an attack path, which creates security exposure, trust issues, and release risk.

What’s the MVP scope?
Week 1 must include sanitizer hardening, iframe sandbox enforcement, and validation tests for malicious payloads. Advanced observability, CSP optimization strategy, and extended policy management can follow in later iterations.

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Creators can embed rich HTML content, but inconsistent sanitisation and permissive script behavior can allow unsafe payloads to pass through rendering surfaces.

Pain Point

Emotional: Security uncertainty and low confidence in publishing HTML content
Functional: Potentially unsafe rendering behavior and inconsistent protections across preview and learner views
Business Impact: XSS risk, production incident risk, and delayed release approvals

Future State (With Feature)

All HTML node content passes through a predictable sanitisation and sandbox policy before rendering, reducing exploitability while preserving approved interactive content.

Marketing Hook

“Safely deliver rich HTML learning experiences without exposing learners to unsafe script behavior.”

2. 4D FRAMEWORK MAPPING

Diagnose

Identifies high-risk HTML payload patterns early by filtering dangerous tags, attributes, and URL protocols.

Design

Defines and enforces an allow list model for tags and attributes, plus iframe sandbox constraints for controlled embedding.

Develop

Enables creators to build interactive HTML content using approved patterns while maintaining security guardrails in preview and learner renderers.

Deliver

Supports secure publishing and learner delivery by standardizing sanitisation behavior across render surfaces.

3. USER FLOWS

Entry Point

Creator opens Code node editor and writes or pastes custom HTML content.

Success Criteria

Unsafe HTML is stripped or neutralized, valid content renders correctly, and learner-facing renderers behave consistently with security policy.

Main Flow (Happy Path)

Creator writes HTML in Code node editor.
Renderer sanitizes HTML via shared sanitizer utility.
Sanitized HTML is injected into render container.
Allowed scripts and resources execute through controlled script pipeline.
Learner sees intended content without blocked-policy regressions.

Edge Cases

No data: Empty or missing codeContent renders safe fallback content.
API error: Not applicable for primary render path since this feature is frontend utility driven; render should fail safely with no script execution crash.
Permission denied: Not applicable at sanitizer layer; access checks are handled by quest/auth routes before content access.

Decision Points

IF tag or attribute is disallowed → remove it from output.
ELSE retain content and continue sanitisation flow.
IF URL uses blocked protocol → strip attribute.
ELSE preserve URL.
IF iframe is allowed by policy → keep with sandbox constraints.
ELSE remove iframe element.

4. INFORMATION ARCHITECTURE

Primary Information (Always visible)

Sanitized HTML output
Rendered Code node content
Current security behavior for scripts and iframes

Secondary Information

Node type and content source surface (creator preview or learner renderer)
Runtime script execution state

Tertiary Information (Hidden until needed)

Tag and attribute allowlists
Protocol blocklist rules
Internal script deduplication behavior

Actions

Primary CTA:

Save and Preview HTML Node Content

Secondary Actions:

Toggle preview visibility
Insert template
Copy HTML

5. WIREFRAMES

No Wireframe created; Feature not implemented yet

Key Screens:

Main view: Code node editor with HTML input
Modal/detail view: Not required for core sanitisation behavior
Empty state: No content fallback
Loading state: Script/resource load delay in render surface
Error state: Unsupported payload or blocked attribute outcome

Annotations:

Preview renders sanitized HTML from shared utility.
Script execution utility loads external scripts sequentially and executes inline scripts in wrapped context.

6. WIREFLOWS

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

7. PROTOTYPE

Excluded — Feature not implemented yet

How to test:

Paste safe HTML with supported tags and verify render parity.
Paste unsafe HTML payloads such as javascript protocol links and event handlers.
Confirm disallowed content is stripped and app does not crash.
Validate iframe behavior with and without sandbox attributes.
Verify learner renderer behavior matches creator preview policy.

8. BACKEND SCHEMA

Database Tables
-- No new table required for 3.10.
-- Feature uses existing codeContent in node data payload.

Indexes

No new index required.

Constraints

Existing node schema constraints apply.
Code node content length target is controlled at sanitizer level through maxContentLength.

9. API ENDPOINTS

Endpoint 1: GET /api/learner/get-enrollment
Purpose: Provides learner progress context where code content may be consumed in flow
Auth: Required (JWT/session)

Response 200:

{
  "success": true,
  "data": {
    "id": "enrollment-id",
    "progress": {
      "percentage": 30
    }
  }
}

Response 401:

{
  "success": false,
  "error": "Unauthorized"
}

Endpoint 2: GET /share/[hash]
Purpose: Public share surface where HTML node security posture must remain safe
Auth: Optional/Public by hash

Response 200:

{
  "success": true
}

Response 404:

{
  "success": false,
  "error": "Not Found"
}

Endpoint 3: GET /quests/[id]
Purpose: Quest delivery path that may include HTML node content in learner flow
Auth: Context-dependent

Response 200:

{
  "success": true
}

Response 401:

{
  "success": false,
  "error": "Unauthorized"
}

Note: 3.10 primarily lives in frontend sanitisation and runtime render utilities; there is no dedicated sanitizer API endpoint in current implementation.

10. DATA REQUIREMENTS

Frontend Needs

Code node content string
Node type metadata
Sanitized HTML output
Script and iframe policy options

API Calls Frontend Will Make

GET /api/learner/get-enrollment (quest session context)
GET quest content routes used by learner playback

Caching Strategy

No dedicated sanitisation cache currently.
Render-time sanitisation executes per content render lifecycle.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

No DB changes for 3.10.
No additional index needed.

Query optimization notes

Not query-bound; main cost is client-side HTML parse/sanitise and script execution.

Caching Strategy

Existing loadedScripts in-memory set prevents repeated external script loads during runtime session.
Invalidate naturally on browser refresh/new session.

API Response Time
Target: No additional API latency budget introduced by 3.10.

12. SECURITY & AUTHORIZATION

Who can access this feature?
Creator: ✓
Reviewer: ✓
Learner: ✓ (render consumption only)

Authorization Logic

Content access follows existing auth/share route controls.
Sanitisation is applied before render in creator and learner surfaces.

Data Validation

Enforce allowlisted tags and attributes.
Strip dangerous protocols from href and src.
Restrict iframe behavior by sandbox policy.
Remove disallowed event handlers when script restrictions apply.

13. ERROR HANDLING

Common Errors
401 Unauthorized: Respect existing route guards before content render
404 Not Found: Show quest or content-not-found fallback
422 Validation Error: Treat malformed content as sanitized output with removals
500 Server Error: Render safe fallback and avoid unsafe execution

14. TESTING CHECKLIST

Happy Path
□ Safe HTML renders correctly in Code node preview
□ Safe HTML renders correctly in learner code renderer
□ Allowed iframe embeds work with expected sandbox behavior

Edge Cases
□ Empty data
□ API timeout
□ Permission denied
□ Invalid input
□ javascript/data/vbscript protocol stripping
□ Disallowed tag and attribute stripping

15. OPEN QUESTIONS

For Frontend:

Should scripts remain enabled on learner surfaces by default?
Should iframe sandbox be force-applied even when missing from source HTML?

For Backend:

Should a server-side sanitisation pass be added before persisted/public delivery?
Should CSP headers be required for share routes as mandatory hardening?

16. OUT OF SCOPE (v1.1+)

Not building in Week 12:

Policy management UI for dynamic allowlist editing
Full server-side sanitisation pipeline and moderation queue

Why: Security baseline hardening is priority; admin tooling and advanced enforcement can follow once baseline is stable.

17. SUCCESS METRICS

How will we know this feature is successful?

Zero high-severity XSS findings in QA and review scope for HTML node surfaces.
100 percent pass rate on blocked protocol and disallowed attribute sanitisation tests.
No regression in approved interactive template rendering.

18. DEPENDENCIES

This feature depends on:

Shared sanitizer utility implementation
Script execution utility behavior
Code node renderers in creator and learner flows

These features depend on this:

[3.9] Embed HTML Custom Node delivery safety
Public share and learner rendering hardening confidence

19. TIMELINE & OWNERSHIP

Backend: Clyde Ador (to do)
Frontend: Clyde Ador (to do)
QA: JD Billate and QA owner (to assign)