Peering: how does the receiver decide a recipient "exists"? (blocks the cmd/cairnd wiring)

Cordy commented

2026-08-05 17:37:08 +00:00

Owner

Surfaced while wiring #102 into cmd/cairnd. The transport is merged (PR #122)
but nothing constructs it yet, because this question has no answer in the code.

The problem

IMPLEMENTED-PEERING.md §4.3 is the core of Manuel's design: "the receiving
instance verifies the recipient exists locally before any bytes flow."
PrepareTransfer needs a peering.Recipients implementation to call.

There isn't one, and it is not an oversight in the peering package — the
information does not exist:

local mode — auth.Local holds users map[string]string (unexported).
Answerable, but needs an exported accessor.
oidc mode — the instance holds no list of users at all. A user does
not exist locally until they first log in. Cairn consumes identity, it does
not implement it (ARCHITECTURE §5.4), so there is nothing to enumerate.
ldap mode — same: search-then-bind authenticates a presented
credential; it is not a roster.

So in two of the three auth modes there is currently nothing to ask.

Options

A. Home directory on the storage backend (recommended).
Define existence as "/home/<recipient> exists". Uniform across all three auth
modes, needs no new auth surface, and fails safe: a user who has never logged in
has no home, so the transfer is refused — which is correct, because delivery
would have had nowhere to put the file. Requires auth.perUserHomes, which
peering delivery already assumes (§5: delivery lands in
/home/<recipient>/Inbox/<peer>/).
Cost: a peer can probe which users have ever logged in. §4.3 already accepts
that enumeration for authenticated, allow-listed peers.

B. Ask the IdP. Reuse #96's admin client to query the directory. Most
"correct" answer, but only works when the admin client is configured, adds a
network round trip inside PrepareTransfer, and makes an inbound transfer
depend on IdP availability.

C. Admin-maintained inbound allow-list per peering. Symmetric with the
outbound sender allow-list (§4.2), leaks nothing, and is fully deterministic —
but it is manual work per recipient and will be forgotten in practice.

D. Accept anything, decide at delivery. Rejected: it discards the property
§4.3 exists for and would let a peer upload gigabytes before discovering the
recipient is unknown.

Recommendation

A, with C available later as an optional narrowing for admins who do not
want the probe surface. If A is chosen, auth.perUserHomes becomes a hard
prerequisite for enabling peering, and that belongs in the docs handbook and in
the admin UI at peering setup.

Also needed once this is decided

peering.* config: staging dir, external base URL (for the absolute upload
URL), maxFileBytes.
Construct grpc.Server, register peering.Service, wrap root with
peering.Mux, mount BlobHandler at /peer/v1/blob/.
A Deliverer — that is #104.

Natural companion to #103, which needs the same config surface.

Surfaced while wiring #102 into `cmd/cairnd`. The transport is merged (PR #122) but nothing constructs it yet, because this question has no answer in the code. ## The problem `IMPLEMENTED-PEERING.md` §4.3 is the core of Manuel's design: *"the receiving instance verifies the recipient exists locally before any bytes flow."* `PrepareTransfer` needs a `peering.Recipients` implementation to call. There isn't one, and it is not an oversight in the peering package — the information does not exist: - **`local` mode** — `auth.Local` holds `users map[string]string` (unexported). Answerable, but needs an exported accessor. - **`oidc` mode** — the instance holds **no list of users at all**. A user does not exist locally until they first log in. Cairn consumes identity, it does not implement it (ARCHITECTURE §5.4), so there is nothing to enumerate. - **`ldap` mode** — same: `search-then-bind` authenticates a presented credential; it is not a roster. So in two of the three auth modes there is currently nothing to ask. ## Options **A. Home directory on the storage backend (recommended).** Define existence as "`/home/<recipient>` exists". Uniform across all three auth modes, needs no new auth surface, and fails safe: a user who has never logged in has no home, so the transfer is refused — which is *correct*, because delivery would have had nowhere to put the file. Requires `auth.perUserHomes`, which peering delivery already assumes (§5: delivery lands in `/home/<recipient>/Inbox/<peer>/`). Cost: a peer can probe which users have ever logged in. §4.3 already accepts that enumeration for authenticated, allow-listed peers. **B. Ask the IdP.** Reuse #96's admin client to query the directory. Most "correct" answer, but only works when the admin client is configured, adds a network round trip inside `PrepareTransfer`, and makes an inbound transfer depend on IdP availability. **C. Admin-maintained inbound allow-list per peering.** Symmetric with the outbound sender allow-list (§4.2), leaks nothing, and is fully deterministic — but it is manual work per recipient and will be forgotten in practice. **D. Accept anything, decide at delivery.** Rejected: it discards the property §4.3 exists for and would let a peer upload gigabytes before discovering the recipient is unknown. ## Recommendation **A**, with **C** available later as an optional narrowing for admins who do not want the probe surface. If A is chosen, `auth.perUserHomes` becomes a hard prerequisite for enabling peering, and that belongs in the docs handbook and in the admin UI at peering setup. ## Also needed once this is decided - `peering.*` config: staging dir, external base URL (for the absolute upload URL), `maxFileBytes`. - Construct `grpc.Server`, register `peering.Service`, wrap `root` with `peering.Mux`, mount `BlobHandler` at `/peer/v1/blob/`. - A `Deliverer` — that is #104. Natural companion to #103, which needs the same config surface.

Cordy added this to the v0.5 — Instance peering (federation v1) milestone

2026-08-05 17:37:08 +00:00

Cordy commented

2026-08-05 17:37:28 +00:00

Author

Owner

Carried over from #118, which is closed for the part it was titled for (the dependency claims in README + ARCHITECTURE §1.4, settled in PR #122).

Its final paragraph also asked to fold in example.config.json + the deployment handbook page gaining the peering block, and a handbook peering page (#109 pipeline). That deliberately did not ship with #122: beyond peering.statePath those config fields do not exist yet — they are blocked on this issue — and documenting them now would describe software that does not exist, which is the exact failure mode #118 was created to prevent.

So it belongs here: whichever option is chosen, the config surface, example.config.json, the handbook deployment page and the handbook peering page all land with the wiring.

If option A is chosen, the handbook must also state plainly that auth.perUserHomes is a hard prerequisite for enabling peering, and the admin UI should say so at peering setup rather than failing at the first inbound transfer.

Carried over from #118, which is closed for the part it was titled for (the dependency claims in README + ARCHITECTURE §1.4, settled in PR #122). Its final paragraph also asked to fold in `example.config.json` + the deployment handbook page gaining the `peering` block, and a handbook peering page (#109 pipeline). That deliberately did **not** ship with #122: beyond `peering.statePath` those config fields do not exist yet — they are blocked on this issue — and documenting them now would describe software that does not exist, which is the exact failure mode #118 was created to prevent. So it belongs here: whichever option is chosen, the config surface, `example.config.json`, the handbook deployment page and the handbook peering page all land with the wiring. If option A is chosen, the handbook must also state plainly that `auth.perUserHomes` is a hard prerequisite for enabling peering, and the admin UI should say so at peering setup rather than failing at the first inbound transfer.

Cordy commented

2026-08-05 18:11:43 +00:00

Author

Owner

Decided (Nikola, 2026-08-05): A + C together.

Rationale: peering was defined from the start as admins choosing which users and groups may communicate with which peer. The per-recipient allow-list is manual by design, not a burden to be avoided — so there is no reason to ship A alone and treat C as a later narrowing.

A structural point this surfaces

The registry today has only the outbound direction. Peer.Senders{Users,Groups} (§4.2) answers "who on THIS instance may send to that peer", and CanSend enforces it.

C is the inbound mirror: "which of MY users may receive from that peer". That field does not exist. So A+C means extending Peer:

{
  "name": "omega",
  "url": "https://files.omega.example",
  "key": "CAIRN-PEER1....",
  "senders":   { "users": ["zeus321"], "groups": ["legal"] },   // outbound, exists
  "receivers": { "users": ["hades123"], "groups": ["records-unit"] }  // inbound, NEW
}

Same Senders struct type, same fail-closed semantics, same live-group evaluation (#96) so revoking a group membership revokes the ability to receive within the cache TTL. The admin UI grows one more picker beside the existing one, which matches how an admin already thinks about a peering: these people, that peer, both directions.

How A and C compose

AND, not OR. A recipient must be allow-listed for that peering and have a home. Fail closed, consistent with CanSend.

Corollary worth deciding deliberately: the refusal for "not allow-listed" and "no such user" should be the same STATUS_UNKNOWN_RECIPIENT. §4.3 accepts enumeration for authenticated peers, but distinguishing the two would additionally leak "this user exists here, you just aren't cleared for them" — which is a fact about our org chart, not about the transfer. Losing that distinction costs a peer admin very little; they can ask.

Consequences to honour when wiring

auth.perUserHomes becomes a hard prerequisite. Peering setup must refuse at configuration time with a clear reason, not accept a transfer and fail at delivery. Note the dogfood instance may not currently have it enabled — verify before #106.
IMPLEMENTED-PEERING.md §4.3 needs rewriting: it currently describes the existence check alone. It should describe A+C, the AND, and the single refusal code.
§4.2 needs a companion paragraph for the inbound list, and the JSON example above.
Registry: new Receivers field, a CanReceive mirroring CanSend, both fail-closed on an unknown peer or empty list.

**Decided (Nikola, 2026-08-05): A + C together.** Rationale: peering was defined from the start as admins choosing which users and groups may communicate with which peer. The per-recipient allow-list is manual **by design**, not a burden to be avoided — so there is no reason to ship A alone and treat C as a later narrowing. ## A structural point this surfaces The registry today has only the **outbound** direction. `Peer.Senders{Users,Groups}` (§4.2) answers *"who on THIS instance may send to that peer"*, and `CanSend` enforces it. C is the **inbound** mirror: *"which of MY users may receive from that peer"*. That field does not exist. So A+C means extending `Peer`: ```jsonc { "name": "omega", "url": "https://files.omega.example", "key": "CAIRN-PEER1....", "senders": { "users": ["zeus321"], "groups": ["legal"] }, // outbound, exists "receivers": { "users": ["hades123"], "groups": ["records-unit"] } // inbound, NEW } ``` Same `Senders` struct type, same fail-closed semantics, same live-group evaluation (#96) so revoking a group membership revokes the ability to receive within the cache TTL. The admin UI grows one more picker beside the existing one, which matches how an admin already thinks about a peering: *these people, that peer, both directions*. ## How A and C compose **AND, not OR.** A recipient must be allow-listed for that peering *and* have a home. Fail closed, consistent with `CanSend`. Corollary worth deciding deliberately: the refusal for "not allow-listed" and "no such user" should be the **same** `STATUS_UNKNOWN_RECIPIENT`. §4.3 accepts enumeration for authenticated peers, but distinguishing the two would additionally leak *"this user exists here, you just aren't cleared for them"* — which is a fact about our org chart, not about the transfer. Losing that distinction costs a peer admin very little; they can ask. ## Consequences to honour when wiring - `auth.perUserHomes` becomes a hard prerequisite. Peering setup must refuse **at configuration time** with a clear reason, not accept a transfer and fail at delivery. Note the dogfood instance may not currently have it enabled — verify before #106. - `IMPLEMENTED-PEERING.md` §4.3 needs rewriting: it currently describes the existence check alone. It should describe A+C, the AND, and the single refusal code. - §4.2 needs a companion paragraph for the inbound list, and the JSON example above. - Registry: new `Receivers` field, a `CanReceive` mirroring `CanSend`, both fail-closed on an unknown peer or empty list.

forgejo-actions referenced this issue from a commit

2026-08-05 18:18:45 +00:00

docs(peering): A+C recipient authorization, correct the 10 build-order row, homes default (#123, #102)

Rows
Columns

Peering: how does the receiver decide a recipient "exists"? (blocks the cmd/cairnd wiring) #123

The problem

Options

Recommendation

Also needed once this is decided

A structural point this surfaces

How A and C compose

Consequences to honour when wiring

One thing implementing it surfaced

The question raised

Why we are not doing it now

What we do instead

The condition for changing our mind

Implemented — closing

Registry: the inbound mirror

The A+C composition

The signature change this forced

Known limitation, worth carrying forward

Also settled here