oauth_provider_rs/

types.rs

use crate::error::OAuthError;
use serde::{Deserialize, Serialize};
use serde_json::Value;

// --- AuthRequest カスタム serializer/deserializer --------------------------------------
fn serialize_scope<S>(scope: &Vec<String>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    let scope_str = scope.join(" ");
    serializer.serialize_str(&scope_str)
}

fn deserialize_scope<'de, D>(d: D) -> Result<Vec<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let s = String::deserialize(d)?; // "read write"
    Ok(s.split_whitespace() // ← 空白で分割
        .map(|s| s.to_owned())
        .collect())
}

fn serialize_scope_option<S>(scope: &Vec<String>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    if scope.is_empty() {
        serializer.serialize_none()
    } else {
        let scope_str = scope.join(" ");
        serializer.serialize_str(&scope_str)
    }
}

fn deserialize_scope_option<'de, D>(d: D) -> Result<Vec<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let s = Option::<String>::deserialize(d)?;
    match s {
        Some(s) if !s.is_empty() => Ok(s.split_whitespace()
            .map(|s| s.to_owned())
            .collect()),
        _ => Ok(Vec::new()),
    }
}

/// Parsed OAuth authorization request parameters
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AuthRequest {
    /// OAuth response type (e.g., "code" for authorization code flow)
    pub response_type: String,

    /// Client identifier for the OAuth client
    pub client_id: String,

    /// URL to redirect to after authorization
    pub redirect_uri: String,

    /// Array of requested permission scopes
    #[serde(
        serialize_with = "serialize_scope_option",
        deserialize_with = "deserialize_scope_option",
        default
    )]
    pub scope: Vec<String>,

    /// Client state value to be returned in the redirect
    pub state: Option<String>,

    /// PKCE code challenge (RFC 7636)
    pub code_challenge: Option<String>,

    /// PKCE code challenge method (plain or S256)
    pub code_challenge_method: Option<String>,
}

/// OAuth client registration information
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ClientInfo {
    /// Unique identifier for the client
    pub client_id: String,

    /// Secret used to authenticate the client (stored as a hash)
    /// Only present for confidential clients; None for public clients.
    pub client_secret: Option<String>,

    /// List of allowed redirect URIs for the client
    pub redirect_uris: Vec<String>,

    /// Human-readable name of the client application
    pub client_name: Option<String>,

    /// URL to the client's logo
    pub logo_uri: Option<String>,

    /// URL to the client's homepage
    pub client_uri: Option<String>,

    /// URL to the client's privacy policy
    pub policy_uri: Option<String>,

    /// URL to the client's terms of service
    pub tos_uri: Option<String>,

    /// URL to the client's JSON Web Key Set for validating signatures
    pub jwks_uri: Option<String>,

    /// List of email addresses for contacting the client developers
    pub contacts: Option<Vec<String>>,

    /// List of grant types the client supports
    pub grant_types: Option<Vec<String>>,

    /// List of response types the client supports
    pub response_types: Option<Vec<String>>,

    /// Unix timestamp when the client was registered
    pub registration_date: Option<i64>,

    /// The authentication method used by the client at the token endpoint.
    /// Values include:
    /// - 'client_secret_basic': Uses HTTP Basic Auth with client ID and secret (default for confidential clients)
    /// - 'client_secret_post': Uses POST parameters for client authentication
    /// - 'none': Used for public clients that can't securely store secrets (SPAs, mobile apps, etc.)
    ///
    /// Public clients use 'none', while confidential clients use either 'client_secret_basic' or 'client_secret_post'.
    pub token_endpoint_auth_method: String,
}

/// Options for completing an authorization request
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CompleteAuthorizationOptions {
    /// The original parsed authorization request
    pub request: AuthRequest,

    /// Identifier for the user granting the authorization
    pub user_id: String,

    /// Application-specific metadata to associate with this grant
    pub metadata: Value,

    /// List of scopes that were actually granted (may differ from requested scopes)
    pub scope: Vec<String>,

    /// Application-specific properties to include with API requests
    /// authorized by this grant
    pub props: Value,
}

