@origins-digital/nestjs-aws-ssm

A NestJS package for interacting with AWS Systems Manager Parameter Store, providing secure parameter storage and retrieval capabilities.

Installation

npm install @origins-digital/nestjs-aws-ssm

Features

• AWS Systems Manager Parameter Store integration
• Secure parameter storage and retrieval with automatic decryption
• Automatic JSON parsing/stringifying
• Type-safe parameter management
• Comprehensive error handling
• Support for parameter versions and metadata

Usage

Basic Setup

import { Module } from '@nestjs/common';
import { AWSSystemManagerModule } from '@origins-digital/nestjs-aws-ssm';

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

Using the Service

import { Injectable } from '@nestjs/common';
import { AWSSystemManagerService } from '@origins-digital/nestjs-aws-ssm';

@Injectable()
export class YourService {
  constructor(private readonly ssmService: AWSSystemManagerService) {}

  async getConfig() {
    // Get a parameter value
    const value = await this.ssmService.getParameterValue(
      'your-parameter-name',
    );

    // Get a secure parameter with decryption
    const secureValue = await this.ssmService.getParameterValue(
      'secure-param',
      {
        withDecryption: true,
      },
    );

    // Get full parameter details
    const parameter = await this.ssmService.getParameter('full-param');

    // Set a parameter
    await this.ssmService.setParameter('new-param', {
      some: 'data',
    });

    // Set a secure parameter
    await this.ssmService.setParameter('secure-param', 'sensitive-data', {
      secured: true,
    });

    // Delete a single parameter
    await this.ssmService.deleteParameter('old-param');

    // Delete multiple parameters
    await this.ssmService.deleteParameters(['param1', 'param2']);
  }
}

Service Methods

getParameterValue(name: string, options?: { withDecryption?: boolean })

Retrieves the value of a parameter, optionally with decryption for secure parameters.

getParameter(name: string)

Retrieves the full parameter object including metadata, type, and version information.

setParameter(name: string, value: any, options?: ParameterOptions)

Sets a parameter value with optional configuration like security, type, and description.

deleteParameter(name: string)

Deletes a single parameter.

deleteParameters(names: string[])

Deletes multiple parameters in a single operation.

Parameter Store Features

• Get Parameters: Retrieve parameters with optional decryption
• Get Full Parameters: Access complete parameter metadata
• Set Parameters: Store parameters with configurable options
• Delete Parameters: Remove single or multiple parameters
• Automatic JSON Handling: Values are automatically parsed/stringified
• Version Support: Access specific versions of parameters
• Secure Parameters: Handle encrypted parameters with automatic decryption

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

Error Handling

The service includes comprehensive error handling for AWS operations:

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

Dependencies

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

Contributing

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

License

MIT License - see the LICENSE file for details.