@kaynooo/cli-env 0.14.0 → 0.15.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/package.json CHANGED
@@ -1,17 +1,17 @@
1
1
  {
2
2
  "name": "@kaynooo/cli-env",
3
3
  "type": "module",
4
- "version": "0.14.0",
5
- "description": "ev lists and edits .env files with secrets masked, redact masks secrets in any piped output.",
4
+ "version": "0.15.1",
5
+ "description": "ev lists and edits .env files with secrets masked, and ev redact masks secrets in any piped output.",
6
6
  "author": "Kaynooo <contact@kaynooo.fr>",
7
7
  "license": "MIT",
8
- "homepage": "https://git.kaynooo.fr/kaynooo/cli/src/branch/main/packages/env#readme",
8
+ "homepage": "https://github.com/Kayno0o/cli/tree/main/packages/env#readme",
9
9
  "repository": {
10
10
  "type": "git",
11
- "url": "git+https://git.kaynooo.fr/kaynooo/cli.git",
11
+ "url": "git+https://github.com/Kayno0o/cli.git",
12
12
  "directory": "packages/env"
13
13
  },
14
- "bugs": "https://git.kaynooo.fr/kaynooo/cli/issues",
14
+ "bugs": "https://github.com/Kayno0o/cli/issues",
15
15
  "keywords": ["env", "dotenv", "secrets", "redact", "mask"],
16
16
  "exports": {
17
17
  "./dotenv": "./src/dotenv.ts",
@@ -21,8 +21,7 @@
21
21
  "./redactor": "./src/redactor.ts"
22
22
  },
23
23
  "bin": {
24
- "ev": "./dist/ev.js",
25
- "redact": "./dist/redact.js"
24
+ "ev": "./dist/ev.js"
26
25
  },
27
26
  "files": ["dist", "src"],
28
27
  "engines": {
@@ -32,11 +31,10 @@
32
31
  "registry": "https://git.kaynooo.fr/api/packages/kaynooo/npm/"
33
32
  },
34
33
  "scripts": {
35
- "build": "$npm_execpath build src/ev.ts src/redact.ts --target bun --outdir dist",
36
- "ev": "$npm_execpath src/ev.ts",
37
- "redact": "$npm_execpath src/redact.ts"
34
+ "build": "$npm_execpath build src/ev.ts --target bun --outdir dist",
35
+ "ev": "$npm_execpath src/ev.ts"
38
36
  },
39
- "devDependencies": {
40
- "@kaynooo/cli-kit": "0.40.0"
37
+ "dependencies": {
38
+ "@kaynooo/cli-kit": "0.45.1"
41
39
  }
42
40
  }
@@ -9,11 +9,10 @@ import { shellQuote } from '@kaynooo/cli-kit/shell'
9
9
  import { audit as findExposed } from '../audit'
10
10
  import { fixCompose, shutOthersOut } from '../fix'
11
11
 
12
- const usage = `ev audit [dir...] [--fix]
12
+ const usage = `ev audit [dir...] [--fix]: lists the .env files any account can read or git tracks and the compose files writing a secret out, never printing a value
13
13
 
14
- Lists the .env files any account on the machine can read or git tracks, and the compose files any account can read that write a secret out (a secret-named value or a URL password) instead of reading it from a .env, never printing a value.
15
- Looks under each folder (the current one by default) down to 5 levels, skipping node_modules, vendor and .git, and leaves .example, .sample, .template and .dist files out. A folder it cannot read is named on stderr.
16
- With --fix, moves each secret a listed compose file writes out into the .env beside it as \${KEY}, puts it back when \`docker compose config\` resolves differently after, and shuts other accounts out of both files and of every listed .env; a key the .env already sets to another value stays put.`
14
+ It looks under each folder (the current one by default) down to 5 levels, skipping \`node_modules\`, \`vendor\` and \`.git\`, and leaves \`.example\`, \`.sample\`, \`.template\` and \`.dist\` files out.
15
+ With --fix, each secret a listed compose file writes out moves into the .env beside it as \`\${KEY}\` and goes back when \`docker compose config\` resolves differently after; a key the .env already sets to another value stays put.`
17
16
 
18
17
  const EXITS: ExitRow[] = [[0, 'it finds none (with --fix, when none is left)'], [1, 'it finds one'], [2, 'a usage error']]
19
18
 
@@ -2,7 +2,7 @@ import type { ExitRow } from '@kaynooo/cli-kit'
2
2
  import { badUsage, fail, isInteractive, parse, readInput } from '@kaynooo/cli-kit'
3
3
  import { input } from '@kaynooo/cli-kit/prompt'
4
4
  import { entries, lastLine, removeKey, setLine } from '../dotenv'
5
- import { loadKnown, readEnv, withLocks, writeEnv } from '../files'
5
+ import { assertDotenvName, loadKnown, readEnv, withLocks, writeEnv } from '../files'
6
6
  import { maskValue } from '../mask'
7
7
 
8
8
  const DEFAULT_FILE = '.env'
@@ -53,6 +53,8 @@ function checkKey(key: string): void {
53
53
  }
54
54
 
55
55
  async function readOrEmpty(path: string) {
56
+ assertDotenvName(path)
57
+
56
58
  return await Bun.file(path).exists() ? readEnv(path) : { lines: [] }
57
59
  }
58
60
 
@@ -8,10 +8,8 @@ import { checkApp } from '../pins'
8
8
  const usage = `ev pins [dir] [--except NAME,...]
9
9
 
10
10
  Checks that an app's tests pin the env that reaches outside.
11
- Reads the app's env schema (the file calling defineEnv, src/env.ts) and lists its optional URL, key, token, secret, password and host variables, then the ones no \`.env.test\` entry, test-level overrideEnv or local bunfig preload dropping what .env sets pins, and each test file that calls testSite or proxyKeyTests without pinning them all.
12
- A file whose pages reach none of them says so with a \`// ev pins: none reached, <why>\` comment.
13
- The dir is an app, or a monorepo holding apps one level down (the current folder by default).
14
- Reads variable names only, never a value.`
11
+ Lists the optional URL, key, token, secret, password and host variables of the app's \`defineEnv\` schema that no \`.env.test\` entry, \`overrideEnv\` or bunfig preload pins, and each test file calling \`testSite\` or \`proxyKeyTests\` without pinning them all; a file reaching none says so with a \`// ev pins: none reached, <why>\` comment.
12
+ The dir is an app, or a monorepo holding apps one level down (the current folder by default). It reads variable names only, never a value.`
15
13
 
16
14
  const EXITS: ExitRow[] = [[0, 'everything is pinned'], [1, 'something is not'], [2, 'a usage error']]
17
15
 
@@ -4,12 +4,12 @@ import type { KnownSecrets } from '../mask'
4
4
  import { fail, jsonOption, parse, printJson, role, table } from '@kaynooo/cli-kit'
5
5
  import { $ } from 'bun'
6
6
  import { entries, parseDotenv } from '../dotenv'
7
- import { envFiles, loadKnown, readEnv } from '../files'
7
+ import { assertDotenvName, assertDotenvText, envFiles, loadKnown, readEnv } from '../files'
8
8
  import { isSecretKey, maskValue } from '../mask'
9
9
 
10
10
  const listUsage = `ev list [file]
11
11
 
12
- Prints every key of the folder's .env* files, or of one file, with secret values masked: a few leading characters and the length under a key named like TOKEN, SECRET, PASSWORD, PASS, PWD, KEY, PRIVATE, DSN, AUTH, SALT or COOKIE, any value equal to a secret of the folder's .env* files, and the password and tokens of any URL.
12
+ Prints every key of the folder's .env* files, or of one file, with secret values masked to a few leading characters and the length.
13
13
 
14
14
  --json prints [{file, key, value, secret}], value masked and secret true when a value was.`
15
15
 
@@ -60,11 +60,11 @@ function printRows(rows: Row[], json: boolean, plain: () => void): void {
60
60
  }
61
61
 
62
62
  // Reads each file once and learns the secrets of the folder and of these files, so a value is masked whatever key holds it.
63
- async function readAll(names: string[]): Promise<{ files: [name: string, file: Dotenv][], known: KnownSecrets }> {
63
+ async function readAll(names: string[], scanned: boolean): Promise<{ files: [name: string, file: Dotenv][], known: KnownSecrets }> {
64
64
  const files: [string, Dotenv][] = []
65
65
 
66
66
  for (const name of names)
67
- files.push([name, await readEnv(name)])
67
+ files.push([name, await readEnv(name, { scanned })])
68
68
 
69
69
  return { files, known: await loadKnown(process.cwd(), files.map(([, file]) => file)) }
70
70
  }
@@ -80,7 +80,7 @@ export async function list(args: string[]): Promise<number> {
80
80
 
81
81
  const rows: Row[] = []
82
82
 
83
- const { files, known } = await readAll(names)
83
+ const { files, known } = await readAll(names, file === undefined)
84
84
 
85
85
  for (const [name, file] of files) {
86
86
  for (const [key, value] of entries(file))
@@ -106,7 +106,7 @@ export async function get(args: string[]): Promise<number> {
106
106
  const names = file === undefined ? await envFiles() : [file]
107
107
  const rows: Row[] = []
108
108
 
109
- const { files, known } = await readAll(names)
109
+ const { files, known } = await readAll(names, file === undefined)
110
110
 
111
111
  for (const [name, file] of files) {
112
112
  const value = entries(file).get(key)
@@ -161,7 +161,7 @@ export async function grep(args: string[]): Promise<number> {
161
161
  const names = given.length === 0 ? await envFiles() : given
162
162
  const rows: Row[] = []
163
163
 
164
- const { files, known } = await readAll(names)
164
+ const { files, known } = await readAll(names, given.length === 0)
165
165
 
166
166
  for (const [name, file] of files) {
167
167
  for (const [key, value] of entries(file)) {
@@ -190,12 +190,18 @@ export async function show(args: string[]): Promise<number> {
190
190
  if (revision.startsWith('-'))
191
191
  fail(`${revision} is not a revision: it reads as a git option`)
192
192
 
193
+ const redact = `git show ${revision}:${path} | ev redact`
194
+
195
+ assertDotenvName(path, redact)
196
+
193
197
  const shown = await $`git show --end-of-options ${`${revision}:${path}`}`.quiet().nothrow()
194
198
 
195
199
  if (shown.exitCode !== 0)
196
200
  fail(`git show ${revision}:${path} failed: ${shown.stderr.toString().trim()}`, 1)
197
201
 
198
202
  const file = parseDotenv(shown.stdout.toString())
203
+
204
+ assertDotenvText(target ?? '', file, redact)
199
205
  const known = await loadKnown(process.cwd(), [file])
200
206
  const rows = [...entries(file)].map(([key, value]) => row(target ?? '', key, value, known))
201
207
 
@@ -4,10 +4,10 @@ import { parse, readInput } from '@kaynooo/cli-kit'
4
4
  import { loadKnown } from '../files'
5
5
  import { check, Redactor } from '../redactor'
6
6
 
7
- const usage = `redact [--check]
7
+ const usage = `ev redact [--check]
8
8
 
9
- Copies stdin to stdout line by line with secrets masked: known token formats (GitHub, GitLab, Slack, AWS, npm, Stripe, Google and SendGrid keys, sk-, JWTs, Authorization headers, password= and secret= pairs), private key blocks, the password and the tokens of any URL and the values of secret-looking keys in this folder's .env* files.
10
- --check prints nothing of the input and lists the file and line of each secret found, exiting 1 when there is any: \`git diff --cached | redact --check\`.`
9
+ Copies stdin to stdout line by line with secrets masked: known token formats, private key blocks, the password and tokens of any URL and the values of secret-looking keys in this folder's .env* files.
10
+ --check prints nothing of the input and lists the file and line of each secret found, exiting 1 when there is any: \`git diff --cached | ev redact --check\`.`
11
11
 
12
12
  const EXITS: ExitRow[] = [[0, 'it copied the input or found no secret'], [1, '--check finds one'], [2, 'a usage error']]
13
13
 
@@ -17,7 +17,7 @@ const options = {
17
17
  } as const
18
18
 
19
19
  export async function redact(args: string[]): Promise<number> {
20
- const parsed = parse(args, usage, options, { exits: EXITS, replaces: 'printing a command\'s secrets into a log or a transcript', examples: [['docker compose config | redact', 'the resolved compose file, secrets masked'], ['git diff --cached | redact --check', 'refuse a commit carrying a secret']] })
20
+ const parsed = parse(args, usage, options, { exits: EXITS, replaces: 'printing a command\'s secrets into a log or a transcript', examples: [['docker compose config | ev redact', 'the resolved compose file, secrets masked'], ['git diff --cached | ev redact --check', 'refuse a commit carrying a secret']] })
21
21
 
22
22
  const known = parsed.values['no-env'] === true ? undefined : await loadKnown()
23
23
 
package/src/files.ts CHANGED
@@ -2,7 +2,7 @@ import type { Dirent } from 'node:fs'
2
2
  import type { Dotenv } from './dotenv'
3
3
  import type { KnownSecrets } from './mask'
4
4
  import { chmod, chown, readdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises'
5
- import { basename, dirname, join } from 'node:path'
5
+ import { basename, dirname, extname, join } from 'node:path'
6
6
  import { fail, ignoredFolders, isSecretName } from '@kaynooo/cli-kit'
7
7
  import { entries, parseDotenv, serializeDotenv } from './dotenv'
8
8
  import { knownSecrets, urlPasswords } from './mask'
@@ -49,13 +49,45 @@ export async function envFiles(folder = process.cwd()): Promise<string[]> {
49
49
  return names.sort()
50
50
  }
51
51
 
52
- export async function readEnv(path: string): Promise<Dotenv> {
52
+ // Formats ev does not read, told apart by their extension.
53
+ const OTHER_FORMATS: Record<string, string> = { '.json': 'JSON', '.jsonc': 'JSON', '.json5': 'JSON', '.yaml': 'YAML', '.yml': 'YAML', '.toml': 'TOML', '.ini': 'INI', '.xml': 'XML' }
54
+ const BLANK_OR_COMMENT = /^\s*(?:#.*)?$/
55
+
56
+ // `redact` is the command masking that file's text, `ev redact < <path>` for a file on disk.
57
+ function notDotenv(why: string, redact: string): never {
58
+ fail(`${why}, and ev reads dotenv files (KEY=value lines)`, 2, `\`${redact}\` masks the secrets of any text`)
59
+ }
60
+
61
+ // A file named as another format is refused before ev reads or writes it.
62
+ export function assertDotenvName(path: string, redact = `ev redact < ${path}`): void {
63
+ const format = OTHER_FORMATS[extname(path).toLowerCase()]
64
+
65
+ if (format !== undefined)
66
+ notDotenv(`${path} is ${format}`, redact)
67
+ }
68
+
69
+ // A file named on the command line is refused when it holds lines but no assignment, rather than read as empty.
70
+ export function assertDotenvText(path: string, dotenv: Dotenv, redact = `ev redact < ${path}`): void {
71
+ if (dotenv.lines.every(line => line.key === undefined) && !dotenv.lines.every(line => BLANK_OR_COMMENT.test(line.raw)))
72
+ notDotenv(`${path} holds no KEY=value line, so it is not a dotenv file`, redact)
73
+ }
74
+
75
+ // The folder's own .env* files are read as they are (`scanned`), a direnv .envrc holding only `use flake` included.
76
+ export async function readEnv(path: string, { scanned = false } = {}): Promise<Dotenv> {
53
77
  const file = Bun.file(path)
54
78
 
79
+ if (!scanned)
80
+ assertDotenvName(path)
81
+
55
82
  if (!await file.exists())
56
83
  fail(`${path} does not exist`)
57
84
 
58
- return parseDotenv(await file.text())
85
+ const dotenv = parseDotenv(await file.text())
86
+
87
+ if (!scanned)
88
+ assertDotenvText(path, dotenv)
89
+
90
+ return dotenv
59
91
  }
60
92
 
61
93
  // Writes through a temp file in the same folder renamed over the target, so a crash or a full disk never leaves a half-written file. The target keeps its mode, owner and group and a new file is 0600.
@@ -16,7 +16,7 @@ const CODE_OPTIONS = new Set(['-e', '-c', '-p', '-E', '-pe', '-r', '--eval', '--
16
16
  const CAN_REACH_FILES = /read|write|open|exec|spawn|system|popen|import|require|eval|load|fetch|glob|stream|source|getline|constructor|file(?!s\b)|\bcat\b|\b(?:Bun|Deno|fs|os|io|sh|bash|process|globalThis|window|Function|qx)\b|\$\s*[`({]|`/i
17
17
  const DECLARERS = new Set(['export', 'declare', 'local', 'readonly', 'typeset'])
18
18
  // Programs that name an env file without reading it: listing, testing, or loading it into a process that prints nothing.
19
- const HARMLESS = new Set(['ev', 'redact', 'ls', 'stat', 'test', '[', '[[', 'touch'])
19
+ const HARMLESS = new Set(['ev', 'ls', 'stat', 'test', '[', '[[', 'touch'])
20
20
  const GIT_HARMLESS = new Set(['check-ignore', 'ls-files', 'status'])
21
21
 
22
22
  // The values each variable is given in a command, by assignment, `export` or a `for` list.
@@ -4,7 +4,7 @@ import { namesEnv } from './guard-names'
4
4
  import { searchesEnvNames } from './guard-search'
5
5
 
6
6
  // Programs an `xargs` can run on a listing of names without printing a line of the files.
7
- const XARGS_SAFE = new Set(['ls', 'stat', 'wc', 'test', '[', 'touch', 'echo', 'printf', 'basename', 'dirname', 'ev', 'redact', ''])
7
+ const XARGS_SAFE = new Set(['ls', 'stat', 'wc', 'test', '[', 'touch', 'echo', 'printf', 'basename', 'dirname', 'ev', ''])
8
8
  // GNU parallel's options taking their value as the next word, before the command it runs.
9
9
  const PARALLEL_VALUE_OPTIONS = new Set(['-j', '--jobs', '-P', '--max-procs', '-S', '--sshlogin', '-C', '--colsep', '-n', '--max-args', '-N', '-d', '--delimiter', '-E', '-I', '--timeout', '--delay', '--joblog', '--results', '--tmpdir', '-a', '--arg-file', '--halt', '--retries', '--tag-string'])
10
10
  const IDENTIFIER = /^[A-Z_]\w*$/i
package/src/guard.ts CHANGED
@@ -8,7 +8,7 @@ import { searchesEnv } from './guard-search'
8
8
  // Code printing the whole environment Bun filled from the .env files.
9
9
  const ENV_DUMP = /(?:console\.\w+|JSON\.stringify|Object\.(?:entries|keys|values)|print)\(\s*process\.env\s*[,)]/
10
10
 
11
- export const USE_EV = '.env files hold secrets that must never reach the transcript, so they are not read, edited or printed directly. Use `ev` instead: `ev list`, `ev get KEY` (masked), `ev grep <regex>` for the keys matching it, `ev show <rev>:<file>` for one at a git revision, `printf %s "$value" | ev set KEY [file]` (`--empty` for an empty value), `ev unset KEY`, `ev cp KEY --from .env --to .env.local`, `ev mv KEY --from .env --to .env.local`, `ev diff a b`, `ev missing`; and pipe output that may carry a secret through `redact`, as `docker compose exec <svc> printenv | redact` or `docker compose config | redact`. If `ev` is missing: `bun install -g @kaynooo/cli-env`.'
11
+ export const USE_EV = '.env files hold secrets that must never reach the transcript, so they are not read, edited or printed directly. Use `ev` instead: `ev list`, `ev get KEY` (masked), `ev grep <regex>` for the keys matching it, `ev show <rev>:<file>` for one at a git revision, `printf %s "$value" | ev set KEY [file]` (`--empty` for an empty value), `ev unset KEY`, `ev cp KEY --from .env --to .env.local`, `ev mv KEY --from .env --to .env.local`, `ev diff a b`, `ev missing`; and pipe output that may carry a secret through `ev redact`, as `docker compose exec <svc> printenv | ev redact` or `docker compose config | ev redact`. If `ev` is missing: `bun install -g @kaynooo/cli-env`.'
12
12
 
13
13
  export const USE_EV_SEARCH = 'To search them, `ev grep <regex>` prints the matching keys, masked. `grep -l`, `-L` and `-c` (file names and counts) are allowed, and a tree-wide search can run as `rg <regex>`, which skips gitignored files, or `grep -r --exclude=\'.env*\' <regex> .`.'
14
14
 
@@ -32,9 +32,11 @@ export function touchingPieces(command: string, options: { hasTrackedEnv?: boole
32
32
  if (!isDump)
33
33
  return false
34
34
 
35
- // a redact further down its pipeline masks what the command prints
35
+ // an `ev redact` further down its pipeline masks what the command prints
36
36
  for (let at = index; pieces[at]?.separator === '|'; at++) {
37
- if (parseCommand(pieces[at + 1]?.command ?? '').program === 'redact')
37
+ const next = parseCommand(pieces[at + 1]?.command ?? '')
38
+
39
+ if (next.program === 'ev' && next.args[0] === 'redact')
38
40
  return false
39
41
  }
40
42
 
@@ -42,7 +44,7 @@ export function touchingPieces(command: string, options: { hasTrackedEnv?: boole
42
44
  })
43
45
  }
44
46
 
45
- // True when the command would read, write or print an env file or the whole environment; an env file named only inside a quoted message or a heredoc body is text, and a container's environment piped through `redact` is masked.
47
+ // True when the command would read, write or print an env file or the whole environment; an env file named only inside a quoted message or a heredoc body is text, and a container's environment piped through `ev redact` is masked.
46
48
  export function touchesEnv(command: string, options: { hasTrackedEnv?: boolean } = {}): boolean {
47
49
  return touchingPieces(command, options).length > 0
48
50
  }