buzz/report.md

# Buzz Security-Relevant Architecture Report

This report explains Buzz from a security review point of view. It is based on
the current code in this repository, including work in progress areas such as
managed agents, relay membership, workspace switching, Git over the relay, and
multi-tenant direction.

The short version: Buzz is a Nostr-backed collaboration system. Almost every
user action becomes a signed Nostr event. The relay verifies signatures, checks
membership, writes events to Postgres, fans them out over WebSockets, and sends
selected content to search, audit, workflow, media, Git, or audio subsystems.
The main security boundaries are Nostr private keys, relay-level membership,
channel membership, event kind validation, and the process boundary around
agents.

## Code Layout

The security-relevant code is spread across the relay, shared Nostr logic,
clients, agent harness, and supporting services.

Relay and core:

- `crates/buzz-relay/src/main.rs` starts the relay, enforces production key
  requirements, and wires services together.
- `crates/buzz-relay/src/config.rs` reads environment configuration and
  service secrets.
- `crates/buzz-relay/src/state.rs` holds shared runtime state, caches, queues,
  the relay keypair, and service clients.
- `crates/buzz-relay/src/connection.rs` handles WebSocket connection lifecycle,
  frame limits, heartbeats, and handler concurrency.
- `crates/buzz-relay/src/handlers/auth.rs` implements NIP-42 WebSocket auth.
- `crates/buzz-relay/src/handlers/event.rs` handles incoming WebSocket `EVENT`
  messages and live fanout.
- `crates/buzz-relay/src/handlers/req.rs` and
  `crates/buzz-relay/src/handlers/count.rs` implement query and count behavior.
- `crates/buzz-relay/src/handlers/ingest.rs` is the main persistent event ingest
  path used by WebSocket and HTTP.
- `crates/buzz-relay/src/handlers/side_effects.rs` applies channel membership,
  channel metadata, deletion, discovery, and notification side effects.
- `crates/buzz-relay/src/handlers/command_executor.rs` handles command events
  such as workflow creation, workflow approval, and direct message commands.
- `crates/buzz-core/src/kind.rs` defines the event kind registry.
- `crates/buzz-core/src/verification.rs` verifies Nostr event IDs and Schnorr
  signatures.
- `crates/buzz-core/src/filter.rs` implements filter matching and per-event
  reader authorization.
- `crates/buzz-auth/src/nip42.rs` and `crates/buzz-auth/src/nip98.rs` implement
  NIP-42 and NIP-98 authentication.

Data and supporting services:

- `crates/buzz-db/src/*` contains Postgres data access for events, channels,
  members, API tokens, workflows, relay members, and user state.
- `migrations/0001_initial_schema.sql` defines the main storage model.
- `crates/buzz-search/src/lib.rs` configures Typesense search.
- `crates/buzz-audit/src/*` records audit log entries.
- `crates/buzz-media/src/*` validates and stores uploads in S3-compatible
  storage.
- `crates/buzz-relay/src/api/media.rs` exposes Blossom-style media upload and
  download endpoints.
- `crates/buzz-relay/src/api/bridge.rs` exposes HTTP `/events`, `/query`,
  `/count`, and workflow webhook endpoints.

Clients and identity:

- `desktop/src-tauri/src/app_state.rs` creates and stores the desktop user
  Nostr key.
- `desktop/src-tauri/src/commands/identity.rs` exposes signing, import, export,
  and auth event commands to the Tauri frontend.
- `desktop/src-tauri/src/commands/workspace.rs` applies the active relay
  workspace to the backend.
- `desktop/src/features/workspaces/*` stores workspace metadata in frontend
  storage and forces React remounts during workspace switching.
- `mobile/lib/shared/workspace/*` stores mobile workspace configuration,
  including the mobile user private key.
- `mobile/lib/shared/auth/auth_provider.dart` authenticates the mobile client
  against the relay.

Agents and developer tools:

- `desktop/src-tauri/src/managed_agents/*` creates, stores, launches, stops, and
  logs managed agents.
- `crates/buzz-acp/src/*` is the ACP harness that bridges Buzz events to an AI
  agent process.
- `crates/buzz-agent/src/*` is a minimal ACP-compatible agent.
- `crates/buzz-dev-mcp/src/*` is the local developer MCP server. It exposes
  shell and file-editing tools to agents.

Other important feature areas:

- `crates/buzz-workflow/src/*` executes workflow definitions.
- `crates/buzz-relay/src/api/git/*` implements Git smart HTTP, object storage,
  and push policy checks.
- `crates/git-credential-nostr/src/lib.rs` signs Git HTTP credentials with a
  Nostr key.
- `crates/git-sign-nostr/src/lib.rs` signs Git commits and tags with Nostr keys.
- `crates/buzz-core/src/pairing/*`, `crates/buzz-pair-relay/src/lib.rs`, and
  `crates/buzz-pairing-cli/src/main.rs` implement device pairing.
- `crates/buzz-relay/src/audio/*` implements huddle audio rooms.
- `crates/buzz-proxy/src/*` provides Nostr compatibility proxy behavior.

## System Model

Buzz uses Nostr as the event format and identity model. A user or agent has a
Nostr keypair. The public key is the account identifier. The private key signs
events.

The relay is the central service. It accepts WebSocket and HTTP requests,
verifies events, checks authorization, writes accepted events to Postgres, and
fans events out to live subscribers. Redis is used for pub/sub and presence.
Typesense is used for search. S3-compatible storage is used for media and Git
object data.

The relay is not a gossiping Nostr relay. It does not replicate events to other
relays as a normal Nostr network relay would. The security model is closer to a
single workspace service that uses Nostr events as signed records.

The important runtime boundaries are:

- Relay process boundary: all normal clients and agents must go through relay
  validation.
- User key boundary: whoever controls a user's Nostr private key can act as
  that user.
- Agent key boundary: a managed agent has its own Nostr key. The desktop app
  can delegate owner context to it with a NIP-OA auth tag.
