@kaynooo/cli-env 0.13.1 → 0.14.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.
@@ -1,4 +1,6 @@
1
- import { badUsage, fail, parse, readInput } from '@kaynooo/cli-kit'
1
+ import type { ExitRow } from '@kaynooo/cli-kit'
2
+ import { badUsage, fail, isInteractive, parse, readInput } from '@kaynooo/cli-kit'
3
+ import { input } from '@kaynooo/cli-kit/prompt'
2
4
  import { entries, lastLine, removeKey, setLine } from '../dotenv'
3
5
  import { loadKnown, readEnv, withLocks, writeEnv } from '../files'
4
6
  import { maskValue } from '../mask'
@@ -11,35 +13,37 @@ const QUIET = { quiet: { type: 'boolean', short: 'q', description: 'print nothin
11
13
 
12
14
  const setUsage = `ev set KEY [file] [--quiet]
13
15
 
14
- Sets KEY in the file (.env by default, created when missing), replacing its line in place or appending one. The value is read from stdin, or from -F <file>, so it never appears in a command line; --empty sets it to an empty value.
16
+ Sets KEY in the file (.env by default, created when missing), replacing its line in place or appending one. The value is read from stdin, or from -F <file>, so it never appears in a command line; on a terminal with nothing piped it is asked for, masked as it is typed. --empty sets it to an empty value.`
15
17
 
16
- Exits 0 when it wrote the key, 1 when it could not, 2 on a usage error.`
18
+ const SET_EXITS: ExitRow[] = [[0, 'it wrote the key'], [1, 'it could not'], [2, 'a usage error'], [130, 'the prompt was cancelled']]
17
19
 
18
20
  const unsetUsage = `ev unset KEY [file] [--quiet]
19
21
 
20
- Removes every line setting KEY from the file (.env by default), leaving comments and other lines as they are.
22
+ Removes every line setting KEY from the file (.env by default), leaving comments and other lines as they are.`
21
23
 
22
- Exits 0 when it removed the key, 1 when the file does not set it, 2 on a usage error.`
24
+ const UNSET_EXITS: ExitRow[] = [[0, 'it removed the key'], [1, 'the file does not set it'], [2, 'a usage error']]
23
25
 
24
26
  const mvUsage = `ev mv KEY --from <file> --to <file> [--quiet]
25
27
 
26
- Moves KEY's line from one file to another, as written. Refuses to replace a key the target already sets unless --force.
28
+ Moves KEY's line from one file to another, as written. Refuses to replace a key the target already sets unless --force.`
27
29
 
28
- Exits 0 when it moved the key, 1 when the source lacks it or the target already sets it, 2 on a usage error.`
30
+ const MV_EXITS: ExitRow[] = [[0, 'it moved the key'], [1, 'the source lacks it or the target already sets it'], [2, 'a usage error']]
29
31
 
30
32
  const cpUsage = `ev cp KEY --from <file> --to <file> [--as NEWKEY] [--quiet]
31
33
 
32
- Copies KEY's value from one file to another without printing it, replacing the key's line in the target in place or appending one, and prints the masked result as ev set does. --as stores the copy under another key.
34
+ Copies KEY's value from one file to another without printing it, replacing the key's line in the target in place or appending one, and prints the masked result as ev set does. --as stores the copy under another key.`
33
35
 
34
- Exits 0 when it copied the key, 1 when the source lacks it, 2 on a usage error.`
36
+ const CP_EXITS: ExitRow[] = [[0, 'it copied the key'], [1, 'the source lacks it'], [2, 'a usage error']]
35
37
 
36
- async function readValue(from: string | undefined): Promise<string> {
37
- const input = await readInput(from ?? '-', { noStdin: 'pipe the value on stdin or give -F <file>, it is never taken from the command line' })
38
+ async function readValue(key: string, from: string | undefined): Promise<string> {
39
+ const value = from === undefined && isInteractive()
40
+ ? await input(`value of ${key}`, { mask: true }) ?? fail('cancelled, nothing was written', 130)
41
+ : await readInput(from ?? '-', { noStdin: 'pipe the value on stdin or give -F <file>, it is never taken from the command line' })
38
42
 
39
- if (input === '')
43
+ if (value === '')
40
44
  fail('the value is empty, nothing was written: --empty sets an empty value')
41
45
 
42
- return input.replace(TRAILING_NEWLINE, '')
46
+ return value.replace(TRAILING_NEWLINE, '')
43
47
  }
44
48
 
45
49
  // A key that is not a plain name could carry a line break or an `=` and write more than one line.
@@ -57,7 +61,7 @@ export async function set(args: string[]): Promise<number> {
57
61
  file: { type: 'string', short: 'F', description: 'read the value from this file instead of stdin' },
58
62
  empty: { type: 'boolean', description: 'set an empty value, reading nothing' },
59
63
  ...QUIET,
60
- })
64
+ }, { exits: SET_EXITS })
61
65
 
