strix-verify 0.2.0__tar.gz

strix_verify-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+.eggs/
+*.egg
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+.env
+.env.local
+
+# uv
+.uv/
+uv.lock.broken
+
+# Tests
+.pytest_cache/
+pytest-cache-files-*/
+.coverage
+htmlcov/
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store

strix_verify-0.2.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `strix-verify` are documented here. This project
+follows semantic versioning (pre-1.0: minor bumps may add functionality or
+fix correctness issues that change verification outcomes).
+
+## [0.2.0] — 2026-05-31
+
+### Fixed — Academy-form record verification (correctness)
+
+`build_canonical_payload` previously reconstructed **only** the Console
+canonical form (string `schemaVersion`/`evidenceId`, `complianceMode`-first
+`regulatoryContext`). It therefore could **not** verify records signed in the
+Academy form — approximately 4,450 historical Academy records — and would have
+reported them as signature failures.
+
+This release adds the SE v1 **dual-form discriminator**, matching the JS
+reference verifier (`@strixgov/verifier`):
+
+- Records with `sourceApp == "academy-platform"` now serialize `schemaVersion`
+  and `evidenceId` as JSON **numbers**, with a `euAiActArticle12`-first
+  `regulatoryContext`.
+- Console records are unchanged (JSON strings, `complianceMode`-first).
+- Added the `signedPayload` reconstruction-free passthrough (v1.10.0): when a
+  record carries the original signed bytes, they are returned verbatim.
+- Canonical output now uses `ensure_ascii=False` for byte-parity with the JS
+  reference on non-ASCII fields.
+
+The Console path is byte-for-byte unchanged (the prior golden-vector test
+remains the canary and still passes).
+
+### Added — cross-language conformance
+
+This verifier is now pinned to the JS reference against a shared,
+language-neutral fixture
+(`packages/strixgov-verifier/test/fixtures/se-v1-conformance-vectors.json`).
+Both implementations read the same fixture and must agree byte-for-byte; a CI
+lane (`SE v1 Cross-Language Conformance`) enforces this on Python 3.10–3.12 and
+Node 20–24. See `tests/test_conformance_vectors.py`.
+
+### Notes
+
+- No new dependencies. No API changes to `verify_evidence` / `verify_evidence_record`.
+- The golden vectors were not modified; the implementation was corrected to
+  match them.
+
+## [0.1.0]
+
+Initial release. Independent SE v1 verification (Ed25519 + SHA-256), JWKS
+resolution, two-layer verification model, EU AI Act compliance-flag derivation.
+Console canonical form only.

strix_verify-0.2.0/PARITY-BACKLOG.md

