Download the PHP package innis/nostr-relay without Composer

innis/nostr-relay

AMPHP-based async WebSocket relay server for Nostr protocol

A private, high-performance Nostr relay implementation designed to be embedded in PHP applications. Built with AMPHP for concurrent connection handling and clean architecture principles.

Features

• Interface-driven design - Storage and policies provided by host application
• AMPHP async - Non-blocking concurrent connection handling
• Private relay focus - Built for single-user/controlled access scenarios
• NIP-01 compliant - EVENT, REQ, CLOSE message handling
• NIP-09 deletion - Kind 5 event processing
• NIP-11 support - Relay information document
• NIP-40 expiration - An already-expired event is refused, and an event that expires while stored is withheld from REQ results
• NIP-42 AUTH - Challenge/response authentication over nostr-core's Nip42Validator; a challenge is issued only when a subscription exceeds guest scope (never on connect), and the client's live subscriptions are re-evaluated once it authenticates
• NIP-45 COUNT - COUNT message support
• Ephemeral events - Kinds 20000-29999 skip storage
• Host-owned HTTP server - The relay is an Amp\Http\Server\RequestHandler you mount on your own HttpServer, so the host controls binding, middleware (CORS, forwarded headers, compression) and lifecycle, and serves its own routes on the same origin
• NIP-11 metadata - Served from a single Nip11InfoProviderInterface: the built-in StaticNip11InfoProvider for a fixed document, or a custom implementation to compute it at runtime
• Built-in RelayPolicy - Configurable tenant/guest permissions
• Real-time distribution - Events broadcast to matching subscriptions
• Metrics - RelayInstance::getMetrics() returns a RelayMetrics snapshot (active connections, events received/sent, subscriptions, start time) via the MetricsCollectorInterface port
• Rate limiting - DDoS protection with configurable limits; tenants (and trusted clients via isRateLimitExempt()) bypass
• Idle timeout - Connections with no inbound message for 5 minutes are closed, freeing the slot (see ADR-0005)
• PSR-3 logging - Standard logging interface

Requirements

• PHP 8.4 or higher
• innis/nostr-core - Core Nostr protocol entities
• amphp/amp ^3.0 - Async runtime
• amphp/http-server ^3.0 - HTTP server
• amphp/websocket-server ^4.0 - WebSocket server
• psr/log ^3.0 - Logging interface

Installation

Quick Start

1. Implement Required Interfaces

The relay requires these interfaces from your host application:

• RelayEventStoreInterface - Event persistence and queries. Use the built-in InMemoryEventStore to run a relay locally or to give a test a real store; it keeps everything in process memory and matches linearly, so a deployment supplies a durable implementation. It implements the replaceable and addressable rules, so storing a newer version of such an event removes the one it supersedes and storing an older one is refused as Superseded. countByFilters returns nostr-core's EventCount: a store that stops counting at a ceiling reports the count as approximate, and the relay marks the NIP-45 reply accordingly (see ADR-0013).
• RelayConfigInterface - The relay's own configuration: the relay URL (for NIP-42 AUTH verification) and the maximum concurrent connections. The listening address and trusted proxies are configured on the HttpServer the host owns, not here.
• RateLimitPolicyInterface - Per-minute rate-limit budgets keyed by RateLimitMetric (events, subscriptions). Use the built-in StaticRateLimitPolicy for fixed limits, or implement the interface to vary limits at runtime.
• Nip11InfoProviderInterface - The single source of the relay's NIP-11 document. Wrap a fixed document in the built-in StaticNip11InfoProvider, or implement the interface to project metadata at runtime (e.g. reflecting live policy).

Access control can use the built-in RelayPolicy or a custom implementation of RelayPolicyInterface. See Implementing RelayPolicyInterface for how a policy signals a rejection.

Optional interfaces extend the relay's behaviour:

• ConnectionGateInterface - Decide whether an IP may connect, before the WebSocket session is established. Defaults to allowing every IP; implement it to enforce an allow-list or deny-list.
• MetricsCollectorInterface - Collect relay metrics (connections, events, subscriptions). Defaults to the in-memory InMemoryMetricsCollector exposed via RelayInstance::getMetrics(); implement it to export to an external monitoring system.

2. Create and Start the Relay

The host owns the HttpServer, so it decides the listening address, middleware and lifecycle, and mounts the relay's request handler on it. Owning the server is what lets the host serve its own routes — a landing page, a management API, static files — on the same origin as the relay:

See examples/relay.example.php for a complete runnable relay: tenant/guest policy, rate limiting, NIP-11 metadata and a stderr logger, on the built-in InMemoryEventStore.

3. Configure Nginx

The relay does not handle TLS. Use a reverse proxy for SSL. If the proxy sets X-Forwarded-For, configure the trusted proxies on the HttpServer the host owns — amphp's ForwardedMiddleware honours the header only for a matching proxy address. The relay reads the client IP from the request the server hands it, so honouring forwarded headers from an untrusted source lets any client spoof their IP; only trust a proxy you control.

Policy Configuration

The built-in RelayPolicy accepts a configuration array that controls access for tenants and guests.

Tenants

tenants: array of hex pubkeys or npub strings identifying relay owners. Tenants authenticate via NIP-42 and bypass all guest restrictions, along with the rate limits and the subscription and filter caps. max_query_limit is the exception: every filter is clamped to it whoever asks, so a tenant reading more than the ceiling pages through it with until (see ADR-0019). If the array is empty or omitted, the relay operates as an open relay (all writes and reads allowed).

