Tooark.Sanitizers 4.7.3

Tooark.Sanitizers

Library with three sanitizers for content that comes from outside the application: HTML with an allowlist, URLs with a scheme allowlist, and the content of the @tooark/wysiwyg editor (the Tiptap JSON), with the same rules the component applies in the browser.

HTML is not sanitized by hand-written code: the service wraps HtmlSanitizer, the de facto standard in .NET, because encodings, nested tags and event attributes make the bypass surface too large. The URL and wysiwyg JSON rules are the package's own, small and tested against the known bypasses.

📖 Docs: Tooark.Sanitizers on the site · All packages · API reference

🌍 Languages: 🇺🇸 English (this file) · 🇧🇷 Português

📑 Contents

• Overview
• Installation
• Configuration
• Sanitizers
• Usage Examples
• Dependencies
• Best Practices
• Error Codes and Solutions
• Contributing
• Help & Security
• Support
• License

📖 Overview

• Safe defaults: the configuration section is optional, and the three sanitizers work without it.
• Guards the configuration cannot turn off: javascript:, vbscript: and data: are never allowed; in HTML, neither are <script>, <object>, <embed> nor event attributes (onclick...).
• Fails at startup: a configuration that tries to allow any of those is rejected at registration, not on the first request.
• No per-call state: the services are singletons and safe for concurrent use.

🔧 Installation

dotnet add package Tooark.Sanitizers

The package runs on the base .NET runtime, without ASP.NET Core. It also comes with the Tooark aggregator, whose AddTooarkService already registers the sanitizers.

⚙️ Configuration

appsettings.json

Everything is optional. The example restricts HTML to a formatting set, accepts relative links and turns videos off in the editor content:

{
  "Sanitizers": {
    "Html": {
      "AllowedTags": ["p", "br", "strong", "em", "u", "a", "ul", "ol", "li"],
      "AllowedAttributes": ["href", "title"],
      "AllowedSchemes": ["https", "mailto"]
    },
    "Url": {
      "AllowedSchemes": ["https"],
      "AllowRelative": true
    },
    "Wysiwyg": {
      "AllowVideos": false
    }
  }
}

Program.cs

using Tooark.Sanitizers.Injections;

// Reads the Sanitizers section
builder.Services.AddTooarkSanitizers(builder.Configuration);

// Or without reading the configuration, only with adjustments in code
builder.Services.AddTooarkSanitizers(options => options.Url.AllowRelative = true);

With both configuration and code, the code adjustment applies on top of the section. Calling the registration more than once does not duplicate the services.

HTML options — Sanitizers:Html

Each list provided replaces HtmlSanitizer's default list. Missing or empty, the default stays, which is already a safe allowlist for formatting HTML.

URL options — Sanitizers:Url

Wysiwyg options — Sanitizers:Wysiwyg

The other wysiwyg rules are the component's and are not configurable: the content accepted on the server must be the same the editor and the viewer accept.

🧹 Sanitizers

HTML — IHtmlSanitizerService

Sanitize(html) returns the fragment with only the allowed tags, attributes, schemes and CSS. Null or blank input becomes empty text. Scripts, event attributes, javascript: in any spelling (uppercase, entities, a tab in the middle) and expression() in CSS do not survive.

URL — IUrlSanitizerService

Sanitize(url) returns the cleaned URL when it is accepted, or empty text when it is not; IsSafe(url) answers the same as a boolean. The rules are those of isSafeUrl in @tooark/wysiwyg, so a URL has the same destination in the browser and on the server:

1. control characters and whitespace are removed from the whole URL, because the browser ignores them and java\tscript: becomes javascript:;
2. relative is a URL that starts with /, #, ?, ./ or ../, and it only passes with AllowRelative;
3. absolute needs a scheme from the list;
4. a user and password in the URL are rejected unless AllowCredentials. In mailto, what comes before the @ is the address, not a credential.

The returned URL is the cleaned one, not normalized: what the browser will interpret is exactly what was validated.

@tooark/wysiwyg content — IWysiwygSanitizerService

The component never works with HTML: the content is the Tiptap JSON, and it sanitizes it in the browser with sanitizeWysiwygContent. But the JSON that reaches the API may not have gone through the editor: a hand-made request sends whatever it wants. The service applies the same rules on the server and rebuilds the document with only what the allowlist knows. Unknown keys and attributes are not copied.

Accepted nodes and marks, those of the @tooark/wysiwyg 1.4 schema:

The rules:

