SecretRotator

Developer

Original Idea

Secrets Rotation Scheduler A background service that tracks rotation calendars and reminds owners before expiry.

Product Requirements Document: SecretRotator (v1.0)

1. Executive Summary

SecretRotator is a centralized background service designed to eliminate service outages and security vulnerabilities caused by expired credentials. Unlike traditional secret managers that store sensitive values, SecretRotator functions as a metadata-only lifecycle orchestrator. It tracks rotation calendars across diverse environments (API keys, SSL certificates, DB passwords), sends multi-channel alerts to owners, and manages escalation paths to ensure no secret is forgotten. By automating the "remind-and-verify" loop, organizations move from manual, error-prone spreadsheets to a high-accountability, audit-ready compliance posture.

2. Problem Statement

Modern organizations manage thousands of credentials across multi-cloud environments.

  1. Unexpected Outages: Critical services often crash because an SSL certificate or an API key expired without warning.
  2. Security Risks: Stale credentials that aren't rotated provide a larger attack surface for lateral movement.
  3. Lack of Accountability: Spreadsheets lack automated reminders, audit logs, and clear ownership, leading to "tragedy of the commons" where no one knows who is responsible for a specific key.
  4. Compliance Failures: SOC2 and ISO27001 require evidence of regular rotation, which is difficult to provide without a centralized tracking system.

3. Goals & Success Metrics

  • Zero Expired-Secret Outages: Achieve 100% notification coverage for all registered secrets.
  • Reduced MTTA (Mean Time to Acknowledge): Decrease the time between an expiry alert and an owner acknowledging the rotation task to < 4 hours.
  • Audit Readiness: Reduce the time required to generate a secret-rotation compliance report from days to seconds.
  • User Adoption: Onboard 5+ core engineering teams within the first quarter.

4. User Personas

| Persona | Role | Primary Goal | | :--- | :--- | :--- | | DevOps/SRE | Infrastructure Owner | Ensure system uptime by tracking SSL and DB credential lifecycles. | | Security Officer | Compliance Manager | Verify that the organization follows rotation policies for SOC2/ISO27001. | | Backend Developer | Secret Owner | Receive timely alerts for their service's API keys and rotate them without friction. |

5. User Stories

  • As a DevOps Engineer, I want to register an SSL certificate's expiry date so that I get alerted 14, 7, and 1 day before it expires.
  • As a Security Officer, I want to see an audit log of every time a secret metadata was changed to ensure no unauthorized policy modifications occurred.
  • As a Developer, I want to receive rotation reminders via Slack so that I don't have to monitor my email for system alerts.
  • As a Manager, I want an alert to escalate to me if a P1 secret is not marked as "Rotated" within 24 hours of its expiry.

6. Functional Requirements

6.1 Secret Metadata Repository

  • Metadata Storage: Store name, provider (AWS, Vault, Stripe, etc.), purpose, and expiry date.
  • Strict Security: Explicitly forbid the storage of actual secret values or plain-text credentials.
  • Search/Filter: Users must be able to filter secrets by owner, provider, and "days until expiry."

6.2 Rotation Scheduling & Logic

  • Configurable Intervals: Support rotation intervals in days, months, and years.
  • Auto-Calculation: Automatically calculate the nextExpiryDate once a secret is marked as "Rotated."

6.3 Multi-Channel Notifications & Escalation

  • Integrations: Slack, Email (SendGrid), and PagerDuty.
  • Escalation Paths: If the Primary Owner does not acknowledge a notification within a set timeframe, the system escalates to the Secondary Owner or Team Lead.
  • Acknowledge via Link: Notifications must contain a secure, unique link to acknowledge or mark as rotated.

6.4 Dashboard & Reporting

  • Overview: High-level view of "Healthy," "Expiring Soon," and "Overdue" secrets.
  • Audit Logs: Immutable record of who changed what metadata and when.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

  • Frontend:
    • Next.js 16.1.3: Utilizing Turbopack for builds and the React Compiler for auto-memoization.
    • Tailwind CSS v4.0: CSS-first configuration using @theme blocks.
    • Shadcn/UI v2: Registry-based components using the "Maia" (rounded) style.
  • Backend:
    • Go (Golang) 1.24+: Using Gin Framework within a Clean/Hexagonal Architecture.
    • Database: PostgreSQL 17+ with AES-256-GCM field-level encryption for metadata strings.
  • Task Scheduling:
    • River: Postgres-backed transactional job queue for Go.
  • Authentication:
    • OIDC: Integrated via Clerk or Auth0.

