pdk_token_introspection_lib/

discovery.rs

// Copyright (c) 2026, Salesforce, Inc.,
// All rights reserved.
// For full license text, see the LICENSE.txt file

//! OAuth 2.0 Protected Resource Discovery (RFC 9728) implementation.
//!
//! This module provides the [`ProtectedResourceMetadata`] which implements
//! RFC 9728 for OAuth 2.0 Protected Resource Metadata. It handles:
//!
//! - Serving the metadata endpoint at `{api_base_path}/.well-known/oauth-protected-resource`
//! - Returning `401 Unauthorized` with `WWW-Authenticate` header for unauthenticated requests
//! - Building RFC 9728 compliant `401` responses for use when token validation fails
//!
//! The API base path is passed in from PDK metadata at configure time so the well-known
//! endpoint is always served relative to the API, not the host root.
//!
//! The request origin (`scheme://authority`) is provided per-request and combined with
//! the API base path to build the `resource` identifier and `resource_metadata` URL.

use pdk_core::classy::hl::Response;
use pdk_core::log::debug;
use pdk_script::Value;
use serde_json::json;
use thiserror::Error;

use crate::discovery_config::ProtectedResourceConfig;

const CONTENT_TYPE_JSON: &str = "application/json";
const CONTENT_TYPE: &str = "Content-Type";
const WELL_KNOWN_PATH: &str = "/.well-known/oauth-protected-resource";
const HTTP_METHOD_GET: &str = "GET";

/// Errors that can occur during discovery handler building.
#[non_exhaustive]
#[derive(Error, Debug)]
pub enum ProtectedResourceMetadataBuildError {
    #[error("Authorization server URL is required but not provided.")]
    MissingAuthorizationServerUrl,
}

/// Created internally by [`crate::introspector::TokenValidatorBuilderInstance::with_protected_resource_metadata`].
/// The API base path is passed in automatically from PDK metadata extracted at configure time.
///
/// This can be built directly by any policy that needs protected-resource metadata, independent of the token introspection flow.
pub struct ProtectedResourceMetadataBuilder {
    authorization_server_url: Option<String>,
    additional_properties: Option<Value>,
    api_base_path: Option<String>,
}

impl ProtectedResourceMetadataBuilder {
    /// Creates a builder for the given API base path (from PDK metadata).
    pub fn new(api_base_path: Option<String>) -> Self {
        ProtectedResourceMetadataBuilder {
            authorization_server_url: None,
            additional_properties: None,
            api_base_path,
        }
    }

    /// Sets the authorization server URL advertised in the metadata document.
    pub fn with_authorization_server(mut self, url: impl Into<String>) -> Self {
        self.authorization_server_url = Some(url.into());
        self
    }

    /// Sets additional optional metadata properties (e.g. `scopes_supported`, `bearer_methods_supported`).
    pub(crate) fn with_metadata_properties(mut self, properties: Value) -> Self {
        self.additional_properties = Some(properties);
        self
    }

    /// Builds the [`ProtectedResourceMetadata`].
    ///
    /// The API base path (from PDK Metadata) is used to place the well-known
    /// endpoint under the API's own path prefix. For example, if the API
    /// listens on `/api`, the metadata endpoint will be
    /// `/api/.well-known/oauth-protected-resource`.
    ///
    /// # Errors
    ///
    /// Returns an error if `authorization_server_url` is missing — call
    /// [`with_authorization_server`](Self::with_authorization_server).
    pub fn build(self) -> Result<ProtectedResourceMetadata, ProtectedResourceMetadataBuildError> {
        let authorization_server_url = self
            .authorization_server_url
            .ok_or(ProtectedResourceMetadataBuildError::MissingAuthorizationServerUrl)?;

        let api_base_path = self
            .api_base_path
            .map(|path| {
                let path = if path.starts_with('/') {
                    path
                } else {
                    format!("/{path}")
                };
                path.trim_end_matches('/').to_string()
            })
            .filter(|path| !path.is_empty());

        // Build the metadata endpoint path:
        //   {api_base_path}/.well-known/oauth-protected-resource
        let base = api_base_path.as_deref().unwrap_or("");
        let metadata_endpoint_path = format!("{base}{WELL_KNOWN_PATH}");

        debug!(
            "Protected resource metadata configured: metadata_endpoint_path={metadata_endpoint_path}"
        );

        Ok(ProtectedResourceMetadata {
            config: ProtectedResourceConfig {
                authorization_server_url,
                additional_properties: self.additional_properties,
            },
            metadata_endpoint_path,
            api_base_path: base.to_string(),
        })
    }
}

