@kaynooo/cli-env 0.14.0 → 0.15.2

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/src/dotenv.ts CHANGED
@@ -15,12 +15,20 @@ const ASSIGNMENT = /^\s*(?:export\s+)?([A-Z_][\w.-]*)\s*=(.*)$/i
15
15
  const EXPORTED = /^\s*export\s/
16
16
  const INLINE_COMMENT = /\s+#.*$/
17
17
  const CARRIAGE_RETURN = /\r$/
18
+ const CARRIAGE_RETURNS = /\r$/gm
19
+ const COMMENT_AFTER_QUOTE = /\s*#.*$/
18
20
  const ESCAPES: Record<string, string> = { 'n': '\n', 'r': '\r', 't': '\t', '"': '"', '\\': '\\', '$': '$' }
19
21
 
20
22
  export const LINE_BREAK = /[\r\n]/
21
- // Bun does not unescape these inside double quotes, so a value holding one is written in single quotes.
22
- const RAW_ONLY = /["\\]/
23
- const NEEDS_QUOTES = /[\s#"'\\$`]/
23
+ // What neither Bun's --env-file nor compose's env_file reads specially.
24
+ const PLAIN = /^[^\s#"'\\$`]+$/
25
+ // What single quotes cannot hold for both: Bun expands `$` in them, compose reads `\'` as a quote, and a carriage return would be written raw.
26
+ const NOT_SINGLE = /['$\r]|\\$/
27
+ // Both read \n, \r and \$ in double quotes, but each reads \", \\ and the other escapes its own way.
28
+ const NOT_DOUBLE = /["\\]/
29
+ // A bare value: Bun ends it at any `#`, both expand `$`, trim it and take a leading quote for an opening one.
30
+ const NOT_BARE = /[#$\r\n]|^[\s"'`]|\s$/
31
+ const UNQUOTABLE = [['$', '$'], ['"', '"'], ['\'', '\''], ['\\', '\\'], ['#', '#'], ['\n', 'a line break'], ['\r', 'a carriage return']] as const
24
32
 
25
33
  // Finds the closing quote, skipping backslash escapes inside double quotes. Returns -1 when the value continues on the next line.
26
34
  function closingQuote(text: string, quote: string): number {
@@ -87,21 +95,23 @@ export function parseDotenv(text: string): Dotenv {
87
95
 
88
96
  const first = index
89
97
 
90
- while (end === -1 && index + 1 < physical.length && !ASSIGNMENT.test(physical[index + 1] ?? '')) {
98
+ // A quoted value runs to its closing quote whatever the lines between look like, as Bun and compose read it: a PEM body line can look like an assignment.
99
+ while (end === -1 && index + 1 < physical.length) {
91
100
  index++
92
101
  body += `\n${(physical[index] ?? '').replace(CARRIAGE_RETURN, '')}`
93
102
  raw += `\n${physical[index] ?? ''}`
94
103
  end = closingQuote(body, quote)
95
104
  }
96
105
 
97
- if (end === -1 && index + 1 < physical.length) {
106
+ // With no closing quote anywhere, Bun keeps the line as it is and reads the next ones on their own.
107
+ if (end === -1) {
98
108
  index = first
99
109
  lines.push({ raw: line, key, value: unescapeDollar(start.replace(INLINE_COMMENT, '').trim()), unterminated: true })
100
110
 
101
111
  continue
102
112
  }
103
113
 
104
- const inner = end === -1 ? body : body.slice(0, end)
114
+ const inner = body.slice(0, end)
105
115
 
106
116
  lines.push({ raw, key, value: quote === '"' ? unescapeDouble(inner) : unescapeDollar(inner) })
107
117
  }
@@ -125,44 +135,84 @@ export function entries(file: Dotenv): Map<string, string> {
125
135
  return map
126
136
  }
127
137
 
128
- // A value written between double quotes, each `$` escaped because Bun expands it in every quoting.
129
- export function escapeDouble(value: string): string {
130
- return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\r', '\\r').replaceAll('\n', '\\n').replaceAll('$', '\\$')
138
+ // The assignment Bun's --env-file and compose's env_file both read back as the value: bare when nothing in it is special, else double-quoted, single-quoted or bare, the first form that holds it for both; undefined when none does.
139
+ export function formatAssignment(key: string, value: string): string | undefined {
140
+ if (value === '' || PLAIN.test(value))
141
+ return `${key}=${value}`
142
+
143
+ if (!NOT_DOUBLE.test(value))
144
+ return `${key}="${value.replaceAll('\r', '\\r').replaceAll('\n', '\\n').replaceAll('$', '\\$')}"`
145
+
146
+ if (!NOT_SINGLE.test(value))
147
+ return `${key}='${value}'`
148
+
149
+ return NOT_BARE.test(value) ? undefined : `${key}=${value}`
131
150
  }
132
151
 
133
- export function formatAssignment(key: string, value: string): string {
134
- if (value === '' || !NEEDS_QUOTES.test(value))
135
- return `${key}=${value}`
152
+ // Why formatAssignment finds no form for the value: the characters in it that clash.
153
+ export function unquotable(value: string): string {
154
+ const held = UNQUOTABLE.filter(([char]) => value.includes(char)).map(([, name]) => name)
155
+ const spaced = value.trim() === value ? [] : ['whitespace at an end']
156
+
157
+ return `its value holds ${[...held, ...spaced].join(', ')}, which no quoting lets both Bun's --env-file and compose's env_file read as it is`
158
+ }
159
+
160
+ // The inline comment after an assignment's value, on its last line.
161
+ function inlineComment(raw: string): string {
162
+ const lines = raw.replaceAll(CARRIAGE_RETURNS, '').split('\n')
163
+ const value = ASSIGNMENT.exec(lines[0] ?? '')?.[2] ?? ''
164
+ const start = value.trimStart()
165
+ const quote = start[0]
136
166
 
137
- // Bun expands a bare `$` in every quoting, so each one is written as `\$`.
138
- if (RAW_ONLY.test(value) && !value.includes('\'') && !LINE_BREAK.test(value))
139
- return `${key}='${value.replaceAll('$', '\\$')}'`
167
+ // An empty value leaves only the comment, whose leading space the trim would take.
168
+ if (quote !== '"' && quote !== '\'' && quote !== '`')
169
+ return INLINE_COMMENT.exec(value)?.[0] ?? ''
140
170
 
141
- return `${key}="${escapeDouble(value)}"`
171
+ const last = lines.length === 1 ? start.slice(1) : lines.at(-1) ?? ''
172
+ const end = closingQuote(last, quote)
173
+
174
+ return end === -1 ? '' : COMMENT_AFTER_QUOTE.exec(last.slice(end + 1))?.[0] ?? ''
175
+ }
176
+
177
+ // The callers refuse an unquotable value first, so reaching this with one is a bug.
178
+ function assignment(key: string, value: string): string {
179
+ const line = formatAssignment(key, value)
180
+
181
+ if (line === undefined)
182
+ throw new Error(unquotable(value))
183
+
184
+ return line
142
185
  }
143
186
 
144
- // Replaces the last assignment of a key keeping its `export`, or appends before the trailing newline. `raw` is the whole line to store when given.
187
+ // Replaces the last assignment of a key keeping its `export`, inline comment and line ending, or appends before the trailing newline in the file's line ending. `raw` is the whole line to store when given.
145
188
  export function setLine(file: Dotenv, key: string, value: string, raw?: string): void {
146
189
  const index = file.lines.findLastIndex(line => line.key === key)
147
190
  const existing = file.lines[index]
148
191
 
149
192
  if (existing !== undefined) {
150
193
  const exported = EXPORTED.test(existing.raw) ? 'export ' : ''
194
+ const ending = existing.raw.endsWith('\r') ? '\r' : ''
195
+ const line = raw?.replace(CARRIAGE_RETURN, '') ?? `${exported}${assignment(key, value)}${inlineComment(existing.raw)}`
151
196
 
152
- file.lines[index] = { raw: raw ?? `${exported}${formatAssignment(key, value)}`, key, value }
197
+ file.lines[index] = { raw: `${line}${ending}`, key, value }
153
198
 
154
199
  return
155
200
  }
156
201
 
157
- const line = { raw: raw ?? formatAssignment(key, value), key, value }
202
+ const ending = file.lines.some(line => line.raw.endsWith('\r')) ? '\r' : ''
203
+ const line = { raw: `${raw?.replace(CARRIAGE_RETURN, '') ?? assignment(key, value)}${ending}`, key, value }
158
204
  const last = file.lines.at(-1)
159
205
 
160
- if (last === undefined)
206
+ if (last === undefined) {
161
207
  file.lines.push(line, { raw: '' })
162
- else if (last.raw === '')
208
+ }
209
+ else if (last.raw === '') {
163
210
  file.lines.splice(-1, 0, line)
164
- else
211
+ }
212
+ else {
213
+ last.raw = `${last.raw.replace(CARRIAGE_RETURN, '')}${ending}`
165
214
  file.lines.push(line, { raw: '' })
215
+ }
166
216
  }
167
217
 
168
218
  // Drops every assignment of the key and returns how many went.
package/src/files.ts CHANGED
@@ -2,10 +2,11 @@ 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, resolve } 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'
9
+ import { parseStructured, structuredFormat } from './structured'
9
10
 
10
11
  // A dotenv file's name (`.env`, `.env.local`, `prod.env`, `.envrc`), and the templates among them that hold no values.
11
12
  export const ENV_FILE = /^(?:\.env(?:\..+)?|.+\.env|\.envrc)$/
@@ -49,13 +50,68 @@ export async function envFiles(folder = process.cwd()): Promise<string[]> {
49
50
  return names.sort()
50
51
  }
51
52
 
52
- export async function readEnv(path: string): Promise<Dotenv> {
53
+ // Formats ev does not read, told apart by their extension.
54
+ const OTHER_FORMATS: Record<string, string> = { '.ini': 'INI', '.xml': 'XML' }
55
+ const BLANK_OR_COMMENT = /^\s*(?:#.*)?$/
56
+
57
+ // `redact` is the command masking that file's text, `ev redact < <path>` for a file on disk.
58
+ function notDotenv(why: string, redact: string): never {
59
+ fail(`${why}, and ev reads dotenv (KEY=value lines), JSON, YAML and TOML files`, 2, `\`${redact}\` masks the secrets of any text`)
60
+ }
61
+
62
+ // A file named as a format ev cannot read is refused before ev reads it.
63
+ export function assertReadableName(path: string, redact = `ev redact < ${path}`): void {
64
+ const format = OTHER_FORMATS[extname(path).toLowerCase()]
65
+
66
+ if (format !== undefined)
67
+ notDotenv(`${path} is ${format}`, redact)
68
+ }
69
+
70
+ // Past set and unset, ev writes dotenv files only, so any other format is refused before ev reads a file to write it.
71
+ export function assertDotenvName(path: string, redact = `ev redact < ${path}`): void {
72
+ assertReadableName(path, redact)
73
+
74
+ const format = structuredFormat(path)
75
+
76
+ if (format !== undefined)
77
+ fail(`${path} is ${format}, which ev set and unset edit while the other commands that write take dotenv files (KEY=value lines)`)
78
+ }
79
+
80
+ // A file named on the command line is refused when it holds lines but no assignment, rather than read as empty.
81
+ export function assertDotenvText(path: string, dotenv: Dotenv, redact = `ev redact < ${path}`): void {
82
+ if (dotenv.lines.every(line => line.key === undefined) && !dotenv.lines.every(line => BLANK_OR_COMMENT.test(line.raw)))
83
+ notDotenv(`${path} holds no KEY=value line, so it is not a dotenv file`, redact)
84
+ }
85
+
86
+ // The folder's own .env* files are read as they are (`scanned`), a direnv .envrc holding only `use flake` included.
87
+ export async function readEnv(path: string, { scanned = false } = {}): Promise<Dotenv> {
88
+ const file = Bun.file(path)
89
+
90
+ if (!scanned)
91
+ assertDotenvName(path)
92
+
93
+ if (!await file.exists())
94
+ fail(`${path} does not exist`)
95
+
96
+ const dotenv = parseDotenv(await file.text())
97
+
98
+ if (!scanned)
99
+ assertDotenvText(path, dotenv)
100
+
101
+ return dotenv
102
+ }
103
+
104
+ // The keys of a file named on the command line, or of one of the folder's own .env* files (`scanned`): a JSON, YAML or TOML one by dotted paths.
105
+ export async function readEntries(path: string, { scanned = false } = {}): Promise<Map<string, string>> {
106
+ if (scanned || structuredFormat(path) === undefined)
107
+ return entries(await readEnv(path, { scanned }))
108
+
53
109
  const file = Bun.file(path)
54
110
 
55
111
  if (!await file.exists())
56
112
  fail(`${path} does not exist`)
57
113
 
58
- return parseDotenv(await file.text())
114
+ return parseStructured(path, await file.text())
59
115
  }
60
116
 
61
117
  // 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.
@@ -113,8 +169,11 @@ export async function withLocks<T>(paths: string[], fn: () => Promise<T>): Promi
113
169
  const held: string[] = []
114
170
 
115
171
  try {
116
- for (const path of [...new Set(paths)].sort())
117
- held.push(await acquire(path))
172
+ // One file spelled two ways, or through a symlink, takes its lock once.
173
+ const locks = new Map(await Promise.all(paths.map(async path => [await lockFor(path), path] as const)))
174
+
175
+ for (const [lock, path] of [...locks].sort(([a], [b]) => a < b ? -1 : 1))
176
+ held.push(await acquire(lock, path))
118
177
 
119
178
  return await fn()
120
179
  }
@@ -155,8 +214,9 @@ async function reap(lock: string): Promise<void> {
155
214
  }
156
215
  }
157
216
 
158
- async function acquire(path: string): Promise<string> {
159
- let real = path
217
+ // The lock file of a path, beside the file it resolves to.
218
+ async function lockFor(path: string): Promise<string> {
219
+ let real = resolve(path)
160
220
 
161
221
  try {
162
222
  real = await realpath(path)
@@ -165,7 +225,10 @@ async function acquire(path: string): Promise<string> {
165
225
  // a missing file is locked by its own name
166
226
  }
167
227
 
168
- const lock = join(dirname(real), `.${basename(real)}.lock`)
228
+ return join(dirname(real), `.${basename(real)}.lock`)
229
+ }
230
+
231
+ async function acquire(lock: string, path: string): Promise<string> {
169
232
  const deadline = Date.now() + LOCK_WAIT_MS
170
233
 
171
234
  while (true) {
@@ -188,11 +251,11 @@ async function acquire(path: string): Promise<string> {
188
251
  }
189
252
  }
190
253
 
191
- // The secrets of a parsed file: values of secret-looking keys and the password of any URL value.
192
- export function secretPairs(file: Dotenv): [string, string][] {
254
+ // The secrets of a file's keys: values of secret-looking keys and the password of any URL value.
255
+ export function secretPairs(keys: Map<string, string>): [string, string][] {
193
256
  const pairs: [string, string][] = []
194
257
 
195
- for (const [key, value] of entries(file)) {
258
+ for (const [key, value] of keys) {
196
259
  if (isSecretName(key))
197
260
  pairs.push([key, value])
198
261
  else
@@ -226,13 +289,13 @@ async function envFilesBelow(folder: string, depth = 0): Promise<string[]> {
226
289
  return found
227
290
  }
228
291
 
229
- // The secrets of the folder's .env* files and of those in the folders below it, plus any `extra` parsed file, ready to be searched for in output.
230
- export async function loadKnown(folder = process.cwd(), extra: Dotenv[] = []): Promise<KnownSecrets> {
292
+ // The secrets of the folder's .env* files and of those in the folders below it, plus the keys of any `extra` file, ready to be searched for in output.
293
+ export async function loadKnown(folder = process.cwd(), extra: Map<string, string>[] = []): Promise<KnownSecrets> {
231
294
  const pairs = extra.flatMap(secretPairs)
232
295
 
233
296
  for (const path of await envFilesBelow(folder)) {
234
297
  try {
235
- pairs.push(...secretPairs(parseDotenv(await Bun.file(path).text())))
298
+ pairs.push(...secretPairs(entries(parseDotenv(await Bun.file(path).text()))))
236
299
  }
237
300
  catch {
238
301
  // a file that cannot be read has no secret to learn
package/src/fix.ts CHANGED
@@ -2,7 +2,7 @@ import { chmod, chown, lstat, rm, stat } from 'node:fs/promises'
2
2
  import { dirname, join } from 'node:path'
3
3
  import { compose } from '@kaynooo/cli-kit'
4
4
  import { isInlineSecret } from './audit'
5
- import { entries, escapeDouble, LINE_BREAK, parseDotenv, serializeDotenv, setLine } from './dotenv'
5
+ import { entries, formatAssignment, parseDotenv, serializeDotenv, setLine, unquotable } from './dotenv'
6
6
  import { writeAtomic } from './files'
7
7
 
8
8
  export interface Left {
@@ -29,7 +29,6 @@ const LIST_ENTRY = /^(\s*-[ \t]*)(["']?)([A-Z0-9_]+)=(.*)$/
29
29
  const TRAILING = /^\s*(?:#.*)?$/
30
30
  const PLAIN_COMMENT = /\s+#.*$/
31
31
  const NOT_PLAIN = /^[|>&*![{]/
32
- const ENV_PLAIN = /^[^\s#"'\\$`]*$/
33
32
 
34
33
  // The inside of a YAML quoted scalar starting after its opening quote: double quotes take only \\ and \" escapes here.
35
34
  function quoted(text: string, quote: string): { value: string, after: string } | undefined {
@@ -100,20 +99,6 @@ export function composeEntry(line: string): Entry | undefined {
100
99
  return { key, value: scalar.value, swap: ref => `${dash}${quote}${key}=${ref}${quote}${scalar.after}` }
101
100
  }
102
101
 
103
- // The .env line holding a value compose and Bun both read literally: plain when nothing needs quoting, single-quoted otherwise, double-quoted with each `$` escaped when it holds one since Bun expands it even in single quotes.
104
- export function envLine(key: string, value: string): string | undefined {
105
- if (ENV_PLAIN.test(value))
106
- return `${key}=${value}`
107
-
108
- if (LINE_BREAK.test(value))
109
- return undefined
110
-
111
- if (value.includes('$'))
112
- return `${key}="${escapeDouble(value)}"`
113
-
114
- return value.includes('\'') ? undefined : `${key}='${value}'`
115
- }
116
-
117
102
  // A link, dangling or not: writing through it would change a file elsewhere.
118
103
  async function isLink(path: string): Promise<boolean> {
119
104
  try {
@@ -201,10 +186,10 @@ export async function fixCompose(path: string, group = false): Promise<ComposeFi
201
186
  const existing = known.get(key)
202
187
 
203
188
  if (existing === undefined) {
204
- const raw = envLine(key, value)
189
+ const raw = formatAssignment(key, value)
205
190
 
206
191
  if (raw === undefined) {
207
- fix.left.push({ key, why: 'its value holds a quote or line break a .env cannot keep literal' })
192
+ fix.left.push({ key, why: unquotable(value) })
208
193
 
209
194
  return line
210
195
  }
@@ -1,3 +1,4 @@
1
+ import { basename } from 'node:path'
1
2
  import { splitCommand, tokenize } from '@kaynooo/cli-kit/shell'
2
3
 
3
4
  const OPENER = /^[({]+/
@@ -5,7 +6,7 @@ const DUMP_FLAGS = /^-[a-z]*[px]/
5
6
  // Git commands whose output carries the content of tracked files.
6
7
  const GIT_PATCHES = new Set(['diff', 'log', 'show', 'whatchanged', 'format-patch', 'grep'])
7
8
  const GIT_NO_PATCH = new Set(['--stat', '--numstat', '--shortstat', '--name-only', '--name-status', '--summary', '-s', '--no-patch', '--check', '--quiet'])
8
- const GIT_VALUE_OPTIONS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path'])
9
+ const GIT_VALUE_OPTIONS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env', '--attr-source'])
9
10
  const GIT_PATCH_FLAGS = new Set(['-p', '-u', '--patch', '-c', '--cc', '--patch-with-stat', '--patch-with-raw'])
10
11
 
11
12
  export const GIT_EXCLUDE = /^:(?:!|\^|\(exclude\))/
@@ -18,6 +19,8 @@ const SHELL_COMMAND_FLAG = /^-[abd-z]*c[a-z]*$/
18
19
  // Options taking a value, before a docker or compose subcommand, and before exec's container.
19
20
  const DOCKER_VALUE_OPTIONS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-file', '--project-directory', '--ansi', '--progress', '--parallel', '-H', '--host', '-c', '--context', '--config', '-l', '--log-level'])
20
21
  const EXEC_VALUE_OPTIONS = new Set(['-e', '--env', '--env-file', '-u', '--user', '-w', '--workdir', '--index', '--detach-keys'])
22
+ // Options taking a value before the image of `docker run` or the service of `compose run`.
23
+ const RUN_VALUE_OPTIONS = new Set([...EXEC_VALUE_OPTIONS, '-a', '--attach', '--add-host', '--annotation', '--blkio-weight', '--cap-add', '--cap-drop', '--cgroup-parent', '--cgroupns', '--cidfile', '-c', '--cpu-shares', '--cpus', '--cpuset-cpus', '--cpuset-mems', '--cpu-period', '--cpu-quota', '--device', '--dns', '--dns-option', '--dns-search', '--domainname', '--entrypoint', '--env-from-file', '--expose', '--gpus', '--group-add', '--health-cmd', '--health-interval', '--health-retries', '--health-start-period', '--health-timeout', '-h', '--hostname', '--ip', '--ip6', '--ipc', '--isolation', '-l', '--label', '--label-file', '--link', '--log-driver', '--log-opt', '--mac-address', '-m', '--memory', '--memory-reservation', '--memory-swap', '--mount', '--name', '--network', '--net', '--network-alias', '--pid', '--pids-limit', '--platform', '-p', '--publish', '--pull', '--restart', '--runtime', '--security-opt', '--shm-size', '--stop-signal', '--stop-timeout', '--storage-opt', '--sysctl', '--tmpfs', '--ulimit', '--userns', '--uts', '-v', '--volume', '--volumes-from'])
21
24
  // `compose config` options printing names, never values.
22
25
  const CONFIG_LISTS = new Set(['--services', '--volumes', '--profiles', '--images', '--networks', '--hash', '-q', '--quiet'])
23
26
  const FORMAT_OPTIONS = new Set(['-f', '--format'])
@@ -38,17 +41,30 @@ function firstOperand(words: readonly string[], valueOptions: ReadonlySet<string
38
41
  return words.length
39
42
  }
40
43
 
44
+ // Whether a program, by path or by name, prints the whole environment.
45
+ function isEnvPrinter(program: string): boolean {
46
+ return ENV_PRINTERS.has(basename(program))
47
+ }
48
+
41
49
  // The command a container runs prints its environment: `env` or `printenv` as the program, or as one run by `sh -c`.
42
50
  function printsEnv([program = '', ...args]: readonly string[]): boolean {
43
51
  const flags = args.findIndex(arg => !arg.startsWith('-') || SHELL_COMMAND_FLAG.test(arg))
44
52
 
45
- if (SHELLS.has(program) && SHELL_COMMAND_FLAG.test(args[flags] ?? ''))
46
- return splitCommand(args[flags + 1] ?? '').some(piece => ENV_PRINTERS.has(tokenize(piece.command)[0] ?? ''))
53
+ if (SHELLS.has(basename(program)) && SHELL_COMMAND_FLAG.test(args[flags] ?? ''))
54
+ return splitCommand(args[flags + 1] ?? '').some(piece => isEnvPrinter(tokenize(piece.command)[0] ?? ''))
55
+
56
+ return isEnvPrinter(program)
57
+ }
58
+
59
+ // `docker run` and `compose run` print the environment when what runs is a dump: the entrypoint given, followed by the words after the image or service, or those words alone.
60
+ function runPrintsEnv(after: readonly string[]): boolean {
61
+ const entrypoint = after.find((_, i) => after[i - 1] === '--entrypoint') ?? after.find(word => word.startsWith('--entrypoint='))?.slice('--entrypoint='.length)
62
+ const command = after.slice(firstOperand(after, RUN_VALUE_OPTIONS) + 1)
47
63
 
48
- return ENV_PRINTERS.has(program)
64
+ return printsEnv(entrypoint === undefined || entrypoint === '' ? command : [entrypoint, ...command])
49
65
  }
50
66
 
51
- // A docker call printing a container's environment: `env` or `printenv` run through exec, `compose config` and `inspect`, which spell it out.
67
+ // A docker call printing a container's environment: `env` or `printenv` run through exec or run, `compose config` and `inspect`, which spell it out.
52
68
  export function dumpsContainerEnv(program: string, args: string[]): boolean {
53
69
  if (!DOCKER.has(program))
54
70
  return false
@@ -60,11 +76,15 @@ export function dumpsContainerEnv(program: string, args: string[]): boolean {
60
76
  if (program === 'docker' && isCompose)
61
77
  rest = afterOptions(rest.slice(1))
62
78
 
63
- const [subcommand = '', ...after] = rest
79
+ // `docker container exec` and `docker container run` are exec and run.
80
+ const [subcommand = '', ...after] = !isCompose && rest[0] === 'container' && ['exec', 'run'].includes(rest[1] ?? '') ? rest.slice(1) : rest
64
81
 
65
82
  if (subcommand === 'exec')
66
83
  return printsEnv(after.slice(firstOperand(after, EXEC_VALUE_OPTIONS) + 1))
67
84
 
85
+ if (subcommand === 'run')
86
+ return runPrintsEnv(after)
87
+
68
88
  if (isCompose)
69
89
  return subcommand === 'config' && !after.some(word => CONFIG_LISTS.has(word))
70
90
 
@@ -89,7 +109,7 @@ export function dumpsEnvironment(program: string, args: readonly string[], token
89
109
  if (program === 'set')
90
110
  return args.length === 0
91
111
 
92
- return program === '' && tokens.some(token => token.replace(OPENER, '') === 'env')
112
+ return program === '' && tokens.some(token => basename(token.replace(OPENER, '')) === 'env')
93
113
  }
94
114
 
95
115
  // Whether a git command prints the content of a tracked env file: a patch or a search with no pathspec leaving env files out.
@@ -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
  }
package/src/mask.ts CHANGED
@@ -28,8 +28,8 @@ const ESCAPE = /[.*+?^${}()|[\]\\]/g
28
28
  interface TokenFormat {
29
29
  kind: string
30
30
  pattern: RegExp
31
- // Skips a candidate that is a placeholder or a plain word. `before` is the line text ahead of it.
32
- skip?: (value: string, before: string) => boolean
31
+ // Skips a candidate that is a placeholder or a plain word. `before` is the line text ahead of it, `name` the key a pattern names `name`.
32
+ skip?: (value: string, before: string, name?: string) => boolean
33
33
  }
34
34
 
35
35
  // A secret value starting like this is a reference or a placeholder, not the secret.
@@ -57,7 +57,31 @@ function isWeak(value: string, before: string): boolean {
57
57
 
58
58
  // A key name holding one of the words: `AWS_SECRET_ACCESS_KEY`, `X-Api-Key`, `access_token`.
59
59
  function keyed(names: string, value: string): RegExp {
60
- return new RegExp(`(?<![\\w-])["']?(?:[\\w-]{0,30}[_-])?(?:${names})(?:[_-][\\w-]{0,30})?["']?${KEY_VALUE_GAP}${value}`, 'dgi')
60
+ return new RegExp(`(?<![\\w-])["']?(?<name>(?:[\\w-]{0,30}[_-])?(?:${names})(?:[_-][\\w-]{0,30})?)["']?${KEY_VALUE_GAP}${value}`, 'dgi')
61
+ }
62
+
63
+ // Any key name, which `isSecretName` then judges, so `PGPASSWORD`, `MYSQL_PWD` and `clientSecret` count as `DB_PASSWORD` does.
64
+ const ANY_NAME = '(?<![\\w.-])["\']?(?<name>[a-z_][\\w.-]{0,60})["\']?'
65
+ // Names a value under is a secret even when short and without a digit, as under `password`.
66
+ const PASSWORD_NAME = new RegExp(`${STRONG_NAME}|pass|pwd`, 'i')
67
+ // Name endings of a setting about a secret rather than the secret (`TOKEN_TTL`, `PASSWORD_FILE`).
68
+ const SETTING_SUFFIX = /[_.-](?:TTL|FILE|PATH|DIR|NAME|URL|TIMEOUT|EXPIRY|EXPIRES|LIFETIME|LENGTH|ENABLED|ALGORITHM|HEADER|PREFIX|COUNT|MAX|MIN)$/i
69
+
70
+ const NUMBER = /^\d+$/
71
+ // Names of a count rather than of the thing counted: `max_tokens`, `num_sessions`, `tokens`.
72
+ const COUNT_NAME = /(?:^|[_.-])(?:max|min|num)[_.-]|^tokens$/i
73
+
74
+ // A value under a setting's name, or a number under a count's (`max_tokens=4096`), is no secret.
75
+ function isSetting(value: string, name: string): boolean {
76
+ return SETTING_SUFFIX.test(name) || (COUNT_NAME.test(name) && NUMBER.test(value))
77
+ }
78
+
79
+ // The skip of a key the name alone does not settle: a private key is masked by its own markers.
80
+ function isPlainNamed(value: string, before: string, name = ''): boolean {
81
+ if (!isSecretName(name) || isSetting(value, name) || value.length < 4 || value.includes('-----BEGIN '))
82
+ return true
83
+
84
+ return PASSWORD_NAME.test(name) ? isProse(value, before) : isWeak(value, before)
61
85
  }
62
86
 
63
87
  // A pattern with a group masks that group only, else the whole match.
@@ -80,10 +104,14 @@ const TOKEN_FORMATS: TokenFormat[] = [
80
104
  { kind: 'SendGrid key', pattern: /\bSG\.[\w-]{16,}\.[\w-]{16,}/dg },
81
105
  { kind: 'Authorization header', pattern: /\bAuthorization["']?\s*[:=]\s*["']?(?:Bearer|Basic|Token|Digest)\s+([^\s"',;]{8,})/dgi, skip: isPlaceholder },
82
106
  { kind: 'Bearer token', pattern: /\bBearer\s+((?=[\w.~+/=-]*\d)[\w.~+/=-]{20,})/dg },
83
- { kind: 'password', pattern: keyed(STRONG_NAME, '([^\\s"\'&;,]{4,})'), skip: isProse },
84
- { kind: 'password', pattern: keyed(WEAK_NAME, '([^\\s"\'&;,]{4,})'), skip: isWeak },
85
- { kind: 'password', pattern: keyed(STRONG_NAME, '(["\'])((?:\\\\.|(?!\\1)[^\\\\\\n]){4,})\\1'), skip: isPlaceholder },
86
- { kind: 'password', pattern: keyed(WEAK_NAME, '(["\'])((?:\\\\.|(?!\\1)[^\\\\\\n]){4,})\\1'), skip: isWeak },
107
+ { kind: 'password', pattern: keyed(STRONG_NAME, '([^\\s"\'&;,]{4,})'), skip: (value, before, name = '') => isSetting(value, name) || isProse(value, before) },
108
+ { kind: 'password', pattern: keyed(WEAK_NAME, '([^\\s"\'&;,]{4,})'), skip: (value, before, name = '') => isSetting(value, name) || isWeak(value, before) },
109
+ { kind: 'password', pattern: keyed(STRONG_NAME, '(["\'])((?:\\\\.|(?!\\2)[^\\\\\\n]){4,})\\2'), skip: (value, _, name = '') => isSetting(value, name) || isPlaceholder(value) },
110
+ { kind: 'password', pattern: keyed(WEAK_NAME, '(["\'])((?:\\\\.|(?!\\2)[^\\\\\\n]){4,})\\2'), skip: (value, before, name = '') => isSetting(value, name) || isWeak(value, before) },
111
+ { kind: 'password', pattern: new RegExp(`${ANY_NAME}${KEY_VALUE_GAP}([^\\s"'&;,]{4,})`, 'dgi'), skip: isPlainNamed },
112
+ { kind: 'password', pattern: new RegExp(`${ANY_NAME}${KEY_VALUE_GAP}(["'])((?:\\\\.|(?!\\2)[^\\\\\\n]){4,})\\2`, 'dgi'), skip: isPlainNamed },
113
+ // A variable as printenv or env prints it, whose value runs to the end of the line, spaces included.
114
+ { kind: 'password', pattern: /^\s*(?:export\s+)?(?<name>[A-Za-z_]\w{0,60})=(?!["'])(\S(?:.*\S)?)/dg, skip: isPlainNamed },
87
115
  ]
88
116
 
89
117
  // A private key block (PEM, PGP). Its body is masked from just after the BEGIN marker to the END marker or the end of the line, so one line may hold the whole key escaped as JSON.
@@ -238,7 +266,7 @@ export function findSecrets(line: string, known?: KnownSecrets): Match[] {
238
266
 
239
267
  const value = line.slice(start, end)
240
268
 
241
- if (!skip?.(value, line.slice(0, start)))
269
+ if (!skip?.(value, line.slice(0, start), token.groups?.name))
242
270
  found.push({ start, end, kind, mask: hint(value) })
243
271
  }
244
272
  }