strix-verify 0.2.0__py3-none-any.whl

strix_verify/__init__.py

@@ -0,0 +1,206 @@
+"""
+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.
+
+Quick start:
+    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
+
+Verification flow:
+    1. Fetch evidence record from proof API
+    2. Reconstruct canonical 13-field payload
+    3. Fetch Ed25519 public key from JWKS endpoint
+    4. Verify signature (Ed25519)
+    5. Verify SHA-256 hash
+    6. Derive EU AI Act compliance flags (never asserted)
+    7. Return VerificationResult
+
+Two-layer model:
+    Layer 1 — Cryptographic Validity (signatureValid):
+        "Was this record produced by the holder of the Strix signing key?"
+    Layer 2 — Deployment Context (environmentMatch, tenantMatch):
+        "Is this record appropriate for this deployment context?"
+        SE-14: environment/tenantId read from stored record fields, never process.env.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import EvidenceFetchError, fetch_evidence, fetch_evidence_async
+from .compliance import derive_compliance_flags
+from .hashing import verify_hash
+from .jwks import DEFAULT_JWKS_BASE, JWKSFetchError, KeyNotFoundError, resolve_key
+from .models import CanonicalPayload, SignatureStatus, VerificationResult
+from .payload import build_canonical_payload
+from .signature import verify_signature
+
+__version__ = "0.2.0"
+__all__ = [
+    "verify_evidence",
+    "verify_evidence_record",
+    "VerificationResult",
+    "SignatureStatus",
+    "CanonicalPayload",
+    "build_canonical_payload",
+    "verify_signature",
+    "verify_hash",
+    "resolve_key",
+    "fetch_evidence",
+    "fetch_evidence_async",
+    "DEFAULT_JWKS_BASE",
+]
+
+
+def verify_evidence(
+    evidence_id: str | int,
+    *,
+    proof_base: str,
+    jwks_base: str = DEFAULT_JWKS_BASE,
+    extra_keys: list[dict[str, Any]] | None = None,
+    expected_environment: str | None = None,
+    expected_tenant_id: str | None = None,
+) -> VerificationResult:
+    """
+    Fetch and verify a Strix evidence record end-to-end.
+
+    This is the primary entry point. It fetches the record, verifies the
+    signature and hash, derives compliance flags, and returns a VerificationResult.
+
+    Args:
+        evidence_id: The evidence record ID to verify.
+        proof_base: Base URL of the Strix proof API for your deployment
+            (e.g. "https://strix.example.com"). Required — no default,
+            so the package never carries a hardcoded customer URL.
+        jwks_base: Base URL of the JWKS endpoint.
+        extra_keys: Optional historical JWK dicts for key rotation support.
+        expected_environment: If provided, checks Layer 2 environment match.
+            (SE-14: read from stored record field, not from process env)
+        expected_tenant_id: If provided, checks Layer 2 tenant match.
+
+    Returns:
+        VerificationResult with all verification outcomes.
+    """
+    result = VerificationResult(evidence_id=evidence_id)
+
+    try:
+        record = fetch_evidence(evidence_id, proof_base=proof_base)
+        result.record = record
+    except EvidenceFetchError as e:
+        result.error = str(e)
+        result.signature_valid = SignatureStatus.ERROR
+        return result
+
+    return verify_evidence_record(
+        record,
+        jwks_base=jwks_base,
+        extra_keys=extra_keys,
+        expected_environment=expected_environment,
+        expected_tenant_id=expected_tenant_id,
+    )
+
+
+def verify_evidence_record(
+    record: dict[str, Any],
+    *,
+    jwks_base: str = DEFAULT_JWKS_BASE,
+    extra_keys: list[dict[str, Any]] | None = None,
+    expected_environment: str | None = None,
+    expected_tenant_id: str | None = None,
+) -> VerificationResult:
+    """
+    Verify an already-fetched evidence record dict.
+
+    Use this when you have the record locally (e.g. from a file or DB).
+    Skips the HTTP fetch step.
+
+    Args:
+        record: Raw evidence record dict.
+        jwks_base: Base URL of the JWKS endpoint.
+        extra_keys: Optional historical JWK dicts.
+        expected_environment: Optional Layer 2 environment check.
+        expected_tenant_id: Optional Layer 2 tenant check.
+
+    Returns:
+        VerificationResult
+    """
+    evidence_id = record.get("evidenceId") or record.get("id") or "unknown"
+    result = VerificationResult(evidence_id=evidence_id, record=record)
+
+    # Step 1 — Check signature presence
+    signature = record.get("signature")
+    signing_key_id = record.get("signingKeyId")
+    result.signature_present = bool(signature)
+    result.signing_key_id = signing_key_id
+
+    if not signature or not signing_key_id:
+        # Legacy unsigned record
+        result.signature_valid = SignatureStatus.LEGACY_UNSIGNED
+        # Still verify hash if possible
+        canonical = build_canonical_payload(record)
+        canonical_json = canonical.to_canonical_json()
+        if record.get("evidenceHash"):
+            result.hash_valid = verify_hash(canonical_json, record["evidenceHash"])
+        result.compliance = derive_compliance_flags(
+            result.signature_valid, result.hash_valid,
+            result.chain_valid, result.signature_present,
+        )
+        return result
+
+    # Step 2 — Fetch public key
+    try:
+        public_key = resolve_key(signing_key_id, jwks_base=jwks_base, extra_keys=extra_keys)
+    except KeyNotFoundError as e:
+        result.signature_valid = SignatureStatus.UNVERIFIABLE_KEY
+        result.error = str(e)
+        result.compliance = derive_compliance_flags(
+            result.signature_valid, result.hash_valid,
+            result.chain_valid, result.signature_present,
+        )
+        return result
+    except JWKSFetchError as e:
+        result.signature_valid = SignatureStatus.ERROR
+        result.error = str(e)
+        return result
+
+    # Step 3 — Reconstruct canonical payload
+    canonical = build_canonical_payload(record)
+    canonical_json = canonical.to_canonical_json()
+
+    # Step 4 — Verify signature
+    sig_ok = verify_signature(canonical_json, signature, public_key)
+    result.signature_valid = SignatureStatus.VERIFIED if sig_ok else SignatureStatus.COMPLIANCE_VIOLATION
+
+    # Step 5 — Verify hash
+    if record.get("evidenceHash"):
+        result.hash_valid = verify_hash(canonical_json, record["evidenceHash"])
+
+    # Step 6 — Layer 2: Deployment context checks (SE-14: from stored fields only)
+    if expected_environment is not None:
+        stored_env = record.get("environment", "")
+        result.environment_match = stored_env == expected_environment
+
+    if expected_tenant_id is not None:
+        stored_tenant = record.get("tenantId", "")
+        result.tenant_match = stored_tenant == expected_tenant_id
+
+    # Step 7 — Derive compliance flags (CI-5: derived, never asserted)
+    result.compliance = derive_compliance_flags(
+        result.signature_valid,
+        result.hash_valid,
+        result.chain_valid,
+        result.signature_present,
+    )
+
+    return result

strix_verify/client.py

@@ -0,0 +1,81 @@
+"""
+HTTP client for fetching evidence records from a Strix proof API.
+
+The proof API host is deployment-specific. Callers must pass `proof_base`
+explicitly — there is no default. This keeps the verifier neutral across
+Strix deployments and prevents the package from carrying any single
+customer's URL in its public metadata.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+_TIMEOUT = httpx.Timeout(15.0)
+
+
+class EvidenceFetchError(Exception):
+    """Raised when the evidence record cannot be fetched."""
+    pass
+
+
+def fetch_evidence(
+    evidence_id: str | int,
+    proof_base: str,
+) -> dict[str, Any]:
+    """
+    Fetch an evidence record from a Strix proof API.
+
+    Args:
+        evidence_id: Numeric or string evidence ID.
+        proof_base: Base URL of the proof API for your Strix deployment
+            (e.g. "https://strix.example.com"). Required — no default.
+
+    Returns:
+        Raw evidence record dict.
+
+    Raises:
+        EvidenceFetchError: If the request fails or returns a non-200 status.
+    """
+    if not proof_base:
+        raise EvidenceFetchError("proof_base is required (no default)")
+    url = f"{proof_base.rstrip('/')}/api/proof/{evidence_id}"
+    with httpx.Client(timeout=_TIMEOUT) as client:
+        response = client.get(url, headers={"Accept": "application/json"})
+
+    if response.status_code != 200:
+        raise EvidenceFetchError(
+            f"Proof API fetch failed: HTTP {response.status_code} from {url}"
+        )
+
+    data = response.json()
+    # API may wrap the record in a { proof: {...} } envelope
+    return data.get("proof") or data
+
+
+async def fetch_evidence_async(
+    evidence_id: str | int,
+    proof_base: str,
+) -> dict[str, Any]:
+    """
+    Async version of fetch_evidence. Uses httpx.AsyncClient.
+
+    Args:
+        evidence_id: Numeric or string evidence ID.
+        proof_base: Base URL of the proof API. Required — no default.
+    """
+    if not proof_base:
+        raise EvidenceFetchError("proof_base is required (no default)")
+    url = f"{proof_base.rstrip('/')}/api/proof/{evidence_id}"
+    async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+        response = await client.get(url, headers={"Accept": "application/json"})
+
+    if response.status_code != 200:
+        raise EvidenceFetchError(
+            f"Proof API fetch failed: HTTP {response.status_code} from {url}"
+        )
+
+    data = response.json()
+    return data.get("proof") or data

