Zero-dependency, DOM-free, tree-shakeable pure predicate for detecting unsafe strings across HTML, XML, SVG, SQL, SQL-STRICT, SHELL, REDOS, NOSQL, and LOG contexts.
Why is-unsafe?
Sanitizer libraries like DOMPurify require a DOM. They cannot run inside XML parsers, template engines, or server-side pipelines that process strings before they ever reach a browser.
is-unsafe fills that gap. It is a pure predicate — it answers one question:
Is this string value unsafe in a given context?
It never mutates strings. It never touches the DOM. It has zero runtime dependencies.
Motivating use case: @nodable/entities / fast-xml-parser
DOCTYPE blocks can define custom entities with arbitrary values:
When @nodable/entities resolves &xss;, it produces a raw string containing </script><script>alert(...). Whether that string is dangerous depends on where it ends up. is-unsafe answers that question — without a DOM.
Installation
npm install is-unsafe
Always check the final string. If your code builds a value by concatenating parts, call isUnsafe on the result, not on the pieces. Two harmless strings can become unsafe only once joined:
const a = 'java', b = 'script:alert(1)';isUnsafe(a, HTML); // falseisUnsafe(b, HTML); // falseisUnsafe(a + b, HTML); // true ← check this one
v2 replaces string context names with imported pattern arrays. This is the only breaking change.
v1
v2
import { isUnsafe, VALID_CONTEXTS } from 'is-unsafe'
import { isUnsafe, HTML, XML } from 'is-unsafe'
isUnsafe(v, 'HTML')
isUnsafe(v, HTML)
isUnsafe(v, ['HTML', 'XML'])
isUnsafe(v, [HTML, XML])
for (const ctx in VALID_CONTEXTS) { isUnsafe(v, ctx) }
for (const ctx of Object.values(VALID_CONTEXTS)) { isUnsafe(v, ctx) }
Why the change? String names required a central registry that imported all 9 context modules unconditionally. Even if you only used HTML and XML, your bundle included all contexts (~22 KB dead weight). With named imports, bundlers include only what you actually import.
API
isUnsafe(value, context) → boolean
Returns true if value is unsafe in the given context, false otherwise.
Parameter
Type
Description
value
string
The string to test. Throws TypeError if not a string.
context
PatternList | PatternList[] | RegExp
A named context import, array of context imports, or a custom RegExp.
import { isUnsafe, HTML, XML } from 'is-unsafe';// Single contextisUnsafe(value, HTML)// Multiple contexts — true if unsafe in ANY of themisUnsafe(value, [HTML, XML])// Custom RegExp — true if pattern matchesisUnsafe(value, /my-pattern/i)
whyUnsafe(value, context) → MatchResult | null
Like isUnsafe, but returns a MatchResult object describing the first matching rule, or null if the value is safe. Useful for logging and error messages.
import { whyUnsafe, HTML } from 'is-unsafe';const result = whyUnsafe('<script>alert(1)</script>', HTML);// {// context: 'HTML',// id: 'html-script-open',// description: '<script opening tag',// pattern: /<script[\s>/]/i// }
allUnsafe(value, context) → MatchResult[]
Returns all matching rules across the given context(s), or an empty array if safe. Useful for comprehensive audits.
Note: SQL-STRICT is exported as SQL_STRICT (hyphens are not valid in JS identifiers).
Custom PatternList
You can supply your own pattern list alongside or instead of the built-in contexts:
import { isUnsafe, whyUnsafe, HTML } from 'is-unsafe';const INTERNAL_RULES = [ { id: 'no-internal-ref', description: 'Blocks references to internal hostnames', pattern: /\.internal\b/i }, { id: 'no-admin-path', description: 'Blocks paths starting with /admin', pattern: /\/admin\b/i },];// Optional — sets the context label in MatchResult. Defaults to 'CUSTOM'.INTERNAL_RULES.label = 'INTERNAL';isUnsafe('https://api.internal/data', INTERNAL_RULES) // trueisUnsafe('https://example.com/page', INTERNAL_RULES) // false// Mix with built-in contextsisUnsafe(value, [HTML, INTERNAL_RULES]);const result = whyUnsafe('https://api.internal/admin', INTERNAL_RULES);// { context: 'INTERNAL', id: 'no-internal-ref', description: '...', pattern: /.../ }
Without setting .label, MatchResult.context will be 'CUSTOM'.
Entity decoding (v2.0.3+)
The built-in HTML, XML and SVG contexts test each rule against both the raw string and an entity-decoded copy, because browsers decode character references (:, :, :, 	, 
) before interpreting a URL.
A custom PatternList does not do this by default. Set decodeEntities to opt in:
Enable it only for markup contexts. Leave it off for SQL, shell, log and similar rules, which should match the string exactly as supplied.
VALID_CONTEXTS
A convenience object that re-exports all contexts under their canonical names. Useful for tooling or exhaustive checks across all contexts.
Warning: importing VALID_CONTEXTS pulls in all 9 context modules. If your bundle size matters and you only need a few contexts, import them individually instead.
import { VALID_CONTEXTS } from 'is-unsafe';// { HTML: [...], XML: [...], SVG: [...], SQL: [...], 'SQL-STRICT': [...],// SHELL: [...], REDOS: [...], NOSQL: [...], LOG: [...] }// Iterate all contexts:for (const [name, ctx] of Object.entries(VALID_CONTEXTS)) { if (isUnsafe(value, ctx)) console.log(`Unsafe in ${name}`);}
Contexts
HTML
XSS vectors when a string is rendered as HTML:
Rule ID
What it catches
html-script-open
<script opening tag
html-script-close
</script> closing tag
html-javascript-protocol
javascript: URI (with whitespace obfuscation)
html-vbscript-protocol
vbscript: URI
html-data-html
data:text/html URI
html-data-xhtml
data:application/xhtml+xml URI
html-data-svg
data:image/svg+xml URI
html-inline-event-handler
onclick=, onerror=, onload=, etc.
html-entity-obfuscated-script
<script, <script, <script
html-entity-obfuscated-javascript
Entity-encoded leading letters of javascript: (colon/letter/tab encodings are also caught — see Entity decoding below)
html-style-expression
CSS expression() — IE code execution
html-object-embed
<object> and <embed> tags
html-base-tag
<base href= — relative URL hijacking
html-meta-refresh
<meta http-equiv="refresh"
html-srcdoc
srcdoc= attribute on iframes
html-iframe
<iframe tag
html-form
<form tag — phishing injection
Entity decoding (HTML, XML, SVG). Browsers decode character references before interpreting a URL, so javascript:alert(1) is a javascript: URL. These three contexts therefore test every rule against the raw input and an entity-decoded copy. Decoded forms: decimal/hex numeric references (any leading zeros, semicolon optional), :, 	, 
. Named references are case-sensitive and need ;. & is intentionally not decoded (double-encoded text renders as text). Other contexts (SQL, SHELL, LOG, …) are matched byte-for-byte.
XML
Parser-level attacks in XML documents (distinct from HTML XSS):
Two tiers of SQL injection detection, chosen based on what kind of input you're validating.
Use SQL for general user-facing fields (names, descriptions, search queries). Its 15 rules are high-precision with very low false-positive risk.
Use SQL_STRICT when the input is specifically a SQL fragment or database identifier — it includes all SQL rules plus three additional rules that would produce false positives on general text:
Patterns handle both bare form ($ne: null) and JSON key form ({"$ne": null}) by allowing an optional closing quote between the operator name and the colon.
LOG
Injection vectors dangerous when a string is written to a log file or passed to a logging framework:
${env:}, ${sys:}, ${ctx:} — data exfiltration lookups
log-ssti-double-brace
{{expression}} — Jinja2, Twig, Handlebars SSTI
log-ssti-hash-brace
#{expression} — Thymeleaf, Velocity, ERB SSTI
log-ssti-dollar-brace
${expr.method()} — JSP EL, Freemarker, SpEL SSTI
log-ssti-percent-tag
<%= expression %> — Ruby ERB, ASP
log-null-byte
\x00 or %00 — truncates log entries
log-ansi-escape
ESC[ — ANSI escape sequences that manipulate terminal output
Note: The log-crlf-injection rule flags literal newline characters (\n, \r). Apply LOG only to single-line log field values (usernames, IDs, request parameters), not to multi-line content.
Integration examples
@nodable/entities — postCheck callback (the motivating use case)
import { isUnsafe, HTML } from 'is-unsafe';import { EntityDecoder, ALL_ENTITIES } from '@nodable/entities';const dec = new EntityDecoder({ namedEntities: ALL_ENTITIES, postCheck: (resolved, original) => { if (isUnsafe(resolved, HTML)) { return original; // keep literal &entity; reference // or: throw new Error(`Unsafe entity blocked: ${original}`); // or: return '[BLOCKED]'; } return resolved; }});
Only html.js ends up in your bundle — XML, SQL, and all other contexts are excluded automatically.
fast-xml-parser — entity check for HTML + XML contexts
import { isUnsafe, HTML, XML } from 'is-unsafe';onInputEntity: (name, value) => isUnsafe(value, [HTML, XML]) ? ENTITY_ACTION.BLOCK : ENTITY_ACTION.ALLOW,
Bundle cost: only html.js + xml.js (~5.8 KB).
Logging with whyUnsafe
import { isUnsafe, whyUnsafe, HTML, SQL } from 'is-unsafe';function safeInsert(value, context) { if (isUnsafe(value, context)) { const reason = whyUnsafe(value, context); logger.warn('Blocked unsafe value', { ruleId: reason.id, context: reason.context }); throw new Error(`Unsafe value rejected (${reason.id})`); } return value;}
import { isUnsafe, SQL, SQL_STRICT } from 'is-unsafe';// General text field (name, description, comment) — use SQLfunction validateUserBio(bio) { if (isUnsafe(bio, SQL)) throw new Error('Invalid content'); return bio;}// Dedicated SQL identifier input (table name picker, column filter) — use SQL_STRICTfunction validateTableName(name) { if (isUnsafe(name, SQL_STRICT)) throw new Error('Invalid identifier'); return name;}validateUserBio("see note -- above"); // passes (-- alone is fine for general text)validateTableName("users -- comment"); // blocked by SQL_STRICT
File upload path guard
import { isUnsafe, SHELL } from 'is-unsafe';function validateUploadPath(filename) { if (isUnsafe(filename, SHELL)) throw new Error('Invalid filename'); return filename;}validateUploadPath('document.pdf'); // OKvalidateUploadPath('../../../etc/passwd'); // throwsvalidateUploadPath('file.txt\x00.jpg'); // throws (null byte)
User-supplied regex guard
import { isUnsafe, whyUnsafe, REDOS } from 'is-unsafe';function compileUserRegex(pattern) { if (isUnsafe(pattern, REDOS)) { const detail = whyUnsafe(pattern, REDOS); throw new Error(`ReDoS risk in pattern (${detail.id})`); } return new RegExp(pattern);}compileUserRegex('^[a-z]+$'); // OKcompileUserRegex('(a+)+'); // throws — nested quantifier
Checking all contexts (tooling / security scanners)
import { isUnsafe, VALID_CONTEXTS } from 'is-unsafe';for (const [name, ctx] of Object.entries(VALID_CONTEXTS)) { if (isUnsafe(value, ctx)) { console.log(`Unsafe in ${name}`); }}
Note: this import brings in all 9 context modules. Fine for CLI tools and scanners; use individual named imports in application bundles.
Design principles
Principle
Detail
Predicate only
Returns true/false. Never mutates strings.
Zero dependencies
No jsdom, no DOM, no framework coupling.
Tree-shakeable
Each context is an independent named export. Unused contexts are dropped by bundlers.
Context-aware
"Unsafe" is not absolute — it depends on where the value will be used.
Caller decides action
is-unsafe classifies. Escaping, throwing, or logging is the caller's responsibility.
ReDoS-safe
All detection patterns use bounded quantifiers. The irony of a security package triggering its own vulnerability (as the sql-injection npm package does) is avoided by design.
Extensible
Custom PatternList arrays work alongside built-in contexts. Set .label on your list to get meaningful context names in MatchResult.
False positives over false negatives
In parser context, blocking a legitimate value is better than passing a malicious one.
What is-unsafe is NOT
Not a sanitizer — it does not modify strings
Not a middleware — no Express/Koa coupling
Not a firewall — it does not block requests
Not a complete security solution — one layer of defence-in-depth
Comparison with existing packages
Package
Problem
dompurify
Requires DOM/jsdom. Sanitizer, not predicate. Has documented SVG/XML bypass vulnerabilities.
xss
Sanitizer — rewrites the string. HTML-only. No predicate API.
xss-filters
Explicitly documented as unable to be used inside <svg>, <object>, <embed>.
xss-checker
465 kB payload list, 6 years abandoned, 5 dependents.
is-sql-injection
Philosophically closest, but v1.0.0 only, 8 years abandoned, 19 dependents.
sql-injection
Express middleware. Has an active ReDoS CVE on its own detection patterns.
is-unsafe
Actively maintained. DOM-free. Pure predicate. Tree-shakeable. Covers HTML, XML, SVG, SQL (two tiers), SHELL, REDOS, NOSQL, and LOG as distinct contexts.
The SVG context is the key differentiator for XSS — no existing package covers SVG-specific vectors (xlink:href, foreignObject, animate/set element attacks). The XML context covers parser-level attacks that DOMPurify has documented bypass vulnerabilities for. The NOSQL and LOG contexts (including Log4Shell) have no equivalent in any current predicate package.
Running tests
npm installnpm test
Tests use Jasmine. Source in src/, specs in specs/.