buzz/docs/operator-nip-fi-bindings.md

NIP-FI Community Issuer Bindings

A deployment that provisions communities under one host suffix, for example <name>.communities.buzz.xyz, stores the NIP-FI issuers allowed to vouch for each community in community_nip_fi_issuers. The relay writes these rows when it creates a community; buzz-admin nip-fi backfills and edits them.

A host may hold a binding only when it is exactly one DNS label under the suffix, has no port, and is not reserved. A host is reserved when https://<host> is a command_audiences entry of any issuer in BUZZ_NIP_FI_ISSUERS, so a command audience can never become a community assertion audience. The relay refuses to start while a reserved host holds a binding, and the operator lookup route reports no issuers for a host that is not bindable or for an issuer that is not configured.

A community with durable requires_nip_fi=true always retains its last issuer. The internal allow_last exception for unbindable hosts cannot override this policy. Bind a replacement first, or archive/delete the community for containment. Bulk backfill skips required communities whose bindings are missing; its closing report still counts them as unbound. Repair those bindings with an explicit bind.

Configuration

BUZZ_NIP_FI_PROVISION_BINDING is read in every NIP-FI mode. Unset or empty binds nothing.

{
  "host_suffix": "communities.buzz.xyz",
  "authorized_issuers": ["https://app.builderlab.xyz/api/goose"]
}

• host_suffix is a lowercase domain name without a port or trailing dot.
• authorized_issuers is non-empty, and every entry must be an issuer in BUZZ_NIP_FI_ISSUERS. Each issuer is 1 to 2048 bytes.
• The suffix must not cover any BUZZ_NIP_FI_COMMUNITIES host, and every canonical_uri there must be readable. The relay and buzz-admin both refuse to start otherwise.

buzz-admin parses the same variables with the relay's parser. Run it with the relay's environment: BUZZ_NIP_FI_PROVISION_BINDING, BUZZ_NIP_FI_ISSUERS, BUZZ_NIP_FI_COMMUNITIES, and DATABASE_URL.

Database community source

BUZZ_NIP_FI_COMMUNITY_SOURCE=database resolves communities from these bindings instead of BUZZ_NIP_FI_COMMUNITIES. The relay refuses to start if BUZZ_NIP_FI_PROVISION_BINDING is unset or BUZZ_NIP_FI_COMMUNITIES is set. In off mode no snapshot is loaded.

Variable	Default	Bound
BUZZ_NIP_FI_COMMUNITY_SOURCE	env	env or database
BUZZ_NIP_FI_SNAPSHOT_MAX_ROWS	1,000,000	1 to 10,000,000 community-issuer rows; a larger load fails
BUZZ_NIP_FI_SNAPSHOT_REFRESH_TIMEOUT_MS	10,000	under the 30s refresh interval
BUZZ_NIP_FI_RESOLVER_NEGATIVE_CACHE_MAX	100,000	1 to 1,000,000 hosts
BUZZ_NIP_FI_RESOLVER_MAX_INFLIGHT	8	at least 1, clamped below the database pool size

Each pod loads a snapshot before it binds any listener, and refreshes it every 30s. A removed binding stops admitting new connections within 30s plus the configured refresh timeout (40s by default) while refreshes succeed, and within two minutes of the last good load while they fail. Open WebSocket sessions are not rechecked when a binding is removed; they end at their own session deadline. Alert on time() - buzz_nip_fi_binding_snapshot_loaded_timestamp_seconds > 120 and on absent(buzz_nip_fi_binding_snapshot_loaded_timestamp_seconds).

Initial policy on operator creation

A trusted NIP-98 operator may send initial_requires_nip_fi: true with create_only: true to POST /operator/communities. The community, owner, issuer bindings and required policy (generation 1) commit in one transaction. Omitted, null or false creates an optional community at generation 0. A non-null policy field without create_only: true returns 400 initial_policy_requires_create_only.

