@node9/proxy 1.0.13 → 1.0.14

package/README.md

@@ -29,7 +29,7 @@ While others try to _guess_ if a prompt is malicious (Semantic Security), Node9
 
 ---
 
-## ⚡ Key Architectural Upgrades
+## ⚡ Key Features
 
 ### 🏁 The Multi-Channel Race Engine
 
@@ -42,7 +42,7 @@ Node9 initiates a **Concurrent Race** across all enabled channels. The first cha
 
 ### 🧠 AI Negotiation Loop
 
-Node9 doesn't just "cut the wire." When a command is blocked, it injects a **Structured Negotiation Prompt** back into the AI’s context window. This teaches the AI why it was stopped and instructs it to pivot to a safer alternative or apologize to the human.
+Node9 doesn't just "cut the wire." When a command is blocked, it injects a **Structured Negotiation Prompt** back into the AI's context window. This teaches the AI why it was stopped and instructs it to pivot to a safer alternative.
 
 ### ⏪ Shadow Git Snapshots (Auto-Undo)
 
@@ -56,41 +56,11 @@ node9 undo
 node9 undo --steps 3
 ```
 
-Example output:
-
-```
-⏪  Node9 Undo
-    Tool:  str_replace_based_edit_tool → src/app.ts
-    When:  2m ago
-    Dir:   /home/user/my-project
-
---- src/app.ts (snapshot)
-+++ src/app.ts (current)
-@@ -1,4 +1,6 @@
--const x = 1;
-+const x = 99;
-+const y = "hello";
-
-Revert to this snapshot? [y/N]
-```
-
-Node9 keeps the last 10 snapshots. Snapshots are only taken for file-writing tools (`write_file`, `edit_file`, `str_replace_based_edit_tool`, `create_file`) — not for read-only or shell commands.
-
-### 🌊 The Resolution Waterfall
-
-Security posture is resolved using a strict 5-tier waterfall:
-
-1.  **Env Vars:** Session-level overrides (e.g., `NODE9_PAUSED=1`).
-2.  **Cloud (SaaS):** Global organization "Locks" that cannot be bypassed locally.
-3.  **Project Config:** Repository-specific rules (`node9.config.json`).
-4.  **Global Config:** Personal UI preferences (`~/.node9/config.json`).
-5.  **Defaults:** The built-in safety net.
-
 ---
 
 ## 🎮 Try it Live
 
-No install needed — test Node9's AST parser against real commands in the browser:
+No install needed — test Node9's policy engine against real commands in the browser:
 
 [![Open in HF Spaces](https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-sm.svg)](https://huggingface.co/spaces/Node9ai/node9-security-demo)
 
@@ -106,19 +76,52 @@ brew install node9
 # Or via npm
 npm install -g @node9/proxy
 
-# 1. Setup protection for your favorite agent
+# 1. Wire Node9 to your agent
 node9 setup           # interactive menu — picks the right agent for you
 node9 addto claude    # or wire directly
 node9 addto gemini
 
-# 2. Initialize your local safety net
-node9 init
+# 2. Enable shields for the services you use
+node9 shield enable postgres
+node9 shield enable aws
 
 # 3. Verify everything is wired correctly
 node9 doctor
+```
+
+---
 