7.2 Architecture Patterns

  • Clean Architecture: Decouple Gin handlers from business logic (use-cases) and data access (repositories).
  • Envelope Encryption: Use a Master Key from AWS KMS to wrap/unwrap Data Encryption Keys (DEKs) used by the GORM serializer.
  • Transactional Enqueueing: Notifications must be enqueued within the same DB transaction as the secret status update.

8. Data Model

SecretMetadata

| Field | Type | Description | | :--- | :--- | :--- | | id | UUID | Primary Key | | name | String | Encrypted name of the secret | | provider_type | Enum | e.g., AWS_SM, VAULT, MANUAL | | expiry_date | Timestamp | Next expiration date | | interval_days | Integer | Frequency of rotation | | owner_id | String | ID of the primary owner |

NotificationPolicy

| Field | Type | Description | | :--- | :--- | :--- | | id | UUID | Primary Key | | secret_id | UUID | Foreign Key | | lead_time_days | Integer | e.g., 7 days before | | channel | Enum | SLACK, EMAIL, PAGERDUTY | | recipient | String | Webhook URL or Email address |

9. API Specification (v1)

POST /api/v1/secrets

Registers a new secret metadata object. Request Body:

{
  "name": "Production Stripe API Key",
  "provider": "Stripe",
  "expiryDate": "2026-12-01T00:00:00Z",
  "intervalDays": 90,
  "ownerId": "user_29384"
}

PATCH /api/v1/secrets/:id/rotate

Marks a secret as rotated and updates the next expiry. Response: 200 OK with updated nextExpiryDate.

10. UI/UX Requirements

  • Performance: Use Partial Prerendering (PPR) for the dashboard to show the sidebar/header instantly while secret lists stream in.
  • Accessibility: WCAG 2.1 AA compliance; full keyboard navigation for the Secret Registration form.
  • Interactive Notifications: Slack blocks with "Acknowledge" and "Mark as Rotated" buttons.

11. Non-Functional Requirements

  • Security: Field-level AES-256-GCM encryption for any data identifying infrastructure (names, provider IDs).
  • Availability: 99.9% uptime for the background worker (River) to ensure notifications are never missed.
  • Compliance: Logs must be stored in a WORM (Write Once, Read Many) format for SOC2.

12. Out of Scope

  • Secret Storage: We are not a Vault; we do not store the "value" (e.g., sk_test_...).
  • Auto-Rotation Code Generation: We do not write the logic to change the password in the target system (v1).
  • Identity Provisioning: We do not manage users; we rely on OIDC.

13. Risks & Mitigations

| Risk | Mitigation | | :--- | :--- | | Notification provider down (e.g., Slack) | Implement "Intelligent Fallback" to Email if Slack API returns 5xx. | | Inaccurate Expiry Input | Implement "Expiry Verification" where the system probes the provider API (if possible) to check actual expiry. | | Database Corruption | Daily encrypted WAL-G backups to AWS S3 with cross-region replication. |

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize Next.js 16.1.3 project with Turbopack and React Compiler enabled
  • [ ] Set up Tailwind CSS v4.0 with @theme configuration
  • [ ] Initialize Go 1.24 project with Clean Architecture folder structure (/internal, /cmd, /pkg)
  • [ ] Configure PostgreSQL with GORM and go.pitz.tech/gorm/encryption for AES-GCM

Phase 2: Core Secret Repository

  • [ ] Create SecretMetadata database schema and migration scripts
  • [ ] Implement POST /api/v1/secrets with field-level encryption
  • [ ] Build "Add Secret" form using Shadcn/UI v2 components and react-hook-form
  • [ ] Implement OIDC authentication via Clerk middleware in both Next.js and Go

Phase 3: Scheduler & Notifications

  • [ ] Configure River worker pool in Go for background task processing
  • [ ] Implement "Check Expiry" cron job (hourly) to identify secrets needing alerts
  • [ ] Integrate Slack Webhook provider with interactive button support
  • [ ] Implement rotation logic that updates nextExpiryDate based on interval_days

Phase 4: Dashboard & Compliance

  • [ ] Build the Next.js Dashboard using Streaming and Suspense for secret lists
  • [ ] Implement the Audit Log entity and read-only UI for compliance officers
  • [ ] Create "Compliance Export" feature (CSV/PDF) mapping logs to SOC2 CC7.1
  • [ ] Implement PagerDuty escalation logic for overdue P1 secrets

Phase 5: Launch & Hardening

  • [ ] Conduct security audit focusing on the AES-256-GCM implementation
  • [ ] Load test the River task queue with 100k+ mock secret entities
  • [ ] Set up OpenTelemetry (OTel) for end-to-end request tracing
  • [ ] Final documentation and "Runbook" for secret rotation responders