Skip to main content

hyprstream_pds/
repo_authority.rs

1//! Which DID methods *our* PDS accepts as a **repo authority** — the account DID
2//! that owns a repository and signs its commits (#908, design #905 §6).
3//!
4//! Public atproto infrastructure allowlists only `did:plc` and `did:web` as repo
5//! authorities. hyprstream additionally accepts **`did:at9p`** (the
6//! self-certifying hybrid-PQC capsule identity, #879/#880) on *our own* side: a
7//! did:at9p account can own and sign a repo hosted by our PDS. Public publication
8//! of such a repo goes through the #896 `alsoKnownAs` bridge, which republishes
9//! under a classical `did:web`/`did:plc` authority that public infra will accept —
10//! so accepting did:at9p here never implies public infra must.
11//!
12//! Public authorities are validated as complete repository identifiers, not
13//! DID URLs. Host-form web authorities use the hosted-account DNS rules plus
14//! atproto's top-level-domain restrictions, with an explicit self-hosted OAuth
15//! extension for canonical encoded ports (including .test hosts). This extension
16//! does not imply interoperability with public AT Protocol services.
17//! PLC authorities require their full base32 identifier. Native at9p capsule
18//! validation remains the native resolver's responsibility. This is not a
19//! signature or ownership check (see [`crate::commit::Commit::verify`]).
20
21use anyhow::{bail, ensure, Result};
22
23use hyprstream_rpc::identity::Did;
24
25/// Whether `did` is a path-form `did:web` identifier.
26///
27/// The atproto DID profile permits only host-form `did:web`; any additional
28/// colon in the method-specific identifier introduces a path segment. Encoded
29/// host ports (`%3A`) do not contain a literal colon and are deliberately not
30/// classified here — this helper answers only the path-form question.
31pub fn is_path_form_did_web(did: &str) -> bool {
32    let Some(method_id) = did.strip_prefix("did:web:") else {
33        return false;
34    };
35    let method_id = method_id.split(['?', '#']).next().unwrap_or(method_id);
36    method_id.contains(':')
37}
38
39/// A DID method our PDS accepts as a repo authority.
40#[derive(Clone, Copy, Debug, Eq, PartialEq)]
41pub enum RepoAuthority {
42    /// `did:web` — an operated node whose keys live as DID-document verification
43    /// methods. Accepted by public atproto infra.
44    Web,
45    /// `did:plc` — the atproto placeholder DID method. Accepted by public atproto
46    /// infra.
47    Plc,
48    /// `did:at9p` — the self-certifying hybrid-PQC capsule identity (#879/#880).
49    /// Accepted by our PDS; **not** by public atproto infra (bridged via #896).
50    At9p,
51}
52
53impl RepoAuthority {
54    /// Whether public atproto infrastructure will itself accept this authority as
55    /// a repo owner.
56    ///
57    /// `true` for `did:web`/`did:plc`; `false` for `did:at9p`. A did:at9p repo is
58    /// published to public infra only via the #896 `alsoKnownAs` bridge under a
59    /// classical DID.
60    pub fn is_publicly_publishable(self) -> bool {
61        matches!(self, RepoAuthority::Web | RepoAuthority::Plc)
62    }
63}
64
65/// Classify `did` as an accepted repo authority for our PDS, or reject it.
66///
67/// Accepts `did:web`, `did:plc`, and `did:at9p`; every other DID method is
68/// rejected. The `did:at9p` arm is what this issue (#908) adds — the classical
69/// methods were already implicitly accepted by the commit layer, which never
70/// method-checked its `did`.
71pub fn accept_repo_authority(did: &str) -> Result<RepoAuthority> {
72    ensure!(
73        did.len() <= 2048 && !did.contains(['/', '?', '#', '\\', '\0']),
74        "repo authority must be a bare DID, not a DID URL"
75    );
76    let d = Did::new(did.to_owned());
77    if d.is_did_web() {
78        if is_path_form_did_web(did) {
79            bail!(
80                "path-form did:web {did:?} is not an accepted repo authority; the atproto profile requires host-form did:web"
81            );
82        }
83        // Repository-specific compatibility with the canonical service DID
84        // produced from configured OAuth origins. The public AT Protocol DID
85        // profile is stricter: non-localhost ports are a Hyprstream self-hosted
86        // extension, not a public interoperability guarantee.
87        let (host_did, has_port) = if let Some((host, port)) = did.split_once("%3A") {
88            let number = port.parse::<u16>()?;
89            ensure!(
90                number != 0 && number != 443 && port == number.to_string(),
91                "repo did:web port must be canonical, nonzero and non-default"
92            );
93            (host, true)
94        } else {
95            (did, false)
96        };
97        // Validating the undecoded host rejects userinfo, IPs, localhost,
98        // other percent escapes and repeated encoded ports without rewriting
99        // the accepted DID used in repository keys or signatures.
100        crate::did_op::validate_host_form_did_web(host_did)?;
101        let tld = host_did.rsplit('.').next().unwrap_or_default();
102        ensure!(
103            tld.as_bytes().first().is_some_and(u8::is_ascii_lowercase),
104            "public did:web top-level domain must start with an ASCII letter"
105        );
106        ensure!(
107            !matches!(
108                tld,
109                "alt"
110                    | "arpa"
111                    | "example"
112                    | "internal"
113                    | "invalid"
114                    | "local"
115                    | "localhost"
116                    | "onion"
117            ),
118            "public did:web top-level domain is reserved or disallowed by atproto"
119        );
120        ensure!(
121            tld != "test" || has_port,
122            "repo did:web .test requires the canonical self-hosted OAuth port form"
123        );
124        Ok(RepoAuthority::Web)
125    } else if let Some(identifier) = did.strip_prefix("did:plc:") {
126        ensure!(
127            identifier.len() == 24
128                && identifier
129                    .bytes()
130                    .all(|b| matches!(b, b'a'..=b'z' | b'2'..=b'7')),
131            "repo did:plc requires 24 lowercase base32 characters"
132        );
133        Ok(RepoAuthority::Plc)
134    } else if d.is_did_at9p() {
135        Ok(RepoAuthority::At9p)
136    } else {
137        bail!("did {did:?} is not an accepted repo authority (want did:web, did:plc, or did:at9p)")
138    }
139}
140
141#[cfg(test)]
142mod tests {
143    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
144    use super::*;
145
146    #[test]
147    fn accepts_did_at9p() {
148        let a = accept_repo_authority("did:at9p:bafkrei1234567890abcdefghijklmnop").unwrap();
149        assert_eq!(a, RepoAuthority::At9p);
150        assert!(
151            !a.is_publicly_publishable(),
152            "did:at9p is bridged, not public"
153        );
154    }
155
156    #[test]
157    fn accepts_classical_methods() {
158        let web = accept_repo_authority("did:web:alice.example.com").unwrap();
159        assert_eq!(web, RepoAuthority::Web);
160        assert!(web.is_publicly_publishable());
161
162        let plc = accept_repo_authority("did:plc:ewvi7nxzyoun6zhxrhs64oiz").unwrap();
163        assert_eq!(plc, RepoAuthority::Plc);
164        assert!(plc.is_publicly_publishable());
165    }
166
167    #[test]
168    fn rejects_path_form_did_web_repo_authority() {
169        assert!(is_path_form_did_web("did:web:accounts.example:users:alice"));
170        assert!(!is_path_form_did_web("did:web:alice.accounts.example"));
171        assert!(!is_path_form_did_web("did:web:localhost%3A6791"));
172
173        let err = accept_repo_authority("did:web:accounts.example:users:alice").unwrap_err();
174        assert!(err.to_string().contains("path-form did:web"));
175    }
176
177    #[test]
178    fn rejects_unknown_methods() {
179        assert!(accept_repo_authority("did:key:z6Mkxyz").is_err());
180        assert!(accept_repo_authority("did:example:123").is_err());
181        assert!(accept_repo_authority("not-a-did").is_err());
182        assert!(accept_repo_authority("").is_err());
183    }
184
185    #[test]
186    fn rejects_malformed_public_identifiers_and_did_urls() {
187        for did in [
188            "did:plc:",
189            "did:plc:abc",
190            "did:plc:ewvi7nxzyoun6zhxrhs64oi1",
191            "did:plc:EWVI7NXZYOUN6ZHX RHS64OIZ",
192            "did:web:",
193            "did:web:example..com",
194            "did:web:-example.com",
195            "did:web:example.com-",
196            "did:web:example_com",
197            "did:web:example.com%23fragment",
198            "did:web:example.com#fragment",
199            "did:web:example.com?query",
200            "did:web:example.com/path",
201            "did:web:example.com\0",
202            "did:plc:ewvi7nxzyoun6zhxrhs64oiz#key",
203            "did:plc:ewvi7nxzyoun6zhxrhs64oiz?query",
204            "did:plc:ewvi7nxzyoun6zhxrhs64oiz/path",
205        ] {
206            assert!(accept_repo_authority(did).is_err(), "{did:?}");
207        }
208    }
209
210    #[test]
211    fn public_web_authority_enforces_tld_and_production_host_rules() {
212        for host in [
213            "example.arpa",
214            "example.onion",
215            "example.123",
216            "example.1com",
217            "127.0.0.1",
218            "[::1]",
219            "%5B%3A%3A1%5D",
220            "localhost",
221            "localhost%3A6791",
222            "example.com%3A443",
223            "example.alt",
224            "example.example",
225            "example.internal",
226            "example.invalid",
227            "example.local",
228            "example.localhost",
229            "example.test",
230        ] {
231            assert!(
232                accept_repo_authority(&format!("did:web:{host}")).is_err(),
233                "{host}"
234            );
235        }
236        for host in [
237            "example.com",
238            "alice.example.com",
239            "123.example.com",
240            "arpa.example.com",
241            "onion.example.com",
242            "example.xn--fiqs8s",
243        ] {
244            assert_eq!(
245                accept_repo_authority(&format!("did:web:{host}")).unwrap(),
246                RepoAuthority::Web
247            );
248        }
249    }
250    #[test]
251    fn repo_web_authority_preserves_canonical_oauth_port_extension() {
252        for did in [
253            "did:web:pds.example.test%3A8443",
254            "did:web:pds.example.com%3A8443",
255            "did:web:example.com%3A1",
256            "did:web:example.com%3A65535",
257        ] {
258            assert_eq!(accept_repo_authority(did).unwrap(), RepoAuthority::Web);
259        }
260        for host in [
261            "example.com%3A0",
262            "example.com%3A443",
263            "example.com%3A65536",
264            "example.com%3A08443",
265            "example.com%3A+8443",
266            "example.com%3A",
267            "example.com%3A8443%3A8444",
268            "example.com%3a8443",
269            "example.com%253A8443",
270            "example.com%3A8443:users",
271            "user@example.com%3A8443",
272            "user%40example.com%3A8443",
273            "127.0.0.1%3A8443",
274            "192.0.2.1%3A8443",
275            "[::1]%3A8443",
276            "localhost%3A8443",
277            "example.123%3A8443",
278            "example.1com%3A8443",
279            "example.arpa%3A8443",
280            "example.onion%3A8443",
281            "example.internal%3A8443",
282            "example.invalid%3A8443",
283            "example.local%3A8443",
284            "example.localhost%3A8443",
285            "example.alt%3A8443",
286            "example.example%3A8443",
287            "example.com%3A8443#key",
288            "example.com%3A8443?query",
289            "example.com%3A8443/path",
290        ] {
291            assert!(
292                accept_repo_authority(&format!("did:web:{host}")).is_err(),
293                "{host}"
294            );
295        }
296    }
297}