feat(auth): add read-only relay observer role

Signed-off-by: fryze <fryze@fryzes-MacBook-Pro.local>

Author: fryze

NOSTR.md

@@ -213,9 +213,21 @@ nak req -k 1059 --tag "p=<your-hex-pubkey>" \
 
 ## Relay Membership (NIP-43)
 
-When `BUZZ_REQUIRE_RELAY_MEMBERSHIP=true`, every authenticated connection is checked against the
-`relay_members` table. In today's single-community deployment this is the relay-wide member list; in multi-community mode the same rule is scoped to the host-derived community. Only pubkeys with a row for that community may use that community. The relay owner
-is bootstrapped automatically from `RELAY_OWNER_PUBKEY` on startup.
+Every authenticated connection is checked for a direct role in the
+`relay_members` table. When `BUZZ_REQUIRE_RELAY_MEMBERSHIP=true`, pubkeys without
+a qualifying row are denied; on an open relay they retain the normal open-relay
+authority. In today's single-community deployment this is the relay-wide member
+list; in multi-community mode the same rule is scoped to the host-derived
+community. The relay owner is bootstrapped automatically from
+`RELAY_OWNER_PUBKEY` on startup.
+
+The `observer` role is directly provisioned and grants exactly
+`messages:read`. Existing channel membership still determines which private
+channel events it may read. It cannot delegate through NIP-OA or use event
+submission, media, Git, huddle, GIF, workflow, membership, join, or leave
+mutation paths. Observer pubkeys and their role are included in the relay's
+kind:13534 membership snapshot, so observer identities are operational service
+identities and must not be treated as secret.
 
 ### CLI: Managing Members
 
@@ -227,6 +239,7 @@ In a Docker Compose deployment, use `run.sh`:
 ./run.sh add-member npub1abc...
 ./run.sh add-member <64-char-hex-pubkey>
 ./run.sh add-member npub1abc... --role admin
+./run.sh add-member npub1observer... --role observer
 
 # Remove a member
 ./run.sh remove-member npub1abc...
@@ -241,6 +254,7 @@ Or invoke `buzz-admin` directly inside the container:
 ```bash
 docker compose exec relay buzz-admin add-member --pubkey npub1abc...
 docker compose exec relay buzz-admin add-member --pubkey npub1abc... --role admin
+docker compose exec relay buzz-admin add-member --pubkey npub1observer... --role observer
 docker compose exec relay buzz-admin remove-member --pubkey npub1abc...
 docker compose exec relay buzz-admin list-members
 ```
@@ -271,9 +285,9 @@ the sender to be authenticated (NIP-42) as the relay owner or an admin.
 
 | Kind | Action | Required tags |
 |------|--------|---------------|
-| 9030 | Add member | `["p", "<hex-pubkey>"]`, optional `["role", "member\|admin"]` |
-| 9031 | Remove member | `["p", "<hex-pubkey>"]`, optional `["role", "member\|admin"]` |
-| 9032 | Change role | `["p", "<hex-pubkey>"]`, `["role", "member\|admin"]` |
+| 9030 | Add member | `["p", "<hex-pubkey>"]`, optional `["role", "member\|admin\|observer"]`; only the owner may grant `admin` or `observer` |
+| 9031 | Remove member | `["p", "<hex-pubkey>"]`, optional `["role", "member\|admin\|observer"]` |
+| 9032 | Change role | `["p", "<hex-pubkey>"]`, `["role", "member\|admin\|observer"]`; owner only |
 | 9033 | Set workspace profile (icon) | `["icon", "<https-url or data:image/* URL>"]` (empty clears) |
 
 Example using `nak`:

crates/buzz-admin/src/main.rs

@@ -52,8 +52,9 @@ enum Command {
         #[arg(long)]
         pubkey: String,
 
-        /// Role: "admin" or "member" (default: member). Cannot be "owner" —
-        /// use RELAY_OWNER_PUBKEY config to set the relay owner.
+        /// Role: "admin", "member", or "observer" (default: member). An
+        /// observer can read channel events but cannot mutate relay state.
+        /// Cannot be "owner" — use RELAY_OWNER_PUBKEY config to set the owner.
         #[arg(long, default_value = "member")]
         role: String,
     },
@@ -299,15 +300,15 @@ async fn cmd_list_members() -> Result<i32> {
     Ok(0)
 }
 
-/// Validate that `role` is `"member"` or `"admin"`. Rejects `"owner"`.
+/// Validate a role that can be directly provisioned by the operator CLI.
 fn validate_role(role: &str) -> std::result::Result<(), String> {
     match role {
-        "member" | "admin" => Ok(()),
+        "member" | "admin" | "observer" => Ok(()),
         "owner" => {
             Err("role 'owner' cannot be set via CLI — use RELAY_OWNER_PUBKEY config".to_string())
         }
         other => Err(format!(
-            "invalid role '{other}': must be 'member' or 'admin'"
+            "invalid role '{other}': must be 'member', 'admin', or 'observer'"
         )),
     }
 }
