vaid-langchain 0.1.0__tar.gz

vaid_langchain-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_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: vaid-langchain
+Version: 0.1.0
+Summary: LangChain request-signing adapter for the VAID standard: sign every outbound agent HTTP request with a VAID proof-of-possession via a thin httpx.Auth seam.
+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-langchain
+Project-URL: Issues, https://github.com/solara-associates/vaid/issues
+Author-email: "solara.associates" <info@solara.associates>
+License: Apache-2.0
+Keywords: agents,httpx,langchain,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: httpx>=0.27
+Requires-Dist: vaid-pop>=0.1.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: test
+Requires-Dist: langchain-core>=0.3; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# vaid-langchain
+
+Sign every outbound HTTP request a LangChain agent makes with a **VAID
+proof-of-possession**, without forking LangChain.
+
+```python
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from vaid_pop import RequestSigner
+from vaid_langchain import make_vaid_tool
+
+signer = RequestSigner(vaid=my_vaid_doc, private_key=my_key)   # hand-provisioned
+tool = make_vaid_tool(signer, base_url="https://api.example.com")
+# give `tool` to a LangChain agent — every call it makes to the backend is
+# VAID-signed with the four x-synthera-* headers.
+```
+
+Run the zero-dependency demo (mock backend, no server/LLM/API key):
+
+```
+python examples/quickstart.py
+```
+
+## How it works — the seam is the HTTP client, not the tool layer
+
+Agent frameworks hook at the *tool-call* layer (a function name + kwargs). VAID
+proof-of-possession signs an *HTTP request* — it binds `(method, request-target,
+body_sha256)`. So the clean, non-forking seam is the **HTTP client** the tool
+uses: **`VaidAuth`** is an `httpx.Auth` subclass that runs on every outbound
+request and attaches the PoP headers.
+
+That means `VaidAuth` is the whole reusable adapter — usable with any `httpx`
+client, LangChain not required:
+
+```python
+import httpx
+from vaid_langchain import VaidAuth
+client = httpx.Client(base_url="https://api.example.com", auth=VaidAuth(signer))
+client.post("/vaid/mint", json={...})   # signed
+```
+
+`make_vaid_tool` is just LangChain's idiomatic wrapper (a `StructuredTool`) around
+a client carrying that auth. Signing itself defers to `vaid_pop.RequestSigner` —
+canonicalization is never reimplemented, so a conforming verifier derives
+identical bytes.
+
+## The signed request target includes the query string — a security decision
+
+The signed `path` is the **on-the-wire request target: percent-encoded path +
+`?query`** (httpx `request.url.raw_path`), never path-only.
+
+This is a **security decision, not a demo convenience.** Signing path-only would
+leave query parameters (`?tenant=…`, `?limit=…`, ids, filters) **outside the
+signature**, so an attacker could alter them under a still-valid signature. Since
+the query frequently carries authorization-relevant material, it must be part of
+the signed target. The convention is pinned and covered by an explicit
+cross-language round-trip test (`tests/test_path_convention.py`), including a case
+proving that using the wrong attribute (query-dropping `.path`) fails verification
+**loudly** rather than silently. A verifier MUST reconstruct the same target
+(path + query) it received.
+
+## Provisioning is hand-done — NOT managed by this SDK
+
+This adapter signs requests; it does **not** provision identity. Getting the
+agent's **VAID document** and its **Ed25519 private key** into the process is the
+caller's responsibility:
+
+- **Mint the VAID** with the reference mint (`vaid-mint`) or your deployment's
+  managed authority.
+- **Load the private key** from your own secret store / env / file.
+
+The quickstart hard-codes a demo VAID + key purely to run offline. Do not ship
+hard-coded keys — treat the agent's private key (and, per the mint's delegation
+model, any parent VAID it holds) as a credential.
+
+## Install (local dev)
+
+Depends on `vaid-pop`. For a local checkout:
+
+```
+pip install -e python/vaid-pop
+pip install -e python/vaid-langchain[test]   # includes langchain-core + pytest
+```
+
+## Other frameworks
+
+CrewAI and Google ADK integrate through the **same `VaidAuth` seam** (subclass
+`crewai.tools.BaseTool` / wrap an ADK `FunctionTool` over a `VaidAuth`-bearing
+client). Only LangChain ships today; the shared auth is what makes the others
+near-copies.

vaid_langchain-0.1.0/README.md

