Skip to main content

hyprstream_pds/
lib.rs

1//! atproto PDS record store — the federated spine's signed-mutable-pointer layer (#392).
2//!
3//! Per-account record store hosting `ai.hyprstream.model` records in a Merkle
4//! Search Tree (MST), emitting signed commits, and serving CAR proofs. This is
5//! the consensus-free versioning primitive: a **signed mutable pointer → immutable
6//! OID** that makes federation work without a coordinator.
7//!
8//! # What this crate provides
9//!
10//! - **Existing native CBOR** deterministic encode/decode ([`dag_cbor`]):
11//!   map keys sorted in lexical text-byte order, minimal-length ints and no
12//!   duplicate keys. Public AT DAG-CBOR instead requires length-first key order;
13//!   [`atproto_cbor`] provides that explicit boundary without changing existing
14//!   native signed artifacts. Public repository call-site integration is still
15//!   required; the existing commit/MST APIs retain their existing bytes.
16//!   CID links use CBOR tag 42 per the
17//!   [DAG-CBOR spec](https://github.com/ipld/specs/blob/master/block-layer/codecs/dag-cbor.md).
18//!   The same record produces identical bytes → same CID every time.
19//! - **`ai.hyprstream.model` record** ([`record`]) — the confirmed 3-field
20//!   lexicon: `repo` (at-uri), `currentOid` (cid), `createdAt` (datetime).
21//!   DAG-CBOR encoded; `currentOid` is a `format: "cid"` *string* (not a link).
22//! - **MST** ([`mst`]) — the atproto repo structure (Auvolat & Taïani, SRDS 2019).
23//!   Insert/delete records keyed by TID; compute the MST root CID. Implemented
24//!   as the full recursive tree (`NodeData { l, e: [TreeEntry { p, k, v, t }] }`)
25//!   matching the atproto reference.
26//! - **Signed commit** ([`commit`]) — `{did, version: 3, rev, data, prev, sig}`.
27//!   `sig` is ES256 (P-256 ECDSA over SHA-256) of the DAG-CBOR of the
28//!   *unsigned* commit (commit minus the `sig` field), signed with the DID's
29//!   `#atproto` P-256 key.
30//! - **CAR proof** ([`car`]) — serve `getRepo`/`getRecord` as a CAR (Content
31//!   Addressable aRchive) containing the commit + MST path + record.
32//! - **`verifyRecordProof`** ([`car::verify_record_proof`]) — offline
33//!   verification: check commit sig, walk the MST proof to the record, verify
34//!   the record's CID. Enforces the D5 untrusted-host posture.
35//!
36//! # What this crate deliberately is NOT
37//!
38//! - No libtorch / inference — this is a metadata/crypto layer.
39//! - No networking — proofs are produced and verified in-process; a transport
40//!   (HTTP/moq) wraps this separately.
41//! - No general repo database — MST/CAR stores remain in-memory. The narrow
42//!   exception is [`DirectoryHostedAccountStore`], which durably establishes
43//!   an account's immutable genesis bundle and generated `#atproto` secret.
44//!
45//! # Reused infrastructure
46//!
47//! ES256/P-256 key handling mirrors `hyprstream::auth::key_rotation`
48//! (`Es256SigningKeyStore`) and the DID-document `#atproto` verification method
49//! from `hyprstream::services::oauth::did_document`. The signing key type is the
50//! same `p256::ecdsa::SigningKey`, so a key from the rotation store drops in
51//! directly.
52
53#![forbid(unsafe_code)]
54#![deny(clippy::unwrap_used, clippy::expect_used)]
55
56pub mod account_label;
57pub mod at9p;
58pub mod at9p_alias;
59pub mod at9p_chain;
60pub mod at9p_duplicity;
61pub mod at9p_gate;
62pub mod at9p_resolver;
63pub mod at9p_sign;
64pub mod atproto_cbor;
65pub mod car;
66pub mod cid;
67pub mod commit;
68pub mod dag_cbor;
69pub mod did_op;
70pub mod event_group;
71pub mod hosted_account;
72pub mod hosted_did_document;
73pub mod hosted_repo;
74pub mod ledger;
75pub mod list_record;
76pub mod mst;
77pub mod name_record;
78#[cfg(all(feature = "postgres", not(target_arch = "wasm32")))]
79pub mod pgsql_kv;
80pub mod placement;
81pub mod rds;
82pub mod record;
83pub mod repo_authority;
84pub mod tid;
85
86pub use account_label::{
87    AccountLabel, AccountLabelRegistry, ReservedAccountLabel, MAX_ACCOUNT_LABEL_LEN,
88    RESERVED_ACCOUNT_LABELS,
89};
90pub use cid::Cid;
91pub use did_op::{
92    sign_genesis, DidOpSignature, GenesisDidOp, GenesisRepoHead, GenesisRotationKeys,
93    HostKeyEnrollment, HostRotationKey, HybridRotationKey, RecoveryKeyEnrollment,
94    RecoveryRotationKey, RotationSlotRef, UnsignedGenesisDidOp, UserRotationKey,
95    DID_OP_SIGNATURE_CONTEXT, DID_OP_VERSION,
96};
97pub use hosted_account::{
98    is_hosted_account_staging_directory, AccountRecord, AllocatedAccountName,
99    DirectoryHostedAccountStore, HostedAccountMint, PendingHostedAccountMint, SealedHostedAccount,
100    ACCOUNT_RECORD_VERSION, ATPROTO_SIGNING_KEY_FILE, DID_DOCUMENT_FILE, GENESIS_DID_OP_FILE,
101};
102pub use hosted_did_document::{
103    SealedHostedDidDocument, DID_DOCUMENT_MEDIA_TYPE, DID_DOCUMENT_PATH, DID_OPERATION_LOG_PATH,
104};
105pub use hosted_repo::HostedRepoGenesis;
106pub use ledger::{AllocationRecord, CheckpointRecord, GrantClass, ReceiptRecord, StateRoot, Unit};
107pub use name_record::NameRecord;
108pub use placement::{GroupItemRecord, GroupRecord, NodeRecord, WorkloadRecord};
109pub use record::ModelRecord;
110pub use repo_authority::{accept_repo_authority, RepoAuthority};