buzz/docs/operator-private-media.md

Private-channel media revocation

BUZZ_MEDIA_READ_MODE is a startup setting: off (default), shadow, or enforce. Unknown values fail startup. Channel revocation is effective only in enforce. Blossom authentication, tenant binding, and community admission remain mandatory in every mode.

Read policy

Every GET and HEAD, including each Range request, authorizes the parent hash before returning blob bytes, thumbnail bytes, existence, size, or range errors. A tenant sidecar lookup precedes the new database lookup. Authorization uses a fresh primary-database repeatable-read snapshot, without membership caches or replicas. A removal committed before that snapshot excludes the member. A request authorized before removal may finish afterward.

A file is readable through any current readable reference. Shared bytes may therefore remain readable through another open channel or a DM the person still belongs to. Channel owners/admins have no blanket exception to private channel membership. Ordinary REQ event visibility, recipient-gated kinds and encrypted engrams retain their restrictions. Gift-wrap ciphertext itself cannot supply hidden attachment references.

Counted references are imeta url and image fields, link-preview snapshot image/favicon fields, profile picture (or image when picture is absent) and banner fields, group metadata picture tags, and emoji tags on emoji lists and sets and per-emoji entries (kind 30180). Persona definitions (kind 30175) count avatar_url, with the same owner-only/shared visibility as their events. Root-relative paths and the tenant's HTTP/HTTPS media bases count. Animated profile descriptors count their poster and decoded animation URL independently, with the same tenant check on each. The indexed profile lookup expects hash characters to remain literal, as in the desktop descriptor. Republish over-encoded hashes such as %61 or JSON Unicode-escaped hash characters such as \u0061 using canonical URLs. Ordinary Unicode escapes in profile names are supported; the URL hash must remain plain ASCII. A pasted URL in free text alone grants nothing; messages must publish imeta. Deleted events/channels grant nothing. Only the newest live edit supplies a message's attachments; its original must remain live. Original link-preview snapshots remain readable through an edit unless the original or any live edit carries the exact ["link-preview","none"] marker; later edits do not undo suppression; this does not retain removed attachments. Superseded profiles are excluded. Current community icons grant community-wide access.

The read path probes the existing tags GIN index for imeta hashes and exact local URL aliases. It scans content only for current kind-0 profiles and kind-30175 persona avatar fields in the community, never all message bodies. LLVM/JIT is disabled only in this short authorization transaction: compiling partitioned permission probes costs seconds without amortizing that cost. Other database work retains its configured JIT policy. A two-second statement deadline and a 1,024-candidate budget per probe and a 16 MiB aggregate work budget bound each lookup. An accessible candidate can succeed before an overflow refusal. Candidates stream one at a time rather than allocating an entire page of message bodies. Budget exhaustion or a database failure returns 503; an inaccessible/missing reference returns 404. NIP-FI strict mode keeps its existing authorization-unavailable response contract.

Uploads and publication

After the upload pipeline verifies the supplied bytes, the relay records media_uploaders through community write admission. This is independent of optional audit/upload moderation records. An unposted file is previewable by its uploader only. Real reuploads may prove possession for another uploader. Possession authorizes publication; a known URL/hash alone does not. A registered agent must hold its own upload proof or readable reference; owner proof is never inherited.

The shared publication check runs before common ingestion dispatch (WS and HTTP, including metadata commands) and before direct workflow persistence. It uses the same reference extractor as reads, plus structured command URLs. A durable media_publications marker consumes preview authority before publication dispatch and survives source deletion. A later rejected operation may conservatively consume a preview; reupload still proves publication rights. Reuploads also record a boundary when a legacy reference already exists, so later purging that reference cannot revive previews. The marker grants no download access. Both tables are purged during community deletion, and every writer uses admission.

Deployment-admin feedback attachment reads retain their independent admin and feedback-row provenance checks. Feedback does not grant community-wide media access through the ordinary media endpoint.

Rollout and recovery

1. Before any pod enters shadow, build and verify the edit-target index. Small databases may auto-migrate through 0086: a missing index builds within a one-second lock and five-second statement budget, even with data. Large deployments disable auto-migration and prebuild concurrently per partition before applying 0086 or desired-state schema. A budget failure leaves migration retryable; a valid prebuild skips the blocking build. Bypassing the schema step can cause lookup timeouts/503 in enforce. Restore off, finish index construction/verification, then begin shadow. The migrations add plain tenant tables and an index, with no SQL functions, triggers, foreign keys or data rewrite.
2. Deploy the new binary on every writer with mode off.
3. Restart all writers in shadow; inspect buzz_media_read_access_total{mode="shadow",reason="no_ref"}, reason="not_member", and reason="lookup_error", plus buzz_media_publication_access_total. Exercise avatars, icons, emoji, uploads, private messages and old attachments during a staging soak.
4. Repair unsupported/historical URLs or republish them through an authorized uploader before restarting every serving pod in enforce.

