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` (a human
//!   decision) or, non-interactively, by the `POLYCHROME_APPROVAL_MODE`
//!   machine-approval path (the reviewer-agent auto-review or the blanket
//!   approve-all mode) carrying a signed decision, distinguishable from a human
//!   one only by its signed `reason` (see [`auto_review_reason`] /
//!   [`AUTO_REVIEW_REASON_PREFIX`] / [`APPROVE_ALL_DANGEROUS_REASON`]).
//!
//! 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::collections::HashSet;
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 ApprovalSigner {
    /// Build a signer from a deterministic seed.
    ///
    /// **Insecure and test-only** (`#784`, `#1171`): this seed is public
    /// (it's checked into this source file's history), so every signature it
    /// mints is forgeable by anyone. Reachable only in tests / `test-util`
    /// builds — gone entirely from a release binary, which must load real
    /// key material via [`ApprovalSigner::from_key_bytes`] instead. There is
    /// deliberately no `Default` impl (`#1171`): every call site names its
    /// seed explicitly, or loads real key material, so a signer's provenance
    /// is never implicit.
    #[cfg(any(test, feature = "test-util"))]
    #[must_use]
    pub fn from_seed(seed: u64) -> Self {
        Self {
            inner: Arc::new(Signer::from_seed(seed)),
        }
    }

    /// Build a signer from raw ed25519 private-key bytes loaded from a
    /// secret store (`#784`) — the ONLY production-safe way to construct an
    /// [`ApprovalSigner`]. `bytes` must be exactly 32 bytes, the raw encoded
    /// ed25519 private key.
    ///
    /// # Errors
    ///
    /// Returns [`crate::SignerError`] if `bytes` is not a validly-encoded
    /// ed25519 private key.
    pub fn from_key_bytes(bytes: &[u8]) -> Result<Self, crate::SignerError> {
        Ok(Self {
            inner: Arc::new(Signer::from_key_bytes(bytes)?),
        })
    }

    /// 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)
    }

    /// Borrow the underlying platform [`Signer`], for the grant-family builders
    /// that take one directly (e.g. [`crate::grant::suspension_payload`], the
    /// platform's ed25519 kill switch for a live grant, #623). The suspension is
    /// signed by the SAME platform key every approval-side signature uses, so a
    /// suspension and a `grant_replay` in the audit trail share one signer.
    #[must_use]
    pub fn as_signer(&self) -> &Signer {
        &self.inner
    }
}

/// 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.
/// `sandbox_mode` is the sandbox/permission mode (`POLYCHROME_SANDBOX_MODE`) the
/// harness was running under when it paused this call. The control plane reads it
/// back at respond time and signs it into the response, so a remembered approval
/// is bound to the mode it was granted under.
/// `reason` is the OVERRIDE explanation for why the call is gated — empty for an
/// ordinary gated call, non-empty only for the lethal-trifecta / Rule-of-Two
/// containment override. It is presentation + audit (NOT covered by any
/// signature — the `approval_request` event itself is unsigned; the *response*
/// is what gets signed), so the durable log records WHY a trifecta-gated call
/// was paused, and the edge can render it on the approval card.
/// `missing_capabilities` records the capability shortfall the gate computed
/// when it paused the call (`#595`): the stable kebab-case names of the
/// capabilities the call required but was not granted. Read back at respond
/// time and signed into the response as `covered_capabilities`, so a
/// remembered grant is scoped to exactly what the approver saw it cover.
/// Empty for an ordinary policy/sandbox gate.
#[must_use]
pub fn request_payload(
    request_id: &str,
    tool_name: &str,
    args_json: &str,
    sandbox_mode: &str,
    reason: &str,
    missing_capabilities: &[String],
) -> Vec<u8> {
    serde_json::json!({
        "tool_name": tool_name,
        "args_json": args_json,
        "request_id": request_id,
        "sandbox_mode": sandbox_mode,
        "reason": reason,
        "missing_capabilities": missing_capabilities,
    })
    .to_string()
    .into_bytes()
}

/// The single source for the signed `approval_response` 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.
///
/// The signature binds the approval to the exact call identity (`request_id`,
/// `tool_name`, `args_json`) so a re-emitted same-id call with different
/// args/tool cannot inherit it, AND — for a "don't ask again" decision — to
/// `approved_for_session` plus the `caller` the memory is scoped to, so a
/// remembered approval is per-caller and unforgeable. A one-shot approval simply
/// signs `approved_for_session: false`.
///
/// `approver` (`#1025`, RFC 8693's `act`/actor claim, distinct from `caller`'s
/// `sub`/subject) is the identity that actually resolved this decision, when
/// the edge supplied one — NOT necessarily the same persona as `caller` (the
/// paused turn's own beneficiary): an admin approving on someone else's
/// behalf signs a DIFFERENT `approver` than `caller`. Omitted from the
/// canonical entirely when empty (rather than signed as `""`) so every
/// `approval_response` persisted before this field existed — and every one
/// an edge that doesn't yet supply an approver identity signs today — stays
/// byte-identical and continues to verify unchanged; only a genuinely
/// non-empty `approver` changes the signed shape, and that decision is
/// always signed by code that already knows about this field.
///
/// `sandbox_mode` is the sandbox/permission mode (`POLYCHROME_SANDBOX_MODE`) the
/// PAUSED turn ran under, resolved server-side from the request. Binding it means
/// a remembered approval granted under one mode cannot be replayed to auto-
/// approve a later call running under a different (e.g. more-privileged) mode —
/// the harness re-prompts. Empty when no mode was recorded.
///
/// `conversation_id` and `nonce` make the response a SINGLE-USE, conversation-
/// bound capability token (`#370`, closes `#77` bug 3B). `conversation_id` binds
/// the approval to the one conversation it was granted in, so a signed response
/// copied into a different conversation's log fails to verify against that
/// conversation. `nonce` is a per-approval unique value the consumer records on
/// use, so a captured token cannot be re-presented after it has been spent. Both
/// are covered by the signature, so neither can be re-targeted or replayed
/// without invalidating it.
/// `covered_capabilities` (`#595`) records the capability shortfall this
/// approval covered — the missing set the gate computed when it paused the
/// call. Covered by the signature, so the effective session-grant key is
/// (caller, tool, covered capabilities): if the tool's required set later
/// grows, the old grant does not cover the new capability and the gate asks
/// again. Empty for an approval of an ordinary policy/sandbox gate.
#[allow(clippy::too_many_arguments)] // each arg is a distinct signed field of the canonical contract
fn response_canonical(
    request_id: &str,
    tool_name: &str,
    args_json: &str,
    modified_args_json: &str,
    approved: bool,
    approved_for_session: bool,
    covered_capabilities: &[String],
    caller: &str,
    approver_id: &str,
    sandbox_mode: &str,
    reason: &str,
    injected_context: &str,
    conversation_id: &str,
    nonce: &str,
) -> Vec<u8> {
    let mut v = serde_json::json!({
        "request_id": request_id,
        "tool_name": tool_name,
        "args_json": args_json,
        "modified_args_json": modified_args_json,
        "approved": approved,
        "approved_for_session": approved_for_session,
        "covered_capabilities": covered_capabilities,
        "caller": caller,
        "sandbox_mode": sandbox_mode,
        "reason": reason,
        "injected_context": injected_context,
        "conversation_id": conversation_id,
        "nonce": nonce,
    });
    // See the doc comment on `response_payload` (#1025): omitted entirely
    // when empty, not signed as `""`, so this stays byte-identical to every
    // `approval_response` ever persisted before this field existed.
    if !approver_id.is_empty() {
        v["approver"] = serde_json::Value::String(approver_id.to_owned());
    }
    v.to_string().into_bytes()
}

/// JSON payload for an `approval_response` event.
///
/// The signature commits to the canonical (unsigned) JSON form: the call
/// identity (`request_id`, `tool_name`, `args_json`), the decision
/// (`approved`), the session scope
/// (`approved_for_session`) and the `caller` it is bound to. `signed_by` and
/// `signature_hex` are populated *after* the signer runs and are NOT covered by
/// the signature.
///
/// Each parameter is a distinct signed field, so they're passed individually
/// rather than wrapped in a struct (the canonical form is the contract).
///
/// `conversation_id` binds the token to the conversation it was granted in and
/// `nonce` is a per-approval unique value (the control plane mints a fresh one
/// per response); together they make the approval a single-use, conversation-
/// bound capability (`#370`). 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 response_payload(
    request_id: &str,
    tool_name: &str,
    args_json: &str,
    modified_args_json: &str,
    approved: bool,
    approved_for_session: bool,
    covered_capabilities: &[String],
    caller: &str,
    approver_id: &str,
    sandbox_mode: &str,
    reason: &str,
    injected_context: &str,
    conversation_id: &str,
    nonce: &str,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    let canonical_bytes = response_canonical(
        request_id,
        tool_name,
        args_json,
        modified_args_json,
        approved,
        approved_for_session,
        covered_capabilities,
        caller,
        approver_id,
        sandbox_mode,
        reason,
        injected_context,
        conversation_id,
        nonce,
    );
    let signature = signer.sign(&canonical_bytes);
    let pk = signer.public_key_bytes();
    let mut full = serde_json::json!({
        "request_id": request_id,
        "tool_name": tool_name,
        "args_json": args_json,
        "modified_args_json": modified_args_json,
        "approved": approved,
        "approved_for_session": approved_for_session,
        "covered_capabilities": covered_capabilities,
        "caller": caller,
        "sandbox_mode": sandbox_mode,
        "reason": reason,
        "injected_context": injected_context,
        "conversation_id": conversation_id,
        "nonce": nonce,
        "signed_by": crate::hex::lower(&pk),
        "signature_hex": crate::hex::lower(&signature),
    });
    // Same omit-when-empty rule as `response_canonical` (#1025) — keeps the
    // persisted payload byte-identical to before this field existed.
    if !approver_id.is_empty() {
        full["approver"] = serde_json::Value::String(approver_id.to_owned());
    }
    (full.to_string().into_bytes(), signature, pk)
}

/// Scope names for a signed taint-excision marker (`#590`).
///
/// `cascade` is the sound default: the named positions are excised AND so is
/// every model-authored content event after the earliest of them — the
/// recovery literature shows a model re-derives an injected instruction from
/// its own retained reasoning if only the source is removed. `source-only`
/// excises exactly the named positions: an explicit, human-vouched override
/// for content the person read and judged benign, named in the signed
/// payload so the audit trail shows which posture the human chose.
pub const EXCISION_SCOPE_CASCADE: &str = "cascade";
/// See [`EXCISION_SCOPE_CASCADE`].
pub const EXCISION_SCOPE_SOURCE_ONLY: &str = "source-only";

/// The canonical (signature-covered) form of a `taint_excision` marker.
///
/// Covers the conversation (a marker signed for one conversation cannot be
/// replayed into another), the scope, the named journal positions, and who
/// requested the excision — so a marker can be neither forged, re-targeted,
/// nor widened. `signed_by`/`signature_hex` are appended after signing and
/// are not covered.
fn excision_canonical(
    conversation_id: &str,
    scope: &str,
    positions: &[u64],
    requested_by: &str,
    reason: &str,
) -> Vec<u8> {
    serde_json::json!({
        "conversation_id": conversation_id,
        "scope": scope,
        "positions": positions,
        "requested_by": requested_by,
        "reason": reason,
    })
    .to_string()
    .into_bytes()
}

/// JSON payload for a signed `taint_excision` event (`#590`).
///
/// Returns `(full_payload_bytes, signature_bytes, public_key_bytes)`.
#[must_use]
pub fn excision_payload(
    conversation_id: &str,
    scope: &str,
    positions: &[u64],
    requested_by: &str,
    reason: &str,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    let canonical = excision_canonical(conversation_id, scope, positions, requested_by, reason);
    let signature = signer.sign(&canonical);
    let pk = signer.public_key_bytes();
    let full = serde_json::json!({
        "conversation_id": conversation_id,
        "scope": scope,
        "positions": positions,
        "requested_by": requested_by,
        "reason": reason,
        "signed_by": crate::hex::lower(&pk),
        "signature_hex": crate::hex::lower(&signature),
    });
    (full.to_string().into_bytes(), signature, pk)
}

