Skip to content

Commit 114d40d

Browse files
authored
feat(relay): gate kind 30178 team-catalog reads behind the shared tag (#3358)
Team catalog projections (`kind:30178`) embed every member's system prompt, so they need the same read gate personas already have: only the author sees an unshared event. The gate was hardcoded to `kind:30175` at six read surfaces plus the SQL pushdown, so rather than adding a second special case it becomes kind-generic over `SHARED_GATED_KINDS = {30175, 30178}`. ## Kind 30178 New parameterized-replaceable kind, addressed by `(pubkey_o, 30178, team_id)`. It embeds sanitized member projections instead of referencing `kind:30175` heads — a foreign reader of a shared team could not otherwise hydrate members whose own persona events are unshared or, for built-ins, absent entirely. `kind:30176`'s wire body is untouched, so device sync keeps its contract. ## Kind-generic shared gate `buzz_core::kind` replaces `is_persona_shared_kind` / `is_unshared_persona_event` / `persona_event_is_shared` with `SHARED_GATED_KINDS` and the kind-agnostic `is_shared_gated_kind` / `is_unshared_gated_event` / `event_is_shared`. Every read surface consults the set: | Surface | File | |---|---| | REQ historical delivery + `ids` lookup | `crates/buzz-relay/src/handlers/req.rs` | | Live fan-out | `crates/buzz-relay/src/handlers/event.rs` | | COUNT fallback | `crates/buzz-relay/src/handlers/count.rs` | | NIP-98 HTTP `/query`, `/count`, `/search` | `crates/buzz-relay/src/api/bridge.rs` | | Pre-`LIMIT` SQL pushdown | `crates/buzz-db/src/event.rs` | The SQL clause generalizes from `kind != 30175` to `kind NOT IN (...)` bound from `SHARED_GATED_KINDS`, still applied before `ORDER BY … LIMIT` so a page of newer private events cannot starve an older shared one off the candidate set. `EventQuery::persona_reader` is renamed `shared_gated_reader` and `needs_persona_filtering` to `needs_shared_gate_filtering` to match. Because the `buzz-core` rename has consumers outside the relay, the four desktop call sites of `persona_event_is_shared` travel with it: `desktop/src-tauri/src/commands/personas/pending.rs`, `desktop/src-tauri/src/event_sync.rs`, and two in `desktop/src-tauri/src/managed_agents/persona_events.rs`. Each call is unchanged apart from the name — the persona `shared` projection behaves exactly as before. ## Ingest validation `validate_persona_envelope` splits into two reusable pieces — `validate_shared_tag` (exactly-two-element `["shared","true"]`, at most one occurrence) and `single_bounded_d_tag` (exactly one `d` tag, non-empty, `<=64` chars, no ASCII control characters or whitespace). `validate_team_catalog_envelope` composes both; personas additionally keep the slug grammar `^[a-z0-9][a-z0-9_-]{0,63}$`. `kind:30178` deliberately does **not** get the slug grammar. Team ids are UUIDs or built-in identifiers such as `builtin-team:welcome`, and the colon is not slug-legal; rewriting ids to fit would break NIP-33 addressing against the team's own `kind:30176` head. The non-empty and exactly-one checks are load-bearing regardless — without them generic NIP-33 storage maps a missing `d` onto `(pubkey_o, 30178, "")` and every team overwrites its predecessor. The exact two-element `shared` shape is enforced because the SQL visibility clause is JSONB containment (`tags @> '[["shared","true"]]'`), which would match a three-element superset such as `["shared","true","extra"]`. `kind:30178` is also added to the `Scope::UsersWrite` allowlist and to `is_global_only_kind`, so a stray `h` tag cannot channel-scope an owner-authored definition. ## Deferred `kind:30176` is deliberately not a gate member. Its writers never emit `shared`, so catalog opt-in semantics do not describe it — it needs owner-private reads driven by an authenticated principal set, tracked as a separate follow-up. ## Tests - 19 new `ingest.rs` unit tests covering the 30178 envelope (UUID and colon `d` tags, 64-char boundary, non-ASCII bound, empty/valueless/duplicate/missing `d`, embedded newline, `shared` false/three-element/duplicate, scope and global-only membership). - Persona regressions for the valueless `["d"]` shapes, since the `d`-tag helper is shared by both validators. - Existing `kind.rs` gate tests generalized and extended to assert the gate applies to 30178 as it does to 30175. - New `crates/buzz-test-client/tests/e2e_team_catalog.rs`: 9 WS-level tests over a live relay covering author reads of unshared heads, foreign omission from REQ, `ids`-lookup denial, COUNT existence-leak, share and unshare transitions, and the mixed-kind filter case. - `.github/workflows/ci.yml` adds `--test e2e_team_catalog` to the Relay E2E job so the new suite runs. ## Docs `docs/nips/NIP-AP.md` gains a "Team catalog projection: kind:30178" section and an "Ingest validation: kind:30178" subsection, records the gate as kind-generic, documents 30178 deletion vs. unshare semantics, and adds a security note that sharing a team exposes every member's instructions even when that member's own `kind:30175` head is unshared. Signed-off-by: Will Pfleger <[email protected]>
1 parent b9e4ed6 commit 114d40d

14 files changed

Lines changed: 1033 additions & 179 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -739,7 +739,7 @@ jobs:
739739
./scripts/start-relay-for-tests.sh --no-build
740740
- name: Relay E2E tests
741741
run: |
742-
cargo test -p buzz-test-client --test e2e_persona --test e2e_nostr_interop -- --ignored --nocapture
742+
cargo test -p buzz-test-client --test e2e_persona --test e2e_team_catalog --test e2e_nostr_interop -- --ignored --nocapture
743743
cargo test -p buzz-test-client --test e2e_relay invite -- --ignored --nocapture
744744
cargo test -p buzz-test-client --test e2e_relay nip43_membership_snapshots_are_rejected -- --ignored --nocapture
745745
env:

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

Lines changed: 143 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -182,48 +182,67 @@ pub const P_GATED_KINDS: &[u32] = &[
182182
/// or more than one `shared` tag) so no ambiguous heads can exist.
183183
pub const KIND_PERSONA: u32 = 30175;
184184

185-
/// Returns `true` if `kind` uses the author-only-unless-shared read model
186-
/// (currently only `KIND_PERSONA` / 30175).
185+
/// Kinds that use the author-only-unless-shared read model.
187186
///
188187
/// Events of these kinds may only be delivered to foreign readers when the
189-
/// event carries exactly `["shared", "true"]`. Used by all relay read
190-
/// chokepoints: REQ historical delivery, live fan-out, COUNT fallback,
191-
/// and the `ids`-lookup result gate.
192-
pub fn is_persona_shared_kind(kind: u32) -> bool {
193-
kind == KIND_PERSONA
188+
/// event carries exactly `["shared", "true"]`. Every relay read chokepoint
189+
/// consults this set: REQ historical delivery, live fan-out, COUNT fallback,
190+
/// the `ids`-lookup result gate, both HTTP surfaces, and the pre-`LIMIT` SQL
191+
/// visibility pushdown in `buzz-db`.
192+
///
193+
/// Membership is a privacy decision, not a convenience: adding a kind here
194+
/// makes its events invisible to foreign readers until their author opts in,
195+
/// and the opt-in must be a `shared` TAG (not a content field) so that
196+
/// toggling it leaves content bytes — and any content hash derived from them —
197+
/// unchanged.
198+
///
199+
/// `KIND_TEAM` (30176) is deliberately NOT a member. Its writers never emit
200+
/// `shared`, so catalog opt-in semantics do not describe it; it needs
201+
/// owner-private read semantics instead, which is a separate change.
202+
pub const SHARED_GATED_KINDS: &[u32] = &[KIND_PERSONA, KIND_TEAM_CATALOG];
203+
204+
/// Returns `true` if `kind` uses the author-only-unless-shared read model
205+
/// (see [`SHARED_GATED_KINDS`]).
206+
pub fn is_shared_gated_kind(kind: u32) -> bool {
207+
SHARED_GATED_KINDS.contains(&kind)
194208
}
195209

196-
/// Returns `true` if the event is a persona-shared-catalog kind AND the
197-
/// requester is NOT the author AND the event does NOT carry `["shared",
198-
/// "true"]`. All three conditions must hold to withhold the event.
210+
/// Returns `true` if the event is a shared-gated kind AND the requester is NOT
211+
/// the author AND the event does NOT carry `["shared", "true"]`. All three
212+
/// conditions must hold to withhold the event.
199213
///
200214
/// This is the per-event gate used by REQ historical delivery, live fan-out,
201215
/// and COUNT fallback paths. It is intentionally independent of
202-
/// `is_author_only_event` — persona events with `["shared", "true"]` MUST
216+
/// `is_author_only_event` — shared-gated events with `["shared", "true"]` MUST
203217
/// reach foreign readers; stripping them at the author-only layer would break
204218
/// the catalog query.
205-
pub fn is_unshared_persona_event(event: &nostr::Event, requester_pubkey_bytes: &[u8]) -> bool {
219+
pub fn is_unshared_gated_event(event: &nostr::Event, requester_pubkey_bytes: &[u8]) -> bool {
206220
let kind = event.kind.as_u16() as u32;
207-
if !is_persona_shared_kind(kind) {
221+
if !is_shared_gated_kind(kind) {
208222
return false;
209223
}
210224
// Author reads are always allowed.
211225
if event.pubkey.to_bytes() == requester_pubkey_bytes {
212226
return false;
213227
}
214228
// Foreign reader: allowed only if the event is explicitly shared.
215-
!persona_event_is_shared(event)
229+
!event_is_shared(event)
216230
}
217231

218232
/// Returns `true` if the event carries exactly one `["shared", "true"]` tag.
219233
///
234+
/// Kind-agnostic: this is purely the tag-shape predicate. The kind check lives
235+
/// in [`is_shared_gated_kind`], so callers that need "is this event shared"
236+
/// for a kind they already know (e.g. a client deciding whether its own
237+
/// retained head is published) can use this directly.
238+
///
220239
/// Requires the tag to have exactly two elements so that a three-element shape
221240
/// like `["shared","true","extra"]` is NOT treated as shared. Ingest enforces
222241
/// the same exact shape, so a well-stored event either has no `shared` tag
223242
/// (author-only) or exactly one with precisely two elements and value `"true"`
224243
/// (community-readable). This helper fails closed on any non-exact shape
225244
/// independently of ingest guarantees.
226-
pub fn persona_event_is_shared(event: &nostr::Event) -> bool {
245+
pub fn event_is_shared(event: &nostr::Event) -> bool {
227246
let mut count = 0usize;
228247
for tag in event.tags.iter() {
229248
let parts = tag.as_slice();
@@ -258,6 +277,34 @@ pub const KIND_TEAM: u32 = 30176;
258277
/// since these events are world-readable on the relay.
259278
pub const KIND_MANAGED_AGENT: u32 = 30177;
260279

280+
/// NIP-AP: Team Catalog projection (parameterized replaceable, owner-authored).
281+
///
282+
/// The shareable projection of a team, addressed by `(pubkey, kind, d_tag)`
283+
/// where `d_tag` is the team's stable id. Content is a versioned JSON body
284+
/// carrying sanitized team fields plus ordered, EMBEDDED member definition
285+
/// projections.
286+
///
287+
/// # Why this is not a `shared` tag on [`KIND_TEAM`]
288+
///
289+
/// A team's members live in kind 30175 events that are author-only unless
290+
/// individually shared, so a foreign reader of a shared team could never
291+
/// hydrate its members. This kind therefore embeds the member projections
292+
/// rather than referencing them: the share is atomic, it covers built-in
293+
/// members that have no 30175 head at all, it is immune to local-id/d-tag
294+
/// divergence, and an unshared 30175 stays private. Kind 30176's wire body is
295+
/// untouched, so device sync keeps its contract.
296+
///
297+
/// # Access control
298+
///
299+
/// Member of [`SHARED_GATED_KINDS`]: author-only unless the event carries
300+
/// exactly `["shared", "true"]`. Ingest additionally requires exactly one
301+
/// non-empty, bounded `d` tag — generic NIP-33 storage maps a missing `d` to
302+
/// the empty coordinate, which would collapse every team into one slot.
303+
///
304+
/// Content carries only sanitized fields: no env vars, no `respond_to`
305+
/// allowlist pubkeys, no source or local ids, no filesystem paths, no secrets.
306+
pub const KIND_TEAM_CATALOG: u32 = 30178;
307+
261308
// NIP-56 reporting
262309
/// NIP-56: Report an event, pubkey, or blob to relay moderators (kind:1984).
263310
///
@@ -586,6 +633,7 @@ pub const ALL_KINDS: &[u32] = &[
586633
KIND_PERSONA,
587634
KIND_TEAM,
588635
KIND_MANAGED_AGENT,
636+
KIND_TEAM_CATALOG,
589637
KIND_REPORT,
590638
KIND_PRODUCT_FEEDBACK,
591639
KIND_NIP29_PUT_USER,
@@ -784,6 +832,7 @@ const _: () = assert!(is_replaceable(KIND_AGENT_PROFILE)); // 10100 ∈ 10000–
784832
const _: () = assert!(is_parameterized_replaceable(KIND_PERSONA)); // 30175 ∈ 30000–39999
785833
const _: () = assert!(is_parameterized_replaceable(KIND_TEAM)); // 30176 ∈ 30000–39999
786834
const _: () = assert!(is_parameterized_replaceable(KIND_MANAGED_AGENT)); // 30177 ∈ 30000–39999
835+
const _: () = assert!(is_parameterized_replaceable(KIND_TEAM_CATALOG)); // 30178 ∈ 30000–39999
787836
const _: () = assert!(is_parameterized_replaceable(KIND_WORKFLOW_DEF)); // 30620 ∈ 30000–39999
788837
const _: () = assert!(is_parameterized_replaceable(KIND_EVENT_REMINDER)); // 30300 ∈ 30000–39999
789838
const _: () = assert!(is_parameterized_replaceable(KIND_DM_VISIBILITY)); // 30622 ∈ 30000–39999
@@ -858,64 +907,68 @@ mod tests {
858907
}
859908
}
860909

861-
// ── persona_event_is_shared / is_unshared_persona_event ──────────────
910+
// ── event_is_shared / is_unshared_gated_event ────────────────────────
862911

863-
fn make_persona_event(tags: &[&[&str]]) -> nostr::Event {
912+
fn make_event_of_kind(kind: u32, tags: &[&[&str]]) -> nostr::Event {
864913
use nostr::{EventBuilder, Keys, Kind, Tag};
865914
let keys = Keys::generate();
866915
let tag_vec: Vec<Tag> = tags
867916
.iter()
868917
.map(|parts| Tag::parse(parts.iter().copied()).unwrap())
869918
.collect();
870-
EventBuilder::new(Kind::Custom(KIND_PERSONA as u16), "")
919+
EventBuilder::new(Kind::Custom(kind as u16), "")
871920
.tags(tag_vec)
872921
.sign_with_keys(&keys)
873922
.unwrap()
874923
}
875924

925+
fn make_persona_event(tags: &[&[&str]]) -> nostr::Event {
926+
make_event_of_kind(KIND_PERSONA, tags)
927+
}
928+
876929
#[test]
877-
fn persona_event_is_shared_true_tag() {
930+
fn event_is_shared_true_tag() {
878931
let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true"]]);
879-
assert!(persona_event_is_shared(&ev));
932+
assert!(event_is_shared(&ev));
880933
}
881934

882935
#[test]
883-
fn persona_event_is_shared_no_tag() {
936+
fn event_is_shared_no_tag() {
884937
let ev = make_persona_event(&[&["d", "my-agent"]]);
885-
assert!(!persona_event_is_shared(&ev));
938+
assert!(!event_is_shared(&ev));
886939
}
887940

888941
#[test]
889-
fn persona_event_is_shared_wrong_value() {
942+
fn event_is_shared_wrong_value() {
890943
let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "false"]]);
891-
assert!(!persona_event_is_shared(&ev));
944+
assert!(!event_is_shared(&ev));
892945
}
893946

894947
#[test]
895-
fn persona_event_is_shared_duplicate_shared_tags() {
948+
fn event_is_shared_duplicate_shared_tags() {
896949
// Two ["shared","true"] tags → ambiguous; not considered shared.
897950
let ev =
898951
make_persona_event(&[&["d", "my-agent"], &["shared", "true"], &["shared", "true"]]);
899-
assert!(!persona_event_is_shared(&ev));
952+
assert!(!event_is_shared(&ev));
900953
}
901954

902955
#[test]
903-
fn persona_event_is_shared_three_element_tag_not_shared() {
956+
fn event_is_shared_three_element_tag_not_shared() {
904957
// ["shared","true","extra"] — three elements — must NOT be treated as shared.
905958
// The helper fails closed on any non-exact shape independently of ingest guarantees.
906959
let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true", "extra"]]);
907-
assert!(!persona_event_is_shared(&ev));
960+
assert!(!event_is_shared(&ev));
908961
}
909962

910963
#[test]
911-
fn persona_event_is_shared_one_element_tag_not_shared() {
964+
fn event_is_shared_one_element_tag_not_shared() {
912965
// ["shared"] — only one element — not shared (fails the == 2 check).
913966
let ev = make_persona_event(&[&["d", "my-agent"], &["shared"]]);
914-
assert!(!persona_event_is_shared(&ev));
967+
assert!(!event_is_shared(&ev));
915968
}
916969

917970
#[test]
918-
fn is_unshared_persona_event_author_always_allowed() {
971+
fn is_unshared_gated_event_author_always_allowed() {
919972
// Even without a shared tag the event author should not be blocked.
920973
use nostr::{EventBuilder, Keys, Kind, Tag};
921974
let keys = Keys::generate();
@@ -924,32 +977,83 @@ mod tests {
924977
.sign_with_keys(&keys)
925978
.unwrap();
926979
let author_bytes = keys.public_key().to_bytes();
927-
assert!(!is_unshared_persona_event(&ev, &author_bytes));
980+
assert!(!is_unshared_gated_event(&ev, &author_bytes));
928981
}
929982

930983
#[test]
931-
fn is_unshared_persona_event_foreign_no_tag() {
984+
fn is_unshared_gated_event_foreign_no_tag() {
932985
let ev = make_persona_event(&[&["d", "my-agent"]]);
933986
let foreign = [0u8; 32];
934-
assert!(is_unshared_persona_event(&ev, &foreign));
987+
assert!(is_unshared_gated_event(&ev, &foreign));
935988
}
936989

937990
#[test]
938-
fn is_unshared_persona_event_foreign_shared_tag() {
991+
fn is_unshared_gated_event_foreign_shared_tag() {
939992
let ev = make_persona_event(&[&["d", "my-agent"], &["shared", "true"]]);
940993
let foreign = [0u8; 32];
941-
assert!(!is_unshared_persona_event(&ev, &foreign));
994+
assert!(!is_unshared_gated_event(&ev, &foreign));
942995
}
943996

944997
#[test]
945-
fn is_unshared_persona_event_non_persona_kind_passthrough() {
998+
fn is_unshared_gated_event_ungated_kind_passthrough() {
946999
use nostr::{EventBuilder, Keys, Kind};
9471000
let keys = Keys::generate();
9481001
let ev = EventBuilder::new(Kind::Custom(KIND_TEAM as u16), "")
9491002
.sign_with_keys(&keys)
9501003
.unwrap();
9511004
let foreign = [0u8; 32];
952-
// Non-persona kinds are never blocked by this gate.
953-
assert!(!is_unshared_persona_event(&ev, &foreign));
1005+
// Kinds outside SHARED_GATED_KINDS are never blocked by this gate.
1006+
assert!(!is_unshared_gated_event(&ev, &foreign));
1007+
}
1008+
1009+
#[test]
1010+
fn is_unshared_gated_event_team_catalog_foreign_no_tag() {
1011+
// The gate must cover 30178 identically to 30175 — an unshared team
1012+
// catalog projection is author-only.
1013+
let ev = make_event_of_kind(KIND_TEAM_CATALOG, &[&["d", "team-1"]]);
1014+
let foreign = [0u8; 32];
1015+
assert!(is_unshared_gated_event(&ev, &foreign));
1016+
}
1017+
1018+
#[test]
1019+
fn is_unshared_gated_event_team_catalog_foreign_shared_tag() {
1020+
let ev = make_event_of_kind(KIND_TEAM_CATALOG, &[&["d", "team-1"], &["shared", "true"]]);
1021+
let foreign = [0u8; 32];
1022+
assert!(!is_unshared_gated_event(&ev, &foreign));
1023+
}
1024+
1025+
#[test]
1026+
fn is_unshared_gated_event_team_catalog_author_always_allowed() {
1027+
use nostr::{EventBuilder, Keys, Kind, Tag};
1028+
let keys = Keys::generate();
1029+
let ev = EventBuilder::new(Kind::Custom(KIND_TEAM_CATALOG as u16), "")
1030+
.tags(vec![Tag::parse(["d", "team-1"]).unwrap()])
1031+
.sign_with_keys(&keys)
1032+
.unwrap();
1033+
let author_bytes = keys.public_key().to_bytes();
1034+
assert!(!is_unshared_gated_event(&ev, &author_bytes));
1035+
}
1036+
1037+
#[test]
1038+
fn is_unshared_gated_event_team_catalog_malformed_shared_tag_fails_closed() {
1039+
// A three-element `shared` tag can never be stored (ingest rejects it),
1040+
// but the read gate must independently treat it as NOT shared.
1041+
let ev = make_event_of_kind(
1042+
KIND_TEAM_CATALOG,
1043+
&[&["d", "team-1"], &["shared", "true", "extra"]],
1044+
);
1045+
let foreign = [0u8; 32];
1046+
assert!(is_unshared_gated_event(&ev, &foreign));
1047+
}
1048+
1049+
#[test]
1050+
fn shared_gated_kinds_membership() {
1051+
assert!(is_shared_gated_kind(KIND_PERSONA));
1052+
assert!(is_shared_gated_kind(KIND_TEAM_CATALOG));
1053+
// 30176 has owner-private semantics, not catalog opt-in semantics: its
1054+
// writers never emit `shared`, so gating it here would hide every team
1055+
// from its own delegated readers.
1056+
assert!(!is_shared_gated_kind(KIND_TEAM));
1057+
assert!(!is_shared_gated_kind(KIND_MANAGED_AGENT));
9541058
}
9551059
}

0 commit comments

Comments
 (0)