Skip to content

About

Embeddable AI governance framework — define guardrails in YAML, enforce in code, prove in math. Three-valued policy engine (permit/deny/modify), 9 drop-in threat contracts, evidence-grade audit trails, MCP tool governance, streaming PII redaction, formal verification.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

25 Commits

Folders and files

Repository files navigation

God Clause

Embeddable TypeScript policy decision point — YAML rules in, permit / deny / modify decisions out, every decision on a verifiable hash-chained audit log. Bring your own detectors.

A decision is permit, deny, or modify. A modify decision carries obligations (redact PII, add a disclaimer, truncate) that your application applies. Every decision is SHA-256 hash-chained; policies can be DSSE-signed.

License: Apache 2.0 Node.js TypeScript CI

Status: 0.1.0, the first published release. The YAML contract format is stable; the TypeScript API may still change before 1.0.


See It Work: A Modify Decision

import { GodClause } from "god-clause";

const gov = new GodClause();
gov.loadContractYAML(`
  schema_version: "1.0"
  metadata:
    name: PII Safety
    version: "1.0.0"
    author: Platform Team
    description: Redact PII from AI outputs
    effective_date: "2025-01-01"
  data_governance:
    allowed_input_classes: [public, internal]
    allowed_output_classes: [public]
    retention_period: P90D
    cross_border_transfer: false
  rules:
    - id: PII-001
      description: Redact PII instead of blocking
      action: generate
      conditions:
        - field: output.contains_pii
          operator: equals
          value: false
      on_violation: modify
      obligations:
        - obligation_id: OBL-REDACT
          type: redact_pii
          params: { replacement: "[REDACTED]" }
      tags: [privacy, pii]
`);

// Your PII detector flagged the LLM output; pass its signal in as output.contains_pii
const decision = await gov.evaluate({
  action: "generate",
  input: { prompt: "Look up John's records" },
  output: { text: "John's SSN is 123-45-6789", contains_pii: true },
  caller: { user_id: "u1", session_id: "s1", roles: ["analyst"] },
});

console.log(decision.outcome);        // "modify"  (not blocked — modified)
console.log(decision.obligations[0]); // { obligation_id: "OBL-REDACT", type: "redact_pii", params: { replacement: "[REDACTED]" }, source_rule_id: "PII-001" }

// Your app applies the obligation:
// "John's SSN is 123-45-6789"  →  "John's SSN is [REDACTED]"

// Meanwhile, the hash-chained audit log recorded everything:
const { valid } = gov.verifyAuditChain();
console.log(valid); // true — tamper-evident proof this decision happened

God Clause did not detect the SSN and did not rewrite the string. Your detector set contains_pii; your code applies the redact_pii obligation. The library evaluated the rule, returned a modify decision with the obligation attached, and recorded the decision on a hash-chained, HMAC-signable, Merkle-sealable audit log. examples/openai-wrapper.ts is the reference pattern: a detector feeding the engine, and the obligation being applied to the response.

Obligations on a decision are the XACML model, and NeMo Guardrails and Guardrails AI rewrite outputs too. The difference is the packaging: one four-dependency Node package that combines a policy engine, a hash-chained + HMAC + Merkle-sealed audit log, and DSSE-signed policies.


Why God Clause?

For developers: a policy decision point you embed

What you get How
Three-valued decisions on_violation: block, warn, log or modify per rule
Obligations on modify Any type you define (redact_pii, add_disclaimer, ...) with params; your code applies them
Rules over your detector signals Conditions on fields you set, such as output.contains_pii, input.injection_score, output.toxicity_score
Rate limiting Built-in sliding window per user/org
Audit trail Every decision hash-chained, optionally HMAC-signed and Merkle-sealed

The library computes no detection signals. It reads fields you place on input, output, caller and metadata. PII, toxicity and injection detection are your job, and so is applying obligations. examples/openai-wrapper.ts shows both ends.

No sidecars. No external services. npm install god-clause and write a YAML file.

For security and compliance reviewers

The audit log is tamper-evident; it is not a compliance product. God Clause records each decision with the SHA-256 of the policy that produced it, chains entries by hash, and can sign entries with HMAC and seal segments with a Merkle root. It generates no compliance reports and certifies nothing against any framework. docs/evidence-grade-audit.md states what each layer proves and what it does not.


Why Trust Contracts Are Not Config Files

A Trust Contract is a YAML file — but it's not "just configuration."

The SHA-256 of the loaded contracts is recorded in every audit entry (policy_sha256; the decision carries it as governance_context.policy_sha256, next to the name@version of each contract), so each decision is tied to the exact contract set that produced it. Change a contract later and the entries made under the old version still carry the old fingerprint.

Add a DSSE signature to record who authored each policy version. The result is a policy document with a verifiable author and a verifiable link to every decision it governed, which is more than a config file.

schema_version: "1.0"
metadata:
  name: Content Safety Policy         # Human-readable
  version: "2.1.0"                    # Versioned
  author: AI Safety Team              # Attributable
  description: Safety guardrails for production LLM
  effective_date: "2025-01-01"
  review_date: "2025-07-01"
  stakeholders: [VP Engineering, Legal, Ethics Board]
data_governance:                      # Declared, not enforced: lint and summarize read it, evaluate() does not
  allowed_input_classes: [public, internal]
  allowed_output_classes: [public]
  retention_period: P90D
  cross_border_transfer: false
rules:
  - id: SAFETY-001
    description: Block toxic content
    action: generate
    conditions:
      - field: output.toxicity_score
        operator: less_than
        value: 0.3
    on_violation: block
    tags: [safety, content]
  - id: PII-001
    description: Redact PII instead of blocking users
    action: generate
    conditions:
      - field: output.contains_pii
        operator: equals
        value: false
    on_violation: modify
    obligations:
      - obligation_id: OBL-REDACT
        type: redact_pii
        params: { fields: [ssn, email, phone] }
    tags: [privacy, compliance]

A lawyer can read it. An engineer can enforce it. An auditor can verify it. Same file.


Architecture

┌─────────────────────────────────────────────────────┐
│                   Trust Contracts                    │
│  Human-readable YAML with machine-enforceable rules │
│  Schema-validated · Versioned · DSSE-signed          │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│              Runtime Policy Engine                   │
│  Recursive AND/OR/NOT · Rate limiting · Tag filters  │
│  Three-valued: permit / deny / modify (obligations)  │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│                     Audit Trail                      │
│  SHA-256 hash chain · HMAC-SHA256 signing            │
│  Merkle seals · policy SHA-256 per entry · OTel      │
└─────────────────────────────────────────────────────┘

Deployment Modes

Mode Use case
Embedded library TypeScript/Node.js apps — import { GodClause }
REST API server Python/Java/Go — call POST /v1/evaluate
Kubernetes sidecar Platform teams — Helm chart + ConfigMap contracts
Serverless Lambda/Cloud Functions — import the library directly

Audit Trail: What Each Layer Proves

A plain database log can be edited by anyone with write access and leaves no trace. God Clause's audit log makes edits detectable:

Layer What it proves
SHA-256 hash chain Each entry links to the previous. Delete or modify any entry → chain breaks → tampering detected
HMAC-SHA256 signing Even if someone recomputes hashes, they need the secret key
Merkle seal checkpoints One root comparison per segment, recomputed over the segment's entries
DSSE contract signatures Cryptographic proof of who authored each policy

What it does not give you: an external clock (entry timestamps come from the host), or any proof of what your application did with the decision. Keep the HMAC key away from whoever can write to the log, or the HMAC layer proves nothing.


Threat Contracts

Pre-built contracts for common AI threats. Each reads detector signals that your application sets on the context; the header comment in each file lists the fields it expects. Copy into your project and load:

