Skip to content
reaatech

@reaatech/secret-rotation-sidecar

npm v0.1.0

HTTP sidecar server that exposes secret rotation operations, health checks, Prometheus metrics, and SSE event streaming over a REST API, built on Node.js's built-in `http` module with zero framework dependencies. Ships as both a programmatic class (`SidecarServer`) and a standalone CLI binary configured via environment variables.

npm →source →

@reaatech/secret-rotation-sidecar

npm version License: MIT CI

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

HTTP sidecar server for Secret Rotation Kit. Exposes rotation operations, health checks, Prometheus metrics, and SSE event streaming over a REST API. Built on Node.js’s built-in http module with zero framework dependencies.

Installation

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

Feature Overview

  • REST API — trigger rotations, query secret state, check health, export metrics
  • SSE streaming — real-time rotation event stream for external consumers
  • Bearer auth — optional shared-secret authentication on write endpoints
  • CORS support — configurable origin for browser-based clients
  • Built-in metrics — automatic Prometheus counters for rotation requests and failures
  • Zero framework dependencies — uses Node.js http.createServer directly
  • Graceful shutdown — closes SSE connections on server stop

Quick Start

typescript
import { RotationManager } from '@reaatech/secret-rotation-core';
import { AWSProvider } from '@reaatech/secret-rotation-provider-aws';
import { SidecarServer } from '@reaatech/secret-rotation-sidecar';
 
const provider = new AWSProvider({ region: 'us-east-1' });
const manager = new RotationManager({ providerInstance: provider });
 
const server = new SidecarServer({
  manager,
  port: 8080,
  authToken: process.env.SIDECAR_AUTH_TOKEN,
});
 
await server.start();
console.log(`Sidecar running at ${server.address}`);

Standalone CLI

The package ships a secret-rotation-sidecar binary that boots a fully wired server from environment variables — no code required. Install the provider package you need (an optional peer dependency) alongside the sidecar:

terminal
npm install @reaatech/secret-rotation-sidecar @reaatech/secret-rotation-provider-aws @aws-sdk/client-secrets-manager
 
SRK_PROVIDER=aws SRK_AWS_REGION=us-east-1 npx secret-rotation-sidecar

This is also the default entry point of the published Docker image (CMD ["node", "packages/sidecar/dist/bin.js"]).

Environment variables

VariableDefaultDescription
SRK_PROVIDER(required)Provider to load: aws, gcp, vault, or vercel
PORT / SRK_PORT8080HTTP port
SRK_HOST0.0.0.0Bind address
SRK_AUTH_TOKEN—Bearer token for write endpoints
SRK_CORS_ORIGINhttp://localhost:*Allowed CORS origin
SRK_LOG_LEVELinfodebug | info | warn | error
SRK_LOG_STRUCTUREDtrueEmit JSON logs (false for human-readable)
SRK_ROTATION_INTERVAL_MS—Enable scheduled rotation at this interval
SRK_SECRETS—Comma-separated secrets to auto-rotate (needs the interval)
SRK_AWS_REGION / SRK_AWS_ENDPOINT—AWS provider config
SRK_GCP_PROJECT_ID / SRK_GCP_ENDPOINT—GCP provider config
SRK_VAULT_URL / SRK_VAULT_MOUNT / SRK_VAULT_TOKEN—Vault provider config
SRK_VERCEL_TOKEN / SRK_VERCEL_PROJECT_ID / SRK_VERCEL_TEAM_ID / SRK_VERCEL_TARGET—Vercel provider config (SRK_VERCEL_TARGET is comma-separated)

The process handles SIGTERM/SIGINT for graceful shutdown (stops scheduled rotation, then closes the server and SSE connections).

API Reference

SidecarServer

Constructor

typescript
new SidecarServer(options: SidecarOptions)

SidecarOptions

PropertyTypeDefaultDescription
managerRotationManager(required)Rotation manager instance
portnumber8080HTTP server port
hoststring127.0.0.1Bind address
eventEmitterEventEmitter—Event source for SSE streaming
metricsMetricsServiceMetricsService()Metrics collector
loggerLogger—Structured logger
corsOriginstringhttp://localhost:*Allowed CORS origin
authTokenstring—Bearer token for write endpoint auth

Methods

MethodReturnsDescription
start()Promise<void>Start the HTTP server
stop()Promise<void>Stop the server and close SSE connections
addressstringServer address as http://host:port
listeningPortnumberActual port (useful when port is set to 0)

Endpoints

MethodPathAuthDescription
POST/rotateBearerTrigger a secret rotation. Body: { "secretName": "...", "force": false }
GET/secrets/:nameBearerGet rotation state for a secret
GET/health—Health check. Returns { status: "healthy", timestamp, uptime }
GET/metrics—Prometheus-format metrics
GET/events—SSE event stream
OPTIONS*—CORS preflight

SSE Events

Connected clients receive typed events:

Event TypeWhen
key_generatedNew key material created
key_propagatedKey stored in provider
key_verifiedPropagation confirmed
key_activatedNew key became active
rotation_failedRotation failed

Built-in Metrics

The sidecar automatically tracks:

MetricTypeDescription
srk_rotate_requests_totalCounterTotal rotation requests
srk_rotate_failures_totalCounterFailed rotation requests

Usage Patterns

Authenticated Access

typescript
const server = new SidecarServer({
  manager,
  port: 8080,
  authToken: 'my-shared-secret',
});
 
// Write endpoints require: Authorization: Bearer my-shared-secret

With SSE Event Streaming

typescript
const server = new SidecarServer({
  manager,
  port: 8080,
  eventEmitter: manager.events, // expose rotation events as SSE
});
 
// Connect: curl -N http://localhost:8080/events

Custom CORS

typescript
const server = new SidecarServer({
  manager,
  port: 8080,
  corsOrigin: '*', // allow any origin
});

Rotate via HTTP

terminal
curl -X POST http://localhost:8080/rotate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-token" \
  -d '{"secretName": "database-password"}'

Query Secret State

terminal
curl http://localhost:8080/secrets/database-password

Scrape Metrics

terminal
curl http://localhost:8080/metrics

Related Packages

License

MIT

All packagessecret-rotation-kit overview