Skip to Content
ZeroLeaksDocs
Shield SDK

Migrate to v2

Upgrade to Shield SDK 2.0, use hosted detection, or keep synchronous local checks.

Version 2.0.0 was released on October 2, 2026. The root detect() function is now asynchronous and uses the Shield API. Local inference remains available through explicit imports. Existing provider wrappers keep their local behavior until you pass a hosted detector.

Install the published v2 release:

npm install @zeroleaks/shield@^2

Update direct detection

Before:

import { detect } from "@zeroleaks/shield";
const result = detect(text);

Hosted detection:

import { detect } from "@zeroleaks/shield";
const result = await detect(text, {
  apiKey: process.env.ZEROLEAKS_API_KEY,
  model: "shield",
});

All hosted models require a dashboard API key. shield is free with research consent; shield-base, shield-large, and shield-tiered require a paid plan or pay as you go. ZEROLEAKS_API_KEY is read automatically on servers when apiKey is omitted. A Worker can pass env.ZEROLEAKS_API_KEY explicitly.

detected, risk, matches, and score remain available. Hosted results also expose the moderation response's flagged, categories, category_scores, and shield metadata. The binary category covers both prompt injection and jailbreaks. Network, authorization, malformed-response, and timeout errors reject with ShieldAPIError; handle them as failed checks instead of treating the input as safe.

To keep the synchronous local implementation:

import { detect } from "@zeroleaks/shield/local";
const result = detect(text, { classifier: false });

The root detectLocal export is an alias for this local function. Root DetectOptions and DetectResult describe hosted detect() and are aliases of HostedDetectOptions and HostedDetectResult. Use root LocalDetectOptions and LocalDetectResult for local detection and provider wrapper options, or import DetectOptions and DetectResult from @zeroleaks/shield/local. Local thresholds, patterns, allow phrases, and normalization options do not configure hosted model classification.

Update provider wrappers

import { createHostedDetector } from "@zeroleaks/shield";
import { shieldOpenAI } from "@zeroleaks/shield/openai";

const shield = createHostedDetector({ model: "shield-large" });
const client = shieldOpenAI(openaiClient, { detect: shield.options() });

The same detect: shield.options() works with shieldLanguageModelMiddleware() for AI SDK, and the other provider wrappers. Tool results inherit those detection options. The wrappers await the hosted verdict by default and stop on service errors. Explicitly configured local model and rule checks keep their existing behavior.

The synchronous shieldMiddleware().wrapParams() helper rejects asynchronous detectors. Use await shieldMiddleware({ detect: shield.options() }).wrapParamsAsync(params), or the AI SDK's shieldLanguageModelMiddleware() integration.

MCP wrappers await hosted checks for tool definitions as well as tool results. For direct tool-definition checks use await scanToolsAsync(tools, shield.options()). Synchronous scanTools() rejects async detector options and keeps its local behavior otherwise.

Run local transformer models

import { detectAsync } from "@zeroleaks/shield/local";
import { createModelDetector } from "@zeroleaks/shield/model";

const model = createModelDetector({ localPath: "/models/shield" });
const result = await detectAsync(text, model.options());

Root detectAsync() is retained for compatibility and still performs local detection with optional async model or LLM checks. It is not an alias for the new hosted detect().

Changed defaults

Local detection and the provider wrappers also changed in 2.0:

Area1.x2.0
Local classifierPatterns and decoding only.On. Local detect() also scores input with a built-in classifier, so it catches more injections and can flag text that 1.x let through. Pass classifier: false to go back, or raise classifier.threshold. See False positives.
Local input limitsScanned the first 8,192 characters of each input.The local detector scans up to maxInputLength (1MB). Optional transformers and hosted models have separate window budgets; a long input can have incomplete model coverage.
allowPhrasesInput that contained an allowed phrase was never flagged.The phrase is removed before scanning, and the rest of the input is still checked.
Tool resultsWrappers checked user messages only.Wrappers also check tool results and documents for injection, with the detect options, and throw InjectionDetectedError with source: "tool". Pass scanToolResults: false to check user messages only. See Tool results.
Output guardProcessed a stream only when there was a system prompt to check it against.On. Output is scanned for credentials and exfiltration links by default, with or without a system prompt. Every stream is processed, so in "buffer" mode nothing arrives until the model finishes. Pass output: false to process only streams with a system prompt, or streamingSanitize: "passthrough" to get the provider's stream unchanged. See Output guard.
"buffer" streamingYielded the guarded text as text-only chunks (for OpenAI and Groq, the first choice's text) and dropped everything else.Replays the provider's own chunks and events, with tool calls, finish reasons, and usage, and the guarded text in place. See Streaming.
onInjectionDetectedOne argument.Gets a second argument, source, which is "user" or "tool". One-argument callbacks keep working.

Set custom endpoints and check long inputs

baseURL includes the API version, such as https://shield.example.invalid/v1; endpoint specifies the complete moderation URL instead. Custom endpoints do not inherit the production API key. Pass an API key explicitly if your endpoint needs one. HTTPS is required except for loopback HTTP during local development.

Inspect result.shield.coverage for a long document's window coverage. By default a partial scan returns its verdict with truncated: true. Set requireFullCoverage: true to reject partial scans or responses without coverage metadata. signal and timeoutMs control cancellation and request duration.

On this page