- Channel membership boundary: private channel reads and writes depend on
  membership and role checks.
- Relay membership boundary: when enabled, the relay only admits configured
  relay members or delegated agents whose owners are relay members.
- Local machine boundary: managed agents and the dev MCP server can run local
  commands. That is intentionally powerful and should be treated like local code
  execution.

## Nostr Machinery

### Event Identity And Signatures

Nostr events contain a public key, kind, timestamp, tags, content, ID, and
signature. The event ID is derived from the event body. The signature is a
Schnorr signature over that ID.

The relay verifies both the event ID and the signature in
`crates/buzz-core/src/verification.rs`. The persistent ingest path in
`crates/buzz-relay/src/handlers/ingest.rs` rejects events that fail signature
verification. The WebSocket event handler in
`crates/buzz-relay/src/handlers/event.rs` also rejects events whose `pubkey`
does not match the authenticated connection, except for specific proxy and gift
wrap cases.

This is a strong property: accepted application events are attributable to the
Nostr key that signed them. The sharp edge is also simple: key compromise is
account compromise.

### Event Kinds

All known event kinds are registered in `crates/buzz-core/src/kind.rs`. Unknown
kinds are rejected by the relay ingest path. This is good because it keeps the
relay from silently storing unexpected signed data with unclear semantics.

Some important kinds:

- NIP-42 auth: `22242`
- NIP-98 HTTP auth: `27235`
- Blossom upload auth: `24242`
- Gift wrap: `1059`
- Channel messages and NIP-29 group events
- Channel metadata and discovery events: `39000`, `39001`, `39002`
- Membership notifications: `44100`, `44101`
- Presence and typing ephemeral events: `20001`, `20002`
- Agent observer frames and agent-specific events
- Workflow, approval, Git, and relay administration events

The relay has several kind-specific guardrails in
`crates/buzz-relay/src/handlers/ingest.rs`: relay-only events are rejected from
clients, HTTP-only or WebSocket-only restrictions are enforced, delete events
must be structurally valid, encrypted engram/reminder envelopes are checked for
basic shape, and channel-scoped kinds must carry valid channel scope.

### WebSocket Auth: NIP-42

WebSocket connections authenticate with NIP-42. The relay sends a random
challenge. The client signs an auth event with the challenge and relay URL. The
relay verifies the signature, the challenge, the relay tag, and timestamp
freshness in `crates/buzz-auth/src/nip42.rs`.

The connection-level auth handler is in `crates/buzz-relay/src/handlers/auth.rs`.
After NIP-42 succeeds, the relay can also check:

- Pubkey allowlist, if configured.
- Relay membership, if `BUZZ_REQUIRE_RELAY_MEMBERSHIP=true`.
- NIP-OA delegation, if `BUZZ_ALLOW_NIP_OA_AUTH=true`.

When relay membership is enabled, `RELAY_OWNER_PUBKEY` bootstraps the owner and
`BUZZ_RELAY_PRIVATE_KEY` is required at startup. This is enforced in
`crates/buzz-relay/src/main.rs`.

### HTTP Auth: NIP-98

HTTP requests use NIP-98 signed auth events. Verification is in
`crates/buzz-auth/src/nip98.rs`; bridge route handling is in
`crates/buzz-relay/src/api/bridge.rs`.

The auth event binds the signer, URL, method, timestamp, and optionally a
payload hash. Buzz clients generally include a payload hash for normal JSON
requests. The verifier accepts requests without a payload hash if the auth event
does not include one. That is allowed by the NIP, but it is risky for
state-changing non-streaming requests because the body is not cryptographically
bound to the signature.

The HTTP bridge has a replay cache for NIP-98 event IDs. Git HTTP intentionally
uses a different tradeoff, described later.

### Scopes, Tokens, And Real Authorization

Buzz has a `Scope` model in `crates/buzz-auth/src/scope.rs`. API tokens can be
stored with scoped permissions in the `api_tokens` table. Those token records
are used by paths such as production media upload.

For normal Nostr-authenticated users, the relay generally grants the known
application scopes after authentication and then relies on relay membership,
channel membership, ownership checks, and per-kind validation for the real
authorization decision. That is important during review: a scope check may be
necessary, but it is rarely sufficient by itself.

This also means new features should not treat "authenticated Nostr user" as
"authorized user." They need an explicit policy for the event kind, channel,
global record, owner, or resource being accessed.

### NIP-OA Delegation

Buzz uses NIP-OA-style auth tags to connect an agent key to a human owner key.
The helper is in `crates/buzz-sdk/src/nip_oa.rs`. The owner signs an auth tag
that names the owner pubkey, the agent pubkey, conditions, and a signature. The
relay can verify that tag when `BUZZ_ALLOW_NIP_OA_AUTH=true`.

This is how a managed agent can be admitted when relay membership is enabled and
the owner is a relay member. The agent still signs events with its own key. The
auth tag proves that the owner delegated that agent.

The sharp edge is that `BUZZ_AUTH_TAG` is a credential. It is not the owner's
private key, but when paired with the agent private key it can carry owner
context in parts of the system that trust NIP-OA. If conditions gain more
semantics, expiry, or scope rules, those rules need to be enforced everywhere
the tag is accepted.

### Encrypted Nostr Payloads

Some Buzz data is encrypted at the Nostr payload layer. Gift wraps, engrams,
event reminders, observer frames, and pairing messages all use encrypted content
or encrypted envelopes in different ways.

The relay can validate envelope shape, route by tags, and enforce read gates,
but it usually cannot read the encrypted plaintext. The metadata is still
visible: kind, pubkey, created timestamp, tags, event size, and routing
relationships. NIP-44 conversation keys are derived in memory from Nostr keys;
they are not stored as independent long-lived keys in the relay.

The important review rule is that encryption does not remove the need for relay
authorization. Encrypted global events still need p-gates, author gates,
indexing exclusions, and live fanout filtering.

### Channel Scope

Buzz uses the NIP-29 `h` tag for channels. Channel data is not scoped by `e`
tags. `h` tags and `channel_id` are checked throughout the relay.

Important code:

- `crates/buzz-relay/src/handlers/ingest.rs` resolves channel scope and checks
  membership before storing most channel events.
- `crates/buzz-relay/src/handlers/side_effects.rs` applies role checks for
  admin actions.
- `crates/buzz-relay/src/handlers/req.rs` checks channel access before
  registering subscriptions or returning historical results.
- `crates/buzz-core/src/filter.rs` performs final filter matching and
  per-event reader authorization.

Private channel reads and writes require membership. Open channels are
deliberately readable and writable by nonmembers, subject to relay-level auth
and any token restrictions. If relay membership is disabled, an arbitrary
authenticated Nostr identity can interact with open channels.

### Global Events And P-Gated Events

Some events are global instead of channel-scoped. Examples include profiles,
gift wraps, user state, agent engrams, reminders, and some Git or workflow
events.

Global events are a security sharp edge because they are not protected by
channel membership. The relay compensates with kind-specific checks:

- Gift wraps and DM visibility records are p-gated. Queries must include a
  `#p` tag that matches the authenticated user.
- Agent engrams must be requested by the author or by the user named in `#p`.
- Author-only kinds, such as event reminders, can only be queried by the author.
- Search excludes gift wraps, DM visibility records, and author-only records.

The relevant checks live in `crates/buzz-relay/src/handlers/req.rs`,
`crates/buzz-relay/src/handlers/event.rs`, and
`crates/buzz-core/src/filter.rs`.

One sharp edge: global-only kinds are stored with `channel_id = NULL`, but the
raw signed tags are still present. `crates/buzz-core/src/filter.rs` treats
explicit `h` tags as authoritative during filter matching. A malformed or
surprising global event with an `h` tag can therefore match a channel-style
filter even though it is not stored as a channel event. This should not leak
private channel data by itself, because the event is global already, but it can
confuse automation, counts, or UI assumptions.

### Live Fanout And Queries

Subscriptions are registered after auth and access checks in
`crates/buzz-relay/src/handlers/req.rs`. The subscription registry in
`crates/buzz-relay/src/subscription.rs` keeps channel and global subscriptions
separate. Channel subscriptions do not receive global events, and global
subscriptions do not receive channel events.

Live fanout also has a backstop in `crates/buzz-relay/src/handlers/event.rs`.
Private channel fanout is filtered by visibility and membership caches before
events are sent. Sensitive global kinds are filtered by recipient. Search
results are also post-filtered after Typesense returns matches.

This is one of the stronger parts of the system: authorization is checked both
before registering interest and before sending results.

### Replaceable Events, Deletions, And Side Effects

Nostr has replaceable and parameterized replaceable event kinds. Buzz handles
replacement behavior during ingest. It also has kind-specific validation for
deletions, edits, reactions, admin events, forum votes, and workflow commands.

Side effects are in `crates/buzz-relay/src/handlers/side_effects.rs`. This is
one of the most important files to review because it determines who can add or
remove members, change channel metadata, archive channels, delete groups, and
emit relay-signed discovery or notification events.

Good behavior in this area:

- Last-owner removal is guarded.
- Private channel admin changes require a member with sufficient role.
- Channel archive and visibility changes are restricted.
- Deletion has author and owner/admin checks.
- Open channel joins are allowed, but private channel joins are not open.

The important policy decision is that open channels are intentionally open to
nonmember writes. That is not a bug, but it must be clear in product and
deployment docs.

## Feature Review

### Relay, Auth, And Membership

The relay is the main enforcement point. It verifies Nostr signatures, checks
auth state, checks relay membership when enabled, checks channel membership, and
enforces per-kind rules.

Attack surface:

- WebSocket clients can send auth, event, req, close, and count messages.
- HTTP clients can use `/events`, `/query`, `/count`, media endpoints, Git
  endpoints, and workflow webhooks.
- Redis pub/sub messages are trusted enough to fan out events between relay
  instances.
- Postgres stores plaintext event content and tags for normal events.
- Typesense stores searchable plaintext for indexed events.

Good things:

- WebSocket frame size is bounded in `crates/buzz-relay/src/connection.rs`.
- There is handler concurrency control and heartbeat cleanup for dead clients.
- Unknown event kinds are rejected.
- Event content size and timestamp drift are bounded.
- Relay membership mode fails startup if required owner or relay key config is
  missing.
- Sensitive global kinds are p-gated or author-gated.

Risky things:

- Development defaults are permissive. `BUZZ_REQUIRE_AUTH_TOKEN=false`,
  `BUZZ_REQUIRE_RELAY_MEMBERSHIP=false`, permissive CORS defaults, and the
  hardcoded development relay key are acceptable for local development but
  dangerous if deployed accidentally.
- The relay has no first-class tenant ID in the schema. The isolation model is
  relay membership plus channel membership, not tenant membership.
- Redis, Postgres, Typesense, and S3 are all inside the trusted service
  boundary. A compromise of any of them exposes meaningful data.

### Channels, Messages, Threads, Reactions, And Deletions

Messages are signed Nostr events scoped to channels with `h` tags. Threads are
represented with NIP-10-style relationships. Replies update materialized thread
counters. Reactions and deletions are kind-specific events.

Attack surface:

- Malformed tags can try to confuse thread, channel, or deletion semantics.
- Message content is plaintext unless the specific event kind uses encryption.
- Open channels allow writes by nonmembers.
- Delete events can be used to hide or remove content if policy checks are
  wrong.

Good things:

- Channel membership is checked before normal private channel writes.
- Delete events require exactly one target tag and then ownership or role
  authorization.
- Reactions have deduplication logic.
- Archived channel checks block writes after archive.
- Thread counter behavior is centralized enough to review.

Risky things:

- Any new message-like kind must remember to use `h` tags and the same
  membership checks.
- Any new reply insertion path must update thread counters.
- Global event kinds carrying accidental `h` tags can surprise channel-style
  filters.

### Search

Search uses Typesense through `crates/buzz-search/src/lib.rs`. The relay indexes
accepted events and uses Typesense for NIP-50-style search. Query results are
post-filtered by the relay.

Attack surface:

- Typesense receives plaintext searchable content for indexed event kinds.
- Search filters must stay aligned with relay authorization rules.
- Search queue pressure can drop indexing work.

Good things:

- Gift wraps, DM visibility records, and author-only records are excluded from
  indexing.
- Search results are post-filtered after Typesense returns them.
- Accessible channel IDs are added to search filters.

Risky things:

- Typesense must be protected like a primary data store because it contains
  sensitive channel text for indexed kinds.
- Dropped indexing work can create security-adjacent confusion: users may think
  absence from search means absence from the system.

### Audit

Audit logging is handled by `crates/buzz-audit/src/*` and queued from the relay.
The audit path records accepted events and selected service actions.

Attack surface:

- Audit integrity depends on Postgres and the relay process.
- Queue send failures or worker failures can create gaps if not monitored.

Good things:

- Audit writes are separated from the main event path with backpressure.
- The audit service uses a hash-chain style design.

Risky things:

- This is not a tamper-proof external audit system. A database administrator or
  a relay host compromise can still affect the audit store.
- The security review should check whether queue and worker failures are
  surfaced strongly enough for production operations.

### Media Upload And Download

Media upload uses Blossom-style signed upload auth. The relay validates the
auth event before accepting the body. Files are validated by content type and
stored by hash in S3-compatible storage. The code is mainly in
`crates/buzz-relay/src/api/media.rs` and `crates/buzz-media/src/*`.

Attack surface:

- Uploaders can attempt oversized files, active content, media parser bugs, or
  content type confusion.
- Download URLs are unauthenticated once the hash URL is known.
- S3 credentials and bucket policy are part of the trusted boundary.

Good things:

- Upload auth is verified before reading the body.
- Upload auth binds the expected SHA-256 hash through the `x` tag.
- Image, video, and generic file validation reject many active content types.
- Generic files are served as attachments with defensive headers.
- The response content type comes from the validated sidecar metadata, not from
  untrusted request headers.
- Range reads are capped and stream from storage.

Risky things:

- `GET /media/...` and `HEAD /media/...` are unauthenticated. Media URLs are
  bearer-by-knowledge. Anyone with the URL can fetch the object.
- Media privacy depends on unguessable hashes and controlled sharing, not on
  per-request auth.
- Production mode depends on correct `X-Auth-Token` and S3 configuration.
- S3 buckets must not be public.

### Desktop Client And Workspaces

Desktop is a Tauri app. It holds the user's signing key in the backend process
and exposes signing commands to the frontend.

Important code:

- `desktop/src-tauri/src/app_state.rs`
- `desktop/src-tauri/src/commands/identity.rs`
- `desktop/src-tauri/src/commands/workspace.rs`
- `desktop/src/features/workspaces/workspaceStorage.ts`
- `desktop/src/features/workspaces/useWorkspaceInit.ts`

Attack surface:

- A compromised frontend or webview can ask the Tauri backend to sign events.
- Today it can also call `get_nsec` and export the user's private key.
- Local files in the app data directory contain identity and managed agent
  secrets.
- Workspace switching changes relay URL and remounts React state, but it does
  not create a separate per-workspace identity by default.

Good things:

- The desktop frontend migration strips old `nsec` values out of localStorage.
- The main user key is stored in `identity.key`, not localStorage.
- `identity.key` writes are atomic.
- On Unix, `identity.key` is written with mode `0600`.
- Corrupt `identity.key` files are quarantined rather than overwritten.
- Workspace switching resets known module-level caches in
  `desktop/src/features/workspaces/useWorkspaceInit.ts`.

Risky things:

- `identity.key` is an unencrypted Nostr private key on disk. It is protected by
  filesystem permissions, not by the OS keychain.
- `desktop/src-tauri/src/commands/identity.rs` exposes `get_nsec`. This means an
  XSS or compromised frontend can exfiltrate the full user private key, not only
  request signatures.
- `apply_workspace` accepts an optional `nsec` over IPC. The current frontend
  passes `undefined`, but the command surface still supports changing the
  signing key.
- Desktop workspaces are mostly relay URL profiles. The desktop identity is
  global unless explicitly replaced through env or IPC.

### Mobile Client

Mobile stores workspaces using Flutter secure storage. The workspace JSON can
include `nsec`, and auth uses that key to sign NIP-42 events.

Important code:

- `mobile/lib/shared/workspace/workspace_storage.dart`
- `mobile/lib/shared/workspace/workspace.dart`
- `mobile/lib/shared/auth/auth_provider.dart`

Attack surface:

- Device compromise or app compromise exposes the mobile Nostr key.
- Workspace JSON contains the key material needed to act as the user.

Good things:

- Mobile uses platform secure storage rather than normal localStorage.
- Auth failures can remove invalid or restricted workspaces.

Risky things:

- Secure storage improves local at-rest protection, but the app still needs the
  plaintext key while running.
- The mobile workspace model can hold different keys per workspace, unlike the
  current desktop default. That difference should be intentional and documented.

### Managed Agents

Managed agents are launched by the desktop app. Each managed agent has its own
Nostr keypair. The desktop stores the agent private key and passes it to the
agent process as environment variables.

Important code:

- `desktop/src-tauri/src/managed_agents/types.rs`
- `desktop/src-tauri/src/managed_agents/storage.rs`
- `desktop/src-tauri/src/managed_agents/runtime.rs`
- `desktop/src-tauri/src/managed_agents/env_vars.rs`
- `desktop/src-tauri/src/commands/agents.rs`
- `crates/buzz-acp/src/*`

