@reaatech/secret-rotation-core

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Core rotation engine for Secret Rotation Kit. Orchestrates the full zero-downtime rotation lifecycle with propagation verification, resilience patterns, and pluggable provider adapters.

Installation

npm install @reaatech/secret-rotation-core
# or
pnpm add @reaatech/secret-rotation-core

To rotate secrets, you’ll also need at least one provider adapter:

pnpm add @reaatech/secret-rotation-provider-aws

Feature Overview

• Full rotation lifecycle — generate → propagate → verify → activate → revoke
• Overlapping key windows — old and new keys coexist during rotation (configurable overlap/grace periods)
• Dual verification strategies — provider-level polling and consumer-level active verification
• Resilience patterns — exponential backoff with jitter, circuit breaker, automatic rollback
• Key lifecycle management — state machine: pending → active → expired → revoked/failed
• Consumer registry — track consumers with health monitoring and interest groups
• Key storage backends — in-memory (test/dev) and persistent file-system with AES-256-GCM encryption
• Event system — typed event emitter with in-memory and disk-persisted (JSON-lines) backends
• Pluggable providers — swap AWS, GCP, or Vault without changing application code
• Input validation — secret name constraints, metadata limits, numeric range checks
• Rate limiting — per-secret token-bucket rate limiter to prevent rotation flooding

Quick Start

import { RotationManager } from '@reaatech/secret-rotation-core';
import { AWSProvider } from '@reaatech/secret-rotation-provider-aws';
 
const provider = new AWSProvider({ region: 'us-east-1' });
 
const manager = new RotationManager({
  providerInstance: provider,
  rotationIntervalMs: 24 * 60 * 60 * 1000, // 24 hours
});
 
// Subscribe to events
manager.events.on('key_activated', (event) => {
  console.log(`Key ${event.keyId} active for ${event.secretName}`);
});
 
// Manual rotation
const result = await manager.rotate('database-password');
 
// Scheduled rotation
await manager.start(['database-password']);

API Reference

RotationManager

The primary entry point. Wires together provider, key store, verifier, rate limiter, rollback manager, and event emitter.

Constructor Options

Methods

RotationWorkflow

The lifecycle orchestrator. Executes a 7-step pipeline and emits events at each stage:

1. Generate key material (CryptographicKeyGenerator)
2. Save to key store
3. Begin provider rotation session
4. Store secret value in provider
5. Verify propagation
6. Activate new key (old key → expired)
7. Complete provider session

KeyLifecycleManager

Key state machine:

pending → active → expired → revoked
                      ↘ failed

Verification

PollingPropagationVerifier

Polls the provider to confirm the new version is readable. Suitable for library-managed secrets.

const verifier = new PollingPropagationVerifier(provider);

ActivePropagationVerifier

Reaches out to registered consumers via HTTP to confirm they’re serving the new version.

const verifier = new ActivePropagationVerifier(provider, consumerRegistry, {
  timeout: 30000,
  minConsumerCoverage: 1.0,
});

Resilience

Key Storage

Key Generation

Events

Related Packages

• @reaatech/secret-rotation-types — Shared types and interfaces
• @reaatech/secret-rotation-observability — Logging and metrics
• @reaatech/secret-rotation-provider-aws — AWS adapter
• @reaatech/secret-rotation-provider-gcp — GCP adapter
• @reaatech/secret-rotation-provider-vault — Vault adapter
• @reaatech/secret-rotation-sidecar — HTTP sidecar

License

MIT