polyc_crypto/

question.rs

//! `ask_question` (`#1660`) signed-answer canonical, verification, and the
//! per-question correlation-token contract.
//!
//! A **sibling to the HITL approval flow's `approval_response` machinery in
//! [`crate::approval`], not a reuse of it** — see issue #1660 and its parent
//! PRD #1659. The trust shape is identical (THIN signing: an edge sends an
//! *unsigned* answer intent, the control plane resolves and signs
//! server-side, the harness re-verifies before trusting the answer) but the
//! signed canonical is its own, with its own field set and its own key names
//! (`question_call_id`/`question_index`, not `request_id`/`tool_name`), so an
//! approval signature can never verify as a question answer and vice versa.
//! The [`ApprovalSigner`] role intentionally covers this human-decision
//! answer family as well as tool approvals. Session, turn-read, web-session
//! grants, and journal roots use different roles.

use std::collections::HashSet;

use serde::Serialize;
use serde_json::Value;

use crate::approval::ApprovalSigner;
use crate::signed::{Envelope, canonical_bytes};
use crate::verify;

/// The signed `state` value for a question a human explicitly answered by
/// picking an option.
pub const ANSWERED_STATE: &str = "answered";
/// The signed `state` value for a question a human explicitly declined to
/// choose ("use your own judgment") — distinct from [`ANSWERED_STATE`] so the
/// agent never mistakes a decline for a real answer.
pub const DECLINED_STATE: &str = "declined";
/// The signed `state` value for a question nobody answered before its idle
/// window elapsed.
///
/// The control plane auto-resolved it to the recommended option (or the
/// first option if none was marked recommended). Signed and unforgeable, so
/// the agent is told this was an assumption, not a genuine human answer.
pub const AUTO_RESOLVED_STATE: &str = "auto_resolved";

/// TTL for a minted answer token (`#1660`).
///
/// Mirrors [`crate::approval::RESOLVE_TOKEN_TTL_MS`]'s reasoning: generous
/// enough that a human has time to see and answer the question card (which
/// can sit in a chat thread for hours or days), short enough that a token
/// captured off a stale card cannot answer the question indefinitely.
pub const ANSWER_TOKEN_TTL_MS: u64 = 24 * 60 * 60 * 1000;

/// The single source for the signed `question_response` canonical JSON. Both
/// the signing path ([`answer_payload`]) and the verifying paths
/// ([`verify_signed_answer`], [`verify_wire_answer`]) route through this so
/// the covered field set/order cannot drift. Adding/renaming/reordering here
/// is a signed-contract change.
///
/// Deliberately uses `question_call_id`/`question_index` rather than the
/// approval canonical's `request_id`/`tool_name` key names: even though both
/// canonicals are JSON objects an attacker might try to splice together, no
/// approval signature can ever verify against this shape (the signed BYTES
/// differ) and no answer signature can ever verify as an approval.
///
/// `question_args_json` is the `ask_question` call's full raw arguments (every
/// question in the call, not just this one) — the audit binding a verifier
/// matches against [`VerifiedQuestionAnswer::binds_question`], mirroring how
/// the approval canonical binds `args_json`. `conversation_id` and `nonce`
/// make the answer a single-use, conversation-bound capability, exactly like
/// `#370`'s approval-response token.
#[allow(clippy::too_many_arguments)] // each arg is a distinct signed field of the canonical contract
fn answer_canonical(
    call_id: &str,
    index: u32,
    question_args_json: &str,
    state: &str,
    selected_index: Option<u32>,
    selected_label: &str,
    answered_by: &str,
    conversation_id: &str,
    nonce: &str,
) -> Vec<u8> {
    canonical_bytes(&answer_fields(
        call_id,
        index,
        question_args_json,
        state,
        selected_index,
        selected_label,
        answered_by,
        conversation_id,
        nonce,
    ))
}

/// The signed `question_response` field set, in its frozen order.
///
/// Declaration order IS the signed contract — see [`canonical_bytes`] and ADR
/// 0009. `selected_index` is serialized as an explicit `null` for a decline
/// rather than skipped, which is what the `json!` object this replaced emitted
/// and therefore what every already-signed `question_response` in a
/// deployment's log covers.
#[derive(Serialize)]
struct AnswerCanonical<'a> {
    question_call_id: &'a str,
    question_index: u32,
    question_args_json: &'a str,
    state: &'a str,
    selected_index: Option<u32>,
    selected_label: &'a str,
    answered_by: &'a str,
    conversation_id: &'a str,
    nonce: &'a str,
}

/// The answer body both [`answer_canonical`] and [`answer_payload`] build, so
/// the signed field list exists once rather than in two hand-maintained copies
/// (`#1845`).
#[allow(clippy::too_many_arguments)] // each arg is a distinct signed field of the canonical contract
const fn answer_fields<'a>(
    call_id: &'a str,
    index: u32,
    question_args_json: &'a str,
    state: &'a str,
    selected_index: Option<u32>,
    selected_label: &'a str,
    answered_by: &'a str,
    conversation_id: &'a str,
    nonce: &'a str,
) -> AnswerCanonical<'a> {
    AnswerCanonical {
        question_call_id: call_id,
        question_index: index,
        question_args_json,
        state,
        selected_index,
        selected_label,
        answered_by,
        conversation_id,
        nonce,
    }
}