/// The canonical (signature-covered) form of a `grant_replay` audit record
/// (`#594`).
///
/// Binds the conversation and turn the replay happened in, the tool the grant
/// cleared, the [`crate::grant::grant_ref`] of the grant that cleared it, the
/// capability names the grant kept against taint, and the template-coverage hash
/// (#618) the grant matched — so the durable record commits to exactly which
/// grant kept which capabilities on which turn. `signed_by`/`signature_hex` are
/// appended after signing and are not covered.
fn grant_replay_canonical(
    conversation_id: &str,
    turn_id: &str,
    tool: &str,
    grant_ref: &str,
    covered_capabilities: &[String],
    coverage_hash: &str,
) -> Vec<u8> {
    serde_json::json!({
        "conversation_id": conversation_id,
        "turn_id": turn_id,
        "tool": tool,
        "grant_ref": grant_ref,
        "covered_capabilities": covered_capabilities,
        "coverage_hash": coverage_hash,
    })
    .to_string()
    .into_bytes()
}

/// JSON payload for a signed `grant_replay` audit event (`#594`).
///
/// The durable, trust-tagged record PRD §12 requires that a replayed grant kept
/// a capability taint would have removed — appended by the control plane once per
/// grant-cleared gate (never a `tracing` line). Platform-signed (ed25519, the
/// [`ApprovalSigner`]) so the record is tamper-evident and attributable. The
/// field names match `polychrome.events.v1.GrantReplayEvent`, so the forensics
/// decoder renders it. Returns `(full_payload_bytes, signature_bytes,
/// public_key_bytes)`.
#[must_use]
#[allow(clippy::too_many_arguments)] // each arg is a distinct field of the audit record
pub fn grant_replay_payload(
    conversation_id: &str,
    turn_id: &str,
    tool: &str,
    grant_ref: &str,
    covered_capabilities: &[String],
    coverage_hash: &str,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    let canonical = grant_replay_canonical(
        conversation_id,
        turn_id,
        tool,
        grant_ref,
        covered_capabilities,
        coverage_hash,
    );
    let signature = signer.sign(&canonical);
    let pk = signer.public_key_bytes();
    let full = serde_json::json!({
        "conversation_id": conversation_id,
        "turn_id": turn_id,
        "tool": tool,
        "grant_ref": grant_ref,
        "covered_capabilities": covered_capabilities,
        "coverage_hash": coverage_hash,
        "signed_by": crate::hex::lower(&pk),
        "signature_hex": crate::hex::lower(&signature),
    });
    (full.to_string().into_bytes(), signature, pk)
}

/// Verify a persisted `grant_replay` audit payload against its embedded signer
/// (`#594`).
///
/// Rebuilds the canonical from the payload's own fields and checks the embedded
/// ed25519 signature. Returns `true` only when the signature covers the exact
/// record — a tamper to any bound field flips it to `false`. Fail-closed on any
/// malformed field or bad hex.
#[must_use]
pub fn verify_grant_replay(payload: &[u8]) -> bool {
    let Ok(v) = serde_json::from_slice::<serde_json::Value>(payload) else {
        return false;
    };
    let (
        Some(conversation_id),
        Some(turn_id),
        Some(tool),
        Some(grant_ref),
        Some(covered),
        Some(coverage_hash),
        Some(signed_by),
        Some(signature_hex),
    ) = (
        v.get("conversation_id").and_then(Value::as_str),
        v.get("turn_id").and_then(Value::as_str),
        v.get("tool").and_then(Value::as_str),
        v.get("grant_ref").and_then(Value::as_str),
        v.get("covered_capabilities").and_then(Value::as_array),
        v.get("coverage_hash").and_then(Value::as_str),
        v.get("signed_by").and_then(Value::as_str),
        v.get("signature_hex").and_then(Value::as_str),
    )
    else {
        return false;
    };
    let Some(covered_capabilities) = covered
        .iter()
        .map(|c| c.as_str().map(str::to_owned))
        .collect::<Option<Vec<_>>>()
    else {
        return false;
    };
    let (Some(pk), Some(sig)) = (
        crate::hex::decode(signed_by),
        crate::hex::decode(signature_hex),
    ) else {
        return false;
    };
    let canonical = grant_replay_canonical(
        conversation_id,
        turn_id,
        tool,
        grant_ref,
        &covered_capabilities,
        coverage_hash,
    );
    crate::verify(&pk, &canonical, &sig)
}

/// Whether `signer_pk` is a member of the deployment's pinned approval
/// allow-list (`#845`).
///
/// An internally-consistent ed25519 signature proves only that a payload was
/// not altered after it was signed; it says nothing about whether the signer is
/// one the deployment trusts, since anyone can mint a keypair, embed its own
/// public key, and self-sign an arbitrary payload. Every trust-gated verifier
/// therefore checks membership here before honoring a payload. An empty
/// allow-list trusts no one (fail closed). Shared by the grant-replay and
/// approval-response pinned verifiers so the allow-list check cannot drift
/// between them or from [`verify_signed_receipt`]'s.
fn signer_is_trusted(signer_pk: &[u8], trusted_signers: &[Vec<u8>]) -> bool {
    trusted_signers.iter().any(|k| k.as_slice() == signer_pk)
}

/// Verify a persisted `grant_replay` audit payload against a **trusted-signer
/// allow-list** (`#845`).
///
/// Like [`verify_grant_replay`] but additionally rejects any payload whose
/// embedded `signed_by` key is not one of `trusted_signers` — the deployment's
/// pinned approval public key(s), typically the running
/// [`ApprovalSigner::public_key_bytes`], since every `grant_replay` record this
/// control plane persists is self-signed with it. Without this gate an attacker
/// could sign a well-formed record with their own key, embed it, and have the
/// audit trail render it as `valid`. Mirrors [`verify_signed_receipt`]'s
/// allow-list gate. Returns `true` only when the signer is trusted AND the
/// signature covers the exact record; `false` (fail closed) on a malformed
/// payload, an untrusted signer, or a bad signature.
#[must_use]
pub fn verify_grant_replay_pinned(payload: &[u8], trusted_signers: &[Vec<u8>]) -> bool {
    // Gate on the allow-list before the (single-sourced) signature check: an
    // untrusted signer is rejected no matter how internally consistent its
    // signature is.
    let Some(pk) = serde_json::from_slice::<Value>(payload).ok().and_then(|v| {
        v.get("signed_by")
            .and_then(Value::as_str)
            .and_then(crate::hex::decode)
    }) else {
        return false;
    };
    if !signer_is_trusted(&pk, trusted_signers) {
        return false;
    }
    verify_grant_replay(payload)
}

/// A verified `taint_excision` marker.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VerifiedExcision {
    /// The conversation the marker is bound to.
    pub conversation_id: String,
    /// [`EXCISION_SCOPE_CASCADE`] or [`EXCISION_SCOPE_SOURCE_ONLY`].
    pub scope: String,
    /// The named journal positions.
    pub positions: Vec<u64>,
    /// Who requested the excision (persona id or operator identity).
    pub requested_by: String,
    /// Free-text audit reason.
    pub reason: String,
    /// The verified signer's public key (encoded).
    pub signer_public_key: Vec<u8>,
}

impl VerifiedExcision {
    /// Whether this marker's scope is the cascading (sound-default) one.
    #[must_use]
    pub fn is_cascade(&self) -> bool {
        self.scope == EXCISION_SCOPE_CASCADE
    }
}

/// Verify a persisted `taint_excision` payload.
///
/// `None` for a malformed payload, an unknown scope, or a signature that
/// does not verify — the caller ignores the marker and taint stays (fail
/// closed).
#[must_use]
pub fn verify_signed_excision(payload: &[u8]) -> Option<VerifiedExcision> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    let conversation_id = v.get("conversation_id")?.as_str()?.to_owned();
    let scope = v.get("scope")?.as_str()?.to_owned();
    if scope != EXCISION_SCOPE_CASCADE && scope != EXCISION_SCOPE_SOURCE_ONLY {
        return None;
    }
    let positions: Vec<u64> = v
        .get("positions")?
        .as_array()?
        .iter()
        .map(serde_json::Value::as_u64)
        .collect::<Option<Vec<_>>>()?;
    let requested_by = v.get("requested_by")?.as_str()?.to_owned();
    let reason = v.get("reason")?.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 =
        excision_canonical(&conversation_id, &scope, &positions, &requested_by, &reason);
    if verify(&pk, &canonical, &sig) {
        Some(VerifiedExcision {
            conversation_id,
            scope,
            positions,
            requested_by,
            reason,
            signer_public_key: pk,
        })
    } else {
        None
    }
}

/// JSON payload for an `approval_deferred` event (`#67` "send back").
///
/// A defer records that the approver bounced the call back without approving or
/// denying it — the audit trail shows the intent, but the pending
/// `approval_request` is NOT resolved (no `approval_response`), so the call stays
/// open. The signature commits to the call identity (`request_id`), the
/// `conversation_id` it was deferred in, and the free-form `reason`; `signed_by`
/// and `signature_hex` are appended after signing and are not covered.
///
/// Returns `(full_payload_bytes, signature_bytes, public_key_bytes)`.
#[must_use]
pub fn deferred_payload(
    request_id: &str,
    conversation_id: &str,
    reason: &str,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    let canonical = serde_json::json!({
        "request_id": request_id,
        "conversation_id": conversation_id,
        "reason": reason,
    })
    .to_string()
    .into_bytes();
    let signature = signer.sign(&canonical);
    let pk = signer.public_key_bytes();
    let full = serde_json::json!({
        "request_id": request_id,
        "conversation_id": conversation_id,
        "reason": reason,
        "signed_by": crate::hex::lower(&pk),
        "signature_hex": crate::hex::lower(&signature),
    });
    (full.to_string().into_bytes(), signature, pk)
}

/// Verify a persisted `approval_deferred` payload (`#67`).
///
/// Returns `Some((request_id, conversation_id, reason))` when the signature
/// checks out against the embedded key, else `None`.
#[must_use]
pub fn verify_deferred(payload: &[u8]) -> Option<(String, String, String)> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    let request_id = v.get("request_id")?.as_str()?.to_owned();
    let conversation_id = v.get("conversation_id")?.as_str()?.to_owned();
    let reason = v.get("reason")?.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 = serde_json::json!({
        "request_id": request_id,
        "conversation_id": conversation_id,
        "reason": reason,
    })
    .to_string()
    .into_bytes();
    verify(&pk, &canonical, &sig).then_some((request_id, conversation_id, reason))
}

/// JSON payload for a dispatch-mutation event (`#67`, #539/#540).
///
/// A signed record that a policy rewrote a call's args (`tool_input_rewrite`),
/// injected context (`tool_context_injection`), or redacted a result
/// (`tool_result_redaction`).
///
/// The signature commits to the event `kind` (so a record can't be re-filed under
/// another mutation kind), the call identity (`tool_call_id`, `tool_name`), the
/// conversation, and the mutation's `before`/`after` (proposed→executed args,
/// or empty→context, or original→redacted result). `signed_by` / `signature_hex`
/// are appended after signing and not covered. Returns
/// `(full_payload_bytes, signature_bytes, public_key_bytes)`.
#[must_use]
#[allow(clippy::too_many_arguments)] // each is a distinct signed field of the canonical contract
pub fn mutation_payload(
    kind: &str,
    tool_call_id: &str,
    tool_name: &str,
    conversation_id: &str,
    before: &str,
    after: &str,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    let canonical = serde_json::json!({
        "kind": kind,
        "tool_call_id": tool_call_id,
        "tool_name": tool_name,
        "conversation_id": conversation_id,
        "before": before,
        "after": after,
    })
    .to_string()
    .into_bytes();
    let signature = signer.sign(&canonical);
    let pk = signer.public_key_bytes();
    let full = serde_json::json!({
        "kind": kind,
        "tool_call_id": tool_call_id,
        "tool_name": tool_name,
        "conversation_id": conversation_id,
        "before": before,
        "after": after,
        "signed_by": crate::hex::lower(&pk),
        "signature_hex": crate::hex::lower(&signature),
    });
    (full.to_string().into_bytes(), signature, pk)
}

/// Verify a persisted dispatch-mutation payload (`#67`).
///
/// Returns the signed `(kind, tool_call_id, tool_name, conversation_id, before,
/// after)` when the signature checks out against the embedded key, else `None`.
#[must_use]
pub fn verify_mutation(payload: &[u8]) -> Option<(String, String, String, String, String, String)> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    let kind = v.get("kind")?.as_str()?.to_owned();
    let tool_call_id = v.get("tool_call_id")?.as_str()?.to_owned();
    let tool_name = v.get("tool_name")?.as_str()?.to_owned();
    let conversation_id = v.get("conversation_id")?.as_str()?.to_owned();
    let before = v.get("before")?.as_str()?.to_owned();
    let after = v.get("after")?.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 = serde_json::json!({
        "kind": kind,
        "tool_call_id": tool_call_id,
        "tool_name": tool_name,
        "conversation_id": conversation_id,
        "before": before,
        "after": after,
    })
    .to_string()
    .into_bytes();
    verify(&pk, &canonical, &sig).then_some((
        kind,
        tool_call_id,
        tool_name,
        conversation_id,
        before,
        after,
    ))
}

