feat(parameters): SecretsProvider support

[dreamorosi]

Description of your changes

This PR introduces the SecretsProvider class which will allow the future Parameters utility to support retrieving secrets from AWS Secrets Manager.

The SecretsProvider supports two retrieval modes, both for retrieving one secret at the time. This is in line with the current functionalities supported by the Parameters utility in Powertools for Python.

• get this class method allows customers to retrieve a single secret by name and allows to specify aspects like the transformation to apply (none, binary, json, automatic) and max age (aka time to live for the item in the cache).

The class method will be used as such:

const secrets = new SecretsProvider();

const secret = secrets.get('foo');
console.log(secret); // value as string or binary

• getSecret utility function that behaves the same as the the method, but doesn't require instantiating a class.

const secret = getSecret('foo');
console.log(secret); // value as string or binary

In both cases users can configure how long the secret should be cached in the Lambda's execution environment:

const secretOne = secrets.get('foo', { maxAge: 5000 }); // This will be cached for 5 seconds
// or
const secretTwo = getSecret('foo', { maxAge: 10000 }); // This will be cached for 10 seconds

Secrets Manger allows to store secrets both as SecretString and SecretBinary. Both of them can be base64-encoded.

Using the provider or helper function, users can optionally specify a transform (json, binary, or auto) and SecretsProvider will try to transform the string or binary accordingly. When using auto, the name of the secret must have a suffix that specifies the transform to use (i.e. my-secret.json will result in a json transform). If no transform is specified, the secret will be returned as-is (aka string or Uint8Array).

Examples:

Note
The examples below use the getSecret notation for brevity, but the are 1:1 equivalent to SecretsProvider.get(...)

// SecretString: foo.json - value: "{ \"hello\": \"world\" }" (stringified version of an object)
const a = getSecret('foo.json');
console.log(a); // "{ \"hello\": \"world\" }" (returned as-is)

const b = getSecret('foo.json', { transform: 'auto' });
console.log(b); // { hello: 'world' } (type object)

const c = getSecret('foo.json', { transform: 'json' });
console.log(c); // { hello: 'world' } (type object)

// SecretString: bar.binary - value: "Yw==" (base64 encoded string - 'hello world')
const a = getSecret('bar.binary');
console.log(a); // "Yw==" (returned as-is)

const b = getSecret('bar.binary', { transform: 'auto' });
console.log(b); // "hello world" (type string - base64 decoded)

const c = getSecret('bar.binary', { transform: 'binary' });
console.log(c); // "hello world" (type string - base64 decoded)

// SecretBinary: baz.binary - value: "Yw==" (base64 encoded string - 'hello world')
const a = getSecret('bar.binary');
console.log(a); // [104, 101, 108, 108, 111,  32, 119, 111, 114, 108, 100] (Uint8Array - returned as-is)

const b = getSecret('bar.binary', { transform: 'auto' });
console.log(b); // "hello world" (type string - base64 decoded)

const c = getSecret('bar.binary', { transform: 'binary' });
console.log(c); // "hello world" (type string - base64 decoded)

Finally, users can also customize the behavior of the underlying AWS SDK client calls by passing an optional sdkOptions of type GetSecretValueCommandInput in the second argument:

const secret = getSecret('bar.binary', {
  sdkOptions: {
    VersionId: 'test-version',
  }
});
// or
const secrets = new SecretsProvider();

const secret = secrets.get('bar.binary', {
  sdkOptions: {
    VersionId: 'test-version',
  }
});

Or, for class-based usage only, they can pass their own SDK client config (of type SecretsManagerClient) altogether while initialising the instance:

const secrets = new SecretsProvider({
  clientConfig: { region: 'eu-west-1' }
});

How to verify this change

See the newly added unit test cases & optionally compare also the API surface with the implementation found in Powertools for Python.

Related issues, RFCs

Issue number: #1175

PR status

Is this ready for review?: YES
Is it a breaking change?: NO

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• I have made corresponding changes to the examples
• My changes generate no new warnings
• The code coverage hasn't decreased
• I have added tests that prove my change is effective and works
• New and existing unit tests pass locally and in Github Actions
• Any dependent changes have been merged and published
• The PR title follows the conventional commit semantics

Breaking change checklist

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[shdq]

Great work!

Should we have tests for the transformation in providers or having them in BaseProvider is enough?

I would add JSDoc for class and methods with a couple of examples (from the PR description).

It looks good to me.

[shdq]

Explicit arguments passed to the constructor will take precedence over ones passed to the method.

I looked at the comment above the removeNonOverridableOptions function and instead of explicitly deleting properties, spread options.sdkOptions first (if any) and then overwrite them with name would work:

const sdkOptions: GetSecretValueCommandInput = {
  ...(options?.sdkOptions || {}),
  SecretId: name,
};

It may be less readable, but I like it more than duplicating removeNonOverridableOptions in every provider. Am I missing something?

[dreamorosi]

Good point, I have applied your suggestion. Thank you!

[dreamorosi]

Great work!

Thank you for the review!

Should we have tests for the transformation in providers or having them in BaseProvider is enough?

I think testing in the BaseProvider should be enough for now, we'll add more testing in the integration tests against real end to end retrievals.

I would add JSDoc for class and methods with a couple of examples (from the PR description).

Definitely, we have a dedicated issue for it (#1043). When doing the planning I put it in a separate one because I thought it'd make more sense to do it once the code is more or less stable. I expect to do this sometime towards the end of the integration tests & before the beta release.