logwisp/doc/scram-auth-plan.md

# Password Authentication (Argon2id-SCRAM)

**Status:** planned. Ships in two batches:

1. **Done:** `lixenwraith/auth` gained SCRAM channel binding, and the mTLS layer
   was hardened (see [mTLS Hardening](#mtls-hardening)).
2. **Next:** the SCRAM integration described here, pinned to the tagged `auth`
   release that carries channel binding.

**Scope:** optional username/password authentication on every network plugin,
next to the existing certificate method, without weakening what mTLS gives.

## Goals

- Password authentication for chain links (`tcp_chain`, `http_chain`: sources
  verify, sinks present) and for viewers of the `tcp` and `http` sinks.
- No password or password-equivalent on the wire, no KDF work on listeners, and
  no credential relay through a TLS-terminating MITM.
- Default stays `auth.type = "none"`; existing configurations are unaffected.
- Config in TOML, credential management and viewer clients in a `logwisp auth`
  CLI.

## Non-Goals

- Standard SASL SCRAM-SHA-256 interoperability. The `auth` exchange is
  logwisp-to-logwisp (or logwisp CLI) only.
- Browser `EventSource` viewers under SCRAM: they cannot set `Authorization` or
  run Argon2. mTLS remains the browser path.
- Multiple backends behind a non-sticky L7 balancer: handshake state and the
  token key live in one process.

## Mechanism

`lixenwraith/auth` Argon2id-SCRAM. The listener stores a verifier per user:
`StoredKey = SHA-256(HMAC(K, "Client Key"))`, `ServerKey = HMAC(K, "Server Key")`,
`K = Argon2id(password, salt)`. The Argon2id digest itself is never stored: it is
the salted password, from which both keys derive. Verifying a proof is HMAC only;
Argon2 runs on the dialer or CLI (64 MiB, t=3, the `auth` defaults).

**Channel binding.** Both peers pass `auth.WithChannelBinding(SHA-256(server leaf
DER))` at the proof step. The server hashes its configured certificate; the
client hashes the certificate it saw. A relay presenting any other certificate,
even one the CA trusts, makes the server reject the proof, so it never obtains a
link or a token. A mismatch is indistinguishable from a wrong password by design;
the client also sends its hash as a diagnostic field so the listener can log
"TLS interception or terminating proxy" and count it. TLS must terminate at
logwisp.

**HTTP pinning.** HTTP auth takes two requests and every later request may use a
new pooled connection, so binding the exchange is not enough. After step 1 the
dialer pins the bound hash on its `VerifyConnection`: step 2 and every ingest
request must present the same leaf. A mismatch clears token and pin and
re-authenticates, which also covers certificate rotation. A token handed to curl
by the CLI is unpinned.

## Configuration

```toml
# listener (tcp_chain/http_chain source, tcp/http sink)
[pipelines.plugin_sources.config.auth]
type              = "scram"
credentials_file  = "/etc/logwisp/users.toml"
token_lifetime_ms = 900000          # http sink and http_chain source only
node_binding      = "force"         # chain sources; binds to the username

# dialer (tcp_chain/http_chain sink)
[pipelines.plugin_sinks.config.auth]
type          = "scram"
username      = "edge-01"
password_file = "/etc/logwisp/edge-01.pass"
```

Validation at construction:

- `scram` requires TLS; a dialer also forbids `insecure_skip_verify`.
- Listeners require `credentials_file` and reject `allow`/`allow_patterns`: the
  credentials file is the allow list. Use one file per listener when listeners
  admit different users.
- Dialers require `username` + `password_file`, and reject `credentials_file`,
  `allow*` and `identity` (server pinning stays an mTLS feature).
- `identity` on a listener requires `tls.client_auth` and **binds the certificate
  to the user**: the certificate's identity field must equal the SCRAM username,
  so a peer needs its own certificate and its own password (PostgreSQL's
  `clientcert=verify-full`). Without it the factors are independent: any
  CA-issued certificate plus any valid password (`clientcert=verify-ca`).
- `token_lifetime_ms` only on HTTP listeners; default 15 minutes.
- `/auth` is reserved; no configured path may equal it.

**Credentials file** (TOML, written by the CLI, mode 0600):

```toml
decoy_key = "<base64, 32 random bytes>"
[[users]]
username = "edge-01"
salt = "<base64>"
argon_time = 3
argon_memory = 65536
argon_threads = 4
stored_key = "<base64>"
server_key = "<base64>"
```

`decoy_key` keeps unknown-user challenges stable across restarts and edits, so
probing usernames reveals nothing. It is created by the first `add-user` and
preserved by every rewrite. An empty user set, a duplicate user, a missing
`decoy_key` or mixed KDF profiles are configuration errors. The file is read at
construction; the SCRAM server starts in the plugin's `Start` and stops in `Stop`,
so a rejected reload leaks nothing.

## Wire Protocol

`chain.Hello` gains `scram` (raw JSON, decoded by `authz`); the protocol version
stays 1 because the field is additive. Every message after the hello is one
`authStep`: `error`, `challenge`, `proof` (+ `binding`), `final` (+ `token`,
`expires_in` on HTTP). Pre-auth lines are capped at 4 KiB.

**TCP** (`tcp_chain`, `tcp` sink): hello carrying the client-first message,
challenge, proof, final — all under one deadline (`hello_timeout_ms` on the
`tcp_chain` source, 10 s on the `tcp` sink and every dialer, with the dialer's
context able to cut it short). The final is written only after every admission
check (certificate binding, node binding); the stream then continues on the same
buffered reader. A source without SCRAM answers a hello carrying credentials with
`error: authentication not enabled`; only an old binary stays silent, and the
dialer's deadline covers that.

**HTTP** (`http_chain` source, `http` sink): `POST /auth`, outside the auth
middleware, with its own 10 s read/write deadline and a 4 KiB body limit.

| Step | Request body | Success | Failure |
|------|--------------|---------|---------|
| 1 | hello | `200` challenge | `429` throttled, `503` handshake table full, `400` malformed |
| 2 | proof | `200` final, token, expires_in | `401 {"error":"authentication failed"}` |

Protected endpoints take `Authorization: Bearer <token>`: missing or invalid is
`401` with `WWW-Authenticate: Bearer realm="logwisp"`, a certificate-binding miss
is `403`. Tokens are HS256 JWTs from `auth.NewJWT` with a random per-instance key,
so every reload revokes them. An SSE stream is checked at connect and outlives its
token; a reload ends it.

**Dialer outcomes** (`http_chain` sink): every `/auth` failure is transient (the
batch is held under backoff); `404`/`405` from `/auth` logs "no auth endpoint:
older logwisp or auth.type is not scram"; an ingest `401` clears the token and is
retried; `403` drops the batch; a pin mismatch clears token and pin. Rejections
are logged at WARN once per change of state and counted in `auth_failures` /
`last_auth_error`.

## Throttling

Per remote IP (the socket address, never a forwarded header), on handshake
starts: a token bucket (burst 10, 1/s) refunded on success, and at most 4
unfinished exchanges. The table is bounded and fails closed when full. Abandoned
TCP exchanges release their slot in the `auth` handshake table immediately.
Counters: `auth_allowed` and `auth_rejected` once per exchange outcome;
`auth_throttled`, `auth_busy` and `auth_binding_mismatch` separately.

## The `authz` Seam

Listeners never call `Authorize` directly any more; one entry point per transport
decides, and `Authorize` itself refuses under `scram` so a missed call site fails
closed.

- `Admit(conn, cs, wantHello, timeout)` returns an admission (identity, hello,
  reader) whose `Accept` or `Reject` writes the final message.
- `AuthorizeRequest(r)` covers mTLS certificates and bearer tokens;
  `ServeAuth(w, r)` serves `/auth`.
- Dialers: `Greet(ctx, conn, node)` writes the hello (plain or SCRAM);
  `Authenticate`, `SetAuthorization`, `ClearToken` and `VerifyConnection` serve
  HTTP.
- `Start`/`Close` bracket the SCRAM server and are nil-safe like everything else.

## CLI

```
logwisp auth add-user    -credentials F -user U [-password-file P] [-generate]
logwisp auth remove-user -credentials F -user U
logwisp auth token  -url https://host:port -user U -password-file P [TLS flags]
logwisp auth stream -addr host:port        -user U -password-file P [TLS flags]
```

- `add-user` takes the password from `-password-file` when it exists; a new user
  without one gets a generated 130-bit password, written to that file (0600) or
  printed once. Rotating an existing user needs the file or `-generate`, so a
  mistyped path cannot replace a password. The file's KDF profile and decoy key
  are reused, the result is validated with the daemon's own loader, and the
  rewrite (temp file in the same directory, rename) keeps the existing mode and
  owner.
- `remove-user` refuses to remove the last user.
- Both print that changes apply on `SIGHUP`: `auto_reload` does not watch the
  credentials file.
- `token` prints a bearer token for curl (`-H @<(...)` keeps it out of argv);
  `stream` authenticates to a `tcp` sink and copies the stream to stdout.
- TLS flags: `-ca-file`, `-server-name`, `-cert-file`, `-key-file`. There is no
  insecure flag.

## Rollout and Rotation

- Turning SCRAM on is per listener and cuts off unconfigured dialers. To migrate
  without a gap, upgrade binaries, add a second SCRAM listener, move dialers,
  then remove the old listener.
- Password rotation: `add-user -generate`, `SIGHUP` the listener, deploy the new
  password file, `SIGHUP` the dialer. The dialer retries under backoff in
  between.
- Revocation: `remove-user`, `SIGHUP`. All tokens die with the reload.

## Verification

Go tests, one per rule: binding (match, mismatch, one-sided, length) in `auth`;
in `authz` the validation table, credential loading, decoy stability across
edits, TCP exchange over `net.Pipe` (success, wrong password equals unknown
user, binding mismatch, missing hello, silent peer within the deadline,
abandoned exchange frees its slot, final and first entry in one write, assert
mismatch gets an error rather than a final), HTTP exchange on a TLS test server
(token accepted, garbage and foreign tokens `401`, forged final yields no token,
a different certificate after step 1 refused before the body is sent), the
limiter bound; `http_chain` sink re-authentication and outcome table; CLI
add/remove/rotate, mode preservation, last-user refusal, password trimming.

`test/scram-chain-test.sh --auto` (ports 15821-15825): a relay with SCRAM on all
four listener types plus one `client_auth` + SCRAM port; authorized edges over
both chain transports; node labels forced to usernames; wrong password, unknown
user and no-auth edges deliver nothing; a `tcp` sink viewer through `logwisp auth
stream` held past the exchange deadline; a raw TLS client without a hello gets
nothing; the `http` sink through `logwisp auth token` and curl; missing and bad
tokens get `401`; `remove-user` + `SIGHUP` revokes token and login; throttling
last. The existing scripts keep passing.

## mTLS Hardening

Shipped with this plan, independent of SCRAM:

- The `http_chain` sink no longer follows redirects. Go's client resends the
  body on a 307/308, including from `https` to plaintext `http`.
- Its response drain is bounded (64 KiB).
- The `tcp` sink tracks connections from accept, so `Stop` and reloads no longer
  wait out the 10 s handshake timeout of a silent peer.
- Unknown keys in any plugin's config, at any depth, fail construction: a typo
  such as `[...tls] enabeld = true` used to switch protection off silently.
- Startup and every reload warn about certificates that expired, are not yet
  valid, or expire within 30 days; about `insecure_skip_verify`; about
  `allow_patterns` that are not anchored at both ends of every alternative; and,
  once per path, about key files every local user can read.
- An `http` sink with an auth policy no longer sends
  `Access-Control-Allow-Origin: *`.