GitOps Secrets

Easily and securely inject environment variable secrets—no matter the size—into any JavaScript runtime. Bypass the 4KB environment variable limit in AWS Lambda, Vercel, and Netlify, and run on the edge in environments like Deno, Bun, and others where NodeJS built-in modules aren't available.

Table of Contents

• Installation
• Usage Options
  • File System Access Available
  • No File System Access (Edge Functions)
• Secret Storage Formats
  • JSON Format
  • JS Module Format
• Providers
• Background

Installation

# npm
npm install @jacobwolf/gitops-secrets
# yarn
yarn add @jacobwolf/gitops-secrets
# pnpm
pnpm add @jacobwolf/gitops-secrets
# bun
bun add @jacobwolf/gitops-secrets

Usage Options

File System Access Available

1. Build the encryption file at bundle time

Create a script (e.g., scripts/build-secrets.ts) to generate your encrypted secrets:

import*asgitopsSecretsfrom'@jacobwolf/gitops-secrets';// Fetch secrets from provider (e.g., Doppler)constsecretsData=awaitgitopsSecrets.providers.doppler.fetchSecrets({dopplerToken: process.env.DOPPLER_TOKEN});// Encrypt and store secretsawaitgitopsSecrets.build(secretsData,{// Optional: Custom path (defaults to .secrets/.secrets.enc.js)path: './config/secrets.enc.js',// Optional: Only export cipher text without loading logiccipherTextOnly: false});

Run this script during your build process by adding it to your package.json:

{
"scripts": {
"prebuild": "ts-node scripts/build-secrets.ts",
"build": "your-build-command"
}
}

This ensures your secrets are encrypted and available before your application builds. Make sure you have ts-node installed:

npm install --save-dev ts-node
# or
yarn add -D ts-node
# or
pnpm add -D ts-node
# or
bun add -D ts-node

2. Load secrets at runtime

import*asgitopsSecretsfrom'@jacobwolf/gitops-secrets';// Method 1: Default path (.secrets/.secrets.enc.js)awaitgitopsSecrets.loadSecrets();// Method 2: Custom module pathconstsecretsModule=require('./config/secrets.enc.js');awaitsecretsModule.loadSecrets();// Method 3: From JSON fileconstdecryptedSecrets=awaitgitopsSecrets.decryptFromFile('./path/to/secrets.enc.json');decryptedSecrets.mergeSecrets();// Now process.env has all your secretsconsole.log(process.env.API_KEY);// "your-secret-api-key"

No File System Access (Edge Functions)

For environments without file system access (Vercel Edge, Cloudflare Workers, browsers):

1. Import the no-fs version

// Import the edge-compatible versionimport*asgitopsSecretsfrom'@jacobwolf/gitops-secrets/no-fs';// Or import specific functionsimport{providers,encrypt,decrypt}from'@jacobwolf/gitops-secrets/no-fs';

2. Handle encryption/decryption directly

// Encrypt secrets to string// Uses GITOPS_SECRETS_MASTER_KEY environment variableconstencryptedSecrets=awaitgitopsSecrets.encrypt(JSON.stringify(secretsData));// Later, decrypt and useconstdecryptedJson=awaitgitopsSecrets.decrypt(encryptedSecrets);constsecrets=JSON.parse(decryptedJson);// Or load directly into environmentawaitgitopsSecrets.loadSecrets(encryptedSecrets);

3. Recommended pattern for edge functions

// During build time (build script)import{providers,encrypt}from'@jacobwolf/gitops-secrets';constsecretsData=awaitproviders.doppler.fetchSecrets({dopplerToken: process.env.DOPPLER_TOKEN});constencryptedText=awaitencrypt(JSON.stringify(secretsData));// Add to your edge code as a constantconsole.log(`const ENCRYPTED_SECRETS = "${encryptedText}";`);// In your edge function:import{decrypt}from'@jacobwolf/gitops-secrets/no-fs';exportdefaultasyncfunctionhandler(request){constdecryptedJson=awaitdecrypt(ENCRYPTED_SECRETS);constsecrets=JSON.parse(decryptedJson);// Use your secretsconstapiKey=secrets.API_KEY;// ...your edge function logic}

Secret Storage Formats

There are two file formats for bundling encrypted secrets:

JSON Format

Stores encrypted data in a JSON file.

import*asgitopsSecretsfrom'@jacobwolf/gitops-secrets';// Encrypt to JSON fileasyncfunctionencryptToJSON(){constpayload=awaitgitopsSecrets.providers.doppler.fetchSecrets({dopplerToken: process.env.DOPPLER_TOKEN});// Default path (.secrets/.secrets.enc.json)awaitgitopsSecrets.encryptToFile(payload);// Or custom pathawaitgitopsSecrets.encryptToFile(payload,{path: "./custom/path/secrets.enc.json"});}// Decrypt from JSON fileasyncfunctiondecryptFromJSON(){// Default pathconstsecrets=awaitgitopsSecrets.decryptFromFile();// Or custom pathconstcustomSecrets=awaitgitopsSecrets.decryptFromFile('./custom/path/secrets.enc.json');// Merge into environmentsecrets.mergeSecrets();}

JS Module Format

Ideal for restricted environments like Vercel where file access is problematic.

import*asgitopsSecretsfrom'@jacobwolf/gitops-secrets';// Encrypt to JS moduleasyncfunctionbuildJSModule(){constpayload=awaitgitopsSecrets.providers.doppler.fetchSecrets({dopplerToken: process.env.DOPPLER_TOKEN});// Default path (.secrets/.secrets.enc.js)awaitgitopsSecrets.build(payload);// Custom pathawaitgitopsSecrets.build(payload,{path: "lib/secrets.js"});// Only export cipher textawaitgitopsSecrets.build(payload,{path: "lib/secrets.js",cipherTextOnly: true});}// Load from default pathasyncfunctionloadFromDefaultPath(){import{loadSecrets}from'@jacobwolf/gitops-secrets';awaitloadSecrets();}// Load from custom moduleasyncfunctionloadFromCustomModule(){// CommonJSconst{ loadSecrets }=require("./lib/secrets");awaitloadSecrets();// ES modulesimport{loadSecrets}from"./lib/secrets";awaitloadSecrets();}

Providers

Currently supported remote secrets providers:

• Doppler

More providers will be added in future releases.

Background

Serverless platforms like Vercel, Netlify, and AWS Lambda limit environment variables to 4KB, which complex applications can quickly exceed.

This package was inspired by Doppler's GitOps Secrets package, but it uses the Web Crypto API instead of node:crypto for broader compatibility with modern web environments like edge functions.