Registry / auth-security / cerberus-node-client

cerberus-node-client

library4.0.0jsnpmunverified

The `cerberus-node-client` is a Node.js client library designed for secure interaction with a Cerberus Key Management backend. It facilitates storing, retrieving, and managing secrets and files programmatically. The current stable version is 4.0.0. This library is specifically tailored for environments where AWS credentials are available, leveraging the AWS SDK Credentials provider chain for authentication, which distinguishes it from generic secret management tools. It automatically handles token expiration and re-authentication, aiming for a 'just use the client' experience. While release cadence can be irregular, recent activity includes dependency updates and a major version bump with `v4.0.0`. It should not be confused with `cerberus-client` for Kubernetes/OpenShift cluster monitoring.

auth-security aws

npm install cerberus-node-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CERBERUS-NODE-CLIE

cerberus-node-client

auth-securityjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CerberusClient

✓ import { CerberusClient } from 'cerberus-node-client';

✗ const CerberusClient = require('cerberus-node-client');

Primary class for interacting with Cerberus. The package ships TypeScript types.

CerberusClientOptions

✓ import type { CerberusClientOptions } from 'cerberus-node-client';

Type definition for the options object passed to the CerberusClient constructor. Useful for strict TypeScript environments.

getSecureData

✓ const client = new CerberusClient(options); const data = await client.getSecureData('path/to/secret');

✗ import { getSecureData } from 'cerberus-node-client';

Core methods like `getSecureData` are instance methods of `CerberusClient`, not named exports directly from the package.

Instantiates the Cerberus client, authenticates using AWS credentials, and retrieves a secret from a specified SDB path. Ensure `CERBERUS_HOST`, `AWS_REGION`, and `TEST_SDB_PATH` environment variables are set.

import { CerberusClient } from 'cerberus-node-client'; async function runCerberusClient() { const cerberusHost = process.env.CERBERUS_HOST ?? 'https://your-cerberus-host.com'; const awsRegion = process.env.AWS_REGION ?? 'us-west-2'; // Or your specific region const sdbPath = process.env.TEST_SDB_PATH ?? 'app/my-sdb/my-secret'; // Example SDB path if (!cerberusHost || !awsRegion || !sdbPath) { console.error('Environment variables CERBERUS_HOST, AWS_REGION, and TEST_SDB_PATH must be set.'); process.exit(1); } try { console.log('Initializing CerberusClient...'); const client = new CerberusClient({ hostUrl: cerberusHost, region: awsRegion, debug: true // Enable debug logging for more verbose output }); console.log(`Attempting to retrieve secret from path: ${sdbPath}`); // The client automatically handles AWS authentication and token refresh const secureData = await client.getSecureData(sdbPath); console.log('Secret retrieved successfully:'); console.log(JSON.stringify(secureData, null, 2)); // Example: Accessing a specific key in the secret // console.log(`MySecretKey value: ${secureData.mySecretKey}`); } catch (error) { console.error('Failed to interact with Cerberus:', error); if (error instanceof Error) { console.error(error.message); } } } runCerberusClient();

Debug

Known issues

breakingVersion `4.0.0` officially deprecated Node.js `v12.x`. While previous versions stated compatibility, upgrading to `4.x` requires moving to a newer Node.js runtime (e.g., `v14+`).

fix

Upgrade your Node.js runtime to version 14 or higher before migrating to `cerberus-node-client` v4.0.0.

affects: >=4.0.0

gotchaUsing `cerberus-node-client` in AWS Lambda functions for runtime secret retrieval is generally discouraged due to potential latency and scale limitations. Cerberus may not handle thousands of requests per second that Lambdas often demand.

fix

For Lambda secrets, prefer AWS encrypted environmental variables or read secrets from Cerberus only at Lambda deploy time, then store them as encrypted environment variables.

affects: >=1.0.0

gotchaThe client relies on the AWS SDK Credentials provider chain for authentication. Improperly configured AWS credentials (e.g., missing environment variables, expired temporary credentials, incorrect IAM role) will lead to authentication failures.

fix

Ensure your environment has valid AWS credentials configured, either via environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`), IAM roles for EC2/Lambda, or a credentials file.

affects: >=1.0.0

breakingBeginning with `v3.4.6`, the client will now throw an error with a specific message when a request to Cerberus returns nothing (e.g., an empty or unexpected response). Previously, this might have been handled differently or silently.

fix

Update error handling logic in applications using `cerberus-node-client` to explicitly catch and manage errors that indicate no data was returned from Cerberus API calls.

affects: >=3.4.6

Errors

Common errors & fixes

CerberusClient: No AWS credentials found

The client failed to find valid AWS credentials through the SDK's credential provider chain, which is required for authenticating with Cerberus.

fix

Ensure AWS environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN), an IAM role, or a valid credentials file are accessible to the Node.js process.

Error: Secret not found at path /app/my-sdb/non-existent-secret

The requested secure data path does not exist in the Cerberus backend or the authenticated principal lacks permissions to access it.

fix

Verify the SDB path for the secret is correct and that the IAM role or user associated with your AWS credentials has appropriate read permissions in Cerberus.

FetchError: request to https://your-cerberus-host.com/v1/secret/foo/bar failed, reason: getaddrinfo ENOTFOUND your-cerberus-host.com

The Cerberus host URL specified is incorrect or unreachable, resulting in a DNS resolution failure.

fix

Double-check the `hostUrl` in `CerberusClientOptions` or the `CERBERUS_HOST` environment variable for typos, and ensure network connectivity to the Cerberus endpoint.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Nike-Inc/cerberus-node-client ↗

packagehttps://www.npmjs.com/package/cerberus-node-client ↗

homepagehttps://engineering.nike.com/cerberus/ ↗