Skip to main content

hyprstream_core/services/oauth/
introspection.rs

1//! RFC 7662 Token Introspection endpoint.
2//!
3//! `POST /oauth/introspect` — validates a token and returns its metadata.
4//! Caller must authenticate with a Bearer token.
5//!
6//! - JWT access tokens: routed by algorithm and verified against the server's
7//!   exact published composite pair or Ed25519 key.
8//! - Opaque refresh tokens: looked up from RocksDB with lazy expiry.
9//! - Any failure → `{"active": false}` per RFC 7662 § 2.2.
10
11use std::sync::Arc;
12
13use axum::{
14    extract::{Extension, State},
15    http::{header, StatusCode},
16    response::{IntoResponse, Response},
17    Form, Json,
18};
19use serde::Deserialize;
20
21use super::state::OAuthState;
22use crate::server::middleware::AuthenticatedUser;
23
24#[derive(Deserialize)]
25pub struct IntrospectRequest {
26    pub token: String,
27    #[serde(default)]
28    pub token_type_hint: Option<String>,
29}
30
31/// POST /oauth/introspect (RFC 7662)
32pub async fn introspect_token(
33    State(state): State<Arc<OAuthState>>,
34    Extension(caller): Extension<AuthenticatedUser>,
35    Form(params): Form<IntrospectRequest>,
36) -> Response {
37    // JWT tokens contain dots; opaque tokens do not.
38    if params.token.contains('.') {
39        introspect_jwt(&state, &caller, &params.token).await
40    } else {
41        introspect_refresh(&state, &caller, &params.token).await
42    }
43}
44
45fn caller_may_introspect_tenant(caller: &AuthenticatedUser, tenant: Option<&str>) -> bool {
46    match caller.authorization_domain() {
47        Ok(domain) if domain == "*" => true,
48        Ok(domain) => tenant.is_some_and(|tenant| tenant == domain),
49        Err(_) => false,
50    }
51}
52
53async fn introspect_jwt(
54    state: &Arc<OAuthState>,
55    caller: &AuthenticatedUser,
56    token: &str,
57) -> Response {
58    let claims = match super::auth::validate_oauth_access_token(state, token).await {
59        Ok(c) => c,
60        Err(_) => return inactive_response(),
61    };
62
63    if !caller_may_introspect_tenant(caller, claims.tenant.as_deref()) {
64        return inactive_response();
65    }
66
67    let now = chrono::Utc::now().timestamp();
68    if claims.exp < now {
69        return inactive_response();
70    }
71
72    (
73        StatusCode::OK,
74        [
75            (header::CACHE_CONTROL, "no-store"),
76            (header::PRAGMA, "no-cache"),
77        ],
78        Json(serde_json::json!({
79            "active": true,
80            "token_type": "Bearer",
81            "sub": claims.sub,
82            "iss": claims.iss,
83            "exp": claims.exp,
84            "iat": claims.iat,
85            "aud": claims.aud,
86            "scope": claims.scope,
87        })),
88    )
89        .into_response()
90}
91
92async fn introspect_refresh(
93    state: &Arc<OAuthState>,
94    caller: &AuthenticatedUser,
95    token: &str,
96) -> Response {
97    match state.get_refresh_token(token).await {
98        Ok(Some(entry)) => {
99            let (hosted_did, tenant) =
100                match super::token::resolve_hosted_account_binding(state, &entry.username).await {
101                    Ok(binding) => binding,
102                    Err(error) => {
103                        tracing::warn!(
104                            username = %entry.username,
105                            %error,
106                            "refresh-token introspection failed closed on account binding lookup"
107                        );
108                        return inactive_response();
109                    }
110                };
111            if !caller_may_introspect_tenant(caller, Some(&tenant)) {
112                return inactive_response();
113            }
114
115            // Match the mint boundary: generic tokens retain the username,
116            // while active atproto-profile tokens report the mapped DID.
117            let sub = if super::state::atproto_profile_active(&entry.scopes) {
118                hosted_did
119            } else {
120                entry.username.clone()
121            };
122            (
123                StatusCode::OK,
124                [
125                    (header::CACHE_CONTROL, "no-store"),
126                    (header::PRAGMA, "no-cache"),
127                ],
128                Json(serde_json::json!({
129                    "active": true,
130                    "token_type": "refresh_token",
131                    "sub": sub,
132                    "client_id": entry.client_id,
133                    "scope": entry.scopes.join(" "),
134                    "exp": entry.expires_at_unix,
135                })),
136            )
137                .into_response()
138        }
139        _ => inactive_response(),
140    }
141}
142
143fn inactive_response() -> Response {
144    (
145        StatusCode::OK,
146        [
147            (header::CACHE_CONTROL, "no-store"),
148            (header::PRAGMA, "no-cache"),
149        ],
150        Json(serde_json::json!({"active": false})),
151    )
152        .into_response()
153}