shieldkit Documentation

Production guardrails, structured output repair, and basic compliance for the Vercel AI SDK.

Quick links

Section	Description
Getting started	Install, first call, mode presets
Architecture	Middleware chain, request lifecycle, configuration
Features	Guards, repair, cost, audit, tools
Design	Rationale, trade-offs, limitations
Testing	How to run tests and verify correctness
CI and automation	GitHub Actions, Dependabot, schedules
npm publishing	Version tags, GitHub Release from CHANGELOG
Dependency policy	Vercel AI SDK version strategy
Adversarial assurance	Hardcore tests, contrast harness, red team
API reference	Public exports
Examples	Runnable examples in the repo
Deployment	Publish docs to GitHub Pages
Cursor Agent Skills	AI playbooks for dev, test, docs (Cursor)
Security policy	Vulnerability reporting and scope

What is shieldkit?

shieldkit is published on npm and developed at sakurablush/shieldkit. It wraps any LanguageModelV3 (OpenAI, Anthropic, Ollama, etc.) with a middleware chain that provides:

• Input guardrails — prompt injection detection (with homoglyph/zero-width normalization since 0.2.0), PII redaction, keyword deny lists
• Output guardrails — PII/keyword filtering on model responses
• Structured output repair — JSON repair and Zod schema validation with retries
• Cost tracking — per-session token and USD budgets
• Audit logging — structured lifecycle events to console or custom sinks
• Tool guards — allow/deny lists, call limits, approval gates
• Verified — 163 automated tests in the CI merge gate

import { generateText } from 'ai';
import { shield } from 'shieldkit';

const model = shield(yourModel, { mode: 'balanced' });

await generateText({
  model,
  prompt: 'Hello',
  providerOptions: { aiShield: { sessionId: 'user-123' } },
});

Documentation map

docs/
├── getting-started.md
├── architecture/
│   ├── overview.md
│   ├── request-lifecycle.md
│   └── configuration.md
├── features/
│   ├── input-guardrails.md
│   ├── output-guardrails.md
│   ├── structured-output.md
│   ├── cost-tracking.md
│   ├── audit-logging.md
│   └── tool-guards.md
├── design/
│   ├── why-middleware.md
│   ├── trade-offs.md
│   └── limitations.md
├── testing/
│   ├── running-tests.md
│   ├── writing-tests.md
│   ├── verification-matrix.md
│   ├── adversarial-assurance-plan.md
│   └── SECURITY_ASSURANCE_REPORT.md
├── api/
│   └── reference.md
├── contributing/
│   ├── ci-and-automation.md
│   ├── dependency-policy.md
│   ├── npm-publishing.md
│   └── cursor-skills.md
├── DEPLOYMENT.md
└── examples/
    └── index.md

Security

See security-policy.md for vulnerability reporting and production recommendations.

Contributing

See Contributing for development setup and the quality gate (npm run ci).

Using Cursor? Start with Cursor Agent Skills.