polyc_crypto/

approval.rs

//! HITL approval payload encoders/decoders and signer.
//!
//! The approval flow persists two event payloads in the conversation eventlog:
//!
//! * `approval_request` — minted when `polyc_agent::run_turn` surfaces a
//!   pending tool call that needs human consent.
//! * `approval_response` — minted by `ApprovalService::Respond` (or the
//!   `POLYCHROME_APPROVE_ALL` auto-approve fast path) carrying a signed
//!   decision.
//!
//! The encoders / decoders live in `polyc-crypto` (this crate) rather
//! than the control-plane binary so the harness pod can verify inbound
//! `approval_response` payloads on its own — the harness sits in a sandbox
//! and shouldn't trust the wire blindly.

use std::sync::Arc;

use serde_json::Value;

use crate::{Signer, verify};

/// Ed25519 signer that mints provenance signatures for `approval_response`
/// payloads. Wraps [`Signer`] in an `Arc` so the gRPC service and the
/// `connect` path share one instance.
#[derive(Clone)]
pub struct ApprovalSigner {
    inner: Arc<Signer>,
}

impl Default for ApprovalSigner {
    /// Deterministic seed (V1 only). Production wires this to a secret
    /// store; the `Default` is here purely so callers can compose.
    fn default() -> Self {
        Self::from_seed(1)
    }
}

impl ApprovalSigner {
    /// Build a signer from a deterministic seed (dev / tests). Production
    /// keys come from a secret store; that wiring is a follow-up.
    #[must_use]
    pub fn from_seed(seed: u64) -> Self {
        Self {
            inner: Arc::new(Signer::from_seed(seed)),
        }
    }

    /// Encoded public key bytes; clients verify approval signatures against
    /// these.
    #[must_use]
    pub fn public_key_bytes(&self) -> Vec<u8> {
        self.inner.public_key_bytes()
    }

    /// Sign the canonical bytes of a response payload. The canonical bytes
    /// are the JSON encoding with the `signature_hex` and `signed_by` fields
    /// cleared — same shape as [`crate::toolcall`] (signature commits to
    /// everything except itself).
    #[must_use]
    pub fn sign(&self, canonical_bytes: &[u8]) -> Vec<u8> {
        self.inner.sign(canonical_bytes)
    }
}

/// JSON payload for an `approval_request` event.
///
/// `request_id` is the model's tool-call id — stable for the lifetime of the
/// turn and used by `ApprovalService::Respond` to address the matching
/// response.
#[must_use]
pub fn request_payload(request_id: &str, tool_name: &str, args_json: &str) -> Vec<u8> {
    serde_json::json!({
        "tool_name": tool_name,
        "args_json": args_json,
        "request_id": request_id,
    })
    .to_string()
    .into_bytes()
}

/// Current signed `approval_response` schema version.
///
/// **v2** binds the approval to the request identity by covering `tool_name` +
/// `args_json` in the signature, closing the call-id-only inheritance gap (#141).
/// **v1** (legacy, no `version` field) signed only `{request_id, approved,
/// reason}` and so cannot authorize execution under v2 rules — it verifies for
/// forensics/display but is treated as **not approved** by the execution gate
/// (fail closed, re-prompt).
pub const RESPONSE_VERSION: u64 = 2;

/// The single source for the **v2** signed canonical JSON. Both the signing path
/// ([`response_payload`]) and the verifying paths ([`verify_signed_response`],
/// [`verify_wire_response`]) route through this so the covered field set/order
/// cannot drift. Adding/renaming/reordering here is a signed-contract change.
fn response_canonical_v2(
    request_id: &str,
    tool_name: &str,
    args_json: &str,
    approved: bool,
    reason: &str,
) -> Vec<u8> {
    serde_json::json!({
        "version": RESPONSE_VERSION,
        "request_id": request_id,
        "tool_name": tool_name,
        "args_json": args_json,
        "approved": approved,
        "reason": reason,
    })
    .to_string()
    .into_bytes()
}

/// Legacy **v1** signed canonical (no `version`, no `tool_name`/`args_json`).
/// Retained only so previously-persisted responses still *verify* (for forensics
/// / display); v1 never authorizes execution under the v2 binding.
fn response_canonical_v1(request_id: &str, approved: bool, reason: &str) -> Vec<u8> {
    serde_json::json!({
        "request_id": request_id,
        "approved": approved,
        "reason": reason,
    })
    .to_string()
    .into_bytes()
}

/// JSON payload for an `approval_response` event (schema **v2**).
///
/// The signature commits to the canonical (unsigned) JSON form — now including
/// `version`, `tool_name`, and `args_json` so an approval is bound to the exact
/// `(request_id, tool_name, args_json)` the human authorized; a re-emitted
/// same-id call with different args/tool no longer inherits it. `signed_by` and
/// `signature_hex` are populated *after* the signer runs and are NOT covered by
/// the signature.
///
/// Returns `(full_payload_bytes, signature_bytes, public_key_bytes)`.
#[must_use]
pub fn response_payload(
    request_id: &str,
    tool_name: &str,
    args_json: &str,
    approved: bool,
    reason: &str,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    let canonical_bytes = response_canonical_v2(request_id, tool_name, args_json, approved, reason);
    let signature = signer.sign(&canonical_bytes);
    let pk = signer.public_key_bytes();
    let full = serde_json::json!({
        "version": RESPONSE_VERSION,
        "request_id": request_id,
        "tool_name": tool_name,
        "args_json": args_json,
        "approved": approved,
        "reason": reason,
        "signed_by": hex_lower(&pk),
        "signature_hex": hex_lower(&signature),
    });
    (full.to_string().into_bytes(), signature, pk)
}

/// A decoded `approval_response` payload after signature verification.
#[derive(Debug, Clone)]
pub struct VerifiedResponse {
    /// The tool-call id this response answers.
    pub request_id: String,
    /// The bound tool name (v2 only; `None` for legacy v1 — not executable).
    pub tool_name: Option<String>,
    /// The bound `args_json` (v2 only; `None` for legacy v1 — not executable).
    pub args_json: Option<String>,
    /// Whether the request was approved.
    pub approved: bool,
    /// Free-form human-supplied reason.
    pub reason: String,
    /// The verified signer's public key (encoded).
    pub signer_public_key: Vec<u8>,
}

impl VerifiedResponse {
    /// Whether this response can authorize **execution**: it must be v2 (carry a
    /// signed `tool_name` + `args_json`) and be approved. Legacy v1 responses
    /// return `false` so the gate re-prompts (fail closed).
    #[must_use]
    pub const fn is_executable_approval(&self) -> bool {
        self.approved && self.tool_name.is_some() && self.args_json.is_some()
    }
}

/// Verify a persisted `approval_response` payload.
///
/// Returns `Some(record)` if the signature checks out against the embedded
/// public key (caller is responsible for trusting that public key — in V1
/// we trust any signed response; in production a key allow-list lives
/// alongside this).
///
/// Returns `None` if the payload is malformed, the hex fields don't decode,
/// or the signature doesn't verify.
#[must_use]
pub fn verify_signed_response(payload: &[u8]) -> Option<VerifiedResponse> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    let request_id = v.get("request_id")?.as_str()?.to_owned();
    let approved = v.get("approved")?.as_bool()?;
    let reason = v.get("reason")?.as_str()?.to_owned();
    let signed_by_hex = v.get("signed_by")?.as_str()?;
    let signature_hex = v.get("signature_hex")?.as_str()?;
    let pk = hex_decode(signed_by_hex)?;
    let sig = hex_decode(signature_hex)?;

    // Version-aware: v2 binds tool_name + args_json into the signature; legacy v1
    // (no version) signed only id/approved/reason. Verify against the matching
    // canonical so old persisted responses still verify (for forensics), but only
    // v2 carries the executable (tool_name, args_json) binding.
    //
    // A legacy response carries no `version` key; treat it as v1. A present
    // `version` must equal the exact current version — any other value (an
    // explicit `1`, a future `3`, or a non-integer) is refused outright rather
    // than verified against a guessed canonical. The v1 canonical does not cover
    // the `version` key, so dispatching an unknown claimed version to v1 would
    // let a valid v1 signature verify under the weaker (unbound) rules while the
    // output echoed an unsigned, writer-chosen version — fail closed instead,
    // exactly as `verify_signed_receipt` does.
    let version = match v.get("version") {
        None => 1,
        Some(n) if n.as_u64() == Some(RESPONSE_VERSION) => RESPONSE_VERSION,
        Some(_) => return None,
    };
    if version == RESPONSE_VERSION {
        let tool_name = v.get("tool_name")?.as_str()?.to_owned();
        let args_json = v.get("args_json")?.as_str()?.to_owned();
        let canonical =
            response_canonical_v2(&request_id, &tool_name, &args_json, approved, &reason);
        if verify(&pk, &canonical, &sig) {
            return Some(VerifiedResponse {
                request_id,
                tool_name: Some(tool_name),
                args_json: Some(args_json),
                approved,
                reason,
                signer_public_key: pk,
            });
        }
        return None;
    }
    // Legacy v1.
    let canonical = response_canonical_v1(&request_id, approved, &reason);
    if verify(&pk, &canonical, &sig) {
        Some(VerifiedResponse {
            request_id,
            tool_name: None,
            args_json: None,
            approved,
            reason,
            signer_public_key: pk,
        })
    } else {
        None
    }
}

/// Verify a wire-form **v2** `approval_response`, binding the approval to its
/// `(request_id, tool_name, args_json)` identity.
///
/// Used by the harness when it receives `HarnessMessage.approval_responses` over
/// the wire and must confirm provenance AND identity before executing the paused
/// tool. Returns `true` only if `signer_pk_hex + signature_hex` validates against
/// the v2 canonical `(version, request_id, tool_name, args_json, approved,
/// reason)`. Legacy v1 responses (which carry no signed tool/args) never validate
/// here, so the gate re-prompts for them — fail closed.
#[must_use]
pub fn verify_wire_response(
    request_id: &str,
    tool_name: &str,
    args_json: &str,
    approved: bool,
    reason: &str,
    signer_pk_hex: &str,
    signature_hex: &str,
) -> bool {
    let Some(pk) = hex_decode(signer_pk_hex) else {
        return false;
    };
    let Some(sig) = hex_decode(signature_hex) else {
        return false;
    };
    let canonical = response_canonical_v2(request_id, tool_name, args_json, approved, reason);
    verify(&pk, &canonical, &sig)
}