strix_verify/compliance.py

@@ -0,0 +1,56 @@
+"""
+EU AI Act compliance flag derivation.
+
+CI-5 invariant: Compliance flags are DERIVED from verification outcomes only.
+They are never asserted directly, never read from stored fields.
+
+Article mapping:
+  Article 12 — Technical documentation and tamper-resistance
+  Article 14 — Human oversight
+  Article 28 — Provider obligations (high-risk AI systems)
+"""
+
+from __future__ import annotations
+
+from .models import ComplianceFlags, SignatureStatus
+
+
+def derive_compliance_flags(
+    signature_valid: SignatureStatus,
+    hash_valid: bool | None,
+    chain_valid: bool | None,
+    signature_present: bool,
+) -> ComplianceFlags:
+    """
+    Derive EU AI Act compliance flags from verification outcomes.
+
+    This function implements CI-5: flags are computed, never stored or asserted.
+
+    Args:
+        signature_valid: Layer 1 cryptographic validity status.
+        hash_valid: Whether the SHA-256 evidence hash matches. None = unchecked
+            (no evidenceHash on record). Treated as False for Article 12.
+        chain_valid: Whether the proof chain link is valid (None if unchecked).
+        signature_present: Whether a signature field exists on the record.
+
+    Returns:
+        ComplianceFlags with derived boolean values.
+    """
+    is_verified = signature_valid == SignatureStatus.VERIFIED
+    chain_ok = chain_valid is True or chain_valid is None  # None = unchecked, not failed
+    # hash_valid=None means unchecked (no stored hash), treated as False for Article 12
+    hash_ok = hash_valid is True
+
+    return ComplianceFlags(
+        # Article 12: Evidence is tamper-resistant
+        # Requires: hash intact AND chain intact AND cryptographically signed by known key
+        article12_tamper_resistant=hash_ok and chain_ok and is_verified,
+
+        # Article 14: Human oversight is cryptographically bound
+        # Requires: actor fields are present in a signed record (signature present)
+        article14_human_oversight=signature_present,
+
+        # Article 28: Provider obligations met
+        # Requires: record produced by holder of a known Strix signing key
+        article28_provider_obligations=is_verified,
+    )

