WiseKey

A lightweight key management library and CLI for Node.js. WiseKey stores secrets in a local SQLite database, encrypts them with a master key saved in the operating system keychain, and supports manual or scheduled key rotation.

Features

• Secure storage: Secrets are encrypted with AES-256-GCM before being written to SQLite.
• Native keychain integration: The master encryption key is stored with cross-keychain.
• Key rotation: Supports both manual and scheduled automatic rotation via cron expressions.
• Singleton design: Initialize once and reuse the same instance across your app.
• TypeScript support: Fully typed API surface.

Installation

npm install wisekey

Usage

Initialization

Initialize WiseKey once in your application startup. It requires a configuration object with the application name used for the keychain entry and the path to the SQLite database file.

import { WiseKey } from 'wisekey';

async function bootstrap() {
  const wiseKey = await WiseKey.init({
    name: 'my-app-secrets', // Name used in the OS keychain
    path: './secrets.sqlite', // Path to the SQLite database
  });

  console.log('WiseKey initialized successfully!');
}

bootstrap();

Storing and Retrieving Secrets

Once initialized, you can store, retrieve, and delete secrets.

import { WiseKey } from 'wisekey';

async function manageSecrets() {
  // Get the initialized instance
  // Note: You must call WiseKey.init() before using it elsewhere
  const wiseKey = await WiseKey.init({ name: 'my-app-secrets', path: './secrets.sqlite' });

  // Store a secret
  await wiseKey.set('api_key', '<API_KEY_PLACEHOLDER>');
  console.log('Secret stored.');

  // Retrieve a secret
  const apiKey = await wiseKey.get('api_key');
  console.log('Retrieved API Key:', apiKey);

  // Delete a secret
  await wiseKey.delete('api_key');
  console.log('Secret deleted.');
}

Key Rotation

WiseKey allows you to rotate the master encryption key. When rotated, all stored secrets are decrypted with the old key and re-encrypted with the new key, and the new master key is saved to the OS keychain.

Manual Rotation

You can trigger a rotation manually at any time. You can optionally provide a new 32-byte hex string, or let WiseKey generate a secure one automatically.

import { WiseKey } from 'wisekey';

async function rotateManually() {
  const wiseKey = await WiseKey.init({ name: 'my-app-secrets', path: './secrets.sqlite' });

  console.log('Starting manual rotation...');
  await wiseKey.rotate(); // Automatically generates a new master key
  console.log('Rotation complete!');
}

Automatic Rotation

You can configure WiseKey to automatically rotate the master key on a schedule using a cron expression.

import { WiseKey } from 'wisekey';

async function setupAutoRotation() {
  const wiseKey = await WiseKey.init({
    name: 'my-app-secrets',
    path: './secrets.sqlite',
    autoRotateCron: '0 0 1 * *', // Rotate at midnight on the 1st of every month
  });

  console.log('WiseKey initialized with auto-rotation.');

  // If you need to stop the auto-rotation later:
  // wiseKey.stopAutoRotation();
}

CLI Usage

WiseKey also provides a command-line interface for loading secrets from a .env file and rotating the master key for a service.

Load a .env file

Import key-value pairs from a .env file into a service:

wisekey <serviceName> load -env [path]

If path is omitted, WiseKey uses .env in the current working directory.

Rotate the master key

Rotate the master key for a service from the CLI:

wisekey <serviceName> rotate [newKey]

If newKey is omitted, WiseKey generates a new secure master key automatically.

The CLI does not expose secret read, write, delete, or service deletion commands. Use the library API for those operations.

API Reference

WiseKey.init(config: WiseKeyConfig): Promise<WiseKey>

Initializes the WiseKey instance. Must be called at least once before using the instance.

• config.name: string - The identifier used to store the master key in the OS keychain.
• config.path: string - The file path for the SQLite database.
• config.autoRotateCron (optional): string - A cron expression to schedule automatic key rotation.

wiseKey.set(keyName: string, value: string): Promise<void>

Encrypts and stores a secret.

wiseKey.get(keyName: string): Promise<string | null>

Retrieves and decrypts a secret. Returns null if the secret does not exist.

wiseKey.delete(keyName: string): Promise<void>

Deletes a secret from the database.

wiseKey.rotate(newKeyHex?: string): Promise<void>

Rotates the master encryption key. Re-encrypts all stored secrets. If newKeyHex is not provided, a new secure key is generated automatically.

wiseKey.stopAutoRotation(): void

Stops the scheduled auto-rotation task if one was configured during initialization.

wiseKey.close(): void

Stops auto-rotation, closes the database, and releases the singleton instance.

License

ISC