Upload folder using huggingface_hub

alembic/versions/e4a7c1f9b3d2_create_onchain_rationales_table.py

@@ -0,0 +1,62 @@
+"""create onchain_rationales table
+
+Stores the plaintext preimage of an anchored `RiskAttestation.rationale_hash`
+(arf-onchain's RiskAttestationRegistry / enterprise's
+arf_enterprise.onchain.attestation). The chain only ever holds the hash --
+see models_onchain.py's module docstring for why the text has to live here,
+keyed by that same hash, or the anchored hash is unverifiable.
+
+Revision ID: e4a7c1f9b3d2
+Revises: a1f3c9d2e6b7
+Create Date: 2026-09-07 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "e4a7c1f9b3d2"
+down_revision: Union[str, Sequence[str], None] = "a1f3c9d2e6b7"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.create_table(
+        "onchain_rationales",
+        sa.Column("id", sa.String(length=64), nullable=False),
+        sa.Column("rationale_hash", sa.String(length=66), nullable=False),
+        sa.Column("rationale", sa.Text(), nullable=False),
+        sa.Column("agent_address", sa.String(length=42), nullable=True),
+        sa.Column("evaluator_address", sa.String(length=42), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_onchain_rationales_rationale_hash"),
+        "onchain_rationales",
+        ["rationale_hash"],
+        unique=True,
+    )
+    op.create_index(
+        op.f("ix_onchain_rationales_created_at"),
+        "onchain_rationales",
+        ["created_at"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_index(
+        op.f("ix_onchain_rationales_created_at"), table_name="onchain_rationales"
+    )
+    op.drop_index(
+        op.f("ix_onchain_rationales_rationale_hash"), table_name="onchain_rationales"
+    )
+    op.drop_table("onchain_rationales")

app/api/routes_onchain.py

@@ -0,0 +1,143 @@
+"""Routes for on-chain attestation rationale.
+
+`RiskAttestationRegistry` (arf-onchain) anchors only a `rationale_hash` --
+never the reasoning itself, to keep operational detail about a customer's
+infrastructure off a public chain. These endpoints are the off-chain half:
+a reference risk evaluator (`arf_enterprise.onchain.evaluator`) persists the
+plaintext here immediately after signing an attestation, keyed by the same
+hash it put on-chain, and an auditor who reads a `DecisionAnchored` or
+`AttestationIssued` event can fetch the reasoning behind it here.
+
+Internal-key gated like `routes_governance.py`: this is a service-to-service
+surface for the evaluator process and for auditor tooling, not a
+tenant-scoped customer endpoint -- see `OnchainRationaleDB`'s docstring for
+why there is no tenant_id to enforce here.
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, field_validator
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_db, verify_internal_key
+from app.database.models_onchain import OnchainRationaleDB
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(verify_internal_key)])
+
+
+def _validate_hex_hash(value: str) -> str:
+    text = value.strip()
+    if not text.startswith("0x") or len(text) != 66:
+        raise ValueError("rationale_hash must be a 0x-prefixed 32-byte hex string")
+    try:
+        int(text, 16)
+    except ValueError:
+        raise ValueError("rationale_hash is not valid hex") from None
+    return text.lower()
+
+
+class RationaleRequest(BaseModel):
+    rationale_hash: str
+    rationale: str
+    agent_address: str | None = None
+    evaluator_address: str | None = None
+
+    @field_validator("rationale_hash")
+    @classmethod
+    def _validate_hash(cls, value: str) -> str:
+        return _validate_hex_hash(value)
+
+    @field_validator("rationale")
+    @classmethod
+    def _validate_rationale(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("rationale must not be empty")
+        return value
+
+
+class RationaleResponse(BaseModel):
+    rationale_hash: str
+    rationale: str
+    agent_address: str | None
+    evaluator_address: str | None
+
+
+@router.post("/onchain/rationale", status_code=201)
+async def persist_rationale(
+    req: RationaleRequest,
+    db: Session = Depends(get_db),
+):
+    """Store the plaintext behind an anchored `rationale_hash`.
+
+    Idempotent on `rationale_hash`: signing the same decision twice (a
+    retry after a network error, for instance) posts the same hash and
+    text, so the second call is a no-op rather than a uniqueness-constraint
+    error. A *different* text arriving for a hash already on record is
+    refused -- that would mean either hash collision or a caller bug, and
+    silently overwriting an anchored record's preimage is the one thing
+    this table must never do.
+    """
+    existing = (
+        db.query(OnchainRationaleDB)
+        .filter(OnchainRationaleDB.rationale_hash == req.rationale_hash)
+        .one_or_none()
+    )
+    if existing is not None:
+        if existing.rationale != req.rationale:
+            raise HTTPException(
+                status_code=409,
+                detail=(
+                    "rationale_hash already recorded with different text; "
+                    "an anchored hash's preimage cannot be overwritten"
+                ),
+            )
+        return {"status": "already_recorded", "rationale_hash": req.rationale_hash}
+
+    row = OnchainRationaleDB(
+        rationale_hash=req.rationale_hash,
+        rationale=req.rationale,
+        agent_address=req.agent_address,
+        evaluator_address=req.evaluator_address,
+    )
+    db.add(row)
+    db.commit()
+    logger.info("persisted rationale for hash %s", req.rationale_hash)
+    return {"status": "recorded", "rationale_hash": req.rationale_hash}
+
+
+@router.get("/onchain/rationale/{rationale_hash}", response_model=RationaleResponse)
+async def get_rationale(
+    rationale_hash: str,
+    db: Session = Depends(get_db),
+):
+    """Fetch the plaintext behind an anchored `rationale_hash`.
+
+    What an auditor calls after reading a `DecisionAnchored` event off-chain
+    -- the hash from the event is the only key this endpoint accepts, by
+    design: there is no listing or search here, only lookup by the exact
+    value that was signed and anchored.
+    """
+    try:
+        normalized = _validate_hex_hash(rationale_hash)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    row = (
+        db.query(OnchainRationaleDB)
+        .filter(OnchainRationaleDB.rationale_hash == normalized)
+        .one_or_none()
+    )
+    if row is None:
+        raise HTTPException(
+            status_code=404, detail="no rationale recorded for this hash"
+        )
+
+    return RationaleResponse(
+        rationale_hash=row.rationale_hash,
+        rationale=row.rationale,
+        agent_address=row.agent_address,
+        evaluator_address=row.evaluator_address,
+    )

app/database/models_onchain.py

@@ -0,0 +1,54 @@
+"""Database models for on-chain governance attestations.
+
+``RiskAttestation.rationale_hash`` (see arf-onchain's ``AttestationLib.sol``
+and enterprise's ``arf_enterprise.onchain.attestation``) is a ``keccak256``
+digest anchored on Monad -- the chain deliberately never stores the rationale
+text itself, only its hash, to keep operational detail about a customer's
+infrastructure off a public ledger. That means the text has to live
+somewhere off-chain, keyed by the same hash, or the anchored hash proves
+nothing: nobody could ever produce the preimage to check it against.
+
+This table is that store. It is intentionally separate from
+``DecisionAuditLogDB`` (``models_intents.py``) rather than an extension of
+it: that table is written for every governance decision, on-chain or not,
+and already has its own signature column for a different purpose (Ed25519
+intent-signing, not the secp256k1 EIP-712 signature the guard verifies).
+Conflating the two would mean a column that is only sometimes meaningful
+depending on whether the decision was ever attested on-chain.
+"""
+
+import uuid
+import datetime
+
+from sqlalchemy import Column, String, DateTime, Text
+
+from .base import Base
+
+
+class OnchainRationaleDB(Base):
+    """The plaintext preimage of an anchored ``rationale_hash``.
+
+    Keyed by the hash itself (unique, indexed) rather than by an
+    auto-incrementing id: a lookup always starts from a hash read off-chain
+    (from `DecisionAnchored` or `AttestationIssued`), never from a row id
+    nothing on-chain knows about.
+
+    No ``tenant_id`` / foreign key to ``tenants``: an on-chain agent is
+    identified by its wallet address, not by this service's tenant concept,
+    and the two are not yet bridged. `evaluator_address` and `agent_address`
+    are recorded instead so a row can still be attributed and audited
+    without assuming a tenant relationship that may not exist.
+    """
+
+    __tablename__ = "onchain_rationales"
+
+    id = Column(String(64), primary_key=True, default=lambda: str(uuid.uuid4()))
+    rationale_hash = Column(
+        String(66), nullable=False, unique=True, index=True
+    )  # "0x" + 64 hex chars
+    rationale = Column(Text, nullable=False)
+    agent_address = Column(String(42), nullable=True)
+    evaluator_address = Column(String(42), nullable=True)
+    created_at = Column(
+        DateTime, default=datetime.datetime.utcnow, nullable=False, index=True
+    )

app/main.py

@@ -91,6 +91,7 @@ from app.api import (
     routes_history,
     routes_incidents,
     routes_intents,
+    routes_onchain,
     routes_risk,
     routes_memory,
     routes_admin,
@@ -491,6 +492,9 @@ def create_app() -> FastAPI:
     app.include_router(
         routes_governance.router, prefix="/api/v1", tags=["governance"]
     )
+    app.include_router(
+        routes_onchain.router, prefix="/api/v1", tags=["onchain"]
+    )
     app.include_router(
         routes_memory.router, prefix="/v1/memory", tags=["memory"]
     )

tests/test_routes_onchain.py

@@ -0,0 +1,82 @@
+"""Tests for POST/GET /api/v1/onchain/rationale.
+
+`verify_internal_key` and `get_db` are already overridden in conftest.py the
+same way every other route test relies on -- this exercises the endpoint's
+own logic (idempotent-on-hash write, conflict on a differing text, 404 on an
+unknown hash, hash format validation), not authentication or the database
+layer itself.
+"""
+
+VALID_HASH = "0x" + "ab" * 32
+
+
+def _post(
+    client,
+    rationale_hash=VALID_HASH,
+    rationale="the volume's final backup was skipped",
+    **extra,
+):
+    payload = {"rationale_hash": rationale_hash, "rationale": rationale, **extra}
+    return client.post("/api/v1/onchain/rationale", json=payload)
+
+
+class TestPersistRationale:
+    def test_a_new_hash_is_recorded(self, client):
+        resp = _post(client)
+        assert resp.status_code == 201, resp.text
+        assert resp.json() == {"status": "recorded", "rationale_hash": VALID_HASH}
+
+    def test_posting_the_same_hash_and_text_again_is_a_no_op(self, client):
+        first = _post(client)
+        assert first.status_code == 201
+        second = _post(client)
+        assert second.status_code == 200
+        assert second.json()["status"] == "already_recorded"
+
+    def test_the_same_hash_with_different_text_is_refused(self, client):
+        first = _post(client)
+        assert first.status_code == 201
+        second = _post(client, rationale="a different reason entirely")
+        assert second.status_code == 409
+
+    def test_a_malformed_hash_is_rejected(self, client):
+        resp = _post(client, rationale_hash="not-a-hash")
+        assert resp.status_code == 422
+
+    def test_a_short_hash_is_rejected(self, client):
+        resp = _post(client, rationale_hash="0x" + "ab" * 16)
+        assert resp.status_code == 422
+
+    def test_empty_rationale_is_rejected(self, client):
+        resp = _post(client, rationale="   ")
+        assert resp.status_code == 422
+
+    def test_agent_and_evaluator_addresses_are_stored(self, client):
+        resp = _post(
+            client,
+            rationale_hash="0x" + "cd" * 32,
+            agent_address="0x00000000000000000000000000000000000000A1",
+            evaluator_address="0x00000000000000000000000000000000000000B2",
+        )
+        assert resp.status_code == 201
+        fetched = client.get(f"/api/v1/onchain/rationale/{'0x' + 'cd' * 32}")
+        assert fetched.status_code == 200
+        body = fetched.json()
+        assert body["agent_address"] == "0x00000000000000000000000000000000000000A1"
+        assert body["evaluator_address"] == "0x00000000000000000000000000000000000000B2"
+
+
+class TestGetRationale:
+    def test_fetching_a_recorded_hash_returns_its_text(self, client):
+        _post(client)
+        resp = client.get(f"/api/v1/onchain/rationale/{VALID_HASH}")
+        assert resp.status_code == 200
+        assert resp.json()["rationale"] == "the volume's final backup was skipped"
+
+    def test_fetching_an_unknown_hash_is_404(self, client):
+        resp = client.get(f"/api/v1/onchain/rationale/{'0x' + 'ef' * 32}")
+        assert resp.status_code == 404
+
+    def test_fetching_a_malformed_hash_is_422_not_404(self, client):
+        resp = client.get("/api/v1/onchain/rationale/not-a-hash")
+        assert resp.status_code == 422