Skip to main content

hyprstream_core/services/oauth/
device_enrollment.rs

1//! Anonymous device identity enrollment — POST /api/device/challenge and /api/device/enroll.
2//!
3//! Unauthenticated endpoints. A client proves Ed25519 key possession without
4//! an existing user session. Device-user association happens later, implicitly,
5//! when the `__Secure-VaultDevice` cookie accompanies an OAuth token request.
6//!
7//! Rate limiting on these endpoints is mandatory before production use (RATE-1).
8
9use std::sync::Arc;
10
11use axum::{
12    extract::State,
13    http::{header, StatusCode},
14    response::{IntoResponse, Response},
15    Json,
16};
17use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
18use chrono::Utc;
19use ed25519_dalek::SigningKey;
20use serde::{Deserialize, Serialize};
21
22use crate::auth::{
23    device_challenge::{
24        compute_kid, derive_challenge_key, derive_cookie_key_seed, device_challenge,
25        encode_vault_device_cookie, verify_device_enrollment,
26    },
27    user_store::DeviceRecord,
28};
29use crate::services::oauth::state::OAuthState;
30use hyprstream_rpc::node_identity::derive_purpose_key;
31
32#[derive(Debug, Deserialize)]
33pub struct ChallengeRequest {
34    pub pubkey: String,
35}
36
37#[derive(Debug, Serialize)]
38pub struct ChallengeResponse {
39    pub challenge: String,
40}
41
42#[derive(Debug, Deserialize)]
43pub struct EnrollRequest {
44    pub pubkey: String,
45    pub signature: String,
46}
47
48#[derive(Debug, Serialize)]
49pub struct EnrollResponse {
50    pub adt: String,
51    pub expires_in: u64,
52}
53
54fn decode_b64url(s: &str) -> Option<Vec<u8>> {
55    URL_SAFE_NO_PAD.decode(s).ok()
56}
57
58fn json_error(status: StatusCode, msg: &str) -> Response {
59    (status, Json(serde_json::json!({ "error": msg }))).into_response()
60}
61
62/// POST /api/device/challenge
63///
64/// Returns `HMAC(challenge_key, pubkey)` for the client to sign.
65/// Stateless — no server storage.
66pub async fn device_challenge_handler(
67    State(state): State<Arc<OAuthState>>,
68    Json(req): Json<ChallengeRequest>,
69) -> Response {
70    let pubkey_bytes = match decode_b64url(&req.pubkey) {
71        Some(b) if b.len() == 32 => b,
72        _ => return json_error(StatusCode::BAD_REQUEST, "pubkey must be 32 bytes base64url"),
73    };
74    let mut pubkey_arr = [0u8; 32];
75    pubkey_arr.copy_from_slice(&pubkey_bytes);
76
77    let Some(ref sk) = state.signing_key else {
78        return json_error(
79            StatusCode::SERVICE_UNAVAILABLE,
80            "signing key not configured",
81        );
82    };
83
84    let sk_bytes = sk.to_bytes();
85    let challenge_key = derive_challenge_key(&sk_bytes);
86    let challenge = device_challenge(&challenge_key, &pubkey_arr);
87
88    Json(ChallengeResponse {
89        challenge: URL_SAFE_NO_PAD.encode(challenge),
90    })
91    .into_response()
92}
93
94/// POST /api/device/enroll
95///
96/// Verifies the Ed25519 signature, upserts a DeviceRecord, issues an ADT JWT,
97/// and sets the `__Secure-VaultDevice` cookie.
98pub async fn device_enroll_handler(
99    State(state): State<Arc<OAuthState>>,
100    Json(req): Json<EnrollRequest>,
101) -> Response {
102    let pubkey_bytes = match decode_b64url(&req.pubkey) {
103        Some(b) if b.len() == 32 => b,
104        _ => return json_error(StatusCode::BAD_REQUEST, "pubkey must be 32 bytes base64url"),
105    };
106    let sig_bytes = match decode_b64url(&req.signature) {
107        Some(b) if b.len() == 64 => b,
108        _ => {
109            return json_error(
110                StatusCode::BAD_REQUEST,
111                "signature must be 64 bytes base64url",
112            )
113        }
114    };
115
116    let mut pubkey_arr = [0u8; 32];
117    pubkey_arr.copy_from_slice(&pubkey_bytes);
118    let mut sig_arr = [0u8; 64];
119    sig_arr.copy_from_slice(&sig_bytes);
120
121    let Some(ref sk) = state.signing_key else {
122        return json_error(
123            StatusCode::SERVICE_UNAVAILABLE,
124            "signing key not configured",
125        );
126    };
127
128    let sk_bytes = sk.to_bytes();
129    let challenge_key = derive_challenge_key(&sk_bytes);
130
131    if !verify_device_enrollment(&challenge_key, &pubkey_arr, &sig_arr) {
132        return json_error(StatusCode::UNAUTHORIZED, "invalid signature");
133    }
134
135    // Compute base58 fingerprint
136    let fingerprint = bs58::encode(&pubkey_arr).into_string();
137    let now = Utc::now().timestamp();
138
139    // Upsert DeviceRecord
140    let record = DeviceRecord {
141        pubkey: pubkey_arr,
142        fingerprint: fingerprint.clone(),
143        label: None,
144        enrolled_at: now,
145        last_seen_at: None,
146        user_sub: None,
147    };
148
149    if let Some(ref ds) = state.device_store {
150        if let Err(e) = ds.enroll_device(record).await {
151            tracing::warn!("Failed to persist DeviceRecord: {e}");
152        }
153    }
154
155    // Derive cookie signing key from signing key
156    let cookie_seed = derive_cookie_key_seed(&sk_bytes);
157    let cookie_sk = SigningKey::from_bytes(&cookie_seed);
158    let cookie_kid = compute_kid(cookie_sk.verifying_key().as_bytes());
159    let cookie_exp = now + 2_592_000; // 30 days, matches Max-Age
160    let cookie_value = encode_vault_device_cookie(&cookie_sk, &cookie_kid, &pubkey_arr, cookie_exp);
161
162    // Issue ADT JWT
163    let sub = format!("device:{fingerprint}");
164    let pubkey_b64 = URL_SAFE_NO_PAD.encode(pubkey_arr);
165    let adt_exp = now + 86400;
166
167    // Build claims manually (Claims struct may not have all fields we need)
168    let adt_payload = serde_json::json!({
169        "iss": state.issuer_url,
170        "sub": sub,
171        "aud": "hyprstream",
172        "cnf": { "jwk": { "kty": "OKP", "crv": "Ed25519", "x": pubkey_b64 } },
173        "scope": "device:anonymous",
174        "iat": now,
175        "exp": adt_exp,
176    });
177
178    // Sign the ADT JWT using the JWT signing purpose key
179    let jwt_key = derive_purpose_key(sk, "hyprstream-jwt-v1");
180    let kid = hyprstream_rpc::auth::jwt::kid_for_key(&jwt_key);
181    let header = serde_json::json!({ "alg": "EdDSA", "typ": "at+jwt", "kid": kid });
182    let header_b64 = URL_SAFE_NO_PAD.encode(header.to_string());
183    let payload_b64 = URL_SAFE_NO_PAD.encode(adt_payload.to_string());
184    let signing_input = format!("{header_b64}.{payload_b64}");
185    use ed25519_dalek::Signer;
186    let sig = jwt_key.sign(signing_input.as_bytes());
187    let adt = format!("{signing_input}.{}", URL_SAFE_NO_PAD.encode(sig.to_bytes()));
188
189    // Cookie attributes: HttpOnly, Secure, SameSite=Strict, Max-Age=30 days
190    let cookie_header = format!(
191        "__Secure-VaultDevice={}; HttpOnly; Secure; SameSite=Strict; Max-Age=2592000; Path=/",
192        cookie_value
193    );
194
195    (
196        StatusCode::OK,
197        [(header::SET_COOKIE, cookie_header)],
198        Json(EnrollResponse {
199            adt,
200            expires_in: 86400,
201        }),
202    )
203        .into_response()
204}