Skip to main content

hyprstream_pds/
atproto_cbor.rs

1//! Explicit public AT Protocol CBOR boundary over the existing value type.
2//!
3//! Public DAG-CBOR orders text map keys by encoded bytes: UTF-8 byte length
4//! first, then lexical bytes. The existing native codec has a different order
5//! and is retained for already-signed artifacts. Neither decoder falls back to
6//! the other's order. This module does not change existing record, commit, MST
7//! or identity call sites, and does not establish public repository readiness.
8//!
9//! Integer-only AT data uses signed 64-bit integers. The public encoder checks
10//! this and validates map structure/depth before invoking the existing scalar
11//! writer. The decoder retains minimal-width, tag, UTF-8, duplicate-key and
12//! bounded-depth checks. Floats remain unsupported by the AT data model.
13
14use std::cmp::Ordering;
15
16use anyhow::{ensure, Result};
17
18use crate::cid::Cid;
19use crate::dag_cbor::DagCbor;
20use crate::tid::Tid;
21
22const MAX_DEPTH: usize = 128;
23
24/// A validated AT Protocol record key.
25///
26/// Record keys are user-controlled path segments. They may be TIDs, literal
27/// values such as `self`, NSIDs, or any other value permitted by the baseline
28/// record-key syntax; they are not limited to the TID format.
29#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
30pub struct AtprotoRecordKey(String);
31
32impl AtprotoRecordKey {
33    pub fn new(value: impl Into<String>) -> Result<Self> {
34        let value = value.into();
35        ensure!(
36            (1..=512).contains(&value.len())
37                && value.is_ascii()
38                && value != "."
39                && value != ".."
40                && value.bytes().all(|c| {
41                    c.is_ascii_alphanumeric() || matches!(c, b'.' | b'-' | b'_' | b':' | b'~')
42                }),
43            "invalid AT record key"
44        );
45        Ok(Self(value))
46    }
47
48    pub fn as_str(&self) -> &str {
49        &self.0
50    }
51}
52
53impl From<Tid> for AtprotoRecordKey {
54    fn from(value: Tid) -> Self {
55        Self(value.encode())
56    }
57}
58
59impl From<&Tid> for AtprotoRecordKey {
60    fn from(value: &Tid) -> Self {
61        Self::from(*value)
62    }
63}
64
65impl From<&AtprotoRecordKey> for AtprotoRecordKey {
66    fn from(value: &AtprotoRecordKey) -> Self {
67        value.clone()
68    }
69}
70
71/// A generic public AT Protocol repository record.
72///
73/// The value is retained as a typed DAG-CBOR value and its exact public bytes
74/// and CID are derived once at construction. This is deliberately independent
75/// of native `ModelRecord`: any supported collection can be stored without
76/// converting through a lossy JSON DTO. Construction validates the collection,
77/// general record key, `$type` discriminator and canonical public bytes; it does
78/// not grant write authority or perform a full Lexicon validation.
79#[derive(Clone, Debug, PartialEq)]
80pub struct AtprotoRecord {
81    collection: String,
82    rkey: AtprotoRecordKey,
83    value: DagCbor,
84    bytes: Vec<u8>,
85    cid: Cid,
86}
87
88impl AtprotoRecord {
89    pub fn new(
90        collection: impl Into<String>,
91        rkey: impl Into<AtprotoRecordKey>,
92        value: DagCbor,
93    ) -> Result<Self> {
94        let collection = collection.into();
95        let rkey: AtprotoRecordKey = rkey.into();
96        validate_nsid(&collection)?;
97        let type_value = value
98            .get("$type")
99            .ok_or_else(|| anyhow::anyhow!("AT record is missing $type"))?
100            .as_str()?;
101        ensure!(
102            type_value == collection,
103            "AT record $type does not match collection"
104        );
105        let bytes = encode(&value)?;
106        let cid = Cid::from_dag_cbor(&bytes);
107        Ok(Self {
108            collection,
109            rkey,
110            value,
111            bytes,
112            cid,
113        })
114    }
115
116    /// Reconstruct a record only when bytes are already strict public
117    /// canonical encoding. This check prevents a caller from changing the CID
118    /// by normalizing at a later boundary.
119    pub fn from_bytes(
120        collection: impl Into<String>,
121        rkey: impl Into<AtprotoRecordKey>,
122        bytes: &[u8],
123    ) -> Result<Self> {
124        let value = decode(bytes)?;
125        let record = Self::new(collection, rkey, value)?;
126        ensure!(record.bytes == bytes, "AT record bytes are not canonical");
127        Ok(record)
128    }
129
130    pub fn bytes(&self) -> &[u8] {
131        &self.bytes
132    }
133
134    /// The validated collection NSID. Record identity fields are immutable
135    /// after construction so this always agrees with `bytes()` and `cid()`.
136    pub fn collection(&self) -> &str {
137        &self.collection
138    }
139
140    /// The validated record key.
141    pub fn rkey(&self) -> &AtprotoRecordKey {
142        &self.rkey
143    }
144
145    /// The validated record value.
146    pub fn value(&self) -> &DagCbor {
147        &self.value
148    }
149
150    pub fn cid(&self) -> Cid {
151        self.cid
152    }
153    pub fn uri(&self, did: &str) -> String {
154        format!("at://{did}/{}/{}", self.collection, self.rkey.as_str())
155    }
156}
157
158fn validate_nsid(nsid: &str) -> Result<()> {
159    ensure!(
160        !nsid.is_empty() && nsid.len() <= 317 && nsid.is_ascii(),
161        "invalid AT collection NSID"
162    );
163    let segments: Vec<&str> = nsid.split('.').collect();
164    ensure!(
165        segments.len() >= 3,
166        "invalid NSID: authority and name required"
167    );
168
169    let name = segments.last().copied().unwrap_or_default();
170    ensure!(
171        (1..=63).contains(&name.len())
172            && name.as_bytes()[0].is_ascii_alphabetic()
173            && name.bytes().all(|c| c.is_ascii_alphanumeric()),
174        "invalid NSID name"
175    );
176
177    let authority = &segments[..segments.len() - 1];
178    let authority_len = nsid.len() - name.len() - 1;
179    ensure!(
180        authority.len() >= 2 && authority_len <= 253,
181        "invalid NSID authority"
182    );
183    for (index, segment) in authority.iter().enumerate() {
184        ensure!(
185            (1..=63).contains(&segment.len())
186                && segment
187                    .bytes()
188                    .all(|c| c.is_ascii_alphanumeric() || c == b'-')
189                && segment.as_bytes()[0] != b'-'
190                && segment.as_bytes()[segment.len() - 1] != b'-'
191                && (index != 0 || segment.as_bytes()[0].is_ascii_alphabetic()),
192            "invalid NSID segment"
193        );
194    }
195    Ok(())
196}
197
198fn key_order(a: &[u8], b: &[u8]) -> Ordering {
199    a.len().cmp(&b.len()).then_with(|| a.cmp(b))
200}
201
202/// Encode a value in the public AT Protocol format without mutating it.
203/// This is canonical serialization, not schema validation or authorization.
204pub fn encode(value: &DagCbor) -> Result<Vec<u8>> {
205    Ok(normalize(value, 0)?.encode())
206}
207
208/// Decode exactly one strictly canonical public AT Protocol value.
209/// No legacy/native ordering fallback is permitted.
210pub fn decode(bytes: &[u8]) -> Result<DagCbor> {
211    let value = DagCbor::decode_with_order(bytes, key_order)?;
212    // Enforce signed integer bounds and the same construction constraints as
213    // encode; byte-level canonicality has already been checked by the parser.
214    normalize(&value, 0)
215}
216
217fn normalize(value: &DagCbor, depth: usize) -> Result<DagCbor> {
218    ensure!(
219        depth <= MAX_DEPTH,
220        "ATProto CBOR nesting exceeds {MAX_DEPTH}"
221    );
222    Ok(match value {
223        DagCbor::Unsigned(n) => {
224            ensure!(
225                *n <= i64::MAX as u64,
226                "ATProto integer exceeds signed 64-bit range"
227            );
228            value.clone()
229        }
230        DagCbor::Negative(n) => {
231            ensure!(
232                *n >= i64::MIN as i128 && *n < 0,
233                "ATProto negative integer outside signed 64-bit range"
234            );
235            value.clone()
236        }
237        DagCbor::List(items) => DagCbor::List(
238            items
239                .iter()
240                .map(|item| normalize(item, depth + 1))
241                .collect::<Result<_>>()?,
242        ),
243        DagCbor::Map(pairs) => {
244            let mut normalized = Vec::with_capacity(pairs.len());
245            for (key, val) in pairs {
246                ensure!(depth < MAX_DEPTH, "ATProto CBOR map exceeds nesting limit");
247                let text = key.as_str()?;
248                normalized.push((text.to_owned(), normalize(val, depth + 1)?));
249            }
250            normalized.sort_by(|(a, _), (b, _)| key_order(a.as_bytes(), b.as_bytes()));
251            ensure!(
252                normalized.windows(2).all(|pair| pair[0].0 != pair[1].0),
253                "duplicate ATProto CBOR map key"
254            );
255            DagCbor::Map(
256                normalized
257                    .into_iter()
258                    .map(|(k, v)| (DagCbor::Text(k), v))
259                    .collect(),
260            )
261        }
262        _ => value.clone(),
263    })
264}
265
266#[cfg(test)]
267mod tests {
268    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::indexing_slicing)]
269
270    use super::*;
271    use crate::car::{build_public_record_proof_car, parse_car_v1_atproto};
272    use crate::commit::{Commit, UnsignedCommit};
273    use crate::mst::Node;
274    use crate::tid::Tid;
275    use crate::Cid;
276    use p256::ecdsa::SigningKey;
277
278    fn post() -> DagCbor {
279        DagCbor::str_map([
280            ("$type", DagCbor::Text("app.bsky.feed.post".into())),
281            ("text", DagCbor::Text("Hello from Torment Nexus".into())),
282            (
283                "createdAt",
284                DagCbor::Text("2026-09-09T00:00:00.000Z".into()),
285            ),
286        ])
287    }
288
289    #[test]
290    fn public_post_matches_upstream_bytes_and_cid() {
291        // Generated independently with @atproto/lex-cbor 0.1.6 encode/cidForLex.
292        let upstream = hex::decode("a36474657874781848656c6c6f2066726f6d20546f726d656e74204e65787573652474797065726170702e62736b792e666565642e706f7374696372656174656441747818323032362d30392d30395430303a30303a30302e3030305a").unwrap();
293        let bytes = encode(&post()).unwrap();
294        assert_eq!(bytes, upstream);
295        assert_eq!(
296            Cid::from_dag_cbor(&bytes).to_string(),
297            "bafyreiaapk47b4fmdslcizkj5aj6ws6bmpmvfvjq3ryhx5qwgug6tldalm"
298        );
299        assert_eq!(encode(&decode(&bytes).unwrap()).unwrap(), bytes);
300    }
301
302    #[test]
303    fn native_bytes_and_strict_verifier_remain_separate() {
304        let value = DagCbor::str_map([("aa", DagCbor::Unsigned(1)), ("b", DagCbor::Unsigned(2))]);
305        let native = hex::decode("a262616101616202").unwrap();
306        let public = hex::decode("a261620262616101").unwrap();
307        assert_eq!(value.encode(), native);
308        assert_eq!(DagCbor::decode(&native).unwrap(), value);
309        assert_eq!(encode(&value).unwrap(), public);
310        assert!(DagCbor::decode(&public).is_err());
311        assert!(decode(&native).is_err());
312    }
313
314    #[test]
315    fn public_order_applies_to_nested_maps_and_utf8_byte_lengths() {
316        let inner = DagCbor::str_map([("é", DagCbor::Bool(true)), ("z", DagCbor::Bool(false))]);
317        let value = DagCbor::list([inner]);
318        assert_eq!(hex::encode(encode(&value).unwrap()), "81a2617af462c3a9f5");
319        assert_eq!(
320            encode(&decode(&encode(&value).unwrap()).unwrap()).unwrap(),
321            encode(&value).unwrap()
322        );
323    }
324
325    #[test]
326    fn malformed_construction_is_rejected_without_panic() {
327        for value in [
328            DagCbor::Negative(0),
329            DagCbor::Negative(i128::MIN),
330            DagCbor::Unsigned(u64::MAX),
331            DagCbor::Map(vec![(DagCbor::Bool(true), DagCbor::Null)]),
332            DagCbor::Map(vec![(DagCbor::Text("a".into()), DagCbor::Null); 2]),
333        ] {
334            assert!(encode(&value).is_err());
335        }
336    }
337
338    #[test]
339    fn nsid_validation_matches_at_protocol_syntax() {
340        for valid in [
341            "com.example.fooBar",
342            "net.users.bob.ping",
343            "a-0.b-1.c",
344            "a.b.c",
345            "cn.8.lex.stuff",
346        ] {
347            validate_nsid(valid).unwrap();
348        }
349        for invalid in [
350            "com.example",
351            "com.example.3",
352            "1.example.record",
353            "com.-example.record",
354            "com.example-.record",
355            "com.example.re-cord",
356            "com..example.record",
357            "com.example.",
358            "com.example.é",
359            "com.example.this_name_is_invalid",
360        ] {
361            assert!(validate_nsid(invalid).is_err(), "{invalid}");
362        }
363        assert!(validate_nsid(&format!("com.{}.record", "a".repeat(64))).is_err());
364        assert!(validate_nsid(&format!("com.example.{}", "a".repeat(64))).is_err());
365        assert!(validate_nsid(&format!(
366            "{}.{}.{}.{}.record",
367            "a".repeat(63),
368            "b".repeat(63),
369            "c".repeat(63),
370            "d".repeat(63),
371        ))
372        .is_err());
373    }
374
375    #[test]
376    fn record_identity_fields_are_immutable_after_construction() {
377        let record = AtprotoRecord::new("app.bsky.feed.post", Tid::from_raw(7), post()).unwrap();
378        assert_eq!(record.collection(), "app.bsky.feed.post");
379        assert_eq!(record.rkey().as_str(), Tid::from_raw(7).encode());
380        assert_eq!(record.value(), &post());
381        assert_eq!(record.cid(), Cid::from_dag_cbor(record.bytes()));
382    }
383
384    #[test]
385    fn literal_record_key_is_preserved_in_public_proof_path() {
386        let collection = "app.bsky.actor.profile";
387        let key = AtprotoRecordKey::new("self").unwrap();
388        let value = DagCbor::str_map([("$type", DagCbor::Text(collection.to_owned()))]);
389        let record = AtprotoRecord::new(collection, &key, value).unwrap();
390        let mut records = std::collections::BTreeMap::new();
391        records.insert(format!("{collection}/self"), record.cid());
392        let tree = Node::from_keyed_records(&records);
393        let proof = tree.proof_atproto(collection, &key).unwrap();
394        let root = tree
395            .to_node_data_with_blocks_atproto()
396            .unwrap()
397            .0
398            .cid_atproto()
399            .unwrap();
400        proof.verify_atproto(&root, &record.cid()).unwrap();
401        assert_eq!(record.rkey().as_str(), "self");
402        assert!(AtprotoRecordKey::new(".").is_err());
403    }
404
405    #[test]
406    fn decoder_retains_strictness_and_integer_bounds() {
407        for wire in [
408            "a2616101616102",     // duplicate keys
409            "1817",               // nonminimal integer
410            "00ff",               // trailing data
411            "9fff",               // indefinite array
412            "c000",               // unsupported tag
413            "61ff",               // invalid UTF-8
414            "1b8000000000000000", // outside signed integer range
415            "3b8000000000000000", // below signed integer range
416        ] {
417            assert!(decode(&hex::decode(wire).unwrap()).is_err(), "{wire}");
418        }
419    }
420
421    #[test]
422    fn links_and_signed_integer_extremes_round_trip() {
423        let value = DagCbor::list([
424            DagCbor::Link(Cid::from_raw(b"public blob")),
425            DagCbor::Unsigned(i64::MAX as u64),
426            DagCbor::Negative(i64::MIN as i128),
427        ]);
428        assert_eq!(decode(&encode(&value).unwrap()).unwrap(), value);
429    }
430
431    #[test]
432    fn public_record_mst_commit_and_car_proof_round_trip() {
433        let rkey = Tid::from_raw(7);
434        let record = AtprotoRecord::new("app.bsky.feed.post", rkey, post()).unwrap();
435        let tree = Node::from_keyed_records(
436            &[(
437                format!("app.bsky.feed.post/{}", rkey.encode()),
438                record.cid(),
439            )]
440            .into_iter()
441            .collect(),
442        );
443        let (root_data, node_blocks) = tree.to_node_data_with_blocks_atproto().unwrap();
444        let root = root_data.cid_atproto().unwrap();
445        let unsigned =
446            UnsignedCommit::new("did:web:tormentnexus.social", root, Tid::from_raw(8), None);
447        let signing = SigningKey::from_bytes((&[7u8; 32]).into()).unwrap();
448        let commit = Commit::sign_atproto(&unsigned, &signing).unwrap();
449        commit.verify_atproto(signing.verifying_key()).unwrap();
450        let proof = tree.proof_atproto("app.bsky.feed.post", rkey).unwrap();
451        proof.verify_atproto(&root, &record.cid()).unwrap();
452        let car = build_public_record_proof_car(&commit, &proof, &node_blocks, &record).unwrap();
453        let (roots, blocks) = parse_car_v1_atproto(&car).unwrap();
454        assert_eq!(roots, vec![commit.cid_atproto().unwrap()]);
455        assert!(blocks
456            .iter()
457            .any(|(cid, bytes)| *cid == record.cid() && bytes == record.bytes()));
458        assert!(blocks
459            .iter()
460            .any(|(cid, bytes)| *cid == commit.cid_atproto().unwrap()
461                && bytes == &commit.to_atproto_dag_cbor().unwrap()));
462
463        let empty = crate::mst::Proof { path: Vec::new() };
464        assert!(build_public_record_proof_car(&commit, &empty, &node_blocks, &record).is_err());
465
466        let wrong_unsigned = UnsignedCommit::new(
467            "did:web:tormentnexus.social",
468            Cid::from_dag_cbor(b"wrong public root"),
469            Tid::from_raw(9),
470            None,
471        );
472        let wrong_commit = Commit::sign_atproto(&wrong_unsigned, &signing).unwrap();
473        assert!(
474            build_public_record_proof_car(&wrong_commit, &proof, &node_blocks, &record).is_err()
475        );
476
477        // The record bytes/CID are identical, but its record key is different.
478        // A proof must remain bound to the collection/rkey path.
479        let wrong_record =
480            AtprotoRecord::new("app.bsky.feed.post", Tid::from_raw(9), post()).unwrap();
481        assert!(
482            build_public_record_proof_car(&commit, &proof, &node_blocks, &wrong_record).is_err()
483        );
484
485        assert!(build_public_record_proof_car(&commit, &proof, &[], &record).is_err());
486        let mislabeled = node_blocks
487            .iter()
488            .map(|(_, data)| (Cid::from_dag_cbor(b"wrong label"), data.clone()))
489            .collect::<Vec<_>>();
490        assert!(build_public_record_proof_car(&commit, &proof, &mislabeled, &record).is_err());
491
492        let native_commit = Commit::sign(&unsigned, &signing);
493        assert!(
494            build_public_record_proof_car(&native_commit, &proof, &node_blocks, &record).is_err(),
495            "native-signed commits must not be emitted as public proof CARs"
496        );
497        let laundered = Commit::from_atproto_dag_cbor(
498            &native_commit
499                .to_atproto_dag_cbor()
500                .expect("native commit can be encoded for the negative test"),
501        )
502        .expect("canonical public shape must decode structurally");
503        assert!(
504            build_public_record_proof_car(&laundered, &proof, &node_blocks, &record).is_err(),
505            "decoding canonical bytes must not launder native signature provenance"
506        );
507
508        let mut unsupported_unsigned = unsigned.clone();
509        unsupported_unsigned.version = 4;
510        assert!(
511            Commit::sign_atproto(&unsupported_unsigned, &signing).is_err(),
512            "public signing must reject unsupported commit versions"
513        );
514
515        let mut mutated_public_commit = commit.clone();
516        mutated_public_commit.rev = Tid::from_raw(10);
517        assert!(
518            build_public_record_proof_car(&mutated_public_commit, &proof, &node_blocks, &record)
519                .is_err(),
520            "public CAR publication must reject a commit whose signed fields were mutated"
521        );
522
523        let mut mutated_public_signature = commit.clone();
524        mutated_public_signature.sig[0] ^= 1;
525        assert!(
526            build_public_record_proof_car(&mutated_public_signature, &proof, &node_blocks, &record)
527                .is_err(),
528            "public CAR publication must reject a mutated signature"
529        );
530    }
531
532    #[test]
533    fn excessive_nesting_is_rejected() {
534        let mut value = DagCbor::Null;
535        for _ in 0..130 {
536            value = DagCbor::list([value]);
537        }
538        assert!(encode(&value).is_err());
539        assert!(decode(&value.encode()).is_err());
540    }
541}