FRD-070: Secret Rotation Reminder Widget

Field	Value
Owner	David Holmes
Status	Draft
Last Updated	2026-05-26
Related	ADR-027 (Default Tech Stack)
Target Release	v2.0.0 (P2)
T-Shirt Size	S
Type	Widget

Document Summary

A compact widget displaying secrets approaching their rotation deadline. Shows secret name, store, days until due, and an “Initiate rotation” CTA. Complements the existing SecretsStatusPanel which shows sync status rather than rotation lifecycle.

Introduction

Overview

Secret rotation is a critical security practice. Teams need visibility into which secrets are approaching or past their rotation deadlines. The existing SecretsStatusPanel shows sync status (synced, failed, refreshing) but not rotation lifecycle. This widget fills that gap by surfacing rotation-due secrets with urgency indicators and an action to initiate rotation.

Goals

Display secrets approaching rotation deadline in a compact list.
Show secret name, secret store, days until due, and urgency level.
Provide an “Initiate rotation” CTA per secret.
Color-code urgency: overdue (red), due soon (yellow), healthy (green).
Ship Storybook stories covering urgency states.

Non-Goals

Secret rotation execution (consumer handles via callback).
Secret value display or management.
Rotation policy configuration.
Integration with specific secret managers (Vault, AWS Secrets Manager, etc.).

Scope

In Scope

Item	Description
`SecretRotationReminder` component	List of secrets with rotation status and CTA
Urgency indicators	Color-coded badges: overdue, due-soon, healthy
Rotation CTA	”Initiate rotation” button per secret; calls `onInitiateRotation`
Summary header	Count of overdue and due-soon secrets
Storybook stories	AllHealthy, DueSoon, Overdue, Mixed, Empty, Loading

Out of Scope

Item	Rationale
Rotation execution	Consumer triggers rotation via callback
Secret value display	Security concern; not shown in this widget
Policy management	Admin configuration; separate UI
Secret store integration	Consumer normalizes data from their secret manager

Users and Pain Points

User	Pain Point
SRE/security teams	No dashboard-level visibility into rotation deadlines
DevOps engineers	Secrets expire without warning, causing outages
Compliance officers	Cannot easily prove rotation policy adherence

Definitions

Term	Definition
Secret rotation	The practice of periodically replacing secret values (keys, tokens, passwords)
Rotation deadline	The date by which a secret must be rotated per policy
Days until due	The number of days remaining before the rotation deadline
Secret store	The system storing the secret (e.g., Vault, AWS Secrets Manager, K8s Secret)

Current State

secrets-status-panel.tsx shows secrets with their sync status (synced, failed, refreshing, unknown) and last-synced timestamps. It includes a SecretEntry type with expiresAt field but does not calculate or display days until rotation. No rotation-specific urgency indicators or rotation CTAs exist.

Proposed Solution

Create a SecretRotationReminder widget at src/components/widgets/sre-devops/secret-rotation-reminder.tsx that:

Accepts an array of RotationSecret objects with name, store, and rotation deadline.
Calculates days until due from the deadline date.
Color-codes each entry: overdue (past deadline), due-soon (within configurable threshold), healthy.
Renders an “Initiate rotation” button per entry that calls onInitiateRotation(secretName).
Shows a summary header with overdue and due-soon counts.

Requirements

The widget must calculate urgency from deadline dates at render time. The “due soon” threshold must be configurable. The widget must not store or display secret values.

Functional Requirements

ID	Requirement	Priority
FR-01	Render a list of secrets with name, store, and days until rotation deadline	Must
FR-02	Color-code entries: overdue (destructive), due-soon (warning), healthy (success)	Must
FR-03	Display a badge with urgency label (“Overdue”, “Due in X days”, “Healthy”)	Must
FR-04	Render “Initiate rotation” button per entry	Must
FR-05	Call `onInitiateRotation(secretName, secretStore)` when CTA is clicked	Must
FR-06	Show summary header with counts (e.g., “2 overdue, 3 due soon”)	Should
FR-07	Configurable “due soon” threshold via `dueSoonDays` prop (default 30)	Should
FR-08	Sort entries by urgency (overdue first, then due-soon, then healthy)	Should
FR-09	Show empty state when no secrets are provided	Must
FR-10	Support a `loading` prop with skeleton entries	Should

Non-Functional Requirements

ID	Requirement
NFR-01	Bundle size under 2 KB gzipped
NFR-02	Full light/dark theme support
NFR-03	Renders 50 secrets without perceptible lag

API / Interface Requirements

interface RotationSecret {
  name: string;
  secretStore: string;
  rotationDeadline: string;    // ISO 8601 date
  lastRotatedAt?: string;      // ISO 8601 date
  owner?: string;
}

interface SecretRotationReminderProps {
  secrets: RotationSecret[];
  dueSoonDays?: number;         // default 30
  loading?: boolean;
  emptyMessage?: string;        // default "All secrets are within rotation policy"
  onInitiateRotation?: (secretName: string, secretStore: string) => void;
  className?: string;
}

Accessibility Requirements

ID	Requirement
A11Y-01	Secret list uses `<ul>` with descriptive `aria-label`
A11Y-02	Urgency badges have accessible text (not just color)
A11Y-03	”Initiate rotation” buttons have `aria-label` including secret name
A11Y-04	Summary header is announced via `role="status"`
A11Y-05	Overdue entries are conveyed to screen readers with urgency

Content and Documentation Requirements

Storybook doc page explaining rotation concepts and relationship to SecretsStatusPanel.
Stories: AllHealthy, DueSoon, Overdue, Mixed, Empty, Loading.
JSDoc on all exported types.

Dependencies

Dependency	Type	Notes
`Badge`	Internal	Urgency indicators
`Button`	Internal	Rotation CTA
`SecretEntry` type reference	Internal	Alignment with `secrets-status-panel.tsx` naming

Risks and Tradeoffs

Risk	Impact	Mitigation
Timezone differences in deadline calculation	Wrong urgency classification	Use UTC for all date calculations; document timezone expectations
Stale data if not refreshed	Users see outdated deadlines	Document that consumer should refresh data regularly
Rotation CTA without confirmation	Accidental rotation triggers	Recommend consumer adds a confirmation dialog before executing

Open Questions

Should the widget support grouping by secret store?
Do we need a “Snooze” option per secret to temporarily dismiss a reminder?
Should there be a link to the SecretsStatusPanel for sync status context?

Acceptance Criteria

Secrets render with name, store, and days-until-due.
Urgency badges display correct colors and labels.
“Initiate rotation” button calls onInitiateRotation with correct arguments.
Summary header shows overdue and due-soon counts.
Entries are sorted by urgency.
Empty and loading states render correctly.
All Storybook stories render without errors.
Passes axe accessibility audit with zero violations.
Unit tests cover urgency calculation, sorting, CTA callback, and empty state.

LLM Handoff Instructions

When implementing this FRD:

Create src/components/widgets/sre-devops/secret-rotation-reminder.tsx.
Calculate days-until-due using Date arithmetic in UTC.
Urgency thresholds: overdue = days < 0, due-soon = days <= dueSoonDays, healthy = days > dueSoonDays.
Reference secrets-status-panel.tsx for styling conventions and badge patterns.
Create src/components/widgets/sre-devops/secret-rotation-reminder.stories.tsx.
Create src/components/widgets/sre-devops/secret-rotation-reminder.test.tsx.
Sort: overdue first (most overdue at top), then due-soon (fewest days first), then healthy.

Decision Log

Date	Decision	Rationale
2026-05-26	Separate from SecretsStatusPanel	Different concerns: sync status vs. rotation lifecycle
2026-05-26	Deadline-based calculation, not policy-based	Simpler API; consumer pre-calculates deadline from their rotation policy

Document History

Date	Version	Author	Changes
2026-05-26	0.1	David Holmes	Initial draft