Secrets

Service and library managing Secrets in AWS SSM Parameter store.

Table of Contents

• Installation
• Development
• Deployment
• Services
  • SecretsService
• When used as a dependency
• Libraries
  • SecretsManager
• Commands

Installation

From the command line run:

npm install @saws/secrets

Then add the SecretsService to your saws.js file.

Development

When running your SAWS application in development, this service will store and retrieve local secrets out of a .gitignored file located at .saws/.secrets. This file is in the same format as a .env file.

Deployment

When you deploy a SecretsService it will not create any additional AWS resources for you. The way to set secrets in a specific stage would be to use the @saws/cli secrets command.

Services

@saws/secrets includes one service, SecretsService.

SecretsService

You can require the SecretsService and use it in your saws.js file like so:

const { SecretsService } = require('@saws/secrets/secrets-service')

// will almost exclusively be used as a dependency to other services
const secrets = new SecretsService({
  name: 'my-secrets',
})

The SecretsService constructor accepts the following options:

name: string

The name of your service. This should be unique across all of your services.

dependencies: ServiceDefinition[]

An array of all of the other services this service depends on. This will ensure that permissions, environment variables, and execution order are all set up.

When used as a dependency

When a SecretsService is used as a dependency, it will not attach any environment variables to the dependant service.

Libraries

@saws/secrets includes a SecretsManager class that can be used to get and set secrets in the current stage.

SecretsManager

The SecretsManager class can be used as follows:

import { SecretsManager } from '@saws/secrets/secrets-manager'

const manager = new SecretsManager()

await manager.get('secret-name')

await manager.set('secret-name', 'value')

get(name: string): Promise<string>

This function will get a secret value from either your .secrets file when running locally, or from SSM Parameter Store when running in a production environment.

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

This function will set a secret value either in your .secrets file when running locally, or to SSM Parameter Store when running in a production environment. The secret will be set as an encrypted string in Parameter Store.

Commands

When you have a SecretsService in your saw.js config file, it will add the following commands to the saws cli command:

secrets

The saws secrets command is used for managing secrets within the application. It requires a secret name and supports various operations such as setting and getting secrets.

Usage

saws secrets [options] <name>

Arguments : The name of the secret. This is a required argument.

Options --stage : Specifies the stage environment (e.g., local, dev, prod). Default is local. --set : Sets the secret to the specified value. --get: Retrieves the current value of the secret.

Examples

Set a secret: This command sets the value of mySecret in the prod stage to mySecretValue.

saws secrets --stage prod --set "mySecretValue" mySecret

Get a secret: This command retrieves the value of mySecret in the dev stage.

saws secrets --stage dev --get mySecret