The flow is: desktop creates an agent record, generates an agent Nostr keypair,
creates an owner delegation auth tag, stores both in the managed agent JSON
store, and later starts the ACP harness. The harness receives the agent command,
agent args, MCP command, relay URL, agent private key, and optional auth tag in
environment variables. The harness connects to Buzz as the agent, listens for
events it is allowed to respond to, and invokes the configured AI agent process.

Attack surface:

- The agent process can sign as the agent.
- The agent receives `BUZZ_PRIVATE_KEY` and `NOSTR_PRIVATE_KEY`.
- The agent may receive `BUZZ_AUTH_TAG`, which proves owner delegation in
  places that accept NIP-OA.
- User-provided environment variables and commands affect the child process.
- Agent stdout and stderr are written to local log files.

Good things:

- Agents use separate keys from the human owner.
- The owner key is not passed to the managed agent.
- Reserved environment variables are stripped from user-provided env.
- Malformed environment keys are rejected, including keys containing `=`.
- Agent process cleanup uses process groups where supported.
- Logs are rotated.

Risky things:

- `managed-agents.json` contains agent private keys and auth tags in app data.
  The write path is atomic, but it does not set explicit `0600` permissions the
  way `identity.key` does.
- Any tool available to the agent can read its own private key from the
  environment unless the tool is deliberately isolated.
- `BUZZ_AUTH_TAG` is a delegated credential. If an attacker has both the agent
  key and auth tag, they can act as that delegated agent wherever the relay
  accepts the owner delegation.
- ACP permission defaults should be reviewed carefully. The ACP config supports
  powerful modes, including bypass-style permissions, and the managed agent
  posture should match the user's expectation for local command execution.

### Developer MCP Server

The developer MCP server exposes local shell and file tools to agents. This is
not a sandbox. It is a controlled way to give an agent access to the developer's
machine.

Important code:

- `crates/buzz-dev-mcp/src/shell.rs`
- `crates/buzz-dev-mcp/src/paths.rs`
- `crates/buzz-dev-mcp/src/shim.rs`

Attack surface:

- The shell tool runs arbitrary `bash -c` commands.
- File tools can read and edit paths outside the repo.
- The shell child environment intentionally includes `BUZZ_PRIVATE_KEY` so the
  `buzz` CLI works.
- Git signing helpers are configured with a temporary keyfile.

Good things:

- Command duration, output size, and artifact size are bounded.
- Process groups are killed on timeout or cancellation where supported.
- The shim removes `NOSTR_PRIVATE_KEY` and uses a `0600` temporary keyfile for
  Git helpers.
- The session temp directory is created with restrictive permissions.

Risky things:

- This is local code execution by design. Any agent with this MCP server can
  read files, run commands, and exfiltrate secrets available to its process.
- There is no path containment in the file tools.
- `BUZZ_PRIVATE_KEY` remains available to shell commands.

### Workflows

Workflows are YAML or JSON definitions executed by the workflow engine. They can
run conditions, add reactions, call webhooks, and wait for approvals.

Important code:

- `crates/buzz-workflow/src/executor.rs`
- `crates/buzz-relay/src/handlers/command_executor.rs`
- `crates/buzz-relay/src/webhook_secret.rs`
- `crates/buzz-relay/src/api/bridge.rs`
- `crates/buzz-db/src/workflow.rs`

Attack surface:

- Workflow definitions can call outbound webhooks.
- Webhook triggers expose an unauthenticated HTTP endpoint protected by a
  workflow secret.
- Conditions are evaluated from user-controlled expressions.
- Approval tokens control resumable workflow execution.

Good things:

- Webhook outbound calls reject private and reserved IPs after DNS resolution.
- The HTTP client pins the resolved IP and disables redirects.
- Webhook response bodies are capped.
- Condition expression length is bounded and evaluation has a timeout.
- Workflow webhook secrets are generated with random UUID v4 values and compared
  in constant time.
- Workflow approval tokens are stored as SHA-256 hashes.

Risky things:

- Workflow webhook secrets are stored inside the workflow definition in
  Postgres under `_webhook_secret`. They are stripped from normal responses and
  returned once at creation, but DB compromise exposes them.
- The webhook endpoint also accepts `?secret=...`. Headers are preferred, but
  query parameters are often logged by proxies.
- Workflow outbound webhooks can exfiltrate data by design. That means workflow
  creation and editing permissions matter.
- The command executor notes that command event idempotency and domain mutation
  writes are not always in a single transaction. That can produce event/mutation
  divergence in failure cases.

### Git

Buzz implements Git smart HTTP backed by object storage and Nostr auth. All Git
HTTP routes require NIP-98 auth. Push policy is enforced by a pre-receive hook
callback.

Important code:

- `crates/buzz-relay/src/api/git/transport.rs`
- `crates/buzz-relay/src/api/git/policy.rs`
- `crates/buzz-relay/src/api/git/store.rs`
- `crates/buzz-relay/src/api/git/cas_publish.rs`
- `crates/git-credential-nostr/src/lib.rs`
- `crates/git-sign-nostr/src/lib.rs`

Attack surface:

- Git clients stream packfiles to the relay.
- The Git credential helper signs NIP-98 credentials.
- Push policy depends on hook callback integrity.
- Object storage holds repository data.
- Git subprocesses are launched by the relay.

Good things:

- Repo IDs are validated: owner must be a lowercase 64-char pubkey, and repo
  names are limited.
- Git subprocess environments are cleared and rebuilt with minimal variables.
- The push policy hook uses HMAC-SHA256 over a canonical payload.
- Hook callbacks have a short freshness window.
- Push policy checks repo ownership, channel binding, archive state, roles, and
  branch rules.
- Object publication uses content-addressed storage and compare-and-swap style
  manifest pointers.

Risky things:

- Git auth intentionally signs the repo-root URL, not the exact Git service URL,
  because Git credential protocol does not pass query strings cleanly.
