@zeroleaks/shield weekly downloads statistics

@zeroleaks/shield

Prompt injection and jailbreak detection for agents. await detect(text) checks user messages, retrieved documents, and tool results with the hosted Shield API. Provider wrappers apply the check before a model call and check its output for secrets, personal data, and prompt leaks.

Built and maintained by ZeroLeaks. See the migration guide when upgrading from synchronous detect().

Install

The hosted client uses fetch and supports Node.js 18+, Bun, Deno, Cloudflare Workers, and browsers. Keep dashboard API keys in your server or Worker environment. Provider SDKs and local transformer inference are optional peer dependencies.

For optional local model inference, use a current security-patched Node.js 22 release (22.23.3 or later) or Bun 1.4.2 or later. The local model installation guide pins Transformers 3.8.1 and shows the consumer application override for Sharp 0.35.4, which includes fixes absent from Transformers' default Sharp 0.34.x dependency. The default SDK install does not include either package.

Quick start

Create a zl_live_ key in the ZeroLeaks dashboard. All hosted models require a key, including the free model. Set ZEROLEAKS_API_KEY on your server, or pass apiKey explicitly:

detected and flagged carry the same verdict. score is the effective binary score; shield.model_score is the model's raw score and shield.rules says whether a rule also flagged the text. The single prompt_injection category includes jailbreaks. It does not provide a separate jailbreak probability.

| Model | Access |

| shield (default) | Free, with a dashboard key and research consent | | shield-base | Paid | | shield-large | Paid | | shield-tiered | Paid |

Choose a model with detect(text, { model: "shield-large" }). Free access requires the dashboard research consent flow. Paid requests are excluded from research retention, including when a paid account selects shield.

Protect a model call

Reuse a hosted detector and pass its options to a provider wrapper. The wrapper blocks flagged user messages and tool results before calling the model:

For Vercel AI SDK:

Pass detect: shield.options() to the other wrappers in the same way. Omitting it preserves the wrappers' existing local detection behavior. The AI SDK middleware waits for detection before the model call. The legacy shieldMiddleware() helper provides await wrapParamsAsync(params) for hosted detection; its synchronous wrapParams() accepts only local synchronous checks.

AI SDK inspection tool

Shield 2.1.2 adds an inspection tool for AI SDK 5, 6, and 7:

Use tools: { shieldCheck: shieldCheck() } with generateText or streamText for model-invoked inspection. Pair it with shieldLanguageModelMiddleware for enforced checks before model calls: the model chooses whether to call the tool and which text to submit. A negative detection is not a guarantee of safety or permission to act. Tool execution errors become AI SDK tool-error parts; application code must decide whether the agent can continue.

Configure local checks with shieldCheck({ detect: { sensitivity: "strict" } }), or opt into hosted checks with shieldCheck({ hosted: { apiKey, model: "shield" } }). Hosted checks always require complete coverage and throw on missing or truncated coverage. Local checks reject oversized input instead of silently truncating it. The executor accepts { abortSignal } as its second argument.

The new subpath requires ai 5 or later; AI SDK 7 requires Node.js 22+. Install ai and its zod peer alongside Shield. Other entry points still work without ai installed, and middleware retains SDK 4 support. See the complete AI SDK tool guide for a runnable model example, result fields, access requirements, and limitations.

Request options

| Option | Default | Purpose |

| apiKey | Server ZEROLEAKS_API_KEY | Dashboard key for the hosted service | | model | shield | One of the four model IDs above | | baseURL | https://api.zeroleaks.ai/v1 | OpenAI-compatible base URL, including /v1 | | endpoint | Derived from baseURL | Full moderation URL; use instead of baseURL | | timeoutMs | 30000 | Timeout for the request and response body | | signal | — | AbortSignal for cancellation | | requireFullCoverage | false | Reject results with partial or missing coverage metadata | | fetch | Global fetch | Custom transport for your runtime |

Long documents can exceed a model's window budget. Inspect result.shield.coverage: truncated indicates partial coverage, while windows and max_windows describe the scan. A clean verdict with partial coverage says nothing about unscanned text. Use requireFullCoverage: true when the application requires every window to be checked.

Authentication failures, service failures, invalid responses, timeouts, and cancellation reject with ShieldAPIError. They never produce a clean verdict. Error messages contain no input, key, or server response body. The client does not retry or follow redirects.

Self-hosting and local checks

Point the same hosted client at an OpenAI-compatible moderation endpoint you operate:

Custom endpoints require HTTPS except for loopback HTTP. They do not inherit ZEROLEAKS_API_KEY; pass any self-hosted key explicitly. The package's /server module provides the private inference service; an OpenAI-compatible gateway must expose its results as /v1/moderations for this client.

Use explicit local imports to keep detection in your process:

/local preserves the synchronous rules and bundled classifier, normalization, decoded-payload checks, and conversation helpers. /model provides optional transformer inference and requires @huggingface/transformers. A model configured by name may download weights on first use; supply localPath for an offline deployment. These imports make no calls to the hosted Shield API.

Output guards stay local:

Benchmarks…

Description from the npm listing.