- Docs
- Nostrfi Relay
- Operations
- Moderation
Moderation
How moderation works
The relay implements the ban-list and role parts of the
NIP-86 relay management API.
Requests are JSON-RPC POST requests to the relay's own URL, with
Content-Type: application/nostr+json+rpc, authenticated with a NIP-98
signature from the owner's key or an administrator's key.
You can call the API from the admin dashboard
or from any NIP-98-capable tool, such as nak. The dashboard forwards your
signed request unchanged, so the relay authorizes it the same way either way.


Methods
| Method | Effect |
|---|---|
banpubkey / unbanpubkey / listbannedpubkeys | Rejects future publishes from a pubkey with blocked:. Events it already published stay served unless you ban them separately. |
banevent / allowevent / listbannedevents | Hides an event from REQ results. The row is kept, so allowevent reverses it. |
blockip / unblockip / listblockedips | Rejects new WebSocket connections from an IP address or CIDR range with 403. |
assignrole / unassignrole | Grants or revokes the admin role. Owner only. See administrators. |
listroleassignments | Lists the owner and every administrator. Owner only. Specific to this relay. |
whoami | Returns the caller's own pubkey and role. Specific to this relay. |
supportedmethods | Lists the methods above. |
Allow-list, custom-role (createrole and similar), kind-filter, and
relay-metadata methods are not implemented.
Administrators
The owner is the key in moderation.admin_pubkey, which defaults to the
relay's NIP-11 pubkey. Since 0.3.0 the owner can grant administrator rights
to other pubkeys, so a team can run a relay without sharing the owner's key.
Administrators sign every request with their own key.
| Operator API | Owner | Administrator |
|---|---|---|
Ban-list methods, supportedmethods, whoami | Yes | Yes |
| Event browse and statistics APIs | Yes | Yes |
assignrole, unassignrole, listroleassignments | Yes | No (403) |
| Configuration API | Yes | No (403) |
An administrator calling an owner-only method gets 403 with
{"error": "forbidden", "reason": "owner only"}.
admin is the only role:
{"method": "assignrole", "params": ["<64-char-lowercase-hex-pubkey>", "admin", "optional label"]}
{"method": "unassignrole", "params": ["<64-char-lowercase-hex-pubkey>", "admin"]}
The optional third assignrole parameter is a label of up to 100 characters.
It is specific to this relay; NIP-86 defines only the first two. Granting the
role again replaces the label.
listroleassignments returns the owner first, then each administrator with
its label, who granted it, and when. whoami returns the caller's own role.
A key that holds no role gets the usual generic 401, so whoami can't be
used to find out who the administrators are.
Grants are stored in the relay's database, so they survive restarts and are included in backups. A revocation takes effect on the revoked key's next request. The owner always comes from configuration and can't be granted, revoked, or removed through the API.
What an administrator can do
Administrators can read every stored event through the event browser,
including encrypted direct messages and gift wraps (as ciphertext only). They
can ban any pubkey or event and block any IP range, including the owner's
pubkey or 0.0.0.0/0. Bans and blocks apply to publishing and WebSocket
connections, never to the operator APIs, so an administrator can't lock the
owner out of management. The owner can undo anything an administrator does
with the matching unban, allow, or unblock call.
Grant the role only to people you would trust with that access.
Changing the owner key
If you change moderation.admin_pubkey, the new key is the owner from the
next start.
- Administrators granted by the old owner keep their role. The relay logs a
warning at start for each one. If you rotated the key because it may have
been compromised, check the list with
listroleassignmentsandunassignroleany grant you didn't make. - A stored grant for the new owner's own key is deleted at start.
Authentication
Each request needs an Authorization: Nostr <base64> header containing a
signed kind 27235 event. Its payload tag must be the SHA-256 of the exact
request body. The relay rejects the request with 401 if the signature,
tags, or freshness (60 seconds by default) fail, or if the signer is neither
the owner nor an administrator.
Since 0.3.0, two more checks bind each signature to this relay and to one request:
- The
utag must name this relay's origin, not just the right path. The origin comes frommoderation.api_origin, or else fromauth.relay_url(wss://becomeshttps://). It is read from configuration, not from the request, so it holds behind a TLS proxy. This stops a malicious website from getting your signer to sign a request and replaying it at the relay. - Each signed event is accepted once. A second use within the freshness
window gets the same
401as an unknown key. A client that repeats a call quickly must vary the event; the dashboard adds a randomnoncetag. The record of used events is kept in memory, so a restart clears it.
auth.relay_url nor moderation.api_origin set, the relay logs
a warning at startup and refuses every operator request, including
dashboard sign-in. Set auth.relay_url to the relay's public wss:// URL.
For local development against the dashboard's dev server, set
moderation.api_origin: "http://localhost:3000".Validation
- Pubkeys and event IDs must be 64-character lowercase hex.
npub/noteforms, prefixes, and uppercase hex are rejected. - IP blocks must be a valid IPv4 or IPv6 address or CIDR range.
- The optional reason is at most 500 characters and can't be only whitespace.
A rejected call stores nothing and returns an {"error": "..."} response.
Accountability
Every management call, successful or not, is logged with the method, the
operator's pubkey and role, the outcome, and, for role changes, the target
pubkey. A successful whoami is not logged, because it changes nothing and
runs at every dashboard sign-in. Logs never include event content,
private keys, or the raw request body.
Limits
- Moderation acts on this relay only. It can't stop the same content being published to other relays.
- IP blocks match the address the relay sees. Behind the documented TLS proxy, that is the proxy's address, so IP blocks are not effective there yet. See current limitations.
- Abuse reports go to the contact address in the relay's NIP-11 document and are triaged by the operator.
Previous
Event browserNext
Observability