/// Extract `(request_id, approved)` from an `approval_response` payload.
///
/// Used by replay to find which pending requests have been answered. Skips
/// signature verification on the assumption the caller has already accepted
/// the entry — pair with [`verify_signed_response`] when trust matters.
#[must_use]
pub fn decode_response_minimal(payload: &[u8]) -> Option<(String, bool)> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    let request_id = v.get("request_id")?.as_str()?.to_owned();
    let approved = v.get("approved")?.as_bool()?;
    Some((request_id, approved))
}

/// Every decoded field of an `approval_response` payload (unverified). `tool_name`
/// / `args_json` are present only for v2 payloads.
#[derive(Debug, Clone)]
pub struct DecodedResponse {
    /// Tool-call id this response answers.
    pub request_id: String,
    /// Bound tool name (v2 only).
    pub tool_name: Option<String>,
    /// Bound `args_json` (v2 only).
    pub args_json: Option<String>,
    /// Approve / deny decision.
    pub approved: bool,
    /// Human-supplied reason.
    pub reason: String,
    /// Signer public key, hex.
    pub signer_pk_hex: String,
    /// Signature, hex.
    pub signature_hex: String,
}

/// Decode every field of an `approval_response` payload without verifying.
///
/// Used by the control plane to forward signed responses onto the harness wire;
/// the harness re-verifies on receipt. For v1 payloads, `tool_name`/`args_json`
/// are `None`.
#[must_use]
pub fn decode_response_full(payload: &[u8]) -> Option<DecodedResponse> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    Some(DecodedResponse {
        request_id: v.get("request_id")?.as_str()?.to_owned(),
        tool_name: v
            .get("tool_name")
            .and_then(Value::as_str)
            .map(str::to_owned),
        args_json: v
            .get("args_json")
            .and_then(Value::as_str)
            .map(str::to_owned),
        approved: v.get("approved")?.as_bool()?,
        reason: v.get("reason")?.as_str()?.to_owned(),
        signer_pk_hex: v.get("signed_by")?.as_str()?.to_owned(),
        signature_hex: v.get("signature_hex")?.as_str()?.to_owned(),
    })
}

/// Current signed `payment_receipt` schema version.
///
/// **v2** makes a settled receipt self-describing: alongside the original
/// settlement facts it covers the event `kind` (direction — without it an
/// inbound payload could be re-filed under the outbound kind, or vice versa,
/// since the stored `Event.kind` is not itself signed), the binding fields
/// (`tool_call_id`, `approval_pos`, `approved_args_hash`), and an opaque
/// `subject` — so an auditor can bind the receipt to the exact approved tool
/// call it answered without walking the log to the separate
/// `outbound_payment_attempt` event. **v1** (legacy, no `version` field) signed
/// only the six settlement facts; it still *verifies* for forensics but carries
/// no kind or binding tuple.
pub const RECEIPT_VERSION: u64 = 2;

/// The receipt body fields [`receipt_payload`] signs, named at the call site.
///
/// Replaces positional `&str` arguments: with the positional form, two
/// same-typed fields (e.g. `recipient` and `method`) could be swapped at a call
/// site and still compile, silently signing a corrupt receipt. Naming the
/// fields here makes such a swap a compile error.
///
/// The field set, names, and the order they are serialized in
/// [`receipt_payload`] are the signed-payload contract: they must NOT change
/// without a version bump, or previously-persisted receipts stop verifying.
///
/// `kind` and the trailing four fields are **v2** additions: the event kind
/// (direction) plus the binding tuple and an opaque `subject`. Inbound (the
/// server was *paid*) receipts have no approved tool call, so they pass empty
/// strings for the binding tuple and subject; outbound (the control plane
/// *paid* a 402 service) receipts populate them. Both directions sign their
/// `kind`.
#[derive(Debug, Clone, Copy)]
pub struct ReceiptPayload<'a> {
    /// The event kind the payload is stored under (`payment_receipt` for
    /// inbound, `outbound_payment_receipt` for outbound). Signed so a payload
    /// cannot be re-filed under the other direction's kind (v2; empty for
    /// legacy v1).
    pub kind: &'a str,
    /// Chain/transaction reference (e.g. tx id) the receipt settles.
    pub reference: &'a str,
    /// Decimal amount as a string (avoids float drift).
    pub amount: &'a str,
    /// Currency / asset symbol.
    pub currency: &'a str,
    /// Recipient address.
    pub recipient: &'a str,
    /// Settlement method (e.g. `tempo`).
    pub method: &'a str,
    /// RFC3339 settlement timestamp.
    pub timestamp: &'a str,
    /// The `paid_fetch` tool-call id this payment answered (v2; empty for
    /// inbound and legacy v1).
    pub tool_call_id: &'a str,
    /// Decimal string of the `approval_request` log position the payment
    /// answered (v2; empty for inbound and legacy v1).
    pub approval_pos: &'a str,
    /// sha256 hex of the approved `args_json` — the same idempotency-key
    /// component the `outbound_payment_attempt` marker carries, so a verifier
    /// can cross-check the receipt against the attempt (v2; empty otherwise).
    pub approved_args_hash: &'a str,
    /// Opaque principal the spend is attributed to. Currently the conversation
    /// id; the structured agent/tenant identity is supplied later by the
    /// declarative-catalog identity model. Treat as opaque (v2; empty otherwise).
    pub subject: &'a str,
}

