buzz/docs/moderation/PLAN.md

# Community-Admin Moderation Plan

**Goal (Tyler, 2026-07-01):** let community admins moderate their own communities.
Co-authored by Eva + Wren. Grounded against `buzz-1321-review @ 86d6388` and
`RESEARCH/NOSTR_CONTENT_REPORTING_MODERATION.md`. Re-verified against fresh
`REPOS/buzz-moderation-ref` @ main `1f5ba5b` (2026-07-07).

## 0. DECISIONS LOCKED (Tyler, 2026-07-07, #buzz-moderation thread e2a91af6)

All open calls below are now decided. The UX was refined by Eva + Wren to a
co-signed 9/10+ (Wren's line-cited corner-check: event `295db04e`; final
presentation: event `4273365f`).

1. **Roles: owner + admin only. No Moderator tier for now.** (Tyler, event `559f838f`.)
2. **Reporter identities visible to mods** in the queue (never to the reported author).
3. **Relay-key resolution DM** (Tyler, event `34de7dac`): on report resolution the
   relay key authors a regular nostr message stored in the DB. Container (Wren-verified):
   relay/moderation key creates/reuses a two-party DM channel `{mod key, user}` via the
   participant-hash-idempotent DM model (`buzz-db/src/dm.rs`), emits 39000 discovery
   (`hidden`, `t=dm`, `p` tags), inserts relay-signed kind-9 with `h=<dm_channel_id>`.
   One DM thread per user per community; relay publishes kind-0 "{Community} Moderation"
   identity. `moderation_reports` persists `reporter_pubkey`. Same primitive carries
   actioned-author notices and timeout/ban issuance. Non-replyable v1; replies (v2)
   route to mod queue as appeals.
4. **Ban/timeout gate at the auth seam** (Tyler, event `34de7dac`): evaluated after
   NIP-42 verify, before pubkey allowlist / `enforce_relay_membership`
   (`handlers/auth.rs` — gate goes immediately after ~L91). Banned ⇒
   `OK false "blocked: you are banned from this community"` + immediate WS close, zero
   further processing (`blocked:` is the NIP-01 standardized prefix; there is no
   `banned:` prefix; AUTH must be answered with `OK` per NIP-42). Live ban kill:
   cluster-wide disconnect-by-pubkey over Redis pub-sub; `CLOSED "blocked: ..."` per
   active sub, then socket close (needs a close-by-pubkey API on `ConnectionManager`).
   NIP-OA: gate checks the authenticating pubkey always + owner pubkey when present —
   owner ban cascades to agents; agent ban is agent-only; audit records matched
   principal, client never learns which. Timeout is a write-block, not a connection
   block: `OK false "restricted: you are timed out until <ts>"`, desktop disables
   composer with countdown chip. No silent write-drops.

## 1. Where this sits — two moderation layers, not one

Discord's published model (safety/our-approach-to-content-moderation) is explicitly
**two-layer**, and Buzz should mirror it:

| Layer | Discord | Buzz | Owner | This plan |
|-------|---------|------|-------|-----------|
| **Platform safety** | Trust & Safety team: CSAM image-hashing → NCMEC, ML network detection, human investigations | Relay operator: sha-match in S3, NIP-86 ban/takedown, NIP-62 vanish | Block / relay operator | **Adjacent** — Fizz's `MODERATION_SAFETY_SKETCH.md` owns it. We cite, don't duplicate. |
| **Community moderation** | Server owners + volunteer mods: AutoMod keyword/spam filters, Warning System | Community admins/mods: NIP-29 admin actions, report queue, in-community bans | Community admins | **THIS PLAN.** |

The severe-safety class (CSAM) is never delegated to community admins — it's a
platform-level hard-removal + legal-report path. Community moderation is the
subjective, per-community rule enforcement layer on top.

## 2. What PR #1321 already gives us (the foundation)

