shrike-guard 4.0.3 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## [4.1.0] - 2026-09-09
+
+### Added
+- **Act-plane scanning: every channel the backend scans is now reachable from
+  the SDK.** The backend has scanned eight specialized content types since the
+  act plane shipped; this SDK exposed four. `scanCommand` — the highest-volume
+  surface, the one an agent hits before every shell-out — had no method at all,
+  so the only way to reach it was to hand-roll an HTTP call or route through the
+  MCP server. New on `ScanClient`:
+  - `scanCommand(command, cwd?)` — shell commands, screened before `exec`.
+    Commands are decomposed, so SQL passed to `psql -c`, `mysql -e`, or a
+    heredoc is scanned as SQL rather than as opaque shell text.
+  - `scanWebSearch(query)` — search queries that acquire attack tooling,
+    credentials, or evasion tradecraft.
+  - `scanRagContext(chunks, query?)` — retrieved context, the standard carrier
+    for indirect prompt injection. Accepts a string or a list of strings.
+  - `scanMcpSchema(name, description, inputSchema?)` — a single MCP tool
+    definition, for tool poisoning in a `tools/list` response. Screened once at
+    registration, not per call.
+- **`content_origin` on `ScanResult`.** Every verdict now says where the scanned
+  content came from: `human_prompt`, `agent_output`, `agent_action`, or
+  `third_party`. This answers the question a verdict alone cannot — was that my
+  prompt, or the agent acting on its own — which decides who a refusal message
+  is addressed to. Exported alongside it: the `ContentOrigin` type and
+  `attributableToOperator(origin)`, true only for `human_prompt`. Unknown content
+  types resolve to `agent_action`, never to `human_prompt`.
+- **Act-plane parity test** (`tests/unit/actplane-parity.test.ts`). Iterates the
+  canonical channel list and fails when a channel has no SDK method. The gap
+  above went unnoticed because "the backend supports it" and "a customer can
+  call it" were two facts with nothing comparing them. This is the comparison.
+
+- **Per-request session identity — `sessionId`/`agentId` on `ScanClientOptions`,
+  and `forSession()`.** Session identity is the key the backend accumulates
+  multi-turn risk against, so it has to mean one unit of work: one agent run,
+  one conversation, one user's request. It defaults to a process-wide id, which
+  suits a CLI or a worker but not a server serving many end users, where every
+  user would share one risk score and one user's refusal would count against
+  the next user's action. `forSession()` returns a view that shares the parent's
+  rate limiter, so deriving one per request is cheap and cannot multiply your
+  rate budget:
+
+  ```ts
+  const guard = new ScanClient({ apiKey: KEY });   // once, at startup
+
+  app.post('/act', async (req, res) => {           // per request
+    const scoped = guard.forSession(req.session.id);
+    const verdict = await scoped.scanCommand(req.body.command);
+  });
+  ```
+
+  The process-wide default is unchanged when nothing is supplied, so
+  single-agent callers keep multi-turn correlation; the SDK now warns once when
+  it is in force. Silence that with `SHRIKE_SUPPRESS_SESSION_WARNING=1`.
+
+  `evaluateRotation`'s caller-owned branch now applies: a caller that supplies
+  its own session id receives a rotation recommendation rather than a
+  module-owned rotation.
+
+### Fixed
+- **`content_origin` was computed by the backend and dropped before the caller.**
+  The response sanitizer is an allow-list, and the field was never added to
+  `PRESERVED_GOVERNANCE_FIELDS`, so it was serialized by the server and stripped
+  one layer before the application. It now survives sanitization.
+- **Session identity could not be configured.** Every scan in a process used one
+  generated session id, so a server scanning on behalf of more than one person
+  placed all of them in one session. See `sessionId` / `forSession()` above.
+
+## [4.0.5] - 2026-08-31
+
+### Added
+- **Custom endpoint for the Gemini wrapper (`baseUrl`).** `ShrikeGemini` now
+  accepts `baseUrl` (applied as `httpOptions.baseUrl` on the underlying
+  `@google/genai` client) and a `geminiOptions` passthrough for advanced
+  constructor options — parity with the OpenAI and Anthropic wrappers, which
+  already forwarded a custom endpoint via `openaiOptions.baseURL` /
+  `anthropicOptions.baseURL`. An explicit `geminiOptions.httpOptions` takes
+  precedence over `baseUrl`.
+- **Documented local / self-hosted LLM governance.** New README section shows
+  governing an OpenAI-compatible local runtime (Ollama, vLLM, LM Studio) by
+  forwarding `openaiOptions.baseURL`, plus the Gemini and Anthropic equivalents.
+  The plumbing already worked for OpenAI/Anthropic; this documents it and closes
+  the Gemini gap.
+
+_(Version aligned to 4.0.5 with the Python SDK for this coordinated local-LLM
+parity release; 4.0.4 was not published for the TypeScript SDK.)_
+
 ## [4.0.3] - 2026-07-17
 
 ### Fixed

