feat: sweep expired data with an in-process retention worker

[Ptilopsi4]

What this adds

Expired rows in oauth_authorizations, oauth_access_tokens, oauth_refresh_tokens and audit_logs were never deleted — the cleanup design existed only as pg_cron SQL in docs/psql-db-design.md, and no migration ever created it. This adds the cleanup as an in-process Go worker.

• internal/worker/retention.go — ticker worker, one round per hour by default
• internal/repository/retention.go — four batched deletes plus advisory-lock acquire/release
• migrations/000006_* — one index, no data changes
• six RETENTION_* variables with startup validation

Why not pg_cron

The production database has no pg_cron extension, and installing one requires editing shared_preload_libraries and restarting the database.

The stronger reason is test coverage: the integration suite runs postgres:16-alpine, which cannot load pg_cron at all. A pg_cron implementation would ship with its retention rules untested. Scheduling in Go also follows an existing pattern rather than introducing a second one — sessionworker.TokenBlacklist has been cleaning token_blacklist_outbox from an hourly ticker since V004.

The cost: cleanup only happens while the API process is alive. When the service is fully stopped nothing is written either, so nothing is lost.

Two delete conditions that are narrower than they look

Both are cases where the straightforward DELETE WHERE dead breaks a live auth flow. Each has a test pinning it.

Refresh tokens keep every family's sequence-0 row. FindFamilyOriginCreatedAt reads that row to date an ID Token's auth_time, and the row carries revoked_at from the first rotation onward — so revoked_at IS NOT NULL AND expires_at < cutoff matches it while the family is still in use. A family that keeps rotating outlives the origin row's own expires_at; deleting it sends oauth.Service.refresh down its "metadata inconsistent" branch, which revokes the whole family and returns 500. That is a forced logout for an active user. TestRetentionKeepsAuthTimeReadableAcrossRotations rotates three times, sweeps between each, and asserts the origin row stays readable.

Access-token metadata is swept 24h after expiry, not 1h. The auth middleware answers an unknown JTI with the same 401 it uses for a revoked token, so metadata deleted while its JWT is still inside exp presents a merely expired token as revoked: the client receives CodeAccessTokenInvalid instead of CodeAccessTokenExpired and reads a forced logout where it should have refreshed. There is no clock-skew leeway in the JWT verifier to rely on. Validation also refuses any value below JWT_ACCESS_TOKEN_EXPIRY.

Multi-instance coordination

Each round takes pg_try_advisory_lock and skips when another instance holds it. try rather than a blocking lock is deliberate: a missed round is harmless because the next one covers the same rows, so returning immediately beats queueing behind the winner. Every delete is DELETE WHERE already-dead and therefore idempotent — the lock saves duplicate scans, it is not what makes the sweep correct.

The lock pins one *sql.Conn for its lifetime. It is session-scoped while a pooled *gorm.DB hands out an arbitrary connection per statement, so releasing through the pool could run pg_advisory_unlock on a connection that never held the lock — that returns false instead of erroring, and the real holder would stay locked until its connection happened to be recycled, blocking every later sweep on every instance.

Pool and backlog safety

The worker shares its connection pool with live request traffic, so each delete is restricted to a primary-key subquery with LIMIT, and one round is capped at 20 batches per table. A table neglected for months drains across several rounds instead of monopolizing the pool in one. Hitting the cap logs a warning, so a permanent backlog does not read as a clean sweep.

Failures are logged and abandoned until the next tick rather than returned from Run: retention falling behind degrades storage, while a returned error would take the whole API process down with it.

The index

idx_oauth_authorizations_expires_at is partial on WHERE is_used = FALSE, and the sweep deletes expired codes regardless of redemption — a redeemed code is exactly the row that index excludes, and it is the common case. V006 adds a full expires_at index so the hourly pass is not a sequential scan. The other three tables already have usable indexes; notably idx_oauth_refresh_tokens_expires_at is partial on WHERE revoked_at IS NOT NULL, which matches the refresh condition exactly.

Configuration

Windows are measured back from now, so a row must have been dead for the whole window; the margin absorbs clock skew between the API and PostgreSQL.

Variable	Default	Note
RETENTION_INTERVAL	1h	at least 1m
RETENTION_BATCH_SIZE	1000	rows per statement
RETENTION_AUTHORIZATION_AGE	1h
RETENTION_ACCESS_TOKEN_AGE	24h	may not be below JWT_ACCESS_TOKEN_EXPIRY
RETENTION_REFRESH_TOKEN_AGE	24h
RETENTION_AUDIT_LOG_AGE	2160h (90d)	30-day floor

Audit retention keeps the 90 days PRD §9 targets as its default, but the bound is a 30-day sanity floor rather than a hard 90-day minimum: audit history here is operational, not compliance-bound, so trimming below 90 is a legitimate deployment choice. The floor only rejects values so short an incident investigation would find the entries already deleted.

token_blacklist_outbox is deliberately absent from this worker — sessionworker.TokenBlacklist already owns it, and a second cleaner would just contend on the same table. The pg_cron design listed it because that design predates the outbox worker.

Tests

• 9 worker unit tests: per-table cutoffs, lock-skip, lock released after a delete failure, sweep continues past a failing table, drain-until-short, pass cap, Run validation, sweep-before-first-tick
• 7 repository integration tests against real PostgreSQL, including the two guards above and batch-size enforcement
• TestRetentionTryLockIsExclusive — a second holder appears only after Unlock
• TestUpCreatesLatestSchema asserts the V006 index exists
• 3 config tests covering both floors and every default

golangci-lint run ./... reports 0 issues. Full suite passes with -race -shuffle=on.

Deployment note

V006 creates an index and touches no data. Production migrations still go through docs/runbooks/database-baseline.md and the explicit migrate up --confirm-production form; this PR does not run it anywhere.