/// JSON payload for a `question_response` event.
///
/// The signature commits to the canonical (unsigned) JSON form: the question
/// identity (`call_id`, `index`, `question_args_json`), the resolution
/// (`state`/`selected_index`/`selected_label`), who resolved it
/// (`answered_by`, empty for [`AUTO_RESOLVED_STATE`]), and the
/// conversation/nonce binding. `signed_by`/`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]
#[allow(clippy::too_many_arguments)] // each arg is a distinct signed field of the canonical contract
pub fn answer_payload(
    call_id: &str,
    index: u32,
    question_args_json: &str,
    state: &str,
    selected_index: Option<u32>,
    selected_label: &str,
    answered_by: &str,
    conversation_id: &str,
    nonce: &str,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    Envelope::seal(
        answer_fields(
            call_id,
            index,
            question_args_json,
            state,
            selected_index,
            selected_label,
            answered_by,
            conversation_id,
            nonce,
        ),
        signer.as_signer(),
    )
}

/// A verified, decoded `question_response` payload.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VerifiedQuestionAnswer {
    /// The `ask_question` tool-call id this answer resolves.
    pub call_id: String,
    /// This answer's question index within its call's `questions` array.
    pub index: u32,
    /// The bound raw `ask_question` call arguments (every question in the
    /// call) — the audit binding [`Self::binds_question`] matches
    /// byte-for-byte.
    pub question_args_json: String,
    /// One of [`ANSWERED_STATE`], [`DECLINED_STATE`], or
    /// [`AUTO_RESOLVED_STATE`].
    pub state: String,
    /// The chosen option's index, when `state == ANSWERED_STATE` or
    /// `AUTO_RESOLVED_STATE`. `None` for a decline.
    pub selected_index: Option<u32>,
    /// The chosen option's label, mirrored alongside the index so a consumer
    /// never has to re-resolve it against the (possibly since-compacted)
    /// original question payload.
    pub selected_label: String,
    /// Who answered — empty for [`AUTO_RESOLVED_STATE`] (nobody did).
    pub answered_by: String,
    /// The conversation this answer was signed for, covered by the
    /// signature so a token signed for one conversation cannot be replayed
    /// into another.
    pub conversation_id: String,
    /// Per-answer unique value, covered by the signature. A consumer
    /// records it on use so the answer cannot be re-applied once spent
    /// (single-use, mirrors `#370`).
    pub nonce: String,
    /// The verified signer's public key (encoded).
    pub signer_public_key: Vec<u8>,
    /// Hex-encoded ed25519 public key of the signer — the same bytes as
    /// [`Self::signer_public_key`], kept alongside it in the wire-ready
    /// encoding so a consumer forwarding this answer onward (the control
    /// plane's outstanding-answer collector, to the harness) never
    /// re-derives the hex itself. Mirrors
    /// `polyc_crypto::approval::DecodedResponse::signer_pk_hex`.
    pub signer_pk_hex: String,
    /// Hex-encoded ed25519 signature over the canonical answer tuple —
    /// forwarded onward so the harness can independently re-verify (THIN
    /// signing) rather than trust the control plane's own verification.
    /// Mirrors `polyc_crypto::approval::DecodedResponse::signature_hex`.
    pub signature_hex: String,
}

impl VerifiedQuestionAnswer {
    /// Whether this verified answer is bound to the EXACT question
    /// `(call_id, index, question_args_json)` — the args-binding a resume
    /// path must check before applying the answer, mirroring
    /// [`crate::approval::VerifiedResponse::authorizes_call`].
    #[must_use]
    pub fn binds_question(&self, call_id: &str, index: u32, question_args_json: &str) -> bool {
        self.call_id == call_id
            && self.index == index
            && self.question_args_json == question_args_json
    }
}

