@sunaiva/gate

@sunaiva/gate

Stop documenting rules your agents ignore. Start enforcing them.

@sunaiva/gate is an MCP server that intercepts AI agent actions before they execute and blocks the ones that violate your rules. It runs locally, in process, with zero external dependencies on the Free tier — the rules are baked into the package and enforced by a deterministic engine.

npx @sunaiva/gate

Status: 1.1.5 "Freemium Monetization" — strip-patterns constitutional fix + per-session upsell trigger. Full changelog: CHANGELOG.md.

60-second quickstart

# 1. Install (no signup, no API key, no DNS records)
npx @sunaiva/gate

# 2. Verify it loaded
npx @sunaiva/gate --smoke-test
# → ✓ Gate loaded — 100 rules
# → ✓ Constitutional rules — 31 local (23 constitutional + 8 recommended) (cannot be disabled, enforced locally)
# → ✓ Premium rules — 69 server-side (require backend service)
# → Status: HEALTHY
# → Version: 1.1.0

# 3. Add to your MCP client (Claude Code, Cursor, Windsurf, Cline)
#    settings — see "MCP configuration" below.

That is the entire onboarding. The 31 local rules are active on first boot; no other configuration is required.

What's free, forever

The 1.1.0 Free tier (BUSL-1.1) ships with everything below baked into the npm package. No backend, no telemetry, no API key required.

• 31 local rules (23 constitutional + 8 recommended) enforced locally across five categories — financial-safety, data-protection, action-governance, security, and communication-safety. Detection patterns ship intact inside the package at dist/rules/rules.json.
• Severity ladder: block / warn-then-block / warn.
• Approval-token workflow — drop a JSON token at data/deploy_queue/APPROVAL_TOKENS/<artifact>.json and the gate honours it once, within a 1-hour TTL. This is the free-tier escape valve for one-shot manual unblocks.
• Local audit log at ~/.sunaiva/audit/audit.jsonl (lifetime, no rotation cap). Every entry records tier, audit_status, evidence, and event_type for queryable history.
• Kill-switch — DISABLE_SUNAIVA_GATE=1 short-circuits every validate_action to allowed: true with unconditional stderr disclosure.
• Dry-run mode — SUNAIVA_GATE_DRY_RUN=1 evaluates rules normally and records would_have_blocked: [...] without ever blocking.
• Constitutional immutability — the 31 local rules cannot be disabled via update_rules and cannot be bypassed via log_bypass, even if ~/.sunaiva/gate-config.json is hand-edited (the loader re-merges on every read).
• Fail-CLOSED by default — uncaught exceptions exit 3, malformed input exits 4. Both write a structured audit entry. Opt-in legacy fail-open via SUNAIVA_GATE_FAIL_OPEN_ON_ERROR=1.
• MCP integration — Claude Code, Cursor, Copilot, Windsurf, Cline via the standard mcpServers config.

The Free tier is BUSL-1.1 licensed and converts to Apache-2.0 on 2030-05-10. You can fork it, modify it, embed it in internal CI, and ship it in non-production workflows today — no contract, no signup, no credit card.

What you get with Pro (recommended, BYOK)

Pro adds the things a deterministic local engine cannot do on its own. Full tier matrix in TIER_DEFINITIONS.md. Current pricing at https://sunaivacore.io/pricing (canonical source of truth across all Sunaiva Core products). Manage your account and audit dashboard at https://dashboard.sunaivacore.io.

• 69 premium rules (100 total) evaluated server-side via the premium backend at https://mcp.sunaivacore.io/v1/gatehooks. Detection patterns are proprietary and stay in our infrastructure.
• Signed Ship-Confidence verdicts — HMAC-SHA256, 60-minute freshness window. The ship_confidence_check MCP tool verifies the signature in constant time and returns allowed: true only when the verdict is GREEN, fresh, and untampered.
• sunaiva-ship-confidence skill integration — three independent verification layers (cross-provider spec verification, property-based testing with Hypothesis, adversarial audit via garak + DeepTeam) that emit signed verdicts the Gate honours automatically in CI.
• Dashboard — rules tab, audit tab, settings tab, billing tab. Cloud audit sync with 90-day retention.
• BYOK — bring your own ANTHROPIC_API_KEY and OPENROUTER_API_KEY. You pay your own inference bill. We never see your tokens.
• Email support — [e-mail], 2-business-day SLA target.
• Stripe-managed billing — early-reviewer coupons are distributed privately to invited testers; the public price is the price you see.

