veilgate 0.1.1__tar.gz

veilgate-0.1.1/.env.example

@@ -0,0 +1,23 @@
+# Veilgate Environment Configuration Template
+# Copy to .env for local runtime overrides. NEVER commit actual .env files containing secrets.
+
+# Local Storage (SQLite WAL mode)
+VEILGATE_DB_PATH=./veilgate.db
+
+# Logging (DEBUG | INFO | WARNING | ERROR)
+VEILGATE_LOG_LEVEL=INFO
+
+# Cryptography (3-Tier Auto-Provisioning: if empty, auto-stored in OS native keyring)
+VEILGATE_MASTER_KEY=
+
+# Declarative Policy File Path
+VEILGATE_POLICY_PATH=./policy.yaml
+
+# Dashboard Port (FastAPI)
+VEILGATE_DASHBOARD_PORT=7878
+
+# Streamable HTTP Gateway Port
+VEILGATE_HTTP_PORT=8765
+
+# Remote MCP Testing Upstream Auth (Optional)
+GITHUB_PERSONAL_ACCESS_TOKEN=

veilgate-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI Quality Gate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    name: Unit & Security Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra dashboard
+
+      - name: Run unit test suite
+        run: uv run pytest tests/unit -q

veilgate-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,139 @@
+name: Publish to PyPI / TestPyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Publish destination registry'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+          - testpypi
+          - pypi
+  push:
+    tags:
+      - 'v*'       # Official release to PyPI (e.g., v0.1.0)
+      - 'test-v*'  # Test release to TestPyPI (e.g., test-v0.1.0)
+
+jobs:
+  test:
+    name: Run Quality Gate & Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra dashboard
+
+      - name: Run unit tests
+        run: uv run pytest tests/unit -q
+
+  build:
+    name: Build Distribution Packages
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Verify package distributions with twine
+        run: uvx twine check dist/*
+
+      - name: Store distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          retention-days: 5
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: |
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi') ||
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/test-v'))
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/veilgate
+    permissions:
+      id-token: write
+    env:
+      HAS_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN != '' }}
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI (Trusted Publishing / OIDC)
+        if: env.HAS_TOKEN == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish to TestPyPI (API Token)
+        if: env.HAS_TOKEN == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+
+  publish-to-pypi:
+    name: Publish to Official PyPI
+    needs: build
+    if: |
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi') ||
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && !startsWith(github.ref, 'refs/tags/test-v'))
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/veilgate
+    permissions:
+      id-token: write
+    env:
+      HAS_TOKEN: ${{ secrets.PYPI_API_TOKEN != '' }}
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI (Trusted Publishing / OIDC)
+        if: env.HAS_TOKEN == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Publish to PyPI (API Token)
+        if: env.HAS_TOKEN == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

veilgate-0.1.1/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.hypothesis/
+
+# Type checking & Linters
+.mypy_cache/
+.ruff_cache/
+
+# Veilgate Local Database & Sensitive Key Material (NEVER commit secrets or DBs)
+*.db
+*.db-wal
+*.db-shm
+*.key
+*.bak
+*.bak.json
+.env
+.env.local
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+.DS_Store

veilgate-0.1.1/.python-version

@@ -0,0 +1 @@
+3.14

veilgate-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Om Harsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

veilgate-0.1.1/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.5
+Name: veilgate
+Version: 0.1.1
+Summary: Local-First Zero-Trust MCP Privacy Firewall & Context-Diet Gateway
+Author: Veilgate Authors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,firewall,llm,mcp,model-context-protocol,privacy,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.21
+Requires-Dist: cryptography>=44
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp<5,>=4.1.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: keyring>=25
+Requires-Dist: numpy>=2.0
+Requires-Dist: phonenumbers>=9.0
+Requires-Dist: pydantic-settings>=2.10
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: python-ulid>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: rich>=13.0
+Requires-Dist: tiktoken>=0.9
+Requires-Dist: typer>=0.15
+Requires-Dist: uvicorn>=0.32
+Provides-Extra: dashboard
+Requires-Dist: fastapi>=0.115; extra == 'dashboard'
+Requires-Dist: jinja2>=3.1; extra == 'dashboard'
+Requires-Dist: uvicorn>=0.32; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: faker>=30; extra == 'dev'
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pyinstrument; extra == 'dev'
+Requires-Dist: pytest-benchmark; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: presidio
+Requires-Dist: presidio-analyzer>=2.2.36; extra == 'presidio'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://github.com/OmH3/Veilgate" target="blank"><img src="https://raw.githubusercontent.com/OmH3/Veilgate/main/docs/assets/logo.svg" width="120" alt="Veilgate Logo" /></a>
+</p>
+
+<p align="center">A local-first zero-trust <a href="https://modelcontextprotocol.io" target="_blank">Model Context Protocol (MCP)</a> privacy firewall & context-diet gateway.</p>
+
+<p align="center">
+  <a href="https://github.com/OmH3/Veilgate/releases" target="_blank"><img src="https://img.shields.io/badge/version-0.1.1-blue.svg" alt="Version" /></a>
+  <a href="https://github.com/OmH3/Veilgate/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
+  <a href="https://www.python.org/" target="_blank"><img src="https://img.shields.io/badge/python-%3E%3D3.11-blue.svg" alt="Python Versions" /></a>
+  <a href="https://github.com/OmH3/Veilgate/actions" target="_blank"><img src="https://img.shields.io/badge/build-passing-brightgreen.svg" alt="Build Status" /></a>
+  <a href="https://github.com/OmH3/Veilgate" target="_blank"><img src="https://img.shields.io/badge/coverage-96%25-brightgreen.svg" alt="Coverage" /></a>
+  <a href="https://discord.gg/veilgate" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
+</p>
+
+---
+
+## Description
+
+**Veilgate** is an enterprise-grade, local-first proxy and security gateway that sits transparently between AI client hosts (Claude Desktop, Cursor, Antigravity, LangGraph) and upstream Model Context Protocol (MCP) tool servers.
+
+As agentic AI workflows adopt dozens of autonomous MCP tools, developers face critical security and efficiency risks:
+1. **Unchecked Data Exfiltration:** Upstream tools can leak corporate databases, PII, and financial accounts directly into public LLM context windows.
+2. **Confused Deputy Attacks:** Tainted prompt data can trick LLMs into re-routing sensitive secrets into unmonitored external network sinks (email, webhooks, cURL).
+3. **Rug-Pull Tool Mutation:** Malicious or compromised servers can stealthily alter tool schemas and descriptions after initial approval.
+4. **Context Window Token Bloat:** Unbounded tool definitions consume 40–70% of prompt token limits before reasoning even begins.
+
+Veilgate eliminates these risks with a **zero-trust, fail-closed security architecture**:
+- **Lossless Context Diet:** Dynamically prunes bloated schemas and applies BM25 adaptive ranking to keep prompts lean and fast.
+- **Cryptographic Data Minimization:** Intercepts sensitive PII/secrets, stores them locally in an AES-256-GCM vault, and injects format-preserving synthetic tokens (`<vg:TYPE:ID>`) into LLM prompts.
+- **Taint-Aware Egress Enforcement:** Tracks data origin and halts unauthorized token re-hydration into external sinks.
+- **Interactive Human-in-the-Loop (HITL) Review:** Prompts developers via terminal or the sleek web dashboard with `⚡ Allow Once`, `🛡️ Allow Always`, or `✕ Deny`.
+- **Tamper-Evident SHA-256 Audit Trail:** Cryptographically hash-chains every discovery, call, token transformation, and approval in a local SQLite WAL ledger.
+
+---
+
+## System Architecture
+
+```mermaid
+flowchart TD
+    subgraph ClientHost["AI Client Host (Claude Desktop / Cursor / CLI)"]
+        LLM["AI Agent / LLM Engine"]
+    end
+
+    subgraph VeilgateGateway["Veilgate Zero-Trust Privacy Firewall"]
+        Proxy["FastMCP MITM Proxy Router"]
+        
+        subgraph Pipeline["Firewall Security Pipeline"]
+            RugPull["1. Rug-Pull & Fingerprint Guard"]
+            Diet["2. Lossless Context-Diet & BM25 Ranker"]
+            ACL["3. Zero-Trust ACL & Egress Inspector"]
+            HITL["4. Interactive HITL Review Queue"]
+            Taint["5. Taint Tracker & Vault Minimizer"]
+        end
+
+        Vault[("Local AES-GCM Vault & Stash")]
+        Audit[("Tamper-Evident Audit Ledger (SHA-256)")]
+        Policy[("policy.yaml & policy.learned.yaml")]
+    end
+
+    subgraph UpstreamMCP["Upstream MCP Ecosystem"]
+        ServerA["Database MCP (invoicedb)"]
+        ServerB["Egress MCP (mailer / web)"]
+        ServerC["Filesystem / CLI Tools"]
+    end
+
+    LLM <-->|"MCP stdio / SSE"| Proxy
+    Proxy --> Pipeline
+    Pipeline --> Vault
+    Pipeline --> Audit
+    Pipeline --> Policy
+    HITL <-->|"WebSocket / REST API"| Dashboard["Local Web Dashboard (Port 8765)"]
+    Pipeline <-->|"Safe Filtered Calls"| UpstreamMCP
+```
+
+---
+
+## Repository Layout
+
+| Path | Responsibility |
+| :--- | :--- |
+| `src/veilgate/config/` | Declarative Pydantic settings, constants, and layered policy compilers (`policy.yaml`, `policy.learned.yaml`). |
+| `src/veilgate/middleware/` | FastMCP interceptor middlewares for discovery filtering, tool calls, and structured error routing. |
+| `src/veilgate/pipeline.py` | Central `FirewallPipeline` orchestrating ACL, taint tracking, vault minimization, and audit hashing. |
+| `src/veilgate/services/` | Modular domain services: `AclService`, `ApprovalService`, `TaintService`, `MinimizerService`, `DietService`, `CatalogService`. |
+| `src/veilgate/security/` | Cryptographic primitives: AES-256-GCM envelope encryption, OS keyring integration, and blind hashing. |
+| `src/veilgate/repositories/` | Async SQLite repositories for sessions, tool catalog entries, approval states, and immutable audit logs. |
+| `src/veilgate/dashboard/` | Local FastAPI & Jinja2 monitoring dashboard featuring live metrics, interactive HITL approval queue, and audit trail stream. |
+| `src/veilgate/cli.py` | Rich Typer CLI powering `run`, `dashboard`, `init`, `adopt`, `keygen`, and `audit`. |
+| `tests/` | Comprehensive test suite containing unit tests, hypothesis property tests, and the A1–A16 security attack catalog. |
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum Version | Description |
+| :--- | :--- | :--- |
+| **Python** | `>= 3.11` | Modern async runtime supporting typed Pydantic models. |
+| **uv** *(Recommended)* | `>= 0.5.0` | Ultra-fast package installer and virtualenv manager. |
+| **SQLite** | `>= 3.35` | Built-in WAL mode database for local-first cryptographic storage. |
+
+### Installing uv
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell)
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+---
+
+## Project Setup
+
+Clone the repository and synchronize dependencies into an isolated virtual environment:
+
+```bash
+# Clone repository
+git clone https://github.com/OmH3/Veilgate.git
+cd veilgate
+
+# Install with development and dashboard extras
+uv sync --extra dev --extra dashboard
+
+# Alternatively with standard pip
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e ".[dev,dashboard]"
+```
+
+Generate your master cryptographic key:
+```bash
+uv run veilgate keygen
+```
+
+---
+
+## Quickstart & CLI Commands
+
+### 1. Initialize a New Policy
+Generate a baseline `policy.yaml` pre-configured with recommended security rules and PII detectors:
+```bash
+uv run veilgate init
+```
+
+### 2. Adopt Existing MCP Configurations
+Instantly migrate existing Claude Desktop, Cursor, or Cline MCP configs into Veilgate:
+```bash
+uv run veilgate adopt --client claude-desktop
+```
+
+### 3. Run the Veilgate Firewall Proxy
+Start the proxy gateway in foreground mode:
+```bash
+uv run veilgate run --config policy.yaml
+```
+
+### 4. Launch the Live Observability Dashboard
+Start the local review and monitoring dashboard:
+```bash
+uv run veilgate dashboard --config policy.yaml --port 8765
+```
+Open **`http://localhost:8765`** in your browser.
+
+---
+
+## Interactive Human-in-the-Loop (HITL) Approvals
+
+Veilgate treats egress and unallowed tools with zero trust. Whenever an agent attempts to invoke a tool that lacks pre-approved authorization or touches external networks, execution is **automatically paused** and queued for developer review:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/OmH3/Veilgate/main/docs/assets/dashboard-approval-preview.png" width="850" alt="Veilgate Approval Dashboard Preview" />
+</p>
+
+### Decision Matrix
+
+| Action | Decision State | Behavior & Security Guarantee |
+| :--- | :--- | :--- |
+| **`⚡ Allow Once`** | `APPROVED` | Permits this single tool call to proceed upstream. Leaves the policy unchanged so future invocations require fresh approval. |
+| **`🛡️ Allow Always`** | `APPROVED_AND_SAVED` | Permits execution **and** permanently appends a new grant rule to `policy.learned.yaml`. Subsequent invocations execute instantly without prompting. |
+| **`✕ Deny`** | `DENIED` | Immediately aborts the invocation with `ApprovalDeniedError`. Zero upstream data is transmitted, and the denial is logged to the audit ledger. |
+
+> [!NOTE]
+> All pending requests enforce a configurable fail-closed timeout (default: `120s`). If an approval expires without user intervention, Veilgate automatically denies the call.
+
+---
+
+## Live Web Dashboard & Observability
+
+The local-first dashboard (`http://localhost:8765`) gives developers complete visibility into agentic operations:
+
+1. **Minimization Metrics:**
+   - **Total Intercepted Calls:** Lifetime count of all MCP tool executions.
+   - **Blocked Exfiltrations:** Real-time count of blocked unauthorized calls or taint policy violations.
+   - **Tokens Minted:** Number of sensitive values safely anonymized into `<vg:TYPE:ID>`.
+   - **Pending Approvals:** Real-time count of calls awaiting human review.
+2. **Interactive Review Queue:**
+   - Visual cards detailing the tool name, session ID, reason code, and sanitized argument preview.
+   - Action buttons with real-time feedback.
+3. **Tamper-Evident Audit Stream:**
+   - Live stream of all gateway events chronologically ordered.
+   - Cryptographic SHA-256 hashes linking each row to its predecessor (`prev_hash`).
+
+---
+
+## Audit Verification & Security
+
+Veilgate maintains an append-only, tamper-evident cryptographic ledger:
+
+```bash
+# Verify integrity of all audit events
+uv run veilgate audit verify
+
+# Export audit trail to JSONL for SIEM ingestion
+uv run veilgate audit export --output audit_export.jsonl
+
+# Inspect details of a specific tool
+uv run veilgate explain mailer.send_email
+```
+
+---
+
+## Running Tests
+
+Veilgate maintains exhaustive test coverage across unit contracts and real-world attack vectors:
+
+```bash
+# Run all unit tests
+uv run pytest tests/unit -q
+
+# Run security attack suite (A1-A16 catalog)
+uv run pytest tests/security -q
+
+# Run test suite with coverage report
+uv run pytest --cov=src/veilgate --cov-report=term-missing
+```
+
+---
+
+## Publishing to PyPI
+
+Veilgate uses standard modern PyPA packaging powered by `hatchling` and `twine`:
+
+```bash
+# 1. Clean previous build artifacts
+rm -rf dist build *.egg-info
+
+# 2. Build sdist and wheel
+uv run python -m build
+
+# 3. Validate packages
+uv run twine check dist/*
+
+# 4. Upload to TestPyPI (optional verification)
+uv run twine upload --repository testpypi dist/*
+
+# 5. Upload to official PyPI
+uv run twine upload dist/*
+```
+
+---
+
+## Resources & Support
+
+- **Documentation:** [https://github.com/OmH3/Veilgate](https://github.com/OmH3/Veilgate)
+- **Model Context Protocol Specification:** [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
+- **Issues & Bug Reports:** [https://github.com/OmH3/Veilgate/issues](https://github.com/OmH3/Veilgate/issues)
+- **Discussions & Community:** [Discord Community](https://discord.gg/veilgate)
+
+---
+
+## License
+
+Veilgate is open-source software licensed under the **[MIT License](LICENSE)**.