-# 4. Check your status
-node9 status
+## 🛡️ How Protection Works
+
+Node9 has two layers of protection. You get Layer 1 automatically. Layer 2 is one command per service.
+
+### Layer 1 — Core Protection (Always On)
+
+Built into the binary. Zero configuration required. Protects the tools every developer uses.
+
+| What it protects | Example blocked action                                  |
+| :--------------- | :------------------------------------------------------ |
+| **Git**          | `git push --force`, `git reset --hard`, `git clean -fd` |
+| **Shell**        | `curl ... \| bash`, `sudo` commands                     |
+| **SQL**          | `DELETE` / `UPDATE` without a `WHERE` clause            |
+| **Filesystem**   | `rm -rf` targeting home directory                       |
+
+### Layer 2 — Shields (Opt-in, Per Service)
+
+Shields add protection for specific infrastructure and services — only relevant if you actually use them.
+
+| Shield       | What it protects                                                              |
+| :----------- | :---------------------------------------------------------------------------- |
+| `postgres`   | Blocks `DROP TABLE`, `TRUNCATE`, `DROP COLUMN`; reviews `GRANT`/`REVOKE`      |
+| `github`     | Blocks `gh repo delete`; reviews remote branch deletion                       |
+| `aws`        | Blocks S3 bucket deletion, EC2 termination; reviews IAM changes, RDS deletion |
+| `filesystem` | Reviews `chmod 777`, writes to `/etc/`                                        |
+
+```bash
+node9 shield enable postgres    # protect your database
+node9 shield enable aws         # protect your cloud infrastructure
+node9 shield list               # see all available shields
+node9 shield status             # see what's currently active
 ```
 
 ---
@@ -133,78 +136,55 @@ node9 status
 
 ---
 
-## ⚙️ Configuration (`node9.config.json`)
+## 🔗 Configuration Precedence
+
+Node9 merges configuration from multiple sources in priority order. Higher tiers win:
+
+| Tier | Source                    | Notes                                                     |
+| :--- | :------------------------ | :-------------------------------------------------------- |
+| 1    | **Environment variables** | `NODE9_MODE=strict` overrides everything                  |
+| 2    | **Cloud / Org policy**    | Set in the Node9 dashboard — cannot be overridden locally |
+| 3    | **Project config**        | `node9.config.json` in the working directory              |
+| 4    | **Global config**         | `~/.node9/config.json`                                    |
+| 5    | **Built-in defaults**     | Always active, no config needed                           |
+
+**Settings** (mode, approvers, timeouts) follow the table above — higher tier wins. A project config overrides a global config.
+
+**Smart rules** work differently. All layers are concatenated into a single ordered list and evaluated first-match-wins:
+
+```
+built-in defaults → global config → project config → shields → advisory defaults
+```
+
+Because built-in `block` rules sit at the front of this list, they always fire before any user-defined `allow` rule. **A project or global config cannot bypass Layer 1 protection.** Within the user layers, a project `block` rule fires before a shield `block` rule — so project policy can tighten or selectively override a shield.
+
+---
+
+## ⚙️ Custom Rules (Advanced)
+
+Most users never need this. If you need protection beyond Layer 1 and the available shields, add **Smart Rules** to `node9.config.json` in your project root or `~/.node9/config.json` globally.
 
-Rules are **merged additive**—you cannot "un-danger" a word locally if it was defined as dangerous by a higher authority (like the Cloud).
+Smart Rules match on **raw tool arguments** using structured conditions:
 
 ```json
 {
-  "settings": {
-    "mode": "standard",
-    "enableUndo": true,
-    "approvalTimeoutMs": 30000,
-    "approvers": {
-      "native": true,
-      "browser": true,
-      "cloud": true,
-      "terminal": true
-    }
-  },
   "policy": {
-    "sandboxPaths": ["/tmp/**", "**/test-results/**"],
-    "dangerousWords": ["drop", "destroy", "purge", "push --force"],
-    "ignoredTools": ["list_*", "get_*", "read_*"],
-    "toolInspection": {
-      "bash": "command",
-      "postgres:query": "sql"
-    },
-    "rules": [
-      { "action": "rm", "allowPaths": ["**/node_modules/**", "dist/**"] },
-      { "action": "push", "blockPaths": ["**"] }
-    ],
     "smartRules": [
       {
-        "name": "no-delete-without-where",
-        "tool": "*",
+        "name": "block-prod-deploy",
+        "tool": "bash",
         "conditions": [
-          { "field": "sql", "op": "matches", "value": "^(DELETE|UPDATE)\\s", "flags": "i" },
-          { "field": "sql", "op": "notMatches", "value": "\\bWHERE\\b", "flags": "i" }
+          { "field": "command", "op": "matches", "value": "kubectl.*--namespace=production" }
         ],
-        "verdict": "review",
-        "reason": "DELETE/UPDATE without WHERE — would affect every row"
+        "verdict": "block",
+        "reason": "Deploying to production requires a manual release process"
       }
     ]
   }
 }
 ```
 
