Migrating from JVM TIM

This chapter documents every observable difference between TIM-on-Rust and the two upstream Java implementations:

  • Original Buerokratt TIM (Java / Spring Boot, JVM 1.x).
  • Buerostack JVM 2.0 (Java / Spring Boot 3.3.3 rewrite).

If you are migrating an existing deployment, use this as a per-endpoint checklist. Every deviation was surfaced during the post-alpha audit; see the CHANGELOG entry for [0.2.0-alpha.1] for the full change list.

Endpoint availability matrix

EndpointBuerokratt JVM 1.xBuerostack JVM 2.0TIM-on-Rust
GET /healthyesyesyes
GET /jwt/keys/publicyes (wrapped)yes (wrapped)yes (bare JWKS, RFC 7517)
POST /jwt/custom/generate(was /jwt/custom-jwt-generate)yesyes, admin-gated
POST /jwt/custom/validatevia /custom-jwt-verifyyesyes
POST /jwt/custom/validate/boolean—yesyes
POST /jwt/custom/revokevia /custom-jwt-blacklistyesyes, admin-gated
POST /jwt/custom/revoke/bulk—yesyes, admin-gated
POST /jwt/custom/extendvia /custom-jwt-extendyesyes, admin-gated
POST /jwt/custom/list/me—yesyes
POST /introspect—yesyes
GET /introspect/types—yesyes
GET /auth/providers(implicit)yesyes
GET /auth/login/{id}via Spring Security OAuth2yesyes
GET /auth/callback/{id}via /authenticateyesyes (+ real ID-token verification)
GET /auth/session/validate—yesyes
GET /auth/profilevia /userinfo (cookie)yesyes
POST /auth/logoutvia /logoutyesyes
GET /jwt/userinfoyes (cookie)droppedrestored (legacy, public)
POST /jwt/blacklistyesdroppedrestored (legacy, admin-gated)
POST /jwt/custom-jwt-blacklistyesdroppedrestored (legacy, admin-gated)

The three restored legacy endpoints are documented in Legacy compatibility. They coexist with the modern shapes; nothing was replaced.

Response-shape changes

POST /jwt/custom/generate

FieldJVM 2.0TIM-on-Rust
status"created""created" ← parity restored

TIM-on-Rust 0.1.0-alpha.1 briefly returned "ok"; the current build returns "created" to match JVM 2.0.

POST /jwt/custom/extend

FieldJVM 2.0TIM-on-Rust
status"extended""extended" ← parity restored
jwt_name on missing"EXTENDED_TOKEN""EXTENDED_TOKEN" ← parity restored
Default expirationInMinutes6060 ← parity restored
HTTP on expired/revoked401422 (Rust chose 422 as more precise; JVM callers switching on 401 need to add 422 to their branch)

POST /jwt/custom/revoke

SituationJVM 2.0TIM-on-Rust
Newly revoked200 {"status": "revoked"}200 {"status": "revoked", "message": "..."}
Idempotent repeat409 {"status": "already_revoked"}409 {"status": "already_revoked", "message": "..."}

Parity restored.

POST /jwt/custom/validate

SituationJVM 2.0TIM-on-Rust
Valid + active200200
Invalid or revoked401 with response body401 ← parity restored

Callers that assumed 200 for every response now need to check HTTP status. The response body's valid/active fields still tell the full story.

POST /jwt/custom/list/me

FieldJVM 2.0TIM-on-Rust
Request offsetpage numberpage number (opt into row-offset with by_row: true)
Request limitpage size (default 20)page size (default 20)
Request jwtNameaccepted (JVM bug: silently ignored)accepted and honoured
Response pagepresentpresent
Response sizepresentpresent
Response total_pagespresentpresent
Response offsetabsentadditionally present (row offset)
Response limitabsentadditionally present (page size)
Denylist checkyesyes ← now checked (was missing in initial Rust cut)

GET /jwt/keys/public

ShapeJVM 2.0TIM-on-Rust
Response{"jwk": "<stringified JWKS>"}{"keys": [...]} (bare RFC 7517 JWKS)

Breaking difference kept for RFC-correctness. Clients that unwrapped .jwk and parsed the inner string must switch to parsing the top-level keys directly.

OAuth2 flow changes

ID-token verification

JVM 2.0 — JwtValidationService.validateIdToken verifies signature, iss, aud, exp, nbf, iat, and nonce.

TIM-on-Rust 0.1.0-alpha.1 — did not verify signature at all (critical bug fixed post-alpha.1).

Current — matches JVM 2.0 behaviour and adds: constant-time nonce comparison, mandatory nonce presence, refusal of alg=none and symmetric algorithms.

Session storage

JVM 2.0 — in-process ConcurrentHashMap; no persistence.

TIM-on-Rust 0.1.0-alpha.1 — same, but the config knob was silently ignored.

Current — oauth2.session_store: "memory" | "postgres". Postgres mode persists across restart, spans replicas, encrypts profile data at rest with chacha20poly1305.

Session TTL

JVM 2.0 — min(24h, expires_in).

TIM-on-Rust 0.1.0-alpha.1 — expires_in unbounded.

Current — min(oauth2.session_ttl_seconds, expires_in). Matches JVM's cap semantics.

redirect_uri handling

Buerokratt / JVM 2.0 — hard-coded http://localhost:8085/... (TODO comment in both).

TIM-on-Rust 0.1.0-alpha.1 — accepted any caller-supplied value without validation.

Current — per-provider allowed_redirect_uris allow-list; falls back to {server.public_base_url}/auth/callback/{id}. Invalid input rejected 400.

Callback error handling

JVM 2.0 — accepts error= param, bubbles to caller.

TIM-on-Rust 0.1.0-alpha.1 — required code=, so IdP-returned errors surfaced as "missing field code" 400s.

Current — matches JVM.

auth.oauth_state hygiene

JVM 2.0 — in-memory state, 5-minute expiry checked in validateCallback.

TIM-on-Rust 0.1.0-alpha.1 — DB-backed state, no age check, no sweep — rows accumulated indefinitely.

Current — DB-backed state with 5-minute default age cap (oauth2.state_max_age_seconds) enforced in the DELETE ... RETURNING clause, plus a background sweeper every oauth2.session_sweep_interval_seconds.

Config surface — new fields

FieldPurposeDefault
server.public_base_urlExternal TIM URL; used for default callback synthesis""
database.acquire_timeout_secondsPool timeout knob30
database.idle_timeout_secondsPool timeout knob600
database.max_lifetime_secondsPool timeout knob1800
jwt.cookie_nameCookie name for legacy endpoints"jwt"
oauth2.state_max_age_secondsoauth_state row max age300
oauth2.session_sweep_interval_secondsSweeper interval60
oauth2.session_encryption_key_envEnv var for AEAD key"TIM_SESSION_ENCRYPTION_KEY"
oauth2.providers.<id>.allowed_redirect_urisPer-provider allow-list[]
security.admin_token_envEnv var for admin token"TIM_ADMIN_TOKEN" (empty in defaults)
security.require_admin_tokenRefuse boot if unresolvedtrue
security.cors_allowed_originsCORS origin list[]
security.content_security_policyCSP header(see Security hardening)
security.strict_transport_securityHSTS header(see Security hardening)
security.referrer_policyReferrer-Policy header"no-referrer"
security.x_frame_optionsX-Frame-Options header"DENY"
security.x_content_type_optionsX-Content-Type-Options header"nosniff"

Migration checklist

For each existing JVM 2.0 deployment:

  1. Generate an admin token and set TIM_ADMIN_TOKEN in the environment.
  2. Set server.public_base_url in tim.yaml.
  3. For every provider block, add allowed_redirect_uris: [<canonical URL>].
  4. Decide session store: keep memory (single replica) or switch to postgres (multi replica). If Postgres, generate a 32-byte hex key and set TIM_SESSION_ENCRYPTION_KEY.
  5. Update client-side callers that switched on body.status == "ok" — the value is now "created" for generate and "extended" for extend.
  6. Update client-side callers that expected 200 for every validate response — invalid tokens now return 401.
  7. Update client-side callers that expected 200 for idempotent revokes — repeat revocations now return 409.
  8. If you consume /jwt/keys/public, unwrap the JVM's {"jwk": "..."} wrapper — TIM-on-Rust returns the bare JWKS.
  9. If any Ruuter DSL calls /jwt/userinfo, /jwt/blacklist, or /jwt/custom-jwt-blacklist, no changes are required — those endpoints are still present. See Legacy compatibility.

For deployments coming from Buerokratt JVM 1.x (not 2.0), additionally:

  • Rename all endpoint calls per the table at the top of this page.
  • The UserInfo shape from the original /jwt/userinfo has been simplified — Estonian-specific fields (channel type, personal ID) are gone; extract them from the claims map instead.
  • IP allow-listing (security.allowlist.jwt) is not implemented; gate at the reverse proxy or rely on the admin token.