package/README.md

@@ -6,6 +6,8 @@
 
 **Shrike Guard** is a TypeScript SDK for the [Shrike](https://shrikesecurity.com) platform — AI governance for every AI interaction. It wraps OpenAI, Anthropic (Claude), and Google Gemini clients to automatically evaluate all prompts against policy before they reach the LLM. Whether you're governing a customer-facing chatbot, securing developer AI tools, or managing autonomous agent actions — the same 9-layer cognitive pipeline evaluates every interaction.
 
+It scans two different things. **Prompts and responses**, which is what a guardrail library normally means. And **agent actions** — the shell command, the SQL query, the web search, the retrieved document, the MCP tool definition — screened before they run, which is where an autonomous agent actually causes harm. See [Scanning agent actions](#scanning-agent-actions-shell-commands-sql-web-search-rag-mcp-tools).
+
 ## Features
 
 - **Drop-in replacement** for OpenAI, Anthropic, and Gemini clients
@@ -15,6 +17,8 @@
   - Jailbreak attempts
   - SQL injection
   - Path traversal
+- **Pre-execution scanning for agent actions**: shell commands, SQL, file writes, web searches, RAG context, agent-to-agent messages, agent cards, and MCP tool schemas
+- **Content provenance** (`content_origin`): every verdict says whether a human typed it, the model wrote it, the agent is about to do it, or it arrived from outside
 - **Fail-safe modes**: Defaults to fail-closed (Zero Trust posture); opt into fail-open explicitly when availability outranks enforcement
 - **CJS + ESM**: Dual build via tsup, works everywhere
 - **Subpath imports**: `shrike-guard/openai`, `shrike-guard/anthropic`, `shrike-guard/gemini`
@@ -167,31 +171,216 @@ const client = new ShrikeOpenAI({
 });
 ```
 
-## SQL and File Scanning
+### Sessions: one per unit of work, not one per process
+
+Shrike correlates risk across a session. After a refusal, later actions in the
+same session are held until the session recovers. That is the multi-turn
+defence, and it means the session id has to mean one unit of work: one agent
+run, one conversation, one user's request.
+
+By default the SDK scans under one id for the whole process. That suits a CLI,
+a worker, or a single agent. It does not suit a server that scans on behalf of
+many end users, because every user then shares one risk score, and one user's
+refusal counts against the next user's action.
+
+Build one client at startup and derive a per-request view from it. The view
+shares the rate limiter, so it costs nothing to make one per request and it
+cannot multiply your rate budget:
+
+```typescript
+import { ScanClient } from 'shrike-guard';
+
+const guard = new ScanClient({ apiKey: 'shrike-...' });   // once, at startup
+
+app.post('/act', async (req, res) => {                     // per request
+  const scoped = guard.forSession(req.session.id);
+  const verdict = await scoped.scanCommand(req.body.command);
+  if (verdict.refuse_tier !== 'allow') {
+    ...
+  }
+});
+```
 
-The OpenAI client also provides standalone scanning for SQL queries and file paths:
+Or pin the identity at construction when one client serves one unit of work:
+
+```typescript
+const client = new ScanClient({ apiKey: 'shrike-...', sessionId: 'job-42', agentId: 'ingest' });
+```
+
+`agentId` is separate on purpose: it names *which agent* a scope is enforced
+against and who an incident is attributed to. Set it when one process drives
+several distinct agents.
+
+The SDK warns once per process when it is scanning under the shared default.
+Set `SHRIKE_SUPPRESS_SESSION_WARNING=1` to silence it once you have decided
+the default is what you want.
+
+### Local and self-hosted LLMs
+
+Shrike governs the model you point it at — it does not have to be a hosted
+frontier API. Local runtimes like [Ollama](https://ollama.com),
+[vLLM](https://docs.vllm.ai), and LM Studio expose an OpenAI-compatible
+endpoint, so `ShrikeOpenAI` guards them by forwarding a `baseURL` through
+`openaiOptions`:
 
 ```typescript
 import { ShrikeOpenAI } from 'shrike-guard/openai';
 
+// Ollama serving llama3 locally, governed by Shrike before every call
 const client = new ShrikeOpenAI({
-  apiKey: 'sk-...',
+  apiKey: 'ollama', // local servers ignore the value
+  shrikeApiKey: 'shrike-...', // governance still runs server-side
+  openaiOptions: { baseURL: 'http://localhost:11434/v1' },
+});
+
+const response = await client.chat.completions.create({
+  model: 'llama3',
+  messages: [{ role: 'user', content: 'Summarize this ticket…' }],
+});
+```
+
+The same pattern works for Anthropic-compatible gateways via
+`anthropicOptions.baseURL`. For Gemini, use the `baseUrl` option (added in
+4.0.5), applied as `httpOptions.baseUrl` on the `@google/genai` client:
+
+```typescript
+import { ShrikeGemini } from 'shrike-guard/gemini';
+
+const client = new ShrikeGemini({
+  apiKey: '…',
   shrikeApiKey: 'shrike-...',
+  baseUrl: 'https://your-gemini-gateway.example',
 });
+```
+
+The prompt still leaves your process to reach the Shrike backend for scanning;
+the *model call* stays on your local/self-hosted endpoint.
+
+## Scanning agent actions (shell commands, SQL, web search, RAG, MCP tools)
+
+Scanning the prompt protects the model. It does not protect the shell. An agent
+that was never told anything malicious can still be talked into running
+`curl … | sh` by a poisoned README, and the prompt scan has no view of that.
 
-// Scan SQL queries for injection attacks
-const sqlResult = await client.scanSql('SELECT * FROM users WHERE id = 1');
-if (!sqlResult.safe) {
-  console.log(`SQL threat: ${sqlResult.reason}`);
+`ScanClient` exposes a method per action channel. Call the one that matches
+what the agent is about to do, before it does it:
+
+| Channel | Method | Screens for |
+|---|---|---|
+| Shell command | `scanCommand(command, cwd?)` | destructive commands, data exfiltration, credential dumps, embedded SQL injection |
+| SQL query | `scanSql(query, database?, allowDestructive?)` | SQL injection, unauthorized destructive statements |
+| File path | `scanFile(path)` | path traversal, writes outside the working tree |
+| File content | `scanFile(path, content)` | secrets, credentials, PII before they land on disk |
+| Web search | `scanWebSearch(query)` | searches that acquire attack tooling, credentials, or evasion tradecraft |
+| RAG context | `scanRagContext(chunks, query?)` | indirect prompt injection in retrieved documents |
+| Agent message | `scanA2AMessage(message, options?)` | instructions smuggled between agents |
+| Agent card | `scanAgentCard(card, verifySignature?)` | capability misrepresentation in A2A discovery |
+| MCP tool schema | `scanMcpSchema(name, description, inputSchema?)` | tool poisoning in `tools/list` responses |
+
+```typescript
+import { ScanClient } from 'shrike-guard';
+
+const scanner = new ScanClient({ apiKey: 'shrike-...' });
+
+// Before shelling out
+const cmd = await scanner.scanCommand('psql -c "SELECT * FROM users"', '/srv/app');
+if (!cmd.safe) throw new Error(`Refused: ${cmd.reason}`);
+
+// Before querying
+const sql = await scanner.scanSql('SELECT * FROM users WHERE id = $1', 'postgres');
+
+// Before writing
+const write = await scanner.scanFile('/tmp/config.py', 'api_key = "sk-..."');
+
+// Before searching the web
+const search = await scanner.scanWebSearch('sql injection prevention owasp');
+```
+
+A shell command is not one thing. `scanCommand` decomposes it, so SQL passed to
+`psql -c`, `mysql -e`, or a heredoc is scanned as SQL rather than as an opaque
+string of shell text.
+
+### Indirect prompt injection in RAG pipelines
+
+Retrieved chunks are text somebody else wrote. They are the standard carrier for
+indirect prompt injection: the user asks nothing unusual, the document tells the
+model what to do, and the model complies. Scan on the way in, not after the
+model has acted:
+
+```typescript
+const chunks = await vectorStore.similaritySearch(userQuery, 5);
+
+const verdict = await scanner.scanRagContext(
+  chunks.map((c) => c.pageContent),
+  userQuery,
+);
+
+if (!verdict.safe) {
+  // The retrieved context is hostile, not the user's question.
+  console.warn(`Poisoned context: ${verdict.reason}`);
 }
+```
+
+### MCP tool poisoning
 
-// Scan file paths for path traversal
-const fileResult = await client.scanFile('/app/data/output.csv');
+An MCP tool description is read by the model as guidance. A hostile server can
+put instructions in the `description` field of a tool that never executes, and
+the agent will act on them at registration time. Screen every entry of a
+`tools/list` response from a server you do not control:
 
-// Scan file content for secrets
-const contentResult = await client.scanFile('/tmp/config.py', 'api_key = "sk-..."');
+```typescript
+const { tools } = await mcpClient.listTools();
+
+for (const tool of tools) {
+  const verdict = await scanner.scanMcpSchema(
+    tool.name,
+    tool.description ?? '',
+    tool.inputSchema,
+  );
+  if (!verdict.safe) {
+    console.warn(`Not registering ${tool.name}: ${verdict.reason}`);
+    continue;
+  }
+  register(tool);
+}
 ```
 
+Screening happens once per tool at registration, not on every call.
+
+## Who is answerable: `content_origin`
+
+Every verdict carries `content_origin`, which says where the scanned content
+came from. It answers the question a verdict alone cannot: *was that my prompt,
+or the agent acting on its own?*
+
+| Value | Meaning |
+|---|---|
+| `human_prompt` | the operator typed it |
+| `agent_output` | the model generated it |
+| `agent_action` | the agent is about to do it (every act-plane channel) |
+| `third_party` | it arrived from outside: a tool result, a retrieved document, a peer agent |
+
+```typescript
+import { attributableToOperator } from 'shrike-guard';
+
+const verdict = await scanner.scanRagContext(chunks);
+
+if (!verdict.safe) {
+  if (attributableToOperator(verdict.content_origin)) {
+    showUser(`Your request was blocked: ${verdict.reason}`);
+  } else {
+    // The agent poisoned its own context. Telling the user "your request
+    // was blocked" would be both wrong and unhelpful.
+    log.warn('agent-side refusal', verdict.reason);
+    retryWithCleanContext();
+  }
+}
+```
+
+Unknown content types resolve to `agent_action`, never to `human_prompt`:
+attributing an unattributable action to the operator is the one error that is
+never safe to make by default.
+
 ## Error Handling
 
 ```typescript
@@ -257,6 +446,8 @@ export OPENAI_API_KEY="sk-..."
 export ANTHROPIC_API_KEY="sk-ant-..."
 export SHRIKE_API_KEY="shrike-..."
 export SHRIKE_ENDPOINT="https://your-shrike-instance.com"
+export SHRIKE_AGENT_ID="ingest"                 # names this process's agent; see Sessions
+export SHRIKE_SUPPRESS_SESSION_WARNING=1        # once you have decided the shared session is right
 ```
 
 ## Scope and Limitations
@@ -267,13 +458,23 @@ export SHRIKE_ENDPOINT="https://your-shrike-instance.com"
 | Multi-modal text content | Image/audio content |
 | SQL queries | Non-chat API calls |
 | File paths and content | |
+| Shell commands | |
+| Web search queries | |
+| Retrieved RAG context | |
+| Agent-to-agent messages and agent cards | |
+| MCP tool schemas | |
 
-### Why Input-Only Scanning?
+### Why Pre-Execution Scanning?
 
-Shrike Guard focuses on **pre-flight protection** — blocking malicious prompts BEFORE they reach the LLM. This:
+Shrike Guard focuses on **pre-flight protection** — evaluating a prompt before it
+reaches the LLM, and an action before it runs. This:
 - Prevents prompt injection attacks at the source
 - Has zero latency impact on LLM responses
-- Catches the vast majority of threats at the input layer
+- Puts the decision point before the side effect, where refusing still costs nothing
+
+An action already taken cannot be un-taken by detecting it afterwards. That is the
+distinction between this and after-the-fact monitoring: the verdict arrives while
+refusing is still free.
 
 ## Other Integration Surfaces
 
@@ -291,22 +492,39 @@ Shrike Guard is one of several ways to integrate with the Shrike platform:
 | Scenario | How Shrike Guard Helps |
 |---|---|
 | **Customer chatbot** | Wrap your OpenAI/Anthropic client. Every user message scanned for injection before it reaches the model. |
-| **Internal RAG pipeline** | Scan retrieved context + user queries for PII leakage and injection attempts. |
-| **AI coding assistant** | Scan prompts for proprietary code patterns before they leave your environment. |
-| **Agent orchestration** | Scan every tool call and LLM request in your LangChain/CrewAI/AutoGen pipeline. |
-
-## Alternatives
-
-Looking for an AI security SDK? Here's how Shrike Guard compares:
-
-| Feature | Shrike Guard | Lakera | Prompt Armor |
-|---|---|---|---|
-| Drop-in OpenAI/Anthropic/Gemini wrapper | Yes | No | No |
-| 9-layer cognitive pipeline | Yes | Limited | Limited |
-| PII detection + redaction | Yes | Partial | No |
-| Session correlation | Yes (Pro+) | No | No |
-| Free tier (no API key) | Yes | No | No |
-| Open source client | Yes (Apache 2.0) | No | No |
+| **Coding agents that shell out** | `scanCommand` before every `exec`. Destructive commands, exfiltration, and SQL smuggled through `psql -c` are caught before the process starts. |
+| **Internal RAG pipeline** | `scanRagContext` on retrieved chunks for indirect prompt injection, plus PII leakage on the query. |
+| **MCP clients** | `scanMcpSchema` on every `tools/list` entry from a server you do not control, to catch tool poisoning at registration. |
+| **Multi-agent systems** | `scanA2AMessage` and `scanAgentCard` for instructions smuggled between agents. |
+| **Agent orchestration** | Scan every tool call and LLM request in your LangChain/LangGraph/CrewAI/AutoGen pipeline. |
+
+## How This Differs From a Prompt Scanner
+
+If you are evaluating TypeScript or JavaScript AI security SDKs, this is the
+distinction worth testing against your own workload.
+
+Most guardrail libraries answer one question: **is this text hostile?** They read
+the prompt, and sometimes the response. That is necessary, and Shrike Guard does
+it through a 9-layer cascade with PII redaction and multi-turn session
+correlation.
+
+But an autonomous agent does not cause harm by saying something. It causes harm
+by *doing* something: running a command, writing a file, querying a database,
+calling a tool. Shrike Guard scans those too, before they execute:
+
+- **A verdict per action channel** — shell commands, SQL, file writes, web
+  searches, RAG context, agent-to-agent messages, agent cards, MCP tool schemas.
+  See [Scanning agent actions](#scanning-agent-actions-shell-commands-sql-web-search-rag-mcp-tools).
+- **Pre-execution, not after the fact.** The verdict arrives while refusing is
+  still free. An action already taken cannot be un-taken by detecting it.
+- **Provenance on every verdict** (`content_origin`) — whether a human typed it,
+  the model wrote it, the agent is about to do it, or it arrived from outside.
+- **A governance contract, not just a boolean** — `refuse_tier`
+  (allow / warn / require_approval / block), a `recovery` block telling the agent
+  how to proceed legitimately, and `session_state`. Present on safe verdicts too.
+- **Drop-in wrappers** for OpenAI, Anthropic, and Gemini, so the prompt-scanning
+  half needs no code changes.
+- **Free tier with no API key**, and an Apache 2.0 client you can read.
 
 ## License
 

package/dist/anthropic/index.d.mts

@@ -1,6 +1,6 @@
 import Anthropic from '@anthropic-ai/sdk';
 import { MessageCreateParams, Message } from '@anthropic-ai/sdk/resources/messages';
-import { F as FailMode, S as ScanResult } from '../scanner-cxA3LnQR.mjs';
+import { F as FailMode, S as ScanResult } from '../scanner-z9r8BJvO.mjs';
 
 /**
  * ShrikeAnthropic - Drop-in replacement for Anthropic client with security scanning.
@@ -78,8 +78,8 @@ declare class ShrikeAnthropic {
      * Scan user messages for security threats via backend API.
      *
      * Always calls backend - backend handles tier-based scanning:
-     * - Community tier (no API key): L1-L4 (regex, unicode, encoding, token normalization)
-     * - Pro tier: L1-L8 (full scan including LLM)
+     * - Community tier (no API key): L1-L5 (regex, unicode, malformed, encoding, token/semantic)
+     * - Pro tier and above: L1-L9 (adds visual, LLM semantic, response intel, session correlation)
      */
     _scanMessages(messages: AnthropicMessage[]): Promise<ScanResult>;
     /**

package/dist/anthropic/index.d.ts

@@ -1,6 +1,6 @@
 import Anthropic from '@anthropic-ai/sdk';
 import { MessageCreateParams, Message } from '@anthropic-ai/sdk/resources/messages';
-import { F as FailMode, S as ScanResult } from '../scanner-cxA3LnQR.js';
+import { F as FailMode, S as ScanResult } from '../scanner-z9r8BJvO.js';
 
 /**
  * ShrikeAnthropic - Drop-in replacement for Anthropic client with security scanning.
@@ -78,8 +78,8 @@ declare class ShrikeAnthropic {
      * Scan user messages for security threats via backend API.
      *
      * Always calls backend - backend handles tier-based scanning:
-     * - Community tier (no API key): L1-L4 (regex, unicode, encoding, token normalization)
-     * - Pro tier: L1-L8 (full scan including LLM)
+     * - Community tier (no API key): L1-L5 (regex, unicode, malformed, encoding, token/semantic)
+     * - Pro tier and above: L1-L9 (adds visual, LLM semantic, response intel, session correlation)
      */
     _scanMessages(messages: AnthropicMessage[]): Promise<ScanResult>;
     /**

package/dist/anthropic/index.js

@@ -13,12 +13,12 @@ var DEFAULT_FAIL_MODE = "closed" /* CLOSED */;
 var DEFAULT_ENDPOINT = "https://api.shrikesecurity.com/agent";
 var SDK_NAME = "typescript";
 var SESSION_ID = crypto.randomUUID();
-var AGENT_ID = process.env.SHRIKE_AGENT_ID || `sdk-ts-${crypto.randomUUID().slice(0, 8)}`;
+var AGENT_ID = `sdk-ts-${crypto.randomUUID().slice(0, 8)}`;
 function getSessionId() {
   return SESSION_ID;
 }
 function getAgentId() {
-  return AGENT_ID;
+  return process.env.SHRIKE_AGENT_ID || AGENT_ID;
 }
 
 // src/errors.ts
@@ -266,6 +266,13 @@ var PRESERVED_GOVERNANCE_FIELDS = [
   "recovery",
   "session_state",
   "content_type",
+  // Provenance: human_prompt / agent_output / agent_action / third_party.
+  // An OUTCOME field, not detection attribution — it says who is answerable
+  // for the scanned content, which the caller needs in order to know who a
+  // refusal is even addressed to. It shipped on the backend in 2cfaa5f and was
+  // silently dropped here, because this is an allow-list and nobody added it:
+  // a new backend field reaches no caller until it appears in this array.
+  "content_origin",
   "approval_info",
   "client_session_rotation"
 ];
@@ -330,7 +337,7 @@ function sanitizeScanResponse(raw) {
 }
 
 // package.json
-var version = "4.0.3";
+var version = "4.1.0";
 
 // src/version.ts
 var VERSION = version;
@@ -419,8 +426,8 @@ var ShrikeAnthropic = class {
    * Scan user messages for security threats via backend API.
    *
    * Always calls backend - backend handles tier-based scanning:
-   * - Community tier (no API key): L1-L4 (regex, unicode, encoding, token normalization)
-   * - Pro tier: L1-L8 (full scan including LLM)
+   * - Community tier (no API key): L1-L5 (regex, unicode, malformed, encoding, token/semantic)
+   * - Pro tier and above: L1-L9 (adds visual, LLM semantic, response intel, session correlation)
    */
   async _scanMessages(messages) {
     const userContent = this._extractUserContent(messages);