vtc_client/

lib.rs

//! Client SDK for a Verifiable Trust Community (VTC).
//!
//! The VTA SDK ([`vta_sdk`]) is the client for *VTAs*; this crate is the
//! equivalent for *VTCs*. It lets an operator or an integration drive a VTC's
//! member-facing and admin-facing surface over REST: authenticate, list members
//! (the community roster), run the join ceremony, remove members, and manage
//! community policy.
//!
//! It is deliberately thin: authentication reuses
//! [`vta_sdk::auth_light::challenge_response_light`] (the challenge-response
//! flow is audience-agnostic — pass the VTC's URL and DID and the server binds
//! `aud` to itself), and the join wire types are re-exported from
//! [`vta_sdk::protocols::join_requests`]. Only the VTC-specific REST shapes
//! (member records, pagination) are defined here.
//!
//! ## Mount path
//!
//! A VTC mounts its API under a configurable base (default `/v1`). Pass the
//! **full** API base to [`VtcClient::connect`] / [`VtcClient::with_token`] —
//! e.g. `https://vtc.example.com/v1` — so both `/auth/*` and `/members` resolve.
//!
//! ## The `Trust-Task` header is mandatory
//!
//! The VTC gates **every** route on a per-route `Trust-Task` URL header
//! (`vtc-service/src/routes/mod.rs`, the `tt(...)` wrapper) and answers `400`
//! without it — only `/health` and the browser wallet's `/wallet/auth/*`
//! aliases are exempt. This client sent it on nothing, so every method failed
//! at the transport layer regardless of its body. [`task`] holds the URL for
//! each route and `VtcClient::tt` attaches it; a new method must go through
//! that helper, not a bare `self.http.get(...)`.
//!
//! ## Scope
//!
//! Authentication, the member roster, the admin join queue, removal, policy,
//! and the applicant side of the join ceremony
//! ([`VtcClient::submit_join`], which signs its own document and needs no
//! token).

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

/// The `Trust-Task` URL each route this client calls is gated on, as declared
/// in `vtc-service/src/routes/mod.rs`.
///
/// Kept as one block so the mapping is auditable against the server's router in
/// a single read, rather than scattered as string literals down the file. A URL
/// that drifts from the server's is a 400 at runtime, so this list is part of
/// the client's contract, not decoration.
pub mod task {
    pub const MEMBERS_LIST: &str = "https://trusttasks.org/spec/vtc/members/list/0.1";
    pub const MEMBERS_UPDATE: &str = "https://trusttasks.org/spec/vtc/members/update/0.1";
    pub const MEMBERS_ADMIN_REMOVE: &str =
        "https://trusttasks.org/spec/vtc/members/admin-remove/0.1";
    pub const JOIN_REQUESTS_LIST: &str = "https://trusttasks.org/spec/vtc/join-requests/list/0.1";
    pub const JOIN_REQUESTS_DECIDE: &str =
        "https://trusttasks.org/spec/vtc/join-requests/decide/0.1";
    pub const POLICY_LIST: &str = "https://trusttasks.org/spec/policy/list/0.2";
    pub const POLICY_GET: &str = "https://trusttasks.org/spec/policy/get/0.1";
    pub const POLICY_UPSERT: &str = "https://trusttasks.org/spec/policy/upsert/0.2";
    pub const POLICY_ACTIVATE: &str = "https://trusttasks.org/spec/policy/activate/0.1";
}

/// Re-export of the published join-request protocol wire types, so a consumer
/// driving the join ceremony depends on one crate.
pub use vta_sdk::protocols::join_requests;