strix_verify/hashing.py

@@ -0,0 +1,84 @@
+"""
+SHA-256 hash verification for Strix evidence records.
+
+Ports the verifyHash() function from packages/strixgov-verifier/src/index.mjs.
+
+Hash design (non-circular):
+    evidenceHash = sha256(canonical_json_where_evidenceHash="")
+
+    The evidenceHash field is computed over the canonical payload with the
+    evidenceHash field itself set to the empty string. This prevents circular
+    dependency (a hash field that contains a hash of itself) while still
+    cryptographically binding all other 12 fields into the stored hash.
+
+    Signing flow:
+        1. Build canonical payload with evidenceHash=""
+        2. compute_evidence_hash(canonical_json) → H
+        3. Update evidenceHash=H on record
+        4. Rebuild canonical payload with evidenceHash=H
+        5. Sign the rebuilt payload (evidenceHash=H is now signature-protected)
+
+    Verification flow:
+        1. Build canonical payload with stored evidenceHash=H
+        2. Verify signature over canonical payload (covers evidenceHash=H)
+        3. verify_hash(canonical_json, H):
+             strips evidenceHash → canonical_json_with_empty
+             sha256(canonical_json_with_empty) → H'
+             H == H' → True
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+
+def _normalize_for_hashing(canonical_payload: str) -> str:
+    """
+    Strip the evidenceHash field value (set to "") before computing the hash.
+
+    This breaks the circular dependency: the stored evidenceHash is the hash
+    of the canonical payload with evidenceHash="", not of itself.
+
+    Field order is preserved because Python 3.7+ dicts maintain insertion order
+    and json.loads/json.dumps round-trips are order-preserving.
+    """
+    data = json.loads(canonical_payload)
+    data["evidenceHash"] = ""
+    return json.dumps(data, separators=(",", ":"), ensure_ascii=False)
+
+
+def compute_evidence_hash(canonical_payload: str) -> str:
+    """
+    Compute the SHA-256 hash of the canonical payload (with evidenceHash normalized to "").
+
+    Args:
+        canonical_payload: The deterministic JSON string from CanonicalPayload.to_canonical_json()
+            The evidenceHash field value is stripped before hashing to prevent circular dependency.
+
+    Returns:
+        Lowercase hex-encoded SHA-256 digest.
+    """
+    normalized = _normalize_for_hashing(canonical_payload)
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+def verify_hash(canonical_payload: str, expected_hash: str) -> bool:
+    """
+    Verify that the canonical payload's SHA-256 hash matches the stored evidence hash.
+
+    The evidenceHash field in the canonical payload is normalized to "" before
+    hashing, matching the signing-time computation.
+
+    Args:
+        canonical_payload: The deterministic JSON string (evidenceHash field is stripped
+            before comparison).
+        expected_hash: The evidenceHash field from the evidence record (hex string).
+
+    Returns:
+        True if hashes match, False otherwise.
+    """
+    if not expected_hash:
+        return False
+    computed = compute_evidence_hash(canonical_payload)
+    return computed == expected_hash.lower()

strix_verify/jwks.py

@@ -0,0 +1,154 @@
+"""
+JWKS public key resolution for Strix evidence verification.
+
+Ports the fetchPublicKey() function from packages/strixgov-verifier/src/index.mjs.
+Supports key rotation via historical key lookup.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from .signature import decode_jwk_to_public_key
+
+# Default JWKS endpoint — canonical Strix Platform host. Mirrors the JS
+# verifier's DEFAULT_JWKS_BASE (packages/strixgov-verifier/src/index.mjs).
+# Both /api/proof/* and /.well-known/strix-jwks.json are served here.
+# Historical records signed when the platform was on velarisgroup.app remain
+# verifiable: velarisgroup.app/.well-known/strix-jwks.json 302-redirects to
+# www.strixgov.com during the 90-day cutover window (see
+# docs/DOMAIN_MIGRATION_RUNBOOK.md).
+DEFAULT_JWKS_BASE = "https://www.strixgov.com"
+
+# Request timeout
+_TIMEOUT = httpx.Timeout(10.0)
+
+
+class KeyNotFoundError(Exception):
+    """Raised when the signing key cannot be found in the JWKS."""
+    pass
+
+
+class JWKSFetchError(Exception):
+    """Raised when the JWKS endpoint cannot be reached or returns an error."""
+    pass
+
+
+def fetch_jwks(jwks_url: str) -> list[dict[str, Any]]:
+    """
+    Fetch the raw JWKS from the given URL.
+
+    Args:
+        jwks_url: Full URL to the JWKS endpoint (e.g. https://.../.well-known/strix-jwks.json)
+
+    Returns:
+        List of JWK dicts.
+
+    Raises:
+        JWKSFetchError: If the request fails or returns a non-200 status.
+    """
+    with httpx.Client(timeout=_TIMEOUT) as client:
+        response = client.get(jwks_url)
+    if response.status_code != 200:
+        raise JWKSFetchError(f"JWKS fetch failed: HTTP {response.status_code} from {jwks_url}")
+    data = response.json()
+    return data.get("keys", [])
+
+
+def resolve_key(
+    kid: str,
+    jwks_base: str = DEFAULT_JWKS_BASE,
+    extra_keys: list[dict[str, Any]] | None = None,
+) -> Ed25519PublicKey:
+    """
+    Resolve an Ed25519PublicKey for the given key ID.
+
+    Resolution order:
+    1. Fetch from the live JWKS endpoint (with ?kid= filter for efficiency)
+    2. Fall back to extra_keys (historical keys from STRIX_SIGNING_JWKS_EXTRA)
+
+    JWKS key rotation: Keys are retained for a minimum of 2 years for
+    EU AI Act compliance. Historical keys are provided via extra_keys.
+
+    Args:
+        kid: Key ID (format: strix-{env}-{YYYY-MM})
+        jwks_base: Base URL of the JWKS server.
+        extra_keys: Optional list of historical JWK dicts for key rotation support.
+
+    Returns:
+        Ed25519PublicKey for the given kid.
+
+    Raises:
+        KeyNotFoundError: If the key is not found in JWKS or extra_keys.
+        JWKSFetchError: If the JWKS endpoint cannot be reached.
+    """
+    url = f"{jwks_base.rstrip('/')}/.well-known/strix-jwks.json?kid={kid}"
+    try:
+        keys = fetch_jwks(url)
+    except JWKSFetchError:
+        if not extra_keys:
+            # No fallback available — propagate so caller gets the real error
+            raise
+        # Live fetch failed but we have historical keys to try
+        keys = []
+
+    # Find the key in the live JWKS
+    matching = [k for k in keys if k.get("kid") == kid]
+
+    # Fall back to extra_keys (historical rotation keys)
+    if not matching and extra_keys:
+        matching = [k for k in extra_keys if k.get("kid") == kid]
+
+    if not matching:
+        raise KeyNotFoundError(
+            f"Signing key '{kid}' not found in JWKS at {jwks_base} "
+            f"or in {len(extra_keys or [])} historical key(s)."
+        )
+
+    return decode_jwk_to_public_key(matching[0])
+
+
+async def resolve_key_async(
+    kid: str,
+    jwks_base: str = DEFAULT_JWKS_BASE,
+    extra_keys: list[dict[str, Any]] | None = None,
+) -> Ed25519PublicKey:
+    """
+    Async version of resolve_key. Uses httpx.AsyncClient.
+
+    Args:
+        kid: Key ID
+        jwks_base: Base URL of the JWKS server.
+        extra_keys: Optional historical JWK dicts.
+
+    Returns:
+        Ed25519PublicKey
+
+    Raises:
+        KeyNotFoundError, JWKSFetchError
+    """
+    url = f"{jwks_base.rstrip('/')}/.well-known/strix-jwks.json?kid={kid}"
+    keys: list[dict[str, Any]] = []
+
+    async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+        try:
+            response = await client.get(url)
+            if response.status_code == 200:
+                keys = response.json().get("keys", [])
+        except httpx.HTTPError:
+            pass  # Fall through to extra_keys
+
+    matching = [k for k in keys if k.get("kid") == kid]
+    if not matching and extra_keys:
+        matching = [k for k in extra_keys if k.get("kid") == kid]
+
+    if not matching:
+        raise KeyNotFoundError(
+            f"Signing key '{kid}' not found in JWKS at {jwks_base} "
+            f"or in {len(extra_keys or [])} historical key(s)."
+        )
+
+    return decode_jwk_to_public_key(matching[0])

