securedbg 🛡️

A robust, cross-platform solution for securely storing credentials, API keys, and other secrets in Node.js applications.

securedbg leverages the operating system’s native secure storage mechanisms (such as Keychain on macOS, Credential Manager on Windows, or Keyring/Secret Service on Linux) whenever available. In environments where native storage is not present (e.g., headless servers), it falls back to an AES-256-GCM encrypted local file, protected by a master password.

✨ Why use securedbg?

• Security by Default: Prevents secrets from being stored in plaintext, environment variables, or unencrypted config files.
• Cross-Platform: Works consistently across macOS, Windows, and Linux—both on desktops and servers.
• Simple, Intuitive API: Manage secrets with only three async methods: setSecret, getSecret, and deleteSecret.
• Smart Fallback: Automatically detects and chooses the best storage strategy without manual setup.
• Zero Runtime Dependencies (besides keytar): Lightweight and focused on doing one thing well.

📦 Installation

Install with npm or yarn:

npm install securedbg
# or
yarn add securedbg

🚀 Quick Start

Using securedbg is straightforward. First, import and instantiate the SecuredBG class with a unique service name for your application.

// Import the class
const SecuredBG = require('securedbg');

// 1. Create an instance with a unique service name
const storage = new SecuredBG('my-awesome-app');

// Example async function
async function manageMySecrets() {
  const apiKeyName = 'my-service-api-key';

  try {
    // 2. Store a secret
    console.log('Storing API key...');
    await storage.setSecret(apiKeyName, 'super-secret-value-12345');
    console.log('API key stored successfully!');

    // 3. Retrieve the secret
    console.log('Retrieving API key...');
    const apiKey = await storage.getSecret(apiKeyName);

    if (apiKey) {
      console.log(`API key retrieved: ${apiKey}`);
      // Use the key to connect to your service
    } else {
      console.log('API key not found.');
    }

    // 4. Delete the secret
    console.log('Deleting API key...');
    const wasDeleted = await storage.deleteSecret(apiKeyName);
    if (wasDeleted) {
      console.log('API key deleted successfully.');
    }

  } catch (error) {
    console.error('An error occurred while managing the secret:', error);
  }
}

manageMySecrets();

🔑 Master Password (Fallback Mode)

If securedbg does not detect a native keychain, it creates an encrypted file in the user’s home directory (e.g., ~/.my-awesome-app.secrets.enc).

On the first attempt to store a secret (setSecret), the terminal will prompt you to create and confirm a master password. This password is used to encrypt and decrypt the file. The password is cached in memory during the process to avoid repeated prompts.

📖 API

new SecuredBG(serviceName)

Creates a new secret manager instance.

• serviceName (string, required): A unique identifier for your application.

async setSecret(name, secret)

Stores or updates a secret.

• name (string, required): The secret’s identifier (e.g., 'databasePassword').
• secret (string, required): The secret value.
• Returns: Promise<void>

async getSecret(name)

Retrieves a secret.

• name (string, required): The secret’s identifier.
• Returns: Promise<string|null> – the secret value, or null if not found.

async deleteSecret(name)

Deletes a secret permanently.

• name (string, required): The secret’s identifier.
• Returns: Promise<boolean> – true if successfully deleted, false if not found.

🤝 Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

1. Fork the project: securedbg on GitHub
2. Create your feature branch:

   git checkout -b feature/AmazingFeature

3. Commit your changes:

   git commit -m 'Add some AmazingFeature'

4. Push to the branch:

   git push origin feature/AmazingFeature

5. Open a Pull Request

📜 License

Distributed under the MIT License. See LICENSE.txt for details.