/// Verify a persisted `question_response` payload.
///
/// Returns `Some(record)` if the signature checks out against the embedded
/// public key (the caller is responsible for trusting that public key — see
/// [`verify_signed_answer_pinned`]). 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_answer(payload: &[u8]) -> Option<VerifiedQuestionAnswer> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    let call_id = v.get("question_call_id")?.as_str()?.to_owned();
    let index = u32::try_from(v.get("question_index")?.as_u64()?).ok()?;
    let question_args_json = v.get("question_args_json")?.as_str()?.to_owned();
    let state = v.get("state")?.as_str()?.to_owned();
    let selected_index = match v.get("selected_index") {
        Some(Value::Null) | None => None,
        Some(x) => Some(u32::try_from(x.as_u64()?).ok()?),
    };
    let selected_label = v.get("selected_label")?.as_str()?.to_owned();
    let answered_by = v.get("answered_by")?.as_str()?.to_owned();
    let conversation_id = v.get("conversation_id")?.as_str()?.to_owned();
    let nonce = v.get("nonce")?.as_str()?.to_owned();
    let pk = crate::hex::decode(v.get("signed_by")?.as_str()?)?;
    let sig = crate::hex::decode(v.get("signature_hex")?.as_str()?)?;

    let canonical = answer_canonical(
        &call_id,
        index,
        &question_args_json,
        &state,
        selected_index,
        &selected_label,
        &answered_by,
        &conversation_id,
        &nonce,
    );
    if verify(&pk, &canonical, &sig) {
        Some(VerifiedQuestionAnswer {
            call_id,
            index,
            question_args_json,
            state,
            selected_index,
            selected_label,
            answered_by,
            conversation_id,
            nonce,
            signer_pk_hex: crate::hex::lower(&pk),
            signature_hex: crate::hex::lower(&sig),
            signer_public_key: pk,
        })
    } else {
        None
    }
}

/// Verify a persisted `question_response` payload against a **trusted-signer
/// allow-list**.
///
/// Mirrors [`crate::approval::verify_signed_response_pinned`]: without this
/// gate an attacker could sign a well-formed answer with their own key,
/// embed it, and have it honored. Returns `None` (fail closed) on a
/// malformed payload, an untrusted signer, or a bad signature.
#[must_use]
pub fn verify_signed_answer_pinned(
    payload: &[u8],
    trusted_signers: &[Vec<u8>],
) -> Option<VerifiedQuestionAnswer> {
    let verified = verify_signed_answer(payload)?;
    if !trusted_signers
        .iter()
        .any(|k| k.as_slice() == verified.signer_public_key)
    {
        return None;
    }
    Some(verified)
}

/// Verify a persisted `question_response` as a SINGLE-USE, conversation-bound
/// capability (invariant I3/I7), gated on a trusted-signer allow-list.
///
/// Returns the verified answer only when ALL hold: the embedded signer is
/// trusted; the signature verifies; the signed `conversation_id` equals
/// `conversation_id`; the signed `nonce` is non-empty AND not already in
/// `consumed`. The caller MUST record the returned nonce into its `consumed`
/// set before honoring the answer, so a second presentation is rejected.
#[must_use]
pub fn verify_answer_capability<S: std::hash::BuildHasher>(
    payload: &[u8],
    conversation_id: &str,
    consumed: &HashSet<String, S>,
    trusted_signers: &[Vec<u8>],
) -> Option<VerifiedQuestionAnswer> {
    let verified = verify_signed_answer_pinned(payload, trusted_signers)?;
    if verified.conversation_id != conversation_id {
        return None;
    }
    if verified.nonce.is_empty() || consumed.contains(&verified.nonce) {
        return None;
    }
    Some(verified)
}

/// Verify a wire-form `question_response`, binding the answer to its full
/// signed identity.
///
/// Used by the harness when it receives an answer over the wire and must
/// confirm provenance AND identity before feeding it back into the turn as
/// the `ask_question` call's result — the trust boundary this exists for:
/// silent acceptance would let a compromised control plane forge a user's
/// answer. Returns `true` only if `signer_pk_hex + signature_hex` validates
/// against the canonical.
#[must_use]
#[allow(clippy::too_many_arguments)] // each arg is a distinct signed field of the canonical contract
pub fn verify_wire_answer(
    call_id: &str,
    index: u32,
    question_args_json: &str,
    state: &str,
    selected_index: Option<u32>,
    selected_label: &str,
    answered_by: &str,
    conversation_id: &str,
    nonce: &str,
    signer_pk_hex: &str,
    signature_hex: &str,
) -> bool {
    let Some(pk) = crate::hex::decode(signer_pk_hex) else {
        return false;
    };
    let Some(sig) = crate::hex::decode(signature_hex) else {
        return false;
    };
    let canonical = answer_canonical(
        call_id,
        index,
        question_args_json,
        state,
        selected_index,
        selected_label,
        answered_by,
        conversation_id,
        nonce,
    );
    verify(&pk, &canonical, &sig)
}

// ── Per-question correlation token ──────────────────────────────────────────

/// The canonical (signature-covered) form of an answer token (`#1660`).
///
/// Deliberately uses the SAME `question_call_id`/`question_index` key names
/// [`answer_canonical`] uses, but a DIFFERENT key set than
/// [`crate::approval`]'s `resolve_token_canonical` (`request_id` vs
/// `question_call_id`) — an approval resolve token must never verify as an
/// answer token and vice versa; [`verify_answer_token`]'s own test pins this
/// cross-domain rejection.
fn answer_token_canonical(
    call_id: &str,
    index: u32,
    conversation_id: &str,
    minted_at_ms: u64,
) -> Vec<u8> {
    canonical_bytes(&AnswerTokenCanonical {
        question_call_id: call_id,
        question_index: index,
        conversation_id,
        minted_at_ms,
    })
}

