Skip to content

Commit e47312d

Browse files
wpfleger96npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7
andauthored
feat(relay): accept kind:30621 multi-repo projects at ingest (#3171)
Buzz renders one card per `kind:30617`, so a project spanning several repositories has no representation. [NIP-MP](#3163) defines `kind:30621` as an addressable container holding a group's name, description, channel binding, and member coordinates. This adds the kind to `buzz-core` and its structural validation to the relay ingest path. ## Event shape ```json { "kind": 30621, "tags": [ ["d", "platform"], ["name", "Platform"], ["description", "Relay, desktop, and mobile."], ["a", "30617:<owner-a-hex>:buzz"], ["a", "30617:<owner-b-hex>:buzz-infra"], ["buzz-channel", "<channel-uuid>"], ["buzz-visibility", "listed"] ] } ``` ## Validation at ingest | Rule | Behavior | |------|----------| | `d` tag | exactly one, non-empty (length already bounded by the generic `D_TAG_MAX_LEN` check) | | member `a` tag arity | exactly 2 or 3 elements per NIP-01's `a` tag grammar; a 4th element has no defined meaning and is rejected | | member `a` tag coordinate | must parse as `30617:<lowercase-64-hex-owner>:<non-empty-d>` | | duplicate members | rejected on exact string match of the canonical coordinate | | member cap | 64, counted over raw `a` tags | | metadata cardinality | at most one each of `name`, `description`, `buzz-channel`, `buzz-visibility` | | metadata length | `name` ≤ 256 bytes, `description` ≤ 2048 bytes, `buzz-channel` ≤ 256 bytes, `buzz-visibility` ≤ 256 bytes | | zero members | valid | | unknown tags | ignored | Rejection order is normative so a client can predict which rule fires: `d`-cardinality → `d`-empty → member-cap → member-arity → coordinate parse → member-duplicate → metadata cardinality → metadata length. ## Design notes **No membership authorization.** Members are `a` tags, so one project may name repositories owned by different pubkeys — the entire point of the kind. That is safe because membership grants nothing: push policy reads a repository's own `kind:30617` (`api/git/policy.rs`) and never a project. `buzz-channel` is a metadata reference, not a routing directive, so projects are classified global-only. **Owner-only editing is free.** NIP-33 addressing keys replacement on `(pubkey, kind, d)`, so one signer can never overwrite another's project. No relay-side permission check exists or is needed, and `test_project_same_d_under_two_authors_are_independent` pins it. **Duplicates are rejected, not deduped.** A relay cannot rewrite tags inside a signed event without invalidating its id and signature, so the alternative to rejection is a stored duplicate-member head that every consumer must apply a first-wins rule to. **The cap is checked before the duplicate set is built.** Counting raw `a` tags rather than distinct coordinates means an event naming one coordinate thousands of times is refused on count, instead of being bounded only by the relay frame limit. **No side-effect handler.** Generic NIP-33 replacement and generic NIP-09 coordinate soft-delete already cover replacement and deletion; `kind:30621` needs no entry in `is_side_effect_kind`. ## Generic NIP-09 fix carried along `soft_delete_by_coordinate` (`crates/buzz-db/src/event.rs`) previously deleted the live coordinate head regardless of the tombstone's own `created_at`, so a delayed or replayed `a`-tag deletion signed between two versions destroyed the newer replacement. NIP-09 scopes an `a`-tag deletion to versions at or before the deletion request, so the `UPDATE` now carries `created_at <= $5` and `handle_a_tag_deletion` threads the deletion event's `created_at` through. The bug predates `kind:30621` and affected every parameterized-replaceable kind on the generic path — `kind:30617` repository announcements included — so the fix lands there rather than as a project special case. `events.created_at` is immutable per row, so the predicate guarantees a tombstone can never erase a version newer than itself; the UPDATE re-evaluates its WHERE clause after any lock wait. Under READ COMMITTED, a same-coordinate replacement racing the deletion may cause the deletion to evaluate before the new head lands, returning `Ok(false)` — but that outcome is state-identical to the deletion having arrived first, a valid Nostr ordering Nostr never fixes. The return value feeds only a debug log. No coordinate-level lock is needed. ## Coverage 32 unit tests in `crates/buzz-relay/src/handlers/ingest.rs` pin the envelope contract (accept: minimal, cross-owner, zero-member, same repo `d` under two owners, colon-bearing repo `d`, cap boundary, unknown tags, relay hint on member `a` tag, max-length metadata, stranger-owned member, uninterpreted metadata values, non-empty content; reject: every rule above plus valueless `d`/`a` tags). A fixture-driven test (`project_envelope_validates_all_shared_fixtures`) runs every case in the shared `NIP-MP.fixtures.json` oracle (11 accept + 20 reject) against `validate_project_envelope`, so any future change that breaks a case turns the test suite red. 6 `#[ignore]`d e2e tests in `crates/buzz-test-client/tests/e2e_project.rs` cover behavior that only exists past storage — coordinate round-trip, newer-wins replacement, two authors sharing a `d`, an `a`-tag tombstone that removes the project while leaving referenced `kind:30617`s intact, and a tombstone timestamped between V1 and V2 that must leave V2 live. The negative e2e case asserts on the rejection message so a refusal for an unrelated reason cannot satisfy it; that is what proves the validator is reachable from the live write path rather than merely correct in isolation. The new e2e binary is wired into the Relay E2E job. The timestamp predicate is additionally pinned at the storage layer by `coordinate_delete_spares_head_newer_than_the_deletion` in `crates/buzz-db/src/lib.rs`, which asserts both directions: a stale tombstone deletes nothing and leaves the newer head readable, and a tombstone at the head's own timestamp still deletes it. This test is wired into the Backend Integration job. Related: #3163 (the NIP-MP spec and shared conformance fixtures). Independent — either can merge first. --------- Signed-off-by: Will Pfleger <[email protected]> Co-authored-by: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
1 parent 811c5ec commit e47312d

9 files changed

Lines changed: 1338 additions & 14 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -704,6 +704,17 @@ jobs:
704704
--run-ignored ignored-only
705705
env:
706706
RELAY_URL: ws://localhost:3000
707+
- name: NIP-MP coordinate deletion guard
708+
# Verifies the never-delete-newer invariant of soft_delete_by_coordinate:
709+
# a stale tombstone (created_at earlier than the live head) spares that
710+
# head, and an equal-timestamp tombstone deletes it.
711+
run: |
712+
cargo nextest run \
713+
--archive-file target/ci/backend-integration-tests.tar.zst \
714+
-E 'package(buzz-db) and test(coordinate_delete_spares_head_newer_than_the_deletion)' \
715+
--run-ignored ignored-only
716+
env:
717+
DATABASE_URL: postgres://buzz:${{ env.BUZZ_TEST_POSTGRES_PASSWORD }}@localhost:5432/buzz
707718
- name: Upload relay log
708719
if: failure()
709720
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -739,7 +750,7 @@ jobs:
739750
./scripts/start-relay-for-tests.sh --no-build
740751
- name: Relay E2E tests
741752
run: |
742-
cargo test -p buzz-test-client --test e2e_persona --test e2e_team_catalog --test e2e_nostr_interop -- --ignored --nocapture
753+
cargo test -p buzz-test-client --test e2e_persona --test e2e_team_catalog --test e2e_nostr_interop --test e2e_project -- --ignored --nocapture
743754
cargo test -p buzz-test-client --test e2e_relay invite -- --ignored --nocapture
744755
cargo test -p buzz-test-client --test e2e_relay nip43_membership_snapshots_are_rejected -- --ignored --nocapture
745756
env:

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -609,6 +609,15 @@ pub const KIND_GIT_STATUS_CLOSED: u32 = 1632;
609609
/// NIP-34: Status — Draft.
610610
pub const KIND_GIT_STATUS_DRAFT: u32 = 1633;
611611

612+
/// NIP-MP: Multi-repo project — a named grouping of `kind:30617` repository
613+
/// announcements (parameterized replaceable, d=project slug).
614+
///
615+
/// Members are `a` tags holding `30617:<owner-hex>:<repo-d>` coordinates, so one
616+
/// project may span repositories owned by different pubkeys. The signer gains no
617+
/// authority over any member: push policy reads the repository's own
618+
/// announcement, never a project. See `docs/nips/NIP-MP.md`.
619+
pub const KIND_PROJECT: u32 = 30621;
620+
612621
/// All registered kind constants — used for duplicate detection and iteration.
613622
pub const ALL_KINDS: &[u32] = &[
614623
KIND_PROFILE,
@@ -739,6 +748,7 @@ pub const ALL_KINDS: &[u32] = &[
739748
KIND_GIT_STATUS_MERGED,
740749
KIND_GIT_STATUS_CLOSED,
741750
KIND_GIT_STATUS_DRAFT,
751+
KIND_PROJECT,
742752
];
743753

744754
/// Returns `true` if `kind` is in the ephemeral range (20000–29999).
@@ -836,6 +846,7 @@ const _: () = assert!(is_parameterized_replaceable(KIND_TEAM_CATALOG)); // 30178
836846
const _: () = assert!(is_parameterized_replaceable(KIND_WORKFLOW_DEF)); // 30620 ∈ 30000–39999
837847
const _: () = assert!(is_parameterized_replaceable(KIND_EVENT_REMINDER)); // 30300 ∈ 30000–39999
838848
const _: () = assert!(is_parameterized_replaceable(KIND_DM_VISIBILITY)); // 30622 ∈ 30000–39999
849+
const _: () = assert!(is_parameterized_replaceable(KIND_PROJECT)); // 30621 ∈ 30000–39999
839850
const _: () = assert!(is_parameterized_replaceable(KIND_THREAD_SUMMARY)); // 39005 ∈ 30000–39999
840851
const _: () = assert!(is_parameterized_replaceable(KIND_WINDOW_BOUNDS)); // 39006 ∈ 30000–39999
841852

‎crates/buzz-db/src/event.rs‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -789,31 +789,54 @@ pub async fn soft_delete_event(
789789
}
790790

791791
/// Soft-delete the live row for an addressable coordinate
792-
/// `(kind, pubkey, d_tag)` — the NIP-33 replacement key.
792+
/// `(kind, pubkey, d_tag)` — the NIP-33 replacement key — provided it is not
793+
/// newer than the deletion request.
793794
///
794795
/// Used by `handle_a_tag_deletion` to honour NIP-09 a-tag deletions for any
795796
/// parameterized-replaceable kind. The WHERE clause mirrors
796797
/// `replace_parameterized_event` so the coordinate semantics stay consistent:
797798
/// `channel_id` is intentionally NOT in the key (NIP-33 replacement is global
798799
/// per the spec — `channel_id` is stored for query scoping, not identity).
799800
///
801+
/// `deletion_created_at_secs` is the deletion event's own `created_at`. NIP-09
802+
/// scopes an `a`-tag deletion to versions at or before that instant, so a
803+
/// delayed or replayed tombstone signed between two versions must not erase the
804+
/// newer replacement. `events.created_at` is immutable per row, so the predicate
805+
/// guarantees a tombstone can never erase a version newer than itself — the UPDATE
806+
/// re-evaluates its WHERE clause after any lock wait, so a replacement that races
807+
/// the deletion and lands with a later `created_at` is always spared.
808+
///
809+
/// This does NOT guarantee deletion completeness when a same-coordinate
810+
/// replacement races the deletion: the deletion may evaluate its predicate before
811+
/// the replacement arrives, miss the incoming head, and return `Ok(false)`. That
812+
/// outcome is state-identical to the deletion having arrived first (old head
813+
/// gone, new head present), which is a valid Nostr ordering — Nostr never fixes
814+
/// the order of concurrent writes from different signers, and even same-signer
815+
/// ordering is advisory. The return value feeds only a debug log, not a
816+
/// correctness gate.
817+
///
800818
/// Returns `Ok(true)` if a row was deleted, `Ok(false)` if no live row matched
801-
/// (already deleted, or never existed).
819+
/// (already deleted, never existed, or strictly newer than the deletion).
802820
pub async fn soft_delete_by_coordinate(
803821
pool: &PgPool,
804822
community_id: CommunityId,
805823
kind: i32,
806824
pubkey: &[u8],
807825
d_tag: &str,
826+
deletion_created_at_secs: i64,
808827
) -> Result<bool> {
828+
let deletion_created_at = DateTime::from_timestamp(deletion_created_at_secs, 0)
829+
.ok_or(DbError::InvalidTimestamp(deletion_created_at_secs))?;
809830
let result = sqlx::query(
810831
"UPDATE events SET deleted_at = NOW() \
811-
WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL",
832+
WHERE community_id = $1 AND kind = $2 AND pubkey = $3 AND d_tag = $4 AND deleted_at IS NULL \
833+
AND created_at <= $5",
812834
)
813835
.bind(community_id.as_uuid())
814836
.bind(kind)
815837
.bind(pubkey)
816838
.bind(d_tag)
839+
.bind(deletion_created_at)
817840
.execute(pool)
818841
.await?;
819842

‎crates/buzz-db/src/lib.rs‎

Lines changed: 83 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1813,16 +1813,27 @@ impl Db {
18131813
event::soft_delete_event(&self.pool, community_id, event_id).await
18141814
}
18151815

1816-
/// Soft-delete the live row for an addressable coordinate `(kind, pubkey, d_tag)`.
1817-
/// Used by NIP-09 a-tag deletion for parameterized-replaceable kinds.
1816+
/// Soft-delete the live row for an addressable coordinate `(kind, pubkey, d_tag)`
1817+
/// when it is not newer than the deletion request.
1818+
/// Used by NIP-09 a-tag deletion for parameterized-replaceable kinds;
1819+
/// `deletion_created_at_secs` is the deletion event's `created_at`.
18181820
pub async fn soft_delete_by_coordinate(
18191821
&self,
18201822
community_id: CommunityId,
18211823
kind: i32,
18221824
pubkey: &[u8],
18231825
d_tag: &str,
1826+
deletion_created_at_secs: i64,
18241827
) -> Result<bool> {
1825-
event::soft_delete_by_coordinate(&self.pool, community_id, kind, pubkey, d_tag).await
1828+
event::soft_delete_by_coordinate(
1829+
&self.pool,
1830+
community_id,
1831+
kind,
1832+
pubkey,
1833+
d_tag,
1834+
deletion_created_at_secs,
1835+
)
1836+
.await
18261837
}
18271838

18281839
/// Atomically soft-delete an event and decrement thread reply counters.
@@ -5227,6 +5238,75 @@ mod tests {
52275238
);
52285239
}
52295240

5241+
#[tokio::test]
5242+
#[ignore = "requires Postgres"]
5243+
async fn coordinate_delete_spares_head_newer_than_the_deletion() {
5244+
use nostr::{EventBuilder, Keys, Kind, Tag, Timestamp};
5245+
5246+
let db = setup_db().await;
5247+
let community = CommunityId::from_uuid(make_community(&db.pool).await);
5248+
let keys = Keys::generate();
5249+
let kind = buzz_core::kind::KIND_PROJECT as i32;
5250+
let d_tag = "stale-tombstone-project";
5251+
let pubkey = keys.public_key().to_bytes().to_vec();
5252+
let base = Timestamp::now().as_secs();
5253+
5254+
let version = |content: &str, offset: u64| {
5255+
EventBuilder::new(Kind::Custom(buzz_core::kind::KIND_PROJECT as u16), content)
5256+
.tags(vec![Tag::parse(["d", d_tag]).expect("d tag")])
5257+
.custom_created_at(Timestamp::from(base + offset))
5258+
.sign_with_keys(&keys)
5259+
.expect("sign project version")
5260+
};
5261+
5262+
for (content, offset) in [("v1", 0), ("v2", 100)] {
5263+
assert!(
5264+
db.replace_parameterized_event(community, &version(content, offset), d_tag, None)
5265+
.await
5266+
.expect("store project version")
5267+
.1
5268+
);
5269+
}
5270+
5271+
// Tombstone timestamped between V1 and V2: it authorizes deleting V1,
5272+
// never the newer head that replaced it.
5273+
let stale_deleted = db
5274+
.soft_delete_by_coordinate(community, kind, &pubkey, d_tag, (base + 50) as i64)
5275+
.await
5276+
.expect("stale coordinate delete");
5277+
assert!(
5278+
!stale_deleted,
5279+
"a tombstone older than the live head must delete nothing"
5280+
);
5281+
5282+
let live_content: Option<String> = sqlx::query_scalar(
5283+
"SELECT content FROM events \
5284+
WHERE community_id=$1 AND kind=$2 AND pubkey=$3 AND d_tag=$4 AND deleted_at IS NULL",
5285+
)
5286+
.bind(community.as_uuid())
5287+
.bind(kind)
5288+
.bind(&pubkey)
5289+
.bind(d_tag)
5290+
.fetch_optional(&db.pool)
5291+
.await
5292+
.expect("read live head");
5293+
assert_eq!(
5294+
live_content.as_deref(),
5295+
Some("v2"),
5296+
"the newer head must survive a stale tombstone"
5297+
);
5298+
5299+
// A tombstone at or after the head's own timestamp still deletes it.
5300+
let current_deleted = db
5301+
.soft_delete_by_coordinate(community, kind, &pubkey, d_tag, (base + 100) as i64)
5302+
.await
5303+
.expect("current coordinate delete");
5304+
assert!(
5305+
current_deleted,
5306+
"a tombstone at the head's timestamp must delete it (NIP-09 is at-or-before)"
5307+
);
5308+
}
5309+
52305310
#[tokio::test]
52315311
#[ignore = "requires Postgres"]
52325312
async fn duplicate_nip_rs_discriminator_tags_keep_legacy_retention() {

‎crates/buzz-relay/src/api/git/transport.rs‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2795,10 +2795,18 @@ mod sec005_read_gate_tests {
27952795
);
27962796

27972797
let owner_pk = f.owner_keys.public_key().to_bytes().to_vec();
2798+
// Tombstone timestamped after the announcement, per NIP-09's
2799+
// at-or-before scoping in `soft_delete_by_coordinate`.
27982800
let deleted =
2799-
f.db.soft_delete_by_coordinate(f.community, 30617, &owner_pk, &f.repo)
2800-
.await
2801-
.expect("soft delete 30617");
2801+
f.db.soft_delete_by_coordinate(
2802+
f.community,
2803+
30617,
2804+
&owner_pk,
2805+
&f.repo,
2806+
chrono::Utc::now().timestamp() + 60,
2807+
)
2808+
.await
2809+
.expect("soft delete 30617");
28022810
assert!(deleted, "precondition: a live announcement row was deleted");
28032811

28042812
assert!(

0 commit comments

Comments
 (0)