user-verification-nip05.md (10057B)
1 # Author Verification Design Document 2 3 The relay will use NIP-05 DNS-based author verification to limit which 4 authors can publish events to a relay. This document describes how 5 this feature will operate. 6 7 ## Considerations 8 9 DNS-based author verification is designed to be deployed in relays that 10 want to prevent spam, so there should be strong protections to prevent 11 unauthorized authors from persisting data. This includes data needed to 12 verify new authors. 13 14 There should be protections in place to ensure the relay cannot be 15 used to spam or flood other webservers. Additionally, there should be 16 protections against server-side request forgery (SSRF). 17 18 ## Design Overview 19 20 ### Concepts 21 22 All authors are initially "unverified". Unverified authors that submit 23 appropriate `NIP-05` metadata events become "candidates" for 24 verification. A candidate author becomes verified when the relay 25 inspects a kind `0` metadata event for the author with a `nip05` field, 26 and follows the procedure in `NIP-05` to successfully associate the 27 author with an internet identifier. 28 29 The `NIP-05` procedure verifies an author for a fixed period of time, 30 configurable by the relay operator. If this "verification expiration 31 time" (`verify_expiration`) is exceeded without being refreshed, they 32 are once again unverified. 33 34 Verified authors have their status regularly and automatically updated 35 through scheduled polling to their verified domain, this process is 36 "re-verification". It is performed based on the configuration setting 37 `verify_update_frequency`, which defines how long the relay waits 38 between verification attempts (whether the result was success or 39 failure). 40 41 Authors may change their verification data (the internet identifier from 42 `NIP-05`) with a new metadata event, which then requires 43 re-verification. Their old verification remains valid until 44 expiration. 45 46 Performing candidate author verification is a best-effort activity and 47 may be significantly rate-limited to prevent relays being used to 48 attack other hosts. Candidate verification (untrusted authors) should 49 never impact re-verification (trusted authors). 50 51 ## Operating Modes 52 53 The relay may operate in one of three modes. "Disabled" performs no 54 validation activities, and will never permit or deny events based on 55 an author's NIP-05 metadata. "Passive" performs NIP-05 validation, 56 but does not permit or deny events based on the validity or presence 57 of NIP-05 metadata. "Enabled" will require current and valid NIP-05 58 metadata for any events to be persisted. "Enabled" mode will 59 additionally consider domain whitelist/blacklist configuration data to 60 restrict which author's events are persisted. 61 62 ## Design Details 63 64 ### Data Storage 65 66 Verification is stored in a dedicated table. This tracks: 67 68 * `nip05` identifier 69 * most recent verification timestamp 70 * most recent verification failure timestamp 71 * reference to the metadata event (used for tracking `created_at` and 72 `pubkey`) 73 74 ### Event Handling 75 76 All events are first validated to ensure the signature is valid. 77 78 Incoming events of kind _other_ than metadata (kind `0`) submitted by 79 clients will be evaluated as follows. 80 81 * If the event's author has a current verification, the event is 82 persisted as normal. 83 * If the event's author has either no verification, or the 84 verification is expired, the event is rejected. 85 86 If the event is a metadata event, we handle it differently. 87 88 We first determine the verification status of the event's pubkey. 89 90 * If the event author is unverified, AND the event contains a `nip05` 91 key, we consider this a verification candidate. 92 * If the event author is unverified, AND the event does not contain a 93 `nip05` key, this is not a candidate, and the event is dropped. 94 95 * If the event author is verified, AND the event contains a `nip05` 96 key that is identical to the currently stored value, no special 97 action is needed. 98 * If the event author is verified, AND the event contains a different 99 `nip05` than was previously verified, with a more recent timestamp, 100 we need to re-verify. 101 * If the event author is verified, AND the event is missing a `nip05` 102 key, and the event timestamp is more recent than what was verified, 103 we do nothing. The current verification will be allowed to expire. 104 105 ### Candidate Verification 106 107 When a candidate verification is requested, a rate limit will be 108 utilized. If the rate limit is exceeded, new candidate verification 109 requests will be dropped. In practice, this is implemented by a 110 size-limited channel that drops events that exceed a threshold. 111 112 Candidates are never persisted in the database. 113 114 ### Re-Verification 115 116 Re-verification is straightforward when there has been no change to 117 the `nip05` key. A new request to the `nip05` domain is performed, 118 and if successful, the verification timestamp is updated to the 119 current time. If the request fails due to a timeout or server error, 120 the failure timestamp is updated instead. 121 122 When the the `nip05` key has changed and this event is more recent, we 123 will create a new verification record, and delete all other records 124 for the same name. 125 126 Regarding creating new records vs. updating: We never update the event 127 reference or `nip05` identifier in a verification record. Every update 128 either reset the last failure or last success timestamp. 129 130 ### Determining Verification Status 131 132 In determining if an event is from a verified author, the following 133 procedure should be used: 134 135 Join the verification table with the event table, to provide 136 verification data alongside the event `created_at` and `pubkey` 137 metadata. Find the most recent verification record for the author, 138 based on the `created_at` time. 139 140 Reject the record if the success timestamp is not within our 141 configured expiration time. 142 143 Reject records with disallowed domains, based on any whitelists or 144 blacklists in effect. 145 146 If a result remains, the author is treated as verified. 147 148 This does give a time window for authors transitioning their verified 149 status between domains. There may be a period of time in which there 150 are multiple valid rows in the verification table for a given author. 151 152 ### Cleaning Up Inactive Verifications 153 154 After a author verification has expired, we will continue to check for 155 it to become valid again. After a configurable number of attempts, we 156 should simply forget it, and reclaim the space. 157 158 ### Addition of Domain Whitelist/Blacklist 159 160 A set of whitelisted or blacklisted domains may be provided. If both 161 are provided, only the whitelist is used. In this context, domains 162 are either "allowed" (present on a whitelist and NOT present on a 163 blacklist), or "denied" (NOT present on a whitelist and present on a 164 blacklist). 165 166 The processes outlined so far are modified in the presence of these 167 options: 168 169 * Only authors with allowed domains can become candidates for 170 verification. 171 * Verification status queries additionally filter out any denied 172 domains. 173 * Re-verification processes only proceed with allowed domains. 174 175 ### Integration 176 177 We have an existing database writer thread, which receives events and 178 attempts to persist them to disk. Once validated and persisted, these 179 events are broadcast to all subscribers. 180 181 When verification is enabled, the writer must check to ensure a valid, 182 unexpired verification record exists for the auther. All metadata 183 events (regardless of verification status) are forwarded to a verifier 184 module. If the verifier determines a new verification record is 185 needed, it is also responsible for persisting and broadcasting the 186 event, just as the database writer would have done. 187 188 ## Threat Scenarios 189 190 Some of these mitigations are fully implemented, others are documented 191 simply to demonstrate a mitigation is possible. 192 193 ### Domain Spamming 194 195 *Threat*: A author with a high-volume of events creates a metadata event 196 with a bogus domain, causing the relay to generate significant 197 unwanted traffic to a target. 198 199 *Mitigation*: Rate limiting for all candidate verification will limit 200 external requests to a reasonable amount. Currently, this is a simple 201 delay that slows down the HTTP task. 202 203 ### Denial of Service for Legitimate Authors 204 205 *Threat*: A author with a high-volume of events creates a metadata event 206 with a domain that is invalid for them, _but which is used by other 207 legitimate authors_. This triggers rate-limiting against the legitimate 208 domain, and blocks authors from updating their own metadata. 209 210 *Mitigation*: Rate limiting should only apply to candidates, so any 211 existing verified authors have priority for re-verification. New 212 authors will be affected, as we can not distinguish between the threat 213 and a legitimate author. _(Unimplemented)_ 214 215 ### Denial of Service by Consuming Storage 216 217 *Threat*: A author creates a high volume of random metadata events with 218 unique domains, in order to cause us to store large amounts of data 219 for to-be-verified authors. 220 221 *Mitigation*: No data is stored for candidate authors. This makes it 222 harder for new authors to become verified, but is effective at 223 preventing this attack. 224 225 ### Metadata Replay for Verified Author 226 227 *Threat*: Attacker replays out-of-date metadata event for a author, to 228 cause a verification to fail. 229 230 *Mitigation*: New metadata events have their signed timestamp compared 231 against the signed timestamp of the event that has most recently 232 verified them. If the metadata event is older, it is discarded. 233 234 ### Server-Side Request Forgery via Metadata 235 236 *Threat*: Attacker includes malicious data in the `nip05` event, which 237 is used to generate HTTP requests against potentially internal 238 resources. Either leaking data, or invoking webservices beyond their 239 own privileges. 240 241 *Mitigation*: Consider detecting and dropping when the `nip05` field 242 is an IP address. Allow the relay operator to utilize the `blacklist` 243 or `whitelist` to constrain hosts that will be contacted. Most 244 importantly, the verification process is hardcoded to only make 245 requests to a known url path 246 (`.well-known/nostr.json?name=<LOCAL_NAME>`). The `<LOCAL_NAME>` 247 component is restricted to a basic ASCII subset (preventing additional 248 URL components).