#1321 is **not** a moderation PR — it's the multi-tenant substrate that makes
per-community moderation *safe*:

- Every scoped row carries a **server-resolved `community_id`** (never caller-supplied).
- `TenantContext` is minted only on the host-resolution path and threaded through
  every scoped DB read + Redis publish — a proven cross-community isolation fence.

**Implication:** community-admin moderation authority is naturally tenant-scoped, but
only if target resolution also stays inside the fence. An admin of community A can
never reach community B's content when the query lists/deletes/bans with
`for_community(A)`. The dangerous edge is a new moderation signal whose *target* is a
bare event id, address, pubkey, or blob hash. Therefore every new moderation table gets
`community_id`, every new action takes `&TenantContext`, and every report/label target
is resolved under `tenant.community()` before it enters a queue or action row. No new
isolation primitive needed; reuse #1321's — but do not add any global target lookup in
the report/label path.

## 3. What already exists (build-on, don't rebuild)

From `crates/buzz-relay/src/handlers/side_effects.rs` + `buzz-core`:

- **NIP-29 admin kinds**, authorized in `validate_admin_event`:
  - `9000` put-user (add / assign role), `9001` remove-user (kick),
    `9002` edit-metadata, `9005` delete-event, `9008` delete-group,
    `9021`/`9022` join/leave request.
- **Role model** (`buzz-core/src/channel.rs`): `Owner > Admin > Member > Guest`, plus
  `Bot`. `is_elevated()` = Owner|Admin gates elevated-role grants. Agent-owner
  delegation lets the owning human act.
- **39000-series** group-state mirrors (metadata/admins/members/roles).
- **NIP-51 mute list** (kind:10000) constant exists — user-level, client-advisory.

## 4. The gaps (what this plan adds)

### Gap A — No distinct Moderator role
Today the only elevated tier is `Admin` (can manage members + settings). Discord's
model leans on a **volunteer-moderator** tier that can act on content/users but
*cannot* reconfigure the community or manage other mods.

**Recommendation after corner-check:** ship v1 **Admin-only for community-wide
moderation**, with an explicit capability helper, and defer a distinct `Moderator`
role until product needs delegated volunteer moderation.

Why not add `Moderator` in v1:

- Community-wide authority lives in the tenant-scoped `relay_members` table, not in
  channel `MemberRole`. Adding `Moderator` to `MemberRole` would migrate channel-local
  DB enum/API/UI/projection surfaces without actually creating tenant-wide authority.
- Adding `moderator` to `relay_members.role` is possible, but still touches admin
  commands, membership announcements, UI, downgrade paths, and tests. That is extra
  surface before we have the basic report/delete/ban loop working.
- NIP-29 interop is fine either way because roles are relay-defined/arbitrary, but
  clients that only reconstruct channel `39001` admins will not understand a
  community-wide moderator unless the relay explains/enforces it. A relay-signed
  tombstone is clearer than silently adding every community admin/mod to every group.
- A capability helper now makes v2 cheap: later `moderator` is a role-to-capability
  mapping, not an authorization rewrite.

V1 capability grid:

| Capability | Community owner | Community admin | Channel owner/admin | Member |
|------------|:---:|:---:|:---:|:---:|
| Delete any message in community (9005) | ✅ | ✅ | channel only | own only |
| Remove/kick user (9001) | ✅ | ✅ | channel only | self |
| Ban user from community | ✅ | ✅ | ❌ | ❌ |
| Timeout/mute user in-community | ✅ | ✅ | ❌ | ❌ |
| Resolve reports (queue actions) | ✅ | ✅ | optional channel-view | ❌ |
| Assign/revoke community Admin | ✅ | ❌ | ❌ | ❌ |
| Edit community-level settings | ✅ | ✅ | ❌ | ❌ |
| Delete community / hard-delete channel (9008) | ✅ | ❌ | channel owner only where already allowed | ❌ |

Open call for Tyler: **is a distinct Moderator tier required in v1?** My reviewed lean
is **no**: ship Admin-only, but structure authorization around capabilities so adding
`moderator` later is a narrow extension. If Tyler wants Discord-like volunteer mods on
day one, add `moderator` first to `relay_members.role` (tenant-level), advertise it in
`39003`, and only then decide whether channel `MemberRole` also needs a `Moderator`.

### Gap B — No NIP-56 reports (the report button)
**The single biggest missing primitive.** kind:1984 is referenced only as a CLI
filter example; there is no ingest, queue, or UI. Without it, mods have nothing to
act *on* — they can only delete what they personally see.

Pipeline (all tenant-scoped via #1321's fence; target resolution is the sharp edge):

```
client "Report" → kind:1984 event (p + e/x tags, report-type, free-text)
       │  ingest: validate_report_event (new, in side_effects.rs)
       ▼
  moderation_reports table (community_id, target_event/pubkey/blob,
       reporter, type, reason, created_at, status=Open)
       │  aggregate by target; weight trusted reporters (mods > members)
       ▼
  per-community moderation queue (buzz-cli / desktop admin surface)
       │  mod resolves: dismiss | delete (9005) | remove (9001) |
       │                ban | mute | escalate-to-platform
       ▼
  moderation_actions table (audit) + relay-signed tombstone (see Gap D)
```

Target-resolution rules to keep the tenant fence closed:

- `e` target: look up the event only with `tenant.community()`; infer `channel_id`
  from that row. If missing in this tenant, reject or store as an unresolved report —
  never search other tenants by event id.
- `x` blob target: resolve through tenant-scoped media references, e.g.
  `(community_id, sha256)` or `(community_id, event_id, sha256)`. A bare SHA-256 can
  be shared across tenants and must not grant cross-tenant visibility/action.
- `p`-only target: treat as a community-local report about that pubkey in the current
  tenant. It cannot imply a platform/global ban.
- NIP-32 labels (`1985`) in v2 follow the same rule: labels are advisory inputs until
  their target is resolved under the current `TenantContext`.

Key policy (from NIP-56 + the RESEARCH doc): **relays should not auto-moderate on
random-user reports** — they're gameable. Reports are a triage inbox, not an
auto-takedown trigger. Exception: trusted-admin reports of CSAM/illegal class can
fast-path to platform quarantine (Fizz's layer), not to community-admin discretion.

### Gap C — No persistent ban / in-community mute
`9001` remove-user is a kick — nothing stops re-join on an open channel. Add:
- `community_bans` table (`community_id`, pubkey, actor, reason, expires_at NULL=perm).
- Enforce at join (`9021`/`9000` self-add) and at event ingest for the community.
- **Mute/timeout** = time-boxed write-block (can read, cannot post) — a softer tool
  than ban, matches Discord's timeout. Same table, `muted_until` column.

### Gap D — No "Warning System" (why-was-this-removed)
Discord tells users *why* content was actioned. Buzz already has the right primitive:
`handle_delete_event_side_effect` soft-deletes the target, then emits a relay-signed
kind `40099` system message with `type: "message_deleted"`, `actor`, and
`target_event_id`. Extend that rather than inventing a new 48000-range event for v1.

Recommended shape:

- **Public/in-context tombstone:** relay-signed kind `40099`, rendered as "Removed by a
  community moderator" without exposing removed content. Add safe fields:
  `action_id`, `target_event_id`, `target_author`, `reason_code`, optional sanitized
  `public_reason`, and maybe `actor` if moderator identity is intentionally visible.
- **Private author notice:** separate p-gated/DM notification to the actioned user with
  the reason, community rule, and appeal/restore path. This is the closer Discord
  Warning System analog.
- **Internal action/audit row:** full moderator, report ids, reporter identities,
  evidence, and unsafe details stay admin-only.
- **NIP-32 label:** useful in v2 as an advisory/scanner signal, not the authoritative
  enforcement record. Labels can be consumed by clients; tombstones explain relay
  actions.

## 5. Standards to adopt vs. skip (from RESEARCH doc, cited to nostr-protocol/nips)

| NIP | Adopt? | Role in this plan |
|-----|--------|-------------------|
| **NIP-29** groups (9000–9022) | **Yes — already have it.** Extend authorization for community Admin + ban. | Relay-enforced community roles + admin actions. |
| **NIP-56** reports (1984) | **Yes — new.** Gap B. | User report button; interop-standard so other clients work. |
| **NIP-32** labels (1985) | **v2.** | Distributed/automated moderation output; feeds queue as a signal. Client-advisory blur/hide. |
| **NIP-51** mute (10000) | **Yes (exists).** | *User-level* self-mute — client-advisory, orthogonal to community moderation. Keep distinct from Gap C's community mute. |
| **NIP-86** relay-admin API | **Platform layer** (Fizz). | Operator ban/takedown at event/pubkey/IP grain. Not community-admin scope. |
| **NIP-62** vanish (kind:62) | **Platform layer.** | GDPR right-to-erasure; MUST fully delete + block rebroadcast. Legal, not community. |
| **NIP-72** moderated communities | **Skip.** | Deprecated upstream in favor of NIP-29 (README marks it unrecommended). |
| **NIP-09** deletion (kind:5) | Keep (exists). | Author self-delete only; advisory. Not a moderation tool for others' content. |

## 6. Phased rollout

**Phase 1 — community-admin MVP (this plan's core):**
1. Add a community moderation capability helper and extend `validate_admin_event` for
   community `owner|admin` authority (Admin-only v1 unless Tyler explicitly wants
   `moderator`).
2. NIP-56 kind:1984 ingest → tenant-scoped `moderation_reports`, with target
   resolution under `TenantContext`.
3. `moderation_actions` audit table + extended relay-signed kind `40099` tombstone for removals.
4. `community_bans` (+ mute/timeout column); enforce at join + ingest.
5. `buzz-cli moderation` queue commands (list/resolve/ban/mute) for admins.

**Phase 2 — UX + trust weighting:**
6. Desktop/mobile Report button + moderation queue surface.
7. Trusted-reporter weighting; report aggregation by target.
8. Warning-System notifications to actioned users.

**Phase 3 — distributed signals:**
9. NIP-32 labels (1985) as a queue input + client-advisory hide.
10. Cross-community shared blocklists (opt-in), platform-layer coordination.

## 7. Open calls for Tyler — ALL DECIDED 2026-07-07, see §0
- **Moderator role in v1, or Admin-only first?** (§4 Gap A — reviewed lean: Admin-only v1 with capability seams.)
- **Ban grain:** per-community only, or should a community ban be able to request a
  platform-level ban for severe cases? (Escalation path to Fizz's layer.)
- **Report visibility:** are reports mod-only, or does a reporter see resolution?
- **Warning System shape:** reviewed lean is relay-signed kind `40099` tombstone + private author notice; NIP-32 label is v2/advisory (§4 Gap D).

## Sources
- `buzz-1321-review @ 86d6388`: `crates/buzz-core/src/kind.rs`,
  `crates/buzz-core/src/channel.rs`, `crates/buzz-relay/src/handlers/side_effects.rs`.
- PR #1321 description (multi-tenant `community_id` / `TenantContext`).
- `RESEARCH/NOSTR_CONTENT_REPORTING_MODERATION.md` (cited to nostr-protocol/nips).
- Discord: safety/our-approach-to-content-moderation (2024-03-15).
- Fizz's `docs/MODERATION_SAFETY_SKETCH.md` (platform media-safety layer, adjacent).
- Wren corner-check: `PLANS/COMMUNITY_MODERATION_CORNER_CHECK_WREN.md`.