Coverterage

Super-simple-secrets using S3

Coverterage is a super simple secrets solutions that works with your existing AWS account (if you don't have an AWS account, see about getting set up here).

Coverterage is both a command line tool and an api.
Use the CLI tool to define your secrets into categories of Domain and Subject and then publish them to the cloud where they can be accessed by your applications using the very simple API.

Secrets are organized into domain/subject/property groups.

• a domain is the realm of secrets for a purpose. This corresponds to an AWS bucket in deployment.
• a subject is a JSON object that holds the secrets. This corresponds to an AWS object within the domain bucket.
• a property is a property of the json object, and a value is the value of that object property.

individual secrets can be considered as these object property values.

A path-like syntax is used to identify these in the command line.

For example, MySecrets/APIKeys/SomeProvider would refer to domain="MySecrets", subject="APIKeys".

Properties within this object could be retrieved such as MySecrets/APIKeys/google-clientId or set with MySecrets/APIKeys/google-clientId="Some Value"

installing for the CLI command

install with

npm install -g @tremho/coverterage

This will make the coverterage cli command available to you whereever you need it.

Some examples:

adding secrets to a domain/subject

coverterage add Example/MySecrets/foo="this is totally fubar"
coverterage add Example/MySecrets/bar="the bar is closed"

note that values may be quoted or unquoted. If your value contains quote characters, surround the value with the opposite quote type (' vs ") or escape the quote characters with backslashes.

viewing those secrets

coverterage get Example/MySecrets

returns

{ foo: 'this is totally fubar', bar: 'the bar is closed' }

If we try to add a property that already exists we will get an error

coverterage add Example/MySecrets/foo="something new"

property 'foo already exists for secret object 'Example/MySecrets'

but we can use the edit command if we want to update it

coverterage edit Example/MySecrets/foo="that's better"
coverterage edit Example/MySecrets/bar="the bar is open"

so now...

coverterage get Example/MySecrets

returns

{ foo: "that's better", bar: 'the bar is open' }

Remove a property if you like with remove

coverterage remove Example/MySecrets/foo

you will be prompted with Are you sure?

Remove the secret at Example/MySecrets/foo
Current Value is that's better
Are you sure? y

You can also remove the entire subject

coverterage remove Example/MySecrets 

or the entire domain

coverterage remove Example 

You will of course be prompted for confirmation on these actions too.

If the values are removed, or if you access values that never existed, you will get an error when you try to access them

coverterage get Example/MySecrets 

s3GetResponse Failed on exception: The specified bucket does not exist

The get command will attempt to read the secrets from the local dev store and use values it finds there, but if it does not find values there it will reach out to the cloud for any values that may have been published

The get command can accept one of two options --local or --cloud to force where the data is fetched from.

If we try that same command for the local store, we get a slightly different error message

Unrecognized Domain "Example"

In this example, we haven't published anything yet to the cloud, and we removed the values that we originally set locally. So let's put those back first.

coverterage add Example/MySecrets/foo="this is totally fubar"
coverterage add Example/MySecrets/bar="the bar is closed"

Now let's publish this to the cloud

coverterage publish Example 

this will publish the domain Example with its subjects to AWS.

If we had just said coverterage publish, then all the domains in the local store would be updated the cloud

Now let's change the values in the local store

converterage edit Example/MySecrets/foo="local change" 

And let's view that value:

converterage get Example/MySecrets/foo 

it appears as

local change

because we changed it, but if we look at the cloud version

converterage get --cloud Example/MySecrets/foo  

we see the one that we published there

this is totally fubar

we can remove the local subject completely

coverterage remove Example/MySecrets

and when we look for our value

coverterage get Example/MySecrets/foo 

we get the cloud value

this is totally fubar

if we try to find it locally, though, we get an error

coverterage get Example/MySecrets/foo --local 

Unrecognized Subject "MySecrets"

So you can use the --cloud and --local options of get to compare pending and current versions, and then sync to the cloud when you are ready with a new publish operation.

Finally, the last operation to show is the retrieve operation. This is sort of like a 'reverse publish' in that it pulls values from the cloud and writes them in the local store.

coverterage retrieve Example

will add the subjects in the cloud for the Example domain to the local store, replacing any values that may have been in this location before.

Using the api in an app

First, make sure you have installed coverterage for your project

npm install @tremho/coverterage

then, import into your application

import Secret from '@tremho/coverterage'

then use to fetch the subject object that you created, and read the secret from that:

const secrets = await Secret('MyDomain', 'MySubject');
const clientId = secrets.clientId

This example gets clientId from a published coverterage that was created with

coverterage add MyDomain/MySubject/clientId=xxxxxxxxwhateverxxxxxx
coverterage publish MyDomain 

Coverterage Github Repository

Changelog

• 1.0.5 - general maintenance update
• 1.0.4 - minor readme fix
• 1.0.3 - fix badges
• 1.0.2 - typescript types fix
• 1.0.1 - readme update
• 1.0.0 - initial release