{"id":47345,"library":"cross-keychain","title":"cross-keychain","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/magarcia/cross-keychain","tags":["javascript","cross-keychain","secrets","storage","encryption","cross-platform","credential locker","secret service","keychain","typescript"],"install":[{"cmd":"npm install cross-keychain","lang":"bash","label":"npm"},{"cmd":"yarn add cross-keychain","lang":"bash","label":"yarn"},{"cmd":"pnpm add cross-keychain","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to compile native bindings for macOS Keychain","package":"node-gyp","optional":true}],"imports":[{"note":"Package ships ESM and TypeScript types, CommonJS require is also supported but not recommended for ESM projects.","wrong":"const setPassword = require('cross-keychain').setPassword","symbol":"setPassword","correct":"import { setPassword } from 'cross-keychain'"},{"note":"Named export, not default.","wrong":null,"symbol":"getPassword","correct":"import { getPassword } from 'cross-keychain'"},{"note":"Named export; default import is undefined.","wrong":"import deletePassword from 'cross-keychain'","symbol":"deletePassword","correct":"import { deletePassword } from 'cross-keychain'"},{"note":"Named export, returns an object with username and password.","wrong":null,"symbol":"getCredential","correct":"import { getCredential } from 'cross-keychain'"}],"quickstart":{"code":"import { setPassword, getPassword } from 'cross-keychain';\n\nasync function main() {\n  const service = 'myapp';\n  const account = 'admin';\n  const password = process.env.SECRET ?? 'default-secret';\n\n  // Store a password\n  await setPassword(service, account, password);\n  console.log('Password stored');\n\n  // Retrieve the password\n  const retrieved = await getPassword(service, account);\n  console.log('Retrieved password:', retrieved);\n\n  // Verify it matches\n  if (retrieved === password) {\n    console.log('Success: passwords match');\n  } else {\n    console.error('Error: passwords do not match');\n  }\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Demonstrates storing and retrieving a secret using setPassword and getPassword with error handling."},"warnings":[{"fix":"Update all calls to await setPassword, getPassword, deletePassword, and getCredential.","message":"Version 1.0.0 changed the API from synchronous to asynchronous functions; old synchronous calls will return a Promise and not wait for resolution.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Sign the application with appropriate entitlements or use --backend file for CI.","message":"On 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install libsecret-1-dev on Debian/Ubuntu (sudo apt install libsecret-1-dev) or use the file backend explicitly.","message":"On 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use stdin pipe instead of --password-stdin flag.","message":"The --password-stdin CLI flag is deprecated in favor of piping stdin directly (e.g. echo 'secret' | cross-keychain set service account).","severity":"deprecated","affected_versions":"1.0.0 - 1.0.9"},{"fix":"Use npx cross-keychain del or call the programmatic API instead.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.1.0':7 '18':18 'activ':68 'altern':84 'api':23 'automat':56 'backend':35,62,110 'base':61 'bind':49,89 'broader':100 'cli':25,60,81 'cli-bas':59 'credenti':31,37,123 'cross':2,5,11,97,115,121 'cross-keychain':1,4,96,114 'cross-platform':10,120 'deprec':87 'encrypt':119 'enhanc':53 'fallback':57 'github':71 'integr':105 'javascript':113 'keychain':3,6,40,92,98,116,127 'keytar':86 'librari':15 'like':85 'linux':42 'locker':124 'maco':39,51,94,104 'macos-on':93 'maintain':69 'manag':38 'modul':65 'nativ':33,47,64,88,103 'node.js':17 'null':109 'offer':99 'option':108 'os':34,101 'platform':12,122 'programmat':79 'provid':20 'retriev':30 'secret':13,43,117,125 'secur':27,54 'security.framework':48 'servic':44,126 'ship':73 'storag':14,118 'store':28 'support':77,102 'test':112 'type':75 'typescript':74,128 'unavail':67 'unifi':22 'unlik':83 'usag':82 'use':32,46 'window':36","created_at":"2026-06-07T16:51:03.440894+00:00","updated_at":"2026-06-07T16:51:03.440894+00:00","problems":[{"fix":"Install libsecret-1-dev (Debian/Ubuntu) or equivalent (libsecret-devel on Fedora).","cause":"Missing libsecret library on Linux required for secret-service backend.","error":"Error: libsecret-1.so.0: cannot open shared object file: No such file or directory"},{"fix":"Add await before calls: await setPassword(...) or use .then()","cause":"Calling setPassword or getPassword without await in an async context, trying to treat a Promise as sync.","error":"TypeError: Cannot read properties of undefined (reading 'then')"},{"fix":"Install a supported backend (libsecret on Linux) or use --backend file to force file storage.","cause":"No supported backend found (e.g., on a headless Linux without libsecret and no file backend configured).","error":"Error: No backends available"},{"fix":"Use --backend file or set the KEYCHAIN_ALLOW_USER_INTERACTION environment variable to 0 to disable dialogs.","cause":"On macOS, the Keychain access dialog was cancelled by the user or timed out in a non-interactive session.","error":"Error: The user cancelled the operation"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/magarcia/cross-keychain#readme","github":"https://github.com/magarcia/cross-keychain","docs":null,"changelog":null,"pypi":null,"npm":"cross-keychain","openapi_spec":null,"status_page":null,"smithery":null,"categories":["security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}