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_id is null and context is empty, so only endpoints without an application filter receive it, as for every ban event.
  • occurred_at is the ban’s expires_at, not the time the cron noticed it.
  • event_id is derived from the tenant, the type and the action key ban:{banId}:expired. A manual unban uses ban:{banId}:unbanned, so the two never share an id.
  • The ban’s reason is 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