-### ⚙️ `settings` options
-
-| Key                  | Default      | Description                                                  |
-| :------------------- | :----------- | :----------------------------------------------------------- |
-| `mode`               | `"standard"` | `standard` \| `strict` \| `audit`                            |
-| `enableUndo`         | `true`       | Take git snapshots before every AI file edit                 |
-| `approvalTimeoutMs`  | `0`          | Auto-deny after N ms if no human responds (0 = wait forever) |
-| `approvers.native`   | `true`       | OS-native popup                                              |
-| `approvers.browser`  | `true`       | Browser dashboard (`node9 daemon`)                           |
-| `approvers.cloud`    | `true`       | Slack / SaaS approval                                        |
-| `approvers.terminal` | `true`       | `[Y/n]` prompt in terminal                                   |
-
-### 🧠 Smart Rules
-
-Smart rules match on **raw tool arguments** using structured conditions — more powerful than `dangerousWords` or `rules`, which only see extracted tokens.
-
-```json
-{
-  "name": "curl-pipe-to-shell",
-  "tool": "bash",
-  "conditions": [{ "field": "command", "op": "matches", "value": "curl.+\\|.*(bash|sh)" }],
-  "verdict": "block",
-  "reason": "curl piped to shell — remote code execution risk"
-}
-```
-
-**Fields:**
+**Smart Rule fields:**
 
 | Field           | Description                                                                          |
 | :-------------- | :----------------------------------------------------------------------------------- |
@@ -216,33 +196,50 @@ Smart rules match on **raw tool arguments** using structured conditions — more
 
 **Condition operators:**
 
-| `op`          | Meaning                                                             |
-| :------------ | :------------------------------------------------------------------ |
-| `matches`     | Field value matches regex (`value` = pattern, `flags` = e.g. `"i"`) |
-| `notMatches`  | Field value does not match regex                                    |
-| `contains`    | Field value contains substring                                      |
-| `notContains` | Field value does not contain substring                              |
-| `exists`      | Field is present and non-empty                                      |
-| `notExists`   | Field is absent or empty                                            |
+| `op`             | Meaning                                                                    |
+| :--------------- | :------------------------------------------------------------------------- |
+| `matches`        | Field value matches regex (`value` = pattern, `flags` = e.g. `"i"`)        |
+| `notMatches`     | Field value does not match regex (`value` = pattern, `flags` optional)     |
+| `contains`       | Field value contains substring                                             |
+| `notContains`    | Field value does not contain substring                                     |
+| `exists`         | Field is present and non-empty                                             |
+| `notExists`      | Field is absent or empty                                                   |
+| `matchesGlob`    | Field value matches a glob pattern (`value` = e.g. `"**/node_modules/**"`) |
+| `notMatchesGlob` | Field value does not match a glob pattern                                  |
 
 The `field` key supports dot-notation for nested args: `"params.query.sql"`.
 
-**Built-in default smart rule** (always active, no config needed):
+Use `node9 explain <tool> <args>` to dry-run any tool call and see exactly which rule would trigger.
+
+### Settings
 
 ```json
 {
-  "name": "no-delete-without-where",
-  "tool": "*",
-  "conditions": [
-    { "field": "sql", "op": "matches", "value": "^(DELETE|UPDATE)\\s", "flags": "i" },
-    { "field": "sql", "op": "notMatches", "value": "\\bWHERE\\b", "flags": "i" }
-  ],
-  "verdict": "review",
-  "reason": "DELETE/UPDATE without WHERE clause — would affect every row in the table"
+  "settings": {
+    "mode": "standard",
+    "enableUndo": true,
+    "approvalTimeoutMs": 30000,
+    "approvers": {
+      "native": true,
+      "browser": true,
+      "cloud": true,
+      "terminal": true
+    }
+  }
 }
 ```
 
-Use `node9 explain <tool> <args>` to dry-run any tool call and see exactly which smart rule (or other policy tier) would trigger.
+| Key                  | Default      | Description                                                  |
+| :------------------- | :----------- | :----------------------------------------------------------- |
+| `mode`               | `"standard"` | `standard` \| `strict` \| `audit`                            |
+| `enableUndo`         | `true`       | Take git snapshots before every AI file edit                 |
+| `approvalTimeoutMs`  | `0`          | Auto-deny after N ms if no human responds (0 = wait forever) |
+| `approvers.native`   | `true`       | OS-native popup                                              |
+| `approvers.browser`  | `true`       | Browser dashboard (`node9 daemon`)                           |
+| `approvers.cloud`    | `true`       | Slack / SaaS approval                                        |
+| `approvers.terminal` | `true`       | `[Y/n]` prompt in terminal                                   |
+
+---
 
 ## 🖥️ CLI Reference
 
@@ -253,14 +250,13 @@ Use `node9 explain <tool> <args>` to dry-run any tool call and see exactly which
 | `node9 init`                  | Create default `~/.node9/config.json`                                                 |
 | `node9 status`                | Show current protection status and active rules                                       |
 | `node9 doctor`                | Health check — verifies binaries, config, credentials, and all agent hooks            |
+| `node9 shield <cmd>`          | Manage shields (`enable`, `disable`, `list`, `status`)                                |
 | `node9 explain <tool> [args]` | Trace the policy waterfall for a given tool call (dry-run, no approval prompt)        |
 | `node9 undo [--steps N]`      | Revert the last N AI file edits using shadow Git snapshots                            |
 | `node9 check`                 | Called by agent hooks; evaluates a pending tool call and exits 0 (allow) or 1 (block) |
 
 ### `node9 doctor`
 
-Runs a full self-test and exits 1 if any required check fails:
-
 ```
 Node9 Doctor  v1.2.0
 ────────────────────────────────────────
@@ -283,7 +279,7 @@ All checks passed ✅
 
 ### `node9 explain`
 
-Dry-runs the policy engine and prints exactly which rule (or waterfall tier) would block or allow a given tool call — useful for debugging your config:
+Dry-runs the policy engine and prints exactly which rule would fire — useful for debugging:
 
 ```bash
 node9 explain bash '{"command":"rm -rf /tmp/build"}'
@@ -294,9 +290,6 @@ Policy Waterfall for: bash
 ──────────────────────────────────────────────
 Tier 1 · Cloud Org Policy       SKIP  (no org policy loaded)
 Tier 2 · Dangerous Words        BLOCK ← matched "rm -rf"
-Tier 3 · Path Block             –
-Tier 4 · Inline Exec            –
-Tier 5 · Rule Match             –
 ──────────────────────────────────────────────
 Verdict: BLOCK  (dangerous word: rm -rf)
 ```
@@ -324,6 +317,11 @@ A corporate policy has locked this action. You must click the "Approve" button i
 - [x] **Native OS Dialogs** (Sub-second approval via Mac/Win/Linux system windows)
 - [x] **Shadow Git Snapshots** (1-click Undo for AI hallucinations)
 - [x] **Identity-Aware Execution** (Differentiates between Human vs. AI risk levels)
+- [x] **Shield Templates** (`node9 shield enable <service>` — one-click protection for Postgres, GitHub, AWS)
+- [ ] **Content Scanner / DLP** (Detect and block secrets like AWS keys and Bearer tokens in-flight)
+- [ ] **Universal MCP Gateway** (Standalone security tunnel for LangChain, CrewAI, and any agent without native hooks)
+- [ ] **Cursor & Windsurf Hook** (Native hook support for AI-first IDEs)
+- [ ] **VS Code Extension** (Approval requests in a native sidebar — no more OS popups)
 - [ ] **Execution Sandboxing** (Simulate dangerous commands in a virtual FS before applying)
 - [ ] **Multi-Admin Quorum** (Require 2+ human signatures for high-stakes production actions)
 - [ ] **SOC2 Tamper-proof Audit Trail** (Cryptographically signed, cloud-managed logs)