vta-service 0.31.0

//! Trust-Task client for webvh server operations.
//!
//! ## The name said DIDComm; the transport is no longer this module's business
//!
//! This was the DIDComm sibling of `webvh_client.rs`, and it argued at length
//! that it needed none of the REST client's signing identity, audience binding
//! or typed-error machinery because DIDComm authcrypt supplied each one at the
//! envelope layer. That argument was sound and is now the wrong shape: since
//! the outbound refactor every document here goes to `operations::outbound`,
//! which reads the peer's advertisement and picks TSP > DIDComm > REST. The
//! guarantees quoted below hold for the DIDComm binding specifically; the other
//! bindings carry their own.
//!
//! What is still this module's: **the did-management documents** it composes
//! and the replies it reads. What is not: choosing a transport, applying its
//! binding, or awaiting an answer — the same three steps for every peer, done
//! once in the seam.
//!
//! **Do not "add parity" with `webvh_client.rs` by porting the JWS-flow
//! primitives in here.** They would duplicate what the transport layer already
//! provides, and the duplicate would drift out of sync with it. The original
//! reasoning, still accurate for the DIDComm leg:
//!
//! - **Signing identity** — the `DIDCommBridge` packs every outbound
//!   message with the VTA's existing DIDComm sender key; the daemon
//!   verifies it via `unpack_signed` exactly the same way it verifies
//!   the JWS-over-REST envelope.
//! - **Audience binding** — DIDComm messages are addressed to a
//!   specific `to:` DID intrinsically; replay against a different
//!   daemon fails because the message is encrypted to *this* daemon's
//!   key-agreement key.
//! - **Typed errors** — DIDComm replies carry `e.p.msg.*`
//!   problem-report codes which the SDK maps to typed `VtaError`
//!   variants via `VtaError::from_problem_report`. The CLI surfaces
//!   them with the same hint discipline as the REST path.
//! - **Transport security** — DIDComm over the mediator is
//!   end-to-end encrypted regardless of the underlying socket; there
//!   is no plaintext-leak surface to defend at this layer.

use crate::didcomm_bridge::DIDCommBridge;
use crate::error::{AppError, bad_gateway_error};
use crate::webvh_client::RequestUriResponse;
// The one DIDComm message type this module names, taken from the binding crate
// rather than copied (#900). Every task URI below travels *inside* the envelope.

// did-management Trust-Task URIs (v0.1, hosted-DID category).
//
// Replaces the legacy `https://affinidi.com/webvh/1.0/did/...` constants
// this client used through v0.6. The remote `did-hosting-control`
// accepts both URI families through its alias map during the v0.7
// deprecation window — see `did-hosting-common::v1_aliases` in
// affinidi-webvh-service — and drops the legacy ones in v0.8.0. We move
// outbound traffic to the v0.1 URIs now so this client isn't the source
// of deprecation-warn log lines on every hosting host the VTA talks to.
//
// Spec drafts live in `dtgwg-trust-tasks-tf` under
// `specs/did-management/...`.
//
// Notable shape changes from the legacy surface:
// - `did/request/1.0` (slot reservation) is absorbed by
//   `did/check-name/0.1` with `reserve: true`. The two-step
//   reservation-then-publish flow still works; one round-trip fewer.
// - Paired confirm/offer types collapse to `<base>#response`.
// - Every slot-touching task accepts an optional `domain` field so
//   the VTA can direct provisioning at the right hosting domain when
//   the same control plane serves multiple tenants.
const TASK_DID_CHECK_NAME: &str = "https://trusttasks.org/spec/did-management/did/check-name/0.1";
const TASK_DID_CHECK_NAME_RESPONSE: &str =
    "https://trusttasks.org/spec/did-management/did/check-name/0.1#response";
// `did/publish/0.1` is NOT sent. did-hosting 0.8.3 retired it — spec
// `supersededBy: did/register` — so the host's DIDComm router has no arm for
// it and its fallback drops the message without replying, which cost every
// server-managed publish a 30s `send_and_wait` timeout surfaced as a 500
// (affinidi-webvh-service#144). `publish_did` below sends `did/register/0.1`
// instead: on the host, an owner re-registering their own slot IS a publish —
// same content replace, version bump, `created_at` preservation and
// agent-name reconcile, in one batch.
const TASK_DID_REGISTER: &str = "https://trusttasks.org/spec/did-management/did/register/0.1";
const TASK_DID_REGISTER_RESPONSE: &str =
    "https://trusttasks.org/spec/did-management/did/register/0.1#response";
const TASK_DID_DELETE: &str = "https://trusttasks.org/spec/did-management/did/delete/0.1";
const TASK_DID_DELETE_RESPONSE: &str =
    "https://trusttasks.org/spec/did-management/did/delete/0.1#response";
const TASK_DID_PROBLEM_REPORT: &str =
    "https://trusttasks.org/spec/did-management/did/problem-report/0.1";

// Agent names. These had no DIDComm form until the hosting server gained
// them, so a DIDComm-transport VTA could not manage names at all — it either
// refused, or reached sideways to the server's REST control plane. Same
// `spec/did-management/...` family as the verbs above; the server answers
// them from the same `did_ops` functions its REST routes use, so the two
// transports return identical payloads.
// One declarative `update` carrying `state: active | parked` replaced the
// `set` / `enable` / `disable` trio in did-hosting 0.8.3, alongside the
// `did/publish` retirement above and for the same reason — those three URIs
// now hit the host's silent fallback. `remove` stays a separate destructive
// task. The VTA's own *inbound* four-verb surface is unchanged; the collapse
// is a property of the host wire only (see `AgentNameVerb::host_endpoint`).
const TASK_AGENT_NAME_UPDATE: &str =
    "https://trusttasks.org/spec/did-management/agent-name/update/0.1";
const TASK_AGENT_NAME_UPDATE_RESPONSE: &str =
    "https://trusttasks.org/spec/did-management/agent-name/update/0.1#response";
const TASK_AGENT_NAME_REMOVE: &str =
    "https://trusttasks.org/spec/did-management/agent-name/remove/0.1";
const TASK_AGENT_NAME_REMOVE_RESPONSE: &str =
    "https://trusttasks.org/spec/did-management/agent-name/remove/0.1#response";
const TASK_AGENT_NAME_LIST: &str = "https://trusttasks.org/spec/did-management/agent-name/list/0.1";
const TASK_AGENT_NAME_LIST_RESPONSE: &str =
    "https://trusttasks.org/spec/did-management/agent-name/list/0.1#response";
const TASK_AGENT_NAME_CHECK: &str =
    "https://trusttasks.org/spec/did-management/agent-name/check/0.1";
const TASK_AGENT_NAME_CHECK_RESPONSE: &str =
    "https://trusttasks.org/spec/did-management/agent-name/check/0.1#response";

/// Build the `did/check-name/0.1` reservation body.
///
/// `path == None` is the auto-assign case: the `path` field is OMITTED
/// entirely so the host runs its server-generated-mnemonic branch. A
/// present-but-empty path is rejected by the host with
/// `e.p.did.path-invalid` ("path must not be empty"), so an absent path
/// must never be coerced to `""` — that coercion was the regression this
/// pins. Mirrors the REST `request_uri`, which omits the field for `None`.
fn build_check_name_body(
    path: Option<&str>,
    domain: Option<&str>,
) -> serde_json::Map<String, serde_json::Value> {
    let mut body = serde_json::Map::new();
    if let Some(p) = path {
        body.insert("path".to_string(), serde_json::Value::String(p.to_string()));
    }
    body.insert("reserve".to_string(), serde_json::Value::Bool(true));
    if let Some(d) = domain {
        body.insert(
            "domain".to_string(),
            serde_json::Value::String(d.to_string()),
        );
    }
    body
}

/// Build the `did/register/0.1` body.
///
/// Serves both callers of the register task: the atomic claim-and-publish and
/// — since did-hosting retired `did/publish/0.1` in favour of it — the plain
/// "publish the log for a slot I own" path, where `path` is the reserved
/// slot's mnemonic and `force` is false.
///
/// Extracted so the body is assertable without a live bridge; the publish
/// regression this pins was a silent 30s timeout, which no unit test built on
/// `send_and_wait` would have caught.
fn build_register_body(
    path: &str,
    did_log: &str,
    force: bool,
    domain: Option<&str>,
) -> serde_json::Map<String, serde_json::Value> {
    let mut body = serde_json::Map::new();
    body.insert(
        "path".to_string(),
        serde_json::Value::String(path.to_string()),
    );
    body.insert(
        "method".to_string(),
        serde_json::Value::String("webvh".to_string()),
    );
    // v0.1 spec names this field `didData`; the legacy
    // did-hosting-control alias map normalises legacy `did_log`
    // → `didData` server-side, so passing the canonical name
    // works on both old and new hosts.
    body.insert(
        "didData".to_string(),
        serde_json::Value::String(did_log.to_string()),
    );
    body.insert("force".to_string(), serde_json::Value::Bool(force));
    if let Some(d) = domain {
        body.insert(
            "domain".to_string(),
            serde_json::Value::String(d.to_string()),
        );
    }
    body
}

/// Project a `did/check-name/0.1#response` payload into the local
/// [`RequestUriResponse`].
///
/// The v0.1 response carries top-level `available` + `reserved`, and —
/// when reserved — a `record: DidRecord` whose `mnemonic` + `didUrl` we
/// project out. Legacy did-hosting-control hosts (pre-v0.7) flatten the
/// fields at the top level and omit `reserved`; we fall back to the flat
/// body and to the snake_case `did_url` alias so both wire dialects work,
/// mirroring `register_did_atomic`'s parser.
fn parse_check_name_response(body: serde_json::Value) -> Result<RequestUriResponse, AppError> {
    let reserved = body
        .get("reserved")
        .and_then(|v| v.as_bool())
        .unwrap_or(false);
    if !reserved {
        let available = body
            .get("available")
            .and_then(|v| v.as_bool())
            .unwrap_or(false);
        // `available == false` ⇒ the path is already taken: a clean,
        // client-facing conflict (409), not a server fault. (Before the
        // path-resolution fix, a deterministic URL-derived name collided
        // here on every re-run and surfaced — wrongly — as a 500.)
        // `available == true` but un-reserved is a genuine remote anomaly —
        // we asked for `reserve=true`, the slot was free, yet nothing was
        // granted — so that stays a 500.
        if !available {
            return Err(AppError::Conflict(
                "webvh path already taken on the hosting server — choose a different \
                 WEBVH_PATH, or omit it for a server-assigned path"
                    .to_string(),
            ));
        }
        return Err(AppError::Internal(format!(
            "remote refused reservation despite the path being available \
             (available={available}); check-name with reserve=true expected to succeed"
        )));
    }
    // Prefer the spec `record`; fall back to the flat legacy body.
    let record = body.get("record").cloned().unwrap_or_else(|| body.clone());
    let mnemonic = record
        .get("mnemonic")
        .and_then(|v| v.as_str())
        .ok_or_else(|| AppError::Internal("check-name response missing `mnemonic`".to_string()))?
        .to_string();
    let did_url = record
        .get("didUrl")
        .or_else(|| record.get("did_url"))
        .and_then(|v| v.as_str())
        .ok_or_else(|| AppError::Internal("check-name response missing `didUrl`".to_string()))?
        .to_string();
    Ok(RequestUriResponse { mnemonic, did_url })
}

/// DIDComm-based client for communicating with a WebVH server.
///
/// Routes messages through the DIDComm service's listener connection,
/// avoiding duplicate WebSocket connections to the mediator.
pub struct WebvhDIDCommClient<'a> {
    bridge: &'a DIDCommBridge,
    resolver: &'a affinidi_did_resolver_cache_sdk::DIDCacheClient,
    /// Owned rather than borrowed so `WebvhTransport` can hold the whole client
    /// in its arm instead of the parts to rebuild one. Nine call sites used to
    /// destructure those parts and re-run `new`; storing the client is what
    /// lets a field be added here — like `tsp` — without touching any of them.
    server_did: String,
    /// What lets the seam choose TSP. `None` on a caller with no `AppState` to
    /// borrow a socket from, where DIDComm is the honest answer.
    #[cfg(feature = "tsp")]
    tsp: Option<crate::operations::outbound::TspSender>,
}

/// The `trust-task-error/0.x` family the framework emits for transport-level
/// refusals (malformed body, proof required, wrong recipient). Matched by prefix
/// because the version floats — did-hosting emits `0.1` for a body-parse failure
/// and `0.2` from the typed §7.2 pipeline, in the same conversation.
const TRUST_TASK_ERROR_PREFIX: &str = "https://trusttasks.org/spec/trust-task-error/";

/// Build the `TrustTask` document that rides inside the envelope.
///
/// Extracted so the outbound shape is assertable without a live bridge — the
/// same reason `build_register_body` exists, and for the same class of bug: the
/// failure this whole change addresses is a *silent* one, so nothing downstream
/// would have caught a malformed document either.
fn build_envelope_document(
    task: &str,
    recipient: &str,
    issuer: Option<String>,
    payload: serde_json::Value,
) -> serde_json::Value {
    let mut doc = serde_json::json!({
        "id": format!("urn:uuid:{}", uuid::Uuid::new_v4()),
        // The task type lives HERE, on the document — never on the DIDComm
        // message, which is always the envelope type.
        "type": task,
        "issuedAt": chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        // Addressed to the host, per SPEC §4.8. did-hosting does not enforce
        // `recipient` on the DID-management bridge (it authorizes the authcrypt
        // sender), but an unaddressed document is one a stricter peer is
        // entitled to refuse.
        "recipient": recipient,
        "issuedAt": chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
        "payload": payload,
    });
    // `issuer` only when we actually know it. SPEC §4.8.1 requires an in-band
    // issuer to match the transport-authenticated sender, so a guess would be
    // worse than the omission the spec permits.
    if let Some(vta_did) = issuer {
        doc["issuer"] = serde_json::Value::String(vta_did);
    }
    doc
}

/// Unwrap a reply document from a trust-task envelope into its `payload`.
///
/// On the envelope binding every reply arrives with the *same* DIDComm `type`,
/// so no transport-level type check can tell success from rejection — which is
/// why `operations::outbound` hands back the reply document rather than
/// interpreting it, and why that decision is made here, on the document's own
/// `type`.
/// Three outcomes, and the caller must not be able to confuse them:
///
/// - the expected `<task>#response` → its `payload`,
/// - `did/problem-report/0.1` → the typed [`AppError`] the REST path produces,
///   via the *same* mapping table `didcomm_bridge` uses for the bare framing,
/// - `trust-task-error/0.x` → a 502; the framework refused the envelope itself
///   rather than the task, so it is not an outcome the caller can act on.
///
/// Anything else is a 502 naming both types, because a reply that threads to our
/// request but answers a different task is a contract break, not a task failure.
fn unwrap_envelope_reply(
    doc: serde_json::Value,
    expected: &str,
) -> Result<serde_json::Value, AppError> {
    let doc_type = doc.get("type").and_then(|v| v.as_str()).unwrap_or_default();

    if doc_type == TASK_DID_PROBLEM_REPORT {
        let payload = doc.get("payload").unwrap_or(&serde_json::Value::Null);
        let code = payload
            .get("code")
            .and_then(|v| v.as_str())
            .unwrap_or("e.p.did.unknown");
        let comment = payload
            .get("comment")
            .and_then(|v| v.as_str())
            .unwrap_or_default();
        return Err(crate::didcomm_bridge::problem_report_to_app_error(
            code, comment,
        ));
    }

    if doc_type.starts_with(TRUST_TASK_ERROR_PREFIX) {
        let payload = doc.get("payload").unwrap_or(&serde_json::Value::Null);
        let code = payload
            .get("code")
            .and_then(|v| v.as_str())
            .unwrap_or("unknown");
        let message = payload
            .get("message")
            .and_then(|v| v.as_str())
            .unwrap_or_default();
        return Err(bad_gateway_error(format!(
            "hosting peer refused the trust-task envelope: {message} [{code}]"
        )));
    }

    if doc_type != expected {
        return Err(bad_gateway_error(format!(
            "unexpected response document type: expected {expected}, got {doc_type}"
        )));
    }

    Ok(doc
        .get("payload")
        .cloned()
        .unwrap_or(serde_json::Value::Null))
}

impl<'a> WebvhDIDCommClient<'a> {
    pub fn new(
        bridge: &'a DIDCommBridge,
        resolver: &'a affinidi_did_resolver_cache_sdk::DIDCacheClient,
        server_did: impl Into<String>,
        #[cfg(feature = "tsp")] tsp: Option<crate::operations::outbound::TspSender>,
    ) -> Self {
        Self {
            bridge,
            resolver,
            server_did: server_did.into(),
            #[cfg(feature = "tsp")]
            tsp,
        }
    }

    /// Send one DID-management task and return the response document's
    /// `payload`.
    ///
    /// **This client no longer names a transport or a message type at all.** It
    /// builds the document and hands it to `operations::outbound`, which reads
    /// what the server advertises, applies that binding and returns the reply.
    /// Putting a task type on the wire — the mistake #900 and #903 were about —
    /// is now unrepresentable for a different and better reason than before: not
    /// because this function is careful, but because there is no argument here
    /// that could carry one.
    ///
    /// The task type moves *into* the document, where the binding requires it.
    /// did-hosting reads it back out via `bridge_did_management` and dispatches
    /// through the same `dispatch_did_op` table the bare `MSG_*` framing hits, so
    /// the operation, its authorization and its responses are unchanged — only
    /// the framing differs.
    async fn send_task(
        &self,
        task: &str,
        response_task: &str,
        payload: serde_json::Value,
    ) -> Result<serde_json::Value, AppError> {
        let doc = build_envelope_document(task, &self.server_did, self.bridge.vta_did(), payload);

        // Carriage is `operations::outbound`'s, not this client's: choosing the
        // transport, applying its binding and awaiting the reply are the same
        // three steps for every peer, and this module used to be one of three
        // places doing them. What is still this module's is the document above
        // and the reply reading below — those are did-management's, not any
        // transport's.
        //
        // `TransportAuthenticated`, and this is the call being made explicit
        // rather than changed: this client has never verified a reply's proof.
        // The two sealing bindings both authenticate the peer end to end — the
        // authcrypt envelope over DIDComm, the sender VID over TSP — and these
        // replies confer nothing anyway: a reserved path, an availability
        // answer, an acknowledgement. Raising it to `SignedByRecipient` is a
        // real question, and one to ask of did-hosting (whether it signs these
        // replies at all) rather than to assume here.
        //
        // Worth re-reading if the seam ever selects the Trust-Task HTTPS
        // binding for this caller: TLS authenticates a *host*, not the DID that
        // composed the reply, so `TransportAuthenticated` would then be a
        // weaker claim than it is today. `transport.rs` deliberately keeps
        // `TrustTaskHTTPS` out of the seam's reach here, which is what makes
        // the sentence above true rather than merely usually true.
        let reply = crate::operations::outbound::Outbound::from_parts(
            self.resolver,
            self.bridge,
            #[cfg(feature = "tsp")]
            self.tsp.clone(),
        )
        .send(
            &self.server_did,
            doc,
            crate::operations::outbound::ReplyTrust::TransportAuthenticated,
        )
        .await?;

        unwrap_envelope_reply(reply, response_task)
    }

    /// Reserve a path on the remote DID-hosting server (v0.1
    /// `did-management/did/check-name/0.1` with `reserve: true`).
    ///
    /// Replaces the legacy `did/request/1.0` round-trip. The
    /// `check-name` task absorbs both modes: a pure availability
    /// probe (omit `reserve`), and the atomic check-and-reserve
    /// (`reserve: true`). This client uses the reserve mode so the
    /// behaviour matches the prior `request_uri` semantics.
    ///
    /// `domain` is the optional hosting domain to target. When the
    /// remote serves multiple tenant domains (the common case for a
    /// VTA-managed `did-hosting-control` backplane), the operator
    /// supplies the target; otherwise the remote falls back to the
    /// caller's ACL default → system default. An unknown domain is
    /// rejected with `did-management:unknownDomain`.
    pub async fn request_uri(
        &self,
        path: Option<&str>,
        domain: Option<&str>,
    ) -> Result<RequestUriResponse, AppError> {
        let body = build_check_name_body(path, domain);

        let payload = self
            .send_task(
                TASK_DID_CHECK_NAME,
                TASK_DID_CHECK_NAME_RESPONSE,
                serde_json::Value::Object(body),
            )
            .await?;

        parse_check_name_response(payload)
    }

    /// Atomic claim-and-publish (v0.1 `did-management/did/register/0.1`).
    ///
    /// Replaces the legacy `did/register/1.0` URI. Wire shape stays
    /// the same — `path`, `didData`, `force` — plus the optional
    /// `domain` and `method` discriminator the v0.1 surface introduces.
    pub async fn register_did_atomic(
        &self,
        path: &str,
        did_log: &str,
        force: bool,
        domain: Option<&str>,
    ) -> Result<RequestUriResponse, AppError> {
        let payload = self
            .send_task(
                TASK_DID_REGISTER,
                TASK_DID_REGISTER_RESPONSE,
                serde_json::Value::Object(build_register_body(path, did_log, force, domain)),
            )
            .await?;

        // v0.1 response carries `{ record: DidRecord }`; we project
        // the mnemonic + didUrl out of it for the local response shape.
        let record = payload
            .get("record")
            .cloned()
            .or_else(|| {
                // Legacy did-hosting-control responses (still emitted
                // by pre-v0.7 hosts) flatten the fields at the top
                // level. Fall back to that shape transparently.
                Some(payload.clone())
            })
            .unwrap_or(serde_json::Value::Null);
        let mnemonic = record
            .get("mnemonic")
            .and_then(|v| v.as_str())
            .ok_or_else(|| AppError::Internal("register response missing `mnemonic`".to_string()))?
            .to_string();
        let did_url = record
            .get("didUrl")
            .or_else(|| record.get("did_url"))
            .and_then(|v| v.as_str())
            .ok_or_else(|| AppError::Internal("register response missing `didUrl`".to_string()))?
            .to_string();
        Ok(RequestUriResponse { mnemonic, did_url })
    }

    /// Publish a DID log to the remote as an owner re-register (v0.1
    /// `did-management/did/register/0.1`).
    ///
    /// Carries the slot's `mnemonic` as the register `path` — the host keys
    /// the slot on that path either way, and re-registering a slot you already
    /// own is idempotent: content is replaced in-batch (never a half-updated
    /// slot from a resolver's view), `version_count` bumps, `created_at` is
    /// preserved, and the agent-name registry is reconciled against the new
    /// document. That is the retired publish verb's behaviour exactly, which is
    /// why the spec supersedes one with the other.
    ///
    /// `force` is always false: this call means "publish the log for a slot I
    /// own", and forcing is how you'd take a slot from *another* owner. A
    /// genuine ownership conflict must surface as a conflict, not be papered
    /// over by a publish.
    ///
    /// The `domain` argument is accepted for disambiguation when the remote
    /// runs per-domain mnemonic namespaces; consumers that haven't enabled
    /// per-domain namespacing treat it as a no-op on the lookup.
    pub async fn publish_did(
        &self,
        mnemonic: &str,
        log_content: &str,
        domain: Option<&str>,
    ) -> Result<(), AppError> {
        self.register_did_atomic(mnemonic, log_content, false, domain)
            .await
            .map(|_| ())
    }

    /// Soft-delete a DID on the remote (v0.1
    /// `did-management/did/delete/0.1`).
    pub async fn delete_did(&self, mnemonic: &str, domain: Option<&str>) -> Result<(), AppError> {
        let mut body = serde_json::Map::new();
        body.insert(
            "mnemonic".to_string(),
            serde_json::Value::String(mnemonic.to_string()),
        );
        if let Some(d) = domain {
            body.insert(
                "domain".to_string(),
                serde_json::Value::String(d.to_string()),
            );
        }

        self.send_task(
            TASK_DID_DELETE,
            TASK_DID_DELETE_RESPONSE,
            serde_json::Value::Object(body),
        )
        .await?;
        Ok(())
    }

    // ── Agent names ────────────────────────────────────────────────────
    //
    // Both mutating tasks share a body and a `{record}` response, so they
    // share one submit. `didLog` carries the newly signed document: the server
    // requires `state: active` to claim the name in `alsoKnownAs` and
    // `remove`/`state: parked` not to, which is what makes the registry and
    // the document agree.
    //
    // `didLog` — not the spec's `didData` — is deliberate: it is the canonical
    // field name on `remove` and an accepted alias on `update`, so one
    // spelling satisfies both tasks.

    async fn agent_name_verb(
        &self,
        task: &str,
        response_task: &str,
        mnemonic: &str,
        name: &str,
        state: Option<&str>,
        did_log: &str,
        domain: Option<&str>,
    ) -> Result<(), AppError> {
        let mut body = serde_json::Map::new();
        body.insert("mnemonic".to_string(), serde_json::json!(mnemonic));
        body.insert("name".to_string(), serde_json::json!(name));
        body.insert("didLog".to_string(), serde_json::json!(did_log));
        if let Some(s) = state {
            body.insert("state".to_string(), serde_json::json!(s));
        }
        if let Some(d) = domain {
            body.insert("domain".to_string(), serde_json::json!(d));
        }
        self.send_task(task, response_task, serde_json::Value::Object(body))
            .await?;
        Ok(())
    }

    /// Set `name`'s binding state on `mnemonic` — `active` to bind, refresh,
    /// or resume it; `parked` to stop it resolving while keeping it reserved
    /// to this DID.
    ///
    /// One call for what used to be `set`, `enable`, and `disable`: the host
    /// takes the desired end state and the document that must agree with it,
    /// so "bind" and "resume" are the same request and idempotent by
    /// construction.
    pub async fn update_agent_name(
        &self,
        mnemonic: &str,
        name: &str,
        state: &str,
        did_log: &str,
        domain: Option<&str>,
    ) -> Result<(), AppError> {
        self.agent_name_verb(
            TASK_AGENT_NAME_UPDATE,
            TASK_AGENT_NAME_UPDATE_RESPONSE,
            mnemonic,
            name,
            Some(state),
            did_log,
            domain,
        )
        .await
    }

    /// Release `name` — it stops resolving and anyone may reclaim it.
    pub async fn remove_agent_name(
        &self,
        mnemonic: &str,
        name: &str,
        did_log: &str,
        domain: Option<&str>,
    ) -> Result<(), AppError> {
        self.agent_name_verb(
            TASK_AGENT_NAME_REMOVE,
            TASK_AGENT_NAME_REMOVE_RESPONSE,
            mnemonic,
            name,
            None,
            did_log,
            domain,
        )
        .await
    }

    /// Read the DID's agent-name registry, parked names included.
    ///
    /// The registry — not the DID document — is the only place a parked name
    /// is visible, since dropping the `alsoKnownAs` claim is *how* parking
    /// stops it resolving. `agentNames` is always present, so an absent field
    /// is a contract violation rather than an empty registry.
    pub async fn list_agent_names(
        &self,
        mnemonic: &str,
        domain: Option<&str>,
    ) -> Result<Vec<crate::webvh_client::AgentNameEntryWire>, AppError> {
        let mut body = serde_json::Map::new();
        body.insert("mnemonic".to_string(), serde_json::json!(mnemonic));
        if let Some(d) = domain {
            body.insert("domain".to_string(), serde_json::json!(d));
        }
        let payload = self
            .send_task(
                TASK_AGENT_NAME_LIST,
                TASK_AGENT_NAME_LIST_RESPONSE,
                serde_json::Value::Object(body),
            )
            .await?;
        // A host predating the registry omits the field entirely. That is an
        // empty list, not a parse error — otherwise every read against an
        // older host fails. The REST path has always been tolerant here
        // (`webvh_client::list_agent_names`); erroring on one transport and
        // succeeding on the other made the same DID appear to have names or
        // not depending on how the VTA happened to reach its host.
        let Some(names) = payload.get("agentNames") else {
            return Ok(Vec::new());
        };
        serde_json::from_value(names.clone())
            .map_err(|e| AppError::Internal(format!("agent-name list response parse error: {e}")))
    }

    /// Is `name` free to claim on this domain?
    ///
    /// A reserved name answers `available: false, reserved: true` rather than
    /// erroring, so the caller can tell "taken" from "never allowed".
    pub async fn check_agent_name(
        &self,
        name: &str,
        domain: Option<&str>,
    ) -> Result<crate::webvh_client::AgentNameAvailabilityWire, AppError> {
        let mut body = serde_json::Map::new();
        body.insert("name".to_string(), serde_json::json!(name));
        if let Some(d) = domain {
            body.insert("domain".to_string(), serde_json::json!(d));
        }
        let payload = self
            .send_task(
                TASK_AGENT_NAME_CHECK,
                TASK_AGENT_NAME_CHECK_RESPONSE,
                serde_json::Value::Object(body),
            )
            .await?;
        serde_json::from_value(payload)
            .map_err(|e| AppError::Internal(format!("agent-name check response parse error: {e}")))
    }
}

#[cfg(test)]
mod tests {
    use super::{
        TASK_AGENT_NAME_LIST, TASK_AGENT_NAME_REMOVE, TASK_AGENT_NAME_UPDATE, TASK_DID_CHECK_NAME,
        TASK_DID_DELETE, TASK_DID_REGISTER, build_check_name_body, build_register_body,
        parse_check_name_response,
    };

    /// None of the tasks this client sends may be one did-hosting retired in
    /// 0.8.3 (`did/publish`, `agent-name/{set,enable,disable}`). Those URIs
    /// have no route on the host, and its DIDComm fallback drops an unrouted
    /// type **without replying** — so the failure mode is a 30s `send_and_wait`
    /// timeout surfaced as a 500, not an error naming the task. That is what
    /// broke every server-managed publish, and what made it hard to see.
    ///
    /// Asserted over the constants rather than per-call-site: adding a retired
    /// URI back is the regression, and it can only enter through one of these.
    #[test]
    fn no_task_constant_names_a_retired_verb() {
        const RETIRED: &[&str] = &[
            "did/publish/",
            "agent-name/set/",
            "agent-name/enable/",
            "agent-name/disable/",
        ];
        for task in [
            TASK_DID_CHECK_NAME,
            TASK_DID_REGISTER,
            TASK_DID_DELETE,
            TASK_AGENT_NAME_UPDATE,
            TASK_AGENT_NAME_REMOVE,
            TASK_AGENT_NAME_LIST,
        ] {
            for retired in RETIRED {
                assert!(
                    !task.contains(retired),
                    "{task} names `{retired}`, retired by did-hosting 0.8.3 — \
                     the host will drop it silently and the caller will hang 30s"
                );
            }
        }
    }

    /// A publish is a register of the slot we already own: the mnemonic
    /// travels as `path`, the log as `didData`, and `force` is false.
    ///
    /// `force: false` is the load-bearing part. Forcing is how a *different*
    /// owner takes a slot, so a forced publish would convert a genuine
    /// ownership conflict into a silent takeover — the opposite of what a
    /// publish means.
    #[test]
    fn publish_registers_the_owned_slot_without_forcing() {
        let body = build_register_body("brave-otter", "<jsonl>", false, None);
        assert_eq!(body.get("path"), Some(&serde_json::json!("brave-otter")));
        assert_eq!(body.get("didData"), Some(&serde_json::json!("<jsonl>")));
        assert_eq!(body.get("force"), Some(&serde_json::json!(false)));
        assert_eq!(body.get("method"), Some(&serde_json::json!("webvh")));
        assert!(!body.contains_key("domain"));
        // The retired verb's field name must not leak into the register body:
        // the host keys the slot on `path`, and a `mnemonic` key would be
        // silently ignored, publishing nothing while appearing to succeed.
        assert!(!body.contains_key("mnemonic"));
    }

    /// `domain` rides along on register exactly as it does on check-name.
    #[test]
    fn register_body_includes_domain_when_present() {
        let body = build_register_body("brave-otter", "<jsonl>", true, Some("acme.example.com"));
        assert_eq!(
            body.get("domain"),
            Some(&serde_json::json!("acme.example.com"))
        );
        assert_eq!(body.get("force"), Some(&serde_json::json!(true)));
    }

    /// Regression for `e.p.did.path-invalid`: auto-assign (`path == None`)
    /// must OMIT the `path` field, not send `""`. The host rejects a
    /// present-but-empty path; only an absent one triggers
    /// server-side mnemonic generation.
    #[test]
    fn auto_assign_omits_path() {
        let body = build_check_name_body(None, None);
        assert!(
            !body.contains_key("path"),
            "auto-assign must omit `path`; got {body:?}"
        );
        assert_eq!(body.get("reserve"), Some(&serde_json::json!(true)));
    }

    /// An explicit label travels verbatim under `reserve: true`.
    #[test]
    fn explicit_path_is_sent() {
        let body = build_check_name_body(Some("alice"), None);
        assert_eq!(body.get("path"), Some(&serde_json::json!("alice")));
        assert_eq!(body.get("reserve"), Some(&serde_json::json!(true)));
    }

    /// `.well-known` (the root-DID marker) is sent as a normal path —
    /// the host's `create_did` treats it as the reserved root slot.
    #[test]
    fn well_known_is_sent_as_path() {
        let body = build_check_name_body(Some(".well-known"), None);
        assert_eq!(body.get("path"), Some(&serde_json::json!(".well-known")));
    }

    /// The optional `domain` rides along only when present.
    #[test]
    fn domain_included_only_when_present() {
        let with = build_check_name_body(Some("alice"), Some("acme.example.com"));
        assert_eq!(
            with.get("domain"),
            Some(&serde_json::json!("acme.example.com"))
        );
        let without = build_check_name_body(Some("alice"), None);
        assert!(!without.contains_key("domain"));
    }

    /// The v0.1 (and current host) response nests the assigned mnemonic +
    /// didUrl inside `record`. This is the shape that the auto-assign fix
    /// makes the host emit; the parser must read through `record`.
    #[test]
    fn parses_spec_record_shaped_response() {
        let body = serde_json::json!({
            "available": true,
            "reserved": true,
            "record": {
                "mnemonic": "brave-otter",
                "owner": "did:key:z6MkAlice",
                "createdAt": "2026-06-04T10:00:01Z",
                "updatedAt": "2026-06-04T10:00:01Z",
                "versionCount": 0,
                "domain": "did.example.com",
                "didUrl": "https://did.example.com/brave-otter/did.jsonl",
                "disabled": false
            }
        });
        let resp = parse_check_name_response(body).expect("spec record parses");
        assert_eq!(resp.mnemonic, "brave-otter");
        assert_eq!(
            resp.did_url,
            "https://did.example.com/brave-otter/did.jsonl"
        );
    }

    /// Legacy did-hosting-control hosts (pre-v0.7) flatten the fields at
    /// the top level and use the snake_case `did_url` alias. The parser
    /// must still accept them so a VTA can talk to an un-upgraded host.
    #[test]
    fn parses_legacy_flat_response() {
        let body = serde_json::json!({
            "available": true,
            "reserved": true,
            "mnemonic": "alice",
            "did_url": "https://did.example.com/alice/did.jsonl"
        });
        let resp = parse_check_name_response(body).expect("legacy flat parses");
        assert_eq!(resp.mnemonic, "alice");
        assert_eq!(resp.did_url, "https://did.example.com/alice/did.jsonl");
    }

    /// `reserved: false` + `available: false` means the path is already
    /// taken — a clean client-facing conflict (409), not a server fault.
    /// (This is the case that, with a deterministic URL-derived name, used
    /// to surface — wrongly — as a 500 on every re-run.)
    #[test]
    fn not_reserved_and_unavailable_is_a_conflict() {
        let body = serde_json::json!({ "available": false, "reserved": false });
        let err = parse_check_name_response(body).expect_err("must error");
        assert!(
            matches!(err, crate::error::AppError::Conflict(_)),
            "taken path must be a 409 conflict, got: {err:?}"
        );
        assert!(
            err.to_string().contains("taken"),
            "conflict should explain the path is taken: {err}"
        );
    }

    /// `reserved: false` but `available: true` is a genuine remote anomaly
    /// — we asked for `reserve=true`, the slot was free, yet nothing was
    /// granted. That stays a 500 so it isn't mistaken for a normal
    /// already-taken conflict.
    #[test]
    fn not_reserved_but_available_is_an_internal_anomaly() {
        let body = serde_json::json!({ "available": true, "reserved": false });
        let err = parse_check_name_response(body).expect_err("must error");
        assert!(
            matches!(err, crate::error::AppError::Internal(_)),
            "free-but-ungranted slot must be a 500 anomaly, got: {err:?}"
        );
        assert!(
            err.to_string().contains("available=true"),
            "anomaly should surface availability: {err}"
        );
    }

    /// A reserved response that omits the locator is malformed — fail
    /// loudly rather than returning an empty `did_url` downstream.
    #[test]
    fn reserved_without_did_url_errors() {
        let body = serde_json::json!({
            "reserved": true,
            "record": { "mnemonic": "alice" }
        });
        let err = parse_check_name_response(body).expect_err("must error");
        assert!(err.to_string().contains("didUrl"), "got: {err}");
    }
}

#[cfg(test)]
mod envelope_binding_tests {
    use super::{
        TASK_DID_CHECK_NAME, TASK_DID_CHECK_NAME_RESPONSE, TASK_DID_PROBLEM_REPORT,
        build_envelope_document, unwrap_envelope_reply,
    };
    use crate::error::AppError;
    use serde_json::json;

    const SERVER: &str = "did:webvh:example.com:control";
    const VTA: &str = "did:webvh:example.com:vta";

    /// The task type goes **in the document**. Where the envelope type goes is
    /// no longer this module's business: `operations::outbound` names the
    /// DIDComm message type once for every caller, and asserts it there. What
    /// stays here is the half this module still decides.
    #[test]
    fn the_task_type_is_in_the_document() {
        let doc = build_envelope_document(
            TASK_DID_CHECK_NAME,
            SERVER,
            Some(VTA.to_string()),
            json!({ "path": "bob", "reserve": true }),
        );

        assert_eq!(doc["type"], TASK_DID_CHECK_NAME);
        assert_eq!(doc["recipient"], SERVER);
        assert_eq!(doc["issuer"], VTA);
        // The body the host dispatches on must survive the wrap untouched — the
        // envelope adds framing, it does not reshape the request.
        assert_eq!(doc["payload"]["path"], "bob");
        assert_eq!(doc["payload"]["reserve"], true);
        assert!(
            doc["id"]
                .as_str()
                .unwrap_or_default()
                .starts_with("urn:uuid:"),
            "the document id is the thread anchor and must be a urn:uuid"
        );
    }

    /// No `issuer` rather than a wrong one. SPEC §4.8.1 makes an in-band issuer
    /// that disagrees with the transport sender a rejection, so omitting it when
    /// the bridge has no DID yet is the safe half of the choice.
    #[test]
    fn an_unknown_issuer_is_omitted_not_guessed() {
        let doc = build_envelope_document(TASK_DID_CHECK_NAME, SERVER, None, json!({}));
        assert!(
            doc.get("issuer").is_none(),
            "an unknown issuer must be absent, not empty or invented: {doc}"
        );
    }

    /// The happy path yields the response document's `payload`, which is what
    /// every verb's parser consumes.
    #[test]
    fn a_response_document_yields_its_payload() {
        let reply = json!({
            "id": "urn:uuid:2",
            "type": TASK_DID_CHECK_NAME_RESPONSE,
            "issuedAt": chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            "payload": { "available": true, "reserved": true, "record": { "mnemonic": "bob" } },
        });
        let payload = unwrap_envelope_reply(reply, TASK_DID_CHECK_NAME_RESPONSE)
            .expect("a matching response document unwraps");
        assert_eq!(payload["available"], true);
        assert_eq!(payload["record"]["mnemonic"], "bob");
    }

    /// A problem report inside the envelope maps through the *same* table the
    /// bare framing uses, so the operator-facing status does not depend on which
    /// framing carried the rejection.
    ///
    /// `path-unavailable` → 409 is the case that matters: it is a clean client
    /// conflict, and collapsing it to 502 was the bug the mapping table was
    /// introduced to fix.
    #[test]
    fn an_enveloped_problem_report_keeps_its_typed_meaning() {
        let reply = json!({
            "id": "urn:uuid:3",
            "type": TASK_DID_PROBLEM_REPORT,
            "issuedAt": chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            "payload": { "code": "e.p.did.path-unavailable", "comment": "taken" },
        });
        let err = unwrap_envelope_reply(reply, TASK_DID_CHECK_NAME_RESPONSE)
            .expect_err("a problem report is an error, not a payload");
        assert!(
            matches!(err, AppError::Conflict(_)),
            "path-unavailable must stay a 409, got: {err:?}"
        );
    }

    /// A framework-level refusal is not a task outcome, so it surfaces as a 502
    /// rather than being mistaken for a rejection the caller could act on. The
    /// version floats (0.1 from a body-parse failure, 0.2 from the typed
    /// pipeline), so the match is by prefix.
    #[test]
    fn a_trust_task_error_is_a_bad_gateway_at_either_version() {
        for version in ["0.1", "0.2"] {
            let reply = json!({
                "id": "urn:uuid:4",
                "type": format!("https://trusttasks.org/spec/trust-task-error/{version}"),
                "issuedAt": chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
                "payload": { "code": "malformedRequest", "message": "nope" },
            });
            let err = unwrap_envelope_reply(reply, TASK_DID_CHECK_NAME_RESPONSE)
                .expect_err("a framework error is not a payload");
            let msg = format!("{err:?}");
            assert!(
                msg.contains("refused the trust-task envelope"),
                "trust-task-error/{version} must surface as an envelope refusal, got: {msg}"
            );
        }
    }

    /// A reply that threads to our request but answers a different task is a
    /// contract break, not a task failure — it must never be handed to a parser
    /// as though it were the expected payload.
    #[test]
    fn a_mismatched_response_type_is_refused() {
        let reply = json!({
            "id": "urn:uuid:5",
            "type": "https://trusttasks.org/spec/did-management/did/delete/0.1#response",
            "issuedAt": chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            "payload": { "deleted": true },
        });
        let err = unwrap_envelope_reply(reply, TASK_DID_CHECK_NAME_RESPONSE)
            .expect_err("an off-task response must not be accepted");
        let msg = format!("{err:?}");
        assert!(
            msg.contains("unexpected response document type"),
            "got: {msg}"
        );
    }
}