/// Errors surfaced by the VTC client.
#[derive(Debug, thiserror::Error)]
pub enum VtcError {
    /// A request needed a bearer token but the client has none — call
    /// [`VtcClient::connect`] (or construct via [`VtcClient::with_token`]).
    #[error("not authenticated — call VtcClient::connect first")]
    NotAuthenticated,
    /// The VTC returned a non-success HTTP status.
    #[error("VTC returned HTTP {status}: {body}")]
    Http { status: u16, body: String },
    /// A request URL could not be built.
    #[error("invalid request url: {0}")]
    Url(String),
    /// A transport-level error talking to the VTC.
    #[error("transport error: {0}")]
    Transport(#[from] reqwest::Error),
    /// Challenge-response authentication failed.
    #[error("authentication failed: {0}")]
    Auth(#[from] vta_sdk::error::VtaError),
    /// The operation's route no longer exists on the VTC and this client has no
    /// replacement for it. Carries what to use instead.
    #[error("unsupported by this client: {0}")]
    Unsupported(&'static str),
    /// Building or signing a holder Trust Task failed — e.g. a non-`did:key`
    /// applicant, or an undecodable private key.
    #[error("could not sign the request document: {0}")]
    Signing(String),
}

/// A single member of the community, as returned by `GET /members`. Mirrors the
/// VTC's `MemberResponse` (the fields a fleet/operator typically needs);
/// unrecognised fields in the response are ignored.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct MemberRecord {
    /// The member's DID (for a fleet, the managed VTA's DID).
    pub did: String,
    /// The member's role on the wire (`"admin"`, `"moderator"`, `"member"`,
    /// `"custom:…"`, …).
    pub role: String,
    #[serde(default)]
    pub label: Option<String>,
    pub joined_at: DateTime<Utc>,
    /// Index of the member's revocation slot in the community status list, when
    /// allocated.
    #[serde(default)]
    pub status_list_index: Option<u32>,
    /// Id of the member's current membership credential (VMC), if issued.
    #[serde(default)]
    pub current_vmc_id: Option<String>,
    #[serde(default)]
    pub personhood: bool,
    #[serde(default)]
    pub joined_via_invitation: bool,
    /// Community-defined extensions (opaque JSON). A fleet manager can stash
    /// per-member operational state here — e.g. a `fleet_index` — at enrollment.
    #[serde(default)]
    pub extensions: serde_json::Value,
}

/// One page of a cursor-paginated VTC listing. Mirrors the server's
/// `Paginated<T>` (`items` + `next_cursor`); `total_estimate` is ignored.
#[derive(Debug, Clone, Deserialize)]
struct Page<T> {
    items: Vec<T>,
    next_cursor: Option<String>,
}

/// A join request in the admin work queue (subset of the VTC's `JoinRequest`).
#[derive(Debug, Clone, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct JoinRequestSummary {
    /// The request id (used to approve / reject).
    pub id: String,
    /// The DID applying to join (for a fleet, the VTA being enrolled).
    pub applicant_did: String,
    /// Wire status: `"pending"`, `"approved"`, `"rejected"`, `"withdrawn"`.
    pub status: String,
    pub submitted_at: DateTime<Utc>,
}

/// Outcome of approving or rejecting a join request.
#[derive(Debug, Clone, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct DecideResult {
    pub request_id: String,
    pub status: String,
    /// The issued membership credential (VMC) — present on approve.
    #[serde(default)]
    pub vmc: Option<serde_json::Value>,
    /// The issued role credential (VEC) — present on approve when a role applies.
    #[serde(default)]
    pub role_vec: Option<serde_json::Value>,
}

/// Outcome of removing a member (offboarding). The VTC flips the member's
/// status-list revocation bit as part of removal.
#[derive(Debug, Clone, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct RemoveResult {
    pub did: String,
    /// Wire disposition: `"tombstone"`, `"purge"`, `"historical"`.
    pub disposition: String,
    pub removed: bool,
}

/// A client bound to one VTC's API base, holding a bearer token once
/// authenticated.
#[derive(Debug, Clone)]
pub struct VtcClient {
    http: reqwest::Client,
    /// The VTC API base, including the mount (e.g. `https://vtc.example.com/v1`),
    /// trailing slash trimmed.
    base_url: String,
    /// The VTC's own DID (the authentication audience / DIDComm recipient).
    vtc_did: String,
    /// Bearer access token, set after [`connect`](Self::connect).
    token: Option<String>,
}

impl VtcClient {
    /// Authenticate to the VTC as `client_did` (challenge-response, reusing the
    /// VTA SDK's audience-agnostic flow) and return a ready client.
    ///
    /// `base_url` is the full API base including the mount (e.g.
    /// `https://vtc.example.com/v1`); `vtc_did` is the community's DID.
    pub async fn connect(
        base_url: &str,
        vtc_did: &str,
        client_did: &str,
        private_key_multibase: &str,
    ) -> Result<Self, VtcError> {
        // Finite request + connect timeouts (R1.2) — `reqwest::Client::new()`
        // has neither, so a blackholed VTC would hang an operator forever.
        let http = vta_sdk::http::rest_client();
        let base_url = base_url.trim_end_matches('/').to_string();
        let auth = vta_sdk::auth_light::challenge_response_light(
            &http,
            &base_url,
            client_did,
            private_key_multibase,
            vtc_did,
        )
        .await?;
        Ok(Self {
            http,
            base_url,
            vtc_did: vtc_did.to_string(),
            token: Some(auth.access_token),
        })
    }

