com.worxbend.codeberg4s.auth

A Codeberg / Forgejo personal access token.

The only way to observe the material is ApiToken.reveal, whose single legitimate caller is the transport adapter building the Authorization: token header. Every other rendering path — toString, string interpolation, the generated toString of any case class or enum case holding one, and therefore CodebergError.describe — sees the constant mask "***".

'''Why this is a final class and not an opaque type.''' An opaque type ApiToken = String has Any as its visible upper bound, so outside its defining scope token.toString and s"$token" both dispatch to String's toString and print the secret. That defeats the whole point of the wrapper, so the redaction guarantee is bought with an ordinary final class that overrides toString. ApiTokenSuite pins this behaviour down.

Instances compare structurally on the underlying material, so configuration values remain comparable in tests. The comparison is not constant-time; this type guards against accidental disclosure in logs, not against a timing oracle, and a client library holds its own token rather than checking someone else's.

How this client authenticates against a Forgejo instance.

Forgejo advertises several security definitions; this library supports exactly the three below and treats the rest (SudoParam, TOTPHeader, query-parameter tokens) as unsupported, because they either weaken the redaction guarantee or belong to admin flows that are out of scope.

Auth is applied once, in the transport adapter, as a request transformation. Nothing above the transport knows how credentials are carried, and no credential ever reaches a com.worxbend.codeberg4s.CallContext.

Every case renders its credentials as "***", so toString on an Auth — or on a com.worxbend.codeberg4s.CodebergConfig holding one — is safe to log.

The password half of HTTP basic credentials.

Same redaction discipline as ApiToken, and a final class for the same reason: an opaque alias over String cannot stop toString or string interpolation from printing the secret. The only way to observe the material is Password.reveal, whose single legitimate caller is the transport adapter encoding the Authorization: Basic header.

Basic auth is supported because some self-hosted Forgejo deployments still require it; prefer ApiToken wherever the instance allows it.