@origins-digital/nestjs-aws-secrets-manager

A NestJS package for interacting with AWS Secrets Manager, providing secure secret storage and retrieval capabilities.

Installation

npm install @origins-digital/nestjs-aws-secrets-manager

Features

• AWS Secrets Manager integration
• Secure secret storage and retrieval
• Type-safe secret management
• Comprehensive error handling
• Support for secret versions and metadata

Usage

Basic Setup

import { Module } from '@nestjs/common';
import { AWSSecretsManagerModule } from '@origins-digital/nestjs-aws-secrets-manager';

@Module({
  imports: [AWSSecretsManagerModule],
})
export class AppModule {}

Using the Service

import { Injectable } from '@nestjs/common';
import { AWSSecretsManagerService } from '@origins-digital/nestjs-aws-secrets-manager';

@Injectable()
export class YourService {
  constructor(private readonly secretsService: AWSSecretsManagerService) {}

  async getSecrets() {
    // Get a secret value (returns string)
    const secret = await this.secretsService.getSecret('your-secret-name');

    // The secret is returned as a string
    // If it's JSON, you need to parse it manually
    console.log(secret); // Always a string

    // Set a new secret with JSON (must stringify manually)
    await this.secretsService.setSecret(
      'new-secret',
      JSON.stringify({
        username: 'admin',
        password: 'secure-password',
        apiKey: 'your-api-key',
      }),
    );

    // Set a plain text secret
    await this.secretsService.setSecret(
      'plain-text-secret',
      'simple-text-value',
    );

    // Delete a secret
    await this.secretsService.deleteSecret('old-secret');
  }
}

Service Methods

getSecret(name: string): Promise<string | null>

Retrieves a secret from AWS Secrets Manager. Returns the secret value as a string, or null if the secret doesn't exist.

setSecret(name: string, value: string): Promise<void>

Stores a secret in AWS Secrets Manager. The value must be a string - use JSON.stringify() for objects and arrays.

deleteSecret(name: string): Promise<void>

Deletes a secret from AWS Secrets Manager.

Secret Management Features

• Get Secrets: Retrieve secrets as strings
• Set Secrets: Store string values (JSON must be stringified manually)
• Delete Secrets: Remove secrets completely
• Version Support: Access specific versions of secrets
• Secure Storage: All secrets are encrypted at rest using AWS KMS

Configuration

The service uses AWS SDK v3 and inherits configuration from your AWS environment:

• Environment Variables: AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• AWS Profiles: Uses default profile or specified profile
• IAM Roles: Supports EC2 instance roles and ECS task roles
• KMS Keys: Automatically uses the default KMS key for your account

Error Handling

The service includes comprehensive error handling for AWS operations:

• Returns null for non-existent secrets instead of throwing errors
• Provides detailed error information for AWS operation failures
• Handles network timeouts and retries gracefully

JSON Handling

Since the service works with strings, you need to handle JSON manually:

// Storing a JSON secret
await this.secretsService.setSecret(
  'config',
  JSON.stringify({
    database: {
      host: 'localhost',
      port: 5432,
    },
    api: {
      timeout: 5000,
    },
  }),
);

// Retrieving the same secret
const configString = await this.secretsService.getSecret('config');
const config = JSON.parse(configString);
console.log(config.database.host); // 'localhost'
console.log(config.api.timeout); // 5000

Dependencies

• @nestjs/common: NestJS framework
• @aws-sdk/client-secrets-manager: AWS SDK v3 for Secrets Manager

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.