/// OAuth 2.0 Protected Resource Metadata (RFC 9728).
///
/// Handles the server-side discovery flow:
///
/// 1. **Metadata endpoint** — serves resource metadata JSON at the well-known
///    path (GET only, per RFC 9728 §3.1).
/// 2. **Invalid token helper** — [`unauthorized_response`](Self::unauthorized_response)
///    builds a 401 for use after token validation failure.
///
/// The well-known path is placed under the API base path, e.g.
/// `/api/.well-known/oauth-protected-resource`.
///
/// All methods take the request `origin` (`scheme://authority`) and combine it
/// with the API base path to build the `resource` identifier and
/// `resource_metadata` URL.
///
/// Use [`ProtectedResourceMetadataBuilder`] to create instances of this type.
#[derive(Clone, Debug)]
pub struct ProtectedResourceMetadata {
    config: ProtectedResourceConfig,
    metadata_endpoint_path: String,
    /// Normalized API base path (e.g. `/api`), empty when no base path.
    api_base_path: String,
}

impl ProtectedResourceMetadata {
    /// Builds the metadata response if the request matches the well-known endpoint.
    ///
    /// The `origin` parameter (`scheme://authority`) is combined with the API
    /// base path to produce the `resource` field in the metadata response.
    ///
    /// Returns `Some(response)` when the request matches; `None` when it does not,
    /// meaning the caller should continue to normal request processing.
    pub fn build_metadata_response(
        &self,
        path: &str,
        method: &str,
        origin: &str,
    ) -> Option<Response> {
        if path == self.metadata_endpoint_path && method.eq_ignore_ascii_case(HTTP_METHOD_GET) {
            debug!(
                "Serving resource metadata at {}",
                self.metadata_endpoint_path
            );
            let origin = origin.trim_end_matches('/');
            let resource_url = format!("{origin}{}", self.api_base_path);
            return Some(self.build_metadata_json_response(&resource_url));
        }
        None
    }

    /// Builds a 401 response with `WWW-Authenticate` including `resource_metadata`.
    ///
    /// The `origin` parameter (`scheme://authority`) is combined with the
    /// metadata endpoint path to produce the `resource_metadata` URL.
    ///
    /// `www_authenticate_extra` is an optional string to include before the
    /// `resource_metadata` hint (e.g. `realm="My API"` produces
    /// `Bearer realm="My API", resource_metadata="..."`).
    pub fn unauthorized_response(
        &self,
        origin: &str,
        www_authenticate_extra: Option<&str>,
    ) -> Response {
        let origin = origin.trim_end_matches('/');
        let metadata_url = format!("{origin}{}", self.metadata_endpoint_path);
        Self::build_unauthorized_response(&metadata_url, www_authenticate_extra)
    }

    /// Internal: builds the 401 response given a fully-qualified metadata URL.
    fn build_unauthorized_response(
        metadata_url: &str,
        www_authenticate_extra: Option<&str>,
    ) -> Response {
        let www_authenticate = match www_authenticate_extra {
            Some(extra) => format!("Bearer {extra}, resource_metadata=\"{metadata_url}\""),
            None => format!("Bearer resource_metadata=\"{metadata_url}\""),
        };
        Response::new(401).with_headers(vec![("WWW-Authenticate".to_string(), www_authenticate)])
    }