62
66
  const [key, target = DEFAULT_FILE] = parsed.positionals
63
67
 
@@ -69,7 +73,7 @@ export async function set(args: string[]): Promise<number> {
69
73
 
70
74
  checkKey(key)
71
75
 
72
- const value = parsed.values.empty === true ? '' : await readValue(parsed.values.file)
76
+ const value = parsed.values.empty === true ? '' : await readValue(key, parsed.values.file)
73
77
 
74
78
  const file = await withLocks([target], async () => {
75
79
  const current = await readOrEmpty(target)
@@ -87,7 +91,7 @@ export async function set(args: string[]): Promise<number> {
87
91
  }
88
92
 
89
93
  export async function unset(args: string[]): Promise<number> {
90
- const parsed = parse(args, unsetUsage, QUIET)
94
+ const parsed = parse(args, unsetUsage, QUIET, { exits: UNSET_EXITS })
91
95
 
92
96
  const [key, target = DEFAULT_FILE] = parsed.positionals
93
97
 
@@ -145,7 +149,7 @@ export async function mv(args: string[]): Promise<number> {
145
149
  to: { type: 'string', description: 'the file to put KEY in, created when missing' },
146
150
  force: { type: 'boolean', description: 'replace KEY when the target already sets it' },
147
151
  ...QUIET,
148
- })
152
+ }, { exits: MV_EXITS })
149
153
 
150
154
  const [key] = parsed.positionals
151
155
  const { from, to, force } = parsed.values
@@ -172,7 +176,7 @@ export async function cp(args: string[]): Promise<number> {
172
176
  to: { type: 'string', description: 'the file to put the copy in, created when missing' },
173
177
  as: { type: 'string', description: 'store the copy under this key instead' },
174
178
  ...QUIET,
175
- })
179
+ }, { exits: CP_EXITS })
176
180
 
177
181
  const [key] = parsed.positionals
178
182
  const { from, to, as } = parsed.values
@@ -1,3 +1,4 @@
1
+ import type { ExitRow } from '@kaynooo/cli-kit'
1
2
  import type { AppPins } from '../pins'
2
3
  import { readdir, stat } from 'node:fs/promises'
3
4
  import { join, resolve } from 'node:path'
@@ -10,8 +11,9 @@ Checks that an app's tests pin the env that reaches outside.
10
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.
11
12
  A file whose pages reach none of them says so with a \`// ev pins: none reached, <why>\` comment.
12
13
  The dir is an app, or a monorepo holding apps one level down (the current folder by default).
13
- Reads variable names only, never a value.
14
- Exits 0 when everything is pinned, 1 when something is not, 2 on a usage error.`
14
+ Reads variable names only, never a value.`
15
+
16
+ const EXITS: ExitRow[] = [[0, 'everything is pinned'], [1, 'something is not'], [2, 'a usage error']]
15
17
 
16
18
  const options = {
17
19
  json: jsonOption('each app with its reaching, unpinned variables and flagged test files'),
@@ -57,7 +59,7 @@ function name(app: AppPins, root: string): string {
57
59
  }
58
60
 
59
61
  export async function pins(args: string[]): Promise<number> {
60
- const parsed = parse(args, usage, options, { positionals: ['[dir]'] })
62
+ const parsed = parse(args, usage, options, { positionals: ['[dir]'], exits: EXITS })
61
63
  const json = parsed.values.json === true
62
64
  const root = resolve(parsed.positionals[0] ?? '.')
63
65
  const except = new Set((parsed.values.except ?? '').split(',').map(entry => entry.trim()).filter(entry => entry !== ''))
@@ -1,3 +1,4 @@
1
+ import type { ExitRow } from '@kaynooo/cli-kit'
1
2
  import type { Dotenv } from '../dotenv'
2
3
  import type { KnownSecrets } from '../mask'
3
4
  import { fail, jsonOption, parse, printJson, role, table } from '@kaynooo/cli-kit'
@@ -10,17 +11,17 @@ const listUsage = `ev list [file]
10
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
13
 
