Azure Key Vault

Node library to handle Azure Key Vault secrets by project, environment and group (when a vault is shared), as nested JSON. Every failure is classified and logged at its level, and the library says who it signed in as, so a missing vault, an identity without access and a missing secret never look the same.

ESM only, Node.js 22.12 or later.

How To Use 💡

import { AzureKeyVault } from '@achs/azure-key-vault';

// DefaultAzureCredential: environment variables, workload or
// managed identity, Azure CLI ("az login")...
const keyVault = new AzureKeyVault({
    vaultUrl: 'https://my-key-vault.vault.azure.net',
    project: 'my-project',
    group: 'web',
    env: 'dev',
});

await keyVault.setAll({
    SECRET1: 'my secret 1',
    otherConfig: { SECRET2: 'my secret 2' },
});

const secrets = await keyVault.getFor({
    SECRET1: null,
    otherConfig: { SECRET2: null },
    SECRET3: 'default for secret 3',
});
// { SECRET1: 'my secret 1', otherConfig: { SECRET2: 'my secret 2' }, SECRET3: 'default for secret 3' }
// typed with the shape of the input: secrets.otherConfig.SECRET2

Options

A service principal with only some of its values throws a TypeError, naming the missing ones, and so do invalid concurrency, timeoutMs or expiryWarningDays values. The library never writes process.env.

Secret names

A key maps to the secret project-group-env-key, lowercase, with _ and spaces turned into - (toSecretName(scope, key) gives it).

• : (or --) nests a key: car:props:name is { car: { props: { name } } }.
• A last segment starting with $ is shared by every group (app) of the project, in the same environment: parent:$global_var maps to project-env-parent--global-var. It is not shared with other projects. Without a group, KEY and $KEY map to the same secret.
• A key that does not map to a valid secret name (letters, digits and dashes, up to 127) fails before any request; a scoped package name as group (@scope/name) does too, so set AZURE_GROUP.
• The scope (project, group, environment) compares like names do, whatever case or spaces it was written with (normalizeScope): My App and my-app are one group, and tags are written normalized.

Tags

Every secret carries tags that rebuild its key and scope (project, group, env, name, path), plus:

A JSON value (anything but a string) also has contentType: application/json, and is parsed when either says so. updated-by comes from the identity the library signed in with (it asks for a token before its first write); with an injected client it is left out.

Logging and traceability 🔎

Every failure is classified (AzureKeyVaultErrorKind) and logged at its level, naming the vault and the secrets it affects. Values are never logged, only secret names.

What each level shows:

• error / warn: one line per cause, with every secret it affects. A forbidden line names the identity the vault saw (appid/oid), the permission and role the operation needs (Key Vault Secrets User to read and list, Key Vault Secrets Officer to write) and who the library signed in as.
• warn also: secrets read that are expired, not valid yet (Key Vault gives them anyway) or about to expire (expiryWarningDays).
• info: who the library signed in as (authenticated as user [email protected] (tenant ...), from the first token: user, service principal or managed identity), the summary of every operation over many secrets (read 3 of 5 secrets, 1 not found or disabled, 1 failed), and the result of check().
• debug: each secret read, written, deleted, purged or restored.
• trace: the original Azure SDK error of each cause.

keyVault.identity gives the identity once known (only when the library builds the client).

Where the logs go

• An injected logger receives every level and filters itself, so a host application keeps one log level for everything. @achs/env passes its own tslog logger this way. Set logLevel to filter it here too.
• Without a logger, the library writes to the console with a [akv] prefix, from logLevel, else the AKV_LOG_LEVEL environment variable, else warn.

const keyVault = new AzureKeyVault({
    vaultUrl,
    project: 'my-project',
    env: 'dev',
    logger: parentLogger.getSubLogger({ name: 'akv' }),
});

Failures and strict

• Reads and maintenance (get, getFor, getAll, keys, versions, delete, purge, restore and the *All functions) log their failures and go on: a value that could not be read keeps its default (or null). With strict: true, an error level failure throws an AzureKeyVaultError once everything is logged; a missing or disabled secret only warns.
• Writes (set, setAll, rollback) and getInfo always throw an AzureKeyVaultError.

