vault-plugin-secrets-apptoken/README.md

# vault-plugin-secrets-apptoken

A HashiCorp Vault / OpenBao secrets engine that issues **short-lived, signed
JWT "app tokens"** for self-made services (keaapi, encapi, artifactapi,
tomswallapi, bootapi, ...). It replaces per-app static bearer `Secret`s with one
mechanism: define a per-app role, read `creds/<app>` to mint a token, and let
the app validate it **offline** against the engine's public JWKS — no Vault
round-trip per request.

Any principal allowed to read `creds/<role>` (for example the agents approle)
can mint a token for that app. Signing keys are generated inside Vault's barrier
(seal-wrapped) and never leave it; only the public JWKS is exposed.

```
issuer (this engine)                     consumer app (keaapi)
  ├── creds/keaapi ──▶ signed JWT ──────▶ Authorization: Bearer <jwt>
  │   (aud=keaapi, exp, sub=caller)          │
  └── .well-known/jwks.json ◀── fetch ───────┘ verify signature + aud, offline
```

## Signing

Tokens are signed with **EdDSA (Ed25519)** by default — compact signatures,
fast verification, first-class support in Go's stdlib and `go-jose`, which the
whole ecosystem (and Vault itself) uses. `RS256` is available via
`config algorithm=RS256` for consumers that need RSA interop. The `kid` header
is the RFC 7638 JWK thumbprint of the signing key, so it is stable and matches
the JWKS entry.

## Paths

| Path | Op | Purpose |
|------|----|---------|
| `config` | R/W | `issuer` (external mount URL, becomes `iss` + base of `jwks_uri`), `algorithm` (`EdDSA`\|`RS256`), `retained_keys` |
| `config/keys` | R | current signing `kid` + all retained kids (keys are generated lazily on first use) |
| `config/keys/rotate` | W | generate a new current signing key; up to `retained_keys` previous keys stay in the JWKS |
| `roles/<name>` | R/W/D, list `roles/` | per-app role: `audience` (defaults to role name), `ttl`, `max_ttl`, `allowed_subjects`, `claims` |
| `creds/<name>` | R | mint a signed JWT for the role |
| `.well-known/jwks.json` | R, **unauthenticated** | public JSON Web Key Set for offline validation |
| `.well-known/openid-configuration` | R, **unauthenticated** | OIDC issuer metadata (`issuer`, `jwks_uri`) |

Token claims: `iss` (issuer), `aud` (role audience), `sub` (requesting Vault
entity id or token display name), `exp`/`nbf`/`iat`, `jti`, plus any role
`claims`. Registered claims cannot be overridden by a role.

`allowed_subjects`, when set, restricts which callers (matched on Vault entity
id or token display name) may mint from a role. `retained_keys` keeps N previous
signing keys published after a rotation so tokens signed just before it keep
validating during the grace window.

## Usage

```sh
# register + enable (the plugin_directory must contain the binary)
sha=$(sha256sum /opt/vault-plugins/vault-plugin-secrets-apptoken | cut -d' ' -f1)
vault plugin register -sha256=$sha secret vault-plugin-secrets-apptoken
vault secrets enable -path=apptoken vault-plugin-secrets-apptoken

# configure the issuer to this mount's external URL
vault write apptoken/config issuer="https://vault.k8s.syd1.au.unkin.net/v1/apptoken"

# define a per-app role and mint a token
vault write apptoken/roles/keaapi ttl=15m max_ttl=1h claims="scope=leases"
vault read  apptoken/creds/keaapi                # -> token, aud=keaapi, exp, ...

# public validation material (no token required)
curl -s "$VAULT_ADDR/v1/apptoken/.well-known/jwks.json"
curl -s "$VAULT_ADDR/v1/apptoken/.well-known/openid-configuration"

# rotate signing keys; tokens signed before rotation still validate during grace
vault write -f apptoken/config/keys/rotate
```

## Validating tokens in a service (Go)

Consumers only need the JWKS URL and their expected audience. Fetch and cache
the JWKS (honouring cache headers / periodic refresh), then verify offline:

```go
// keaapi middleware sketch — do NOT hit Vault per request.
import (
    "github.com/coreos/go-oidc/v3/oidc" // or MicahParks/keyfunc + golang-jwt
)

// jwks_uri = "https://vault.../v1/apptoken/.well-known/jwks.json"
keySet := oidc.NewRemoteKeySet(ctx, jwksURL)
verifier := func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        raw := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
        payload, err := keySet.VerifySignature(r.Context(), raw)
        // then decode payload, check: iss == expected, aud contains "keaapi",
        // exp in the future. Reject otherwise.
        ...
    })
}
```

`kea-operator`'s `internal/keaapi` is the first intended consumer — see
Follow-ups.

## Why not the built-in OIDC identity-token provider?

Vault ships an identity-token provider (`identity/oidc`) that also issues signed
JWTs with a JWKS. This engine is deliberately parallel to it because:

- **Roles are issuable by other principals.** `creds/<role>` is a normal secret
  path, so the agents approle (or CI) can mint an app's token without being the
  token's own identity. The identity provider ties issuance to the caller's
  entity and its role/client model is heavier.
- **Simpler audience model.** One role = one app = one audience, no separate
  OIDC client/assignment objects to wire up.
- **OpenBao parity + house pattern.** Same plugin/Makefile/`.woodpecker`/RPM
  shape as the other `vault-plugin-secrets-*` engines, and the identical binary
  runs on OpenBao.

If you only need tokens whose subject is always the calling entity, the built-in
provider may suffice; for per-app service tokens minted by shared automation,
this engine is the better fit.

## Build

```sh
make build      # -> dist/vault-plugin-secrets-apptoken
make test lint  # go test -race / go vet
make rpm        # vault + openbao RPM flavours
```

CI (Woodpecker) runs pre-commit/build/lint/test on PRs and, on a `v*` tag,
builds the vault + openbao RPM flavours and uploads them to the artifactapi
`rpm-internal` repo. Cut a release with `make patch|minor|major` (tags + pushes).