@hushspec/core

Portable specification types for AI agent security rules.

@hushspec/core is the TypeScript SDK for the HushSpec open policy format. Parse, validate, evaluate, and enforce security rules for AI agent runtimes.

Installation

npm install @hushspec/core

Quick Start

import { parseOrThrow, validate, evaluate } from '@hushspec/core';

const policy = parseOrThrow(`
hushspec: "0.1.0"
name: my-policy
rules:
  egress:
    allow: ["api.github.com"]
    block: []
    default: block
`);

// Validate
const result = validate(policy);
console.log(result.valid); // true

// Evaluate an action
const decision = evaluate(policy, { type: 'egress', target: 'api.github.com' });
console.log(decision.decision); // 'allow'

HushGuard Middleware

HushGuard wraps policy loading and evaluation behind a simple interface for application code.

import { HushGuard } from '@hushspec/core';

const guard = HushGuard.fromFile('./policy.yaml');

// Check without throwing
const result = guard.check({ type: 'tool_call', target: 'bash' });
if (result.decision === 'deny') {
  console.log('Blocked:', result.reason);
}

// Or enforce (throws HushSpecDenied on deny)
guard.enforce({ type: 'egress', target: 'api.openai.com' });

Features

Evaluation

import { parseOrThrow, evaluate } from '@hushspec/core';

const spec = parseOrThrow(policyYaml);
const result = evaluate(spec, { type: 'egress', target: 'evil.example.com' });
// result.decision: 'allow' | 'warn' | 'deny'
// result.matched_rule: 'rules.egress.default'

Audit Trail

import { parseOrThrow, evaluateAudited } from '@hushspec/core';

const receipt = evaluateAudited(spec, action, {
  enabled: true,
  include_rule_trace: true,
  redact_content: false,
});
// receipt.decision, receipt.rule_evaluations, receipt.policy_summary

Detection Pipeline

Plug prompt injection, jailbreak, and exfiltration checks into the evaluation flow.

import { evaluateWithDetection, DetectorRegistry } from '@hushspec/core';

const registry = DetectorRegistry.withDefaults();
const result = evaluateWithDetection(spec, action, registry, {
  enabled: true,
  prompt_injection_threshold: 0.5,
});

Framework Adapters

Prebuilt adapters for Claude, OpenAI, and MCP tool calls.

import { HushGuard, mapClaudeToolToAction } from '@hushspec/core';

const guard = HushGuard.fromFile('./policy.yaml');
const action = mapClaudeToolToAction(toolUseBlock);
guard.enforce(action);

Hot Reload

import { PolicyWatcher, HushGuard } from '@hushspec/core';

const guard = HushGuard.fromFile('./policy.yaml');
const watcher = new PolicyWatcher('./policy.yaml', {
  onChange: (newSpec) => guard.swapPolicy(newSpec),
});
watcher.start();

Observability

import { ObservableEvaluator, JsonLineObserver, MetricsCollector } from '@hushspec/core';

const evaluator = new ObservableEvaluator();
evaluator.addObserver(new JsonLineObserver(process.stderr));
evaluator.addObserver(new MetricsCollector());

Panic Mode

import { activatePanic, deactivatePanic, isPanicActive } from '@hushspec/core';

activatePanic();
// All evaluate() calls now return deny
deactivatePanic();

CLI

The h2h CLI tool provides validate, lint, test, diff, format, sign, and more:

cargo install hushspec-cli
h2h validate policy.yaml
h2h lint policy.yaml

License

Apache-2.0