ProofedMesh/services/verification-service/README.md

verification-service

Phase-1 Verifier for the ProofedMesh two-stage trust chain (approval → transform) per DEV-612, parent DEV-606.

Validates an end-to-end chain for sink:dummy-sink and reserves a decision_id exactly once so a replayed sink delivery can be refused without re-running the signature math.

Endpoint

POST /api/v1/verify/chain
Content-Type: application/json

{
  "decision_id":   "dec-123",
  "approval_ref":  "sha256:<64-hex>",
  "transform_ref": "sha256:<64-hex>",
  "payload_hash":  "sha256:<64-hex>",
  "sink_target":   "sink:dummy-sink"
}

Response (always 200 unless the TLog is unreachable):

{
  "valid":        true | false,
  "replay":       true | false,
  "decision_id":  "dec-123",
  "actors":       ["trust-api/approval-signer-2026-q4", "trust-api/agent-testagent-transform-2026-q4"],
  "approval_ref": "sha256:…",
  "transform_ref": "sha256:…",
  "reasons":      ["<reason code>", …]
}

The sink (dummy-sink) maps replay: true to 409 Conflict and the rest of valid: false to 403 Forbidden; the verification-service itself only uses non-200 status codes for transport failures (502 when the transparency-log is unavailable, 400 for malformed bodies).

The handler also accepts target_sink as a legacy alias for sink_target so the DEV-612 scope wording stays wire-compatible.

Chain rules (hard-coded, Phase 1)

In order; the first failure wins and populates reasons:

1. DSSE signatures.
   • Approval signed by trust-api/approval-signer-2026-q4 (configurable via APPROVAL_SIGNER_KEY_ID).
   • Transform signed by trust-api/agent-testagent-transform-2026-q4 (configurable via TRANSFORM_SIGNER_KEY_ID).
   • Public keys loaded from VERIFICATION_SIGNER_KEYS as a comma- / newline-separated spec: trust-api/approval-signer-2026-q4=pem:<PEM>,trust-api/agent-testagent-transform-2026-q4=hex:<64-hex>. Supported encodings: pem, hex, b64, b64u.
2. Transparency-log inclusion proofs. RFC 6962 §2.1.1; the proof returned by the TLog must close against the tree_root_hash for both envelopes.
3. Content-binding hash.
   • approval.subject.digest.sha256 matches strip("sha256:", approval.predicate.content_hash).
   • transform.subject.digest.sha256 matches strip("sha256:", request.payload_hash).
4. allowed_transformations on the approval predicate covers the transform predicate's operation.
5. allowed_sinks on the approval predicate contains the chain request's sink_target.
6. Replay guard. decision_id is reserved by the replay store (verification_decisions table). A second call with the same id returns replay: true, valid: false.

Approval predicates MUST additionally carry expires_at as an RFC 3339 timestamp. A verification call after that instant returns approval_expired and does not reserve the decision.

Reason codes

Stable strings; dashboards grep them.

• bad_request
• approval_fetch_failed, transform_fetch_failed
• approval_signature_unknown_key, approval_signature_invalid
• transform_signature_unknown_key, transform_signature_invalid
• approval_inclusion_proof_invalid, transform_inclusion_proof_invalid
• approval_predicate_malformed, transform_predicate_malformed
• approval_hash_drift, transform_hash_drift
• operation_not_in_allowed_transformations
• sink_not_in_allowed_sinks
• approval_expired
• replay_decision_id

Expected predicate fields

The verifier is strict about the fields it reads. The approval predicate (basicstack.de/attestations/approval/v1) MUST carry:

• content_hash — sha256:<hex> of the approved canonical payload.
• allowed_transformations: ["<operation>", …]
• allowed_sinks: ["<sink_id>", …]
• expires_at — RFC 3339 timestamp.

The transform predicate (basicstack.de/attestations/transform/v1) MUST carry:

• operation — the OPA-vetted transformation name (e.g. expense.map_to_sink).

The approval-service (DEV-608) currently emits content_hash, performed_by, performed_at, verification_digits and approval_schema. The three new fields (allowed_transformations, allowed_sinks, expires_at) must be added to the approval predicate upstream before the Phase-1 end-to-end smoke (DEV-613) can pass; this verifier returns approval_predicate_malformed until they are present.

Configuration

Env var	Flag	Default	Required
TLOG_URL	-tlog-url	—	yes
TLOG_READ_TOKEN	-tlog-token	empty	no
APPROVAL_SIGNER_KEY_ID	-approval-key-id	trust-api/approval-signer-2026-q4	no
TRANSFORM_SIGNER_KEY_ID	-transform-key-id	trust-api/agent-testagent-transform-2026-q4	no
VERIFICATION_SIGNER_KEYS	-signer-keys	—	yes
VERIFICATION_STORE_BACKEND	-backend	memory	no

The replay store is in-memory in Phase 1. The Postgres backend is a stub mirroring the pattern used by the approval-service's Postgres skeleton; the schema is authoritative in db/trust/migrations/0005_verification_decisions.{up,down}.sql.

Build + test

cd services/verification-service
go vet ./...
go test ./...

The CI pipeline (.forgejo/workflows/validate.yml) iterates every services/*/go.mod so the module is picked up automatically.

Non-scope (Phase 2)

• A second transform agent / N-stage chains.
• OPA for verification. The rules above are hard-coded here; moving them to OPA is tracked under the Phase-2 chain-policy work.
• Live agent-registry lookups for transform signer keys. The registry.Keyring interface is the swap-point when the HTTP-backed registry lands.