profile-metadata.md (10922B)
1 # Profile metadata contract 2 3 Status: canonical 4 5 This contract defines the public kind-`0` Profile metadata boundary used by 6 Radroots strict authoring and tolerant inbound projection. It is based on the 7 pinned NIP-01, NIP-05, and NIP-24 documents at NIPs commit 8 `bdfa7e62ef87fcfcb992b1a27aee49d36b0b4f91` and the Blossom protocol at commit 9 `b5bd2801d1763aa635fc8fea7a76597e0eb18990`. 10 11 ## Operation authority 12 13 | Operation | Boundary | Signing | Transport | 14 | --- | --- | --- | --- | 15 | `event.verify_nip01` | exact identifier and Schnorr verification to a non-forgeable wrapper | NIP-01 | none | 16 | `event.select_head` | NIP-01 replaceable/addressable timestamp and lowest-id selection | none | none | 17 | `profile.build_authored_draft` | strict authored metadata to kind-`0` wire parts | none | none | 18 | `profile.parse_inbound_metadata` | JSON object to tolerant inbound metadata | none | none | 19 | `profile.verify_and_admit_event` | verified exact kind-`0` envelope to tolerant metadata bound to that envelope | NIP-01 | none | 20 21 `profile.parse_inbound_metadata` is a content parser, not an event-acceptance 22 boundary. A caller must supply content from a kind-`0` event only after the 23 event identifier and signature have been verified. The authoritative combined 24 boundary is `profile.verify_and_admit_event`: it recomputes the identifier, 25 verifies the Schnorr signature, requires exact kind `0`, and only then invokes 26 the same tolerant parser. It accepts standard tagless Profile events and does 27 not require a Radroots marker tag. 28 29 `event.verify_nip01` and its `RadrootsSignatureVerifiedEvent` result are 30 available through the codec's `nostr` feature without enabling `knowledge`. 31 Envelope conversion requires the author to be a valid secp256k1 x-only public 32 key; a canonical-length hex value that is not a curve point returns 33 `malformed_envelope`, not `signature_invalid`. Knowledge contract validation and 34 decoding are a later optional stage and cannot be substituted for general event 35 verification. 36 37 The direct legacy `Profile` codec, Profile-specific Nostr/network 38 publish helpers, and replica Profile draft emission were removed in the 39 `1.0.0-alpha.1` breaking contract. A replica Profile row is a lossy inbound 40 projection and cannot prove author intent for a complete kind-`0` replacement. 41 New authored callers must use `profile.build_authored_draft`. The opaque 42 Radroots generic builder rejects kind `0` at direct-signing and client 43 publication boundaries, so it cannot substitute for Profile operation 44 authority. 45 46 `RadrootsNostrClient` no longer dereferences implicitly to the upstream SDK 47 client, so upstream Profile conveniences are not exposed through ordinary 48 method resolution. `from_inner` and `into_inner`, externally supplied unsigned 49 events and NIP-46 signing, and already-signed event relay remain explicit 50 low-level interoperability boundaries. Their results carry no Radroots typed 51 product-authoring claim; once a caller takes one of those boundaries, upstream 52 protocol behavior is outside the Radroots authored-operation contract. 53 54 Legacy `profile::decode`, Nostr Profile adapters/fetchers, the network Profile 55 fetch methods, and replica Profile ingest remain read-side compatibility paths. 56 They may require or coerce legacy fields, discard unprojected metadata, or rely 57 on legacy marker tags. They are not `profile.parse_inbound_metadata`, do not 58 establish verified event admission, and must not be used as its substitute. 59 60 ## Strict authored boundary 61 62 `AuthoredProfile` has private fields and requires a non-whitespace, 63 control-free `name`, consistent with the NIP-24 recommendation that `name` 64 remain present when `display_name` is used. The scoped optional fields are 65 `display_name`, `about`, `nip05`, `bot`, `picture`, and `banner`; `bot` is a 66 Boolean. NIP-05 values enter only through `Nip05Identifier`. Picture and 67 banner values enter through the shared `AuthoredImage`, which can wrap 68 only an `image/*` `ByteVerifiedDescriptor`. There is no raw-string 69 media setter or unchecked deserialization path. Generic `website`, `lud06`, and 70 `lud16` strings remain outside this strict authored operation. 71 72 Kind `0` is whole-object replaceable. Strict authored output is therefore a 73 complete replacement snapshot, never a patch: every omitted existing standard, 74 residual, or custom field is removed by the replacement. This operation does 75 not merge the tolerant inbound raw object. It is safe for initial Profile 76 creation or an explicitly confirmed full replacement; it must not power a 77 silent partial edit. Retaining an existing picture or banner requires the 78 runtime to re-fetch or retain the bytes, re-establish the byte-verified image 79 descriptor, and satisfy BUD-02 before signing. Until such a full-snapshot edit 80 pipeline exists, clients must keep existing Profile editing read-only. 81 82 The authored codec emits: 83 84 - kind `0` 85 - no tags 86 - one JSON object with fields in this deterministic order when present: 87 `name`, `display_name`, `about`, `picture`, `banner`, `nip05`, `bot` 88 - only the descriptor URL for each media field 89 - at most 131072 UTF-8 bytes of metadata content 90 91 The descriptor state proves that approved descriptor hash, size, and media type 92 match supplied bytes. It does not prove that BUD-02 upload completed or that a 93 blob is network-retrievable, and it does not inspect or sanitize the image 94 format. A publication runtime must require successful BUD-02 completion before 95 signing media-bearing output. A consuming media runtime remains responsible for 96 decode and format-safety policy. 97 98 For two verified kind-`0` events from the same author, the head is the event 99 with the greater `created_at`. Equal timestamps select the lexicographically 100 lowest canonical event id, independent of relay or ingestion arrival order. 101 102 ## Tolerant inbound boundary 103 104 ### Complete-profile edit 105 106 `AuthoredEventPlan::from_profile_edit` adds an explicit registry-v8 107 `radroots.profile.metadata_edit.v1` operation. Registry-v7 defaults, 108 inventories, strict authoring and historical vectors remain unchanged. 109 `ProfileEdit` accepts typed keep/set/clear intent for the seven known fields. 110 Unknown and wrong-typed untouched values remain exact raw JSON values, 111 including nested duplicate names and numeric lexemes. There is no unknown-field 112 or raw-JSON setter. A kept string picture/banner requires a matching 113 byte-verified `AuthoredImage`; unsupported references refuse unless explicitly 114 cleared or replaced. Upload completion and decode safety remain runtime gates. 115 116 The baseline and current head must be verified admitted kind-0 events from the 117 expected author with the same exact event id. Output time must advance; nonempty 118 baseline tags refuse rather than disappear. The runtime must supply its actual 119 canonical head, persist the baseline id and recheck it before signing or side 120 effects. The pure codec comparison does not provide storage CAS. 121 122 Output is a complete tagless replacement, sorted by top-level field name, 123 bounded to 131072 content bytes and 262144 serialized durable-plan bytes. 124 Explicit clear removes a field. A set name retains strict name validation; 125 untouched admitted values retain their original meaning and trust state. 126 Existing initial/full-replacement authoring remains available. 127 128 `profile.parse_inbound_metadata` accepts a JSON object of at most 131072 UTF-8 129 bytes without requiring `name`. Correctly typed `name`, `display_name`, `about`, 130 `picture`, `banner`, `nip05`, and `bot` fields are projected without JSON type 131 coercion; accepted NIP-05 domains are canonicalized as described below. In 132 particular, `bot` must be a JSON Boolean. Every string picture or banner is 133 returned as `RadrootsUnverifiedProfileMediaReference`, including strings that 134 look like valid Blossom hash-path URLs. 135 136 The result retains: 137 138 - the exact input content 139 - the complete parsed object 140 - a residual map containing every unknown field, wrong-typed known field, and 141 syntactically invalid NIP-05 string 142 143 Oversized content is rejected before parsing. Malformed JSON and non-object 144 roots are parse errors. Duplicate top-level metadata keys are rejected because 145 they have ambiguous cross-parser semantics. Optional metadata that this 146 contract does not project, including NIP-24 `website` and birthday data plus 147 `lud06` and `lud16`, remains in the residual and complete raw views. Exact 148 nested JSON text, including any duplicate nested names, remains available 149 through the raw content view. 150 151 ## NIP-05 boundary 152 153 `Nip05Identifier` requires exactly one `@`, a non-empty local part using 154 only lowercase `a-z`, digits, `-`, `_`, or `.`, and an ASCII DNS domain. 155 Domain matching is case-insensitive, so accepted domains are canonicalized to 156 lowercase. Parsing is syntax-only. It performs no HTTPS lookup and never 157 represents verified ownership or identity trust. 158 159 A syntax-checked identifier is not a safe network-fetch target by itself. A 160 future resolver must separately govern HTTPS, redirects, address resolution, 161 loopback/private/link-local targets, response size, and timeouts. 162 163 ## Stable error codes 164 165 The public error enums are non-exhaustive so future codes can be added without 166 making downstream matches exhaustive. Current stable codes are: 167 168 | Boundary | Codes | 169 | --- | --- | 170 | NIP-05 syntax | `missing_separator`, `multiple_separators`, `invalid_local_part`, `invalid_domain` | 171 | strict Profile construction | `invalid_name` | 172 | shared authored image construction | `media_type_not_image` | 173 | strict Profile encoding | `content_too_large` | 174 | tolerant inbound parsing | `content_too_large`, `invalid_json`, `root_not_object`, `duplicate_field` | 175 | NIP-01 event verification | `malformed_envelope`, `kind_out_of_range`, `id_mismatch`, `signature_invalid`, `signature_verification_unavailable` | 176 | verified Profile admission | NIP-01 codes plus `invalid_kind`, `content_too_large`, `invalid_json`, `root_not_object`, `duplicate_field` | 177 178 Inbound size validation occurs before JSON parsing. For content within the 179 limit, malformed JSON returns `invalid_json`; a well-formed non-object returns 180 `root_not_object`; and a well-formed object with a duplicate top-level field 181 returns `duplicate_field`. Wrong-typed projected fields are residual data, not 182 parse errors. 183 184 ## Conformance 185 186 The canonical suite is 187 `contracts/conformance/vectors/profile/metadata.v1.json`. Verified event 188 admission and replacement use 189 `contracts/conformance/vectors/profile/verified_event.v1.json`. Both are 190 mirrored under `crates/event_codec/tests/fixtures/` for published-package 191 tests. The dispatchers execute every vector against the public APIs and require 192 canonical and packaged copies to be byte-for-byte equal when the workspace 193 contract is present. The verified-event suite includes a canonical-id raw event 194 whose author is not a valid secp256k1 curve point, proving the stable 195 `malformed_envelope` mapping. Consumers enable `serde_json` for metadata 196 operations and both `serde_json` and `nostr` for cryptographic Profile 197 admission.