# NIP-FI Community Issuer Bindings A deployment that provisions communities under one host suffix, for example `.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://` 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. ## Configuration `BUZZ_NIP_FI_PROVISION_BINDING` is read in every NIP-FI mode. Unset or empty binds nothing. ```json { "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)`. ## Commands ```sh 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: ```json {"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=` 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.