@@ -0,0 +1,248 @@
+# Python verifier — feature-parity backlog
+
+Source of truth: `packages/strixgov-verifier/src/index.mjs` (JS verifier).
+This doc tracks where `strix-verify` (Python) lags the JS verifier and
+which gaps are worth closing.
+
+> **Read first:** the trust math (Ed25519 + SHA-256 + canonical-JSON)
+> in Python is byte-identical to JS for the surfaces Python implements.
+> The gap is feature breadth, not correctness. Mirror-parity tests on
+> the JS side lock the canonical payload builders; any port has to
+> preserve those bytes exactly.
+
+---
+
+## Scope
+
+`strix-verify` (Python) is the **auditor-facing subset** of the JS
+verifier — not full parity. Canonical statement of the decision,
+deciding principle, and reversal triggers lives in
+[`SCOPE.md`](./SCOPE.md). Read that first if the question is "should
+this be ported at all?"; read this doc for "what's the state of each
+capability?"
+
+The one-line summary: in scope = anything an external AI Act auditor
+would independently verify against a public proof URL. Out of scope =
+runtime-integration primitives (tool gateway, wire envelope,
+snapshots).
+
+---
+
+## Current parity (2026-05-18)
+
+| Capability | JS export | Python | Status |
+|---|---|---|---|
+| Signed Evidence v1 verify | `verify` (`index.mjs:411`) | `verify_evidence` | Complete |
+| SE v1 canonical payload | `buildCanonicalPayload` (`:275`) | `build_canonical_payload` | Complete |
+| Ed25519 signature | `verifySignature` (`:383`) | `verify_signature` | Complete |
+| SHA-256 hash | `verifyHash` (`:395`) | `verify_hash` | Complete |
+| Evidence fetch | `fetchEvidence` (`:200`) | `fetch_evidence` | Complete (defaults aligned) |
+| JWKS resolve | `fetchPublicKey` (`:158`) | `resolve_key` | Complete |
+| EU AI Act compliance flags | inline | `derive_compliance_flags` | Complete |
+| Redacted-kid resolution | `resolveJwkFromKid` (`:70`) | not implemented | **Gap — P1** |
+| Approval artifact verify | `verifyApprovalArtifact` (`:597`) | not implemented | **Gap — P1** |
+| Approval quorum verify | `verifyApprovalQuorum` (`:688`) | not implemented | **Gap — P2** |
+| Actor Attestation v1 | `verifyAttestation` (`:840`) | not implemented | **Gap — P1 (post AA-1 flip)** |
+| AA-1 composite status | `computeAttestationCompositeStatus` (`:977`) | not implemented | **Gap — P1 (post AA-1 flip)** |
+| AA-1 + evidence combined | `verifyWithAttestations` (`:1036`) | not implemented | **Gap — P1 (post AA-1 flip)** |
+| Tool-gateway receipt verify | `verifyReceipt` (`:1193`) | not implemented | **Gap — P2** |
+| Receipt-chain verify | `verifyReceiptChain` (`:1264`) | not implemented | **Gap — P2** |
+| Snapshot verify | `verifySnapshot` (`:1353`) | not implemented | **Gap — P3** |
+| Tool-gateway proof aggregator | `verifyToolGatewayProof` (`:1434`) | not implemented | **Gap — P3** |
+| Visual SVG verify | `verifyVisual` (`:1623`) | not implemented | **Gap — P3** |
+| Connected-mode wire envelope | `verifyConnectedWireEnvelope` (`:1510`) | not implemented | **Non-goal** |
+| CLI binary | `bin/strix-verify` | not implemented | **Gap — P1** |
+
+---
+
+## Backlog
+
+### P1 — auditor-facing, ship before next launch milestone
+
+#### CLI binary
+
+Mirror `npx @strixgov/verifier@latest 5686` as
+`strix-verify 5686`. Single entry point in `pyproject.toml`
+(`[project.scripts] strix-verify = "strix_verify.cli:main"`).
+Behavior: same exit codes as the JS CLI, same human-readable
+output, plus `--json` for machine consumption. No new
+deployment-specific defaults — inherits `DEFAULT_PROOF_BASE`.
+
+Reference: JS CLI lives at `packages/strixgov-verifier/bin/strix-verify.mjs`.
+
+#### Redacted-kid resolution
+
+JS `resolveJwkFromKid` (`index.mjs:70`) handles the redacted kid
+format `strix-***-2026-04` by suffix-matching the `YYYY-MM`
+segment against the full JWKS. Python's `resolve_key` today
+does exact-string match only.
+
+Without this, Python cannot verify any record where
+`signingKeyId` came through `redactSigningKeyId()` — which is
+the entire public-approval-artifact surface (Gap 5 mitigation).
+SE v1 evidence records expose the unredacted kid inside the
+signed `fields.*` block, so basic evidence verification still
+works; this gap shows up the moment Python tries an approval
+artifact.
+
+Mirror test: JS pins this with `redaction-promotion.test.mjs`.
+Port: add suffix-match fallback to `resolve_key`, then port the
+same locked redacted-kid fixture into `tests/`.
+
+#### Approval artifact verifier
+
+Phase 3 ships `SalesApprovalArtifact` with a locked 9-field
+canonical payload. Public REST surface exists today
+(`GET /api/public/approval-artifact/:id`). Auditors will want
+to verify approval authority independently — same trust story
+as evidence records, different schema.
+
+Implementation cost: low. Port `buildApprovalCanonicalPayload`
+(`index.mjs:511`) byte-for-byte (field order is contract — see
+CLAUDE.md "Files that require extra care"), reuse the existing
+SE v1 signature/hash machinery.
+
+Mirror test: golden vectors from
+`apps/strix-console/tests/sales-pipeline/approval-artifact-parity.test.ts`.
+
+#### Actor Attestation v1 verifier
+
+Currently dormant in production
+(`STRIX_ACTOR_ATTESTATION_V1=false`). When the flag flips, the
+public `/api/public/verify` response starts carrying an
+`actorClass` block; Python users will see records they cannot
+fully verify.
+
+Implementation cost: medium. Port:
+
+- `buildActorAttestationPayload` (`index.mjs:805`) — sibling
+  artifact joined to SE v1 by `evidenceId`
+- `verifyAttestation` (`:840`) — 8 rules, 11 reason codes
+- `computeAttestationCompositeStatus` (`:977`) — composes
+  evidence verification result with attestation outcome
+- `verifyWithAttestations` (`:1036`) — convenience wrapper
+
+Contract: `docs/architecture/actor-attestation-v1.md`
+contractVersion 1.0.0 (frozen). Reason codes are public API —
+do not rename when porting.
+
+Trigger: AA-1 flag flip. Track against
+`scripts/aa1-postflip-validate.mjs` running GREEN in production.
+
+### P2 — system-integrator-facing, port if Python demand surfaces
+
+#### Approval quorum verifier
+
+`verifyApprovalQuorum` (`index.mjs:688`) verifies the full set
+of approval artifacts for a decision plus quorum rules
+(N-of-M). Auditor demand is real but narrower than single
+approval verification — most external review walks one
+artifact at a time. Port after single-artifact lands.
+
+#### Tool-gateway receipt verifier (v1 + v2)
+
+`buildReceiptCanonicalPayload` (`index.mjs:1157`) supports
+schemaVersion v1 (11 fields) and v2 (14 fields with
+`policyVersion` / `tenantId` / `environment`).
+`verifyReceipt` (`:1193`) consumes both, dispatching on
+`schemaVersion`.
+
+Auditor demand: low today. Tool-gateway receipts live
+client-side in `@strixgov/tool-gateway`; the verification path
+that matters most is the hosted approval/evidence side. Defer
+unless a Python-native tool-gateway consumer materializes.
+
+Mirror test if porting:
+`packages/tool-gateway/tests/verifier-parity.test.mjs` — both
+v1 and v2 receipt canonical bytes must match exactly.
+
+#### Receipt-chain verifier
+
+`verifyReceiptChain` (`index.mjs:1264`). Walks a chain of
+tool-gateway receipts and verifies the sequencing invariant.
+Same demand profile as single-receipt verify. Defer.
+
+### P3 — unlikely to be needed in Python
+
+#### Snapshot verifier
+
+`verifySnapshot` (`index.mjs:1353`) +
+`buildSnapshotCanonicalPayload` (`:1322`) — tool-gateway chain
+snapshots (v0.2 rotation). Internal to tool-gateway operation.
+External auditors do not consume these directly.
+
+#### Tool-gateway proof aggregator
+
+`verifyToolGatewayProof` (`index.mjs:1434`). Composite verifier
+across receipts + snapshots. Same reasoning as snapshot.
+
+#### Visual SVG verifier
+
+`extractVisualMetadata` (`index.mjs:1581`) + `verifyVisual`
+(`:1623`) parse the `<strix:*>` metadata block embedded in
+signed visual artifacts. The artifact format is web-facing (a
+shareable signed badge). A Python port would only matter if
+someone wanted to verify the badge from a backend job. CI gate
+`scripts/lint-visual-artifacts-signed.mjs` already locks the
+producer side; consumer-side parity in Python is theoretical.
+
+---
+
+## Non-goals
+
+These will not be ported even if asked.
+
+| Capability | Why not |
+|---|---|
+| `verifyConnectedWireEnvelope` (`index.mjs:1510`) | The wire envelope is a runtime integration concern (replay defense between tool-gateway and hosted kernel). Auditors verify the resulting evidence record, not the wire that carried it. |
+| `SUPPORTED_WIRE_VERSIONS` (`:1483`) | Same reasoning. |
+| Anything in `packages/tool-gateway/` | Not part of the verifier surface. Tool-gateway has its own JS-only release cadence and the parity tests live there. |
+
+---
+
+## Mirror discipline (if you port anything)
+
+Any canonical payload builder you port from JS MUST stay
+byte-identical to the JS source. The audit story collapses if
+JS and Python disagree on a single byte for the same record.
+
+Rules:
+
+1. **Copy the field order exactly.** Re-ordering a canonical
+   payload field invalidates every previously-signed artifact.
+   The locked field orders are documented in CLAUDE.md under
+   "Files that require extra care."
+2. **Port the locked goldens.** Every JS builder has a frozen
+   test vector (`tests/golden-vectors/` in solo-builder-core,
+   or inline in the parity test files). Reuse those bytes as
+   Python test fixtures — do not regenerate.
+3. **Public API name-stability.** `BindingReason` codes,
+   AA-1 reason codes, approval status enums — these are
+   public contract. Port them with the same names and the
+   same values.
+4. **One canonicalizer.** If you find yourself
+   re-implementing JSON serialization, stop. Use a single
+   canonical-JSON helper (`payload.py` today) and route every
+   new artifact type through it.
+5. **No deployment-specific defaults.** The package must not
+   carry any single customer's URL. Hosts default to the
+   canonical Strix Platform host only (`www.strixgov.com`),
+   which mirrors the JS verifier exactly.
+
+---
+
+## References
+
+- JS verifier: `packages/strixgov-verifier/src/index.mjs`
+- JS launch incident analysis:
+  `docs/postmortems/2026-05-15-launch-day-9-bug-stack.md`
+- Load-bearing rules for signed-evidence paths:
+  `docs/CONSTRAINTS-FOR-AGENTS.md`
+- Signed Evidence v1 spec:
+  `docs/gates/SIGNED-EVIDENCE-V1-AGENT-PROMPT.md`
+- Actor Attestation v1 contract:
+  `docs/architecture/actor-attestation-v1.md`
+- Approval artifact canonical schema:
+  `apps/strix-console/src/lib/sales-pipeline/approval-artifact.ts`
+- Tool-gateway parity test (if ever porting receipts):
+  `packages/tool-gateway/tests/verifier-parity.test.mjs`