    /// Construct a client from an already-obtained bearer token (e.g. a token
    /// minted out of band, or for testing). `base_url` includes the mount.
    pub fn with_token(base_url: &str, vtc_did: &str, token: impl Into<String>) -> Self {
        Self {
            http: vta_sdk::http::rest_client(),
            base_url: base_url.trim_end_matches('/').to_string(),
            vtc_did: vtc_did.to_string(),
            token: Some(token.into()),
        }
    }

    /// Construct a client with **no** bearer token, for the applicant side of
    /// the join ceremony.
    ///
    /// [`submit_join`](Self::submit_join) authenticates with the document's own
    /// holder proof, so an applicant — who is by definition not yet a member and
    /// has no token to get — needs exactly this. Every other method returns
    /// [`VtcError::NotAuthenticated`], which is the honest answer rather than a
    /// 401 from the server.
    ///
    /// `vtc_did` still matters: it is the audience the submitted document is
    /// addressed to, and the VTC rejects a document addressed elsewhere.
    pub fn anonymous(base_url: &str, vtc_did: &str) -> Self {
        Self {
            http: vta_sdk::http::rest_client(),
            base_url: base_url.trim_end_matches('/').to_string(),
            vtc_did: vtc_did.to_string(),
            token: None,
        }
    }

    /// The community's DID this client is bound to.
    pub fn vtc_did(&self) -> &str {
        &self.vtc_did
    }

    /// Start a request carrying the route's `Trust-Task` URL header and the
    /// bearer token.
    ///
    /// Every authenticated call goes through here. The VTC rejects a request
    /// with no `Trust-Task` header (400) before any handler sees it, so a
    /// method that builds its request by hand is broken on arrival — which is
    /// how every method in this client came to be.
    fn tt(
        &self,
        method: reqwest::Method,
        url: impl reqwest::IntoUrl,
        task: &str,
    ) -> Result<reqwest::RequestBuilder, VtcError> {
        let token = self.token()?;
        Ok(self
            .http
            .request(method, url)
            .header("Trust-Task", task)
            .bearer_auth(token))
    }

    /// List every community member, optionally filtered by `role`, following the
    /// cursor to completion. Requires an admin token. This is the fleet roster
    /// when the community's members are managed VTAs.
    pub async fn list_members(&self, role: Option<&str>) -> Result<Vec<MemberRecord>, VtcError> {
        let mut out: Vec<MemberRecord> = Vec::new();
        let mut cursor: Option<String> = None;

        loop {
            let mut params: Vec<(&str, &str)> = Vec::new();
            if let Some(role) = role {
                params.push(("role", role));
            }
            if let Some(cursor) = &cursor {
                params.push(("cursor", cursor.as_str()));
            }
            let url =
                reqwest::Url::parse_with_params(&format!("{}/members", self.base_url), &params)
                    .map_err(|e| VtcError::Url(e.to_string()))?;

            let resp = self
                .tt(reqwest::Method::GET, url, task::MEMBERS_LIST)?
                .send()
                .await?;
            if !resp.status().is_success() {
                let status = resp.status().as_u16();
                let body = resp.text().await.unwrap_or_default();
                return Err(VtcError::Http { status, body });
            }

            let page: Page<MemberRecord> = resp.json().await?;
            out.extend(page.items);
            match page.next_cursor {
                Some(next) => cursor = Some(next),
                None => break,
            }
        }
        Ok(out)
    }

    /// List join requests (the admin work queue), optionally filtered by
    /// `status` (e.g. `"pending"`). Requires an admin token. For a fleet, these
    /// are VTAs awaiting enrollment.
    pub async fn list_join_requests(
        &self,
        status: Option<&str>,
    ) -> Result<Vec<JoinRequestSummary>, VtcError> {
        let mut out: Vec<JoinRequestSummary> = Vec::new();
        let mut cursor: Option<String> = None;
        loop {
            let mut params: Vec<(&str, &str)> = Vec::new();
            if let Some(status) = status {
                params.push(("status", status));
            }
            if let Some(cursor) = &cursor {
                params.push(("cursor", cursor.as_str()));
            }
            let url = reqwest::Url::parse_with_params(
                &format!("{}/join-requests", self.base_url),
                &params,
            )
            .map_err(|e| VtcError::Url(e.to_string()))?;

            let resp = self
                .tt(reqwest::Method::GET, url, task::JOIN_REQUESTS_LIST)?
                .send()
                .await?;
            if !resp.status().is_success() {
                let status = resp.status().as_u16();
                let body = resp.text().await.unwrap_or_default();
                return Err(VtcError::Http { status, body });
            }
            let page: Page<JoinRequestSummary> = resp.json().await?;
            out.extend(page.items);
            match page.next_cursor {
                Some(next) => cursor = Some(next),
                None => break,
            }
        }
        Ok(out)
    }

    /// Approve a join request — admit the applicant and issue its membership
    /// credential (VMC). Requires an admin token. For a fleet, this enrolls a
    /// VTA that has applied to join.
    pub async fn approve_join(&self, request_id: &str) -> Result<DecideResult, VtcError> {
        self.decide(request_id, "approved", None).await
    }

    /// Reject a join request, optionally recording an operator rationale in the
    /// audit trail. Requires an admin token.
    pub async fn reject_join(
        &self,
        request_id: &str,
        reason: Option<&str>,
    ) -> Result<DecideResult, VtcError> {
        self.decide(request_id, "rejected", reason).await
    }

    /// `POST /join-requests/{id}/decide` with `{ decision, reason? }`.
    ///
    /// The VTC previously exposed a `/approve` + `/reject` mount pair; both were
    /// retired in favour of this single endpoint carrying the decision in the
    /// body, and the old mounts are **gone** — this client was still posting to
    /// them, so approve and reject were 404s independent of the missing header.
    /// `decision` is the server's `Decision` enum on the wire (`approved` /
    /// `rejected`), not the imperative verb the old paths used.
    async fn decide(
        &self,
        request_id: &str,
        decision: &str,
        reason: Option<&str>,
    ) -> Result<DecideResult, VtcError> {
        let url = format!("{}/join-requests/{request_id}/decide", self.base_url);
        let mut body = serde_json::json!({ "decision": decision });
        if let Some(reason) = reason {
            body["reason"] = serde_json::json!(reason);
        }
        let resp = self
            .tt(reqwest::Method::POST, url, task::JOIN_REQUESTS_DECIDE)?
            .json(&body)
            .send()
            .await?;
        if !resp.status().is_success() {
            let status = resp.status().as_u16();
            let body = resp.text().await.unwrap_or_default();
            return Err(VtcError::Http { status, body });
        }
        Ok(resp.json().await?)
    }

    /// Remove a member (offboarding). The VTC applies its removal disposition and
    /// flips the member's status-list revocation bit. `reason` is an optional
    /// admin note. Requires an admin token. For a fleet, this decommissions a
    /// managed VTA.
    pub async fn remove_member(
        &self,
        did: &str,
        reason: Option<&str>,
    ) -> Result<RemoveResult, VtcError> {
        let url = format!("{}/members/{did}", self.base_url);
        let mut req = self.tt(reqwest::Method::DELETE, url, task::MEMBERS_ADMIN_REMOVE)?;
        if let Some(reason) = reason {
            req = req.json(&serde_json::json!({ "reason": reason }));
        }
        let resp = req.send().await?;
        if !resp.status().is_success() {
            let status = resp.status().as_u16();
            let body = resp.text().await.unwrap_or_default();
            return Err(VtcError::Http { status, body });
        }
        Ok(resp.json().await?)
    }

    /// Update a member's community-defined `extensions` (opaque JSON) via
    /// `PATCH /members/{did}`. A fleet manager records per-member operational
    /// state here — e.g. the assigned `fleet_index` at enrollment, which the
    /// roster then carries (see [`MemberRecord::extensions`]). Admin token.
    pub async fn update_member_extensions(
        &self,
        did: &str,
        extensions: serde_json::Value,
    ) -> Result<(), VtcError> {
        let resp = self
            .tt(
                reqwest::Method::PATCH,
                format!("{}/members/{did}", self.base_url),
                task::MEMBERS_UPDATE,
            )?
            .json(&serde_json::json!({ "extensions": extensions }))
            .send()
            .await?;
        if !resp.status().is_success() {
            let status = resp.status().as_u16();
            let body = resp.text().await.unwrap_or_default();
            return Err(VtcError::Http { status, body });
        }
        Ok(())
    }

