floonet-strfry/README.md

floonet-strfry

A hardened, easy-to-deploy strfry relay package for Floonet, the network of Nostr relays for the Grin community. Anyone can run one, and anyone can run a name authority on it so people can claim (and optionally pay GRIN for) a name@domain identity.

strfry core ships stock: the upstream C++ source is cloned at a pinned commit and compiled unmodified. Everything Floonet-specific is layered on through strfry's own extension points:

Piece	What it is
plugin/floonet_writepolicy.py	The write policy plugin: default-deny kind whitelist, optional NIP-42 gate, optional paid-write gate
name-authority/	The bundled name authority (Rust/axum/SQLite): NIP-05 resolution, NIP-98 self-service registration, optional GoblinPay paywall — co-located on the relay's own domain by default
mixexit/	An optional, scoped mixnet exit so wallets can reach this relay over the mixnet
deploy/	strfry conf + Dockerfile + apply-spec.sh, Caddy TLS proxy, landing page, hardened systemd units

Deploy

Pick your comfort level. All three paths produce the same relay.

1. Docker Compose (recommended)

One command brings up the whole unit: relay + name authority + auto-TLS proxy (and, if enabled, the mixnet exit).

cp .env.example .env    # set FLOONET_DOMAIN, FLOONET_BASE_URL, FLOONET_RELAYS
docker compose up -d

DNS for FLOONET_DOMAIN must already point at the host; Caddy obtains the certificate on first start. That is all a free relay needs.

2. apply-spec.sh + systemd (no Docker)

Builds stock strfry at the pinned ref and lays the Floonet conf + plugin on top:

./deploy/strfry/apply-spec.sh          # needs a C++ toolchain + strfry's libs
cd name-authority && cargo build --release