- Method checking is intentionally relaxed because the same credential is reused
  across GET and POST.
- Packfile bodies are not covered by a NIP-98 payload hash because they are
  streamed.
- Git auth does not use the generic NIP-98 replay cache. The design relies on
  short timestamp freshness, URL binding, TLS, and push policy.
- A captured Git HTTP credential can likely be replayed briefly for the same
  repo within the freshness window.
- Local repo name reservation currently has a cross-instance caveat. Separate
  relay instances with separate disks can race to grant the same display name.

### Pairing

Pairing lets one device transfer secret material to another device using a QR
payload, ephemeral keys, encrypted events, and a short authentication string.

Important code:

- `crates/buzz-core/src/pairing/crypto.rs`
- `crates/buzz-core/src/pairing/qr.rs`
- `crates/buzz-core/src/pairing/session.rs`
- `crates/buzz-pair-relay/src/lib.rs`
- `crates/buzz-pairing-cli/src/main.rs`

Attack surface:

- The QR URI contains a 32-byte session secret.
- Pairing events are encrypted, but the sidecar relay can see metadata.
- Device users must compare the short authentication string.
- Pairing payloads can contain private key material.

Good things:

- Pairing uses ephemeral keys and HKDF-derived session state.
- Transcript hashes are checked.
- Short authentication string confirmation is required before payload acceptance.
- Pairing session timeout is short.
- Pairing event signatures and IDs are verified.
- Pairing relay has tight limits: short TTL, small frames, small per-connection
  budgets, deduplication, and no persistence.
- Secret buffers use zeroization in several places.

Risky things:

- The QR code is a secret. A screenshot, camera, or screen share can expose the
  session secret.
- SAS confirmation is a human security step. If users skip or misunderstand it,
  pairing can be attacked.
- Some temporary plaintext copies can still exist because serde and NIP-44
  internals allocate strings.
- The pairing relay is intentionally unauthenticated and should be exposed only
  in the intended narrow deployment shape.

### Huddle Audio

Huddle audio is a WebSocket audio relay for channel rooms.

Important code:

- `crates/buzz-relay/src/audio/handler.rs`
- `crates/buzz-relay/src/audio/room.rs`
- `crates/buzz-relay/src/audio/wire.rs`

Attack surface:

- Audio clients authenticate over WebSocket.
- The relay receives audio frames and forwards them to room peers.
- Telemetry such as audio level is client-provided.

Good things:

- Huddle connections use NIP-42 auth.
- Relay membership and channel membership are checked.
- Room size, frame size, text control frames, heartbeat, and peer admission are
  bounded.
- Room version is pinned.
- Audio level telemetry is treated as untrusted and clamped.

Risky things:

- Audio is relayed through the server. It is not end-to-end encrypted at the
  application layer.
- The relay can observe room metadata and audio frame traffic.
- Any future moderation or trust decision must not rely on client-supplied audio
  level telemetry.

### NIP-28 Proxy Compatibility

The proxy provides compatibility with clients that expect NIP-28 behavior. It
maps NIP-28-style interactions to Buzz channel behavior.

Important code:

- `crates/buzz-proxy/src/*`
- `NOSTR.md`

Attack surface:

- The proxy has its own server key, salt, admin secret, and API token config.
- It creates deterministic shadow identities for compatibility behavior.
- Private channels require the proxy server pubkey to be a member.

Good things:

- Proxy config keeps the compatibility layer separated from the core direct
  relay path.
- Private channel behavior depends on explicit proxy membership.

Risky things:

- Shadow identity derivation and proxy secrets are security-sensitive. If the
  salt or proxy server key changes, identity continuity and trust assumptions
  change.
- Proxy admin secrets and API tokens need production-grade secret storage.

### Multi-Tenancy And Workspaces

Today, Buzz has workspace switching in the desktop app and relay-level
membership in the relay. It does not yet have a first-class tenant ID that is
carried through every table, query, cache, search index, S3 key, and pub/sub
topic.

Important code:

- `migrations/0001_initial_schema.sql`
- `crates/buzz-db/src/relay_members.rs`
- `crates/buzz-relay/src/handlers/relay_admin.rs`
- `desktop/src/features/workspaces/useWorkspaces.tsx`
- `desktop/src/features/workspaces/workspaceStorage.ts`
- `desktop/src-tauri/src/commands/workspace.rs`

Current behavior:

- Relay membership is global to a relay.
- Channel membership is per channel.
- Events have optional `channel_id`, but no `tenant_id`.
- Global events are shared within the relay.
- Desktop workspaces are mostly relay URL profiles with local metadata.
- Desktop switches workspace by changing relay URL state and remounting the
  React app subtree.

Attack surface:

- Any shared relay deployment uses one database realm unless tenant scoping is
  added.
- Global events, relay members, API tokens, workflows, media, search, audit,
  Redis pub/sub, and S3 keys all need a tenant story before multi-tenant hosting
  can be considered isolated.
- Client-side workspace switching can accidentally retain module-level caches
  unless each singleton is reset.

Good things:

- Workspace switching already has an explicit reset path in
  `desktop/src/features/workspaces/useWorkspaceInit.ts`.
- Relay membership mode provides a useful coarse admission control for private
  deployments.
- Channel access checks are centralized enough that tenant scoping can be added
  deliberately.

Risky things:

- Without a tenant ID, "multi-tenant" means multiple users or workspaces inside
  one relay security domain, not hard tenant isolation.
- Typesense indexes, Redis channels, S3 object keys, audit logs, API tokens, and
  workflow state must all be scoped if a single relay serves multiple tenants.
- Desktop uses one default identity across workspaces. That may be correct for a
  user moving between relays, but it is not the same as per-tenant identity
  separation.

## Keys And Secrets

This section lists the important keys and secrets, where they live, and what
happens if they are compromised.