Required insertion needs an effective provision binding for the host; otherwise 400 nip_fi_binding_required leaves no row. Reserved hosts retain the existing reserved_host refusal. The successful response includes the stored requires_nip_fi and status: "created" for insertion or "existed" for a same-owner replay. A replay changes neither policy nor bindings, including after an operator disable or a change in issuer configuration. A different owner retains the existing conflict. Legacy ensure and deployment bootstrap remain optional and do not accept an explicit initial policy.

This policy is independent of BUZZ_NIP_FI_UPGRADES_ENABLED. Mode off stores it but bypasses enforcement. The production creation paths are operator create-only, legacy operator ensure, and deployment bootstrap; only create-only accepts this choice.

Upgrade the whole serving relay fleet before callers request true. Older writers may ignore the unknown field and insert an optional row. Checking the created response for stored true detects that incompatible writer, but cannot undo its insertion; a later existing-row lookup remains read-only. Turn caller targeting off before rolling back the relay. Turning it off affects future insertions only; it does not clear existing policy.

Commands

buzz-admin nip-fi backfill
buzz-admin nip-fi bind --host acme.communities.buzz.xyz --issuer https://issuer.example
buzz-admin nip-fi unbind --host acme.communities.buzz.xyz --issuer https://issuer.example

backfill binds the authorized issuers to every active, unbound, bindable community, a page of 1000 hosts at a time. Archived communities are bound on purpose, so unarchiving leaves a community that can log in. A community whose deletion has started is skipped. It always prints its counts and exits 1 while any bindable community remains unbound:

{"rows_bound": 12, "unbound": 0, "unbound_hosts": [], "truncated": false}

unbound_hosts lists at most 100 hosts; truncated is true when there are more.

bind refuses a reserved host, a host that is not one label under the suffix, and an issuer not in BUZZ_NIP_FI_ISSUERS.

unbind works without BUZZ_NIP_FI_PROVISION_BINDING. It refuses to remove a community's last issuer, because an empty community looks never-provisioned and the next backfill would bind it again. To swap issuers, bind the new one and then unbind the old one. To stop a community logging in, archive or delete it. When the provisioning config is present and shows the host is not bindable (a reserved host or one outside the suffix), unbind removes the last issuer too; this is how to clear a reserved-host binding that blocks relay startup.

backfill never adds the default issuers beside an operator bind: both lock the community row, and the backfill only inserts while the community still has no binding.

Lookup route

GET /operator/communities/nip-fi-binding?host=<host> is operator-signed and returns {"host": ..., "active": ..., "issuers": [...]}. kgoose relies on this contract:

• host is the host stored on the community row.
• Every lifecycle state answers 200. active is false once the community is archived or its deletion has started quiescing, including a tombstoned community; it stays true while a deletion is only requested.
• issuers is [] when BUZZ_NIP_FI_PROVISION_BINDING is unset, the host is not bindable, or nothing is bound. Only issuers in BUZZ_NIP_FI_ISSUERS are reported, in byte order.
• 404 means no community has this host; 400 means the host is malformed.

Rollout

1. Deploy the relay with BUZZ_NIP_FI_PROVISION_BINDING set. New communities are bound at creation from then on.
2. Run buzz-admin nip-fi backfill with the relay's environment. Repeat it until it exits 0.
3. Do not turn on the database binding source in enforce mode while any bindable community is unbound: an unbound community fails closed.

Database source runbook

BUZZ_NIP_FI_COMMUNITY_SOURCE=database reads communities from these bindings instead of BUZZ_NIP_FI_COMMUNITIES. Move one mode at a time, and only move forward when the step's go signals hold.

Off

Set BUZZ_NIP_FI_COMMUNITY_SOURCE=database with BUZZ_NIP_FI_MODE=off. No snapshot loads in off, but every BUZZ_NIP_FI_RESOLVER_* and BUZZ_NIP_FI_SNAPSHOT_* value is validated, so a bad one fails this deploy.

• Go: the rollout completes, and buzz-admin nip-fi backfill exits 0.
• No-go: a pod fails config validation. Fix the named variable.

Shadow

