envstash-cli 0.5.1 → 0.6.0

package/src/repo-path.mjs

@@ -1,4 +1,5 @@
-import { isAbsolute, relative, resolve } from 'node:path'
+import { lstatSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
 
 import { CliError } from './ui.mjs'
 
@@ -24,7 +25,44 @@ const SEGMENT = /^[A-Za-z0-9._-]+$/
 
 const MAX_LENGTH = 255
 
+/**
+ * Directories whose contents run code, and the file that decides where this CLI
+ * sends credentials. The grammar keeps a name inside the repo, but inside the
+ * repo is not the same as harmless: a server that answers `.git/config` with an
+ * `fsmonitor` line, `.husky/pre-commit`, or `node_modules/.bin/next` gets a
+ * command run by the next `git status` or `pnpm dev`, and one that answers
+ * `.envstash.json` gets to repoint every later command at itself.
+ *
+ * Denied at any depth rather than only as the first segment: a nested package
+ * has its own `node_modules`, a vendored repo its own `.git`, and a nested link
+ * file is found first when commands run from that package. Compared without
+ * case, because on macOS and Windows `.GIT/config` is `.git/config`.
+ */
+const DENIED_SEGMENTS = new Set(['.git', 'node_modules', '.husky'])
+const DENIED_FILE = '.envstash.json'
+
 export function isSafeRepoPath(name) {
+  return isWellFormedRepoPath(name) && !isDeniedRepoPath(name)
+}
+
+/** True for a well-formed name that lands somewhere envstash never writes. */
+export function isDeniedRepoPath(name) {
+  const segments = String(name).toLowerCase().split('/').map(stripWindowsTrailing)
+
+  return segments.some(segment => DENIED_SEGMENTS.has(segment)) || segments.at(-1) === DENIED_FILE
+}
+
+/**
+ * Win32 path normalisation drops trailing dots and spaces from every component,
+ * so on NTFS `.git./hooks/pre-commit` and `.git /hooks` both land in `.git/hooks`.
+ * `.git.` passes the segment grammar, so the deny list compares what Windows
+ * would actually open. Harmless elsewhere: no legitimate name ends in a dot.
+ */
+function stripWindowsTrailing(segment) {
+  return segment.replace(/[. ]+$/, '')
+}
+
+function isWellFormedRepoPath(name) {
   if (typeof name !== 'string' || name === '' || name.length > MAX_LENGTH) {
     return false
   }
@@ -66,12 +104,76 @@ export function resolveInsideRepo(repoRoot, name) {
   return target
 }
 
+/**
+ * Resolve `name` under `repoRoot` for an actual read or write, or refuse.
+ *
+ * `resolveInsideRepo` is lexical: it proves the *name* stays inside, but a
+ * symbolic link does not care what its name is. A cloned repo can ship
+ * `.env.local -> ~/.ssh/id_rsa`, and `envs push` would upload the key; `pull`
+ * would write through the same link. So every component from the repo root down
+ * to the file is lstat-ed, and any link — the file itself or a directory on the
+ * way — is refused. Components that do not exist yet are fine: `pull` creates
+ * them, as real directories.
+ *
+ * Refusing rather than following even a link that points inside the repo: this
+ * only ever handles `.env` files and credentials, which have no reason to be
+ * links, and "inside" is exactly the judgement an attacker gets to race.
+ */
+export function resolveRepoFile(repoRoot, name) {
+  const target = resolveInsideRepo(repoRoot, name)
+  const link = findSymlink(repoRoot, name)
+
+  if (link) {
+    throw new CliError(`Refusing to follow a symbolic link: ${link}.`, {
+      hint:
+        link === name
+          ? `${name} is a link to somewhere else. envstash only reads and writes real files, so a link cannot redirect a secret. Replace it with the file itself.`
+          : `${name} is inside ${link}, which is a link to somewhere else. envstash only reads and writes real files inside the repo.`,
+    })
+  }
+
+  return target
+}
+
+/**
+ * The first symbolic link on the way from `repoRoot` to `name` (as a repo-relative
+ * path), or null. Links above the repo root are not this CLI's business — a home
+ * directory on a symlinked volume is ordinary.
+ */
+export function findSymlink(repoRoot, name) {
+  const segments = name.split('/')
+
+  for (let depth = 1; depth <= segments.length; depth += 1) {
+    const partial = segments.slice(0, depth).join('/')
+    let stats
+
+    try {
+      stats = lstatSync(join(repoRoot, partial))
+    } catch {
+      // Nothing here yet, so nothing below it either.
+      return null
+    }
+
+    if (stats.isSymbolicLink()) {
+      return partial
+    }
+  }
+
+  return null
+}
+
 /** Drop the names that are not safe, for the paths where refusing is too blunt. */
 export function keepSafeRepoPaths(names) {
   return names.filter(name => isSafeRepoPath(name))
 }
 
 function refuse(name) {
+  if (isWellFormedRepoPath(name) && isDeniedRepoPath(name)) {
+    return new CliError(`Refusing to use the file name ${JSON.stringify(String(name))}.`, {
+      hint: 'envstash never reads or writes .git/, node_modules/, .husky/ or .envstash.json — files there run code or redirect the CLI. Report this if it came from your own server.',
+    })
+  }
+
   return new CliError(`Refusing to use the file name ${JSON.stringify(String(name))}.`, {
     hint: 'A file name must stay inside the repo. Report this if it came from your own server.',
   })

package/src/session.mjs

@@ -67,16 +67,21 @@ export function resolveHostSource(flags) {
     return explicit
   }
 
-  try {
-    const link = readLink(findRepoRoot())
+  let link = null
 
-    if (link?.host) {
-      return { host: resolveHost(link.host), source: 'link' }
-    }
+  try {
+    link = readLink(findRepoRoot())
   } catch {
     // A malformed link file is reported by the commands that actually read it.
   }
 
+  // Outside the try: a host the CLI refuses (plain http to another machine) is
+  // an answer, not a malformed file, and falling back to the default instead
+  // would quietly run this repo's commands against a different server.
+  if (link?.host) {
+    return { host: resolveHost(link.host), source: 'link' }
+  }
+
   return { host: resolveHost(undefined), source: 'default' }
 }
 

package/src/status.mjs

@@ -1,5 +1,5 @@
 import { digestFileBytes } from './blob.mjs'
-import { digestValue } from './env-file.mjs'
+import { digestValue, KEY_PATTERN } from './env-file.mjs'
 
 /**
  * Per-key verdicts.
@@ -39,7 +39,15 @@ export function compareFile(name, localEntries, cloudKeys) {
 
   const keys = []
   const localMap = new Map((localEntries ?? []).map(entry => [entry.key, entry.value]))
-  const cloudMap = new Map((cloudKeys ?? []).map(entry => [entry.key, entry.digest]))
+  // A cloud key outside the variable-name grammar is dropped, not compared. The
+  // server enforces the same grammar on the way in, so only a hostile or broken
+  // server sends one — and a key name is printed by status and diff, which makes
+  // it a way to put escape sequences on the developer's terminal.
+  const cloudMap = new Map(
+    (cloudKeys ?? [])
+      .filter(entry => typeof entry?.key === 'string' && KEY_PATTERN.test(entry.key))
+      .map(entry => [entry.key, entry.digest])
+  )
 
   for (const [key, value] of localMap) {
     const cloudDigest = cloudMap.get(key)

package/src/sync.mjs

@@ -0,0 +1,137 @@
+import { FILE_STATE, KEY_STATE } from './status.mjs'
+
+/**
+ * What `envs sync` decided to do about one file.
+ *
+ * `MERGE` is the interesting one and the reason the command exists: both sides
+ * moved, and neither is wholly right.
+ */
+export const SYNC_ACTION = {
+  /** Already identical. */
+  NONE: 'none',
+  /** Only the cloud has it — write it to disk. */
+  PULL: 'pull',
+  /** Only disk has it — send it up. */
+  PUSH: 'push',
+  /** Both sides moved; copy each side's additions to the other. */
+  MERGE: 'merge',
+  /** An opaque file that differs. Bytes do not merge — a human has to choose. */
+  CONFLICT: 'conflict',
+}
+
+/** `--prefer` values. */
+export const PREFER = { LOCAL: 'local', CLOUD: 'cloud' }
+
+/**
+ * Decide what sync does, for a whole comparison. Pure: no network, no disk.
+ *
+ * The rule, and the reason for it:
+ *
+ * There is no record of the last sync, so "which side moved" is unknowable —
+ * the same fact that makes `envs status` say `local_only` and `cloud_only`
+ * rather than "added" and "deleted". Sync therefore performs the one merge
+ * that cannot lose anything: every key that exists on one side only is copied
+ * to the other, in whichever direction that implies, and nothing is ever
+ * deleted or pruned. When the guess is wrong, the cost is a key coming back
+ * that a teammate had removed — visible in the next `envs status`, and fixed
+ * with `envs rm` — rather than a secret that exists nowhere any more.
+ *
+ * A key that exists on both sides with different values is the one case where
+ * copying would destroy something, so sync refuses to guess: it is reported as
+ * a conflict and both sides are left exactly as they are. `--prefer local` or
+ * `--prefer cloud` is how a developer says which side wins, and it is
+ * deliberately a separate, typed-out act.
+ */
+export function planSync(files, { prefer } = {}) {
+  return files.map(file => planFile(file, prefer))
+}
+
+function planFile(file, prefer) {
+  const plan = {
+    name: file.name,
+    kind: file.kind,
+    action: SYNC_ACTION.NONE,
+    /** Keys to send up. */
+    upload: [],
+    /** Keys to bring down. */
+    download: [],
+    /** Keys that differ on both sides and nobody has chosen between. */
+    conflicts: [],
+  }
+
+  if (file.state === FILE_STATE.IN_SYNC) {
+    return plan
+  }
+
+  if (file.state === FILE_STATE.CLOUD_ONLY) {
+    return { ...plan, action: SYNC_ACTION.PULL }
+  }
+
+  if (file.state === FILE_STATE.UNTRACKED) {
+    return { ...plan, action: SYNC_ACTION.PUSH }
+  }
+
+  // DIFFERS. An opaque file has no keys to merge — half a certificate is not a
+  // certificate — so the whole file is the unit, and the whole file is the
+  // conflict until someone names a winner.
+  if (file.kind === 'file') {
+    if (prefer === PREFER.LOCAL) {
+      return { ...plan, action: SYNC_ACTION.PUSH }
+    }
+
+    if (prefer === PREFER.CLOUD) {
+      return { ...plan, action: SYNC_ACTION.PULL }
+    }
+
+    return { ...plan, action: SYNC_ACTION.CONFLICT }
+  }
+
+  const keysIn = state => file.keys.filter(entry => entry.state === state).map(entry => entry.key)
+  const modified = keysIn(KEY_STATE.MODIFIED)
+
+  const upload = keysIn(KEY_STATE.LOCAL_ONLY)
+  const download = keysIn(KEY_STATE.CLOUD_ONLY)
+
+  if (prefer === PREFER.LOCAL) {
+    upload.push(...modified)
+  } else if (prefer === PREFER.CLOUD) {
+    download.push(...modified)
+  }
+
+  return {
+    ...plan,
+    action: SYNC_ACTION.MERGE,
+    upload: upload.sort(),
+    download: download.sort(),
+    conflicts: prefer ? [] : modified,
+  }
+}
+
+/** True when this file needs a decision sync will not make on its own. */
+export function isBlocked(plan) {
+  return plan.action === SYNC_ACTION.CONFLICT || plan.conflicts.length > 0
+}
+
+/** True when the plan would touch anything at all. */
+export function isChanging(plan) {
+  return (
+    plan.action === SYNC_ACTION.PULL ||
+    plan.action === SYNC_ACTION.PUSH ||
+    plan.upload.length > 0 ||
+    plan.download.length > 0
+  )
+}
+
+/**
+ * Exit 1 when a conflict is left unresolved, the way `status` and `diff` exit 1
+ * on drift: sync having run is not the same as the repo being in sync, and a
+ * hook or a CI job should hear the difference. `--exit-zero` opts out, as it
+ * does there.
+ */
+export function conflictExitCode(flags, plans) {
+  if (flags['exit-zero']) {
+    return 0
+  }
+
+  return plans.some(isBlocked) ? 1 : 0
+}

package/src/ui.mjs

@@ -1,3 +1,5 @@
+import { createInterface } from 'node:readline'
+
 /**
  * Terminal output helpers.
  *
@@ -71,20 +73,97 @@ export function fail(message, options) {
 }
 
 /**
- * Mask a secret for display: keep a little of the head and tail so a human can
- * recognise which value it is, hide the middle. Short values are hidden whole —
- * showing 2 of 6 characters of a PIN is worse than showing none.
+ * Mask a secret for display: a little of the head, so a human can tell which
+ * value it is, and the length. Never the tail — the end of a key is often the
+ * part a provider prints as its fingerprint, and head plus tail together gave
+ * away 8 characters of every secret on screen. Short values are hidden whole,
+ * length included — showing 2 of 6 characters of a PIN, or that it has 6, is
+ * worse than showing nothing.
  */
+const MASK = '•'.repeat(8)
+
 export function maskValue(value) {
   if (value === '') {
     return style.dim('(empty)')
   }
 
   if (value.length <= 12) {
-    return style.dim('•'.repeat(8))
+    return style.dim(MASK)
   }
 
-  return `${value.slice(0, 4)}${style.dim('•'.repeat(8))}${value.slice(-4)}`
+  return `${sanitize(value.slice(0, 4))}${style.dim(`${MASK} (${value.length} chars)`)}`
+}
+
+/**
+ * Terminal control sequences, whole: CSI (`ESC [ … final`), OSC and the other
+ * string commands (`ESC ] … BEL` or `… ESC \\`), and two-byte escapes. Removed
+ * as units so a stripped sequence does not leave its `[2J` behind as litter.
+ */
+const ESCAPE_SEQUENCE =
+  /\u001b(?:\[[0-?]*[ -/]*[@-~]|[\]PX^_][^\u0007\u001b]*(?:\u0007|\u001b\\)?|[@-Z\\-_]?)/g
+
+/**
+ * Everything else a terminal acts on rather than prints: C0 controls, DEL, the
+ * C1 range (U+009B is a one-character CSI), and the Unicode line separators and
+ * bidi overrides that can reorder or break a line visually.
+ */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g
+
+/**
+ * Make a string safe to print when someone else chose it.
+ *
+ * Key names, error messages and account details come from the server, and a
+ * hostile one could otherwise send escape sequences that clear the screen and
+ * draw a convincing "all in sync" over the real output. Newlines become spaces
+ * by default, because a forged line is the attack; pass `{ newlines: true }`
+ * where a line break is meant.
+ */
+export function sanitize(text, { newlines = false } = {}) {
+  const stripped = String(text ?? '').replace(ESCAPE_SEQUENCE, '')
+
+  return stripped.replace(CONTROL, char => {
+    if (char === '\n') {
+      return newlines ? '\n' : ' '
+    }
+
+    return char === '\t' ? ' ' : ''
+  })
+}
+
+/**
+ * True when a human is there to answer a question: both ends are a terminal.
+ * Checking stdin alone is not enough — `envs push > log.txt` has a keyboard but
+ * no screen to show the question on.
+ */
+export function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY)
+}
+
+/**
+ * Ask a yes/no question; anything but y or yes is no.
+ *
+ * Resolves false if input ends before an answer (Ctrl-D, a closed pipe), so an
+ * unanswered question can never be read as consent.
+ */
+export async function confirm(question, { input = process.stdin, output = process.stdout } = {}) {
+  const rl = createInterface({ input, output })
+
+  return await new Promise(resolve => {
+    let answered = false
+
+    rl.once('close', () => {
+      if (!answered) {
+        output.write('\n')
+        resolve(false)
+      }
+    })
+
+    rl.question(question, answer => {
+      answered = true
+      rl.close()
+      resolve(/^y(es)?$/i.test(answer.trim()))
+    })
+  })
 }
 
 /** Pad to a display width, ignoring colour codes. */