Enforce blocker: SDK/CLI attachment edits remain unsupported. buzz_sdk::build_edit and buzz messages edit currently omit attachment imeta. Editing an attachment message through these clients can make its file unreadable, including to its sender. This review item is deferred, not fixed. Enforce stays blocked unless the operator can rule out SDK/CLI attachment edits in the community. The agent harness edit producer is unverified and remains inside this blocker until its metadata behavior is traced and tested. To remove the blocker, update both SDK/CLI paths to preserve the latest effective attachment metadata across successive edits without restoring files removed by an earlier edit. Require an upload → successive edits → GET/HEAD regression proving retained files stay readable and removed files stay denied. Keeping a URL in the edited body does not preserve access.

There is no grant backfill: existing stored references are evaluated directly, and signed event tags are never rewritten. Legacy unreferenced/orphan blobs have no upload proof and are denied in enforce mode; their owner must reupload. Pre-enforcement references remain authoritative, including a preexisting avatar that points to the same bytes as a private attachment. Custom historical media hosts beyond the tenant's current authority require explicit repair.

Roll back policy by restarting with off; retain the additive schema and publication markers. If rolling back to a pre-0086 binary, keep auto-migration disabled and suspend community deletion: its exact-set deletion catalog does not recognize the two added media tables, so deletion fails closed. Resume deletion after deploying a binary whose deletion catalog includes them. Mixed off/enforce serving pods cannot provide revocation. Shadow/off do not close the original exposure. Shadow authorization lookup failures, including sidecar failures, are counted without refusing reads. The serving path can still fail if storage cannot supply bytes. Enforcement fails closed.

Successful media responses, authorized range errors and media denials use private, no-store in all modes, including off. Off preserves the previous authorization behavior; cache headers intentionally change before enforce to avoid creating more year-long immutable entries during the preparatory rollout. New responses therefore increase repeat-download bandwidth. The desktop proxy passes this policy to the WebView; its local file cache and the mobile client's local copies can still display previously fetched bytes. Old immutable HTTP cache entries, files already downloaded, screenshots and copied bytes cannot be recalled. The guarantee applies to requests reaching the relay; migrating existing client caches is a separate client rollout concern.

Any authorized member may deliberately republish or reupload bytes into a readable channel or avatar. Revoking one channel cannot revoke that independent share. This policy does not prevent authorized recipients from copying data.

Media authorization uses a shared semaphore across database-handle clones, limited to one quarter of the writer pool, capped at eight lookups. Saturation waits up to 500 ms before returning authorization-unavailable, counted with reason="capacity", before pool acquisition. Every Range request reauthorizes; all events, including emoji lists and sets, have a 512-reference cap, and checks run sequentially within that connection bound. Missing sidecars reject publication in enforce mode; shadow counts failures and accepts the write, including stale avatar metadata edits and upload-proof/publication-marker errors.

Eight slots provide an upper bound of 8 / mean_lookup_seconds lookups per second per pod before queueing (for example, 20 ms means about 400/s; 100 ms means about 80/s). A smaller writer pool reduces that bound proportionally. These are capacity calculations, not measured throughput targets. Measure full request latency and concurrent image/avatar bursts, including all probes, sidecars and pool acquisition. Keep sustained traffic below the measured bound; the 500 ms queue absorbs bursts but cannot increase throughput. Each lookup uses a writer connection and several statements; no-store repeats that work on every view. The synthetic query-plan times exclude storage/network/pool costs.

During staging soak, abort enforcement if writer authorization acquire p95 exceeds 50 ms for five minutes, event-write acquire p95 doubles its pre-rollout baseline, or media lookup_error/capacity refusal exceeds 0.1% of requests for five minutes. Investigate query latency, pool utilization and storage errors before retrying. Shadow failures must be repaired before enforce, since a failed recording does not establish possession. Uploads made in off mode record no proof: uploads not yet posted when enforce starts require reuploading.

Before enforce, every client that uploads avatars with one key and publishes profiles with another must transfer the actual poster/animation bytes to an upload signed by the profile key. Owner relationships never inherit possession. Validate this in each supported client during shadow; upgrading only this repository's desktop does not migrate other clients. This includes the new desktop/web app in block/buzz-app, mobile, and CLI/plugin integrations that publish agent profiles: verify their signer and upload flow before enabling enforce for their users.

The legacy desktop transfers both poster and animation bytes for changed persona avatars before saving the edit; transfer failures leave the old local avatar intact. Team and individual agent snapshot imports also transfer selected target-local avatars before publishing each new agent profile. Imports report transfer failures in their profile-sync results. Validate all three workflows against enforce mode before rollout. Unchanged-avatar reconciliation never borrows the owner's signer.

New managed-agent creation explicitly downloads the chosen target-local avatar with the captured owner's signer, verifies its image bytes and hash, then uploads those bytes with the new agent's signer. The agent holds its own possession proof. The captured community stays pinned through profile publication, even if the owner changes workspaces during transfer. Automatic reconciliation never borrows the owner's proof or signer.

Changed-avatar edits refuse the entire save before any transfer when a linked instance has no usable signing key. The error names affected instances; restore their keys, or remove/unlink those instances, then retry. The previous persona and instance avatars remain unchanged, so the same requested avatar is retryable. Keys may be permanently lost; waiting alone does not repair a lost key.