import { AzureKeyVaultError } from '@achs/azure-key-vault';

try {
    await keyVault.getFor(schema);
} catch (error) {
    if (error instanceof AzureKeyVaultError)
        console.error(error.kind, error.vaultUrl, error.secretNames);
}

classifyError(error) gives the kind of any error the Azure SDK throws.

check()

Diagnoses a vault with a single request for a secret that should not exist: it passes when the vault host resolves and answers, the identity authenticates and may read secrets, and it says who signed in. It never throws.

const { ok, kind, message, identity } = await keyVault.check();
// { ok: false, kind: 'forbidden', identity: { type: 'service-principal', appId: '...' }, message: 'https://...: the identity appid=... lacks the "get" secret permission (...), signed in as service principal appid=...' }

Network: DNS check, VPN and proxies

Before its first request, the library resolves the vault host once with the system DNS, the one every request uses (a VPN's DNS included): a host that does not resolve fails at once as vault-not-found, instead of after the retries of each request. It never contradicts the requests, unlike a check against public DNS servers, which a VPN may block. It is skipped when a proxy resolves the host instead (clientOptions.proxyOptions, or HTTPS_PROXY/HTTP_PROXY/ALL_PROXY), with an injected client, and with dnsCheck: false.

concurrency caps the requests at once (a shared vault throttles all of its callers), timeoutMs bounds each operation, and clientOptions reaches the Azure client (retries, proxy). The user agent carries @achs/azure-key-vault/<version>, so the vault's diagnostic logs tell who called.

Functions 🧰

getFor reads only the keys whose default is empty (null, '', 0, false), or every key with override; a secret stored as JSON (an array, an object, a number) comes back parsed.

const secrets = await keyVault.getFor({
    '$global-var': null,
    'my-secret': null,
    'my-secret-2': 'default value',
    'my-secret-group1': { 'my-secret-3': null },
    'my-array-secret': null,
});

Audit

audit() lists the vault once (names, tags and dates; never values) and reports, for the project or with allProjects for the whole vault, a summary (secrets, managed by the library, tagged, untagged, projects, groups, by environment) and these findings, logged at their level:

auditSecrets(properties, options) runs the same checks over secret properties listed elsewhere.

Testing with the mock

createAzureKeyVaultMock(options, { faults }) gives a handler over an in-memory vault shared by every mock, that fails like Azure does (a missing secret is a secret-not-found). faults injects failures by key, or for every request with '*'; resetAzureKeyVaultMock() empties the vault.

const vault = createAzureKeyVaultMock(
    { project: 'app', env: 'dev' },
    { faults: { DB_PASS: 'forbidden', '*': 'timeout' } },
);

Command 💻

The akv command runs the same operations. Logs go to stderr (at info unless --log says otherwise) and output to stdout.

Exit codes: 0 success, 2 vault not found, unreachable or timed out, 3 no usable identity, 4 permission denied, 1 anything else. Reads only fail the command with --strict (or when get, list or versions read nothing).

akv check --uri=https://my-key-vault.vault.azure.net --project=my-project --env=dev --json
printf '%s' "$DB_PASS" | akv set --uri=... --project=my-project --env=dev --key=DB_PASS
akv getfor --uri=... --project=my-project --env=dev --file=structure.json --output=secrets.json --log=debug

runCli(argv) runs the same command from code, and exitCode(kind) maps a failure kind to its code.

Development 🧿

pnpm test:cov   # Vitest with coverage (100% thresholds)
pnpm lint       # ESLint
pnpm typecheck  # TypeScript
pnpm format     # Prettier
pnpm build      # Vite library build into dist/

Changelog 📄

For last changes see CHANGELOG.md.

Built with 🛠️

• @azure/identity - Azure identity provider.
• @azure/keyvault-secrets - Azure Key Vault secrets client.