Repository navigation
Releases
v0.4.1-alpha
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 now
gcr.io/distroless/cc-debian12:nonroot. No shell, noapt, no
curl. Move anyRUNsteps into an earlier builder stage. - Custom HEALTHCHECK invoking
curl— swap to
["CMD", "/app/tim", "healthcheck"]. Thetim healthcheck
subcommand probes/healthvia reqwest and exits 0/1; no shell
needed. docker exec <container> sh— no shell exists. Use
kubectl 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 while
retires_at > now; afterretires_atthe previous key is dropped
from JWKS and refused on verification. Boot +tim doctoremit
WARN when the retirement cliff is within
jwt.rotation_warn_daysdays (default 7). See
book/src/security-hardening.md§Grace-period rotation.tim healthchecksubcommand (T-12) — probes/healthvia
reqwestand exits 0 on 200 / 1 otherwise. Wired as the
docker-compose HEALTHCHECK on the distroless image (which has no
curl/ shell forCMD-SHELL).--urloverrides the default
http://127.0.0.1:<server.port>/health;--timeout-seconds
bounds 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::decrypt
call 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 callbackerror+
error_description, id_token parse errors, JWK decode errors,
and?jwt=echoes are all clipped to 256 characters via
error::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 refuses
alg=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 past
server.request_timeout_secondsis aborted at the configured
deadline. Not vulnerable, but pinned by
tests/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.
v0.4.0-alpha
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: falseTo 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 callerThen 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_endpoints
protects/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). WrappedDefaultBodyLimitwith a middleware
that returns{"error":"payload_too_large","max":N}with
Content-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::Layer
gates 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()and
diagnose()— 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_OFFLINE
documented. - 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)
v0.3.0-alpha
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 at
https://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) plus
code_challenge_method=S256per RFC 7636 (PKCE). The 32-byte
verifier is persisted alongsidestateinauth.oauth_state
and 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 new
introspectionsection: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 referenced
client_secret_envis unset when the gate is required.
Changed
src/oauth2/flow.rs,src/oauth2/state_sweeper.rs—auth.oauth_state
interval expressions rewritten as
now() - 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 set
oauth2.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 of
format!("{e}").contains("expired"). The prior pattern would have
silently reclassified every non-expiry error as
signature_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 theTimError
wrapper.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).
v0.2.1-alpha
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 rejects
client_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_post
are 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 under
profile_attributes, and the previous flat lookup returned
Nonefor 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 onresp.text(); dotted mapping
profile_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 the
resolve_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.
v0.2.0-alpha.2
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 sets
TIM_ADMIN_TOKEN=smoke-only-not-a-real-secretwhen launching
the container. Fix for the failed alpha.1 publish.
v0.2.0-alpha.1
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 match
discovery.issuer),aud(must containclient_id),exp,
nbf,iat(with configurable clock skew), and mandatorynonce
comparison — all constant-time where relevant. Refusesalg=none
and 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,/extend
now 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 via
oauth2.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_codeand
response_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_seconds
are consumed by the ID-token verifier — previously they were
parsed but ignored.auth.oauth_staterows have an age cap enforced in the
DELETE ... RETURNINGclause. Default 300 s (JVM 2.0 parity).
A background sweeper reaps stale rows every
session_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 hardcoded
http://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-Cookie
on 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 JVMpage
semantics (offset= page number,limit= page size, default
20); response carries bothpage/size/total_pagesand
offset/limit(row shape). Opt-inby_row: trueinterprets
offsetas 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, and
profile_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 for
tim::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 from
oauth2.session_encryption_key_env(default
TIM_SESSION_ENCRYPTION_KEY). Startup refuses if the key env
var is unset or malformed.- Background sweeper deletes expired sessions + stale
oauth_state rows everyoauth2.session_sweep_interval_seconds
(default 60 s). SessionStoretrait withMemoryStoreandPostgresStore
backends. 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/ke...
TIM v0.1.0-alpha.1 — first alpha release
First alpha release. Full Rust rewrite of TIM (Java / Spring Boot 3.3.3) targeting feature parity with the upstream JVM implementation, hardened per DEV-REQUIREMENTS.md.
Multi-arch container images
Both linux/amd64 and linux/arm64, keyless-signed via cosign (Sigstore).
docker.io/turnerrainer/tim:0.1.0-alpha.1docker.io/turnerrainer/tim:alphaghcr.io/turnerrainer/tim:0.1.0-alpha.1ghcr.io/turnerrainer/tim:alpha
Verify signature:
cosign verify docker.io/turnerrainer/tim:0.1.0-alpha.1 \
--certificate-identity-regexp '(?i)https://github\.com/turnerrainer/tim/' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com'What's in this release
Custom JWT lifecycle
POST /jwt/custom/generate— RS256-signed JWT with custom claims, optional audience, configurable expirationPOST /jwt/custom/validate— signature + expiration + denylist + optional audience/issuerPOST /jwt/custom/validate/boolean— plain-texttrue/falsePOST /jwt/custom/extend— new token preserving claims, old one denylisted, chain linkage recordedPOST /jwt/custom/revoke(+/bulk, up to 100 per request)POST /jwt/custom/list/me— paginated caller-token listing (bearer JWT)GET /jwt/keys/public— JWKS with signing public key
OAuth2 / OIDC (MVP)
GET /auth/providers,GET /auth/login/{id},GET /auth/callback/{id}- Session validate / profile / logout
- OIDC discovery + JWKS cached per-provider
- Config-driven provider list — no code changes to add a standard OIDC provider
- Session storage MVP: in-process
DashMap. Postgres-backed session store tracked as follow-up
RFC 7662 introspection
POST /introspect(form + JSON),GET /introspect/types