Overview
Composable inline guardrails for AI agents.
Theo Guardrails is the inline, synchronous enforcement layer of Theo's trust
plane — a stateless, dependency-light library that inspects agent input and
output before it flows through and can allow, block, or modify it.
Guardrails compose into a sequential pipeline that short-circuits on the first
block and chains rewritten content through modify steps. It is fail-closed
by design: a guardrail that throws becomes a block unless explicitly marked
failOpen.
Pre-release (0.1.0). The package @usetheo/trust-guardrails is Apache-2.0 and
not yet published to npm. It ships the pipeline engine plus credential
masking, PII redaction, and shell-pattern blocking; the shared policy taxonomy is
a later milestone.
Quick start
import {
createGuardrailPipeline,
createCredentialMaskingGuardrail,
createPiiGuardrail,
createShellPatternGuardrail,
type GuardrailEntry,
} from '@usetheo/trust-guardrails';
const entries: GuardrailEntry[] = [
{ guardrail: createShellPatternGuardrail(), options: { name: 'shell' } },
{ guardrail: createCredentialMaskingGuardrail(), options: { name: 'credentials' } },
{ guardrail: createPiiGuardrail({ strategy: 'redact' }), options: { name: 'pii' } },
];
const pipeline = createGuardrailPipeline(entries);
const result = await pipeline.run({
direction: 'input', // 'input' | 'output' | 'tool_input' | 'tool_output'
content: 'my key is sk-ant-XXXXXXXX and email a@b.com',
});
// result: { action: 'allow' | 'block' | 'modify', reason?, modified? }
if (result.action === 'block') reject(result.reason);
else if (result.action === 'modify') use(result.modified);An empty pipeline allows; the first block short-circuits; a modify feeds its
rewritten content into the next guardrail; the caller's context is never mutated.
Guardrails included
Credential masking
`createCredentialMaskingGuardrail()` — 11 built-in rules (Anthropic, OpenAI, Stripe, GitHub PAT, AWS, Google, Slack, bearer, ETH/BTC keys) with a reversible restore map. Emits `modify`.
PII redaction
`createPiiGuardrail({ strategy })` — email, credit card (Luhn-validated), phone, SSN. `redact` replaces with `[REDACTED_*]` tokens, or `block`.
Shell-pattern blocking
`createShellPatternGuardrail()` blocks 7 dangerous patterns (`rm -rf /`, `curl | sh`, `sudo rm`, `chmod 777`, `dd of=/dev/`, …). Returns `block`.
Tristate action model
Every guardrail returns `allow` / `block` / `modify` with an optional `reason` and `modified` string — a uniform, composable contract.
Direction-aware
Each run is tagged `input` / `output` / `tool_input` / `tool_output`, so guardrails can behave differently per boundary.
Fail-closed
A throwing guardrail becomes a `block` unless its options set `failOpen: true`. Safety is the default, not an opt-in.