@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: 2.0.5 "THUNDERSTRIKE P0-A + version coherence" — see CHANGELOG.md for full history.

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 — 104 rules
# → ✓ Constitutional rules — 35 local (27 constitutional + 8 recommended-default)
# → ✓ Premium rules — 69 (require backend service)
# → Status: HEALTHY
# → Version: 2.0.5

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

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

What's free, forever

The 2.0.5 Free tier (BUSL-1.1) ships with everything below baked into the npm package. No backend, no telemetry, no API key required. (Keyed installs emit one anonymous version ping on first use — opt out via SUNAIVA_GATE_TELEMETRY=0.)

• 35 local rules (27 constitutional + 8 recommended-default) 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 35 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-07-19. 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.

Pricing

Plan	Price	Rules	Agents	Seats	Webhook	Support
Open	$0/mo	35 local rules	—	1	—	Community
Dev	$0/mo (account)	35 local rules	—	1	—	Email (2 business days)
Pro	$49/mo ($490/yr)	104 rules (69 hosted)	5	1	✓	Email support (48h SLA)
Team	$199/mo ($1,990/yr)	104 rules (69 hosted)	Larger team	5 incl. (need more? contact us)	✓	Priority support (24h SLA)
Enterprise	from $999/mo (custom)	Custom rule sets	Unlimited	Unlimited	✓ + SSO	Dedicated + MSA SLA

See sunaivacore.io/pricing for the live price.

Team seat ceiling: 5 seats is what you are billed for today — that is the live Stripe SKU. The backend's org fleet-management enforcement ceiling (SEAT_LIMIT in routes/fleet.ts) is currently set to 10, a known billing/backend mismatch tracked internally as a P1 cross-lane defect. Do not read "10" anywhere as a sold entitlement — seats beyond 5 require contacting support until the mismatch is resolved.

All paid plans include: offline-capable on-device enforcement, model routing (bring your own inference provider API key — BYOK only in v1, see Known limitations below), fail-safe (fail-closed) enforcement, multi-target policy compilation (Pro+), and @sunaiva/gate npm package (BUSL-1.1).

Open (no account): npm i @sunaiva/gate — 35 local rules, no network call required, zero telemetry. One immutable policy constitution, compiled to Claude Code, MCP clients, and future agent platforms.

Dev (free account) (get a free API key: POST https://mcp.sunaivacore.io/v1/signup with {"email":"[e-mail]"} — returns an sgk_dev_ key instantly, no credit card required; dashboard at dashboard.sunaivacore.io): your own live dashboard showing enforcement activity, blocked actions, and rule coverage — your value made visible. Premium rules and features are shown visible-but-locked until you upgrade.

Current pricing at https://sunaivacore.io/pricing (canonical source of truth). Manage your account and audit dashboard at https://dashboard.sunaivacore.io.

Full tier matrix: TIER_DEFINITIONS.md.

Need adversarial multi-gate output verification with cryptographic proof anchors? → Sunaiva Validation — a separate product for verifying AI outputs, documents, and claims. Enterprise pricing, sales-led.

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 (35) — 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_KEY)          │    │
│   │            ─────────────────────────────► 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).

Installation

Wire @sunaiva/gate into every AI agent environment detected on this machine with a single command:

npx @sunaiva/gate install

Or using the long form:

npx @sunaiva/gate --install

What it does

install scans for known AI agent environments (Claude Code, Cursor, Codex, Aider, Continue, Cline, Gemini), writes the appropriate MCP configuration for each one it finds, and reports results. All writes are idempotent — re-running on an already-configured system is safe.

Flags

Flag	Description
--dry-run	Print what would be written without making any changes. Exit 0 even if some agents would fail.
--detected-only	Only configure agents that are already installed/active on this machine. Skip undetected ones.
--agents <csv>	Comma-separated list of specific agents to target (e.g. claude-code,cursor). Overrides detection.
--mcp-endpoint <url>	Custom MCP server URL. Defaults to https://gate.sunaivacore.io/mcp.

Examples

# Dry-run: preview all changes without writing
npx @sunaiva/gate install --dry-run

# Install only for Claude Code
npx @sunaiva/gate install --agents claude-code

# Install for detected agents with a custom endpoint
npx @sunaiva/gate install --detected-only --mcp-endpoint https://my-gate.example.com/mcp

# Install for multiple specific agents
npx @sunaiva/gate install --agents claude-code,cursor,codex

Install exit codes

Code	Meaning
0	All targeted agents configured successfully.
1	One or more per-agent failures (see output for details). Agents that succeeded are still configured.
2	Internal unhandled exception — no changes made.

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.
audit_verify	Verify the forward-linked cryptographic hash chain of the audit log (Patent Claim 19). Reports chain integrity, tamper evidence, and ed25519 signature validity per entry.
set_rule_mode	Set enforcement mode (shadow/advisory/enforce) for a specific rule. Requires API key (Pro+).
get_rule_modes	List all enforcement-mode overrides configured for the authenticated customer. Requires API key (Pro+).
reset_rule_mode	Remove a mode override for a rule, reverting it to its default enforcement mode. Requires API key (Pro+).
add_custom_rule	Create a custom detection rule in the backend. Requires API key (Pro+).
update_custom_rule	Update an existing custom rule. Requires API key (Pro+).
delete_custom_rule	Delete a custom rule. Requires API key (Pro+).
list_custom_rules	List all custom rules for the authenticated customer. Requires API key (Pro+).
list_presets	List available rule preset bundles. Requires API key (Dev+).
apply_preset	Apply a preset bundle, activating all its included rules. Requires API key (Pro+).

Total: 16 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_KEY	unset	Bearer token (JWT) for the premium backend. Required when SUNAIVA_GATE_BACKEND_URL is set. (SUNAIVA_GATE_API_TOKEN is accepted as a deprecated alias.)
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 v2.0.5] 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 — 104 rules
✓ Constitutional rules — 35 local (27 constitutional + 8 recommended-default, cannot be disabled)
✓ Premium rules — 69 (require backend service)
✓ Immutability guard — ACTIVE — 27 constitutional rule IDs locked
✓ Presets file — 5 presets available
✓ Live eval (git push origin main) — HARD block via gov-001,cnst-gov-deploy
✓ Live eval (ls -la) — ALLOW
✓ Live eval (rm -rf /) — HARD block via gov-002
✓ Live eval (stripe.charges.create) — HARD block via fin-001,cnst-fin-debit
✓ MCP server — ready (not started in smoke test)
Status: HEALTHY
Version: 2.0.5
Support: [e-mail]

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

Runtime note (WSL / 9p mounts): scripts/smoke.sh makes two Node.js invocations (--version then --smoke-test). On WSL with a 9p-mounted working directory, each startup takes ~10-60 s of real time because Node.js ESM resolution performs many metadata stat calls across the network filesystem. On a native Linux or macOS host the script finishes in 1-3 s. The script caches the --version result to avoid a third invocation, but the two remaining calls are irreducible without bundling.

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	104	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@2.0.5
# 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 35 local rules (27 constitutional + 8 recommended-default) 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 2.0.5 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 closed all seven. What is honestly not in 2.0.5 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.
• Deeper multi-tenant dashboard analytics — the self-serve Team tier ($199/mo or $1,990/yr, 5 seats incl.; need more? contact us) is live today with shared custom rules and a shared audit dashboard (see Pricing above); expanded cross-seat analytics views beyond the audit log are still in progress.
• 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 inference provider API keys go direct from your machine to those providers — they do not transit Sunaiva.

Install telemetry (keyed installs only). Keyless / free-tier installs make zero outbound network calls. If you set SUNAIVA_GATE_API_KEY, on first use @sunaiva/gate emits one anonymous install event so we can count real adoption. The event contains:

• gate version, OS platform, OS release;
• a timestamp.

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

To opt out (keyed installs), set SUNAIVA_GATE_TELEMETRY=0 in your environment. The gate respects this immediately. The marker is written to ~/.sunaiva-gate/first-run-<version> so subsequent runs do not re-emit.

Source: src/identity/first-run.ts. Receiver: https://api.sunaiva.ai/api/telemetry/first-run. 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-07-19, 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-07-19
• 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.