Skip to content

feat: user groups (@handle) with relay-checked mentions and buzz groups CRUD - #8819

Draft
blakemcanally wants to merge 5 commits into
mainfrom
bmcanally/user-groups
Draft

blakemcanally wants to merge 5 commits into
mainfrom
bmcanally/user-groups

Conversation

@blakemcanally

@blakemcanally blakemcanally commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds user groups: a named handle (@ios-team) with a display name, description, and member list. A mention of the handle notifies every member. People and agents can create, read, update, and delete groups, and add and remove members. This is the Buzz equivalent of Slack user groups, which teams use daily to reach a team, and its absence blocks the move from Slack.

Design: docs/user-groups.md. Wire format: docs/nips/NIP-UG.md.

Event model. One addressable event per group: kind:30182, d = handle, name, creator, admin, p (members), policy (admins | open), and status (active | disabled) tags. The description goes in content. No new table or migration; storage, queries, #p lookup ("which groups am I in"), and live fan-out use the generic addressable path. The empty reserved range "User groups (47000–47999)" in kind.rs is removed, because group state must be addressable.

Who may edit. The relay treats (kind, d) as one community-wide coordinate, so the second person to sync a team can update a group the first person created. buzz_core::user_group::authorize_write allows the creator, listed group admins, community admins, or anyone when policy is open. After it stores a newer head from another author, the relay removes the previous head (a documented deviation from NIP-33's per-author replacement). A non-author disables a group with status: disabled; deleting is author-only for now.

Mentions. The sender expands the group into marked p tags: ["p", <member>, "", "group:<handle>"]. Every receive path already works on p tags (desktop and mobile filters, push leases, the event_mentions index, the mentions feed, agent wake-ups), so no client needs a new subscription. The relay rejects marked tags whose pubkey is not a member of an active group with that handle (validate_group_mentions), and the push hellthread gate counts one mention per group (weighted_p_count), so a group larger than p_tags_max still pushes.

CLI. buzz groups list|get|members|create|update|add-member|remove-member|delete, and buzz messages send --mention-group <handle>. update takes --disable, --enable, --set-member, and --policy. SDK: build_user_group.

Not in this PR (listed in the design doc):

  • Desktop (block/buzz-app) and mobile: @ picker entries for groups, expansion on send (exempt marked tags from the 32-recipient cap), one @handle chip when rendering, group management UI, and counting a group once in the mobile hellthread check (push_subscription.dart, BuzzPushKit/PushLease.swift:125).
  • Relay: an atomic handle check (two creators of a new handle in the same instant can both succeed; readers pick the newest head), delete by non-author editors, a per-community group cap and edit rate limit.

Open questions

  1. Default edit policy: admins here; Slack behaves closer to open.
  2. Size: at most 500 members per group; a mention is a snapshot of members at send time.
  3. Whether to move later to a relay-signed command model (NIP-29 style) for audit history.

Related issue

None found. Kind 30181 is claimed by #6582, so this uses 30182.

Testing

  • cargo test -p buzz-core -p buzz-sdk -p buzz-cli: 299, 326, 512 passed.
  • cargo test -p buzz-relay --lib -- --skip audio::: 1460 passed, 494 ignored. (The audio:: tests stop locally for an unrelated reason; CI covers them.)
  • Postgres: user_group_ingest_authorizes_edits_and_validates_mentions passes against a scratch database (creator, group admin, community admin, and open-policy writes; the one-live-head rule; mention validation). It found a real bug, now fixed with a regression test: nostr's EventBuilder dropped a p tag matching the signer, so a member who edited a group removed themself.
  • cargo clippy -p buzz-core -p buzz-sdk -p buzz-cli -p buzz-relay --all-targets: clean.
  • Migration tooling: slack2buzz groups plan|sync maps Slack usergroups.list members to Buzz pubkeys and creates and updates these groups through the CLI.

🤖 Generated with Claude Code

blakemcanally and others added 5 commits November 5, 2026 11:51
Add KIND_USER_GROUP, NIP-UG, and buzz_core::user_group: parsing,
validation, edit authorization, and group-mention helpers shared by
relay, SDK and CLI. The push hellthread gate in NIP-PL counts a group
once.

Kind 30181 belongs to the open NIP-AW PR (#6582), so user
groups use 30182.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Blake McAnally <bmcanally@squareup.com>
Add build_user_group, build_user_group_deletion, and group_mention_tags.
build_user_group opts in to self-tagging: nostr drops p tags equal to
the signer, so a member who edited a group would be removed from it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Blake McAnally <bmcanally@squareup.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Blake McAnally <bmcanally@squareup.com>
Admit kind 30182 under UsersWrite as a global kind. Check each write
against the community-wide head of its handle (creator, group admins,
community admins, open policy), require a newer created_at for a
cross-author edit, and remove the superseded head after the new one is
stored. Reject group-marked p tags that do not match the current members
of an active group, and count a group once in the push hellthread gate.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Blake McAnally <bmcanally@squareup.com>
buzz groups list|get|members|create|update|add-member|remove-member|delete
manage kind 30182 user groups with JSON output. Each write reads the
current head with strong consistency and publishes one newer head.

messages send --mention-group expands a group into p tags marked
group:<handle>.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Blake McAnally <bmcanally@squareup.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant