agentmux_common/

jekt_sign.rs

// Copyright 2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0

//! Jekt sender signing/verification — three schemes, one signed-material
//! format:
//!   - Host-tier: HMAC-SHA256, one shared key per agent (`sign_jekt`/
//!     `verify_jekt`). A 1:1 sender-to-local-srv relationship, so a
//!     symmetric key is fine — the srv instance is the sole verifier.
//!   - WAN, reagent only: Ed25519 against one pinned service keypair
//!     (`verify_reagent_jekt`). Multi-party (any receiving instance must
//!     verify without being able to forge), hence asymmetric.
//!   - LAN, any agent: Ed25519, one keypair per agent
//!     (`sign_lan_jekt`/`verify_lan_jekt`). Same multi-party reasoning as
//!     WAN, but per-sender instead of one pinned key — see
//!     docs/specs/SPEC_JEKT_LAN_TIER_SIGNING_2026_08_15.md.
//!
//! Shared between `agentmux-mcp` (the `SendMessage` tool signs an outgoing
//! jekt with the calling agent's own key, read from its `AGENTMUX_JEKT_KEY`/
//! `AGENTMUX_LAN_KEY` process env vars) and `agentmux-srv` (the reactive
//! handler verifies an incoming jekt's claimed signature against the
//! claimed sender's key, looked up server-side by agent_id — see
//! `crates/srv/src/backend/storage/agent_jekt_keys.rs` and
//! `agent_lan_keys.rs`). Living here, not in either binary, is what
//! guarantees the two can never independently drift on the signed-material
//! format.
//!
//! See docs/specs/SPEC_JEKT_TRUST_LAYER_COMPLETION_2026_08_13.md §2.2,
//! `docs/specs/SPEC_JEKT_SECURITY_AND_VISIBILITY_2026_07_01.md` §5.3 (the
//! original spec's never-built "Phase 5" this module implements), and
//! `docs/specs/SPEC_JEKT_LAN_TIER_SIGNING_2026_08_15.md`.
//!
//! The signed material binds sender, target, message id, and timestamp
//! together (not just msgid+payload) so a valid signature can't be replayed
//! against a different target or reattributed to a different claimed sender.

use base64::{engine::general_purpose::STANDARD as BASE64, Engine as _};
use ed25519_dalek::{Signature, Verifier, VerifyingKey};
use hmac::{Hmac, Mac};
use sha2::Sha256;

type HmacSha256 = Hmac<Sha256>;

/// Field separator inside the signed material — a control character, not a
/// character any of the individual fields can plausibly contain, so
/// concatenation can't be ambiguated by a field that happens to contain the
/// separator (msgid/agent ids are validated elsewhere to be alnum/_/-; the
/// message body is free text, but shifting the separator's *position* within
/// the body can't produce a colliding signature for a different logical
/// (source, target, msgid, ts) tuple, which is what actually matters here).
pub(crate) const FIELD_SEP: char = '\u{1}';

fn signed_material(msgid: &str, source_agent: &str, target_agent: &str, ts_secs: i64, message: &str) -> String {
    format!("{msgid}{FIELD_SEP}{source_agent}{FIELD_SEP}{target_agent}{FIELD_SEP}{ts_secs}{FIELD_SEP}{message}")
}

/// Decode a base64-encoded signing key (e.g. from the `AGENTMUX_JEKT_KEY`
/// process env var). Returns `None` on malformed input rather than erroring
/// — callers should treat that the same as "no key available" (sign
/// nothing, deliver unsigned rather than fail the send). Exposed here so
/// `agentmux-mcp` doesn't need its own `base64` dependency just for this.
pub fn decode_key(b64: &str) -> Option<Vec<u8>> {
    BASE64.decode(b64).ok()
}

/// Sign a jekt with the sender's key. Returns a base64-encoded HMAC-SHA256
/// tag. `key` of any length is accepted (HMAC's own key-hashing handles
/// that) but `agent_jekt_keys::agent_jekt_key_ensure` always mints 32 bytes.
pub fn sign_jekt(key: &[u8], msgid: &str, source_agent: &str, target_agent: &str, ts_secs: i64, message: &str) -> String {
    let material = signed_material(msgid, source_agent, target_agent, ts_secs, message);
    let mut mac = HmacSha256::new_from_slice(key).expect("HMAC accepts a key of any length");
    mac.update(material.as_bytes());
    BASE64.encode(mac.finalize().into_bytes())
}

/// Verify a claimed signature against the sender's stored key. Constant-time
/// comparison via `Mac::verify_slice` (not a manual `==`), so this can't leak
/// timing information about how much of the tag matched.
pub fn verify_jekt(
    key: &[u8],
    msgid: &str,
    source_agent: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
    sig_b64: &str,
) -> bool {
    let Ok(sig) = BASE64.decode(sig_b64) else { return false };
    let material = signed_material(msgid, source_agent, target_agent, ts_secs, message);
    let Ok(mut mac) = HmacSha256::new_from_slice(key) else { return false };
    mac.update(material.as_bytes());
    mac.verify_slice(&sig).is_ok()
}

// ---- WAN-tier sender signing (Ed25519) ----
//
// Distinct signing scheme from host-tier's HMAC above, and deliberately so:
// host-tier's key is minted per-instance and never leaves the srv process
// that owns it, so a symmetric secret shared only between "sign" and
// "verify" on the very same machine is the right tool. A WAN-tier service
// sender (e.g. the GitHub review-notification consumer, "reagent") is
// verified by *every* AgentMux instance on the network, not just its own
// account — an HMAC key distributed that widely is no longer meaningfully
// secret. Asymmetric signing lets the private key stay in exactly one
// place (the signing key held in AgentMux's private secret store) while
// every client ships only the public key, openly.
//
// Reuses the exact same `signed_material` construction as host-tier HMAC —
// same replay/reattribution-resistance properties (msgid+source+target+ts
// bound into what's signed), just a different signature algorithm over it.

/// Pinned Ed25519 public keys for AgentMux's own WAN-tier service senders.
/// Keyed by `key_id` (carried alongside the signature in the wire format)
/// so a future key rotation can add a new entry without invalidating
/// verification of messages already in flight when signed under the old
/// key. The matching private key is never present in this repo — it is
/// the signing key held in AgentMux's private secret store, used only by
/// the signing service.
///
/// `reagent-v1-dev` was a placeholder minted during initial implementation
/// (its private half was generated in a local shell for wiring/testing
/// purposes and was treated as already-exposed from the moment it was
/// generated) — kept registered here, but the signing service no longer
/// signs under it, so no genuine production traffic uses it. Left in place only
/// so any message that happened to be signed under it before the rotation
/// still verifies, matching this map's whole "add, don't replace" design.
///
/// `reagent-v1` (2026-08-14) is the real production key: generated so that
/// the private key was never printed, logged, or otherwise appeared in any
/// transcript — the private half is the signing key held in AgentMux's
/// private secret store, consistent with the exposure lesson
/// `reagent-v1-dev` was kept around specifically to document.
fn reagent_public_key(key_id: &str) -> Option<[u8; 32]> {
    match key_id {
        "reagent-v1-dev" => Some([
            104, 98, 241, 120, 99, 50, 230, 185, 228, 117, 241, 110, 130, 85, 252, 75, 141, 152,
            224, 92, 125, 154, 123, 40, 96, 149, 214, 172, 94, 120, 116, 200,
        ]),
        "reagent-v1" => Some([
            185, 72, 99, 0, 119, 36, 15, 50, 117, 0, 134, 93, 66, 39, 65, 21, 64, 229, 3, 157,
            238, 188, 79, 40, 74, 42, 99, 108, 28, 101, 243, 205,
        ]),
        _ => None,
    }
}

/// The one `key_id` whose matching private key is believed secret today.
/// `reagent-v1-dev` stays registered in `reagent_public_key` (so
/// `verify_reagent_jekt` still checks its signatures), but its private half
/// is documented above as exposed since it was generated, so a signature
/// under it proves nothing about the sender. Receivers record a reagent
/// signature as verified only through [`verify_trusted_reagent_jekt`],
/// which requires this key; any other key yields `reagent_verified =
/// Some(false)` — an active verification failure, forced sensitive.
pub fn is_reagent_trusted_signing_key(key_id: &str) -> bool {
    key_id == "reagent-v1"
}

/// Verify a WAN-tier jekt's claimed `reagent_sig` against the pinned public
/// key for `key_id`. Returns `false` (never panics) for an unknown
/// `key_id`, malformed base64, a malformed/wrong-length signature, or a
/// signature that simply doesn't verify — callers should treat all of
/// these identically: "not verified," rendering `SIG=invalid` rather than
/// `SIG=verified` in the marker (see `wrap_jekt_message`'s doc comment).
///
/// This function alone does NOT make a verified sender: a message signed
/// under `reagent-v1-dev` verifies here exactly like one under the
/// production key. Receivers must use [`verify_trusted_reagent_jekt`].
pub fn verify_reagent_jekt(
    key_id: &str,
    msgid: &str,
    source_agent: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
    sig_b64: &str,
) -> bool {
    let Some(pubkey_bytes) = reagent_public_key(key_id) else { return false };
    let Ok(verifying_key) = VerifyingKey::from_bytes(&pubkey_bytes) else { return false };
    let Ok(sig_bytes) = BASE64.decode(sig_b64) else { return false };
    let Ok(sig_arr) = <[u8; 64]>::try_from(sig_bytes.as_slice()) else { return false };
    let signature = Signature::from_bytes(&sig_arr);
    let material = signed_material(msgid, source_agent, target_agent, ts_secs, message);
    verifying_key.verify(material.as_bytes(), &signature).is_ok()
}

/// The verification result a receiver records as `reagent_verified`: the
/// signature checks out AND its key is the trusted production key. A
/// signature under any other registered key is not a verified sender.
pub fn verify_trusted_reagent_jekt(
    key_id: &str,
    msgid: &str,
    source_agent: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
    sig_b64: &str,
) -> bool {
    is_reagent_trusted_signing_key(key_id)
        && verify_reagent_jekt(key_id, msgid, source_agent, target_agent, ts_secs, message, sig_b64)
}

