feat: opt-in structured access-audit logging

[alexluft]

What

Adds an opt-in access-audit log: telemetry.audit.enabled, default false. When it is disabled, nothing changes: no layer, no writer thread, and the same log output. The one exception is the ANSI change listed under Also included.

When it is enabled, every HTTP request emits one self-contained JSON line on stdout:

{"audit":"http-access","ts":"2026-08-17T17:16:55Z","user":"user@example.org",
 "subject":"a1b2c3d4-…","source":"192.0.2.10","method":"GET",
 "path":"/aets/PACS/studies/1.2.3.4","aet":"PACS","study":"1.2.3.4",
 "status":200,"duration_ms":4886,"request_id":"0b6f…"}

Motivation. In clinical deployments, "who accessed which study, when" is a legal requirement. Log pipelines (Loki, ELK, …) can select these lines by the audit field and ship them to WORM storage.

Design

• Identity comes from the authenticating reverse proxy's request headers.
  • Which headers is configurable: user-header and subject-header default to X-Forwarded-Email and X-Forwarded-User.
  • The first version of this PR read X-Auth-Request-*. In oauth2-proxy's reverse-proxy mode those are response headers: they are never set on the upstream request and never stripped from client input. So the identity was empty for real traffic and forgeable by any client.
  • oauth2-proxy (checked in v7.15.3) strips client copies of X-Forwarded-{User,Email,Groups,Preferred-Username,Access-Token} before setting them from the verified session.
  • The docs spell out the preconditions as a product-neutral trust model:
    • the proxy strips client copies of the identity headers;
    • DICOM-RST is reachable only through the proxy.
  • An identity header that is repeated, over-long (more than 320 bytes) or malformed counts as absent. It is never truncated.
• Optional on-behalf-of for trusted relays, also off by default.
  • A relay application may call DICOM-RST with its own machine identity on behalf of its users, for example because the proxy's authorization is a single role that also gates STOW-RS.
  • Such a relay can name the end user in X-On-Behalf-Of. It is recorded as on_behalf_of only when telemetry.audit.trusted-relays lists the caller's proxy-asserted identity.
  • Anything else is recorded only as on_behalf_of_rejected: "untrusted-caller" | "invalid". The rejected value itself is never logged.
  • With no relays configured, the header is not read at all.
  • This records the relay's claim; it does not authorize anything.
• request_id comes from X-Request-Id, for correlation with the proxy's access log.
• Fail-open, off the request path.
  • Records go through a bounded channel (1024) to a dedicated writer thread, so a stalled stdout never ties up a runtime worker.
  • When the buffer is full, the record is dropped and a warning with a running count is logged: the first time, then every 100th.
  • Buffered records are flushed on graceful shutdown, with a bounded wait.
  • Copied values are capped by bytes, the truncation marker included: path 8 KiB, user agent 512 B, source 64 B, each DICOM coordinate 256 B.
• What is recorded: method, full path and query (QIDO match parameters are part of "which data"), the aet, study, series and instance path parameters, status and duration.
  • Path parameters are read without ever rejecting a request. The first version answered a non-UTF-8 path segment with its own 400.
  • Status and duration are taken when the response head is produced.
  • The layer sits outside the timeout layer, so a timed-out request is audited with its 408.
• Timestamps use chrono, which is already a transitive dependency via dicom-core. It is declared directly with default-features = false, features = ["clock"].

Also included

• movescu: logs the Study Instance UID on C-MOVE completion, only when auditing is enabled, Debug-escaped.
• Regular log, only while auditing is enabled: line breaks inside a log event are escaped (\n, \r).
  • Why: audit records share stdout with the text log, and tracing-subscriber escapes ANSI sequences but not line breaks. A log message that carries request data could otherwise start a line of its own that looks like an audit record. One example is the S3 prefix log, which is built from percent-decoded path segments.
  • The formatter hands each event to the writer with one write_all, and a test pins that.
  • With auditing disabled, the default writer is used and the output is unchanged.
  • Residual: panic messages go to stderr unescaped. A collector that merges stderr into the same stream as stdout should keep the stream distinction.
• ANSI colours: with_ansi(is_terminal() && NO_COLOR unset) on the fmt layer. Container logs lose the escape codes, TTY output keeps colours, and NO_COLOR is still honoured. This is the one default-on change. It is listed under Changed in the CHANGELOG. Please say if you would rather have it as a separate PR.
• Docs: docs/topics/configuration.md documents every key, the trust model and the record's limits. CHANGELOG entries are under Unreleased.

Relation to native OIDC

This agrees with @feliwir's point above: native OIDC, with the subject taken from a verified JWT, is the better end state. Until DICOM-RST has it, an authenticating proxy is the only way to run it in an SSO environment, and this PR makes the audit correct and hard to forge in that setup.

When native OIDC lands, the identity could come from the verified token instead of headers. Relays could then forward their users' own tokens, which would replace the on-behalf-of mechanism.

Open question for maintainers

source is still the leftmost X-Forwarded-For entry, as in the first version. It is documented as client-asserted, because proxies usually append to a client's XFF. Recording the peer address, or a configurable number of trusted hops, would be stricter. That is left to you.

Testing

• cargo check, cargo test and cargo test --all-features pass: 53 unit, 2 end-to-end audit tests through the real binary (enabled and disabled), and 4 existing integration tests.
• cargo fmt --check passes. cargo clippy --all-targets -- -D warnings is clean. CI's --all-features clippy shows only the 11 warnings already on main.
• MSRV: cargo +1.91 check and test pass.
• Each commit builds and passes the tests on its own.
• Every new test was checked by deliberately breaking the code it covers.

Please squash-merge. The branch carries 23 commits of review iterations.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q9PMSu4fFsV5dSNojTTQaG
https://claude.ai/code/session_01HcyZjaNmg7eB5uC1jeXV3k

[feliwir]

I think it would make sense to integrate OIDC authorization first. So we could track the subject from the JWT.

Reading the user & mail from some HTTP header fields is some special case when deployed behind a reverse proxy that is not really the default setup.

[MaxOremek]

We have in Bonn developed a RUST based LDAP Audit Microservices with JWT with Access Logging to a PostGres. Would you be interested in recycling this?

[alexluft]

I'd absolutely upvote a native oidc support 👍
Until then, using oauth2 proxy is the only way to get dicom-rst integrated into sso environments.
Running web services behind reverse proxies with- or without an authentication layer is pretty common and best practice. Passing sub and more information from the reverse proxy for audit log (which is required legally) is a low hanging fruit.

[alexluft]

@feliwir this is ready for review. It adds an opt-in access-audit log: it is off by default, and nothing changes unless telemetry.audit.enabled is set. Identity comes from the authenticating proxy's forwarded request headers, and on-behalf-of is recorded only for explicitly configured trusted relays; everything is documented in docs/topics/configuration.md and the CHANGELOG. Given the review iterations on the branch, I'd suggest a squash-merge. Thanks!

[nickamzol]

The motivation states that access auditing is a legal requirement, but the design is fail-open: records are dropped under pressure and lost on write errors. Is that intended?

I'm also not comfortable with the on-behalf-of / trusted-relay mechanism. It adds a fair amount of security-sensitive configuration and logic to work around missing OIDC support, and it records a claim that DICOM-RST can't verify. I'd rather drop it from this PR and implement native OIDC instead.