Enterprise (SSO, on-prem, multi-tenant org dashboard, named CSM) is quote-to-cash — see the Enterprise tier in TIER_DEFINITIONS.md.

Architecture

┌────────────────────────────────────────────────────────────────┐
│  Your project (Claude Code / Cursor / Windsurf / Cline)        │
│                                                                │
│   ┌──────────────────────────────────────────────────────┐    │
│   │  MCP client invokes a tool                            │    │
│   │     e.g. Bash("git push origin main")                 │    │
│   └────────────────────────┬─────────────────────────────┘    │
└────────────────────────────┼───────────────────────────────────┘
                             ▼
┌────────────────────────────────────────────────────────────────┐
│  @sunaiva/gate  (MCP server, stdio transport)                  │
│                                                                │
│   ┌──────────────────────────────────────────────────────┐    │
│   │  validate_action                                      │    │
│   │     │                                                  │    │
│   │     ├─►  Local rules (31) — pattern matched  │    │
│   │     │     LOCALLY against dist/rules/rules.json       │    │
│   │     │     ─────────────────────────────► block/warn   │    │
│   │     │                                                  │    │
│   │     └─►  Premium rules (69) — only if backend set      │    │
│   │            POST https://mcp.sunaivacore.io/v1/gatehooks   │    │
│   │            (JWT auth via SUNAIVA_GATE_API_TOKEN)       │    │
│   │            ─────────────────────────────► block/warn   │    │
│   │            (fail-OPEN per-rule on backend error)       │    │
│   └──────────────────────────────────────────────────────┘    │
│                                                                │
│   audit log ─►  ~/.sunaiva/audit/audit.jsonl                  │
└────────────────────────────────────────────────────────────────┘

The Free tier path (constitutional rules) has zero network dependencies. The Pro path is opt-in — set SUNAIVA_GATE_BACKEND_URL and the engine starts POSTing actions to the backend for the premium-rule subset; without it, those rules are skipped (recorded as skipped_premium in the audit, surfaced once per session as a stderr notice).

Sunaiva Gate vs. the Sunaiva Validation Engine

@sunaiva/gate is an action-governance product: it intercepts AI agent tool calls at runtime and enforces constitutional hook rules with a deterministic OR-logic engine (any matching rule blocks). It validates agent ACTIONS — things the agent is about to do.

The Sunaiva Validation Engine at sunaiva.ai is a separate product that validates AI OUTPUTS — documents, reports, claims, and decisions — via a multi-gate architecture with composite cryptographic binding. These are complementary layers, not substitutes for each other.

The Sunaiva product family includes patent-pending validation technologies (USPTO 64/006,491 family) — see sunaiva.ai for the full Validation Engine.

MCP configuration

Add to your client's MCP settings:

{
  "mcpServers": {
    "sunaiva-gate": {
      "command": "npx",
      "args": ["@sunaiva/gate"]
    }
  }
}

Restart your MCP client. The first tool call will trigger the gate.

MCP tool reference

Tool	What it does
validate_action	Check a proposed action against all active rules. Returns {allowed, violations[], warnings[], skipped_premium[], dry_run?, would_have_blocked?, stamp}. The workhorse — every PreToolUse hook calls this.
log_bypass	Record an intentional rule bypass for the audit log. Rejects constitutional rules with a structured CONSTITUTIONAL_RULE_CANNOT_BE_BYPASSED error.
get_rules	List active rules; supports filtering by category or preset.
update_rules	Enable / disable rules. Rejects disable attempts against constitutional rules with a structured CONSTITUTIONAL_RULE_IMMUTABLE error.
get_audit_log	Return recent gate decisions from ~/.sunaiva/audit/audit.jsonl with tier, audit_status, evidence, event_type fields.
ship_confidence_check	Paid-tier production-deploy gate. Accepts a signed verdict path or artifact ID; verifies HMAC-SHA256 against SHIP_CONFIDENCE_SIGNING_KEY; returns {allowed, tier: "paid"|"free", reason, evidence}. Tagged in the audit ledger so you can measure the free-→paid upgrade funnel.

