README.md (14921B)
1 # radroots_nostr 2 3 The `public_ingress` feature retains one original authenticated listing or 4 capability head per explicit scope. It applies frozen NIP-01 replacement order 5 before profile, expiry or caller-injected clock evaluation. Newer authentic 6 unsupported, invalid or future heads prevent older actionable fallback. Closed 7 known profiles retain validated values; observed support remains a participant 8 claim. This boundary performs no IO, publication, stock or permission decision. 9 The successor public reader uses explicit64KiB event/tag budgets; legacy defaults 10 and private profiles remain separately governed. The owning contract is 11 [`public_ingress.v1.json`](../../contracts/protocol/public_ingress.v1.json). 12 13 `radroots_nostr` is the portable Nostr protocol adapter for Radroots. It 14 converts between canonical Radroots identity/event values and Nostr protocol 15 values, provides typed NIP helpers, and supplies an optional concrete local 16 implementation of the `radroots_signing` SPI. 17 18 With `signing`, `LocalSigner` also reports its actual participant identity. 19 With `nip17` or `private_ingress`, it decrypts bounded NIP-44 v2 payloads and can encrypt after 20 explicit nonce-source injection through `with_nonce_source`. Native hosts may 21 choose `OsNonceSource`; deterministic sources belong only in controlled tests. 22 Call identity/deadline/cancellation checks precede effects. Private text is 23 owned and redacted, and obtained outputs are not discarded by a later clock 24 or cancellation check. These are crypto primitives: the composing executor 25 authenticates carriers, enforces profile budgets and retains preimages before 26 signing or transport. No private key is exported or message published. 27 28 With both `signing` and `nip17`, `signing::gift_wrap::wrap_retained_seal` 29 authenticates an already obtained kind-13 seal and wraps its exact original 30 bytes. It accepts an explicit positive time and qualified entropy source, 31 creates a separate temporary key, and never invokes the participant signer. 32 The complete nested budget is checked before entropy; randomized timestamps, 33 nonce generation and signing auxiliary randomness use the injected source. 34 `PendingGiftWrap` retains the exact outer bytes and temporary key for independent 35 protected-capture verification, with redacted diagnostics and no cloning or 36 automatic serialization. The caller must retain the envelope and its original 37 operation, recipient and route binding before transport. This primitive grants 38 no scheduling authority and proves no durable capture or relay observation. 39 40 Run `cargo extbuild run -- cargo run -p radroots_nostr --example 41 participant_private --features signing,nip17 --locked` for the native OS-entropy 42 smoke. It uses published synthetic vector identities, encrypts twice and 43 decrypts both results without persistence or network effects. 44 45 This crate owns no relay client. It owns no sockets, HTTP client, relay pool, 46 database, account store, retry loop, scheduler, executor, or process-global 47 state. Live Nostr transport belongs in `radroots_transport_nostr`; application 48 composition belongs in `radroots_sdk` or an advanced host. 49 50 The authoritative package charter is the 51 [`radroots_nostr` section of the Release V1 specification](../../contracts/crates/release_v1/radroots_crates_release_v1.toml). 52 53 ## Quick start 54 55 Convert a canonical Radroots public key to and from its NIP-19 `npub` 56 representation: 57 58 ```rust 59 use radroots_identity::PublicKey; 60 use radroots_nostr::key::{public_key_from_npub, public_key_to_npub}; 61 62 let public_key = PublicKey::from_hex( 63 "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798", 64 )?; 65 let npub = public_key_to_npub(public_key)?; 66 67 assert_eq!(public_key_from_npub(&npub)?, public_key); 68 # Ok::<(), Box<dyn core::error::Error>>(()) 69 ``` 70 71 The same flow is available as a standalone example: 72 73 ```sh 74 cargo run -p radroots_nostr --example identity_conversion 75 ``` 76 77 ## Public boundary 78 79 The durable public modules are organized by responsibility: 80 81 - `event` converts event identifiers, coordinates, and signed NIP-01 values. 82 - `filter` constructs explicit Nostr subscription filters. 83 - `key` converts public identities, provides NIP-19 helpers, and—with 84 `signing`—owns opaque local secret-key handling and NIP-49 operations. 85 - `tag` converts ordered tag parts and exposes focused tag inspection helpers. 86 - `signing` implements `radroots_signing::Signer` for local Nostr keys. 87 - `nip17` wraps and unwraps typed Radroots message events with NIP-17/NIP-59. 88 - `blossom` signs and verifies BUD-11 HTTP authorization values. 89 90 `Error` is the only intended root export. Protocol representations that must 91 cross the adapter are exposed from the module that owns the conversion, rather 92 than through a root prelude or wildcard alias set. 93 94 ## Event model and typed authoring 95 96 Canonical product drafts and verified events belong to `radroots_event`. 97 Encoding, signature verification, contract admission, and typed inbound 98 projection belong to `radroots_event_codec`. This crate performs the explicit 99 translation to or from Nostr protocol values. 100 101 With `events`, typed builders cover the supported Profile, Update, 102 PhotoUpdate, Ask, Reply, Comment, deletion-request, NIP-52 date/time Event, and 103 FoodAvailability authoring profiles. Sealed focused builders fix the event kind and canonical 104 tag model before signer access. Generic builders reject reserved typed kinds; 105 relaying an already signed event is a transport operation and does not grant a 106 typed Radroots authoring claim. 107 108 Conversion and verification are deterministic for their inputs. Inbound 109 admission proves the received event and its typed projection; it does not prove 110 that referenced events, authors, addresses, relays, or external resources 111 exist. 112 113 `event::EventAdapter` preserves the original numeric wire kind in its borrowed 114 and owned job conversions, including named Nostr kinds such as feedback kind 115 7000. The job decoder separately enforces its supported kind; conversion does 116 not establish event authenticity or job admission. 117 118 ## Local signing 119 120 The `signing` feature provides an opaque `key::SecretKey` and a concrete local 121 signer adapter. Secret-bearing values are single-owner, are not serializable, 122 and always redact `Debug` output. Public identities are converted to the 123 canonical `radroots_identity::PublicKey` boundary before they leave the 124 adapter. 125 126 NIP-19 `nsec` export and NIP-49 encryption/decryption are explicit operations. 127 `secret_key_to_nsec` deliberately returns plaintext secret material; callers 128 must treat that string as a credential, avoid logs and serialization, and 129 zeroize or discard it promptly. Password, ciphertext, and plaintext failures 130 are normalized so error values do not retain caller-supplied secret text. 131 132 ## Side effects, cancellation, and commit points 133 134 This crate performs in-memory parsing, validation, encoding, cryptography, and 135 local signing only. It never opens a network connection, writes a file or 136 database, selects an account, publishes an event, or installs a runtime. 137 138 Some cryptographic adapters are async because their upstream protocol 139 operations are async. Local key-backed work returns an in-memory result, while 140 an injected upstream signer may invoke external custody. Dropping its observer 141 does not prove that no artifact was obtained remotely. The protocol-only 142 multi-recipient helper is not a durable issuance journal: an earlier recipient 143 may already have an obtained seal when a later request fails. The composing 144 executor must retain each disposition and exact obtained result. Transport and 145 storage owners supply their own publication and durable commit semantics. 146 147 The `blossom` module converts exact, verified signer output into and from 148 signed `Authorization: Nostr` values but never sends an HTTP request. BUD-11 149 plans remain distinct from relay-authored plans. The `nip17` module creates and 150 opens gift-wrap events. It does not select relays, deliver events, retry 151 operations, or persist message state. 152 153 Opening verifies the bounded outer event and its single recipient before any 154 signer callback, then authenticates a closed empty-tag kind13 seal. It checks 155 NIP-44 v2 framing, identity continuity, complete24KiB rumors and depth16, raw 156 u16 kinds before upstream conversion, required canonical IDs and author/recipient 157 bindings. The original rumor ID is recomputed rather than trusted. Peer and 158 sender self copies retain the same logical message. Decrypted frames and the 159 temporary parsed rumor are cleared on drop; returned legacy message/file DTOs 160 remain ordinary owned application data. This helper supplies no commerce, 161 durability, consent, stock or current-history authority. Its typed outer input 162 does not recover malformed raw fields already lost by an earlier decoder. 163 Authentic unknown rumor kinds return unsupported after header/ID/author checks; 164 their content and tags are not interpreted as known chat data. 165 166 With `private_ingress`, `private_ingress::open` takes the original raw outer 167 JSON and a captured `ParticipantProvider` call. It shares the exact signed 168 reader with the existing adapter, verifies each carrier before decryption, 169 and retains the original outer, protected seal and identity-checked rumor. 170 Provider-owned custody, MAC validation, deadline and cancellation remain 171 required; the composing host qualifies its actual provider implementation. 172 173 With `commerce`, `commerce::open` additionally checks complete closed kind8890 174 record data, its separate content hash, empty rumor tags, exact author/time, 175 and the actual recipient's buyer/seller membership. Known records and protected 176 authenticated unsupported or rejected outcomes remain distinct. Unknown 177 profiles cannot become known records through a fallback. These values supply 178 cryptographic provenance without granting business authority or executing a 179 durable transition. The owning successor contract is 180 [`commerce_ingress.v1.json`](../../contracts/protocol/commerce_ingress.v1.json). 181 The optional pinned Node fixture producer under `tools/protocol_oracle` is 182 development-only; standalone Rust tests consume checked-in synthetic vectors. 183 184 The local participant adapter implements separately qualified exact-intent 185 recovery through `recover_exact`. It recomputes only the complete original 186 preimage while the original first-issuance window remains open and the current 187 recovery-call budget permits work. A longer call budget cannot renew the original 188 window: the earlier claim may have preceded an invocation that never began. 189 Identity/clock/cancellation refusal retains original uncertainty, and post-effect 190 clock failure cannot discard obtained bytes. This path performs no encryption, 191 route replacement, network call or legacy fallback. After-expiry durable signer 192 retrieval is unavailable. Legacy replay and first-dispatch behavior are unchanged. 193 194 `radroots_signing::commerce::VerifiedCommerceSigningPlan::verify` checks both exact recipient 195 ciphertexts against the original rumor through the selected participant 196 provider, verifies original signed DM advertisements and their selected subsets, 197 and checks the provider's actual replay declaration. It performs no signing or 198 store transaction. Current consent, approved network targets, durable T1 and 199 dispatch permission remain executor obligations. 200 201 ## Serialization contract 202 203 - Canonical durable Radroots data should be serialized through 204 `radroots_event`, `radroots_event_codec`, or versioned `radroots_protocol` 205 contracts. 206 - Explicit Nostr boundary aliases use the upstream NIP-01 JSON representation. 207 - `event::ExternalSigningRequest` serializes only as the standard 208 unsigned Nostr event after reserved-kind and authoring-policy validation. 209 - Returned externally signed events are accepted only when author, canonical 210 event ID, and the complete NIP-01 signature verify against the request. 211 - Secret-bearing key and local-signer values do not implement serialization. 212 213 Deserializing protocol data never establishes product admission, account 214 authority, upload completion, referenced-event existence, or relay trust. 215 216 ## Security guidance 217 218 - Parse untrusted protocol data through the checked conversion/admission 219 functions; do not infer Radroots product validity from a syntactically valid 220 upstream event. 221 - Treat event content, tags, relay hints, Blossom claims, and NIP-17 plaintext 222 as untrusted input even after signature verification. 223 - BUD-11 authorization events are ephemeral credentials for a specific HTTP 224 operation. This crate does not transmit them or manage replay protection for 225 a server. 226 - Typed media descriptors prove bytes and metadata, not successful BUD-02 227 upload. The composing runtime must establish upload completion separately. 228 - NIP-49 protects exported key material at rest; callers still own password 229 handling, ciphertext storage, memory hygiene, and access control. 230 - The crate forbids unsafe code and does not expose a live Nostr client or an 231 ambient authority boundary. 232 233 ## Features 234 235 | Feature | Default | Contract | 236 | --- | --- | --- | 237 | `std` | yes | Enables standard-library support required by selected upstream protocol operations; it adds no network, storage, runtime, or global initialization. | 238 | `events` | yes | Enables typed event builders, deterministic Radroots/Nostr event conversion, and verified event adapters. | 239 | `signing` | no | Adds opaque local secret handling, NIP-49 helpers, draft signing, and the concrete local `radroots_signing::Signer` adapter. | 240 | `nip17` | no | Adds focused NIP-17/NIP-59 typed message and message-file wrapping/unwrapping; no delivery or persistence. | 241 | `private_ingress` | no | Authenticates original raw NIP-59 carriers through participant-owned custody and retains protected evidence. | 242 | `commerce` | no | Adds complete known commerce record admission and protected unsupported/rejected outcomes. | 243 | `blossom` | no | Adds BUD-11 signed HTTP authorization value creation and verification; no HTTP client or endpoint operation. | 244 245 Features are additive. `--no-default-features` provides the portable 246 `no_std + alloc` conversion core. 247 248 ## Intended consumers 249 250 - `radroots_nostr_connect` uses explicit Nostr conversion while owning NIP-46 251 protocol state. 252 - `radroots_transport_nostr` performs live relay I/O behind the generic 253 transport contracts. 254 - `radroots_sdk` composes local or remote signing, storage, and transport. 255 - Myc and `radrootsd` consume focused protocol adapters without moving their 256 host authority into this crate. 257 - Advanced Rust hosts may use this package directly for offline conversion, 258 verification, or a local signer adapter. 259 260 Applications that only need ordinary Radroots workflows should normally use 261 `radroots` or `radroots_sdk`. 262 263 ## Copyright 264 265 Except as otherwise noted, all files in the `radroots_nostr` distribution are 266 267 Copyright (c) 2025 Tyson Lupul 268 269 For information on usage and redistribution, and for a DISCLAIMER OF ALL 270 WARRANTIES, see LICENSE included in the `radroots_nostr` distribution.