/// Reason-string prefix marking an `approval_response` as a reviewer-agent
/// auto-approval (`#377`), as opposed to a human decision.
///
/// The reviewer signs the EXACT same canonical `approval_response` a human
/// would — same [`response_payload`], same signer, same bound identity
/// (`request_id` + `tool_name` + `args_json` + `caller` + `sandbox_mode`),
/// `approved == true`, `approved_for_session == false` — so the wire/signature
/// contract is byte-for-byte identical and every existing verify path accepts
/// it unchanged. The ONLY field distinguishing an auto-approval from a human
/// one is the signed `reason`, which carries this prefix. Because `reason` is
/// covered by the signature (`response_canonical`), the distinction is
/// unforgeable: a compromised forwarder can neither launder an auto-approval as
/// human nor a human decision as auto without invalidating the signature. The
/// event log is therefore auditable for machine-vs-human consent off this one
/// signed field — the guardrail `#377` requires.
pub const AUTO_REVIEW_REASON_PREFIX: &str = "auto-review:";

/// Build the signed `reason` for a reviewer auto-approval at risk `tier`.
///
/// Carries [`AUTO_REVIEW_REASON_PREFIX`] so the audit log can tell it from a
/// human decision; `tier` (e.g. `"low"`) records WHY the classifier deemed the
/// call auto-eligible. The control plane passes the result as the `reason`
/// argument to the SAME [`response_payload`] the human path uses, so no
/// separate signing surface exists.
#[must_use]
pub fn auto_review_reason(tier: &str) -> String {
    format!("{AUTO_REVIEW_REASON_PREFIX}{tier}")
}

/// Whether a signed `reason` marks its `approval_response` as a reviewer
/// auto-approval (`#377`) rather than a human decision.
///
/// The audit distinguisher; it reads the signed `reason` field, so it cannot be
/// spoofed without breaking the signature.
#[must_use]
pub fn is_auto_review_reason(reason: &str) -> bool {
    reason.starts_with(AUTO_REVIEW_REASON_PREFIX)
}

/// Signed `reason` recorded for the blanket `approve-all-dangerous` mode.
///
/// Set by `POLYCHROME_APPROVAL_MODE=approve-all-dangerous` — the legible single
/// approve-all surface that replaced the legacy `POLYCHROME_APPROVE_ALL` flag.
/// Unlike [`auto_review_reason`] this is NOT a risk-classified verdict: it marks
/// an unconditional machine approval, so the audit log can tell a blanket
/// test-rig approval apart from both a human decision and a reviewer
/// auto-approval. Like every other reason it is covered by the signature, so the
/// distinction is unforgeable.
pub const APPROVE_ALL_DANGEROUS_REASON: &str = "approve-all-dangerous: blanket machine approval";

/// 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 — the approval applies only to this exact call.
    pub tool_name: String,
    /// The bound `args_json` — the model's PROPOSED args, the identity the
    /// approval is bound to. [`Self::authorizes_call`] matches this byte-for-byte,
    /// so a re-emitted call with different args cannot inherit the approval. This
    /// is the args the approver saw, NOT necessarily the args that execute.
    pub args_json: String,
    /// The approver's EDIT to the proposed args — the args to actually execute,
    /// or empty when the approver did not edit (execute `args_json` unchanged).
    /// Signed, so the edit is unforgeable and auditable; the delta from
    /// `args_json` is the recorded mutation. Resolve the effective execution args
    /// with the pure `polyc_agent::resolve_approved_call`.
    pub modified_args_json: String,
    /// Whether the request was approved.
    pub approved: bool,
    /// Whether the approval is remembered for the rest of the session ("don't
    /// ask again"); `false` for a one-shot approval.
    pub approved_for_session: bool,
    /// The capability shortfall this approval covered (`#595`): the stable
    /// kebab-case capability names the gate reported missing when it paused
    /// the call. Covered by the signature, so the effective session-grant key
    /// is (caller, tool, covered capabilities) — a grant recorded against one
    /// covered set never satisfies the same tool after its required set grows.
    /// Empty for an approval of an ordinary policy/sandbox gate.
    pub covered_capabilities: Vec<String>,
    /// The caller identity the (session) approval is scoped to — the paused
    /// turn's own beneficiary (RFC 8693 `sub`/subject), NOT necessarily who
    /// clicked. Set by the trusted control plane and covered by the
    /// signature, so a session grant cannot be re-scoped to a different user.
    pub caller: String,
    /// The identity that actually resolved this decision (`#1025`, RFC 8693
    /// `act`/actor), when the edge supplied one — empty otherwise (no edge
    /// integration yet, or a payload signed before this field existed).
    /// Distinct from `caller`: an admin approving on someone else's behalf
    /// signs a different `approver` than `caller`. For approval-policy
    /// checks and the audit trail ONLY — never fed into `principal_ref` (see
    /// `caller`'s own resume-attribution use in the control plane).
    pub approver: String,
    /// The sandbox/permission mode the paused turn ran under, covered by the
    /// signature so a grant cannot be replayed under a different mode.
    pub sandbox_mode: String,
    /// Free-form human-supplied reason.
    pub reason: String,
    /// Context the approver attached to inject before the tool runs — prepended
    /// as an `internal_only` message ahead of execution, or empty when none.
    /// Signed, so an injected instruction is unforgeable and recorded.
    pub injected_context: String,
    /// The conversation the approval was granted in, covered by the signature so
    /// a token signed for one conversation cannot be replayed into another
    /// (`#370`, closes `#77` bug 3B).
    pub conversation_id: String,
    /// Per-approval unique value, covered by the signature. A consumer records it
    /// on use so the token cannot be re-presented once spent (single-use, `#370`).
    pub nonce: String,
    /// The verified signer's public key (encoded).
    pub signer_public_key: Vec<u8>,
}

impl VerifiedResponse {
    /// Whether this verified, approved token authorizes the EXACT call
    /// `(request_id, tool_name, args_json)` — the args-binding (`#370` item 3).
    ///
    /// The signed `args_json` is matched byte-for-byte, so a re-emitted same-id
    /// call with different arguments (or a different tool) is NOT authorized: a
    /// captured approval can never be reused to run a different action. A denial
    /// (`approved == false`) authorizes nothing.
    #[must_use]
    pub fn authorizes_call(&self, request_id: &str, tool_name: &str, args_json: &str) -> bool {
        self.approved
            && self.request_id == request_id
            && self.tool_name == tool_name
            && self.args_json == args_json
    }
}

/// Verify a persisted `approval_response` payload.
///
/// Returns `Some(record)` if the signature checks out against the embedded
/// public key (the caller is responsible for trusting that public key — a key
/// allow-list lives alongside this in production). 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 tool_name = v.get("tool_name")?.as_str()?.to_owned();
    let args_json = v.get("args_json")?.as_str()?.to_owned();
    let modified_args_json = v.get("modified_args_json")?.as_str()?.to_owned();
    let approved = v.get("approved")?.as_bool()?;
    let approved_for_session = v.get("approved_for_session")?.as_bool()?;
    let covered_capabilities: Vec<String> = v
        .get("covered_capabilities")?
        .as_array()?
        .iter()
        .map(|c| c.as_str().map(str::to_owned))
        .collect::<Option<Vec<_>>>()?;
    let caller = v.get("caller")?.as_str()?.to_owned();
    // #1025: absent on every payload signed before this field existed (and
    // on any signed today with an empty approver — omitted, not `""`, at
    // sign time) — defaults to empty, NOT a decode failure.
    let approver_id = v
        .get("approver")
        .and_then(|x| x.as_str())
        .unwrap_or_default()
        .to_owned();
    let sandbox_mode = v.get("sandbox_mode")?.as_str()?.to_owned();
    let reason = v.get("reason")?.as_str()?.to_owned();
    let injected_context = v.get("injected_context")?.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 = response_canonical(
        &request_id,
        &tool_name,
        &args_json,
        &modified_args_json,
        approved,
        approved_for_session,
        &covered_capabilities,
        &caller,
        &approver_id,
        &sandbox_mode,
        &reason,
        &injected_context,
        &conversation_id,
        &nonce,
    );
    if verify(&pk, &canonical, &sig) {
        Some(VerifiedResponse {
            request_id,
            tool_name,
            args_json,
            modified_args_json,
            approved,
            approved_for_session,
            covered_capabilities,
            caller,
            approver: approver_id,
            sandbox_mode,
            reason,
            injected_context,
            conversation_id,
            nonce,
            signer_public_key: pk,
        })
    } else {
        None
    }
}

/// Verify a persisted `approval_response` payload against a **trusted-signer
/// allow-list** (`#845`).
///
/// Like [`verify_signed_response`] but additionally rejects any payload whose
/// embedded `signed_by` key is not one of `trusted_signers` — the deployment's
/// pinned approval public key(s), typically the running
/// [`ApprovalSigner::public_key_bytes`], since every `approval_response` this
/// control plane persists is self-signed with it. Without this gate an attacker
/// could sign a well-formed decision with their own key, embed it, and have it
/// honored as an approval. Mirrors [`verify_signed_receipt`]'s allow-list gate.
/// Returns `None` (fail closed) on a malformed payload, an untrusted signer, or
/// a bad signature.
#[must_use]
pub fn verify_signed_response_pinned(
    payload: &[u8],
    trusted_signers: &[Vec<u8>],
) -> Option<VerifiedResponse> {
    let verified = verify_signed_response(payload)?;
    // Reject an untrusted signer even though its signature is self-consistent:
    // anyone can mint a keypair, embed its public key, and self-sign.
    if !signer_is_trusted(&verified.signer_public_key, trusted_signers) {
        return None;
    }
    Some(verified)
}

/// Verify a persisted `approval_response` as a SINGLE-USE, conversation-bound
/// capability token (`#370`), gated on a **trusted-signer allow-list** (`#845`).
///
/// Returns the verified response only when ALL hold:
/// * the embedded `signed_by` key is a member of `trusted_signers` — the
///   deployment's pinned approval public key(s) (see
///   [`verify_signed_response_pinned`]); an internally-consistent signature over
///   an untrusted key authorizes nothing;
/// * the signature verifies against that key (provenance);
/// * the signed `conversation_id` equals `conversation_id` — a token signed for
///   one conversation is rejected when presented for another (closes `#77`
///   bug 3B);
/// * the signed `nonce` is non-empty AND not already in `consumed` — a token
///   that has been spent (its nonce recorded on a prior use) is rejected.
///
/// The caller binds the token to a specific call by matching the returned
/// [`VerifiedResponse::authorizes_call`], and MUST record the returned
/// [`VerifiedResponse::nonce`] into its `consumed` set before honoring it, so a
/// second presentation of the same token is rejected. An empty nonce is treated
/// as malformed and fails closed (every minted token carries one).
#[must_use]
pub fn verify_capability<S: std::hash::BuildHasher>(
    payload: &[u8],
    conversation_id: &str,
    consumed: &HashSet<String, S>,
    trusted_signers: &[Vec<u8>],
) -> Option<VerifiedResponse> {
    let verified = verify_signed_response_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 `approval_response`, binding the approval to its full
/// signed identity `(request_id, tool_name, args_json, approved,
/// approved_for_session, caller, reason)`.
///
/// Used by the harness when it receives `HarnessMessage.approval_responses` over
/// the wire and must confirm provenance AND identity before executing the paused
/// tool or honoring a "don't ask again" grant. The `caller` is covered by the
/// signature, so a compromised control plane cannot re-scope a remembered
/// approval onto a different user. 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_response(
    request_id: &str,
    tool_name: &str,
    args_json: &str,
    modified_args_json: &str,
    approved: bool,
    approved_for_session: bool,
    covered_capabilities: &[String],
    caller: &str,
    approver_id: &str,
    sandbox_mode: &str,
    reason: &str,
    injected_context: &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 = response_canonical(
        request_id,
        tool_name,
        args_json,
        modified_args_json,
        approved,
        approved_for_session,
        covered_capabilities,
        caller,
        approver_id,
        sandbox_mode,
        reason,
        injected_context,
        conversation_id,
        nonce,
    );
    verify(&pk, &canonical, &sig)
}