impl ReceiptPayload<'_> {
    /// Build the canonical (unsigned) **v2** JSON the signature commits to.
    ///
    /// This is the SINGLE source for the signed v2 receipt field set and order:
    /// both the signing path ([`receipt_payload`]) and the verifying path
    /// ([`verify_signed_receipt`]) route their canonical bytes through here,
    /// so adding, renaming, or reordering a covered field is a one-line edit
    /// and the two paths cannot drift. The key set/order is the on-wire
    /// signed contract and must NOT change without a version bump.
    #[must_use]
    fn canonical_json(&self) -> Value {
        serde_json::json!({
            "version": RECEIPT_VERSION,
            "kind": self.kind,
            "reference": self.reference,
            "amount": self.amount,
            "currency": self.currency,
            "recipient": self.recipient,
            "method": self.method,
            "timestamp": self.timestamp,
            "tool_call_id": self.tool_call_id,
            "approval_pos": self.approval_pos,
            "approved_args_hash": self.approved_args_hash,
            "subject": self.subject,
        })
    }

    /// Legacy **v1** canonical (the original six settlement fields, no
    /// `version`). Retained only so receipts persisted before the v2 binding
    /// still *verify* for forensics; new receipts always sign v2.
    #[must_use]
    fn canonical_json_v1(&self) -> Value {
        serde_json::json!({
            "reference": self.reference,
            "amount": self.amount,
            "currency": self.currency,
            "recipient": self.recipient,
            "method": self.method,
            "timestamp": self.timestamp,
        })
    }
}

/// JSON payload for a `payment_receipt` event.
///
/// Mirrors [`response_payload`] exactly: the signature commits to the
/// canonical (unsigned) JSON form of the receipt body
/// (`reference`, `amount`, `currency`, `recipient`, `method`, `timestamp`).
/// `signed_by` and `signature_hex` are populated *after* the signer runs and
/// are NOT covered by the signature itself. Tampering with any body field
/// invalidates the signature.
///
/// The fields arrive as a single named [`ReceiptPayload`] (rather than six
/// positional strings) so a call site cannot silently swap two same-typed
/// fields; the serialized key set/order is unchanged and remains the signed
/// contract.
///
/// Returns `(full_payload_bytes, signature_bytes, public_key_bytes)`.
#[must_use]
pub fn receipt_payload(
    fields: &ReceiptPayload<'_>,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    let mut full = fields.canonical_json();
    let canonical_bytes = full.to_string().into_bytes();
    let signature = signer.sign(&canonical_bytes);
    let pk = signer.public_key_bytes();
    // The full payload is the canonical body plus the two signature fields,
    // which are NOT covered by the signature. Append them to the single-source
    // canonical object so the body field set still lives only in
    // `ReceiptPayload::canonical_json`.
    if let Value::Object(map) = &mut full {
        map.insert("signed_by".to_owned(), Value::String(hex_lower(&pk)));
        map.insert(
            "signature_hex".to_owned(),
            Value::String(hex_lower(&signature)),
        );
    }
    (full.to_string().into_bytes(), signature, pk)
}

/// A decoded `payment_receipt` payload after signature verification.
#[derive(Debug, Clone)]
pub struct VerifiedReceipt {
    /// Chain/transaction reference (e.g. tx id) the receipt settles.
    pub reference: String,
    /// Decimal amount, as a string (avoids float drift).
    pub amount: String,
    /// Currency / asset symbol.
    pub currency: String,
    /// Recipient address.
    pub recipient: String,
    /// Settlement method (e.g. `tempo`).
    pub method: String,
    /// RFC3339 settlement timestamp.
    pub timestamp: String,
    /// Schema version (`1` = legacy settlement-only, `2` = kind + binding
    /// tuple present).
    pub version: u64,
    /// The signed event kind (`payment_receipt` or `outbound_payment_receipt`).
    /// Callers should check it matches the kind the event was stored under —
    /// the stored kind itself is not signed (v2; empty for v1).
    pub kind: String,
    /// The `paid_fetch` tool-call id this payment answered (v2; empty for v1).
    pub tool_call_id: String,
    /// Decimal string of the `approval_request` log position (v2; empty for v1).
    pub approval_pos: String,
    /// sha256 hex of the approved `args_json` (v2; empty for v1).
    pub approved_args_hash: String,
    /// Opaque principal the spend is attributed to (v2; empty for v1).
    pub subject: String,
    /// The verified signer's public key (encoded).
    pub signer_public_key: Vec<u8>,
}

