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