/// The signed answer-token field set, in its frozen order. See ADR 0009.
#[derive(Serialize)]
struct AnswerTokenCanonical<'a> {
    question_call_id: &'a str,
    question_index: u32,
    conversation_id: &'a str,
    minted_at_ms: u64,
}

/// A minted answer token: the canonical body plus its signature.
///
/// The token carries no `signed_by` — it is verified against the control
/// plane's own key, supplied by the caller of [`verify_answer_token`], never
/// one carried on the token itself. Mirrors
/// `polyc_crypto::approval::mint_resolve_token`'s shape, so
/// [`crate::signed::Envelope`] (which always writes both provenance fields)
/// does not apply here.
#[derive(Serialize)]
struct AnswerToken<'a> {
    #[serde(flatten)]
    body: AnswerTokenCanonical<'a>,
    signature_hex: String,
}

/// Mint a short-lived, signed answer token scoped to one pending question.
///
/// Scoped to `(call_id, index, conversation_id)` — the correlation-token
/// contract every downstream edge slice (#1661-#1664) consumes unchanged.
/// Mirrors [`crate::approval::mint_resolve_token`]'s shape and
/// unforgeability argument: opaque to, and unforgeable by, anything
/// downstream of the mint point. `minted_at_ms` is the caller's wall clock
/// at mint time; pass a real timestamp in production, an injected one in
/// tests.
///
/// Returns the token as a lowercase-hex opaque string, safe to carry on any
/// wire surface (a button value, a proto field) alongside `call_id`/`index`.
#[must_use]
pub fn mint_answer_token(
    call_id: &str,
    index: u32,
    conversation_id: &str,
    minted_at_ms: u64,
    signer: &ApprovalSigner,
) -> String {
    // Built once and reused for both the signature and the envelope. Writing the
    // field list a second time here would be a second hand-maintained copy of a
    // signed field set — the drift this module's `answer_fields` exists to stop.
    let body = AnswerTokenCanonical {
        question_call_id: call_id,
        question_index: index,
        conversation_id,
        minted_at_ms,
    };
    let signature = signer.sign(&canonical_bytes(&body));
    let full = AnswerToken {
        body,
        signature_hex: crate::hex::lower(&signature),
    };
    crate::hex::lower(&canonical_bytes(&full))
}

