Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/api.md

@@ -0,0 +1,179 @@
+# API
+
+Generated from the package comment and every exported declaration. Do not edit.
+Regenerate with `UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1`.
+
+## Package usertoken
+
+Package usertoken mints and checks the short-lived RS256 user token an ExApp sends to Microservices.
+
+An ExApp calls [NewSignerFromEnv](#newsignerfromenv) and [Signer.Mint](#signermint) after AppAPI has named the user. A Microservice calls [FromEnv](#fromenv) and [Auth.Middleware](#authmiddleware) or [Auth.UnaryServerInterceptor](#authunaryserverinterceptor). One process trusts either a static public key or an OIDC issuer, not both.
+
+The procedure, claims, and environment variables are in knowledge/platforms/nextcloud/exapps/authentication.md.
+
+## Variables
+
+### ErrUnauthorized
+
+```go
+var ErrUnauthorized = errors.New("unauthorized")
+```
+
+ErrUnauthorized is wrapped by every failed token check. Startup and configuration failures do not wrap it.
+
+## Functions
+
+### BearerFromContext
+
+```go
+func BearerFromContext(ctx context.Context) (string, bool)
+```
+
+BearerFromContext returns the raw JWT [Auth.Middleware](#authmiddleware) stored, without the "Bearer " prefix. Outbound calls send "Bearer " plus this string.
+
+## Types
+
+### Auth
+
+```go
+type Auth struct {
+	// contains filtered or unexported fields
+}
+```
+
+Auth verifies bearers for one Microservice process.
+
+#### FromEnv
+
+```go
+func FromEnv(ctx context.Context) (*Auth, error)
+```
+
+FromEnv reads the process environment and builds an Auth. Set USER\_TOKEN\_PUBLIC\_KEY\_FILE or OIDC\_ISSUER, not both and not neither. Static mode also reads USER\_TOKEN\_ISSUER and USER\_TOKEN\_AUDIENCE. OIDC mode reads OIDC\_AUDIENCE and optional OIDC\_GROUPS\_CLAIM. Optional USER\_TOKEN\_SKEW is a time.Duration; empty uses 1 minute. It returns an error when the mode is ambiguous, the key file is unreadable, USER\_TOKEN\_SKEW cannot be parsed, or OIDC discovery fails. ctx is used for OIDC discovery.
+
+#### New
+
+```go
+func New(ctx context.Context, cfg Config) (*Auth, error)
+```
+
+New builds an Auth from explicit configuration. ctx is used for OIDC discovery.
+
+#### Auth.Middleware
+
+```go
+func (a *Auth) Middleware() func(http.Handler) http.Handler
+```
+
+Middleware requires a bearer on every path except /health. Success stores the Caller and the raw JWT on the request context.
+
+#### Auth.UnaryServerInterceptor
+
+```go
+func (a *Auth) UnaryServerInterceptor() grpc.UnaryServerInterceptor
+```
+
+UnaryServerInterceptor requires a bearer on every RPC. Success stores the Caller and the raw JWT on the handler context, same as [Auth.Middleware](#authmiddleware). Native clients send metadata key "authorization". The HTTP gateway's forwarded header is "grpcgateway-authorization".
+
+#### Auth.Verify
+
+```go
+func (a *Auth) Verify(ctx context.Context, raw string) (Caller, error)
+```
+
+Verify checks a raw JWT. raw has no "Bearer " prefix. A failed check wraps ErrUnauthorized. Startup and configuration failures do not.
+
+### Caller
+
+```go
+type Caller struct {
+	Subject		string
+	Username	string
+	Groups		[]string
+}
+```
+
+Caller is the user a verified token names. Groups is nil when the token omitted the claim, and non-nil (possibly empty) when the claim was present.
+
+#### CallerFromContext
+
+```go
+func CallerFromContext(ctx context.Context) (Caller, bool)
+```
+
+CallerFromContext returns the user [Auth.Middleware](#authmiddleware) stored.
+
+### Config
+
+```go
+type Config struct {
+	PublicKey	*rsa.PublicKey
+	Issuer		string
+	Audience	string
+	OIDCIssuer	string
+	OIDCAudience	string
+	GroupsClaim	string
+	Skew		time.Duration
+}
+```
+
+Config selects one verify mode. Set PublicKey for static RS256, or OIDCIssuer for discovery. Not both. Skew of zero uses 1 minute. GroupsClaim empty uses "groups" (OIDC only). Audience empty is allowed only for OIDC, where it skips the audience check.
+
+### MintInput
+
+```go
+type MintInput struct {
+	Subject	string
+	Groups	*[]string
+}
+```
+
+MintInput is one user token. Groups nil omits the claim. A non-nil pointer includes it, including an empty list.
+
+### SignConfig
+
+```go
+type SignConfig struct {
+	PrivateKey	*rsa.PrivateKey
+	Issuer		string
+	Audience	string
+	TTL		time.Duration
+}
+```
+
+SignConfig is the ExApp mint configuration. TTL of zero uses 5 minutes.
+
+### Signer
+
+```go
+type Signer struct {
+	// contains filtered or unexported fields
+}
+```
+
+Signer mints RS256 user tokens. Only the ExApp should hold one.
+
+#### NewSigner
+
+```go
+func NewSigner(cfg SignConfig) (*Signer, error)
+```
+
+NewSigner checks the key, issuer, and audience. It returns an error when PrivateKey is nil or issuer or audience is empty. A TTL of zero or less uses 5 minutes.
+
+#### NewSignerFromEnv
+
+```go
+func NewSignerFromEnv() (*Signer, error)
+```
+
+NewSignerFromEnv reads USER\_TOKEN\_PRIVATE\_KEY\_FILE, USER\_TOKEN\_ISSUER, USER\_TOKEN\_AUDIENCE, and optional USER\_TOKEN\_TTL. It returns an error when the private-key path is empty, the PEM is not an RSA key, USER\_TOKEN\_TTL is set and is not a time.Duration, or issuer or audience is empty. An empty USER\_TOKEN\_TTL uses 5 minutes.
+
+#### Signer.Mint
+
+```go
+func (s *Signer) Mint(now time.Time, in MintInput) (string, error)
+```
+
+Mint signs one RS256 token at now. Subject becomes both sub and preferred\_username. It returns an error when Subject is empty or the key cannot sign.
+