authkit-server

authkit-server

The standalone, self-hostable AuthKit server (#142). Runs the engine in-process and exposes, on one listener:

• Browser auth-flow routes under AUTHKIT_API_PREFIX (default /api/v1) — register / login / OIDC / passwordless / 2FA, the same routes an embedding host mounts with authhttp.NewServer.
• JWKS at /.well-known/jwks.json — downstream verifiers fetch signing keys here.
• Management API at POST /v1/call/{Method} — the authenticated control surface for provisioning, management, and token minting. The authkit/remote Go SDK drives it (so a Go app swaps embedded.New ↔ remote.New with one line); non-Go clients call it directly.

Wire contract (management API)

Generic method dispatch — {Method} is any method on authkit.Client:

POST /v1/call/CreateUser
Authorization: Bearer <AUTHKIT_MGMT_TOKEN>
Content-Type: application/json

{"email": "a@b.com", "username": "alice"}

Success → 200 {"result": <value>}. Failure → 4xx/5xx {"error": {"code": "<code>"}}, where code is an AuthKit sentinel's code; the remote SDK re-derives it via authkit.ErrorForCode so errors.Is(err, authkit.ErrX) holds across the network.

The handler and the SDK are generated from the authkit.Client interface (go generate ./..., see internal/genremote), so the two transports cannot drift.

Configuration (env)

Dev-only (honored only when AUTHKIT_ENV is a dev env)

The server folds in the integration-test affordances that used to live in the separate authkit-devserver (#194). They are mounted only in a dev env and are never reachable in production (fail-closed).

GET {prefix}/dev/whoami (reflect the resolved principal) is served whenever the env is dev. In dev with no AUTHKIT_MGMT_TOKEN, the management API is also exposed unauthenticated — POST /v1/call/MintCustomJWT is the production-grade way to mint arbitrary-claim (non-access) tokens.

Env doctrine (#231)

The AuthKit library reads no environment variables — this binary is the one place env is read, once, in loadConfig. It maps AUTHKIT_ENV through the single classifier (embedded.IsDevEnvironment) and, in a dev env, sets Keys.AllowEphemeralDevKeys so go run ./cmd/authkit-server still boots with auto-generated dev signing keys (persisted under .runtime/authkit/). In any non-dev env with no keys configured, the server refuses to boot.

JWT key material maps env → the explicit key-source config (#231): when ACTIVE_KEY_ID / ACTIVE_PRIVATE_KEY_PEM (plus optional PUBLIC_KEYS) are set, the binary builds a jwtkit.NewStaticKeySourceFromPEM(...) and passes it as Keys.Source; otherwise it passes AUTHKIT_KEYS_PATH as Keys.Path and the engine loads <path>/keys.json (hot-reloaded on rotation).

Run

# Apply the schema (one-shot; needs only DB_URL):
DB_URL=postgres://... go run ./cmd/authkit-server migrate

# Then serve:
AUTHKIT_ISSUER=https://auth.example.com \
DB_URL=postgres://... \
AUTHKIT_MGMT_TOKEN=$(openssl rand -hex 32) \
go run ./cmd/authkit-server

A Go client then talks to it backend-agnostically:

var c authkit.Client = remote.New("https://auth.example.com", mgmtToken)
u, _ := c.CreateUser(ctx, "a@b.com", "alice") // identical to the embedded call