AUTH4D-384 user.unbanned when a timed ban runs out
This fragment extends AUTH4D-310 (repository file docs/api-spec/auth4d-310.md) and AUTH4D-362 (repository file docs/api-spec/auth4d-362.md). A timed ban
still stops applying the moment its expires_at passes, with no job involved. What is new is the
event: the API Worker’s lifecycle cron now publishes user.unbanned for each timed ban that ran out
on its own, so game backends that mirror ban state from webhooks or Flows can clear it. No endpoint
or event type is added.
Event
The event is the one a manual unban publishes, with the same envelope and strict data:
{
"event_id": "evt_Qm3Vb8Zr1Hs6Kt0Wx4Lp9Dc2Nf5Gj7Ya8Ue3Oi6Tk1B",
"version": 1,
"type": "user.unbanned",
"tenant_id": "ten_0123456789abcdef",
"application_id": null,
"user_id": "usr_0123456789abcdef",
"occurred_at": "2026-10-26T14:02:51.330Z",
"context": {},
"data": { "ban_id": "ban_0123456789abcdef0123" }
}
application_idisnullandcontextis empty, so only endpoints without an application filter receive it, as for every ban event.occurred_atis the ban’sexpires_at, not the time the cron noticed it.event_idis derived from the tenant, the type and the action keyban:{banId}:expired. A manual unban usesban:{banId}:unbanned, so the two never share an id.- The ban’s
reasonis never published.
When it is published
The lifecycle cron (*/10 * * * *, also the fallback task list for other cron expressions) runs a
ban-expiry sweep. It reads up to 100 bans per run, oldest expiry first, that:
- are not revoked (
revoked_at IS NULL), - are timed and have run out (
expires_at <= now), - have not had their expiry published (
user_bans.expiry_event_at IS NULL), and - still belong to an existing player.
For each one it writes, in one D1 batch, a user.ban_expired audit event and
UPDATE user_bans SET expiry_event_at = now WHERE tenant_id = ? AND ban_id = ? AND … under the same
condition, and publishes only if that update changed the row. Each ban therefore publishes at most
once, even when two cron runs overlap. Any remaining bans wait for the next run, so delivery can be
up to about 10 minutes after expires_at (longer only when more than 100 bans expire in one
window). The player can sign in again from expires_at without waiting for the event.
Nothing is published for a permanent ban, a ban lifted by hand before it ran out (that sends its
own user.unbanned with the unbanned action key), or a ban whose player was deleted. Bans that
had already run out before this change was deployed are announced once, on the first run.
Delivery is best effort, as for every other event: a queue failure is logged as
flows.publish_failed with only type and tenant_id, and the ban stays marked as published.
Audit
| Event | Target | Metadata |
|---|---|---|
user.ban_expired |
ban ban ID |
user_id, expires_at |
The audit event has no actor; the cron records it. The console labels it Ban expired.
Migration
0047_ban_expiry_events.sql adds the nullable user_bans.expiry_event_at column and a partial
index, user_bans_expiry_pending, over bans still waiting for their expiry event. It is additive.
On a database without migration 0041 or 0047 the sweep does nothing and does not fail the cron.
Source: docs/api-spec/auth4d-384.md