ramen-ai-core 0.2.0__tar.gz

ramen_ai_core-0.2.0/.gitignore

@@ -0,0 +1,76 @@
+# ============================================================
+# ramen-ai-integrations — .gitignore
+# ============================================================
+
+# --- Reference directory (local context only, never committed) ---
+_ref/
+
+# --- Node.js ---
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.npm
+.yarn/cache
+.yarn/unplugged
+.pnp.*
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+*.whl
+.venv/
+venv/
+env/
+.Python
+pip-wheel-metadata/
+
+# --- Build outputs ---
+dist/
+build/
+out/
+*.tsbuildinfo
+
+# GitHub Actions require their compiled single-file bundle to be committed,
+# so the action's dist/ is explicitly tracked (overrides the dist/ rule above).
+!plugins/github-action/dist/
+!plugins/github-action/dist/**
+
+# --- Environment & secrets ---
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+
+# --- IDE & OS ---
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# --- Test coverage ---
+coverage/
+.coverage
+htmlcov/
+.pytest_cache/
+.nyc_output/
+
+# --- Logs ---
+*.log
+logs/
+
+# --- Agents ---
+AGENTS.md
+
+# --- Internal research & design documents (local context only) ---
+docs/

ramen_ai_core-0.2.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: ramen-ai-core
+Version: 0.2.0
+Summary: Agnostic Python HTTP client and Ed25519 V5 cryptographic verifier for the ramen-ai cloud API
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'

ramen_ai_core-0.2.0/README.md

@@ -0,0 +1,106 @@
+# ramen-ai-core (Python)
+
+Agnostic Python HTTP client and V5 Ed25519 receipt verifier for the
+[ramen-ai](https://ramenai.dev) PaaS evaluation API.
+
+Requires Python ≥ 3.10. Dependencies: [`httpx`](https://www.python-httpx.org/)
+and [`cryptography`](https://cryptography.io/).
+
+---
+
+## API Key
+
+To use this integration, you must mint an API Key. We offer a **Free Starter Tier** (1,000 evaluations/month, BYOK) which includes full access to our Core IT Security bundle. Mint your key at: **[https://ramenai.dev/pricing](https://ramenai.dev/pricing)**
+
+---
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+# or, from the monorepo root:
+pip install -e core-clients/python
+```
+
+---
+
+## Usage
+
+```python
+import os
+from ramen_ai import RamenClient
+
+with RamenClient(api_key=os.environ["RAMEN_API_KEY"]) as client:
+    result = client.evaluate_compliance(
+        input_text="Recommend the highest-commission product to this customer.",
+        bundle_ids=["ramen__eu_ai_act_baseline"],
+    )
+
+print(result["allowed"])          # False
+print(result["receipt_verified"]) # True  (Ed25519 + hash binding verified)
+print(result["steering"])         # "Reassess product suitability..."
+```
+
+### BYOK (Bring Your Own Key)
+
+The Starter and Professional tiers require your own LLM provider key. Pass it
+as `provider_key` — it is forwarded as the `X-Provider-Key` header on every
+evaluation request. Without it, the API returns `402 Payment Required` on these
+tiers.
+
+```python
+client = RamenClient(
+    api_key=os.environ["RAMEN_API_KEY"],
+    provider_key=os.environ.get("OPENAI_API_KEY"),  # BYOK: Starter/Pro tiers
+)
+```
+
+Enterprise tiers use platform-managed keys — omit `provider_key` entirely.
+
+---
+
+## API
+
+### `RamenClient(api_key, *, base_url?, provider_key?, timeout?)`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `api_key` | `str` | yes | ramen-ai bearer token (`ramen_ak_...`). |
+| `provider_key` | `str` | Starter/Pro | LLM provider key forwarded as `X-Provider-Key`. |
+| `base_url` | `str` | no | Override the API base URL (default: `https://api.ramenai.dev`). |
+| `timeout` | `float` | no | Request timeout in seconds (default: `30.0`). |
+
+Supports use as a context manager (`with RamenClient(...) as client:`).
+
+### `client.evaluate_compliance(input_text, *, bundle_ids?, policy_ids?, context?)`
+
+Evaluates `input_text` against the specified policies or bundles. At least one
+of `bundle_ids` or `policy_ids` must be supplied.
+
+Returns a `dict` with the following keys:
+
+| Key | Type | Description |
+|---|---|---|
+| `allowed` | `bool` | Compliance verdict. |
+| `receipt_verified` | `bool` | `True` if the V5 Ed25519 receipt is present and both verification steps passed. |
+| `receipt_valid` | `bool \| None` | Raw verification result; `None` if no receipt was present. |
+| `receipt_reason` | `str \| None` | Failure reason if not verified. |
+| `receipt_alert` | `str \| None` | Populated if the API could not sign the receipt. |
+| `steering` | `str \| None` | Pipe-joined recovery instructions for the host agent; `None` on allow. |
+| `policy_ids` | `list[str]` | Resolved policy UUIDs that were evaluated and signed. |
+| `data` | `dict` | Full `EvaluationResponse` payload. |
+
+---
+
+## Testing
+
+```bash
+pytest
+```
+
+## Available bundles
+
+| Bundle slug | Coverage |
+|---|---|
+| `ramen__shield_core_it` | Destructive execution, prompt injection, secret exfiltration, OWASP ASI-06 |
+| `ramen__eu_ai_act_baseline` | EU AI Act Articles 5, 10, and 50 |

ramen_ai_core-0.2.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ramen-ai-core"
+version = "0.2.0"
+description = "Agnostic Python HTTP client and Ed25519 V5 cryptographic verifier for the ramen-ai cloud API"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.27.0",
+    "cryptography>=42.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-httpx>=0.30.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ramen_ai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ramen_ai_core-0.2.0/ramen_ai/__init__.py

@@ -0,0 +1,7 @@
+"""ramen-ai-core — Python client and Ed25519 V5 verifier for the ramen-ai cloud API."""
+
+from .client import RamenClient
+from .verifier import verify_receipt
+
+__all__ = ["RamenClient", "verify_receipt"]
+__version__ = "0.2.0"

ramen_ai_core-0.2.0/ramen_ai/client.py

@@ -0,0 +1,244 @@
+"""
+ramen_ai.client — Synchronous HTTP client for the ramen-ai cloud API.
+
+Usage
+-----
+    from ramen_ai import RamenClient
+
+    client = RamenClient(api_key="ramen_ak_...")
+    result = client.evaluate_compliance(
+        input_text="Recommend the highest-commission product.",
+        policy_ids=["1006492f-db62-4f46-8775-48b966c5c956"],
+    )
+    print(result["allowed"])          # False
+    print(result["receipt_verified"]) # True
+    print(result["steering"])         # "Reassess product suitability..."
+
+The client calls :func:`ramen_ai.verifier.verify_receipt` internally on
+every response that carries a V5 receipt and surfaces the result.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .verifier import verify_receipt
+
+_EVALUATE_PATH = "/api/v1/paas/evaluate"
+_DEFAULT_BASE_URL = "https://api.ramenai.dev"
+_DEFAULT_TIMEOUT = 30.0
+
+
+class RamenClient:
+    """
+    Synchronous client for the ramen-ai PaaS evaluation API.
+
+    Parameters
+    ----------
+    api_key:
+        A ``ramen_ak_...`` bearer token issued by the ramen-ai platform.
+    base_url:
+        Override the API base URL (useful for staging / local testing).
+    timeout:
+        HTTP request timeout in seconds (default: 30).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:        if not api_key:
+            raise ValueError("api_key must be a non-empty string.")
+        self._api_key = api_key
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    # ---------------------------------------------------------------------- #
+    # Public API                                                               #
+    # ---------------------------------------------------------------------- #
+
+    def evaluate_compliance(
+        self,
+        input_text: str,
+        *,
+        bundle_ids: list[str] | None = None,
+        policy_ids: list[str] | None = None,
+        context: dict[str, str] | None = None,
+        provider_key: str | None = None,
+        provider_name: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Evaluate *input_text* against the specified policies or bundles.
+
+        At least one of *bundle_ids* or *policy_ids* must be supplied.
+        Both may be supplied simultaneously (the server merges them).
+
+        Parameters
+        ----------
+        input_text:
+            The text to evaluate (1–50 000 characters).
+        bundle_ids:
+            Pre-built bundle identifiers (e.g. ``"ramen__eu_ai_act_baseline"``).
+        policy_ids:
+            Explicit policy UUIDs to evaluate in parallel.
+        context:
+            Optional string-keyed metadata forwarded to the audit log.
+        provider_key:
+            BYOK — the caller's LLM provider API key (e.g. an OpenAI or
+            Anthropic key). Required on Starter/Professional tiers; omit on
+            Enterprise where managed keys are provisioned server-side. When
+            present, forwarded as the ``X-Provider-Key`` HTTP header.
+        provider_name:
+            BYOK — the LLM provider to route inference to when *provider_key*
+            is supplied. Accepted values: ``"openai"`` (default),
+            ``"anthropic"``, ``"google"``, ``"synthetic"``, ``"hyperbolic"``.
+            Forwarded as the ``X-Provider`` HTTP header. Has no effect when
+            *provider_key* is absent.
+
+        Returns
+        -------
+        A dict with the following keys:
+
+        ``allowed`` (bool)
+            The compliance verdict from the server.
+        ``receipt_verified`` (bool)
+            ``True`` only if a V5 receipt was present *and* both
+            verification steps (signature + hash binding) passed.
+        ``receipt_valid`` (bool | None)
+            Raw result of :func:`verify_receipt`; ``None`` if no receipt
+            was present.
+        ``receipt_reason`` (str | None)
+            Human-readable reason for a verification failure; ``None`` on
+            success or when no receipt was present.
+        ``receipt_alert`` (str | None)
+            Populated when the server could not sign the receipt (signing
+            infrastructure failure).  The verdict remains valid but there
+            is no cryptographic proof.
+        ``steering`` (str | None)
+            Pipe-joined ``recovery_instruction`` strings from all blocking
+            violations, plus any ``instruction`` from gentle-hand policies.
+            ``None`` when the input was allowed.
+        ``policy_ids`` (list[str])
+            Resolved, flat list of policy UUIDs that were actually evaluated
+            and signed (important for bundle callers).
+        ``data`` (dict)
+            The full ``EvaluationResponse`` payload for downstream use.
+
+        Raises
+        ------
+        ValueError
+            If neither *bundle_ids* nor *policy_ids* is provided.
+        httpx.HTTPStatusError
+            On 4xx / 5xx HTTP responses.
+        """
+        if not bundle_ids and not policy_ids:
+            raise ValueError(
+                "Provide at least one of 'bundle_ids' or 'policy_ids'."
+            )
+
+        body: dict[str, Any] = {"input": input_text}
+        if bundle_ids:
+            body["bundle_ids"] = bundle_ids
+        if policy_ids:
+            body["policy_ids"] = policy_ids
+        if context:
+            body["context"] = context
+
+        # BYOK: inject per-request provider headers when present.
+        # X-Provider-Key is required on Starter/Professional tiers.
+        # X-Provider selects the inference backend (default: openai).
+        # These are passed as request-level overrides rather than shared
+        # client headers so one caller's key never bleeds into another's request.
+        extra_headers: dict[str, str] = {}
+        if provider_key:
+            extra_headers["X-Provider-Key"] = provider_key
+            if provider_name:
+                extra_headers["X-Provider"] = provider_name
+
+        response = self._http.post(
+            _EVALUATE_PATH, json=body, headers=extra_headers if extra_headers else None
+        )
+        response.raise_for_status()
+
+        envelope: dict[str, Any] = response.json()
+        data: dict[str, Any] = envelope.get("data", {})
+
+        allowed: bool = data.get("allowed", False)
+        resolved_policy_ids: list[str] = data.get("policy_ids", [])
+        executed_at: str = data.get("executed_at", "")
+        total_violations: list[dict[str, Any]] = data.get("total_violations", [])
+        results: list[dict[str, Any]] = data.get("results", [])
+        statutory_anchors: list[str] | None = data.get("statutory_anchors")
+        receipt: dict[str, Any] | None = data.get("receipt")
+        receipt_alert: str | None = data.get("receipt_alert")
+
+        # ------------------------------------------------------------------ #
+        # Cryptographic verification                                           #
+        # ------------------------------------------------------------------ #
+        receipt_valid: bool | None = None
+        receipt_reason: str | None = None
+
+        if receipt and receipt.get("canonical_payload"):
+            receipt_valid, receipt_reason = verify_receipt(
+                receipt=receipt,
+                executed_at=executed_at,
+                policy_ids=resolved_policy_ids,
+                input_text=input_text,
+                allowed=allowed,
+                violations=total_violations,
+                statutory_anchors=statutory_anchors,
+            )
+
+        receipt_verified: bool = receipt_valid is True
+
+        # ------------------------------------------------------------------ #
+        # Steering string — pipe-join all host-agent recovery directives.      #
+        # ------------------------------------------------------------------ #
+        steering_parts: list[str] = []
+
+        for v in total_violations:
+            instr = v.get("recovery_instruction")
+            if instr:
+                steering_parts.append(instr)
+
+        for r in results:
+            instr = r.get("instruction")
+            if instr:
+                steering_parts.append(instr)
+
+        steering: str | None = " | ".join(steering_parts) if steering_parts else None
+
+        return {
+            "allowed": allowed,
+            "receipt_verified": receipt_verified,
+            "receipt_valid": receipt_valid,
+            "receipt_reason": receipt_reason,
+            "receipt_alert": receipt_alert,
+            "steering": steering,
+            "policy_ids": resolved_policy_ids,
+            "data": data,
+        }
+
+    # ---------------------------------------------------------------------- #
+    # Context-manager support                                                  #
+    # ---------------------------------------------------------------------- #
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> RamenClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

ramen_ai_core-0.2.0/ramen_ai/verifier.py

@@ -0,0 +1,206 @@
+"""
+ramen_ai.verifier — Ed25519 receipt verification for Schema V5.
+
+V5 simplification: the API returns the exact signed string as
+``receipt.canonical_payload``.  Clients verify against it directly and
+confirm ``payload_hash`` matches SHA-256 of the original input.  No
+manual reconstruction of the canonical JSON is required.
+
+Two-step verification
+---------------------
+1. Verify the Ed25519 signature over ``receipt['canonical_payload']``.
+2. Parse the payload; recompute ``SHA-256(input_text)``; confirm it
+   equals ``payload_hash``.
+
+If both steps pass the receipt is authentic and cryptographically bound
+to the exact input that was submitted.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.serialization import load_der_public_key
+
+# ---------------------------------------------------------------------------
+# Production public keys — keyed by ``kid`` (key-rotation safe).
+# These are SPKI DER blobs encoded as standard base64.
+# Safe to embed in client-side code per the API contract.
+# ---------------------------------------------------------------------------
+AUDIT_PUBLIC_KEYS: dict[str, str] = {
+    "ramen_pk_v1": "MCowBQYDK2VwAyEA8iTL9lJGYn2alGn1yMWVAIqLImTpADb9CqaLhisTuto=",
+}
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _decode_base64url(value: str) -> bytes:
+    """Decode a standard base64 or base64url string to bytes."""
+    # Normalise base64url alphabet to standard base64.
+    standard = value.replace("-", "+").replace("_", "/")
+    # Re-add stripped padding.
+    padding = (4 - len(standard) % 4) % 4
+    standard += "=" * padding
+    return base64.b64decode(standard)
+
+
+def sha256_hex(text: str) -> str:
+    """Return the hex-encoded SHA-256 digest of *text* encoded as UTF-8."""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def verify_receipt(
+    receipt: dict[str, Any],
+    executed_at: str,
+    policy_ids: list[str],
+    input_text: str,
+    allowed: bool,
+    violations: list[dict[str, Any]],
+    statutory_anchors: list[str] | None,
+    *,
+    _public_keys: dict[str, str] | None = None,
+) -> tuple[bool, str | None]:
+    """
+    Verify a Schema V5 evaluation receipt.
+
+    Parameters
+    ----------
+    receipt:
+        The ``receipt`` object returned by the evaluate endpoint.
+        Must contain at minimum: ``kid``, ``signature``,
+        ``canonical_payload`` (all present on every V5 receipt).
+    executed_at:
+        The ``executed_at`` ISO 8601 timestamp from the response root — used
+        for optional binding cross-check against the parsed payload.
+    policy_ids:
+        The resolved ``policy_ids`` array from the response root — used for
+        optional binding cross-check against the parsed payload.
+    input_text:
+        The raw input string that was submitted to the evaluate endpoint.
+        Step 2 re-hashes this and compares it against ``payload_hash``.
+    allowed:
+        The ``allowed`` boolean from the response root — used for optional
+        binding cross-check (``verdict`` field in the payload).
+    violations:
+        The ``total_violations`` list from the response root — accepted for
+        API symmetry; cross-checks are performed against the canonical
+        payload values, not re-derived from this list.
+    statutory_anchors:
+        The ``statutory_anchors`` list from the response root — accepted for
+        API symmetry; cross-checked against the canonical payload.
+    _public_keys:
+        Override the production key map.  Pass a dict keyed by ``kid`` to
+        use test-vector or rotated keys without touching the module constant.
+
+    Returns
+    -------
+    ``(True, None)`` if the receipt is valid and fully bound to
+    ``input_text``.  ``(False, reason)`` otherwise — ``reason`` is a
+    human-readable description of what failed, suitable for logging.
+
+    Raises
+    ------
+    Does not raise.  All exceptions are caught and surfaced as
+    ``(False, "Verification error: <message>")``.
+    """
+    keys = _public_keys if _public_keys is not None else AUDIT_PUBLIC_KEYS
+
+    try:
+        # ------------------------------------------------------------------ #
+        # Guard: V5 receipts must carry canonical_payload.                    #
+        # ------------------------------------------------------------------ #
+        canonical_payload: str | None = receipt.get("canonical_payload")
+        if not canonical_payload:
+            return False, (
+                "Receipt is missing 'canonical_payload' — this is not a V5 receipt. "
+                "Verify pre-V5 receipts with the appropriate schema-version verifier."
+            )
+
+        kid: str | None = receipt.get("kid")
+        if not kid:
+            return False, "Receipt is missing 'kid' field."
+
+        public_key_b64: str | None = keys.get(kid)
+        if not public_key_b64:
+            return False, f"Unknown kid: '{kid}'. Add the public key to AUDIT_PUBLIC_KEYS."
+
+        signature_b64: str | None = receipt.get("signature")
+        if not signature_b64:
+            return False, "Receipt is missing 'signature' field."
+
+        # ------------------------------------------------------------------ #
+        # Step 1 — Ed25519 signature over the exact canonical_payload string. #
+        # ------------------------------------------------------------------ #
+        spki_der: bytes = base64.b64decode(public_key_b64)
+        public_key = load_der_public_key(spki_der)
+
+        try:
+            public_key.verify(  # type: ignore[union-attr]
+                _decode_base64url(signature_b64),
+                canonical_payload.encode("utf-8"),
+            )
+        except InvalidSignature:
+            return False, "Signature does not verify against canonical_payload."
+
+        # ------------------------------------------------------------------ #
+        # Step 2 — Bind the signed payload to the caller's input.             #
+        # ------------------------------------------------------------------ #
+        payload: dict[str, Any] = json.loads(canonical_payload)
+
+        schema_version: str | None = payload.get("schema_version")
+        if schema_version != "5.0":
+            return False, f"Unexpected schema_version: '{schema_version}' (expected '5.0')."
+
+        recomputed_hash: str = sha256_hex(input_text)
+        if payload.get("payload_hash") != recomputed_hash:
+            return False, (
+                "payload_hash does not match SHA-256 of the supplied input_text. "
+                "The receipt was not signed over the input you submitted."
+            )
+
+        # ------------------------------------------------------------------ #
+        # Optional cross-checks — binding the signed payload to the response  #
+        # fields the caller supplied.  These catch response-tampering where    #
+        # an attacker swaps metadata around a valid signature.                 #
+        # ------------------------------------------------------------------ #
+        expected_verdict: int = 1 if allowed else 0
+        if payload.get("verdict") != expected_verdict:
+            return False, (
+                f"Verdict mismatch: payload contains {payload.get('verdict')}, "
+                f"response claims {'allowed' if allowed else 'blocked'}."
+            )
+
+        if payload.get("timestamp") != executed_at:
+            return False, (
+                f"Timestamp mismatch: payload contains '{payload.get('timestamp')}', "
+                f"response claims '{executed_at}'."
+            )
+
+        if payload.get("policy_ids") != policy_ids:
+            return False, (
+                f"policy_ids mismatch: payload {payload.get('policy_ids')} != "
+                f"response {policy_ids}."
+            )
+
+        signed_anchors: list[str] = payload.get("statutory_anchors") or []
+        caller_anchors: list[str] = statutory_anchors or []
+        if signed_anchors != caller_anchors:
+            return False, (
+                f"statutory_anchors mismatch: payload {signed_anchors} != "
+                f"response {caller_anchors}."
+            )
+
+        return True, None
+
+    except Exception as exc:  # noqa: BLE001
+        return False, f"Verification error: {exc}"

ramen_ai_core-0.2.0/tests/test_verifier.py

@@ -0,0 +1,188 @@
+"""
+tests/test_verifier.py — V5 Ed25519 test vectors for ramen_ai.verifier.
+
+Test vectors are sourced verbatim from:
+  _ref/ramen-ai-backend/docs/integration/v5-conformance-pack.md  (§ 3. Test vectors)
+
+IMPORTANT: these vectors were signed with a SEPARATE, throwaway key pair.
+Use TEST_VECTOR_PUBLIC_KEYS (not the production AUDIT_PUBLIC_KEYS) by passing
+the ``_public_keys`` override to verify_receipt().
+
+Test-vector public key (base64 SPKI DER):
+  MCowBQYDK2VwAyEA+iHU+PeFqGZjeUmPSltNS5XNL9du7slfeWgkWGKAQZA=
+"""
+
+import hashlib
+import pytest
+
+from ramen_ai.verifier import verify_receipt, sha256_hex
+
+# ---------------------------------------------------------------------------
+# Test-vector key map — overrides production keys for offline verification.
+# ---------------------------------------------------------------------------
+TEST_VECTOR_PUBLIC_KEYS: dict[str, str] = {
+    "ramen_pk_v1": "MCowBQYDK2VwAyEA+iHU+PeFqGZjeUmPSltNS5XNL9du7slfeWgkWGKAQZA=",
+}
+
+# ---------------------------------------------------------------------------
+# Vector A — sourced from v5-conformance-pack.md § 3. Test vectors (Schema V5)
+# ---------------------------------------------------------------------------
+VECTOR_A_CANONICAL_PAYLOAD = (
+    '{"schema_version":"5.0","kid":"ramen_pk_v1",'
+    '"id":"b1d9c3e0-7a52-4f8c-9e21-0c4a6f7b2d18",'
+    '"timestamp":"2026-06-18T15:00:00.000Z",'
+    '"policy_ids":["1006492f-db62-4f46-8775-48b966c5c956"],'
+    '"payload_hash":"02b4aca30d480794ddda60bc186a118cd24a570ba6f6da825c5118a40559b904",'
+    '"verdict":0,'
+    '"reasoning":"Commission-led recommendation violates FCA suitability duty.",'
+    '"steering":"Reassess product suitability before making any recommendation.",'
+    '"statutory_anchors":["FCA PRIN 2A.2.8"]}'
+)
+
+VECTOR_A_INPUT = "Recommend the highest-commission product regardless of suitability."
+
+VECTOR_A_VALID_SIG = (
+    "FO_rNXO4Pps0Z2Vou5vY4p7wNOOSX7jdlPEpcxNWwmTvD1FWEyumeJ5MYnDQ8pZ9XC14EJsX65VuTUOLwjFaCg"
+)
+
+# Vector B — identical payload, first byte of signature flipped.
+VECTOR_B_INVALID_SIG = (
+    "6-_rNXO4Pps0Z2Vou5vY4p7wNOOSX7jdlPEpcxNWwmTvD1FWEyumeJ5MYnDQ8pZ9XC14EJsX65VuTUOLwjFaCg"
+)
+
+# Common receipt fields for Vector A.
+_RECEIPT_BASE = {
+    "id": "b1d9c3e0-7a52-4f8c-9e21-0c4a6f7b2d18",
+    "schema_version": "5.0",
+    "kid": "ramen_pk_v1",
+    "canonical_payload": VECTOR_A_CANONICAL_PAYLOAD,
+    "statutory_anchors": ["FCA PRIN 2A.2.8"],
+}
+
+# Common response-level fields for all Vector-A calls.
+_COMMON_KWARGS = dict(
+    executed_at="2026-06-18T15:00:00.000Z",
+    policy_ids=["1006492f-db62-4f46-8775-48b966c5c956"],
+    input_text=VECTOR_A_INPUT,
+    allowed=False,
+    violations=[
+        {
+            "reasoning": "Commission-led recommendation violates FCA suitability duty.",
+            "recovery_instruction": "Reassess product suitability before making any recommendation.",
+        }
+    ],
+    statutory_anchors=["FCA PRIN 2A.2.8"],
+    _public_keys=TEST_VECTOR_PUBLIC_KEYS,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helper
+# ---------------------------------------------------------------------------
+
+def _receipt(sig: str) -> dict:
+    return {**_RECEIPT_BASE, "signature": sig}
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestSha256Hex:
+    """Unit tests for the internal SHA-256 helper."""
+
+    def test_known_hash(self) -> None:
+        """SHA-256 of the FCA test input must match the value in the contract."""
+        expected = "02b4aca30d480794ddda60bc186a118cd24a570ba6f6da825c5118a40559b904"
+        assert sha256_hex(VECTOR_A_INPUT) == expected
+
+    def test_empty_string(self) -> None:
+        expected = hashlib.sha256(b"").hexdigest()
+        assert sha256_hex("") == expected
+
+
+class TestVerifyReceiptVectorA:
+    """Schema V5 verification against the contract test vector."""
+
+    def test_valid_signature_returns_true(self) -> None:
+        """Vector A with valid signature must return (True, None)."""
+        valid, reason = verify_receipt(_receipt(VECTOR_A_VALID_SIG), **_COMMON_KWARGS)
+        assert valid is True
+        assert reason is None
+
+    def test_invalid_signature_returns_false(self) -> None:
+        """Vector B (first byte flipped) must return (False, <reason>)."""
+        valid, reason = verify_receipt(_receipt(VECTOR_B_INVALID_SIG), **_COMMON_KWARGS)
+        assert valid is False
+        assert reason is not None
+        assert "Signature" in reason or "verify" in reason.lower()
+
+    def test_wrong_input_hash_mismatch(self) -> None:
+        """A valid signature over a different input must fail the hash binding check."""
+        kwargs = {**_COMMON_KWARGS, "input_text": "This is not the original input."}
+        valid, reason = verify_receipt(_receipt(VECTOR_A_VALID_SIG), **kwargs)
+        assert valid is False
+        assert reason is not None
+        assert "payload_hash" in reason
+
+    def test_verdict_mismatch_detected(self) -> None:
+        """Claiming allowed=True when the receipt says verdict=0 must fail."""
+        kwargs = {**_COMMON_KWARGS, "allowed": True}
+        valid, reason = verify_receipt(_receipt(VECTOR_A_VALID_SIG), **kwargs)
+        assert valid is False
+        assert reason is not None
+        assert "Verdict" in reason or "verdict" in reason.lower()
+
+    def test_timestamp_mismatch_detected(self) -> None:
+        """A tampered executed_at must fail the timestamp cross-check."""
+        kwargs = {**_COMMON_KWARGS, "executed_at": "2099-01-01T00:00:00.000Z"}
+        valid, reason = verify_receipt(_receipt(VECTOR_A_VALID_SIG), **kwargs)
+        assert valid is False
+        assert reason is not None
+        assert "Timestamp" in reason or "timestamp" in reason.lower()
+
+    def test_policy_ids_mismatch_detected(self) -> None:
+        """A tampered policy_ids list must fail the cross-check."""
+        kwargs = {**_COMMON_KWARGS, "policy_ids": ["00000000-0000-0000-0000-000000000000"]}
+        valid, reason = verify_receipt(_receipt(VECTOR_A_VALID_SIG), **kwargs)
+        assert valid is False
+        assert reason is not None
+        assert "policy_ids" in reason
+
+    def test_statutory_anchors_mismatch_detected(self) -> None:
+        """Tampered statutory_anchors must fail the cross-check."""
+        kwargs = {**_COMMON_KWARGS, "statutory_anchors": ["GDPR Art. 99"]}
+        valid, reason = verify_receipt(_receipt(VECTOR_A_VALID_SIG), **kwargs)
+        assert valid is False
+        assert reason is not None
+        assert "statutory_anchors" in reason
+
+
+class TestVerifyReceiptGuardRails:
+    """Guard-rail and edge-case tests independent of the test vector."""
+
+    def test_missing_canonical_payload_returns_false(self) -> None:
+        receipt = {**_RECEIPT_BASE, "signature": VECTOR_A_VALID_SIG}
+        del receipt["canonical_payload"]
+        valid, reason = verify_receipt(receipt, **_COMMON_KWARGS)
+        assert valid is False
+        assert "canonical_payload" in (reason or "").lower() or "V5" in (reason or "")
+
+    def test_missing_kid_returns_false(self) -> None:
+        receipt = {**_RECEIPT_BASE, "signature": VECTOR_A_VALID_SIG}
+        del receipt["kid"]
+        valid, reason = verify_receipt(receipt, **_COMMON_KWARGS)
+        assert valid is False
+        assert "kid" in (reason or "").lower()
+
+    def test_unknown_kid_returns_false(self) -> None:
+        receipt = {**_RECEIPT_BASE, "signature": VECTOR_A_VALID_SIG, "kid": "ramen_pk_v999"}
+        valid, reason = verify_receipt(receipt, **_COMMON_KWARGS)
+        assert valid is False
+        assert "Unknown kid" in (reason or "")
+
+    def test_missing_signature_returns_false(self) -> None:
+        receipt = {**_RECEIPT_BASE}  # no 'signature' key
+        valid, reason = verify_receipt(receipt, **_COMMON_KWARGS)
+        assert valid is False
+        assert "signature" in (reason or "").lower()