/// Verify a persisted `payment_receipt` payload.
///
/// Returns `Some(record)` if the signature checks out against the embedded
/// public key (caller trusts that key; V1 trusts any signed receipt, like
/// [`verify_signed_response`] — a production key allow-list is a follow-up).
///
/// Returns `None` if the payload is malformed, the hex fields don't decode,
/// or the signature doesn't verify.
#[must_use]
pub fn verify_signed_receipt(payload: &[u8]) -> Option<VerifiedReceipt> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    let reference = v.get("reference")?.as_str()?.to_owned();
    let amount = v.get("amount")?.as_str()?.to_owned();
    let currency = v.get("currency")?.as_str()?.to_owned();
    let recipient = v.get("recipient")?.as_str()?.to_owned();
    let method = v.get("method")?.as_str()?.to_owned();
    let timestamp = v.get("timestamp")?.as_str()?.to_owned();
    let signed_by_hex = v.get("signed_by")?.as_str()?;
    let signature_hex = v.get("signature_hex")?.as_str()?;
    let pk = hex_decode(signed_by_hex)?;
    let sig = hex_decode(signature_hex)?;
    // A legacy receipt carries no `version` key; treat it as v1. A present
    // `version` must equal the exact current version — any other value
    // (including an explicit `1`, a future `3`, or a non-integer) is refused
    // outright rather than verified against a guessed canonical. The v1
    // canonical does not cover the `version` key, so dispatching an unknown
    // claimed version to v1 would let a valid v1 signature verify while the
    // output echoed an unsigned, writer-chosen version — fail closed instead.
    let version = match v.get("version") {
        None => 1,
        Some(n) if n.as_u64() == Some(RECEIPT_VERSION) => RECEIPT_VERSION,
        Some(_) => return None,
    };
    let (kind, tool_call_id, approval_pos, approved_args_hash, subject) =
        if version == RECEIPT_VERSION {
            (
                v.get("kind")?.as_str()?.to_owned(),
                v.get("tool_call_id")?.as_str()?.to_owned(),
                v.get("approval_pos")?.as_str()?.to_owned(),
                v.get("approved_args_hash")?.as_str()?.to_owned(),
                v.get("subject")?.as_str()?.to_owned(),
            )
        } else {
            (
                String::new(),
                String::new(),
                String::new(),
                String::new(),
                String::new(),
            )
        };
    // Rebuild the canonical bytes via the SAME single source the signer used,
    // so the verify path can never check a different field set/order.
    let fields = ReceiptPayload {
        kind: &kind,
        reference: &reference,
        amount: &amount,
        currency: &currency,
        recipient: &recipient,
        method: &method,
        timestamp: &timestamp,
        tool_call_id: &tool_call_id,
        approval_pos: &approval_pos,
        approved_args_hash: &approved_args_hash,
        subject: &subject,
    };
    let canonical_bytes = if version == RECEIPT_VERSION {
        fields.canonical_json()
    } else {
        fields.canonical_json_v1()
    }
    .to_string()
    .into_bytes();
    if verify(&pk, &canonical_bytes, &sig) {
        Some(VerifiedReceipt {
            reference,
            amount,
            currency,
            recipient,
            method,
            timestamp,
            version,
            kind,
            tool_call_id,
            approval_pos,
            approved_args_hash,
            subject,
            signer_public_key: pk,
        })
    } else {
        None
    }
}

/// Extract `request_id` from an `approval_request` payload.
#[must_use]
pub fn decode_request_id(payload: &[u8]) -> Option<String> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    Some(v.get("request_id")?.as_str()?.to_owned())
}

/// Extract `(request_id, tool_name, args_json)` from an `approval_request`
/// payload — the fields a v2 `approval_response` must sign to bind the approval
/// to the request identity.
#[must_use]
pub fn decode_request_fields(payload: &[u8]) -> Option<(String, String, String)> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    Some((
        v.get("request_id")?.as_str()?.to_owned(),
        v.get("tool_name")?.as_str()?.to_owned(),
        v.get("args_json")?.as_str()?.to_owned(),
    ))
}

fn hex_lower(bytes: &[u8]) -> String {
    let mut s = String::with_capacity(bytes.len() * 2);
    for b in bytes {
        use std::fmt::Write as _;
        let _ = write!(&mut s, "{b:02x}");
    }
    s
}

fn hex_decode(s: &str) -> Option<Vec<u8>> {
    if !s.len().is_multiple_of(2) {
        return None;
    }
    (0..s.len())
        .step_by(2)
        .map(|i| u8::from_str_radix(&s[i..i + 2], 16).ok())
        .collect()
}

#[cfg(test)]
mod tests {
    #![allow(clippy::pedantic, clippy::nursery, missing_docs)]

    use super::*;

