# auth

Shared Go library with authentication primitives for all Shiny backend services.

## Shared Documentation

@../docs/claude/architecture.md
@../docs/claude/go-services.md
@../docs/claude/conventions.md

## Library Information

### Purpose

Single home for the `user`-header auth and secret-startup-guard code that was
previously byte-identical-copied into every backend (the `auth` package and
`cmd/service/secrets_guard.go`). Enforces ADR-0005 (HMAC-signed `user` header,
keyless fail-open only in acctest) and ADR-0006 (fail closed when required
secrets are missing in `staging`/`production`).

### Usage

```go
import "gitea.unbound.se/shiny/auth"

// Fail closed on missing deployed secrets before serving (ADR-0005/0006).
if missing := auth.MissingDeployedSecrets(environment, map[string]string{
    "USER_SIGNING_KEY":  cfg.UserSigningKey,
    "INTERNAL_API_KEY":  cfg.InternalAPIKey,
}); len(missing) > 0 {
    log.Fatalf("refusing to start: missing secrets in %s: %v", environment, missing)
}

// Verify the gateway's signed user header and inject *User into the context.
handler = auth.UserMiddleware([]byte(cfg.UserSigningKey))(handler)

// Read the authenticated user downstream.
user := auth.FromContext(ctx)
if user.HasRole("admin") { /* ... */ }
```

### Exported API

- `UserMiddleware(signingKey []byte)` — HTTP middleware verifying the
  HMAC-signed `user` header; injects `*User` into the request context.
- `FromContext(ctx) *User`, `User.HasRole(...) bool`, `ContextKey`/`UserKey`.
- `MissingDeployedSecrets(environment string, secrets map[string]string) []string`
  — returns the sorted names of secrets that are empty in `staging`/`production`
  (nil for any other environment, e.g. `development`/acctest).

### Conventions

Standard Shiny library scaffolding: `gofumpt`/`goimports -local`, golangci-lint,
gitleaks and conventional-commit checks via pre-commit; coverage-regression gate
in CI (`.testcoverage.yml`); releases auto-tagged from conventional commits by
the shared Release workflow. Bump the consuming services' `go.mod` after a
release. A breaking change to the signed-header or secret-guard contract is a
cross-service change — see ADR-0005/0006 before changing it.