@@ -631,3 +632,18 @@ async fn reconcile_channels(
     );
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::validate_role;
+
+    #[test]
+    fn operator_can_provision_only_supported_non_owner_roles() {
+        for role in ["member", "admin", "observer"] {
+            assert_eq!(validate_role(role), Ok(()), "role {role}");
+        }
+        assert!(validate_role("owner").is_err());
+        assert!(validate_role("future-role").is_err());
+        assert!(validate_role("").is_err());
+    }
+}

crates/buzz-auth/src/scope.rs

@@ -61,6 +61,14 @@ pub enum Scope {
 }
 
 impl Scope {
+    /// Return the complete authority granted to a directly provisioned observer.
+    ///
+    /// Observers may read channel events only. Channel and community visibility
+    /// remain independently constrained by the relay's existing membership gates.
+    pub fn observer_read_only() -> Vec<Scope> {
+        vec![Self::MessagesRead]
+    }
+
     /// Return a `Vec` containing every known scope variant.
     ///
     /// Used in dev mode (`require_auth_token=false`) where `X-Pubkey` header
@@ -246,4 +254,12 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn observer_authority_is_explicit_nonempty_and_read_only() {
+        let scopes = Scope::observer_read_only();
+        assert_eq!(scopes, vec![Scope::MessagesRead]);
+        assert!(!scopes.is_empty());
+        assert!(scopes.iter().all(|scope| scope.as_str().ends_with(":read")));
+    }
 }

crates/buzz-db/src/runtime/migration.rs

@@ -702,7 +702,7 @@ mod postgres_tests {
         let mut migrations: Vec<_> = MIGRATOR.iter().collect();
         migrations.sort_by_key(|migration| migration.version);
 
-        assert_eq!(migrations.len(), 44);
+        assert_eq!(migrations.len(), 45);
         assert_eq!(migrations[0].version, 1);
         assert_eq!(&*migrations[0].description, "initial schema");
         assert!(migrations[0]
@@ -1287,6 +1287,12 @@ mod postgres_tests {
             desired_schema.contains("'rate_limit_violations'\n    ]::TEXT[])"),
             "schema.sql exclusion list must match the pre-0041 body after ledger removal"
         );
+
+        assert_eq!(migrations[44].version, 45);
+        let observer_role = migrations[44].sql.as_str();
+        assert!(observer_role.contains("relay_members_role_check"));
+        assert!(observer_role.contains("'observer'"));
+        assert!(desired_schema.contains("'observer'"));
     }
 
     #[test]

crates/buzz-db/src/store/relay_members.rs

@@ -20,7 +20,7 @@ use crate::{observability, replaceable, CommunityId, Db, RouteDecision, RoutePre
 pub struct RelayMember {
     /// 64-char lowercase hex pubkey.
     pub pubkey: String,
-    /// Role: `"owner"`, `"admin"`, or `"member"`.
+    /// Role: `"owner"`, `"admin"`, `"member"`, or `"observer"`.
     pub role: String,
     /// Hex pubkey of who added this member, or `None` for bootstrap entries.
     pub added_by: Option<String>,
@@ -1272,6 +1272,56 @@ mod postgres_tests {
         );
     }
 
+    /// The authoritative NIP-43 snapshot must advertise the same observer role
+    /// that drives admission. Omitting observers would create protocol/DB drift;
+    /// dropping the role would hide the relay policy clients are allowed to
+    /// display even though the server remains authoritative for permissions.
+    #[tokio::test]
+    #[ignore = "requires Postgres"]
+    async fn observer_role_round_trips_through_nip43_snapshot_and_reconciliation() {
+        let pool = setup_pool().await;
+        let community = make_test_community(&pool).await;
+        let observer = test_pubkey();
+        add_relay_member(&pool, community, &observer, "observer", None)
+            .await
+            .expect("add observer");
+
+        let db = Db::from_pool(pool.clone());
+        let relay_keys = nostr::Keys::generate();
+        let (snapshot, inserted, member_count) = db
+            .publish_nip43_membership_locked(community, &relay_keys)
+            .await
+            .expect("publish membership snapshot");
+        assert!(inserted);
+        assert_eq!(member_count, 1);
+        assert!(snapshot.event.tags.iter().any(|tag| {
+            tag.as_slice()
+                == [
+                    "member".to_string(),
+                    observer.clone(),
+                    "observer".to_string(),
+                ]
+        }));
+        assert!(!db
+            .nip43_membership_snapshot_needs_reconciliation_for_maintenance(
+                community,
+                &relay_keys.public_key(),
+            )
+            .await
+            .expect("snapshot matches canonical observer row"));
+
+        update_relay_member_role(&pool, community, &observer, "member")
+            .await
+            .expect("change observer role");
+        assert!(db
+            .nip43_membership_snapshot_needs_reconciliation_for_maintenance(
+                community,
+                &relay_keys.public_key(),
+            )
+            .await
+            .expect("role drift is detected"));
+    }
+
     /// Owner bootstrap is community-scoped: bootstrapping the owner in A does not
     /// make that pubkey an owner (or member) of B. Guards against a global
     /// `INSERT ... (pubkey, role)` bootstrap leaking the owner across tenants.