strix_verify/models.py

@@ -0,0 +1,241 @@
+"""
+Canonical data models for Strix evidence verification.
+
+These models are the Python equivalent of the TypeScript types in
+packages/strixgov-verifier and solo-builder-core/src/types.ts.
+Schema version is locked — do not reorder fields.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+def _coerce_to_number(value: Any, fallback: int) -> int | float:
+    """
+    Mirror of coerceSchemaVersionToNumber / coerceEvidenceIdToNumber in
+    packages/strixgov-verifier/src/index.mjs. Used only for the Academy
+    dual-form, where schemaVersion + evidenceId are emitted as JSON numbers.
+    Integer-valued inputs serialize without a decimal point (1, not 1.0),
+    matching JS Number()/JSON.stringify.
+    """
+    if isinstance(value, bool):
+        return fallback
+    if isinstance(value, (int, float)):
+        return value
+    if isinstance(value, str) and value:
+        try:
+            f = float(value)
+        except ValueError:
+            return fallback
+        return int(f) if f.is_integer() else f
+    return fallback
+
+
+# ── Verification States ────────────────────────────────────────────────────────
+
+class SignatureStatus(str, Enum):
+    """Layer 1 — Cryptographic validity of the evidence record's signature."""
+
+    VERIFIED = "VERIFIED"
+    """Signature is valid, payload is intact, key is known."""
+
+    INVALID_SIGNATURE = "INVALID_SIGNATURE"
+    """Record tampered, payload mismatch, or wrong key used."""
+
+    UNVERIFIABLE_KEY = "UNVERIFIABLE_KEY"
+    """Key ID not found in JWKS or rotation history."""
+
+    UNSIGNED = "UNSIGNED"
+    """No signature present on this record."""
+
+    LEGACY_UNSIGNED = "LEGACY_UNSIGNED"
+    """Record predates signing migration (0039) — hash/chain may still be valid."""
+
+    COMPLIANCE_VIOLATION = "COMPLIANCE_VIOLATION"
+    """Record has a signature field but it fails cryptographic verification."""
+
+    ERROR = "ERROR"
+    """Verification could not complete due to a network or parsing error."""
+
+
+# ── Regulatory Context ─────────────────────────────────────────────────────────
+
+class RegulatoryContext(BaseModel):
+    """EU AI Act compliance flags — always derived, never asserted."""
+
+    compliance_mode: str = Field(default="", alias="complianceMode")
+    eu_ai_act_article12: bool = Field(default=False, alias="euAiActArticle12")
+    eu_ai_act_article14: bool = Field(default=False, alias="euAiActArticle14")
+    eu_ai_act_article28: bool = Field(default=False, alias="euAiActArticle28")
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Canonical Payload ──────────────────────────────────────────────────────────
+
+class CanonicalPayload(BaseModel):
+    """
+    The locked 13-field signed payload schema (Signed Evidence v1).
+
+    Field order is frozen — reordering invalidates all existing signatures.
+    See: docs/gates/SIGNED-EVIDENCE-V1-AGENT-PROMPT.md
+    """
+
+    schema_version: str = Field(alias="schemaVersion")
+    evidence_id: str = Field(alias="evidenceId")
+    evidence_hash: str = Field(alias="evidenceHash")
+    proof_chain_hash: str = Field(alias="proofChainHash")
+    capability_id: str = Field(alias="capabilityId")
+    action: str
+    actor_id: str = Field(alias="actorId")
+    actor_role: str = Field(alias="actorRole")
+    created_at: str = Field(alias="createdAt")
+    signing_key_id: str = Field(alias="signingKeyId")
+    environment: str
+    tenant_id: str = Field(alias="tenantId")
+    regulatory_context: RegulatoryContext = Field(alias="regulatoryContext")
+
+    # Dual-form discriminator (v1.3) — mirrors buildCanonicalPayload in
+    # packages/strixgov-verifier/src/index.mjs. Academy
+    # (sourceApp == "academy-platform") signs schemaVersion + evidenceId as
+    # JSON NUMBERS with a euAiActArticle12-first regulatoryContext; Console
+    # signers emit them as JSON STRINGS with a complianceMode-first context.
+    # The two byte-shapes verify against DIFFERENT signatures. Collapsing this
+    # silently breaks every record signed in the dropped form.
+    is_academy_form: bool = False
+
+    # v1.10.0 reconstruction-free path: if the API returns the original signed
+    # bytes (signedPayload), they ARE the canonical — return verbatim.
+    signed_payload: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+    def to_canonical_json(self) -> str:
+        """
+        Serialize to the canonical JSON string used for signing.
+        Field order is frozen. Honors the Academy/Console dual-form
+        discriminator and the signedPayload passthrough so this verifier
+        reproduces the JS reference byte-for-byte (see the conformance
+        fixture at packages/strixgov-verifier/test/fixtures).
+        """
+        import json
+
+        # Reconstruction-free path: signed bytes are the canonical bytes.
+        if self.signed_payload is not None:
+            return self.signed_payload
+
+        if self.is_academy_form:
+            schema_version: int | float | str = _coerce_to_number(self.schema_version, 1)
+            evidence_id: int | float | str = _coerce_to_number(self.evidence_id, 0)
+            regulatory_context = {
+                "euAiActArticle12": self.regulatory_context.eu_ai_act_article12,
+                "euAiActArticle14": self.regulatory_context.eu_ai_act_article14,
+                "euAiActArticle28": self.regulatory_context.eu_ai_act_article28,
+                "complianceMode": self.regulatory_context.compliance_mode,
+            }
+        else:
+            schema_version = self.schema_version
+            evidence_id = self.evidence_id
+            regulatory_context = {
+                "complianceMode": self.regulatory_context.compliance_mode,
+                "euAiActArticle12": self.regulatory_context.eu_ai_act_article12,
+                "euAiActArticle14": self.regulatory_context.eu_ai_act_article14,
+                "euAiActArticle28": self.regulatory_context.eu_ai_act_article28,
+            }
+
+        ordered = {
+            "schemaVersion": schema_version,
+            "evidenceId": evidence_id,
+            "evidenceHash": self.evidence_hash,
+            "proofChainHash": self.proof_chain_hash,
+            "capabilityId": self.capability_id,
+            "action": self.action,
+            "actorId": self.actor_id,
+            "actorRole": self.actor_role,
+            "createdAt": self.created_at,
+            "signingKeyId": self.signing_key_id,
+            "environment": self.environment,
+            "tenantId": self.tenant_id,
+            "regulatoryContext": regulatory_context,
+        }
+        # ensure_ascii=False: JS JSON.stringify emits raw UTF-8, not \\u escapes.
+        # Byte-parity on non-ASCII fields depends on this.
+        return json.dumps(ordered, separators=(",", ":"), ensure_ascii=False)
+
+
+# ── Compliance Flags (derived, never asserted) ─────────────────────────────────
+
+class ComplianceFlags(BaseModel):
+    """
+    EU AI Act compliance flags derived from verification outcomes.
+
+    CI-5 invariant: These are DERIVED from signatureValid/hashValid/chainValid.
+    They must never be asserted directly or read from stored fields.
+    """
+
+    article12_tamper_resistant: bool = False
+    """hash_valid AND chain_valid AND signature_valid == VERIFIED"""
+
+    article14_human_oversight: bool = False
+    """signature_present (actor fields cryptographically bound to record)"""
+
+    article28_provider_obligations: bool = False
+    """signature_valid (record produced by holder of known Strix signing key)"""
+
+
+# ── Verification Result ────────────────────────────────────────────────────────
+
+class VerificationResult(BaseModel):
+    """
+    The complete result of verifying a Strix evidence record.
+
+    Layer 1 — Cryptographic Validity: signatureValid
+    Layer 2 — Deployment Context: environmentMatch, tenantMatch
+
+    SE-14 invariant: environment and tenantId are read from stored record fields,
+    never from process environment variables.
+    """
+
+    evidence_id: str | int
+    """The evidence record ID that was verified."""
+
+    # Layer 1 — Cryptographic validity
+    signature_valid: SignatureStatus = SignatureStatus.UNSIGNED
+    hash_valid: bool | None = None
+    """None = not checked (no evidenceHash on record); True/False = checked."""
+    chain_valid: bool | None = None
+    """None = not checked (would require fetching the previous record)."""
+
+    signature_present: bool = False
+    signing_key_id: str | None = None
+
+    # Layer 2 — Deployment context (SE-14: read from stored fields only)
+    environment_match: bool | None = None
+    tenant_match: bool | None = None
+
+    # Compliance (derived from Layer 1+2 outcomes — CI-5)
+    compliance: ComplianceFlags = Field(default_factory=ComplianceFlags)
+
+    # The raw evidence record (for caller inspection)
+    record: dict[str, Any] | None = None
+
+    # Error details if verification failed
+    error: str | None = None
+
+    @property
+    def verified(self) -> bool:
+        """
+        True only when cryptographic validity is fully confirmed.
+
+        hash_valid=None (unchecked) is treated as a pass for the verified property —
+        the signature itself covers the evidenceHash field, so absence of an
+        external hash check doesn't mean the record is unverified.
+        hash_valid=False explicitly means the stored hash failed verification.
+        """
+        sig_ok = self.signature_valid == SignatureStatus.VERIFIED
+        hash_ok = self.hash_valid is not False  # None = unchecked = ok; False = failed
+        return sig_ok and hash_ok

