← BACK

Cross-Platform Secret Storage in Node.js with cross-keychain

— 3 min read

Stop storing API keys in plaintext .env files. cross-keychain is a TypeScript library that uses your OS's native credential manager to store secrets securely—macOS Keychain, Windows Credential Manager, or Linux Secret Service. One API, zero plaintext config files.

Born from mcp-tool-selector (still work in progress), where I needed to manage API keys for multiple MCP servers without scattering secrets across .env files — or worse, committing them to repos. It became a solid cross-platform utility, so I published it.

At a glance

  • Works on macOS, Windows, and Linux with native backend support
  • Provides both programmatic API and CLI for storing/retrieving secrets
  • Automatic fallback when native modules aren't available
  • Zero deps on the public API, TS-first, Node 18+, ESM/CJS

Docs & API: read the GitHub repo and the npm package page.

Quick taste: store & retrieve secrets

Programmatic usage:

import { setPassword, getPassword } from "cross-keychain";


// Store a secret
await setPassword("myapp", "api-token", "sk-1234567890");


// Retrieve it later
const token = await getPassword("myapp", "api-token");
console.log(token); // "sk-1234567890"


// Delete when done
await deletePassword("myapp", "api-token");

CLI usage:

# Store a secret
npx cross-keychain set myapp api-token


# Retrieve it
npx cross-keychain get myapp api-token


# Delete it
npx cross-keychain delete myapp api-token

Why this matters

Storing secrets in plaintext .env or config files is common but risky. You must remember to .gitignore them, rotate them when they leak, and manage them across environments. Native OS credential stores handle this—encrypted at rest, access-controlled, and integrated with your system.

cross-keychain provides a consistent API across platforms: write once, let the OS handle the heavy lifting.

My third AI-engineered project (after mcp-server-giphy and env-interpolation), built with multiple AI agents. Tired of managing plaintext secrets? This simplifies everything.

When to Use cross-keychain

This library is ideal for:

  • CLI tools that need to store API tokens between sessions
  • Development environments where you want secure credential storage
  • Local applications that authenticate with external services
  • Any Node.js app that currently uses .env files for secrets

It's not suitable for server-side applications in production—those should use dedicated secret managers like HashiCorp Vault or cloud provider solutions.

Conclusion

If you're building Node.js tools that handle credentials, stop relying on plaintext files. cross-keychain gives you secure, native storage with minimal API surface. Your users' secrets deserve better than credentials.json.

Related posts: