Cloud

Secrets Management

AES-256-GCM authenticated encryption for secrets held in memory, with key generation and a warn-once ephemeral key for development.

3 min readUpdated DocumentationEdit this page
On this page7

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

TypeScript
TS
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:

TypeScript
TS
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:

TypeScript
TS
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

OptionTypeDefaultDescription
encryptionKeystringRandom per process64-character hex string (32 bytes)

API Reference

MethodReturnsDescription
set(name, plaintext)Promise<void>Encrypt and store
get(name)Promise<string | null>Decrypt and return, or null if missing
has(name)booleanCheck existence without decrypting
delete(name)booleanRemove a secret; true if it existed
list()Array<{ name, createdAt, updatedAt }>Enumerate names; values are never exposed
SecretsManager.generateKey()stringCreate a new 64-character hex key

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY