@sunaiva/gate 1.1.2 → 1.1.4

package/BUSINESS_LICENSE.md

@@ -21,7 +21,7 @@ The following uses are licensed at no cost the moment you `npx @sunaiva/gate`:
 You need a paid license from Sunaiva Digital if you use this package to
 provide a service to **third-party paying customers in production** (i.e.
 running it in the critical path of a revenue-generating product before the
-Change Date below). Contact **kinan@sunaiva.ai** for pricing.
+Change Date below). Contact **licensing@sunaiva.ai** for pricing.
 
 ## Change Date and Change License
 
@@ -65,6 +65,6 @@ paid Sunaiva subscription regardless of the wrapper's licence state.
 
 ## Questions
 
-- General licensing questions: **kinan@sunaiva.ai**
+- General licensing questions: **licensing@sunaiva.ai**
 - Security concerns: **support@sunaiva.ai**
 - Commercial / paid tiers: **support@sunaiva.ai**

package/CHANGELOG.md

@@ -40,7 +40,7 @@ the **Sunaiva Core brand rebrand** (locked 2026-05-23: primary domain
 `sunaivacore.io`, parent `sunaiva.ai`, support mailbox `support@sunaiva.ai`).
 
 ### Changed
-- **Support / docs URLs scrubbed** of `github.com/Kinan27/sunaiva-gate` AND
+- **Support / docs URLs scrubbed** of the legacy public-repo reference AND
   rebranded to Sunaiva Core domain — package.json `repository` field removed;
   `bugs.email` now `support@sunaiva.ai`; `homepage` updated to
   `https://sunaivacore.io/products/gate`. The same scrub applied to
@@ -52,7 +52,7 @@ the **Sunaiva Core brand rebrand** (locked 2026-05-23: primary domain
 - **Backend URL updated** — `DEFAULT_BACKEND_URL` in both `dist/types/backend.{js,d.ts}`
   and `dist/version-pin/registry.js` changed from `mcp.sunaivacore.io/v1/gatehooks` to
   `mcp.sunaivacore.io/v1/gatehooks` per the Sunaiva MCP Command lane endpoint
-  ownership decision (Kinan directive 2026-05-25).
+  ownership decision (operator directive 2026-05-25).
 - **In-toto attestation URIs updated** — `BUILD_TYPE` and `BUILDER_ID` in
   `dist/installer/attestation/intoto.js` re-rooted from `sunaivadigital.com`
   to `sunaivacore.io`.

package/README.DRAFT.md

@@ -0,0 +1,418 @@
+# @sunaiva/gate — Free Safety Hook for AI Coding Agents
+
+**A fail-open safety net for your AI agent workflows. It catches more than
+you have today. If it ever errors, it gets out of your way. It cannot break
+your build.**
+
+> **Current version**: `1.1.2` | BUSL-1.1 license, Apache-2.0 on 2030-05-10
+> **Status**: learning in public — pattern coverage improves with every release.
+
+```bash
+npx @sunaiva/gate
+```
+
+No signup. No API key. No DNS record. Just add it to your MCP config and the
+32 free constitutional rules are active on the next tool call.
+
+---
+
+## The honest pitch
+
+AI coding agents are capable and fast. They are also capable of:
+
+- Committing hardcoded API keys to a public repository
+- Firing off a bulk email campaign the moment copy is approved
+- Charging a Stripe customer to test a payment flow
+- Running `rm -rf` on the wrong directory at 2am
+- Deploying a broken build to production because the test suite was skipped
+
+None of these require a rogue model. They happen from completely reasonable
+agent behaviour applied in the wrong moment. The gate intercepts those
+moments.
+
+The free tier works entirely on your machine — no backend, no telemetry,
+no external calls of any kind. It evaluates 32 constitutional rules locally
+against pattern matching. It is not perfect. Some edge cases are unmapped.
+The patterns improve with each release. We publish the miss reports and the
+fixes together.
+
+The core guarantee: **if the gate itself errors, it degrades to exactly
+your current behaviour**. You lose nothing by installing it.
+
+---
+
+## Install
+
+### 1. Add to your MCP client
+
+```json
+{
+  "mcpServers": {
+    "sunaiva-gate": {
+      "command": "npx",
+      "args": ["@sunaiva/gate"]
+    }
+  }
+}
+```
+
+Supported clients: Claude Code, Cursor, Windsurf, Cline, Aider, Codex, Zed.
+Restart your client. The gate loads on the first tool call.
+
+### 2. Verify it is working
+
+```bash
+npx @sunaiva/gate --smoke-test
+```
+
+Expected output:
+
+```
+✓ Gate loaded — 100 rules
+✓ Constitutional rules — 32 (cannot be disabled, enforced locally)
+✓ Premium rules — 68 (require backend service)
+✓ Live eval (git push origin main) — HARD block via gov-001
+✓ Live eval (rm -rf /) — HARD block via dat-001
+✓ Live eval (stripe.charges.create) — HARD block via fin-001
+Status: HEALTHY
+Version: 1.1.2
+```
+
+That is the full install. No further configuration required.
+
+---
+
+## What it catches today (free, local, no backend)
+
+The 32 constitutional rules are evaluated entirely on your machine using
+keyword and pattern matching against the action text. They are split across
+five categories.
+
+### Financial safety (6 rules)
+
+| Rule | What it blocks |
+|------|---------------|
+| `fin-001` | Stripe charges, PayPal payments, checkout submissions, in-app purchase flows |
+| `fin-002` | Cumulative API cost overruns, cloud billing events that exceed cap |
+| `fin-003` | Subscription changes, free-trial conversions, auto-renewal toggles |
+| `fin-004` | Crypto wallet transfers, DeFi interactions, gas fee submissions |
+| `fin-008` | Wire transfers, ACH batch files, SWIFT/IBAN banking API payloads |
+| `fin-009` | Google Ads / Meta Ads / TikTok campaign launches with spend attached |
+
+### Action governance (7 rules)
+
+| Rule | What it blocks |
+|------|---------------|
+| `gov-001` | `git push origin main/master`, Netlify prod deploys, Docker prod pushes |
+| `gov-002` | `rm -rf`, `DROP TABLE`, `git reset --hard`, S3 bucket deletes, file overwrites without backup |
+| `gov-004` | Cloudflare/Route 53/GoDaddy DNS record changes via API |
+| `gov-005` | IAM role assignment, OAuth scope escalation, admin privilege grants |
+| `gov-006` | Account deletion API calls (Stripe customer delete, workspace deactivation) |
+| `gov-008` | Instantly / Mailchimp / Klaviyo / Twilio bulk campaign activations |
+| `gov-012` | `terraform destroy`, CloudFormation stack deletion, Kubernetes namespace purges |
+
+### Data protection (4 rules)
+
+| Rule | What it blocks |
+|------|---------------|
+| `dat-001` | API key patterns in logs, secret env vars written to stdout, Bearer tokens in debug output |
+| `dat-002` | Names + email combinations, SSNs, passport numbers, health identifiers stored without consent |
+| `dat-004` | API keys hardcoded in git diffs, secrets in PR descriptions, keys in chat history |
+| `dat-010` | Audit log deletion, timestamp modification in records, log rotation bypasses |
+
+### Communication safety (6 rules)
+
+| Rule | What it blocks |
+|------|---------------|
+| `com-001` | SMTP sends, Gmail API message sends, SendGrid/Postmark sends to external recipients |
+| `com-002` | Twitter/X, LinkedIn, Facebook, Instagram, TikTok API post submissions |
+| `com-005` | CRM-triggered customer emails, in-app messages sent to user segments |
+| `com-006` | PR Newswire / Business Wire distribution API calls, investor relation sends |
+| `com-007` | DocuSign envelope sends, HelloSign contract submissions, NDA emails |
+| `com-009` | Cold email sequence activations (Instantly, Lemlist, Apollo, Outreach) |
+| `com-011` | Emails or messages attributed to a named human without a disclosure header |
+
+### Security and compliance (8 rules)
+
+| Rule | What it blocks |
+|------|---------------|
+| `sec-001` | API keys / passwords printed via `console.log`, `print()`, `logger.info()` |
+| `sec-002` | `eval()` on external input, `exec()` with user strings, `subprocess.run` with unvalidated args |
+| `sec-004` | `sudo` commands outside approved list, IAM scope requests exceeding declared need |
+| `sec-006` | JWT secret changes, OAuth provider config modifications, MFA bypass additions |
+| `sec-010` | API calls to banned model providers (DeepSeek, Kimi, MiniMax, and similar) |
+| `sec-011` | MFA disable API calls, TOTP secret deletion, 2FA removal from admin accounts |
+| `cmp-002` | EU resident data stored without consent record, PII transfers without lawful basis |
+| `know-009` | Market size claims without cited research, conversion rates without a source, fabricated benchmarks |
+
+**A further 68 standard rules are enumerated in the package** but require
+the premium backend (`SUNAIVA_GATE_BACKEND_URL`) to evaluate. Without it,
+they are skipped and recorded as `skipped_premium` in the audit log. You
+will see a once-per-session notice on stderr pointing to the upgrade path.
+
+---
+
+## The fail-open guarantee
+
+This is the property that makes install low-risk:
+
+- **Backend errors are always fail-open** — if the premium backend times out
+  or returns 5xx, that rule is skipped and recorded as
+  `skipped_premium_backend_error`. The action proceeds.
+- **The Python hook adapter (`hooks/sunaiva_gate_hook.py`) is always
+  fail-open** — any exception exits `0`, never blocks.
+- **The ship-confidence gate engine is always fail-open on its own
+  exceptions** — records `FAIL_OPEN_ON_EXCEPTION` in the audit, decision
+  is `allow`.
+- **Bad `rules.json`** — if the rules file is corrupt or unreadable, the
+  gate loads an empty rule set and logs to stderr. Nothing blocks.
+
+The **one exception to fail-open**: the 32 constitutional rules evaluated
+by the local engine exit with code `3` (internal error) or `4` (malformed
+input) if the gate binary itself crashes on those paths. This is intentional
+— a gate that silently passes everything on an internal error provides no
+protection. You can opt back into legacy fail-open with
+`SUNAIVA_GATE_FAIL_OPEN_ON_ERROR=1`.
+
+**Worst case: you set `DISABLE_SUNAIVA_GATE=1` and the gate is gone.**
+Every block message discloses this escape hatch, because an enforcement
+tool that hides its bypass is one that gets silently routed around. The
+kill-switch invocation is logged to the audit ledger as
+`decision: 'bypass_kill_switch'`.
+
+---
+
+## Honest limitations
+
+The free constitutional rules use **keyword and pattern matching**. They
+are not semantic. They can be:
+
+- **Defeated by rephrasing** — `send email to customer@example.com` blocks;
+  a sufficiently indirect phrasing may not.
+- **Wrong about context** — `gov-002` blocks `git reset --hard`; in a
+  deliberate rollback context that is correct behaviour that you have
+  deliberately chosen. Use the kill-switch or approval-token workflow to
+  unblock one-shot legitimate actions.
+- **Incomplete** — some attack patterns are not yet mapped. The 68 premium
+  rules cover more edge cases server-side; the free set is the foundation,
+  not the ceiling.
+
+We track miss reports. When a rule fails to catch a real incident, we log
+it, write a failing test fixture, and ship a new detection pattern in the
+next release. The changelog records every addition.
+
+---
+
+## Severity ladder
+
+The gate has three severity levels:
+
+| Severity | First match | Subsequent matches |
+|----------|-------------|-------------------|
+| `block` (constitutional) | Block immediately | Block every time |
+| `warn-then-block` | Warn, allow | Block |
+| `warn` | Warn, allow | Warn, allow |
+
+Constitutional rules always `block` on first match. The session escalation
+counter resets when the MCP server process restarts.
+
+---
+
+## Escaping a false positive
+
+Three escape valves, in order of preference:
+
+**1. Dry-run mode** — measure what would block without actually blocking:
+
+```bash
+export SUNAIVA_GATE_DRY_RUN=1
+# response.dry_run: true
+# response.would_have_blocked: [{rule_id, name, severity}, ...]
+```
+
+**2. Approval token** — for a one-shot legitimate deploy or action, drop a
+token file:
+
+```json
+// data/deploy_queue/APPROVAL_TOKENS/<artifact>.json
+{
+  "artifact": "my-package@1.0.0",
+  "approved_by": "you",
+  "approved_at": "2026-05-29T12:00:00Z",
+  "ttl_minutes": 60
+}
+```
+
+The gate honours it once within the TTL, then the token is consumed.
+
+**3. Kill-switch** — temporarily disables all enforcement:
+
+```bash
+export DISABLE_SUNAIVA_GATE=1  # Loud: logs every bypass
+unset DISABLE_SUNAIVA_GATE     # Enforcement resumes
+```
+
+---
+
+## Audit log
+
+Every gate decision is written to `~/.sunaiva/audit/audit.jsonl`:
+
+```json
+{
+  "timestamp": "2026-05-29T12:00:00.000Z",
+  "action": "git push origin main",
+  "decision": "blocked",
+  "rule_id": "gov-001",
+  "rule_name": "Production Deployment Gate",
+  "tier": "free",
+  "audit_status": "constitutional_block",
+  "evidence": ["keyword: git push", "keyword: origin main"],
+  "event_type": "validate_action"
+}
+```
+
+The audit log has no rotation cap. It is local only on the free tier —
+nothing leaves your machine. The `get_audit_log` MCP tool queries it
+directly.
+
+---
+
+## Data privacy
+
+**Free tier**: zero external network calls. Constitutional rules are evaluated
+against patterns shipped inside the package at `dist/rules/rules.json`. No
+action text, no code, no secrets leave your machine.
+
+**Pro tier** (opt-in): when you set `SUNAIVA_GATE_BACKEND_URL`, the engine
+POSTs only the proposed action text and rule IDs to the backend for the
+premium-rule subset. We never see your source code, your file contents, or
+your secrets. BYOK means your `ANTHROPIC_API_KEY` and `OPENROUTER_API_KEY`
+go directly from your machine to those providers — they do not transit
+Sunaiva infrastructure.
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DISABLE_SUNAIVA_GATE` | unset | Set to `1` to allow all actions (logged loudly) |
+| `SUNAIVA_GATE_DRY_RUN` | unset | Set to `1` to evaluate but never block |
+| `SUNAIVA_GATE_FAIL_OPEN_ON_ERROR` | unset | Set to `1` for legacy fail-open on internal errors |
+| `SUNAIVA_GATE_BACKEND_URL` | unset | Premium backend endpoint (Pro tier) |
+| `SUNAIVA_GATE_API_TOKEN` | unset | Bearer token for the premium backend |
+| `SUNAIVA_GATE_BACKEND_TIMEOUT_MS` | `3000` | Backend timeout — network errors fail-open |
+| `SUNAIVA_GATE_AUDIT_PATH` | `~/.sunaiva/audit/audit.jsonl` | Override audit log location |
+| `SHIP_CONFIDENCE_SIGNING_KEY` | unset | HMAC key for verifying signed ship-confidence verdicts |
+
+---
+
+## MCP tool reference
+
+| Tool | What it does |
+|------|--------------|
+| `validate_action` | Evaluate a proposed action against all active rules |
+| `get_audit_log` | Query the local audit log |
+| `get_rules` | List active rules; filter by `category` or `preset` |
+| `update_rules` | Enable / disable non-constitutional rules |
+| `log_bypass` | Record an intentional bypass (constitutional rules rejected) |
+| `ship_confidence_check` | Production deploy gate — free (approval token) or paid (signed verdict) |
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Allow / success / smoke-test HEALTHY |
+| `2` | Block |
+| `3` | Internal error, fail-CLOSED (opt into fail-open via `SUNAIVA_GATE_FAIL_OPEN_ON_ERROR=1`) |
+| `4` | Invalid input, fail-CLOSED (same opt-in) |
+
+---
+
+## Where this is going
+
+The free gate is the entry point to a capability ladder that maps directly
+to the hard problems of AI agent governance. Each tier unlocks capabilities
+that a local pattern-matching engine structurally cannot provide:
+
+**Tier 1 — Free gate (now)**: 32 local constitutional rules. Fail-open
+guarantee. Pattern coverage grows with every release. This is the floor.
+
+**Tier 2 — Cross-provider verification (~$0.002 per call)**: The same
+action evaluated by independent model providers simultaneously. A single
+model can be convinced; three models from different training lineages
+reaching the same verdict is structurally harder to manipulate. This is
+the conjunctive-routing layer.
+
+**Tier 3 — Signed compliance records ($50k/yr enterprise, $0.05/record
+metered)**: Cryptographically signed audit records for EU AI Act Article 12
+(transparency), Article 14 (human oversight), and Article 15 (accuracy)
+requirements. An immutable, tamper-evident trail that satisfies enterprise
+procurement and regulatory review — not documentation, but provable
+evidence. The ZK-receipt variant makes the proof verifiable without
+disclosing the underlying data.
+
+**Tier 4 — Adaptive memory**: The gate learns which rules generated
+friction with no follow-on incident (false positives) and which rules were
+bypassed before a real incident (missed catches). The pattern library
+improves from usage signals. Cost model: a share of the token-budget
+savings from avoiding the incidents the gate prevents.
+
+The cryptographic infrastructure behind Tiers 3 and 4 is covered by USPTO
+provisional patents 64/006,491 and 64/030,411.
+
+If Tier 2 or Tier 3 sounds relevant, email `support@sunaiva.ai`.
+
+---
+
+## Known gaps in the current release
+
+We track these openly:
+
+- The `--mcp-bridge` flag documented in the installer shims is not yet
+  wired into the binary entrypoint. Installer output references it but the
+  bridge path is a no-op until the next patch. The `validate_action` MCP
+  tool works correctly; only the direct-hook installer path is affected.
+- Version badge in this file reflects `1.1.2`. If `--smoke-test` shows a
+  different version, the package cache may be stale — run
+  `npx --yes @sunaiva/gate@latest --smoke-test`.
+- No aggregate telemetry today. The gate records decisions locally but
+  does not phone home. This means we cannot see which rules trigger most
+  often across the install base. A privacy-preserving aggregate metrics
+  channel (opt-in, anonymous counters only) is on the roadmap.
+
+---
+
+## License
+
+[BUSL-1.1](./BUSINESS_LICENSE.md) — free for evaluation, internal
+development, hobby and academic use. Commercial license required if you
+embed the gate in the critical path of a product sold to third-party
+paying customers before **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 | `support@sunaiva.ai` — include `--smoke-test` output and `node --version` |
+| Feature request | `support@sunaiva.ai` with subject `[feature-request]` |
+| Security vulnerability | `support@sunaiva.ai` — do not file publicly |
+| Pro / Enterprise enquiry | `support@sunaiva.ai` |
+| Product page | `https://sunaivacore.io/products/gate` |
+
+---
+
+*Built by a team whose own hooks locked them out of their development
+environment for nine hours. We fixed it. Then we shipped the fix.
+Then we signed the proof.*