vauban-verify 1.0.0__tar.gz

vauban_verify-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.tox/
+.coverage
+htmlcov/
+*.swp
+.venv/
+venv/

vauban_verify-1.0.0/LICENSE

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

vauban_verify-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: vauban-verify
+Version: 1.0.0
+Summary: Offline cryptographic verifier for Vauban Command Center proof certificates.
+Project-URL: Homepage, https://vauban.tech
+Project-URL: Repository, https://github.com/seritalien/command-center
+Author-email: Vauban <ops@vauban.tech>
+License: MIT
+License-File: LICENSE
+Keywords: merkle,poseidon,proof,starknet,verifier,zk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: starknet-py>=0.24.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# vauban-verify
+
+Offline cryptographic verifier for Vauban Command Center proof certificates.
+
+Recomputes the Poseidon Merkle root from a certificate's `decision_chain` and
+asserts it matches the certificate's anchored `merkle_root`. **No network
+calls. No trust in our infrastructure or keys.** Trust derives entirely from
+your independent on-chain read of the anchored root.
+
+Pure Python; the only runtime dependency is
+[`starknet-py`](https://github.com/software-mansion/starknet.py) (vendored
+`poseidon-py` for native felt252 arithmetic).
+
+The reference implementation lives in
+`command-center/src/proof/poseidon-hasher.ts` (sprint-521, commit `139d76e`).
+Cross-language parity is enforced by 30 deterministic test vectors checked in
+CI — any drift between TypeScript and Python fails the build.
+
+## Install
+
+```bash
+pip install vauban-verify
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/seritalien/command-center
+cd command-center/tools/vauban-verify
+pip install -e ".[test]"
+```
+
+Requires Python ≥ 3.10.
+
+## CLI usage
+
+```bash
+vauban-verify path/to/cert.json
+# → vauban-verify: OK — run_id=<…> leaves=<N> root=0x…
+echo $?  # 0 = valid, 1 = tampered/invalid, 2 = usage error
+```
+
+## Library usage
+
+```python
+from vauban_verify import (
+    compute_step_leaf_hash,
+    compute_poseidon_merkle_root,
+    verify_poseidon_merkle_proof,
+    load_certificate,
+    verify_offline,
+)
+
+# Recompute a leaf from a run_step payload
+leaf = compute_step_leaf_hash({"step_id": "s1", "type": "decision", "agent": "BUILDER"})
+
+# Recompute a Merkle root from a list of leaves
+root = compute_poseidon_merkle_root([leaf, ...])
+
+# Verify a sibling-path inclusion proof
+ok = verify_poseidon_merkle_proof(leaf, proof, root)
+
+# Verify a full certificate offline
+cert = load_certificate("cert.json")
+verify_offline(cert)  # raises VerifierError on any inconsistency
+```
+
+## Security model
+
+| Threat                                  | Defended by                                                |
+|-----------------------------------------|-------------------------------------------------------------|
+| Compromised Vauban infrastructure       | This verifier runs offline; never contacts our servers      |
+| Compromised Vauban signing keys         | The verifier asserts only Merkle consistency; trust the chain anchor, not us |
+| Hash-function preimage attacks          | Poseidon over felt252 — STARK-friendly, post-quantum sound  |
+| Drift between TS reference and verifier | 30 cross-language vectors gated in CI (regen + diff)        |
+
+The only thing that *should* be trusted is the on-chain `merkle_root`. Read it
+yourself from Starknet (e.g. via `starknet-py`'s `read_contract`) and compare
+to `cert.merkle_root` — this verifier proves the rest of the certificate is
+internally consistent with that root.
+
+## Algorithm reference
+
+* **JCS canonicalisation** (RFC 8785 subset): keys sorted recursively, `-0 → 0`,
+  arrays preserve order, `JSON.stringify`-equivalent emission.
+* **Step leaf**: `Poseidon([0x1, sha256_to_31_felt(JCS(payload)), step_marker])`.
+* **Merkle**: leaves sorted lexicographically, padded with
+  `Poseidon([0, 0])` to next power of 2, commutative pair-merge with
+  `Poseidon([min, max])`.
+
+Hex output matches `starknet.js`: lowercase, `0x`-prefixed, no leading-zero
+padding (e.g. `POSEIDON_NULL_LEAF =
+0x1fb7169b936dd880cb7ebc50e932a495a60e0084cdab94a681040cb4006e1a0`).
+
+## Publishing
+
+Releases are published to PyPI via Trusted Publishers (sigstore-signed) using
+the `.github/workflows/vauban-verify-publish.yml` workflow. Tag a release with
+`vauban-verify-vX.Y.Z` to trigger publication.
+
+## License
+
+MIT.

vauban_verify-1.0.0/README.md

@@ -0,0 +1,103 @@
+# vauban-verify
+
+Offline cryptographic verifier for Vauban Command Center proof certificates.
+
+Recomputes the Poseidon Merkle root from a certificate's `decision_chain` and
+asserts it matches the certificate's anchored `merkle_root`. **No network
+calls. No trust in our infrastructure or keys.** Trust derives entirely from
+your independent on-chain read of the anchored root.
+
+Pure Python; the only runtime dependency is
+[`starknet-py`](https://github.com/software-mansion/starknet.py) (vendored
+`poseidon-py` for native felt252 arithmetic).
+
+The reference implementation lives in
+`command-center/src/proof/poseidon-hasher.ts` (sprint-521, commit `139d76e`).
+Cross-language parity is enforced by 30 deterministic test vectors checked in
+CI — any drift between TypeScript and Python fails the build.
+
+## Install
+
+```bash
+pip install vauban-verify
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/seritalien/command-center
+cd command-center/tools/vauban-verify
+pip install -e ".[test]"
+```
+
+Requires Python ≥ 3.10.
+
+## CLI usage
+
+```bash
+vauban-verify path/to/cert.json
+# → vauban-verify: OK — run_id=<…> leaves=<N> root=0x…
+echo $?  # 0 = valid, 1 = tampered/invalid, 2 = usage error
+```
+
+## Library usage
+
+```python
+from vauban_verify import (
+    compute_step_leaf_hash,
+    compute_poseidon_merkle_root,
+    verify_poseidon_merkle_proof,
+    load_certificate,
+    verify_offline,
+)
+
+# Recompute a leaf from a run_step payload
+leaf = compute_step_leaf_hash({"step_id": "s1", "type": "decision", "agent": "BUILDER"})
+
+# Recompute a Merkle root from a list of leaves
+root = compute_poseidon_merkle_root([leaf, ...])
+
+# Verify a sibling-path inclusion proof
+ok = verify_poseidon_merkle_proof(leaf, proof, root)
+
+# Verify a full certificate offline
+cert = load_certificate("cert.json")
+verify_offline(cert)  # raises VerifierError on any inconsistency
+```
+
+## Security model
+
+| Threat                                  | Defended by                                                |
+|-----------------------------------------|-------------------------------------------------------------|
+| Compromised Vauban infrastructure       | This verifier runs offline; never contacts our servers      |
+| Compromised Vauban signing keys         | The verifier asserts only Merkle consistency; trust the chain anchor, not us |
+| Hash-function preimage attacks          | Poseidon over felt252 — STARK-friendly, post-quantum sound  |
+| Drift between TS reference and verifier | 30 cross-language vectors gated in CI (regen + diff)        |
+
+The only thing that *should* be trusted is the on-chain `merkle_root`. Read it
+yourself from Starknet (e.g. via `starknet-py`'s `read_contract`) and compare
+to `cert.merkle_root` — this verifier proves the rest of the certificate is
+internally consistent with that root.
+
+## Algorithm reference
+
+* **JCS canonicalisation** (RFC 8785 subset): keys sorted recursively, `-0 → 0`,
+  arrays preserve order, `JSON.stringify`-equivalent emission.
+* **Step leaf**: `Poseidon([0x1, sha256_to_31_felt(JCS(payload)), step_marker])`.
+* **Merkle**: leaves sorted lexicographically, padded with
+  `Poseidon([0, 0])` to next power of 2, commutative pair-merge with
+  `Poseidon([min, max])`.
+
+Hex output matches `starknet.js`: lowercase, `0x`-prefixed, no leading-zero
+padding (e.g. `POSEIDON_NULL_LEAF =
+0x1fb7169b936dd880cb7ebc50e932a495a60e0084cdab94a681040cb4006e1a0`).
+
+## Publishing
+
+Releases are published to PyPI via Trusted Publishers (sigstore-signed) using
+the `.github/workflows/vauban-verify-publish.yml` workflow. Tag a release with
+`vauban-verify-vX.Y.Z` to trigger publication.
+
+## License
+
+MIT.

vauban_verify-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "vauban-verify"
+version = "1.0.0"
+description = "Offline cryptographic verifier for Vauban Command Center proof certificates."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Vauban", email = "ops@vauban.tech" }]
+requires-python = ">=3.10"
+dependencies = ["starknet-py>=0.24.0"]
+keywords = ["starknet", "poseidon", "merkle", "zk", "proof", "verifier"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security :: Cryptography",
+]
+
+[project.urls]
+Homepage = "https://vauban.tech"
+Repository = "https://github.com/seritalien/command-center"
+
+[project.scripts]
+vauban-verify = "vauban_verify.__main__:main"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vauban_verify"]
+
+[tool.hatch.build.targets.sdist]
+include = ["vauban_verify", "tests", "README.md", "pyproject.toml"]