# 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.