The platform already had two revocation surfaces : Redis-backed
TokenBlacklist (token-hash keyed, T0174) and TokenVersion bump on the
user row (revokes ALL of a user's tokens). Both work but leave gaps :
* Redis restart wipes the blacklist — a token revoked seconds before
a Redis crash becomes valid again until natural expiry.
* No way to revoke "session #3 of user X" from an admin UI : the
blacklist is keyed by token hash, the admin doesn't have it.
This commit adds a durable, jti-keyed revocation ledger that closes
both gaps. The jti claim is already emitted on every access + refresh
token (services/jwt_service.go:155, RegisteredClaims.ID = uuid).
Schema (migrations/993_jwt_revocations.sql)
* jwt_revocations(jti PK, user_id, expires_at, revoked_at, reason,
revoked_by). PRIMARY KEY on jti = idempotent re-revoke. Indexes
on user_id (admin "list my revocations") and expires_at (cleanup
cron).
Service (internal/services/jwt_revocation_service.go)
* NewJWTRevocationService(db, redisClient, logger) — Redis is
optional cache.
* Revoke(ctx, jti, userID, expiresAt, reason, revokedBy)
- Redis SET (best-effort cache, TTL = remaining lifetime)
- DB INSERT (durable record, idempotent via PK)
* IsRevoked(ctx, jti)
- Redis GET fast path
- DB fallback on cache miss / Redis blip (fail-open : DB error
is logged + treated as not-revoked, because the existing
token-hash blacklist still protects).
- Backfills Redis on DB hit so the next request hits cache.
* ListByUser(ctx, userID, limit) — for the admin/user "active
sessions" UI.
* PurgeExpired(ctx, safetyMargin) — daily cron handle.
Middleware (internal/middleware/auth.go)
* JTIRevocationChecker interface + SetJTIRevocationChecker setter.
* After ValidateToken, in addition to the token-hash blacklist
check, IsRevoked(claims.ID) is called. Either match = reject.
* Nil-safe via reflect.ValueOf.IsNil() pattern matching the
existing tokenBlacklist nil guard.
Wiring
* config/services_init.go : always instantiate the service (DB
required, Redis passed as nil if unavailable).
* config/middlewares_init.go : SetJTIRevocationChecker on the auth
middleware after construction.
* config/config.go : new Config.JWTRevocationService field.
Logout flow (handlers/auth.go)
* In addition to TokenBlacklist.Add(token, ttl), now calls
JWTRevocationService.Revoke(jti, ...). Best-effort : the blacklist
already protects the immediate-rejection path ; this just adds
durability + a stable handle for admin tools.
Tests pass : go test ./internal/{handlers,services,middleware,core/auth}
-short -count=1.
What v1.0.10 leaves to v2.1
* /api/v1/auth/sessions/revoke/:jti — admin-targeted endpoint.
Service is ready ; the admin UI to drive it follows.
* Daily PurgeExpired cron — call from a Forgejo workflow once
per day with safetyMargin = 1h to keep table size bounded.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026ffcb06