Set BUZZ_NIP_FI_MODE=shadow. Each pod now loads the snapshot before any listener binds, refreshes it every 30 s, and records what enforce would decide without refusing anything. Shadow labels database-source records community="bound" or "unmapped", never a host.

• Go, held for at least a day of normal traffic:
  • time() - buzz_nip_fi_binding_snapshot_loaded_timestamp_seconds stays under 60 on every pod.
  • buzz_nip_fi_binding_snapshot_load_failures_total is flat.
  • buzz_nip_fi_binding_snapshot_rows / buzz_nip_fi_binding_snapshot_max_rows is under 0.5.
  • buzz_nip_fi_resolver_miss_rejections_total is flat.
  • The non-admit share of buzz_nip_fi_shadow_total is only what you expect to deny; community="unmapped" comes only from hosts you do not serve.
  • stage="owner" counts as would-deny: each is an agent enforce will refuse for its token owner.
• No-go: any of these fails. Return to off and investigate.

Enforce

Set BUZZ_NIP_FI_MODE=enforce. Watch the same signals, plus the rate of 503 responses on login.

• Go: the shadow signals keep holding, and 503s stay at their shadow baseline.
• No-go: logins return 503 or are refused unexpectedly. Set mode=off (below).

Alerts

• Stale snapshot: time() - buzz_nip_fi_binding_snapshot_loaded_timestamp_seconds > 120, together with absent(buzz_nip_fi_binding_snapshot_loaded_timestamp_seconds) for a database-source pod.
• Near the row cap: buzz_nip_fi_binding_snapshot_rows / buzz_nip_fi_binding_snapshot_max_rows > 0.8. buzz_nip_fi_binding_snapshot_rows is the size of the last good load.
• Over the cap or too slow: any increase of buzz_nip_fi_binding_snapshot_load_failures_total{reason=~"over_cap|timeout"}.
• Live lookups shed: any increase of buzz_nip_fi_resolver_miss_rejections_total.

When the snapshot is too big or too slow

A load fails when the snapshot has more rows than BUZZ_NIP_FI_SNAPSHOT_MAX_ROWS or takes longer than BUZZ_NIP_FI_SNAPSHOT_REFRESH_TIMEOUT_MS. Both get worse as communities are added, so they usually arrive during normal growth, not at a deploy.

• New pods: the startup load fails and the process exits, so new pods crash-loop and a rollout stalls. Boot already fails when the database is unreachable; what this source adds is that snapshot size and load time can also fail it.
• Running pods: their refreshes fail but the last good snapshot keeps answering. Once it is 120 s old it is stale, and every login's host goes to a live lookup. Live lookups share BUZZ_NIP_FI_RESOLVER_MAX_INFLIGHT slots (8 by default). Concurrent logins for the same host share one lookup, and a login waits up to 50 ms for a free slot; how many are shed depends on login load across distinct hosts and on lookup latency. In enforce, a shed login gets 503 (authorization_unavailable); in shadow it is only recorded as a would-deny.

Ways out, in order:

1. Raise BUZZ_NIP_FI_SNAPSHOT_MAX_ROWS (up to 10,000,000) or BUZZ_NIP_FI_SNAPSHOT_REFRESH_TIMEOUT_MS (under 30,000), whichever the failure reason names, and roll out.
2. If that cannot land quickly, set BUZZ_NIP_FI_MODE=off. off loads no snapshot, so pods boot and admit as they did before NIP-FI.

Assertion policy ID change

This release changes every verified assertion's policy ID once, on purpose. The base ID (derive_assertion_policy_id in crates/buzz-auth/src/nip_fi/config.rs) no longer hashes the configured community audiences. The ID carried on a verified assertion is now IssuerPolicy::id_for_community: a hash of that base and the one community audience the request resolved to. The issuer is still committed through the base.

Policy IDs from earlier releases therefore do not match. Inside the relay the ID is only carried on the verified assertion and never compared with a stored ID, so admission is unaffected. Anything outside the relay that recorded old policy IDs, such as dashboards, log queries or allow-lists, should expect new values after the upgrade.