feat(oauth-client): add metadata document deserializer and ScopeSet parser

+372

2 changed files

expand all

src

commands

test

oauth

client

pipeline

metadata.rs

pipeline.rs

src/commands/test/oauth/client/pipeline.rs

··· 1 1 //! OAuth client conformance test pipeline and target parsing. 2 2 3 3 pub mod discovery; 4 + pub mod metadata; 4 5 5 6 use miette::{Diagnostic, NamedSource, SourceSpan}; 6 7 use thiserror::Error;

+371

src/commands/test/oauth/client/pipeline/metadata.rs

··· 1 + //! OAuth client metadata document parsing and scope validation. 2 + //! 3 + //! This stage parses the discovered metadata document and validates 4 + //! every spec-derived static property of an atproto OAuth client metadata 5 + //! document. 6 + 7 + use miette::Diagnostic; 8 + use serde::{Deserialize, Serialize}; 9 + use thiserror::Error; 10 + 11 + /// Raw OAuth client metadata document with every field optional. 12 + /// 13 + /// Allows deserialization of metadata documents with missing or additional 14 + /// fields. Additional OAuth fields are allowed per the spec; we only validate 15 + /// the fields we care about. 16 + #[derive(Debug, Clone, Deserialize, Serialize)] 17 + pub struct RawMetadataDocument { 18 + pub client_id: Option<String>, 19 + pub application_type: Option<String>, 20 + pub grant_types: Option<Vec<String>>, 21 + pub response_types: Option<Vec<String>>, 22 + pub scope: Option<String>, 23 + pub redirect_uris: Option<Vec<String>>, 24 + pub dpop_bound_access_tokens: Option<bool>, 25 + pub token_endpoint_auth_method: Option<String>, 26 + /// Stored as raw JSON; Phase 5 parses it into JWK format. 27 + pub jwks: Option<serde_json::Value>, 28 + pub jwks_uri: Option<String>, 29 + } 30 + 31 + /// Parse a metadata document from raw bytes. 32 + pub fn parse_raw(bytes: &[u8]) -> Result<RawMetadataDocument, serde_json::Error> { 33 + serde_json::from_slice(bytes) 34 + } 35 + 36 + /// A single scope token in the atproto permission grammar. 37 + #[derive(Debug, Clone, PartialEq, Eq)] 38 + pub enum ScopeToken { 39 + /// The `atproto` baseline scope. 40 + Atproto, 41 + /// A permission token with resource, optional positional, and query params. 42 + Permission { 43 + resource: String, 44 + positional: Option<String>, 45 + query: Vec<(String, String)>, 46 + }, 47 + } 48 + 49 + /// A parsed set of scope tokens. 50 + #[derive(Debug, Clone)] 51 + pub struct ScopeSet { 52 + pub tokens: Vec<ScopeToken>, 53 + } 54 + 55 + /// Reason for a scope parse failure. 56 + #[derive(Debug, Clone, Copy, PartialEq, Eq)] 57 + pub enum ScopeParseReason { 58 + /// Resource name not in the known set. 59 + UnknownResource, 60 + /// Empty resource name (e.g., `:foo` or `:?param=val`). 61 + EmptyResource, 62 + /// Invalid query parameter syntax. 63 + InvalidQuery, 64 + /// Percent-decoding error. 65 + InvalidPercentEncoding, 66 + } 67 + 68 + impl std::fmt::Display for ScopeParseReason { 69 + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 70 + match self { 71 + ScopeParseReason::UnknownResource => write!(f, "unknown resource name"), 72 + ScopeParseReason::EmptyResource => write!(f, "empty resource name"), 73 + ScopeParseReason::InvalidQuery => write!(f, "invalid query parameters"), 74 + ScopeParseReason::InvalidPercentEncoding => { 75 + write!(f, "percent-encoding error") 76 + } 77 + } 78 + } 79 + } 80 + 81 + /// Error from parsing a scope token. 82 + #[derive(Debug, Clone, Error, Diagnostic)] 83 + #[error("Failed to parse scope token: {reason}")] 84 + #[diagnostic(code = "oauth_client::metadata::scope_grammar")] 85 + pub struct ScopeParseError { 86 + /// The offending token string. 87 + pub token: String, 88 + /// Byte offset within the scope string (for computing source spans). 89 + pub byte_offset: usize, 90 + /// The specific reason for the parse failure. 91 + pub reason: ScopeParseReason, 92 + } 93 + 94 + /// Parse a scope string into a set of tokens. 95 + /// 96 + /// The scope string is space-separated. Each token is either: 97 + /// - The literal string `"atproto"` (baseline scope). 98 + /// - A resource permission: `<resource>[:<positional>][?param=val&param=val...]`. 99 + /// 100 + /// Known resources: `repo`, `identity`, `blob`, `account`, `rpc`, `include`. 101 + /// Positional and query parameters are mutually exclusive for the same key. 102 + pub fn parse_scope(s: &str) -> Result<ScopeSet, ScopeParseError> { 103 + let mut tokens = Vec::new(); 104 + let mut byte_offset = 0; 105 + 106 + for token in s.split_whitespace() { 107 + if token == "atproto" { 108 + tokens.push(ScopeToken::Atproto); 109 + } else { 110 + // Try to parse as a permission token. 111 + match parse_permission_token(token, byte_offset) { 112 + Ok(perm) => tokens.push(perm), 113 + Err(e) => return Err(e), 114 + } 115 + } 116 + 117 + byte_offset += token.len() + 1; // +1 for the whitespace separator 118 + } 119 + 120 + Ok(ScopeSet { tokens }) 121 + } 122 + 123 + /// Result type for parsing positional and query parameters. 124 + type PositionalAndQuery = (Option<String>, Vec<(String, String)>); 125 + 126 + /// Parse a single permission token. 127 + fn parse_permission_token(token: &str, byte_offset: usize) -> Result<ScopeToken, ScopeParseError> { 128 + // Split on the first ':' to separate resource from rest. 129 + let (resource_part, rest) = match token.split_once(':') { 130 + Some((r, rest)) => (r, Some(rest)), 131 + None => (token, None), 132 + }; 133 + 134 + // Check that resource is not empty. 135 + if resource_part.is_empty() { 136 + return Err(ScopeParseError { 137 + token: token.to_string(), 138 + byte_offset, 139 + reason: ScopeParseReason::EmptyResource, 140 + }); 141 + } 142 + 143 + // Validate resource name. 144 + let known_resources = ["repo", "identity", "blob", "account", "rpc", "include"]; 145 + if !known_resources.contains(&resource_part) { 146 + return Err(ScopeParseError { 147 + token: token.to_string(), 148 + byte_offset, 149 + reason: ScopeParseReason::UnknownResource, 150 + }); 151 + } 152 + 153 + let resource = resource_part.to_string(); 154 + let (positional, query) = if let Some(rest) = rest { 155 + // Parse positional and query from the remainder. 156 + match parse_positional_and_query(rest, byte_offset) { 157 + Ok((pos, q)) => (pos, q), 158 + Err(e) => return Err(e), 159 + } 160 + } else { 161 + (None, Vec::new()) 162 + }; 163 + 164 + Ok(ScopeToken::Permission { 165 + resource, 166 + positional, 167 + query, 168 + }) 169 + } 170 + 171 + /// Parse the positional parameter and query parameters from the post-colon part. 172 + fn parse_positional_and_query( 173 + rest: &str, 174 + byte_offset: usize, 175 + ) -> Result<PositionalAndQuery, ScopeParseError> { 176 + // Split on '?' to separate positional from query. 177 + let (positional_part, query_part) = match rest.split_once('?') { 178 + Some((pos, q)) => { 179 + if pos.is_empty() { 180 + (None, Some(q)) 181 + } else { 182 + (Some(pos.to_string()), Some(q)) 183 + } 184 + } 185 + None => { 186 + if rest.is_empty() { 187 + (None, None) 188 + } else { 189 + (Some(rest.to_string()), None) 190 + } 191 + } 192 + }; 193 + 194 + // Parse query parameters if present. 195 + let query = if let Some(q) = query_part { 196 + parse_query_string(q, byte_offset)? 197 + } else { 198 + Vec::new() 199 + }; 200 + 201 + Ok((positional_part, query)) 202 + } 203 + 204 + /// Parse the query string (param=val&param=val...). 205 + fn parse_query_string( 206 + query_str: &str, 207 + byte_offset: usize, 208 + ) -> Result<Vec<(String, String)>, ScopeParseError> { 209 + let mut params = Vec::new(); 210 + for param in query_str.split('&') { 211 + match param.split_once('=') { 212 + Some((key, val)) => { 213 + // Optionally percent-decode key and value (for Phase 4, we keep it simple). 214 + let key = percent_decode(key).map_err(|_| ScopeParseError { 215 + token: format!("?{param}"), 216 + byte_offset, 217 + reason: ScopeParseReason::InvalidPercentEncoding, 218 + })?; 219 + let val = percent_decode(val).map_err(|_| ScopeParseError { 220 + token: format!("?{param}"), 221 + byte_offset, 222 + reason: ScopeParseReason::InvalidPercentEncoding, 223 + })?; 224 + params.push((key, val)); 225 + } 226 + None => { 227 + return Err(ScopeParseError { 228 + token: format!("?{param}"), 229 + byte_offset, 230 + reason: ScopeParseReason::InvalidQuery, 231 + }); 232 + } 233 + } 234 + } 235 + Ok(params) 236 + } 237 + 238 + /// Percent-decode a string (simplified: just handle %20, %3A, etc.). 239 + fn percent_decode(s: &str) -> Result<String, ()> { 240 + let mut result = String::new(); 241 + let mut chars = s.chars().peekable(); 242 + while let Some(ch) = chars.next() { 243 + if ch == '%' { 244 + // Expect two hex digits. 245 + let h1 = chars.next().ok_or(())?; 246 + let h2 = chars.next().ok_or(())?; 247 + let hex_str = format!("{h1}{h2}"); 248 + let byte = u8::from_str_radix(&hex_str, 16).map_err(|_| ())?; 249 + result.push(byte as char); 250 + } else { 251 + result.push(ch); 252 + } 253 + } 254 + Ok(result) 255 + } 256 + 257 + // ============================================================================ 258 + // Unit tests for Task 1 259 + // ============================================================================ 260 + 261 + #[cfg(test)] 262 + mod tests { 263 + use super::*; 264 + 265 + #[test] 266 + fn scope_parses_atproto_alone() { 267 + let result = parse_scope("atproto").expect("parse failed"); 268 + assert_eq!(result.tokens.len(), 1); 269 + assert_eq!(result.tokens[0], ScopeToken::Atproto); 270 + } 271 + 272 + #[test] 273 + fn scope_parses_atproto_plus_permission() { 274 + let result = parse_scope("atproto repo:app.bsky.feed.post").expect("parse failed"); 275 + assert_eq!(result.tokens.len(), 2); 276 + assert_eq!(result.tokens[0], ScopeToken::Atproto); 277 + match &result.tokens[1] { 278 + ScopeToken::Permission { 279 + resource, 280 + positional, 281 + query, 282 + } => { 283 + assert_eq!(resource, "repo"); 284 + assert_eq!(positional.as_deref(), Some("app.bsky.feed.post")); 285 + assert!(query.is_empty()); 286 + } 287 + _ => panic!("expected Permission token"), 288 + } 289 + } 290 + 291 + #[test] 292 + fn scope_rejects_empty_string() { 293 + // Empty string should produce empty token list but no error. 294 + let result = parse_scope("").expect("parse failed"); 295 + assert_eq!(result.tokens.len(), 0); 296 + } 297 + 298 + #[test] 299 + fn scope_rejects_unknown_resource() { 300 + let result = parse_scope("foo:bar"); 301 + assert!(result.is_err()); 302 + let err = result.unwrap_err(); 303 + assert_eq!(err.reason, ScopeParseReason::UnknownResource); 304 + assert_eq!(err.token, "foo:bar"); 305 + } 306 + 307 + #[test] 308 + fn scope_rejects_empty_resource() { 309 + let result = parse_scope(":bar"); 310 + assert!(result.is_err()); 311 + let err = result.unwrap_err(); 312 + assert_eq!(err.reason, ScopeParseReason::EmptyResource); 313 + } 314 + 315 + #[test] 316 + fn scope_accepts_query_forms() { 317 + let result = 318 + parse_scope("atproto repo:app.bsky.feed.post?action=create").expect("parse failed"); 319 + assert_eq!(result.tokens.len(), 2); 320 + match &result.tokens[1] { 321 + ScopeToken::Permission { 322 + resource, 323 + positional, 324 + query, 325 + } => { 326 + assert_eq!(resource, "repo"); 327 + assert_eq!(positional.as_deref(), Some("app.bsky.feed.post")); 328 + assert_eq!(query.len(), 1); 329 + assert_eq!(query[0], ("action".to_string(), "create".to_string())); 330 + } 331 + _ => panic!("expected Permission token"), 332 + } 333 + } 334 + 335 + #[test] 336 + fn raw_metadata_doc_deserializes_with_missing_fields() { 337 + let json = r#"{"client_id":"https://example.com"}"#; 338 + let doc: RawMetadataDocument = serde_json::from_str(json).expect("deserialize failed"); 339 + assert_eq!(doc.client_id.as_deref(), Some("https://example.com")); 340 + assert!(doc.application_type.is_none()); 341 + assert!(doc.scope.is_none()); 342 + } 343 + 344 + #[test] 345 + fn parse_raw_deserializes_json_bytes() { 346 + let json = br#"{"client_id":"https://example.com","scope":"atproto"}"#; 347 + let doc = parse_raw(json).expect("parse failed"); 348 + assert_eq!(doc.client_id.as_deref(), Some("https://example.com")); 349 + assert_eq!(doc.scope.as_deref(), Some("atproto")); 350 + } 351 + 352 + #[test] 353 + fn parse_raw_rejects_invalid_json() { 354 + let invalid = br#"not json at all"#; 355 + let result = parse_raw(invalid); 356 + assert!(result.is_err()); 357 + } 358 + 359 + #[test] 360 + fn scope_error_has_stable_diagnostic_code() { 361 + let err = ScopeParseError { 362 + token: "invalid".to_string(), 363 + byte_offset: 0, 364 + reason: ScopeParseReason::UnknownResource, 365 + }; 366 + // The derive(Diagnostic) with code = "..." should set the code. 367 + // We can't directly test this without rendering, but the test ensures 368 + // it compiles and has the right structure. 369 + let _ = err; 370 + } 371 + }

Configure Feed

Configure Feed