keytar

keytar is a native Node.js addon that provides a simple, promise-based API for storing, retrieving, and deleting passwords in your operating system’s secure credential store — Keychain on macOS, the Secret Service API/libsecret on Linux, and Credential Vault on Windows.

Originally built by GitHub for the Atom editor, keytar became the de facto standard for desktop applications — including many built with Electron — that need to persist user credentials without writing them to disk in plain text. It ships prebuilt binaries for supported Node.js and Electron ABI versions, avoiding a native compile step for most consumers.

What You Get

• A cross-platform native addon that talks to macOS Keychain, Windows Credential Vault, and Linux libsecret through a single API
• Prebuilt binaries for supported Node.js and Electron runtimes via prebuild-install, avoiding local compilation for most installs
• A minimal, promise-based API surface: getPassword, setPassword, deletePassword, findCredentials, and findPassword
• TypeScript typings shipped in the package (keytar.d.ts)

Common Use Cases

• Storing a user’s API token or session credential for an Electron desktop app
• Persisting database or service passwords for a CLI tool without writing them to a plaintext config file
• Building a password manager or credential-vault integration on top of native OS keychains

Under The Hood

Architecture - keytar is a thin native addon: a small JavaScript wrapper (lib/keytar.js) forwards five calls (getPassword, setPassword, deletePassword, findCredentials, findPassword) to a compiled keytar.node binary built from C++ sources in src/. Each OS gets its own backend file — keytar_mac.cc talks to the macOS Security framework’s Keychain APIs, keytar_posix.cc talks to libsecret/Secret Service on Linux, and keytar_win.cc talks to the Windows Credential Vault — all implementing the same KEYTAR_OP_RESULT-returning C++ interface defined in keytar.h, with async.cc bridging the synchronous native calls into async N-API work so JS callers get promises instead of blocking the event loop.

Tech Stack - Built on node-addon-api (N-API) for ABI-stable native bindings, node-gyp for compiling from source when no prebuilt binary matches, and prebuild-install/prebuild to fetch or produce per-platform, per-ABI prebuilt binaries so most npm install runs skip compilation entirely. Platform SDKs are used directly: Apple’s Security framework on macOS, libsecret on Linux, and the Windows Credential Manager API (wincred.h) on Windows.

Code Quality - The native code is compact and single-purpose (under 1,200 lines across all four backend files), with a consistent error-passing convention (std::string* errStr out-parameters) across platforms. Tests live in spec/keytar-spec.js and run via Mocha against the compiled binary, exercising the real OS keychain rather than mocks. The project has been archived since December 2022 (last commit) after GitHub sunset Atom, so no further maintenance or security patches are expected.

API Design - The public API is deliberately tiny: five verbs, each taking plain strings, each returning a promise. There is no configuration, no classes, and no setup beyond require('keytar'), which makes it trivial to adopt but leaves error handling coarse (a single rejected promise per failure mode).