    #[test]
    fn signed_response_round_trips() {
        let signer = ApprovalSigner::from_seed(42);
        let (payload, _sig, _pk) = response_payload(
            "req-1",
            "rm",
            r#"{"path":"/etc"}"#,
            true,
            "looks fine",
            &signer,
        );
        let verified =
            verify_signed_response(&payload).expect("signature verifies on untampered payload");
        assert!(verified.approved);
        assert_eq!(verified.reason, "looks fine");
        assert_eq!(verified.request_id, "req-1");
        assert_eq!(verified.tool_name.as_deref(), Some("rm"));
        assert_eq!(verified.args_json.as_deref(), Some(r#"{"path":"/etc"}"#));
        assert!(verified.is_executable_approval());
    }

    #[test]
    fn tampered_response_fails_verification() {
        let signer = ApprovalSigner::from_seed(42);
        let (payload, _sig, _pk) =
            response_payload("req-1", "rm", "{}", true, "looks fine", &signer);
        // Tampering with any signed field (approved, tool_name, or args_json)
        // invalidates the signature.
        for field in ["approved", "tool_name", "args_json"] {
            let mut v: Value = serde_json::from_slice(&payload).unwrap();
            v[field] = if field == "approved" {
                Value::Bool(false)
            } else {
                Value::String("EVIL".to_owned())
            };
            assert!(
                verify_signed_response(&v.to_string().into_bytes()).is_none(),
                "tampering with {field} must fail verification"
            );
        }
    }

    #[test]
    fn wire_verification_round_trips_with_hex_fields() {
        let signer = ApprovalSigner::from_seed(7);
        let (payload, _sig, _pk) =
            response_payload("req-x", "fetch", r#"{"u":"x"}"#, true, "go", &signer);
        let d = decode_response_full(&payload).expect("decoded payload");
        let (name, args) = (d.tool_name.unwrap(), d.args_json.unwrap());
        assert!(verify_wire_response(
            &d.request_id,
            &name,
            &args,
            d.approved,
            &d.reason,
            &d.signer_pk_hex,
            &d.signature_hex
        ));
        // Tampering with the bound args over the wire invalidates the sig.
        assert!(!verify_wire_response(
            &d.request_id,
            &name,
            r#"{"u":"EVIL"}"#,
            d.approved,
            &d.reason,
            &d.signer_pk_hex,
            &d.signature_hex
        ));
    }

    /// Migration: a legacy **v1** `approval_response` (no version/tool/args) still
    /// VERIFIES (for forensics/display) but is **not executable** — the execution
    /// gate must re-prompt rather than inherit it.
    #[test]
    fn legacy_v1_response_verifies_but_is_not_executable() {
        let signer = ApprovalSigner::from_seed(7);
        // Reconstruct the exact v1 payload the old code produced.
        let canonical = response_canonical_v1("req-old", true, "ok");
        let sig = signer.sign(&canonical);
        let pk = signer.public_key_bytes();
        let v1 = serde_json::json!({
            "request_id": "req-old",
            "approved": true,
            "reason": "ok",
            "signed_by": hex_lower(&pk),
            "signature_hex": hex_lower(&sig),
        })
        .to_string()
        .into_bytes();

        let verified = verify_signed_response(&v1).expect("a valid v1 signature still verifies");
        assert!(verified.approved, "v1 decision is readable for forensics");
        assert!(verified.tool_name.is_none());
        assert!(
            !verified.is_executable_approval(),
            "v1 must NOT authorize execution (re-prompt, fail closed)"
        );
        // And a v1 payload never satisfies the v2 wire verification.
        assert!(!verify_wire_response(
            "req-old",
            "any",
            "{}",
            true,
            "ok",
            &hex_lower(&pk),
            &hex_lower(&sig)
        ));
    }

    #[test]
    fn injected_version_on_v1_signed_response_fails() {
        // A writer-chosen `version` on an otherwise-valid v1 response must be
        // refused outright (fail closed), never verified against the v1
        // canonical — mirrors `injected_version_on_v1_signed_receipt_fails`, so
        // the two signed-schema verifiers can't drift in strictness.
        let signer = ApprovalSigner::from_seed(7);
        let canonical = response_canonical_v1("req-old", true, "ok");
        let sig = signer.sign(&canonical);
        let pk = signer.public_key_bytes();
        let full = serde_json::json!({
            "request_id": "req-old",
            "approved": true,
            "reason": "ok",
            "signed_by": hex_lower(&pk),
            "signature_hex": hex_lower(&sig),
        });

        for injected in [
            Value::from(99_u64),           // unknown future version
            Value::from(1_u64),            // explicit v1 (still must be absent)
            Value::String("2".to_owned()), // non-integer claiming current
        ] {
            let mut tampered = full.clone();
            tampered["version"] = injected;
            assert!(
                verify_signed_response(&tampered.to_string().into_bytes()).is_none(),
                "a writer-chosen version key must never verify"
            );
        }
        // Sanity: without the injected key the same payload verifies as v1.
        assert!(verify_signed_response(&full.to_string().into_bytes()).is_some());
    }

    #[test]
    fn request_payload_round_trips_id() {
        let bytes = request_payload("call-7", "rm", r#"{"path":"/etc"}"#);
        assert_eq!(decode_request_id(&bytes).as_deref(), Some("call-7"));
    }

    /// Golden test: `receipt_payload` must produce the EXACT **v2** signed-payload
    /// bytes — `version` + the six settlement facts + the four binding fields,
    /// in that order — plus the two uncovered signature fields. We recompute the
    /// expected canonical+full JSON inline and assert the struct form is
    /// byte-identical, pinning the v2 key set, order, and signature so a future
    /// edit cannot silently reorder, rename, or swap a covered field. Recomputing
    /// inline (rather than hardcoding bytes) keeps the golden stable across
    /// `serde_json` feature unification (e.g. `preserve_order`), which only flips
    /// key order — what matters is that both forms agree under whatever ordering
    /// is in effect.
    #[test]
    fn receipt_payload_pins_v2_canonical_shape() {
        let signer = ApprovalSigner::from_seed(99);
        let (reference, amount, currency, recipient, method, timestamp) = (
            "tx-abc",
            "0.01",
            "USDC",
            "0xrecipient",
            "tempo",
            "2026-06-02T00:00:00Z",
        );
        let (kind, tool_call_id, approval_pos, approved_args_hash, subject) = (
            "outbound_payment_receipt",
            "call-1",
            "42",
            "abcd1234",
            "conv-xyz",
        );

        // The exact v2 JSON the implementation must build, recomputed here.
        let expected_canonical = serde_json::json!({
            "version": RECEIPT_VERSION,
            "kind": kind,
            "reference": reference,
            "amount": amount,
            "currency": currency,
            "recipient": recipient,
            "method": method,
            "timestamp": timestamp,
            "tool_call_id": tool_call_id,
            "approval_pos": approval_pos,
            "approved_args_hash": approved_args_hash,
            "subject": subject,
        });
        let expected_sig = signer.sign(expected_canonical.to_string().as_bytes());
        let expected_pk = signer.public_key_bytes();
        let expected_full = serde_json::json!({
            "version": RECEIPT_VERSION,
            "kind": kind,
            "reference": reference,
            "amount": amount,
            "currency": currency,
            "recipient": recipient,
            "method": method,
            "timestamp": timestamp,
            "tool_call_id": tool_call_id,
            "approval_pos": approval_pos,
            "approved_args_hash": approved_args_hash,
            "subject": subject,
            "signed_by": hex_lower(&expected_pk),
            "signature_hex": hex_lower(&expected_sig),
        })
        .to_string();

        let (payload, sig, pk) = receipt_payload(
            &ReceiptPayload {
                kind,
                reference,
                amount,
                currency,
                recipient,
                method,
                timestamp,
                tool_call_id,
                approval_pos,
                approved_args_hash,
                subject,
            },
            &signer,
        );

        assert_eq!(
            String::from_utf8(payload).unwrap(),
            expected_full,
            "v2 receipt payload must be byte-identical to the pinned v2 shape"
        );
        assert_eq!(
            sig, expected_sig,
            "signature must match the pinned v2 shape"
        );
        assert_eq!(pk, expected_pk, "public key must be unchanged");
    }

    /// Single-source guard: both the signing path (`receipt_payload`) and the
    /// verifying path (`verify_signed_receipt`) MUST derive their canonical
    /// signed JSON from the one [`ReceiptPayload::canonical_json`] builder, so
    /// the signed field set/order cannot drift between sign and verify.
    ///
    /// We assert the canonical bytes the signer commits to are exactly the
    /// bytes `canonical_json` produces for the same fields, and that a receipt
    /// reconstructed from `VerifiedReceipt` (the verify path's owned form)
    /// yields the identical canonical bytes. If a future edit added a field to
    /// one json! block but not the other, those bytes would differ and this
    /// (plus the round-trip) would fail.
    #[test]
    fn receipt_sign_and_verify_share_one_canonical_source() {
        let signer = ApprovalSigner::from_seed(99);
        let fields = ReceiptPayload {
            kind: "outbound_payment_receipt",
            reference: "tx-abc",
            amount: "0.01",
            currency: "USDC",
            recipient: "0xrecipient",
            method: "tempo",
            timestamp: "2026-06-02T00:00:00Z",
            tool_call_id: "call-1",
            approval_pos: "42",
            approved_args_hash: "abcd1234",
            subject: "conv-xyz",
        };

        // The signed bytes the producer commits to.
        let canonical_bytes = fields.canonical_json().to_string().into_bytes();
        let expected_sig = signer.sign(&canonical_bytes);
        let (_payload, sig, _pk) = receipt_payload(&fields, &signer);
        assert_eq!(
            sig, expected_sig,
            "receipt_payload must sign exactly ReceiptPayload::canonical_json"
        );

        // The verify path reconstructs the same canonical bytes from its owned
        // form before checking the signature.
        let (payload, _sig, _pk) = receipt_payload(&fields, &signer);
        let verified = verify_signed_receipt(&payload).expect("verifies");
        let verified_canonical = ReceiptPayload {
            kind: &verified.kind,
            reference: &verified.reference,
            amount: &verified.amount,
            currency: &verified.currency,
            recipient: &verified.recipient,
            method: &verified.method,
            timestamp: &verified.timestamp,
            tool_call_id: &verified.tool_call_id,
            approval_pos: &verified.approval_pos,
            approved_args_hash: &verified.approved_args_hash,
            subject: &verified.subject,
        }
        .canonical_json()
        .to_string()
        .into_bytes();
        assert_eq!(
            verified_canonical, canonical_bytes,
            "verify path must derive canonical JSON from the same single source"
        );
    }

    #[test]
    fn crypto_receipt_payload_signs_and_verifies() {
        let signer = ApprovalSigner::from_seed(99);
        let (payload, _sig, _pk) = receipt_payload(
            &ReceiptPayload {
                kind: "outbound_payment_receipt",
                reference: "tx-abc",
                amount: "0.01",
                currency: "USDC",
                recipient: "0xrecipient",
                method: "tempo",
                timestamp: "2026-06-02T00:00:00Z",
                tool_call_id: "call-1",
                approval_pos: "42",
                approved_args_hash: "abcd1234",
                subject: "conv-xyz",
            },
            &signer,
        );
        let verified =
            verify_signed_receipt(&payload).expect("signature verifies on untampered receipt");
        assert_eq!(verified.reference, "tx-abc");
        assert_eq!(verified.amount, "0.01");
        assert_eq!(verified.currency, "USDC");
        assert_eq!(verified.recipient, "0xrecipient");
        assert_eq!(verified.method, "tempo");
        assert_eq!(verified.timestamp, "2026-06-02T00:00:00Z");
        // The v2 kind + binding tuple + opaque subject round-trip and are
        // covered by the signature.
        assert_eq!(verified.version, RECEIPT_VERSION);
        assert_eq!(verified.kind, "outbound_payment_receipt");
        assert_eq!(verified.tool_call_id, "call-1");
        assert_eq!(verified.approval_pos, "42");
        assert_eq!(verified.approved_args_hash, "abcd1234");
        assert_eq!(verified.subject, "conv-xyz");
    }

    #[test]
    fn tampered_receipt_fails_verification() {
        let signer = ApprovalSigner::from_seed(99);
        let (payload, _sig, _pk) = receipt_payload(
            &ReceiptPayload {
                kind: "outbound_payment_receipt",
                reference: "tx-abc",
                amount: "0.01",
                currency: "USDC",
                recipient: "0xrecipient",
                method: "tempo",
                timestamp: "2026-06-02T00:00:00Z",
                tool_call_id: "call-1",
                approval_pos: "42",
                approved_args_hash: "abcd1234",
                subject: "conv-xyz",
            },
            &signer,
        );
        // Tamper with a covered field (amount).
        let mut v: Value = serde_json::from_slice(&payload).unwrap();
        v["amount"] = Value::String("9999.00".to_owned());
        let tampered = v.to_string().into_bytes();
        assert!(verify_signed_receipt(&tampered).is_none());
    }

    #[test]
    fn tampered_receipt_binding_field_fails_verification() {
        let signer = ApprovalSigner::from_seed(99);
        let (payload, _sig, _pk) = receipt_payload(
            &ReceiptPayload {
                kind: "outbound_payment_receipt",
                reference: "tx-abc",
                amount: "0.01",
                currency: "USDC",
                recipient: "0xrecipient",
                method: "tempo",
                timestamp: "2026-06-02T00:00:00Z",
                tool_call_id: "call-1",
                approval_pos: "42",
                approved_args_hash: "abcd1234",
                subject: "conv-xyz",
            },
            &signer,
        );
        // Re-pointing the receipt at a different approval position invalidates
        // the signature — the binding tuple is covered, not advisory.
        let mut v: Value = serde_json::from_slice(&payload).unwrap();
        v["approval_pos"] = Value::String("7".to_owned());
        let tampered = v.to_string().into_bytes();
        assert!(verify_signed_receipt(&tampered).is_none());

        // Re-filing the payload under the other direction's kind likewise
        // fails — the signed `kind` is what makes direction trustworthy
        // independent of the (unsigned) stored event kind.
        let mut v: Value = serde_json::from_slice(&payload).unwrap();
        v["kind"] = Value::String("payment_receipt".to_owned());
        let refiled = v.to_string().into_bytes();
        assert!(verify_signed_receipt(&refiled).is_none());
    }

    /// A receipt persisted before the v2 binding (no `version`, six fields only)
    /// must still verify for forensics, surfacing as `version == 1` with empty
    /// binding fields. Mirrors the legacy approval-response path.
    #[test]
    fn legacy_v1_receipt_still_verifies() {
        let signer = ApprovalSigner::from_seed(99);
        let canonical = serde_json::json!({
            "reference": "tx-old",
            "amount": "0.02",
            "currency": "USDC",
            "recipient": "0xr",
            "method": "tempo",
            "timestamp": "2026-06-01T00:00:00Z",
        });
        let sig = signer.sign(canonical.to_string().as_bytes());
        let pk = signer.public_key_bytes();
        let v1 = serde_json::json!({
            "reference": "tx-old",
            "amount": "0.02",
            "currency": "USDC",
            "recipient": "0xr",
            "method": "tempo",
            "timestamp": "2026-06-01T00:00:00Z",
            "signed_by": hex_lower(&pk),
            "signature_hex": hex_lower(&sig),
        })
        .to_string()
        .into_bytes();

        let verified = verify_signed_receipt(&v1).expect("a valid v1 receipt still verifies");
        assert_eq!(verified.version, 1);
        assert_eq!(verified.reference, "tx-old");
        assert!(verified.kind.is_empty());
        assert!(verified.tool_call_id.is_empty());
        assert!(verified.approval_pos.is_empty());
        assert!(verified.subject.is_empty());
    }

    /// Injecting a `version` key into a validly-signed legacy receipt must not
    /// verify: the v1 canonical does not cover `version`, so dispatching the
    /// claimed version to the v1 canonical would let the signature check pass
    /// while `VerifiedReceipt.version` echoed an unsigned, writer-chosen value.
    /// Only an absent `version` (⇒ 1) or the exact current version is accepted.
    #[test]
    fn injected_version_on_v1_signed_receipt_fails() {
        let signer = ApprovalSigner::from_seed(99);
        let canonical = serde_json::json!({
            "reference": "tx-old",
            "amount": "0.02",
            "currency": "USDC",
            "recipient": "0xr",
            "method": "tempo",
            "timestamp": "2026-06-01T00:00:00Z",
        });
        let sig = signer.sign(canonical.to_string().as_bytes());
        let pk = signer.public_key_bytes();
        let mut full = canonical;
        full["signed_by"] = Value::String(hex_lower(&pk));
        full["signature_hex"] = Value::String(hex_lower(&sig));

        // A claimed future version, an explicit "1", and a non-integer are all
        // refused outright (fail closed) — never verified against a guessed
        // canonical.
        for injected in [
            Value::from(7_u64),
            Value::from(1_u64),
            Value::String("2".to_owned()),
        ] {
            let mut tampered = full.clone();
            tampered["version"] = injected;
            assert!(
                verify_signed_receipt(&tampered.to_string().into_bytes()).is_none(),
                "a writer-chosen version key must never verify"
            );
        }
        // Sanity: without the injected key the same payload verifies as v1.
        assert!(verify_signed_receipt(&full.to_string().into_bytes()).is_some());
    }
}