strix_verify/payload.py

@@ -0,0 +1,74 @@
+"""
+Canonical payload reconstruction for Strix evidence records.
+
+Ports the buildCanonicalPayload() function from:
+  packages/strixgov-verifier/src/index.mjs
+
+The 13-field schema is locked. Reordering fields invalidates all signatures.
+See: docs/gates/SIGNED-EVIDENCE-V1-AGENT-PROMPT.md
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import CanonicalPayload, RegulatoryContext
+
+
+def build_canonical_payload(record: dict[str, Any]) -> CanonicalPayload:
+    """
+    Reconstruct the canonical signed payload from an evidence record.
+
+    Matches the TypeScript implementation exactly:
+      - Field extraction uses the same fallback chains
+      - The Academy/Console dual-form discriminator (sourceApp ==
+        "academy-platform") is honored: serialization differs (see
+        CanonicalPayload.to_canonical_json)
+      - signedPayload, when present, is returned verbatim (v1.10.0)
+      - regulatoryContext defaults to empty/false values if absent
+
+    Args:
+        record: Raw evidence record dict from the proof API or local storage.
+
+    Returns:
+        CanonicalPayload instance. Call .to_canonical_json() to get the
+        deterministic JSON string used for signature verification.
+    """
+    # Dual-form discriminator: Academy signs numbers + article12-first ctx.
+    is_academy = record.get("sourceApp") == "academy-platform"
+
+    # v1.10.0 reconstruction-free path: original signed bytes, if present.
+    signed = record.get("signedPayload")
+    signed_payload = signed if isinstance(signed, str) and len(signed) > 0 else None
+
+    # Extract actor sub-fields (handle nested actor object or flat fields)
+    actor = record.get("actor") or {}
+    actor_id = record.get("actorId") or actor.get("id") or ""
+    actor_role = record.get("actorRole") or actor.get("role") or ""
+
+    # regulatory_context — use stored values or safe defaults
+    reg_raw = record.get("regulatoryContext") or {}
+    regulatory_context = RegulatoryContext(
+        complianceMode=reg_raw.get("complianceMode", ""),
+        euAiActArticle12=reg_raw.get("euAiActArticle12", False),
+        euAiActArticle14=reg_raw.get("euAiActArticle14", False),
+        euAiActArticle28=reg_raw.get("euAiActArticle28", False),
+    )
+
+    return CanonicalPayload(
+        schemaVersion="1",
+        evidenceId=str(record.get("evidenceId") or record.get("id") or ""),
+        evidenceHash=record.get("evidenceHash") or "",
+        proofChainHash=record.get("proofChainHash") or "",
+        capabilityId=record.get("capabilityId") or "",
+        action=record.get("action") or record.get("decision") or "",
+        actorId=actor_id,
+        actorRole=actor_role,
+        createdAt=record.get("createdAt") or "",
+        signingKeyId=record.get("signingKeyId") or "",
+        environment=record.get("environment") or "",
+        tenantId=record.get("tenantId") or "",
+        regulatoryContext=regulatory_context,
+        is_academy_form=is_academy,
+        signed_payload=signed_payload,
+    )

strix_verify/signature.py

@@ -0,0 +1,97 @@
+"""
+Ed25519 signature verification for Strix evidence records.
+
+Uses the Python `cryptography` library — no Strix tooling required.
+Ports the verifySignature() function from packages/strixgov-verifier/src/index.mjs.
+"""
+
+from __future__ import annotations
+
+import base64
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+
+def verify_signature(
+    canonical_payload: str,
+    signature_b64url: str,
+    public_key: Ed25519PublicKey,
+) -> bool:
+    """
+    Verify an Ed25519 signature against the canonical JSON payload.
+
+    Args:
+        canonical_payload: The deterministic JSON string from CanonicalPayload.to_canonical_json()
+        signature_b64url: Base64url-encoded signature from the evidence record
+        public_key: Ed25519PublicKey object (from jwks.resolve_key())
+
+    Returns:
+        True if the signature is valid, False otherwise.
+        Never raises — invalid signatures return False.
+    """
+    try:
+        data = canonical_payload.encode("utf-8")
+        # Add padding if needed for base64url
+        padding = 4 - len(signature_b64url) % 4
+        if padding != 4:
+            signature_b64url += "=" * padding
+        sig = base64.urlsafe_b64decode(signature_b64url)
+        public_key.verify(sig, data)
+        return True
+    except (InvalidSignature, ValueError, Exception):
+        return False
+
+
+def decode_jwk_to_public_key(jwk: dict) -> Ed25519PublicKey:
+    """
+    Convert a JWK (OKP/Ed25519) to an Ed25519PublicKey object.
+
+    Mirrors the TypeScript SPKI DER construction in fetchPublicKey():
+      - Extracts the 'x' parameter (base64url, 32 bytes)
+      - Prepends the 12-byte SPKI header: 302a300506032b6570032100
+      - Imports as DER SPKI
+
+    Args:
+        jwk: A JWK dict with kty="OKP", crv="Ed25519", and x (base64url pubkey)
+
+    Returns:
+        Ed25519PublicKey
+
+    Raises:
+        ValueError: If the JWK is malformed or the key type is wrong.
+    """
+    from cryptography.hazmat.primitives.serialization import (
+        Encoding,
+        PublicFormat,
+        load_der_public_key,
+    )
+
+    if jwk.get("kty") != "OKP" or jwk.get("crv") != "Ed25519":
+        raise ValueError(
+            f"Expected OKP/Ed25519 key, got kty={jwk.get('kty')} crv={jwk.get('crv')}"
+        )
+
+    x_b64url = jwk.get("x", "")
+    if not x_b64url:
+        raise ValueError("JWK missing 'x' parameter")
+
+    # base64url decode (add padding if needed)
+    padding = 4 - len(x_b64url) % 4
+    if padding != 4:
+        x_b64url += "=" * padding
+    raw_bytes = base64.urlsafe_b64decode(x_b64url)
+
+    if len(raw_bytes) != 32:
+        raise ValueError(f"Ed25519 key must be 32 bytes, got {len(raw_bytes)}")
+
+    # Build SPKI DER: 12-byte header + 32-byte raw key
+    # This mirrors the TypeScript: Buffer.from("302a300506032b6570032100", "hex")
+    spki_header = bytes.fromhex("302a300506032b6570032100")
+    spki_der = spki_header + raw_bytes
+
+    key = load_der_public_key(spki_der)
+    if not isinstance(key, Ed25519PublicKey):
+        raise ValueError("Decoded key is not an Ed25519PublicKey")
+
+    return key

strix_verify-0.2.0.dist-info/METADATA

@@ -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.

strix_verify-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+strix_verify/__init__.py,sha256=3qyXdSwRK3i5RNXYOvNoUy6qW3lhbqYBKD1__Z-PMMQ,7409
+strix_verify/client.py,sha256=cWuzfYyJ1-OeDGezko_YOktuSTFvmlDHEEkrjL9qfW4,2462
+strix_verify/compliance.py,sha256=rWSEzYFkhlwarDt2lxotaaMtLGvXsHie9bgMNHnSjNM,2150
+strix_verify/hashing.py,sha256=QpzWbA4Oi71Hu7DMhvxMeBsKxgfve1hduHiKuBUFIvI,3140
+strix_verify/jwks.py,sha256=tO7HvHthlK7XjNpLia4ViS_FXPWPqZbA1y06eZUSGmI,4897
+strix_verify/models.py,sha256=nBgQGulIqBZ3OLWgtDpkV9uO1GY0JxV-IQeMaAKJp-Y,10063
+strix_verify/payload.py,sha256=siD8HICoFIWeJJHXSomInzbszt1BjfSx-R3d_ixkQ88,2993
+strix_verify/signature.py,sha256=1H_HKrXesfMegIv6AutwY5EEqry5r8_zbAYeV7z9fWY,3132
+strix_verify-0.2.0.dist-info/METADATA,sha256=KAL9pxy1OHF-QWoi6CaGIKGqI1U2p2X1lro-uH05Dko,8536
+strix_verify-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+strix_verify-0.2.0.dist-info/RECORD,,

strix_verify-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any