@sonoma-security/mcp-gateway 0.1.4 → 0.1.5

package/README.md

@@ -1,82 +1,141 @@
-# @sonoma/mcp-gateway
+# @sonoma-security/mcp-gateway
 
-Local MCP proxy for tool-level visibility. Intercepts stdio MCP servers, aggregates tools, forwards calls.
+Local MCP gateway for tool-level visibility and policy enforcement. Intercepts MCP tool calls, reports telemetry to Sonoma, and enforces allowlist/blocklist policies.
 
-## Usage
+## Quick Start
 
-```bash
-# With config file
-bun run src/cli.ts --config config.json
-
-# Auto-detect Claude Desktop config
-bun run src/cli.ts --auto --debug
-```
-
-## Config Format
+Add to your MCP client config (`~/.cursor/mcp.json`, Claude Desktop, etc.):
 
 ```json
 {
-  "servers": [
-    { "name": "fs", "command": "npx", "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/tmp"] }
-  ]
+  "mcpServers": {
+    "sonoma": {
+      "command": "npx",
+      "args": ["@sonoma-security/mcp-gateway@latest"],
+      "servers": {
+        "filesystem": {
+          "command": "npx",
+          "args": ["@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
 }
 ```
 
-Also accepts Claude Desktop `mcpServers` format.
+On first run, the gateway prompts for OAuth login. That's it - tool calls are now visible in your Sonoma dashboard.
 
-## Add to MCP Client
+## How It Works
+
+```
+AI Client (stdio) -> Sonoma Gateway -> [Upstream MCP Servers]
+                           |
+                           +-> Telemetry to Sonoma
+                           +-> Policy enforcement
+```
+
+The gateway:
+1. Spawns your upstream MCP servers
+2. Aggregates tools (namespaced as `serverName__toolName`)
+3. Forwards tool calls to the appropriate server
+4. Reports telemetry (tool name, duration, status)
+5. Blocks tools per your org's allowlist/blocklist
+
+## Auto-Detection
+
+By default (no arguments), the gateway auto-detects config from:
+- `~/.claude.json` (Claude Code)
+- `~/.cursor/mcp.json` (Cursor)
+- `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude Desktop)
+- `~/.codeium/windsurf/mcp_config.json` (Windsurf)
+
+## Non-Standard Config Location
+
+If your config is elsewhere, pass `--mcp-json-path`:
 
-**Cursor** (`~/.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {
     "sonoma": {
-      "command": "bun",
-      "args": ["run", "/path/to/packages/mcp-gateway/src/cli.ts", "--config", "/path/to/config.json"]
+      "command": "npx",
+      "args": ["@sonoma-security/mcp-gateway", "--mcp-json-path", "/custom/path/mcp.json"],
+      "servers": { ... }
     }
   }
 }
 ```
 
-**Claude Code**:
+## Auth Modes
+
+### User ID (default)
+Opens browser for OAuth on first run. Tool calls attributed to logged-in user.
+
+### Org Key
+Device-level telemetry via API key. No login required.
+
+```json
+"env": {
+  "SONOMA_API_KEY": "org_xxx_yyy",
+  "SONOMA_GATEWAY_AUTH_MODE": "org_key"
+}
+```
+
+## CLI
+
 ```bash
-claude mcp add sonoma -- bun run /path/to/packages/mcp-gateway/src/cli.ts --config /path/to/config.json
+npx @sonoma-security/mcp-gateway --help
+
+# Auth commands
+npx @sonoma-security/mcp-gateway --login   # OAuth login
+npx @sonoma-security/mcp-gateway --logout  # Clear credentials
+npx @sonoma-security/mcp-gateway --status  # Show auth status
+
+# Debug mode
+npx @sonoma-security/mcp-gateway --debug
 ```
 
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SONOMA_ENDPOINT` | Sonoma API URL (default: `https://app.sonoma.dev`) |
+| `SONOMA_API_KEY` | Org API key (for org_key mode) |
+| `SONOMA_GATEWAY_AUTH_MODE` | `user_id` or `org_key` |
+
+## Limitations
+
+- **Stdio servers only** - HTTP MCP servers not supported
+- **Nested config** - Servers must be nested under the gateway entry
+
 ## Development
 
 ```bash
-# Run tests (vitest)
+# Run tests
 bun run test
 
-# Watch mode
-bun run test -- --watch
-
 # Typecheck
 bun run typecheck
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector bun run src/cli.ts --config ./test-config.json --debug
 ```
 
