Nostrfi
/Docs
Browse documentation
Owner: NostrfiLast reviewed: 2026-11-16

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.

The moderation page listing a banned pubkey, a banned event, and a blocked IP range, each with a reasonThe moderation page listing a banned pubkey, a banned event, and a blocked IP range, each with a reason
Moderation in the admin dashboard. Every action is signed by your key.

Methods

MethodEffect
banpubkey / unbanpubkey / listbannedpubkeysRejects future publishes from a pubkey with blocked:. Events it already published stay served unless you ban them separately.
banevent / allowevent / listbannedeventsHides an event from REQ results. The row is kept, so allowevent reverses it.
blockip / unblockip / listblockedipsRejects new WebSocket connections from an IP address or CIDR range with 403.
assignrole / unassignroleGrants or revokes the admin role. Owner only. See administrators.
listroleassignmentsLists the owner and every administrator. Owner only. Specific to this relay.
whoamiReturns the caller's own pubkey and role. Specific to this relay.
supportedmethodsLists 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 APIOwnerAdministrator
Ban-list methods, supportedmethods, whoamiYesYes
Event browse and statistics APIsYesYes
assignrole, unassignrole, listroleassignmentsYesNo (403)
Configuration APIYesNo (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 listroleassignments and unassignrole any 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 u tag must name this relay's origin, not just the right path. The origin comes from moderation.api_origin, or else from auth.relay_url (wss:// becomes https://). 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 401 as an unknown key. A client that repeats a call quickly must vary the event; the dashboard adds a random nonce tag. The record of used events is kept in memory, so a restart clears it.
With neither 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/note forms, 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.