vta-sdk 0.19.2

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
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

//! Passkey-based login wire types.
//!
//! Maps to the trust-task URIs declared in
//! [`crate::trust_tasks::TASK_AUTH_PASSKEY_LOGIN_START_0_1`] and
//! [`crate::trust_tasks::TASK_AUTH_PASSKEY_LOGIN_FINISH_0_1`].
//!
//! ## Flow
//!
//! 1. Client → `POST /auth/passkey-login/start` with
//!    [`PasskeyLoginStartRequest`]. Server replies
//!    [`PasskeyLoginStartResponse`] with a challenge nonce + the list
//!    of credential IDs the browser may present.
//!
//! 2. Browser runs `navigator.credentials.get(challenge)` and
//!    produces a WebAuthn assertion.
//!
//! 3. Client → `POST /auth/passkey-login/finish` with
//!    [`PasskeyLoginFinishRequest`] carrying the assertion bytes.
//!    Server replies
//!    [`crate::protocols::auth::AuthenticateResponse`] (same shape
//!    as the legacy auth flow's tokens) on success.
//!
//! All byte fields are base64url-encoded (no padding) on the wire.
//! Server-side handlers decode before handing to the verifier.

use serde::{Deserialize, Serialize};

/// Client → server: request a passkey-login challenge.
///
/// Wire shape conforms to `spec/auth/passkey/login/start/0.1`: the
/// `did` field serialises as `subject` per the canonical schema.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct PasskeyLoginStartRequest {
    /// The DID the holder claims they control. Server resolves the
    /// DID document, locates passkey VMs, and returns their
    /// credential IDs as `allow_credentials`.
    #[serde(rename = "subject", alias = "did")]
    pub did: String,
}

/// Server → client: challenge + allowable credentials.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct PasskeyLoginStartResponse {
    /// Opaque session id; client returns it in
    /// [`PasskeyLoginFinishRequest`].
    pub session_id: String,
    /// Hex-encoded 32-byte challenge. The browser passes this (after
    /// base64url-encoding) to `navigator.credentials.get(...)` as the
    /// `challenge` field. Server stores it on the session and
    /// verifies against `clientData.challenge` at finish time.
    pub challenge: String,
    /// Base64url-encoded credential IDs the server expects to see.
    /// May be empty in v0.1 (browser uses discoverable credentials);
    /// Phase 3 hardening adds real credential-ID enumeration.
    #[serde(default)]
    pub allow_credentials: Vec<String>,
}

/// Client → server: present a WebAuthn assertion for verification.
///
/// All byte fields are base64url-encoded (no padding) when serialised.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct PasskeyLoginFinishRequest {
    /// The session id returned by `start`.
    pub session_id: String,
    /// The credential id the browser used to sign (raw assertion `id`).
    pub credential_id: String,
    /// WebAuthn `authenticatorData`.
    pub authenticator_data: String,
    /// WebAuthn `clientDataJSON`. Serde's `camelCase` would lowercase
    /// the "JSON" acronym; we override to match what browsers actually
    /// emit (uppercase JSON suffix).
    #[serde(rename = "clientDataJSON")]
    pub client_data_json: String,
    /// WebAuthn `signature`.
    pub signature: String,
    /// The verificationMethod URL whose key signed the assertion.
    pub verification_method: String,
}

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

    #[test]
    fn start_response_camel_case() {
        let json = r#"{
            "sessionId": "sess-1",
            "challenge": "deadbeef",
            "allowCredentials": ["abc","def"]
        }"#;
        let parsed: PasskeyLoginStartResponse = serde_json::from_str(json).unwrap();
        assert_eq!(parsed.session_id, "sess-1");
        assert_eq!(parsed.challenge, "deadbeef");
        assert_eq!(parsed.allow_credentials, vec!["abc", "def"]);
    }

    #[test]
    fn finish_request_camel_case() {
        let json = r#"{
            "sessionId": "sess-1",
            "credentialId": "cred-id-b64",
            "authenticatorData": "ad-b64",
            "clientDataJSON": "cd-b64",
            "signature": "sig-b64",
            "verificationMethod": "did:webvh:example.com:alice#passkey-abc"
        }"#;
        let parsed: PasskeyLoginFinishRequest = serde_json::from_str(json).unwrap();
        assert_eq!(parsed.session_id, "sess-1");
        assert_eq!(parsed.credential_id, "cred-id-b64");
        assert_eq!(
            parsed.verification_method,
            "did:webvh:example.com:alice#passkey-abc"
        );
    }
}