vaultcompute 0.1.0a1__tar.gz

vaultcompute-0.1.0a1/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Tests / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pyright/
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# Editors
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# VaultCompute local artifacts
+vault.db
+vault.db-wal
+vault.db-shm
+*.db-wal
+*.db-shm
+vaultcompute.yaml
+vaultcompute-proxy.yaml
+.mcp.json
+*.vaultcompute.log
+
+# Pre-rename local files may contain real schemas or secrets. Keep them ignored
+# so an existing checkout cannot accidentally stage them during migration.
+blindfold.yaml
+blindfold-proxy.yaml
+*.blindfold.log
+
+# Local development scaffolding — tooling and scratch harnesses, not part of
+# the project. Kept out of the repo deliberately: they belong to one machine
+# and one workflow, and would rot here.
+graphify-out/
+.claude/
+CLAUDE.md
+examples/debug_walkthrough.py
+examples/demo_chat_ollama.py

vaultcompute-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to VaultCompute are documented here.
+
+## 0.1.0a1 - 2026-09-14
+
+First alpha of the Mode B library, with memory and SQLite storage, optional
+encryption and the CLI. Mode A remains a beta proxy; Modes C/D are experimental
+host adapters.
+
+### Distribution
+
+- MIT SPDX metadata and explicit source-archive contents.
+- Clean wheel and source installs checked across the supported CI matrix.
+- Manual, tag-bound Trusted Publishing through TestPyPI before PyPI.
+- Runnable controlled-query demo, pilot protocol and private security reporting.
+- Python selection in CI now explicitly follows the declared matrix.
+
+### Security
+
+- Strict Mode A and Claude Code reject protected MCP responses containing
+  unsupported `structuredContent`, which previously remained in cleartext.
+- Resource schema merging preserves both full coverage and required-path
+  checks across overlapping globs, without nesting placeholders.
+- Resource `tables` declarations are rejected at config load until supported;
+  use `sensitive_fields` to hide a resource's array as an opaque value.
+- Hook vault initialization failures now emit the host's blocking response.
+- Schema overlap validation now includes intersecting wildcards and indices.
+
+## Development snapshot - 2026-09-04 (unpublished)
+
+First public release candidate.
+
+The project was renamed from its unpublished working name to **VaultCompute**;
+the distribution, Python package, CLI, configuration file and operation tools
+now use the `vaultcompute` / `vault_*` naming consistently.
+
+### Added
+
+- Fail-closed Mode B `VaultComputeSession` for synchronous and asynchronous tool
+  protection, exact capability-authorized table queries, model instructions and
+  final rendering.
+- Strict Mode A stdio MCP proxy for declared JSON tool results and resources.
+- Experimental Claude Code and Codex host adapters.
+- Memory and SQLite token stores, with optional AES-256-GCM encryption at rest.
+- Controlled collective-table operations and explicit `python_unsafe` compute.
+- Session-bound policy, lineage, compute-attempt quotas and transcript audit.
+
+### Security
+
+- Required protected paths and strict unsupported-shape handling fail closed.
+- Exact table capabilities bind session, table, complete operations and expiry.
+- Adversarial Mode B tests cover shape drift, adaptive threshold changes,
+  forged placeholders and cross-session access.
+
+Known structural and temporary limits are maintained in
+[`LIMITATIONS.md`](LIMITATIONS.md).

vaultcompute-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Start with a small, reproducible integration case. Use synthetic data and
+include the Python/package versions and integration mode; host reports also
+need the host version. Security issues belong in the private channel described
+in [SECURITY.md](SECURITY.md).
+
+## Local checks
+
+```bash
+uv sync --locked --all-extras --dev
+uv run pytest
+uv build --no-sources --out-dir dist/release
+uv run python scripts/verify_package.py dist/release --install
+```
+
+Use a fresh output directory when preparing a new version. The package verifier
+rejects mixed or stale release artifacts. It installs the wheel and source
+archive into temporary environments outside the checkout, with `PYTHONPATH`
+removed, and exercises the public API, CLI and encrypted storage.
+
+Changes to a privacy boundary need a failing regression case before the fix,
+then both the focused tests and the full suite. Avoid tests that merely repeat
+implementation details. Update the changelog and the supported-shape contract
+when behavior changes. Real-host compatibility requires an actual host run;
+fixtures are only a regression check.
+
+For new features, explain the user task and why the current operations cannot
+complete it. Preserve the separation between the core and host/transport
+adapters, and keep raw values out of model-visible errors.
+
+Release preparation and the pilot protocol live in [docs/release.md](docs/release.md)
+and [docs/pilot.md](docs/pilot.md). Code is distributed under the repository's
+[MIT license](LICENSE).