Limits

Optional keys with sensible defaults:

• max_subscriptions - Maximum concurrent subscriptions per client. Also gates COUNT requests: a COUNT from a client already at the cap is rejected with blocked: too many subscriptions (see ADR-0006).
• max_filters - Maximum filters per subscription
• max_event_size - Maximum event payload size in bytes
• max_query_limit - The ceiling on how many stored events one filter may return. Every filter is clamped to it, and a filter stating no limit of its own is given it, so a client asking for more receives the ceiling rather than a refusal (see ADR-0017). Publish it as max_limit in your relay-information document.

Implementing RelayPolicyInterface

A policy answers "may this client do this?" by returning an outcome — it never throws to reject. allowEventSubmission() and allowSubscription() both return ?PolicyRejection:

• Return null to admit.
• Return PolicyRejection::blocked($reason) for a definitive refusal.
• Return PolicyRejection::authRequired($reason) when authenticating could change the answer. The relay additionally sends the client an AUTH challenge alongside the refusal, so it can authenticate and retry.
• Return PolicyRejection::rateLimited($reason) when the client is asking too often, PolicyRejection::invalid($reason) when the event cannot be accepted on its own terms, and PolicyRejection::restricted($reason) when this relay is not open to the client at all.

The port has seven methods, and every one of them is yours to answer:

The relay frames the rejection as the wire reply that matches the client's message: OK for an EVENT, CLOSED for a REQ or COUNT. You do not construct wire messages yourself.

Rejections are returned rather than thrown so the analyser forces every caller to handle them — see ADR-0015. Genuine faults are still exceptions: a structurally invalid or badly-signed event raises InvalidEventException from the core validator, which the relay catches and reports as invalid:.

offersAuthChallenge() is separate from rejection: it lets a policy admit an event and still invite the client to authenticate (see ADR-0011). The built-in policy returns false.

Rate-Limit Exemption

RelayPolicyInterface::isRateLimitExempt() lets the policy opt specific clients out of rate limits and subscription caps. The built-in RelayPolicy exempts authenticated tenants only; rate limits apply to every untrusted client, including on an open relay (see ADR-0019). Implement RelayPolicyInterface directly to exempt other trusted clients — for example, internal services or IPs behind a trusted proxy.

Guest Rules

Unauthenticated clients are treated as guests. Guest permissions are defined under the guest key:

guest.read: array of rules controlling what events guests can query. Each rule has:

• kinds (int array) - Event kinds the guest may read
• from (optional, 'tenants') - Restrict results to events authored by tenants

Guests may read every kind only when guest.read is left out altogether. Once the section is present, guests read exactly the kinds its rules list and nothing else — so an empty section, or rules listing no valid kinds, means guests read nothing (see ADR-0012).

guest.write: array of rules controlling what events guests can publish. Each rule has:

• kinds (int array) - Event kinds the guest may publish
• tagged_to_tenant (optional, true) - Require the event to tag a tenant pubkey

If no config is passed, the relay is fully open with no restrictions.

Authentication (NIP-42)

The relay does not challenge on connect. It issues an AUTH challenge only when a subscription requests something outside the guest's scope — when the requested kinds aren't guest-readable, when the requested authors aren't tenants (under from = 'tenants'), or when the filter reads a tenant's mailbox (a #p tag referencing a tenant). The challenge is an offer: a client that authenticates gains full scope, while a client that ignores it still receives the guest-scoped results. The connection is never blocked for not authenticating. (Why a scope-exceeding request rather than every connection: see ADR-0004.)

When a client authenticates, its already-open subscriptions are re-evaluated against its new scope: each is re-admitted with its original filters and the now-visible stored events are streamed, so a subscription opened as a guest widens automatically without the client having to re-subscribe (see ADR-0016).

Architecture

Relay Handles:

• WebSocket session handling (as a request handler mounted on the host's server)
• Message parsing (EVENT, REQ, CLOSE, AUTH, COUNT)
• NIP-42 authentication (challenge/response)
• NIP-09 deletion (kind 5 event processing)
• Ephemeral event handling (kinds 20000-29999)
• Subscription management and limits
• Filter matching and event distribution
• Rate limiting

Host Application Handles:

• The HTTP server: binding, middleware (CORS, forwarded headers, compression) and start/stop lifecycle
• Event storage and queries
• Access control policies (use built-in RelayPolicy or implement RelayPolicyInterface directly)
• Relay configuration (RelayConfigInterface)
• NIP-11 metadata (Nip11InfoProviderInterface — built-in StaticNip11InfoProvider, or implement for runtime-computed metadata)
• Any additional routes served on the same origin (landing page, management API, static files)

Testing

Runs the Unit, Integration and Acceptance suites, then the soak harness (tools/soak-harness.php), then PHPStan level 9 static analysis. composer test-unit runs the Unit suite alone; composer soak the harness alone.

Manual testing with websocat:

Performance

The relay is designed for concurrent connection handling. Concrete throughput, latency, and memory figures depend on the host's event store and hardware and are not benchmarked here.

Design choices that bear on performance:

• AMPHP fibres for concurrent clients
• Subscriptions pre-indexed by event kind, so event distribution looks up only the subscriptions whose filters declare a matching kind (plus kind-agnostic filters) rather than scanning every subscription
• Per-event filter matching delegated to nostr-core's Filter
• Non-blocking I/O throughout

License

MIT License. See LICENSE file for details.