# swarm-authelia-bridge

The only thing allowed to write `swarm-authelia`'s users database.

## Why this exists

`swarm-controller`'s `CreateIdentity` job needs to add an agent as an
authelia subject, but `swarm-controller` runs unprivileged and does not own
`users.yml` — a different uid does (`authelia-swarm`, the user
`services.authelia.instances.swarm` runs as). Root/`CAP_CHOWN`/a shared
group were all examined and rejected during this crate's design thread —
see `swarmctl/README.md`'s identical analysis of this same file, written
before this crate existed.

The fix: run **this** process as `User = "authelia-swarm";` instead —
inside the `swarm-authelia` container, alongside authelia itself — so it
simply owns the file it writes. No elevated privilege anywhere.

## Shape

- One endpoint, `POST /requests`, body = `swarm-authelia-bridge-sock`'s
  `BridgeRequest` verbatim — `EnsureAgentIdentity` (idempotently ensure an
  agent exists as an authelia subject), `ListAgentIdentities` (the
  roster: the subjects carrying the agent marker group, names only) and
  `ListOperators` (the operator group's usernames).
- Bearer-authenticated via authelia's own OIDC token introspection (RFC
  7662), against `swarm-controller`'s **existing** machine-client identity
  (already minted for the queue connection) — no new credential. ⚠️ Every
  request admits only the client named by
  `SWARM_AUTHELIA_BRIDGE_CONTROLLER_CLIENT_ID` (`swarm-controller`'s) and
  answers every other active token `403`: authelia issues machine tokens to
  every hive and its agents too.
- No restart of authelia after a write — relies on
  `authentication_backend.file.watch`, confirmed working against the
  pinned 4.39.20 build during this design work.
- Listens on loopback. The authelia vhost proxies `/bridge/` to it with
  the prefix stripped, so `swarm-controller` on any host calls
  `https://<swarm.authelia.domain>/bridge/requests`.

## One store, two writers

This bridge and `swarmctl` both read and write authelia's `users.yml`
directly. That is the whole arrangement — neither keeps a private copy it
considers canonical.

It used to be otherwise, and the seam was real: each side had its own
`users.json` treated as authoritative, rendering the _same_ physical
`users.yml`. A writer whose own JSON was missing could not tell "nothing
here yet" from "someone else's users", so it refused to write at all —
which is exactly what a hive with existing users hit.

What still has to hold, since two processes share the file:

- **One lock around read → write.** Both take an exclusive `flock` on
  `users.yml.lock`, a sibling file in the same directory, before loading and
  hold it until the rename lands, waiting at most 10 seconds. Reading the
  file first is not enough: both writers spend about a second minting a
  password between load and write, and the second rename would drop the
  first writer's user. The lock file is opened `O_NOFOLLOW`, so a symlink
  cannot point either side at another file. `swarmctl` is root: it refuses an
  existing lock file with more than one hard link, and it changes the owner
  of a lock file only when it created that file in the same call, handing it
  to the directory's owner so the bridge can open it. The bridge opens the
  lock read-only, which is all `flock` needs.
- **Unknown keys survive.** Both carry unmodelled top-level and per-user
  fields through a round-trip, or whichever writes second would silently
  delete what the first added.
- **Every user gets an email.** A relying party asking for the claim fails
  rather than degrades, so both write paths fill in a synthetic address
  when none was supplied.

Neither restarts authelia: it watches the file. `swarmctl` _could_ (it is
root); this bridge deliberately cannot, and a reload that depends on which
process wrote is not a reload.