Security hardening
TIM ships secure defaults, but its threat model changes with the deployment topology. This chapter walks through every knob that affects the security posture: what the default is, what the safer production setting looks like, and what breaks if you get it wrong.
Admin token
Config: security.admin_token_env (default
"TIM_ADMIN_TOKEN"), security.require_admin_token (default
true).
Gated endpoints:
POST /jwt/custom/generatePOST /jwt/custom/revokePOST /jwt/custom/revoke/bulkPOST /jwt/custom/extendPOST /jwt/custom-jwt-blacklist(legacy)POST /jwt/blacklist(legacy)
Transport: callers present the token via one of:
X-TIM-Admin-Token: <secret>(preferred)Authorization: Bearer <secret>(accepted for symmetry with modern APIs; use only when the caller is not simultaneously carrying a user JWT)
Comparison is constant-time (subtle::ConstantTimeEq).
Provisioning:
# 32 random bytes, hex-encoded — 64 chars. Store in your secrets
# manager alongside the DB password.
openssl rand -hex 32
Mount into the container's environment via docker-compose / k8s
secret / whatever your platform does. TIM refuses to boot if
require_admin_token: true (the default) and the referenced env
var is unset or empty.
Ungated mode (require_admin_token: false + empty
admin_token_env): available only for tests and single-machine dev.
Startup logs a WARN. Never deploy this way to a network reachable by
untrusted callers.
Endpoint auth invariants
Full audit performed 2026-09-18 (h2ck.me v1 NEXT-TASKS T-19). Every
route in src/router/mod.rs::build_router was classified. Regression
pin: tests/security_admin_surface_audit.rs.
Public-by-design (no credentials, cannot be gated without breaking the protocol or the operator's health-check story):
| Route | Why public |
|---|---|
GET /health, GET /healthz | LB / K8s liveness probe. |
GET /auth/health | OAuth registry status probe. |
GET /jwt/keys/public | RFC 7517 JWKS — verifiers pull unauth. |
GET /jwt/verification-key | Legacy JVM 1.x PEM mirror of JWKS. |
GET /introspect/types | RFC 7662-shaped discovery of supported token types. |
GET /auth/providers, GET /auth/providers/:id | Public provider catalogue (client picks a provider before it has a session). |
GET /auth/login/:id | Starts OAuth flow — must be reachable pre-session. |
GET /auth/callback/:id | Called by the IdP after user consent — must be reachable pre-session. |
Optionally gated (config flag decides): POST /introspect +
/jwt/custom/validate* + the three JVM cookie validation compat
endpoints — see Validation-endpoint DoS gate
below.
Always gated (admin, bearer, session, or cookie extractor):
every write path (generate, revoke*, extend*, blacklist*) and
every session-scoped read (/auth/session/validate, /auth/profile,
/auth/logout, /jwt/custom/list/me, all JVM cookie compat handlers).
The full auth matrix lives in API reference → Auth legend; this section only summarises the security invariant.
Verdict on Ruuter-style /_/* admin surface: not adopted. Ruuter's
/_/* env-gated prefix solves a different problem (per-environment
feature-flag surfaces for its runtime config UI). TIM's admin surface
is already comprehensive: every mutating endpoint runs behind
AdminAuth, every session read behind SessionAuth, no admin-shaped
functionality lives on a public route. Adding /_/* would give
attackers a distinct env-shape to probe without security benefit.
HTTP response headers
Config: security.content_security_policy,
security.strict_transport_security, security.referrer_policy,
security.x_frame_options, security.x_content_type_options.
Each is a string that becomes a response header on every route (including 404s). Empty string skips a given header.
Defaults are conservative — the shipped tim.yaml sets:
content_security_policy: "default-src 'none'; frame-ancestors 'none'"
strict_transport_security: "max-age=63072000; includeSubDomains"
referrer_policy: "no-referrer"
x_frame_options: "DENY"
x_content_type_options: "nosniff"
These are TIM's own responses. If your reverse proxy already sets
these headers, either leave TIM's alone (harmless — the proxy
usually preserves) or set the fields to "" to opt out.
CORS
Config: security.cors_allowed_origins (default []).
Behaviour:
[](default) — no CORS layer, noAccess-Control-*headers emitted. Same-origin callers work; cross-origin browser callers get blocked at the browser.["*"]— wildcardAccess-Control-Allow-Origin: *; browser callers from anywhere accepted; credentials NOT allowed (browser-side spec restriction with wildcard).- Explicit list — reflected origin match plus
Access-Control-Allow-Credentials: truefor cookie-carrying browsers. Recommended in production.
Example:
security:
cors_allowed_origins:
- "https://app.example.com"
- "https://admin.example.com"
Session encryption at rest
Config: oauth2.session_store: "postgres" +
oauth2.session_encryption_key_env (default
"TIM_SESSION_ENCRYPTION_KEY").
When postgres is selected, the profile map in auth.session is
sealed with chacha20poly1305 (12-byte random nonce prepended to the
ciphertext + tag). A 32-byte (64 hex chars) key is required; startup
refuses if the env var is unset or malformed.
Generate and mount:
openssl rand -hex 32
Key rotation: out-of-scope for the current release — rotating the key invalidates all existing sessions. Plan a rollout that drains sessions before rotating, or accept the forced re-login.
Database schema isolation (optional)
File: db/schema-security.sql (NOT auto-applied).
By default, TIM runs against a single Postgres role with full access
to both custom_jwt.* and auth.*. For defense-in-depth against a
bug that accidentally crosses schema boundaries, apply
db/schema-security.sql as a superuser once per deployment:
psql "$TIM_ADMIN_URL" \
-v tim.cjwt_password="$TIM_CJWT_PASSWORD" \
-v tim.auth_password="$TIM_AUTH_PASSWORD" \
-v tim.introspect_password="$TIM_INTROSPECT_PASSWORD" \
-f db/schema-security.sql
Then run three TIM instances (or one TIM behind a routing layer / PgBouncer) each connecting as the narrowest role:
tim_custom_jwt— RW oncustom_jwt.*, noauthaccess.tim_auth— RW onauth.*, nocustom_jwtaccess.tim_introspect— RO on both.
A bug that queries the wrong schema now raises permission denied
at the DB rather than silently succeeding. Not required for
correctness — offered for operators who want the extra layer.
Key rotation
The JWT signing key is loaded once at startup from a PKCS#8 PEM file
(jwt.private_key_path). Two rotation modes are supported:
Grace-period rotation (recommended)
For a rotation that does not require every downstream verifier to
refresh JWKS on the same second, configure jwt.previous_key alongside
the new active key:
jwt:
private_key_path: /opt/tim/keys/jwt-private-2027.pem
key_id: tim-rs-2
previous_key:
private_key_path: /opt/tim/keys/jwt-private-2026.pem
key_id: tim-rs-1
retires_at: "2027-01-15T00:00:00Z"
rotation_warn_days: 7 # boot WARN threshold, default 7
While retires_at is in the future:
GET /jwt/keys/publicreturns BOTH keys.- Newly signed tokens use
tim-rs-2(the current key). POST /introspectaccepts tokens signed by either key.
At or after retires_at, the previous key is refused on verification
and dropped from JWKS. Remove the jwt.previous_key block on the next
deploy to clean up.
tim doctor reports the rotation state as a jwt.previous_key check
row; boot emits WARN when the retirement cliff is within
jwt.rotation_warn_days days. Fleet-strongholds row U22/U23: this
grace-period mechanism is the runtime handshake that lets an operator
adopt an HSM/KMS-backed key without a coordinated fleet cut-over.
The legacy JVM 1.x /jwt/verification-key PEM endpoint always returns
the CURRENT key only — its callers cannot pick between candidates. Any
JVM consumer that needs multi-key support must migrate to
/jwt/keys/public (JWKS).
Cold-swap rotation (legacy)
If your downstream verifiers all refresh JWKS quickly and you can tolerate a brief window of "old-kid tokens" being refused:
- Generate a new PKCS#8 PEM keypair.
- Update
jwt.key_idto a new value. - Deploy a new TIM instance with the new key + new kid (no
jwt.previous_key). - Verify
/jwt/keys/publicon the new instance advertises the new kid. - Drain traffic from the old instance.
The old kid disappears from JWKS immediately on cutover. Downstream services that cache JWKS with a TTL keep validating old-kid tokens until their cache expires. Size the overlap window accordingly.
There is no runtime rotation endpoint. This is deliberate — see the "What TIM does NOT do" note in the Introduction.
Container posture
The shipped Dockerfile + docker-compose.yml enforce:
- Distroless runtime (
gcr.io/distroless/cc-debian12:nonroot) — no shell, no package manager, nocurl/wget, no useradd. Trivy--severity HIGH,CRITICALbaseline: 0. (Olddebian:13.6-slimruntime: 3 CRITICAL + 62 HIGH.) - Runs as
USER nonroot:nonroot(UID 65532) — no root at any point. - Read-only root filesystem (
read_only: true), tmpfs for/tmp. - All Linux capabilities dropped (
cap_drop: [ALL]). no-new-privilegesset.- Resource limits (CPU / memory) applied.
- Healthcheck via
tim healthcheck(probes/healthvia reqwest; no shell needed) every 30 s.
No tini. TIM is a single-process axum server — the child-reaping
role tini plays for multi-process containers is a no-op here. K8s or
docker run --init cover PID-1 signal forwarding if needed.
If you build your own image, keep these guarantees. If you run TIM outside Docker (systemd, Nomad), replicate the equivalent primitives.
Rate limiting
TIM does not rate-limit. Put a rate-limiting reverse proxy in
front: nginx limit_req, envoy local_ratelimit, cloud WAF, etc.
The admin-gated endpoints are the primary abuse targets; validate
and userinfo are relatively cheap but still worth capping.
Validation-endpoint DoS gate (audit F-TIM-2, F-TIM-6)
/introspect is not the only endpoint with the "crypto verify +
DB SELECT" shape. /jwt/custom/validate and the JVM 1.x compat
validation endpoints (/jwt/userinfo, /jwt/custom-jwt-verify,
/jwt/custom-jwt-userinfo) share the same DoS profile: an attacker
sending arbitrary tokens can drive the DB pool to exhaustion at low
cost. TIM ships an opt-in Basic-auth gate that reuses the same
introspection.clients list to protect these endpoints without
adding a second secret-rotation policy.
Turn on when TIM is exposed to untrusted networks OR when the reverse proxy in front can forward a Basic header on behalf of the DSL callers. See Configuration → introspection for the three independent axes:
introspection.required_client_auth— protects/introspect(defaulttruesince 0.4.0-alpha).introspection.gate_validation_endpoints— protects/jwt/custom/validate+/validate/boolean(defaultfalse).introspection.gate_jvm_compat_endpoints— protects the three JVM 1.x cookie-borne validation compat endpoints (defaultfalse— enabling breaks browser-direct DSL flows).
Pre-boot validation — tim doctor
Every deploy should run tim doctor before restarting the service.
The subcommand parses tim.yaml, resolves every referenced env var
(admin token, database URL, session encryption key, provider
credentials, introspection client secrets), verifies the JWT key
file exists and parses as PKCS#8 PEM, and prints a structured
PASS / WARN / FAIL table. It never binds a port, never opens a
Postgres connection, never touches the network — safe to run in
locked-down CI.
$ tim doctor
[ OK ] config: loaded from /etc/tim/tim.yaml
[ OK ] config: validate: all cross-field checks pass
[ OK ] jwt.private_key: parsed OK from /etc/secrets/tim/jwt-private.pem (kid=prod-2026-01)
[ OK ] database.url_env: `TIM_DATABASE_URL` resolved to a non-empty value
[ OK ] security.admin_token_env: `TIM_ADMIN_TOKEN` resolved (require_admin_token = true)
[ OK ] introspection.clients: client[ruuter].client_secret_env `TIM_INTROSPECT_RUUTER_SECRET` resolved
[ WARN ] jwt.audience: validation_enabled = false — every caller can request any audience.
---
Summary: 6 pass, 1 warn, 0 fail (total 7)
Exit codes: 0 on all-pass (WARN advisory), 1 on any FAIL or
(under --strict) any WARN, 2 on doctor itself failing. Wire
into deploy pipelines as a pre-flight gate:
tim doctor --strict || { echo "config unsafe, refusing deploy"; exit 1; }
Offline mode — TIM_OFFLINE=1
For pentest engagements, adversarial CI, or any environment where
TIM must NOT accidentally reach a real upstream IdP: set
TIM_OFFLINE=1 and every outbound HTTP call (discovery, JWKS,
token exchange) refuses with 502 instead of hitting the network.
Boot emits a WARN so operators see the flag in the log. Env-only
knob, snapshotted at first read; changing it mid-run has no
effect.
W3C Trace Context — every response carries traceparent
TIM emits traceparent: 00-<32-hex trace-id>-<16-hex span-id>-<2-hex flags>
and x-trace-id: <32-hex trace-id> on every response, including
4xx and 5xx. When a request arrives with a well-formed incoming
traceparent (typically from Ruuter, the fleet reverse proxy),
TIM echoes the caller's trace-id and preserves their sampling
decision (flags). Span-id is always fresh — TIM is a new span
within the (possibly-inherited) trace.
Downstream tooling can correlate a specific TIM response with TIM's log line by grepping the trace-id; the access-log line that names the request carries the same value:
INFO http_request_completed method=POST route=/introspect
status=200 duration_us=1234 trace_id=<same 32-hex value>
Strict request schemas — #[serde(deny_unknown_fields)]
Every modern JSON body / form / query DTO carries
#[serde(deny_unknown_fields)]. A caller sending
{"token":"x","admin_override":true} gets 4xx with the offending
field named, instead of the extra field being silently dropped.
Applies to:
POST /jwt/custom/{generate,validate,extend,revoke,revoke/bulk,list/me}POST /introspect(both JSON and form-encoded)POST /auth/logout(body),GET /auth/login/:id(query)
Deliberately exempt (compat / IdP-driven surfaces): JVM 1.x compat
endpoints, GET /auth/callback/:id (IdPs add per-request params
per RFC 6749), and IdP response DTOs (discovery, JWKS, token
response).
Threat model summary
| Attacker capability | Protection |
|---|---|
| Reach the network | Admin gate on state-changing endpoints (26); reverse-proxy rate limits; CORS if browser-borne |
| Steal a session ID | Session IDs travel via header (27); still short-lived (session_ttl_seconds cap, 9) |
| Steal an admin token | Constant-time compare (26); short-token lifetime by rotation; monitor for unusual X-TIM-Admin-Token traffic |
| Compromise the IdP token endpoint | ID-token JWKS signature verification (01); iss / aud / nonce (02) blocks forged tokens |
| Compromise the DB | Session profile encrypted at rest; JWT tokens hashed to jti in denylist (no plaintext in DB) |
| Bug in JWT service that touches auth schema | Optional per-schema role isolation (23) |
Downgrade to alg=none | Refused at token-header parse (see oauth2::idtoken::verify) |