@benefi/secrets

Load secrets from AWS Secrets Manager and expose them by app-defined names. Fetches by AWS secret id (e.g. STG_BACKEND_URL), stores under a secret name (e.g. BACKEND_URL) so your app uses stable keys.

Installation

npm install @benefi/secrets
# or
yarn add @benefi/secrets

Requires: AWS_REGION must be set in the environment (or the AWS SDK will resolve region via its default chain).

Quick start

import { secretsManager } from "@benefi/secrets";

// 1. Pass a dictionary: secret name (app key) → AWS secret id
await secretsManager.loadSecrets({
  BACKEND_URL: "STG_BACKEND_URL",
  JWT_SECRET: "STG_JWT_SECRET",
});

// 2. Read by secret name (the key you chose)
const backendUrl = secretsManager.getSecret("BACKEND_URL");
const jwtSecret = secretsManager.getSecret("JWT_SECRET");

API

secretsManager (singleton)

Pre-built instance of SecretsManager. Use it when you’re fine with the default client (region from process.env.AWS_REGION).

SecretsManager (class)

• Constructor
  Requires process.env.AWS_REGION to be set; otherwise throws.

• loadSecrets(config: SecretsConfig): Promise<void>
  Fetches secrets from AWS (via BatchGetSecretValue, in batches of 20) and stores them by secret name.

  • config = dictionary: secret name (app key) → AWS secret id (e.g. { BACKEND_URL: "STG_BACKEND_URL" }).
  • Response order from AWS is not guaranteed; entries are matched by secret id (Name/ARN).
  • Throws if any requested secret fails to load or has no string/binary value.

• getSecret(secretName: string, versionId?: string): Promise<string | null>
  Returns the secret value for secretName.

  • Must call loadSecrets first.
  • If versionId is passed and differs from the cached version, the secret is fetched again for that version (and cache may be updated).
  • Throws if not loaded or secret not configured.

• reloadSecret(secretName: string): Promise<boolean>
  Re-fetches a single secret from AWS and updates the cached value.

  • Uses the stored secretId for that secretName.
  • Returns true if the value changed, false if unchanged.
  • Throws if secretName was never loaded or the fetch fails.

Types

Exported from the package:

• SecretsConfig

  type SecretsConfig = Record<string, string>;
  // e.g. { BACKEND_URL: "STG_BACKEND_URL", JWT_SECRET: "STG_JWT_SECRET" }

• SecretConfigItem

  type SecretConfigItem = {
    value: string;
    versionId: string;
    createdDate: Date;
    stages: string[];
    secretId: string; // AWS secret id (used for reload)
  };

AWS configuration

Uses @aws-sdk/client-secrets-manager. Ensure the runtime can authenticate:

• Environment: e.g. AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, or
• Instance/role: EC2 instance profile, ECS task role, Lambda execution role, etc.

AWS_REGION is required by this package’s constructor.

License

MIT