feat(nixos): package buzz-relay and add a deliberately-disabled module

[cameronraysmith]

Packages the Buzz Nostr relay and adds a NixOS module for it, shipped disabled.
magnetite imports the module but does not enable it, so nothing on the live host changes.
Not deployed.

Why this shape

This repository already contained an unsuperseded decision spike, docs/notes/development/buzz/self-hosting.md (2026-08-04), whose verdict was do not self-host the relay now.
Research confirmed its premises still hold at upstream 6e5c462: the relay hard-requires Postgres, Redis and an S3-compatible store, media-storage init is fatal at startup, and there is no SQLite or embedded path.
Rather than run past that or stop on it, the scope was settled deliberately: land the hard, reviewable work — packaging, the module, the specification — and leave the operational go/no-go as a separate gated change.

Three prerequisites are unmet and each is its own change:

1. an object store that passes the relay's startup CAS conformance probe;
2. Redis, a daemon class this fleet has never run;
3. backups, which do not exist fleet-wide.

Postgres, Redis and object storage are modelled here as dependencies and options.
This module provisions none of them.

The R2 verdict — the most useful thing in this PR

R2 was required to be verified at source, not assumed. It was, and it fails.

The git object store runs a conformance probe at boot that races 32 writers against a single key for three rounds, twice (192 conditional writes per boot).
Cloudflare documents a hard limit of 1 write/second per key, returning HTTP 429, corroborated by error code 10058.
The failure is not confined to the probe: the pointer key is the sole writer-serialization primitive, and 429 is not mapped to Conflict, so concurrent pushes surface an opaque 500 instead of a 409 pull-and-retry — intermittent and load-dependent, the worst shape for a correctness-adjacent defect.

Three of the spike's own arguments were wrong and are corrected in the addendum:

• it missed the BUZZ_GIT_CONFORMANCE_PROBE=false off-switch;
• it asserted the 429 mechanism without checking the client — it is rust-s3 with RETRIES defaulting to 1, one blind retry that cannot absorb 32 writers (and it is status-blind, so it also retries 412 on every backend);
• it overstated R2's consistency weakness — R2 documents strong read-after-write and list consistency, so the real gap is silence on CAS atomicity, not documented weakness.

BUZZ_GIT_PROBE_WRITERS=2 is worse than leaving it alone: it risks a false pass.
Recommendation is Garage single-node on fleet fit, with MinIO as the known-good fallback since upstream verifies against MinIO; the probe itself is the cheap adjudicator.
Garage's conditional-PUT CAS was not doc-verified in this pass, and the addendum says so.

What is deliberately not spent here

No nginx vhost, no DNS record, no tenant hostname.
The Host derived from RELAY_URL is the durable tenant key, persisted as communities.host and signed into every NIP-42/NIP-98 auth event, so it cannot be renamed later without invalidating history.
relayUrl therefore has no default and is required at enable time — as are database.url, redis.url and the object-store endpoint and bucket, because every upstream default is a working dev value that would otherwise be inherited silently.

Notable decisions

• Separate relay-v* source pin. The relay ships at 0.2.1 on relay-v* while buzz-source tracks desktop-v* and feeds the CLI and credential helper the home configuration uses. Repinning the shared source would couple a server upgrade to a client upgrade.
• BUZZ_REQUIRE_AUTH_TOKEN defaulted to true, departing from upstream's false. That default selects a published hardcoded dev key when no private key is supplied; with the identity generator always supplying one, true is safe and converts a silent fallback into a loud failure.
• Secrets travel the sops-backed clan-vars lane and arrive via EnvironmentFile (the relay has no *_FILE variants). An earlier draft had both a generator and a manual credentialsFile option, so an operator would have supplied the same S3 credentials twice, by two mechanisms, one inert. Resolved by wiring the generators in and deleting the manual options.
• Known gap: BUZZ_WEB_DIR/BUZZ_ADMIN_WEB_DIR are unset because web and admin-web are Vite/React sources needing a pnpm build. That means no admin UI and no invite landing page. Unset is upstream's own default; pointing them at a directory lacking index.html is instead a hard startup failure.

Verification

Every check below was run and observed to pass.

Check	Result
nix build .#nixosConfigurations.magnetite.config.system.build.toplevel -L	pass (x86_64-linux via magnetite as remote builder)
nix build .#checks.{aarch64-darwin,x86_64-linux}.package-buzz-relay{,-source} -L	pass on both systems
openspec validate --all --strict	10 passed / 0 failed (was 9)
just lint → prek (gitleaks + treefmt)	pass; gitleaks scanned 142 KB of staged content, and ran again on each of the four commits
eval of all 6 nixosConfigurations + 4 darwinConfigurations toplevels	pass

Why this selection covers the change. It adds two by-name packages and one module imported by exactly one host. The package checks cover the derivations on both systems that modules/checks/packages.nix will auto-generate — which is why building on aarch64-darwin mattered, and it does, so no blacklist entry was needed. The magnetite toplevel build covers the module import and the host's whole evaluation; the realised drvPath matched the independent fleet eval, so the thing evaluated is the thing built. The all-host eval covers the one genuine blast-radius risk, that a new file under modules/ reaches other machines through import-tree auto-import. gitleaks is load-bearing here because the change mints secret generators.

Deliberately not run: full nix flake check, which builds every package for every system and is far larger than this change; and builds (as opposed to evals) of the nine non-magnetite hosts, which this change cannot reach.

Inertness was proven, not asserted. No unit, no user, no firewall change, no clan-vars generator materialises, and buzz-relay is absent from all 21,231 derivations in magnetite's closure. A drvPath shift was traced to inputs.self source hashing and refuted by a control that added an empty unrelated module and reproduced the same shift.

Review notes

An adversarial review checked 24 upstream citations against 6e5c462; all 24 held. It found no blocking defect and four should-fix items, all in the enable path rather than the disabled-ship property. All four are fixed in this branch.

One nit is knowingly left: the no-public-bind assertion's isLoopbackOrMesh accepts the name localhost, making it a slightly weaker gate than cognee's address-based one. It only matters on the enable path, which gets its own change and its own review.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request