{"id":12950,"library":"cerberus-node-client","title":"Cerberus Node Client","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/Nike-Inc/cerberus-node-client","tags":["javascript","nike","cerberus","typescript"],"install":[{"cmd":"npm install cerberus-node-client","lang":"bash","label":"npm"},{"cmd":"yarn add cerberus-node-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add cerberus-node-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary class for interacting with Cerberus. The package ships TypeScript types.","wrong":"const CerberusClient = require('cerberus-node-client');","symbol":"CerberusClient","correct":"import { CerberusClient } from 'cerberus-node-client';"},{"note":"Type definition for the options object passed to the CerberusClient constructor. Useful for strict TypeScript environments.","symbol":"CerberusClientOptions","correct":"import type { CerberusClientOptions } from 'cerberus-node-client';"},{"note":"Core methods like `getSecureData` are instance methods of `CerberusClient`, not named exports directly from the package.","wrong":"import { getSecureData } from 'cerberus-node-client';","symbol":"getSecureData","correct":"const client = new CerberusClient(options);\nconst data = await client.getSecureData('path/to/secret');"}],"quickstart":{"code":"import { CerberusClient } from 'cerberus-node-client';\n\nasync function runCerberusClient() {\n  const cerberusHost = process.env.CERBERUS_HOST ?? 'https://your-cerberus-host.com';\n  const awsRegion = process.env.AWS_REGION ?? 'us-west-2'; // Or your specific region\n  const sdbPath = process.env.TEST_SDB_PATH ?? 'app/my-sdb/my-secret'; // Example SDB path\n\n  if (!cerberusHost || !awsRegion || !sdbPath) {\n    console.error('Environment variables CERBERUS_HOST, AWS_REGION, and TEST_SDB_PATH must be set.');\n    process.exit(1);\n  }\n\n  try {\n    console.log('Initializing CerberusClient...');\n    const client = new CerberusClient({\n      hostUrl: cerberusHost,\n      region: awsRegion,\n      debug: true // Enable debug logging for more verbose output\n    });\n\n    console.log(`Attempting to retrieve secret from path: ${sdbPath}`);\n    // The client automatically handles AWS authentication and token refresh\n    const secureData = await client.getSecureData(sdbPath);\n\n    console.log('Secret retrieved successfully:');\n    console.log(JSON.stringify(secureData, null, 2));\n    // Example: Accessing a specific key in the secret\n    // console.log(`MySecretKey value: ${secureData.mySecretKey}`);\n\n  } catch (error) {\n    console.error('Failed to interact with Cerberus:', error);\n    if (error instanceof Error) {\n      console.error(error.message);\n    }\n  }\n}\n\nrunCerberusClient();","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 14 or higher before migrating to `cerberus-node-client` v4.0.0.","message":"Version `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+`).","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Using `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Beginning 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.","severity":"breaking","affected_versions":">=3.4.6"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The client failed to find valid AWS credentials through the SDK's credential provider chain, which is required for authenticating with Cerberus.","error":"CerberusClient: No AWS credentials found"},{"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.","cause":"The requested secure data path does not exist in the Cerberus backend or the authenticated principal lacks permissions to access it.","error":"Error: Secret not found at path /app/my-sdb/non-existent-secret"},{"fix":"Double-check the `hostUrl` in `CerberusClientOptions` or the `CERBERUS_HOST` environment variable for typos, and ensure network connectivity to the Cerberus endpoint.","cause":"The Cerberus host URL specified is incorrect or unreachable, resulting in a DNS resolution failure.","error":"FetchError: request to https://your-cerberus-host.com/v1/secret/foo/bar failed, reason: getaddrinfo ENOTFOUND your-cerberus-host.com"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}