// ── LAN-tier per-agent Ed25519 signing (SPEC_JEKT_LAN_TIER_SIGNING_2026_08_15.md) ──
//
// Asymmetric, not HMAC like host-tier: LAN is multi-party (any receiving
// instance must be able to verify without being able to forge — the same
// reason reagent's WAN signing above is asymmetric, just per-agent instead
// of one pinned service key). Signed material is the exact same
// `signed_material` host-tier and reagent both already use — one format,
// three signature schemes layered on top depending on tier.

/// Generate a fresh Ed25519 keypair for a newly-registered agent's LAN
/// signing key. Returns `(public_key_bytes, private_key_seed_bytes)`, both
/// 32 bytes raw — callers base64-encode for storage/transport (mirrors
/// the `random_seed_bytes` + `BASE64.encode` split in the srv crate's
/// `agent_lan_keys.rs`).
///
/// No RNG dependency needed beyond what's already used for HMAC key
/// generation: `SigningKey::from_bytes` accepts any 32 bytes of randomness
/// as a valid seed (deterministic key derivation from the seed, not a
/// call into an RNG itself) — reusing the two-v4-UUIDs CSPRNG source
/// `agent_lan_keys.rs::random_seed_bytes` already established avoids
/// adding a `rand`/`getrandom` dependency here too.
pub fn generate_lan_keypair(seed: [u8; 32]) -> ([u8; 32], [u8; 32]) {
    let signing_key = ed25519_dalek::SigningKey::from_bytes(&seed);
    (signing_key.verifying_key().to_bytes(), seed)
}

/// Sign a jekt with the sending agent's own LAN private key (read from its
/// `AGENTMUX_LAN_KEY` process env var, mirroring `sign_jekt`'s
/// `AGENTMUX_JEKT_KEY` — called client-side, inside `agentmux-mcp`, never
/// server-side). `private_key` must be exactly 32 bytes (the seed
/// `generate_lan_keypair` produced) — returns `None` on any other length
/// rather than panicking, same "missing/malformed key must never block
/// sending" policy `sign_jekt`'s callers already rely on.
pub fn sign_lan_jekt(
    private_key: &[u8],
    msgid: &str,
    source_agent: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
) -> Option<String> {
    let seed: [u8; 32] = private_key.try_into().ok()?;
    let signing_key = ed25519_dalek::SigningKey::from_bytes(&seed);
    let material = signed_material(msgid, source_agent, target_agent, ts_secs, message);
    let signature = ed25519_dalek::Signer::sign(&signing_key, material.as_bytes());
    Some(BASE64.encode(signature.to_bytes()))
}

/// Verify a claimed LAN signature against the claimed sender's public key
/// (looked up server-side by `source_agent`, over the LAN peer-lookup RPC —
/// see `LanDiscovery::find_agent_lan_pubkey`). Returns `false` (never
/// panics) for a malformed public key, malformed base64, a
/// malformed/wrong-length signature, or a signature that simply doesn't
/// verify — same "treat all of these identically as not verified" policy
/// `verify_reagent_jekt` already documents.
pub fn verify_lan_jekt(
    public_key: &[u8],
    msgid: &str,
    source_agent: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
    sig_b64: &str,
) -> bool {
    let Ok(pubkey_arr) = <[u8; 32]>::try_from(public_key) else { return false };
    let Ok(verifying_key) = VerifyingKey::from_bytes(&pubkey_arr) else { return false };
    let Ok(sig_bytes) = BASE64.decode(sig_b64) else { return false };
    let Ok(sig_arr) = <[u8; 64]>::try_from(sig_bytes.as_slice()) else { return false };
    let signature = Signature::from_bytes(&sig_arr);
    let material = signed_material(msgid, source_agent, target_agent, ts_secs, message);
    verifying_key.verify(material.as_bytes(), &signature).is_ok()
}

// ── Cross-channel per-agent Ed25519 signing (SPEC_JEKT_CROSS_CHANNEL_TRUST_2026_09_02.md §D5) ──
//
// Same machine, different AgentMux instance. Asymmetric for the same reason
// LAN is: the receiving instance must be able to verify without being able to
// forge — and unlike host-tier's HMAC, the key can therefore be published in
// the host-global shared registry, which is what makes cross-channel
// verification possible at all (§5 of the spec explains why globalizing the
// symmetric host key instead would be strictly worse).
//
// Reuses the agent's EXISTING LAN keypair — no new key material, no new
// provisioning step. What it does NOT reuse is the signed material.

/// Domain separator for cross-channel signatures.
///
/// Without this, a cross-channel signature and a LAN signature over the same
/// (msgid, source, target, ts, message) tuple would be byte-identical, signed
/// by the byte-identical key — so either could be replayed as the other. The
/// tiers make different trust claims (`TRUST=lan-verified` vs
/// `TRUST=channel-verified`) and are verified against different key sources, so
/// they must not be interchangeable. Cheap now; a flag day later.
const CHANNEL_DOMAIN: &str = "amx-jekt-channel-v1";

/// Signed material for a cross-channel jekt.
///
/// Differs from [`signed_material`] in two ways, both load-bearing:
///  - the [`CHANNEL_DOMAIN`] prefix (see above), and
///  - `source_channel`, which binds the signature to the channel that minted
///    it. Without it, a signature legitimately produced by an agent running in
///    channel A could be replayed as that same agent speaking from channel B —
///    and since one agent name can legitimately be live in several channels at
///    once (`AgentEntry::channel` exists precisely because of that), the
///    receiver has no other way to tell those apart.
fn channel_signed_material(
    msgid: &str,
    source_agent: &str,
    source_channel: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
) -> String {
    format!(
        "{CHANNEL_DOMAIN}{FIELD_SEP}{msgid}{FIELD_SEP}{source_agent}{FIELD_SEP}\
         {source_channel}{FIELD_SEP}{target_agent}{FIELD_SEP}{ts_secs}{FIELD_SEP}{message}"
    )
}

/// Sign a cross-channel jekt with the sending agent's own LAN private key
/// (`AGENTMUX_LAN_KEY`) — called client-side in `agentmux-mcp`, never
/// server-side, exactly like [`sign_lan_jekt`].
///
/// `private_key` must be exactly 32 bytes (the seed [`generate_lan_keypair`]
/// produced); returns `None` on any other length rather than panicking — same
/// "a missing or malformed key must never block sending" policy the other
/// signers use. A message that can't be signed is delivered unsigned, and the
/// receiver decides what that means.
pub fn sign_channel_jekt(
    private_key: &[u8],
    msgid: &str,
    source_agent: &str,
    source_channel: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
) -> Option<String> {
    let seed: [u8; 32] = private_key.try_into().ok()?;
    let signing_key = ed25519_dalek::SigningKey::from_bytes(&seed);
    let material =
        channel_signed_material(msgid, source_agent, source_channel, target_agent, ts_secs, message);
    let signature = ed25519_dalek::Signer::sign(&signing_key, material.as_bytes());
    Some(BASE64.encode(signature.to_bytes()))
}

/// Verify a claimed cross-channel signature against the claimed sender's
/// published public key (read server-side from the host-global shared registry
/// entry — `AgentEntry::jekt_public_key`).
///
/// Returns `false`, never panics, for a malformed public key, malformed
/// base64, a wrong-length signature, or a signature that simply doesn't verify
/// — the same "all of these are identically 'not verified'" policy
/// [`verify_lan_jekt`] and [`verify_reagent_jekt`] already document. The
/// caller distinguishes "couldn't check" from "checked and failed"; this
/// function only answers the second question.
#[allow(clippy::too_many_arguments)]
pub fn verify_channel_jekt(
    public_key: &[u8],
    msgid: &str,
    source_agent: &str,
    source_channel: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
    sig_b64: &str,
) -> bool {
    let Ok(pubkey_arr) = <[u8; 32]>::try_from(public_key) else { return false };
    let Ok(verifying_key) = VerifyingKey::from_bytes(&pubkey_arr) else { return false };
    let Ok(sig_bytes) = BASE64.decode(sig_b64) else { return false };
    let Ok(sig_arr) = <[u8; 64]>::try_from(sig_bytes.as_slice()) else { return false };
    let signature = Signature::from_bytes(&sig_arr);
    let material =
        channel_signed_material(msgid, source_agent, source_channel, target_agent, ts_secs, message);
    verifying_key.verify(material.as_bytes(), &signature).is_ok()
}

// ── Cross-channel v2: bound to the sender's UID (identity M4d-6) ──
mod channel_v2;
pub use channel_v2::{sign_channel_jekt_v2, verify_channel_jekt_v2};
mod lan_v2;
pub use lan_v2::{sign_lan_jekt_v2, verify_lan_jekt_v2};

// ── General agent-to-agent WAN signing ──
//
// Issue #2586's second half. Asymmetric for the same reason LAN and
// cross-channel are — the receiving instance must verify without being able to
// forge — but with a different key-distribution story: the public half is
// published to muxbus's agent-ownership registry rather than fetched from a
// peer, because a WAN counterpart is by definition unreachable directly.
//
// **Only the signing primitives live here.** Publication, lookup, and
// verification wiring are deliberately NOT part of this change: verifying a
// WAN signature means resolving `(sender_account, source_agent)` to exactly
// one key, which waits on relay-side work tracked in the private cloud repo.
// Minting and signing are safe
// and useful ahead of that — an agent only gets a key when it is spawned, so
// starting now is what makes verification meaningful later instead of
// silently applying to nobody.

/// Domain separator for general agent-to-agent WAN signatures.
///
/// Exactly the same reasoning as [`CHANNEL_DOMAIN`], and load-bearing for the
/// same reason: `db_agent_wan_keys` is a *separate* keypair from
/// `db_agent_lan_keys`, but nothing structurally prevents a future change from
/// reusing one key across tiers, and an undomained signature over the shared
/// (msgid, source, target, ts, message) tuple would then be replayable from
/// one tier to the other. The tiers make different trust claims
/// (`TRUST=lan-verified` vs `TRUST=wan-verified`) against different key
/// sources — a LAN peer's own answer vs. the cloud registry — so they must
/// never be interchangeable.
const WAN_DOMAIN: &str = "amx-jekt-wan-v1";

/// Signed material for a general agent-to-agent WAN jekt.
///
/// Binds the sending **instance** (`source_host` + `source_channel`) as well
/// as the agent, for the same reason [`channel_signed_material`] binds
/// `source_channel`: one agent name can
/// legitimately be live on several instances under one account — a different
/// machine, or a different build channel on the same machine — and **each
/// mints its own keypair**, because each srv instance has its own database.
/// The instance therefore selects which key a signature is checked against,
/// so it has to be part of what the signature covers; otherwise a mislabelled
/// instance would silently select a different key rather than fail.
///
/// Deliberately does NOT bind the sender's muxbus account, even though
/// verification resolves the key by `(account, host, channel, agent)`: the
/// account is a cloud-side fact the signing process has no trustworthy view
/// of at sign time, and binding a client-asserted account into the signature
/// would let a sender pick which account's key it is checked against. The
/// account is resolved server-side from the authenticated caller instead
/// (§3.4.1) and selects the key; the signature then proves the agent and its
/// instance. Host and channel are different: both are injected into the
/// agent's env at spawn, so the sending process knows them reliably, and a
/// wrong value selects a key the signature cannot verify under — it grants
/// nothing.
fn wan_signed_material(
    msgid: &str,
    source_agent: &str,
    source_host: &str,
    source_channel: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
) -> String {
    format!(
        "{WAN_DOMAIN}{FIELD_SEP}{msgid}{FIELD_SEP}{source_agent}{FIELD_SEP}\
         {source_host}{FIELD_SEP}{source_channel}{FIELD_SEP}\
         {target_agent}{FIELD_SEP}{ts_secs}{FIELD_SEP}{message}"
    )
}

/// Generate an agent's WAN keypair from 32 bytes of seed entropy, returning
/// `(public_key, private_key)`.
///
/// Identical construction to [`generate_lan_keypair`] — same curve, same seed
/// handling — but kept as its own entry point because the two keys are
/// independent by design and must be minted separately: LAN public keys are
/// permanently trust-on-first-use pinned by peers
/// (`db_lan_peer_pubkey_pins`), which is exactly why
/// `SPEC_JEKT_HOST_KEY_TTL_ROTATION_2026_09_14.md` §4 declined to rotate them,
/// whereas WAN keys are served from an authoritative registry and are intended
/// to rotate. One key cannot have both lifecycles.
pub fn generate_wan_keypair(seed: [u8; 32]) -> ([u8; 32], [u8; 32]) {
    let signing_key = ed25519_dalek::SigningKey::from_bytes(&seed);
    (signing_key.verifying_key().to_bytes(), seed)
}

/// Sign a jekt with the sending agent's own WAN private key (read from its
/// `AGENTMUX_WAN_KEY` process env var, client-side inside `agentmux-mcp`,
/// never server-side — same placement as [`sign_lan_jekt`]).
///
/// `private_key` must be exactly 32 bytes (the seed [`generate_wan_keypair`]
/// produced); any other length returns `None` rather than panicking, matching
/// the "a missing or malformed key must never block sending" policy every
/// other signer here follows.
pub fn sign_wan_jekt(
    private_key: &[u8],
    msgid: &str,
    source_agent: &str,
    source_host: &str,
    source_channel: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
) -> Option<String> {
    let seed: [u8; 32] = private_key.try_into().ok()?;
    let signing_key = ed25519_dalek::SigningKey::from_bytes(&seed);
    let material = wan_signed_material(
        msgid,
        source_agent,
        source_host,
        source_channel,
        target_agent,
        ts_secs,
        message,
    );
    let signature = ed25519_dalek::Signer::sign(&signing_key, material.as_bytes());
    Some(BASE64.encode(signature.to_bytes()))
}

/// Verify a claimed WAN signature against the claimed sender's published
/// public key.
///
/// Returns `false` (never panics) for a malformed key, malformed base64, a
/// wrong-length signature, or a signature that simply doesn't verify — the
/// same "treat all of these identically as not verified" policy
/// [`verify_lan_jekt`] and [`verify_reagent_jekt`] document. Note that the
/// *caller* is responsible for the distinction that actually matters to tier
/// escalation: "no key could be resolved" (nothing to check against) is not
/// the same as "a key was resolved and this failed" (active forgery).
pub fn verify_wan_jekt(
    public_key: &[u8],
    msgid: &str,
    source_agent: &str,
    source_host: &str,
    source_channel: &str,
    target_agent: &str,
    ts_secs: i64,
    message: &str,
    sig_b64: &str,
) -> bool {
    let Ok(pubkey_arr) = <[u8; 32]>::try_from(public_key) else { return false };
    let Ok(verifying_key) = VerifyingKey::from_bytes(&pubkey_arr) else { return false };
    let Ok(sig_bytes) = BASE64.decode(sig_b64) else { return false };
    let Ok(sig_arr) = <[u8; 64]>::try_from(sig_bytes.as_slice()) else { return false };
    let signature = Signature::from_bytes(&sig_arr);
    let material = wan_signed_material(
        msgid,
        source_agent,
        source_host,
        source_channel,
        target_agent,
        ts_secs,
        message,
    );
    verifying_key.verify(material.as_bytes(), &signature).is_ok()
}

// ── W3-S: same-account WAN verification (SPEC_WAN_JEKT_VERIFICATION_2026_09_24.md) ──
//
// The pure half of W3-S: identifiers, the instance-signed agent-key
// certificate, the revocation record, and the checks a receiver runs on the
// fields the cloud relay carried. Storage, publishing, directory lookup and
// replay tracking live in agentmux-srv; the cloud re-implements the chain
// check in TypeScript and must match the
// byte formats here exactly — the fixed vectors in the tests below are the
// contract between the two.

/// Domain separator for an instance's certificate over one agent key (§2.2).
const WAN_CERT_DOMAIN: &str = "amx-wan-agent-cert-v1";

/// Domain separator for an instance revocation record (§2.2).
const WAN_REVOKE_DOMAIN: &str = "amx-wan-instance-revoke-v1";

/// How old a carried `wan_ts_secs` may be: the relay's own 1800 s delivery
/// TTL plus 300 s of slack (§2.4). A shorter window would reject messages
/// the relay is still legitimately holding.
pub const WAN_SIG_MAX_AGE_SECS: i64 = 1800 + 300;

/// How far in the future a carried `wan_ts_secs` may be — desktop clock skew
/// between sender and receiver (§2.4).
pub const WAN_SIG_MAX_FUTURE_SKEW_SECS: i64 = 300;

/// Length of an instance id: 128 bits as unpadded base32.
pub const WAN_INSTANCE_ID_LEN: usize = 26;

/// Length of a key fingerprint: 256 bits as unpadded base64url.
pub const WAN_KEY_FP_LEN: usize = 43;

const BASE32_ALPHABET: &[u8; 32] = b"abcdefghijklmnopqrstuvwxyz234567";

/// RFC 4648 base32, lowercase, no padding.
fn base32_lower_nopad(bytes: &[u8]) -> String {
    let mut out = String::with_capacity((bytes.len() * 8).div_ceil(5));
    let mut buffer: u32 = 0;
    let mut bits = 0;
    for &byte in bytes {
        buffer = (buffer << 8) | u32::from(byte);
        bits += 8;
        while bits >= 5 {
            bits -= 5;
            out.push(BASE32_ALPHABET[((buffer >> bits) & 0x1f) as usize] as char);
        }
    }
    if bits > 0 {
        out.push(BASE32_ALPHABET[((buffer << (5 - bits)) & 0x1f) as usize] as char);
    }
    out
}

/// An instance's id: the first 128 bits of `SHA-256(instance public key)`,
/// lowercase unpadded base32 — 26 chars of `[a-z2-7]` (§2.2).
///
/// Not secret. It names the key, so anything signed by the instance key can
/// be checked against the id without trusting whoever supplied the key.
pub fn wan_instance_id(instance_public_key: &[u8; 32]) -> String {
    use sha2::Digest;
    let digest = Sha256::digest(instance_public_key);
    base32_lower_nopad(&digest[..16])
}

/// An agent key's fingerprint: `SHA-256(agent public key)`, unpadded
/// base64url — 43 chars. Carried as `wan_key_fp`, an unsigned lookup hint
/// (§2.1): a wrong value finds a key the signature won't verify under.
pub fn wan_key_fingerprint(agent_public_key: &[u8; 32]) -> String {
    use base64::engine::general_purpose::URL_SAFE_NO_PAD;
    use sha2::Digest;
    URL_SAFE_NO_PAD.encode(Sha256::digest(agent_public_key))
}

/// Whether `host_hint` is safe to render: `[a-z0-9.-]{1,48}` (§2.6). The
/// hint is sender-chosen; anything else renders as `?`.
pub fn is_valid_wan_host_hint(host_hint: &str) -> bool {
    (1..=48).contains(&host_hint.len())
        && host_hint.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'.' || b == b'-')
}

/// The label a human sees for a verified instance: `<host_hint>~<id8>`
/// (§2.6). The suffix comes from the id the chain proved, never from the
/// sender's own label, so two instances claiming the same hostname still
/// render differently.
pub fn wan_instance_display_label(host_hint: &str, verified_instance_id: &str) -> String {
    let hint = if is_valid_wan_host_hint(host_hint) { host_hint } else { "?" };
    let id8: String = verified_instance_id.chars().take(8).collect();
    format!("{hint}~{id8}")
}

/// Whether a carried `wan_ts_secs` is inside the freshness window (§2.4).
/// Both bounds inclusive. Outside it the verdict is `None` (stale), not
/// `Some(false)`: a stale signature grants nothing that dropping it wouldn't.
pub fn wan_sig_is_fresh(wan_ts_secs: i64, now_secs: i64) -> bool {
    now_secs.saturating_sub(wan_ts_secs) <= WAN_SIG_MAX_AGE_SECS
        && wan_ts_secs.saturating_sub(now_secs) <= WAN_SIG_MAX_FUTURE_SKEW_SECS
}

/// ASCII case-insensitive equality after trimming — the one comparison every
/// W3-S identifier check uses (§2.1). Agent ids are ASCII-only, and the cloud
/// lowercases most of them but stores `github*` sources raw.
fn wan_id_eq(a: &str, b: &str) -> bool {
    a.trim().eq_ignore_ascii_case(b.trim())
}

fn wan_cert_material(
    instance_id: &str,
    agent_id: &str,
    channel: &str,
    agent_public_key_b64: &str,
    host_hint: &str,
    issued_at: i64,
) -> String {
    let agent_id = agent_id.to_ascii_lowercase();
    format!(
        "{WAN_CERT_DOMAIN}{FIELD_SEP}{instance_id}{FIELD_SEP}{agent_id}{FIELD_SEP}\
         {channel}{FIELD_SEP}{agent_public_key_b64}{FIELD_SEP}{host_hint}{FIELD_SEP}{issued_at}"
    )
}

fn wan_revoke_material(old_instance_id: &str, new_instance_id: &str, revoked_at: i64) -> String {
    format!("{WAN_REVOKE_DOMAIN}{FIELD_SEP}{old_instance_id}{FIELD_SEP}{new_instance_id}{FIELD_SEP}{revoked_at}")
}

pub(crate) fn ed25519_sign_b64(private_key: &[u8], material: &str) -> Option<String> {
    let seed: [u8; 32] = private_key.try_into().ok()?;
    let signing_key = ed25519_dalek::SigningKey::from_bytes(&seed);
    let signature = ed25519_dalek::Signer::sign(&signing_key, material.as_bytes());
    Some(BASE64.encode(signature.to_bytes()))
}

pub(crate) fn ed25519_verify_b64(public_key: &[u8; 32], material: &str, sig_b64: &str) -> bool {
    let Ok(verifying_key) = VerifyingKey::from_bytes(public_key) else { return false };
    let Ok(sig_bytes) = BASE64.decode(sig_b64) else { return false };
    let Ok(sig_arr) = <[u8; 64]>::try_from(sig_bytes.as_slice()) else { return false };
    verifying_key.verify(material.as_bytes(), &Signature::from_bytes(&sig_arr)).is_ok()
}

pub(crate) fn decode_public_key_b64(b64: &str) -> Option<[u8; 32]> {
    BASE64.decode(b64).ok()?.try_into().ok()
}

/// One entry in the per-account key directory (§2.2): an agent key,
/// certified by the instance that minted it. Public keys are standard
/// base64 of the raw 32 bytes; `cert_sig` is standard base64 Ed25519.
///
/// Every field is untrusted until [`WanKeyRecord::check_chain`] passes —
/// the record arrives from the cloud, which may be tampering.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct WanKeyRecord {
    pub instance_id: String,
    pub agent_id: String,
    pub channel: String,
    pub key_fp: String,
    pub instance_pubkey: String,
    pub agent_pubkey: String,
    pub host_hint: String,
    pub issued_at: i64,
    pub cert_sig: String,
}

impl WanKeyRecord {
    /// Certify `agent_public_key` with the instance key. Called by the srv
    /// that owns the instance; returns `None` for a malformed instance
    /// private key, never panics.
    pub fn certify(
        instance_private_key: &[u8],
        agent_id: &str,
        channel: &str,
        agent_public_key: &[u8; 32],
        host_hint: &str,
        issued_at: i64,
    ) -> Option<Self> {
        let seed: [u8; 32] = instance_private_key.try_into().ok()?;
        let instance_public_key = ed25519_dalek::SigningKey::from_bytes(&seed).verifying_key().to_bytes();
        let instance_id = wan_instance_id(&instance_public_key);
        let agent_pubkey = BASE64.encode(agent_public_key);
        let material = wan_cert_material(&instance_id, agent_id, channel, &agent_pubkey, host_hint, issued_at);
        Some(Self {
            instance_id,
            agent_id: agent_id.to_ascii_lowercase(),
            channel: channel.to_string(),
            key_fp: wan_key_fingerprint(agent_public_key),
            instance_pubkey: BASE64.encode(instance_public_key),
            agent_pubkey,
            host_hint: host_hint.to_string(),
            issued_at,
            cert_sig: ed25519_sign_b64(&seed, &material)?,
        })
    }

    /// The chain every holder of a record checks — the cloud on `PUT`
    /// (hygiene) and the receiver before trusting it (the real anchor):
    /// the instance id is the hash of the instance key, the fingerprint is
    /// the hash of the agent key, and the instance key signed the
    /// certificate. Returns the decoded agent public key on success.
    pub fn check_chain(&self) -> Option<[u8; 32]> {
        let instance_public_key = decode_public_key_b64(&self.instance_pubkey)?;
        let agent_public_key = decode_public_key_b64(&self.agent_pubkey)?;
        if wan_instance_id(&instance_public_key) != self.instance_id
            || wan_key_fingerprint(&agent_public_key) != self.key_fp
            || self.agent_id != self.agent_id.to_ascii_lowercase()
        {
            return None;
        }
        let material = wan_cert_material(
            &self.instance_id,
            &self.agent_id,
            &self.channel,
            &self.agent_pubkey,
            &self.host_hint,
            self.issued_at,
        );
        ed25519_verify_b64(&instance_public_key, &material, &self.cert_sig).then_some(agent_public_key)
    }
}

/// An instance revocation (§2.2), signed by the **old** instance key so only
/// the owner of that key can retire it. Sticky: nothing un-revokes an id.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct WanRevocation {
    pub old_instance_id: String,
    pub old_instance_pubkey: String,
    pub new_instance_id: String,
    pub revoked_at: i64,
    pub sig: String,
}

impl WanRevocation {
    /// Sign a revocation of the instance whose private key is `old_private_key`.
    pub fn sign(old_private_key: &[u8], new_instance_id: &str, revoked_at: i64) -> Option<Self> {
        let seed: [u8; 32] = old_private_key.try_into().ok()?;
        let old_public_key = ed25519_dalek::SigningKey::from_bytes(&seed).verifying_key().to_bytes();
        let old_instance_id = wan_instance_id(&old_public_key);
        let material = wan_revoke_material(&old_instance_id, new_instance_id, revoked_at);
        Some(Self {
            old_instance_id,
            old_instance_pubkey: BASE64.encode(old_public_key),
            new_instance_id: new_instance_id.to_string(),
            revoked_at,
            sig: ed25519_sign_b64(&seed, &material)?,
        })
    }

    /// The old id is the hash of the old key, and the old key signed it.
    pub fn verify(&self) -> bool {
        let Some(old_public_key) = decode_public_key_b64(&self.old_instance_pubkey) else { return false };
        wan_instance_id(&old_public_key) == self.old_instance_id
            && ed25519_verify_b64(
                &old_public_key,
                &wan_revoke_material(&self.old_instance_id, &self.new_instance_id, self.revoked_at),
                &self.sig,
            )
    }
}

/// The signed tuple as carried through the relay (§2.1). All of it is
/// sender-supplied; `key_fp` is a lookup hint and is not signed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WanCarried<'a> {
    pub sig: &'a str,
    pub msg_id: &'a str,
    pub ts_secs: i64,
    pub source_agent: &'a str,
    pub target_agent: &'a str,
    pub source_host: &'a str,
    pub source_channel: &'a str,
    pub key_fp: &'a str,
}

/// Why a carried signature did not verify. Each maps to the §2.3 verdict the
/// caller records; the ones that are `None` there are "couldn't check",
/// never a forgery signal.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WanCheckFailure {
    /// The carried source or target isn't the one actually delivered →
    /// `Some(false)`.
    EnvelopeMismatch,
    /// Outside the freshness window → `None`, audit `wan_sig_stale`.
    Stale,
    /// The directory record's chain is broken → `Some(false)`, audit
    /// `wan_cert_invalid`. Only a tampering cloud or a bug produces this.
    CertInvalid,
    /// The record is for a different instance, channel, agent or key than
    /// the carried one → `Some(false)`.
    RecordMismatch,
    /// The message signature doesn't verify under the certified key →
    /// `Some(false)`.
    BadSignature,
}

impl WanCheckFailure {
    /// The `wan_verified` value this failure records: `None` for "couldn't
    /// check", `Some(false)` for an active verification failure.
    pub fn verdict(self) -> Option<bool> {
        match self {
            Self::Stale => None,
            Self::EnvelopeMismatch | Self::CertInvalid | Self::RecordMismatch | Self::BadSignature => Some(false),
        }
    }
}

/// The checks that need no directory record, in the §2.3 order: the
/// envelope binding, then freshness. `row_source_agent` is the cloud row's
/// `source_agent`; `polled_agent_id` is the agent the subscriber is
/// delivering to — **not** a row field, so a cloud can't move a message
/// signed for one agent into another's queue.
pub fn check_wan_envelope(
    carried: &WanCarried<'_>,
    row_source_agent: &str,
    polled_agent_id: &str,
    now_secs: i64,
) -> Result<(), WanCheckFailure> {
    if !wan_id_eq(carried.source_agent, row_source_agent) || !wan_id_eq(carried.target_agent, polled_agent_id) {
        return Err(WanCheckFailure::EnvelopeMismatch);
    }
    if !wan_sig_is_fresh(carried.ts_secs, now_secs) {
        return Err(WanCheckFailure::Stale);
    }
    Ok(())
}

/// The checks against a directory record, in the §2.3 order: the chain, the
/// record matching what was carried, then the message signature. Run after
/// [`check_wan_envelope`] passes and a record was found. Replay is the
/// caller's (it needs state).
pub fn verify_wan_against_record(
    carried: &WanCarried<'_>,
    record: &WanKeyRecord,
    message: &str,
) -> Result<(), WanCheckFailure> {
    let agent_public_key = record.check_chain().ok_or(WanCheckFailure::CertInvalid)?;
    // ASCII case-insensitive for instance, channel and agent, as §2.3
    // specifies (Codex P2 on #3727). Safe: the signature still covers the
    // carried values exactly, the certificate the record's, and a channel that
    // differs only in case is a different data dir, hence a different
    // instance id.
    if !wan_id_eq(&record.instance_id, carried.source_host)
        || !wan_id_eq(&record.channel, carried.source_channel)
        || !wan_id_eq(&record.agent_id, carried.source_agent)
        || record.key_fp != carried.key_fp
    {
        return Err(WanCheckFailure::RecordMismatch);
    }
    if !verify_wan_jekt(
        &agent_public_key,
        carried.msg_id,
        carried.source_agent,
        carried.source_host,
        carried.source_channel,
        carried.target_agent,
        carried.ts_secs,
        message,
        carried.sig,
    ) {
        return Err(WanCheckFailure::BadSignature);
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn key() -> Vec<u8> {
        vec![7u8; 32]
    }

    #[test]
    fn a_correctly_signed_message_verifies() {
        let k = key();
        let sig = sign_jekt(&k, "msg-1", "agentx", "agenty", 1_000, "hello");
        assert!(verify_jekt(&k, "msg-1", "agentx", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn wrong_key_fails_verification() {
        let sig = sign_jekt(&key(), "msg-1", "agentx", "agenty", 1_000, "hello");
        let other_key = vec![9u8; 32];
        assert!(!verify_jekt(&other_key, "msg-1", "agentx", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn tampered_message_fails_verification() {
        let k = key();
        let sig = sign_jekt(&k, "msg-1", "agentx", "agenty", 1_000, "hello");
        assert!(!verify_jekt(&k, "msg-1", "agentx", "agenty", 1_000, "goodbye", &sig));
    }

    #[test]
    fn signature_cannot_be_replayed_against_a_different_target() {
        // The whole point of binding target_agent into the signed material:
        // a signature legitimately produced for agenty must not verify when
        // replayed claiming a different target.
        let k = key();
        let sig = sign_jekt(&k, "msg-1", "agentx", "agenty", 1_000, "hello");
        assert!(!verify_jekt(&k, "msg-1", "agentx", "agentz", 1_000, "hello", &sig));
    }

    #[test]
    fn signature_cannot_be_reattributed_to_a_different_claimed_sender() {
        let k = key();
        let sig = sign_jekt(&k, "msg-1", "agentx", "agenty", 1_000, "hello");
        assert!(!verify_jekt(&k, "msg-1", "agentz", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn different_msgid_fails_verification() {
        let k = key();
        let sig = sign_jekt(&k, "msg-1", "agentx", "agenty", 1_000, "hello");
        assert!(!verify_jekt(&k, "msg-2", "agentx", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn different_timestamp_fails_verification() {
        let k = key();
        let sig = sign_jekt(&k, "msg-1", "agentx", "agenty", 1_000, "hello");
        assert!(!verify_jekt(&k, "msg-1", "agentx", "agenty", 1_001, "hello", &sig));
    }

    #[test]
    fn malformed_base64_signature_fails_verification_not_panics() {
        assert!(!verify_jekt(&key(), "msg-1", "agentx", "agenty", 1_000, "hello", "not-valid-base64!!"));
    }

    #[test]
    fn empty_signature_fails_verification() {
        assert!(!verify_jekt(&key(), "msg-1", "agentx", "agenty", 1_000, "hello", ""));
    }

    // ---- verify_reagent_jekt (Ed25519) ----
    //
    // Fixture signature produced offline against the "reagent-v1-dev" pinned
    // public key's matching private key, over signed_material("msg-1",
    // "github-consumer", "agentx", 1000, "hello") — i.e. the exact material
    // `signed_material()` above constructs for those arguments. Exercises the
    // real pinned key path end to end rather than a separate test-only key.
    const FIXTURE_SIG_B64: &str =
        "QehidZjJa2jYLPIPYSsVxUlm86W5Fdbr9PV3P4HJyZwJ68/HZR9EaAL0MpcVtTuZJW2+MMGebc0RH9HITNJGCw==";

    #[test]
    fn a_correctly_signed_reagent_message_verifies() {
        assert!(verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    // Same fixture material, signed under the real production key
    // (`reagent-v1`, provisioned 2026-08-14 — see this key's own doc comment
    // on `reagent_public_key` for how the private half was generated and
    // provisioned without ever appearing in a transcript). Proves the
    // production key is genuinely wired up and verifiable end to end, not
    // just registered as an unused map entry.
    const PROD_FIXTURE_SIG_B64: &str =
        "FCFjcvAzla329a39u8fFxOvRWaH1R2fUn8RsGtP9RaIbLbaS3aXgAQ7YB4ssWV5TDvAeGrwSkHfoeGi11iCPBg==";

    #[test]
    fn a_correctly_signed_reagent_message_verifies_under_the_production_key() {
        assert!(verify_reagent_jekt(
            "reagent-v1",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            PROD_FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn the_dev_and_prod_reagent_keys_are_not_interchangeable() {
        // The prod fixture must NOT verify against the dev key id, and
        // vice versa -- proves these are genuinely two distinct keys, not
        // the same key registered twice under different names.
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            PROD_FIXTURE_SIG_B64,
        ));
        assert!(!verify_reagent_jekt(
            "reagent-v1",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    // ---- is_reagent_trusted_signing_key ----
    //
    // The dev key verifies signatures fine (it's a real registered key) but
    // must never be treated as authorization to relax TIER=sensitive — its
    // private half is documented as exposed since generation. Only the
    // production key is "trusted" in that stronger sense.

    #[test]
    fn the_production_key_is_trusted_for_tier_relaxation() {
        assert!(is_reagent_trusted_signing_key("reagent-v1"));
    }

    #[test]
    fn the_exposed_dev_key_is_not_trusted_for_tier_relaxation_even_though_it_verifies() {
        assert!(!is_reagent_trusted_signing_key("reagent-v1-dev"));
        // Sanity check: it's not untrusted because it's unregistered — it
        // genuinely verifies signatures, it's just not the trusted one.
        assert!(verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn an_unregistered_key_id_is_not_trusted_for_tier_relaxation() {
        assert!(!is_reagent_trusted_signing_key("reagent-v2-does-not-exist"));
    }

    // ---- verify_trusted_reagent_jekt ----

    #[test]
    fn a_production_key_signature_is_a_trusted_verification() {
        assert!(verify_trusted_reagent_jekt(
            "reagent-v1",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            PROD_FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn a_valid_dev_key_signature_is_not_a_trusted_verification() {
        assert!(!verify_trusted_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn a_tampered_production_key_message_is_not_a_trusted_verification() {
        assert!(!verify_trusted_reagent_jekt(
            "reagent-v1",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello, tampered",
            PROD_FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn reagent_unknown_key_id_fails_verification() {
        assert!(!verify_reagent_jekt(
            "reagent-v2-does-not-exist",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn reagent_tampered_message_fails_verification() {
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "goodbye",
            FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn reagent_wrong_target_fails_verification() {
        // Same reattribution/replay resistance as host-tier HMAC — the
        // signature is bound to target_agent, so it can't be replayed
        // claiming delivery to a different agent.
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agenty",
            1_000,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn reagent_wrong_source_fails_verification() {
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "someone-else",
            "agentx",
            1_000,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn reagent_wrong_timestamp_fails_verification() {
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_001,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn reagent_wrong_msgid_fails_verification() {
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-2",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            FIXTURE_SIG_B64,
        ));
    }

    #[test]
    fn reagent_malformed_base64_signature_fails_verification_not_panics() {
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            "not-valid-base64!!",
        ));
    }

    #[test]
    fn reagent_wrong_length_signature_fails_verification_not_panics() {
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            "dG9vc2hvcnQ=", // "tooshort" base64 — decodes fine, wrong length
        ));
    }

    #[test]
    fn reagent_empty_signature_fails_verification() {
        assert!(!verify_reagent_jekt(
            "reagent-v1-dev",
            "msg-1",
            "github-consumer",
            "agentx",
            1_000,
            "hello",
            "",
        ));
    }

    // ---- LAN-tier Ed25519 signing ----

    fn lan_seed(byte: u8) -> [u8; 32] {
        [byte; 32]
    }

    #[test]
    fn lan_keypair_is_deterministic_from_seed_and_public_differs_from_private() {
        let (pub1, priv1) = generate_lan_keypair(lan_seed(3));
        let (pub2, priv2) = generate_lan_keypair(lan_seed(3));
        assert_eq!(pub1, pub2, "same seed must derive the same keypair");
        assert_eq!(priv1, priv2);
        assert_ne!(pub1, priv1, "public and private halves must differ");
    }

    #[test]
    fn different_seeds_give_different_keypairs() {
        let (pub_a, _) = generate_lan_keypair(lan_seed(1));
        let (pub_b, _) = generate_lan_keypair(lan_seed(2));
        assert_ne!(pub_a, pub_b);
    }

    #[test]
    fn a_correctly_signed_lan_message_verifies() {
        let (public_key, private_key) = generate_lan_keypair(lan_seed(5));
        let sig = sign_lan_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello").unwrap();
        assert!(verify_lan_jekt(&public_key, "msg-1", "agentx", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn lan_wrong_key_fails_verification() {
        let (_, private_key) = generate_lan_keypair(lan_seed(5));
        let sig = sign_lan_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello").unwrap();
        let (other_public, _) = generate_lan_keypair(lan_seed(9));
        assert!(!verify_lan_jekt(&other_public, "msg-1", "agentx", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn lan_tampered_message_fails_verification() {
        let (public_key, private_key) = generate_lan_keypair(lan_seed(5));
        let sig = sign_lan_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello").unwrap();
        assert!(!verify_lan_jekt(&public_key, "msg-1", "agentx", "agenty", 1_000, "goodbye", &sig));
    }

    #[test]
    fn lan_tampered_claimed_sender_fails_verification() {
        // Same signature, different claimed source_agent — binding sender
        // into the signed material means a captured signature can't be
        // reattributed to a different identity.
        let (public_key, private_key) = generate_lan_keypair(lan_seed(5));
        let sig = sign_lan_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello").unwrap();
        assert!(!verify_lan_jekt(&public_key, "msg-1", "someoneelse", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn lan_signing_with_wrong_length_key_returns_none_not_panics() {
        assert!(sign_lan_jekt(&[1u8; 16], "msg-1", "agentx", "agenty", 1_000, "hello").is_none());
        assert!(sign_lan_jekt(&[], "msg-1", "agentx", "agenty", 1_000, "hello").is_none());
    }

    #[test]
    fn lan_verify_with_wrong_length_public_key_fails_not_panics() {
        let (_, private_key) = generate_lan_keypair(lan_seed(5));
        let sig = sign_lan_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello").unwrap();
        assert!(!verify_lan_jekt(&[1u8; 16], "msg-1", "agentx", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn lan_verify_with_malformed_base64_signature_fails_not_panics() {
        let (public_key, _) = generate_lan_keypair(lan_seed(5));
        assert!(!verify_lan_jekt(
            &public_key,
            "msg-1",
            "agentx",
            "agenty",
            1_000,
            "hello",
            "not-valid-base64!!",
        ));
    }

    #[test]
    fn lan_verify_with_wrong_length_signature_fails_not_panics() {
        let (public_key, _) = generate_lan_keypair(lan_seed(5));
        assert!(!verify_lan_jekt(
            &public_key,
            "msg-1",
            "agentx",
            "agenty",
            1_000,
            "hello",
            "dG9vc2hvcnQ=", // "tooshort" base64 — decodes fine, wrong length
        ));
    }

    #[test]
    fn lan_verify_with_empty_signature_fails_not_panics() {
        let (public_key, _) = generate_lan_keypair(lan_seed(5));
        assert!(!verify_lan_jekt(&public_key, "msg-1", "agentx", "agenty", 1_000, "hello", ""));
    }

    #[test]
    fn a_lan_signature_does_not_verify_against_reagent_or_host_schemes() {
        // Cross-scheme confusion check: a LAN Ed25519 signature must not be
        // mistakable for anything the HMAC verifier would accept (different
        // algorithm entirely, so this is really just documenting the type
        // boundary — verify_jekt takes a raw HMAC key, not an Ed25519 one).
        let (_, private_key) = generate_lan_keypair(lan_seed(5));
        let sig = sign_lan_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello").unwrap();
        assert!(!verify_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello", &sig));
    }

    // ---- Cross-channel Ed25519 signing (SPEC_JEKT_CROSS_CHANNEL_TRUST_2026_09_02.md §D5) ----

    #[test]
    fn a_correctly_signed_channel_message_verifies() {
        let (public_key, private_key) = generate_lan_keypair(lan_seed(9));
        let sig =
            sign_channel_jekt(&private_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello")
                .unwrap();
        assert!(verify_channel_jekt(
            &public_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello", &sig
        ));
    }

    #[test]
    fn channel_wrong_key_fails_verification() {
        let (_, private_key) = generate_lan_keypair(lan_seed(9));
        let (other_public, _) = generate_lan_keypair(lan_seed(10));
        let sig =
            sign_channel_jekt(&private_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello")
                .unwrap();
        assert!(!verify_channel_jekt(
            &other_public, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello", &sig
        ));
    }

    #[test]
    fn channel_tampered_fields_fail_verification() {
        let (public_key, private_key) = generate_lan_keypair(lan_seed(9));
        let sig =
            sign_channel_jekt(&private_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello")
                .unwrap();
        // Every signed field must actually be covered.
        for (msgid, src, chan, tgt, ts, msg) in [
            ("msg-2", "agentx", "chan-a", "agenty", 1_000, "hello"),
            ("msg-1", "agentz", "chan-a", "agenty", 1_000, "hello"),
            ("msg-1", "agentx", "chan-a", "agentz", 1_000, "hello"),
            ("msg-1", "agentx", "chan-a", "agenty", 1_001, "hello"),
            ("msg-1", "agentx", "chan-a", "agenty", 1_000, "goodbye"),
        ] {
            assert!(
                !verify_channel_jekt(&public_key, msgid, src, chan, tgt, ts, msg, &sig),
                "tampering with a signed field must fail: {msgid}/{src}/{chan}/{tgt}/{ts}/{msg}"
            );
        }
    }

    #[test]
    fn a_signature_minted_for_one_channel_does_not_verify_as_another() {
        // §D5 channel binding. One agent name can be live in several channels
        // at once; without `source_channel` in the signed material, a signature
        // legitimately produced in chan-a could be replayed as that same agent
        // speaking from chan-b, and the receiver would have no way to tell.
        let (public_key, private_key) = generate_lan_keypair(lan_seed(9));
        let sig =
            sign_channel_jekt(&private_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello")
                .unwrap();
        assert!(!verify_channel_jekt(
            &public_key, "msg-1", "agentx", "chan-b", "agenty", 1_000, "hello", &sig
        ));
    }

    #[test]
    fn lan_and_channel_signatures_are_not_interchangeable_in_either_direction() {
        // §D5 domain separation — the test the separator exists for. Same key,
        // same (msgid, source, target, ts, message) tuple: without
        // CHANNEL_DOMAIN these two signatures would be byte-identical and each
        // would verify as the other, collapsing two different trust claims
        // (TRUST=lan-verified vs TRUST=channel-verified) into one.
        let (public_key, private_key) = generate_lan_keypair(lan_seed(9));
        let lan_sig = sign_lan_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello").unwrap();
        let channel_sig =
            sign_channel_jekt(&private_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello")
                .unwrap();

        assert_ne!(lan_sig, channel_sig, "the two schemes must not produce identical bytes");

        // A LAN signature replayed as a cross-channel one.
        assert!(!verify_channel_jekt(
            &public_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello", &lan_sig
        ));
        // A cross-channel signature replayed as a LAN one.
        assert!(!verify_lan_jekt(
            &public_key, "msg-1", "agentx", "agenty", 1_000, "hello", &channel_sig
        ));
    }

    #[test]
    fn channel_malformed_inputs_fail_rather_than_panic() {
        let (public_key, private_key) = generate_lan_keypair(lan_seed(9));
        let sig =
            sign_channel_jekt(&private_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello")
                .unwrap();
        // Wrong-length private key → None, never a panic.
        assert!(sign_channel_jekt(&[1u8; 16], "m", "a", "c", "b", 1, "x").is_none());
        // Malformed public key / base64 / signature length → false, never a panic.
        assert!(!verify_channel_jekt(&[0u8; 16], "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello", &sig));
        assert!(!verify_channel_jekt(&public_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello", "!!not base64!!"));
        assert!(!verify_channel_jekt(&public_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello", ""));
    }

    #[test]
    fn an_empty_source_channel_is_still_bound_not_ignored() {
        // A pre-upgrade or unknown channel id must not act as a wildcard that
        // matches any channel — it is just another distinct value.
        let (public_key, private_key) = generate_lan_keypair(lan_seed(9));
        let sig = sign_channel_jekt(&private_key, "msg-1", "agentx", "", "agenty", 1_000, "hello").unwrap();
        assert!(verify_channel_jekt(&public_key, "msg-1", "agentx", "", "agenty", 1_000, "hello", &sig));
        assert!(!verify_channel_jekt(&public_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello", &sig));
    }

    // ── WAN tier ──

    #[test]
    fn a_correctly_signed_wan_message_verifies() {
        let (public_key, private_key) = generate_wan_keypair(lan_seed(11));
        let sig = sign_wan_jekt(&private_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello").unwrap();
        assert!(verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn a_wan_signature_does_not_verify_under_another_agents_key() {
        let (_, private_key) = generate_wan_keypair(lan_seed(11));
        let (other_public, _) = generate_wan_keypair(lan_seed(12));
        let sig = sign_wan_jekt(&private_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello").unwrap();
        assert!(!verify_wan_jekt(&other_public, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello", &sig));
    }

    #[test]
    fn tampering_with_any_wan_field_breaks_verification() {
        let (public_key, private_key) = generate_wan_keypair(lan_seed(11));
        let sig = sign_wan_jekt(&private_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello").unwrap();
        assert!(!verify_wan_jekt(&public_key, "msg-2", "agentx", "narko", "stable", "agenty", 1_000, "hello", &sig));
        assert!(!verify_wan_jekt(&public_key, "msg-1", "someoneelse", "narko", "stable", "agenty", 1_000, "hello", &sig));
        assert!(!verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agentz", 1_000, "hello", &sig));
        assert!(!verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_001, "hello", &sig));
        assert!(!verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "goodbye", &sig));
    }

    #[test]
    fn wan_malformed_inputs_fail_rather_than_panic() {
        let (public_key, private_key) = generate_wan_keypair(lan_seed(11));
        let sig = sign_wan_jekt(&private_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello").unwrap();
        assert!(sign_wan_jekt(&[1u8; 16], "m", "a", "h", "c", "b", 1, "x").is_none());
        assert!(!verify_wan_jekt(&[0u8; 16], "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello", &sig));
        assert!(!verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello", "!!not base64!!"));
        assert!(!verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello", ""));
    }

    #[test]
    fn a_wan_signature_is_bound_to_the_sending_instance() {
        // One account can run
        // the same agent name on several instances — another machine, or
        // another build channel on the same machine — and each mints its own
        // keypair. The instance selects which key a signature is checked
        // against, so it must be part of what the signature covers: otherwise
        // a mislabelled instance would silently select a different key instead
        // of failing.
        let (public_key, private_key) = generate_wan_keypair(lan_seed(14));
        let sig =
            sign_wan_jekt(&private_key, "msg-1", "lark", "narko", "stable", "agenty", 1_000, "hello")
                .unwrap();

        assert!(verify_wan_jekt(
            &public_key, "msg-1", "lark", "narko", "stable", "agenty", 1_000, "hello", &sig
        ));
        // Same agent, same account, different machine → not the same claim.
        assert!(!verify_wan_jekt(
            &public_key, "msg-1", "lark", "area54", "stable", "agenty", 1_000, "hello", &sig
        ));
        // Same agent, same machine, different build channel → also distinct,
        // because that is a different data dir, database, and keypair.
        assert!(!verify_wan_jekt(
            &public_key, "msg-1", "lark", "narko", "local-dev", "agenty", 1_000, "hello", &sig
        ));
    }

    #[test]
    fn a_wan_signature_is_not_interchangeable_with_lan_or_channel() {
        // The whole point of WAN_DOMAIN. Even with the SAME key bytes and the
        // SAME (msgid, source, target, ts, message) tuple, a signature minted
        // for one tier must not verify as another — otherwise a signature
        // captured off the LAN could be replayed to claim `TRUST=wan-verified`,
        // which is a materially stronger claim verified against a different
        // key source.
        let seed = lan_seed(13);
        let (public_key, private_key) = generate_wan_keypair(seed);

        let wan_sig = sign_wan_jekt(&private_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello").unwrap();
        let lan_sig = sign_lan_jekt(&private_key, "msg-1", "agentx", "agenty", 1_000, "hello").unwrap();
        let channel_sig =
            sign_channel_jekt(&private_key, "msg-1", "agentx", "chan-a", "agenty", 1_000, "hello")
                .unwrap();

        // Each verifies only under its own tier's verifier.
        assert!(verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello", &wan_sig));
        assert!(!verify_lan_jekt(&public_key, "msg-1", "agentx", "agenty", 1_000, "hello", &wan_sig));
        assert!(!verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello", &lan_sig));
        assert!(!verify_wan_jekt(&public_key, "msg-1", "agentx", "narko", "stable", "agenty", 1_000, "hello", &channel_sig
        ));
        assert_ne!(wan_sig, lan_sig);
    }

    // ── W3-S ──
    //
    // The vectors below were computed by an independent implementation
    // (Node's `crypto`: raw Ed25519 from a PKCS#8-wrapped seed, SHA-256,
    // hand-rolled base32) and pasted in. The cloud's TypeScript chain check
    // asserts the same values, so a byte
    // drift on either side fails a test instead of every verification.
    // Instance seed [1; 32], agent seed [2; 32], successor instance [3; 32].

    const V_INSTANCE_PUBKEY: &str = "iojj3XQJ8ZX9UtstPLpdcspnCb8dlBIb83SIAbQPb1w=";
    const V_INSTANCE_ID: &str = "gr2q7gf5lh6pzfdnurnkvputhm";
    const V_AGENT_PUBKEY: &str = "gTl3Dqh9F19Wo1Rmw0x+zMuNipG07jeiXfYPW4/Js5Q=";
    const V_KEY_FP: &str = "ajgD1fBZkCocba-8m6RykhL3yqwIY0zDrnaydSnwOCc";
    const V_CERT_SIG: &str =
        "ighbn1y/kyisIolSHwNyRtBqC2u95zQEBtGc3wxwksBUBHrDoUvXmz8yEXY20TFzOBC6IDEsG51WzTNJCrgNAA==";
    const V_NEW_INSTANCE_ID: &str = "wyxim75c6m5p4ywv22ywilqwee";
    const V_REVOKE_SIG: &str =
        "DOQzFIVNGItL3mkN7IPlEk5lBrmM96Dgub7jbL5JmTR5oDnCwWlfKzuYsyvZcUJJMRs56glIBhrDVHIeclqEDg==";
    const V_MSG_SIG: &str =
        "49VODE2M7pORgWgcQPl2p+M8W2ccaXJ1O8Zu1XeR4qRiJDsshawzq8eMpSkKTz+CJE0CXz2oTlXsNDobpgsRBw==";
    const V_ISSUED_AT: i64 = 1_790_000_000;
    const V_MSG_TS: i64 = 1_790_000_100;

    fn vector_record() -> WanKeyRecord {
        let (agent_public_key, _) = generate_wan_keypair([2; 32]);
        WanKeyRecord::certify(&[1; 32], "camper", "stable", &agent_public_key, "narko", V_ISSUED_AT).unwrap()
    }

    fn vector_carried() -> WanCarried<'static> {
        WanCarried {
            sig: V_MSG_SIG,
            msg_id: "msg-1",
            ts_secs: V_MSG_TS,
            source_agent: "camper",
            target_agent: "agent2",
            source_host: V_INSTANCE_ID,
            source_channel: "stable",
            key_fp: V_KEY_FP,
        }
    }

    #[test]
    fn w3s_identifiers_and_certificate_match_the_cross_language_vectors() {
        let record = vector_record();
        assert_eq!(record.instance_pubkey, V_INSTANCE_PUBKEY);
        assert_eq!(record.instance_id, V_INSTANCE_ID);
        assert_eq!(record.instance_id.len(), WAN_INSTANCE_ID_LEN);
        assert_eq!(record.agent_pubkey, V_AGENT_PUBKEY);
        assert_eq!(record.key_fp, V_KEY_FP);
        assert_eq!(record.key_fp.len(), WAN_KEY_FP_LEN);
        assert_eq!(record.cert_sig, V_CERT_SIG);
        assert!(record.check_chain().is_some());

        let (new_instance_public_key, _) = generate_wan_keypair([3; 32]);
        assert_eq!(wan_instance_id(&new_instance_public_key), V_NEW_INSTANCE_ID);
        let revocation = WanRevocation::sign(&[1; 32], V_NEW_INSTANCE_ID, 1_790_000_500).unwrap();
        assert_eq!(revocation.sig, V_REVOKE_SIG);
        assert!(revocation.verify());

        let (_, agent_private_key) = generate_wan_keypair([2; 32]);
        let msg_sig = sign_wan_jekt(&agent_private_key, "msg-1", "camper", V_INSTANCE_ID, "stable", "agent2", V_MSG_TS, "hello");
        assert_eq!(msg_sig.as_deref(), Some(V_MSG_SIG));
    }

    #[test]
    fn base32_matches_rfc4648_lowercased() {
        // RFC 4648 §10 test vectors, lowercased and unpadded.
        for (input, expected) in
            [("", ""), ("f", "my"), ("fo", "mzxq"), ("foo", "mzxw6"), ("foob", "mzxw6yq"), ("fooba", "mzxw6ytb"), ("foobar", "mzxw6ytboi")]
        {
            assert_eq!(base32_lower_nopad(input.as_bytes()), expected, "input {input:?}");
        }
    }

    #[test]
    fn a_certificate_chain_breaks_on_any_substituted_field() {
        let good = vector_record();
        let (other_public_key, _) = generate_wan_keypair([9; 32]);
        let other_b64 = BASE64.encode(other_public_key);
        type Mutation<'a> = (&'a str, Box<dyn Fn(&mut WanKeyRecord) + 'a>);
        let mutations: Vec<Mutation> = vec![
            // A cloud swapping in its own agent key, with a matching fingerprint.
            ("agent key", Box::new(|r| {
                r.agent_pubkey = other_b64.clone();
                r.key_fp = wan_key_fingerprint(&other_public_key);
            })),
            // A cloud swapping the instance key: the id no longer matches.
            ("instance key", Box::new(|r| r.instance_pubkey = other_b64.clone())),
            // ...or relabelling the id to match its own key: the cert no longer verifies.
            ("instance id + key", Box::new(|r| {
                r.instance_pubkey = other_b64.clone();
                r.instance_id = wan_instance_id(&other_public_key);
            })),
            ("fingerprint", Box::new(|r| r.key_fp = wan_key_fingerprint(&other_public_key))),
            ("agent id", Box::new(|r| r.agent_id = "lark".into())),
            ("uppercased agent id", Box::new(|r| r.agent_id = "Camper".into())),
            ("channel", Box::new(|r| r.channel = "beta".into())),
            ("host hint", Box::new(|r| r.host_hint = "area54".into())),
            ("issued_at", Box::new(|r| r.issued_at += 1)),
            ("cert sig", Box::new(|r| r.cert_sig = V_REVOKE_SIG.into())),
            ("garbage key", Box::new(|r| r.agent_pubkey = "not base64".into())),
        ];
        for (name, mutate) in mutations {
            let mut record = good.clone();
            mutate(&mut record);
            assert!(record.check_chain().is_none(), "{name} substitution passed the chain");
        }
    }

    #[test]
    fn certify_lowercases_the_agent_id_and_rejects_a_bad_seed() {
        let (agent_public_key, _) = generate_wan_keypair([2; 32]);
        let record = WanKeyRecord::certify(&[1; 32], "Camper", "stable", &agent_public_key, "narko", V_ISSUED_AT).unwrap();
        assert_eq!(record, vector_record());
        assert!(WanKeyRecord::certify(&[1; 31], "camper", "stable", &agent_public_key, "narko", 0).is_none());
    }

    #[test]
    fn a_revocation_verifies_only_as_signed_by_the_old_key() {
        let good = WanRevocation::sign(&[1; 32], V_NEW_INSTANCE_ID, 1_790_000_500).unwrap();
        let mut retargeted = good.clone();
        retargeted.new_instance_id = V_INSTANCE_ID.into();
        assert!(!retargeted.verify());
        let mut redated = good.clone();
        redated.revoked_at += 1;
        assert!(!redated.verify());
        // Someone else's key revoking this instance: the id doesn't match the key.
        let mut foreign = WanRevocation::sign(&[9; 32], V_NEW_INSTANCE_ID, 1_790_000_500).unwrap();
        foreign.old_instance_id = V_INSTANCE_ID.into();
        assert!(!foreign.verify());
    }

    #[test]
    fn freshness_window_boundaries() {
        let now = 1_790_000_000;
        assert!(wan_sig_is_fresh(now, now));
        assert!(wan_sig_is_fresh(now - WAN_SIG_MAX_AGE_SECS, now));
        assert!(!wan_sig_is_fresh(now - WAN_SIG_MAX_AGE_SECS - 1, now));
        assert!(wan_sig_is_fresh(now + WAN_SIG_MAX_FUTURE_SKEW_SECS, now));
        assert!(!wan_sig_is_fresh(now + WAN_SIG_MAX_FUTURE_SKEW_SECS + 1, now));
        assert_eq!(WAN_SIG_MAX_AGE_SECS, 2100);
        // Extremes saturate instead of overflowing into "fresh".
        assert!(!wan_sig_is_fresh(i64::MIN, now));
        assert!(!wan_sig_is_fresh(i64::MAX, now));
    }

    #[test]
    fn the_envelope_binds_source_to_the_row_and_target_to_the_polled_agent() {
        let carried = vector_carried();
        assert_eq!(check_wan_envelope(&carried, "camper", "agent2", V_MSG_TS), Ok(()));
        // Trimmed and case-folded, as the cloud normalises (or, for github*, doesn't).
        assert_eq!(check_wan_envelope(&carried, " Camper ", "AGENT2", V_MSG_TS), Ok(()));
        // A cloud moving a message signed for agent2 into lark's queue.
        assert_eq!(check_wan_envelope(&carried, "camper", "lark", V_MSG_TS), Err(WanCheckFailure::EnvelopeMismatch));
        assert_eq!(check_wan_envelope(&carried, "clamk", "agent2", V_MSG_TS), Err(WanCheckFailure::EnvelopeMismatch));
        // The binding is checked before freshness: a moved stale message is still a mismatch.
        assert_eq!(
            check_wan_envelope(&carried, "camper", "lark", V_MSG_TS + 10_000),
            Err(WanCheckFailure::EnvelopeMismatch)
        );
        assert_eq!(check_wan_envelope(&carried, "camper", "agent2", V_MSG_TS + 2_101), Err(WanCheckFailure::Stale));
        assert_eq!(WanCheckFailure::Stale.verdict(), None);
        assert_eq!(WanCheckFailure::EnvelopeMismatch.verdict(), Some(false));
    }

    #[test]
    fn a_carried_message_verifies_against_its_certified_record() {
        assert_eq!(verify_wan_against_record(&vector_carried(), &vector_record(), "hello"), Ok(()));
    }

    #[test]
    fn each_carried_field_altered_in_turn_fails() {
        let record = vector_record();
        let cases: Vec<(&str, WanCarried<'static>, WanCheckFailure)> = vec![
            ("msg_id", WanCarried { msg_id: "msg-2", ..vector_carried() }, WanCheckFailure::BadSignature),
            ("ts", WanCarried { ts_secs: V_MSG_TS + 1, ..vector_carried() }, WanCheckFailure::BadSignature),
            ("target", WanCarried { target_agent: "lark", ..vector_carried() }, WanCheckFailure::BadSignature),
            ("sig", WanCarried { sig: V_CERT_SIG, ..vector_carried() }, WanCheckFailure::BadSignature),
            ("source", WanCarried { source_agent: "lark", ..vector_carried() }, WanCheckFailure::RecordMismatch),
            ("host", WanCarried { source_host: V_NEW_INSTANCE_ID, ..vector_carried() }, WanCheckFailure::RecordMismatch),
            ("channel", WanCarried { source_channel: "beta", ..vector_carried() }, WanCheckFailure::RecordMismatch),
            ("key_fp", WanCarried { key_fp: "x", ..vector_carried() }, WanCheckFailure::RecordMismatch),
        ];
        for (name, carried, expected) in cases {
            assert_eq!(verify_wan_against_record(&carried, &record, "hello"), Err(expected), "altered {name}");
        }
        assert_eq!(
            verify_wan_against_record(&vector_carried(), &record, "hello!"),
            Err(WanCheckFailure::BadSignature)
        );
    }

    #[test]
    fn the_record_match_is_ascii_case_insensitive_for_instance_channel_and_agent() {
        // A record certified for channel `Stable` and a message signed under
        // `stable`: both halves are individually valid, so the only question is
        // the §2.3 match, which is case-insensitive.
        let (agent_public_key, agent_private_key) = generate_wan_keypair([2; 32]);
        let record = WanKeyRecord::certify(&[1; 32], "camper", "Stable", &agent_public_key, "narko", V_ISSUED_AT).unwrap();
        let sig = sign_wan_jekt(&agent_private_key, "msg-1", "Camper", V_INSTANCE_ID, "stable", "agent2", V_MSG_TS, "hello").unwrap();
        let carried = WanCarried {
            sig: &sig,
            source_agent: "Camper",
            source_channel: "stable",
            ..vector_carried()
        };
        assert_eq!(verify_wan_against_record(&carried, &record, "hello"), Ok(()));
    }

    #[test]
    fn a_tampered_record_is_cert_invalid_before_anything_else() {
        let mut record = vector_record();
        record.host_hint = "evil".into();
        assert_eq!(
            verify_wan_against_record(&vector_carried(), &record, "hello"),
            Err(WanCheckFailure::CertInvalid)
        );
    }

    #[test]
    fn host_hints_and_display_labels() {
        assert!(is_valid_wan_host_hint("narko"));
        assert!(is_valid_wan_host_hint("host-1.lan"));
        for bad in ["", "Narko", "narko~x", "has space", "ümlaut", &"a".repeat(49)] {
            assert!(!is_valid_wan_host_hint(bad), "{bad:?}");
        }
        assert_eq!(wan_instance_display_label("narko", V_INSTANCE_ID), "narko~gr2q7gf5");
        // A sender-chosen label that tries to smuggle its own suffix renders as `?`.
        assert_eq!(wan_instance_display_label("narko~abcdefgh", V_INSTANCE_ID), "?~gr2q7gf5");
    }
}

/// Cross-version wire compatibility for jekt signatures. The fleet never
/// upgrades all at once, so a signature made by one ed25519-dalek major must
/// verify on another. Ed25519 signing is deterministic (RFC 8032), so the
/// strongest check is byte equality: these goldens were produced by
/// ed25519-dalek 2.2.0 (2026-10-01) and must stay identical across upgrades.
/// If one changes, older peers would reject the new signatures — that is a
/// fleet-breaking change, not a test to update.
#[cfg(test)]
mod cross_version_goldens {
    use super::*;

    const SEED: [u8; 32] = [42u8; 32];
    const TS: i64 = 1_790_000_000;
    const PK: &str = "GX9rI+FshTLGq8g4+s1ep4m+DHaykgM0A5v6iz02jWE=";
    const LAN: &str = "EXTYmZi7R4FlXQU5olRQng9i3JvoyPaNk+5hsgz/pwLVYBoIP5/fKSlN8YCAViv/j18Gr9fCp0W9fS2NYrFrAQ==";
    const CHAN: &str = "lSTM+FmFR/QsqzmTiVvO8KLa5jmFrnQhpuQ7i543/ezCoeOMaAll+N2NEs2wfL727/vwzOYFDt3Exkk6h7yKCw==";
    const WAN: &str = "IeNtT8Ivh6k84poizAS0a1oBzBQsDRteO72vlsviWieBDHu/ET8XZNwjLNlZGFyjMWA4GnbZbOn9S02pvbYjCw==";

    fn hex(s: &str) -> Vec<u8> {
        (0..s.len()).step_by(2).map(|i| u8::from_str_radix(&s[i..i + 2], 16).unwrap()).collect()
    }

    #[test]
    fn rfc8032_test_1_matches() {
        let seed: [u8; 32] = hex("9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60")
            .try_into()
            .unwrap();
        let key = ed25519_dalek::SigningKey::from_bytes(&seed);
        assert_eq!(
            key.verifying_key().to_bytes().to_vec(),
            hex("d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a")
        );
        let sig = ed25519_dalek::Signer::sign(&key, b"");
        assert_eq!(
            sig.to_bytes().to_vec(),
            hex("e5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b")
        );
    }

    #[test]
    fn public_key_matches_golden() {
        assert_eq!(BASE64.encode(generate_lan_keypair(SEED).0), PK);
    }

    #[test]
    fn lan_signature_is_byte_identical_and_verifies() {
        let sig = sign_lan_jekt(&SEED, "msg-golden", "agentx", "manoz", TS, "hello fleet").unwrap();
        assert_eq!(sig, LAN);
        let pk = BASE64.decode(PK).unwrap();
        assert!(verify_lan_jekt(&pk, "msg-golden", "agentx", "manoz", TS, "hello fleet", LAN));
        assert!(!verify_lan_jekt(&pk, "msg-golden", "agentx", "manoz", TS, "hello fleet!", LAN));
    }

    #[test]
    fn channel_signature_is_byte_identical_and_verifies() {
        let sig = sign_channel_jekt(&SEED, "msg-golden", "agentx", "local-main", "manoz", TS, "hello fleet").unwrap();
        assert_eq!(sig, CHAN);
        let pk = BASE64.decode(PK).unwrap();
        assert!(verify_channel_jekt(&pk, "msg-golden", "agentx", "local-main", "manoz", TS, "hello fleet", CHAN));
    }

    #[test]
    fn wan_signature_is_byte_identical_and_verifies() {
        let sig =
            sign_wan_jekt(&SEED, "msg-golden", "agentx", "narko", "stable", "manoz", TS, "hello fleet").unwrap();
        assert_eq!(sig, WAN);
        let pk = BASE64.decode(PK).unwrap();
        assert!(verify_wan_jekt(&pk, "msg-golden", "agentx", "narko", "stable", "manoz", TS, "hello fleet", WAN));
    }
}