/// Whether an approval response is a session ("don't ask again") grant for
/// `current_caller`.
///
/// True when it is approved, flagged for the session, and bound to a non-empty
/// `caller` equal to the current turn's caller.
///
/// This is the per-USER isolation invariant — user A's remembered approval must
/// never auto-approve user B in a shared conversation. It lives here, in one
/// place, so the harness (which re-verifies signed wire responses) and the
/// control plane (the in-process path) cannot drift on *who* a remembered
/// approval applies to. Callers still gate the TOOL on its idempotency
/// separately ([`crate`] does not know tool policy).
#[must_use]
pub fn is_session_grant_for(
    approved: bool,
    approved_for_session: bool,
    caller: &str,
    current_caller: &str,
) -> bool {
    approved && approved_for_session && !caller.is_empty() && caller == current_caller
}

/// 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).
#[derive(Debug, Clone)]
pub struct DecodedResponse {
    /// Tool-call id this response answers.
    pub request_id: String,
    /// Bound tool name.
    pub tool_name: String,
    /// Bound `args_json` — the model's proposed args (identity binding).
    pub args_json: String,
    /// The approver's edit to the proposed args (empty = unedited).
    pub modified_args_json: String,
    /// Approve / deny decision.
    pub approved: bool,
    /// Whether the approval is remembered for the session ("don't ask again").
    pub approved_for_session: bool,
    /// The capability shortfall this approval covered (`#595`).
    pub covered_capabilities: Vec<String>,
    /// The caller identity the (session) approval is scoped to — the paused
    /// turn's own beneficiary, NOT necessarily who clicked. See `approver`.
    pub caller: String,
    /// The identity that actually resolved this decision (`#1025`), when the
    /// edge supplied one — empty otherwise (no edge integration yet, or a
    /// payload signed before this field existed). Distinct from `caller`.
    pub approver: String,
    /// The sandbox/permission mode the grant was made under.
    pub sandbox_mode: String,
    /// Human-supplied reason.
    pub reason: String,
    /// Context the approver attached to inject before execution (empty = none).
    pub injected_context: String,
    /// The conversation the approval was granted in (`#370` binding).
    pub conversation_id: String,
    /// Per-approval single-use nonce (`#370` binding).
    pub nonce: 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.
#[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")?.as_str()?.to_owned(),
        args_json: v.get("args_json")?.as_str()?.to_owned(),
        modified_args_json: v.get("modified_args_json")?.as_str()?.to_owned(),
        approved: v.get("approved")?.as_bool()?,
        approved_for_session: v.get("approved_for_session")?.as_bool()?,
        covered_capabilities: v
            .get("covered_capabilities")
            .and_then(Value::as_array)
            .map(|a| {
                a.iter()
                    .filter_map(|c| c.as_str().map(str::to_owned))
                    .collect()
            })
            .unwrap_or_default(),
        caller: v.get("caller")?.as_str()?.to_owned(),
        // #1025: absent on every payload signed before this field existed —
        // defaults to empty, NOT a decode failure (see `response_canonical`).
        approver: v
            .get("approver")
            .and_then(|x| x.as_str())
            .unwrap_or_default()
            .to_owned(),
        sandbox_mode: v.get("sandbox_mode")?.as_str()?.to_owned(),
        reason: v.get("reason")?.as_str()?.to_owned(),
        injected_context: v.get("injected_context")?.as_str()?.to_owned(),
        conversation_id: v.get("conversation_id")?.as_str()?.to_owned(),
        nonce: v.get("nonce")?.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(crate::hex::lower(&pk)),
        );
        map.insert(
            "signature_hex".to_owned(),
            Value::String(crate::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`/`outbound_payment_receipt` payload
/// against a **trusted-signer allow-list**.
///
/// Returns `Some(record)` only if the signature checks out against the
/// embedded public key AND that key is a member of `trusted_signers`. An
/// internally-consistent signature over an *unknown* key proves the payload
/// was not tampered with after signing — it proves nothing about whether the
/// signer should be trusted; anyone can mint a fresh keypair, embed its own
/// public key, and sign an arbitrary settlement, so a caller MUST supply the
/// deployment's own set of trusted signers here (typically the deployment's
/// [`ApprovalSigner::public_key_bytes`], since receipts are self-signed by
/// this same control plane) rather than treating "verifies" as "trustworthy".
///
/// Returns `None` if the payload is malformed, the hex fields don't decode,
/// the embedded key is not in `trusted_signers`, or the signature doesn't
/// verify.
#[must_use]
pub fn verify_signed_receipt(
    payload: &[u8],
    trusted_signers: &[Vec<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 = crate::hex::decode(signed_by_hex)?;
    let sig = crate::hex::decode(signature_hex)?;
    // Reject an unknown signer before doing any further work (including the
    // signature check below): a key that is not on the allow-list is not
    // trusted no matter how internally consistent its signature is — anyone
    // can mint a keypair and self-sign an arbitrary receipt.
    if !signer_is_trusted(&pk, trusted_signers) {
        return None;
    }
    // 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
    }
}

/// TTL for a minted `resolve_token` (`#787`).
///
/// Generous enough that a human has time to see and act on the approval card
/// (which can sit in a Slack/Telegram thread for hours), short enough that a
/// token captured off a stale card cannot resolve the request indefinitely.
/// Independent of the underlying approval's own lifetime — a request that
/// outlives the TTL simply needs the control plane to re-mint (a fresh
/// `ListPending` call re-renders the card with a fresh token).
pub const RESOLVE_TOKEN_TTL_MS: u64 = 24 * 60 * 60 * 1000;

/// The canonical (signature-covered) form of a `resolve_token` (`#787`).
///
/// Binds the token to the exact `(request_id, conversation_id)` pair it was
/// minted for and the time it was minted, so it cannot be replayed against a
/// different request, a different conversation, or presented once its TTL has
/// elapsed.
fn resolve_token_canonical(request_id: &str, conversation_id: &str, minted_at_ms: u64) -> Vec<u8> {
    serde_json::json!({
        "request_id": request_id,
        "conversation_id": conversation_id,
        "minted_at_ms": minted_at_ms,
    })
    .to_string()
    .into_bytes()
}

/// Mint a short-lived, signed `resolve_token` (`#787`) scoped to one
/// `(request_id, conversation_id)` pair.
///
/// This is the capability `ApprovalService.Respond` requires alongside the
/// plain `request_id`/`conversation_id` it already checks: minted by the
/// control plane at the moment it hands a pending approval to an edge for
/// rendering (`AgentEnd.pending_approvals`, `ListPendingReply.pending`), it is
/// opaque to — and unforgeable by — anything downstream of that mint point,
/// including a compromised harness pod (the harness never holds the signing
/// key and never sees the minted token; it only proposes the tool call the
/// token later authorizes resolving). `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 `request_id`.
#[must_use]
pub fn mint_resolve_token(
    request_id: &str,
    conversation_id: &str,
    minted_at_ms: u64,
    signer: &ApprovalSigner,
) -> String {
    let canonical = resolve_token_canonical(request_id, conversation_id, minted_at_ms);
    let signature = signer.sign(&canonical);
    let full = serde_json::json!({
        "request_id": request_id,
        "conversation_id": conversation_id,
        "minted_at_ms": minted_at_ms,
        "signature_hex": crate::hex::lower(&signature),
    });
    crate::hex::lower(full.to_string().as_bytes())
}

/// Verify a `resolve_token` minted by [`mint_resolve_token`] against the
/// `(request_id, 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 `request_id`
/// and `conversation_id` equal the ones supplied, and `now_ms - minted_at_ms`
/// is within [`RESOLVE_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_resolve_token(
    token: &str,
    request_id: &str,
    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_request_id),
        Some(bound_conversation_id),
        Some(minted_at_ms),
        Some(signature_hex),
    ) = (
        v.get("request_id").and_then(Value::as_str),
        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;
    };
    if bound_request_id != request_id || bound_conversation_id != conversation_id {
        return false;
    }
    let elapsed = now_ms.abs_diff(minted_at_ms);
    if elapsed > RESOLVE_TOKEN_TTL_MS {
        return false;
    }
    let Some(sig) = crate::hex::decode(signature_hex) else {
        return false;
    };
    let canonical = resolve_token_canonical(bound_request_id, bound_conversation_id, minted_at_ms);
    verify(&signer.public_key_bytes(), &canonical, &sig)
}

/// The canonical (signature-covered) form of an `admin_model_change` audit
/// record (`#787`).
///
/// Covers who made the change (the authenticated bearer principal), what the
/// selection moved from and to, and when — so the durable record cannot be
/// forged or re-attributed to a different operator without invalidating the
/// signature. `signed_by`/`signature_hex` are appended after signing and are
/// not covered.
fn admin_model_change_canonical(
    principal: &str,
    previous_provider: &str,
    previous_model: &str,
    new_provider: &str,
    new_model: &str,
    changed_at_ms: u64,
) -> Vec<u8> {
    serde_json::json!({
        "principal": principal,
        "previous_provider": previous_provider,
        "previous_model": previous_model,
        "new_provider": new_provider,
        "new_model": new_model,
        "changed_at_ms": changed_at_ms,
    })
    .to_string()
    .into_bytes()
}

/// JSON payload for a signed `admin_model_change` audit event (`#787`).
///
/// The durable, tamper-evident record that the live `provider/model`
/// selection changed, written on every successful `POST /admin/model` — the
/// same posture `#590`/`#594`/`#623` established for other admin-signed
/// actions. 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 admin_model_change_payload(
    principal: &str,
    previous_provider: &str,
    previous_model: &str,
    new_provider: &str,
    new_model: &str,
    changed_at_ms: u64,
    signer: &ApprovalSigner,
) -> (Vec<u8>, Vec<u8>, Vec<u8>) {
    let canonical = admin_model_change_canonical(
        principal,
        previous_provider,
        previous_model,
        new_provider,
        new_model,
        changed_at_ms,
    );
    let signature = signer.sign(&canonical);
    let pk = signer.public_key_bytes();
    let full = serde_json::json!({
        "principal": principal,
        "previous_provider": previous_provider,
        "previous_model": previous_model,
        "new_provider": new_provider,
        "new_model": new_model,
        "changed_at_ms": changed_at_ms,
        "signed_by": crate::hex::lower(&pk),
        "signature_hex": crate::hex::lower(&signature),
    });
    (full.to_string().into_bytes(), signature, pk)
}

/// A verified `admin_model_change` audit record.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VerifiedAdminModelChange {
    /// The authenticated bearer principal that made the change.
    pub principal: String,
    /// Provider before the change (may be empty — deferred to harness default).
    pub previous_provider: String,
    /// Model before the change.
    pub previous_model: String,
    /// Provider after the change.
    pub new_provider: String,
    /// Model after the change.
    pub new_model: String,
    /// Unix ms the change was applied.
    pub changed_at_ms: u64,
    /// The verified signer's public key (encoded).
    pub signer_public_key: Vec<u8>,
}

/// Verify a persisted `admin_model_change` payload.
///
/// `None` for a malformed payload or a signature that does not verify — the
/// caller treats the record as untrusted (fail closed).
#[must_use]
pub fn verify_admin_model_change(payload: &[u8]) -> Option<VerifiedAdminModelChange> {
    let v: Value = serde_json::from_slice(payload).ok()?;
    let principal = v.get("principal")?.as_str()?.to_owned();
    let previous_provider = v.get("previous_provider")?.as_str()?.to_owned();
    let previous_model = v.get("previous_model")?.as_str()?.to_owned();
    let new_provider = v.get("new_provider")?.as_str()?.to_owned();
    let new_model = v.get("new_model")?.as_str()?.to_owned();
    let changed_at_ms = v.get("changed_at_ms")?.as_u64()?;
    let pk = crate::hex::decode(v.get("signed_by")?.as_str()?)?;
    let sig = crate::hex::decode(v.get("signature_hex")?.as_str()?)?;
    let canonical = admin_model_change_canonical(
        &principal,
        &previous_provider,
        &previous_model,
        &new_provider,
        &new_model,
        changed_at_ms,
    );
    if verify(&pk, &canonical, &sig) {
        Some(VerifiedAdminModelChange {
            principal,
            previous_provider,
            previous_model,
            new_provider,
            new_model,
            changed_at_ms,
            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(),
    ))
}

/// Extract the `sandbox_mode` an `approval_request` was emitted under.
///
/// The mode the harness was running when it paused the call. Separate from
/// [`decode_request_fields`] so its many callers keep their tuple shape; the
/// control plane signs this into the response so a remembered approval is
/// bound to the mode it was granted under. Empty/absent → `""`.
#[must_use]
pub fn decode_request_sandbox_mode(payload: &[u8]) -> String {
    serde_json::from_slice::<Value>(payload)
        .ok()
        .and_then(|v| {
            v.get("sandbox_mode")
                .and_then(Value::as_str)
                .map(str::to_owned)
        })
        .unwrap_or_default()
}

/// Extract the override `reason` an `approval_request` carried.
///
/// Non-empty only for the lethal-trifecta / Rule-of-Two containment override;
/// empty/absent → `""` (an ordinary gated call, or a record written before the
/// field existed). Used by the edge to render the gate's explanation and by
/// forensics to show why a trifecta-gated call was paused.
#[must_use]
pub fn decode_request_reason(payload: &[u8]) -> String {
    serde_json::from_slice::<Value>(payload)
        .ok()
        .and_then(|v| v.get("reason").and_then(Value::as_str).map(str::to_owned))
        .unwrap_or_default()
}

/// Extract the `missing_capabilities` recorded on an `approval_request`
/// payload (`#595`) — the capability shortfall the gate computed when it
/// paused the call.
///
/// Read back at respond time and signed into the response as its
/// `covered_capabilities`. Absent or malformed decodes to empty: the grant
/// then covers nothing beyond the ordinary gate, the narrow direction.
#[must_use]
pub fn decode_request_missing_capabilities(payload: &[u8]) -> Vec<String> {
    serde_json::from_slice::<Value>(payload)
        .ok()
        .and_then(|v| {
            v.get("missing_capabilities")
                .and_then(Value::as_array)
                .map(|a| {
                    a.iter()
                        .filter_map(|c| c.as_str().map(str::to_owned))
                        .collect()
                })
        })
        .unwrap_or_default()
}

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

    use super::*;

    // #784: an `ApprovalSigner` built from real key material (the shape a
    // secret-store load produces) signs a genuine, verifiable
    // `approval_response`, and a signature minted under the well-known
    // deterministic `from_seed(1)` key does NOT verify against it — proving
    // the loaded key is a distinct, non-derivable key, not the forgeable
    // default.
    #[test]
    fn loaded_key_signature_verifies_and_from_seed_signature_does_not() {
        // Stand-in for key bytes read back from a secret store (any 32 bytes
        // are a valid ed25519 private key — no seed-derivation involved).
        let key_bytes = [42u8; 32];
        let loaded = ApprovalSigner::from_key_bytes(&key_bytes).expect("valid key material");
        let forged = ApprovalSigner::from_seed(1);
        assert_ne!(
            loaded.public_key_bytes(),
            forged.public_key_bytes(),
            "a loaded key must not collide with the public, deterministic seed-1 key"
        );

        let (payload, _sig, _pk) = response_payload(
            "req-1",
            "web_fetch",
            r#"{"url":"https://a"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "",
            "",
            "conv-1",
            "nonce-1",
            &loaded,
        );
        let verified = verify_signed_response(&payload).expect("verifies under the loaded key");
        assert_eq!(verified.signer_public_key, loaded.public_key_bytes());

        // The exact same payload, signed under `from_seed(1)` and stamped
        // with the LOADED key's public key (impersonation attempt), fails —
        // the seed-1 signature does not verify against the loaded key.
        let (forged_payload, _sig, _pk) = response_payload(
            "req-1",
            "web_fetch",
            r#"{"url":"https://a"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "",
            "",
            "conv-1",
            "nonce-1",
            &forged,
        );
        let mut v: serde_json::Value = serde_json::from_slice(&forged_payload).unwrap();
        v["signed_by"] = serde_json::json!(crate::hex::lower(&loaded.public_key_bytes()));
        assert!(
            verify_signed_response(v.to_string().as_bytes()).is_none(),
            "a from_seed(1) signature must not verify against the loaded key"
        );
    }

    // #594: a grant_replay audit record round-trips through verification and any
    // tamper to a bound field flips verification to false.
    #[test]
    fn grant_replay_audit_is_signed_and_tamper_evident() {
        let signer = ApprovalSigner::from_seed(9);
        let covered = vec!["arbitrary-egress".to_owned()];
        let (payload, _sig, _pk) = grant_replay_payload(
            "conv-1",
            "turn-7",
            "post_summary",
            "deadbeef",
            &covered,
            "sha256:template-abc",
            &signer,
        );
        assert!(verify_grant_replay(&payload), "the genuine record verifies");
        // Tampering any bound field breaks the signature.
        for (field, val) in [
            ("conversation_id", serde_json::json!("conv-EVIL")),
            ("turn_id", serde_json::json!("turn-8")),
            ("tool", serde_json::json!("exfiltrate")),
            ("grant_ref", serde_json::json!("cafe")),
            (
                "covered_capabilities",
                serde_json::json!(["arbitrary-egress", "mutate-external"]),
            ),
            ("coverage_hash", serde_json::json!("sha256:other")),
        ] {
            let mut v: Value = serde_json::from_slice(&payload).unwrap();
            v[field] = val;
            assert!(
                !verify_grant_replay(v.to_string().as_bytes()),
                "tampered {field} must fail verification"
            );
        }
        assert!(!verify_grant_replay(b"not json"));
    }

    // #595: the covered capability set is part of the signed contract — it
    // round-trips through verification and cannot be widened after signing.
    #[test]
    fn covered_capabilities_are_signed_and_tamper_evident() {
        let signer = ApprovalSigner::from_seed(42);
        let covered = vec!["arbitrary-egress".to_owned()];
        let (payload, _sig, _pk) = response_payload(
            "req-1",
            "web_fetch",
            r#"{"url":"https://a"}"#,
            "",
            true,
            true,
            &covered,
            "slack:T1:U9",
            "",
            "workspace-write",
            "",
            "",
            "conv-1",
            "nonce-1",
            &signer,
        );
        let verified = verify_signed_response(&payload).expect("verifies untampered");
        assert_eq!(verified.covered_capabilities, covered);

        // Widening the covered set after signing invalidates the signature.
        let mut v: serde_json::Value = serde_json::from_slice(&payload).unwrap();
        v["covered_capabilities"] = serde_json::json!(["arbitrary-egress", "mutate-external"]);
        assert!(
            verify_signed_response(v.to_string().as_bytes()).is_none(),
            "a tampered covered set must fail verification"
        );
        // So does shrinking it to hide what a grant covered.
        let mut v: serde_json::Value = serde_json::from_slice(&payload).unwrap();
        v["covered_capabilities"] = serde_json::json!([]);
        assert!(verify_signed_response(v.to_string().as_bytes()).is_none());
    }

    // #595: the request records the gate's capability shortfall and decodes
    // it back for the respond path; absent decodes empty (covers nothing).
    #[test]
    fn request_missing_capabilities_round_trip() {
        let missing = vec!["arbitrary-egress".to_owned(), "mutate-external".to_owned()];
        let bytes = request_payload("call-1", "web_fetch", "{}", "", "", &missing);
        assert_eq!(decode_request_missing_capabilities(&bytes), missing);
        let bare = request_payload("call-2", "grep", "{}", "", "", &[]);
        assert_eq!(
            decode_request_missing_capabilities(&bare),
            Vec::<String>::new()
        );
        assert_eq!(
            decode_request_missing_capabilities(b"{\"nope\":1}"),
            Vec::<String>::new()
        );
    }

    // #590: excision markers round-trip and are tamper-evident on every
    // covered field — widening positions, flipping scope, or re-targeting
    // the conversation all fail verification (taint stays, fail closed).
    #[test]
    fn signed_excision_round_trips_and_is_tamper_evident() {
        let signer = ApprovalSigner::from_seed(11);
        let (payload, _sig, _pk) = excision_payload(
            "conv-1",
            EXCISION_SCOPE_CASCADE,
            &[17, 23],
            "persona-9",
            "poisoned fetch",
            &signer,
        );
        let v = verify_signed_excision(&payload).expect("verifies untampered");
        assert_eq!(v.conversation_id, "conv-1");
        assert!(v.is_cascade());
        assert_eq!(v.positions, vec![17, 23]);
        assert_eq!(v.requested_by, "persona-9");

        for (field, value) in [
            ("positions", serde_json::json!([17, 23, 40])),
            ("scope", serde_json::json!(EXCISION_SCOPE_SOURCE_ONLY)),
            ("conversation_id", serde_json::json!("conv-2")),
            ("requested_by", serde_json::json!("someone-else")),
        ] {
            let mut t: serde_json::Value = serde_json::from_slice(&payload).unwrap();
            t[field] = value;
            assert!(
                verify_signed_excision(t.to_string().as_bytes()).is_none(),
                "tampered {field} must fail verification"
            );
        }
        // An unknown scope is refused even before the signature check.
        let mut t: serde_json::Value = serde_json::from_slice(&payload).unwrap();
        t["scope"] = serde_json::json!("everything");
        assert!(verify_signed_excision(t.to_string().as_bytes()).is_none());
        // Garbage is refused.
        assert!(verify_signed_excision(b"not json").is_none());
    }

    #[test]
    fn signed_response_round_trips() {
        let signer = ApprovalSigner::from_seed(42);
        // A one-shot approval: approved_for_session = false.
        let (payload, _sig, _pk) = response_payload(
            "req-1",
            "rm",
            r#"{"path":"/etc"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "looks fine",
            "",
            "conv-1",
            "nonce-1",
            &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, "rm");
        assert_eq!(verified.args_json, r#"{"path":"/etc"}"#);
        assert_eq!(verified.caller, "slack:T1:U9");
        assert_eq!(verified.conversation_id, "conv-1");
        assert_eq!(verified.nonce, "nonce-1");
        assert!(verified.approved);
        // A one-shot approval carries no session scope.
        assert!(!verified.approved_for_session);
    }

    /// #1025 backward compatibility: a payload signed BEFORE the `approver`
    /// field existed (no `approver` key at all, not merely an empty one)
    /// must still decode and verify byte-for-byte identically — every
    /// `approval_response` ever persisted was signed this way, and they are
    /// re-verified on every replay.
    ///
    /// The pre-#1025 shape is recomputed inline (NOT a hardcoded byte/hex
    /// fixture) rather than pinned literally: `Value::to_string()`'s key
    /// order depends on `serde_json`'s `preserve_order` feature, which flips
    /// under Cargo feature unification depending on what else is in the
    /// build graph (`#345`) — a literal fixture captured under one build
    /// configuration silently fails under another that unifies the feature
    /// differently, even though nothing about the signed *content* changed.
    /// See `receipt_payload_pins_v2_canonical_shape`'s identical note.
    #[test]
    fn pre_approver_field_payload_still_verifies_unchanged() {
        let signer = ApprovalSigner::from_seed(42);
        let (request_id, tool_name, args_json, modified_args_json) =
            ("req-1", "tool.name", r#"{"a":1}"#, "");
        let (approved, approved_for_session) = (true, true);
        let covered_capabilities = ["cap.a".to_owned(), "cap.b".to_owned()];
        let caller = "persona-caller";
        let sandbox_mode = "sandboxed";
        let reason = "looks fine";
        let injected_context = "";
        let conversation_id = "conv-1";
        let nonce = "nonce-1";

        // The exact pre-#1025 canonical/payload shape — the 13 fields
        // `response_canonical`/`response_payload` signed before `approver`
        // existed, recomputed here with the SAME macro call so both sides
        // agree under whatever key ordering is in effect for this build.
        let pre_approver_canonical = serde_json::json!({
            "request_id": request_id,
            "tool_name": tool_name,
            "args_json": args_json,
            "modified_args_json": modified_args_json,
            "approved": approved,
            "approved_for_session": approved_for_session,
            "covered_capabilities": covered_capabilities,
            "caller": caller,
            "sandbox_mode": sandbox_mode,
            "reason": reason,
            "injected_context": injected_context,
            "conversation_id": conversation_id,
            "nonce": nonce,
        });
        let expected_sig = signer.sign(pre_approver_canonical.to_string().as_bytes());
        let expected_pk = signer.public_key_bytes();
        let pre_approver_payload = serde_json::json!({
            "request_id": request_id,
            "tool_name": tool_name,
            "args_json": args_json,
            "modified_args_json": modified_args_json,
            "approved": approved,
            "approved_for_session": approved_for_session,
            "covered_capabilities": covered_capabilities,
            "caller": caller,
            "sandbox_mode": sandbox_mode,
            "reason": reason,
            "injected_context": injected_context,
            "conversation_id": conversation_id,
            "nonce": nonce,
            "signed_by": crate::hex::lower(&expected_pk),
            "signature_hex": crate::hex::lower(&expected_sig),
        })
        .to_string()
        .into_bytes();

        let verified = verify_signed_response(&pre_approver_payload)
            .expect("a pre-#1025 payload must still verify");
        assert_eq!(verified.request_id, request_id);
        assert_eq!(verified.caller, caller);
        assert_eq!(
            verified.approver, "",
            "no approver field existed on this payload — decodes to empty, not an error"
        );

        // Re-signing the SAME inputs with today's code (empty approver) must
        // reproduce byte-identical output — the additive field is omitted
        // from the canonical entirely when empty, not merely defaulted.
        let (regenerated, sig, pk) = response_payload(
            request_id,
            tool_name,
            args_json,
            modified_args_json,
            approved,
            approved_for_session,
            &covered_capabilities,
            caller,
            "",
            sandbox_mode,
            reason,
            injected_context,
            conversation_id,
            nonce,
            &signer,
        );
        assert_eq!(
            regenerated, pre_approver_payload,
            "an empty approver must produce byte-identical canonical/payload to before #1025"
        );
        assert_eq!(
            sig, expected_sig,
            "an empty approver must sign byte-identically to before #1025"
        );
        assert_eq!(pk, expected_pk, "public key must be unchanged");
    }

    #[test]
    fn session_response_round_trips_with_caller_binding() {
        let signer = ApprovalSigner::from_seed(42);
        let (payload, _sig, _pk) = response_payload(
            "req-1",
            "grep",
            r#"{"pattern":"x"}"#,
            "",
            true,
            true,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "remember it",
            "",
            "conv-1",
            "nonce-1",
            &signer,
        );
        let verified = verify_signed_response(&payload).expect("session signature verifies");
        assert!(verified.approved);
        assert!(verified.approved_for_session, "carries session scope");
        assert_eq!(verified.caller, "slack:T1:U9");
        assert_eq!(verified.tool_name, "grep");
        assert!(verified.approved);
    }

    #[test]
    fn tampered_session_or_caller_fails_verification() {
        let signer = ApprovalSigner::from_seed(42);
        let (payload, _sig, _pk) = response_payload(
            "req-1",
            "grep",
            "{}",
            "",
            true,
            true,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "ok",
            "",
            "conv-1",
            "nonce-1",
            &signer,
        );
        // Every signed field is covered: re-scoping the memory to another user,
        // flipping the session flag, swapping the tool, re-targeting the
        // conversation, or re-rolling the nonce must all fail.
        for (field, val) in [
            ("caller", Value::String("slack:T1:ATTACKER".to_owned())),
            ("approved_for_session", Value::Bool(false)),
            ("tool_name", Value::String("rm".to_owned())),
            ("approved", Value::Bool(false)),
            ("args_json", Value::String("EVIL".to_owned())),
            // The approver's edit and injected context are signed too: forging
            // either — swapping in different execution args, or a different
            // injected instruction — must invalidate the signature.
            (
                "modified_args_json",
                Value::String(r#"{"path":"/EVIL"}"#.to_owned()),
            ),
            ("injected_context", Value::String("do EVIL".to_owned())),
            (
                "sandbox_mode",
                Value::String("danger-full-access".to_owned()),
            ),
            ("conversation_id", Value::String("conv-OTHER".to_owned())),
            ("nonce", Value::String("nonce-OTHER".to_owned())),
        ] {
            let mut v: Value = serde_json::from_slice(&payload).unwrap();
            v[field] = val;
            assert!(
                verify_signed_response(&v.to_string().into_bytes()).is_none(),
                "tampering with {field} must fail verification"
            );
        }
    }

    /// #67 gate A: an approver can approve with EDITED args. The signed response
    /// carries both the model's PROPOSED args (`args_json`, the identity binding)
    /// and the approver's EDIT (`modified_args_json`, what executes). Both are
    /// covered by the signature. Crucially, the identity binding
    /// ([`VerifiedResponse::authorizes_call`]) still matches the PROPOSED args —
    /// so a model that re-emits a different call on resume cannot inherit the
    /// approval — while the edit is a separate signed field the executor
    /// substitutes. The pure resolver (`polyc_agent::resolve_approved_call`) owns
    /// the "empty edit ⇒ run proposed" defaulting; here we only pin the crypto
    /// contract: both fields round-trip, and identity binds the proposed args.
    #[test]
    fn edited_response_binds_proposed_and_carries_modified() {
        let signer = ApprovalSigner::from_seed(7);
        let proposed = r#"{"path":"/etc/shadow"}"#;
        let edited = r#"{"path":"/etc/hostname"}"#;
        let (payload, _sig, _pk) = response_payload(
            "call-1",
            "read_file",
            proposed,
            edited,
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "narrowed the path",
            "",
            "conv-1",
            "nonce-1",
            &signer,
        );
        let v = verify_signed_response(&payload).expect("edited approval verifies");
        assert_eq!(v.args_json, proposed, "identity binds the proposed args");
        assert_eq!(
            v.modified_args_json, edited,
            "the edit is carried and signed"
        );
        // Identity binding is against the PROPOSED args — this is what the model
        // must re-present on resume; the edit is not part of the identity.
        assert!(
            v.authorizes_call("call-1", "read_file", proposed),
            "the exact proposed call is authorized"
        );
        assert!(
            !v.authorizes_call("call-1", "read_file", edited),
            "the edited args are NOT the identity — authorizes_call binds proposed"
        );
    }

    /// #67 gate A: an unedited approval carries an empty `modified_args_json` and
    /// still authorizes exactly the proposed call — behaviourally identical to the
    /// pre-#67 approve path, so the common case is unchanged.
    #[test]
    fn unedited_response_carries_empty_edit() {
        let signer = ApprovalSigner::from_seed(7);
        let proposed = r#"{"path":"/tmp/x"}"#;
        let (payload, _sig, _pk) = response_payload(
            "call-1",
            "read_file",
            proposed,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "ok",
            "",
            "conv-1",
            "nonce-1",
            &signer,
        );
        let v = verify_signed_response(&payload).expect("verifies");
        assert!(v.modified_args_json.is_empty(), "no edit ⇒ empty");
        assert!(v.injected_context.is_empty(), "no injected context ⇒ empty");
        assert!(v.authorizes_call("call-1", "read_file", proposed));
    }

    /// #67 gate A: an approver can attach context to inject before the tool runs.
    /// The injected context is a signed field that round-trips.
    #[test]
    fn injected_context_round_trips_and_is_signed() {
        let signer = ApprovalSigner::from_seed(7);
        let (payload, _sig, _pk) = response_payload(
            "call-1",
            "shell",
            r#"{"cmd":"ls"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "ok",
            "only touch files under src/",
            "conv-1",
            "nonce-1",
            &signer,
        );
        let v = verify_signed_response(&payload).expect("verifies");
        assert_eq!(v.injected_context, "only touch files under src/");
    }

    /// #67 (#539/#540): a dispatch-mutation record round-trips and verifies;
    /// tampering with any covered field — including the kind — fails.
    #[test]
    fn mutation_round_trips_and_tamper_fails() {
        let signer = ApprovalSigner::from_seed(7);
        let (payload, _s, _p) = mutation_payload(
            "tool_input_rewrite",
            "call-1",
            "shell",
            "conv-1",
            r#"{"cmd":"rm -rf /"}"#,
            r#"{"cmd":"rm /tmp/x"}"#,
            &signer,
        );
        assert_eq!(
            verify_mutation(&payload).map(|t| (t.0, t.4, t.5)),
            Some((
                "tool_input_rewrite".to_owned(),
                r#"{"cmd":"rm -rf /"}"#.to_owned(),
                r#"{"cmd":"rm /tmp/x"}"#.to_owned()
            ))
        );
        for field in [
            "kind",
            "tool_call_id",
            "tool_name",
            "conversation_id",
            "before",
            "after",
        ] {
            let mut v: Value = serde_json::from_slice(&payload).unwrap();
            v[field] = Value::String("EVIL".to_owned());
            assert!(
                verify_mutation(&v.to_string().into_bytes()).is_none(),
                "tampering with {field} must fail"
            );
        }
    }

    /// #67 (#538): a deferred "send back" round-trips and verifies; tampering
    /// with any covered field fails.
    #[test]
    fn deferred_round_trips_and_tamper_fails() {
        let signer = ApprovalSigner::from_seed(7);
        let (payload, _sig, _pk) = deferred_payload("call-1", "conv-1", "need more info", &signer);
        assert_eq!(
            verify_deferred(&payload),
            Some((
                "call-1".to_owned(),
                "conv-1".to_owned(),
                "need more info".to_owned()
            ))
        );
        for field in ["request_id", "conversation_id", "reason"] {
            let mut v: Value = serde_json::from_slice(&payload).unwrap();
            v[field] = Value::String("EVIL".to_owned());
            assert!(
                verify_deferred(&v.to_string().into_bytes()).is_none(),
                "tampering with {field} must fail"
            );
        }
    }

    #[test]
    fn wire_verification_round_trips_and_binds_session_and_caller() {
        let signer = ApprovalSigner::from_seed(7);
        let (payload, _sig, _pk) = response_payload(
            "req-x",
            "grep",
            r#"{"p":"x"}"#,
            "",
            true,
            true,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "go",
            "",
            "conv-7",
            "nonce-7",
            &signer,
        );
        let d = decode_response_full(&payload).expect("decoded payload");
        // decode_response_full surfaces every signed field.
        assert!(d.approved_for_session);
        assert_eq!(d.caller, "slack:T1:U9");
        assert_eq!(d.sandbox_mode, "workspace-write");
        assert_eq!(d.conversation_id, "conv-7");
        assert_eq!(d.nonce, "nonce-7");
        assert!(verify_wire_response(
            &d.request_id,
            &d.tool_name,
            &d.args_json,
            "",
            d.approved,
            d.approved_for_session,
            &[],
            &d.caller,
            &d.approver,
            &d.sandbox_mode,
            &d.reason,
            "",
            &d.conversation_id,
            &d.nonce,
            &d.signer_pk_hex,
            &d.signature_hex
        ));
        // Re-scoping the remembered grant to a different caller over the wire
        // must fail — the caller is covered by the signature.
        assert!(!verify_wire_response(
            &d.request_id,
            &d.tool_name,
            &d.args_json,
            "",
            d.approved,
            d.approved_for_session,
            &[],
            "slack:T1:ATTACKER",
            &d.approver,
            &d.sandbox_mode,
            &d.reason,
            "",
            &d.conversation_id,
            &d.nonce,
            &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,
            &d.tool_name,
            r#"{"p":"EVIL"}"#,
            "",
            d.approved,
            d.approved_for_session,
            &[],
            &d.caller,
            &d.approver,
            &d.sandbox_mode,
            &d.reason,
            "",
            &d.conversation_id,
            &d.nonce,
            &d.signer_pk_hex,
            &d.signature_hex
        ));
        // Replaying the token into a DIFFERENT conversation over the wire must
        // fail — `conversation_id` is covered by the signature (#370, #77 3B).
        assert!(!verify_wire_response(
            &d.request_id,
            &d.tool_name,
            &d.args_json,
            "",
            d.approved,
            d.approved_for_session,
            &[],
            &d.caller,
            &d.approver,
            &d.sandbox_mode,
            &d.reason,
            "",
            "conv-OTHER",
            &d.nonce,
            &d.signer_pk_hex,
            &d.signature_hex
        ));
    }

    /// #1025: `approver` is a distinct fact from `caller`, recoverable from a
    /// signed response and covered by the signature — the same-person and
    /// different-person (admin-approves-for-someone-else) cases both round-trip
    /// correctly, and the two identities are never conflated.
    #[test]
    fn approver_is_recoverable_and_distinct_from_caller() {
        let signer = ApprovalSigner::from_seed(3);

        // Same-person: the caller approving their own paused turn signs an
        // approver equal to caller. Distinguishable by field, still equal by
        // value — this is the common case, not a degenerate one.
        let (self_approved, ..) = response_payload(
            "req-1",
            "grep",
            r#"{"q":"x"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "slack:T1:U9",
            "workspace-write",
            "self-approved",
            "",
            "conv-1",
            "nonce-1",
            &signer,
        );
        let self_decoded = decode_response_full(&self_approved).expect("decodes");
        assert_eq!(self_decoded.caller, "slack:T1:U9");
        assert_eq!(self_decoded.approver, "slack:T1:U9");
        let self_verified = verify_signed_response(&self_approved).expect("verifies");
        assert_eq!(self_verified.caller, self_verified.approver);

        // Different-person: an admin approves on behalf of the turn's own
        // beneficiary. `caller` stays the beneficiary (principal_ref's own
        // resume-attribution source, per the sibling #1024 fix); `approver` is
        // the admin — a genuinely different persona, both recoverable and
        // distinguishable from the same signed record.
        let (admin_approved, ..) = response_payload(
            "req-2",
            "rm",
            r#"{"path":"/tmp/x"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:BENEFICIARY",
            "slack:T1:ADMIN",
            "workspace-write",
            "approved on your behalf",
            "",
            "conv-2",
            "nonce-2",
            &signer,
        );
        let admin_decoded = decode_response_full(&admin_approved).expect("decodes");
        assert_eq!(admin_decoded.caller, "slack:T1:BENEFICIARY");
        assert_eq!(admin_decoded.approver, "slack:T1:ADMIN");
        assert_ne!(
            admin_decoded.caller, admin_decoded.approver,
            "admin-approves-for-someone-else must decode two DISTINCT identities"
        );
        let admin_verified = verify_signed_response(&admin_approved).expect("verifies");
        assert_eq!(admin_verified.caller, "slack:T1:BENEFICIARY");
        assert_eq!(admin_verified.approver, "slack:T1:ADMIN");

        // Tampering with the signed approver (re-scoping the policy/audit fact
        // to a different identity post-signing) invalidates the signature —
        // it is covered exactly like `caller`.
        let mut v: serde_json::Value = serde_json::from_slice(&admin_approved).unwrap();
        v["approver"] = serde_json::json!("slack:T1:ATTACKER");
        assert!(
            verify_signed_response(v.to_string().as_bytes()).is_none(),
            "a tampered approver must fail verification"
        );
    }

    /// `#377` core invariant: a reviewer auto-approval signs a payload that is
    /// BYTE-IDENTICAL to the one a human signs for the same decision, yet is
    /// distinguishable in the audit log by its signed `reason`.
    ///
    /// There is a single signing function ([`response_payload`]); the reviewer
    /// path is just that function with `approved == true`,
    /// `approved_for_session == false`, and an auto-review `reason`. We pin two
    /// properties:
    ///   1. With every argument INCLUDING the reason held equal, the auto and
    ///      human calls produce identical bytes + signature — proving the auto
    ///      path adds no hidden field and shares the human signing contract
    ///      exactly (guards against a future forked auto-signer).
    ///   2. With the auto-review reason, the response still verifies, still
    ///      carries `approved && !approved_for_session`, and is flagged by
    ///      [`is_auto_review_reason`] while a human reason is not — so the event
    ///      log can tell machine from human consent off the signed field alone.
    ///   3. Substitution resistance: flipping ANY one bound field — the tool, the
    ///      args, the beneficiary caller, or the request id — changes both the
    ///      canonical bytes AND the signature, so a forged or substituted
    ///      approval (signed for one call, replayed to authorize another) cannot
    ///      match. Without this, (1)'s byte-identical property would be vacuous.
    #[test]
    fn auto_review_signs_byte_identical_canonical_and_is_distinguishable() {
        let signer = ApprovalSigner::from_seed(7);
        let (rid, tool, args, caller, mode, conv, nonce) = (
            "req-9",
            "file_read",
            r#"{"path":"a.txt"}"#,
            "slack:T1:U9",
            "read-only",
            "conv-9",
            "nonce-9",
        );

        // (1) Same decision + same reason via the one signing path ⇒ identical
        // bytes regardless of which side "produced" it. The reviewer is not a
        // separate signer; it cannot diverge structurally from the human path.
        let shared_reason = auto_review_reason("low");
        let human_like = response_payload(
            rid,
            tool,
            args,
            "",
            true,
            false,
            &[],
            caller,
            "",
            mode,
            &shared_reason,
            "",
            conv,
            nonce,
            &signer,
        );
        let reviewer = response_payload(
            rid,
            tool,
            args,
            "",
            true,
            false,
            &[],
            caller,
            "",
            mode,
            &shared_reason,
            "",
            conv,
            nonce,
            &signer,
        );
        assert_eq!(human_like.0, reviewer.0, "auto path must be byte-identical");
        assert_eq!(human_like.1, reviewer.1, "signature must be identical");

        // (2) The auto-review response verifies and is an approve-once decision.
        let verified = verify_signed_response(&reviewer.0).expect("auto-review verifies");
        assert!(verified.approved);
        assert!(
            !verified.approved_for_session,
            "a machine decision is never remembered per-caller"
        );
        assert!(
            is_auto_review_reason(&verified.reason),
            "the signed reason marks this as an auto-approval"
        );

        // A genuine human approval over the same call is NOT flagged as auto —
        // the distinguisher reads the signed reason, so it is unforgeable.
        let (human_payload, _s, _p) = response_payload(
            rid,
            tool,
            args,
            "",
            true,
            false,
            &[],
            caller,
            "",
            mode,
            "looks fine",
            "",
            conv,
            nonce,
            &signer,
        );
        let human = verify_signed_response(&human_payload).expect("human verifies");
        assert!(!is_auto_review_reason(&human.reason));

        // The two payloads differ ONLY in the reason field — every bound
        // identity / decision / scope field is byte-equal, which is what makes
        // the auto path indistinguishable from a human one except by reason.
        let a: Value = serde_json::from_slice(&reviewer.0).unwrap();
        let h: Value = serde_json::from_slice(&human_payload).unwrap();
        for field in [
            "request_id",
            "tool_name",
            "args_json",
            "modified_args_json",
            "approved",
            "approved_for_session",
            "caller",
            "sandbox_mode",
            "injected_context",
            "conversation_id",
            "nonce",
        ] {
            assert_eq!(a[field], h[field], "{field} must match the human payload");
        }
        assert_ne!(a["reason"], h["reason"], "reason is the sole distinguisher");

        // (3) Substitution resistance: each variant holds every input equal to
        // `reviewer` and flips exactly ONE bound field. A different tool / args /
        // caller / request_id / conversation / nonce must change BOTH the
        // canonical bytes and the signature — so an approval signed for
        // `(req-9, file_read, a.txt, U9, conv-9, nonce-9)` can never be replayed to
        // authorize a write, a different path, a different beneficiary, a
        // different CONVERSATION (#370, #77 3B), or re-presented under a new nonce.
        // This is what makes (1)'s "byte-identical for identical inputs" a
        // security property and not just determinism.
        let base = &reviewer.0;
        let base_sig = &reviewer.1;
        for (label, variant) in [
            (
                "tool",
                response_payload(
                    rid,
                    "file_write",
                    args,
                    "",
                    true,
                    false,
                    &[],
                    caller,
                    "",
                    mode,
                    &shared_reason,
                    "",
                    conv,
                    nonce,
                    &signer,
                ),
            ),
            (
                "args",
                response_payload(
                    rid,
                    tool,
                    r#"{"path":"b.txt"}"#,
                    "",
                    true,
                    false,
                    &[],
                    caller,
                    "",
                    mode,
                    &shared_reason,
                    "",
                    conv,
                    nonce,
                    &signer,
                ),
            ),
            (
                "caller",
                response_payload(
                    rid,
                    tool,
                    args,
                    "",
                    true,
                    false,
                    &[],
                    "slack:T1:UEVIL",
                    "",
                    mode,
                    &shared_reason,
                    "",
                    conv,
                    nonce,
                    &signer,
                ),
            ),
            (
                "request_id",
                response_payload(
                    "req-OTHER",
                    tool,
                    args,
                    "",
                    true,
                    false,
                    &[],
                    caller,
                    "",
                    mode,
                    &shared_reason,
                    "",
                    conv,
                    nonce,
                    &signer,
                ),
            ),
            (
                "conversation_id",
                response_payload(
                    rid,
                    tool,
                    args,
                    "",
                    true,
                    false,
                    &[],
                    caller,
                    "",
                    mode,
                    &shared_reason,
                    "",
                    "conv-OTHER",
                    nonce,
                    &signer,
                ),
            ),
            (
                "nonce",
                response_payload(
                    rid,
                    tool,
                    args,
                    "",
                    true,
                    false,
                    &[],
                    caller,
                    "",
                    mode,
                    &shared_reason,
                    "",
                    conv,
                    "nonce-OTHER",
                    &signer,
                ),
            ),
        ] {
            assert_ne!(
                &variant.0, base,
                "{label}: a different {label} must change the canonical bytes"
            );
            assert_ne!(
                &variant.1, base_sig,
                "{label}: a different {label} must change the signature"
            );
        }
    }

    /// `#370` (a): a capability token signed for one conversation is REJECTED
    /// when presented for another. The `conversation_id` is covered by the
    /// signature, so it cannot be re-targeted without invalidating it; the
    /// consume gate ([`verify_capability`]) refuses any token whose signed
    /// conversation does not match the one it is being consumed in. Closes `#77`
    /// bug 3B (one signed response valid across conversations sharing a
    /// `request_id`).
    #[test]
    fn capability_rejected_across_conversations() {
        let signer = ApprovalSigner::from_seed(11);
        let (payload, _sig, _pk) = response_payload(
            "call-0",
            "delete_file",
            r#"{"path":"/etc/hosts"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "ok",
            "",
            "conv-A",
            "nonce-A",
            &signer,
        );
        let consumed = HashSet::new();
        // Same conversation, fresh nonce ⇒ honored.
        assert!(
            verify_capability(&payload, "conv-A", &consumed, &[signer.public_key_bytes()])
                .is_some(),
            "a token must verify in the conversation it was signed for"
        );
        // Different conversation ⇒ rejected, even though request_id/tool/args
        // are byte-identical (the #77 3B replay).
        assert!(
            verify_capability(&payload, "conv-B", &consumed, &[signer.public_key_bytes()])
                .is_none(),
            "a token signed for conv-A must be rejected when consumed in conv-B"
        );
    }

    /// `#370` (b): a single-use token is REJECTED on a second presentation. The
    /// consumer records the token's `nonce` after honoring it; a re-presentation
    /// of the SAME signed bytes (a captured/replayed token) is then refused.
    #[test]
    fn capability_is_single_use() {
        let signer = ApprovalSigner::from_seed(11);
        let (payload, _sig, _pk) = response_payload(
            "call-0",
            "delete_file",
            r#"{"path":"/etc/hosts"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "ok",
            "",
            "conv-A",
            "nonce-A",
            &signer,
        );
        let mut consumed = HashSet::new();
        // First presentation is honored and yields the bound nonce.
        let v = verify_capability(&payload, "conv-A", &consumed, &[signer.public_key_bytes()])
            .expect("first use honored");
        assert_eq!(v.nonce, "nonce-A");
        consumed.insert(v.nonce.clone());
        // Second presentation of the same token is rejected — single-use.
        assert!(
            verify_capability(&payload, "conv-A", &consumed, &[signer.public_key_bytes()])
                .is_none(),
            "a spent token must be rejected on re-presentation"
        );
    }

    /// `#370` (c)/(d): the token is ARGS-BOUND. A verified, approved token
    /// authorizes ONLY the exact `(request_id, tool_name, args_json)` it was
    /// signed for; a call with different args (a captured approval reused with a
    /// new payload) is NOT authorized, while the matching call IS.
    #[test]
    fn capability_authorizes_only_matching_args() {
        let signer = ApprovalSigner::from_seed(11);
        let (payload, _sig, _pk) = response_payload(
            "call-0",
            "delete_file",
            r#"{"path":"/tmp/scratch"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "ok",
            "",
            "conv-A",
            "nonce-A",
            &signer,
        );
        let consumed = HashSet::new();
        let v = verify_capability(&payload, "conv-A", &consumed, &[signer.public_key_bytes()])
            .expect("verifies in conv-A");
        // (c) different args ⇒ NOT authorized.
        assert!(
            !v.authorizes_call("call-0", "delete_file", r#"{"path":"/etc/hosts"}"#),
            "a token must not authorize a call with different args"
        );
        // …nor a different tool with the same id.
        assert!(
            !v.authorizes_call("call-0", "shell", r#"{"path":"/tmp/scratch"}"#),
            "a token must not authorize a different tool"
        );
        // (d) the exact signed call ⇒ authorized (happy path).
        assert!(
            v.authorizes_call("call-0", "delete_file", r#"{"path":"/tmp/scratch"}"#),
            "the exact signed call must be authorized"
        );
    }

    /// A denial never authorizes a call, regardless of identity match.
    #[test]
    fn denied_capability_authorizes_nothing() {
        let signer = ApprovalSigner::from_seed(11);
        let (payload, _sig, _pk) = response_payload(
            "call-0",
            "delete_file",
            "{}",
            "",
            false,
            false,
            &[],
            "slack:T1:U9",
            "",
            "workspace-write",
            "deny",
            "",
            "conv-A",
            "nonce-A",
            &signer,
        );
        let consumed = HashSet::new();
        let v = verify_capability(&payload, "conv-A", &consumed, &[signer.public_key_bytes()])
            .expect("verifies");
        assert!(!v.approved);
        assert!(
            !v.authorizes_call("call-0", "delete_file", "{}"),
            "a denied token authorizes nothing even on an exact identity match"
        );
    }

    #[test]
    fn request_payload_round_trips_id() {
        let bytes = request_payload(
            "call-7",
            "rm",
            r#"{"path":"/etc"}"#,
            "workspace-write",
            "",
            &[],
        );
        assert_eq!(decode_request_id(&bytes).as_deref(), Some("call-7"));
        // An ordinary gated call carries no override reason.
        assert_eq!(decode_request_reason(&bytes), "");
    }

    #[test]
    fn request_payload_carries_override_reason() {
        // The lethal-trifecta override reason rides the durable approval_request
        // so the signed log records WHY a trifecta-gated call was paused.
        let reason = "lethal-trifecta / Rule-of-Two: untrusted content is in context";
        let bytes = request_payload(
            "call-9",
            "web_fetch",
            r#"{"url":"https://x"}"#,
            "",
            reason,
            &[],
        );
        assert_eq!(decode_request_reason(&bytes), reason);
        // The existing scalar fields still decode unchanged.
        assert_eq!(decode_request_id(&bytes).as_deref(), Some("call-9"));
        assert_eq!(
            decode_request_fields(&bytes),
            Some((
                "call-9".to_owned(),
                "web_fetch".to_owned(),
                r#"{"url":"https://x"}"#.to_owned()
            ))
        );
    }

    /// 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": crate::hex::lower(&expected_pk),
            "signature_hex": crate::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 trusted = vec![signer.public_key_bytes()];
        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, &trusted).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 trusted = vec![signer.public_key_bytes()];
        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, &trusted)
            .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 trusted = vec![signer.public_key_bytes()];
        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, &trusted).is_none());
    }

    #[test]
    fn tampered_receipt_binding_field_fails_verification() {
        let signer = ApprovalSigner::from_seed(99);
        let trusted = vec![signer.public_key_bytes()];
        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, &trusted).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, &trusted).is_none());
    }

    /// The acceptance gate (issue #806): a receipt signed by a key that is
    /// NOT on the trusted-signer allow-list must fail verification, even
    /// though its signature is perfectly self-consistent — proving the
    /// allow-list, not mere signature validity, gates trust. The SAME
    /// receipt verifies once its signer is added to the allow-list.
    #[test]
    fn receipt_from_non_allowlisted_signer_is_rejected() {
        let trusted_signer = ApprovalSigner::from_seed(99);
        let attacker_signer = ApprovalSigner::from_seed(31337);
        let fields = ReceiptPayload {
            kind: "outbound_payment_receipt",
            reference: "tx-forged",
            amount: "100.00",
            currency: "USDC",
            recipient: "0xattacker",
            method: "tempo",
            timestamp: "2026-06-02T00:00:00Z",
            tool_call_id: "call-1",
            approval_pos: "42",
            approved_args_hash: "abcd1234",
            subject: "conv-xyz",
        };
        // The attacker signs a fully self-consistent receipt with THEIR OWN
        // key (not a forged signature over the trusted signer's key).
        let (payload, _sig, _pk) = receipt_payload(&fields, &attacker_signer);

        // An allow-list that does not include the attacker's key rejects it,
        // no matter how internally consistent the signature is.
        let trusted = vec![trusted_signer.public_key_bytes()];
        assert!(
            verify_signed_receipt(&payload, &trusted).is_none(),
            "a receipt signed by a non-allow-listed key must not verify"
        );

        // The IDENTICAL payload verifies once the attacker's key is
        // allow-listed (proves the rejection above was the allow-list, not
        // some other defect).
        let trusted_plus_attacker = vec![
            trusted_signer.public_key_bytes(),
            attacker_signer.public_key_bytes(),
        ];
        assert!(
            verify_signed_receipt(&payload, &trusted_plus_attacker).is_some(),
            "the same receipt must verify once its signer is allow-listed"
        );

        // An empty allow-list rejects every signer, including the deployment's
        // own — fail closed, never fail open on a misconfigured (empty) list.
        assert!(verify_signed_receipt(&payload, &[]).is_none());
    }

    /// The acceptance gate (issue #845): a `grant_replay` audit record signed by
    /// a key that is NOT on the trusted-signer allow-list must fail
    /// verification, even though its signature is perfectly self-consistent —
    /// the allow-list, not mere signature validity, gates trust. The SAME record
    /// verifies once its signer is allow-listed. Mirrors
    /// [`receipt_from_non_allowlisted_signer_is_rejected`].
    #[test]
    fn grant_replay_from_non_allowlisted_signer_is_rejected() {
        let trusted_signer = ApprovalSigner::from_seed(99);
        let attacker_signer = ApprovalSigner::from_seed(31337);
        let covered = vec!["arbitrary-egress".to_owned()];
        // The attacker signs a fully self-consistent record with THEIR OWN key.
        let (payload, _sig, _pk) = grant_replay_payload(
            "conv-1",
            "turn-7",
            "post_summary",
            "deadbeef",
            &covered,
            "sha256:template-abc",
            &attacker_signer,
        );

        // The unpinned verifier accepts it (signature is internally consistent) —
        // exactly the forgery surface this issue closes.
        assert!(
            verify_grant_replay(&payload),
            "the unpinned verifier trusts any self-consistent signature"
        );

        // An allow-list that does not include the attacker's key rejects it.
        let trusted = vec![trusted_signer.public_key_bytes()];
        assert!(
            !verify_grant_replay_pinned(&payload, &trusted),
            "a grant_replay signed by a non-allow-listed key must not verify"
        );

        // The IDENTICAL payload verifies once the attacker's key is allow-listed
        // (proves the rejection was the allow-list, not some other defect).
        let trusted_plus_attacker = vec![
            trusted_signer.public_key_bytes(),
            attacker_signer.public_key_bytes(),
        ];
        assert!(
            verify_grant_replay_pinned(&payload, &trusted_plus_attacker),
            "the same record must verify once its signer is allow-listed"
        );

        // An empty allow-list rejects every signer — fail closed.
        assert!(!verify_grant_replay_pinned(&payload, &[]));
    }

    /// The acceptance gate (issue #845): an `approval_response` signed by a key
    /// that is NOT on the trusted-signer allow-list must fail verification via
    /// both [`verify_signed_response_pinned`] and the single-use
    /// [`verify_capability`] gate, even though its signature is self-consistent.
    /// The SAME response verifies once its signer is allow-listed. Mirrors
    /// [`receipt_from_non_allowlisted_signer_is_rejected`].
    #[test]
    fn signed_response_from_non_allowlisted_signer_is_rejected() {
        let trusted_signer = ApprovalSigner::from_seed(99);
        let attacker_signer = ApprovalSigner::from_seed(31337);
        // The attacker self-signs a fully consistent approval with their key.
        let (payload, _sig, _pk) = response_payload(
            "call-0",
            "delete_file",
            r#"{"path":"/etc/hosts"}"#,
            "",
            true,
            false,
            &[],
            "slack:T1:U9",
            "slack:T1:U9",
            "workspace-write",
            "ok",
            "",
            "conv-A",
            "nonce-A",
            &attacker_signer,
        );

        // The unpinned verifier accepts it — the forgery surface this closes.
        assert!(
            verify_signed_response(&payload).is_some(),
            "the unpinned verifier trusts any self-consistent signature"
        );

        // Pinned to a legit allow-list that excludes the attacker ⇒ rejected,
        // both as a bare response and through the capability consume gate.
        let trusted = vec![trusted_signer.public_key_bytes()];
        let consumed = HashSet::new();
        assert!(
            verify_signed_response_pinned(&payload, &trusted).is_none(),
            "an approval_response signed by a non-allow-listed key must not verify"
        );
        assert!(
            verify_capability(&payload, "conv-A", &consumed, &trusted).is_none(),
            "the capability gate must reject a non-allow-listed signer"
        );

        // The IDENTICAL payload verifies once the attacker's key is allow-listed.
        let trusted_plus_attacker = vec![
            trusted_signer.public_key_bytes(),
            attacker_signer.public_key_bytes(),
        ];
        assert!(
            verify_signed_response_pinned(&payload, &trusted_plus_attacker).is_some(),
            "the same response must verify once its signer is allow-listed"
        );
        assert!(
            verify_capability(&payload, "conv-A", &consumed, &trusted_plus_attacker).is_some(),
            "the capability gate honors an allow-listed signer"
        );

        // An empty allow-list rejects every signer — fail closed.
        assert!(verify_signed_response_pinned(&payload, &[]).is_none());
        assert!(verify_capability(&payload, "conv-A", &consumed, &[]).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 trusted = vec![signer.public_key_bytes()];
        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": crate::hex::lower(&pk),
            "signature_hex": crate::hex::lower(&sig),
        })
        .to_string()
        .into_bytes();

        let verified =
            verify_signed_receipt(&v1, &trusted).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 trusted = vec![signer.public_key_bytes()];
        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(crate::hex::lower(&pk));
        full["signature_hex"] = Value::String(crate::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(), &trusted).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(), &trusted).is_some());
    }
}

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

    #[test]
    fn resolve_token_verifies_for_its_own_request_and_conversation() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_resolve_token("call-1", "conv-a", 1_000, &signer);
        assert!(verify_resolve_token(
            &token, "call-1", "conv-a", 1_000, &signer
        ));
    }

    #[test]
    fn resolve_token_rejects_a_different_request_id() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_resolve_token("call-1", "conv-a", 1_000, &signer);
        assert!(!verify_resolve_token(
            &token, "call-2", "conv-a", 1_000, &signer
        ));
    }

    #[test]
    fn resolve_token_rejects_a_different_conversation() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_resolve_token("call-1", "conv-a", 1_000, &signer);
        assert!(!verify_resolve_token(
            &token, "call-1", "conv-b", 1_000, &signer
        ));
    }

    #[test]
    fn resolve_token_rejects_wrong_signer() {
        let signer = ApprovalSigner::from_seed(11);
        let other = ApprovalSigner::from_seed(12);
        let token = mint_resolve_token("call-1", "conv-a", 1_000, &signer);
        assert!(!verify_resolve_token(
            &token, "call-1", "conv-a", 1_000, &other
        ));
    }

    #[test]
    fn resolve_token_rejects_after_ttl_elapses() {
        let signer = ApprovalSigner::from_seed(11);
        let token = mint_resolve_token("call-1", "conv-a", 0, &signer);
        assert!(verify_resolve_token(
            &token,
            "call-1",
            "conv-a",
            RESOLVE_TOKEN_TTL_MS,
            &signer
        ));
        assert!(!verify_resolve_token(
            &token,
            "call-1",
            "conv-a",
            RESOLVE_TOKEN_TTL_MS + 1,
            &signer
        ));
    }

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

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

    #[test]
    fn admin_model_change_round_trips_and_is_tamper_evident() {
        let signer = ApprovalSigner::from_seed(31);
        let (payload, _sig, _pk) = admin_model_change_payload(
            "team-a",
            "vertex",
            "old-model",
            "vertex",
            "new-model",
            1_000,
            &signer,
        );
        let verified = verify_admin_model_change(&payload).expect("genuine record verifies");
        assert_eq!(verified.principal, "team-a");
        assert_eq!(verified.new_model, "new-model");
        assert_eq!(verified.signer_public_key, signer.public_key_bytes());

        for (field, val) in [
            ("principal", serde_json::json!("attacker")),
            ("new_model", serde_json::json!("evil-model")),
            ("new_provider", serde_json::json!("evil-provider")),
        ] {
            let mut v: Value = serde_json::from_slice(&payload).unwrap();
            v[field] = val;
            assert!(
                verify_admin_model_change(v.to_string().as_bytes()).is_none(),
                "tampered {field} must fail verification"
            );
        }
    }
}