13
- --json prints [{file, key, value, secret}], value masked and secret true when a value was.
14
+ --json prints [{file, key, value, secret}], value masked and secret true when a value was.`
14
15
 
15
- Exits 0 when it printed them, 1 when there is no .env* file, 2 on a usage error.`
16
+ const LIST_EXITS: ExitRow[] = [[0, 'it printed them'], [1, 'there is no .env* file'], [2, 'a usage error']]
16
17
 
17
18
  const getUsage = `ev get KEY [file]
18
19
 
19
20
  Prints the masked value of one key, from every .env* file that sets it or from one file.
20
21
 
21
- --json prints [{file, key, value, secret}] for each file that sets it.
22
+ --json prints [{file, key, value, secret}] for each file that sets it.`
22
23
 
23
- Exits 0 when the key is set, 1 when it is not set anywhere, 2 on a usage error.`
24
+ const GET_EXITS: ExitRow[] = [[0, 'the key is set'], [1, 'it is not set anywhere'], [2, 'a usage error']]
24
25
 
25
26
  function display(key: string, value: string, known: KnownSecrets): string {
26
27
  return maskValue(key, value, known).replaceAll('\n', '\\n').replaceAll('\r', '\\r')
@@ -69,7 +70,7 @@ async function readAll(names: string[]): Promise<{ files: [name: string, file: D
69
70
  }
70
71
 
71
72
  export async function list(args: string[]): Promise<number> {
72
- const parsed = parse(args, listUsage, jsonFlag)
73
+ const parsed = parse(args, listUsage, jsonFlag, { exits: LIST_EXITS })
73
74
 
74
75
  const [file] = parsed.positionals
75
76
  const names = file === undefined ? await envFiles() : [file]
@@ -95,7 +96,7 @@ export async function list(args: string[]): Promise<number> {
95
96
  }
96
97
 
97
98
  export async function get(args: string[]): Promise<number> {
98
- const parsed = parse(args, getUsage, jsonFlag)
99
+ const parsed = parse(args, getUsage, jsonFlag, { exits: GET_EXITS })
99
100
 
100
101
  const [key, file] = parsed.positionals
101
102
 
@@ -126,22 +127,22 @@ const grepUsage = `ev grep [-i] <regex> [file...]
126
127
 
127
128
  Prints the keys matching the regular expression, from the folder's .env* files or the files given, with their values masked as ev list does. The regex is matched against the key only, never the value: \`ev grep '^DATABASE_'\` instead of \`grep ^DATABASE_ .env\`.
128
129
 
129
- --json prints [{file, key, value, secret}].
130
+ --json prints [{file, key, value, secret}].`
130
131
 
131
- Exits 0 when a key matches, 1 when none does, 2 on a usage error.`
132
+ const GREP_EXITS: ExitRow[] = [[0, 'a key matches'], [1, 'none does'], [2, 'a usage error']]
132
133
 
133
134
  const showUsage = `ev show <rev>:<file>
134
135
 
135
136
  Prints every key of an env file as a git revision holds it, values masked as ev list does: \`ev show HEAD~1:api/.env\` instead of \`git show HEAD~1:api/.env\`.
136
137
 
137
- --json prints [{file, key, value, secret}].
138
+ --json prints [{file, key, value, secret}].`
138
139
 
