How to store your users' API keys safely in Node.js and MongoDB

import {
  createCipheriv,
  createDecipheriv,
  createHmac,
  randomBytes,
} from "node:crypto";

// Envelope encryption for API keys your users give you.
// Each stored key gets its own random data key. The data key encrypts the
// secret; a master key (kept outside the database) encrypts the data key.

export type MasterKey = { id: string; key: Buffer }; // 32 bytes for AES-256

export type StoredSecret = {
  kekId: string; // which master key wrapped the data key
  wrappedKey: string; // data key, encrypted with the master key
  wrapIv: string;
  wrapTag: string;
  ciphertext: string; // the API key, encrypted with the data key
  iv: string;
  tag: string;
};

const b64 = (buf: Buffer) => buf.toString("base64");
const unb64 = (s: string) => Buffer.from(s, "base64");

function seal(key: Buffer, plaintext: Buffer, aad: Buffer) {
  const iv = randomBytes(12); // never reuse an IV with the same key
  const cipher = createCipheriv("aes-256-gcm", key, iv);
  cipher.setAAD(aad);
  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
  return { iv, ciphertext, tag: cipher.getAuthTag() };
}

function open(key: Buffer, iv: Buffer, ciphertext: Buffer, tag: Buffer, aad: Buffer) {
  const decipher = createDecipheriv("aes-256-gcm", key, iv);
  decipher.setAAD(aad);
  decipher.setAuthTag(tag); // a changed byte anywhere makes final() throw
  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
}

// The context ties a ciphertext to one tenant and one record, so a row copied
// onto another tenant's record fails to decrypt instead of leaking.
const contextOf = (tenantId: string, recordId: string) =>
  Buffer.from(`${tenantId}:${recordId}`, "utf8");

export function encryptSecret(
  secret: string,
  master: MasterKey,
  tenantId: string,
  recordId: string,
): StoredSecret {
  const aad = contextOf(tenantId, recordId);
  const dataKey = randomBytes(32);
  const body = seal(dataKey, Buffer.from(secret, "utf8"), aad);
  const wrap = seal(master.key, dataKey, aad);
  dataKey.fill(0);
  return {
    kekId: master.id,
    wrappedKey: b64(wrap.ciphertext),
    wrapIv: b64(wrap.iv),
    wrapTag: b64(wrap.tag),
    ciphertext: b64(body.ciphertext),
    iv: b64(body.iv),
    tag: b64(body.tag),
  };
}

export function decryptSecret(
  stored: StoredSecret,
  masters: Map<string, Buffer>,
  tenantId: string,
  recordId: string,
): string {
  const master = masters.get(stored.kekId);
  if (!master) throw new Error(`Unknown master key ${stored.kekId}`);
  const aad = contextOf(tenantId, recordId);
  const dataKey = open(master, unb64(stored.wrapIv), unb64(stored.wrappedKey), unb64(stored.wrapTag), aad);
  try {
    return open(dataKey, unb64(stored.iv), unb64(stored.ciphertext), unb64(stored.tag), aad).toString("utf8");
  } finally {
    dataKey.fill(0);
  }
}

// Rotating the master key only re-wraps the small data key.
// The encrypted API key itself is not touched.
export function rewrap(
  stored: StoredSecret,
  masters: Map<string, Buffer>,
  next: MasterKey,
  tenantId: string,
  recordId: string,
): StoredSecret {
  const aad = contextOf(tenantId, recordId);
  const oldMaster = masters.get(stored.kekId);
  if (!oldMaster) throw new Error(`Unknown master key ${stored.kekId}`);
  const dataKey = open(oldMaster, unb64(stored.wrapIv), unb64(stored.wrappedKey), unb64(stored.wrapTag), aad);
  const wrap = seal(next.key, dataKey, aad);
  dataKey.fill(0);
  return { ...stored, kekId: next.id, wrappedKey: b64(wrap.ciphertext), wrapIv: b64(wrap.iv), wrapTag: b64(wrap.tag) };
}

// What you can safely show and search on. The fingerprint is a keyed hash, so
// you can detect "this key is already saved" without storing the key.
export function describeKey(secret: string, fingerprintSecret: Buffer) {
  return {
    fingerprint: createHmac("sha256", fingerprintSecret).update(secret).digest("hex").slice(0, 16),
    preview: `${secret.slice(0, 3)}...${secret.slice(-4)}`,
  };
}

# Generate a 32-byte master key once, store it in your secret manager
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

// At startup: load every master key you still need to decrypt with,
// and mark the newest one as the key for new writes.
const masters = new Map([
  ["kek-2026-10", Buffer.from(process.env.KEY_MASTER_2026_10!, "base64")],
]);
const current = { id: "kek-2026-10", key: masters.get("kek-2026-10")! };