/// Authorization grant record
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Grant {
    /// Unique identifier for the grant
    pub id: String,

    /// Client that received this grant
    pub client_id: String,

    /// User who authorized this grant
    pub user_id: String,

    /// List of scopes that were granted
    pub scope: Vec<String>,

    /// Application-specific metadata associated with this grant
    pub metadata: Value,

    /// Encrypted application-specific properties
    pub encrypted_props: String,

    /// Unix timestamp when the grant was created
    pub created_at: i64,

    /// The hash of the current refresh token associated with this grant
    pub refresh_token_id: Option<String>,

    /// Wrapped encryption key for the current refresh token
    pub refresh_token_wrapped_key: Option<String>,

    /// The hash of the previous refresh token associated with this grant
    /// This token is still valid until the new token is first used
    pub previous_refresh_token_id: Option<String>,

    /// Wrapped encryption key for the previous refresh token
    pub previous_refresh_token_wrapped_key: Option<String>,

    /// The hash of the authorization code associated with this grant
    /// Only present during the authorization code exchange process
    pub auth_code_id: Option<String>,

    /// Wrapped encryption key for the authorization code
    /// Only present during the authorization code exchange process
    pub auth_code_wrapped_key: Option<String>,

    /// PKCE code challenge for this authorization
    /// Only present during the authorization code exchange process
    pub code_challenge: Option<String>,

    /// PKCE code challenge method (plain or S256)
    /// Only present during the authorization code exchange process
    pub code_challenge_method: Option<String>,
}

/// Token record stored in storage
/// Note: The actual token format is "{userId}:{grantId}:{random-secret}"
/// but we only store the hash of the full token string.
/// This contains only access tokens; refresh tokens are stored within the grant records.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Token {
    /// Unique identifier for the token (hash of the actual token)
    pub id: String,

    /// Identifier of the grant this token is associated with
    pub grant_id: String,

    /// User ID associated with this token
    pub user_id: String,

    /// Unix timestamp when the token was created
    pub created_at: i64,

    /// Unix timestamp when the token expires
    pub expires_at: i64,

    /// The encryption key for props, wrapped with this token
    pub wrapped_encryption_key: String,

    /// Denormalized grant information for faster access
    pub grant: TokenGrant,
}

/// Denormalized grant information stored within a token
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TokenGrant {
    /// Client that received this grant
    pub client_id: String,

    /// List of scopes that were granted
    pub scope: Vec<String>,

    /// Encrypted application-specific properties
    pub encrypted_props: String,
}

/// Options for listing operations that support pagination
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OAuthListOptions {
    /// Maximum number of items to return (max 1000)
    pub limit: Option<usize>,

    /// Cursor for pagination (from a previous listing operation)
    pub cursor: Option<String>,
}

/// Result of a listing operation with pagination support
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OAuthListResult<T> {
    /// The list of items
    pub items: Vec<T>,

    /// Cursor to get the next page of results, if there are more results
    pub cursor: Option<String>,
}

/// Public representation of a grant, with sensitive data removed
/// Used for list operations where the complete grant data isn't needed
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GrantSummary {
    /// Unique identifier for the grant
    pub id: String,

    /// Client that received this grant
    pub client_id: String,

    /// User who authorized this grant
    pub user_id: String,

    /// List of scopes that were granted
    pub scope: Vec<String>,

    /// Application-specific metadata associated with this grant
    pub metadata: Value,

    /// Unix timestamp when the grant was created
    pub created_at: i64,
}

