Secrets Management
AES-256-GCM authenticated encryption for secrets held in memory, with key generation and a warn-once ephemeral key for development.
Overview
SecretsManager encrypts and decrypts sensitive values with AES-256-GCM,
authenticated encryption that protects against both eavesdropping and
tampering. Encrypted secrets are kept in an in-memory store on the instance.
Usage
1import { SecretsManager } from '@axiljs/cloud'
2
3const secrets = new SecretsManager({
4 encryptionKey: process.env.SECRETS_ENCRYPTION_KEY,
5})
6
7await secrets.set('DATABASE_URL', 'postgres://user:pass@host/db')
8const dbUrl = await secrets.get('DATABASE_URL') // string | null
9
10secrets.has('DATABASE_URL') // true
11
12secrets.list()
13// [{ name: 'DATABASE_URL', createdAt: '...', updatedAt: '...' }]set() and get() are async; has(), delete(), and list() are synchronous.
Calling set() again for an existing name keeps its createdAt and updates
updatedAt.
Key Generation
Generate a cryptographically secure 32-byte encryption key:
const key = SecretsManager.generateKey()
// 64 hex characters, e.g. 'a3f1b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0'encryptionKey must decode to exactly 32 bytes (64 hex characters); otherwise
the constructor throws. Store the key in an environment variable or KMS.
Never commit it to source control.
Global Singleton
For convenience, a shared instance is exported:
1import { secrets } from '@axiljs/cloud'
2
3await secrets.set('API_KEY', 'sk-...')
4const key = await secrets.get('API_KEY')The singleton has no encryptionKey, so it uses a random key generated at
startup. Secrets it stores cannot be decrypted after a restart. Create your own
SecretsManager with encryptionKey in production.
Ephemeral Key Warning
When no encryptionKey is given, a random key is generated and a warning is
printed with console.warn, once per instance, the first time set() is
called. Constructing the instance, or importing @axiljs/cloud (which builds the
secrets singleton), prints nothing.
Note
Changed in 0.3.3: the warning used to be printed at construction, so every
app that imported @axiljs/cloud saw it even if it never used secrets. It now
appears only on first use of an auto-generated key. If you relied on seeing it
at startup to catch a missing key, check for the key explicitly instead.
Options
| Option | Type | Default | Description |
|---|---|---|---|
encryptionKey | string | Random per process | 64-character hex string (32 bytes) |
API Reference
| Method | Returns | Description |
|---|---|---|
set(name, plaintext) | Promise<void> | Encrypt and store |
get(name) | Promise<string | null> | Decrypt and return, or null if missing |
has(name) | boolean | Check existence without decrypting |
delete(name) | boolean | Remove a secret; true if it existed |
list() | Array<{ name, createdAt, updatedAt }> | Enumerate names; values are never exposed |
SecretsManager.generateKey() | string | Create a new 64-character hex key |
Was this page helpful?