/// Verify an answer token minted by [`mint_answer_token`] against the
/// `(call_id, index, conversation_id)` a `Respond` call presents it for.
///
/// Returns `true` only when ALL hold: the token decodes; its embedded
/// signature verifies against `signer`'s public key; its bound identity
/// equals the ones supplied; and `now_ms - minted_at_ms` is within
/// [`ANSWER_TOKEN_TTL_MS`] (a token minted in the future, by clock skew
/// beyond the TTL, also fails — fail closed rather than trust an
/// out-of-bounds clock). Fails closed on any malformed field.
#[must_use]
pub fn verify_answer_token(
    token: &str,
    call_id: &str,
    index: u32,
    conversation_id: &str,
    now_ms: u64,
    signer: &ApprovalSigner,
) -> bool {
    let Some(bytes) = crate::hex::decode(token) else {
        return false;
    };
    let Ok(v) = serde_json::from_slice::<Value>(&bytes) else {
        return false;
    };
    let (
        Some(bound_call_id),
        Some(bound_index),
        Some(bound_conversation_id),
        Some(minted_at_ms),
        Some(signature_hex),
    ) = (
        v.get("question_call_id").and_then(Value::as_str),
        v.get("question_index").and_then(Value::as_u64),
        v.get("conversation_id").and_then(Value::as_str),
        v.get("minted_at_ms").and_then(Value::as_u64),
        v.get("signature_hex").and_then(Value::as_str),
    )
    else {
        return false;
    };
    let Ok(bound_index) = u32::try_from(bound_index) else {
        return false;
    };
    if bound_call_id != call_id || bound_index != index || bound_conversation_id != conversation_id
    {
        return false;
    }
    let elapsed = now_ms.abs_diff(minted_at_ms);
    if elapsed > ANSWER_TOKEN_TTL_MS {
        return false;
    }
    let Some(sig) = crate::hex::decode(signature_hex) else {
        return false;
    };
    let canonical = answer_token_canonical(
        bound_call_id,
        bound_index,
        bound_conversation_id,
        minted_at_ms,
    );
    verify(&signer.public_key_bytes(), &canonical, &sig)
}

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

    fn valid_answer_payload(signer: &ApprovalSigner) -> Vec<u8> {
        answer_payload(
            "call-1",
            0,
            r#"{"questions":[]}"#,
            ANSWERED_STATE,
            Some(1),
            "Production",
            "slack:T1:U9",
            "conv-A",
            "nonce-A",
            signer,
        )
        .0
    }

    #[test]
    fn signed_answer_round_trips() {
        let signer = ApprovalSigner::from_seed(1);
        let payload = valid_answer_payload(&signer);
        let verified = verify_signed_answer(&payload).expect("signature verifies");
        assert_eq!(verified.call_id, "call-1");
        assert_eq!(verified.index, 0);
        assert_eq!(verified.state, ANSWERED_STATE);
        assert_eq!(verified.selected_index, Some(1));
        assert_eq!(verified.selected_label, "Production");
        assert_eq!(verified.answered_by, "slack:T1:U9");
        assert!(verified.binds_question("call-1", 0, r#"{"questions":[]}"#));
        assert!(!verified.binds_question("call-2", 0, r#"{"questions":[]}"#));
    }

    /// `#1660` Step 7: the decoded record carries the RAW signer/signature
    /// hex alongside the verified fields — not just `signer_public_key`
    /// bytes — so a consumer (the control plane's outstanding-answer
    /// collector) can re-forward the exact signed bytes to the harness for
    /// its own independent re-verification (THIN signing), mirroring
    /// `polyc_crypto::approval::DecodedResponse::{signer_pk_hex,
    /// signature_hex}`.
    #[test]
    fn verified_answer_carries_raw_signer_and_signature_hex() {
        let signer = ApprovalSigner::from_seed(1);
        let payload = valid_answer_payload(&signer);
        let verified = verify_signed_answer(&payload).expect("signature verifies");
        assert_eq!(
            verified.signer_pk_hex,
            crate::hex::lower(&signer.public_key_bytes())
        );
        assert!(!verified.signature_hex.is_empty());
        // The hex must actually verify against the canonical this payload
        // signs — not just be non-empty — so re-derive the signature bytes
        // and check them against `verify` directly.
        let sig_bytes = crate::hex::decode(&verified.signature_hex).expect("valid hex");
        let canonical = answer_canonical(
            &verified.call_id,
            verified.index,
            &verified.question_args_json,
            &verified.state,
            verified.selected_index,
            &verified.selected_label,
            &verified.answered_by,
            &verified.conversation_id,
            &verified.nonce,
        );
        assert!(verify(&signer.public_key_bytes(), &canonical, &sig_bytes));
    }

    #[test]
    fn declined_and_auto_resolved_states_round_trip_with_no_selection_or_answerer() {
        let signer = ApprovalSigner::from_seed(1);
        let (payload, ..) = answer_payload(
            "call-1",
            0,
            "{}",
            DECLINED_STATE,
            None,
            "",
            "slack:T1:U9",
            "conv-A",
            "nonce-B",
            &signer,
        );
        let v = verify_signed_answer(&payload).expect("verifies");
        assert_eq!(v.state, DECLINED_STATE);
        assert_eq!(v.selected_index, None);

        let (payload, ..) = answer_payload(
            "call-1",
            0,
            "{}",
            AUTO_RESOLVED_STATE,
            Some(0),
            "Staging",
            "",
            "conv-A",
            "nonce-C",
            &signer,
        );
        let v = verify_signed_answer(&payload).expect("verifies");
        assert_eq!(v.state, AUTO_RESOLVED_STATE);
        assert_eq!(
            v.answered_by, "",
            "nobody answered an auto-resolved question"
        );
    }

    /// Invariant I3: every signed field is covered — tampering with any one
    /// (the state, the selection, who answered, the conversation, or the
    /// nonce) must fail verification.
    #[test]
    fn tampered_state_or_selection_fails_verification() {
        let signer = ApprovalSigner::from_seed(1);
        let payload = valid_answer_payload(&signer);
        let mut v: Value = serde_json::from_slice(&payload).unwrap();
        for (field, val) in [
            ("state", Value::String(DECLINED_STATE.to_owned())),
            ("selected_index", Value::Number(2.into())),
            ("selected_label", Value::String("Staging".into())),
            ("answered_by", Value::String("slack:T1:U0".into())),
            ("conversation_id", Value::String("conv-B".into())),
            ("nonce", Value::String("nonce-Z".into())),
            ("question_call_id", Value::String("call-2".into())),
            ("question_index", Value::Number(1.into())),
        ] {
            let mut tampered = v.clone();
            tampered[field] = val;
            let bytes = serde_json::to_vec(&tampered).unwrap();
            assert!(
                verify_signed_answer(&bytes).is_none(),
                "tampering `{field}` must invalidate the signature"
            );
        }
        // Sanity: the untampered payload still verifies.
        assert!(verify_signed_answer(&serde_json::to_vec(&v.take()).unwrap()).is_some());
    }

    /// Invariant I3: a signature from a signer outside the trusted allow-list
    /// authorizes nothing, even though it is internally self-consistent.
    #[test]
    fn answer_from_non_allowlisted_signer_is_rejected() {
        let trusted = ApprovalSigner::from_seed(1);
        let attacker = ApprovalSigner::from_seed(666);
        let payload = valid_answer_payload(&attacker);
        assert!(
            verify_signed_answer_pinned(&payload, &[trusted.public_key_bytes()]).is_none(),
            "an untrusted signer's answer must never verify"
        );
        assert!(
            verify_signed_answer_pinned(&payload, &[attacker.public_key_bytes()]).is_some(),
            "sanity: the attacker's own key does verify its own signature"
        );
    }

    /// Invariant I3/`#370`-style replay guard: a token signed for one
    /// conversation must be rejected when presented for another, even though
    /// every other field is byte-identical.
    #[test]
    fn answer_rejected_across_conversations() {
        let signer = ApprovalSigner::from_seed(1);
        let payload = valid_answer_payload(&signer);
        let consumed = HashSet::new();
        assert!(
            verify_answer_capability(&payload, "conv-A", &consumed, &[signer.public_key_bytes()])
                .is_some()
        );
        assert!(
            verify_answer_capability(&payload, "conv-B", &consumed, &[signer.public_key_bytes()])
                .is_none(),
            "an answer signed for conv-A must be rejected when presented for conv-B"
        );
    }

    /// Invariant I2/I7: a single-use answer is rejected on a second
    /// presentation, mirroring `capability_is_single_use` for approvals.
    #[test]
    fn question_answer_capability_is_single_use() {
        let signer = ApprovalSigner::from_seed(1);
        let payload = valid_answer_payload(&signer);
        let mut consumed = HashSet::new();
        let v =
            verify_answer_capability(&payload, "conv-A", &consumed, &[signer.public_key_bytes()])
                .expect("first use honored");
        assert_eq!(v.nonce, "nonce-A");
        consumed.insert(v.nonce.clone());
        assert!(
            verify_answer_capability(&payload, "conv-A", &consumed, &[signer.public_key_bytes()])
                .is_none(),
            "a spent answer must be rejected on re-presentation"
        );
    }

    /// Cross-domain canonical separation: an approval's own signed
    /// `approval_response`/`resolve_token` bytes must never verify as a
    /// question answer/token, and vice versa — the two canonicals use
    /// different key names specifically so this can never accidentally work.
    #[test]
    fn approval_payloads_never_verify_as_question_answers() {
        let signer = ApprovalSigner::from_seed(1);
        let (approval_payload, ..) = crate::approval::response_payload(
            "call-1",
            "ask_question",
            r#"{"questions":[]}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "",
            "",
            "",
            "conv-A",
            "nonce-A",
            &signer,
        );
        assert!(
            verify_signed_answer(&approval_payload).is_none(),
            "an approval_response payload must never decode+verify as a question_response"
        );

        let resolve_token = crate::approval::mint_resolve_token("call-1", "conv-A", 1_000, &signer);
        assert!(
            !verify_answer_token(&resolve_token, "call-1", 0, "conv-A", 1_000, &signer),
            "an approval resolve_token must never verify as an answer token"
        );
    }

    /// `polyc_proto::tool_display::question_answered_text` duplicates
    /// `ANSWERED_STATE`/`DECLINED_STATE`/`AUTO_RESOLVED_STATE` as local
    /// string literals (`polyc-proto` can't depend on `polyc-crypto` for the
    /// real consts — see that function's own doc for the layer reason).
    /// `polyc-crypto` depends on `polyc-proto`, so this crate is the one
    /// that CAN cross-check them: feed this crate's own real consts in and
    /// confirm each produces its OWN distinct sentence shape, not the
    /// declined-shaped fallback every unrecognized string renders as.
    #[test]
    fn proto_question_answered_text_recognizes_this_crates_real_state_consts() {
        let answered = polyc_proto::question_answered_text(
            "Deploy target",
            ANSWERED_STATE,
            "@ada",
            "Production",
        );
        assert!(
            answered.contains("@ada answered"),
            "ANSWERED_STATE must render as a real answer, not the declined fallback: {answered}"
        );

        let auto_resolved = polyc_proto::question_answered_text(
            "Deploy target",
            AUTO_RESOLVED_STATE,
            "",
            "Production",
        );
        assert!(
            auto_resolved.contains("Nobody answered"),
            "AUTO_RESOLVED_STATE must render as an assumption, not the declined fallback: {auto_resolved}"
        );

        let declined =
            polyc_proto::question_answered_text("Deploy target", DECLINED_STATE, "@ada", "");
        assert!(
            declined.contains("@ada declined"),
            "DECLINED_STATE must render as a real decline: {declined}"
        );
    }
}

#[cfg(test)]
mod answer_token_tests {
    #![allow(clippy::pedantic, clippy::nursery, missing_docs)]
    use super::*;

    #[test]
    fn answer_token_verifies_for_its_own_question() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_answer_token("call-1", 0, "conv-A", 1_000, &signer);
        assert!(verify_answer_token(
            &token, "call-1", 0, "conv-A", 1_000, &signer
        ));
    }

    #[test]
    fn answer_token_rejects_a_different_question_index() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_answer_token("call-1", 0, "conv-A", 1_000, &signer);
        assert!(!verify_answer_token(
            &token, "call-1", 1, "conv-A", 1_000, &signer
        ));
    }

    #[test]
    fn answer_token_rejects_a_different_call_id() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_answer_token("call-1", 0, "conv-A", 1_000, &signer);
        assert!(!verify_answer_token(
            &token, "call-2", 0, "conv-A", 1_000, &signer
        ));
    }

    #[test]
    fn answer_token_rejects_a_different_conversation() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_answer_token("call-1", 0, "conv-A", 1_000, &signer);
        assert!(!verify_answer_token(
            &token, "call-1", 0, "conv-B", 1_000, &signer
        ));
    }

    #[test]
    fn answer_token_rejects_wrong_signer() {
        let signer = ApprovalSigner::from_seed(11);
        let other = ApprovalSigner::from_seed(12);
        let token = mint_answer_token("call-1", 0, "conv-A", 1_000, &signer);
        assert!(!verify_answer_token(
            &token, "call-1", 0, "conv-A", 1_000, &other
        ));
    }

    #[test]
    fn answer_token_rejects_after_ttl_elapses() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_answer_token("call-1", 0, "conv-A", 0, &signer);
        assert!(verify_answer_token(
            &token,
            "call-1",
            0,
            "conv-A",
            ANSWER_TOKEN_TTL_MS,
            &signer
        ));
        assert!(!verify_answer_token(
            &token,
            "call-1",
            0,
            "conv-A",
            ANSWER_TOKEN_TTL_MS + 1,
            &signer
        ));
    }

    #[test]
    fn answer_token_rejects_garbage() {
        let signer = ApprovalSigner::from_seed(11);
        assert!(!verify_answer_token(
            "not-hex", "call-1", 0, "conv-A", 0, &signer
        ));
        assert!(!verify_answer_token("", "call-1", 0, "conv-A", 0, &signer));
    }
}

