Local detect()

This page describes detect, detectAsync, and detectConversation from @zeroleaks/shield/local. The root detect export is asynchronous and calls the hosted API; see the Shield API quickstart.

Checks text for prompt injection. Returns detected, risk, matches, and the classifier's score.

Use it on everything that reaches the model's context: user messages, retrieved documents, web pages, emails, and tool results. The provider wrappers do this for user messages and tool results automatically.

APICopy Anchor Link

function detect(input: string, options?: DetectOptions): DetectResult
function detectAsync(input: string, options?: DetectOptions): Promise<DetectResult>
function detectConversation(messages: ConversationMessage[], options?: ConversationDetectOptions): ConversationDetectResult

detect() ignores secondaryDetector. Use detectAsync() when you want the verifier to run.

DetectResultCopy Anchor Link

OptionsCopy Anchor Link

How it worksCopy Anchor Link

Every input goes through four layers. The whole input is scanned, in overlapping 8KB windows, not just a prefix.

1. Normalization. Unicode is folded (NFKC, accents, look-alike letters inside words that mix scripts, small capitals), invisible characters are removed, and a second view undoes common obfuscation: spaced-out letters, separators inside words, leetspeak, and misspellings. Views that keep digits and symbols are matched too, so an address like 169.254.169.254 or $(whoami) survives normalization.
2. Hidden payloads. Base64, hex, binary, decimal character codes, URL encoding, HTML entities, escape sequences, ROT13, Morse, Braille, reversed and upside-down text, and text smuggled in Unicode tag characters or variation selectors are decoded. The decoded text is scanned like the input. A payload that decodes to an injection adds a high-risk encoding_attack finding.
3. Patterns. A pattern library for well-known phrasings. Each pattern only runs when a literal it needs is in the text, so most never run on benign input.
4. Classifier. A logistic-regression model over hashed character and word n-grams, trained on public labeled datasets and shipped inside the package as 4-bit weights. Long text is scored in overlapping windows of about 500 characters and the highest window counts, so an instruction buried in a long document isn't averaged away.

A short chat message takes about 40µs and an 8KB document about 2ms on a server CPU.

To use a locally configured transformer model instead of the built-in classifier, call detectAsync(text, model.options()). See local model detection. Accuracy and latency depend on the artifacts and hardware.

HTMLCopy Anchor Link

For input with eight or more HTML elements, such as a web page or an HTML email, Shield also extracts the text an agent would read: text, comments, and descriptive attributes such as alt and title, without markup, scripts, or styles. Patterns run on both the markup and the extracted text; the classifier scores the text. Text inside hidden elements (display: none, visibility: hidden, zero size or opacity, the hidden attribute) is scanned separately. An injection found there produces a high-risk indirect_injection finding with pattern hidden_html_text. A hidden element alone isn't a finding: ordinary pages have many.

Slower detectorsCopy Anchor Link

The escalate option in detectAsync() sends input to a detector you provide. Shield includes three detectors for this option:

• createModelDetector() from @zeroleaks/shield/model runs Shield's own model, or another transformer classifier, in your process. Its options() method returns the options that use it in place of the built-in classifier.
• createLlmDetector() asks an LLM, over any OpenAI-compatible Chat Completions endpoint (OpenAI, Azure AI Foundry, OpenRouter, or a local server), whether the text is an injection. It uses fetch and adds no dependency.
• anyOf(...detectors) runs several detectors at once and reports a detection as soon as one of them detects.

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

const judge = createLlmDetector({
  url: "https://api.openai.com/v1/chat/completions",
  model: "gpt-5.6-luna",
  apiKey: process.env.OPENAI_API_KEY,
});
const result = await detectAsync(text, {
  escalate: { minScore: 0, detector: anyOf(createModelDetector(), judge) },
});

createLlmDetector() options:

An LLM call takes about a second or more, so escalating every input to one adds that much to each request. The provider wrappers can hide it behind the model call with parallelDetection. The text is sent to the LLM's provider, so choose one you would trust with your users' messages and tool results.

Pattern categoriesCopy Anchor Link

Low-risk categories only run when threshold is "low" and the input shows another sign of an attack, such as a keyword like "system" or "ignore", two or more suspicious words, or bracketed markers like [SYSTEM].

ConversationsCopy Anchor Link

detectConversation() scans every user and tool message on its own, and also the latest user messages joined together, which catches an instruction split across turns.

import { detectConversation } from "@zeroleaks/shield/local";

const result = detectConversation(messages, { window: 4 });
if (result.detected) {
  console.warn("flagged messages:", result.flagged.map((f) => f.index));
  console.warn("split across turns:", result.splitAcrossTurns);
}

It takes every detect() option as well.

False positivesCopy Anchor Link

The classifier can flag benign text despite training on examples that use the same words as attacks (instructions, passwords, "act as" prompts, formatting requests). Short imperative requests to the model, such as "from now on, always answer in French", are the most likely to be flagged.

Since the wrappers block by default, try your real traffic with onDetection: "warn" first. Then raise classifier.threshold, use excludeCategories or allowPhrases, or add a secondaryDetector for the cases you see.

NormalizationCopy Anchor Link

All steps are on by default. Pass an object to turn individual steps off, or false to turn them all off.

detect(input, { normalization: { decodeLeetspeak: false } });
detect(input, { normalization: false });

ExampleCopy Anchor Link

import { detect, detectAsync } from "@zeroleaks/shield/local";

const result = detect(userInput);
if (result.detected) {
  console.log(`Injection detected: ${result.risk} risk, score ${result.score?.toFixed(2)}`);
  for (const m of result.matches) {
    console.log(`  - ${m.category}: ${m.pattern}`);
  }
}

// A retrieved document or tool result
const doc = detect(pageText);

// Only report high and critical findings
const strict = detect(userInput, { threshold: "high" });

// Stricter classifier
const fewerFlags = detect(userInput, { classifier: { threshold: 0.8 } });

// Add a custom pattern
const withCustom = detect(userInput, {
  customPatterns: [{ category: "internal_marker", regex: /\[internal:\s*.+\]/i, risk: "critical" }],
});

// Let a second check overrule the result
const verified = await detectAsync(userInput, {
  secondaryDetector: async (input) => {
    const isInjection = await classifyWithLLM(input); // your own check
    return isInjection ? null : { detected: false, risk: "none", matches: [] };
  },
});