@@ -0,0 +1,89 @@
+# vaid-langchain
+
+Sign every outbound HTTP request a LangChain agent makes with a **VAID
+proof-of-possession**, without forking LangChain.
+
+```python
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from vaid_pop import RequestSigner
+from vaid_langchain import make_vaid_tool
+
+signer = RequestSigner(vaid=my_vaid_doc, private_key=my_key)   # hand-provisioned
+tool = make_vaid_tool(signer, base_url="https://api.example.com")
+# give `tool` to a LangChain agent — every call it makes to the backend is
+# VAID-signed with the four x-synthera-* headers.
+```
+
+Run the zero-dependency demo (mock backend, no server/LLM/API key):
+
+```
+python examples/quickstart.py
+```
+
+## How it works — the seam is the HTTP client, not the tool layer
+
+Agent frameworks hook at the *tool-call* layer (a function name + kwargs). VAID
+proof-of-possession signs an *HTTP request* — it binds `(method, request-target,
+body_sha256)`. So the clean, non-forking seam is the **HTTP client** the tool
+uses: **`VaidAuth`** is an `httpx.Auth` subclass that runs on every outbound
+request and attaches the PoP headers.
+
+That means `VaidAuth` is the whole reusable adapter — usable with any `httpx`
+client, LangChain not required:
+
+```python
+import httpx
+from vaid_langchain import VaidAuth
+client = httpx.Client(base_url="https://api.example.com", auth=VaidAuth(signer))
+client.post("/vaid/mint", json={...})   # signed
+```
+
+`make_vaid_tool` is just LangChain's idiomatic wrapper (a `StructuredTool`) around
+a client carrying that auth. Signing itself defers to `vaid_pop.RequestSigner` —
+canonicalization is never reimplemented, so a conforming verifier derives
+identical bytes.
+
+## The signed request target includes the query string — a security decision
+
+The signed `path` is the **on-the-wire request target: percent-encoded path +
+`?query`** (httpx `request.url.raw_path`), never path-only.
+
+This is a **security decision, not a demo convenience.** Signing path-only would
+leave query parameters (`?tenant=…`, `?limit=…`, ids, filters) **outside the
+signature**, so an attacker could alter them under a still-valid signature. Since
+the query frequently carries authorization-relevant material, it must be part of
+the signed target. The convention is pinned and covered by an explicit
+cross-language round-trip test (`tests/test_path_convention.py`), including a case
+proving that using the wrong attribute (query-dropping `.path`) fails verification
+**loudly** rather than silently. A verifier MUST reconstruct the same target
+(path + query) it received.
+
+## Provisioning is hand-done — NOT managed by this SDK
+
+This adapter signs requests; it does **not** provision identity. Getting the
+agent's **VAID document** and its **Ed25519 private key** into the process is the
+caller's responsibility:
+
+- **Mint the VAID** with the reference mint (`vaid-mint`) or your deployment's
+  managed authority.
+- **Load the private key** from your own secret store / env / file.
+
+The quickstart hard-codes a demo VAID + key purely to run offline. Do not ship
+hard-coded keys — treat the agent's private key (and, per the mint's delegation
+model, any parent VAID it holds) as a credential.
+
+## Install (local dev)
+
+Depends on `vaid-pop`. For a local checkout:
+
+```
+pip install -e python/vaid-pop
+pip install -e python/vaid-langchain[test]   # includes langchain-core + pytest
+```
+
+## Other frameworks
+
+CrewAI and Google ADK integrate through the **same `VaidAuth` seam** (subclass
+`crewai.tools.BaseTool` / wrap an ADK `FunctionTool` over a `VaidAuth`-bearing
+client). Only LangChain ships today; the shared auth is what makes the others
+near-copies.

vaid_langchain-0.1.0/examples/quickstart.py

@@ -0,0 +1,62 @@
+"""5-minute quickstart: a LangChain tool whose calls are VAID-signed.
+
+Run:  python examples/quickstart.py
+
+This uses an in-process mock backend (httpx.MockTransport) so it runs with no
+server, no network, and no LLM/API key — it prints the four x-synthera-* PoP
+headers the tool attaches to its outbound request, and verifies the signature.
+
+IMPORTANT — provisioning is hand-done here, NOT managed by the SDK:
+the VAID document and the Ed25519 private key below are hard-coded demo values.
+In a real deployment you mint the VAID (see vaid-mint) and load the agent's
+private key from your own secret store; the vaid SDK does not provision either.
+"""
+
+from __future__ import annotations
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from vaid_pop import RequestSigner
+from vaid_langchain import VaidAuth, make_vaid_tool
+
+# ── Hand-provisioned demo identity (NOT SDK-managed) ──
+DEMO_SEED = bytes.fromhex(
+    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
+)
+DEMO_VAID = {
+    "vaid_id": "11111111-1111-1111-1111-111111111111",
+    "tenant_id": "acme",
+}
+
+
+def main() -> None:
+    private_key = Ed25519PrivateKey.from_private_bytes(DEMO_SEED)
+    signer = RequestSigner(vaid=DEMO_VAID, private_key=private_key)
+
+    # A mock backend that echoes back the PoP headers it received.
+    def backend(request: httpx.Request) -> httpx.Response:
+        pop = {k: v for k, v in request.headers.items() if k.startswith("x-synthera-")}
+        print("── request arrived at the protected backend ──")
+        print(f"  {request.method} {request.url.raw_path.decode('ascii')}")
+        for k, v in pop.items():
+            shown = v if len(v) < 60 else v[:57] + "..."
+            print(f"  {k}: {shown}")
+        return httpx.Response(200, json={"minted": True})
+
+    client = httpx.Client(
+        base_url="https://api.example.com",
+        auth=VaidAuth(signer),
+        transport=httpx.MockTransport(backend),
+    )
+    tool = make_vaid_tool(signer, "https://api.example.com", client=client)
+
+    # An agent would call this tool; here we invoke it directly (no LLM needed).
+    result = tool.invoke(
+        {"path": "/vaid/mint?tenant=acme", "payload": {"seed": {"agentClass": "runner"}}}
+    )
+    print("\nbackend response:", result)
+
+
+if __name__ == "__main__":
+    main()

