lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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.