Add SafeMode for XSS protection (#3)

- Add SafeMode configuration class with URL sanitization,
  attribute filtering, and raw HTML handling modes
- Block dangerous URL schemes (javascript:, vbscript:, data:, file:)
- Filter event handler attributes (onclick, onload, etc.)
- Support for escaping, stripping, or allowing raw HTML
- Add safeMode option to DjotConverter constructor
- Add 27 tests covering all safe mode functionality

Closes #2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: dereuromark

src/DjotConverter.php

@@ -27,13 +27,43 @@ class DjotConverter
      * @param bool $xhtml Whether to use XHTML-compatible output
      * @param bool $warnings Whether to collect warnings during parsing
      * @param bool $strict Whether to throw exceptions on parse errors
+     * @param \Djot\SafeMode|bool|null $safeMode Enable safe mode (true for defaults, SafeMode instance for custom config)
      */
-    public function __construct(bool $xhtml = false, bool $warnings = false, bool $strict = false)
-    {
+    public function __construct(
+        bool $xhtml = false,
+        bool $warnings = false,
+        bool $strict = false,
+        bool|SafeMode|null $safeMode = null,
+    ) {
         $this->collectWarnings = $warnings;
         $this->strictMode = $strict;
         $this->parser = new BlockParser($warnings, $strict);
         $this->renderer = new HtmlRenderer($xhtml);
+
+        // Configure safe mode
+        if ($safeMode === true) {
+            $this->renderer->setSafeMode(SafeMode::defaults());
+        } elseif ($safeMode instanceof SafeMode) {
+            $this->renderer->setSafeMode($safeMode);
+        }
+    }
+
+    /**
+     * Enable or disable safe mode
+     *
+     * @param \Djot\SafeMode|bool|null $safeMode True for defaults, SafeMode for custom, null/false to disable
+     */
+    public function setSafeMode(bool|SafeMode|null $safeMode): self
+    {
+        if ($safeMode === true) {
+            $this->renderer->setSafeMode(SafeMode::defaults());
+        } elseif ($safeMode instanceof SafeMode) {
+            $this->renderer->setSafeMode($safeMode);
+        } else {
+            $this->renderer->setSafeMode(null);
+        }
+
+        return $this;
     }
 
     /**

src/Renderer/HtmlRenderer.php

@@ -44,6 +44,7 @@
 use Djot\Node\Inline\Symbol;
 use Djot\Node\Inline\Text;
 use Djot\Node\Node;
+use Djot\SafeMode;
 
 /**
  * Renders AST to HTML
@@ -52,6 +53,11 @@ class HtmlRenderer
 {
     protected bool $softBreakAsNewline = true;
 
+    /**
+     * Safe mode configuration (null = disabled)
+     */
+    protected ?SafeMode $safeMode = null;
+
     /**
      * @var array<string, array<\Closure(\Djot\Event\RenderEvent): void>>
      */
@@ -99,6 +105,32 @@ public function __construct(protected bool $xhtml = false)
     {
     }
 
+    /**
+     * Enable safe mode with the given configuration
+     */
+    public function setSafeMode(?SafeMode $safeMode): self
+    {
+        $this->safeMode = $safeMode;
+
+        return $this;
+    }
+
+    /**
+     * Get the current safe mode configuration
+     */
+    public function getSafeMode(): ?SafeMode
+    {
+        return $this->safeMode;
+    }
+
+    /**
+     * Check if safe mode is enabled
+     */
+    public function isSafeModeEnabled(): bool
+    {
+        return $this->safeMode !== null;
+    }
+
     public function setSoftBreakAsNewline(bool $value): void
     {
         $this->softBreakAsNewline = $value;
@@ -312,6 +344,11 @@ protected function renderAttributesExcluding(Node $node, array $exclude): string
             return '';
         }
 
+        // Filter dangerous attributes in safe mode
+        if ($this->safeMode !== null) {
+            $attrs = $this->safeMode->filterAttributes($attrs);
+        }
+
         // Sort attributes: id first, then others in source order
         uksort($attrs, function (string $a, string $b): int {
             if ($a === 'id') {
@@ -625,6 +662,11 @@ protected function renderLink(Link $node): string
         $href = $node->getDestination();
         $title = $node->getTitle();
 
+        // Sanitize URL in safe mode
+        if ($this->safeMode !== null && $href !== null) {
+            $href = $this->safeMode->sanitizeUrl($href);
+        }
+
         $html = '<a';
         // Only output href if destination is set (even if empty)
         if ($href !== null) {
@@ -642,10 +684,15 @@ protected function renderImage(Image $node): string
     {
         $attrs = $this->renderAttributes($node);
         $alt = $this->escape($node->getAlt());
-        $src = $this->escape($node->getSource());
+        $src = $node->getSource();
         $title = $node->getTitle();
 
-        $html = '<img alt="' . $alt . '" src="' . $src . '"';
+        // Sanitize URL in safe mode
+        if ($this->safeMode !== null) {
+            $src = $this->safeMode->sanitizeUrl($src);
+        }
+
+        $html = '<img alt="' . $alt . '" src="' . $this->escape($src) . '"';
         if ($title !== null) {
             $html .= ' title="' . $this->escape($title) . '"';
         }
@@ -720,6 +767,11 @@ protected function renderAttributes(Node $node): string
             return '';
         }
 
+        // Filter dangerous attributes in safe mode
+        if ($this->safeMode !== null) {
+            $attrs = $this->safeMode->filterAttributes($attrs);
+        }
+
         // Sort attributes: id first, then others in source order
         uksort($attrs, function (string $a, string $b): int {
             if ($a === 'id') {
@@ -768,21 +820,47 @@ protected function escapeAttribute(string $text): string
     protected function renderRawBlock(RawBlock $node): string
     {
         // Only output if format is HTML
-        if ($node->getFormat() === 'html') {
-            return $node->getContent() . "\n";
+        if ($node->getFormat() !== 'html') {
+            return '';
         }
 
-        return '';
+        $content = $node->getContent();
+
+        // Handle raw HTML according to safe mode
+        if ($this->safeMode !== null) {
+            $mode = $this->safeMode->getRawHtmlMode();
+            if ($mode === SafeMode::RAW_HTML_STRIP) {
+                return '';
+            }
+            if ($mode === SafeMode::RAW_HTML_ESCAPE) {
+                return $this->escape($content) . "\n";
+            }
+        }
+
+        return $content . "\n";
     }
 
     protected function renderRawInline(RawInline $node): string
     {
         // Only output if format is HTML
-        if ($node->getFormat() === 'html') {
-            return $node->getContent();
+        if ($node->getFormat() !== 'html') {
+            return '';
         }
 
-        return '';
+        $content = $node->getContent();
+
+        // Handle raw HTML according to safe mode
+        if ($this->safeMode !== null) {
+            $mode = $this->safeMode->getRawHtmlMode();
+            if ($mode === SafeMode::RAW_HTML_STRIP) {
+                return '';
+            }
+            if ($mode === SafeMode::RAW_HTML_ESCAPE) {
+                return $this->escape($content);
+            }
+        }
+
+        return $content;
     }
 
     protected function renderDefinitionList(DefinitionList $node): string