Then install the hardened units from deploy/systemd/ (each unit's header has the exact install commands): floonet-strfry.service, floonet-authority.service and, optionally, floonet-mixexit.service. Put Caddy or nginx in front (see deploy/Caddyfile); the proxy MUST set X-Real-IP, the authority's rate limiting keys off it.

3. From source (developers)

deploy/strfry/Dockerfile and apply-spec.sh document the strfry build exactly; the authority and the exit are plain cargo build crates; the plugin is a single Python file with no dependencies. plugin/test_policy.py and cargo test in name-authority/ run the test suites.

The kind whitelist (the keystone)

The relay is default-deny: the write policy rejects every event whose kind is not explicitly allowed, at every ingest path (client publishes and negentropy sync alike), failing closed on anything malformed. The shipped set is exactly what the Goblin wallet uses:

Kind	Meaning
0	profile metadata
3	contact list
5	deletion (NIP-09)
13	seal (NIP-59)
1059	gift wrap (NIP-59)
10002	relay list (NIP-65)
10050	DM relays (NIP-17)
27235	HTTP auth (NIP-98)

To accept another kind, edit FLOONET_ALLOWED_KINDS in .env and restart the relay. Nothing else changes.

Authentication (NIP-42), optional

Set FLOONET_REQUIRE_AUTH=true in .env and flip relay.auth.enabled to true in deploy/strfry/strfry.conf. strfry then issues AUTH challenges and validates the kind-22242 responses; the plugin rejects writes from unauthenticated connections with an auth-required: message.

Client flow on stock strfry (pinned ref): publish events with a NIP-70 - tag. The first protected publish triggers the AUTH challenge; the client answers with a signed kind-22242 event and republishes. strfry enforces that the event author is the authenticated key and hands that key to the plugin.

Charge GRIN for your relay

Getting paid is editing a few .env keys; prices are yours to set and change, no code involved. You need a running GoblinPay server (your own payment processor; it holds the wallet, produces payment proofs, and hosts the pay pages).

FLOONET_PAY_MODE=name          # or: write
FLOONET_NAME_PRICE_GRIN=1.5    # what a name costs, in GRIN
GOBLINPAY_URL=https://pay.your.domain
GOBLINPAY_TOKEN=<GP_API_TOKEN from your GoblinPay>

Modes:

• off: everything free (default).
• name: claiming name@domain requires payment. The register call answers 402 with a JSON body carrying pay_url (the hosted GoblinPay checkout), invoice_id and the price; the client sends the payer there and retries the same call once the invoice settles. Payment is confirmed against GoblinPay's REST API (which verifies the Grin payment on chain); a paid claim consumes its grant, so releasing the name and claiming another needs a fresh payment.
• write: publishing requires a one-time payment per pubkey. Clients NIP-42 AUTH (grants are per pubkey, see the section above), obtain a quote from POST /api/v1/quote with {"resource": "write"} (NIP-98 signed), pay, and publish. The relay plugin checks grants against the authority and caches verdicts for FLOONET_PAID_CACHE_SECS.

Optionally set GOBLINPAY_WEBHOOK_SECRET and point a GoblinPay webhook at https://your.domain/api/v1/goblinpay/webhook: payments then confirm the moment GoblinPay sees them instead of on the next status poll. The webhook is HMAC-verified and only ever triggers a re-check against the REST API, so a replayed delivery grants nothing.

The relay's public NIP-11 metadata stays neutral in every mode; it carries relay facts, nothing else.

The name authority

Bundled in the package and consulted by the relay plugin; also usable on its own. Names are lowercase a-z0-9._-, start and end alphanumeric, 3 to 20 characters, one active name per pubkey, with a reserved list (generic infra and finance terms, your own domain labels, plus look-alike folding so g0blin cannot impersonate goblin) and an anti-churn cooldown after releasing a name.

Endpoint	Auth	Purpose
GET /.well-known/nostr.json?name=<name>	none	NIP-05 resolution
GET /api/v1/name/{name}	none	availability check
POST /api/v1/register	NIP-98	claim {name, pubkey}; 402 + pay URL in paid mode
DELETE /api/v1/register/{name}	NIP-98	release (owner only)
GET /api/v1/profile/{name}	none	name to pubkey
GET /api/v1/by-pubkey/{pubkey}	none	reverse lookup
GET /api/v1/paid/{pubkey}	none	write-grant status (what the plugin polls)
POST /api/v1/quote	NIP-98	price + pay URL for a paid resource
POST /api/v1/goblinpay/webhook	HMAC	payment confirmation nudge
GET /api/v1/health	none	liveness

NIP-98 requests are verified fully: signature, kind 27235, u/method/ payload tags against FLOONET_BASE_URL, a freshness window, and one-time event ids (replay rejection).

Co-locating names on the relay domain

FLOONET_AUTHORITY_COLOCATED controls whether the authority's NIP-05 lookup (/.well-known/nostr.json) is served on the relay's own domain, so name@relay.example resolves without the authority needing its own hostname.

• Docker Compose / Caddy: on by default. The whole stack lives on one FLOONET_DOMAIN; deploy/Caddyfile routes /.well-known/nostr.json (and /api/*) to the authority and everything else to the relay, so name@FLOONET_DOMAIN just works. Nothing to configure.

• Split nginx deploy: opt in. When the relay and the authority run on separate subdomains (the deploy/us-east/ pattern — relay on relay.example, the authority's own vhost on nm.example), enable it by including the shipped snippet in the relay vhost's :443 server block, ahead of the WebSocket catch-all:

  # inside  server { listen ...:443 ssl ...; server_name relay.example; }
  # BEFORE  location / { ...websocket... }
  include /etc/nginx/snippets/floonet-colocated-authority.conf;   # deploy/us-east/colocated-authority.conf
  

  Then nginx -t && nginx -s reload, and https://relay.example/.well-known/nostr.json?name=<n> returns the authority's JSON. Only the exact-match read path is co-located; registration and the rest of /api/* stay on the authority's own domain. The snippet sets X-Real-IP (load-bearing — the authority's per-IP rate limiter keys off it).

Mixnet exit (optional)

Uncomment COMPOSE_PROFILES=exit in .env and the package also runs floonet-mixexit: a small, unbonded mixnet client that accepts incoming mixnet streams and pipes every one of them to this stack's own TLS front. Wallets that prefer not to touch DNS or reveal their relay choice can then reach this relay entirely over the mixnet, with end-to-end TLS; the exit sees only ciphertext.

It is deliberately scoped: per-stream targets are never honored, the one upstream is fixed by config, so it is structurally not an open proxy and carries no open-proxy liability. No bonding, no tokens, no directory listing.

On first start it prints its stable mixnet address (also written to the data volume's nym_address.txt). Publish that address in your relay pool listing (the exit field) so wallets can find it, and back the data directory up: losing it rotates the address.

Extending the policy (plugins, paid resources)

• Add a kind: edit FLOONET_ALLOWED_KINDS, restart.
• Add a policy check: the plugin is a small, documented Python file. Write def check_foo(req, cfg): return None or "reason", append it to CHECKS, and it runs on every write, fail-closed. strfry reloads the plugin when the file's mtime changes.
• Replace the policy entirely: point relay.writePolicy.plugin in strfry.conf at any executable speaking strfry's stdin/stdout JSONL plugin protocol.
• Add a paid resource: the paywall is one mechanism applied to many resources. name and write ship today; the same pattern fits paid media/blob storage for GRIN (NIP-96 HTTP file storage or Blossom content-addressed blobs, advertised with a kind 10063 server list): pick a resource id, give it a price, gate the endpoint on ensure_paid, and the plugin/authority handle quoting, the hosted pay page, and confirmation unchanged. See name-authority/src/paid.rs.

Security model

• Fail closed everywhere. Malformed events, plugin errors, unreachable payment backend, unparseable config: all reject rather than admit.
• Stock + spec. strfry is never patched; the upstream ref is pinned in deploy/strfry/Dockerfile and apply-spec.sh, so updating strfry is bumping one hash.
• Containers run non-root (fixed uids) with the data volume as the only writable state; systemd units use DynamicUser, ProtectSystem=strict, NoNewPrivileges, syscall filtering, and a single writable state dir.
• Reverse proxy sets X-Real-IP (load-bearing: all per-IP rate limits key off it); TLS terminates at Caddy.
• Rate limits per IP on the authority's read and write endpoints, NIP-98 replay protection, name-change cooldown, and a poll throttle so outsiders cannot hammer GoblinPay through the public paid endpoint.
• No secrets in the repo. The GoblinPay token comes from the environment or a 0400 file via GOBLINPAY_TOKEN_FILE; the authority never logs it. The relay itself holds no secrets at all.
• events.maxEventSize is sized so large gift-wrapped payloads fit.

Configuration reference

Everything lives in .env (see .env.example, fully commented). The essentials:

Key	Default	Meaning
FLOONET_DOMAIN	floonet.example	your domain (names + TLS cert)
FLOONET_BASE_URL	https://floonet.example	public base URL (NIP-98 verification)
FLOONET_RELAYS	wss://floonet.example	relays advertised in nostr.json
FLOONET_ALLOWED_KINDS	0,3,5,13,1059,10002,10050,27235	the whitelist
FLOONET_REQUIRE_AUTH	false	NIP-42 gate
FLOONET_PAY_MODE	off	off / name / write
FLOONET_NAME_PRICE_GRIN	0	price of a name, in GRIN
FLOONET_WRITE_PRICE_GRIN	0	price of write access, in GRIN
GOBLINPAY_URL / GOBLINPAY_TOKEN	unset	your GoblinPay server
GOBLINPAY_WEBHOOK_SECRET	unset	enables the webhook receiver
COMPOSE_PROFILES	unset	exit also runs the mixnet exit

Note for Goblin wallet users

One wallet can hold multiple Nostr identities (npubs). If you pay for a name and want to keep it, load the same wallet in Goblin and switch to (or add) that npub; different identities share one wallet.

License

Apache-2.0 for everything in this repository. strfry itself (built from upstream at the pinned ref, never vendored here) is licensed under GPL-3.0 by its authors.

---

🤖 Built with AI pair-programming assistance (Claude)