Node Native Keychain

This is a TypeScript library to store and retrieve secure information from the macos keychain. It is a wrapper around the native keychain APIs on macOS built in Swift and bindings with Koffi.

Installation

npm install native-keychain

Usage

Note: For the moment, we only store Generic passwords in the keychain.

import * as keychain from 'native-keychain';

keychain.setPassword({
    service: 'my-service',
    account: 'my-account',
    password: 'my-password'
});

const secret = await keychain.getPassword({
    service: 'my-service',
    account: 'my-account',
    requireBiometrics: true
}); // 'my-password'

Available methods

Method	Description	Output
getPassword	Retrieve a password from the keychain.	Promise<string>
setPassword	Store a password in the keychain.	void
deletePassword	Delete a password from the keychain.	void
isBiometricsSupported	Check if biometrics is supported.	boolean
requestBiometricsVerification	Request biometrics verification.	Promise<boolean>

Development

Running Tests

npm run test

Note: The tests require user interaction for biometric authentication. When prompted, please authenticate using Touch ID, Face ID, or your system password to complete the biometric verification tests.

The test suite includes:

• Biometric support verification
• Password storage and retrieval with accounts
• Biometric-protected password operations
• Cleanup and error handling

Building

npm run build

Linting

npm run lint

Maintainer

Corentin Mors