@basic-tools/secrets-resolver

Load secrets from different sources — AWS Secrets Manager, .env files, JSON files, or in-memory data — with a single consistent API. Switch sources per environment without changing your application code.

Requires Node.js >= 26.3.0

Installation

npm install @basic-tools/secrets-resolver

Quick start

Configure once at startup (main.ts / index.ts), then call get() anywhere.

import { SecretResolver, RESOLVER_TYPES, SecretResolverByEnviromentOptions } from '@basic-tools/secrets-resolver'

const options: SecretResolverByEnviromentOptions = {
  resolverInDevelopment: { resolveFrom: RESOLVER_TYPES.environments },
  resolverInProduction:  { resolveFrom: RESOLVER_TYPES.aws },
  resolverInTest:        { resolveFrom: RESOLVER_TYPES.environments },
}

await SecretResolver.config(options)

// anywhere in your code
SecretResolver.get('DB_HOST')
SecretResolver.get('API_KEY')

AWS auto-detection — when running on ECS or Lambda (AWS_EXECUTION_ENV or the three AWS credential env vars are present), the library ignores currentEnv and always uses the aws resolver.

Resolver types

environments — process.env / .env file

Reads directly from process.env. No caching — always reflects the current value of the variable.

resolverInDevelopment: { resolveFrom: RESOLVER_TYPES.environments }

Required env vars: none beyond what your app already uses.

aws — AWS Secrets Manager

Fetches secrets from AWS and caches them in memory for the lifetime of the process.

Single secret (via env var)

# .env or system environment
AWS_REGION=us-east-1
AWS_SECRET_ID=arn:aws:secretsmanager:us-east-1:123456789012:secret:myapp/prod

resolverInProduction: { resolveFrom: RESOLVER_TYPES.aws }

Single secret (explicit — overrides env var)

resolverInProduction: {
  resolveFrom: RESOLVER_TYPES.aws,
  optionsResolveFrom: {
    secretId: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:myapp/prod',
  },
}

Multiple secrets (same account, same region)

Secrets are fetched in parallel and merged left→right — the last entry wins on key conflict.

resolverInProduction: {
  resolveFrom: RESOLVER_TYPES.aws,
  optionsResolveFrom: {
    secretIds: [
      'arn:aws:secretsmanager:us-east-1:123456789012:secret:myapp/db',
      'arn:aws:secretsmanager:us-east-1:123456789012:secret:myapp/api-keys',
      'myapp/shared-config',  // short name also works
    ],
  },
}

Merge order — if myapp/db and myapp/api-keys both define HOST, the value from myapp/api-keys is used because it appears last.

Local development with AWS

Add these to your local .env:

AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_SESSION_TOKEN=your-session-token
AWS_REGION=us-east-1
AWS_SECRET_ID=arn:aws:secretsmanager:...   # or use secretId / secretIds in config

file — JSON file

Reads a local JSON file once and caches it in memory.

resolverInDevelopment: {
  resolveFrom: RESOLVER_TYPES.file,
  optionsResolveFrom: { data: './secrets.json' },
}

secrets.json must be a flat JSON object:

{
  "DB_HOST": "localhost",
  "API_KEY": "dev-key-123"
}

data — in-memory object

Wraps a plain object. Useful for tests or when secrets are already loaded from another source.

resolverInTest: {
  resolveFrom: RESOLVER_TYPES.data,
  optionsResolveFrom: {
    data: { DB_HOST: 'localhost', API_KEY: 'test-key' },
  },
}

Environment-aware configuration

SecretResolverByEnviromentOptions lets you declare a resolver per environment. Pass currentEnv to control which one is used:

import { CURRENT_ENVS } from '@basic-tools/secrets-resolver'

const options: SecretResolverByEnviromentOptions = {
  resolverInDevelopment: { resolveFrom: RESOLVER_TYPES.environments },
  resolverInTest:        { resolveFrom: RESOLVER_TYPES.data, optionsResolveFrom: { data: mockSecrets } },
  resolverInProduction: {
    resolveFrom: RESOLVER_TYPES.aws,
    optionsResolveFrom: {
      secretIds: ['arn:...myapp/db', 'arn:...myapp/api-keys'],
    },
  },
  currentEnv: CURRENT_ENVS.development,  // omit to default to development
}

If omitted, currentEnv defaults to development. AWS auto-detection overrides this regardless of the value.

Debugging

Set RESOLVER_SECRETS_DEBUG=true to enable verbose logging — AWS account ID, secret IDs being fetched, and resolved values.

RESOLVER_SECRETS_DEBUG=true