-## Manual JSON-RPC Testing
+## Releasing
 
-```bash
-cat << 'EOF' | bun run src/cli.ts --config tests/fixtures/echo-server.json
-{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}
-{"jsonrpc":"2.0","method":"tools/list","id":2}
-EOF
-```
+Publishing is automated via GitHub Actions with npm trusted publishing (OIDC).
 
-## Architecture
+**To release a new version:**
 
-```
-AI Client (stdio) → Gateway → [Upstream MCP Servers]
-                      ↓
-              Tools namespaced as serverName__toolName
-```
+1. Update version in `package.json`
+2. Commit: `git commit -am "chore(mcp-gateway): bump to x.y.z"`
+3. Tag: `git tag mcp-gateway-vX.Y.Z`
+4. Push both: `git push origin staging --tags`
+
+CI automatically builds, tests, and publishes to npm. No tokens required.
+
+**What's automated:** build, test, typecheck, npm publish with provenance
+**What's manual:** version bump, git tag, push
 
-## Status
+## License
 
-- [x] Core proxy (tools/list, tools/call forwarding)
-- [x] Config loader (native + Claude Desktop format)
-- [x] CLI
-- [ ] Telemetry reporter
-- [ ] Policy enforcement
+MIT

package/dist/__tests__/config.test.js

@@ -171,4 +171,32 @@ describe("loadFromParentConfig", () => {
         expect(() => loadFromParentConfig(configPath)).toThrow("No mcpServers found");
     });
 });
