README.md (8256B)
1 # radroots_event_codec 2 3 `radroots_event_codec` is the portable, deterministic algorithm layer for 4 Radroots events. It converts between bounded wire representations and native 5 `radroots_event` values, computes canonical NIP-01 identifiers, verifies event 6 identifiers and signatures, validates event contracts, admits typed event 7 profiles, and generates governed contract manifests. 8 9 The crate is pre-release and its Cargo version is frozen at `0.1.0-alpha` 10 until explicitly changed. Serialized contract generations such as registry v7 11 are versioned independently from the Cargo package. 12 13 ## Canonical surface 14 15 New code should enter through these modules: 16 17 | Module | Responsibility | 18 | --- | --- | 19 | `authoring` | Freeze exact registry-authored event plans and distinct HTTP-only Blossom authorization plans with semantic digests. | 20 | `canonical` | Compute canonical NIP-01 preimages and event identifiers without asserting trust. | 21 | `decode` | Parse bounded wire data and domain projections without silently verifying later stages. | 22 | `encode` | Produce deterministic JSON, tags, and unsigned wire parts from validated native inputs. | 23 | `verify` | Advance explicit identifier, signature, and contract-validation typestates. | 24 | `admission` | Apply typed or registry admission to an already verified event; available with `json`. | 25 | `manifest` | Generate and validate registry and knowledge inventories; available with `manifests`. | 26 27 The Release V1 canonical root consists of `Codec`, `DecodeError`, 28 `EncodeError`, and `VerificationError`. Domain algorithms stay beneath the 29 canonical modules so each import states whether it encodes, decodes, verifies, 30 or admits data. Legacy top-level domain routes are not exposed. The canonical 31 surface is recorded in the 32 [public API baseline](../../contracts/api_baselines/radroots_event_codec.txt). 33 34 ## Verification pipeline 35 36 File-message authoring requires a supplied `original_hash`, `blurhash`, or 37 `thumb` value to contain non-whitespace text, matching the decoder's admission 38 rules. Nonblank values retain their exact text; use `None` to omit a field. 39 40 Wire parsing and cryptographic trust are separate operations. A successful 41 decode returns a structurally valid `RawEvent`; it does not make the declared 42 event ID, signature, contract, referenced events, relay hints, or remote media 43 trustworthy. 44 45 ```rust 46 use radroots_event_codec::{admission, decode, verify}; 47 48 const PROFILE_EVENT: &str = r#"{"id":"762bee187e9e645b81ec26ade05a69b5e8398caf527be8de0d9a45311ed0c7a0","pubkey":"585591529da0bab31b3b1b1f986611cf5f435dca84f978c89ee8a40cca7103df","created_at":1800000100,"kind":0,"tags":[],"content":"{\"display_name\":\"Moss Street Farm\",\"bot\":false,\"website\":\"https://mossstreet.example\",\"picture\":42}","sig":"4290da0bb6422986647bc8cd5f63bd52d49f41e7b665d3b47105b8109183e8d596f322c531d4061df53e1d2b70fda12d5d1c14f3720d7a56d9d0a03746af5109"}"#; 49 50 let raw = decode::event(PROFILE_EVENT)?; 51 let verified = verify::verify_nip01_event(raw.into_event())?; 52 let admitted = admission::admit_verified_event(verified)?; 53 54 assert_eq!(admitted.event().kind_u32(), 0); 55 # Ok::<(), Box<dyn std::error::Error>>(()) 56 ``` 57 58 A runnable version is available at 59 [`examples/verify_profile.rs`](examples/verify_profile.rs). 60 61 For capability-injected verification, use `verify::id`, then 62 `verify::signature`, then `verify::contract`. Each function consumes its input 63 typestate and returns the next, so callers cannot obtain a later state by 64 accidentally skipping an earlier check. 65 66 ## Features 67 68 | Feature | Default | Effect | 69 | --- | --- | --- | 70 | `std` | yes | Standard-library error integration for the portable surface. | 71 | `serde` | no | Serde support for native values used by codec contracts. | 72 | `json` | yes | Bounded JSON parsing/encoding and JSON-backed typed profiles; enables `serde`. | 73 | `knowledge` | no | Knowledge event codecs and verified decoding; enables `json`. | 74 | `manifests` | no | Typed registry and knowledge manifest generation; enables `knowledge`. | 75 76 `--no-default-features` keeps the portable allocation-backed canonical, 77 encoding, decoding, and verification core. Feature-specific APIs disappear 78 when their feature is disabled rather than installing a fallback with weaker 79 guarantees. 80 81 ## Serialization and canonicalization 82 83 - `decode::event` accepts compact NIP-01 JSON only within the shared bounded 84 wire limits. Unknown extension structure is bounded before it can consume 85 unbounded memory or parser depth. 86 - `encode::event` emits deterministic compact JSON from an existing event 87 envelope. Encoding does not verify or alter the envelope. 88 - `canonical::id_preimage` and `canonical::id` compute canonical bytes and the 89 corresponding identifier. They do not compare the result with the event's 90 declared ID. 91 - Domain encoders accept checked `radroots_event` inputs and emit unsigned 92 wire parts. Signing and publication belong to the owning runtime. 93 - `authoring::BlossomAuthorizationPlan` binds a strict BUD-11 upload claim to 94 an expected author and event ID under a domain-separated digest. Its 95 distinct type cannot be passed to relay push APIs. 96 - Manifest JSON and digests are generated from versioned contract authority; 97 a manifest feature does not grant storage or publication authority. 98 99 Serialized output is stable only where its event profile or manifest 100 generation says it is stable. Rust data layout and the pre-release public API 101 are not serialized contracts. 102 103 ## Security and trust boundaries 104 105 All public parsers treat their inputs as untrusted. They return structured 106 errors for malformed or over-budget data and do not intentionally panic on 107 untrusted input. Verification distinguishes these claims: 108 109 1. structural decoding proves only bounded event shape; 110 2. ID verification proves the declared identifier matches canonical bytes; 111 3. signature verification proves the BIP-340 signature for that event and 112 author; 113 4. contract validation proves the event matches a registered shape; 114 5. typed admission proves the selected Radroots profile. 115 116 No stage proves referenced-event existence, relay availability, media upload 117 or retrievability, actor authorization, business-policy approval, persistence, 118 or publication. Inbound URLs and relay hints remain structural observations 119 unless a higher layer explicitly establishes a stronger state. 120 121 The crate never owns secret keys and does not sign events. Signature 122 verification is deterministic and public-key-only. Callers must not interpret 123 a successfully encoded unsigned event as signed or published. 124 125 ## Side effects, cancellation, and commit points 126 127 This crate performs no network access, filesystem access, database access, 128 background work, executor installation, timer management, signing, or event 129 publication. Its algorithms are synchronous and deterministic for the same 130 inputs. 131 132 There is therefore no asynchronous cancellation or deadline boundary and no 133 durable commit point. Dropping a computation only discards in-memory work. 134 Storage, signing, transport, SDK, and daemon callers own cancellation and must 135 report success only after their own explicit commit boundary succeeds. 136 137 ## Intended consumers 138 139 Direct consumers are `radroots_nostr`, `radroots_storage_sqlite`, 140 `radroots_transport_nostr`, `radroots_sync`, `radroots_sdk`, generated 141 bindings, indexers, and conformance tooling. Applications should normally use 142 the `radroots` or `radroots_sdk` front door and depend on this crate directly 143 only when implementing a deterministic event boundary. 144 145 This package must not acquire live relay clients, persistence, background 146 workers, host configuration, SDK state, or upstream client error types. Those 147 responsibilities belong to adapter and runtime crates. 148 149 ## Package charter 150 151 The authoritative Release V1 responsibility, dependency, feature, module, and 152 forbidden-scope contract is the 153 [Radroots crates Release V1 specification](../../contracts/crates/release_v1/radroots_crates_release_v1.toml). 154 The reviewed surface is the 155 [`radroots_event_codec` API baseline](../../contracts/api_baselines/radroots_event_codec.txt). 156 157 ## Copyright 158 159 Except as otherwise noted, all files in the `radroots_event_codec` 160 distribution are copyright (c) 2025 Tyson Lupul. See `LICENSE` for usage, 161 redistribution, and warranty terms.