Skip to main content

hyprstream_core/services/oauth/
user_mapping.rs

1//! User identity mapping from external OIDC providers to local hyprstream subjects.
2
3use anyhow::{anyhow, Result};
4
5use crate::config::{ProvisioningMode, UserMappingStrategy};
6
7/// Map an external OIDC identity to a local hyprstream subject.
8///
9/// The returned string becomes the `sub` claim in the hyprstream-issued JWT.
10/// Casbin policies grant permissions to this mapped subject.
11pub fn map_external_identity(
12    provider_slug: &str,
13    external_claims: &serde_json::Value,
14    strategy: &UserMappingStrategy,
15    _local_issuer_url: &str,
16) -> Result<String> {
17    match strategy {
18        UserMappingStrategy::Namespaced => {
19            let sub = external_claims["sub"]
20                .as_str()
21                .ok_or_else(|| anyhow!("External id_token missing 'sub' claim"))?;
22            Ok(format!("{provider_slug}:{sub}"))
23        }
24        UserMappingStrategy::Email => {
25            let email = external_claims["email"]
26                .as_str()
27                .ok_or_else(|| anyhow!("External id_token missing 'email' claim"))?;
28            let verified = external_claims["email_verified"].as_bool().unwrap_or(false);
29            if !verified {
30                return Err(anyhow!(
31                    "Email '{}' is not verified by the external provider (email_verified=false)",
32                    email
33                ));
34            }
35            Ok(email.to_owned())
36        }
37        UserMappingStrategy::Claim { name } => {
38            let val = external_claims[name]
39                .as_str()
40                .ok_or_else(|| anyhow!("External id_token missing '{}' claim", name))?;
41            Ok(val.to_owned())
42        }
43        UserMappingStrategy::DidWeb => Err(anyhow!(
44            "did:web path-form account minting is disabled: the atproto profile requires host-form account DIDs (#1159)"
45        )),
46    }
47}
48
49/// Map a verified Federate ATProto claim set to its enrolled owner DID.
50///
51/// `expected_issuer` and `expected_owner_did` must come from trusted server
52/// configuration and the server-side enrollment profile, respectively. They
53/// must never be populated from callback parameters or browser state. This
54/// helper validates the issuer, Federate connector, and both DID values before
55/// requiring the signed claim to match the enrolled owner exactly.
56pub fn map_federate_atproto_owner(
57    external_claims: &serde_json::Value,
58    expected_issuer: &str,
59    expected_owner_did: &str,
60) -> Result<String> {
61    if expected_issuer != super::federate_source::ISSUER {
62        return Err(anyhow!("Federate expected issuer is not the pinned issuer"));
63    }
64
65    let issuer = external_claims["iss"]
66        .as_str()
67        .ok_or_else(|| anyhow!("Federate id_token missing 'iss' claim"))?;
68    if issuer != expected_issuer {
69        return Err(anyhow!("Federate id_token issuer mismatch"));
70    }
71
72    let connector = external_claims["federated_claims"]["connector_id"]
73        .as_str()
74        .ok_or_else(|| anyhow!("Federate id_token missing connector_id"))?;
75    if connector != "atproto" {
76        return Err(anyhow!("Federate connector is not 'atproto'"));
77    }
78
79    let claimed_owner = super::federate_source::atproto_account_did(external_claims, "atproto")
80        .map_err(|error| anyhow!("Federate ATProto user_id is not a valid owner DID: {error}"))?;
81    validate_federate_owner_repo_authority(&claimed_owner).map_err(|error| {
82        anyhow!("Federate ATProto user_id is not an accepted owner DID: {error}")
83    })?;
84    let expected_owner_claims = serde_json::json!({
85        "federated_claims": {
86            "connector_id": "atproto",
87            "user_id": expected_owner_did
88        }
89    });
90    let expected_owner =
91        super::federate_source::atproto_account_did(&expected_owner_claims, "atproto")
92            .map_err(|error| anyhow!("server-enrolled owner DID is invalid: {error}"))?;
93    validate_federate_owner_repo_authority(&expected_owner)
94        .map_err(|error| anyhow!("server-enrolled owner DID is invalid: {error}"))?;
95
96    if claimed_owner != expected_owner {
97        return Err(anyhow!(
98            "Federate ATProto owner DID does not match the enrolled owner"
99        ));
100    }
101
102    Ok(expected_owner)
103}
104
105fn validate_federate_owner_repo_authority(did: &str) -> Result<()> {
106    match hyprstream_pds::repo_authority::accept_repo_authority(did)
107        .map_err(|error| anyhow!("DID is not a valid repo authority: {error}"))?
108    {
109        hyprstream_pds::repo_authority::RepoAuthority::Web
110        | hyprstream_pds::repo_authority::RepoAuthority::Plc => Ok(()),
111        hyprstream_pds::repo_authority::RepoAuthority::At9p => Err(anyhow!(
112            "did:at9p is not a Federate ATProto connector identity"
113        )),
114    }
115}
116
117/// Check if a user should be provisioned based on the provisioning mode.
118///
119/// Returns `Ok(true)` if the user should be auto-provisioned.
120/// Returns `Ok(false)` if the user must already exist.
121/// Returns `Err` if the user is denied by the allowlist.
122pub fn should_provision(
123    mode: &ProvisioningMode,
124    mapped_subject: &str,
125    allowed_domains: &[String],
126) -> Result<bool> {
127    match mode {
128        ProvisioningMode::Deny => Ok(false),
129        ProvisioningMode::Auto => Ok(true),
130        ProvisioningMode::Allowlist => {
131            // Check if the subject matches any allowed domain.
132            // For email-based subjects: check the domain part.
133            // For namespaced subjects: check the provider slug.
134            let domain = mapped_subject
135                .rsplit_once('@')
136                .map(|(_, d)| d)
137                .or_else(|| mapped_subject.split_once(':').map(|(p, _)| p));
138
139            if let Some(domain) = domain {
140                if allowed_domains.iter().any(|d| d == domain) {
141                    return Ok(true);
142                }
143            }
144
145            Err(anyhow!(
146                "User '{}' is not in the allowed domains: {:?}",
147                mapped_subject,
148                allowed_domains
149            ))
150        }
151    }
152}
153
154#[cfg(test)]
155#[allow(clippy::unwrap_used)]
156mod tests {
157    use super::*;
158
159    #[test]
160    fn test_namespaced_mapping() {
161        let claims = serde_json::json!({"sub": "12345", "email": "alice@example.com"});
162        let result =
163            map_external_identity("keycloak", &claims, &UserMappingStrategy::Namespaced, "")
164                .unwrap();
165        assert_eq!(result, "keycloak:12345");
166    }
167
168    #[test]
169    fn test_email_mapping_verified() {
170        let claims =
171            serde_json::json!({"sub": "12345", "email": "alice@corp.com", "email_verified": true});
172        let result =
173            map_external_identity("google", &claims, &UserMappingStrategy::Email, "").unwrap();
174        assert_eq!(result, "alice@corp.com");
175    }
176
177    #[test]
178    fn test_email_mapping_unverified_fails() {
179        let claims =
180            serde_json::json!({"sub": "12345", "email": "alice@corp.com", "email_verified": false});
181        let result = map_external_identity("google", &claims, &UserMappingStrategy::Email, "");
182        assert!(result.is_err());
183    }
184
185    #[test]
186    fn test_claim_mapping() {
187        let claims = serde_json::json!({"sub": "12345", "preferred_username": "alice"});
188        let strategy = UserMappingStrategy::Claim {
189            name: "preferred_username".into(),
190        };
191        let result = map_external_identity("dex", &claims, &strategy, "").unwrap();
192        assert_eq!(result, "alice");
193    }
194
195    #[test]
196    fn federate_atproto_owner_mapping_accepts_matching_enrolled_did() {
197        let owner = "did:plc:abcdefghijklmnopqrstuvwx";
198        let claims = serde_json::json!({
199            "iss": "https://login.federate.to",
200            "sub": "opaque-federate-subject",
201            "federated_claims": {
202                "connector_id": "atproto",
203                "user_id": owner
204            }
205        });
206
207        assert_eq!(
208            map_federate_atproto_owner(&claims, "https://login.federate.to", owner).unwrap(),
209            owner
210        );
211    }
212
213    #[test]
214    fn federate_atproto_owner_mapping_accepts_valid_host_form_did_web() {
215        let owner = "did:web:alice.example.com";
216        let claims = serde_json::json!({
217            "iss": "https://login.federate.to",
218            "federated_claims": {
219                "connector_id": "atproto",
220                "user_id": owner
221            }
222        });
223
224        assert_eq!(
225            map_federate_atproto_owner(&claims, "https://login.federate.to", owner).unwrap(),
226            owner
227        );
228    }
229
230    #[test]
231    fn federate_atproto_owner_mapping_rejects_wrong_issuer() {
232        let claims = serde_json::json!({
233            "iss": "https://attacker.example",
234            "federated_claims": {
235                "connector_id": "atproto",
236                "user_id": "did:plc:abcdefghijklmnopqrstuvwx"
237            }
238        });
239
240        assert!(map_federate_atproto_owner(
241            &claims,
242            "https://login.federate.to",
243            "did:plc:abcdefghijklmnopqrstuvwx"
244        )
245        .unwrap_err()
246        .to_string()
247        .contains("issuer mismatch"));
248    }
249
250    #[test]
251    fn federate_atproto_owner_mapping_rejects_attacker_issuer_even_when_configured() {
252        let attacker_issuer = "https://attacker.example";
253        let claims = serde_json::json!({
254            "iss": attacker_issuer,
255            "federated_claims": {
256                "connector_id": "atproto",
257                "user_id": "did:plc:abcdefghijklmnopqrstuvwx"
258            }
259        });
260
261        assert!(map_federate_atproto_owner(
262            &claims,
263            attacker_issuer,
264            "did:plc:abcdefghijklmnopqrstuvwx"
265        )
266        .unwrap_err()
267        .to_string()
268        .contains("pinned issuer"));
269    }
270
271    #[test]
272    fn federate_atproto_owner_mapping_rejects_wrong_connector() {
273        let claims = serde_json::json!({
274            "iss": "https://login.federate.to",
275            "federated_claims": {
276                "connector_id": "github",
277                "user_id": "did:plc:abcdefghijklmnopqrstuvwx"
278            }
279        });
280
281        assert!(map_federate_atproto_owner(
282            &claims,
283            "https://login.federate.to",
284            "did:plc:abcdefghijklmnopqrstuvwx"
285        )
286        .unwrap_err()
287        .to_string()
288        .contains("connector"));
289    }
290
291    #[test]
292    fn federate_atproto_owner_mapping_rejects_invalid_did() {
293        let claims = serde_json::json!({
294            "iss": "https://login.federate.to",
295            "federated_claims": {
296                "connector_id": "atproto",
297                "user_id": "did:plc:short"
298            }
299        });
300
301        assert!(map_federate_atproto_owner(
302            &claims,
303            "https://login.federate.to",
304            "did:plc:abcdefghijklmnopqrstuvwx"
305        )
306        .unwrap_err()
307        .to_string()
308        .contains("valid owner DID"));
309    }
310
311    #[test]
312    fn federate_atproto_owner_mapping_rejects_malformed_web_hosts() {
313        for owner in [
314            "did:web:example..com",
315            "did:web:-example.com",
316            "did:web:example-.com",
317        ] {
318            let claims = serde_json::json!({
319                "iss": "https://login.federate.to",
320                "federated_claims": {
321                    "connector_id": "atproto",
322                    "user_id": owner
323                }
324            });
325
326            assert!(
327                map_federate_atproto_owner(
328                    &claims,
329                    "https://login.federate.to",
330                    "did:plc:abcdefghijklmnopqrstuvwx"
331                )
332                .unwrap_err()
333                .to_string()
334                .contains("accepted owner DID"),
335                "{owner}"
336            );
337        }
338    }
339
340    #[test]
341    fn federate_atproto_owner_mapping_rejects_malformed_enrolled_web_host() {
342        let claims = serde_json::json!({
343            "iss": "https://login.federate.to",
344            "federated_claims": {
345                "connector_id": "atproto",
346                "user_id": "did:web:alice.example.com"
347            }
348        });
349
350        assert!(map_federate_atproto_owner(
351            &claims,
352            "https://login.federate.to",
353            "did:web:example..com"
354        )
355        .unwrap_err()
356        .to_string()
357        .contains("server-enrolled owner DID is invalid"));
358    }
359
360    #[test]
361    fn federate_atproto_owner_mapping_rejects_malformed_web_percent_encoding() {
362        let claims = serde_json::json!({
363            "iss": "https://login.federate.to",
364            "federated_claims": {
365                "connector_id": "atproto",
366                "user_id": "did:web:example%2G.test"
367            }
368        });
369
370        assert!(map_federate_atproto_owner(
371            &claims,
372            "https://login.federate.to",
373            "did:plc:abcdefghijklmnopqrstuvwx"
374        )
375        .unwrap_err()
376        .to_string()
377        .contains("valid owner DID"));
378    }
379
380    #[test]
381    fn federate_atproto_owner_mapping_rejects_non_ascii_did() {
382        let claims = serde_json::json!({
383            "iss": "https://login.federate.to",
384            "federated_claims": {
385                "connector_id": "atproto",
386                "user_id": "did:web:exämple.test"
387            }
388        });
389
390        assert!(map_federate_atproto_owner(
391            &claims,
392            "https://login.federate.to",
393            "did:plc:abcdefghijklmnopqrstuvwx"
394        )
395        .unwrap_err()
396        .to_string()
397        .contains("valid owner DID"));
398    }
399
400    #[test]
401    fn federate_atproto_owner_mapping_rejects_non_enrolled_owner() {
402        let claims = serde_json::json!({
403            "iss": "https://login.federate.to",
404            "federated_claims": {
405                "connector_id": "atproto",
406                "user_id": "did:plc:bcdefghijklmnopqrstuvwxy"
407            }
408        });
409
410        assert!(map_federate_atproto_owner(
411            &claims,
412            "https://login.federate.to",
413            "did:plc:abcdefghijklmnopqrstuvwx"
414        )
415        .unwrap_err()
416        .to_string()
417        .contains("does not match"));
418    }
419
420    #[test]
421    fn federate_atproto_owner_mapping_rejects_invalid_server_enrollment() {
422        let owner = "did:plc:abcdefghijklmnopqrstuvwx";
423        let claims = serde_json::json!({
424            "iss": "https://login.federate.to",
425            "federated_claims": {
426                "connector_id": "atproto",
427                "user_id": owner
428            }
429        });
430
431        assert!(map_federate_atproto_owner(
432            &claims,
433            "https://login.federate.to",
434            "owner-from-browser"
435        )
436        .unwrap_err()
437        .to_string()
438        .contains("server-enrolled owner DID is invalid"));
439    }
440
441    #[test]
442    fn test_didweb_mapping_is_a_hard_error() {
443        let claims = serde_json::json!({"sub": "alice"});
444        let err = map_external_identity(
445            "keycloak",
446            &claims,
447            &UserMappingStrategy::DidWeb,
448            "https://hyprstream.example.com",
449        )
450        .unwrap_err();
451        assert!(err
452            .to_string()
453            .contains("path-form account minting is disabled"));
454    }
455
456    #[test]
457    fn test_provisioning_deny() {
458        assert!(!should_provision(&ProvisioningMode::Deny, "keycloak:123", &[]).unwrap());
459    }
460
461    #[test]
462    fn test_provisioning_auto() {
463        assert!(should_provision(&ProvisioningMode::Auto, "keycloak:123", &[]).unwrap());
464    }
465
466    #[test]
467    fn test_provisioning_allowlist_email() {
468        assert!(should_provision(
469            &ProvisioningMode::Allowlist,
470            "alice@corp.com",
471            &["corp.com".into()],
472        )
473        .unwrap());
474    }
475
476    #[test]
477    fn test_provisioning_allowlist_denied() {
478        let result = should_provision(
479            &ProvisioningMode::Allowlist,
480            "alice@other.com",
481            &["corp.com".into()],
482        );
483        assert!(result.is_err());
484    }
485}