vaid-pop 0.1.0__tar.gz

vaid_pop-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Rust
+/target
+**/*.rs.bk
+Cargo.lock.orig
+
+# Backtraces
+rustc-ice-*.txt
+
+# Editor / OS
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+.buildvenv/
+.installtest/

vaid_pop-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: vaid-pop
+Version: 0.1.0
+Summary: Canonical Python proof-of-possession (PoP) request signer for the VAID standard.
+Project-URL: Homepage, https://github.com/solara-associates/vaid
+Project-URL: Repository, https://github.com/solara-associates/vaid
+Project-URL: Source, https://github.com/solara-associates/vaid/tree/main/python/vaid-pop
+Project-URL: Issues, https://github.com/solara-associates/vaid/issues
+Author-email: "solara.associates" <info@solara.associates>
+License: Apache-2.0
+Keywords: agent-identity,cryptography,ed25519,proof-of-possession,signing,vaid
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: rfc8785>=0.1.2
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# vaid-pop
+
+Canonical Python proof-of-possession (PoP) request signer for the
+[VAID](https://github.com/solara-associates/vaid) standard.
+
+This is the **single Python definition** of the PoP signing contract. A
+VAID-bound request carries a fresh, replay-protected Ed25519 signature; this
+package builds the four `x-synthera-*` headers that carry it. Import it
+directly — no extra runtime, no framework.
+
+```python
+from vaid_pop import RequestSigner
+
+signer = RequestSigner(vaid=vaid_doc, private_key=agent_key)
+headers = signer.sign_headers("POST", "/vaid/mint", body_bytes)
+# -> {"x-synthera-vaid": ..., "x-synthera-timestamp": ...,
+#     "x-synthera-nonce": ..., "x-synthera-signature": ...}
+```
+
+> The `x-synthera-*` header names are the VAID wire contract — the prefix is the
+> fixed header namespace a conforming verifier reads, not a package dependency.
+
+## The firewall
+
+Cross-language byte-identity is the whole point. The signer is locked against the
+frozen cross-language vector (vendored here at
+`vaid_pop/vectors/operator_pop_v1.json`), which the Rust client (`vaid-client`)
+and the verifier (`vaid_pop`) assert against too. The `pop-conformance` CI job
+proves **Rust output == Python output == vector** byte-for-byte. A mismatch is a
+hard blocker.
+
+Contract: RFC 8785 (JCS) over the camelCase `RequestAuthPayload` → SHA-256 →
+pure Ed25519 over the 32-byte digest → raw 64-byte signature.
+
+> Standardized on `rfc8785` for JCS — the byte-for-byte JCS implementation the
+> vector is proven against. Do not substitute another JCS library without
+> re-proving byte-equality.
+
+## Relationship to other packages
+
+- **`vaid-client`** (Rust) is the cross-language peer, proven against the same vector.
+- Language-specific agent integrations depend on this package and re-export `RequestSigner`.
+- Clients consume this directly to authenticate a VAID-bound request.

vaid_pop-0.1.0/README.md

@@ -0,0 +1,43 @@
+# vaid-pop
+
+Canonical Python proof-of-possession (PoP) request signer for the
+[VAID](https://github.com/solara-associates/vaid) standard.
+
+This is the **single Python definition** of the PoP signing contract. A
+VAID-bound request carries a fresh, replay-protected Ed25519 signature; this
+package builds the four `x-synthera-*` headers that carry it. Import it
+directly — no extra runtime, no framework.
+
+```python
+from vaid_pop import RequestSigner
+
+signer = RequestSigner(vaid=vaid_doc, private_key=agent_key)
+headers = signer.sign_headers("POST", "/vaid/mint", body_bytes)
+# -> {"x-synthera-vaid": ..., "x-synthera-timestamp": ...,
+#     "x-synthera-nonce": ..., "x-synthera-signature": ...}
+```
+
+> The `x-synthera-*` header names are the VAID wire contract — the prefix is the
+> fixed header namespace a conforming verifier reads, not a package dependency.
+
+## The firewall
+
+Cross-language byte-identity is the whole point. The signer is locked against the
+frozen cross-language vector (vendored here at
+`vaid_pop/vectors/operator_pop_v1.json`), which the Rust client (`vaid-client`)
+and the verifier (`vaid_pop`) assert against too. The `pop-conformance` CI job
+proves **Rust output == Python output == vector** byte-for-byte. A mismatch is a
+hard blocker.
+
+Contract: RFC 8785 (JCS) over the camelCase `RequestAuthPayload` → SHA-256 →
+pure Ed25519 over the 32-byte digest → raw 64-byte signature.
+
+> Standardized on `rfc8785` for JCS — the byte-for-byte JCS implementation the
+> vector is proven against. Do not substitute another JCS library without
+> re-proving byte-equality.
+
+## Relationship to other packages
+
+- **`vaid-client`** (Rust) is the cross-language peer, proven against the same vector.
+- Language-specific agent integrations depend on this package and re-export `RequestSigner`.
+- Clients consume this directly to authenticate a VAID-bound request.

vaid_pop-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vaid-pop"
+# Independent semver. Additive-minor for new optional fields; major for any
+# canonicalization / field-name change (those break cross-language byte-identity
+# against operator_pop_v1.json).
+version = "0.1.0"
+description = "Canonical Python proof-of-possession (PoP) request signer for the VAID standard."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "solara.associates", email = "info@solara.associates" }]
+keywords = ["vaid", "agent-identity", "ed25519", "proof-of-possession", "cryptography", "signing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+# cryptography = Ed25519 (no stdlib option); rfc8785 = RFC 8785 JCS, spec-for-spec
+# identical to the Rust serde_jcs path so the canonical bytes agree by construction
+# (locked by the vendored operator_pop_v1.json). NOTE: standardized on rfc8785 — do
+# NOT substitute another JCS library without re-proving byte-equality against the
+# frozen vector.
+dependencies = [
+    "cryptography>=42.0",
+    "rfc8785>=0.1.2",
+]
+
+[project.scripts]
+# The packaged firewall: an external consumer who installed ONLY the wheel can run
+# `vaid-pop-conformance` to prove the signer they got reproduces the frozen
+# cross-language vector byte-for-byte. Ships in the wheel (it's a package module),
+# unlike the repo `tests/` suite.
+vaid-pop-conformance = "vaid_pop.conformance:main"
+
+[project.urls]
+Homepage = "https://github.com/solara-associates/vaid"
+Repository = "https://github.com/solara-associates/vaid"
+Source = "https://github.com/solara-associates/vaid/tree/main/python/vaid-pop"
+Issues = "https://github.com/solara-associates/vaid/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+# The vendored conformance vector ships inside the wheel so a consumer's CI runs
+# the firewall against the exact bytes this signer was proven against.
+packages = ["vaid_pop"]
+
+[tool.hatch.build.targets.sdist]
+include = ["vaid_pop", "tests", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vaid_pop-0.1.0/tests/test_completion_conformance.py

@@ -0,0 +1,87 @@
+"""Completion-record conformance gate (Python side of the cross-language firewall).
+
+The vendored vector ``vaid_pop/vectors/completion_v1.json`` is byte-identical to
+the Rust copy (a CI drift-check enforces that). Asserts the Python signer
+reproduces the frozen digest + signature for a real CompletionRecord, and — since
+this is the FIRST vector with an ENUM — that every AssuranceTier serializes to
+exactly the frozen string (the most likely place for silent Rust/Python drift).
+"""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from vaid_pop import (
+    AssuranceTier,
+    build_completion_record,
+    canonical_request_signing_bytes,
+)
+
+
+def _vector() -> dict:
+    data = files("vaid_pop").joinpath("vectors/completion_v1.json").read_text()
+    return json.loads(data)
+
+
+def _record_from_input(inp: dict) -> dict:
+    # Rebuild through the package builder (not the raw vector dict) so the test
+    # exercises the real construction path, then assert it equals the frozen input.
+    return build_completion_record(
+        vaid_id=inp["vaidId"],
+        request_digest_sha256=inp["requestDigestSha256"],
+        tenant_id=inp["tenantId"],
+        status=inp["status"],
+        result_sha256=inp["resultSha256"],
+        completed_at=inp["completedAt"],
+        signer_vaid_id=inp["signerVaidId"],
+        assurance_tier=inp["assuranceTier"],
+        record_nonce=inp["recordNonce"],
+    )
+
+
+def test_completion_digest_matches_frozen_vector():
+    v = _vector()
+    record = _record_from_input(v["input"])
+    assert record == v["input"], "builder output must equal the frozen input dict"
+    digest = canonical_request_signing_bytes(record)
+    assert digest.hex() == v["digest_sha256_hex"], (
+        "Python completion-record digest diverged from the frozen vector — BLOCKER"
+    )
+    assert len(digest) == 32
+
+
+def test_completion_signature_matches_frozen_vector():
+    v = _vector()
+    seed = bytes.fromhex(v["ed25519"]["private_key_seed_hex"])
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+
+    pub = sk.public_key().public_bytes_raw()
+    assert pub.hex() == v["ed25519"]["public_key_hex"], "public key diverged — BLOCKER"
+
+    digest = canonical_request_signing_bytes(_record_from_input(v["input"]))
+    sig = sk.sign(digest)
+    assert sig.hex() == v["ed25519"]["signature_hex"], "signature diverged — BLOCKER"
+    assert len(sig) == 64
+    Ed25519PublicKey.from_public_bytes(pub).verify(sig, digest)  # raises on failure
+
+
+def test_assurance_tier_strings_match_frozen_vector():
+    """THE ENUM DRIFT GUARD: the Python AssuranceTier values must equal the frozen
+    strings, in order — the field where Rust camelCase serde and Python enum values
+    must agree byte-for-byte inside the signed document."""
+    v = _vector()
+    frozen = v["assurance_tier_strings"]
+    py_values = [
+        AssuranceTier.SELF_REPORTED.value,
+        AssuranceTier.COUNTER_SIGNED.value,
+        AssuranceTier.THIRD_PARTY_ATTESTED.value,
+    ]
+    assert py_values == frozen, "AssuranceTier strings diverged from the frozen vector — BLOCKER"
+    # The declared tier in `input` is the only substantiated tier.
+    assert v["input"]["assuranceTier"] == AssuranceTier.SELF_REPORTED.value

vaid_pop-0.1.0/tests/test_conformance.py

@@ -0,0 +1,110 @@
+"""Canonical PoP conformance gate (Python side of the cross-language firewall).
+
+The vendored vector ``vaid_pop/vectors/operator_pop_v1.json`` is byte-identical
+to the canonical cross-language vector in the ``vaid`` repo (a CI drift-check
+enforces that). These tests assert the Python signer reproduces the frozen
+digest + Ed25519 signature byte-for-byte; a mismatch is a BLOCKER, not a
+ship-anyway. The Rust client (`vaid-client`) asserts the same vector, and the
+repo-level ``pop-conformance`` job proves Rust output == Python output == vector.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from datetime import datetime, timezone
+from importlib.resources import files
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from vaid_pop import (
+    HEADER_NONCE,
+    HEADER_SIGNATURE,
+    HEADER_TIMESTAMP,
+    HEADER_VAID,
+    RequestSigner,
+    canonical_request_signing_bytes,
+)
+
+
+def _vector() -> dict:
+    # Read the vector the package SHIPS — the firewall is only real if a consumer
+    # runs it against the copy bundled with the signer it actually installed.
+    data = files("vaid_pop").joinpath("vectors/operator_pop_v1.json").read_text()
+    return json.loads(data)
+
+
+def test_canonical_digest_matches_frozen_vector():
+    """Python JCS + SHA-256 over the camelCase RequestAuthPayload reproduces the
+    Rust-frozen digest byte-for-byte."""
+    v = _vector()
+    digest = canonical_request_signing_bytes(v["input"])
+    assert digest.hex() == v["digest_sha256_hex"], (
+        "Python canonical digest diverged from the frozen vector — BLOCKER"
+    )
+    assert len(digest) == 32
+
+
+def test_deterministic_signature_matches_frozen_vector():
+    """From the frozen seed, Python derives the same public key and produces the
+    same deterministic Ed25519 signature the Rust vector froze."""
+    v = _vector()
+    seed = bytes.fromhex(v["ed25519"]["private_key_seed_hex"])
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+
+    pub = sk.public_key().public_bytes_raw()
+    assert pub.hex() == v["ed25519"]["public_key_hex"], "public key diverged — BLOCKER"
+
+    digest = canonical_request_signing_bytes(v["input"])
+    sig = sk.sign(digest)
+    assert sig.hex() == v["ed25519"]["signature_hex"], "signature diverged — BLOCKER"
+    assert len(sig) == 64
+
+    Ed25519PublicKey.from_public_bytes(pub).verify(sig, digest)  # raises on failure
+
+
+def test_request_signer_produces_verifiable_pop_headers():
+    """The real signer path: RequestSigner.sign_headers builds the camelCase
+    RequestAuthPayload, signs it, and X-Synthera-Signature verifies against the
+    agent key over the reconstructed digest."""
+    v = _vector()
+    seed = bytes.fromhex(v["ed25519"]["private_key_seed_hex"])
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+    pub = sk.public_key()
+
+    vaid = {
+        "vaid_id": v["input"]["vaidId"],
+        "tenant_id": v["input"]["tenantId"],
+        "agent_id": "22222222-2222-2222-2222-222222222222",
+    }
+    signer = RequestSigner(vaid=vaid, private_key=sk)
+
+    fixed_now = datetime(2026, 6, 4, 12, 0, 0, tzinfo=timezone.utc)
+    body = b""  # vector bodySha256 = sha256("") = e3b0c442...
+    headers = signer.sign_headers(
+        "POST", "/vaid/mint", body, now=fixed_now, nonce=v["input"]["clientNonce"]
+    )
+
+    assert headers[HEADER_TIMESTAMP] == v["input"]["timestamp"]
+    assert headers[HEADER_NONCE] == v["input"]["clientNonce"]
+
+    payload = {
+        "vaidId": vaid["vaid_id"],
+        "method": "POST",
+        "path": "/vaid/mint",
+        "bodySha256": hashlib.sha256(body).hexdigest(),
+        "tenantId": vaid["tenant_id"],
+        "timestamp": headers[HEADER_TIMESTAMP],
+        "clientNonce": headers[HEADER_NONCE],
+    }
+    digest = canonical_request_signing_bytes(payload)
+    # The signer must reproduce the frozen digest AND signature for this input.
+    assert digest.hex() == v["digest_sha256_hex"]
+    sig = base64.b64decode(headers[HEADER_SIGNATURE])
+    assert sig.hex() == v["ed25519"]["signature_hex"], "header signature diverged — BLOCKER"
+    assert len(sig) == 64
+    pub.verify(sig, digest)  # raises on failure → the header signature is valid

vaid_pop-0.1.0/vaid_pop/__init__.py

@@ -0,0 +1,43 @@
+"""vaid-pop — canonical Python proof-of-possession request signer.
+
+The single Python definition of the VAID PoP signing contract. Import this
+package directly to sign a VAID-bound request without pulling in a framework
+(language-specific agent integrations depend on this package and re-export the
+signer). Byte-identity with the Rust client (`vaid-client`) and the verifier
+(`vaid_pop`) is locked by the vendored cross-language vector
+``vaid_pop/vectors/operator_pop_v1.json``.
+
+Usage::
+
+    from vaid_pop import RequestSigner
+
+    signer = RequestSigner(vaid=vaid_doc, private_key=agent_key)
+    headers = signer.sign_headers("POST", "/vaid/mint", body_bytes)
+"""
+
+from vaid_pop.completion import AssuranceTier, build_completion_record
+from vaid_pop.signer import (
+    HEADER_NONCE,
+    HEADER_SIGNATURE,
+    HEADER_TIMESTAMP,
+    HEADER_VAID,
+    RequestSigner,
+    build_request_auth_payload,
+    canonical_request_signing_bytes,
+    utc_whole_second_rfc3339,
+)
+
+__all__ = [
+    "RequestSigner",
+    "canonical_request_signing_bytes",
+    "build_request_auth_payload",
+    "utc_whole_second_rfc3339",
+    "AssuranceTier",
+    "build_completion_record",
+    "HEADER_VAID",
+    "HEADER_TIMESTAMP",
+    "HEADER_NONCE",
+    "HEADER_SIGNATURE",
+]
+
+__version__ = "0.1.0"

vaid_pop-0.1.0/vaid_pop/completion.py

@@ -0,0 +1,72 @@
+"""Completion / provenance record — Python mirror of the Rust
+``vaid_pop::request_completion``.
+
+A signed statement that a VAID-authorized action finished, over the SAME
+JCS→SHA-256→Ed25519 pipeline as the request PoP (no new crypto). Byte-identity
+with the Rust ``CompletionRecord`` is locked by the shared vector
+``completion_v1.json``.
+
+SCOPE — self-signed, DECLARED metadata only
+-------------------------------------------
+The record carries one detached signature by ``signer_vaid_id``. That proves only
+that this signer signed the record. The ``assurance_tier`` is therefore
+**declared, not proven**:
+
+* ``AssuranceTier.SELF_REPORTED`` is the only tier this repo substantiates on its
+  own (actor signs its own outcome; the signature verifies against the actor key).
+* ``COUNTER_SIGNED`` / ``THIRD_PARTY_ATTESTED`` are NOT independently verifiable
+  from this repo alone — a self-reporting signer can set either and the single
+  signature still verifies. Provable counter-signing / third-party attestation is
+  a separate, not-yet-built primitive and is OUT OF SCOPE here.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class AssuranceTier(str, Enum):
+    """Declared assurance level. String values mirror the Rust enum's
+    ``rename_all = "camelCase"`` serialization EXACTLY — these strings go into the
+    signed document, so any divergence breaks cross-language byte-identity (this is
+    the enum-drift risk the conformance vector guards)."""
+
+    SELF_REPORTED = "selfReported"
+    COUNTER_SIGNED = "counterSigned"
+    THIRD_PARTY_ATTESTED = "thirdPartyAttested"
+
+
+def build_completion_record(
+    *,
+    vaid_id: str,
+    request_digest_sha256: str,
+    tenant_id: str,
+    status: str,
+    result_sha256: str,
+    completed_at: str,
+    signer_vaid_id: str,
+    assurance_tier: AssuranceTier | str,
+    record_nonce: str,
+) -> dict:
+    """Assemble the camelCase ``CompletionRecord`` a completer signs.
+
+    Field names/encoding mirror the Rust ``CompletionRecord`` serde exactly. The
+    result is a plain ``dict`` (like a ``RequestAuthPayload``) ready for
+    ``canonical_request_signing_bytes`` → ``sign``. ``assurance_tier`` accepts the
+    :class:`AssuranceTier` enum or its string value; it is written as the string.
+
+    ``completed_at`` MUST be whole-second RFC 3339 ``…Z`` (the same fixed point as
+    ``RequestAuthPayload.timestamp``) or byte-identity breaks.
+    """
+    tier = assurance_tier.value if isinstance(assurance_tier, AssuranceTier) else assurance_tier
+    return {
+        "vaidId": vaid_id,
+        "requestDigestSha256": request_digest_sha256,
+        "tenantId": tenant_id,
+        "status": status,
+        "resultSha256": result_sha256,
+        "completedAt": completed_at,
+        "signerVaidId": signer_vaid_id,
+        "assuranceTier": tier,
+        "recordNonce": record_nonce,
+    }

vaid_pop-0.1.0/vaid_pop/conformance.py

@@ -0,0 +1,218 @@
+"""Packaged cross-language PoP conformance check — the firewall, shipped in the wheel.
+
+This module is the externally-consumable form of the conformance gate. Unlike the
+repo test suite under ``tests/`` (which does not ship in the wheel), this lives
+*inside* the installed package, so a consumer who has only ``pip install
+vaid-pop`` — no repo checkout — can prove the signer they installed reproduces
+the frozen cross-language vector byte-for-byte:
+
+    python -m vaid_pop.conformance      # exit 0 = PASS, 1 = BLOCKER
+    vaid-pop-conformance                # same, via the console entry point
+
+Programmatically::
+
+    from vaid_pop.conformance import run
+    run()  # raises ConformanceError on any divergence; returns the vector on PASS
+
+The vector it checks against is the one bundled with the signer
+(``vaid_pop/vectors/operator_pop_v1.json``) — the firewall is only real if a
+consumer runs it against the exact bytes the installed signer was proven against.
+The Rust client (``vaid-client``) asserts the identical vector; the repo-level
+``pop-conformance`` job proves Rust output == Python output == vector.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from importlib.resources import files
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from vaid_pop import (
+    HEADER_NONCE,
+    HEADER_SIGNATURE,
+    HEADER_TIMESTAMP,
+    RequestSigner,
+    canonical_request_signing_bytes,
+)
+
+
+class ConformanceError(AssertionError):
+    """A cross-language byte-identity divergence — a hard BLOCKER, never ship-anyway."""
+
+
+def load_vector() -> dict:
+    """The operator-PoP conformance vector bundled with the installed package."""
+    data = files("vaid_pop").joinpath("vectors/operator_pop_v1.json").read_text()
+    return json.loads(data)
+
+
+def load_completion_vector() -> dict:
+    """The completion-record conformance vector bundled with the installed package."""
+    data = files("vaid_pop").joinpath("vectors/completion_v1.json").read_text()
+    return json.loads(data)
+
+
+def check_completion(v: dict) -> None:
+    """Python JCS + SHA-256 + Ed25519 over the camelCase CompletionRecord reproduce
+    the frozen digest + signature, and the AssuranceTier strings match (the enum
+    drift guard — the first vector with an enum)."""
+    from vaid_pop import AssuranceTier
+
+    digest = canonical_request_signing_bytes(v["input"])
+    if digest.hex() != v["digest_sha256_hex"]:
+        raise ConformanceError(
+            f"completion digest diverged from the frozen vector — BLOCKER\n"
+            f"  got    = {digest.hex()}\n  vector = {v['digest_sha256_hex']}"
+        )
+    seed = bytes.fromhex(v["ed25519"]["private_key_seed_hex"])
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+    sig = sk.sign(digest)
+    if sig.hex() != v["ed25519"]["signature_hex"]:
+        raise ConformanceError(
+            f"completion signature diverged from the frozen vector — BLOCKER\n"
+            f"  got    = {sig.hex()}\n  vector = {v['ed25519']['signature_hex']}"
+        )
+    py_tiers = [
+        AssuranceTier.SELF_REPORTED.value,
+        AssuranceTier.COUNTER_SIGNED.value,
+        AssuranceTier.THIRD_PARTY_ATTESTED.value,
+    ]
+    if py_tiers != v["assurance_tier_strings"]:
+        raise ConformanceError(
+            f"AssuranceTier strings diverged from the frozen vector — BLOCKER\n"
+            f"  got    = {py_tiers}\n  vector = {v['assurance_tier_strings']}"
+        )
+
+
+def check_digest(v: dict) -> None:
+    """Python JCS + SHA-256 over the camelCase RequestAuthPayload == frozen digest."""
+    digest = canonical_request_signing_bytes(v["input"])
+    if digest.hex() != v["digest_sha256_hex"]:
+        raise ConformanceError(
+            f"canonical digest diverged from the frozen vector — BLOCKER\n"
+            f"  got    = {digest.hex()}\n  vector = {v['digest_sha256_hex']}"
+        )
+    if len(digest) != 32:
+        raise ConformanceError(f"digest is {len(digest)} bytes, expected 32")
+
+
+def check_signature(v: dict) -> None:
+    """From the frozen seed, derive the same public key + deterministic signature."""
+    seed = bytes.fromhex(v["ed25519"]["private_key_seed_hex"])
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+
+    pub = sk.public_key().public_bytes_raw()
+    if pub.hex() != v["ed25519"]["public_key_hex"]:
+        raise ConformanceError(
+            f"public key diverged — BLOCKER\n"
+            f"  got    = {pub.hex()}\n  vector = {v['ed25519']['public_key_hex']}"
+        )
+
+    digest = canonical_request_signing_bytes(v["input"])
+    sig = sk.sign(digest)
+    if sig.hex() != v["ed25519"]["signature_hex"]:
+        raise ConformanceError(
+            f"signature diverged — BLOCKER\n"
+            f"  got    = {sig.hex()}\n  vector = {v['ed25519']['signature_hex']}"
+        )
+    Ed25519PublicKey.from_public_bytes(pub).verify(sig, digest)  # raises on failure
+
+
+def check_request_signer(v: dict) -> None:
+    """The real signer path: RequestSigner.sign_headers produces the frozen signature
+    and a header that verifies against the agent key over the reconstructed digest."""
+    from datetime import datetime, timezone
+
+    seed = bytes.fromhex(v["ed25519"]["private_key_seed_hex"])
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+    pub = sk.public_key()
+
+    inp = v["input"]
+    vaid = {"vaid_id": inp["vaidId"], "tenant_id": inp["tenantId"]}
+    signer = RequestSigner(vaid=vaid, private_key=sk)
+
+    now = datetime.strptime(inp["timestamp"], "%Y-%m-%dT%H:%M:%SZ").replace(
+        tzinfo=timezone.utc
+    )
+    body = b""  # vector bodySha256 = sha256("")
+    headers = signer.sign_headers(
+        inp["method"], inp["path"], body, now=now, nonce=inp["clientNonce"]
+    )
+
+    if headers[HEADER_TIMESTAMP] != inp["timestamp"]:
+        raise ConformanceError("header timestamp diverged — BLOCKER")
+    if headers[HEADER_NONCE] != inp["clientNonce"]:
+        raise ConformanceError("header nonce diverged — BLOCKER")
+
+    payload = {
+        "vaidId": vaid["vaid_id"],
+        "method": "POST",
+        "path": "/vaid/mint",
+        "bodySha256": hashlib.sha256(body).hexdigest(),
+        "tenantId": vaid["tenant_id"],
+        "timestamp": headers[HEADER_TIMESTAMP],
+        "clientNonce": headers[HEADER_NONCE],
+    }
+    digest = canonical_request_signing_bytes(payload)
+    sig = base64.b64decode(headers[HEADER_SIGNATURE])
+    if sig.hex() != v["ed25519"]["signature_hex"]:
+        raise ConformanceError("header signature diverged — BLOCKER")
+    pub.verify(sig, digest)  # raises on failure → header signature is valid
+
+
+def run() -> dict:
+    """Run all firewall checks against the bundled vector. Raises ConformanceError
+    on any divergence; returns the vector on PASS."""
+    v = load_vector()
+    check_digest(v)
+    check_signature(v)
+    check_request_signer(v)
+    check_completion(load_completion_vector())
+    return v
+
+
+# --- pytest discovery (so `pytest --pyargs vaid_pop` runs the firewall) ---
+
+
+def test_packaged_digest_matches_frozen_vector() -> None:
+    check_digest(load_vector())
+
+
+def test_packaged_signature_matches_frozen_vector() -> None:
+    check_signature(load_vector())
+
+
+def test_packaged_request_signer_matches_frozen_vector() -> None:
+    check_request_signer(load_vector())
+
+
+def test_packaged_completion_matches_frozen_vector() -> None:
+    check_completion(load_completion_vector())
+
+
+def main() -> int:
+    try:
+        v = run()
+    except ConformanceError as exc:
+        print(f"CROSS-LANGUAGE PoP FIREWALL: MISMATCH — BLOCKER\n{exc}")
+        return 1
+    c = load_completion_vector()
+    print(
+        "CROSS-LANGUAGE PoP FIREWALL: PASS — installed signer == frozen vectors, "
+        "byte-for-byte\n"
+        f"  operator   digest    = {v['digest_sha256_hex']}\n"
+        f"  operator   signature = {v['ed25519']['signature_hex']}\n"
+        f"  completion digest    = {c['digest_sha256_hex']}\n"
+        f"  completion signature = {c['ed25519']['signature_hex']}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vaid_pop-0.1.0/vaid_pop/signer.py

@@ -0,0 +1,142 @@
+"""VAID proof-of-possession request signing — canonical Python signer.
+
+The Rust `vaid-pop` crate (the operator-signing port and the `vaid_pop`
+verifier) defines the CANONICAL contract; this is the Python **mirror**, not a
+second definition. Byte-identity is locked by the shared cross-language vector
+``operator_pop_v1.json`` (vendored into this package at ``vaid_pop/vectors/`` and
+drift-checked against the canonical source): if these bytes ever diverge from
+Rust, the conformance test is a BLOCKER.
+
+This module is the single source of the Python PoP signer. Language-specific
+agent integrations DEPEND ON this package and re-export ``RequestSigner`` /
+``canonical_request_signing_bytes`` — they no longer carry their own copy. Any
+framework-free consumer imports ``vaid_pop`` directly and pulls in nothing else.
+
+Contract: RFC 8785 (JCS) over the camelCase ``RequestAuthPayload`` -> SHA-256 ->
+32-byte digest -> **pure Ed25519 over the digest as the raw message** -> raw
+64-byte signature. The four headers below carry it.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+from datetime import datetime, timezone
+
+import rfc8785
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+# VAID PoP wire headers — the fixed `x-synthera-*` header namespace a conforming
+# verifier reads (the wire contract; the prefix is not a package dependency).
+HEADER_VAID = "x-synthera-vaid"
+HEADER_TIMESTAMP = "x-synthera-timestamp"
+HEADER_NONCE = "x-synthera-nonce"
+HEADER_SIGNATURE = "x-synthera-signature"
+
+
+def canonical_request_signing_bytes(payload: dict) -> bytes:
+    """The 32-byte signing digest: RFC 8785 (JCS) of `payload`, then SHA-256.
+
+    Mirror of the Rust `vaid_pop::canonical_request_signing_bytes`. The
+    payload MUST use the camelCase `RequestAuthPayload` field names
+    (`vaidId`, `method`, `path`, `bodySha256`, `tenantId`, `timestamp`,
+    `clientNonce`) — JCS sorts keys, so order is irrelevant, but names are not.
+    """
+    return hashlib.sha256(rfc8785.dumps(payload)).digest()
+
+
+def build_request_auth_payload(
+    *,
+    vaid_id: str,
+    method: str,
+    path: str,
+    body_sha256: str,
+    tenant_id: str,
+    timestamp: str,
+    client_nonce: str,
+) -> dict:
+    """The seven ADR-mandated fields, camelCase (mirrors `RequestAuthPayload`)."""
+    return {
+        "vaidId": vaid_id,
+        "method": method,
+        "path": path,
+        "bodySha256": body_sha256,
+        "tenantId": tenant_id,
+        "timestamp": timestamp,
+        "clientNonce": client_nonce,
+    }
+
+
+def utc_whole_second_rfc3339(now: datetime | None = None) -> str:
+    """Whole-second UTC RFC 3339 with `Z`.
+
+    This is the chrono-serde fixed point: the verifier parses the
+    `x-synthera-timestamp` header into a `DateTime<Utc>` and re-serializes it
+    when it recomputes the canonical bytes; a whole-second `...Z` string parses
+    and re-serializes to itself, so the client's signed-payload timestamp matches
+    the server's. Sub-second precision would risk a re-serialization mismatch.
+    """
+    now = now or datetime.now(timezone.utc)
+    return now.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class RequestSigner:
+    """Signs requests with the agent's per-agent Ed25519 key (build-3 PoP).
+
+    The agent's VAID document (as minted) and its private key are INPUTS here;
+    durable provisioning/injection of the key is the agent template's job,
+    not this client's.
+    """
+
+    def __init__(self, *, vaid: dict, private_key: Ed25519PrivateKey) -> None:
+        # The VAID document is snake_case (`Vaid` has no serde rename), unlike
+        # the camelCase `RequestAuthPayload`. Extract identity by snake_case keys.
+        try:
+            self._vaid_id = str(vaid["vaid_id"])
+            self._tenant_id = str(vaid["tenant_id"])
+        except KeyError as exc:
+            raise ValueError(f"VAID document missing required field {exc}") from exc
+        self._private_key = private_key
+        # X-Synthera-Vaid = base64 of the VAID document JSON. The verifier
+        # re-deserializes by field and recomputes the VAID's own canonical bytes
+        # for signature verification, so a compact re-encoding is fine.
+        self._vaid_header = base64.b64encode(
+            json.dumps(vaid, separators=(",", ":")).encode("utf-8")
+        ).decode("ascii")
+
+    def sign_headers(
+        self,
+        method: str,
+        path: str,
+        body: bytes,
+        *,
+        now: datetime | None = None,
+        nonce: str | None = None,
+    ) -> dict[str, str]:
+        """Produce the four PoP headers for `(method, path, body)`.
+
+        `now`/`nonce` are injectable for deterministic tests; in production they
+        default to the current UTC second and a fresh 128-bit random nonce.
+        """
+        timestamp = utc_whole_second_rfc3339(now)
+        nonce = nonce or secrets.token_hex(16)
+        body_sha256 = hashlib.sha256(body).hexdigest()
+        payload = build_request_auth_payload(
+            vaid_id=self._vaid_id,
+            method=method.upper(),
+            path=path,
+            body_sha256=body_sha256,
+            tenant_id=self._tenant_id,
+            timestamp=timestamp,
+            client_nonce=nonce,
+        )
+        digest = canonical_request_signing_bytes(payload)
+        signature = self._private_key.sign(digest)  # pure Ed25519, raw 64 bytes
+        return {
+            HEADER_VAID: self._vaid_header,
+            HEADER_TIMESTAMP: timestamp,
+            HEADER_NONCE: nonce,
+            HEADER_SIGNATURE: base64.b64encode(signature).decode("ascii"),
+        }

vaid_pop-0.1.0/vaid_pop/vectors/completion_v1.json

@@ -0,0 +1,27 @@
+{
+  "_comment": "Completion-record conformance vector (v1). Load-bearing. `input` is a real CompletionRecord (camelCase). NOTE: this is the FIRST vector containing an ENUM (`assuranceTier`) — the most likely place for silent Rust/Python string divergence, so an explicit enum round-trip test accompanies it. A conforming implementation MUST produce `digest_sha256_hex` from `input` via JCS (RFC 8785) -> SHA-256 and reproduce `ed25519.signature_hex` byte-for-byte. SCOPE: self-signed DECLARED metadata only — the single signature substantiates `assuranceTier=selfReported` and nothing above it; counterSigned / thirdPartyAttested are unverified claims here (a separate, not-yet-built primitive would substantiate them). Same JCS→SHA-256→Ed25519 primitive as operator_pop_v1.json.",
+  "assurance_tier_strings": [
+    "selfReported",
+    "counterSigned",
+    "thirdPartyAttested"
+  ],
+  "digest_sha256_hex": "98a51b7e34cbfc8d57a58f7c8fd6e353ad50936ab9f26293a10374c755cd784d",
+  "ed25519": {
+    "_comment": "Deterministic test key (same RFC 8032 seed as operator_pop_v1.json).",
+    "private_key_seed_hex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+    "public_key_hex": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
+    "signature_hex": "19657ec3ea3c660807e6153b66ff6e6d534c0aa798344614d162790564103be6a393eca15da2db52d0a7572f1d014a68834217c221895de46b8d322b2a3a150e"
+  },
+  "input": {
+    "assuranceTier": "selfReported",
+    "completedAt": "2026-06-04T12:00:05Z",
+    "recordNonce": "fedcba9876543210fedcba9876543210",
+    "requestDigestSha256": "ee474ba87d703ebeacf663d7d6a2f15319bdef285c5b702e336d0f4af5b61327",
+    "resultSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "signerVaidId": "11111111-1111-1111-1111-111111111111",
+    "status": "succeeded",
+    "tenantId": "synthera-control-plane",
+    "vaidId": "11111111-1111-1111-1111-111111111111"
+  },
+  "scheme": "JCS(RFC8785) -> SHA-256 -> pure Ed25519 over the 32-byte digest as raw message; raw 64-byte signature; raw 32-byte Ed25519 public key"
+}

vaid_pop-0.1.0/vaid_pop/vectors/operator_pop_v1.json

@@ -0,0 +1,20 @@
+{
+  "_comment": "Operator-signing conformance vector (v1). Load-bearing. `input` is a real RequestAuthPayload (#[serde(rename_all=camelCase)]), not a hand-written generic object. A conforming verifier MUST produce `digest_sha256_hex` from `input` via JCS (RFC 8785) -> SHA-256, and (given `ed25519.private_key_seed_hex`) reproduce `ed25519.signature_hex` byte-for-byte (Ed25519 is deterministic, RFC 8032). A mismatch in any field name, ordering, encoding, or signature is a canonicalization break.",
+  "scheme": "JCS(RFC8785) -> SHA-256 -> pure Ed25519 over the 32-byte digest as raw message; raw 64-byte signature; raw 32-byte Ed25519 public key",
+  "input": {
+    "vaidId": "11111111-1111-1111-1111-111111111111",
+    "method": "POST",
+    "path": "/vaid/mint",
+    "bodySha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "tenantId": "synthera-control-plane",
+    "timestamp": "2026-06-04T12:00:00Z",
+    "clientNonce": "0123456789abcdef0123456789abcdef"
+  },
+  "digest_sha256_hex": "ee474ba87d703ebeacf663d7d6a2f15319bdef285c5b702e336d0f4af5b61327",
+  "ed25519": {
+    "_comment": "Deterministic test key (RFC 8032 Ed25519 private seed). Any conforming implementation derives the same public key and produces the same signature over digest_sha256_hex. The signature verifies under vaid_pop::verify_signed_payload.",
+    "private_key_seed_hex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+    "public_key_hex": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
+    "signature_hex": "77e79744c362d352ce678992a3e3934fa57c33c3f307f6ffbe6ffc4ec5e726e096844fd8552db819b21a3e49e3b7796e23d1e10d4a03699285df4871f62e1502"
+  }
+}