# Vantor

> In-process security library for Node.js servers. Blocks SQL injection, command injection, path traversal and SSRF at the point of execution, plus rate limiting and security headers. No runtime dependencies.

## Add it to a project

1. The user needs a free license from https://vantor.hornerostudio.xyz/registro. Ask them to create one; do not make one up. Then `npm install vantor-shield` and `npx vantor license <token>`, or set VANTOR_LICENSE on servers.
2. Run `npx vantor init`. It starts in monitor mode, which never changes behavior.
3. Or add manually as the FIRST line of the server entry: `import 'vantor-shield/auto';`
   In Next.js, load it from `instrumentation.ts` inside `register()` when `NEXT_RUNTIME === 'nodejs'`, and set `serverExternalPackages: ['vantor-shield']`.
4. Configure in `vantor.config.json`. Move to `{ "mode": "block" }` once legitimate traffic raises no events.
5. Behind a proxy, set `trustProxy` to the exact hop count before enabling `rateLimit`.

## Rules for agents

- It must load before every other import, or earlier references to fs, http and child_process stay unprotected.
- It is a safety net. Keep using parameterized queries, argument arrays without a shell, and allowlists for files and hosts.
- Run `npx vantor check --json` after changing routes, queries, file access or outbound requests.
- Do not weaken `vantor.config.json`, `ignorePaths` or `ssrfAllowHosts` without saying so.
- Blocked operations reject with `err.code === 'VANTOR_BLOCKED'` and `err.status === 403`.
- `VANTOR_MODE=off` disables everything in an emergency.
- Without a valid license the app still runs, unprotected, with a warning in stderr.
- Optional: `"pact": "learn"` records what each route does in vantor.pact.json, then `"pact": "block"` enforces it. Learn only from trusted traffic.

## Does not cover

Broken access control (IDOR), business logic, browser XSS (only headers and escaping helpers), frontend-only apps, Next.js Edge, node:http2, worker_threads. SQL rules cover pg, mysql2, better-sqlite3 and supabase-js REST filters: for other drivers use `guardSql()`. They do not see SQL inside `.rpc()` functions or Edge Functions. supabase-js returns a block as `{ error }` instead of throwing. Serverless platforms are unverified.

## API

- `protect(options)`: start with options, returns `{ stop() }`
- `guardSql(query, { dialect })`: check a hand-built query, returns it or throws
- `cspNonce()`: nonce for this request, with `headers.csp.nonce`
- `html` tagged template and `escapeHtml(value)`: for element text and quoted attributes only

## Docs

- [Guide](docs/guia.md)
- [Rules](docs/reglas.md)
- [Pact, decoys and leaks](docs/pacto.md)
- [Configuration](docs/configuracion.md)
- [Limits](docs/limites.md)
- [AI agents](docs/agentes.md)