Skip to content

Commit d02c9be

Browse files
npub1qyvc0c5kl4gqv2fd97fsk46tu378sqgy35vc83rvgfwne90sel7s0ed67dTyler Longwell
andcommitted
fix(moderation): contract patch — DB-enforced invariants + kind registry
Wren's contract review of 67373d9 (two blockers + pins): - 0006_moderation.sql: CHECK-enforce exactly-one-target-class per report row (target_kind authoritative, matching column only); 32-byte length checks on every pubkey/event-id/sha256 column; matched_principal restricted to self|owner; same-community FKs for channel provenance (reports+actions -> channels) and resolution provenance (reports.action_id -> moderation_actions). - buzz-core: KIND_REPORT + 9040-9044 registered in ALL_KINDS (duplicate detection now covers them); is_moderation_command_kind() as the one canonical route check; compile-time asserts (u16 fit, not ephemeral). - moderation_commands.rs docs: pinned 9040-9044 routing (community-global direct commands, is_global_only_kind, fresh timestamp, never stored, no channel-scoped tokens) and the exact tag vocabulary per kind so the CLI and relay seams cannot diverge. Verified on live Postgres: migration applies; a two-target insert is rejected by moderation_reports_check. Co-authored-by: Tyler Longwell <[email protected]> Signed-off-by: Tyler Longwell <[email protected]>
1 parent 3ae043f commit d02c9be

3 files changed

Lines changed: 85 additions & 16 deletions

File tree

‎crates/buzz-core/src/kind.rs‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,6 +218,21 @@ pub const KIND_MODERATION_UNTIMEOUT: u32 = 9043;
218218
/// `status` tag = resolved|dismissed|escalated).
219219
pub const KIND_MODERATION_RESOLVE_REPORT: u32 = 9044;
220220