| Key or secret | Where it is stored or passed | Used for | Compromise impact |
| --- | --- | --- | --- |
| Human Nostr private key, desktop | `{app_data_dir}/identity.key`; `BUZZ_PRIVATE_KEY` env can override; exportable through `get_nsec` | Signs user events, NIP-42 auth, NIP-98 auth, observer control events | Full account compromise for that Nostr identity |
| Human Nostr private key, mobile | Flutter secure storage workspace JSON, including `nsec` | Signs mobile user events and auth | Full account compromise on mobile identity |
| Human Nostr private key, CLI and Git tools | `BUZZ_PRIVATE_KEY`, `NOSTR_PRIVATE_KEY`, or Git config `nostr.keyfile` | CLI event signing, Git credentials, Git object signatures | Full account compromise for that key |
| Managed agent private key | `desktop` app data under `agents/managed-agents.json`; child env as `BUZZ_PRIVATE_KEY` and `NOSTR_PRIVATE_KEY`; dev MCP temp keyfile for Git | Signs agent events and auth | Attacker can act as the managed agent |
| NIP-OA auth tag | Managed agent record and child env `BUZZ_AUTH_TAG`; also Git config path in some tools | Proves an agent is delegated by an owner key | With the agent key, attacker can act as delegated agent where NIP-OA is trusted |
| Relay private key | `BUZZ_RELAY_PRIVATE_KEY` env; hardcoded dev fallback only when auth token is not required | Signs relay/system/discovery/notification events | Attacker can forge relay-signed system behavior and damage trust in relay events |
| Relay owner pubkey | `RELAY_OWNER_PUBKEY` env and `relay_members` table | Bootstraps relay owner membership | Wrong value gives owner control to wrong pubkey |
| API tokens | Raw token returned to caller; SHA-256 hash stored in `api_tokens` | Scoped API access, especially media upload in production | Raw token grants its configured scopes until revoked or expired |
| Workflow webhook secret | Stored inside workflow definition as `_webhook_secret`; returned once at creation; sent as `X-Webhook-Secret` or `?secret=` | Authenticates external webhook triggers | Anyone with the secret can trigger that workflow |
| Workflow approval token | Raw token generated by workflow engine; SHA-256 hash stored in DB | Approves or denies waiting workflow steps | Hash leak is less useful than raw token, but approval authorization still needs review around token delivery |
| Blossom upload auth event | Short-lived signed event in HTTP `Authorization: Nostr ...` | Authorizes one upload hash | Replay within validity window may upload the same hash if other checks allow it |
| S3 media credentials | `BUZZ_S3_ACCESS_KEY`, `BUZZ_S3_SECRET_KEY`, `BUZZ_S3_ENDPOINT`, `BUZZ_S3_BUCKET` | Media object storage | Attacker can read or write stored media if bucket policy also allows it |
| S3 Git credentials | `BUZZ_GIT_S3_*` or fallback S3 env vars | Git object and manifest storage | Attacker can read or tamper with Git backing storage depending on bucket permissions |
| Typesense API key | `TYPESENSE_API_KEY` env | Search indexing and querying | Attacker can read indexed plaintext content or tamper with search results |
| Database URL and credentials | `DATABASE_URL` env | Primary Postgres access | Attacker can read and mutate almost all application state |
| Redis URL and credentials | `REDIS_URL` env | Pub/sub, presence, cache coordination | Attacker can inject or observe live coordination data depending on Redis access |
| Git hook HMAC secret | `BUZZ_GIT_HOOK_HMAC_SECRET` env, random dev fallback | Authenticates pre-receive hook callbacks to relay policy endpoint | Attacker can forge hook policy callbacks |
| Proxy server key, salt, admin secret, API token | Proxy env vars documented in `NOSTR.md` | NIP-28 compatibility behavior and proxy administration | Attacker can impersonate proxy behavior or administer proxy depending on secret |
| Pairing session secret | Encoded in `nostrpair://...secret=...` QR URI | Establishes pairing session | Anyone who sees it can participate in the pairing attempt unless SAS confirmation stops them |
| Pairing ephemeral private keys | In memory during a pairing session | Establishes encrypted pairing messages and SAS | Compromise during the short session can attack that pairing |
| NIP-44 derived conversation keys | Derived in memory from Nostr private keys | Encrypts and decrypts NIP-44 payloads | Compromise allows plaintext access for that derived conversation context |

## Security Strengths

These are the design and implementation choices that look good from a security
review point of view.

- Normal actions are signed by user or agent Nostr keys.
- Event IDs and signatures are verified before storage.
- Unknown kinds are rejected.
- NIP-42 auth uses random challenges, relay binding, and timestamp freshness.
- NIP-98 auth verifies URL, method, timestamp, signature, and payload hash when
  present.
- WebSocket frames, event content, historical limits, media sizes, workflow
  expressions, webhook responses, and audio frames have bounds.
- Channel and global subscriptions are kept separate.
- Private channel live fanout is filtered again at send time.
- Sensitive global kinds are p-gated or author-gated.
- Search results are post-filtered after Typesense.
- Gift wraps and other sensitive global kinds are excluded from search.
- Relay membership mode fails startup if required production secrets are absent.
- Desktop no longer stores the user `nsec` in localStorage.
- Desktop user key writes use atomic writes and `0600` permissions on Unix.
- Mobile uses secure storage for workspace secrets.
- Managed agent environment handling strips reserved variables and rejects
  malformed env keys.
- The dev MCP shim removes `NOSTR_PRIVATE_KEY` and uses a `0600` temporary
  keyfile for Git helpers.
- Workflow outbound webhooks have SSRF defenses: private IP rejection, DNS
  pinning, no redirects, timeout, and response body cap.
- Git subprocess environments are hardened.
- Git push policy callbacks use HMAC and a short freshness window.
- Pairing uses ephemeral keys, transcript binding, SAS confirmation, and a
  tightly limited sidecar relay.