#[cfg(test)]
mod canonical_freeze {
    //! Every signed canonical in this module, frozen as literal bytes (`#1845`).
    //!
    //! These are the bytes a deployment has already signed and has sitting in
    //! its log. They are checked in, never regenerated: regenerating one is the
    //! defect this module exists to catch, because a canonical whose bytes move
    //! invalidates every signature ever minted over the old ones.
    //!
    //! The reason they can be single literals at all is the conversion `#1845`
    //! made, following `#1842`. Before it, each canonical was a
    //! [`serde_json::Value`], whose object is a `BTreeMap` (keys sorted) by
    //! default and an `IndexMap` (insertion order) whenever anything in the
    //! build graph enables `serde_json/preserve_order` — so the same payload
    //! signed by two binaries with different dependency sets produced different
    //! bytes and different signatures. Every literal below is the
    //! insertion-order form, which is what a control-plane binary (where
    //! `preserve_order` is unified in) has always signed. Run this module under
    //! either selection and every literal holds:
    //!
    //! ```text
    //! cargo nextest run -p polyc-crypto                    # no preserve_order
    //! cargo nextest run -p polyc-crypto -p polyc-payments  # preserve_order on
    //! ```
    //!
    //! See ADR 0009 for the decision these literals enforce.
    #![allow(clippy::pedantic, clippy::nursery, missing_docs)]

    use super::*;

    /// Assert a canonical's bytes are exactly the frozen literal.
    fn frozen(label: &str, got: &[u8], want: &str) {
        assert_eq!(
            String::from_utf8(got.to_vec()).unwrap(),
            want,
            "{label}: canonical bytes moved — every signature over the old bytes is now unverifiable"
        );
    }

    const QUESTION_ARGS: &str =
        r#"{"questions":[{"prompt":"Ship it?","options":["Hold","Yes, proceed"]}]}"#;
    const MINTED_AT_MS: u64 = 1_750_000_000_000;

    #[test]
    fn answered_canonical_and_payload_are_frozen() {
        frozen(
            "answer_canonical (answered)",
            &answer_canonical(
                "call-1",
                0,
                QUESTION_ARGS,
                ANSWERED_STATE,
                Some(1),
                "Yes, proceed",
                "persona:alice",
                "conv-1",
                "nonce-answer",
            ),
            ANSWERED_CANONICAL,
        );
        let (full, sig, _) = answer_payload(
            "call-1",
            0,
            QUESTION_ARGS,
            ANSWERED_STATE,
            Some(1),
            "Yes, proceed",
            "persona:alice",
            "conv-1",
            "nonce-answer",
            &ApprovalSigner::from_seed(99),
        );
        frozen("answer_payload (answered)", &full, ANSWERED_PAYLOAD);
        assert_eq!(crate::hex::lower(&sig), ANSWERED_SIG);
    }