221+
/// Returns `true` for community moderation command kinds (9040–9044).
222+
///
223+
/// The canonical route check — use this instead of scattering
224+
/// `9040..=9044` matches across ingest/dispatch.
225+
pub const fn is_moderation_command_kind(kind: u32) -> bool {
226+
matches!(
227+
kind,
228+
KIND_MODERATION_BAN
229+
| KIND_MODERATION_UNBAN
230+
| KIND_MODERATION_TIMEOUT
231+
| KIND_MODERATION_UNTIMEOUT
232+
| KIND_MODERATION_RESOLVE_REPORT
233+
)
234+
}
235+
221236
// NIP-43 relay membership admin commands
222237
/// NIP-43: Add a pubkey to the relay member list.
223238
pub const RELAY_ADMIN_ADD_MEMBER: u32 = 9030;
@@ -503,6 +518,7 @@ pub const ALL_KINDS: &[u32] = &[
503518
KIND_PERSONA,
504519
KIND_TEAM,
505520
KIND_MANAGED_AGENT,
521+
KIND_REPORT,
506522
KIND_NIP29_PUT_USER,
507523
KIND_NIP29_REMOVE_USER,
508524
KIND_NIP29_EDIT_METADATA,
@@ -512,6 +528,11 @@ pub const ALL_KINDS: &[u32] = &[
512528
KIND_NIP29_CREATE_INVITE,
513529
KIND_NIP29_JOIN_REQUEST,
514530
KIND_NIP29_LEAVE_REQUEST,
531+
KIND_MODERATION_BAN,
532+
KIND_MODERATION_UNBAN,
533+
KIND_MODERATION_TIMEOUT,
534+
KIND_MODERATION_UNTIMEOUT,
535+
KIND_MODERATION_RESOLVE_REPORT,
515536
RELAY_ADMIN_ADD_MEMBER,
516537
RELAY_ADMIN_REMOVE_MEMBER,
517538
RELAY_ADMIN_CHANGE_ROLE,
@@ -725,6 +746,15 @@ const _: () = assert!(!is_ephemeral(KIND_AGENT_TURN_METRIC));
725746
const _: () = assert!(!is_replaceable(KIND_AGENT_TURN_METRIC));
726747
const _: () = assert!(!is_parameterized_replaceable(KIND_AGENT_TURN_METRIC));
727748
const _: () = assert!(KIND_AGENT_TURN_METRIC <= u16::MAX as u32);
749+
// Moderation kinds fit u16 and are neither replaceable nor ephemeral:
750+
// 1984 is a regular event (persisted to the queue, never fanned out);
751+
// 9040–9044 are direct commands (executed, never stored).
752+
const _: () = assert!(KIND_REPORT <= u16::MAX as u32);
753+
const _: () = assert!(KIND_MODERATION_RESOLVE_REPORT <= u16::MAX as u32);
754+
const _: () = assert!(!is_ephemeral(KIND_REPORT));
755+
const _: () = assert!(is_moderation_command_kind(KIND_MODERATION_BAN));
756+
const _: () = assert!(is_moderation_command_kind(KIND_MODERATION_RESOLVE_REPORT));
757+
const _: () = assert!(!is_moderation_command_kind(KIND_REPORT));
728758

729759
#[cfg(test)]
730760
mod tests {

‎crates/buzz-relay/src/handlers/moderation_commands.rs‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,31 @@
1717
//! Targets (`p` tag pubkey, `report` tag row id) are resolved under the
1818
//! request's `TenantContext` only.
1919
//!
20+
//! ## Routing (pinned — Wren contract review, 2026-07-07)
21+
//! 9040–9044 are **community-global direct commands**, exactly like the
22+
//! relay-admin 9030-series: route via
23+
//! [`buzz_core::kind::is_moderation_command_kind`], list them in
24+
//! `is_global_only_kind` so a stray `h` tag can never channel-scope them
25+
//! (no channel membership/archive gates apply), require a fresh timestamp,
26+
//! never store them, and reject channel-scoped API tokens.
27+
//!
28+
//! ## Tag vocabulary (pinned — CLI and relay must agree)
29+
//! - 9040 ban: `["p", <hex pubkey>]` required; optional
30+
//! `["expiration", <unix secs>]` (absent ⇒ permanent), `["reason", <text>]`.
31+
//! - 9041 unban: `["p", <hex pubkey>]`.
32+
//! - 9042 timeout: `["p", <hex pubkey>]` + required `["expiration", <unix secs>]`;
33+
//! optional `["reason", <text>]`.
34+
//! - 9043 untimeout: `["p", <hex pubkey>]`.
35+
//! - 9044 resolve: `["report", <row uuid>]` + `["status", resolved|dismissed|escalated]`
36+
//! + `["resolution", dismiss|delete|kick|ban|timeout|escalate]`; optional
37+
//! `["reason", <text>]` (private) and `["public_reason", <text>]` (tombstone-safe).
38+
//! `delete`/`kick`/`ban`/`timeout` resolutions fan out through the existing
39+
//! 9005/9001 paths and the 9040/9042 handlers — no second implementation.
40+
//!
2041
//! Lane ownership: L6 (Quinn) — plus `buzz-cli` `moderation` command group.
21-
//! The `ingest.rs` routing entries (scope map + direct-processing dispatch)
22-
//! for 9040–9044 belong to L3 (Perci): coordinate, don't edit ingest.rs.
42+
//! The `ingest.rs` routing entries (scope map + `is_global_only_kind` +
43+
//! direct-processing dispatch) for 9040–9044 belong to L3 (Perci):
44+
//! coordinate, don't edit ingest.rs.
2345
2446
use std::sync::Arc;
2547

‎migrations/0006_moderation.sql‎

Lines changed: 31 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,13 @@ CREATE TABLE moderation_reports (
1616
community_id UUID NOT NULL REFERENCES communities(id),
1717
id UUID NOT NULL DEFAULT gen_random_uuid(),
1818
-- The signed kind:1984 event id (stored for audit/idempotency).
19-
report_event_id BYTEA NOT NULL,
20-
reporter_pubkey BYTEA NOT NULL,
21-
-- What was reported. Exactly one target class per row.
19+
report_event_id BYTEA NOT NULL CHECK (length(report_event_id) = 32),
20+
reporter_pubkey BYTEA NOT NULL CHECK (length(reporter_pubkey) = 32),
21+
-- What was reported. Exactly one target class per row (CHECK-enforced below).
2222
target_kind TEXT NOT NULL CHECK (target_kind IN ('event', 'pubkey', 'blob')),
23-
target_event_id BYTEA,
24-
target_pubkey BYTEA,
25-
target_blob_sha256 BYTEA,
23+
target_event_id BYTEA CHECK (target_event_id IS NULL OR length(target_event_id) = 32),
24+
target_pubkey BYTEA CHECK (target_pubkey IS NULL OR length(target_pubkey) = 32),
25+
target_blob_sha256 BYTEA CHECK (target_blob_sha256 IS NULL OR length(target_blob_sha256) = 32),
2626
-- Channel inferred from an in-tenant target event row, when resolvable.
2727
channel_id UUID,
2828
-- NIP-56 report type: illegal|nudity|malware|spam|impersonation|profanity|other.
@@ -36,7 +36,17 @@ CREATE TABLE moderation_reports (
3636
-- moderation_actions row that resolved this report, if any.
3737
action_id UUID,
3838
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
39-
PRIMARY KEY (community_id, id)
39+
PRIMARY KEY (community_id, id),
40+
-- Exactly one target class per row: target_kind is authoritative and the
41+
-- matching column (only) is populated. Queue/action code never guesses.
42+
CHECK (
43+
(target_kind = 'event' AND target_event_id IS NOT NULL AND target_pubkey IS NULL AND target_blob_sha256 IS NULL) OR
44+
(target_kind = 'pubkey' AND target_event_id IS NULL AND target_pubkey IS NOT NULL AND target_blob_sha256 IS NULL) OR
45+
(target_kind = 'blob' AND target_event_id IS NULL AND target_pubkey IS NULL AND target_blob_sha256 IS NOT NULL)
46+
),
47+
-- Same-community channel provenance (channels are soft-deleted, never
48+
-- hard-deleted, so this FK cannot dangle).
49+
FOREIGN KEY (community_id, channel_id) REFERENCES channels (community_id, id)
4050
);
4151

4252
-- Queue reads: open reports, newest first, per community.
@@ -61,7 +71,7 @@ CREATE UNIQUE INDEX idx_moderation_reports_event
6171

6272
CREATE TABLE community_bans (
6373
community_id UUID NOT NULL REFERENCES communities(id),
64-
pubkey BYTEA NOT NULL,
74+
pubkey BYTEA NOT NULL CHECK (length(pubkey) = 32),
6575
banned BOOLEAN NOT NULL DEFAULT false,
6676
-- NULL + banned=true ⇒ permanent.
6777
ban_expires_at TIMESTAMPTZ,
@@ -70,7 +80,7 @@ CREATE TABLE community_bans (
7080
muted_until TIMESTAMPTZ,
7181
mute_reason TEXT,
7282
-- Moderator who last modified this row.
73-
actor_pubkey BYTEA NOT NULL,
83+
actor_pubkey BYTEA NOT NULL CHECK (length(actor_pubkey) = 32),
7484
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
7585
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
7686
PRIMARY KEY (community_id, pubkey)
@@ -84,12 +94,12 @@ CREATE TABLE community_bans (
8494
CREATE TABLE moderation_actions (
8595
community_id UUID NOT NULL REFERENCES communities(id),
8696
id UUID NOT NULL DEFAULT gen_random_uuid(),
87-
actor_pubkey BYTEA NOT NULL,
97+
actor_pubkey BYTEA NOT NULL CHECK (length(actor_pubkey) = 32),
8898
action TEXT NOT NULL CHECK (action IN (
8999
'delete_message', 'kick', 'ban', 'unban',
90100
'timeout', 'untimeout', 'dismiss_report', 'escalate')),
91-
target_pubkey BYTEA,
92-
target_event_id BYTEA,
101+
target_pubkey BYTEA CHECK (target_pubkey IS NULL OR length(target_pubkey) = 32),
102+
target_event_id BYTEA CHECK (target_event_id IS NULL OR length(target_event_id) = 32),
93103
channel_id UUID,
94104
-- Machine-readable rule/reason code (e.g. "spam", "community_rule_3").
95105
reason_code TEXT,
@@ -99,13 +109,20 @@ CREATE TABLE moderation_actions (
99109
private_reason TEXT,
100110
-- NIP-OA: which principal matched a ban ('self' | 'owner'); audit-only,
101111
-- the client never learns which.
102-
matched_principal TEXT,
112+
matched_principal TEXT CHECK (matched_principal IS NULL OR matched_principal IN ('self', 'owner')),
103113
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
104-
PRIMARY KEY (community_id, id)
114+
PRIMARY KEY (community_id, id),
115+
FOREIGN KEY (community_id, channel_id) REFERENCES channels (community_id, id)
105116
);
106117

107118
CREATE INDEX idx_moderation_actions_created
108119
ON moderation_actions (community_id, created_at DESC);
109120
CREATE INDEX idx_moderation_actions_target_pubkey
110121
ON moderation_actions (community_id, target_pubkey)
111122
WHERE target_pubkey IS NOT NULL;
123+
124+
-- Same-community resolution provenance: a report can only be resolved by an
125+
-- action row in its own community. Added after moderation_actions exists.
126+
ALTER TABLE moderation_reports
127+
ADD FOREIGN KEY (community_id, action_id)
128+
REFERENCES moderation_actions (community_id, id);

0 commit comments

Comments
 (0)