AWS Lambda Secret Fetcher

A lightweight TypeScript library for fetching secrets from AWS Secrets Manager using the AWS Parameters and Secrets Lambda Extension.

Features

• Uses the local Lambda Extension API (no AWS SDK required)
• Retry with timeout and full jitter backoff via fetch-retrier
• Configurable timeout, retries, and base backoff
• Automatic JSON parsing for secret values
• TypeScript support with generics

Installation

npm

npm install aws-lambda-secret-fetcher

yarn

yarn add aws-lambda-secret-fetcher

Prerequisites

Your Lambda function must have the AWS Parameters and Secrets Lambda Extension layer attached.

Usage

Basic Usage

import { secretFetcher } from 'aws-lambda-secret-fetcher';

// Get a plain string secret
const apiKey = await secretFetcher.getSecretValue('my-api-key');

// Get a JSON secret with type inference
interface DbCredentials {
  username: string;
  password: string;
  host: string;
}

const credentials = await secretFetcher.getSecretValue<DbCredentials>('my-db-credentials');
console.log(credentials.username); // Type-safe access

With Options

import { secretFetcher, type GetSecretValueOptions } from 'aws-lambda-secret-fetcher';

const options: GetSecretValueOptions = {
  timeoutMs: 3000,
  retries: 5,
  baseBackoffMs: 500,
};

const secret = await secretFetcher.getSecretValue('my-secret', options);

Options

Option	Type	Default	Description
timeoutMs	number	2000	Request timeout in milliseconds per attempt
retries	number	3	Maximum number of attempts (including the first request)
baseBackoffMs	number	300	Base delay in milliseconds for backoff between retries

API

The package exports secretFetcher, an object that provides:

secretFetcher.getSecretValue<T>(name, options?)

Fetches a secret value from AWS Secrets Manager via the Lambda Extension.

Parameters

Parameter	Type	Description
name	string	The name or ARN of the secret
options	GetSecretValueOptions	Optional timeout, retries, and backoff settings

Returns

• Promise<T> — The secret value. If the secret is a JSON string, it is automatically parsed as T.

Throws

• Error — If the secret cannot be retrieved after all retries, or if the response format is invalid.

Retry Behavior

Retries use full jitter exponential backoff. The library retries on:

• HTTP status codes: 429, 500, 502, 503, 504
• Lambda Extension not ready (400 with "not ready to serve traffic")
• Request timeouts
• Network errors

Requirements

• Node.js >= 20.0.0
• AWS Lambda environment with the Parameters and Secrets Extension

License

This project is licensed under the Apache-2.0 License.