@wgtechlabs/secrets-engine

Keep your secrets truly secret. With encrypted names and values, zero friction, and strict security by default, secrets‑engine gives developers defense‑in‑depth without the hassle. It’s a TypeScript SDK for secure secret storage, powered by machine‑bound AES‑256‑GCM and hardened SQLite.

Features

• Zero friction — No passphrase, no setup wizard. Works out of the box.
• Maximum privacy — Both key names and values are encrypted. No metadata leakage.
• Machine-bound — Encryption keys are derived from machine identity + random keyfile via scrypt.
• Defense in depth — Filesystem permission verification, HMAC integrity checks, per-entry unique IVs.
• Bun-native — Built on bun:sqlite and Node crypto. Zero external runtime dependencies.

Installation

bun add @wgtechlabs/secrets-engine

Quick Start

import { SecretsEngine } from "@wgtechlabs/secrets-engine";

// Open or create a store (defaults to ~/.secrets-engine/)
const secrets = await SecretsEngine.open();

// Store secrets with dot-notation namespacing
await secrets.set("openai.apiKey", "sk-...");
await secrets.set("anthropic.apiKey", "sk-ant-...");

// Retrieve
const key = await secrets.get("openai.apiKey"); // "sk-..."

// Check existence (no decryption needed — HMAC lookup)
await secrets.has("openai.apiKey"); // true

// List keys with glob patterns
await secrets.keys("openai.*"); // ["openai.apiKey"]

// Delete
await secrets.delete("openai.apiKey");

// Clean up
await secrets.close();

Storage Location

The SDK resolves the storage directory using this priority order:

Priority	Option	Path
1 (highest)	{ path: "/custom/path" }	Explicit path
2	{ location: "xdg" }	~/.config/secrets-engine/
3 (default)	(none)	~/.secrets-engine/

// XDG-aware
const secrets = await SecretsEngine.open({ location: "xdg" });

// Custom path
const secrets = await SecretsEngine.open({ path: "/opt/myapp/secrets" });

API Reference

SecretsEngine.open(options?)

Open or create a secrets store. Returns a Promise<SecretsEngine>.

secrets.get(key)

Retrieve a decrypted secret value. Returns string | null.

secrets.getOrThrow(key)

Retrieve a decrypted secret, throwing KeyNotFoundError if missing.

secrets.set(key, value)

Store an encrypted secret.

secrets.has(key)

Check if a key exists via HMAC hash lookup (no decryption).

secrets.delete(key)

Remove a secret. Returns true if deleted, false if not found.

secrets.keys(pattern?)

List all key names, optionally filtered by glob pattern (e.g., "openai.*").

secrets.destroy()

Irreversibly delete the entire store, keyfile, and directory.

secrets.close()

Close the database connection and release resources. This method is async and must be awaited.

Returns a Promise<void> that resolves when the database is closed and integrity is finalized.

Breaking Change (v2.0.0): This method is now async. Update your code to await secrets.close().

secrets.size

Number of secrets currently stored.

secrets.storagePath

Absolute path to the storage directory.

Security Model

Layer	Protection
Encryption	AES-256-GCM with unique IV per entry
Key derivation	scrypt (N=2¹⁷, r=8, p=1) from machine ID + random keyfile
Key name privacy	Both names and values encrypted; HMAC-SHA256 index
File permissions	Strict verification on open (700/600/400)
Integrity	HMAC-SHA256 of database contents in meta.json
Machine binding	Hostname + MAC + username + random keyfile

Error Types

Error	When
SecurityError	File permissions too permissive
IntegrityError	Database HMAC verification fails
KeyNotFoundError	getOrThrow() for missing key
DecryptionError	Corrupted entry or wrong key
InitializationError	Cannot create store directory

All errors extend SecretsEngineError with a .code property.

Development

bun install
bun test
bun run typecheck
bun run lint

License

MIT — WG Tech Labs