+describe("config path validation", () => {
+    it("rejects non-JSON file extensions", () => {
+        expect(() => loadConfig("/some/path/config.txt")).toThrow("Config files must have .json extension");
+        expect(() => loadConfig("/etc/passwd")).toThrow("Config files must have .json extension");
+        expect(() => loadConfig("/some/path/config.yaml")).toThrow("Config files must have .json extension");
+    });
+    it("rejects paths outside allowed directories", () => {
+        // This path won't exist, but validation happens before existence check
+        // for files that do exist but are outside allowed dirs
+        // The .json extension check happens first, so this should pass extension check
+        // but fail on the location check IF the file existed
+        expect(() => loadConfig("/nonexistent/path/config.json")).toThrow("Config file not found");
+    });
+    it("accepts paths in temp directory", () => {
+        const testDir = join(tmpdir(), `mcp-gateway-security-test-${Date.now()}`);
+        mkdirSync(testDir, { recursive: true });
+        try {
+            const configPath = join(testDir, "valid.json");
+            writeFileSync(configPath, JSON.stringify({ servers: [] }));
+            // Should not throw - temp dir is allowed
+            const config = loadConfig(configPath);
+            expect(config.servers).toEqual([]);
+        }
+        finally {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+});
 //# sourceMappingURL=config.test.js.map

package/dist/__tests__/config.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.test.js","sourceRoot":"","sources":["../../src/__tests__/config.test.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEhE,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,IAAI,OAAe,CAAC;IAEpB,UAAU,CAAC,GAAG,EAAE;QACd,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,oBAAoB,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC3D,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAChD,aAAa,CACX,UAAU,EACV,IAAI,CAAC,SAAS,CAAC;YACb,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,aAAa;oBACnB,OAAO,EAAE,MAAM;oBACf,IAAI,EAAE,CAAC,WAAW,CAAC;iBACpB;aACF;YACD,KAAK,EAAE,IAAI;SACZ,CAAC,CACH,CAAC;QAEF,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;QAEtC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACnD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;QACtD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAChD,aAAa,CACX,UAAU,EACV,IAAI,CAAC,SAAS,CAAC;YACb,UAAU,EAAE;gBACV,UAAU,EAAE;oBACV,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,yCAAyC,EAAE,MAAM,CAAC;iBAC1D;gBACD,MAAM,EAAE;oBACN,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,qCAAqC,CAAC;oBAC7C,GAAG,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE;iBAC7B;aACF;SACF,CAAC,CACH,CAAC;QAEF,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;QAEtC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAEvC,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC;QAC/D,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,yCAAyC,CAAC,CAAC;QAEtE,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QAC3D,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,wBAAwB,CAAC,CAAC,CAAC,OAAO,CACxD,uBAAuB,CACxB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC/C,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAE3D,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,IAAI,OAAe,CAAC;IAEpB,UAAU,CAAC,GAAG,EAAE;QACd,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,2BAA2B,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAClE,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7C,aAAa,CACX,UAAU,EACV,IAAI,CAAC,SAAS,CAAC;YACb,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,qBAAqB,EAAE,iBAAiB,EAAE,UAAU,CAAC;oBAC5D,OAAO,EAAE;wBACP,UAAU,EAAE;4BACV,OAAO,EAAE,KAAK;4BACd,IAAI,EAAE,CAAC,yCAAyC,EAAE,MAAM,CAAC;yBAC1D;wBACD,MAAM,EAAE;4BACN,OAAO,EAAE,KAAK;4BACd,IAAI,EAAE,CAAC,qCAAqC,CAAC;4BAC7C,GAAG,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE;yBAC7B;qBACF;iBACF;aACF;SACF,CAAC,CACH,CAAC;QAEF,MAAM,MAAM,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAEhD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAEvC,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC;QAC/D,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,yCAAyC,CAAC,CAAC;QAEtE,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QAC3D,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7C,aAAa,CACX,UAAU,EACV,IAAI,CAAC,SAAS,CAAC;YACb,UAAU,EAAE;gBACV,aAAa,EAAE;oBACb,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,qBAAqB,CAAC;oBAC7B,OAAO,EAAE;wBACP,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE;qBACnD;iBACF;aACF;SACF,CAAC,CACH,CAAC;QAEF,MAAM,MAAM,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAEhD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7C,aAAa,CACX,UAAU,EACV,IAAI,CAAC,SAAS,CAAC;YACb,UAAU,EAAE;gBACV,UAAU,EAAE;oBACV,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,yCAAyC,EAAE,MAAM,CAAC;iBAC1D;gBACD,MAAM,EAAE;oBACN,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,qCAAqC,CAAC;iBAC9C;aACF;SACF,CAAC,CACH,CAAC;QAEF,MAAM,MAAM,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAEhD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IACrF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7C,aAAa,CACX,UAAU,EACV,IAAI,CAAC,SAAS,CAAC;YACb,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,qBAAqB,EAAE,iBAAiB,EAAE,UAAU,CAAC;iBAC7D;gBACD,UAAU,EAAE;oBACV,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,yCAAyC,EAAE,MAAM,CAAC;iBAC1D;aACF;SACF,CAAC,CACH,CAAC;QAEF,MAAM,MAAM,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAEhD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,wBAAwB,CAAC,CAAC,CAAC,OAAO,CAClE,8BAA8B,CAC/B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC/C,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;QAE9C,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CACpD,qBAAqB,CACtB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"config.test.js","sourceRoot":"","sources":["../../src/__tests__/config.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/ssrf-protection.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ssrf-protection.test.d.ts.map

package/dist/__tests__/ssrf-protection.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-protection.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ssrf-protection.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/ssrf-protection.test.js

@@ -0,0 +1,389 @@
+/**
+ * Unit tests for SSRF protection module
+ *
+ * Tests all exported functions:
+ * - ipToNum: IPv4 dotted-quad to 32-bit number conversion
+ * - isBlockedIP: IP range blocking (RFC 1918, link-local, etc.)
+ * - validateUrl: URL validation with DNS resolution and IP checks
+ * - safeFetch: Safe fetch with DNS pinning and redirect validation
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { ipToNum, isBlockedIP, validateUrl, safeFetch } from "../ssrf-protection.js";
+import dns from "node:dns/promises";
+describe("ipToNum", () => {
+    it("converts 0.0.0.0 to 0", () => {
+        expect(ipToNum("0.0.0.0")).toBe(0);
+    });
+    it("converts 255.255.255.255 to 4294967295", () => {
+        expect(ipToNum("255.255.255.255")).toBe(4294967295);
+    });
+    it("converts 192.168.1.1 correctly (tests unsigned shift)", () => {
+        // 192.168.1.1 = (192 << 24) | (168 << 16) | (1 << 8) | 1
+        // Without >>> 0, this would be negative due to sign bit
+        expect(ipToNum("192.168.1.1")).toBe(3232235777);
+    });
+    it("converts 10.0.0.1", () => {
+        expect(ipToNum("10.0.0.1")).toBe(167772161);
+    });
+    it("converts 172.16.0.1", () => {
+        expect(ipToNum("172.16.0.1")).toBe(2886729729);
+    });
+    it("converts 8.8.8.8 (public IP)", () => {
+        expect(ipToNum("8.8.8.8")).toBe(134744072);
+    });
+});
+describe("isBlockedIP", () => {
+    describe("RFC 1918 private ranges", () => {
+        it("blocks 10.0.0.0/8", () => {
+            expect(isBlockedIP("10.0.0.1")).toBe(true);
+            expect(isBlockedIP("10.128.0.1")).toBe(true);
+            expect(isBlockedIP("10.255.255.254")).toBe(true);
+        });
+        it("blocks 172.16.0.0/12", () => {
+            expect(isBlockedIP("172.16.0.1")).toBe(true);
+            expect(isBlockedIP("172.20.0.1")).toBe(true);
+            expect(isBlockedIP("172.31.255.254")).toBe(true);
+        });
+        it("blocks 192.168.0.0/16", () => {
+            expect(isBlockedIP("192.168.0.1")).toBe(true);
+            expect(isBlockedIP("192.168.1.1")).toBe(true);
+            expect(isBlockedIP("192.168.255.254")).toBe(true);
+        });
+    });
+    describe("link-local and metadata endpoints", () => {
+        it("blocks 169.254.0.0/16", () => {
+            expect(isBlockedIP("169.254.0.1")).toBe(true);
+            expect(isBlockedIP("169.254.169.254")).toBe(true); // AWS/GCP/Azure metadata
+            expect(isBlockedIP("169.254.255.254")).toBe(true);
+        });
+    });
+    describe('"this" network', () => {
+        it("blocks 0.0.0.0/8", () => {
+            expect(isBlockedIP("0.0.0.1")).toBe(true);
+            expect(isBlockedIP("0.128.0.1")).toBe(true);
+            expect(isBlockedIP("0.255.255.254")).toBe(true);
+        });
+    });
+    describe("loopback addresses (intentionally allowed)", () => {
+        it("allows 127.0.0.1", () => {
+            expect(isBlockedIP("127.0.0.1")).toBe(false);
+        });
+        it("allows 127.0.0.2", () => {
+            expect(isBlockedIP("127.0.0.2")).toBe(false);
+        });
+        it("allows 127.255.255.254", () => {
+            expect(isBlockedIP("127.255.255.254")).toBe(false);
+        });
+    });
+    describe("public IPv4 addresses", () => {
+        it("allows 8.8.8.8 (Google DNS)", () => {
+            expect(isBlockedIP("8.8.8.8")).toBe(false);
+        });
+        it("allows 1.1.1.1 (Cloudflare DNS)", () => {
+            expect(isBlockedIP("1.1.1.1")).toBe(false);
+        });
+        it("allows 151.101.1.140 (Fastly)", () => {
+            expect(isBlockedIP("151.101.1.140")).toBe(false);
+        });
+    });
+    describe("IPv4-mapped IPv6 addresses", () => {
+        it("blocks ::ffff:10.0.0.1 (private)", () => {
+            expect(isBlockedIP("::ffff:10.0.0.1")).toBe(true);
+        });
+        it("blocks ::ffff:169.254.169.254 (metadata)", () => {
+            expect(isBlockedIP("::ffff:169.254.169.254")).toBe(true);
+        });
+        it("blocks ::FFFF:192.168.1.1 (case-insensitive)", () => {
+            expect(isBlockedIP("::FFFF:192.168.1.1")).toBe(true);
+        });
+        it("allows ::ffff:127.0.0.1 (loopback - intentional)", () => {
+            expect(isBlockedIP("::ffff:127.0.0.1")).toBe(false);
+        });
+        it("allows ::ffff:8.8.8.8 (public)", () => {
+            expect(isBlockedIP("::ffff:8.8.8.8")).toBe(false);
+        });
+    });
+    describe("IPv6 link-local addresses", () => {
+        it("blocks fe80::1", () => {
+            expect(isBlockedIP("fe80::1")).toBe(true);
+        });
+        it("blocks fe80::abcd:ef01:2345:6789", () => {
+            expect(isBlockedIP("fe80::abcd:ef01:2345:6789")).toBe(true);
+        });
+        it("blocks febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff (edge of fe80::/10)", () => {
+            expect(isBlockedIP("febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff")).toBe(true);
+        });
+    });
+    describe("IPv6 unique-local addresses", () => {
+        it("blocks fc00::1 (ULA)", () => {
+            expect(isBlockedIP("fc00::1")).toBe(true);
+        });
+        it("blocks fd00::1 (ULA)", () => {
+            expect(isBlockedIP("fd00::1")).toBe(true);
+        });
+        it("blocks fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff (edge of fc00::/7)", () => {
+            expect(isBlockedIP("fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff")).toBe(true);
+        });
+    });
+    describe("IPv6 public addresses", () => {
+        it("allows 2001:db8::1 (documentation prefix, but not in block list)", () => {
+            expect(isBlockedIP("2001:db8::1")).toBe(false);
+        });
+        it("allows 2606:4700:4700::1111 (Cloudflare DNS)", () => {
+            expect(isBlockedIP("2606:4700:4700::1111")).toBe(false);
+        });
+        it("allows 2001:4860:4860::8888 (Google DNS)", () => {
+            expect(isBlockedIP("2001:4860:4860::8888")).toBe(false);
+        });
+    });
+    describe("IPv6 loopback (intentionally allowed)", () => {
+        it("allows ::1", () => {
+            expect(isBlockedIP("::1")).toBe(false);
+        });
+    });
+});
+describe("validateUrl", () => {
+    beforeEach(() => {
+        // Mock dns.lookup for most tests
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        vi.spyOn(dns, "lookup").mockImplementation((async (hostname) => {
+            // Default: return a public IP
+            if (hostname === "example.com") {
+                return [{ address: "93.184.216.34", family: 4 }];
+            }
+            if (hostname === "private.local") {
+                return [{ address: "10.0.0.1", family: 4 }];
+            }
+            if (hostname === "metadata.local") {
+                return [{ address: "169.254.169.254", family: 4 }];
+            }
+            if (hostname === "multi-ip.local") {
+                return [
+                    { address: "8.8.8.8", family: 4 },
+                    { address: "10.0.0.1", family: 4 }, // One blocked IP
+                ];
+            }
+            if (hostname === "notfound.local") {
+                const error = new Error("getaddrinfo ENOTFOUND");
+                error.code = "ENOTFOUND";
+                throw error;
+            }
+            // Default fallback
+            return [{ address: "1.1.1.1", family: 4 }];
+        }));
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe("protocol validation", () => {
+        it("rejects ftp:// protocol", async () => {
+            await expect(validateUrl("ftp://example.com")).rejects.toThrow("Protocol ftp: is not allowed");
+        });
+        it("rejects file:// protocol", async () => {
+            await expect(validateUrl("file:///etc/passwd")).rejects.toThrow("Protocol file: is not allowed");
+        });
+        it("rejects javascript: protocol", async () => {
+            await expect(validateUrl("javascript:alert(1)")).rejects.toThrow("Protocol javascript: is not allowed");
+        });
+        it("allows http:// protocol", async () => {
+            const result = await validateUrl("http://example.com");
+            expect(result.url.protocol).toBe("http:");
+        });
+        it("allows https:// protocol", async () => {
+            const result = await validateUrl("https://example.com");
+            expect(result.url.protocol).toBe("https:");
+        });
+    });
+    describe("blocked hostname detection", () => {
+        it("blocks metadata.google.internal", async () => {
+            await expect(validateUrl("http://metadata.google.internal")).rejects.toThrow("Access to metadata.google.internal is blocked for security reasons");
+        });
+        it("blocks metadata (GCP short name)", async () => {
+            await expect(validateUrl("http://metadata/")).rejects.toThrow("Access to metadata is blocked for security reasons");
+        });
+        it("blocks metadata.goog", async () => {
+            await expect(validateUrl("http://metadata.goog")).rejects.toThrow("Access to metadata.goog is blocked for security reasons");
+        });
+        it("blocks 169.254.169.254 as hostname", async () => {
+            // When IP is in hostname, it first checks BLOCKED_HOSTNAMES
+            await expect(validateUrl("http://169.254.169.254")).rejects.toThrow("Access to 169.254.169.254 is blocked for security reasons");
+        });
+        it("blocks fd00:ec2::254 (AWS IPv6 metadata) via BLOCKED_HOSTNAMES", async () => {
+            // The BLOCKED_HOSTNAMES check uses plain fd00:ec2::254 (without brackets).
+            // When used in a URL, IPv6 addresses require brackets [fd00:ec2::254],
+            // but url.hostname in Bun returns them WITH brackets, so net.isIP returns 0,
+            // triggering DNS resolution. We test the hostname check directly by mocking
+            // DNS to return the blocked address.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            vi.spyOn(dns, "lookup").mockImplementation((async (hostname) => {
+                if (hostname === "[fd00:ec2::254]") {
+                    return [{ address: "fd00:ec2::254", family: 6 }];
+                }
+                if (hostname === "example.com") {
+                    return [{ address: "93.184.216.34", family: 4 }];
+                }
+                return [{ address: "1.1.1.1", family: 4 }];
+            }));
+            // Should be blocked via DNS resolution check
+            await expect(validateUrl("http://[fd00:ec2::254]")).rejects.toThrow("resolves to private IP fd00:ec2::254");
+        });
+        it("allows example.com", async () => {
+            const result = await validateUrl("http://example.com");
+            expect(result.url.hostname).toBe("example.com");
+        });
+    });
+    describe("IP address validation in URL", () => {
+        it("blocks 10.0.0.1 (private)", async () => {
+            await expect(validateUrl("http://10.0.0.1")).rejects.toThrow("Access to private IP 10.0.0.1 is blocked for security reasons");
+        });
+        it("blocks 192.168.1.1 (private)", async () => {
+            await expect(validateUrl("http://192.168.1.1")).rejects.toThrow("Access to private IP 192.168.1.1 is blocked for security reasons");
+        });
+        it("blocks IPv6 fc00::1 (ULA) via DNS resolution", async () => {
+            // Set up mock to return a blocked IPv6 address
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            vi.spyOn(dns, "lookup").mockImplementation((async (hostname) => {
+                if (hostname === "[fc00::1]") {
+                    // Bun keeps brackets in url.hostname for IPv6
+                    return [{ address: "fc00::1", family: 6 }];
+                }
+                if (hostname === "example.com") {
+                    return [{ address: "93.184.216.34", family: 4 }];
+                }
+                return [{ address: "1.1.1.1", family: 4 }];
+            }));
+            // URL with brackets triggers DNS lookup in Bun (net.isIP("[fc00::1]") === 0)
+            await expect(validateUrl("http://[fc00::1]")).rejects.toThrow("resolves to private IP fc00::1");
+        });
+        it("allows 8.8.8.8 (public)", async () => {
+            const result = await validateUrl("http://8.8.8.8");
+            expect(result.url.hostname).toBe("8.8.8.8");
+            expect(result.resolvedAddress).toBeNull();
+        });
+        it("allows localhost (intentional for CLI)", async () => {
+            // localhost is not an IP, so DNS resolution happens
+            const result = await validateUrl("http://localhost:3000");
+            expect(result.url.hostname).toBe("localhost");
+            expect(result.resolvedAddress).toBe("1.1.1.1"); // From our mock
+        });
+        it("allows 127.0.0.1 (intentional for CLI)", async () => {
+            const result = await validateUrl("http://127.0.0.1:8080");
+            expect(result.url.hostname).toBe("127.0.0.1");
+            expect(result.resolvedAddress).toBeNull();
+        });
+        it("allows IPv6 ::1 (loopback) via DNS resolution", async () => {
+            // Set up mock to return loopback IPv6
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            vi.spyOn(dns, "lookup").mockImplementation((async (hostname) => {
+                if (hostname === "[::1]") {
+                    // Bun keeps brackets in url.hostname for IPv6
+                    return [{ address: "::1", family: 6 }];
+                }
+                if (hostname === "example.com") {
+                    return [{ address: "93.184.216.34", family: 4 }];
+                }
+                return [{ address: "1.1.1.1", family: 4 }];
+            }));
+            const result = await validateUrl("http://[::1]:9000");
+            // Bun keeps brackets in hostname for IPv6
+            expect(result.url.hostname).toBe("[::1]");
+            expect(result.resolvedAddress).toBe("::1");
+        });
+    });
+    describe("DNS resolution", () => {
+        it("returns resolved address for hostname-based URLs", async () => {
+            const result = await validateUrl("http://example.com");
+            expect(result.resolvedAddress).toBe("93.184.216.34");
+        });
+        it("returns null resolvedAddress for IP-based URLs", async () => {
+            const result = await validateUrl("http://8.8.8.8");
+            expect(result.resolvedAddress).toBeNull();
+        });
+        it("blocks hostname that resolves to private IP", async () => {
+            await expect(validateUrl("http://private.local")).rejects.toThrow("Hostname private.local resolves to private IP 10.0.0.1");
+        });
+        it("blocks hostname that resolves to metadata endpoint", async () => {
+            await expect(validateUrl("http://metadata.local")).rejects.toThrow("Hostname metadata.local resolves to private IP 169.254.169.254");
+        });
+        it("blocks hostname with any blocked IP in multi-A record", async () => {
+            await expect(validateUrl("http://multi-ip.local")).rejects.toThrow("Hostname multi-ip.local resolves to private IP 10.0.0.1");
+        });
+        it("throws on DNS resolution failure", async () => {
+            await expect(validateUrl("http://notfound.local")).rejects.toThrow("Unable to resolve hostname: notfound.local");
+        });
+    });
+    describe("invalid URL handling", () => {
+        it("rejects malformed URL", async () => {
+            await expect(validateUrl("not-a-url")).rejects.toThrow("Invalid URL format");
+        });
+        it("rejects URL with invalid characters", async () => {
+            await expect(validateUrl("http://example .com")).rejects.toThrow("Invalid URL format");
+        });
+    });
+    describe("URL preservation", () => {
+        it("preserves path and query parameters", async () => {
+            const result = await validateUrl("http://example.com/path?query=value");
+            expect(result.url.pathname).toBe("/path");
+            expect(result.url.search).toBe("?query=value");
+        });
+        it("preserves port", async () => {
+            const result = await validateUrl("http://example.com:8080");
+            expect(result.url.port).toBe("8080");
+        });
+    });
+});
+describe("safeFetch", () => {
+    beforeEach(() => {
+        // Mock DNS for safeFetch tests
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        vi.spyOn(dns, "lookup").mockImplementation((async (hostname) => {
+            if (hostname === "private.local") {
+                return [{ address: "10.0.0.1", family: 4 }];
+            }
+            // Don't provide mock for example.com - tests will fail without proper mocking
+            throw new Error(`Mock not configured for hostname: ${hostname}`);
+        }));
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.unstubAllGlobals();
+    });
+    describe("URL validation", () => {
+        it("rejects blocked URLs", async () => {
+            await expect(safeFetch("http://private.local")).rejects.toThrow("Hostname private.local resolves to private IP 10.0.0.1");
+        });
+        it("allows public IP addresses without DNS lookup", async () => {
+            // Mock fetch to verify it gets called
+            const mockFetch = vi.fn(async () => {
+                return new Response("success", { status: 200 });
+            });
+            vi.stubGlobal("fetch", mockFetch);
+            const response = await safeFetch("http://8.8.8.8/test");
+            expect(response.status).toBe(200);
+            expect(mockFetch).toHaveBeenCalledWith("http://8.8.8.8/test", expect.objectContaining({ redirect: "manual" }));
+        });
+    });
+    describe("redirect handling", () => {
+        it("throws on too many redirects", async () => {
+            // Call with remainingRedirects=0 to trigger immediate error
+            await expect(safeFetch("http://8.8.8.8", undefined, 0)).rejects.toThrow("Too many redirects");
+        });
+        it("validates each redirect target independently", async () => {
+            // Start with a valid public IP
+            const mockFetch = vi.fn(async (url) => {
+                if (url.includes("8.8.8.8")) {
+                    // Redirect to a private IP (should be blocked)
+                    return new Response(null, {
+                        status: 302,
+                        headers: { location: "http://10.0.0.1/evil" },
+                    });
+                }
+                return new Response("should not reach here", { status: 200 });
+            });
+            vi.stubGlobal("fetch", mockFetch);
+            // Initial URL is valid, but redirect target is blocked
+            await expect(safeFetch("http://8.8.8.8/start", undefined, 10)).rejects.toThrow("Access to private IP 10.0.0.1 is blocked");
+        });
+    });
+});
+//# sourceMappingURL=ssrf-protection.test.js.map