wacht 0.1.0-beta.5

Official Rust SDK for the Wacht platform, providing type-safe API client and authentication middleware
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

//! JWT authentication middleware for Axum web framework.
//!
//! This module provides middleware for validating JWT tokens and extracting
//! authentication context from requests.

#![cfg(feature = "axum")]

use axum::{
    Extension, body::Body, extract::Request, http::StatusCode, middleware::Next, response::Response,
};
use serde::{Deserialize, Serialize};

use crate::models::JwksDocument;

/// JWT token claims structure.
///
/// Contains standard JWT claims plus Wacht-specific claims for
/// session, organization, and workspace context.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TokenClaims {
    /// Token issuer (iss)
    pub iss: String,
    /// Subject - user ID (sub)
    pub sub: String,
    /// Issued at timestamp (iat)
    pub iat: i64,
    /// Expiration timestamp (exp)
    pub exp: i64,
    /// Session ID
    pub sid: String,
    /// Organization ID if user is in organization context
    #[serde(skip_serializing_if = "Option::is_none")]
    pub organization: Option<String>,
    /// Workspace ID if user is in workspace context
    #[serde(skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
    /// Permissions grouped by scope
    #[serde(skip_serializing_if = "Option::is_none")]
    pub permissions: Option<TokenPermissions>,
    /// Custom claims object
    #[serde(skip_serializing_if = "Option::is_none")]
    pub claims: Option<serde_json::Map<String, serde_json::Value>>,
    /// Metadata object
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
    /// Additional custom claims (flattened)
    #[serde(flatten)]
    pub custom_claims: serde_json::Map<String, serde_json::Value>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TokenPermissions {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub organization: Option<Vec<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub workspace: Option<Vec<String>>,
}

/// Authentication context extracted from JWT token.
///
/// This struct is inserted into the request extensions after successful
/// token validation and can be extracted in request handlers.
#[derive(Debug, Clone)]
pub struct AuthContext {
    /// User ID from token subject
    pub user_id: String,
    /// Session ID
    pub session_id: String,
    /// Organization ID if present
    pub organization_id: Option<String>,
    /// Workspace ID if present
    pub workspace_id: Option<String>,
    /// Permissions
    pub permissions: Option<TokenPermissions>,
    /// Full token claims
    pub claims: TokenClaims,
}

/// Configuration for JWT authentication.
#[derive(Clone)]
pub struct AuthConfig {
    /// Public key for token verification (PEM format)
    pub public_key: String,
    /// JWKS document for token verification
    pub public_jwks: Option<JwksDocument>,
    /// Allowed clock skew in seconds (default: 5)
    pub allowed_clock_skew: u64,
    /// Whether to validate token expiration (default: true)
    pub validate_exp: bool,
    /// Whether to validate not-before claim (default: true)
    pub validate_nbf: bool,
    /// Required issuer claim value
    pub required_issuer: Option<String>,
}

impl Default for AuthConfig {
    fn default() -> Self {
        Self {
            public_key: String::new(),
            public_jwks: None,
            allowed_clock_skew: 5,
            validate_exp: true,
            validate_nbf: true,
            required_issuer: None,
        }
    }
}

/// Extract authentication context from request extensions.
///
/// Use this in request handlers to access the authenticated user's context.
///
/// # Example
/// ```ignore
/// async fn handler(req: Request<Body>) -> Result<Response, StatusCode> {
///     let auth = extract_auth_context(&req)
///         .ok_or(StatusCode::UNAUTHORIZED)?;
///
///     println!("User ID: {}", auth.user_id);
///     // ... handle request
/// }
/// ```
pub fn extract_auth_context(req: &Request<Body>) -> Option<&AuthContext> {
    req.extensions().get::<AuthContext>()
}

/// Configuration for permission-based authorization middleware.
#[derive(Debug, Clone)]
pub struct RequirePermission {
    /// The permission string to check
    pub permission: String,
    /// The scope in which to check the permission
    pub scope: PermissionScope,
}

/// Scope for permission checking.
#[derive(Debug, Clone)]
pub enum PermissionScope {
    /// Check permission in organization context
    Organization,
    /// Check permission in workspace context
    Workspace,
}

impl RequirePermission {
    /// Create a permission requirement for organization scope.
    pub fn organization(permission: impl Into<String>) -> Self {
        Self {
            permission: permission.into(),
            scope: PermissionScope::Organization,
        }
    }

    /// Create a permission requirement for workspace scope.
    pub fn workspace(permission: impl Into<String>) -> Self {
        Self {
            permission: permission.into(),
            scope: PermissionScope::Workspace,
        }
    }
}

/// Middleware to check if authenticated user has required permission.
///
/// This middleware should be used after `auth_middleware` to check
/// specific permissions in organization or workspace context.
///
/// # Example
/// ```ignore
/// let app = Router::new()
///     .route("/admin", get(handler))
///     .route_layer(middleware::from_fn(auth_middleware))
///     .route_layer(middleware::from_fn(move |req, next| {
///         require_permission_middleware(
///             Extension(RequirePermission::organization("admin")),
///             req,
///             next
///         )
///     }));
/// ```
pub async fn require_permission_middleware(
    Extension(required): Extension<RequirePermission>,
    req: Request<Body>,
    next: Next,
) -> Result<Response, (StatusCode, String)> {
    let auth_context = req.extensions().get::<AuthContext>().ok_or_else(|| {
        (
            StatusCode::UNAUTHORIZED,
            "No auth context found".to_string(),
        )
    })?;

    let has_permission = if let Some(permissions) = &auth_context.permissions {
        match required.scope {
            PermissionScope::Organization => permissions
                .organization
                .as_ref()
                .map(|perms| perms.contains(&required.permission))
                .unwrap_or(false),
            PermissionScope::Workspace => permissions
                .workspace
                .as_ref()
                .map(|perms| perms.contains(&required.permission))
                .unwrap_or(false),
        }
    } else {
        false
    };

    if !has_permission {
        return Err((
            StatusCode::FORBIDDEN,
            format!("Missing required permission: {}", required.permission),
        ));
    }

    Ok(next.run(req).await)
}