vta-sdk 0.80.0

SDK for Verifiable Trust Agents operating in Verifiable Trust Communities
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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

use serde::{Deserialize, Serialize};

/// Body for the four agent-name Trust Tasks
/// (`spec/vta/webvh/agent-name/{set,remove,enable,disable}/1.0`).
///
/// All four carry the same shape: the hosted DID and the name's local
/// part (the `alice` in `/@alice`, without the leading `@`). The agent
/// resolves the current DID document, edits its `alsoKnownAs` to
/// claim/no-longer-claim `https://<domain>/@<name>`, signs a new version,
/// and submits it to the hosting server's matching `agent-name/{op}`
/// endpoint. The hosting domain is the DID's own host — derived from the
/// `did:webvh` identifier, not carried here.
///
/// The verb lives in the task's `type` URI, not in this body, so the
/// wallet's consent screen can classify each one independently.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct AgentNameBody {
    pub did: String,
    pub name: String,
}

/// Result of an agent-name Trust Task.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct AgentNameResultBody {
    pub did: String,
    pub name: String,
    /// Whether the name resolves after the operation: `true` for `set`
    /// and `enable`, `false` for `disable` and `remove`.
    ///
    /// It does **not** distinguish parked from released — `disable` and
    /// `remove` both report `false`, and they differ in whether the name
    /// stays reserved to this DID. The caller knows which verb it sent, so
    /// the distinction is in the request rather than duplicated here.
    pub enabled: bool,
}

// `vta/webvh/agent-name/list/1.1` has no hand-written type: its payload and
// response are `vti_specs::vta::webvh::agent_name::list::v1_1`.

/// Body for `spec/vta/webvh/agent-name/check/1.0`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct AgentNameCheckBody {
    /// The DID whose host the name is checked against. Availability is
    /// domain-scoped, and the domain is the DID's own host — the same rule
    /// the mutating verbs use.
    pub did: String,
    /// The name's local part, without the `@`.
    pub name: String,
}

/// Result of `spec/vta/webvh/agent-name/check/1.0`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct AgentNameCheckResultBody {
    /// The canonicalised local part.
    pub name: String,
    /// The domain the answer applies to.
    pub domain: String,
    /// Free to claim: neither reserved nor already bound on this domain.
    pub available: bool,
    /// On the host's reserved list (`@admin`, `@support`, …) — unavailable
    /// but well-formed, which is distinct from a malformed name (an error).
    pub reserved: bool,
}

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

    // Wire shapes crossing to the DID-hosting control plane. Casing drift is
    // this workspace's recurring defect class — an `allowed_contexts` that
    // should have been `allowedContexts` once silently minted a super-admin
    // (#656/#658) — so these pin the serialised key names, not just that the
    // types round-trip through themselves.

    #[test]
    fn request_bodies_serialise_camel_case() {
        let v = serde_json::to_value(AgentNameBody {
            did: "did:webvh:QmScid:example.com".into(),
            name: "ops".into(),
        })
        .unwrap();
        assert_eq!(v["did"], "did:webvh:QmScid:example.com");
        assert_eq!(v["name"], "ops");

        let v = serde_json::to_value(AgentNameCheckBody {
            did: "did:webvh:QmScid:example.com".into(),
            name: "ops".into(),
        })
        .unwrap();
        assert_eq!(v.as_object().unwrap().len(), 2, "no stray fields");
    }

    #[test]
    fn check_result_distinguishes_reserved_from_taken() {
        // Three distinct outcomes share two booleans, so the combination
        // carries the meaning: reserved names are unavailable but well-formed.
        let reserved: AgentNameCheckResultBody = serde_json::from_value(serde_json::json!({
            "name": "admin", "domain": "example.com",
            "available": false, "reserved": true,
        }))
        .unwrap();
        assert!(reserved.reserved && !reserved.available);

        let taken: AgentNameCheckResultBody = serde_json::from_value(serde_json::json!({
            "name": "ops", "domain": "example.com",
            "available": false, "reserved": false,
        }))
        .unwrap();
        assert!(!taken.reserved && !taken.available);
    }

    #[test]
    fn result_body_reports_whether_the_name_resolves() {
        let v = serde_json::to_value(AgentNameResultBody {
            did: "did:webvh:QmScid:example.com".into(),
            name: "ops".into(),
            enabled: false,
        })
        .unwrap();
        assert_eq!(v["enabled"], false);
    }
}