    // A decline signs `selected_index` as an explicit `null`, not an omitted
    // key — the shape the `json!` object this replaced emitted, and therefore
    // what every already-signed decline in a deployment's log covers.
    #[test]
    fn declined_canonical_and_payload_are_frozen() {
        frozen(
            "answer_canonical (declined)",
            &answer_canonical(
                "call-1",
                0,
                QUESTION_ARGS,
                DECLINED_STATE,
                None,
                "",
                "persona:alice",
                "conv-1",
                "nonce-answer",
            ),
            DECLINED_CANONICAL,
        );
        let (full, sig, _) = answer_payload(
            "call-1",
            0,
            QUESTION_ARGS,
            DECLINED_STATE,
            None,
            "",
            "persona:alice",
            "conv-1",
            "nonce-answer",
            &ApprovalSigner::from_seed(99),
        );
        frozen("answer_payload (declined)", &full, DECLINED_PAYLOAD);
        assert_eq!(crate::hex::lower(&sig), DECLINED_SIG);
    }

    #[test]
    fn answer_token_is_frozen() {
        frozen(
            "answer_token_canonical",
            &answer_token_canonical("call-1", 0, "conv-1", MINTED_AT_MS),
            TOKEN_CANONICAL,
        );
        assert_eq!(
            mint_answer_token(
                "call-1",
                0,
                "conv-1",
                MINTED_AT_MS,
                &ApprovalSigner::from_seed(99)
            ),
            TOKEN_MINTED,
            "a minted answer token's bytes are frozen — a token is hex of the whole object"
        );
    }

    const ANSWERED_CANONICAL: &str = r#"{"question_call_id":"call-1","question_index":0,"question_args_json":"{\"questions\":[{\"prompt\":\"Ship it?\",\"options\":[\"Hold\",\"Yes, proceed\"]}]}","state":"answered","selected_index":1,"selected_label":"Yes, proceed","answered_by":"persona:alice","conversation_id":"conv-1","nonce":"nonce-answer"}"#;
    const ANSWERED_PAYLOAD: &str = r#"{"question_call_id":"call-1","question_index":0,"question_args_json":"{\"questions\":[{\"prompt\":\"Ship it?\",\"options\":[\"Hold\",\"Yes, proceed\"]}]}","state":"answered","selected_index":1,"selected_label":"Yes, proceed","answered_by":"persona:alice","conversation_id":"conv-1","nonce":"nonce-answer","signed_by":"35ccaf567ce385fe73a3d0ef44c04c8e4f13cf02ec853ac430a8bfd40cefe008","signature_hex":"e7b877065d853887c0188eff5fb971a9d8e531e2c36e3ffa8d02dc5da2b3cb17a8dc140bfb1d6b4c6c6529d0b4890851516d03b1d633d96b1496d6713b08a705"}"#;
    const ANSWERED_SIG: &str = "e7b877065d853887c0188eff5fb971a9d8e531e2c36e3ffa8d02dc5da2b3cb17a8dc140bfb1d6b4c6c6529d0b4890851516d03b1d633d96b1496d6713b08a705";
    const DECLINED_CANONICAL: &str = r#"{"question_call_id":"call-1","question_index":0,"question_args_json":"{\"questions\":[{\"prompt\":\"Ship it?\",\"options\":[\"Hold\",\"Yes, proceed\"]}]}","state":"declined","selected_index":null,"selected_label":"","answered_by":"persona:alice","conversation_id":"conv-1","nonce":"nonce-answer"}"#;
    const DECLINED_PAYLOAD: &str = r#"{"question_call_id":"call-1","question_index":0,"question_args_json":"{\"questions\":[{\"prompt\":\"Ship it?\",\"options\":[\"Hold\",\"Yes, proceed\"]}]}","state":"declined","selected_index":null,"selected_label":"","answered_by":"persona:alice","conversation_id":"conv-1","nonce":"nonce-answer","signed_by":"35ccaf567ce385fe73a3d0ef44c04c8e4f13cf02ec853ac430a8bfd40cefe008","signature_hex":"5961a4cc427c84674a0a60b0f51552143b511751c2295705dbd323e062b504858de0f2209e67bb0c7a6826e80ec9831c2864c9f910cf7b4e137656da273fa30d"}"#;
    const DECLINED_SIG: &str = "5961a4cc427c84674a0a60b0f51552143b511751c2295705dbd323e062b504858de0f2209e67bb0c7a6826e80ec9831c2864c9f910cf7b4e137656da273fa30d";
    const TOKEN_CANONICAL: &str = r#"{"question_call_id":"call-1","question_index":0,"conversation_id":"conv-1","minted_at_ms":1750000000000}"#;
    const TOKEN_MINTED: &str = "7b227175657374696f6e5f63616c6c5f6964223a2263616c6c2d31222c227175657374696f6e5f696e646578223a302c22636f6e766572736174696f6e5f6964223a22636f6e762d31222c226d696e7465645f61745f6d73223a313735303030303030303030302c227369676e61747572655f686578223a223337633731353962313761313236643935323466313766616636323766623565396461626133313535616638316163666539313966633634363833653634626530333833386539363033383165313931366533643033626437333338653830353762636636326565313365643166353639363866616366323034373936643065227d";
}