• a node or mark outside the schema is dropped; a node goes with its children;
• URLs (href, src, poster) follow the URL rule above with http, https, mailto, tel and prefixed relative URLs, as in the component. A rejected link leaves the mark and the text stays; a rejected image or video leaves the document; a rejected poster leaves alone;
• colors only in hex, a CSS name or rgb()/hsl() without ;. Others (oklch(), var()) are dropped, as in the component;
• textAlign only in left, center, right and justify; the heading level becomes an integer between 1 and 4, and 1 when it is not an integer;
• an empty text node is dropped, because ProseMirror rejects it and the whole document would no longer open;
• a document that loses all its blocks becomes the component's empty document (one paragraph);
• nesting beyond 64 levels is cut.

Sanitize(JsonNode) returns a new JsonObject; Sanitize(string) returns the JSON as text, with accents readable and <, >, & and quotes escaped, so it stays safe if embedded in a page. Null input, invalid JSON or a root that is not doc return null.

Component version. The schema follows @tooark/wysiwyg 1.4. A new node or attribute in the component needs a new version of this package; until then, the server removes it.

📝 Usage Examples

Saving the editor content

<ark-wysiwyg-editor> emits the JSON in the ark-wysiwyg-change event. The API sanitizes it before saving, and the same JSON goes back to <ark-wysiwyg-viewer>:

using System.Text.Json.Nodes;
using Microsoft.AspNetCore.Mvc;
using Tooark.Sanitizers.Interfaces;

public sealed record SaveArticleDto(string Title, JsonObject Content);

[ApiController]
[Route("articles")]
public sealed class ArticleController(IWysiwygSanitizerService wysiwyg) : ControllerBase
{
  [HttpPost]
  public IActionResult Save([FromBody] SaveArticleDto dto)
  {
    // Null when the JSON is not an editor document
    var content = wysiwyg.Sanitize(dto.Content);

    if (content is null)
    {
      return BadRequest();
    }

    // Save content.ToJsonString(): it is what the viewer gets back
    return Ok();
  }
}

Link provided by the user

using Tooark.Sanitizers.Interfaces;

public sealed class ProfileService(IUrlSanitizerService urls)
{
  // Empty text when the link is rejected
  public string ProfileWebsite(string? website) => urls.Sanitize(website);
}

urls.Sanitize("https://tooark.com");       // "https://tooark.com"
urls.Sanitize(" java\tscript:alert(1)");   // ""
urls.Sanitize("data:text/html,<script>");  // ""
urls.IsSafe("https://bank.com@scam.com");  // false

HTML from an external source

using Tooark.Sanitizers.Interfaces;

public sealed class ImportService(IHtmlSanitizerService html)
{
  public string Clean(string importedContent) => html.Sanitize(importedContent);
}

html.Sanitize("<p onclick=\"alert(1)\">Hello <script>alert(1)</script></p>"); // "<p>Hello </p>"
html.Sanitize("<a href=\"javascript:alert(1)\">link</a>");                    // "<a>link</a>"

Without dependency injection

The services have a public constructor, for tools and tests:

using Microsoft.Extensions.Options;
using Tooark.Sanitizers;
using Tooark.Sanitizers.Options;

var options = Options.Create(new SanitizerOptions());
var wysiwyg = new WysiwygSanitizerService(options);

📋 Dependencies

🎯 Best Practices

1. Sanitize on input and keep encoding on output — sanitizing before saving does not replace context encoding when displaying (Razor, textContent, quoted attributes).
2. Sanitize the editor JSON on the server — the component sanitizes in the browser, but the API receives whatever any client sends.
3. List only what the content needs — shrink the HTML tag list instead of widening it.
4. Turn off the media the application does not use — without the media group in the editor, AllowImages and AllowVideos set to false prevent an image pointing to a tracking server.
5. Do not use the URL sanitizer to validate redirects — with AllowRelative, //other.com passes as relative, as in the component, and leads to another host. For a returnUrl, use ASP.NET Core's Url.IsLocalUrl.

⚠️ Error Codes and Solutions

The errors are configuration errors: InternalServerErrorException thrown at registration (AddTooarkSanitizers) or when creating the service without dependency injection. Sanitization itself does not throw: what is not accepted is removed.

🤝 Contributing

Contributions are welcome! Start with CONTRIBUTING.md — it covers the development workflow, the coding and commit conventions and the pull request checklist. Bugs and feature requests go through the issue templates of the Tooark repository.

By participating you agree to the Code of Conduct.

🆘 Help & Security

• ❓ Questions, bugs, feature ideas — see SUPPORT.md for the right channel
• 🔒 Security vulnerabilities — do not open a public issue; follow SECURITY.md

💖 Support

If Tooark helps your projects, consider supporting its development:

• 💙 GitHub Sponsors
• ☕ Ko-fi

Every contribution helps keep the project maintained and improving. Thank you! 🙏

📄 License

This project is licensed under the BSD 3-Clause License.