lib

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

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.