ok    round trip: true
ok    stored document contains the key?: false
ok    same key encrypted twice gives the same ciphertext?: false
fails one flipped byte: Unsupported state or unable to authenticate data
fails row copied to tenant_b: Unsupported state or unable to authenticate data
fails wrong master key: Unsupported state or unable to authenticate data
ok    after rotation, ciphertext unchanged: true
ok    after rotation, decrypts with new master only: true
fails old row after old master retired: Unknown master key kek-2026-10
ok    fingerprint stable: true
ok    preview: sk-...f80b
ok    redacted log line: call failed for key sk-[REDACTED] with header Authorization: Bearer [JWT REDACTED]

import { randomUUID } from "node:crypto";
import type { Collection, Db } from "mongodb";
import {
  decryptSecret,
  describeKey,
  encryptSecret,
  type MasterKey,
  type StoredSecret,
} from "./key-vault.ts";

type ProviderKeyDoc = {
  _id: string;
  tenantId: string;
  provider: "openai" | "anthropic" | "google";
  secret: StoredSecret;
  fingerprint: string;
  preview: string;
  createdAt: Date;
  lastUsedAt: Date | null;
  revokedAt: Date | null;
};

// Every read except the one that makes the provider call leaves the secret out.
const PUBLIC_FIELDS = { secret: 0 } as const;

export class ProviderKeys {
  private col: Collection<ProviderKeyDoc>;

  constructor(
    db: Db,
    private master: MasterKey,
    private masters: Map<string, Buffer>,
    private fingerprintSecret: Buffer,
  ) {
    this.col = db.collection<ProviderKeyDoc>("provider_keys");
  }

  async setup() {
    // One active copy of the same key per tenant.
    await this.col.createIndex(
      { tenantId: 1, fingerprint: 1 },
      { unique: true, partialFilterExpression: { revokedAt: null } },
    );
  }

  async add(tenantId: string, provider: ProviderKeyDoc["provider"], apiKey: string) {
    const _id = randomUUID();
    const { fingerprint, preview } = describeKey(apiKey, this.fingerprintSecret);
    await this.col.insertOne({
      _id,
      tenantId,
      provider,
      secret: encryptSecret(apiKey, this.master, tenantId, _id),
      fingerprint,
      preview,
      createdAt: new Date(),
      lastUsedAt: null,
      revokedAt: null,
    });
    return { id: _id, provider, preview }; // never echo the key back
  }

  list(tenantId: string) {
    return this.col
      .find({ tenantId, revokedAt: null }, { projection: PUBLIC_FIELDS })
      .toArray();
  }

  // The only place the plaintext exists: inside the call, then it is dropped.
  async withKey<T>(tenantId: string, id: string, call: (apiKey: string) => Promise<T>) {
    const doc = await this.col.findOneAndUpdate(
      { _id: id, tenantId, revokedAt: null },
      { $set: { lastUsedAt: new Date() } },
    );
    if (!doc) throw new Error("Key not found or revoked");
    return call(decryptSecret(doc.secret, this.masters, tenantId, id));
  }

  async revoke(tenantId: string, id: string) {
    // Remove the ciphertext too, so a revoked key cannot be recovered later.
    await this.col.updateOne(
      { _id: id, tenantId },
      { $set: { revokedAt: new Date() }, $unset: { secret: "" } },
    );
  }
}

add() returns      { id: 'edee9f1e-...', provider: 'openai', preview: 'sk-...bfe9' }
plaintext in DB?   false
list() fields      _id, tenantId, provider, fingerprint, preview, createdAt, lastUsedAt, revokedAt
withKey() got key  true
tenant_b access    Key not found or revoked
same key twice     E11000 duplicate key error ... index: tenantId_1_fingerprint_1
after revoke       { secretKept: false, revoked: true }
use revoked key    Key not found or revoked

// Last line of defence: scrub anything that looks like a secret before it is
// logged or returned in an error. Patterns are examples; add your providers'.
const PATTERNS: [RegExp, string][] = [
  [/sk-[A-Za-z0-9_-]{16,}/g, "sk-[REDACTED]"], // OpenAI / Anthropic style
  [/AIza[0-9A-Za-z_-]{30,}/g, "AIza[REDACTED]"], // Google API keys
  [/(?:ghp|gho|ghs|github_pat)_[A-Za-z0-9_]{20,}/g, "gh_[REDACTED]"], // GitHub tokens
  [/eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, "[JWT REDACTED]"],
  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[PRIVATE KEY REDACTED]"],
];

export function redact(text: string): string {
  return PATTERNS.reduce((out, [pattern, replacement]) => out.replace(pattern, replacement), text);
}