Markdown Sanitizer Development

Expert guidance for the vercel-labs/markdown-sanitizers monorepo containing security-focused npm packages for hardening markdown against data exfiltration attacks through LLM prompt injection.

Project Context

This monorepo contains two related packages:

1. **harden-react-markdown**: React wrapper for `react-markdown` with URL filtering

2. **markdown-to-markdown-sanitizer**: Standalone markdown-to-markdown sanitizer for third-party rendering (GitHub, GitLab)

**Package Manager**: pnpm (NOT npm)

Step-by-Step Instructions

1. Understanding the Repository Structure

When exploring this codebase:

2. Running Tests

**Root-level commands:**

```bash

pnpm test # All packages

pnpm run test:harden-react-markdown # React wrapper only

pnpm run test:markdown-to-markdown-sanitizer # Sanitizer only

```

**Package-specific testing:**

For `harden-react-markdown`:

```bash

cd harden-react-markdown

pnpm test # Run all tests

pnpm run test:watch # Watch mode

pnpm run test:ui # UI mode

```

For `markdown-to-markdown-sanitizer`:

```bash

cd markdown-to-markdown-sanitizer

pnpm test # All tests

pnpm run test:watch # Watch mode

pnpm run test:ui # UI mode

pnpm run test:coverage # With coverage

pnpm test -- tests/basic-sanitization.test.ts # Single file

```

3. Building Packages

```bash

In either package directory

pnpm run build

For harden-react-markdown, pre-publish workflow:

pnpm run prepublishOnly # Build + test

```

4. Type Checking and Linting

For `markdown-to-markdown-sanitizer`:

```bash

pnpm run check-types # Source files

pnpm run check-types:tests # Test files

pnpm run check-types:all # Everything

pnpm run lint # Source files

pnpm run lint:tests # Test files

```

5. Adding Security Tests

Both packages benefit from shared bypass attempt tests. To add new security tests:

6. Security Architecture

**harden-react-markdown:**

**markdown-to-markdown-sanitizer:**

- `MarkdownSanitizer`: Main orchestration

- `UrlNormalizer`: URL validation and prefix matching

- `HtmlSanitizer`: DOMPurify wrapper with GitHub-compatible rules

7. URL Normalization Rules

When working with URL filtering:

8. HTML Sanitization (markdown-to-markdown-sanitizer)

9. Performance Considerations

10. Security Constraints

**These packages are for defensive security only:**

**Do NOT:**

Common Tasks

**Adding a new security test:**

1. Create markdown file in `markdown-to-markdown-sanitizer/tests/bypass-attempts/`

2. Run `pnpm test` from root or package directory

3. Verify both packages handle the attack vector

4. If bypass succeeds, implement fix in appropriate package

**Making changes to URL filtering:**

1. Modify `UrlNormalizer` in markdown-to-markdown-sanitizer

2. Update corresponding logic in harden-react-markdown if needed

3. Run full test suite: `pnpm test`

4. Add specific test cases for new behavior

**Publishing updates:**

```bash

cd harden-react-markdown # or markdown-to-markdown-sanitizer

pnpm run prepublishOnly # Build + test (harden-react-markdown)

pnpm run build && pnpm test # For markdown-to-markdown-sanitizer

Follow npm publishing workflow

```

Key Files Reference

Important Notes