Installation

Version 2.0.0 was released on October 2, 2026. These docs describe v2. If you use 1.x, read the migration guide before upgrading.

Install @zeroleaks/shield with your preferred package manager. It runs on Node.js 18 or later, Bun, Deno, Cloudflare Workers, and browsers, with no runtime dependencies. Detection, sanitizing, output scanning, canaries, and scanTools() were checked on Node.js 22, Bun, Deno 2.9, workerd, and headless Chromium. Canary tokens need Web Crypto, which Node.js 18 only exposes with --experimental-global-webcrypto.

npm install @zeroleaks/shield@^2

bun add @zeroleaks/shield@^2

Hosted detection requires a dashboard API key. Keep it on your server; only local checks belong in browser code. Free accounts can use shield. See the API quickstart for your first request.

Upgrading from 1.xCopy Anchor Link

Version 2.0 changes these defaults:

• Root detection is hosted and asynchronous. Use await detect(text, { apiKey }) for the hosted API, or import detect from @zeroleaks/shield/local for synchronous local checks.
• The local classifier is on. Local detect() scores input with a built-in classifier as well as patterns, so it catches more injections and can flag text that 1.x let through. Pass classifier: false to go back to patterns and decoding only, or raise classifier.threshold. See False positives.
• Local input limits changed. 1.x scanned the first 8,192 characters of each input; the v2 local detector scans up to maxInputLength (1MB). Optional transformers and hosted models have separate window budgets; a long input can have incomplete model coverage.
• allowPhrases removes phrases instead of suppressing detection. In 1.x, input that contained an allowed phrase was never flagged. In 2.0 the phrase is removed before scanning, and the rest of the input is still checked.
• Tool results are scanned. The wrappers check tool results and documents for injection too, with the detect options, and throw InjectionDetectedError with source: "tool". Pass scanToolResults: false to check user messages only, as 1.x did. See Tool results.
• The output guard is on, so every stream is processed. Output is scanned for credentials and exfiltration links by default, with or without a system prompt. 1.x only processed a stream when there was a system prompt to check it against; 2.0 processes every stream, so in "buffer" mode nothing arrives until the model finishes. Pass output: false to process only streams with a system prompt, as 1.x did, or streamingSanitize: "passthrough" to get the provider's stream unchanged. See Output guard.
• "buffer" mode replays the provider's chunks. 1.x yielded the guarded text as text-only chunks (for OpenAI and Groq, the first choice's text) and dropped everything else. 2.0 replays the provider's own chunks and events, with tool calls, finish reasons, and usage, and the guarded text in place. See Streaming.
• onInjectionDetected gets a second argument, source, which is "user" or "tool". One-argument callbacks keep working.

Peer dependenciesCopy Anchor Link

Provider wrappers require the corresponding LLM client. All are optional; install only what you use:

Example: if you use the OpenAI wrapper only:

npm install @zeroleaks/shield openai

TypeScriptCopy Anchor Link

Type definitions ship with the package. Types are exported from the main entry point and from each provider subpath:

import { detect, harden, createHostedDetector, sanitize } from "@zeroleaks/shield";
import { detect as detectLocal } from "@zeroleaks/shield/local";
import type {
  HardenOptions,
  DetectOptions,
  DetectNormalizationOptions,
  DetectResult,
  LocalDetectOptions,
  LocalDetectResult,
  SanitizeOptions,
  SanitizeResult,
} from "@zeroleaks/shield";

// Provider-specific types
import { shieldOpenAI } from "@zeroleaks/shield/openai";
import type { ShieldOpenAIOptions } from "@zeroleaks/shield/openai";

Root DetectOptions and DetectResult describe hosted detect(). Use LocalDetectOptions and LocalDetectResult for detectLocal() and provider wrapper settings. The /local subpath also exports its local types under the names DetectOptions and DetectResult.

Import pathsCopy Anchor Link

Each path also exports its associated types, such as DetectOptions, ScanOutputOptions, ShieldProviderOptions, ShieldGoogleGenAIOptions, and ShieldCallbackHandlerOptions.

The package ships both ESM and CommonJS builds.

The root detect export is asynchronous and uses the hosted API. Existing synchronous code should import detect from @zeroleaks/shield/local. See the Shield API quickstart for keys and models.