npm package: @origins-digital/nestjs-aws-secrets-manager
Description: Origins Digital NestJS AWS Secrets Manager Module
Author: Origins Digital
Latest version: 2.1.4

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

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

## Installation

```bash
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

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

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

### Using the Service

```typescript
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:

```typescript
// 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.