@karmaniverous/aws-secrets-manager-tools 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +45 -39
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,35 +1,37 @@
|
|
|
1
|
-
# AWS Secrets Manager Tools
|
|
2
|
-
|
|
1
|
+
# AWS Secrets Manager Tools
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@karmaniverous/aws-secrets-manager-tools)  [](https://docs.karmanivero.us/aws-secrets-manager-tools) [](./CHANGELOG.md) [](./LICENSE)
|
|
4
|
+
|
|
3
5
|
Tools and a get-dotenv plugin for working with AWS Secrets Manager “env-map” secrets (JSON object maps of environment variables).
|
|
4
|
-
|
|
5
|
-
This package provides:
|
|
6
|
-
|
|
6
|
+
|
|
7
|
+
This package provides:
|
|
8
|
+
|
|
7
9
|
- A tools-style wrapper that owns AWS client setup (including optional AWS X-Ray capture):
|
|
8
|
-
- `AwsSecretsManagerTools`
|
|
10
|
+
- `AwsSecretsManagerTools`
|
|
9
11
|
- A get-dotenv plugin intended to be mounted under `aws`:
|
|
10
12
|
- `secretsPlugin()` → `aws secrets pull|push|delete`
|
|
11
|
-
- A CLI embedding get-dotenv with the secrets plugin:
|
|
12
|
-
- `aws-secrets-manager-tools`
|
|
13
|
-
|
|
13
|
+
- A CLI embedding get-dotenv with the secrets plugin:
|
|
14
|
+
- `aws-secrets-manager-tools`
|
|
15
|
+
|
|
14
16
|
## Documentation
|
|
15
|
-
|
|
17
|
+
|
|
16
18
|
- Learn the programmatic API: [AwsSecretsManagerTools guide](guides/aws-secrets-manager-tools.md)
|
|
17
19
|
- Learn the CLI and plugin behavior: [aws secrets plugin guide](guides/secrets-plugin.md)
|
|
18
20
|
- Browse the generated API reference: [TypeDoc site](https://docs.karmanivero.us/aws-secrets-manager-tools)
|
|
19
|
-
|
|
21
|
+
|
|
20
22
|
## Install
|
|
21
|
-
|
|
23
|
+
|
|
22
24
|
```bash
|
|
23
25
|
npm i @karmaniverous/aws-secrets-manager-tools
|
|
24
26
|
```
|
|
25
|
-
|
|
27
|
+
|
|
26
28
|
This package is ESM-only (Node >= 20).
|
|
27
|
-
|
|
29
|
+
|
|
28
30
|
## Quick start (programmatic)
|
|
29
|
-
|
|
31
|
+
|
|
30
32
|
```ts
|
|
31
33
|
import { AwsSecretsManagerTools } from '@karmaniverous/aws-secrets-manager-tools';
|
|
32
|
-
|
|
34
|
+
|
|
33
35
|
const tools = await AwsSecretsManagerTools.init({
|
|
34
36
|
clientConfig: { region: 'us-east-1', logger: console },
|
|
35
37
|
xray: 'auto',
|
|
@@ -37,49 +39,49 @@ const tools = await AwsSecretsManagerTools.init({
|
|
|
37
39
|
|
|
38
40
|
const current = await tools.readEnvSecret({ secretId: 'my-app/dev' });
|
|
39
41
|
await tools.upsertEnvSecret({ secretId: 'my-app/dev', value: current });
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
+
```
|
|
43
|
+
|
|
42
44
|
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).
|
|
43
|
-
|
|
45
|
+
|
|
44
46
|
## Quick start (CLI)
|
|
45
|
-
|
|
47
|
+
|
|
46
48
|
```bash
|
|
47
49
|
aws-secrets-manager-tools --env dev aws secrets pull --secret-name '$STACK_NAME'
|
|
48
50
|
aws-secrets-manager-tools --env dev aws secrets push --secret-name '$STACK_NAME'
|
|
49
51
|
aws-secrets-manager-tools --env dev aws secrets delete --secret-name '$STACK_NAME'
|
|
50
52
|
```
|
|
51
|
-
|
|
53
|
+
|
|
52
54
|
Notes:
|
|
53
|
-
|
|
55
|
+
|
|
54
56
|
- `--env` is a root-level (get-dotenv) option and must appear before the command path.
|
|
55
57
|
- Secret name expansion is evaluated at action time against `{ ...process.env, ...ctx.dotenv }` (ctx wins).
|
|
56
|
-
|
|
58
|
+
|
|
57
59
|
## Env-map secret format
|
|
58
|
-
|
|
60
|
+
|
|
59
61
|
Secrets are stored as a JSON object map of environment variables in `SecretString`:
|
|
60
|
-
|
|
62
|
+
|
|
61
63
|
```json
|
|
62
64
|
{ "KEY": "value", "OPTIONAL": null }
|
|
63
65
|
```
|
|
64
|
-
|
|
66
|
+
|
|
65
67
|
Notes:
|
|
66
|
-
|
|
68
|
+
|
|
67
69
|
- Values must be strings or `null`.
|
|
68
70
|
- `null` is treated as `undefined` when decoding.
|
|
69
|
-
|
|
71
|
+
|
|
70
72
|
## AWS X-Ray capture (optional)
|
|
71
|
-
|
|
73
|
+
|
|
72
74
|
X-Ray support is guarded:
|
|
73
|
-
|
|
75
|
+
|
|
74
76
|
- Default behavior is `xray: 'auto'`: capture is enabled only when `AWS_XRAY_DAEMON_ADDRESS` is set.
|
|
75
77
|
- To enable capture, install the optional peer dependency:
|
|
76
78
|
- `aws-xray-sdk`
|
|
77
79
|
- In `auto` mode, if `AWS_XRAY_DAEMON_ADDRESS` is set but `aws-xray-sdk` is not installed, initialization throws.
|
|
78
|
-
|
|
79
|
-
## Config defaults (getdotenv.config
|
|
80
|
-
|
|
80
|
+
|
|
81
|
+
## Config defaults (getdotenv.config.\*)
|
|
82
|
+
|
|
81
83
|
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']`:
|
|
82
|
-
|
|
84
|
+
|
|
83
85
|
```jsonc
|
|
84
86
|
{
|
|
85
87
|
"plugins": {
|
|
@@ -87,10 +89,14 @@ If you embed the plugin in your own get-dotenv host (or use the shipped CLI), yo
|
|
|
87
89
|
"secretName": "$STACK_NAME",
|
|
88
90
|
"templateExtension": "template",
|
|
89
91
|
"push": { "from": ["file:env:private"] },
|
|
90
|
-
"pull": { "to": "env:private" }
|
|
91
|
-
}
|
|
92
|
-
}
|
|
92
|
+
"pull": { "to": "env:private" },
|
|
93
|
+
},
|
|
94
|
+
},
|
|
93
95
|
}
|
|
94
96
|
```
|
|
95
|
-
|
|
96
|
-
See the [secrets plugin guide](guides/secrets-plugin.md) for `--from` / `--to` selector details and all supported config keys.
|
|
97
|
+
|
|
98
|
+
See the [secrets plugin guide](guides/secrets-plugin.md) for `--from` / `--to` selector details and all supported config keys.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
Built for you with ❤️ on Bali! Find more great tools & templates on [my GitHub Profile](https://github.com/karmaniverous).
|
package/package.json
CHANGED