139
- Exits 0 when it printed them, 1 when git cannot show the file, 2 on a usage error.`
140
+ const SHOW_EXITS: ExitRow[] = [[0, 'it printed them'], [1, 'git cannot show the file'], [2, 'a usage error']]
140
141
 
141
142
  const REVISION = /^([^:]+):(.+)$/
142
143
 
143
144
  export async function grep(args: string[]): Promise<number> {
144
- const parsed = parse(args, grepUsage, { 'ignore-case': { type: 'boolean', short: 'i', description: 'match the key whatever its case' }, ...jsonFlag })
145
+ const parsed = parse(args, grepUsage, { 'ignore-case': { type: 'boolean', short: 'i', description: 'match the key whatever its case' }, ...jsonFlag }, { exits: GREP_EXITS })
145
146
 
146
147
  const [source, ...given] = parsed.positionals
147
148
 
@@ -178,7 +179,7 @@ export async function grep(args: string[]): Promise<number> {
178
179
  }
179
180
 
180
181
  export async function show(args: string[]): Promise<number> {
181
- const parsed = parse(args, showUsage, jsonFlag)
182
+ const parsed = parse(args, showUsage, jsonFlag, { exits: SHOW_EXITS })
182
183
 
183
184
  const [target] = parsed.positionals
184
185
  const [, revision, path] = REVISION.exec(target ?? '') ?? []
@@ -1,3 +1,4 @@
1
+ import type { ExitRow } from '@kaynooo/cli-kit'
1
2
  import process from 'node:process'
2
3
  import { parse, readInput } from '@kaynooo/cli-kit'
3
4
  import { loadKnown } from '../files'
@@ -6,7 +7,9 @@ import { check, Redactor } from '../redactor'
6
7
  const usage = `redact [--check]
7
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.
9
- --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\`.\n\nExits 0 when it copied the input or found no secret, 1 when --check finds one, 2 on a usage error.`
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\`.`
11
+
12
+ const EXITS: ExitRow[] = [[0, 'it copied the input or found no secret'], [1, '--check finds one'], [2, 'a usage error']]
10
13
 
