@karmaniverous/aws-secrets-manager-tools 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Jason Williscroft
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,96 @@
+# AWS Secrets Manager Tools
+
+Tools and a get-dotenv plugin for working with AWS Secrets Manager “env-map” secrets (JSON object maps of environment variables).
+
+This package provides:
+
+- A tools-style wrapper that owns AWS client setup (including optional AWS X-Ray capture):
+  - `AwsSecretsManagerTools`
+- A get-dotenv plugin intended to be mounted under `aws`:
+  - `secretsPlugin()` → `aws secrets pull|push|delete`
+- A CLI embedding get-dotenv with the secrets plugin:
+  - `aws-secrets-manager-tools`
+
+## Documentation
+
+- Learn the programmatic API: [AwsSecretsManagerTools guide](guides/aws-secrets-manager-tools.md)
+- Learn the CLI and plugin behavior: [aws secrets plugin guide](guides/secrets-plugin.md)
+- Browse the generated API reference: [TypeDoc site](https://docs.karmanivero.us/aws-secrets-manager-tools)
+
+## Install
+
+```bash
+npm i @karmaniverous/aws-secrets-manager-tools
+```
+
+This package is ESM-only (Node >= 20).
+
+## Quick start (programmatic)
+
+```ts
+import { AwsSecretsManagerTools } from '@karmaniverous/aws-secrets-manager-tools';
+
+const tools = await AwsSecretsManagerTools.init({
+  clientConfig: { region: 'us-east-1', logger: console },
+  xray: 'auto',
+});
+
+const current = await tools.readEnvSecret({ secretId: 'my-app/dev' });
+await tools.upsertEnvSecret({ secretId: 'my-app/dev', value: current });
+```
+
+When you need AWS functionality not wrapped by this package, use the fully configured AWS SDK v3 client at `tools.client` (see the [programmatic guide](guides/aws-secrets-manager-tools.md) for examples).
+
+## Quick start (CLI)
+
+```bash
+aws-secrets-manager-tools --env dev aws secrets pull --secret-name '$STACK_NAME'
+aws-secrets-manager-tools --env dev aws secrets push --secret-name '$STACK_NAME'
+aws-secrets-manager-tools --env dev aws secrets delete --secret-name '$STACK_NAME'
+```
+
+Notes:
+
+- `--env` is a root-level (get-dotenv) option and must appear before the command path.
+- Secret name expansion is evaluated at action time against `{ ...process.env, ...ctx.dotenv }` (ctx wins).
+
+## Env-map secret format
+
+Secrets are stored as a JSON object map of environment variables in `SecretString`:
+
+```json
+{ "KEY": "value", "OPTIONAL": null }
+```
+
+Notes:
+
+- Values must be strings or `null`.
+- `null` is treated as `undefined` when decoding.
+
+## AWS X-Ray capture (optional)
+
+X-Ray support is guarded:
+
+- Default behavior is `xray: 'auto'`: capture is enabled only when `AWS_XRAY_DAEMON_ADDRESS` is set.
+- To enable capture, install the optional peer dependency:
+  - `aws-xray-sdk`
+- In `auto` mode, if `AWS_XRAY_DAEMON_ADDRESS` is set but `aws-xray-sdk` is not installed, initialization throws.
+
+## Config defaults (getdotenv.config.*)
+
+If you embed the plugin in your own get-dotenv host (or use the shipped CLI), you can provide safe defaults in config under `plugins['aws/secrets']`:
+
+```jsonc
+{
+  "plugins": {
+    "aws/secrets": {
+      "secretName": "$STACK_NAME",
+      "templateExtension": "template",
+      "push": { "from": ["file:env:private"] },
+      "pull": { "to": "env:private" }
+    }
+  }
+}
+```
+
+See the [secrets plugin guide](guides/secrets-plugin.md) for `--from` / `--to` selector details and all supported config keys.