5.5 KeyRotationReminder

1. Bot Identity

Operational profile

2. Purpose

Nag the user to rotate signing keys on a schedule; prevent key reuse across environments.

3. Why This Bot Matters

• Signing key never rotated

  A long-lived key that is compromised silently provides unlimited signing authority over time.

• Same key used across prod and staging

  A staging environment compromise exposes production signing capability.

• No block on overdue rotation

  Users ignore rotation reminders indefinitely, leaving stale keys in production.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "rotate_every_days": 30 }

if (key_age_d > p.rotate_every_days + p.block_on_overdue_h/24) return reject('KEY_ROTATION_OVERDUE');

{ "require_unique_per_env": true }

if (p.require_unique_per_env && isKeySharedAcrossEnvs(key)) return reject('KEY_REUSE_ACROSS_ENV');

8. Default Configuration

{
  "bot_id": "sec.key_rotation_reminder",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "rotate_every_days": 30,
    "block_on_overdue_h": 24,
    "require_unique_per_env": true,
    "publish_to_user": true
  }
}

9. Implementation Flow

1. Receive signing call.
2. Check KillSwitch; if active, REJECT(KILL_SWITCH_ACTIVE).
3. FETCH key registration timestamp from ClobAuth.
4. Compute key_age_d = (now - registered_at) / 86400.
5. If key_age_d in warning range: emit WARN and continue.
6. If key_age_d > rotate_every_days + block_on_overdue_h/24: REJECT(KEY_ROTATION_OVERDUE).
7. If require_unique_per_env: check fingerprint across env registry; if shared, REJECT(KEY_REUSE_ACROSS_ENV).
8. Emit RiskVote(APPROVE) if all checks pass.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

// KeyRotationReminder
FUNCTION checkKeyRotation(signingKey, envRegistry):
  IF FETCH(internal.killswitch).active:
    EMIT RiskVote(DENY, KILL_SWITCH_ACTIVE); RETURN
  keyInfo = FETCH(clob_auth.key_info(signingKey.fingerprint))
  IF keyInfo == null:
    EMIT RiskVote(DENY, STALE_DATA); RETURN
  key_age_d = (NOW() - keyInfo.registered_at) / 86400
  grace_d = params.block_on_overdue_h / 24
  // Overdue block
  IF key_age_d > params.rotate_every_days + grace_d:
    EMIT RiskVote(DENY, KEY_ROTATION_OVERDUE); RETURN
  // Warning band
  IF key_age_d > params.rotate_every_days * 0.9:
    EMIT warn(KEY_ROTATION_DUE_SOON)
  // Cross-env check
  IF params.require_unique_per_env:
    IF envRegistry.count(signingKey.fingerprint) > 1:
      EMIT RiskVote(DENY, KEY_REUSE_ACROSS_ENV); RETURN
  EMIT RiskVote(APPROVE)
  LOG(governance.audit, {fingerprint, key_age_d})

SDK calls used

• clob_auth.get_key_info(fingerprint)
• internal.killswitch.status()

Complexity: O(e) where e = number of environments (small constant)

11. Wire Examples

Input — what arrives on the wire

Signing call with healthy key — internal

{
  "intent_id": "int_5e6f7a8b9c0d1e2f",
  "key_fingerprint": "ab12cd34",
  "env": "prod",
  "timestamp_ms": 1746768672000
}

Output — what the bot emits

RiskVote — APPROVE

{
  "vote_id": "sec.key_rotation_reminder.20260509T160000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "key_age_d": 12,
    "days_until_block": 19
  },
  "checked_at": "2026-05-09T16:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "vote_id": "sec.key_rotation_reminder.20260509T160000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "key_fingerprint": "ab12cd34",
    "key_age_d": 12,
    "rotate_every_days": 30,
    "days_until_required_rotation": 18
  },
  "checked_at": "2026-05-09T16:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "sec.key_rotation_reminder",
  "decision": "APPROVE",
  "inputs_used": [
    "clob_auth.key_registered_at",
    "config.rotate_every_days"
  ],
  "checked_at": "2026-05-09T16:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Re-read from ClobAuth on restart; fail-closed if unavailable after grace period.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Backdating key registration timestamp to appear younger than actual age
• Using same key fingerprint across environments to avoid key generation overhead

Mitigations

• Registration timestamp read from authoritative ClobAuth API, not from client
• Cross-environment fingerprint check is server-side

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

KeyRotationOverdue is a P1 security event; trading is blocked until rotation completes.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/keyrotationreminder → green if All active keys within rotate_every_days; no overdue alerts.; red if Any key older than rotate_every_days + block_on_overdue_h/24.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%