NIP-76 Relay Read Permissions

76.md

@@ -0,0 +1,91 @@
+NIP-76
+======
+
+Relay Read Permissions
+----------------------
+
+`draft` `optional`
+
+Tags `rp` (read permission) and `prp` (probabilistic read permission) specify which keys are authorized to download an event from the relay.
+
+Events tagged with `rp` or `prp` require AUTH for download.
+
+## Read Permission
+
+The `rp` tag takes a pubkey in lowercase hex as value. 
+
+```json
+["rp", "<pubkey1>"]
+["rp", "<pubkey2>"]
+["rp", "<pubkey3>"]
+```
+
+When responding to `REQ`s, if an event contains `rp` tags, relays MUST verify that the authenticated user is either the event's author or one of the keys in the `rp` set before delivering it to the client.
+
+## Probabilistic Read Permissions
+
+Probabilistic permissions are implemented using Bloom filters that represent a set of authorized pubkeys. These permissions are expressed as a colon-separated value comprising:
+1. the number of bits in the bit array,
+2. the number of hash rounds applied, and
+3. the bit array encoded in Base64.
+4. the salt encoded in Base64.
+
+```json
+["prp", "<bits>:<rounds>:<base64>:<salt>"]
+```
+
+Bloom filters MUST use `SHA256` functions applied to the concatenation of the key, salt, and index, as demonstrated in the pseudocode below:
+
+```js
+class BloomFilter(size: Int, rounds: Int, buffer: ByteArray, salt: ByteArray) {
+    val bits = BitArray(buffer)
+
+    fun bitIndex(value: ByteArray, index: Byte) {
+        return BigInt(sha256(value || salt || index)) % size
+    }
+
+    fun add(pubkey: HexKey) {
+        val value = pubkey.hexToByteArray()
+
+        for (index in 0 until rounds) {
+            bits[bitIndex(value, index)] = true 
+        }
+    }
+
+    fun mightContains(pubkey: HexKey): Boolean {
+        val value = pubkey.hexToByteArray()
+
+        for (index in 0 until rounds) {
+            if (!bits[bitIndex(value, index)]) {
+                return false
+            }
+        }
+
+        return true
+    }
+
+    fun encode() {
+        return size + ":" + rounds + ":" + base64Encode(bits.toByteArray()) + ":" + base64Encode(salt) 
+    }
+
+    fun decode(str: String): BloomFilter {
+        val [sizeStr, roundsStr, bufferB64, saltB64] = str.split(":")
+        return BloomFilter(sizeStr.toInt(), roundsStr.toInt(), base64Decode(bufferB64), base64Decode(saltB64))
+    }
+}
+```
+
+When responding to `REQ`s, if an event contains `prp` tags, relays MUST verify that the authenticated user is either the event's author or matches any of the filters before delivering it to the client.
+
+If both `rp` and `prp` tags are present, the authenticated user MUST either be in the `rp` set or match any `prp` filter.
+
+### Test cases
+
+The filter below has 100 bits and uses 10 rounds of hashing, which should be capable of handling up to 10,000,000 keys without producing any false positives.
+
+```json
+["prp", "100:10:AAAkAQANcYQFCQoB:hZkZYqqdxcE="]
+```
+
+It includes keys `ca29c211f1c72d5b6622268ff43d2288ea2b2cb5b9aa196ff9f1704fc914b71b` and `460c25e682fda7832b52d1f22d3d22b3176d972f60dcdc3212ed8c92ef85065c`
+