Ga naar inhoud
monsys.ai

Ed25519 signing-key rotatie

Emergency-action tokens (playbook runs, isolation commands, agent self-update wrappers) zijn Ed25519-gesigned door de hub. De agent verifieert tegen een gepinde public key. Voor rotatie zonder downtime:

Het probleem

Naïeve rotatie = nieuwe key + alle agents direct verifiëren tegen nieuwe key → in-flight tokens met de oude key worden plots ongeldig. Bij compromise wil je dat WEL (instant revocation), maar bij geplande rotatie WIL je grace.

Hoe het werkt

De hub houdt een set van hub_signing_keys per tenant. Elke key heeft is_active=true, optioneel expires_at. Bij rotatie:

  1. Nieuwe Ed25519 keypair genereert
  2. Public part INSERT in hub_signing_keys met is_active=true, expires_at=NULL
  3. Bestaande active keys krijgen expires_at = NOW() + grace_days × INTERVAL '1 day'
  4. Private key wordt ÉÉN keer in de response getoond, daarna nooit meer

De agent fetched periodiek GET /api/v1/agents/:id/signing-keys/active (alleen non-expired actives). Tijdens grace heeft de agent dus BEIDE keys in zijn trust set; tokens gesigned met óf de oude óf de nieuwe key valideren.

Na expires_at van de oude key valt deze automatisch uit de trust set.

Hoe je het in de UI doet

/settings → Signing keys tab:

  1. Geef een reden in (“annual rotation”, “suspected compromise”, …)
  2. Kies grace days (default 7, max 90)
  3. Klik Rotate now
  4. Copy de getoonde private_hex direct — wordt nergens opgeslagen, alleen getoond
  5. Plak die in je hub deployment config (env var MONSYS_EMERGENCY_PRIVATE_KEY_HEX of secrets manager)
  6. Restart hub. Vanaf dat moment signt de hub met de nieuwe key; oude tokens blijven grace_days valideren.

Tabel onder de rotate-button toont alle keys: ACTIVE (geen expiry), EXPIRES <date> (in grace), of RETIRED.

Compromise scenario

Bij vermoeden van compromise:

  1. Rotate met grace_days=0 (verkort grace tot ~nu)
  2. Plak nieuwe private key in deploy
  3. Restart hub
  4. Alle oude tokens vallen direct ongeldig

Dit triggert wel: in-flight playbook-runs die nog niet door de agent zijn ontvangen kunnen falen. Daarom alleen bij ÉCHTE compromise — niet voor planned maintenance.

API

GET  /api/v1/signing-keys                       (admin only)
POST /api/v1/signing-keys/rotate                (admin, rate-limit 5/u)
GET  /api/v1/agents/:id/signing-keys/active     (agent-auth)

Body POST /rotate:

{
  "reason": "annual rotation 2026",
  "grace_days": 7
}

Response (ONE TIME):

{
  "id": "uuid",
  "public_hex":  "abc…64",
  "private_hex": "def…128",
  "expires_grace_days": 7,
  "expires_at": "2026-05-17T...Z",
  "warning": "Save the private key now — it is shown only this once."
}

Audit

Elke rotation logt naar audit_log met resource_type='signing_key', resource_id=<new_key_id>, IP, user, reason. Reviewable via /audit?resource_type=signing_key.