dis-gravity 1.1.0 → 1.2.5

package/SECURITY.md

@@ -0,0 +1,105 @@
+# Dis-Gravity Security Policy & Architecture
+
+Dis-Gravity is designed from the ground up for high-security, privacy-conscious developer workflows. When connecting an IDE and agentic coding environment to an external messaging platform like Discord, execution boundaries, credential handling, and network isolation are critical.
+
+This document outlines Dis-Gravity's threat model, security architecture, fail-closed authorization, and responsible disclosure policy.
+
+---
+
+## 🛡️ Core Security Architecture
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                        DEVELOPER LOCAL MACHINE                         │
+│                                                                        │
+│  ┌─────────────────────────┐          ┌─────────────────────────────┐  │
+│  │   Desktop IDE / Agent   │          │     Dis-Gravity Engine      │  │
+│  │ (Antigravity / Cursor / │◄── CDP ──┤  - Snowflake Allowlist      │  │
+│  │   VS Code / Windsurf)   │:9000     │  - Path Traversal Guard     │  │
+│  └─────────────────────────┘(local)   │  - Shell Buffer Limits      │  │
+│                                       └──────────────┬──────────────┘  │
+│                                                      │                 │
+│                                        Outbound TLS  │ (ZERO INBOUND   │
+│                                        WebSocket WSS │  OPEN PORTS)    │
+└──────────────────────────────────────────────────────┼─────────────────┘
+                                                       │
+                                                       ▼
+                                            ┌─────────────────────┐
+                                            │   Discord Gateway   │
+                                            │  (discord.gg / API) │
+                                            └──────────┬──────────┘
+                                                       │
+                                                       ▼
+                                            ┌─────────────────────┐
+                                            │ Mobile Discord App  │
+                                            │  (Authorized User)  │
+                                            └─────────────────────┘
+```
+
+### 1. Zero Inbound Listening Ports
+* **Outbound-Only Ingress:** Dis-Gravity establishes a persistent, TLS-encrypted outbound WebSocket connection (`wss://gateway.discord.gg`) to the Discord Gateway.
+* **No Open Ports on WAN:** Dis-Gravity **never** opens an inbound TCP/UDP port on your host router or public network. It does not require port forwarding, ngrok tunnels, reverse proxies, or dynamic DNS.
+* **Attack Surface Reduction:** External port scanners, automated botnets, and local network peers cannot probe or connect to Dis-Gravity because there is no listening network socket.
+
+### 2. Strict Fail-Closed Authorization (`allowedUsers`)
+* **Snowflake ID Verification:** Every incoming interaction (slash commands, text shortcuts, button clicks, modal submissions, thread creations) is verified against `allowedUsers` in `lib/core.js` (`isUserAllowed`).
+* **Fail-Closed Default:** If `allowedUsers` is empty, unconfigured, or contains an unverified ID, access is **strictly denied immediately**. The command is dropped and never reaches the shell or the IDE.
+* **Channel Partitioning:** During onboarding (`dis-gravity setup`), Dis-Gravity automatically configures strict channel permission overwrites, hiding the bot control channel from `@everyone` and granting access solely to your specific user account.
+
+### 3. Localhost-Only CDP Isolation (Chrome DevTools Protocol)
+* **Loopback Binding Only:** For IDEs that utilize Chrome DevTools Protocol (Google Antigravity, Cursor AI, Windsurf), Dis-Gravity communicates strictly over local loopback (`127.0.0.1:9000`).
+* **No Remote CDP Exposure:** CDP is never bridged over the network. Only the local Dis-Gravity process running on the host machine connects to the IDE's debugging port.
+* **Deterministic Native Clicks:** Approvals (such as "Always Allow" or "Allow Once") are resolved through precise DOM inspection and native mouse click injection. Dis-Gravity never executes arbitrary scripts inside the IDE's webview sandbox.
+
+### 4. Filesystem Boundary & Path Traversal Containment
+* **Safe Path Resolution:** All filesystem inspection commands (`/cat`, `/open`, `/diff`, `/tree`, `/get`) pass through `safeResolveWorkspacePath(workspaceRoot, targetPath)`.
+* **Escaped Path Rejection:** If a relative path or symlink attempts to traverse outside the bounded workspace directory (e.g., `../../etc/passwd` or `..\\Windows\\System32`), Dis-Gravity throws an explicit error and rejects the request.
+* **Thread-Bound Sandboxes:** When using thread-to-workspace mapping (`/bind`), commands executed in that thread are strictly anchored to the assigned directory.
+
+### 5. Safe Shell Subprocess Execution
+* **Hard Timeouts:** Shell commands dispatched via `/sh` or `!sh` are governed by a strict timeout (default: 30 seconds) to prevent runaway or hanging processes.
+* **Buffer Overflow Prevention:** Subprocess outputs are capped at a maximum buffer of 10 MB (`maxBuffer`) to prevent memory exhaustion and denial-of-service on the host machine.
+* **Destructive Keyword Warnings:** Dis-Gravity heuristics detect dangerous operations (`rm -rf`, `mkfs`, `format`, `dd`) and require explicit interactive confirmation before execution.
+
+### 6. Local Credential Isolation
+* **Local Storage Only:** Your Discord bot token and preferences are stored locally on your machine at `~/.dis-gravity/config.json`.
+* **Strict File Permissions:** Configuration files are saved with restricted filesystem permissions (`0o600`).
+* **Zero External Telemetry:** Dis-Gravity does **not** transmit your bot tokens, workspace code, command histories, diffs, or prompts to any external third-party analytics, metrics, or telemetry servers.
+
+---
+
+## 🔍 Comparison: Dis-Gravity vs. Insecure Bridge Architectures
+
+| Security Vector | Insecure / Unaudited Bridges | Dis-Gravity Architecture |
+|---|---|---|
+| **Installation Hooks** | Risky npm `postinstall` scripts that download remote binaries or patch system files | **Zero postinstall scripts.** Pure npm/VS Code standard extension packaging. |
+| **Network Ingress** | Exposes HTTP webhooks, ngrok tunnels, or open WAN ports | **Zero inbound open ports.** 100% outbound TLS WebSocket via Discord.js Gateway. |
+| **User Authorization** | Checks username strings or allows any user in the Discord server | **Fail-closed Discord snowflake ID check.** Cryptographically unforgeable user ID. |
+| **Filesystem Access** | Unrestricted `fs.readFile` allowing full disk access | **`safeResolveWorkspacePath`** strictly enforces directory boundaries. |
+| **Code Execution** | Unchecked background auto-execution | **Explicit 1-tap interactive approvals**; dangerous commands flagged before running. |
+| **Telemetry & Leaks** | Sends tokens or telemetry to creator's backend | **Zero third-party telemetry.** All communication stays strictly between you and Discord. |
+
+---
+
+## ⚙️ Recommended Security Practices for Users
+
+1. **Keep Your Bot Private:** When creating your bot in the [Discord Developer Portal](https://discord.com/developers/applications), ensure **"Public Bot"** is unchecked so third parties cannot invite your bot to other servers.
+2. **Restrict Bot Intents:** Dis-Gravity only requires **Message Content Intent** to process your typed commands and voice messages. It does not require Server Members Intent or Presence Intent.
+3. **Use Dedicated Channels:** Create a private server or private channel accessible only to you. Do not run Dis-Gravity in shared public Discord channels.
+4. **Never Commit Your Bot Token:** Keep your Discord bot token strictly in `~/.dis-gravity/config.json` or as an environment variable (`DISGRAVITY_BOT_TOKEN`). Never commit it to git repositories.
+
+---
+
+## 🚨 Reporting a Vulnerability
+
+We take the security of Dis-Gravity seriously. If you discover a security vulnerability, please do **not** open a public issue.
+
+Instead, please report it via one of the following confidential channels:
+* **Private GitLab Vulnerability Report:** Submit a confidential vulnerability advisory through [Dis-Gravity Security Advisories](https://gitlab.com/rethinakumarsambath8/dis-gravity/-/security/advisories/new).
+* **Direct Email:** Send an encrypted email with reproduction steps to `rethinakumarsambath8@gmail.com`.
+
+### Response SLA
+* **Initial Response:** Within 24 hours of receipt.
+* **Assessment & Triage:** Within 48 hours.
+* **Patch & Coordinated Disclosure:** Within 7 business days for critical vulnerabilities.
+