Secret Expiration Design
Summary
Secrets are often API keys or auth tokens with an expiration date. This feature lets users record an optional expiration on a secret. Axiom then:
- shows expiry status in the UI (Secrets page column, app-wide banner, sidebar badge);
- emits
secret.expiringandsecret.expiredstream events that workflows and pipelines can react to; - blocks runtime resolution of expired secrets with a clear, actionable error.
Goals
- Optional expiration date per secret, with a global warning window and an optional per-secret override.
- Each expiry event fires exactly once per expiry date.
- Expired secrets fail fast with an error that names the secret and the fix.
- Rotating a secret cannot leave it stuck in an expired state.
Non-Goals
- A general notification center (bell, persistence, read/unread).
- Automatic expiry detection (e.g. JWT
expclaims, provider headers). - A dashboard widget for expiring secrets.
- Multiple escalating reminders (e.g. 30/7/1 days).
Data Model
New Flyway migration app/src/main/resources/db/migration/V11__secret_expiration.sql adds nullable columns to
secret:
| Column | Type | Purpose |
|---|---|---|
expires_on |
TIMESTAMP WITH TIME ZONE | When the secret expires (null = never) |
warn_days_before |
INTEGER | Per-secret warning window override |
expiry_warning_sent_on |
TIMESTAMP WITH TIME ZONE | When secret.expiring was emitted (dedupe) |
expired_event_sent_on |
TIMESTAMP WITH TIME ZONE | When secret.expired was emitted (dedupe) |
SecretEntity gets matching fields. Both *_sent_on columns are reset to null whenever the secret value or
expires_on changes.
Configuration
| Property | Default | Meaning |
|---|---|---|
axiom.secrets.expiry-warning-days |
7 |
Warning window in days when warnDaysBefore is null |
axiom.secrets.expiry-check-interval |
15m |
How often the expiry checker runs |
axiom.secrets.expiry-check-interval is off in the test profile.
REST API (contract-first)
All changes start in common/api/src/main/resources/openapi.json.
Secret(response) adds:expiresOn(string, date-time, nullable)warnDaysBefore(integer, nullable)expiryStatus(enumNONE,VALID,EXPIRING,EXPIRED), computed server-sideNewSecret(request) adds optionalexpiresOnandwarnDaysBefore.
Expiry status rules, using the effective warning window w (per-secret override or global default):
NONE:expiresOnis nullEXPIRED:now >= expiresOnEXPIRING:now >= expiresOn - wVALID: otherwise
Validation (createSecret and updateSecret return 400):
expiresOnis in the past.warnDaysBeforeis negative.- On update: the stored secret is expired and the request neither supplies a future
expiresOnnor clears it (explicit null). This applies to every update, including value rotation.
PUT /secrets/{secretId} is a full replace that always carries value, so every update is a rotation.
Omitting expiresOn clears it and past dates are rejected, which satisfies rule 3 without a separate check.
Every update resets the *_sent_on columns.
expiresOn must be formatted yyyy-MM-ddTHH:mm:ssZ (UTC, no fractional seconds), the project-wide
generated-bean convention. Validation 400s return a JSON body {"message": "..."}.
SystemConfig.secretExpiryWarningDays exposes the global warning window to the UI.
Secrets are not part of configuration-pack import/export (only secretName references are), so nothing
changes there.
Expiry Checker and Events
SystemEventPublisher
Extract the stream-event publishing logic from SdkCallService.fireEvent() into a reusable
SystemEventPublisher bean. It builds and persists a StreamEventEntity and fires StreamEventPersisted.
SdkCallService is refactored to use it, with no behaviour change.
Confirm during implementation that free-form event types are accepted on this path (as they are for the SDK).
If EventType or validation restricts types, add secret.expiring and secret.expired.
SecretExpiryChecker
A new @Scheduled bean in app/, running every axiom.secrets.expiry-check-interval after a short startup
delay. It uses an injectable java.time.Clock.
For each secret with a non-null expiresOn:
- If
now >= expiresOn - wandexpiry_warning_sent_onis null, emitsecret.expiringand set the flag. Skip this if the secret is already expired and no warning was ever sent; onlysecret.expiredis emitted. - If
now >= expiresOnandexpired_event_sent_onis null, emitsecret.expiredand set the flag.
Each secret is processed in its own transaction (persist event + set flag together). A failure on one secret is logged and does not stop the batch.
Emitted events
- Stream event via
SystemEventPublisher: eventSourceId = "system",source = "axiom",actor = {"login":"system"}- type
secret.expiringorsecret.expired - payload
{ "secretId", "secretName", "expiresOn", "daysRemaining" }— never the secret value - SSE event
SseEvent.secretExpiry(secretId, status)with typesecret-expiry, used by the UI to refresh.
Create, update, and delete of a secret also fire secret-expiry so the UI stays current.
Runtime Blocking
- New
ExpiredSecretExceptionincore/src/main/java/io/apitomy/axiom/core/services/. Message:Secret '<name>' expired on <date>. Update it on the Secrets page. ExpiredSecretExceptionextendsMissingSecretException(no new common parent), so every existing catch site handles it unchanged.EnvironmentResolverthrowsExpiredSecretExceptionwhen it resolves a secret withnow >= expiresOn, at the same pointMissingSecretExceptionis thrown today.- Audit every
catch (MissingSecretException)site and make sure expired secrets are handled the same way (MCP server start, tool calls, workflow environments).
Validation
ValidationContext*: a config item referencing an expired secret produces a validation error. A reference to
an EXPIRING secret produces a warning.
UI
- Secrets page (
ui/src/pages/SecretsPage.tsx): - New sortable "Expires" column: date plus status label ("Expires in 5d" in warning colour, "Expired" in danger colour).
- Create/edit modal: optional "Expires on" date-time picker and optional "Warn days before" field (placeholder shows the global default).
- Editing an expired secret requires a new future date or clearing the date before saving.
- App-wide banner, modelled on
ConfigurationWarning: "N secrets are expiring soon / M have expired. [View secrets]". Dismissible; reappears when the counts change. - Sidebar badge on the Secrets nav item in
AppSidebar.tsx, showing the count of expiring + expired secrets. - Live updates: listen for
secret-expiryviasseClient.subscribeand refetch the secrets list.
The global warning window must be available to the UI (for the placeholder). Expose it through the existing system/config endpoint if one exists; otherwise add it to the OpenAPI spec.
Testing
All backend tests use JUnit 5; time-dependent methods take an explicit now.
- Checker (
@QuarkusTest): no expiry; entering the warning window; per-secret override; already expired at startup; each event fires only once; flags reset on rotation or date change. - REST: 400 for past
expiresOn, negativewarnDaysBefore, and updating an expired secret without a new date;expiryStatuscomputed correctly. - EnvironmentResolver: expired secrets throw
ExpiredSecretException; valid and non-expiring secrets resolve. - Validation: error for expired references, warning for expiring references.
- SdkCallService: existing tests still pass after the
SystemEventPublisherrefactor. - UI: type-check and build.
- Live check: an isolated instance, e.g.
AXIOM_HOME=/tmp/axiom-test/home ./dev.sh --skip-ui --portOffset=500 --dataDir=/tmp/axiom-test/data, never the production instance on 9191.
Implementation Notes
- Migration
V12__drop_stream_event_source_fk(Java Flyway migration) drops thestream_event.event_source_id -> event_source(id)foreign key from the V1 baseline. Internal stream events (eventSourceIdsystemfrom the expiry checker, andsdkfrom theaxiom_fire_eventSDK call) have noevent_sourcerow, so every such insert failed at commit in Flyway-built databases. This also fixes a pre-existing bug:axiom_fire_eventcould not persist events in production. Tests did not catch it because the test profile builds the schema with Hibernate, which does not generate that foreign key. - Side effect: deleting an event source that has stream events now succeeds; its events remain until retention cleanup (previously the foreign key blocked the delete).
SystemEventPublisherwas extracted fromSdkCallService.fireEvent()and is used by both.- The Secrets table uses a fixed sort (expired, expiring, by date, no expiry) rather than clickable column sorting.
- Event-source pollers (GitHub, Jira) read their secret directly, not through
EnvironmentResolver, so they are not blocked by expiry; an expired poller token fails at the provider instead.