Total: 6 MCP tools. The ship_confidence_check tool is the ported TypeScript implementation of .claude/hooks/ship_confidence_gate.py v1.2.0, byte-compatible with the Python skill's canonical-JSON HMAC format.

Environment variables

Variable	Default	Purpose
DISABLE_SUNAIVA_GATE	unset	Set to 1 to short-circuit every validate_action to allowed: true. Unconditionally logs to stderr.
SUNAIVA_GATE_DRY_RUN	unset	Set to 1 to evaluate rules normally but never block. Response includes dry_run: true and would_have_blocked: [...].
SUNAIVA_GATE_BACKEND_URL	unset	Premium backend endpoint. Default for Pro customers: https://mcp.sunaivacore.io/v1/gatehooks. When unset, premium rules are skipped (recorded as skipped_premium).
SUNAIVA_GATE_API_TOKEN	unset	Bearer token (JWT) for the premium backend. Required when SUNAIVA_GATE_BACKEND_URL is set.
SUNAIVA_GATE_BACKEND_TIMEOUT_MS	3000	Backend request timeout. Backend errors fail-OPEN per-rule (logged as skipped_premium_backend_error).
SUNAIVA_GATE_FAIL_OPEN_ON_ERROR	unset	Set to 1 to restore the 1.0.x fail-open behaviour on uncaught exceptions and malformed input. Default is fail-CLOSED.
SHIP_CONFIDENCE_SIGNING_KEY	unset	HMAC-SHA256 key for verifying signed sunaiva-ship-confidence verdicts. Required by the ship_confidence_check tool.
SUNAIVA_GATE_AUDIT_PATH	~/.sunaiva/audit/audit.jsonl	Override the audit log path.

Exit codes

Code	Meaning
0	Allow / success / smoke-test HEALTHY
1	Generic test failure (legacy --test flag, smoke-test DEGRADED)
2	Block (Claude Code convention)
3	Fail-CLOSED internal error (uncaught exception). Opt-in fail-open via SUNAIVA_GATE_FAIL_OPEN_ON_ERROR=1.
4	Fail-CLOSED invalid input (malformed JSON, empty stdin). Same opt-in escape hatch.
5	Smoke-test DEGRADED with missing required files (e.g. dist/rules/rules.json absent).

Killing the gate (and why we tell you how)

@sunaiva/gate discloses its kill-switch in every block and warn message:

[sunaiva-gate v1.1.0] BLOCK — rule: dat-001 (recursive root deletion)
Escape: export DISABLE_SUNAIVA_GATE=1
Audit: ~/.sunaiva/audit/audit.jsonl

The escape hint is a deliberate security-disclosure design. An enforcement product that hides its own bypass is one that gets routed around in production without anyone knowing. The kill-switch invocation is itself logged to the audit ledger as decision: 'bypass_kill_switch', so disabling the gate is visible to anyone who reads the audit.

export DISABLE_SUNAIVA_GATE=1   # All actions allowed (logged)
unset DISABLE_SUNAIVA_GATE      # Back to normal enforcement

Use dry-run instead of the kill-switch when you want to measure what the gate would block without actually blocking anything:

export SUNAIVA_GATE_DRY_RUN=1
# → response.dry_run: true
# → response.would_have_blocked: [{rule_id, name, severity}, ...]

Decision model — warn-then-block escalation

Constitutional rules block on the first match. Standard rules (the non-constitutional subset) implement a session-state escalation:

• First match in a session → warn (action allowed, message printed).
• Subsequent matches in the same session → block.

