Implementation:Helicone Helicone Secret Manager

Knowledge Sources	Helicone
Domains	Security, Configuration
Last Updated	2026-02-14 06:32 GMT

Overview

A blue-green secret rotation manager that enables zero-downtime credential rotation across all Helicone services by switching between blue and green secret variants without redeployment.

Description

The SecretManagerClass resolves sensitive environment variables through a multi-layer lookup strategy with blue-green rotation support.

Rotation mechanism: For each secret named SECRET_NAME, two variants can exist: SECRET_NAME_BLUE and SECRET_NAME_GREEN. A global ACTIVE_SECRET_CYCLE environment variable (set to "blue" or "green") controls which variant is active for all secrets. If rotation is not configured (no ACTIVE_SECRET_CYCLE or no variant exists), the manager falls back to the base environment variable name.

Lookup chain:

1. Custom env lookup functions passed at construction time (allows Cloudflare Workers bindings, etc.)
2. Known JSON-encoded secret dictionaries (currently JAWN_DATABASE_CONNECTIONS) where multiple secrets are stored as a JSON object in a single env var
3. process.env as the final fallback

API:

• getSecret(secretName, fallback?) -- Public method that resolves a secret with an optional fallback name. If the primary secret is not found and a fallback is provided, it attempts to resolve the fallback name through the same chain.
• resolveSecret(secretName) -- Private method implementing the blue-green resolution logic, returning the value along with its source ("blue", "green", or "fallback").

A singleton instance with an empty lookup function array is exported as SecretManager for simple use cases.

Usage

Use this class in any service that needs to read sensitive configuration values. Construct with custom lookup functions for environments like Cloudflare Workers, or use the exported singleton for standard Node.js environments. The blue-green rotation pattern is critical for database credential rotation without service restarts.

Code Reference

Source Location

• Repository: Helicone
• File: packages/secrets/SecretManager.ts

Signature

interface SecretRotationResult {
  value: string | undefined;
  source: "blue" | "green" | "fallback";
  secretName: string;
}

export class SecretManagerClass {
  constructor(envLookupFunctions: ((key: string) => string | undefined)[]);
  getSecret(secretName: string, fallback?: string | undefined): string | undefined;
}

export const SecretManager: SecretManagerClass;

Import

import { SecretManager, SecretManagerClass } from "@helicone/secrets/SecretManager";

I/O Contract

getSecret

Parameter	Type	Description
secretName	string	The base name of the secret to resolve (e.g., "DATABASE_URL")
fallback	undefined	Optional fallback secret name if primary is not found

Returns	Type	Description
(value)	undefined	The resolved secret value, or undefined if not found

Resolution Priority

Priority	Source	Condition
1	Blue/Green variant	ACTIVE_SECRET_CYCLE is set and the corresponding variant exists
2	Base env var	Fallback when rotation is not configured or variant is missing
3	Fallback name	Only if primary secret resolves to undefined and fallback is provided

Environment Variables

Variable	Description
ACTIVE_SECRET_CYCLE	Set to "blue" or "green" to select the active variant
{SECRET_NAME}_BLUE	Blue variant of the secret
{SECRET_NAME}_GREEN	Green variant of the secret
JAWN_DATABASE_CONNECTIONS	JSON-encoded dictionary of secrets (known dictionary lookup)

Usage Examples

import { SecretManager, SecretManagerClass } from "@helicone/secrets/SecretManager";

// Using the singleton (standard Node.js)
const dbUrl = SecretManager.getSecret("DATABASE_URL");

// Using with a fallback
const cacheUrl = SecretManager.getSecret("REDIS_URL", "CACHE_URL");

// Custom instance for Cloudflare Workers
const workerSecrets = new SecretManagerClass([
  (key) => env[key],  // Cloudflare env bindings
]);
const apiKey = workerSecrets.getSecret("API_KEY");

// Blue-green rotation setup:
// Set ACTIVE_SECRET_CYCLE=blue in env
// Set DATABASE_URL_BLUE=postgres://new-host/db
// Set DATABASE_URL_GREEN=postgres://old-host/db
// SecretManager.getSecret("DATABASE_URL") returns the _BLUE value

Related Pages

• Principle:Helicone_Helicone_Secret_Rotation