# strict-url-sanitise

> Strict URL sanitization with security-focused validation

Latest version **0.0.1** (published 2025-06-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install strict-url-sanitise
pnpm add strict-url-sanitise
yarn add strict-url-sanitise
bun add strict-url-sanitise
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.1 |
| Published | 2025-06-26 |
| First published | 2025-06-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 3.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Glen Maddern |
| Maintainers | geelen |
| Keywords | url, sanitize, security, validation |

## Links

- npm: https://www.npmjs.com/package/strict-url-sanitise
- Repository: https://github.com/geelen/strict-url-sanitise
- Homepage: https://github.com/geelen/strict-url-sanitise#readme
- Issues: https://github.com/geelen/strict-url-sanitise/issues
- npm.io page: https://npm.io/package/strict-url-sanitise

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 0.0.1 (latest) — 2025-06-26

## README

# strict-url-sanitise

Strict URL sanitization with security-focused validation to prevent XSS and command injection attacks.

## Installation

```bash
pnpm add -D strict-url-sanitise
```

## Usage

```typescript
import { sanitizeUrl } from 'strict-url-sanitise'

// Valid URLs are sanitized and returned
const safe = sanitizeUrl('https://example.com/path?param=value')
console.log(safe) // 'https://example.com/path?param=value'

// Invalid URLs throw an error
try {
  sanitizeUrl('javascript:alert("XSS")')
} catch (error) {
  console.log(error.message) // 'Invalid url to pass to open(): javascript:alert("XSS")'
}
```

## Blocked URLs

This library blocks the following types of potentially dangerous URLs:

### Non-HTTP(S) Protocols
```javascript
sanitizeUrl('ftp://example.com/test')                    // ❌ Throws
sanitizeUrl('file:///etc/passwd')                        // ❌ Throws  
sanitizeUrl('javascript:alert("XSS")')                   // ❌ Throws
sanitizeUrl('data:text/html,<script>alert(1)</script>')  // ❌ Throws
```

### Command Injection Attempts
```javascript
sanitizeUrl('https://www.$(calc.exe).com/foo')           // ❌ Throws
sanitizeUrl('javascript:$(cmd /c whoami)')               // ❌ Throws
```

### Invalid Hostnames
```javascript
sanitizeUrl('https://exam ple.com')                      // ❌ Throws (spaces)
```

## What Gets Sanitized

Valid HTTP(S) URLs have their components properly encoded:

```javascript
// Special characters in paths, queries, and fragments are encoded
sanitizeUrl('https://example.com/path with spaces')
// → 'https://example.com/path%2520with%2520spaces'

sanitizeUrl('https://example.com?key=value with spaces')  
// → 'https://example.com/?key=value%20with%20spaces'

// Basic auth credentials are encoded
sanitizeUrl('http://user$(test):pass$(test)@domain.com')
// → 'http://user%24(test):pass%24(test)@domain.com/'
```

This may catch some valid URLs unintentionally but this package is explicitly designed to be as safe as possible to start, then relaxed over time if counter-examples are provided.

## License

MIT

---
_Source: https://npm.io/package/strict-url-sanitise · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
