Trust, federation, and audiences

birdd is distributed: your community’s node can exchange observations with other communities instead of relying on one central database. Three related ideas govern that exchange:

• Identity and trust answer which flock produced an event and which other flocks your node recognizes.
• Federation copies signed events between flock nodes through relays.
• Audiences determine which representation of a local event is sent and who can receive it.

Flock identity

Each flock has a cryptographic key pair. Its public key is its stable identity, and its familiar name is a mutable label. A flock can change their display name without changing their stable identity, defined by the public key.

The private key signs observations, corrections, deletions, and metadata. A valid signature establishes that an event was signed by the holder of that flock’s key and has not been modified since.

The node operator is responsible for protecting the flock’s private key. If it is lost, there is currently no identity recovery or key rotation mechanism.

Trust is local

Your node operator decides which public keys to trust and assigns local names to them. Another flock cannot make your node trust it by publishing its name as someone you already trust.

Signal queries include local observations and observations signed by directly trusted flocks. They exclude observations from other flocks, as well as observations dated in the future. Trusting a flock identifies an accepted source.

This filter is specific to Signal, not a universal access boundary. The CLI and Grist’s Following_Remote table can include valid remote observations retained by the node regardless of trust status. Access to media has additional authorization rules described below.

Trust and permission to use a restricted audience are separate decisions. A node can receive and retain a valid event without making that event visible in every user interface.

How federation works

An observation is recorded as a signed event in its origin flock’s log. Corrections and deletions append new signed events rather than silently changing the original history. User interfaces normally show the latest valid state.

Nodes publish and retrieve events through Nostr-compatible relays:

flowchart LR
    origin[Origin flock] -->|signed event| relay[Relay]
    relay -->|sync| neighbor[Receiving flock]

Relays help disconnected flocks catch up and allow more than one relay to carry the same deterministic event.

Federation is not necessarily immediate. A node or relay may be offline, and a restricted audience may deliberately delay publication. Search results can therefore differ between flocks or catch up later.

Audiences

An audience is an operator-defined sharing policy. It answers:

1. Which fields and timestamp precision leave the node?
2. Is that representation public or encrypted for named recipients?

An observation can be represented in more than one audience. For example, a flock could publish a minimal public representation and send a more detailed version to a restricted group of neighboring flocks.

The current public projection includes the subject, exact observation time, notes, tags, media references, and extensions. It does not include location. A media reference does not make the media bytes public: fetching them requires a signed request from a flock directly trusted by the media’s origin.

A restricted projection can coarsen the observation time to an hour or UTC day, delay publication, omit notes, tags, location, or media, and allow only selected extensions. Extension selection includes each chosen envelope in full, not only the fields shown in Signal or Grist. The subject and observation identity are always included.

Timestamp coarsening applies to when the observation reportedly occurred. It does not hide the exact time the event was created, which remains visible to an authorized recipient. Delayed publication likewise does not conceal that original creation time after delivery.

Important

A restricted audience limits delivery; it cannot control what an authorized recipient does after decryption. Recipients can retain or copy data. Do not record sensitive information solely because the audience is restricted.

Audience policy is selected by the node operator for local events. Signal, Grist, and CLI users do not currently choose an audience for each observation. Ask your operator which audiences are active before recording sensitive notes, tags, media, or extension data.

Receiving and trusting are different

Restricted federation has separate inbound and outbound lists:

• Recipients are flocks that receive this node’s restricted events.
• Allowed senders are flocks whose restricted events this node accepts.
• Directly trusted flocks are sources included by Signal queries and are eligible for media access.

These lists do not imply one another. Being trusted does not automatically make a flock a restricted recipient, and receiving an encrypted event does not automatically make its signer trusted. Media access also requires a signed request and a live observation that disclosed the media reference. A restricted recipient must have received a published projection that included it.

Corrections, deletion, and privacy

Corrections and deletions are signed history. A deletion tells conforming nodes to remove an observation from their current view, but it cannot guarantee that relay operators or prior recipients erase copies they already possess.

Changing audience policy affects future representations and can permanently suppress restricted deliveries that were queued but not yet published. It does not recall published events or automatically share older history with a newly added audience.

An older observation cannot be corrected or deleted when it lacks a representation for every audience that is currently selected. The operator must backfill the missing representation first, but this version of birdd does not yet provide a backfill command. Treat publication, especially public publication, as irreversible.

Questions for your operator

Before contributing observations, it is reasonable to ask:

• Does this flock publish to a public audience?
• Which fields are included in each restricted audience?
• Which flocks receive restricted observations?
• Is publication delayed or are timestamps made less precise?
• Which remote flocks are directly trusted in search results?
• Who can use Grist or other administrative interfaces to make corrections?

Node operators can find implementation and configuration details in Identity and trust and Federation and audiences.