vaid_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vaid-langchain"
+version = "0.1.0"
+description = "LangChain request-signing adapter for the VAID standard: sign every outbound agent HTTP request with a VAID proof-of-possession via a thin httpx.Auth seam."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "solara.associates", email = "info@solara.associates" }]
+keywords = ["vaid", "langchain", "agents", "proof-of-possession", "httpx", "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",
+]
+# vaid-pop = the shared JCS→SHA-256→Ed25519 PoP signer (VaidAuth defers to it,
+# never reimplements it). httpx = the client-auth seam (VaidAuth is an httpx.Auth).
+# langchain-core is OPTIONAL: VaidAuth works with any httpx client standalone;
+# only `make_vaid_tool` needs it, and it is imported lazily.
+dependencies = [
+    "vaid-pop>=0.1.0",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+# The packaged firewall: an external consumer who installed ONLY the wheel can run
+# `vaid-langchain-conformance` to prove the adapter they got reproduces the frozen
+# path-with-query vector byte-for-byte (via its own use of vaid-pop).
+vaid-langchain-conformance = "vaid_langchain.conformance:main"
+
+[project.optional-dependencies]
+langchain = [
+    "langchain-core>=0.3",
+]
+test = [
+    "pytest>=8.0",
+    "langchain-core>=0.3",
+]
+
+[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-langchain"
+Issues = "https://github.com/solara-associates/vaid/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vaid_langchain"]
+
+[tool.hatch.build.targets.sdist]
+include = ["vaid_langchain", "tests", "examples", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vaid_langchain-0.1.0/tests/test_langchain_tool.py

@@ -0,0 +1,112 @@
+"""The LangChain tool wrapper produces VAID-signed requests when invoked.
+
+Proves the end-to-end path an agent takes: invoke the StructuredTool → it calls
+the protected backend through the VaidAuth-bearing client → the request arriving
+at the backend carries valid PoP headers. A MockTransport stands in for the
+backend so no server/LLM is needed.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from vaid_pop import (
+    HEADER_NONCE,
+    HEADER_SIGNATURE,
+    HEADER_TIMESTAMP,
+    HEADER_VAID,
+    RequestSigner,
+    build_request_auth_payload,
+    canonical_request_signing_bytes,
+)
+
+from vaid_langchain import VaidAuth, make_vaid_tool
+from vaid_langchain._target import request_target
+
+SEED_HEX = "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
+VAID_ID = "11111111-1111-1111-1111-111111111111"
+TENANT_ID = "synthera-control-plane"
+
+
+def _key() -> Ed25519PrivateKey:
+    return Ed25519PrivateKey.from_private_bytes(bytes.fromhex(SEED_HEX))
+
+
+def _signer() -> RequestSigner:
+    return RequestSigner(vaid={"vaid_id": VAID_ID, "tenant_id": TENANT_ID}, private_key=_key())
+
+
+def _verify(request: httpx.Request) -> bool:
+    payload = build_request_auth_payload(
+        vaid_id=VAID_ID,
+        method=request.method.upper(),
+        path=request_target(request),
+        body_sha256=hashlib.sha256(request.content or b"").hexdigest(),
+        tenant_id=TENANT_ID,
+        timestamp=request.headers[HEADER_TIMESTAMP],
+        client_nonce=request.headers[HEADER_NONCE],
+    )
+    digest = canonical_request_signing_bytes(payload)
+    sig = base64.b64decode(request.headers[HEADER_SIGNATURE])
+    pub = _key().public_key().public_bytes_raw()
+    try:
+        Ed25519PublicKey.from_public_bytes(pub).verify(sig, digest)
+        return True
+    except Exception:
+        return False
+
+
+def _tool_with_mock_backend(handler):
+    client = httpx.Client(
+        base_url="https://api.example.com",
+        auth=VaidAuth(_signer()),
+        transport=httpx.MockTransport(handler),
+    )
+    return make_vaid_tool(_signer(), "https://api.example.com", client=client)
+
+
+def test_tool_invocation_sends_a_signed_request():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["req"] = request
+        return httpx.Response(200, text='{"ok": true}')
+
+    tool = _tool_with_mock_backend(handler)
+    out = tool.invoke({"path": "/vaid/mint", "payload": {"seed": {"agentClass": "x"}}})
+
+    assert out == '{"ok": true}'
+    req = captured["req"]
+    for h in (HEADER_VAID, HEADER_TIMESTAMP, HEADER_NONCE, HEADER_SIGNATURE):
+        assert h in req.headers
+    assert _verify(req), "the tool's outbound request must carry a valid PoP signature"
+
+
+def test_tool_has_expected_name_and_is_a_langchain_tool():
+    tool = make_vaid_tool(_signer(), "https://api.example.com", name="mint_via_synthera")
+    from langchain_core.tools import BaseTool
+
+    assert isinstance(tool, BaseTool)
+    assert tool.name == "mint_via_synthera"
+
+
+def test_tool_signs_query_string_in_path():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["req"] = request
+        return httpx.Response(200, text="ok")
+
+    tool = _tool_with_mock_backend(handler)
+    tool.invoke({"path": "/things?owner=acme&limit=5", "payload": {}})
+
+    req = captured["req"]
+    assert request_target(req) == "/things?owner=acme&limit=5"
+    assert _verify(req)

vaid_langchain-0.1.0/tests/test_path_convention.py

@@ -0,0 +1,146 @@
+"""PIN THE PATH/QUERY CONVENTION (Investigation 3's silent-failure landmine).
+
+Proves that the request-target string the adapter signs (``request_target`` =
+httpx ``raw_path`` = percent-encoded path+query):
+
+  1. is exactly what we intend, WITH and WITHOUT a query string present;
+  2. round-trips: sign → a verifier reconstructing the SAME target verifies OK;
+  3. is byte-identical to what the canonical RUST signer produces for the same
+     with-query target — asserted against the frozen, vendored vector
+     ``pathquery_v1.json`` (regenerate via
+     ``cargo run -p vaid-client --example emit_pop_pathquery``; a CI drift-check
+     enforces the Rust and Python copies are byte-identical);
+  4. fails closed if the WRONG attribute (``.path``, which drops the query) is
+     used on one side — the landmine bites loudly, not silently-at-runtime.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from datetime import datetime, timezone
+from importlib.resources import files
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from vaid_pop import RequestSigner, build_request_auth_payload, canonical_request_signing_bytes
+
+from vaid_langchain._target import request_target
+
+
+def _vector() -> dict:
+    """The frozen path-with-query vector bundled with the package (byte-identical
+    to the Rust copy under crates/vaid-client/tests/vectors/)."""
+    data = files("vaid_langchain").joinpath("vectors/pathquery_v1.json").read_text()
+    return json.loads(data)
+
+
+V = _vector()
+SEED_HEX = V["ed25519"]["private_key_seed_hex"]
+VAID_ID = V["input"]["vaidId"]
+TENANT_ID = V["input"]["tenantId"]
+TIMESTAMP = V["input"]["timestamp"]
+NONCE = V["input"]["clientNonce"]
+QUERY_PATH = V["input"]["path"]  # "/vaid/mint?tenant=acme&limit=10"
+
+
+def _key() -> Ed25519PrivateKey:
+    return Ed25519PrivateKey.from_private_bytes(bytes.fromhex(SEED_HEX))
+
+
+def _signer() -> RequestSigner:
+    return RequestSigner(vaid={"vaid_id": VAID_ID, "tenant_id": TENANT_ID}, private_key=_key())
+
+
+def _verify(method: str, path: str, body: bytes, headers: dict) -> bool:
+    """A stand-in verifier: reconstruct the payload from the SAME (method, path,
+    body) rule and check the signature against the agent public key."""
+    payload = build_request_auth_payload(
+        vaid_id=VAID_ID,
+        method=method.upper(),
+        path=path,
+        body_sha256=hashlib.sha256(body).hexdigest(),
+        tenant_id=TENANT_ID,
+        timestamp=headers["x-synthera-timestamp"],
+        client_nonce=headers["x-synthera-nonce"],
+    )
+    digest = canonical_request_signing_bytes(payload)
+    sig = base64.b64decode(headers["x-synthera-signature"])
+    pub = _key().public_key().public_bytes_raw()
+    try:
+        Ed25519PublicKey.from_public_bytes(pub).verify(sig, digest)
+        return True
+    except Exception:
+        return False
+
+
+def test_httpx_raw_path_yields_intended_target_without_query():
+    r = httpx.Request("POST", "https://api.example.com/vaid/mint", content=b"{}")
+    assert request_target(r) == "/vaid/mint"
+
+
+def test_httpx_raw_path_yields_intended_target_with_query():
+    r = httpx.Request("POST", f"https://api.example.com{QUERY_PATH}", content=b"{}")
+    # The query IS included in the signed target — the whole point.
+    assert request_target(r) == QUERY_PATH
+
+
+def test_roundtrip_sign_then_verify_no_query():
+    r = httpx.Request("POST", "https://api.example.com/vaid/mint", content=b"")
+    path = request_target(r)
+    now = datetime.strptime(TIMESTAMP, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    headers = _signer().sign_headers("POST", path, b"", now=now, nonce=NONCE)
+    assert _verify("POST", path, b"", headers)
+
+
+def test_roundtrip_sign_then_verify_with_query():
+    r = httpx.Request("POST", f"https://api.example.com{QUERY_PATH}", content=b"")
+    path = request_target(r)
+    now = datetime.strptime(TIMESTAMP, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    headers = _signer().sign_headers("POST", path, b"", now=now, nonce=NONCE)
+    assert _verify("POST", path, b"", headers)
+
+
+def test_cross_language_signature_matches_frozen_vector_for_with_query_target():
+    """Python signing of the httpx-extracted with-query target reproduces the
+    canonical RUST signature (the frozen vector) byte-for-byte — proving the exact
+    path string flows identically through both reference implementations."""
+    r = httpx.Request("POST", f"https://api.example.com{QUERY_PATH}", content=b"")
+    path = request_target(r)
+    assert path == V["input"]["path"]
+
+    payload = build_request_auth_payload(
+        vaid_id=VAID_ID,
+        method="POST",
+        path=path,
+        body_sha256=hashlib.sha256(b"").hexdigest(),
+        tenant_id=TENANT_ID,
+        timestamp=TIMESTAMP,
+        client_nonce=NONCE,
+    )
+    digest = canonical_request_signing_bytes(payload)
+    assert digest.hex() == V["digest_sha256_hex"], "digest diverged from the frozen vector — BLOCKER"
+
+    now = datetime.strptime(TIMESTAMP, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    headers = _signer().sign_headers("POST", path, b"", now=now, nonce=NONCE)
+    sig_hex = base64.b64decode(headers["x-synthera-signature"]).hex()
+    assert sig_hex == V["ed25519"]["signature_hex"], "signature diverged from the vector — BLOCKER"
+
+
+def test_wrong_attribute_dot_path_drops_query_and_fails_closed():
+    """THE LANDMINE: if the signer uses raw_path (with query) but a verifier uses
+    .path (query dropped), verification FAILS — the mismatch is caught, not
+    silently accepted. Proves picking the wrong attribute breaks loudly."""
+    r = httpx.Request("POST", f"https://api.example.com{QUERY_PATH}", content=b"")
+    signed_path = request_target(r)          # raw_path: includes ?query
+    verifier_path = r.url.path               # WRONG: query dropped
+    assert signed_path != verifier_path
+
+    now = datetime.strptime(TIMESTAMP, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    headers = _signer().sign_headers("POST", signed_path, b"", now=now, nonce=NONCE)
+    assert not _verify("POST", verifier_path, b"", headers)

vaid_langchain-0.1.0/tests/test_vaid_auth.py

@@ -0,0 +1,167 @@
+"""VaidAuth attaches valid PoP headers to every outbound request.
+
+Uses httpx's MockTransport so no network/server is needed: the handler receives
+the request AFTER auth_flow has run, so we can assert the four x-synthera-* headers
+are present and that the signature verifies over the reconstructed payload — with
+the raw_path (path+query) convention, and with a body-less (GET) request.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+import httpx
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from vaid_pop import (
+    HEADER_NONCE,
+    HEADER_SIGNATURE,
+    HEADER_TIMESTAMP,
+    HEADER_VAID,
+    RequestSigner,
+    build_request_auth_payload,
+    canonical_request_signing_bytes,
+)
+
+from vaid_langchain import VaidAuth
+from vaid_langchain._target import request_target
+
+SEED_HEX = "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
+VAID_ID = "11111111-1111-1111-1111-111111111111"
+TENANT_ID = "synthera-control-plane"
+
+
+def _key() -> Ed25519PrivateKey:
+    return Ed25519PrivateKey.from_private_bytes(bytes.fromhex(SEED_HEX))
+
+
+def _signer() -> RequestSigner:
+    return RequestSigner(vaid={"vaid_id": VAID_ID, "tenant_id": TENANT_ID}, private_key=_key())
+
+
+def _verify_headers(request: httpx.Request) -> bool:
+    """Reconstruct the payload from the request using the SAME convention the auth
+    used (raw_path) and verify the PoP signature against the agent public key."""
+    target = request_target(request)
+    body = request.content or b""
+    payload = build_request_auth_payload(
+        vaid_id=VAID_ID,
+        method=request.method.upper(),
+        path=target,
+        body_sha256=hashlib.sha256(body).hexdigest(),
+        tenant_id=TENANT_ID,
+        timestamp=request.headers[HEADER_TIMESTAMP],
+        client_nonce=request.headers[HEADER_NONCE],
+    )
+    digest = canonical_request_signing_bytes(payload)
+    sig = base64.b64decode(request.headers[HEADER_SIGNATURE])
+    pub = _key().public_key().public_bytes_raw()
+    try:
+        Ed25519PublicKey.from_public_bytes(pub).verify(sig, digest)
+        return True
+    except Exception:
+        return False
+
+
+def _client(handler) -> httpx.Client:
+    return httpx.Client(
+        base_url="https://api.example.com",
+        auth=VaidAuth(_signer()),
+        transport=httpx.MockTransport(handler),
+    )
+
+
+def test_all_four_headers_attached_and_signature_valid_post_with_body():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["req"] = request
+        return httpx.Response(200, text="ok")
+
+    with _client(handler) as c:
+        c.post("/vaid/mint", json={"seed": {"agentClass": "x"}})
+
+    req = captured["req"]
+    for h in (HEADER_VAID, HEADER_TIMESTAMP, HEADER_NONCE, HEADER_SIGNATURE):
+        assert h in req.headers, f"missing {h}"
+    assert _verify_headers(req), "PoP signature must verify over the signed request"
+
+
+def test_signature_covers_query_string():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["req"] = request
+        return httpx.Response(200, text="ok")
+
+    with _client(handler) as c:
+        c.post("/vaid/mint?tenant=acme&limit=10", json={})
+
+    req = captured["req"]
+    # The signed target includes the query, and it verifies.
+    assert request_target(req) == "/vaid/mint?tenant=acme&limit=10"
+    assert _verify_headers(req)
+
+
+def test_tampering_with_query_after_signing_breaks_verification():
+    """A verifier that sees a DIFFERENT query than what was signed must reject —
+    this is the property path-only signing would forfeit."""
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["req"] = request
+        return httpx.Response(200, text="ok")
+
+    with _client(handler) as c:
+        c.post("/vaid/mint?tenant=acme", json={})
+
+    req = captured["req"]
+    # Simulate a verifier reconstructing with a tampered query.
+    payload = build_request_auth_payload(
+        vaid_id=VAID_ID,
+        method="POST",
+        path="/vaid/mint?tenant=attacker",  # tampered
+        body_sha256=hashlib.sha256(req.content or b"").hexdigest(),
+        tenant_id=TENANT_ID,
+        timestamp=req.headers[HEADER_TIMESTAMP],
+        client_nonce=req.headers[HEADER_NONCE],
+    )
+    digest = canonical_request_signing_bytes(payload)
+    sig = base64.b64decode(req.headers[HEADER_SIGNATURE])
+    pub = _key().public_key().public_bytes_raw()
+    with pytest.raises(Exception):
+        Ed25519PublicKey.from_public_bytes(pub).verify(sig, digest)
+
+
+def test_body_less_get_signs_empty_body():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["req"] = request
+        return httpx.Response(200, text="ok")
+
+    with _client(handler) as c:
+        c.get("/status")
+
+    req = captured["req"]
+    assert (req.content or b"") == b""
+    assert _verify_headers(req), "a GET with no body must sign b'' and verify"
+
+
+def test_each_request_gets_a_fresh_nonce():
+    nonces = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        nonces.append(request.headers[HEADER_NONCE])
+        return httpx.Response(200, text="ok")
+
+    with _client(handler) as c:
+        c.post("/a", json={})
+        c.post("/a", json={})
+
+    assert len(nonces) == 2 and nonces[0] != nonces[1], "nonce must be per-request fresh"

vaid_langchain-0.1.0/vaid_langchain/__init__.py

@@ -0,0 +1,26 @@
+"""vaid-langchain — LangChain request-signing adapter for the VAID standard.
+
+Signs every outbound HTTP request an agent tool makes with a VAID proof-of-
+possession, via a thin ``httpx.Auth`` seam:
+
+    from vaid_pop import RequestSigner
+    from vaid_langchain import make_vaid_tool
+
+    signer = RequestSigner(vaid=my_vaid_doc, private_key=my_key)  # hand-provisioned
+    tool = make_vaid_tool(signer, base_url="https://api.example.com")
+    # give `tool` to a LangChain agent — its calls to the backend are VAID-signed.
+
+The signing lives in :class:`VaidAuth` (an ``httpx.Auth``); the LangChain tool is
+just a registration wrapper. :class:`VaidAuth` is usable standalone with any
+``httpx`` client, LangChain not required. The signed request target is the
+on-the-wire path + query (:func:`request_target`) — a security decision, see that
+function's docs.
+"""
+
+from vaid_langchain._target import request_target
+from vaid_langchain.auth import VaidAuth
+from vaid_langchain.langchain_tool import make_vaid_tool
+
+__all__ = ["VaidAuth", "make_vaid_tool", "request_target"]
+
+__version__ = "0.1.0"

vaid_langchain-0.1.0/vaid_langchain/_target.py

@@ -0,0 +1,43 @@
+"""The pinned request-target convention for VAID request signing.
+
+Investigation 3 flagged the one silent-failure landmine: the ``path`` a client
+signs must be the exact string a verifier reconstructs, and whether the query
+string is included is a convention that MUST be pinned — a mismatch rejects every
+signature (or, worse, leaves query params unsigned and tamperable).
+
+PINNED CONVENTION (permanent, a SECURITY decision — not a demo convenience): the
+signed ``path`` is the **on-the-wire request target** — the percent-encoded path
+plus ``?query`` when present — i.e. exactly what appears after the method on the
+HTTP request line. For an ``httpx`` request this is ``request.url.raw_path``
+(ASCII bytes), NOT ``request.url.path``.
+
+Signing path-only would leave the query string **outside** the signature, so an
+attacker could alter query parameters (``?tenant=…``, ``?limit=…``, ids, filters)
+under a still-valid signature. Because the query frequently carries
+authorization-relevant material, it MUST be part of the signed target. This is
+why ``raw_path`` (path + query) is the permanent convention.
+
+Why ``raw_path`` and not ``path``:
+  * ``.path`` DROPS the query string, leaving query params outside the signature
+    (an attacker can alter ``?tenant=…`` under a valid signature) — unacceptable.
+  * ``.path`` is percent-DECODED ("/a b/x"), so two distinct wire targets can map
+    to the same string — ambiguous.
+  * ``.raw_path`` is the percent-encoded path + query, deterministic and equal to
+    what a server reads from the request line — so a verifier reconstructs the
+    identical string.
+
+The Rust canonical signer binds ``path`` verbatim (no normalization), so this
+string is signed exactly as produced; the frozen operator vector's "/vaid/mint"
+(no query) is the query-absent case of this same rule.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def request_target(request: Any) -> str:
+    """The pinned signed-path string for an ``httpx.Request``: percent-encoded
+    path + query (the on-the-wire request target). ``raw_path`` is ASCII bytes;
+    decode to the ``str`` the signer/verifier bind."""
+    return request.url.raw_path.decode("ascii")

vaid_langchain-0.1.0/vaid_langchain/auth.py

@@ -0,0 +1,55 @@
+"""``VaidAuth`` — the shared httpx auth that signs any outbound request with a VAID.
+
+Agent frameworks (LangChain, CrewAI, ADK) hook at the *tool-call* layer, which is
+function-call-shaped (a name + kwargs). VAID proof-of-possession signs an *HTTP
+request* — it binds ``(method, request-target, body_sha256)``. So the clean,
+non-forking seam is NOT the framework's tool layer but the **HTTP client** the
+tool uses: an ``httpx.Auth`` subclass runs on every outbound request and attaches
+the four ``x-synthera-*`` PoP headers. This one class is the whole reusable
+adapter; a framework "adapter" is then just that framework's idiomatic way of
+registering a tool whose client carries this auth.
+
+Canonicalization/signing is NOT reimplemented here — it defers to
+``vaid_pop.RequestSigner``, so a conforming verifier derives identical bytes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Generator
+
+import httpx
+from vaid_pop import RequestSigner
+
+from vaid_langchain._target import request_target
+
+
+class VaidAuth(httpx.Auth):
+    """Signs every outbound ``httpx`` request with a VAID proof-of-possession.
+
+    Attach to any client: ``httpx.Client(auth=VaidAuth(signer))``. On each request
+    it signs ``(method, raw_path, body)`` via ``vaid_pop.RequestSigner`` and
+    attaches the four ``x-synthera-*`` headers.
+
+    ``requires_request_body = True`` is MANDATORY: without it, ``request.content``
+    is not populated inside ``auth_flow`` and the ``bodySha256`` would be computed
+    over an empty body while a non-empty body is sent — every signature would then
+    fail verification. Do not remove it.
+    """
+
+    # Tell httpx to read/buffer the request body before invoking auth_flow, so
+    # `request.content` is available here.
+    requires_request_body = True
+
+    def __init__(self, signer: RequestSigner) -> None:
+        self._signer = signer
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, Any, None]:
+        # The signed target is the on-the-wire path + query (raw_path), the pinned
+        # security convention — see `_target.request_target`.
+        target = request_target(request)
+        # Body must be bytes; a body-less request (e.g. GET) signs b"" — never
+        # None (hashlib.sha256(None) raises) and never a str.
+        body = request.content or b""
+        headers = self._signer.sign_headers(request.method, target, body)
+        request.headers.update(headers)
+        yield request

vaid_langchain-0.1.0/vaid_langchain/conformance.py

@@ -0,0 +1,191 @@
+"""Packaged path-with-query conformance check — the firewall, shipped in the wheel.
+
+Mirror of ``vaid_pop.conformance`` / ``vaid_mint.conformance``. A consumer who has
+only ``pip install vaid-langchain`` can prove the adapter they installed reproduces
+the frozen ``pathquery_v1.json`` vector byte-for-byte, using only the installed
+package (and its ``vaid-pop`` dependency under the hood)::
+
+    python -m vaid_langchain.conformance     # exit 0 = PASS, 1 = BLOCKER
+    vaid-langchain-conformance               # same, via the console entry point
+
+Programmatically::
+
+    from vaid_langchain.conformance import run
+    run()  # raises ConformanceError on any divergence; returns the vector on PASS
+
+The vector it checks is the one bundled with the package
+(``vaid_langchain/vectors/pathquery_v1.json``). The Rust ``vaid-client``
+``pathquery_conformance`` test asserts the identical vector; a repo-level
+drift-check proves the two copies are byte-identical ⇒ Rust == Python == vector.
+
+What is distinct here vs. the raw PoP firewall: this also confirms the adapter's
+own pinned request-target convention — ``request_target`` (httpx ``raw_path`` =
+percent-encoded path + query) reproduces the frozen ``path`` — before reproducing
+the digest + signature over it. That ties the byte-identity proof to the exact
+convention the adapter signs with.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from datetime import datetime, timezone
+from importlib.resources import files
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+from vaid_pop import (
+    HEADER_SIGNATURE,
+    RequestSigner,
+    build_request_auth_payload,
+    canonical_request_signing_bytes,
+)
+
+from vaid_langchain._target import request_target
+
+
+class ConformanceError(AssertionError):
+    """A cross-language byte-identity divergence — a hard BLOCKER, never ship-anyway."""
+
+
+def load_vector() -> dict:
+    """The path-with-query conformance vector bundled with the installed package."""
+    data = files("vaid_langchain").joinpath("vectors/pathquery_v1.json").read_text()
+    return json.loads(data)
+
+
+def check_target_convention(v: dict) -> None:
+    """The adapter's own request-target rule (``request_target`` = httpx raw_path)
+    reproduces the frozen `path`, and that path carries a query — the pinned,
+    security-relevant convention this vector exists to lock."""
+    path = v["input"]["path"]
+    if "?" not in path:
+        raise ConformanceError("pathquery vector's `path` must include a query string")
+    req = httpx.Request("POST", f"https://host{path}", content=b"")
+    got = request_target(req)
+    if got != path:
+        raise ConformanceError(
+            f"request_target diverged from the frozen path — BLOCKER\n"
+            f"  got    = {got}\n  vector = {path}"
+        )
+
+
+def check_digest(v: dict) -> None:
+    """Python JCS + SHA-256 over the camelCase RequestAuthPayload (path+query) ==
+    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:
+    """End-to-end: the real signer path (vaid-pop RequestSigner) over the pinned
+    request target reproduces the frozen header signature byte-for-byte."""
+    inp = v["input"]
+    seed = bytes.fromhex(v["ed25519"]["private_key_seed_hex"])
+    sk = Ed25519PrivateKey.from_private_bytes(seed)
+    signer = RequestSigner(
+        vaid={"vaid_id": inp["vaidId"], "tenant_id": inp["tenantId"]}, private_key=sk
+    )
+    # Re-derive the signed target through the adapter's own convention.
+    req = httpx.Request("POST", f"https://host{inp['path']}", content=b"")
+    target = request_target(req)
+    now = datetime.strptime(inp["timestamp"], "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    headers = signer.sign_headers(inp["method"], target, b"", now=now, nonce=inp["clientNonce"])
+
+    payload = build_request_auth_payload(
+        vaid_id=inp["vaidId"],
+        method=inp["method"].upper(),
+        path=target,
+        body_sha256=hashlib.sha256(b"").hexdigest(),
+        tenant_id=inp["tenantId"],
+        timestamp=inp["timestamp"],
+        client_nonce=inp["clientNonce"],
+    )
+    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")
+    sk.public_key().verify(sig, digest)  # raises on failure → header signature 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_target_convention(v)
+    check_digest(v)
+    check_signature(v)
+    check_request_signer(v)
+    return v
+
+
+# --- pytest discovery (so `pytest --pyargs vaid_langchain` runs the firewall) ---
+
+
+def test_packaged_target_convention_matches_frozen_vector() -> None:
+    check_target_convention(load_vector())
+
+
+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 main() -> int:
+    try:
+        v = run()
+    except ConformanceError as exc:
+        print(f"CROSS-LANGUAGE PATHQUERY FIREWALL: MISMATCH — BLOCKER\n{exc}")
+        return 1
+    print(
+        "CROSS-LANGUAGE PATHQUERY FIREWALL: PASS — installed adapter == frozen vector, "
+        "byte-for-byte\n"
+        f"  path      = {v['input']['path']}\n"
+        f"  digest    = {v['digest_sha256_hex']}\n"
+        f"  signature = {v['ed25519']['signature_hex']}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vaid_langchain-0.1.0/vaid_langchain/langchain_tool.py

@@ -0,0 +1,72 @@
+"""LangChain tool wrapper — a thin registration layer over :class:`VaidAuth`.
+
+All the signing lives in :class:`~vaid_langchain.auth.VaidAuth`; this module is
+just LangChain's idiomatic way of exposing a tool whose HTTP client carries that
+auth. :func:`make_vaid_tool` returns a LangChain ``StructuredTool`` an agent can
+call; every request the tool makes to the protected backend is VAID-signed.
+
+``langchain_core`` is imported lazily so this package (and :class:`VaidAuth`)
+imports without LangChain installed — you only need it for this wrapper.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from vaid_pop import RequestSigner
+
+from vaid_langchain.auth import VaidAuth
+
+_DEFAULT_DESCRIPTION = (
+    "Call a VAID-protected HTTP API. Pass the request `path` (e.g. '/vaid/mint', "
+    "including any ?query) and an optional JSON `payload`. The request is signed "
+    "with the agent's VAID proof-of-possession before it is sent."
+)
+
+
+def make_vaid_tool(
+    signer: RequestSigner,
+    base_url: str,
+    *,
+    name: str = "call_protected_api",
+    description: str = _DEFAULT_DESCRIPTION,
+    method: str = "POST",
+    client: httpx.Client | None = None,
+) -> Any:
+    """Build a LangChain ``StructuredTool`` that calls a VAID-protected API.
+
+    Parameters
+    ----------
+    signer:
+        A ``vaid_pop.RequestSigner`` built from the agent's minted VAID document
+        and its Ed25519 private key. Provisioning that key/VAID is the caller's
+        job — see the README; it is NOT managed by this SDK.
+    base_url:
+        Base URL of the protected backend (e.g. ``https://api.example.com``).
+    name / description:
+        Surface the tool presents to the agent/LLM.
+    method:
+        HTTP method the tool issues (default ``POST``).
+    client:
+        Optional pre-built ``httpx.Client`` (used in tests to inject a mock
+        transport). When omitted, a client bound to ``base_url`` with
+        ``VaidAuth(signer)`` is created.
+
+    Returns
+    -------
+    A ``langchain_core.tools.StructuredTool``.
+    """
+    from langchain_core.tools import StructuredTool  # lazy: LangChain optional
+
+    http = client or httpx.Client(base_url=base_url, auth=VaidAuth(signer))
+
+    def call_protected_api(path: str, payload: dict | None = None) -> str:
+        """Send a signed request to the protected API and return the response body."""
+        resp = http.request(method, path, json=payload if payload is not None else {})
+        resp.raise_for_status()
+        return resp.text
+
+    return StructuredTool.from_function(
+        call_protected_api, name=name, description=description
+    )

vaid_langchain-0.1.0/vaid_langchain/vectors/pathquery_v1.json

@@ -0,0 +1,20 @@
+{
+  "_comment": "Path-with-query conformance vector (v1). Load-bearing. `input` is a real RequestAuthPayload (camelCase) whose `path` is the on-the-wire request target INCLUDING the query string — the pinned signing convention for framework adapters (httpx `raw_path`), NOT path-only. Signing path-only would leave the query outside the signature (tamperable), so this is a security decision. A conforming signer MUST produce `digest_sha256_hex` from `input` via JCS (RFC 8785) -> SHA-256 and reproduce `ed25519.signature_hex` byte-for-byte from the seed. Same JCS→SHA-256→Ed25519 primitive as operator_pop_v1.json.",
+  "digest_sha256_hex": "b5b3c06fe6fe9a3c7ea848abd2d8d974f71f37f2373fe3bb041821ded88de755",
+  "ed25519": {
+    "_comment": "Deterministic test key (same RFC 8032 seed as operator_pop_v1.json). Any conforming implementation derives the same public key and produces the same signature over digest_sha256_hex.",
+    "private_key_seed_hex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+    "public_key_hex": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
+    "signature_hex": "eb67e1148bce0d3a3386882bf85139ef23f84a5ed876dadb992a666854afeee90d46281df65e1f96f543d1f0bd8f63ec70cbf0a141091f0c5a6bbe281d41880b"
+  },
+  "input": {
+    "bodySha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "clientNonce": "0123456789abcdef0123456789abcdef",
+    "method": "POST",
+    "path": "/vaid/mint?tenant=acme&limit=10",
+    "tenantId": "synthera-control-plane",
+    "timestamp": "2026-06-04T12:00:00Z",
+    "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"
+}