    /// Builds a 200 metadata response (RFC 9728 §3.2).
    fn build_metadata_json_response(&self, resource_url: &str) -> Response {
        let resource_url = resource_url.trim_end_matches('/');
        let mut metadata = json!({
            "resource": resource_url,
            "authorization_servers": [self.config.authorization_server_url],
        });

        // Merge additional properties (scopes_supported, etc.)
        if let Some(additional) = &self.config.additional_properties {
            let additional_json: serde_json::Value = additional.clone().into();
            if let (Some(base), Some(extra)) =
                (metadata.as_object_mut(), additional_json.as_object())
            {
                for (key, value) in extra {
                    base.insert(key.clone(), value.clone());
                }
            }
        }

        Response::new(200)
            .with_headers(vec![(
                CONTENT_TYPE.to_string(),
                CONTENT_TYPE_JSON.to_string(),
            )])
            .with_body(metadata.to_string())
    }
}

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

    fn make_handler(api_base_path: Option<&str>) -> ProtectedResourceMetadata {
        ProtectedResourceMetadataBuilder::new(api_base_path.map(str::to_string))
            .with_authorization_server("https://auth.example.com")
            .build()
            .unwrap()
    }

    fn get_header(response: &Response, name: &str) -> Option<String> {
        response
            .headers()
            .iter()
            .find(|(k, _)| k.eq_ignore_ascii_case(name))
            .map(|(_, v)| v.to_string())
    }

    fn get_body_json(response: &Response) -> serde_json::Value {
        let bytes = response.body().expect("should have body");
        serde_json::from_slice(bytes).expect("should be valid JSON")
    }

    // --- Builder tests ---

    #[test]
    fn build_fails_without_authorization_server() {
        let b = ProtectedResourceMetadataBuilder::new(None);
        assert!(matches!(
            b.build().unwrap_err(),
            ProtectedResourceMetadataBuildError::MissingAuthorizationServerUrl
        ));
    }

    #[test]
    fn build_error_message() {
        let e = ProtectedResourceMetadataBuildError::MissingAuthorizationServerUrl;
        assert!(!e.to_string().is_empty());
    }

    // --- Endpoint path tests ---

    #[test]
    fn endpoint_path_without_base_path() {
        let h = make_handler(None);
        assert_eq!(
            h.metadata_endpoint_path,
            "/.well-known/oauth-protected-resource"
        );
    }

    #[test]
    fn endpoint_path_with_base_path() {
        let h = make_handler(Some("/api"));
        assert_eq!(
            h.metadata_endpoint_path,
            "/api/.well-known/oauth-protected-resource"
        );
    }

    #[test]
    fn endpoint_path_normalizes_missing_leading_slash() {
        let h = make_handler(Some("api"));
        assert_eq!(
            h.metadata_endpoint_path,
            "/api/.well-known/oauth-protected-resource"
        );
    }

    #[test]
    fn endpoint_path_normalizes_trailing_slash() {
        let h = make_handler(Some("/api/"));
        assert_eq!(
            h.metadata_endpoint_path,
            "/api/.well-known/oauth-protected-resource"
        );
    }

    #[test]
    fn endpoint_path_treats_root_slash_as_no_base() {
        let h = make_handler(Some("/"));
        assert_eq!(
            h.metadata_endpoint_path,
            "/.well-known/oauth-protected-resource"
        );
    }

    #[test]
    fn endpoint_path_with_nested_base_path() {
        let h = make_handler(Some("/api/v1"));
        assert_eq!(
            h.metadata_endpoint_path,
            "/api/v1/.well-known/oauth-protected-resource"
        );
    }

    // --- Metadata response tests ---

    #[test]
    fn metadata_response_returns_200_json() {
        let h = make_handler(None);
        let resp = h
            .build_metadata_response(
                "/.well-known/oauth-protected-resource",
                "GET",
                "https://test.com",
            )
            .unwrap();

        assert_eq!(resp.status_code(), 200);
        assert_eq!(
            get_header(&resp, "Content-Type").as_deref(),
            Some("application/json")
        );

        let body = get_body_json(&resp);
        assert_eq!(body["resource"], "https://test.com");
        assert_eq!(
            body["authorization_servers"],
            serde_json::json!(["https://auth.example.com"])
        );
    }

    #[test]
    fn metadata_response_merges_additional_properties() {
        let h = ProtectedResourceMetadataBuilder::new(None)
            .with_authorization_server("https://auth.example.com")
            .with_metadata_properties(Value::Object(
                [
                    (
                        "scopes_supported".to_string(),
                        Value::Array(vec![
                            Value::String("read".to_string()),
                            Value::String("write".to_string()),
                        ]),
                    ),
                    (
                        "bearer_methods_supported".to_string(),
                        Value::Array(vec![Value::String("header".to_string())]),
                    ),
                ]
                .into(),
            ))
            .build()
            .unwrap();

        let resp = h
            .build_metadata_response(
                "/.well-known/oauth-protected-resource",
                "GET",
                "https://test.com",
            )
            .unwrap();
        let body = get_body_json(&resp);

        assert_eq!(body["resource"], "https://test.com");
        assert_eq!(
            body["scopes_supported"],
            serde_json::json!(["read", "write"])
        );
        assert_eq!(
            body["bearer_methods_supported"],
            serde_json::json!(["header"])
        );
    }

    #[test]
    fn metadata_response_normalizes_trailing_slash_in_origin() {
        let h = make_handler(None);
        let resp = h
            .build_metadata_response(
                "/.well-known/oauth-protected-resource",
                "GET",
                "https://test.com/",
            )
            .unwrap();

        let body = get_body_json(&resp);
        assert_eq!(body["resource"], "https://test.com");
    }

    // --- Matching tests ---

    #[test]
    fn returns_none_for_non_metadata_path() {
        let h = make_handler(None);
        assert!(h
            .build_metadata_response("/some/other/path", "GET", "https://test.com")
            .is_none());
    }

    #[test]
    fn returns_none_for_post() {
        let h = make_handler(None);
        // POST to the well-known path should not serve metadata (RFC 9728 §3.1)
        assert!(h
            .build_metadata_response(
                "/.well-known/oauth-protected-resource",
                "POST",
                "https://test.com",
            )
            .is_none());
    }

    #[test]
    fn returns_none_for_query_parameters() {
        let h = make_handler(None);
        assert!(h
            .build_metadata_response(
                "/.well-known/oauth-protected-resource?foo=bar",
                "GET",
                "https://test.com",
            )
            .is_none());
    }

    #[test]
    fn returns_none_without_base_path_prefix() {
        // With /api base path, the bare well-known path should not match
        let h = make_handler(Some("/api"));
        assert!(h
            .build_metadata_response(
                "/.well-known/oauth-protected-resource",
                "GET",
                "https://test.com",
            )
            .is_none());
    }

    #[test]
    fn returns_response_with_base_path() {
        let h = make_handler(Some("/api"));
        let resp = h
            .build_metadata_response(
                "/api/.well-known/oauth-protected-resource",
                "GET",
                "https://test.com",
            )
            .unwrap();

        assert_eq!(resp.status_code(), 200);
        let body = get_body_json(&resp);
        assert_eq!(body["resource"], "https://test.com/api");
    }

    // --- 401 response tests ---

    #[test]
    fn unauthorized_response_with_base_path() {
        let h = make_handler(Some("/api"));
        let resp = h.unauthorized_response("https://test.com", None);

        assert_eq!(resp.status_code(), 401);
        assert_eq!(
            get_header(&resp, "WWW-Authenticate").unwrap(),
            "Bearer resource_metadata=\"https://test.com/api/.well-known/oauth-protected-resource\""
        );
    }

    #[test]
    fn unauthorized_response_without_base_path() {
        let h = make_handler(None);
        let resp = h.unauthorized_response("https://test.com", None);

        assert_eq!(resp.status_code(), 401);
        assert_eq!(
            get_header(&resp, "WWW-Authenticate").unwrap(),
            "Bearer resource_metadata=\"https://test.com/.well-known/oauth-protected-resource\""
        );
    }

    #[test]
    fn unauthorized_response_with_extra() {
        let h = make_handler(Some("/api"));
        let resp = h.unauthorized_response(
            "https://test.com",
            Some("realm=\"OAuth2 Introspection Client Realm\""),
        );

        assert_eq!(resp.status_code(), 401);
        assert_eq!(
            get_header(&resp, "WWW-Authenticate").unwrap(),
            "Bearer realm=\"OAuth2 Introspection Client Realm\", resource_metadata=\"https://test.com/api/.well-known/oauth-protected-resource\""
        );
    }

    #[test]
    fn unauthorized_response_normalizes_trailing_slash() {
        let h = make_handler(Some("/api"));
        let resp = h.unauthorized_response("https://test.com/", None);

        let www_auth = get_header(&resp, "WWW-Authenticate").unwrap();
        assert!(!www_auth.contains("//.well-known"));
        assert!(www_auth.contains("https://test.com/api/.well-known"));
    }

    // --- Origin + base path integration tests ---

    #[test]
    fn origin_with_nested_base_path() {
        let h = make_handler(Some("/api/v1"));

        // 401 points to correct metadata URL
        let resp = h.unauthorized_response("https://test.com", None);
        assert_eq!(
            get_header(&resp, "WWW-Authenticate").unwrap(),
            "Bearer resource_metadata=\"https://test.com/api/v1/.well-known/oauth-protected-resource\""
        );

        // Metadata response has correct resource
        let resp = h
            .build_metadata_response(
                "/api/v1/.well-known/oauth-protected-resource",
                "GET",
                "https://test.com",
            )
            .unwrap();

        let body = get_body_json(&resp);
        assert_eq!(body["resource"], "https://test.com/api/v1");
    }
}