Changelog
All notable changes to TIM will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased
Fixed
- Allow
clippy::double_must_useinCargo.toml [lints.clippy]. Rust 1.99.0's new lint flagsasync fninside#[async_trait]blocks (the macro layers its own#[must_use]on top of an already-#[must_use]boxed future), breakingcargo clippy --all-targets -- -D warningson every PR againstdev. The offending attribute is in theasync-traitcrate's macro expansion, not TIM source. Unblocks thetestsCI workflow.
Security
- Suppress
RUSTSEC-2024-0449(unmaintainedunsafe-libyaml) in.cargo/audit.tomlanddeny.tomlwith rationale + review date. Pulled in only as a transitive dep ofserde_yaml_ng, which parses the operator-supplied YAML config file at startup — not reachable from the network. Unblocks the scheduledsecurityCI workflow. Migration away fromserde_yaml_ngis tracked as a follow-up. - Update
tokio1.53.1 → 1.54.1 (RUSTSEC-2026-0386,AsyncFd::newI/O-safety unsoundness) and the dev-onlyrustix1.1.4 → 1.1.6 (RUSTSEC-2026-0486, xattr zero-length buffer unsoundness) viaCargo.lock. Lockfile-only; noCargo.tomlchange. - Suppress
RUSTSEC-2026-0459(libsqlite3-sysbundled-SQLite uninitialised-memory disclosure) in.cargo/audit.tomlanddeny.tomlwith rationale + review date. The crate is present inCargo.lockonly as an unresolved optional dependency ofsqlx-macros-core; TIM enables just the sqlxpostgresdriver, so no SQLite code is compiled or linked. No sqlx release can pick up the patchedlibsqlite3-sys >= 0.39(sqlx-sqlite 0.8.6 pins^0.30.1, 0.9.0 caps< 0.38). Together with the two lockfile bumps above, this turns the dailysecurityworkflow green again (red since 2026-11-05).
0.4.1-alpha - 2026-09-18
Eight PRs (#28–#32, #52–#54) rolled into a coordinated release closing the remaining h2ck.me v1 NEXT-TASKS backlog: T-4, T-7, T-8, T-12, T-13, T-15, T-18, T-19. Every open finding from the h2ck.me v1 audit is now landed.
No breaking wire-behaviour changes. The only operator-visible shift is the container runtime — see "Upgrading from 0.4.0-alpha" below.
Upgrading from 0.4.0-alpha
Container runtime switched to distroless (T-12 / G1). If your
deployment pulls docker.io/turnerrainer/tim:0.4.1-alpha (or
ghcr.io/...) unchanged, no action needed — the smaller, zero-CVE
image runs as nonroot:nonroot (UID 65532) and starts on the same
port with the same env vars.
If your deployment customises the container in any of these ways, adjust before upgrading:
- Custom
Dockerfile FROM tim:0.4.0-alpha— the base is nowgcr.io/distroless/cc-debian12:nonroot. No shell, noapt, nocurl. Move anyRUNsteps into an earlier builder stage. - Custom HEALTHCHECK invoking
curl— swap to["CMD", "/app/tim", "healthcheck"]. Thetim healthchecksubcommand probes/healthvia reqwest and exits 0/1; no shell needed. docker exec <container> sh— no shell exists. Usekubectl debug --image=busyboxon K8s, or attach a debug sidecar in compose.- Bind-mounted paths under
/opt/tim/keys— the container user is UID 65532 (was 1000). Ensure the file mode allows reads by that UID. tinias PID 1 — removed. TIM is a single-process axum server; child-reaping is a no-op. K8s ordocker run --initcover PID-1 signal forwarding externally if needed.
No schema migration required.
Added
jwt.previous_keyconfig block (T-7 / F-PR-3) — signing-key rotation with a grace period. JWKS emits both keys and/introspectaccepts tokens signed by either whileretires_at > now; afterretires_atthe previous key is dropped from JWKS and refused on verification. Boot +tim doctoremit WARN when the retirement cliff is withinjwt.rotation_warn_daysdays (default 7). Seebook/src/security-hardening.md§Grace-period rotation.tim healthchecksubcommand (T-12) — probes/healthviareqwestand exits 0 on 200 / 1 otherwise. Wired as the docker-compose HEALTHCHECK on the distroless image (which has nocurl/ shell forCMD-SHELL).--urloverrides the defaulthttp://127.0.0.1:<server.port>/health;--timeout-secondsbounds the probe (default 5s).
Changed
- Docker runtime image switched to distroless (T-12 / G1). Was
debian:13.6-slim; nowgcr.io/distroless/cc-debian12:nonroot. Trivy--severity HIGH,CRITICALcount drops from 65 (3 CRITICAL + 62 HIGH) to 0. Image size shrinks from 119 MB to 32 MB. No shell, no package manager, nocurl, nouseradd. See "Upgrading from 0.4.0-alpha" above. .cargo/audit.toml(T-13) — reviewedRUSTSEC-2023-0071(rsa Marvin timing) rationale. Confirmed session-at-rest encryption uses ChaCha20-Poly1305 (not RSA), noRsaPrivateKey::decryptcall path exists. Next review 2027-03-18.
Fixed
- JWKS thundering herd (T-4 / concurrency mini-audit R-3).
src/oauth2/jwks.rsreplaces theget()+insert()cache-miss path with Moka'stry_get_with, coalescing N concurrent misses on the samejwks_uriinto a single upstream fetch. Regression pin:oauth2::jwks::tests::concurrent_misses_coalesce_to_single_upstream_fetch— 100 concurrent misses → 1 upstream hit. - Attacker-controlled fields clipped in error responses (T-18 /
AP-6). Provider IDs, OIDC callback
error+error_description, id_token parse errors, JWK decode errors, and?jwt=echoes are all clipped to 256 characters viaerror::clip_untrusted. Bounds response payload from a malformed input and caps downstream log-echo blast radius. Regression pin:tests/security_error_echo_clipped.rs.
Security
- JWT algorithm-confusion regression pins (T-8 / G4).
tests/security_jwt_alg_confusion_v1.rsproves TIM refusesalg=nonewith a valid kid, HS256-signed-with-public-key, and every symmetric algorithm +noneforging the signer's kid — all resolve to{"active": false}. Pins the positive control against a future regression that swaps in a permissiveValidation. - Slow-body Slowloris probe (T-15). Verified that
tower_http::timeout::TimeoutLayerbounds body-read too, not just handler execution: a request that trickles bytes pastserver.request_timeout_secondsis aborted at the configured deadline. Not vulnerable, but pinned bytests/security_slow_body_timeout.rs— 8s trickle against a 2s timeout completes in ~2s. - Admin-surface audit (T-19). Enumerated every route in
src/router/mod.rs::build_router; confirmed no accidental public exposure — every mutating endpoint runs behindAdminAuth, every session-scoped read behindSessionAuth, the eight public-by-design endpoints are all protocol-required (health probes, JWKS, OAuth flow endpoints, RFC 7662 discovery). Regression pin:tests/security_admin_surface_audit.rs— 5 cases covering admin/bearer/session/cookie 401s AND that documented-public routes do NOT 401. Book updated with the full inventory (§Endpoint auth invariants). Explicit verdict: TIM does NOT adopt a Ruuter-style/_/*env-gated admin surface — the current gating is comprehensive and adding/_/*would offer attackers a distinct env-shape to probe without security benefit.
0.4.0-alpha - 2026-09-12
Twelve PRs landed on dev between 2026-09-11 and 2026-09-12 as
one coordinated batch closing every open h2ck.me v1 finding (LOG
FN-LOG-1..3, RUNTIME FN1..FN5, PUBLIC-EXPOSURE F-TIM-1..6)
plus eight fleet-strongholds patterns (§1.1, §1.2, §1.6, §2.2,
§2.3, §6.1, §8.2, §9.1) and the CLAUDE.md breaking-change
playbook for LLM agents.
One breaking change — see the "Upgrading from 0.3.0-alpha" section below.
Upgrading from 0.3.0-alpha
One breaking change (audit FN1). introspection.required_client_auth
now defaults to true. POST /introspect refuses unauthenticated
requests, and startup refuses if the flag is on and no
introspection.clients are configured.
To keep the previous permissive behaviour, add to tim.yaml
before upgrading:
introspection:
required_client_auth: false
To take the recommended posture, register each caller:
introspection:
required_client_auth: true
clients:
- client_id: "ruuter"
client_secret_env: "TIM_INTROSPECT_RUUTER_SECRET"
# ... one entry per downstream caller
Then export TIM_INTROSPECT_<name>_SECRET for every referenced env
var before starting TIM. Callers present the secret as HTTP Basic
(scheme case-insensitive per RFC 7235 §2.1):
Authorization: Basic <base64(client_id:secret)>
Two optional new gates (audit F-TIM-2, F-TIM-6) reuse the same
client list and both default false:
introspection.gate_validation_endpoints: true— extends the gate to/jwt/custom/validate+/jwt/custom/validate/boolean.introspection.gate_jvm_compat_endpoints: true— extends the gate to/jwt/userinfo,/jwt/custom-jwt-verify,/jwt/custom-jwt-userinfo. Enabling breaks browser-direct DSL flows unless the reverse proxy forwards a Basic header.
Two operational notes (non-breaking):
- Log stream ANSI escapes now off in non-TTY environments. If your log-shipper regex depends on ESC bytes for delimiter detection, update it — the fleet reference (Ruuter, Resql) has always been 0 ESC bytes.
- Every response now carries
traceparent+x-trace-idheaders. Downstream tooling can correlate a response with TIM's access log by grepping the trace-id.
No schema migration required.
Added
- New subcommand
tim doctor(--strictflag) (fleet §8.2). Pre-boot validator: parsestim.yaml, resolves every referenced env var, verifies the JWT key file exists and parses as PKCS#8 PEM, prints a structured[ OK ] / [ WARN ] / [ FAIL ]table. Exits0on all-pass (WARN advisory),1on any FAIL or--strict+ any WARN. No side effects: never binds a port, never opens a Postgres connection, never touches the network. Wire into deploy pipelines as a pre-flight gate. TIM_OFFLINE=1env var (fleet §9.1). When set (1/true/yes), every outbound HTTP call (OIDC discovery, JWKS, token exchange) short-circuits with 502. Intended for pentest / adversarial CI runs; boot WARN emitted so operators see the posture in the log. Snapshotted at first read.- W3C Trace Context on every response (fleet §1.6):
traceparent: 00-<32-hex>-<16-hex>-<flags>+x-trace-id: <32-hex>. Inherits trace-id and flags from a well-formed incomingtraceparent; generates a fresh trace-id otherwise. Span-id is always fresh — TIM is a new span within the (possibly-inherited) trace. Emitted on 4xx and 5xx paths too. - Per-request access log (audit LOG-v1 FN-LOG-2, fleet §1.2).
One INFO line per completed request:
INFO http_request_completed method=POST route=/introspect status=200 duration_us=1234 trace_id=<32-hex>. Deliberately omits headers, request/response body, and client IP — Ruuter's access log is authoritative for those. - Two opt-in Basic-auth gates on validation surfaces (audit
F-TIM-2, F-TIM-6).
introspection.gate_validation_endpointsprotects/jwt/custom/validate*;introspection.gate_jvm_compat_endpointsprotects the three JVM 1.x cookie-borne validation compat endpoints. Both share the sameintrospection.clientslist — one gate, one secret rotation policy. Both defaultfalsefor BC with existing DSL callers. - Structured JSON on 413 responses (audit RUNTIME-v1 FN3,
fleet §2.3 / §6.1). Wrapped
DefaultBodyLimitwith a middleware that returns{"error":"payload_too_large","max":N}withContent-Type: application/json— instead of Axum's default bare-text. Added aContent-Lengthpreflight so an oversize- declared body is rejected before any bytes are read.
Changed
- BREAKING —
introspection.required_client_authnow defaults totrue(audit FN1). See "Upgrading from 0.3.0-alpha" above. - Log stream ANSI escapes disabled under Docker / systemd / any
pipe (audit LOG-v1 FN-LOG-1).
tracing_subscriber::fmt::Layergates ANSI onstd::io::stderr().is_terminal(). Colours retained when a developer runscargo runat a TTY. - Every modern JSON body / form / query DTO now carries
#[serde(deny_unknown_fields)](fleet §2.2). A request with an unknown field returns 4xx naming the field, instead of silently dropping it. Applies to:POST /jwt/custom/{generate, validate, extend, revoke, revoke/bulk, list/me},POST /introspect(JSON- form),
GET /auth/login/:id(query),POST /auth/logout(body). Deliberately exempt (compat / IdP-driven surfaces): JVM 1.x compat endpoints,GET /auth/callback/:id, IdP response DTOs.
- form),
bind_is_loopbackhelper widened (audit PR #9 nit). Previously matched only127.0.0.1+::1; now accepts127.0.0.0/8,localhost(case-insensitive),[::1],::ffff:127.0.0.1. Applied uniformly in bothAppConfig::validate()anddiagnose()— one helper, two callers.- Basic auth scheme comparison now case-insensitive (audit PR #4
nit, RFC 7235 §2.1).
Basic,basic,BASIC,BaSiCall take the same path. Non-basicschemes (bearer,digest, …) still refused in any casing.
Fixed
- Empty-string
oauth2.providers.<id>.jwks_uripin now rejected at config load (audit PR #10 nit). Previously silently permissive at runtime — indistinguishable from "no pin set" despite the operator's clear intent to pin. Omit the field entirely to disable pinning.
Testing
- New regression pins:
tests/security_log_ansi_off.rs— 2 cases (FN-LOG-1).tests/security_log_access_present.rs— 3 cases (FN-LOG-2).tests/security_introspect_no_token_leak.rs— 3 cases (FN-LOG-3).tests/security_traceparent_response.rs— 6 cases (fleet §1.6).tests/security_413_structured_body.rs— 3 cases (FN3).tests/security_deny_unknown_fields.rs— 8 cases (fleet §2.2).tests/security_offline_mode.rs— 1 case (fleet §9.1).tests/security_validation_gate.rs— 11 cases (F-TIM-2, F-TIM-6).
- Plus 20+ new unit tests across
src/config,src/doctor,src/access_log,src/http,src/security/introspect_auth.
Documentation
- CLAUDE.md — "Shipping a breaking change" playbook. Self- contained rules for LLM agents proposing new breaking changes: what counts, version-bump mechanics, CHANGELOG discipline, migration immutability, PR shape, explicit "must NOT" list.
- CLAUDE.md — verification loop grows a "smoke-test necessary" paragraph. Automated tests are necessary but not sufficient; the exact live-boot smoke recipe is documented, with the concrete reason (cross-branch bugs no unit test catches — one was found in this batch by exactly this smoke pass).
- CLAUDE.md — new
timsubcommands + environment variables sections. Code-layout expanded with new modules (src/access_log,src/doctor,src/http). - Book —
configuration.md. Introspection section rewritten for the new default + three-axis gate model.TIM_OFFLINEdocumented. - Book —
security-hardening.md. Four new sections:tim doctor, offline mode, W3C Trace Context, validation-endpoint DoS gate.
Merged PRs
- #13 security(log): disable ANSI + per-request access log middleware (audit FN-LOG-1, FN-LOG-2, FN-LOG-3)
- #14 router(413): structured JSON body on payload-too-large (audit FN3)
- #15 fix: h2ck.me v1 PR-review nits (empty jwks_uri pin, case-insensitive Basic, bind loopback)
- #16 docs(claude): playbook for shipping a breaking change
- #17 introspect(BREAKING): flip required_client_auth default to true (audit FN1)
- #18 access_log: propagate W3C traceparent + x-trace-id on response (fleet §1.6)
- #19 feat:
tim doctor— pre-boot config + env validator (fleet §8.2) - #20 feat: TIM_OFFLINE=1 refuses every outbound HTTP call (fleet §9.1)
- #21 chore:
#[serde(deny_unknown_fields)]on modern request DTOs (fleet §2.2) - #22 docs(book+claude): tim doctor, TIM_OFFLINE, FN1 default, traceparent, deny_unknown
- #23 security: gate /jwt/custom/validate + JVM compat validation endpoints (audit F-TIM-2, F-TIM-6)
0.3.0-alpha - 2026-09-06
Post-audit release. Nine PRs (h2ck.me v1 audit findings + one Snyk
base-image bump) landed on dev between 2026-09-04 and 2026-09-06
as one coordinated batch. Every finding was independently reviewed
by h2ck.me and closed with verdict ✅ pass.
Upgrading from 0.2.x
One breaking change. OIDC discovery is fail-closed on plain
HTTP by default (see ### Changed below). To find and fix
affected configs before upgrading:
# Any plain-http discovery_url in your tim.yaml:
grep -nE 'discovery_url:\s*http://' tim.yaml
# Anywhere in a mounted config directory:
grep -rnE 'discovery_url:\s*http://' /path/to/config/
If a hit is intentional (dev against a non-TLS mock IdP), set
oauth2.providers.<id>.allow_http_discovery: true alongside the
plain-http URL. Otherwise, switch to https:// before upgrading.
The check also enforces HTTPS on endpoints inside the returned
discovery document — a provider that publishes HTTP endpoints in
its .well-known/openid-configuration will fail login regardless
of the URL you configured, and needs the same opt-in.
Two soft behaviour changes worth noting:
- Legacy
?session_id=<id>query-string transport now logs at WARN (was DEBUG). Log-volume alerting keyed on WARN counts may fire on deployments still using the query transport. Migrate callers toAuthorization: Bearer sess_<id>orX-TIM-Session. - JWT validate
reasonfield values may differ for previously mis-classified errors (see### Fixedonjwt/service.rs). Dashboards keyed on the exactreasonstring may need updating.
No schema migration needed. The pkce_verifier column used by the
PKCE work was reserved in migrations/0001_init.sql since the
first alpha; existing databases already have it.
Added
- Boot-time diagnostic in
AppConfig::diagnosenow warns loudly on two long-standing operator footguns:- CORS wildcard exposes cross-origin reads. When
security.cors_allowed_originscontains"*", TIM logs that every unauthenticated read endpoint (/health,/auth/providers, ...) is now reachable cross-origin. - HSTS + non-loopback bind without
preload. When bind is not loopback andstrict_transport_securitylackspreload, TIM names both facts in one line and points athttps://hstspreload.org. First-request MITM against non-preloaded HSTS deployments leaks bearer tokens in the clear.
- CORS wildcard exposes cross-origin reads. When
src/oauth2/flow.rs— OAuth2 authorization requests now send a per-requestcode_challenge(SHA-256 base64url-nopad) pluscode_challenge_method=S256per RFC 7636 (PKCE). The 32-byte verifier is persisted alongsidestateinauth.oauth_stateand replayed on the token endpoint. Unblocks IdP registrations that mandate PKCE (some TARA/Google/Microsoft clients) and protects the authorization code against on-path interception on registrations that permit non-PKCE.oauth2.providers.<id>.jwks_uri: Option<String>— pin the JWKS URI expected in the discovery document. When set, TIM refuses discovery whosejwks_uridiffers, closing the empty-JWKS DoS path against a MITM'd discovery response. Default: unset (no pin), preserving existing behaviour.POST /introspectnow supports optional Basic-auth client authentication per RFC 7662 §2.1. Configured via a newintrospectionsection:introspection.required_client_auth: bool(default false for backwards compatibility)introspection.clients: [{ client_id, client_secret_env }]Secrets are compared constant-time (subtle::ConstantTimeEq). When required, missing/wrong credentials → 401; the endpoint no longer accepts every request against the denylist SELECT.
- New module
src/security/introspect_auth.rs+IntrospectionGateboot resolver. Fails startup if any referencedclient_secret_envis unset when the gate is required.
Changed
src/oauth2/flow.rs,src/oauth2/state_sweeper.rs—auth.oauth_stateinterval expressions rewritten asnow() - make_interval(secs => $N::int)instead of the string-concat- then-cast form. Semantics identical (bind is still parameterised — no injection path either way); the new form reads what it does.- OIDC discovery is now fail-closed on plain HTTP.
provider. discovery_urland endpoints inside the discovery document (authorization_endpoint,token_endpoint,jwks_uri) must all usehttps://or startup / login refuses. Operators intentionally running against a non-TLS mock IdP for dev must setoauth2.providers.<id>.allow_http_discovery: true. Closes MITM substitution of the JWKS URI on the discovery fetch. src/security/session_auth.rs— the legacy?session_id=query transport now emits WARN (was DEBUG). Operators grepping their logs can identify remaining callers before removing the fallback. Payload/behaviour otherwise unchanged.
Fixed
src/jwt/service.rs::validate— reason-code classification now matches onjsonwebtoken::errors::ErrorKindvariants instead offormat!("{e}").contains("expired"). The prior pattern would have silently reclassified every non-expiry error assignature_mismatchon ajsonwebtokentext-format change, hiding real bugs and breaking monitoring keyed on the reason string. NewJwtSigner::verify_rawexposes the typed error so classifier logic doesn't lose the kind through theTimErrorwrapper.src/oauth2/session/postgres.rs—PostgresStore::getnow filters expired rows in the SELECT (AND expires_at > now()) instead of doing a check-then-DELETE in Rust. Removes the two-writer race where concurrent gets on an expiring session both saw the row as expired and raced the DELETE (one won, the other errored — visible as inconsistent 404/401 pairs). Expired rows are now removed only bysweep_expired, which is already scheduled by the state sweeper.
Testing
- New
tests/it_oauth_state_race.rspins the atomic single-use contract onDELETE ... RETURNING: 32 concurrent callbacks with the samestatevalue produce exactly one winner. Also asserts that an aged-past-cap row cannot be consumed even before the sweeper reaches it (closes the sweeper vs. consumer race).
0.2.1-alpha - 2026-08-31
Two OAuth2/OIDC defects, both surfaced against TARA
(tara-test.ria.ee). Thanks to Ermo Mägi for the diagnosis
against the live endpoint.
Fixed
src/oauth2/flow.rs— token exchange now authenticates via HTTP Basic (client_secret_basic) instead of postingclient_id/client_secretas form fields (client_secret_post). OIDC Core §9 makes Basic the default when the client registration is silent, and TARA's registration is silent — it rejectsclient_secret_postwith401 invalid_client, which surfaced in TIM as a bare 502 and blocked every TARA login. Providers that accept both methods (Google, Auth0, Okta, Microsoft, Apple) keep working; providers that only acceptclient_secret_postare not currently supported (no user has one).src/oauth2/idtoken.rs— claim mappings now walk dot-separated paths into nested JSON objects viaresolve_claim_path. TARA carriesgiven_nameandfamily_nameonly underprofile_attributes, and the previous flat lookup returnedNonefor any dotted mapping, silently producing sessions with empty names. A name without a dot is still a plain top-level lookup (behaviour unchanged); a dotted path that does not exist yieldsNoneand does not fall back to a top-level claim with the same trailing segment.src/oauth2/flow.rs— theBadGatewaymessage from a failed token exchange now includes the upstream response body (bounded to 512 characters). OAuth2 error responses name the actual problem (invalid_client,invalid_grant, ...); dropping it left operators with a bare status code and no way to diagnose without reproducing the request by hand.
Testing
- Regression tests cover: token endpoint receives Basic auth with
no client credentials in the form body; upstream 401 surfaces as
502 without panicking on
resp.text(); dotted mappingprofile_attributes.given_nameresolves the nested value end-to-end; a dotted-path miss does not fall back to a top-level claim; and aprofile_from_claimsseam test pinning theresolve_claim_pathdispatch. All would have caught the originals; verified by reverting each fix and re-running.
Container images
Users pulling docker.io/turnerrainer/tim:alpha or
ghcr.io/turnerrainer/tim:alpha get this version automatically.
Pinned users should switch from :0.2.0-alpha.2 to
:0.2.1-alpha.
0.2.0-alpha.2 - 2026-08-05
CI-only fix. Same runtime behaviour as 0.2.0-alpha.1.
The 0.2.0-alpha.1 container images were published to Docker Hub
and GHCR but the publish workflow's smoke test failed (missing
TIM_ADMIN_TOKEN env var — the shipped tim.yaml sets
security.require_admin_token: true), which skipped the cosign
signing step. 0.2.0-alpha.2 re-publishes with the smoke test
fixed and with cosign signatures attached.
Users pulling docker.io/turnerrainer/tim:alpha or
ghcr.io/turnerrainer/tim:alpha get this version automatically.
Users who explicitly pinned to :0.2.0-alpha.1 should switch to
:0.2.0-alpha.2 for a cosign-signed image.
Fixed
.github/workflows/publish.yml— smoke test now setsTIM_ADMIN_TOKEN=smoke-only-not-a-real-secretwhen launching the container. Fix for the failed alpha.1 publish.
0.2.0-alpha.1 - 2026-08-05
Second alpha. Post-audit release: fixes silent-drop bugs from 0.1.0-alpha.1, restores JVM 1.x + JVM 2.0 contract parity where downstream DSLs depend on it, adds TARA integration coverage, adds an admin-token gate on state-changing endpoints, and lands a Postgres session store as an alternative to the default in-memory one.
Still alpha. Two significant features are spec'd but not implemented:
mint-jwt-from-session— no endpoint yet for deriving a TIM-signed service JWT from an OAuth2 session. Downstream services calling TIM-behind-Ruuter for authorised APIs still need to hit/auth/session/validateper request or generate a fresh JWT via the admin gate.- PKCE — the authorization code flow does not send PKCE parameters. Providers that mandate PKCE (some TARA and Google client registrations do) will reject the login.
Live-fire testing against real TARA / Google sandboxes has NOT been done — the TARA integration tests use a mock IdP.
Test coverage at release
96 tests total, --test-threads=1:
| Binary | Count | Purpose |
|---|---|---|
cargo test --lib | 42 | Config validation, crypto primitives, session-store semantics, admin gate, JWKS parsing, ID-token helpers |
it_jwt_lifecycle | 7 | Custom JWT generate → validate → extend → revoke |
it_legacy_compat | 15 | All eight JVM 1.x cookie-borne endpoints end-to-end |
it_oauth2 | 6 | Provider registry, session-auth surfaces, health |
it_oauth2_callback | 3 | End-to-end OAuth2 callback with a mock IdP |
it_oauth2_tara | 7 | TARA-specific claim shape + five rejection paths |
it_regression_findings | 11 | Regression tests for behaviours fixed post-audit |
Fixed — security-relevant
- OIDC ID-token verification is now performed on every callback.
Signature (via the provider's cached JWKS),
iss(must matchdiscovery.issuer),aud(must containclient_id),exp,nbf,iat(with configurable clock skew), and mandatorynoncecomparison — all constant-time where relevant. Refusesalg=noneand symmetric algorithms outright. The 0.1.0-alpha.1 callback did not verify the ID token at all. - Mandatory
nonceon ID tokens. A missingnonceclaim is now a hard rejection; the previous behaviour silently accepted tokens without a nonce claim. oauth2.session_storeconfig value is enforced. Values other than"memory"or"postgres"fail at startup.- Session TTL is capped at
min(configured_ttl_seconds, expires_in-from-IdP); oversizedexpires_inno longer produces an immortal session. POST /jwt/custom/list/mechecks the denylist. Revoked bearer tokens can no longer enumerate the caller's other tokens until natural expiry.- Admin-token gate on state-changing custom-JWT endpoints.
/jwt/custom/generate,/revoke,/revoke/bulk,/extendnow requireX-TIM-Admin-Token:orAuthorization: Bearer <admin>. Configured viasecurity.admin_token_env. Startup refuses whenrequire_admin_token: true(default) and the env var is missing.
Fixed — OAuth2 / OIDC
- Callback bubbles IdP
error=responses as structured 400 instead of "missing field code" schema-validation errors. redirect_uriper-provider allow-list viaoauth2.providers.<id>.allowed_redirect_uris. Caller-supplied URIs must match an entry exactly; falls back to the first entry when the caller omits.- Discovery documents are validated for required fields plus
grant_types_supported: authorization_codeandresponse_types_supported: code. - Discovery fetch retries with exponential backoff on 5xx and network errors (three attempts). 4xx fails fast.
token_validation.clock_skew_seconds/cache_ttl_secondsare consumed by the ID-token verifier — previously they were parsed but ignored.auth.oauth_staterows have an age cap enforced in theDELETE ... RETURNINGclause. Default 300 s (JVM 2.0 parity). A background sweeper reaps stale rows everysession_sweep_interval_seconds(default 60 s).- Session ID transport moved to headers —
Authorization: Bearer sess_<id>orX-TIM-Session: <id>are the primary transports. Legacy?session_id=<id>query still accepted for backward compatibility. server.public_base_urlconfig field replaces the hardcodedhttp://localhost:8085callback synthesis. Empty means "caller must pass?redirect_uri=explicitly."provider.claim_mappingscan now target registered JWT claims (sub,iss,aud). TARA's personal-code mapping (personal_code: "sub") works correctly.
Fixed — Custom JWT lifecycle
POST /jwt/custom/revokereturns 409 on idempotent repeat; matches JVM 2.0's semantics.POST /jwt/custom/validatereturns 401 on invalid/expired/ revoked tokens; the body'svalid/active/reasonfields still carry the details. Matches JVM 2.0.POST /jwt/custom/generatereturnsstatus: "created";POST /jwt/custom/extendreturnsstatus: "extended". Response-shape parity with JVM 2.0.setCookie: truein request body actually emitsSet-Cookieon the response. Attributes:Path=/; HttpOnly; Secure; SameSite=Lax(addsSecure+SameSitebeyond JVM defaults).token_type: "custom_jwt"claim is signed into every custom JWT at generate time; extended tokens preserve or backfill it.POST /jwt/custom/extenddefault TTL is 60 minutes when the caller omitsexpirationInMinutes(JVM 2.0 parity).POST /jwt/custom/list/mepagination accepts JVMpagesemantics (offset= page number,limit= page size, default 20); response carries bothpage/size/total_pagesandoffset/limit(row shape). Opt-inby_row: trueinterpretsoffsetas row offset.jwt_namefilter is honoured onPOST /jwt/custom/list/me(was silently ignored in JVM 2.0).POST /introspectreturns uniform{"active": false}on every inactive path (unknown, revoked, expired, wrong issuer, bad signature).POST /introspectaccepts JSON or form even without a Content-Type header (best-effort parse).
Added — legacy compatibility endpoints
Restored the eight cookie-borne endpoints the original Buerokratt TIM exposed and JVM 2.0 dropped. These coexist with the modern header/body shapes — nothing was replaced.
GET /healthz— alias forGET /health.GET /jwt/verification-key— signing public key as PKCS#1 PEM.GET /jwt/userinfo— read JWT from configured cookie name.POST /jwt/custom-jwt-verify— verify JWT from cookie named in body.POST /jwt/custom-jwt-userinfo— read JWT from cookie named in body.POST /jwt/custom-jwt-extend— admin-gated; extend + refresh cookie.GET /jwt/extend-jwt-session— admin-gated; extend default cookie.POST /jwt/custom-jwt-blacklist— admin-gated; body = cookie name.POST /jwt/blacklist— admin-gated; three modes (cookie /?jwt=<uuid>/?sessionId=<id>). Returns real status codes (200 / 409 / 404) instead of JVM 1.x's "always 200."
Config knob for the cookie name: jwt.cookie_name (default "jwt";
set to "JWTTOKEN" for JVM 1.x DSL parity).
Added — TARA (Estonian eID) integration
Config-only integration. Full "TARA" section added to the OAuth2 book chapter covering:
- Provider block for
tara-test.ria.eeandtara.ria.ee. - Claim mapping:
personal_code: "sub",first_name: "given_name",last_name: "family_name",acr,amr,date_of_birth. - Scope semantics (
openid,openid phone,openid idcard,openid mid). - Test-vs-prod discovery URL swap.
- LoA policy hand-off (target extracts
acr; downstream services enforce policy).
Integration coverage: 7 test cases exercising personal-code
- Estonian UTF-8 round-trip,
acr/amrarray shape, issuer/kid/alg=none/expiry rejection paths, andprofile_attributesnot being silently promoted.
Added — HTTP security posture
security.admin_token_env— env var name holding the privileged-endpoint token. Constant-time comparison.- CORS layer via
security.cors_allowed_origins. - Response-header middleware —
Content-Security-Policy,Strict-Transport-Security,X-Frame-Options,X-Content-Type-Options,Referrer-Policy— all configurable, emitted by default with conservative values. - Boot-time diagnostic pass —
AppConfig::diagnose()logs every parsed config field at INFO with WARN on non-secure or operator-attention-required settings. Grep fortim::config::diagnosein logs.
Added — Postgres session store
oauth2.session_store: "postgres"persists sessions across process restart and spans replicas. Profile data (which may contain IdP-derived PII) is AEAD-encrypted at rest via chacha20poly1305 using a 32-byte key fromoauth2.session_encryption_key_env(defaultTIM_SESSION_ENCRYPTION_KEY). Startup refuses if the key env var is unset or malformed.- Background sweeper deletes expired sessions + stale
oauth_state rows every
oauth2.session_sweep_interval_seconds(default 60 s). SessionStoretrait withMemoryStoreandPostgresStorebackends. Selected by config at startup.
Added — Config / lifecycle knobs
server.public_base_url— externally-reachable URL used to synthesise the default OAuth2 callback URL.database.acquire_timeout_seconds/idle_timeout_seconds/max_lifetime_seconds— pool tuning.test_before_acquire(true)transparently to PgBouncer bouncing.oauth2.session_ttl_seconds(24 h default),state_max_age_seconds(5 min default),session_sweep_interval_seconds(60 s default).serde(deny_unknown_fields)onAppConfigand every nested struct — a typo intim.yamlnow fails at startup rather than silently defaulting.
Known API-shape changes vs. JVM 2.0
Additive or documented; no field removed. Callers unaffected in the common case:
GET /jwt/keys/publicreturns a bare RFC 7517 JWKS ({"keys":[…]}), not JVM 2.0's{"jwk": "<stringified JWKS>"}wrapper. Legacy callers useGET /jwt/verification-keyfor the PKCS#1 PEM shape instead.- List response carries both pagination shapes
(
page/size/total_pagesANDoffset/limit). Set-Cookieattributes addSecureandSameSite=Laxwhere JVM 1.x omitted both.
0.1.0-alpha.1 - 2026-07-30
First alpha release. Rust rewrite of TIM (Java / Spring Boot 3.3.3), covering the endpoints enumerated in the design document.
Known limitations at time of release
- ID-token signature verification NOT implemented — deferred and treated as a critical bug by the post-release audit. Fixed in 0.2.0-alpha.1 above.
- Session store hard-coded to in-memory
DashMap; theoauth2.session_storeconfig knob was accepted but ignored. - No admin gate on
/jwt/custom/generateor related privileged endpoints.
Added — Custom JWT lifecycle
POST /jwt/custom/generate— generate an RS256-signed JWT with a custom claims payload, configurable expiration, and optional audience. Persists tocustom_jwt.jwt_metadatawithoriginal_jwt_uuidset to the new token'sjti(chain root).POST /jwt/custom/validate— signature, expiration, denylist, optional audience + issuer.POST /jwt/custom/validate/boolean— same checks, plain-texttrue/falseresponse.POST /jwt/custom/extend— issue a fresh token preserving the original claims + audience; immediately denylists the old one; links the new token viasupersedes+original_jwt_uuid.POST /jwt/custom/revoke— insert the token'sjtiintocustom_jwt.denylist.POST /jwt/custom/revoke/bulk— up to 100 tokens per request (configurable viajwt.bulk_revoke_max); returns 207-style body with per-token results.POST /jwt/custom/list/me— paginated list of the caller's tokens (bearer JWT inAuthorization).GET /jwt/keys/public— JWK Set advertising the signing public key.
Added — OAuth2 / OIDC (MVP)
GET /auth/providers,GET /auth/providers/{provider_id}.GET /auth/login/{provider_id}— authorization code flow init.GET /auth/callback/{provider_id}— token exchange + session creation. See "Known limitations" above — this path did not validate the ID token in this release.GET /auth/session/validate?session_id=...,GET /auth/profile?session_id=...,POST /auth/logout?session_id=...,GET /auth/health.- OIDC discovery + JWKS cached per-provider (
moka, TTL from config). - Config-driven provider list.
Added — RFC 7662 introspection
POST /introspect(form + JSON),GET /introspect/types.
Added — Framework
- Config loading (CLI → env →
./tim.yaml→ defaults). Secrets via<field>_env: NAMEpattern. TimErrorenum with per-variant HTTP status mapping.- Postgres pool via
sqlx. Migrations auto-applied whendatabase.auto_migrate: true. - RSA private key loaded once at startup (PKCS#8 PEM).
- Request body size cap, per-request timeout.
- Structured tracing via
tracing_subscriber::EnvFilter.
Added — Repository, CI, docs
.github/workflows/: tests, security, publish, docs.book/mdBook.- Hardened container: multi-stage build, non-root user, tini init.
- Hardened compose:
read_only,cap_drop: ALL,no-new-privileges, tmpfs/tmp, resource limits, healthcheck. deny.toml+.cargo/audit.toml.