This avoids one-time false-positive noise while still catching repeated violations. The session counter is reset when the MCP server process restarts. Confidence is derived from keyword-count thresholds: ≥3 keywords matched → high, 1-2 → medium, 0 → low (low confidence is filtered out before the response).

Smoke test

$ npx @sunaiva/gate --smoke-test
✓ Gate loaded — 100 rules
✓ Constitutional rules — 31 local (23 constitutional + 8 recommended) (cannot be disabled, enforced locally)
✓ Premium rules — 69 server-side (require backend service)
✓ Presets file — 5 presets available
✓ Live eval (git push origin main) — HARD block via gov-001
✓ Live eval (ls -la) — ALLOW
✓ Live eval (rm -rf /) — HARD block via dat-001
✓ Live eval (stripe.charges.create) — HARD block via fin-001
✓ Immutability guard — ACTIVE (31 local rules pinned)
✓ MCP server — ready (not started in smoke test)
Status: HEALTHY
Version: 1.1.1
Support: [e-mail]

Exit codes: 0 = HEALTHY, 1 = DEGRADED, 5 = missing required files.

Presets

get_rules accepts a preset argument that filters the active set:

Preset	Rules	Use case
minimal	5	Absolute non-negotiables only
essential	15	Recommended starting point
developer-safety	25	AI coding agents (Cursor / Windsurf / Cline / Aider)
financial-protection	24	All financial + resource rules
full-suite	100	Everything — Free constitutional set + Pro premium set

Presets read from dist/rules/presets.json. Premium presets require SUNAIVA_GATE_BACKEND_URL to be set; without it the premium rules are skipped with a skipped_premium audit entry.

Ship Confidence Gate (paid tier)

The ship_confidence_check MCP tool is the deploy-time gate for high-blast- radius commands (npm publish, wrangler deploy, gh repo create --public, netlify deploy --prod). It checks for authorization in two tiers:

Paid path — signed verdict

• The sunaiva-ship-confidence Python skill runs three verification layers against your product (spec verification, property-based testing, adversarial audit).
• It emits a signed verdict at data/ship_confidence_verdicts/<artifact>.signed.json.
• The ship_confidence_check tool verifies:
  • HMAC-SHA256 signature is valid (constant-time compare, byte-compatible with the Python skill's canonical-JSON encoding).
  • level == "GREEN" (YELLOW and RED hard-block).
  • Signed within the last 60 minutes (configurable via VERDICT_MAX_AGE_MINUTES).
• On all-pass: returns {allowed: true, tier: "paid", ...} and writes an audit entry tagged tier: "paid" with the verdict ID and evidence.

Free fallback — approval token

If no signed verdict is found (or SHIP_CONFIDENCE_SIGNING_KEY is not set), the tool falls back to a one-time approval token at data/deploy_queue/APPROVAL_TOKENS/<artifact>.json written within the last hour. Tagged tier: "free" in the audit ledger with an upgrade hint pointing at the paid skill.

# CLI form for use in CI:
npx @sunaiva/gate --ship-confidence @sunaiva/gate@1.1.0
# Exit 0 = allow, 2 = block, 3 = internal error (fail-OPEN logged)

Constitutional rules cannot be disabled or bypassed

This is the package's hard guarantee. The 31 local rules (23 constitutional + 8 recommended) are re-merged into active_rules on every config load — even if ~/.sunaiva/gate-config.json is hand-edited to remove them — and:

• update_rules({disable: ['fin-001']}) returns {error: "CONSTITUTIONAL_RULE_IMMUTABLE", rule_ids: [...]}. No state change.
• log_bypass({rule_id: 'fin-001'}) returns {error: "CONSTITUTIONAL_RULE_CANNOT_BE_BYPASSED", rule_id: ...}. Nothing written to the bypass log.

The kill-switch (DISABLE_SUNAIVA_GATE=1) is the only way to disable constitutional enforcement, and it is loud — stderr disclosure on every block, audit-ledger entry on every short-circuit. There are no quiet bypasses.

Known limitations — what 1.1.0 does NOT have

We shipped 1.0.1 with seven CRITICAL gaps flagged by our own signed Ship-Confidence verdict on our own commit (01KRDBCEYF2CAB21G6Y3E9VVH5, RED). 1.1.0 closes all seven. What is honestly not in 1.1.0 yet:

• Sunaiva-Managed inference — no flat-fee tier that includes LLM calls. BYOK only in v1. Revisit at 50+ Pro customers.
• UI verification layer (Playwright walkthroughs / computer-use) — designed in data/ship_confidence_skill_upgrade_2026_05_11.md, not yet shipped. Folded into Pro at no extra cost when it lands.
• Multi-tenant dashboard / "Pro Team" tier — Pro is single-seat in v1. Team management is Enterprise. A self-serve "Pro Team" tier waits until 10+ customers ask for it.
• On-prem / VPC deployment — Enterprise-only roadmap item. Helm chart and Terraform module designs exist; not yet packaged.
• Per-call / metered pricing — abandoned. Subscription wins.
• On-chain attestation (ERC-8004) — aspirational. Deferred to v2.x.

Full deferred-feature list: see STRATEGIC_PRIORITIES.md Phase 3 (in-repo, not shipped in the tarball — internal-facing roadmap).

Cross-platform

• Linux — native.
• WSL — native.
• macOS — native.
• Windows — native Node, plus a Python shim for clients that invoke the legacy hooks/sunaiva_gate_hook.py PreToolUse path.

Privacy & Telemetry

Your data stays where you choose. The Free tier makes zero external network calls for rule evaluation — constitutional rules are evaluated locally against patterns shipped inside the package. The Pro path is opt-in: when you set SUNAIVA_GATE_BACKEND_URL, the engine POSTs only the proposed action text and rule IDs to the backend; we never see your code, your secrets, or your filesystem. BYOK means your ANTHROPIC_API_KEY and OPENROUTER_API_KEY go direct from your machine to those providers — they do not transit Sunaiva.

Install telemetry. On first use, @sunaiva/gate emits one anonymous install event so we can count real adoption. The event contains:

• an anonymous fingerprint (SHA-256 of machine signals — not reversible);
• gate version, Node.js version, OS platform;
• a boolean indicating whether the install is from our own internal test environment (so we can subtract those from external-install counts);
• a timestamp.

It does not contain: your email, IP address (not logged), code, prompts, agent traces, or any identifying information.

To opt out, set SUNAIVA_GATE_TELEMETRY=0 in your environment. The gate respects this immediately. The fingerprint marker is written to ~/.sunaiva-gate/first-run.json so subsequent runs do not re-emit.

Source: src/identity/telemetry.ts. Receiver: a Cloudflare Worker that forwards anonymised events to our self-hosted Langfuse instance for analytics. We do not sell, share, or correlate this data.

License

BUSL-1.1 — free for evaluation, internal development, hobby and academic use. Commercial license required if you embed the Gate in the critical path of a third-party paying-customer product before the Change Date of 2030-05-10, after which the wrapper converts to Apache-2.0 automatically. The premium backend stays proprietary regardless of the Change Date.

• Licensor: Sunaiva Digital
• Change Date: 2030-05-10
• Change License: Apache License, Version 2.0

Support

Need	Where
Bug or crash	Email [e-mail] with --smoke-test output + node --version
Feature request	Email [e-mail] with subject [feature-request]
Security vulnerability	Email [e-mail] (do not file publicly)
Licensing	[e-mail]
Commercial / paid tier	[e-mail]
Product page	https://sunaivacore.io/pricing
Dashboard	https://dashboard.sunaivacore.io

When reporting bugs, include the output of npx @sunaiva/gate --smoke-test and node --version.

Contributing

Pull requests welcome. For substantial changes, please open an issue first to discuss the proposal. Constitutional rule additions require a corresponding test fixture in tests/bundle.test.ts and a passing dogfood Ship-Confidence verdict on the change.

Built by a team whose own hooks killed their development for nine hours. We fixed it. Then we shipped the fix. Then we signed the proof.