vera-anchor-verifier 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. vera_anchor_verifier-0.1.0/.editorconfig +17 -0
  2. vera_anchor_verifier-0.1.0/.gitattributes +10 -0
  3. vera_anchor_verifier-0.1.0/.github/workflows/ci.yml +56 -0
  4. vera_anchor_verifier-0.1.0/.gitignore +59 -0
  5. vera_anchor_verifier-0.1.0/CHANGELOG.md +24 -0
  6. vera_anchor_verifier-0.1.0/CONTRIBUTING.md +307 -0
  7. vera_anchor_verifier-0.1.0/PKG-INFO +662 -0
  8. vera_anchor_verifier-0.1.0/README.md +639 -0
  9. vera_anchor_verifier-0.1.0/SECURITY.md +205 -0
  10. vera_anchor_verifier-0.1.0/docs/authenticated-verification.md +211 -0
  11. vera_anchor_verifier-0.1.0/docs/cli.md +589 -0
  12. vera_anchor_verifier-0.1.0/docs/conformance.md +329 -0
  13. vera_anchor_verifier-0.1.0/docs/threat-model.md +239 -0
  14. vera_anchor_verifier-0.1.0/docs/verification-semantics.md +202 -0
  15. vera_anchor_verifier-0.1.0/examples/README.md +157 -0
  16. vera_anchor_verifier-0.1.0/examples/authorized_dataset_policy.py +121 -0
  17. vera_anchor_verifier-0.1.0/examples/authorized_ingest_policy.py +117 -0
  18. vera_anchor_verifier-0.1.0/examples/dataset_offline.py +64 -0
  19. vera_anchor_verifier-0.1.0/examples/dataset_policy.py +78 -0
  20. vera_anchor_verifier-0.1.0/examples/ingest_offline.py +55 -0
  21. vera_anchor_verifier-0.1.0/examples/ingest_policy.py +95 -0
  22. vera_anchor_verifier-0.1.0/pyproject.toml +77 -0
  23. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/__init__.py +617 -0
  24. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/auth/__init__.py +17 -0
  25. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/auth/auth_provider_v1.py +201 -0
  26. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/cli/__init__.py +5 -0
  27. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/cli/__main__.py +5 -0
  28. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/cli/command_v1.py +884 -0
  29. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/contracts.py +121 -0
  30. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/crypto/__init__.py +27 -0
  31. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/crypto/sha3.py +49 -0
  32. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/crypto/stream_sha3.py +98 -0
  33. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/hf/__init__.py +39 -0
  34. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/hf/hash_contract_v1.py +463 -0
  35. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/merkle/__init__.py +17 -0
  36. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/merkle/membership.py +170 -0
  37. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/policy/__init__.py +49 -0
  38. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/policy/contract_v1.py +74 -0
  39. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/policy/evaluate_v1.py +1102 -0
  40. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/__init__.py +1 -0
  41. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/dataset/__init__.py +27 -0
  42. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/dataset/registry_event_v1.py +259 -0
  43. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/dataset/source_v1.py +244 -0
  44. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/dataset/v1.py +812 -0
  45. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/execution/__init__.py +39 -0
  46. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/execution/contract_v1.py +776 -0
  47. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/execution/independent_standards_v1.py +935 -0
  48. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/execution/reason_codes_v1.py +116 -0
  49. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/execution/recomputation_v1.py +255 -0
  50. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/execution/rules_v1.py +1044 -0
  51. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/execution/standards_plan_v1.py +174 -0
  52. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/execution/verification_v1.py +570 -0
  53. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/ingest/__init__.py +31 -0
  54. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/ingest/source_v1.py +321 -0
  55. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/ingest/v1.py +869 -0
  56. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/profiles/source_v1_helpers.py +412 -0
  57. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/py.typed +0 -0
  58. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/reports/__init__.py +39 -0
  59. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/reports/core_v1.py +1186 -0
  60. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/reports/portable_v1.py +779 -0
  61. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/reports/validation_v1.py +1485 -0
  62. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/__init__.py +141 -0
  63. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/authorized_observation_v1.py +257 -0
  64. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/core_authorized_v1.py +685 -0
  65. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/execution_mirror_v1.py +444 -0
  66. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/explorer_execution_v1.py +253 -0
  67. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/explorer_public_v1.py +590 -0
  68. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/explorer_publication_v1.py +462 -0
  69. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/explorer_transport_v1.py +397 -0
  70. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/hcs11_mirror_v1.py +727 -0
  71. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/hcs13_mirror_v1.py +216 -0
  72. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/hcs1_mirror_v1.py +662 -0
  73. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/hcs26_mirror_v1.py +690 -0
  74. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/hcs26_registry_mirror_v1.py +401 -0
  75. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/hcs2_mirror_v1.py +499 -0
  76. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/resolvers/hedera_mirror_v1.py +824 -0
  77. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/__init__.py +1 -0
  78. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/hcs/__init__.py +127 -0
  79. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/hcs/hcs11_v1.py +564 -0
  80. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/hcs/hcs13_v1.py +259 -0
  81. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/hcs/hcs14_v1.py +273 -0
  82. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/hcs/hcs1_v1.py +271 -0
  83. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/hcs/hcs26_v1.py +747 -0
  84. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/hcs/hcs2_v1.py +219 -0
  85. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/standards/hcs/json_canonical_v1.py +306 -0
  86. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/__init__.py +43 -0
  87. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/authorized_dataset_v1.py +351 -0
  88. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/authorized_hcs_v1.py +165 -0
  89. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/authorized_ingest_v1.py +547 -0
  90. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/compare_v1.py +475 -0
  91. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/execution_plan_v1.py +540 -0
  92. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/execution_public_v1.py +150 -0
  93. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/message_observation_v1.py +297 -0
  94. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/triangulation/public_v1.py +495 -0
  95. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/verification/__init__.py +11 -0
  96. vera_anchor_verifier-0.1.0/src/vera_anchor_verifier/verification/source_intent_v1.py +752 -0
  97. vera_anchor_verifier-0.1.0/tests/fixtures/conformance/dataset_v1.json +82 -0
  98. vera_anchor_verifier-0.1.0/tests/fixtures/conformance/hf_v1.json +95 -0
  99. vera_anchor_verifier-0.1.0/tests/fixtures/conformance/js_v02_golden_v1.json +57 -0
  100. vera_anchor_verifier-0.1.0/tests/fixtures/test_js_v02_golden_parity.py +266 -0
  101. vera_anchor_verifier-0.1.0/tests/integration/fixtures/conformance/dataset/mainnet/2026-10-30/bundle.json +38 -0
  102. vera_anchor_verifier-0.1.0/tests/integration/fixtures/conformance/dataset/mainnet/2026-10-30/receipt.json +414 -0
  103. vera_anchor_verifier-0.1.0/tests/integration/fixtures/conformance/dataset/mainnet/2026-10-30/source/vera-execution-evidence-verification-8f5c8410-0f62-5e2b-a251-1c3dfbc914c3.json +979 -0
  104. vera_anchor_verifier-0.1.0/tests/integration/fixtures/conformance/ingest/mainnet/2026-10-31/bundle.json +42 -0
  105. vera_anchor_verifier-0.1.0/tests/integration/fixtures/conformance/ingest/mainnet/2026-10-31/receipt.json +112 -0
  106. vera_anchor_verifier-0.1.0/tests/integration/fixtures/conformance/ingest/mainnet/2026-10-31/source/vera_anchor_ingest_example.txt +1 -0
  107. vera_anchor_verifier-0.1.0/tests/integration/fixtures/conformance/sage/mainnet/2026-10-21/result.json +1 -0
  108. vera_anchor_verifier-0.1.0/tests/integration/fixtures/conformance/sage/mainnet/2026-10-21/standards.json +1 -0
  109. vera_anchor_verifier-0.1.0/tests/integration/test_authorized_dataset_ingest_workflow_v1.py +689 -0
  110. vera_anchor_verifier-0.1.0/tests/integration/test_dataset_mainnet_live_conformance.py +316 -0
  111. vera_anchor_verifier-0.1.0/tests/integration/test_execution_workflow_v1.py +577 -0
  112. vera_anchor_verifier-0.1.0/tests/integration/test_independent_standards_workflow_v1.py +635 -0
  113. vera_anchor_verifier-0.1.0/tests/integration/test_ingest_mainnet_live_conformance.py +398 -0
  114. vera_anchor_verifier-0.1.0/tests/integration/test_public_dataset_ingest_workflow_v1.py +678 -0
  115. vera_anchor_verifier-0.1.0/tests/integration/test_sage_mainnet_live_conformance.py +313 -0
  116. vera_anchor_verifier-0.1.0/tests/unit/auth/test_auth_provider_v1.py +291 -0
  117. vera_anchor_verifier-0.1.0/tests/unit/hf/test_hash_contract_v1.py +255 -0
  118. vera_anchor_verifier-0.1.0/tests/unit/policy/test_policy_v1.py +984 -0
  119. vera_anchor_verifier-0.1.0/tests/unit/profiles/dataset/test_dataset_source_v1.py +136 -0
  120. vera_anchor_verifier-0.1.0/tests/unit/profiles/dataset/test_dataset_v1.py +203 -0
  121. vera_anchor_verifier-0.1.0/tests/unit/profiles/execution/test_contract_v1.py +532 -0
  122. vera_anchor_verifier-0.1.0/tests/unit/profiles/execution/test_independent_standards_v1.py +534 -0
  123. vera_anchor_verifier-0.1.0/tests/unit/profiles/execution/test_recomputation_v1.py +298 -0
  124. vera_anchor_verifier-0.1.0/tests/unit/profiles/execution/test_rules_v1.py +1185 -0
  125. vera_anchor_verifier-0.1.0/tests/unit/profiles/execution/test_standards_plan_v1.py +372 -0
  126. vera_anchor_verifier-0.1.0/tests/unit/profiles/execution/test_verification_v1.py +598 -0
  127. vera_anchor_verifier-0.1.0/tests/unit/profiles/ingest/test_ingest_source_v1.py +292 -0
  128. vera_anchor_verifier-0.1.0/tests/unit/profiles/ingest/test_ingest_v1.py +302 -0
  129. vera_anchor_verifier-0.1.0/tests/unit/profiles/test_source_v1_helpers.py +106 -0
  130. vera_anchor_verifier-0.1.0/tests/unit/reports/test_core_v1.py +508 -0
  131. vera_anchor_verifier-0.1.0/tests/unit/reports/test_portable_v1.py +407 -0
  132. vera_anchor_verifier-0.1.0/tests/unit/reports/test_validation_v1.py +593 -0
  133. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_authorized_observation_v1.py +428 -0
  134. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_core_authorized_v1.py +719 -0
  135. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_execution_mirror_v1.py +328 -0
  136. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_explorer_execution_v1.py +416 -0
  137. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_explorer_public_v1.py +546 -0
  138. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_explorer_publication_v1.py +602 -0
  139. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_explorer_transport_v1.py +442 -0
  140. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_hcs11_mirror.py +651 -0
  141. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_hcs13_mirror_v1.py +395 -0
  142. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_hcs1_mirror_v1.py +582 -0
  143. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_hcs26_mirror_v1.py +651 -0
  144. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_hcs26_registry_mirror_v1.py +751 -0
  145. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_hcs2_mirror_v1.py +522 -0
  146. vera_anchor_verifier-0.1.0/tests/unit/resolvers/test_hedera_mirror_v1.py +703 -0
  147. vera_anchor_verifier-0.1.0/tests/unit/standards/test_hcs11_v1.py +524 -0
  148. vera_anchor_verifier-0.1.0/tests/unit/standards/test_hcs13_v1.py +379 -0
  149. vera_anchor_verifier-0.1.0/tests/unit/standards/test_hcs14_v1.py +272 -0
  150. vera_anchor_verifier-0.1.0/tests/unit/standards/test_hcs1_v1.py +530 -0
  151. vera_anchor_verifier-0.1.0/tests/unit/standards/test_hcs26_v1.py +562 -0
  152. vera_anchor_verifier-0.1.0/tests/unit/standards/test_hcs2_v1.py +334 -0
  153. vera_anchor_verifier-0.1.0/tests/unit/standards/test_json_canonical_v1.py +154 -0
  154. vera_anchor_verifier-0.1.0/tests/unit/test_cli.py +283 -0
  155. vera_anchor_verifier-0.1.0/tests/unit/test_merkle_membership.py +248 -0
  156. vera_anchor_verifier-0.1.0/tests/unit/test_sha3.py +52 -0
  157. vera_anchor_verifier-0.1.0/tests/unit/test_stream_sha3.py +98 -0
  158. vera_anchor_verifier-0.1.0/tests/unit/triangulation/test_authorized_dataset_v1.py +564 -0
  159. vera_anchor_verifier-0.1.0/tests/unit/triangulation/test_authorized_hcs_v1.py +354 -0
  160. vera_anchor_verifier-0.1.0/tests/unit/triangulation/test_authorized_ingest_v1.py +734 -0
  161. vera_anchor_verifier-0.1.0/tests/unit/triangulation/test_compare_v1.py +440 -0
  162. vera_anchor_verifier-0.1.0/tests/unit/triangulation/test_execution_plan_v1.py +416 -0
  163. vera_anchor_verifier-0.1.0/tests/unit/triangulation/test_execution_public_v1.py +346 -0
  164. vera_anchor_verifier-0.1.0/tests/unit/triangulation/test_message_observation_v1.py +265 -0
  165. vera_anchor_verifier-0.1.0/tests/unit/triangulation/test_public_v1.py +755 -0
  166. vera_anchor_verifier-0.1.0/tests/unit/verification/test_source_intent_v1.py +447 -0
@@ -0,0 +1,17 @@
1
+ root = true
2
+
3
+ [*]
4
+ charset = utf-8
5
+ end_of_line = lf
6
+ insert_final_newline = true
7
+ trim_trailing_whitespace = true
8
+ indent_style = space
9
+
10
+ [*.py]
11
+ indent_size = 4
12
+
13
+ [*.{json,yml,yaml,toml}]
14
+ indent_size = 2
15
+
16
+ [*.md]
17
+ trim_trailing_whitespace = false
@@ -0,0 +1,10 @@
1
+ * text=auto
2
+
3
+ *.py text eol=lf
4
+ *.toml text eol=lf
5
+ *.json text eol=lf
6
+ *.yaml text eol=lf
7
+ *.yml text eol=lf
8
+ *.md text eol=lf
9
+ *.txt text eol=lf
10
+ *.sh text eol=lf
@@ -0,0 +1,56 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+ pull_request:
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ test:
14
+ name: Python ${{ matrix.python-version }}
15
+ runs-on: ubuntu-latest
16
+
17
+ strategy:
18
+ fail-fast: false
19
+ matrix:
20
+ python-version:
21
+ - "3.12"
22
+ - "3.13"
23
+ - "3.14"
24
+ - "3.15"
25
+
26
+ steps:
27
+ - name: Checkout
28
+ uses: actions/checkout@v7
29
+ with:
30
+ persist-credentials: false
31
+
32
+ - name: Set up Python
33
+ uses: actions/setup-python@v7
34
+ with:
35
+ python-version: ${{ matrix.python-version }}
36
+ cache: pip
37
+
38
+ - name: Install package and development dependencies
39
+ run: |
40
+ python -m pip install --upgrade pip
41
+ python -m pip install -e ".[dev]"
42
+
43
+ - name: Lint
44
+ run: python -m ruff check .
45
+
46
+ - name: Type check
47
+ run: python -m mypy src
48
+
49
+ - name: Test
50
+ run: python -m pytest
51
+
52
+ - name: Build distributions
53
+ run: python -m build
54
+
55
+ - name: Import smoke test
56
+ run: python -c "import vera_anchor_verifier"
@@ -0,0 +1,59 @@
1
+ # Python bytecode / caches
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # Build / packaging
7
+ build/
8
+ dist/
9
+ *.egg-info/
10
+ .eggs/
11
+ *.egg
12
+ *.whl
13
+
14
+ # Test / coverage
15
+ .pytest_cache/
16
+ .coverage
17
+ .coverage.*
18
+ coverage.xml
19
+ htmlcov/
20
+ .tox/
21
+ .nox/
22
+
23
+ # Type / lint caches
24
+ .mypy_cache/
25
+ .ruff_cache/
26
+ .pytype/
27
+ .pyright/
28
+
29
+ # Virtual environments
30
+ .venv/
31
+ venv/
32
+ env/
33
+ ENV/
34
+
35
+ # Environment / local configuration
36
+ .env
37
+ .env.*
38
+ !.env.example
39
+
40
+ # Credentials / private material
41
+ *.pem
42
+ *.key
43
+ *.p12
44
+ *.pfx
45
+
46
+ # Logs / dumps
47
+ *.log
48
+ *.dump
49
+
50
+ # IDE-local state
51
+ .idea/
52
+ .vscode/
53
+
54
+ # Jupyter
55
+ .ipynb_checkpoints/
56
+
57
+ # OS metadata
58
+ .DS_Store
59
+ Thumbs.db
@@ -0,0 +1,24 @@
1
+ # Changelog
2
+
3
+ All notable changes to the Vera Anchor Verifier SDK for Python are documented here.
4
+
5
+ The project follows semantic versioning while the public API remains pre-1.0.
6
+
7
+ ## [0.1.0] - 2026-11-XX
8
+
9
+ Initial public release of the Vera Anchor Verifier SDK for Python.
10
+
11
+ ### Added
12
+
13
+ - Python implementation targeting verification parity with `@veraanchor/verifier` JavaScript v0.2.0.
14
+ - Deterministic Dataset and Ingest verification.
15
+ - Public Dataset and Ingest triangulation through Vera Anchor Explorer and Hedera Mirror observations.
16
+ - Authorized Dataset and Ingest verification workflows.
17
+ - SAGE execution verification and public execution triangulation.
18
+ - Independent execution standards verification.
19
+ - Verification support for HCS-1, HCS-2, HCS-11, HCS-13, HCS-14, and HCS-26.
20
+ - Canonical portable verification reports and deterministic report digests.
21
+ - Relying-party verification policies with `allow`, `review`, and `deny` decisions.
22
+ - `vera-anchor` command-line interface for verification, report validation, and policy assessment.
23
+ - Cross-language JavaScript/Python golden-vector conformance.
24
+ - Unit, integration, and live Hedera mainnet conformance coverage.
@@ -0,0 +1,307 @@
1
+ # Contributing
2
+
3
+ Contributions to the Vera Anchor Verifier SDK for Python are welcome.
4
+
5
+ The verifier is a security-sensitive, deterministic verification library. Changes should preserve the existing trust model, public contracts, cross-language parity, and fail-closed behavior.
6
+
7
+ Python v0.1 targets verification parity with `@veraanchor/verifier` JavaScript v0.2.0.
8
+
9
+ ## Development requirements
10
+
11
+ - Python 3.12+
12
+
13
+ Create and activate a virtual environment, then install the project and required development tooling.
14
+
15
+ The repository uses:
16
+
17
+ - Ruff for linting and formatting.
18
+ - mypy in strict mode.
19
+ - pytest for unit, integration, and conformance tests.
20
+ - Hatchling for package builds.
21
+
22
+ ## Development principles
23
+
24
+ Changes should preserve the following properties:
25
+
26
+ - Deterministic verification for equivalent deterministic inputs.
27
+ - Explicit trust boundaries.
28
+ - Fail-closed behavior.
29
+ - Read-only verification.
30
+ - Independently supplied verification intent.
31
+ - Independently supplied relying-party policy.
32
+ - Explicit Hedera network selection.
33
+ - Explicit resolver selection.
34
+ - Bounded processing of untrusted inputs.
35
+ - Stable canonicalization and digest behavior.
36
+ - JavaScript/Python parity where the behavior is shared.
37
+
38
+ Do not silently broaden what a successful verification result claims.
39
+
40
+ In particular:
41
+
42
+ ```text
43
+ local consistency
44
+ != producer authenticity
45
+ != independent Hedera corroboration
46
+ != policy authorization
47
+ ```
48
+
49
+ These properties must remain distinct.
50
+
51
+ ## JavaScript parity
52
+
53
+ The JavaScript verifier is the reference implementation for the Python parity target where behavior is shared.
54
+
55
+ Changes to shared verification behavior should be reviewed against the corresponding JavaScript implementation and existing cross-language golden vectors.
56
+
57
+ Language-specific implementation details do not need to be identical.
58
+
59
+ Public verification semantics should remain aligned unless a deliberate versioned divergence is explicitly approved.
60
+
61
+ Do not introduce Python-only behavior that changes:
62
+
63
+ - Verification meaning.
64
+ - Commitment construction.
65
+ - Canonicalization.
66
+ - Reason codes.
67
+ - Policy decisions.
68
+ - Report semantics.
69
+ - Resolver trust boundaries.
70
+ - Historical record selection.
71
+ - Network handling.
72
+
73
+ ## Public contract changes
74
+
75
+ Treat changes to the following as compatibility-sensitive:
76
+
77
+ - Public schemas.
78
+ - Public dataclasses and TypedDicts.
79
+ - Public function signatures.
80
+ - Canonicalization.
81
+ - Commitment algorithms.
82
+ - Digest construction.
83
+ - Verification findings.
84
+ - Reason codes.
85
+ - Report schemas.
86
+ - Report digest behavior.
87
+ - Policy schemas.
88
+ - Policy evaluation.
89
+ - Resolver configuration.
90
+ - CLI commands and exit semantics.
91
+
92
+ If a change affects deterministic output or public verification meaning, it must not be treated as an incidental refactor.
93
+
94
+ ## Security-sensitive changes
95
+
96
+ Extra review is required for changes involving:
97
+
98
+ - Filesystem paths.
99
+ - Source-root containment.
100
+ - Symbolic links.
101
+ - Network endpoints.
102
+ - Redirects.
103
+ - Authentication.
104
+ - Credential handling.
105
+ - Resolver behavior.
106
+ - Input bounds.
107
+ - Parsing.
108
+ - Canonicalization.
109
+ - Digest verification.
110
+ - Report validation.
111
+ - Policy authorization.
112
+ - Cross-network behavior.
113
+ - Error sanitization.
114
+ - Decrypted evidence.
115
+
116
+ Security-sensitive code should remain explicit and easy to audit.
117
+
118
+ Avoid clever abstractions that make trust boundaries harder to understand.
119
+
120
+ ## Dependencies
121
+
122
+ The verifier intentionally minimizes required runtime dependencies.
123
+
124
+ Before adding a runtime dependency, consider whether the same behavior can be implemented safely using the Python standard library or existing verifier primitives.
125
+
126
+ A new dependency should have a clear justification and should be evaluated for:
127
+
128
+ - Security.
129
+ - Maintenance.
130
+ - Determinism.
131
+ - Transitive dependencies.
132
+ - Platform support.
133
+ - Supply-chain risk.
134
+
135
+ Do not add dependencies solely for convenience.
136
+
137
+ ## Code style
138
+
139
+ Keep code compact, explicit, and professional.
140
+
141
+ Prefer:
142
+
143
+ - Small deterministic helpers.
144
+ - Clear type boundaries.
145
+ - Explicit validation.
146
+ - Immutable data where practical.
147
+ - Narrow public interfaces.
148
+ - Existing shared verifier primitives.
149
+ - Standard-library functionality where appropriate.
150
+
151
+ Avoid:
152
+
153
+ - Unnecessary abstraction layers.
154
+ - Large formatting-only rewrites.
155
+ - Duplicated verifier logic.
156
+ - Broad exception swallowing.
157
+ - Hidden network fallback.
158
+ - Implicit trust decisions.
159
+ - Unnecessary runtime dependencies.
160
+ - Large line-count increases without corresponding functionality.
161
+
162
+ Refactors should preserve behavior unless behavioral change is the explicit purpose of the contribution.
163
+
164
+ ## Type safety
165
+
166
+ The project uses strict mypy checking.
167
+
168
+ New code should pass without suppressing legitimate typing problems.
169
+
170
+ Avoid `# type: ignore` unless there is a specific, documented reason that cannot reasonably be represented in the type system.
171
+
172
+ Do not use casts merely to hide an invalid state. Prefer validating and narrowing untrusted input before construction of typed verifier objects.
173
+
174
+ ## Testing
175
+
176
+ Changes should include the smallest set of tests necessary to establish the intended behavior.
177
+
178
+ Depending on the component, this may include:
179
+
180
+ - Unit tests.
181
+ - Integration tests.
182
+ - Negative or fail-closed cases.
183
+ - Cross-language golden-vector coverage.
184
+ - Resolver boundary tests.
185
+ - Live conformance coverage.
186
+
187
+ Tests should verify behavior rather than implementation details where practical.
188
+
189
+ Security-sensitive changes should include relevant negative cases.
190
+
191
+ A successful test must not depend on elevated local privileges when equivalent behavior can be tested deterministically.
192
+
193
+ ## Cross-language golden vectors
194
+
195
+ Golden vectors protect deterministic parity between the Python and JavaScript implementations.
196
+
197
+ Do not update a golden vector merely to make a failing implementation pass.
198
+
199
+ A golden-vector change requires understanding why the deterministic result changed and whether the corresponding public contract is intentionally changing.
200
+
201
+ Unexpected golden-vector drift should be treated as a compatibility defect until proven otherwise.
202
+
203
+ ## Live conformance
204
+
205
+ Live tests validate selected workflows against public services and Hedera network observations.
206
+
207
+ They are not hermetic tests and should not replace deterministic unit or integration coverage.
208
+
209
+ Run live conformance explicitly:
210
+
211
+ ```sh
212
+ VA_LIVE_TESTS=1 python -m pytest -m live -v
213
+ ```
214
+
215
+ PowerShell:
216
+
217
+ ```powershell
218
+ $env:VA_LIVE_TESTS="1"
219
+ python -m pytest -m live -v
220
+ Remove-Item Env:VA_LIVE_TESTS
221
+ ```
222
+
223
+ External service failure must not be converted into successful verification.
224
+
225
+ ## Required checks
226
+
227
+ Before submitting a change, run:
228
+
229
+ ```sh
230
+ python -m ruff check .
231
+ python -m ruff format --check .
232
+ python -m mypy src
233
+ python -m pytest
234
+ python -m build
235
+ ```
236
+
237
+ All checks should pass.
238
+
239
+ Changes affecting live resolver or public-network behavior should also run the relevant live conformance tests when practical.
240
+
241
+ ## Packaging changes
242
+
243
+ Changes to packaging, entry points, or build metadata should be tested from built artifacts rather than only from the repository source tree.
244
+
245
+ For release-affecting changes, verify:
246
+
247
+ - Wheel installation.
248
+ - Source distribution installation.
249
+ - Package metadata.
250
+ - Installed CLI behavior.
251
+ - Distribution contents.
252
+ - Absence of secrets or unintended files.
253
+
254
+ The source tree must not mask packaging defects during consumer smoke testing.
255
+
256
+ ## CLI changes
257
+
258
+ The CLI is an adapter over the verifier APIs, not a separate verification implementation.
259
+
260
+ CLI changes should reuse the existing verifier workflows.
261
+
262
+ Preserve:
263
+
264
+ - Offline-by-default operation.
265
+ - Explicit public mode.
266
+ - Explicit resolver configuration.
267
+ - Source-root containment.
268
+ - Bounded file handling.
269
+ - Sanitized error output.
270
+ - Deterministic exit semantics.
271
+ - Exclusive report creation.
272
+
273
+ Do not duplicate verifier algorithms inside the CLI.
274
+
275
+ ## Documentation
276
+
277
+ Documentation must describe behavior that actually exists in the current release.
278
+
279
+ Do not document speculative APIs, commands, files, or guarantees.
280
+
281
+ Documentation changes affecting verification semantics should be checked against both the Python implementation and the corresponding JavaScript behavior where parity applies.
282
+
283
+ Markdown files should remain readable as plain source and should not rely on repository-specific rendering tricks.
284
+
285
+ ## Commit scope
286
+
287
+ Prefer focused changes.
288
+
289
+ A contribution should not combine unrelated:
290
+
291
+ - Feature work.
292
+ - Refactoring.
293
+ - Formatting changes.
294
+ - Dependency changes.
295
+ - Documentation restructuring.
296
+
297
+ Keeping changes narrow makes deterministic and security review substantially easier.
298
+
299
+ ## Reporting security issues
300
+
301
+ Do not report exploitable vulnerabilities through a public issue.
302
+
303
+ See `SECURITY.md` for responsible disclosure guidance.
304
+
305
+ ## License
306
+
307
+ By contributing to this repository, you agree that your contributions will be licensed under the project's MIT License.