Secrets Management | Bootspring Docs

Patterns for secure handling of secrets, credentials, and API keys.

Overview#

Proper secrets management protects your application from credential leaks. This pattern covers:

Environment variable validation
Runtime secret loading
Encrypted secrets storage
API key generation and validation
Secret rotation

Prerequisites#

npm install zod
# Optional for AWS Secrets Manager
npm install @aws-sdk/client-secrets-manager

Code Example#

Environment Variable Validation#

// lib/env.ts
import { z } from 'zod'

const envSchema = z.object({
  // Database
  DATABASE_URL: z.string().url(),

  // Auth
  NEXTAUTH_SECRET: z.string().min(32),
  NEXTAUTH_URL: z.string().url(),

  // Stripe
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  STRIPE_WEBHOOK_SECRET: z.string().startsWith('whsec_'),
  NEXT_PUBLIC_STRIPE_KEY: z.string().startsWith('pk_'),

  // Email
  RESEND_API_KEY: z.string().startsWith('re_'),

  // Optional
  SENTRY_DSN: z.string().url().optional()
})

// Validate at startup
function validateEnv() {
  const parsed = envSchema.safeParse(process.env)

  if (!parsed.success) {
    console.error('Invalid environment variables:')
    console.error(parsed.error.flatten().fieldErrors)
    throw new Error('Invalid environment configuration')
  }

  return parsed.data
}

export const env = validateEnv()

// Type-safe access: env.DATABASE_URL is guaranteed to be a string

Runtime Secret Loading#

// lib/secrets.ts
interface SecretStore {
  get(key: string): Promise<string | undefined>
}

// Local development
class EnvSecretStore implements SecretStore {
  async get(key: string) {
    return process.env[key]
  }
}

// AWS Secrets Manager
class AwsSecretStore implements SecretStore {
  private client: SecretsManagerClient

  constructor() {
    this.client = new SecretsManagerClient({})
  }

  async get(key: string) {
    const command = new GetSecretValueCommand({ SecretId: key })
    const response = await this.client.send(command)
    return response.SecretString
  }
}

// Factory
export function createSecretStore(): SecretStore {
  if (process.env.NODE_ENV === 'development') {
    return new EnvSecretStore()
  }
  return new AwsSecretStore()
}

// Usage
const secrets = createSecretStore()
const apiKey = await secrets.get('STRIPE_SECRET_KEY')

Encrypted Secrets#

// lib/crypto.ts
import { createCipheriv, createDecipheriv, randomBytes, scrypt } from 'crypto'
import { promisify } from 'util'

const scryptAsync = promisify(scrypt)

export async function encryptSecret(plaintext: string, password: string): Promise<string> {
  const salt = randomBytes(16)
  const key = (await scryptAsync(password, salt, 32)) as Buffer
  const iv = randomBytes(16)

  const cipher = createCipheriv('aes-256-gcm', key, iv)
  const encrypted = Buffer.concat([
    cipher.update(plaintext, 'utf8'),
    cipher.final()
  ])
  const authTag = cipher.getAuthTag()

  // Combine: salt + iv + authTag + encrypted
  const combined = Buffer.concat([salt, iv, authTag, encrypted])
  return combined.toString('base64')
}

export async function decryptSecret(ciphertext: string, password: string): Promise<string> {
  const combined = Buffer.from(ciphertext, 'base64')

  const salt = combined.subarray(0, 16)
  const iv = combined.subarray(16, 32)
  const authTag = combined.subarray(32, 48)
  const encrypted = combined.subarray(48)

  const key = (await scryptAsync(password, salt, 32)) as Buffer

  const decipher = createDecipheriv('aes-256-gcm', key, iv)
  decipher.setAuthTag(authTag)

  const decrypted = Buffer.concat([
    decipher.update(encrypted),
    decipher.final()
  ])

  return decrypted.toString('utf8')
}

API Key Storage#

// lib/api-keys.ts
import { randomBytes, createHash } from 'crypto'
import { prisma } from '@/lib/db'

export async function createApiKey(userId: string, name: string) {
  // Generate key: prefix_randomBytes
  const keyValue = `bs_${randomBytes(24).toString('hex')}`

  // Hash for storage (never store plain key)
  const keyHash = createHash('sha256').update(keyValue).digest('hex')

  // Store last 4 chars for display
  const keyHint = keyValue.slice(-4)

  await prisma.apiKey.create({
    data: {
      userId,
      name,
      keyHash,
      keyHint
    }
  })

  // Only return the full key once!
  return keyValue
}

export async function validateApiKey(key: string) {
  const keyHash = createHash('sha256').update(key).digest('hex')

  const apiKey = await prisma.apiKey.findUnique({
    where: { keyHash },
    include: { user: true }
  })

  if (!apiKey || apiKey.revokedAt) {
    return null
  }

  // Update last used
  await prisma.apiKey.update({
    where: { id: apiKey.id },
    data: { lastUsedAt: new Date() }
  })

  return apiKey.user
}

Secure Token Generation#

// lib/tokens.ts
import { randomBytes } from 'crypto'

// URL-safe token
export function generateToken(bytes = 32): string {
  return randomBytes(bytes).toString('base64url')
}

// Numeric OTP
export function generateOtp(length = 6): string {
  const max = Math.pow(10, length) - 1
  const randomNum = parseInt(randomBytes(4).toString('hex'), 16)
  return String(randomNum % (max + 1)).padStart(length, '0')
}

// Short code (for user input)
export function generateCode(length = 8): string {
  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789' // No confusing chars
  let code = ''

  for (let i = 0; i < length; i++) {
    const randomIndex = randomBytes(1)[0] % chars.length
    code += chars[randomIndex]
  }

  return code
}

Secret Rotation#

// lib/rotation.ts
import { prisma } from '@/lib/db'
import { encryptSecret, decryptSecret } from './crypto'

export async function rotateEncryptionKey() {
  const oldKey = process.env.ENCRYPTION_KEY!
  const newKey = process.env.NEW_ENCRYPTION_KEY!

  // Find all encrypted records
  const records = await prisma.secretData.findMany()

  for (const record of records) {
    // Decrypt with old key
    const plaintext = await decryptSecret(record.encryptedValue, oldKey)

    // Re-encrypt with new key
    const newEncrypted = await encryptSecret(plaintext, newKey)

    // Update record
    await prisma.secretData.update({
      where: { id: record.id },
      data: { encryptedValue: newEncrypted }
    })
  }

  console.log(`Rotated ${records.length} secrets`)
}

Usage Instructions#

Validate all environment variables at application startup
Use different secret stores for development vs production
Never store plain API keys - always hash them
Return full API keys only once during creation
Implement secret rotation for encryption keys

Best Practices#

Never commit secrets - Use .env.local and .gitignore
Validate early - Check environment variables at startup
Hash API keys - Store hashes, not plain text
Rotate regularly - Implement key rotation procedures
Audit access - Track when secrets are accessed
Use prefixes - Make key types identifiable (sk_, pk_, re_)
Limit scope - Use least-privilege access for secrets

Input Validation - Validate all input
Encryption - Data encryption patterns
Audit Logging - Track secret access
Environment Management - Environment configuration