strix_verify-0.2.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: strix-verify
+Version: 0.2.0
+Summary: Independent verification of Strix governance evidence records. Ed25519 + SHA-256 only. No Strix tooling or account required. Public source at github.com/strixgov/strix.
+Project-URL: Homepage, https://strixgov.com
+Project-URL: Repository, https://github.com/strixgov/strix
+Project-URL: Documentation, https://strixgov.com/docs/verify
+Author: Strix Platform Team
+License: MIT
+Keywords: ai-safety,ed25519,evidence,governance,proof,strix,verification
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# strix-verify
+
+Independent verification of Strix governance evidence records.
+
+No Strix tooling, SDK, or account required. Uses only standard cryptographic
+primitives (Ed25519, SHA-256) via the Python `cryptography` library.
+
+**strix-verify is offline-safe.** Save the JWKS once, ship it with the
+evidence, verify on an air-gapped machine. No callbacks. No telemetry.
+No Strix server required at runtime.
+
+**Proof Readiness Level 4.5** — Cryptographically Signed + Externally Verifiable
+
+**Public source:** [github.com/strixgov/strix](https://github.com/strixgov/strix)
+**PyPI:** [pypi.org/project/strix-verify](https://pypi.org/project/strix-verify)
+
+---
+
+## Installation
+
+```bash
+pip install strix-verify
+```
+
+Or from source:
+
+```bash
+cd python/strix-verify
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+```python
+from strix_verify import verify_evidence
+
+result = verify_evidence(
+    evidence_id=123,
+    proof_base="https://strix.example.com",  # your Strix deployment
+    jwks_base="https://strixgov.com",        # canonical JWKS surface
+)
+
+print(result.signature_valid)                          # SignatureStatus.VERIFIED
+print(result.hash_valid)                               # True
+print(result.compliance.article12_tamper_resistant)    # True
+print(result.compliance.article14_human_oversight)     # True
+print(result.compliance.article28_provider_obligations) # True
+```
+
+`proof_base` is required — there is no default. The verifier is neutral
+across Strix deployments and never carries a hardcoded host URL.
+
+### Async
+
+```python
+import asyncio
+from strix_verify import fetch_evidence_async, verify_evidence_record
+
+async def main():
+    record = await fetch_evidence_async(123, proof_base="https://strix.example.com")
+    result = verify_evidence_record(record, jwks_base="https://strixgov.com")
+    return result
+
+asyncio.run(main())
+```
+
+---
+
+## Verification Flow
+
+1. **Fetch** — Retrieve evidence record from the Strix proof API
+2. **Reconstruct** — Build canonical 13-field payload (locked field order)
+3. **Fetch key** — Resolve Ed25519 public key from JWKS endpoint
+4. **Verify signature** — Ed25519 signature over canonical payload
+5. **Verify hash** — SHA-256 hash of canonical payload
+6. **Derive compliance flags** — EU AI Act flags derived from outcomes (never asserted)
+7. **Return** — `VerificationResult` with all outcomes
+
+---
+
+## Two-Layer Verification Model
+
+### Layer 1 — Cryptographic Validity (`signature_valid`)
+
+> "Was this record produced by the holder of the Strix signing key?"
+
+| Status | Meaning |
+|--------|---------|
+| `VERIFIED` | Valid Ed25519 signature from a known key |
+| `LEGACY_UNSIGNED` | Pre-signing record (migration before 0039) |
+| `UNVERIFIABLE_KEY` | Signing key ID not found in JWKS or extra_keys |
+| `COMPLIANCE_VIOLATION` | Signature present but invalid |
+| `ERROR` | Network or unexpected failure |
+
+### Layer 2 — Deployment Context (`environment_match`, `tenant_match`)
+
+> "Is this record appropriate for this deployment context?"
+
+Optional checks against stored record fields. Per **SE-14**, verification reads
+`environment` and `tenantId` from the stored evidence record — never from
+environment variables. This prevents false failures when a production record is
+verified in a development context.
+
+```python
+result = verify_evidence(
+    evidence_id=123,
+    expected_environment="production",   # checks stored record field
+    expected_tenant_id="tenant-abc",     # checks stored record field
+)
+print(result.environment_match)  # True/False/None
+print(result.tenant_match)       # True/False/None
+```
+
+---
+
+## Verifying a Local Record
+
+If you already have the evidence record dict (from a database, file, etc.):
+
+```python
+from strix_verify import verify_evidence_record
+
+result = verify_evidence_record(
+    record,
+    jwks_base="https://strixgov.com",
+)
+```
+
+---
+
+## Verifying Offline (Air-Gapped)
+
+For audit environments that cannot reach the internet, pre-fetch the JWKS
+once, save it next to the evidence, and verify with no network access at
+runtime:
+
+```python
+import json
+from strix_verify import verify_evidence_record
+
+with open("evidence-2026-04-19.json") as f:
+    record = json.load(f)
+
+with open("jwks-snapshot-2026-04.json") as f:
+    extra_keys = json.load(f)["keys"]
+
+result = verify_evidence_record(
+    record,
+    extra_keys=extra_keys,
+    jwks_base="https://unused.invalid",  # never reached when key is in extra_keys
+)
+```
+
+When the signing key is already present in `extra_keys`, `jwks_base` is
+never contacted. The verifier resolves the key from the pre-fetched JWK
+list and does the full cryptographic check locally.
+
+---
+
+## Key Rotation Support
+
+Historical signing keys can be provided to verify older records after key rotation:
+
+```python
+import json, os
+
+extra_keys = json.loads(os.environ.get("STRIX_SIGNING_JWKS_EXTRA", "[]"))
+
+result = verify_evidence(
+    evidence_id=123,
+    extra_keys=extra_keys,
+)
+```
+
+Key ID format: `strix-{env}-{YYYY-MM}` (e.g., `strix-prod-2026-04`). EU AI Act
+compliance requires a minimum 2-year key retention period.
+
+---
+
+## EU AI Act Compliance Flags
+
+Compliance flags are **derived** from verification outcomes — never read from stored
+fields (invariant CI-5). Altering the `regulatoryContext` block in a signed record
+invalidates the Ed25519 signature.
+
+| Flag | Derived From |
+|------|-------------|
+| `article12_tamper_resistant` | `hash_valid AND chain_valid AND signature_valid == VERIFIED` |
+| `article14_human_oversight` | `signature_present` (actor fields cryptographically bound) |
+| `article28_provider_obligations` | `signature_valid == VERIFIED` (evidence from known key) |
+
+---
+
+## Canonical Payload Schema
+
+The 13-field locked-order payload that is signed and hashed:
+
+```
+schemaVersion (always "1")
+evidenceId
+evidenceHash
+proofChainHash
+capabilityId
+action
+actorId
+actorRole
+createdAt
+signingKeyId
+environment
+tenantId
+regulatoryContext { complianceMode, euAiActArticle12, euAiActArticle14, euAiActArticle28 }
+```
+
+**Warning:** Reordering these fields invalidates all existing signatures. This schema
+is locked and versioned. See `tests/test_payload.py::test_golden_vector` for the
+canonical serialization canary.
+
+---
+
+## JWKS Endpoint
+
+Public keys are served at:
+
+```
+GET https://strixgov.com/.well-known/strix-jwks.json
+GET https://strixgov.com/.well-known/strix-jwks.json?kid=strix-prod-2026-04
+```
+
+The endpoint follows RFC 7517. Each key is an OKP/Ed25519 JWK with a `kid` in
+`strix-{env}-{YYYY-MM}` format.
+
+---
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=strix_verify --cov-report=term-missing
+
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/
+```
+
+---
+
+## Architecture Notes
+
+- **No Strix SDK dependency** — pure Python + `cryptography` + `httpx`
+- **Ed25519 SPKI DER construction** matches the TypeScript implementation exactly:
+  12-byte header `302a300506032b6570032100` + 32 raw key bytes
+- **Never raises** on bad signatures — `verify_signature()` returns `False`
+- **Sync and async** HTTP clients available for all network operations
+
+---
+
+## License
+
+MIT — see LICENSE.