11
14
  const options = {
12
15
  'check': { type: 'boolean', description: 'list where secrets are instead of masking them, exit 1 when found' },
@@ -14,7 +17,7 @@ const options = {
14
17
  } as const
15
18
 
16
19
  export async function redact(args: string[]): Promise<number> {
17
- const parsed = parse(args, usage, options, { 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 | redact', 'the resolved compose file, secrets masked'], ['git diff --cached | redact --check', 'refuse a commit carrying a secret']] })
18
21
 
19
22
  const known = parsed.values['no-env'] === true ? undefined : await loadKnown()
20
23
 
package/src/dotenv.ts CHANGED
@@ -3,6 +3,8 @@ export interface DotenvLine {
3
3
  raw: string
4
4
  key?: string
5
5
  value?: string
6
+ // The value opens a quote that no line closes before the next assignment: it is read as the rest of its own line, as Bun does.
7
+ unterminated?: boolean
6
8
  }
7
9
 
8
10
  export interface Dotenv {
@@ -83,13 +85,22 @@ export function parseDotenv(text: string): Dotenv {
83
85
  let raw = line
84
86
  let end = closingQuote(body, quote)
85
87
 
86
- while (end === -1 && index + 1 < physical.length) {
88
+ const first = index
89
+
90
+ while (end === -1 && index + 1 < physical.length && !ASSIGNMENT.test(physical[index + 1] ?? '')) {
87
91
  index++
88
92
  body += `\n${(physical[index] ?? '').replace(CARRIAGE_RETURN, '')}`
89
93
  raw += `\n${physical[index] ?? ''}`
90
94
  end = closingQuote(body, quote)
91
95
  }
92
96
 
97
+ if (end === -1 && index + 1 < physical.length) {
98
+ index = first
99
+ lines.push({ raw: line, key, value: unescapeDollar(start.replace(INLINE_COMMENT, '').trim()), unterminated: true })
100
+
101
+ continue
102
+ }
103
+
93
104
  const inner = end === -1 ? body : body.slice(0, end)
94
105
 
95
106
  lines.push({ raw, key, value: quote === '"' ? unescapeDouble(inner) : unescapeDollar(inner) })
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.
32
- skip?: (value: string) => boolean
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
33
33
  }
34
34
 
35
35
  // A secret value starting like this is a reference or a placeholder, not the secret.
@@ -37,10 +37,39 @@ function isPlaceholder(value: string): boolean {
37
37
  return PLACEHOLDER.test(value) || PLAIN_VALUE.test(value)
38
38
  }
39
39
 
40
+ // Names that are secrets whatever they are followed by, and names that also open prose (`token: expired`, `auth: failed`).
41
+ const STRONG_NAME = 'password|passwd|secret|api[_-]?key|access[_-]?key|private[_-]?key|account[_-]?key|shared[_-]?access[_-]?key'
42
+ const WEAK_NAME = 'token|credentials?|auth'
43
+ const PLAIN_WORD = /^[a-z]+$/i
44
+ const AFTER_COLON = /:\s*$/
45
+ const DIGIT = /\d/
46
+ const KEY_VALUE_GAP = '\\s*[:=]\\s*'
47
+
48
+ // A strong name before a colon, so likely prose, holding only a word is left alone.
49
+ function isProse(value: string, before: string): boolean {
50
+ return isPlaceholder(value) || (AFTER_COLON.test(before) && PLAIN_WORD.test(value))
51
+ }
52
+
53
+ // A value under a weak name is a secret only when it holds a digit or is long, which a word of prose never does.
54
+ function isWeak(value: string, before: string): boolean {
55
+ return isProse(value, before) || !(DIGIT.test(value) || value.length >= 16)
56
+ }
57
+
58
+ // A key name holding one of the words: `AWS_SECRET_ACCESS_KEY`, `X-Api-Key`, `access_token`.
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')
61
+ }
62
+
40
63
  // A pattern with a group masks that group only, else the whole match.
41
64
  const TOKEN_FORMATS: TokenFormat[] = [
42
65
  { kind: 'GitHub token', pattern: /\b(?:gh[pousr]_|github_pat_)\w{20,}/dg },
43
- { kind: 'GitLab token', pattern: /\bglpat-[\w-]{20,}/dg },
66
+ { kind: 'GitLab token', pattern: /\bgl(?:pat|rt|dt|ptt)-[\w-]{20,}/dg },
67
+ { kind: 'Hugging Face token', pattern: /\bhf_[A-Za-z]{30,}/dg },
68
+ { kind: 'webhook secret', pattern: /\bwhsec_\w{20,}/dg },
69
+ { kind: 'DigitalOcean token', pattern: /\bdop_v1_\w{20,}/dg },
70
+ { kind: 'Shopify token', pattern: /\bshp(?:at|ca|pa|ss)_\w{20,}/dg },
71
+ { kind: 'password', pattern: /\bmysql(?:dump|admin)?\s+(?:\S+\s+)*?-p([^\s"'|;&-]\S{3,})/dg },
72
+ { kind: 'password', pattern: /\bsshpass\s+(?:-[a-oq-z]\s+)*-p\s*([^\s"'|;&]{4,})/dg },
44
73
  { kind: 'API key', pattern: /\bsk-[\w-]{20,}/dg },
45
74
  { kind: 'Slack token', pattern: /\bx(?:ox[abprs]|app)-[\w-]{10,}/dg },
46
75
  { kind: 'JWT', pattern: /\beyJ[\w-]+\.[\w-]+\.[\w-]+/dg },
@@ -51,8 +80,10 @@ const TOKEN_FORMATS: TokenFormat[] = [
51
80
  { kind: 'SendGrid key', pattern: /\bSG\.[\w-]{16,}\.[\w-]{16,}/dg },
52
81
  { kind: 'Authorization header', pattern: /\bAuthorization["']?\s*[:=]\s*["']?(?:Bearer|Basic|Token|Digest)\s+([^\s"',;]{8,})/dgi, skip: isPlaceholder },
53
82
  { kind: 'Bearer token', pattern: /\bBearer\s+((?=[\w.~+/=-]*\d)[\w.~+/=-]{20,})/dg },
54
- { kind: 'password', pattern: /(?<![\w-])(?:[\w-]{0,30}[_-])?(?:password|passwd|secret|api[_-]?key)(?:[_-][\w-]{0,30})?=([^\s"'&;,]{4,})/dgi, skip: isPlaceholder },
55
- { kind: 'password', pattern: /(?<![\w-])["']?(?:[\w-]{0,30}[_-])?(?:password|passwd|secret|api[_-]?key)(?:[_-][\w-]{0,30})?["']?\s*[:=]\s*(["'])((?:\\.|(?!\1)[^\\\n]){4,})\1/dgi, skip: isPlaceholder },
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 },
56
87
  ]
57
88
 
58
89
  // 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.
@@ -207,7 +238,7 @@ export function findSecrets(line: string, known?: KnownSecrets): Match[] {
207
238
 
208
239
  const value = line.slice(start, end)
209
240
 
210
- if (!skip?.(value))
241
+ if (!skip?.(value, line.slice(0, start)))
211
242
  found.push({ start, end, kind, mask: hint(value) })
212
243
  }
213
244
  }