Contract Threats covered
pii-redaction.contract.yaml SSNs, emails, phone numbers, credit cards
prompt-injection.contract.yaml Ignore-previous, system prompt extraction, jailbreaks
anti-hallucination.contract.yaml Low-confidence outputs, missing citations, factual grounding
toxic-content.contract.yaml Toxicity, NSFW, hate speech, self-harm
cost-control.contract.yaml Rate limits, token caps, model restrictions
data-leakage.contract.yaml Internal data in outputs, cross-border violations
bias-detection.contract.yaml Demographic bias in scoring, protected class filtering
copyright-protection.contract.yaml Verbatim reproduction, attribution requirements
mcp-tool-abuse.contract.yaml Destructive or unlisted MCP tool calls, per-session call caps, human approval for sensitive tools

See also: domain-specific contracts for healthcare, financial services, HR, and e-commerce.


Features

Three-Valued Decisions (The Differentiator)

  • Permit — action proceeds as-is
  • Deny — action blocked, caller gets structured error
  • Modify — action proceeds with obligations: redact PII, add disclaimers, require human review, truncate output

Obligations follow the XACML permit-with-obligations model. What God Clause adds is the audit chain and signed policies in the same small package.

12 Condition Operators

Operator Example
equals / not_equals output.status equals "approved"
contains / not_contains caller.roles contains "admin"
greater_than / less_than output.confidence greater_than 0.85
in / not_in action in [generate, classify]
matches input.prompt matches "^[A-Za-z ]+$" (regex)
exists / not_exists output.disclaimer exists
rate_limit caller.user_id rate_limit { max: 100, window: "PT1H" }

Composite Logic

conditions:
  - all:                              # AND
      - field: caller.roles
        operator: contains
        value: analyst
      - any:                          # OR
          - field: output.confidence
            operator: greater_than
            value: 0.9
          - field: metadata.approved
            operator: equals
            value: true
      - not:                          # NOT
          field: output.flagged
          operator: equals
          value: true

Everything Else

  • Rate limiting — sliding window counters behind a pluggable StateStore interface (in-memory implementation included)
  • Tag filtering — evaluate rule subsets by tag at runtime
  • Contract versioning — multiple versions with activate/deactivate
  • Multi-tenancy — isolated contracts, engine, and audit per tenant
  • DSSE signing — cryptographic contract authorship via Dead Simple Signing Envelopes
  • OpenTelemetry export — OTLP/HTTP log mapping for Datadog/Grafana/New Relic
  • Prometheus metrics — godclause_decisions_total, godclause_blocks_total, evaluation duration summary
  • REST API server — standalone PDP with 17 endpoints, SSE streaming, batch evaluation
  • CLI tool — validate, lint, summarize, diff, evaluate, serve, audit verify/export, init, proof-bundle, verify-bundle
  • MCP tool authorization — glob-matched, fail-closed routing for Model Context Protocol tool calls

Integrations

HTTP Middleware (Express/Fastify)

app.use(godClauseMiddleware(gov, {
  contextExtractor: (req) => ({
    action: "generate",
    input: req.body,
    caller: { user_id: req.user.id, session_id: req.sessionId, roles: req.user.roles },
  }),
}));
// Auto-returns 403 on block, sets warning headers on warn

LangChain

const handler = createLangChainCallbackHandler(gov, { caller });
const chain = new LLMChain({ llm, prompt, callbacks: [handler] });

Vercel AI SDK

const wrapper = createVercelAIWrapper(gov, { caller });
const result = await wrapper.wrapGenerate({ prompt: params.prompt, doGenerate: () => model.doGenerate(params) });

REST API (Any Language)

# Start server
god-clause serve --port 3000 --contracts ./contracts

# Evaluate from any language
curl -X POST http://localhost:3000/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{"action":"generate","input":{"prompt":"..."},"output":{"toxicity_score":0.9},"caller":{"user_id":"u1","session_id":"s1","roles":["user"]}}'

