NIP-XX: Relay Access Control via Authentication Callbacks #2311

Problem

NIP-42 defines how a client authenticates its identity to a relay, but says nothing about what happens after authentication. Today, relay operators who want to restrict access — for example, to paying subscribers or token holders — must either:

1. Hard-code an allowlist of pubkeys into relay configuration, or
2. Build custom relay software with embedded access logic.

Both approaches are brittle and couple access policy to relay implementation. Every relay that wants gated access reinvents its own solution.

Proposal

Standardize a protocol for relays to delegate access control decisions to an external Access Control Service (ACS) via HTTP callbacks after NIP-42 authentication.

The flow:

1. Client connects and completes NIP-42 auth (kind 22242 signed event)
2. Relay verifies the signature, extracts the pubkey
3. Relay calls POST /check-access on the ACS with the authenticated pubkey and action (connect, read, or write)
4. ACS responds with { "allowed": true/false, "reason": "...", "expires_at": ... }
5. Relay grants or restricts access, using restricted: prefixed messages per NIP-42

The ACS response can optionally include accessible_pubkeys (restrict to events from specific authors) and restricted_kinds (restrict to specific event kinds), enabling fine-grained per-user filtering.

Use Cases

• Subscription-gated relays — a creator platform checks a billing database to verify the subscriber has an active subscription before granting read access to premium content
• Token-gated relays — a community relay verifies the user holds ecash tokens from a specific Cashu mint
• Group membership — a relay checks an external directory to verify the user belongs to a specific organization
• Tiered access — different users see different content on the same relay based on their subscription tier or role

Relation to Existing NIPs

Reference Implementation

A working implementation of the ACS is open-source at Nostreon/relay-auth. It is running in production as part of a creator platform with:

• Dual-relay architecture: public relay (open read) + gated relay (NIP-42 required for read and write)
• ACS endpoints: POST /check-access for boolean subscription checks, POST /accessible-creators for per-creator filtering
• Reverse proxy connecting the relay and ACS

The repo includes the full ACS service, Docker setup, and example relay/proxy configuration.

Draft Spec

A full draft specification is available and will be submitted as a PR once this issue has an assigned number. It covers:

• ACS HTTP API (POST /check-access request/response format)
• Relay behavior for connection, read, and write gating
• Response caching via expires_at
• NIP-11 access_control field for client discovery
• Client behavior guidelines
• Security considerations