cross-keychain

library1.1.0jsnpmunverified

cross-keychain 1.1.0 is a cross-platform secret storage library for Node.js (≥18) that provides a unified API and CLI to securely store and retrieve credentials using native OS backends: Windows Credential Manager, macOS Keychain, and Linux Secret Service. It uses native Security.framework bindings on macOS for enhanced security, with automatic fallback to CLI-based backends when native modules are unavailable. Actively maintained on GitHub, it ships TypeScript types and supports both programmatic and CLI usage. Unlike alternatives like keytar (deprecated, native bindings only) or keychain (macOS-only), cross-keychain offers broader OS support, native macOS integration, and an optional null backend for testing.

security

npm install cross-keychain

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CROSS-KEYCHAIN

cross-keychain

securityjavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

setPassword

✓ import { setPassword } from 'cross-keychain'

✗ const setPassword = require('cross-keychain').setPassword

Package ships ESM and TypeScript types, CommonJS require is also supported but not recommended for ESM projects.

getPassword

✓ import { getPassword } from 'cross-keychain'

Named export, not default.

deletePassword

✓ import { deletePassword } from 'cross-keychain'

✗ import deletePassword from 'cross-keychain'

Named export; default import is undefined.

getCredential

✓ import { getCredential } from 'cross-keychain'

Named export, returns an object with username and password.

Demonstrates storing and retrieving a secret using setPassword and getPassword with error handling.

import { setPassword, getPassword } from 'cross-keychain'; async function main() { const service = 'myapp'; const account = 'admin'; const password = process.env.SECRET ?? 'default-secret'; // Store a password await setPassword(service, account, password); console.log('Password stored'); // Retrieve the password const retrieved = await getPassword(service, account); console.log('Retrieved password:', retrieved); // Verify it matches if (retrieved === password) { console.log('Success: passwords match'); } else { console.error('Error: passwords do not match'); } } main().catch(console.error);

Debug

Known issues

breakingVersion 1.0.0 changed the API from synchronous to asynchronous functions; old synchronous calls will return a Promise and not wait for resolution.

fix

Update all calls to await setPassword, getPassword, deletePassword, and getCredential.

affects: <1.0.0

gotchaOn macOS, the native Security.framework bindings may fail if the app is not signed or has restricted entitlements; falls back to 'security' CLI, which may show a dialog or fail in CI.

fix

Sign the application with appropriate entitlements or use --backend file for CI.

affects: >=1.0.0

gotchaOn Linux, the secret-service backend requires libsecret-1-dev or similar system package; if missing, the backend fails silently and falls back to file backend, which is not protected by the OS keyring.

fix

Install libsecret-1-dev on Debian/Ubuntu (sudo apt install libsecret-1-dev) or use the file backend explicitly.

affects: >=1.0.0

deprecatedThe --password-stdin CLI flag is deprecated in favor of piping stdin directly (e.g. echo 'secret' | cross-keychain set service account).

fix

Use stdin pipe instead of --password-stdin flag.

affects: 1.0.0 - 1.0.9

gotchaThe CLI command 'del' may be ambiguous on some shells (e.g., PowerShell where 'del' is an alias for Remove-Item); ensure you invoke the correct binary (npx cross-keychain del ...) or use the full command.

fix

Use npx cross-keychain del or call the programmatic API instead.

affects: >=1.0.0

Errors

Common errors & fixes

Error: libsecret-1.so.0: cannot open shared object file: No such file or directory

Missing libsecret library on Linux required for secret-service backend.

fix

Install libsecret-1-dev (Debian/Ubuntu) or equivalent (libsecret-devel on Fedora).

TypeError: Cannot read properties of undefined (reading 'then')

Calling setPassword or getPassword without await in an async context, trying to treat a Promise as sync.

fix

Add await before calls: await setPassword(...) or use .then()

Error: No backends available

No supported backend found (e.g., on a headless Linux without libsecret and no file backend configured).

fix

Install a supported backend (libsecret on Linux) or use --backend file to force file storage.

Error: The user cancelled the operation

On macOS, the Keychain access dialog was cancelled by the user or timed out in a non-interactive session.

fix

Use --backend file or set the KEYCHAIN_ALLOW_USER_INTERACTION environment variable to 0 to disable dialogs.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

node-gypoptionalRequired to compile native bindings for macOS Keychain

Agent activity

34 hits · last 30 days

node

Resources

githubhttps://github.com/magarcia/cross-keychain ↗

packagecross-keychain ↗

homepagehttps://github.com/magarcia/cross-keychain#readme ↗