buzz/docs/community-auth-upgrades.md

Community NIP-FI policy operator contract

The operator plane manages a stored community requirement independently of the global FI mode. See operator usage. Receipts prove durable acceptance, never fleet-wide socket closure or current authorization.

Operator boundary

POST/GET /operator/communities/nip-fi-policy require an allowlisted operator's NIP-98 signature bound to RELAY_OPERATOR_API_ORIGIN, method and URL (including the GET query), and POST body hash. Each attempt needs a fresh signature. These routes extend provisioning outside tenant event ingest; ordinary membership credentials cannot invoke them. All responses use Cache-Control: no-store.

The operator mediates an authenticated actor's registered key. The relay verifies the operator and stored owner; actor_pubkey is the mediator's claimed actor, not an independent user credential. Never accept a caller-selected actor as identity.

Generation storage

communities.requires_nip_fi defaults false; policy_generation defaults zero. Every new general operation advances the generation, even a same-state intent. Replay never increments. Generation exhaustion is refused. The historical community_auth_upgrades table stores acceptance receipts for both directions. Receipts survive target deletion and are not tenant serving data.

Enable and disable

POST contains operation_id, community_id, canonical expected_host, actor_pubkey, expected_owner_pubkey, desired requires_nip_fi, and mandatory expected_policy_generation plus expected_requires_nip_fi. UUIDs must be non-nil, keys lowercase hex, generations nonnegative; unknown fields are rejected. Enable requires expected_issuer; disable must omit it.

Read current preconditions with GET ?community_id=<UUID>&expected_host=<host>. Both generation and stored state must still match under the writer row lock. A mismatch returns 409 policy_conflict without mutation or receipt. Re-read and use a new UUID/request for revised intent. On a lost response, preserve the original complete file/UUID and recover or retry it with a fresh signature.

Acceptance serializes UUID reuse, then locks deletion-shared → community FOR NO KEY UPDATE → exclusive host lease, preserving lifecycle/deletion-intent, exact host, single owner and actor==owner checks and community write admission. Acceptance and receipt commit atomically. UUID identity binds the full tuple, action, both preconditions and authenticated operator. Different meaning under a committed UUID returns 409 idempotency_conflict. Identical committed replay recovers history before mutable preflight and never writes policy.

Enable requires a single deployment-selected authorized issuer in BUZZ_NIP_FI_PROVISION_BINDING, an applicable registry policy and exact existing community binding. It locks the binding against unbind and adds no trust. Disable does not depend on issuer availability and does not alter bindings. Every optional→required transition, including re-enable, excludes new host leases and drains prior optional leases for 1.1 seconds before committing.

Readback and response

GET ?operation_id=<UUID> returns only the originating operator's receipt. Mixed query forms are invalid. The response separates receipt (original tuple, accepted generation/action/preconditions and current target generation/flag) from mode and effective_required. Current-state reads also print exact expected expected_policy_generation and expected_requires_nip_fi fields, without a duplicate unprefixed pair. Missing/deleted targets have null current fields.

Receipt state	Meaning	CLI exit
applied	Current stored disable	0
pending	Current accepted enable; closure uncertified	10
superseded	Later generation or state differs	11
unavailable	Target/lifecycle/host or required issuer trust unavailable	12

pending_reasons includes connection_closure_unverified for enable. Neither time, local counters nor a successful sweep certify fleet completion. No response reports active. History is not a current authorization credential; ownership changes do not destroy the original operator's recovery authority.

Invalid requests return 400; operator auth uses existing 401/403 errors. Missing community/operation returns 404. Host, owner, lifecycle, issuer and policy conflicts return 409 with corresponding *_conflict codes; generation exhaustion returns 409 policy_generation_exhausted. New mutations behind a closed gate return 503 upgrades_disabled; unavailable authoritative DB/trust returns 503 authorization_unavailable. Request/transport/response errors exit 5.

Schema and rollout

Migration 0085 adds desired action and nullable CAS preconditions to existing receipts. True/default and null preconditions preserve old receipt meaning and old INSERT compatibility. No data backfill, trigger, function or foreign key is added. Historical rows with null CAS preconditions remain readable through policy status, including after target deletion. A new fenced request cannot reuse such a row's UUID: null historical preconditions differ from the mandatory new preconditions, so it returns idempotency_conflict without mutation.

The old /operator/communities/nip-fi-upgrade endpoint and the nip-fi-upgrade admin command have been removed. Its GET and POST requests receive 404; use nip-fi-policy for both changes and receipt recovery. Upgrade existing clients for the policy client contract before this relay version reaches their fleet, with their mutations paused until rollout ends. No client may guess CAS fields or refresh a saved request during recovery.

Before rolling, close BUZZ_NIP_FI_UPGRADES_ENABLED on every old relay and keep BUZZ_NIP_FI_CHANGES=false on new relays. Apply schema first, roll the whole fleet to the supported policy writer, then explicitly enable the new gate and resume migrated clients. Old binaries with their old gate open can still accept unfenced enables and reverse a disable; a new-name setting alone cannot close that old gate. Retire the old setting after the last old binary is gone. Reads and committed replay remain available on the supported API with its gate closed. Do not roll back to a writer that exposes unfenced enable after any policy operation. This removal does not erase receipts or rewrite schema.

Request enforcement and discovery

off ignores stored requirements; shadow enforces stored true; enforce is a global requirement floor; deny_protected denies protected traffic. Report effective_required alongside stored state so disable under enforce and enable under off cannot be mistaken for effective changes. Evaluating policy lookups fail closed on errors; off does not require an FI policy read.

Host policy comes from the writer, bound to community identity and lifecycle. Optional cache leases last at most one second; enable excludes refills and drains them. Fail-closed cache ordering may retain old required state for the remaining lease after disable. It cannot renew that stale lease. /info advertises effective requires_nip_fi without exposing operator receipts.

Existing connections

The periodic revalidator reads stored policy without row-locking transactions. After disable it stops requesting required-policy closes; a concurrent sweep may request one last non-FI close from its earlier snapshot. That client reconnects under optional policy. FI-admitted sockets retain their finite lifetime and then reconnect under current policy. Disable does not reopen or force-logout sessions. Re-enable repeats the optional-lease drain; non-FI root/audio sockets close through existing revalidation. Valid FI-admitted sockets retain existing rules.

Mistaken acceptance and containment

Stop an uncertain initiating caller and preserve its operation evidence. Read current policy before deciding whether to issue a new explicit CAS disable. A timeout is not permission to discard the original request or edit SQL. Disable is a supported operator action; acceptance is no longer monotonic. Disable removes the required-policy block on last-issuer removal; the separate last-binding guard still applies. The operator unbind command keeps the last issuer for bindable hosts. Re-enable must recheck trust and the exact binding. Removing trust never implicitly clears stored policy.

Close the mutation gate to stop new changes while keeping recovery available. Use established archive/lifecycle containment or repair FI trust as appropriate; never broaden trust to make a probe pass. Global off suspends FI everywhere while preserving stored policy and receipts; it is not per-community disable. Binary rollback does not undo acceptance and must not restore unfenced writers. No live mutation or deployment is implied by this procedure.