Skip to content

Management API: TLS certificate hot-reload #16

Description

@ShortArrow

Context

ADR 0039
ships opt-in TLS / mTLS for the Management HTTP API in v0.1.0,
but the listener does not pick up rotated certificates
without a restart. The cert PFX / PEM path is read once at
`ivicli api start` time.

CHANGELOG.md → Known limitations:

Cert hot-reload deferred (ADR 0039 §Out-of-scope) — long-running
API servers must restart to pick up rotated certs.

Why this matters

Operators who deploy ivi-cli as a long-running daemon (e.g. via
systemd or a Windows Service) and rotate certs via Let's Encrypt
/ ACME / corporate PKI cron jobs have to schedule a restart of
the daemon every rotation cycle, which is intrusive.

Approach sketch

  • Wire a FileSystemWatcher (or polling fallback) on the cert
    paths declared in [api.tls].
  • On change: validate the new cert, swap the listener's cert
    reference under a lock, log a ServerLifecycle audit event
    (kind=cert-reloaded).
  • Reject the rotation if the new cert fails validation (chain,
    expiry, key match); keep the old cert active and emit a
    warning.

Acceptance

  • E2E test: rotate the cert file mid-flight, verify next
    HTTPS request uses the new cert without restarting the
    process.
  • Update ADR 0039 in place: move "cert hot-reload" out of
    §Out-of-scope into §Decision.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:apiManagement HTTP / WebSocket APIarea:securityTLS, ACL, PAT, auditenhancementNew feature or requestpriority:mediumImproves UX/security but not blocking

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions