Struct VtcClient 

pub struct VtcClient { /* private fields */ }

A client bound to one VTC’s API base, holding a bearer token once authenticated.

Implementations

impl VtcClient

pub async fn create_room( &self, room_id: &str, owner_did: &str, visibility: Visibility, retention_days: Option<u32>, signer_did: &str, private_key_multibase: &str, ) -> Result<Value, VtcError>

Register a room with this host.

The caller brings room_id: a room identified by something its host chose could not move to another host without changing identity.

pub async fn put_record( &self, session: &RoomSession, key: &str, sealed: Option<SealedContent>, cleartext: Option<CleartextContent>, expected_version: Option<u64>, signer_did: &str, private_key_multibase: &str, ) -> Result<PutRecordResponse, VtcError>

Write a record.

Exactly one of sealed / cleartext — the host refuses the other shape for the room’s tier, so passing both or neither is a request it cannot honour.

expected_version is an optional precondition: Some(0) means create-only, and Some(n) requires the stored record to be at version n. A mismatch comes back carrying the current version, so a caller does not have to re-read to learn what it lost to.

pub async fn get_record( &self, session: &RoomSession, key: &str, signer_did: &str, private_key_multibase: &str, ) -> Result<Value, VtcError>

Read one record.

Presents exactly as a write does, and needs no session — which is the point on a sealed room: authorizing reads by session would hand the host a member identifier on every access, and a period of those reconstructs the membership the tier withholds.

pub async fn list_records( &self, session: &RoomSession, prefix: Option<&str>, since_version: Option<u64>, signer_did: &str, private_key_multibase: &str, ) -> Result<ListRecordsResponse, VtcError>

List record metadata.

Never returns bodies — fetch the handful that matter with VtcClient::get_record. since_version is the incremental-sync watermark, and the response includes tombstones: a caller that never saw a retraction would resurrect the record on its next full rebuild.

pub async fn mint_epoch( &self, session: &RoomSession, epoch: u32, reason: Option<&str>, signer_did: &str, private_key_multibase: &str, ) -> Result<MintEpochResponse, VtcError>

Advance the room’s key epoch — how a member is removed.

Requires a chain conferring admin. epoch must be exactly one greater than the current one. The host records the number and never learns the key: distributing it to the remaining members happens out of its sight.

pub async fn transfer_owner( &self, session: &RoomSession, new_owner_did: &str, reason: Option<&str>, signer_did: &str, private_key_multibase: &str, ) -> Result<OwnerResponse, VtcError>

Hand the room to another member, deliberately and while still present.

Requires a chain conferring admin — the same grant that mints epochs, since transferring is the more consequential of the two.

The host does not check that new_owner_did is a member, and cannot: it holds no roster and no MLS group state. That obligation is the outgoing owner’s, who can see the group. Give the room to someone who cannot commit and they inherit a room they cannot renew.

pub async fn claim_owner( &self, session: &RoomSession, nomination: &str, reason: Option<&str>, signer_did: &str, private_key_multibase: &str, ) -> Result<OwnerResponse, VtcError>

Claim a room whose owner has stopped renewing it.

nomination is the succession credential the room issued to this claimant in advance. All three of the host’s conditions must hold together: a valid nomination, a room that has been dormant past its grace window — not merely lapsed — and the claimant’s own membership, which is what session carries.

A claim does not renew the room. It hands over a dormant room, and the new owner’s first act should be the epoch mint that proves they can perform it.

impl VtcClient

pub async fn connect( base_url: &str, vtc_did: &str, client_did: &str, private_key_multibase: &str, ) -> Result<Self, VtcError>

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 fn with_token( base_url: &str, vtc_did: &str, token: impl Into<String>, ) -> Self

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 anonymous(base_url: &str, vtc_did: &str) -> Self

Construct a client with no bearer token, for the applicant side of the join ceremony.

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 vtc_did(&self) -> &str

The community’s DID this client is bound to.

pub async fn list_members( &self, role: Option<&str>, ) -> Result<Vec<MemberRecord>, VtcError>

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_join_requests( &self, status: Option<&str>, ) -> Result<Vec<JoinRequestSummary>, VtcError>

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 approve_join( &self, request_id: &str, ) -> Result<DecideResult, VtcError>

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 reject_join( &self, request_id: &str, reason: Option<&str>, ) -> Result<DecideResult, VtcError>

Reject a join request, optionally recording an operator rationale in the audit trail. Requires an admin token.

pub async fn remove_member( &self, did: &str, reason: Option<&str>, ) -> Result<RemoveResult, VtcError>

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 update_member_extensions( &self, did: &str, extensions: Value, ) -> Result<(), VtcError>

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 submit_join( &self, body: &JoinRequestSubmitBody, applicant_did: &str, private_key_multibase: &str, ) -> Result<VerdictResponse, VtcError>

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 nor 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 (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 list_policies(&self) -> Result<Vec<Value>, VtcError>

List the community’s policies (opaque JSON descriptors). Admin token.

pub async fn get_policy(&self, id: &str) -> Result<Value, VtcError>

Fetch one policy by id (opaque JSON, incl. the Rego source). Admin token.

pub async fn upload_policy( &self, purpose: &str, rego_source: &str, ) -> Result<Value, VtcError>

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.

pub async fn activate_policy(&self, id: &str) -> Result<Value, VtcError>

Activate a previously-uploaded policy (make it live for decisions of its purpose). Admin token.

Trait Implementations

impl Clone for VtcClient

fn clone(&self) -> VtcClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VtcClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.