From d692e8d690b4acd1877aac7c697b5661b53b6b76 Mon Sep 17 00:00:00 2001 From: Jean Chevronnet Date: Tue, 14 Jul 2026 16:14:46 +0000 Subject: [PATCH] Add Directory API page --- Directory-API.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 Directory-API.md diff --git a/Directory-API.md b/Directory-API.md new file mode 100644 index 0000000..7b04f58 --- /dev/null +++ b/Directory-API.md @@ -0,0 +1,20 @@ +# Directory API (gRPC) + +`src/grpc.rs` exposes the account and channel directory over gRPC (see `proto/echo.proto`) so a website can mirror it without touching IRC. Omit `[grpc]` in the config to run without it. + +## Directory (read) + +- `Snapshot` returns the current accounts and channels for the initial load. +- `Subscribe` streams every change from that point on. + +It subscribes to the same committed-entry channel gossip does, so a change reaches a subscriber in the same push, with no polling. It deliberately excludes anything credential-shaped (password hashes, SCRAM verifiers, cert fingerprints) and the finer channel-ops events. Identity and metadata only. + +## Accounts (write) + +The same port serves the write side, for a trusted caller such as a website's own backend that has already done its own login or session check: `Register`, `Authenticate`, `SetPassword`, `SetEmail`, `Confirm`, `Drop`, `ForceLogout`, `GroupNick`, `UngroupNick`. This manages accounts the way an IRC user does through NickServ, minus the command syntax. + +The bearer token is the authorization. Unlike the NickServ commands these mirror, most calls do not re-check the account's own password (an admin-level override). `Register` and `Authenticate` are the exceptions, since the password is the input there. A write committed this way replicates to every other node exactly like an IRC-originated one. + +## Auth and transport + +Bearer-token authenticated, optional server TLS. Pair it with `[auth] external = true` (see [Configuration](Configuration)) to let the website own account identity while Echo owns channels and metadata.