# NIP-43 relay membership in geode

Status: implemented (2026-09-27).

PR #4236 added the NIP-86 role / invite-code RPCs (`createrole`, `editrole`,
`deleterole`, `assignrole`, `unassignrole`, `listclaims`, `createclaim`,
`deleteclaim`) and persisted their state in `BanStore` / `RuntimeConfig`, but
nothing consumed that state: geode advertised the methods and they were silent
no-ops. This plan makes them do what NIP-43 says.

## Survey

| Piece | Where | Status |
|---|---|---|
| NIP-43 event models (13534, 33534, 8000, 8001, 28934, 28936) | `quartz/nip43RelayMembers/*` | reused as-is |
| Roles, assignments, claims, allow list | `quartz/nip86RelayManagement/server/BanStore` | reused as-is |
| Local ingest bypassing policies | `NostrServer.ingest(event, skipVerify)` | reused (mirror path) |
| Hook for EVENTs addressed to the relay | — | **new**: `EventCommandHandler` in `quartz/nip01Core/relay/server` |
| Join / leave / republish engine | — | **new**: `quartz/nip43RelayMembers/server/RelayMembershipServer` (generic, any Quartz relay can use it) |
| Members-only write gate | `BanListPolicy` | extended: `membersOnly` |
| Role / claim RPC gating + post-RPC hook | `Nip86Server` | extended: `nip43Methods`, `afterMutation` |
| Relay key, config, NIP-11 `self` | geode `RelayEngine`, `StaticConfig`, `RelayIdentity`, `Main` | geode wiring |

## Decisions

**Membership is the NIP-86 pubkey allow list.** NIP-43 defines 13534 as "pubkeys
that have access to a given relay"; NIP-86's allow list is exactly the set of
pubkeys with write access, and NIP-86 already says `banpubkey` removes a pubkey
from it. Keeping one set avoids two lists drifting apart. So:

- join (28934) = `allowpubkey`; leave (28936) = `unallowpubkey`;
- `allowpubkey`, `unallowpubkey` and `banpubkey` over NIP-86 are membership
  changes and produce 8000 / 8001 + a fresh 13534;
- `[authorization].pubkey_whitelist` seeds the initial members.

**Members-only means closed even when empty.** Plain NIP-86 treats an empty
allow list as "no restriction". With membership on, that would leave a fresh
relay wide open until its first join, and the first join would suddenly close it.
`BanListPolicy(membersOnly = true)` rejects every non-member write with
`restricted: …` regardless of list size. Relay-authored events use
`NostrServer.ingest` and never see the policy; join / leave requests are
consumed before it. Reads are not gated — use NIP-42 + a read policy for that.

**Invite codes are reusable until revoked.** Neither NIP spells out single-use.
NIP-86 calls `listclaims` "invite codes currently accepted by the relay" and
gives revocation its own method (`deleteclaim`); NIP-43 lets users mint claims
(`createclaim`) to share. Consuming a code on first use would make shared invite
links fail for the second person, so a code keeps working until an admin deletes
it. The allow-list reason records which code admitted each pubkey (audit trail).

**Roles are independent of membership.** Assignments live in `BanStore`
regardless of whether the pubkey is currently a member; 13534 lists only members
(with their roles). Leaving keeps assignments, so a returning member gets them
back — role assignment is an operator decision, not the member's.

**Publishing is a reconcile.** `RelayMembershipServer.sync()` diffs the
`BanStore` against what the relay last published (read back from its own store
on first sync, so restarts don't republish) and signs only the difference:
8000 / 8001 per pubkey entering / leaving, one 13534 when members or roles
changed, one 33534 per new / edited role, one NIP-09 kind 5 (`a` =
`33534:<self>:<id>`, `k` = 33534) per deleted role. Every mutation path — join,
admin RPC, a state file edited while offline — converges on the same events, and
repeated syncs are no-ops. The first sync on a fresh relay emits 8000 for each
seeded member (they were added) plus the initial 13534.

Replaceable events are stamped `max(now, previous + 1)` so two edits within one
second still supersede each other (a `created_at` tie would be won by the lower
id, not the newer event), and a re-created role is stamped after its deletion's
tombstone.

**deleterole → NIP-09.** 33534 is addressable; NIP-43 defines no removal, so the
relay deletes the address with a kind 5 it signs itself — the standard way for an
author to retract an addressable event, and what the store already enforces.

**Join / leave run ahead of the policy chain** (`EventCommandHandler`):

- signature and id verified (parallel verify means nothing upstream checked it);
- `created_at` within `[membership].request_window_seconds` (default 300) of now → else `invalid:`;
- join: `claim` tag required → else `restricted:`; banned → `restricted:`; already a member → `OK true "duplicate: …"`; unknown / revoked code → `restricted: that is an invalid invite code.`; success → `OK true "info: welcome to <url>!"`;
- leave: NIP-70 `-` tag required (the spec's MUST) → else `invalid:`; not a member → `OK true "duplicate: …"`; success → `OK true "info: you have left this relay."`;
- neither request is stored or fanned out — a join carries the invite code, and
  both are ephemeral kinds anyway.

They don't require NIP-42 AUTH: the request's signature already proves the
author, and the relay is the recipient rather than a re-publisher (NIP-70's AUTH
rule is about accepting protected events for storage). A captured leave request
could be replayed within the window, which only re-removes the same user.

**Relay identity.** `[identity].secret_key` (nsec or hex) or
`[identity].secret_key_file` (created with a fresh key, mode 0600, if missing).
With membership on and neither set, the key is generated at
`<[admin].state_file>.relay-key`; with no state file either, an in-memory key
is used with a warning. When a key exists, NIP-11 `self` is forced to its pubkey
at boot (overriding a persisted doc). `43` is added to `supported_nips` iff
membership is on — and removed otherwise, since clients only send 28934 to
relays that advertise it.

**Off by default.** `[membership].enabled = false` keeps geode exactly as before
except that the eight role / claim RPCs are no longer advertised or accepted
(`method not supported`) — they were silent no-ops, which is what the review
flagged. Their persisted state is kept untouched in the state file.

## Not done

- Rate limiting join attempts (brute-forcing short invite codes).
- Read gating for members-only relays.
- Kind 28935 (invite request) — deprecated in the current NIP-43.
- Cleaning up 13534 / 33534 signed by a previous relay key after a key change.