    /// Submit a join request (the applicant side): sign a
    /// `join-requests/submit/0.1` Trust Task with the applicant's holder key and
    /// post it to the document endpoint. Returns the community's verdict —
    /// auto-admit carries the issued VMC + role VEC inline, otherwise the
    /// request is queued for an admin.
    ///
    /// **No bearer token.** The document's `eddsa-jcs-2022` proof *is* the
    /// authentication: the VTC takes the proof's `verificationMethod` DID as the
    /// applicant and requires the document `issuer` to match it
    /// (`vtc-service/src/trust_tasks/mod.rs::resolve_holder`). So this is the
    /// one method that works on a client built with neither
    /// [`connect`](Self::connect) nor [`with_token`](Self::with_token) — an
    /// applicant is by definition not yet a member.
    ///
    /// `applicant_did` must be a `did:key` (the server's proof resolver accepts
    /// no other method) whose seed is `private_key_multibase`. It is the DID
    /// that becomes the member on admission, *not* whatever identity this client
    /// may hold a token for — a fleet manager submitting on behalf of a VTA
    /// signs with that VTA's key.
    ///
    /// The document is addressed to [`vtc_did`](Self::vtc_did) (SPEC §4.8.2
    /// audience binding), so a signed submit captured from one community cannot
    /// be replayed into another.
    ///
    /// ## Why the key, and not just a body
    ///
    /// This used to POST the VP-framed body to `POST /join-requests`, a route
    /// that no longer exists — the holder-facing join verbs (`submit`/`request`,
    /// `manifest`, `status`) were folded into the single Trust-Task document
    /// endpoint, routed by document `type`. That fold moved the applicant's
    /// authentication from "a signature somewhere inside the body" to "a proof
    /// over the whole document", which is why this signature grew the key.
    pub async fn submit_join(
        &self,
        body: &join_requests::JoinRequestSubmitBody,
        applicant_did: &str,
        private_key_multibase: &str,
    ) -> Result<join_requests::VerdictResponse, VtcError> {
        let payload = serde_json::to_value(body)
            .map_err(|e| VtcError::Url(format!("serialise submit payload: {e}")))?;
        let doc = vta_sdk::trust_task_sign::build_signed(
            join_requests::JOIN_REQUEST_SUBMIT_TYPE,
            payload,
            applicant_did,
            private_key_multibase,
            &self.vtc_did,
        )
        .await
        .map_err(|e| VtcError::Signing(e.to_string()))?;

        // The document endpoint takes no `Trust-Task` header — the document's
        // own `type` is the identity, which is exactly why one mount can serve
        // every holder verb.
        let resp = self
            .http
            .post(format!("{}/trust-tasks", self.base_url))
            .header("content-type", "application/json")
            .body(doc)
            .send()
            .await?;
        if !resp.status().is_success() {
            let status = resp.status().as_u16();
            let body = resp.text().await.unwrap_or_default();
            return Err(VtcError::Http { status, body });
        }

        // A Trust-Task request is answered with a `#response` document whose
        // payload is the verdict.
        let text = resp.text().await?;
        let response_doc: trust_tasks_rs::TrustTask<serde_json::Value> =
            serde_json::from_str(&text).map_err(|e| VtcError::Http {
                status: 200,
                body: format!(
                    "unexpected submit response (not a Trust Task document): {e}: {text}"
                ),
            })?;
        serde_json::from_value(response_doc.payload).map_err(|e| VtcError::Http {
            status: 200,
            body: format!("submit response payload is not a VerdictResponse: {e}"),
        })
    }

    /// List the community's policies (opaque JSON descriptors). Admin token.
    pub async fn list_policies(&self) -> Result<Vec<serde_json::Value>, VtcError> {
        let mut out = Vec::new();
        let mut cursor: Option<String> = None;
        loop {
            let mut params: Vec<(&str, &str)> = Vec::new();
            if let Some(cursor) = &cursor {
                params.push(("cursor", cursor.as_str()));
            }
            let url =
                reqwest::Url::parse_with_params(&format!("{}/policies", self.base_url), &params)
                    .map_err(|e| VtcError::Url(e.to_string()))?;
            let resp = self
                .tt(reqwest::Method::GET, url, task::POLICY_LIST)?
                .send()
                .await?;
            if !resp.status().is_success() {
                let status = resp.status().as_u16();
                let body = resp.text().await.unwrap_or_default();
                return Err(VtcError::Http { status, body });
            }
            let page: Page<serde_json::Value> = resp.json().await?;
            out.extend(page.items);
            match page.next_cursor {
                Some(next) => cursor = Some(next),
                None => break,
            }
        }
        Ok(out)
    }

    /// Fetch one policy by id (opaque JSON, incl. the Rego source). Admin token.
    pub async fn get_policy(&self, id: &str) -> Result<serde_json::Value, VtcError> {
        self.get_json(&format!("policies/{id}"), task::POLICY_GET)
            .await
    }

    /// Upload a new Rego policy bundle for `purpose` (`"join"`, `"removal"`,
    /// …). Returns the upload descriptor (id, sha256, version). Admin token.
    /// Upload alone does not activate it — call [`activate_policy`](Self::activate_policy).
    pub async fn upload_policy(
        &self,
        purpose: &str,
        rego_source: &str,
    ) -> Result<serde_json::Value, VtcError> {
        self.post_json(
            "policies",
            task::POLICY_UPSERT,
            &serde_json::json!({ "purpose": purpose, "regoSource": rego_source }),
        )
        .await
    }

    /// Activate a previously-uploaded policy (make it live for decisions of its
    /// purpose). Admin token.
    pub async fn activate_policy(&self, id: &str) -> Result<serde_json::Value, VtcError> {
        self.post_json(
            &format!("policies/{id}/activate"),
            task::POLICY_ACTIVATE,
            &serde_json::json!({}),
        )
        .await
    }

    /// Authenticated GET returning JSON, carrying `task` as the Trust-Task URL.
    async fn get_json(&self, path: &str, task: &str) -> Result<serde_json::Value, VtcError> {
        let resp = self
            .tt(
                reqwest::Method::GET,
                format!("{}/{path}", self.base_url),
                task,
            )?
            .send()
            .await?;
        if !resp.status().is_success() {
            let status = resp.status().as_u16();
            let body = resp.text().await.unwrap_or_default();
            return Err(VtcError::Http { status, body });
        }
        Ok(resp.json().await?)
    }

    /// Authenticated POST of a JSON body returning JSON, carrying `task` as the
    /// Trust-Task URL.
    async fn post_json(
        &self,
        path: &str,
        task: &str,
        body: &serde_json::Value,
    ) -> Result<serde_json::Value, VtcError> {
        let resp = self
            .tt(
                reqwest::Method::POST,
                format!("{}/{path}", self.base_url),
                task,
            )?
            .json(body)
            .send()
            .await?;
        if !resp.status().is_success() {
            let status = resp.status().as_u16();
            let body = resp.text().await.unwrap_or_default();
            return Err(VtcError::Http { status, body });
        }
        Ok(resp.json().await?)
    }

    /// Bearer token or [`VtcError::NotAuthenticated`].
    fn token(&self) -> Result<&str, VtcError> {
        self.token.as_deref().ok_or(VtcError::NotAuthenticated)
    }
}

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

    #[test]
    fn member_page_deserializes_from_vtc_shape() {
        // A `Paginated<MemberResponse>` as the VTC serialises it (extra fields
        // present to prove they're ignored).
        let json = serde_json::json!({
            "items": [{
                "did": "did:key:z6MkStaffVta",
                "role": "member",
                "label": "Staff VTA",
                "joinedAt": "2026-06-23T00:00:00Z",
                "publishConsent": true,
                "departurePreference": "tombstone",
                "statusListIndex": 7,
                "currentVmcId": "urn:uuid:vmc-1",
                "extensions": {},
                "personhood": false,
                "joinedViaInvitation": true
            }],
            "next_cursor": null
        });
        let page: Page<MemberRecord> = serde_json::from_value(json).unwrap();
        assert_eq!(page.items.len(), 1);
        let m = &page.items[0];
        assert_eq!(m.did, "did:key:z6MkStaffVta");
        assert_eq!(m.role, "member");
        assert_eq!(m.status_list_index, Some(7));
        assert_eq!(m.current_vmc_id.as_deref(), Some("urn:uuid:vmc-1"));
        assert!(m.joined_via_invitation);
        assert!(page.next_cursor.is_none());
    }

    #[tokio::test]
    async fn list_members_without_token_is_not_authenticated() {
        let client = VtcClient {
            http: reqwest::Client::new(),
            base_url: "https://vtc.example.com/v1".into(),
            vtc_did: "did:web:vtc.example.com".into(),
            token: None,
        };
        // The token guard returns before any network I/O.
        let err = client.list_members(None).await;
        assert!(matches!(err, Err(VtcError::NotAuthenticated)), "{err:?}");
    }

    #[test]
    fn decide_result_deserializes_camel_case() {
        let json = serde_json::json!({
            "requestId": "11111111-1111-1111-1111-111111111111",
            "status": "approved",
            "vmc": { "type": ["VerifiableCredential", "MembershipCredential"] },
            "roleVec": null
        });
        let d: DecideResult = serde_json::from_value(json).unwrap();
        assert_eq!(d.request_id, "11111111-1111-1111-1111-111111111111");
        assert_eq!(d.status, "approved");
        assert!(d.vmc.is_some());
        assert!(d.role_vec.is_none());
    }

    #[test]
    fn join_request_and_remove_results_deserialize() {
        let jr: JoinRequestSummary = serde_json::from_value(serde_json::json!({
            "id": "22222222-2222-2222-2222-222222222222",
            "applicantDid": "did:key:z6MkApplicant",
            "status": "pending",
            "submittedAt": "2026-06-23T00:00:00Z"
        }))
        .unwrap();
        assert_eq!(jr.applicant_did, "did:key:z6MkApplicant");
        assert_eq!(jr.status, "pending");

        let rm: RemoveResult = serde_json::from_value(serde_json::json!({
            "did": "did:key:z6MkGone",
            "disposition": "tombstone",
            "removed": true
        }))
        .unwrap();
        assert_eq!(rm.did, "did:key:z6MkGone");
        assert!(rm.removed);
    }

    #[tokio::test]
    async fn admin_methods_without_token_are_not_authenticated() {
        let client = VtcClient {
            http: reqwest::Client::new(),
            base_url: "https://vtc.example.com/v1".into(),
            vtc_did: "did:web:vtc.example.com".into(),
            token: None,
        };
        assert!(matches!(
            client.list_join_requests(Some("pending")).await,
            Err(VtcError::NotAuthenticated)
        ));
        assert!(matches!(
            client.approve_join("req-1").await,
            Err(VtcError::NotAuthenticated)
        ));
        assert!(matches!(
            client.remove_member("did:key:x", Some("reason")).await,
            Err(VtcError::NotAuthenticated)
        ));
    }

    #[test]
    fn member_extensions_default_and_parse() {
        let none: MemberRecord = serde_json::from_value(serde_json::json!({
            "did": "did:key:z", "role": "member", "joinedAt": "2026-06-23T00:00:00Z"
        }))
        .unwrap();
        assert!(none.extensions.is_null());
        let with: MemberRecord = serde_json::from_value(serde_json::json!({
            "did": "did:key:z", "role": "member", "joinedAt": "2026-06-23T00:00:00Z",
            "extensions": { "fleet_index": 3 }
        }))
        .unwrap();
        assert_eq!(with.extensions["fleet_index"], 3);
    }

    #[tokio::test]
    async fn policy_admin_methods_without_token_are_not_authenticated() {
        let client = VtcClient {
            http: reqwest::Client::new(),
            base_url: "https://vtc.example.com/v1".into(),
            vtc_did: "did:web:vtc.example.com".into(),
            token: None,
        };
        assert!(matches!(
            client.list_policies().await,
            Err(VtcError::NotAuthenticated)
        ));
        assert!(matches!(
            client.get_policy("p1").await,
            Err(VtcError::NotAuthenticated)
        ));
        assert!(matches!(
            client.upload_policy("join", "package x").await,
            Err(VtcError::NotAuthenticated)
        ));
        assert!(matches!(
            client.activate_policy("p1").await,
            Err(VtcError::NotAuthenticated)
        ));
        assert!(matches!(
            client
                .update_member_extensions("did:key:z", serde_json::json!({}))
                .await,
            Err(VtcError::NotAuthenticated)
        ));
    }
}