Skip to main content

atomic_integration_proxy/device/
mod.rs

1//! Additional Local Thought client authentication (RFC 8628), independent
2//! of provider OAuth and of the retired provider connection codes.
3pub(crate) mod store;
4#[cfg(test)]
5mod tests;
6
7use crate::{api_error::ApiError, AppState};
8use axum::{
9    body::Bytes,
10    extract::{ConnectInfo, DefaultBodyLimit, OriginalUri, Path, Query, State},
11    http::{header, HeaderMap, Method, StatusCode},
12    response::{Html, IntoResponse, Response},
13    routing::{delete, get, post},
14    Json, Router,
15};
16use serde::Deserialize;
17use serde_json::json;
18use std::{collections::BTreeMap, net::SocketAddr, time::Duration};
19
20pub const DISCOVERY_SCOPE: &str = "connections:read";
21pub const READ_SCOPE: &str = "proxy:read";
22const DEVICE_GRANT: &str = "urn:ietf:params:oauth:grant-type:device_code";
23
24/// Public clients have display names fixed by the operator, never provided
25/// by the device. The approval URL is a trusted owner hub using the browser
26/// module; registering clients requires an explicit approval integration.
27#[derive(Clone, Debug, Default)]
28pub struct DeviceConfig {
29    pub clients: BTreeMap<String, String>,
30    pub approval_url: Option<String>,
31}
32impl DeviceConfig {
33    pub(crate) fn from_env() -> Result<Self, String> {
34        let clients = match std::env::var("DEVICE_CLIENTS")
35            .ok()
36            .filter(|s| !s.trim().is_empty())
37        {
38            Some(value) => serde_json::from_str(&value).map_err(|_| {
39                "DEVICE_CLIENTS must be a JSON object mapping public client ids to display names"
40            })?,
41            None => BTreeMap::new(),
42        };
43        let config = Self {
44            clients,
45            approval_url: std::env::var("DEVICE_APPROVAL_URL")
46                .ok()
47                .filter(|s| !s.trim().is_empty()),
48        };
49        config.validate()?;
50        Ok(config)
51    }
52    pub(crate) fn validate(&self) -> Result<(), String> {
53        if self.clients.len() > 20
54            || self.clients.iter().any(|(id, name)| {
55                id.is_empty()
56                    || id.len() > 80
57                    || !id
58                        .bytes()
59                        .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
60                    || name.is_empty()
61                    || name.chars().count() > 100
62                    || name.chars().any(char::is_control)
63            })
64        {
65            return Err("DEVICE_CLIENTS allows at most 20 clients, with 1..80 ASCII id characters and 1..100 display name characters".into());
66        }
67        if !self.clients.is_empty() {
68            let url = self
69                .approval_url
70                .as_ref()
71                .ok_or("DEVICE_APPROVAL_URL is required when device clients are registered")?;
72            let parsed = url::Url::parse(url).map_err(|_| {
73                "DEVICE_APPROVAL_URL must be an absolute HTTPS URL (loopback HTTP for development)"
74            })?;
75            let loopback = matches!(parsed.host_str(), Some("localhost" | "127.0.0.1" | "[::1]"));
76            if !(parsed.scheme() == "https" || parsed.scheme() == "http" && loopback)
77                || !parsed.username().is_empty()
78                || parsed.password().is_some()
79                || parsed.query().is_some()
80                || parsed.fragment().is_some()
81            {
82                return Err("DEVICE_APPROVAL_URL must be an absolute HTTPS URL without credentials, query or fragment (loopback HTTP for development)".into());
83            }
84        }
85        Ok(())
86    }
87}
88
89#[derive(Debug)]
90pub(crate) struct Error {
91    code: &'static str,
92    status: StatusCode,
93}
94impl Error {
95    fn oauth(code: &'static str) -> Self {
96        Self {
97            code,
98            status: StatusCode::BAD_REQUEST,
99        }
100    }
101    fn invalid_token() -> Self {
102        Self {
103            code: "invalid_token",
104            status: StatusCode::UNAUTHORIZED,
105        }
106    }
107    fn limited() -> Self {
108        Self {
109            code: "temporarily_unavailable",
110            status: StatusCode::TOO_MANY_REQUESTS,
111        }
112    }
113}
114impl From<tokio_postgres::Error> for Error {
115    fn from(_: tokio_postgres::Error) -> Self {
116        Self {
117            code: "temporarily_unavailable",
118            status: StatusCode::SERVICE_UNAVAILABLE,
119        }
120    }
121}
122impl From<String> for Error {
123    fn from(_: String) -> Self {
124        Self {
125            code: "temporarily_unavailable",
126            status: StatusCode::SERVICE_UNAVAILABLE,
127        }
128    }
129}
130impl IntoResponse for Error {
131    fn into_response(self) -> Response {
132        let mut response = protected((self.status, Json(json!({"error":self.code}))));
133        if self.status == StatusCode::TOO_MANY_REQUESTS {
134            response
135                .headers_mut()
136                .insert(header::RETRY_AFTER, "60".parse().unwrap());
137        }
138        response
139    }
140}
141fn protected(value: impl IntoResponse) -> Response {
142    let mut response = value.into_response();
143    response
144        .headers_mut()
145        .insert(header::CACHE_CONTROL, "no-store".parse().unwrap());
146    response
147        .headers_mut()
148        .insert(header::PRAGMA, "no-cache".parse().unwrap());
149    response
150        .headers_mut()
151        .insert(header::REFERRER_POLICY, "no-referrer".parse().unwrap());
152    response
153}
154fn enabled(state: &AppState) -> Result<&crate::security::Security, Error> {
155    if state.device.clients.is_empty() {
156        return Err(Error {
157            code: "device_auth_disabled",
158            status: StatusCode::NOT_FOUND,
159        });
160    }
161    state.security.as_ref().ok_or(Error {
162        code: "temporarily_unavailable",
163        status: StatusCode::SERVICE_UNAVAILABLE,
164    })
165}
166fn client<'a>(state: &'a AppState, id: &str) -> Result<&'a str, Error> {
167    state
168        .device
169        .clients
170        .get(id)
171        .map(String::as_str)
172        .ok_or(Error::oauth("invalid_client"))
173}
174pub(crate) fn secret(prefix: &str) -> String {
175    format!("{prefix}{}", crate::connect::random())
176}
177pub(crate) fn hash(value: &str) -> String {
178    crate::signature::sha256_hex(value.as_bytes())
179}
180pub(crate) fn valid_secret(value: &str, prefix: &str) -> bool {
181    value.strip_prefix(prefix).is_some_and(|s| {
182        s.len() == 43
183            && s.bytes()
184                .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
185    })
186}
187fn user_code(value: &str) -> Result<String, Error> {
188    if value.len() > 11 {
189        return Err(Error::oauth("invalid_grant"));
190    }
191    let normalized = value.replace('-', "").to_ascii_uppercase();
192    if normalized.len() != 10
193        || !normalized
194            .bytes()
195            .all(|b| b"ABCDEFGHJKLMNPQRSTUVWXYZ23456789".contains(&b))
196    {
197        return Err(Error::oauth("invalid_grant"));
198    }
199    Ok(normalized)
200}
201fn scopes(value: Option<&str>) -> Result<String, Error> {
202    let mut scopes: Vec<&str> = value
203        .unwrap_or("connections:read proxy:read")
204        .split_ascii_whitespace()
205        .collect();
206    if scopes.is_empty()
207        || scopes
208            .iter()
209            .any(|s| *s != DISCOVERY_SCOPE && *s != READ_SCOPE)
210    {
211        return Err(Error::oauth("invalid_scope"));
212    }
213    scopes.sort_unstable();
214    scopes.dedup();
215    Ok(scopes.join(" "))
216}
217fn form(headers: &HeaderMap, body: &[u8]) -> Result<BTreeMap<String, String>, Error> {
218    if body.len() > 8192
219        || !headers
220            .get(header::CONTENT_TYPE)
221            .and_then(|v| v.to_str().ok())
222            .is_some_and(|s| s.split(';').next() == Some("application/x-www-form-urlencoded"))
223    {
224        return Err(Error::oauth("invalid_request"));
225    }
226    let mut fields = BTreeMap::new();
227    for (k, v) in url::form_urlencoded::parse(body) {
228        if fields.insert(k.into_owned(), v.into_owned()).is_some() {
229            return Err(Error::oauth("invalid_request"));
230        }
231    }
232    Ok(fields)
233}
234fn field<'a>(fields: &'a BTreeMap<String, String>, name: &str) -> Result<&'a str, Error> {
235    fields
236        .get(name)
237        .map(String::as_str)
238        .ok_or(Error::oauth("invalid_request"))
239}
240async fn limit(
241    state: &AppState,
242    security: &crate::security::Security,
243    headers: &HeaderMap,
244    peer: Option<SocketAddr>,
245    action: &str,
246    count: u32,
247) -> Result<(), Error> {
248    let network = crate::client_addr::client_network(state.trust_forwarded_for, headers, peer);
249    let bucket = security.key_check_bucket(&format!("device:{action}"), &network);
250    if security
251        .take_key_check_allowance(&bucket, count, Duration::from_secs(60))
252        .await?
253        .is_some()
254    {
255        return Err(Error::limited());
256    }
257    Ok(())
258}
259
260pub(crate) fn router() -> Router<AppState> {
261    Router::new()
262        .route("/.well-known/oauth-authorization-server", get(discovery))
263        .route("/oauth/device/code", post(authorize))
264        .route("/oauth/device/token", post(token))
265        .route("/oauth/device/revoke", post(revoke))
266        .route("/device", get(page))
267        .route("/device/approval.mjs", get(approval_module))
268        .route("/device/challenge", post(challenge))
269        .route("/device/approve", post(approve))
270        .route("/device/sessions", get(sessions))
271        .route("/device/sessions/:session_id", delete(revoke_session))
272        .layer(DefaultBodyLimit::max(8192))
273}
274async fn discovery(State(state): State<AppState>) -> Response {
275    if let Err(e) = enabled(&state) {
276        return e.into_response();
277    }
278    let base = &state.base_url;
279    protected(Json(
280        json!({"issuer":base,"device_authorization_endpoint":format!("{base}/oauth/device/code"),"token_endpoint":format!("{base}/oauth/device/token"),"revocation_endpoint":format!("{base}/oauth/device/revoke"),"grant_types_supported":[DEVICE_GRANT,"refresh_token"],"token_endpoint_auth_methods_supported":["none"],"revocation_endpoint_auth_methods_supported":["none"],"scopes_supported":[DISCOVERY_SCOPE,READ_SCOPE],"device_approval_challenge_endpoint":format!("{base}/device/challenge"),"device_approval_endpoint":format!("{base}/device/approve")}),
281    ))
282}
283async fn authorize(
284    State(state): State<AppState>,
285    peer: Option<ConnectInfo<SocketAddr>>,
286    headers: HeaderMap,
287    body: Bytes,
288) -> Response {
289    let result = async {
290        let security=enabled(&state)?;
291        limit(&state,security,&headers,peer.map(|p|p.0),"code",20).await?;
292        let fields=form(&headers,&body)?;
293        let id=field(&fields,"client_id")?;client(&state,id)?;
294        let scope=scopes(fields.get("scope").map(String::as_str))?;
295        let (device,code)=store::create(security,id,&state.base_url,&scope).await?;
296        let verification=format!("{}/device",state.base_url);
297        let mut complete=url::Url::parse(&verification).map_err(|_|Error::oauth("invalid_request"))?;
298        complete.query_pairs_mut().append_pair("user_code",&code);
299        Ok::<_,Error>(protected(Json(json!({"device_code":device,"user_code":code,"verification_uri":verification,"verification_uri_complete":complete.as_str(),"expires_in":600,"interval":5}))))
300    }.await;
301    result.unwrap_or_else(IntoResponse::into_response)
302}
303async fn token(
304    State(state): State<AppState>,
305    peer: Option<ConnectInfo<SocketAddr>>,
306    headers: HeaderMap,
307    body: Bytes,
308) -> Response {
309    let result = async {
310        let security = enabled(&state)?;
311        limit(&state, security, &headers, peer.map(|p| p.0), "token", 120).await?;
312        let fields = form(&headers, &body)?;
313        let id = field(&fields, "client_id")?;
314        client(&state, id)?;
315        if fields.contains_key("client_secret") {
316            return Err(Error::oauth("invalid_client"));
317        }
318        let value = match field(&fields, "grant_type")? {
319            DEVICE_GRANT => {
320                let code = field(&fields, "device_code")?;
321                if !valid_secret(code, "lt_device_") {
322                    return Err(Error::oauth("invalid_grant"));
323                }
324                store::poll(security, code, id, &state.base_url).await?
325            }
326            "refresh_token" => {
327                if fields.contains_key("scope") {
328                    return Err(Error::oauth("invalid_scope"));
329                }
330                let refresh = field(&fields, "refresh_token")?;
331                if !valid_secret(refresh, "lt_refresh_") {
332                    return Err(Error::oauth("invalid_grant"));
333                }
334                store::refresh(security, refresh, id, &state.base_url).await?
335            }
336            _ => return Err(Error::oauth("unsupported_grant_type")),
337        };
338        Ok::<_, Error>(protected(Json(value)))
339    }
340    .await;
341    result.unwrap_or_else(IntoResponse::into_response)
342}
343async fn revoke(
344    State(state): State<AppState>,
345    peer: Option<ConnectInfo<SocketAddr>>,
346    headers: HeaderMap,
347    body: Bytes,
348) -> Response {
349    let result = async {
350        let security = enabled(&state)?;
351        limit(&state, security, &headers, peer.map(|p| p.0), "revoke", 60).await?;
352        let fields = form(&headers, &body)?;
353        let id = field(&fields, "client_id")?;
354        client(&state, id)?;
355        let token = field(&fields, "token")?;
356        if valid_secret(token, "lt_access_") || valid_secret(token, "lt_refresh_") {
357            store::revoke(security, token, id, &state.base_url).await?;
358        }
359        Ok::<_, Error>(protected(StatusCode::OK))
360    }
361    .await;
362    result.unwrap_or_else(IntoResponse::into_response)
363}
364
365#[derive(Deserialize)]
366#[serde(deny_unknown_fields)]
367struct Code {
368    user_code: String,
369}
370#[derive(Deserialize)]
371#[serde(deny_unknown_fields)]
372struct Approval {
373    challenge: String,
374    approve: bool,
375    connections: Vec<String>,
376}
377async fn owner(
378    state: &AppState,
379    method: &Method,
380    uri: &axum::http::Uri,
381    headers: &HeaderMap,
382    body: &[u8],
383) -> Result<crate::AgentId, ApiError> {
384    if headers.contains_key(header::AUTHORIZATION) {
385        return Err(ApiError::UnsupportedAuthorization);
386    }
387    let security = state.security.as_ref().ok_or(ApiError::Unavailable)?;
388    let owner = crate::signature::authenticate(state, security, method, uri, headers, body).await?;
389    crate::check_access(state, &owner).await?;
390    Ok(owner)
391}
392async fn owner_limit(state: &AppState, owner: &crate::AgentId) -> Result<(), Error> {
393    let security = enabled(state)?;
394    let bucket = security.key_check_bucket("device:owner", owner.as_str());
395    if security
396        .take_key_check_allowance(&bucket, 20, Duration::from_secs(60))
397        .await?
398        .is_some()
399    {
400        return Err(Error::limited());
401    }
402    Ok(())
403}
404async fn challenge(
405    State(state): State<AppState>,
406    peer: Option<ConnectInfo<SocketAddr>>,
407    method: Method,
408    OriginalUri(uri): OriginalUri,
409    headers: HeaderMap,
410    body: Bytes,
411) -> Response {
412    let result = async {
413        let security = enabled(&state).map_err(IntoResponse::into_response)?;
414        limit(
415            &state,
416            security,
417            &headers,
418            peer.map(|p| p.0),
419            "approval",
420            30,
421        )
422        .await
423        .map_err(IntoResponse::into_response)?;
424        let owner = owner(&state, &method, &uri, &headers, &body)
425            .await
426            .map_err(IntoResponse::into_response)?;
427        owner_limit(&state, &owner)
428            .await
429            .map_err(IntoResponse::into_response)?;
430        let request: Code = serde_json::from_slice(&body)
431            .map_err(|_| Error::oauth("invalid_request").into_response())?;
432        let code = user_code(&request.user_code).map_err(IntoResponse::into_response)?;
433        let mut value = store::challenge(security, &code, owner.as_str(), &state.base_url)
434            .await
435            .map_err(IntoResponse::into_response)?;
436        let (connections, _) = security
437            .list_for_owner(owner.as_str())
438            .await
439            .map_err(|_| ApiError::Unavailable.into_response())?;
440        value["client_name"] = json!(client(
441            &state,
442            value["client_id"].as_str().unwrap_or_default()
443        )
444        .map_err(IntoResponse::into_response)?);
445        value["owner"] = json!(owner.as_str());
446        value["connections"] = json!(connections
447            .into_iter()
448            .map(|c| json!({"connection_id":c.connection_id,"platform":c.platform,"label":c.label}))
449            .collect::<Vec<_>>());
450        Ok::<_, Response>(protected(Json(value)))
451    }
452    .await;
453    result.unwrap_or_else(|r| r)
454}
455async fn approve(
456    State(state): State<AppState>,
457    method: Method,
458    OriginalUri(uri): OriginalUri,
459    headers: HeaderMap,
460    body: Bytes,
461) -> Response {
462    let result = async {
463        let security = enabled(&state).map_err(IntoResponse::into_response)?;
464        let owner = owner(&state, &method, &uri, &headers, &body)
465            .await
466            .map_err(IntoResponse::into_response)?;
467        owner_limit(&state, &owner)
468            .await
469            .map_err(IntoResponse::into_response)?;
470        let request: Approval = serde_json::from_slice(&body)
471            .map_err(|_| Error::oauth("invalid_request").into_response())?;
472        if !valid_secret(&request.challenge, "lt_approval_")
473            || request.connections.len() > 20
474            || request.connections.iter().any(|c| c.len() != 43)
475        {
476            return Err(Error::oauth("invalid_request").into_response());
477        }
478        store::approve(
479            security,
480            &request.challenge,
481            owner.as_str(),
482            &state.base_url,
483            &request.connections,
484            request.approve,
485        )
486        .await
487        .map_err(IntoResponse::into_response)?;
488        Ok::<_, Response>(protected(Json(json!({"approved":request.approve}))))
489    }
490    .await;
491    result.unwrap_or_else(|r| r)
492}
493async fn sessions(
494    State(state): State<AppState>,
495    method: Method,
496    OriginalUri(uri): OriginalUri,
497    headers: HeaderMap,
498    body: Bytes,
499) -> Response {
500    let result = async {
501        let security = enabled(&state).map_err(IntoResponse::into_response)?;
502        let owner = owner(&state, &method, &uri, &headers, &body)
503            .await
504            .map_err(IntoResponse::into_response)?;
505        Ok::<_, Response>(protected(Json(
506            store::sessions(security, owner.as_str(), &state.base_url)
507                .await
508                .map_err(IntoResponse::into_response)?,
509        )))
510    }
511    .await;
512    result.unwrap_or_else(|r| r)
513}
514async fn revoke_session(
515    State(state): State<AppState>,
516    Path(session): Path<String>,
517    method: Method,
518    OriginalUri(uri): OriginalUri,
519    headers: HeaderMap,
520    body: Bytes,
521) -> Response {
522    let result = async {
523        let security = enabled(&state).map_err(IntoResponse::into_response)?;
524        let owner = owner(&state, &method, &uri, &headers, &body)
525            .await
526            .map_err(IntoResponse::into_response)?;
527        store::revoke_owned(security, owner.as_str(), &session, &state.base_url)
528            .await
529            .map_err(IntoResponse::into_response)?;
530        Ok::<_, Response>(protected(StatusCode::NO_CONTENT))
531    }
532    .await;
533    result.unwrap_or_else(|r| r)
534}
535async fn page(
536    State(state): State<AppState>,
537    Query(query): Query<BTreeMap<String, String>>,
538) -> Response {
539    if let Err(e) = enabled(&state) {
540        return e.into_response();
541    }
542    let code = query
543        .get("user_code")
544        .and_then(|v| user_code(v).ok())
545        .unwrap_or_default();
546    let mut url =
547        url::Url::parse(state.device.approval_url.as_deref().unwrap_or_default()).unwrap();
548    if !code.is_empty() {
549        url.query_pairs_mut().append_pair("user_code", &code);
550    }
551    // URL comes from validated operator configuration; encode HTML context.
552    let escaped = url
553        .as_str()
554        .replace('&', "&amp;")
555        .replace('"', "&quot;")
556        .replace('<', "&lt;");
557    let mut response=protected(Html(format!("<!doctype html><meta charset=utf-8><title>Approve a CLI connection</title><h1>Approve a CLI connection</h1><p>Continue in your owner hub to authenticate as your existing Atomic owner, review the client, and select connections. Compare the code with the CLI you started. Approve only a login you initiated.</p><p>User code: <strong>{code}</strong></p><a href=\"{escaped}\">Continue to owner approval</a>")));
558    response.headers_mut().insert(
559        header::CONTENT_SECURITY_POLICY,
560        "default-src 'none'; base-uri 'none'; frame-ancestors 'none'"
561            .parse()
562            .unwrap(),
563    );
564    response
565}
566async fn approval_module() -> Response {
567    (
568        [
569            (header::CONTENT_TYPE, "text/javascript; charset=utf-8"),
570            (header::CACHE_CONTROL, "no-store"),
571        ],
572        include_str!("../../static/device-approval.mjs"),
573    )
574        .into_response()
575}
576
577/// Recognizes only new, namespaced Local Thought access tokens. A retired
578/// Bearer connection code stays unsupported and never falls back to signing.
579pub(crate) fn bearer(headers: &HeaderMap) -> Result<Option<&str>, ApiError> {
580    if headers.get_all(header::AUTHORIZATION).iter().count() > 1 {
581        return Err(ApiError::UnsupportedAuthorization);
582    }
583    let Some(value) = headers.get(header::AUTHORIZATION) else {
584        return Ok(None);
585    };
586    let value = value
587        .to_str()
588        .map_err(|_| ApiError::UnsupportedAuthorization)?;
589    let Some((scheme, token)) = value.split_once(' ') else {
590        return Err(ApiError::UnsupportedAuthorization);
591    };
592    if !scheme.eq_ignore_ascii_case("bearer") {
593        return Ok(None);
594    }
595    if !valid_secret(token, "lt_access_") {
596        return Err(ApiError::UnsupportedAuthorization);
597    }
598    Ok(Some(token))
599}
600pub(crate) async fn principal(state: &AppState, token: &str) -> Result<store::Principal, ApiError> {
601    let security = enabled(state).map_err(|e| {
602        if e.status == StatusCode::SERVICE_UNAVAILABLE {
603            ApiError::Unavailable
604        } else {
605            ApiError::InvalidToken
606        }
607    })?;
608    let principal = store::authenticate(security, token, &state.base_url)
609        .await
610        .map_err(|e| {
611            if e.status == StatusCode::SERVICE_UNAVAILABLE {
612                ApiError::Unavailable
613            } else {
614                ApiError::InvalidToken
615            }
616        })?;
617    if !state.device.clients.contains_key(&principal.client_id) {
618        return Err(ApiError::InvalidToken);
619    }
620    crate::check_access(state, &principal.owner).await?;
621    Ok(principal)
622}
623
624pub(crate) async fn connections(state: &AppState, token: &str) -> Result<Response, ApiError> {
625    let principal = principal(state, token).await?;
626    if !principal
627        .scope
628        .split_ascii_whitespace()
629        .any(|s| s == DISCOVERY_SCOPE)
630    {
631        return Err(ApiError::TokenScope);
632    }
633    let security = state.security.as_ref().ok_or(ApiError::Unavailable)?;
634    let (connections, _) = security
635        .list_for_owner(principal.owner.as_str())
636        .await
637        .map_err(|_| ApiError::Unavailable)?;
638    let connections:Vec<_>=connections.into_iter().filter(|c|principal.connections.contains(&c.connection_id)).map(|c|json!({"connection_id":c.connection_id,"platform":c.platform,"owner":c.owner,"label":c.label})).collect();
639    Ok(protected(Json(
640        json!({"owner":principal.owner.as_str(),"client_id":principal.client_id,"session_id":principal.session_id,"connections":connections}),
641    )))
642}