vaultcompute-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Pernigotto
+
+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.

vaultcompute-0.1.0a1/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: vaultcompute
+Version: 0.1.0a1
+Summary: Controlled computation over private data for LLM applications.
+Project-URL: Homepage, https://github.com/ManuelPr/vaultcompute
+Project-URL: Repository, https://github.com/ManuelPr/vaultcompute
+Project-URL: Issues, https://github.com/ManuelPr/vaultcompute/issues
+Project-URL: Changelog, https://github.com/ManuelPr/vaultcompute/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/ManuelPr/vaultcompute/blob/main/docs/api.md
+Author: Manuel Pernigotto
+License-Expression: MIT
+License-File: LICENSE
+Keywords: llm,mcp,privacy,tokenization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: demo
+Requires-Dist: anthropic>=0.30; extra == 'demo'
+Provides-Extra: encryption
+Requires-Dist: cryptography>=42; extra == 'encryption'
+Description-Content-Type: text/markdown
+
+# VaultCompute
+
+**Private data. Usable reasoning.**
+
+VaultCompute is a Python privacy layer for structured LLM tool results. It
+replaces declared private values with opaque tokens before your application
+sends the result to a model. Real values remain in a local vault; your
+application restores authorized values only when displaying the final answer.
+
+Use it when an agent needs to filter, sort or aggregate private records without
+putting those records in the model's context. Your application still owns tool
+access, user authorization and the conversation loop.
+
+**Status: alpha (`0.1.0a1`).** The library, MCP proxy, token stores and host adapters
+are implemented. Host integrations are version-sensitive; test their supported
+result shapes before relying on them. See [limitations](https://github.com/ManuelPr/vaultcompute/blob/main/LIMITATIONS.md).
+
+## How it works
+
+1. **Declare** sensitive fields or whole tables in a schema for each tool.
+2. **Protect** the result: store private values in memory or SQLite and replace
+   them with fresh, opaque placeholders containing 128 random bits.
+3. **Query** a hidden table with `vault_table`. Fixed operations return another
+   placeholder, with lineage and inherited restrictions.
+4. **Render** the final answer for the user after authorization. Keep the
+   rendered cleartext out of subsequent model requests.
+
+For example, a salary tool's result becomes `{"employees": "⟦tok_…⟧"}`. The
+model can request a sort by salary and a limit of one row. It receives another
+token; only final rendering reveals the selected employee. The abbreviated
+placeholder here is illustrative; real placeholders must be copied verbatim.
+
+The default `controlled` profile supports `filter`, `sort_by`, `limit`,
+`select`, `sum`, `mean`, `min`, `max` and `count` over declared tables.
+It executes no model-written code. Arbitrary Python through `vault_compute`
+requires explicit `compute.mode: python_unsafe` opt-in and assumes a cooperative
+model; it is not a safe boundary against malicious code or prompt injection.
+
+## Quick start
+
+Install from this repository with Python 3.11+ and `uv`:
+
+```bash
+git clone https://github.com/ManuelPr/vaultcompute
+cd vaultcompute
+uv sync
+```
+
+Alternatively, in your own Python environment, run `python -m pip install -e .`.
+The commands below use `uv run` to select the project's environment.
+
+Run `uv run python examples/quickstart.py`, or save the complete example below
+as `quickstart.py` and run `uv run python quickstart.py`. It uses synthetic data and a scripted query;
+no API key, model service or MCP server is required.
+
+```python
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from uuid import uuid4
+
+from vaultcompute import TableQueryCapability, VaultComputeSession
+from vaultcompute.config import VaultComputeConfig
+
+sys.stdout.reconfigure(encoding="utf-8")
+
+
+def list_employees():
+    return {"employees": [
+        {"name": "Manuel", "salary": 62000},
+        {"name": "Andrea", "salary": 71000},
+    ]}
+
+
+config = VaultComputeConfig.model_validate({
+    "schemas": {
+        "list_employees": {
+            "tables": [{
+                "path": "$.employees",
+                "columns": [{"name": "name"}, {"name": "salary"}],
+            }]
+        }
+    }
+})
+session = VaultComputeSession(config, session_id=uuid4().hex)
+protected = session.call_protected_tool("list_employees", list_employees)
+print("Tool result for the model:", json.dumps(protected, ensure_ascii=False))
+
+# The trusted application authorizes this exact request: highest-paid employee.
+ops = [
+    {"op": "sort_by", "column": "salary", "desc": True},
+    {"op": "limit", "n": 1},
+    {"op": "select", "columns": ["name", "salary"]},
+]
+capability = TableQueryCapability.issue(
+    session_id=session.session_id,
+    table_token=protected["employees"],
+    ops=ops,
+    expires_at=datetime.now(timezone.utc) + timedelta(minutes=5),
+)
+
+# Scripted stand-in for the model's proposed vault_table call.
+proposed_query = {"table": protected["employees"], "ops": ops}
+result_token = session.execute_authorized_query(
+    proposed_query, capability=capability,
+)
+model_answer = f"Highest-paid employee: {result_token}"
+print("Model answer:", model_answer)
+print("User sees:", session.render_final_answer(model_answer))
+```
+
+The first two lines contain placeholders. The last line shows:
+
+```text
+User sees: Highest-paid employee: [{"name": "Andrea", "salary": 71000}]
+```
+
+In a real integration, add `session.model_instructions` to the system prompt,
+send only protected tool results to the model, and dispatch its proposed table
+queries through the authorized handler. Issue capabilities from trusted
+application decisions, not automatically from whatever query the model proposes.
+Render only at the final user-facing boundary; never add that cleartext to model
+history. Async tools use `await session.call_protected_tool_async(...)`.
+
+The library does not supply an LLM conversation loop. See the
+[Python API](https://github.com/ManuelPr/vaultcompute/blob/main/docs/api.md) for its supported methods and integration contract.
+
+## Choose an integration
+
+| Mode | Use it when | Status | Final values |
+|---|---|---|---|
+| **B — Python library** | You own the application and model loop | Reference integration | Your application renders them |
+| **A — stdio MCP proxy** | You wrap one existing MCP server | Beta | Placeholders unless your client implements final rendering |
+| **C — Claude Code plugin** | You use the supported host hook shapes | Experimental | Display-only reveal through the adapter |
+| **D — Codex plugin** | You protect supported local tool results | Experimental guardrail | Placeholders remain visible |
+
+Start with **Mode B** when you write the application. For Mode A, configure
+your MCP client to launch the proxy with an explicit configuration path:
+
+```bash
+uv run vaultcompute --config vaultcompute.yaml -- python -m your_org.some_mcp_server
+```
+
+The downstream command above is a placeholder for your own MCP server. The
+proxy cannot intercept a third-party client's final answer for display.
+
+For host setup, follow the [Claude Code plugin guide](https://github.com/ManuelPr/vaultcompute/blob/main/plugin/README.md) or the
+[Codex plugin guide](https://github.com/ManuelPr/vaultcompute/blob/main/plugins/vaultcompute-codex/README.md). Both require a shared
+SQLite vault and the `vaultcompute` command on the host's `PATH`.
+The [host adapter contract](https://github.com/ManuelPr/vaultcompute/blob/main/docs/host-adapters.md) lists supported shapes,
+failure behavior and real-host verification. Hook fixtures alone do not prove
+compatibility with an installed host version.
+
+## Configuration
+
+The Python example above creates its configuration directly. For the CLI and
+plugins, create `vaultcompute.yaml`; start from
+[vaultcompute.example.yaml](https://github.com/ManuelPr/vaultcompute/blob/main/vaultcompute.example.yaml). A minimal declaration is:
+
+```yaml
+schemas:
+  get_salary:
+    sensitive_fields:
+      - path: $.salary
+        semantic_type: salary
+        unit: EUR/year
+      - path: $.bonus
+        required: false
+```
+
+- Tool names must match the names passed to the integration exactly.
+- Paths are **required by default**. A missing required path stops protection;
+  `required: false` permits a legitimate absence. Unsupported path syntax and
+  overlapping declarations within one schema are rejected at load.
+- A `tables` declaration hides the entire list. Its columns specify what the
+  model may query. Scalar placeholders are not queryable with `vault_table`.
+- MCP `resources` use URI globs and support **`sensitive_fields` only**.
+  Resource `tables` declarations are rejected. An array can be hidden as a
+  sensitive field, but that does not make it a queryable table.
+- `compute.mode` defaults to `controlled`; the proxy and host operation server
+  also accept `disabled` and the explicit `python_unsafe` profile.
+
+### Storage and expiry
+
+Memory storage is the default and loses its vault when the process ends.
+Use SQLite when tokens must survive restarts or be shared across processes:
+
+```yaml
+storage:
+  backend: sqlite
+  path: ./vault.db
+  encrypt_at_rest: true
+tokens:
+  default_ttl: 3600
+```
+
+For encryption, install the optional dependency from the repository:
+
+```bash
+uv sync --extra encryption
+```
+
+Or use `python -m pip install -e ".[encryption]"` in your own environment.
+Encrypted storage requires `VAULTCOMPUTE_VAULT_KEY` in every process that opens
+the vault: a base64-encoded 32-byte key, supplied outside the configuration and
+database. Values are encrypted with AES-256-GCM; session and lineage metadata
+remain readable. Without encryption enabled, SQLite stores cleartext values.
+
+The default token lifetime is one hour. SQLite persistence does not extend it:
+expired or unknown tokens render as `[unknown token]`; tokens denied by policy
+render as `[redacted]`.
+
+## Threat model & limitations
+
+Protection applies to **declared values on supported result paths**. It does
+not cover the entire conversation or replace your application's access control.
+
+- **Undeclared values remain visible.** Review schemas whenever tools change.
+  User prompts, tool arguments and values sent through other application paths
+  are outside this protection.
+- **Unsupported results are blocked on strict paths.** Mode A strict rejects
+  batches and protected results with non-JSON text, images, blobs or
+  `structuredContent`. The Claude Code MCP adapter also rejects
+  `structuredContent`. `proxy.strict: false` allows compatibility passthrough
+  and gives up that blocking guarantee.
+- **Host coverage is limited.** Tools that do not enter an adapter's supported
+  hooks are not protected. Host telemetry may record original results before
+  a hook runs. The Codex adapter does not provide display-only rehydration.
+- **The vault and final rendering are trusted.** Real values exist in process
+  memory. Session-bound policy is the default; application authorization must
+  decide which user may access the underlying data and approve a query.
+- **Arbitrary Python is unsafe.** Its restricted subprocess and lineage-wide
+  attempt quota do not eliminate extraction through deliberate errors or
+  sandbox escapes. Table-derived tokens cannot be used as Python inputs.
+- **Hidden values limit reasoning.** The model can request supported mechanical
+  operations, but cannot independently assess the meaning of an unseen value.
+
+`vaultcompute audit` checks transcripts against live vault records for exact
+cleartext matches and suspicious compute attempts. It is diagnostic evidence,
+not proof of non-disclosure; undeclared, transformed or expired values can evade
+the check. See [LIMITATIONS.md](https://github.com/ManuelPr/vaultcompute/blob/main/LIMITATIONS.md) for the detailed threat model.
+
+## Development and next steps
+
+From the repository:
+
+```bash
+uv sync --all-extras --dev
+uv run pytest
+```
+
+The CI workflow defines a test matrix for Linux, macOS and Windows on Python
+3.11–3.13. Host compatibility also needs real-host verification.
+
+The next release priorities are testing the built package in clean environments,
+verifying supported host versions and exercising real integration cases.
+Joins, group-by, HTTP transport and additional storage backends are possible
+future work, not available features.
+
+## Documentation and contributing
+
+- [Python API](https://github.com/ManuelPr/vaultcompute/blob/main/docs/api.md): supported imports and the application boundary.
+- [Integration modes](https://github.com/ManuelPr/vaultcompute/blob/main/docs/modes.md): detailed setup and tradeoffs.
+- [Host adapters](https://github.com/ManuelPr/vaultcompute/blob/main/docs/host-adapters.md): exact coverage and compatibility checks.
+- [Architecture](https://github.com/ManuelPr/vaultcompute/blob/main/docs/architecture.md): core, storage, policy and adapters.
+- [Configuration example](https://github.com/ManuelPr/vaultcompute/blob/main/vaultcompute.example.yaml): supported YAML settings.
+- [Limitations](https://github.com/ManuelPr/vaultcompute/blob/main/LIMITATIONS.md) and [changelog](https://github.com/ManuelPr/vaultcompute/blob/main/CHANGELOG.md).
+- [Release procedure](https://github.com/ManuelPr/vaultcompute/blob/main/docs/release.md), [pilot guide](https://github.com/ManuelPr/vaultcompute/blob/main/docs/pilot.md) and [next-version criteria](https://github.com/ManuelPr/vaultcompute/blob/main/docs/roadmap.md).
+- [Contributing](https://github.com/ManuelPr/vaultcompute/blob/main/CONTRIBUTING.md) and [private security reporting](https://github.com/ManuelPr/vaultcompute/blob/main/SECURITY.md).
+
+Issues and pull requests are welcome. Useful contributions include reproducible
+bugs, tests using synthetic data, schema examples and integration feedback.
+Include the package version, integration mode and host version where relevant;
+do not put real private data or vault keys in public reports.
+
+## License
+
+[MIT](https://github.com/ManuelPr/vaultcompute/blob/main/LICENSE). Copyright © 2026 Manuel Pernigotto.