package
A security-focused rehype plugin that filters URLs based on allowed prefixes
npm install rehype-hardenGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
A rehype plugin that ensures that untrusted markdown does not contain images from and links to unexpected origins.
This is particularly important for markdown returned from LLMs in AI agents which might have been subject to prompt injection.
This package validates URL prefixes and URL origins. Prefix allow-lists can be circumvented with open redirects, so make sure to make the prefixes are specific enough to avoid such attacks.
E.g. it is more secure to allow https://example.com/images/ than it is to allow all of
https://example.com/ which may contain open redirects.
Additionally, URLs may contain path traversal like /../. This package does not resolve these.
It is your responsibility that your web server does not allow such traversal.
npm install
import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remarkRehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
defaultOrigin: "https://mysite.com",
allowedLinkPrefixes: ["https://github.com/", "https://docs."],
allowedImagePrefixes: ["https://via.placeholder.com", "/"],
})
.use(/* whatever compiler you want, eg hast-to-jsx-runtime or hast-to-svelte */);defaultOrigin?: stringallowedLinkPrefixes or allowedImagePrefixes are provided (except when using wildcard ["*"])["*"] without defaultOrigin, relative URLs (e.g., /path, ./page) are allowed and preserved as-is"https://mysite.com"allowedLinkPrefixes?: string[][blocked]"*" to allow all URLs (disables filtering. However, javascript: and data: URLs are always disallowed)[] (blocks all links)['https://github.com/', 'https://docs.example.com/'] or ['*']allowedImagePrefixes?: string[]"*" to allow all URLs (disables filtering. However, javascript: and data: URLs are always disallowed unless allowDataImages is enabled)[] (blocks all images)['https://via.placeholder.com/', '/'] or ['*']allowDataImages?: booleantrue, allows data:image/* URLs (base64-encoded images) in image sourcesdata:image/* URLs are allowed; other data: URLs (like data:text/html) remain blocked for securitydata: URLs are never allowed in links, regardless of this settingfalse (blocks all data: URLs)trueallowedProtocols?: string[]tel:, mailto:, postman:, vscode:, slack:)"*" to allow all protocols that can be parsed as valid URLsjavascript:, data:, file:, vbscript:) are always blocked regardless of this setting[] (only allows built-in safe protocols: https:, http:, mailto:, irc:, ircs:, xmpp:, blob:)['tel:', 'postman:', 'vscode:'] or ['*']linkBlockPolicy?: BlockPolicyType"indicator" (default): Renders as plain text with [blocked] suffix and the blocked URL in a title attribute"text-only": Renders just the link text without any indicator or URL"remove": Removes the blocked link entirely from the outputimageBlockPolicy?: BlockPolicyType"indicator" (default): Renders as a placeholder span with [Image blocked: {alt text}]"text-only": Renders just the alt text (images with no alt text are removed)"remove": Removes the blocked image entirely from the outputblockedImageClass?: string"indicator" policy, the replacement span includes this class for styling.blockedLinkClass?: string"indicator" policy.import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
// Blocks all external links and images by default
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden) // No options = blocks everything
.use(/* your compiler */);
const result = processor.processSync(markdownContent);import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
defaultOrigin: "https://mysite.com",
allowedLinkPrefixes: [
"https://github.com/",
"https://docs.github.com/",
"https://www.npmjs.com/",
],
allowedImagePrefixes: [
"https://via.placeholder.com/",
"https://images.unsplash.com/",
"/", // Allow relative images
],
})
.use(/* your compiler */);
const result = processor.processSync(markdownContent);import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
defaultOrigin: "https://mysite.com",
allowedLinkPrefixes: ["https://mysite.com/"],
allowedImagePrefixes: ["https://mysite.com/"],
})
.use(/* your compiler */);
const markdownWithRelativeUrls = `
[Relative Link](/internal-page)

`;
const result = processor.processSync(markdownWithRelativeUrls);import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
allowedLinkPrefixes: ["*"],
allowedImagePrefixes: ["*"],
})
.use(/* your compiler */);
const markdownWithExternalUrls = `
[Any Link](https://anywhere.com/link)

[Relative Link](/internal-page)
`;
const result = processor.processSync(markdownWithExternalUrls);
// All URLs are allowed, including relative URLs like /internal-pageNote: Using "*" disables URL filtering entirely. Only use this when you trust the markdown source. When using wildcard without defaultOrigin, relative URLs are preserved as-is in the output.
import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
defaultOrigin: "https://mysite.com",
allowedImagePrefixes: ["https://mysite.com/"],
allowDataImages: true, // Enable base64 images
})
.use(/* your compiler */);
const markdownWithBase64Images = `


`;
const result = processor.processSync(markdownWithBase64Images);Note: This is particularly useful when converting documents from formats like PDF or .docx where images are embedded as base64. Only data:image/* URLs are allowed; other data: URLs remain blocked for security.
Blob URLs (blob:) are automatically allowed by default for both links and images. These are browser-generated URLs that reference in-memory objects and are commonly used for:
import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
defaultOrigin: "https://mysite.com",
allowedImagePrefixes: ["https://mysite.com/"],
})
.use(/* your compiler */);
const markdownWithBlobUrl = `

`;
const result = processor.processSync(markdownWithBlobUrl);
// The blob: URL will be allowed even without being in allowedImagePrefixesNote: Blob URLs are safe because they can only reference content already loaded in the browser's memory. They cannot be used to exfiltrate data or load external resources.
Enable custom protocols for deep linking to applications and services:
import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
allowedProtocols: ['tel:', 'mailto:', 'postman:', 'vscode:', 'slack:'],
})
.use(/* your compiler */);
const markdownWithCustomProtocols = `
[Call us](tel:+1234567890)
[Email support](mailto:support@example.com)
[Open in Postman](postman://open/collection)
[View in VS Code](vscode://file/path/to/file.ts)
[Join Slack](slack://channel?id=C123456)
`;
const result = processor.processSync(markdownWithCustomProtocols);
// All these custom protocol links will be allowedCommon use cases:
tel: - Phone number links that open the dialer on mobile devicesmailto: - Email links (allowed by default, but shown here for completeness)sms: - SMS/text message linkspostman:, vscode:, slack: - Deep links to desktop applicationsYou can also use the wildcard to allow any custom protocol:
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
allowedProtocols: ['*'], // Allow all protocols
})
.use(/* your compiler */);Security Note: Even with allowedProtocols: ['*'], dangerous protocols like javascript:, data:, file:, and vbscript: are always blocked for security. Custom protocols are safe because they trigger OS-level protocol handlers and don't execute in the browser context.
Control how blocked content is handled instead of the default [blocked] indicator:
import { harden, BlockPolicy } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remarkRehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
defaultOrigin: "https://mysite.com",
allowedLinkPrefixes: ["https://trusted.com/"],
allowedImagePrefixes: ["https://trusted.com/"],
linkBlockPolicy: "text-only", // Show link text only, no [blocked] indicator
imageBlockPolicy: "remove", // Remove blocked images entirely
})
.use(/* your compiler */);Available policies: "indicator" (default), "text-only", "remove".
import { harden } from "rehype-harden";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
.use(remarkRehype)
.use(harden, {
defaultOrigin: "https://mysite.com",
allowedLinkPrefixes: ["https://trusted.com/"],
allowedImagePrefixes: ["https://trusted.com/"],
blockedLinkClass: "blocked-link",
blockedImageClass: "blocked-image",
})
.use(/* your compiler */);
const result = processor.processSync(markdownContent);href attributes in <a> elementssrc attributes in <img> elementsdefaultOrigin../ attacks"*" prefix to disable filtering (only when markdown is trusted)Behavior is configurable per element type via linkBlockPolicy and imageBlockPolicy:
"indicator" (default): Blocked links show a [blocked] suffix; blocked images show [Image blocked: {alt}]"text-only": Outputs just the link text or image alt text with no indicator"remove": Removes blocked elements entirely from the outputjavascript:, data:, vbscript:, file: and other dangerous protocols (always, regardless of configuration)https:, http:, mailto:, blob:, and others while blocking dangerous onestel:, postman:, vscode:) with explicit opt-in via allowedProtocolsThe package includes comprehensive tests covering:
Run tests:
pnpm testgit checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)MIT License - see the LICENSE file for details.
If you discover a security vulnerability, please send an e-mail to security@vercel.com.
Estimated unpacked size across 5 packages.
173.6 kB
Includes dependencies.