/// Result of a token exchange callback function.
/// Allows updating the props stored in both the access token and the grant.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TokenExchangeCallbackResult {
    /// New props to be stored specifically with the access token.
    /// If not provided but new_props is, the access token will use new_props.
    /// If neither is provided, the original props will be used.
    pub access_token_props: Option<Value>,

    /// New props to replace the props stored in the grant itself.
    /// These props will be used for all future token refreshes.
    /// If access_token_props is not provided, these props will also be used for the current access token.
    /// If not provided, the original props will be used.
    pub new_props: Option<Value>,

    /// Override the default access token TTL (time-to-live) for this specific token.
    /// This is especially useful when the application is also an OAuth client to another service
    /// and wants to match its access token TTL to the upstream access token TTL.
    /// Value should be in seconds.
    pub access_token_ttl: Option<u64>,
}

/// Options for token exchange callback functions
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TokenExchangeCallbackOptions {
    /// The type of grant being processed.
    /// 'authorization_code' for initial code exchange,
    /// 'refresh_token' for refresh token exchange.
    pub grant_type: GrantType,

    /// Client that received this grant
    pub client_id: String,

    /// User who authorized this grant
    pub user_id: String,

    /// List of scopes that were granted
    pub scope: Vec<String>,

    /// Application-specific properties currently associated with this grant
    pub props: Value,
}

/// OAuth grant types
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum GrantType {
    #[serde(rename = "authorization_code")]
    AuthorizationCode,
    #[serde(rename = "refresh_token")]
    RefreshToken,
}

/// PKCE code challenge methods
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum CodeChallengeMethod {
    #[serde(rename = "plain")]
    Plain,
    #[serde(rename = "S256")]
    S256,
}

/// Storage key types for different OAuth entities
#[derive(Debug, Clone)]
pub enum StorageKey {
    Client(String),
    Grant(String),
    Token(String),
    AuthCode(String),
    RefreshToken(String),
}

impl StorageKey {
    pub fn as_str(&self) -> String {
        match self {
            StorageKey::Client(id) => format!("client:{}", id),
            StorageKey::Grant(id) => format!("grant:{}", id),
            StorageKey::Token(id) => format!("token:{}", id),
            StorageKey::AuthCode(id) => format!("auth_code:{}", id),
            StorageKey::RefreshToken(id) => format!("refresh_token:{}", id),
        }
    }
}

/// User context for authenticated requests
/// Contains information about the authenticated user extracted from a valid OAuth token
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UserContext {
    /// The user ID extracted from the token
    pub user_id: String,
    /// The client ID that received this token
    pub client_id: String,
    /// List of scopes granted to this token
    pub scope: Vec<String>,
    /// Application-specific properties associated with this token
    pub props: Value,
}

impl UserContext {
    /// Check if the user has a specific scope
    pub fn has_scope(&self, scope: &str) -> bool {
        self.scope.contains(&scope.to_string())
    }

    /// Check if the user has any of the specified scopes
    pub fn has_any_scope(&self, scopes: &[&str]) -> bool {
        scopes.iter().any(|scope| self.has_scope(scope))
    }

    /// Check if the user has all of the specified scopes
    pub fn has_all_scopes(&self, scopes: &[&str]) -> bool {
        scopes.iter().all(|scope| self.has_scope(scope))
    }

    /// Get a property from the user props
    pub fn get_prop<T>(&self, key: &str) -> Option<T>
    where
        T: serde::de::DeserializeOwned,
    {
        self.props
            .get(key)
            .and_then(|v| serde_json::from_value(v.clone()).ok())
    }

    /// Require a specific scope, returning an error if not present
    pub fn require_scope(&self, scope: &str) -> Result<(), OAuthError> {
        if self.has_scope(scope) {
            Ok(())
        } else {
            Err(OAuthError::insufficient_scope(format!(
                "Required scope '{}' not found",
                scope
            )))
        }
    }

    /// Require any of the specified scopes, returning an error if none are present
    pub fn require_any_scope(&self, scopes: &[&str]) -> Result<(), OAuthError> {
        if self.has_any_scope(scopes) {
            Ok(())
        } else {
            Err(OAuthError::insufficient_scope(format!(
                "Required one of scopes: {:?}",
                scopes
            )))
        }
    }
}