Comparison

Feature God Clause OPA/Rego Permit.io Guardrails AI
Decision outcomes permit / deny / modify with obligations Any JSON document; obligations and rewrites are expressible allow / deny pass / fix / filter / reask per validator
Output rewriting Obligations returned to the caller, who applies them Policy can return a rewritten document; caller applies it No Built-in fix actions, including anonymizing validators
Detection (PII, toxicity, injection) Bring your own; the engine reads your signals Bring your own No Built-in validator hub
Policy format YAML Rego UI, Rego or Cedar via OPAL Python validators / RAIL
Audit integrity SHA-256 chain + HMAC + Merkle seals Decision logs, no chain Decision logs No
Signed policies DSSE envelopes Signed bundles Via OPA bundles No
Rate limiting Built-in External Built-in No
Multi-tenancy Isolated scopes Namespaces Built-in No
Embeddable (no server needed) Yes Go library or WASM PDP runs as a container Yes
Runtime dependencies 4 Go binary PDP + OPAL containers Many
Open-source license Apache 2.0 Apache 2.0 PDP and OPAL are open source; control plane is a hosted service Apache 2.0

The Adoption Path

Who it's for: Platform engineering teams building internal GenAI applications who already run (or will build) detectors and want one place to turn those signals into enforced, audited decisions.

Day 1: npm install god-clause. Load pii-redaction.contract.yaml. Wrap your LLM calls, pass your PII detector's result in as output.contains_pii, apply the obligation the decision returns. Every decision is hash-chained.

Week 1: Add prompt-injection.contract.yaml and toxic-content.contract.yaml. Set up the REST API server so your Python services can call it too.

Month 1: Deploy as a Kubernetes sidecar. Connect Prometheus metrics to Grafana. Seal the audit chain on a schedule and export a proof bundle.

Quarter 1: Multi-tenancy for different product teams. DSSE-signed contracts in your policy repo, hot-reloaded as signed bundles.


API Reference

GodClause

Method Returns Description
loadContractYAML(yaml) TrustContract Parse and activate a YAML/JSON contract
loadContract(contract) void Load a pre-parsed contract object
evaluate(ctx, opts?) Promise<PolicyDecision> Evaluate context (non-throwing)
enforce(ctx, opts?) Promise<PolicyDecision> Evaluate + throw on block
queryAudit(query) AuditEntry[] Search audit entries
verifyAuditChain(key?) { valid, brokenAt? } Verify hash chain integrity
sealAuditChain() ChainSeal Create Merkle seal checkpoint
createTenant(id, opts?) TenantScope Create isolated tenant scope

PolicyDecision

Field Type Description
outcome "permit" | "deny" | "modify" Three-valued result
allowed boolean outcome !== "deny"
obligations Obligation[] What to do for modify decisions
blocks RuleEvaluation[] Which rules blocked
warnings RuleEvaluation[] Which rules warned
governance_context GovernanceContext Contract ids and the SHA-256 of the loaded contracts

See full API docs for server endpoints, CLI commands, and configuration reference.


Examples


AI Onboarding

This repo ships with context files so any AI coding assistant can understand the project immediately:

File Assistant What it does
CLAUDE.md Claude Code Auto-read on session start — full architecture, commands, patterns, and rules
.cursorrules Cursor IDE Quick reference with architecture map and 9 development rules
.github/copilot-instructions.md GitHub Copilot Key files, code style, and domain concepts

Try it: Open the project in Claude Code and ask "What is this project?" — it already knows.


Contributing

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

License

Apache License 2.0 — enterprise-friendly with patent grant.

About

Embeddable AI governance framework — define guardrails in YAML, enforce in code, prove in math. Three-valued policy engine (permit/deny/modify), 9 drop-in threat contracts, evidence-grade audit trails, MCP tool governance, streaming PII redaction, formal verification.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages