vta-sdk 0.6.0

SDK for Verifiable Trust Agents operating in Verifiable Trust Communities
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

//! Shared VTA request / reply types for the online provisioning workflow.
//!
//! Three intents are supported:
//!
//! - [`VtaIntent::FullSetup`] — the VTA mints the integration's DID via a
//!   template render, rolls over an admin DID, and returns a
//!   [`super::result::ProvisionResult`] with keys, `did.jsonl`,
//!   authorization VC, and VTA trust bundle.
//! - [`VtaIntent::AdminOnly`] — the integration brings its own DID; the
//!   VTA only issues an admin credential and an ACL row. The setup DID
//!   *is* the long-term admin DID — no rotation. The reply carries an
//!   admin DID + matching private key.
//! - [`VtaIntent::AdminRotated`] — the integration brings its own
//!   integration DID **and** wants the admin DID rotated to a fresh
//!   VTA-minted identity. Same wire flow as `FullSetup` minus the
//!   integration mint. The setup DID authenticates the bootstrap and
//!   loses its authority at the end of the round-trip; the rotated
//!   admin DID becomes the long-term credential. The reply shape
//!   mirrors `AdminOnly` (admin DID + private key), just with a
//!   different DID.
//!
//! Each intent produces a [`VtaReply`] that downstream consumers handle
//! uniformly. The runners in this module produce these replies; the
//! consumer's UI / persistence layer consumes them.
//!
//! Offline / sealed-handoff variants are out of scope for this module —
//! see the workspace `vta bootstrap` CLI for that flow.

use super::result::ProvisionResult;

/// What the operator wants the VTA to do during setup.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VtaIntent {
    /// VTA mints the integration's DID via a template render, rolls over
    /// an admin DID, and returns a [`ProvisionResult`].
    FullSetup,
    /// The integration brings its own DID (out of band); the VTA only
    /// issues an admin credential and an ACL row. The setup DID *is*
    /// the long-term admin DID — no rotation. The reply carries an
    /// admin DID + matching private key.
    AdminOnly,
    /// The integration brings its own DID **and** wants the admin DID
    /// rotated. The setup did:key authenticates the bootstrap and is
    /// then dropped; the VTA mints a fresh admin DID via the
    /// `vta-admin` template, binds the authorization VC + ACL row to
    /// it, and returns the rotated DID + key material. Use this when
    /// a short-lived setup ACL grant should be replaced with a
    /// long-term VTA-minted admin identity in one round-trip.
    AdminRotated,
}

/// Unified reply from the online runners.
///
/// Downstream consumers switch on the variant instead of branching on
/// intent separately. `Full` is boxed so the enum's stack footprint
/// stays uniform regardless of which variant is in play (the underlying
/// `ProvisionResult` is ~528 bytes vs `AdminCredentialReply`'s ~48).
#[derive(Clone, Debug)]
pub enum VtaReply {
    /// Full template-bootstrap reply. The VTA minted the integration's
    /// DID, (optionally) rolled over an admin DID, and returned the
    /// complete trust bundle.
    Full(Box<ProvisionResult>),
    /// Admin-credential-only reply. The integration keeps its own DID;
    /// the VTA supplied an admin identity it authenticates as against
    /// the VTA's admin APIs.
    AdminOnly(AdminCredentialReply),
}

/// Payload of [`VtaReply::AdminOnly`] — an admin DID and its private key.
#[derive(Clone, Debug)]
pub struct AdminCredentialReply {
    /// Admin DID the integration authenticates as.
    pub admin_did: String,
    /// Private key (multibase) paired with `admin_did`.
    pub admin_private_key_mb: String,
}