@bygd/gd-env-loader 0.0.0-stage → 0.1.0
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 +195 -2
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +120 -0
- package/dist/errors.d.ts +14 -0
- package/dist/errors.js +29 -0
- package/dist/index.d.ts +72 -0
- package/dist/index.js +160 -0
- package/dist/path.d.ts +7 -0
- package/dist/path.js +22 -0
- package/dist/payload.d.ts +7 -0
- package/dist/payload.js +74 -0
- package/dist/providers/gcp.d.ts +15 -0
- package/dist/providers/gcp.js +78 -0
- package/dist/providers/types.d.ts +13 -0
- package/dist/providers/types.js +2 -0
- package/dist/resolver.d.ts +26 -0
- package/dist/resolver.js +57 -0
- package/dist/template.d.ts +21 -0
- package/dist/template.js +75 -0
- package/package.json +45 -4
package/README.md
CHANGED
|
@@ -1,3 +1,196 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @bygd/gd-env-loader
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Keep your `.env` files, but take the secrets out of them. Secret values are replaced with `{{placeholders}}`, and
|
|
4
|
+
gd-env-loader fills them in from **GCP Secret Manager** at startup, either as a CLI wrapper around your start
|
|
5
|
+
command or as a library call.
|
|
6
|
+
|
|
7
|
+
```dotenv
|
|
8
|
+
# @gd-env-loader secrets=shared-prod,my-api-prod
|
|
9
|
+
DB_HOST=mysql.internal
|
|
10
|
+
DB_PASSWORD={{CATALOG_DB_PASSWORD}}
|
|
11
|
+
CH_PASSWORD={{clickhouse-prod/CH_PASSWORD}}
|
|
12
|
+
MONGO_URL=mongodb://{{MONGO_USER}}:{{MONGO_PASS}}@mongo:27017/kpi
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
A file **without** placeholders passes through untouched, so the same start script works in environments that
|
|
16
|
+
still use real-values files.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @bygd/gd-env-loader
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Node ≥ 12.20 for pass-through; Node ≥ 14.18 to resolve secrets (uses `@google-cloud/secret-manager`, loaded only
|
|
25
|
+
when there is something to resolve).
|
|
26
|
+
|
|
27
|
+
## CLI
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
"scripts": {
|
|
31
|
+
"start:prod": "gd-env-loader run -- node dist/main",
|
|
32
|
+
"start:dev": "gd-env-loader run -- nest start --watch"
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
gd-env-loader run [options] -- <command> [args...]
|
|
38
|
+
gd-env-loader check [options]
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
| Option | Meaning |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `--env <path>` | Env file. `${VAR}` and `${VAR:-default}` are expanded by the CLI itself. Default `secrets/${BUILD:-local}/.env`, relative to the working directory. |
|
|
44
|
+
| `--strict` | A missing file is an error. On by default when `GD_ENV_LOADER=gcp`. |
|
|
45
|
+
| `--override` | Resolved values replace variables already set in the environment (default: existing ones win, as with dotenv). |
|
|
46
|
+
| `--project <id>` | GCP project. Default: `GD_GCP_PROJECT`, then the Application Default Credentials project (automatic on GKE). |
|
|
47
|
+
| `--timeout <ms>` | Timeout per secret, including the SDK's retries of transient errors (default 10000). |
|
|
48
|
+
| `--quiet` | No summary line. |
|
|
49
|
+
|
|
50
|
+
**`run`** resolves the file, then starts `<command>` with every key of the file in its environment (plus
|
|
51
|
+
`GD_ENV_LOADER_RESOLVED=1`).
|
|
52
|
+
- Signals (SIGTERM, SIGINT, SIGHUP, SIGQUIT) are forwarded to the command.
|
|
53
|
+
- The command's exit code is passed through. If the command dies from a signal, gd-env-loader dies from the same signal.
|
|
54
|
+
|
|
55
|
+
**`check`** resolves and prints where each placeholder comes from. It never prints values. Use it to verify a template.
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
$ gd-env-loader check --env secrets/test/.env
|
|
59
|
+
file: /app/secrets/test/.env
|
|
60
|
+
mode: resolved (project my-project)
|
|
61
|
+
secrets: shared-test@4, my-api-test@2
|
|
62
|
+
DB_PASSWORD <- shared-test@4/CATALOG_DB_PASSWORD
|
|
63
|
+
API_TOKEN <- my-api-test@2/API_TOKEN
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Exit codes: the command's own; `78` resolving failed (the command was not started); `64` usage error; `127`
|
|
67
|
+
command not found. `check` exits `1` on failure.
|
|
68
|
+
|
|
69
|
+
### What happens when
|
|
70
|
+
|
|
71
|
+
| File | Placeholders | Strict | Result |
|
|
72
|
+
|---|---|---|---|
|
|
73
|
+
| missing | — | off | pass-through, silent |
|
|
74
|
+
| missing | — | on | error `ENV_FILE_NOT_FOUND` |
|
|
75
|
+
| present | none | off | pass-through, silent: the command starts with the environment unchanged |
|
|
76
|
+
| present | none | on | pass-through with a `NO_PLACEHOLDERS` warning |
|
|
77
|
+
| present | yes | either | resolve; any failure stops startup |
|
|
78
|
+
|
|
79
|
+
In pass-through mode nothing is added to the environment, so your app's own `dotenv.config()` loads the file
|
|
80
|
+
exactly as before. In resolved mode the values are already in the environment when the app starts. dotenv doesn't
|
|
81
|
+
override variables that are already set, so the app's own `dotenv.config()` on the template does nothing harmful.
|
|
82
|
+
|
|
83
|
+
## Library
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
import { loadEnv } from '@bygd/gd-env-loader';
|
|
87
|
+
|
|
88
|
+
async function bootstrap() {
|
|
89
|
+
await loadEnv(); // same options and rules as the CLI
|
|
90
|
+
const { AppModule } = await import('./app.module'); // import AFTER loading
|
|
91
|
+
// ...
|
|
92
|
+
}
|
|
93
|
+
bootstrap();
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Modules that read `process.env` when they load must be imported after the `await`.
|
|
97
|
+
|
|
98
|
+
| Function | Does |
|
|
99
|
+
|---|---|
|
|
100
|
+
| `loadEnv(options?)` | Resolves, then writes the values into `process.env` (existing variables are kept unless `override: true`). Writes nothing in pass-through mode. |
|
|
101
|
+
| `resolveEnv(options?)` | Resolves and returns `{ mode, path, found, values, sources, secrets, project }` without touching `process.env`. |
|
|
102
|
+
| `assertNoPlaceholders(env?)` | Throws if any variable still holds a `{{placeholder}}`. Put it after your app's `dotenv.config()` to catch starting without the wrapper. |
|
|
103
|
+
|
|
104
|
+
Options: `path`, `cwd`, `strict`, `override`, `project`, `timeoutMs`, `env` (the environment used for path expansion
|
|
105
|
+
and `GD_*` settings), `provider` (custom secret source), `logger` (function, or `false` for silence).
|
|
106
|
+
|
|
107
|
+
Errors are `GdEnvLoaderError` with a `code` (see below). Messages name files, keys and secrets, never values.
|
|
108
|
+
|
|
109
|
+
## Template syntax
|
|
110
|
+
|
|
111
|
+
### Header directive
|
|
112
|
+
|
|
113
|
+
One comment line, anywhere in the file, listing the secrets that unqualified placeholders are looked up in:
|
|
114
|
+
|
|
115
|
+
```dotenv
|
|
116
|
+
# @gd-env-loader secrets=shared-prod,my-api-prod
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Placeholders
|
|
120
|
+
|
|
121
|
+
`{{KEY}}` or `{{secret/KEY}}`. Spaces inside the braces are allowed.
|
|
122
|
+
|
|
123
|
+
- **Unqualified** `{{KEY}}` is looked up in the header's secrets. If more than one of them has `KEY`, that's a
|
|
124
|
+
`KEY_COLLISION` error.
|
|
125
|
+
- **Qualified** `{{secret/KEY}}` reads only that secret, which doesn't need to be in the header. Use it to settle a
|
|
126
|
+
collision or to pull a single value from somewhere else.
|
|
127
|
+
- Several placeholders can sit in one value: `mongodb://{{U}}:{{P}}@host`.
|
|
128
|
+
- Substitution runs on the values after dotenv parses them, so quoting works as usual and resolved values may contain
|
|
129
|
+
any characters, newlines included.
|
|
130
|
+
- Text in braces that doesn't match the grammar (e.g. `{{ two words }}`) is left alone.
|
|
131
|
+
- A file may mix plain values and placeholders, so you can migrate a few keys at a time.
|
|
132
|
+
|
|
133
|
+
## Secret payloads
|
|
134
|
+
|
|
135
|
+
Each Secret Manager secret holds several key/value pairs. JSON is recommended:
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{ "CATALOG_DB_PASSWORD": "…", "MONGO_USER": "…", "MONGO_PASS": "…" }
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- It must be a flat object. Numbers and booleans become strings; nested values are rejected.
|
|
142
|
+
- A payload that doesn't start with `{` or `[` is parsed as dotenv text (`KEY=value` lines).
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
gcloud secrets create shared-prod --replication-policy=automatic --data-file=shared-prod.json
|
|
146
|
+
gcloud secrets versions add shared-prod --data-file=shared-prod.json # update; running apps pick it up on restart
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The latest version is always read. To roll back a bad update, disable the newest version
|
|
150
|
+
(`gcloud secrets versions disable <n> --secret=shared-prod`) and restart; `latest` then points at the previous one.
|
|
151
|
+
|
|
152
|
+
## Authentication and IAM
|
|
153
|
+
|
|
154
|
+
gd-env-loader uses Application Default Credentials:
|
|
155
|
+
|
|
156
|
+
- **Locally:** `gcloud auth application-default login`.
|
|
157
|
+
- **On GKE:** Workload Identity. Give the pod a Kubernetes service account (`serviceAccountName:`) and grant that
|
|
158
|
+
account `roles/secretmanager.secretAccessor` on each secret it reads:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
PN=$(gcloud projects describe $PROJECT --format='value(projectNumber)')
|
|
162
|
+
gcloud secrets add-iam-policy-binding shared-prod --project $PROJECT \
|
|
163
|
+
--role=roles/secretmanager.secretAccessor \
|
|
164
|
+
--member="principal://iam.googleapis.com/projects/$PN/locations/global/workloadIdentityPools/$PROJECT.svc.id.goog/subject/ns/<namespace>/sa/<ksa>"
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Environment variables
|
|
168
|
+
|
|
169
|
+
| Variable | Meaning |
|
|
170
|
+
|---|---|
|
|
171
|
+
| `GD_ENV_LOADER=gcp` | Turns on strict mode. Set it in the deployment of environments that use templates. |
|
|
172
|
+
| `GD_GCP_PROJECT` | Default GCP project. |
|
|
173
|
+
| `GD_ENV_LOADER_RESOLVED=1` | Set by gd-env-loader for the started command when it resolved a file. |
|
|
174
|
+
|
|
175
|
+
## Error codes
|
|
176
|
+
|
|
177
|
+
| Code | Typical cause |
|
|
178
|
+
|---|---|
|
|
179
|
+
| `ENV_FILE_NOT_FOUND` | Strict mode and the file isn't there. Check the mount and `BUILD`. |
|
|
180
|
+
| `INVALID_PATH` | The path uses `${VAR}` and `VAR` is unset. Give it a default: `${VAR:-x}`. |
|
|
181
|
+
| `INVALID_HEADER` | Malformed `# @gd-env-loader` line: it must be exactly `secrets=<id>[,<id>...]`. |
|
|
182
|
+
| `MISSING_HEADER` | Unqualified placeholders but no header. |
|
|
183
|
+
| `NO_PROJECT` | No project from `--project`, `GD_GCP_PROJECT` or ADC. |
|
|
184
|
+
| `AUTH_FAILED` | No usable credentials. Run `gcloud auth application-default login`, or check Workload Identity. |
|
|
185
|
+
| `PERMISSION_DENIED` | The identity lacks `secretmanager.secretAccessor` on the secret, or the Secret Manager API is disabled. |
|
|
186
|
+
| `SECRET_NOT_FOUND` | Wrong secret ID or project, or the secret has no enabled version. |
|
|
187
|
+
| `KEY_NOT_FOUND` | The secret has no such key. |
|
|
188
|
+
| `KEY_COLLISION` | An unqualified key exists in several header secrets. Qualify it. |
|
|
189
|
+
| `INVALID_PAYLOAD` | The secret isn't a flat JSON object or valid dotenv text. |
|
|
190
|
+
| `TIMEOUT` / `PROVIDER_ERROR` | Secret Manager unreachable or returned an unexpected error. |
|
|
191
|
+
| `UNSUPPORTED_NODE` | Resolving needs Node ≥ 14.18. |
|
|
192
|
+
| `UNRESOLVED_PLACEHOLDERS` | From `assertNoPlaceholders()`: the app started without gd-env-loader. |
|
|
193
|
+
|
|
194
|
+
## License
|
|
195
|
+
|
|
196
|
+
MIT
|
package/dist/cli.d.ts
ADDED
package/dist/cli.js
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
|
+
const child_process_1 = require("child_process");
|
|
5
|
+
const commander_1 = require("commander");
|
|
6
|
+
const index_1 = require("./index");
|
|
7
|
+
const EXIT_USAGE = 64;
|
|
8
|
+
const EXIT_CONFIG = 78; // EX_CONFIG: resolving failed, the command was not started
|
|
9
|
+
const EXIT_NOT_FOUND = 127;
|
|
10
|
+
const EXIT_CANNOT_EXEC = 126;
|
|
11
|
+
const FORWARDED_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGQUIT'];
|
|
12
|
+
function parseTimeout(value) {
|
|
13
|
+
const n = Number(value);
|
|
14
|
+
if (!Number.isInteger(n) || n <= 0)
|
|
15
|
+
throw new commander_1.InvalidArgumentError('must be a positive integer (ms).');
|
|
16
|
+
return n;
|
|
17
|
+
}
|
|
18
|
+
async function resolveOrExit(opts, quiet, failCode) {
|
|
19
|
+
try {
|
|
20
|
+
return await (0, index_1.resolveEnv)({
|
|
21
|
+
path: opts.env,
|
|
22
|
+
strict: opts.strict,
|
|
23
|
+
project: opts.project,
|
|
24
|
+
timeoutMs: opts.timeout,
|
|
25
|
+
logger: quiet ? false : undefined,
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
catch (err) {
|
|
29
|
+
const e = err instanceof index_1.GdEnvLoaderError ? err : new index_1.GdEnvLoaderError('PROVIDER_ERROR', String(err));
|
|
30
|
+
process.stderr.write(`gd-env-loader: error [${e.code}] ${e.message}\n`);
|
|
31
|
+
return process.exit(failCode);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** Starts the command, forwards signals to it, and exits the way it exits. */
|
|
35
|
+
function runChild(cmd, env) {
|
|
36
|
+
const child = (0, child_process_1.spawn)(cmd[0], cmd.slice(1), { stdio: 'inherit', env });
|
|
37
|
+
const forward = (sig) => {
|
|
38
|
+
if (child.exitCode === null && child.signalCode === null)
|
|
39
|
+
child.kill(sig);
|
|
40
|
+
};
|
|
41
|
+
FORWARDED_SIGNALS.forEach((sig) => process.on(sig, forward));
|
|
42
|
+
const stopForwarding = () => FORWARDED_SIGNALS.forEach((sig) => process.removeListener(sig, forward));
|
|
43
|
+
child.on('error', (err) => {
|
|
44
|
+
stopForwarding();
|
|
45
|
+
const notFound = err.code === 'ENOENT';
|
|
46
|
+
process.stderr.write(`gd-env-loader: cannot start "${cmd[0]}": ${notFound ? 'command not found' : err.message}\n`);
|
|
47
|
+
process.exit(notFound ? EXIT_NOT_FOUND : EXIT_CANNOT_EXEC);
|
|
48
|
+
});
|
|
49
|
+
child.on('exit', (code, signal) => {
|
|
50
|
+
stopForwarding();
|
|
51
|
+
// Die the same way the child did, so a supervisor sees the real cause.
|
|
52
|
+
if (signal)
|
|
53
|
+
process.kill(process.pid, signal);
|
|
54
|
+
else
|
|
55
|
+
process.exit(code === null ? 1 : code);
|
|
56
|
+
});
|
|
57
|
+
}
|
|
58
|
+
function printCheck(r) {
|
|
59
|
+
const lines = [`file: ${r.path}${r.found ? '' : ' (not found)'}`];
|
|
60
|
+
if (r.mode === 'passthrough') {
|
|
61
|
+
lines.push(`mode: pass-through (${r.found ? 'no placeholders' : 'no file'})`);
|
|
62
|
+
}
|
|
63
|
+
else {
|
|
64
|
+
lines.push(`mode: resolved (project ${r.project})`, `secrets: ${r.secrets.map(index_1.formatSecret).join(', ')}`);
|
|
65
|
+
const width = Math.max(...r.sources.map((s) => s.envKey.length));
|
|
66
|
+
for (const s of r.sources)
|
|
67
|
+
lines.push(` ${s.envKey.padEnd(width)} <- ${(0, index_1.formatSecret)(s)}/${s.secretKey}`);
|
|
68
|
+
}
|
|
69
|
+
process.stdout.write(`${lines.join('\n')}\n`);
|
|
70
|
+
}
|
|
71
|
+
const program = new commander_1.Command('gd-env-loader')
|
|
72
|
+
.description('Resolves {{placeholders}} in an env file from GCP Secret Manager.')
|
|
73
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
74
|
+
.version(require('../package.json').version, '-v, --version')
|
|
75
|
+
.enablePositionalOptions()
|
|
76
|
+
.showHelpAfterError()
|
|
77
|
+
.exitOverride((err) => {
|
|
78
|
+
const ok = err.code === 'commander.helpDisplayed' || err.code === 'commander.version';
|
|
79
|
+
process.exit(ok ? 0 : EXIT_USAGE);
|
|
80
|
+
})
|
|
81
|
+
.addHelpText('after', `\nExit codes: the command's own; ${EXIT_CONFIG} resolving failed (command not started); ` +
|
|
82
|
+
`${EXIT_USAGE} usage error; ${EXIT_NOT_FOUND} command not found.`);
|
|
83
|
+
const withCommonOptions = (cmd) => cmd
|
|
84
|
+
.option('--env <path>', `env file; \${VAR} and \${VAR:-default} are expanded (default ${index_1.DEFAULT_ENV_PATH})`)
|
|
85
|
+
.option('--strict', 'missing file is an error (default: on when GD_ENV_LOADER=gcp)')
|
|
86
|
+
.option('--project <id>', 'GCP project (default: GD_GCP_PROJECT, then ADC)')
|
|
87
|
+
.option('--timeout <ms>', 'timeout per secret, retries included (default 10000)', parseTimeout);
|
|
88
|
+
withCommonOptions(program.command('run'))
|
|
89
|
+
.description('resolve, then start <command> with the values in its environment; passes through when there is nothing to resolve')
|
|
90
|
+
.usage('[options] -- <command> [args...]')
|
|
91
|
+
.argument('<command...>', 'the command to start')
|
|
92
|
+
.option('--override', 'resolved values replace variables already set in the environment')
|
|
93
|
+
.option('--quiet', 'no summary line')
|
|
94
|
+
.passThroughOptions()
|
|
95
|
+
.action(async (cmd, opts) => {
|
|
96
|
+
const result = await resolveOrExit(opts, !!opts.quiet, EXIT_CONFIG);
|
|
97
|
+
let env = process.env;
|
|
98
|
+
if (result.mode === 'resolved') {
|
|
99
|
+
env = { ...process.env };
|
|
100
|
+
for (const [key, value] of Object.entries(result.values)) {
|
|
101
|
+
if (opts.override || env[key] === undefined)
|
|
102
|
+
env[key] = value;
|
|
103
|
+
}
|
|
104
|
+
env.GD_ENV_LOADER_RESOLVED = '1';
|
|
105
|
+
}
|
|
106
|
+
runChild(cmd, env);
|
|
107
|
+
});
|
|
108
|
+
withCommonOptions(program.command('check'))
|
|
109
|
+
.description('resolve and print where each placeholder comes from (never values)')
|
|
110
|
+
.allowExcessArguments(false)
|
|
111
|
+
.action(async (opts) => {
|
|
112
|
+
const result = await resolveOrExit(opts, true, 1);
|
|
113
|
+
printCheck(result);
|
|
114
|
+
if (!result.found)
|
|
115
|
+
process.exit(1);
|
|
116
|
+
});
|
|
117
|
+
program.parseAsync(process.argv).catch((err) => {
|
|
118
|
+
process.stderr.write(`gd-env-loader: unexpected error: ${err instanceof Error ? err.stack : err}\n`);
|
|
119
|
+
process.exit(EXIT_CONFIG);
|
|
120
|
+
});
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export type ErrorCode = 'ENV_FILE_NOT_FOUND' | 'ENV_FILE_UNREADABLE' | 'INVALID_PATH' | 'INVALID_HEADER' | 'MISSING_HEADER' | 'INVALID_PAYLOAD' | 'SECRET_NOT_FOUND' | 'PERMISSION_DENIED' | 'AUTH_FAILED' | 'KEY_NOT_FOUND' | 'KEY_COLLISION' | 'NO_PROJECT' | 'TIMEOUT' | 'PROVIDER_ERROR' | 'UNSUPPORTED_NODE' | 'UNRESOLVED_PLACEHOLDERS';
|
|
2
|
+
/**
|
|
3
|
+
* Every error this package throws on purpose. Messages name files, keys and secrets, never secret values.
|
|
4
|
+
*/
|
|
5
|
+
export declare class GdEnvLoaderError extends Error {
|
|
6
|
+
readonly code: ErrorCode;
|
|
7
|
+
constructor(code: ErrorCode, message: string);
|
|
8
|
+
}
|
|
9
|
+
export declare function isGdEnvLoaderError(err: unknown): err is GdEnvLoaderError;
|
|
10
|
+
/**
|
|
11
|
+
* Combines several errors into one. A single error is returned as is; for more, the code of the first is kept and
|
|
12
|
+
* every message is listed, so one run reports all problems instead of the first only.
|
|
13
|
+
*/
|
|
14
|
+
export declare function combineErrors(errors: GdEnvLoaderError[]): GdEnvLoaderError;
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.GdEnvLoaderError = void 0;
|
|
4
|
+
exports.isGdEnvLoaderError = isGdEnvLoaderError;
|
|
5
|
+
exports.combineErrors = combineErrors;
|
|
6
|
+
/**
|
|
7
|
+
* Every error this package throws on purpose. Messages name files, keys and secrets, never secret values.
|
|
8
|
+
*/
|
|
9
|
+
class GdEnvLoaderError extends Error {
|
|
10
|
+
constructor(code, message) {
|
|
11
|
+
super(message);
|
|
12
|
+
this.name = 'GdEnvLoaderError';
|
|
13
|
+
this.code = code;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
exports.GdEnvLoaderError = GdEnvLoaderError;
|
|
17
|
+
function isGdEnvLoaderError(err) {
|
|
18
|
+
return err instanceof GdEnvLoaderError;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Combines several errors into one. A single error is returned as is; for more, the code of the first is kept and
|
|
22
|
+
* every message is listed, so one run reports all problems instead of the first only.
|
|
23
|
+
*/
|
|
24
|
+
function combineErrors(errors) {
|
|
25
|
+
if (errors.length === 1)
|
|
26
|
+
return errors[0];
|
|
27
|
+
const lines = errors.map((e) => ` - [${e.code}] ${e.message}`).join('\n');
|
|
28
|
+
return new GdEnvLoaderError(errors[0].code, `${errors.length} problems:\n${lines}`);
|
|
29
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import type { SecretProvider } from './providers/types';
|
|
2
|
+
import { FetchedSecret, Source } from './resolver';
|
|
3
|
+
export { GdEnvLoaderError, isGdEnvLoaderError } from './errors';
|
|
4
|
+
export type { ErrorCode } from './errors';
|
|
5
|
+
export type { SecretProvider, AccessedSecret } from './providers/types';
|
|
6
|
+
export type { Source, FetchedSecret } from './resolver';
|
|
7
|
+
export { DEFAULT_ENV_PATH } from './path';
|
|
8
|
+
export type Logger = (message: string) => void;
|
|
9
|
+
export interface LoadOptions {
|
|
10
|
+
/** Env file path; `${VAR}` and `${VAR:-default}` are expanded. Default `secrets/${BUILD:-local}/.env`. */
|
|
11
|
+
path?: string;
|
|
12
|
+
/** Base for a relative path. Default process.cwd(). */
|
|
13
|
+
cwd?: string;
|
|
14
|
+
/**
|
|
15
|
+
* Strict mode: a missing env file is an error, and a file without placeholders logs a warning.
|
|
16
|
+
* Default: true when GD_ENV_LOADER=gcp.
|
|
17
|
+
*/
|
|
18
|
+
strict?: boolean;
|
|
19
|
+
/** loadEnv only: overwrite variables that are already set. Default false (dotenv semantics). */
|
|
20
|
+
override?: boolean;
|
|
21
|
+
/** GCP project. Default: GD_GCP_PROJECT, then the Application Default Credentials project. */
|
|
22
|
+
project?: string;
|
|
23
|
+
/** Timeout per secret in ms for Secret Manager, retries included. Default 10000. */
|
|
24
|
+
timeoutMs?: number;
|
|
25
|
+
/** Environment used for path expansion and the GD_* settings. Default process.env. */
|
|
26
|
+
env?: NodeJS.ProcessEnv;
|
|
27
|
+
/** Where secrets come from. Default: GCP Secret Manager. */
|
|
28
|
+
provider?: SecretProvider;
|
|
29
|
+
/** Receives the one-line summary and warnings. Default: stderr. `false` silences it. */
|
|
30
|
+
logger?: Logger | false;
|
|
31
|
+
}
|
|
32
|
+
export interface ResolveResult {
|
|
33
|
+
/** `passthrough`: nothing to resolve (no file, or no placeholders); `values` is empty. */
|
|
34
|
+
mode: 'passthrough' | 'resolved';
|
|
35
|
+
/** Absolute path of the env file, after expansion. */
|
|
36
|
+
path: string;
|
|
37
|
+
/** Whether the file was found. */
|
|
38
|
+
found: boolean;
|
|
39
|
+
/** Every key in the file with placeholders replaced (resolved mode only). */
|
|
40
|
+
values: Record<string, string>;
|
|
41
|
+
/** Which secret each placeholder came from. No values. */
|
|
42
|
+
sources: Source[];
|
|
43
|
+
/** The secrets that were read. */
|
|
44
|
+
secrets: FetchedSecret[];
|
|
45
|
+
/** The GCP project used (resolved mode only). */
|
|
46
|
+
project?: string;
|
|
47
|
+
}
|
|
48
|
+
export declare const formatSecret: (s: {
|
|
49
|
+
secret: string;
|
|
50
|
+
version?: string;
|
|
51
|
+
}) => string;
|
|
52
|
+
/**
|
|
53
|
+
* Reads the env file and resolves its placeholders, without touching process.env.
|
|
54
|
+
*
|
|
55
|
+
* Mode rules:
|
|
56
|
+
* - file missing: pass-through (strict: error ENV_FILE_NOT_FOUND)
|
|
57
|
+
* - file has no placeholders: pass-through (strict: also a NO_PLACEHOLDERS warning)
|
|
58
|
+
* - file has placeholders: resolve; any failure throws GdEnvLoaderError
|
|
59
|
+
*/
|
|
60
|
+
export declare function resolveEnv(opts?: LoadOptions): Promise<ResolveResult>;
|
|
61
|
+
/**
|
|
62
|
+
* resolveEnv, then writes the values into process.env. Variables that are already set are kept unless `override`.
|
|
63
|
+
* In pass-through mode nothing is written: the app's own dotenv call loads the file as before.
|
|
64
|
+
*
|
|
65
|
+
* Await it before importing modules that read process.env when they load.
|
|
66
|
+
*/
|
|
67
|
+
export declare function loadEnv(opts?: LoadOptions): Promise<ResolveResult>;
|
|
68
|
+
/**
|
|
69
|
+
* Throws if any variable still holds a {{placeholder}}, e.g. because the app was started without gd-env-loader and
|
|
70
|
+
* dotenv loaded a template. Call it right after the app's dotenv.config().
|
|
71
|
+
*/
|
|
72
|
+
export declare function assertNoPlaceholders(env?: NodeJS.ProcessEnv): void;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.formatSecret = exports.DEFAULT_ENV_PATH = exports.isGdEnvLoaderError = exports.GdEnvLoaderError = void 0;
|
|
37
|
+
exports.resolveEnv = resolveEnv;
|
|
38
|
+
exports.loadEnv = loadEnv;
|
|
39
|
+
exports.assertNoPlaceholders = assertNoPlaceholders;
|
|
40
|
+
const fs_1 = require("fs");
|
|
41
|
+
const nodePath = __importStar(require("path"));
|
|
42
|
+
const errors_1 = require("./errors");
|
|
43
|
+
const path_1 = require("./path");
|
|
44
|
+
const gcp_1 = require("./providers/gcp");
|
|
45
|
+
const resolver_1 = require("./resolver");
|
|
46
|
+
const template_1 = require("./template");
|
|
47
|
+
var errors_2 = require("./errors");
|
|
48
|
+
Object.defineProperty(exports, "GdEnvLoaderError", { enumerable: true, get: function () { return errors_2.GdEnvLoaderError; } });
|
|
49
|
+
Object.defineProperty(exports, "isGdEnvLoaderError", { enumerable: true, get: function () { return errors_2.isGdEnvLoaderError; } });
|
|
50
|
+
var path_2 = require("./path");
|
|
51
|
+
Object.defineProperty(exports, "DEFAULT_ENV_PATH", { enumerable: true, get: function () { return path_2.DEFAULT_ENV_PATH; } });
|
|
52
|
+
const PREFIX = 'gd-env-loader:';
|
|
53
|
+
function makeLogger(logger) {
|
|
54
|
+
if (logger === false)
|
|
55
|
+
return () => undefined;
|
|
56
|
+
return logger || ((m) => process.stderr.write(`${m}\n`));
|
|
57
|
+
}
|
|
58
|
+
function isStrictFromEnv(env, log) {
|
|
59
|
+
const v = (env.GD_ENV_LOADER || '').trim().toLowerCase();
|
|
60
|
+
if (v === '')
|
|
61
|
+
return false;
|
|
62
|
+
if (v === 'gcp')
|
|
63
|
+
return true;
|
|
64
|
+
log(`${PREFIX} warning: ignoring unknown GD_ENV_LOADER value "${env.GD_ENV_LOADER}" (expected "gcp").`);
|
|
65
|
+
return false;
|
|
66
|
+
}
|
|
67
|
+
const formatSecret = (s) => (s.version ? `${s.secret}@${s.version}` : s.secret);
|
|
68
|
+
exports.formatSecret = formatSecret;
|
|
69
|
+
/**
|
|
70
|
+
* Reads the env file and resolves its placeholders, without touching process.env.
|
|
71
|
+
*
|
|
72
|
+
* Mode rules:
|
|
73
|
+
* - file missing: pass-through (strict: error ENV_FILE_NOT_FOUND)
|
|
74
|
+
* - file has no placeholders: pass-through (strict: also a NO_PLACEHOLDERS warning)
|
|
75
|
+
* - file has placeholders: resolve; any failure throws GdEnvLoaderError
|
|
76
|
+
*/
|
|
77
|
+
async function resolveEnv(opts = {}) {
|
|
78
|
+
const env = opts.env || process.env;
|
|
79
|
+
const log = makeLogger(opts.logger);
|
|
80
|
+
const strict = opts.strict !== undefined ? opts.strict : isStrictFromEnv(env, log);
|
|
81
|
+
const file = nodePath.resolve(opts.cwd || process.cwd(), (0, path_1.expandPath)(opts.path || path_1.DEFAULT_ENV_PATH, env));
|
|
82
|
+
const passthrough = (found) => ({
|
|
83
|
+
mode: 'passthrough',
|
|
84
|
+
path: file,
|
|
85
|
+
found,
|
|
86
|
+
values: {},
|
|
87
|
+
sources: [],
|
|
88
|
+
secrets: [],
|
|
89
|
+
});
|
|
90
|
+
let content;
|
|
91
|
+
try {
|
|
92
|
+
content = (0, fs_1.readFileSync)(file, 'utf8');
|
|
93
|
+
}
|
|
94
|
+
catch (err) {
|
|
95
|
+
const code = err.code;
|
|
96
|
+
if (code === 'ENOENT') {
|
|
97
|
+
if (strict)
|
|
98
|
+
throw new errors_1.GdEnvLoaderError('ENV_FILE_NOT_FOUND', `Env file not found: ${file}`);
|
|
99
|
+
return passthrough(false);
|
|
100
|
+
}
|
|
101
|
+
throw new errors_1.GdEnvLoaderError('ENV_FILE_UNREADABLE', `Cannot read env file ${file}: ${err.message}`);
|
|
102
|
+
}
|
|
103
|
+
const template = (0, template_1.parseTemplate)(content, file);
|
|
104
|
+
if (template.placeholders.length === 0) {
|
|
105
|
+
if (strict) {
|
|
106
|
+
log(`${PREFIX} warning [NO_PLACEHOLDERS]: ${file} has no {{placeholders}}; ` +
|
|
107
|
+
'starting with its values as they are (expected only during migration or rollback).');
|
|
108
|
+
}
|
|
109
|
+
return passthrough(true);
|
|
110
|
+
}
|
|
111
|
+
const started = Date.now();
|
|
112
|
+
const provider = opts.provider || (0, gcp_1.createGcpProvider)({ timeoutMs: opts.timeoutMs });
|
|
113
|
+
const project = opts.project || env.GD_GCP_PROJECT || (provider.defaultProject ? await provider.defaultProject() : undefined);
|
|
114
|
+
if (!project) {
|
|
115
|
+
throw new errors_1.GdEnvLoaderError('NO_PROJECT', 'Could not determine the GCP project. Set GD_GCP_PROJECT or --project.');
|
|
116
|
+
}
|
|
117
|
+
const resolution = await (0, resolver_1.resolveTemplate)(template, file, provider, project);
|
|
118
|
+
log(`${PREFIX} resolved ${template.placeholders.length} placeholder(s) in ${Object.keys(resolution.values).length} ` +
|
|
119
|
+
`key(s) from ${resolution.secrets.map(exports.formatSecret).join(', ')} (project ${project}, ${Date.now() - started} ms)`);
|
|
120
|
+
return {
|
|
121
|
+
mode: 'resolved',
|
|
122
|
+
path: file,
|
|
123
|
+
found: true,
|
|
124
|
+
values: resolution.values,
|
|
125
|
+
sources: resolution.sources,
|
|
126
|
+
secrets: resolution.secrets,
|
|
127
|
+
project,
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* resolveEnv, then writes the values into process.env. Variables that are already set are kept unless `override`.
|
|
132
|
+
* In pass-through mode nothing is written: the app's own dotenv call loads the file as before.
|
|
133
|
+
*
|
|
134
|
+
* Await it before importing modules that read process.env when they load.
|
|
135
|
+
*/
|
|
136
|
+
async function loadEnv(opts = {}) {
|
|
137
|
+
const result = await resolveEnv(opts);
|
|
138
|
+
if (result.mode === 'resolved') {
|
|
139
|
+
for (const [key, value] of Object.entries(result.values)) {
|
|
140
|
+
if (opts.override || process.env[key] === undefined)
|
|
141
|
+
process.env[key] = value;
|
|
142
|
+
}
|
|
143
|
+
process.env.GD_ENV_LOADER_RESOLVED = '1';
|
|
144
|
+
}
|
|
145
|
+
return result;
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* Throws if any variable still holds a {{placeholder}}, e.g. because the app was started without gd-env-loader and
|
|
149
|
+
* dotenv loaded a template. Call it right after the app's dotenv.config().
|
|
150
|
+
*/
|
|
151
|
+
function assertNoPlaceholders(env = process.env) {
|
|
152
|
+
const keys = Object.keys(env).filter((k) => {
|
|
153
|
+
const v = env[k];
|
|
154
|
+
return typeof v === 'string' && (0, template_1.placeholderRegExp)().test(v);
|
|
155
|
+
});
|
|
156
|
+
if (keys.length > 0) {
|
|
157
|
+
throw new errors_1.GdEnvLoaderError('UNRESOLVED_PLACEHOLDERS', `Unresolved {{placeholders}} in ${keys.sort().join(', ')}. Start the app through ` +
|
|
158
|
+
'"gd-env-loader run -- <command>" or call loadEnv() before reading the environment.');
|
|
159
|
+
}
|
|
160
|
+
}
|
package/dist/path.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export declare const DEFAULT_ENV_PATH = "secrets/${BUILD:-local}/.env";
|
|
2
|
+
/**
|
|
3
|
+
* Expands `${VAR}` and `${VAR:-default}` in a path, the way a POSIX shell does: the default applies when the variable
|
|
4
|
+
* is unset or empty. An unset `${VAR}` without a default is an error, so a missing BUILD can't silently produce
|
|
5
|
+
* `secrets//.env`. Anything else, including a bare `$`, is left as is.
|
|
6
|
+
*/
|
|
7
|
+
export declare function expandPath(input: string, env: NodeJS.ProcessEnv): string;
|
package/dist/path.js
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.DEFAULT_ENV_PATH = void 0;
|
|
4
|
+
exports.expandPath = expandPath;
|
|
5
|
+
const errors_1 = require("./errors");
|
|
6
|
+
exports.DEFAULT_ENV_PATH = 'secrets/${BUILD:-local}/.env';
|
|
7
|
+
const VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
|
|
8
|
+
/**
|
|
9
|
+
* Expands `${VAR}` and `${VAR:-default}` in a path, the way a POSIX shell does: the default applies when the variable
|
|
10
|
+
* is unset or empty. An unset `${VAR}` without a default is an error, so a missing BUILD can't silently produce
|
|
11
|
+
* `secrets//.env`. Anything else, including a bare `$`, is left as is.
|
|
12
|
+
*/
|
|
13
|
+
function expandPath(input, env) {
|
|
14
|
+
return input.replace(VAR_PATTERN, (_match, name, fallback) => {
|
|
15
|
+
const value = env[name];
|
|
16
|
+
if (value !== undefined && value !== '')
|
|
17
|
+
return value;
|
|
18
|
+
if (fallback !== undefined)
|
|
19
|
+
return fallback;
|
|
20
|
+
throw new errors_1.GdEnvLoaderError('INVALID_PATH', `Env file path "${input}" uses \${${name}}, which is not set. Set it or give a default: \${${name}:-value}.`);
|
|
21
|
+
});
|
|
22
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parses a secret payload into key/value pairs. A payload whose first non-space character is `{` or `[` is JSON (a flat
|
|
3
|
+
* object; numbers and booleans become strings). Anything else is parsed as dotenv text.
|
|
4
|
+
*
|
|
5
|
+
* Error messages never quote the payload: JSON.parse's own message can contain a slice of it.
|
|
6
|
+
*/
|
|
7
|
+
export declare function parsePayload(text: string, label: string): Record<string, string>;
|
package/dist/payload.js
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.parsePayload = parsePayload;
|
|
37
|
+
const dotenv = __importStar(require("dotenv"));
|
|
38
|
+
const errors_1 = require("./errors");
|
|
39
|
+
/**
|
|
40
|
+
* Parses a secret payload into key/value pairs. A payload whose first non-space character is `{` or `[` is JSON (a flat
|
|
41
|
+
* object; numbers and booleans become strings). Anything else is parsed as dotenv text.
|
|
42
|
+
*
|
|
43
|
+
* Error messages never quote the payload: JSON.parse's own message can contain a slice of it.
|
|
44
|
+
*/
|
|
45
|
+
function parsePayload(text, label) {
|
|
46
|
+
const trimmed = text.replace(/^\uFEFF/, '').trimStart();
|
|
47
|
+
// `[` counts as JSON too, so an array is rejected instead of silently parsed as dotenv text with no keys.
|
|
48
|
+
if (!trimmed.startsWith('{') && !trimmed.startsWith('['))
|
|
49
|
+
return dotenv.parse(trimmed);
|
|
50
|
+
let data;
|
|
51
|
+
try {
|
|
52
|
+
data = JSON.parse(trimmed);
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
throw new errors_1.GdEnvLoaderError('INVALID_PAYLOAD', `Secret ${label} looks like JSON but is not valid JSON.`);
|
|
56
|
+
}
|
|
57
|
+
if (data === null || typeof data !== 'object' || Array.isArray(data)) {
|
|
58
|
+
throw new errors_1.GdEnvLoaderError('INVALID_PAYLOAD', `Secret ${label} must be a JSON object of key/value pairs.`);
|
|
59
|
+
}
|
|
60
|
+
const result = {};
|
|
61
|
+
const bad = [];
|
|
62
|
+
for (const [key, value] of Object.entries(data)) {
|
|
63
|
+
if (typeof value === 'string')
|
|
64
|
+
result[key] = value;
|
|
65
|
+
else if (typeof value === 'number' || typeof value === 'boolean')
|
|
66
|
+
result[key] = String(value);
|
|
67
|
+
else
|
|
68
|
+
bad.push(key);
|
|
69
|
+
}
|
|
70
|
+
if (bad.length > 0) {
|
|
71
|
+
throw new errors_1.GdEnvLoaderError('INVALID_PAYLOAD', `Secret ${label}: values must be strings, numbers or booleans; not so for key(s) ${bad.join(', ')}.`);
|
|
72
|
+
}
|
|
73
|
+
return result;
|
|
74
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { SecretManagerServiceClient } from '@google-cloud/secret-manager';
|
|
2
|
+
import type { SecretProvider } from './types';
|
|
3
|
+
/** The parts of SecretManagerServiceClient used here; tests pass a fake. */
|
|
4
|
+
export type ClientLike = Pick<SecretManagerServiceClient, 'accessSecretVersion' | 'getProjectId'>;
|
|
5
|
+
export interface GcpProviderOptions {
|
|
6
|
+
/** Timeout per secret in ms, retries included (the SDK retries UNAVAILABLE and RESOURCE_EXHAUSTED). Default 10000. */
|
|
7
|
+
timeoutMs?: number;
|
|
8
|
+
/** For tests. Default: a SecretManagerServiceClient using Application Default Credentials. */
|
|
9
|
+
client?: ClientLike;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Reads secrets from GCP Secret Manager with the official SDK, authenticated with Application Default Credentials.
|
|
13
|
+
* The client is created on first use.
|
|
14
|
+
*/
|
|
15
|
+
export declare function createGcpProvider(options?: GcpProviderOptions): SecretProvider;
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.createGcpProvider = createGcpProvider;
|
|
4
|
+
const errors_1 = require("../errors");
|
|
5
|
+
// The SDK's dependencies use require('node:...'), which Node supports from 14.18.
|
|
6
|
+
const MIN_NODE = [14, 18];
|
|
7
|
+
const AUTH_HINT = 'Locally, run "gcloud auth application-default login"; on GKE, check Workload Identity.';
|
|
8
|
+
function createClient() {
|
|
9
|
+
const [major, minor] = process.versions.node.split('.').map(Number);
|
|
10
|
+
if (major < MIN_NODE[0] || (major === MIN_NODE[0] && minor < MIN_NODE[1])) {
|
|
11
|
+
throw new errors_1.GdEnvLoaderError('UNSUPPORTED_NODE', `Resolving secrets needs Node ${MIN_NODE.join('.')} or later; this is Node ${process.versions.node}. ` +
|
|
12
|
+
'Pass-through (files without placeholders) still works on this version.');
|
|
13
|
+
}
|
|
14
|
+
// Required here, not at import, so pass-through runs never load the SDK.
|
|
15
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
16
|
+
const sdk = require('@google-cloud/secret-manager');
|
|
17
|
+
return new sdk.SecretManagerServiceClient();
|
|
18
|
+
}
|
|
19
|
+
/** Maps SDK (gRPC status) errors to our codes. */
|
|
20
|
+
function toError(err, label) {
|
|
21
|
+
const detail = err.details || err.message || 'unknown error';
|
|
22
|
+
switch (err.code) {
|
|
23
|
+
case 7:
|
|
24
|
+
return new errors_1.GdEnvLoaderError('PERMISSION_DENIED', `Reading ${label}: permission denied (${detail}). The identity running this needs ` +
|
|
25
|
+
"roles/secretmanager.secretAccessor on the secret; on GKE check the pod's serviceAccountName and its " +
|
|
26
|
+
'Workload Identity binding.');
|
|
27
|
+
case 5:
|
|
28
|
+
return new errors_1.GdEnvLoaderError('SECRET_NOT_FOUND', `Reading ${label}: not found (${detail}).`);
|
|
29
|
+
case 16:
|
|
30
|
+
return new errors_1.GdEnvLoaderError('AUTH_FAILED', `Reading ${label}: not authenticated (${detail}). ${AUTH_HINT}`);
|
|
31
|
+
case 4:
|
|
32
|
+
return new errors_1.GdEnvLoaderError('TIMEOUT', `Reading ${label}: timed out (${detail}).`);
|
|
33
|
+
default:
|
|
34
|
+
if (err.code === undefined && /credentials/i.test(detail)) {
|
|
35
|
+
return new errors_1.GdEnvLoaderError('AUTH_FAILED', `Could not get Google credentials (${detail}). ${AUTH_HINT}`);
|
|
36
|
+
}
|
|
37
|
+
return new errors_1.GdEnvLoaderError('PROVIDER_ERROR', `Reading ${label}: ${detail}`);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Reads secrets from GCP Secret Manager with the official SDK, authenticated with Application Default Credentials.
|
|
42
|
+
* The client is created on first use.
|
|
43
|
+
*/
|
|
44
|
+
function createGcpProvider(options = {}) {
|
|
45
|
+
const timeout = options.timeoutMs || 10000;
|
|
46
|
+
let client = options.client;
|
|
47
|
+
const getClient = () => (client = client || createClient());
|
|
48
|
+
return {
|
|
49
|
+
async access(project, secret) {
|
|
50
|
+
const label = `secret ${secret} in project ${project}`;
|
|
51
|
+
const c = getClient();
|
|
52
|
+
try {
|
|
53
|
+
const [res] = await c.accessSecretVersion({ name: `projects/${project}/secrets/${secret}/versions/latest` }, { timeout });
|
|
54
|
+
const data = res.payload && res.payload.data;
|
|
55
|
+
if (data === null || data === undefined) {
|
|
56
|
+
throw new errors_1.GdEnvLoaderError('PROVIDER_ERROR', `Reading ${label}: the response has no payload.`);
|
|
57
|
+
}
|
|
58
|
+
const m = /\/versions\/([^/]+)$/.exec(res.name || '');
|
|
59
|
+
return {
|
|
60
|
+
data: typeof data === 'string' ? data : Buffer.from(data).toString('utf8'),
|
|
61
|
+
version: m ? m[1] : undefined,
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
catch (err) {
|
|
65
|
+
throw err instanceof errors_1.GdEnvLoaderError ? err : toError(err, label);
|
|
66
|
+
}
|
|
67
|
+
},
|
|
68
|
+
async defaultProject() {
|
|
69
|
+
const c = getClient();
|
|
70
|
+
try {
|
|
71
|
+
return (await c.getProjectId()) || undefined;
|
|
72
|
+
}
|
|
73
|
+
catch {
|
|
74
|
+
return undefined;
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
};
|
|
78
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export interface AccessedSecret {
|
|
2
|
+
/** The payload as text. */
|
|
3
|
+
data: string;
|
|
4
|
+
/** The version served (the number behind `latest`), when known. */
|
|
5
|
+
version?: string;
|
|
6
|
+
}
|
|
7
|
+
/** Where secrets come from. The GCP provider is the real one; tests inject fakes. */
|
|
8
|
+
export interface SecretProvider {
|
|
9
|
+
/** Fetches the latest version of a secret. Throws GdEnvLoaderError with a specific code on failure. */
|
|
10
|
+
access(project: string, secret: string): Promise<AccessedSecret>;
|
|
11
|
+
/** The project to use when none is configured, or undefined if it can't be determined. */
|
|
12
|
+
defaultProject?(): Promise<string | undefined>;
|
|
13
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { SecretProvider } from './providers/types';
|
|
2
|
+
import { ParsedTemplate } from './template';
|
|
3
|
+
export interface Source {
|
|
4
|
+
/** The env key that received the value. */
|
|
5
|
+
envKey: string;
|
|
6
|
+
/** The key looked up in the secret payload. */
|
|
7
|
+
secretKey: string;
|
|
8
|
+
secret: string;
|
|
9
|
+
/** The version served (`latest` resolves to a number), when known. */
|
|
10
|
+
version?: string;
|
|
11
|
+
}
|
|
12
|
+
export interface FetchedSecret {
|
|
13
|
+
secret: string;
|
|
14
|
+
version?: string;
|
|
15
|
+
}
|
|
16
|
+
export interface Resolution {
|
|
17
|
+
/** Every key in the template, with placeholders replaced. */
|
|
18
|
+
values: Record<string, string>;
|
|
19
|
+
sources: Source[];
|
|
20
|
+
secrets: FetchedSecret[];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Fetches every secret the template refers to (each once, in parallel) and substitutes the placeholders.
|
|
24
|
+
* All problems found are reported together, so one run lists every missing key.
|
|
25
|
+
*/
|
|
26
|
+
export declare function resolveTemplate(template: ParsedTemplate, file: string, provider: SecretProvider, project: string): Promise<Resolution>;
|
package/dist/resolver.js
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.resolveTemplate = resolveTemplate;
|
|
4
|
+
const errors_1 = require("./errors");
|
|
5
|
+
const payload_1 = require("./payload");
|
|
6
|
+
const template_1 = require("./template");
|
|
7
|
+
const toError = (err, secret) => err instanceof errors_1.GdEnvLoaderError
|
|
8
|
+
? err
|
|
9
|
+
: new errors_1.GdEnvLoaderError('PROVIDER_ERROR', `Reading secret ${secret}: ${err instanceof Error ? err.message : err}`);
|
|
10
|
+
/**
|
|
11
|
+
* Fetches every secret the template refers to (each once, in parallel) and substitutes the placeholders.
|
|
12
|
+
* All problems found are reported together, so one run lists every missing key.
|
|
13
|
+
*/
|
|
14
|
+
async function resolveTemplate(template, file, provider, project) {
|
|
15
|
+
const { headerSecrets, placeholders } = template;
|
|
16
|
+
const unqualified = placeholders.filter((p) => !p.secret);
|
|
17
|
+
if (unqualified.length > 0 && headerSecrets.length === 0) {
|
|
18
|
+
const keys = Array.from(new Set(unqualified.map((p) => p.envKey))).join(', ');
|
|
19
|
+
throw new errors_1.GdEnvLoaderError('MISSING_HEADER', `${file}: ${keys} use(s) unqualified placeholders, but the file has no "# @gd-env-loader secrets=..." line. ` +
|
|
20
|
+
'Add the header or qualify them as {{secret/KEY}}.');
|
|
21
|
+
}
|
|
22
|
+
// Header secrets are fetched even if unused, so a typo in the header fails fast.
|
|
23
|
+
const wanted = Array.from(new Set([...headerSecrets, ...placeholders.map((p) => p.secret).filter(Boolean)]));
|
|
24
|
+
const settled = await Promise.all(wanted.map((secret) => provider.access(project, secret).then((res) => ({ secret, version: res.version, payload: (0, payload_1.parsePayload)(res.data, secret) }), (err) => toError(err, secret))));
|
|
25
|
+
const fetchErrors = settled.filter((s) => s instanceof errors_1.GdEnvLoaderError);
|
|
26
|
+
if (fetchErrors.length > 0)
|
|
27
|
+
throw (0, errors_1.combineErrors)(fetchErrors);
|
|
28
|
+
const loaded = new Map(settled.map((s) => [s.secret, s]));
|
|
29
|
+
const problems = [];
|
|
30
|
+
const sources = [];
|
|
31
|
+
const values = {};
|
|
32
|
+
for (const [envKey, raw] of Object.entries(template.values)) {
|
|
33
|
+
// One pass per value, so a resolved value is never re-scanned for placeholders.
|
|
34
|
+
values[envKey] = raw.replace((0, template_1.placeholderRegExp)(), (match, secret, key) => {
|
|
35
|
+
const holders = secret
|
|
36
|
+
? [loaded.get(secret)].filter((s) => key in s.payload)
|
|
37
|
+
: headerSecrets.map((s) => loaded.get(s)).filter((s) => key in s.payload);
|
|
38
|
+
if (holders.length === 1) {
|
|
39
|
+
const from = holders[0];
|
|
40
|
+
sources.push({ envKey, secretKey: key, secret: from.secret, version: from.version });
|
|
41
|
+
return from.payload[key];
|
|
42
|
+
}
|
|
43
|
+
if (holders.length === 0) {
|
|
44
|
+
const where = secret ? `secret ${secret}` : `any header secret (${headerSecrets.join(', ')})`;
|
|
45
|
+
problems.push(new errors_1.GdEnvLoaderError('KEY_NOT_FOUND', `${envKey}: key "${key}" is not in ${where}.`));
|
|
46
|
+
}
|
|
47
|
+
else {
|
|
48
|
+
problems.push(new errors_1.GdEnvLoaderError('KEY_COLLISION', `${envKey}: key "${key}" is in ${holders.map((h) => h.secret).join(' and ')}. ` +
|
|
49
|
+
`Qualify it, e.g. {{${holders[0].secret}/${key}}}.`));
|
|
50
|
+
}
|
|
51
|
+
return match;
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
if (problems.length > 0)
|
|
55
|
+
throw (0, errors_1.combineErrors)(problems);
|
|
56
|
+
return { values, sources, secrets: wanted.map((s) => ({ secret: s, version: loaded.get(s).version })) };
|
|
57
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
export interface Placeholder {
|
|
2
|
+
/** The env key whose value contains the placeholder. */
|
|
3
|
+
envKey: string;
|
|
4
|
+
/** Set for qualified placeholders (`{{secret/KEY}}`) only. */
|
|
5
|
+
secret?: string;
|
|
6
|
+
/** The key looked up in the secret payload. */
|
|
7
|
+
key: string;
|
|
8
|
+
}
|
|
9
|
+
export interface ParsedTemplate {
|
|
10
|
+
/** Secret IDs from the `# @gd-env-loader secrets=...` line; empty without a header. */
|
|
11
|
+
headerSecrets: string[];
|
|
12
|
+
/** Every key=value in the file, as dotenv parses it, before substitution. */
|
|
13
|
+
values: Record<string, string>;
|
|
14
|
+
placeholders: Placeholder[];
|
|
15
|
+
}
|
|
16
|
+
/** `{{ [secret/]KEY }}`. Text in braces that doesn't match is not a placeholder. */
|
|
17
|
+
export declare const placeholderRegExp: () => RegExp;
|
|
18
|
+
/** Parses `# @gd-env-loader secrets=a,b`. At most one such line is allowed. */
|
|
19
|
+
export declare function parseHeader(content: string, file: string): string[];
|
|
20
|
+
/** Parses a template. `file` is used in messages only. */
|
|
21
|
+
export declare function parseTemplate(content: string, file: string): ParsedTemplate;
|
package/dist/template.js
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.placeholderRegExp = void 0;
|
|
37
|
+
exports.parseHeader = parseHeader;
|
|
38
|
+
exports.parseTemplate = parseTemplate;
|
|
39
|
+
const dotenv = __importStar(require("dotenv"));
|
|
40
|
+
const errors_1 = require("./errors");
|
|
41
|
+
const HEADER_RE = /^[ \t]*#[ \t]*@gd-env-loader\b(.*)$/gm;
|
|
42
|
+
const SECRETS_RE = /^secrets=([A-Za-z0-9_-]+(?:,[A-Za-z0-9_-]+)*)$/;
|
|
43
|
+
/** `{{ [secret/]KEY }}`. Text in braces that doesn't match is not a placeholder. */
|
|
44
|
+
const placeholderRegExp = () => /\{\{\s*(?:([A-Za-z0-9_-]+)\/)?([A-Za-z0-9_.-]+)\s*\}\}/g;
|
|
45
|
+
exports.placeholderRegExp = placeholderRegExp;
|
|
46
|
+
/** Parses `# @gd-env-loader secrets=a,b`. At most one such line is allowed. */
|
|
47
|
+
function parseHeader(content, file) {
|
|
48
|
+
const lines = Array.from(content.matchAll(HEADER_RE));
|
|
49
|
+
if (lines.length === 0)
|
|
50
|
+
return [];
|
|
51
|
+
if (lines.length > 1) {
|
|
52
|
+
throw new errors_1.GdEnvLoaderError('INVALID_HEADER', `${file}: more than one "# @gd-env-loader" line. Keep one.`);
|
|
53
|
+
}
|
|
54
|
+
const body = lines[0][1].trim();
|
|
55
|
+
const m = SECRETS_RE.exec(body);
|
|
56
|
+
if (!m) {
|
|
57
|
+
throw new errors_1.GdEnvLoaderError('INVALID_HEADER', `${file}: header must be "# @gd-env-loader secrets=<id>[,<id>...]" (secret IDs: letters, digits, _ and -), ` +
|
|
58
|
+
`got "${body}".`);
|
|
59
|
+
}
|
|
60
|
+
const secrets = m[1].split(',');
|
|
61
|
+
const dup = secrets.find((s, i) => secrets.indexOf(s) !== i);
|
|
62
|
+
if (dup)
|
|
63
|
+
throw new errors_1.GdEnvLoaderError('INVALID_HEADER', `${file}: secret "${dup}" is listed twice in the header.`);
|
|
64
|
+
return secrets;
|
|
65
|
+
}
|
|
66
|
+
/** Parses a template. `file` is used in messages only. */
|
|
67
|
+
function parseTemplate(content, file) {
|
|
68
|
+
const values = dotenv.parse(content);
|
|
69
|
+
const placeholders = [];
|
|
70
|
+
for (const [envKey, value] of Object.entries(values)) {
|
|
71
|
+
for (const m of value.matchAll((0, exports.placeholderRegExp)()))
|
|
72
|
+
placeholders.push({ envKey, secret: m[1], key: m[2] });
|
|
73
|
+
}
|
|
74
|
+
return { headerSecrets: parseHeader(content, file), values, placeholders };
|
|
75
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,47 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bygd/gd-env-loader",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Load a .env file and resolve {{placeholders}} in it from GCP Secret Manager, as a CLI wrapper or a library.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"dotenv",
|
|
7
|
+
"env",
|
|
8
|
+
"secrets",
|
|
9
|
+
"secret-manager",
|
|
10
|
+
"gcp",
|
|
11
|
+
"google-cloud",
|
|
12
|
+
"kubernetes"
|
|
13
|
+
],
|
|
14
|
+
"license": "MIT",
|
|
15
|
+
"main": "dist/index.js",
|
|
16
|
+
"types": "dist/index.d.ts",
|
|
17
|
+
"bin": {
|
|
18
|
+
"gd-env-loader": "dist/cli.js"
|
|
19
|
+
},
|
|
20
|
+
"files": [
|
|
21
|
+
"dist",
|
|
22
|
+
"README.md"
|
|
23
|
+
],
|
|
24
|
+
"publishConfig": {
|
|
25
|
+
"access": "public"
|
|
26
|
+
},
|
|
27
|
+
"engines": {
|
|
28
|
+
"node": ">=12"
|
|
29
|
+
},
|
|
30
|
+
"scripts": {
|
|
31
|
+
"clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
|
|
32
|
+
"build": "npm run clean && tsc -p tsconfig.build.json",
|
|
33
|
+
"typecheck": "tsc --noEmit",
|
|
34
|
+
"test": "npm run build && vitest run",
|
|
35
|
+
"prepublishOnly": "npm run typecheck && npm test"
|
|
36
|
+
},
|
|
37
|
+
"dependencies": {
|
|
38
|
+
"@google-cloud/secret-manager": "^5.6.0",
|
|
39
|
+
"commander": "^9.5.0",
|
|
40
|
+
"dotenv": "^16.4.7"
|
|
41
|
+
},
|
|
42
|
+
"devDependencies": {
|
|
43
|
+
"@types/node": "^18.19.0",
|
|
44
|
+
"typescript": "~5.9.0",
|
|
45
|
+
"vitest": "^3.2.0"
|
|
46
|
+
}
|
|
47
|
+
}
|