Table of contents

• Adonis Credentials
  • Installation
  • Usage
    • Creating credentials
    • Editing credentials
    • Using in production
  • How it works

Adonis Credentials

adonis, credentials

Adonis Credentials is created to help manage multiple environment secrets, share them securely and even keep them inside your repo. It is heavily insiped by Rails Credentials.

Installation

To install the provider run:

npm install @bitkidd/adonis-credentials
# or
yarn add @bitkidd/adonis-credentials

And then:

node ace configure @bitkidd/adonis-credentials

This will add two new commands to your app and will allow to create and edit credentials.

Then you need to open server.ts file and add there a new line, just before the Ignitor:

import { Credentials } from '@bitkidd/adonis-credentials/build/src/Credentials'

// ...

new Credentials().initialize() // <--- Here
new Ignitor(__dirname).httpServer().start().catch(console.error)

It has to be done to populate values before Adonis starts and Env provider validates values.

Usage

Creating credentials

As you configured the provider, you may now create your first credentials file by running the command:

# node ace credentials:create
# ---
# Flags
#   --env string      Specify an environment for credentials file (default: development)
#   --content string  Specify initial content for credentials file (default: { "hello": "world" })

node ace credentials:create

This will create a new directory in your resources folder, called credentials and will add there two new files, development.key and development.credentials. Obviously the .key file keeps your password to the credentials file, do not commit any .key files to your git repo, please check your .gitignore for *.key exclusion rule.

The .key should be kept somewhere in a secret place, the best spot I know is a sticky note on your laptop. Just NO, don't do this 🙈. Keep your secrets secure and use password managers!

The .credentials file can be committed and shared as it is impossimple to decrypt it without the password.

There two files should be always kept in one folder while in development.

Editing credentials

To edit a newly created file, you should run a command:

# node ace credentials:edit
# ---
# Flags
#   --env string     Specify an environment for credentials file (default: development)
#   --editor string  Specify an editor to use for edit

node ace credentials:edit --editor="code ---wait" --env=development
# or
node ace credentials:edit --editor=nano --env=development

This will decrypt the credentials file, create a temporary one and open it in the editor you specified. As you finish editing, close the file (or tab inside your editor), this will encrypt it back again and remove the temporary file, to keep you safe and sound.

Using in production

You can have multiple credential files, the best way to work is to create one for each environment, development, production, staging, test and etc.

As for development you can keep .key files inside /credentials folder, in production environment this is not a great option.

You should use and set additional environment variable APP_CREDENTIALS_KEY, that will be used to decrypt data and populate it to your app.

How it works

The provider uses node.js' native crypto library and encrypts everything using AES cipher with a random vector, which makes your secrets very secure, with a single key that can decrypt data.

Credentials while decrypted present themselves as simple JSON objects, this allows to keep variables in a very predictable and simple manner:

{
  "google": {
    "key": "your_google_key",
    "secret": "your_google_secret"
  }
}

Which then is being transformed to something like this:

GOOGLE_KEY=your_google_key
GOOGLE_SECRET=your_google_secret

And then populated to process.env, as this is done before Adonis.js Env provider, you may even validate data to be sure that everything is present and has an exact format.