- Huddle audio has auth, membership checks, frame bounds, room caps, and
  untrusted telemetry handling.

## Security Sharp Edges

These are the areas I would prioritize in a security review.

1. Desktop private key exposure

   `desktop/src-tauri/src/commands/identity.rs` exposes `get_nsec`, and the
   desktop key is stored unencrypted in `identity.key`. Filesystem permissions
   help, but a frontend compromise can export the key directly. For a desktop
   app that renders remote or semi-trusted content, this is one of the highest
   risk areas.

2. Managed agent private key storage

   Managed agent records contain agent private keys and auth tags. They are
   stored in JSON in the app data directory and passed to child processes in env
   vars. This is simple and useful, but it means any local process compromise or
   agent tool compromise can steal an agent identity.

3. Agent tool authority

   `buzz-dev-mcp` is intentionally powerful. It can run shell commands and
   access files outside the repo. This should be described to users as local
   code execution, not as a restricted tool sandbox.

4. Multi-tenancy is not hard isolation yet

   The schema does not carry a tenant ID. Relay membership and channel
   membership are useful, but they are not the same thing as tenant isolation.
   Before hosting multiple tenants on one relay, tenant scope needs to be added
   to Postgres queries, Typesense indexes, Redis pub/sub, S3 object keys, audit
   logs, workflow state, API tokens, media, Git storage, caches, and relay admin
   state.

5. Development defaults are unsafe for production

   The relay defaults are convenient for local development. In production, the
   dangerous settings are no relay membership, no auth token requirement,
   permissive CORS, dev Typesense and S3 credentials, and the hardcoded dev
   relay key fallback.

6. Git NIP-98 replay tradeoffs

   Git auth intentionally relaxes URL, method, body hash, and replay behavior
   because of Git smart HTTP constraints. The design may be acceptable, but it
   should be explicitly reviewed as a replay window protected by TLS and short
   freshness, not as full NIP-98 request binding.

7. NIP-98 payload hash is optional

   The generic NIP-98 verifier accepts missing payload hashes. For non-streaming
   state-changing routes, Buzz should consider requiring payload binding unless
   there is a specific reason not to.

8. Media URLs are bearer-by-knowledge

   Media download is unauthenticated. That is a valid product choice if media
   hashes are treated as share links, but it should not be mistaken for private
   media authorization.

9. Workflow secrets are stored in database definitions

   Workflow webhook secrets are stripped from normal responses, but they are in
   Postgres. Query-param secrets are also supported. Header-only secrets and
   stronger secret storage would reduce accidental leakage.

10. Typesense contains sensitive plaintext

   Typesense should be treated as sensitive infrastructure. It can contain
   indexed channel content even when Postgres access is otherwise controlled.

11. Global event `h` tag behavior is surprising

   Global-only events can still contain signed `h` tags. Because filter matching
   respects explicit tags, these events can match channel-style filters even
   though they are stored globally. That is not necessarily a data leak, but it
   is a confusing edge that can affect automation.

12. Relay/system key blast radius

   The relay private key signs system events, discovery events, and membership
   notifications. A relay key compromise lets an attacker forge relay-authored
   system behavior. It should be stored and rotated like a production signing
   key, not like a normal config value.

## Suggested Review Priorities

For a first security review pass, I would focus on these areas in order.

1. Desktop key handling and Tauri command exposure

   Review `get_nsec`, `import_identity`, `sign_event`, observer encryption
   commands, frontend trust assumptions, CSP, remote content rendering, and
   whether the private key can move to OS keychain-backed signing without direct
   export to the frontend.

2. Managed agent launch and local tool model

   Review managed agent key storage permissions, auth tag storage, env passing,
   logs, command configuration, ACP permission defaults, and how clearly the UI
   communicates local command authority.

3. Relay authorization invariants

   Review `ingest.rs`, `req.rs`, `event.rs`, `side_effects.rs`, and
   `filter.rs` together. The key question is whether every event kind has clear
   rules for who can write it, who can read it, whether it is channel or global,
   whether search can index it, and whether live fanout matches historical
   query behavior.

4. Multi-tenant design

   Decide whether a "tenant" is a relay, an org inside a relay, a workspace, or
   something else. If tenants share one relay process and database, add tenant
   scope explicitly before treating the deployment as isolated.

5. Git auth and push policy

   Review the Git NIP-98 exception model, replay window, credential helper
   behavior, hook HMAC, object storage CAS behavior, and repo name reservation
   across multiple relay instances.

6. Workflow and media exfiltration

   Review who can create workflows, where webhook secrets appear, whether query
   secrets can be removed, what data workflows can send out, and whether media
   URL privacy matches product expectations.

7. Production configuration hardening

   Add deployment checks or docs that make production requirements hard to miss:
   relay private key, relay membership, strict CORS, real Typesense key, private
   S3 bucket, strong Git hook secret, TLS, Redis/Postgres network isolation, and
   secret rotation paths.

## Things To Know While Reviewing Code

- The most important relay files are `ingest.rs`, `event.rs`, `req.rs`,
  `side_effects.rs`, and `filter.rs`. Read them as a set.
- Do not assume a Nostr kind is safe because it is signed. Signatures prove who
  authored the event; they do not say the author was allowed to perform the
  action.
- Do not assume global events are harmless. Global events need their own read
  gates and indexing rules.
- Do not assume desktop workspaces are tenants. They are local relay profiles
  unless backed by server-side tenant isolation.
- Do not assume agents are sandboxed. The default developer tool model gives
  agents local machine power.
- Do not assume encrypted content hides metadata. Gift wraps, engrams,
  reminders, observer frames, and pairing events still expose kinds, pubkeys,
  timestamps, tags, and routing metadata.
- Do not assume relay-signed events are user intent. They are relay assertions,
  and their trust depends on the relay private key and relay implementation.
- Do not assume media hashes are private authorization. They are unguessable
  object references, but anyone who learns the URL can fetch the object.