envstash-cli 0.5.2 → 0.6.1

package/src/context.mjs

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { isEnvName } from './blob.mjs'
 import { parseEnvFile } from './env-file.mjs'
 import { discoverTrackedFiles, findRepoRoot, readLink, resolveProject } from './project.mjs'
-import { resolveInsideRepo } from './repo-path.mjs'
+import { findSymlink, resolveInsideRepo, resolveRepoFile } from './repo-path.mjs'
 import { requireHostToken } from './session.mjs'
 import { errOut, pluralize, style } from './ui.mjs'
 
@@ -36,9 +36,11 @@ export function resolveContext(flags) {
  * present — an explicit list is the only way to include a nested path like
  * `apps/web/.env.local`, which discovery does not scan for. With no link file,
  * fall back to the union of what discovery finds — root `.env*` files plus git-ignored
- * files in `.config/` — and whatever the cloud holds.
+ * files in `.config/` — and whatever the cloud holds. Those inferred names skip
+ * symbolic links with a warning rather than refusing (see `skipSymlinks`);
+ * `sink` is `'write'` for `pull`, so the warning says the file is not written.
  */
-export function resolveFileNames({ repoRoot, link, cloudFiles, requested }) {
+export function resolveFileNames({ repoRoot, link, cloudFiles, requested, sink = 'read' }) {
   if (requested?.length) {
     return check([...new Set(requested)].sort())
   }
@@ -49,7 +51,41 @@ export function resolveFileNames({ repoRoot, link, cloudFiles, requested }) {
 
   const names = new Set([...discoverTrackedFiles(repoRoot), ...cloudFiles.map(file => file.name)])
 
-  return check([...names].sort())
+  return skipSymlinks(repoRoot, check([...names].sort()), sink)
+}
+
+/**
+ * Drop, with a warning, the inferred names that are symbolic links on disk.
+ *
+ * Only for names nobody asked for. An explicit argument or a link-file entry
+ * that is a link still stops the command in `resolveRepoFile` — someone chose
+ * that name, so the refusal is the answer. But a name that is here only because
+ * the cloud holds a file by it says nothing about the developer's intent, and a
+ * `.env -> .env.development` or a worktree link is ordinary. Refusing there
+ * would take every sync command down over one file the developer never
+ * mentioned; skipping it leaves the link and whatever it points at untouched.
+ * (Discovery already leaves links out, so in practice these come from the
+ * cloud listing.)
+ */
+function skipSymlinks(repoRoot, names, sink) {
+  return names.filter(name => {
+    const link = findSymlink(repoRoot, name)
+
+    if (!link) {
+      return true
+    }
+
+    const why = link === name ? 'it is a symbolic link' : `${link} is a symbolic link`
+    const effect =
+      sink === 'write'
+        ? `Not written: envstash never writes through a link. Replace ${link} with a real file to pull it.`
+        : `Not read: envstash never reads through a link. Replace ${link} with a real file to sync it.`
+
+    errOut(`  ${style.yellow('!')} skipping ${name}: ${why}`)
+    errOut(`      ${style.dim(effect)}`)
+
+    return false
+  })
 }
 
 /**
@@ -84,8 +120,9 @@ export function loadLocalFiles(repoRoot, names, kinds = new Map()) {
 
   for (const name of names) {
     // Resolved rather than joined: `join` happily walks out of the repo, and
-    // this is the read side of the same hole `pull` had on the write side.
-    const path = resolveInsideRepo(repoRoot, name)
+    // this is the read side of the same hole `pull` had on the write side. A
+    // symlink is refused here too, or `.env.local -> ~/.ssh/id_rsa` uploads the key.
+    const path = resolveRepoFile(repoRoot, name)
 
     if (!existsSync(path)) {
       files.set(name, null)

package/src/env-file.mjs

@@ -38,10 +38,11 @@ export function parseEnvFile(contents) {
   const entries = []
   const skipped = []
   const seen = new Map()
+  const spans = new Map()
 
   let index = 0
   let lineNumber = 1
-  const text = contents.replace(/^/, '')
+  const text = stripBom(contents)
 
   while (index < text.length) {
     const lineEnd = findLineEnd(text, index)
@@ -90,13 +91,29 @@ export function parseEnvFile(contents) {
       entries.push({ key, value })
     }
 
+    // Where this key's assignment sits in `text`, for `mergeEnvText`. A repeated
+    // key overwrites the earlier span, just as it overwrote the earlier value:
+    // the assignment that wins is the one a rewrite has to replace.
+    spans.set(key, { start: index, end: Math.min(nextIndex, text.length) })
+
     // Counted rather than incremented: a quoted value may have spanned several
     // lines, and a later skipped line has to report the number a human sees.
     lineNumber += countNewlines(text, index, nextIndex)
     index = nextIndex
   }
 
-  return { entries, skipped }
+  return { entries, skipped, spans }
+}
+
+/**
+ * Drop a UTF-8 BOM.
+ *
+ * A function rather than a repeated regex because the offsets in `spans` are
+ * relative to its result: anything that rewrites the text has to start from
+ * byte zero of the same string the parser measured.
+ */
+function stripBom(contents) {
+  return String(contents).replace(/^\ufeff/, '')
 }
 
 function findLineEnd(text, from) {
@@ -200,31 +217,95 @@ function needsQuoting(value) {
  * file. That matters because the entries handed to `envs pull` come from the
  * server, not from the developer.
  */
-const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+export const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
 
 /** Serialize entries back to `.env` text. Round-trips with `parseEnv`. */
 export function serializeEnv(entries) {
-  const lines = entries.map(({ key, value }) => {
-    if (!KEY_PATTERN.test(key)) {
-      throw new CliError(`Refusing to write the key ${JSON.stringify(String(key))}.`, {
-        hint: 'An environment variable name must be letters, digits and underscores.',
-      })
-    }
+  const lines = entries.map(serializeEntry)
+
+  return lines.length > 0 ? `${lines.join('\n')}\n` : ''
+}
+
+/** One `KEY=value` line, quoted as the value requires. No trailing newline. */
+export function serializeEntry({ key, value }) {
+  if (!KEY_PATTERN.test(key)) {
+    throw new CliError(`Refusing to write the key ${JSON.stringify(String(key))}.`, {
+      hint: 'An environment variable name must be letters, digits and underscores.',
+    })
+  }
+
+  if (!needsQuoting(value)) {
+    return `${key}=${value}`
+  }
+
+  // `$` and backticks mean nothing to this parser inside double quotes, but
+  // bash, docker compose and dotenv-expand all expand them there — so
+  // `PASS='p$ss'` pulled back as `PASS="p$ss"` becomes `p` everywhere else.
+  // Single quotes are literal to all of them. They cannot hold a `'` or span
+  // lines without escapes, which single quotes do not have, so those values
+  // stay double-quoted.
+  if (/[$`]/.test(value) && !/['\n\r]/.test(value)) {
+    return `${key}='${value}'`
+  }
+
+  const escaped = value
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
 
-    if (!needsQuoting(value)) {
-      return `${key}=${value}`
+  return `${key}="${escaped}"`
+}
+
+/**
+ * Apply key/value changes to existing `.env` text, editing it in place.
+ *
+ * This is what makes `envs sync` safe to run on a file someone maintains by
+ * hand. `pull` regenerates the whole file from the cloud's entries, which is
+ * correct when the cloud's copy *is* the answer — but a merge only has an
+ * opinion about the handful of keys that moved, and rewriting the file would
+ * silently throw away every comment, blank line and grouping around them.
+ *
+ * A key that is already assigned has its assignment line replaced where it
+ * stands; a key that is new is appended. Replacements are applied back to
+ * front so that earlier offsets stay valid as the text changes length.
+ *
+ * Note that a replaced line loses an `export ` prefix or a trailing
+ * `# comment` on that one line: the span covers the whole assignment, and
+ * reproducing decoration around a value nobody can see is not worth a parser
+ * that has to understand it.
+ */
+export function mergeEnvText(contents, changes) {
+  const { spans } = parseEnvFile(contents)
+
+  const replacements = []
+  const additions = []
+
+  for (const change of changes) {
+    const span = spans.get(change.key)
+
+    if (span) {
+      replacements.push({ span, line: serializeEntry(change) })
+    } else {
+      additions.push(change)
     }
+  }
+
+  let merged = stripBom(contents)
 
-    const escaped = value
-      .replace(/\\/g, '\\\\')
-      .replace(/"/g, '\\"')
-      .replace(/\n/g, '\\n')
-      .replace(/\r/g, '\\r')
+  for (const { span, line } of replacements.sort((a, b) => b.span.start - a.span.start)) {
+    merged = `${merged.slice(0, span.start)}${line}\n${merged.slice(span.end)}`
+  }
 
-    return `${key}="${escaped}"`
-  })
+  if (additions.length > 0) {
+    // A file that does not end in a newline would otherwise get the first new
+    // key welded onto its last value.
+    const separator = merged === '' || merged.endsWith('\n') ? '' : '\n'
 
-  return lines.length > 0 ? `${lines.join('\n')}\n` : ''
+    merged = `${merged}${separator}${additions.map(serializeEntry).join('\n')}\n`
+  }
+
+  return merged
 }
 
 /**

package/src/index.mjs

@@ -9,15 +9,16 @@ import { pull } from './commands/pull.mjs'
 import { push } from './commands/push.mjs'
 import { remove } from './commands/remove.mjs'
 import { status } from './commands/status.mjs'
+import { sync } from './commands/sync.mjs'
 import { DEFAULT_HOST } from './config.mjs'
 import { CLI_ALIASES, CLI_COMMAND_PAD, CLI_COMMANDS, CLI_ENV_VARS } from './manifest.mjs'
-import { CliError, errOut, out, style } from './ui.mjs'
+import { CliError, errOut, out, sanitize, style } from './ui.mjs'
 
 /**
  * Flags that take a value. Everything else is a boolean, which is what lets
  * `--force` and `--project my-app` be parsed without a schema per command.
  */
-const VALUE_FLAGS = new Set(['host', 'port', 'project', 'label', 'cwd'])
+const VALUE_FLAGS = new Set(['host', 'port', 'project', 'label', 'cwd', 'prefer'])
 
 /** Git-style `-C <dir>`: the one short flag that takes a value. */
 const SHORT_VALUE_ALIASES = { C: 'cwd' }
@@ -34,6 +35,7 @@ const HANDLERS = {
   diff,
   pull,
   push,
+  sync,
   remove,
   version: versionCommand,
 }
@@ -175,12 +177,14 @@ export async function run(argv) {
     const code = await command.run(flags, rest)
     return finish(code ?? 0)
   } catch (error) {
+    // Sanitized: an ApiError's message and a refused name both carry text the
+    // server chose, and this is where it reaches the terminal.
     if (error instanceof CliError) {
       errOut()
-      errOut(`  ${style.red('✗')} ${error.message}`)
+      errOut(`  ${style.red('✗')} ${sanitize(error.message)}`)
 
       if (error.hint) {
-        errOut(`    ${style.dim(error.hint)}`)
+        errOut(`    ${style.dim(sanitize(error.hint))}`)
       }
 
       errOut()
@@ -188,7 +192,7 @@ export async function run(argv) {
     }
 
     errOut()
-    errOut(`  ${style.red('✗')} ${error?.message ?? 'Unexpected error'}`)
+    errOut(`  ${style.red('✗')} ${sanitize(error?.message ?? 'Unexpected error')}`)
     errOut()
 
     if (process.env.ENVSTASH_DEBUG) {
@@ -269,10 +273,14 @@ function printHelp(topic) {
   out(
     `    --json             ${style.dim('Machine-readable output (status, list, whoami, version)')}`
   )
-  out(`    --exit-zero        ${style.dim('Always exit 0, even when out of sync (status, diff)')}`)
-  out(`    --dry-run          ${style.dim('Show what would happen (pull, push, remove)')}`)
   out(
-    `    --shared           ${style.dim('Target your account-wide shared files (pull, push, remove)')}`
+    `    --exit-zero        ${style.dim('Always exit 0, even when out of sync (status, diff, sync)')}`
+  )
+  out(`    --prefer <side>    ${style.dim('Resolve conflicts as "local" or "cloud" (sync)')}`)
+  out(`    --dry-run          ${style.dim('Show what would happen (pull, push, sync, remove)')}`)
+  out(`    -y, --yes          ${style.dim('Upload newly discovered files without asking (push)')}`)
+  out(
+    `    --shared           ${style.dim('Target your account-wide shared files (pull, push, sync, remove)')}`
   )
   out(`    --dev              ${style.dim('Log in to a local dev server if one is running')}`)
   out()
@@ -312,7 +320,8 @@ const COMMAND_HELP = {
   diff: [
     'Show which keys differ and what they differ to.',
     '',
-    'Values are masked by default; --show-values reveals them.',
+    'Values are masked by default — at most the first 4 characters and the',
+    'length — and --show-values reveals them.',
     '',
     'Like status, exits 1 when anything is out of sync; --exit-zero opts out.',
     '',
@@ -334,18 +343,42 @@ const COMMAND_HELP = {
     '  envs pull --force',
     '  envs pull --shared .npmrc',
   ],
+  sync: [
+    'Reconcile this repo and the cloud in both directions, in one command.',
+    '',
+    'Every file and every key that exists on one side only is copied to the',
+    'other. Nothing is ever deleted — sync does not prune in either direction —',
+    'so the worst a wrong guess costs is a key coming back, never one lost.',
+    '',
+    'A key that exists on both sides with different values is a conflict: there',
+    'is no record of the last sync, so nothing here knows which side moved. Both',
+    'copies are left untouched, the key is named, and sync exits 1. Choose a side',
+    'with --prefer local or --prefer cloud.',
+    '',
+    '  envs sync                   Merge everything both ways',
+    '  envs sync --dry-run         Show what it would do',
+    '  envs sync --prefer local    Conflicting keys: your value wins',
+    '  envs sync --prefer cloud    Conflicting keys: the cloud’s value wins',
+    '  envs sync .env.local        Just one file',
+    '  envs sync --shared .npmrc   Merge against your account-wide shared files',
+  ],
   push: [
     'Send local files to the cloud.',
     '',
     'Keys in the cloud that are absent locally are left alone unless --prune is',
     'given, so pushing a partial .env cannot delete a teammate’s key.',
     '',
+    'Files that would be new in the cloud are listed before anything uploads.',
+    'Ones found by discovery — not named, not in .envstash.json — need a yes:',
+    'asked on a terminal, --yes (-y) anywhere else.',
+    '',
     '--shared sends the named files to your account-wide shared files — for',
     'credentials that follow you across projects, like a global .npmrc. Pull',
     'them into any repo with `envs pull --shared <file>`.',
     '',
     '  envs push',
     '  envs push --dry-run',
+    '  envs push --yes             Upload newly discovered files without asking',
     '  envs push --prune',
     '  envs push --shared .npmrc',
   ],

package/src/local-write.mjs

@@ -0,0 +1,34 @@
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { writeFileAtomic } from './atomic-write.mjs'
+import { resolveRepoFile } from './repo-path.mjs'
+
+/**
+ * Write a synced file to disk, with the care every such write needs.
+ *
+ * One function rather than the same six lines in `pull` and `sync`, because
+ * each of those lines is load-bearing and a copy that quietly drops one is not
+ * obviously wrong on sight:
+ *
+ *   - The path is resolved at the sink, not only where the name entered. This
+ *     is the call that creates directories and writes bytes, so it is the one
+ *     that has to be certain the name is inside the repo and that no symlink on
+ *     the way turns "inside" into somewhere else.
+ *   - It is resolved *again* after the directories exist: the window between
+ *     the first check and the write is where a link could appear.
+ *   - The result is 0600. A synced file holds live credentials and has no
+ *     business being readable by other accounts on a shared machine.
+ *   - The write is atomic, so that holds for a file that already existed too,
+ *     and a failed write leaves the old one intact rather than a truncated one.
+ */
+export function writeSecretFile(repoRoot, name, body) {
+  const path = resolveRepoFile(repoRoot, name)
+
+  mkdirSync(dirname(path), { recursive: true })
+  resolveRepoFile(repoRoot, name)
+
+  writeFileAtomic(path, body, { mode: 0o600 })
+
+  return path
+}

package/src/manifest.mjs

@@ -27,6 +27,7 @@ export const CLI_COMMANDS = [
   { name: 'diff', summary: 'Show which keys differ, and how' },
   { name: 'pull', summary: 'Write the cloud’s version of each file to disk' },
   { name: 'push', summary: 'Send local files to the cloud' },
+  { name: 'sync', summary: 'Reconcile both directions at once, keeping every key' },
   { name: 'remove', summary: 'Delete files from the cloud (local copies stay)', aliases: ['rm'] },
   { name: 'version', summary: 'Show the CLI version and its environment' },
 ]

package/src/project.mjs

@@ -1,10 +1,10 @@
 import { execFileSync } from 'node:child_process'
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, lstatSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join, resolve, sep } from 'node:path'
 
 import { MAX_BLOB_BYTES } from './blob.mjs'
-import { isSafeRepoPath, keepSafeRepoPaths } from './repo-path.mjs'
-import { CliError } from './ui.mjs'
+import { findSymlink, isSafeRepoPath, keepSafeRepoPaths } from './repo-path.mjs'
+import { CliError, sanitize } from './ui.mjs'
 
 /** The per-repo link file. Safe to commit — it names files, never values. */
 export const LINK_FILE = '.envstash.json'
@@ -98,7 +98,8 @@ export function readLink(repoRoot) {
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf8'))
     return {
-      project: typeof parsed.project === 'string' ? parsed.project : null,
+      // Printed in every command's header, and it came with someone else's repo.
+      project: typeof parsed.project === 'string' ? sanitize(parsed.project) : null,
       host: typeof parsed.host === 'string' ? parsed.host : null,
       // A link file arrives with a cloned repo, so its file list is untrusted
       // input. Names that would escape the repo are dropped at the door rather
@@ -113,7 +114,9 @@ export function readLink(repoRoot) {
 }
 
 export function writeLink(repoRoot, link) {
-  const path = join(repoRoot, LINK_FILE)
+  // Not `join`: a cloned repo's `.envstash.json` can be a link to a file outside
+  // it, and init would then overwrite whatever that is.
+  const path = assertRegularTarget(repoRoot, LINK_FILE)
   const body = {
     project: link.project,
     files: link.files,
@@ -125,6 +128,19 @@ export function writeLink(repoRoot, link) {
   return path
 }
 
+/** Same refusal as the sync commands, for the two files the CLI writes itself. */
+function assertRegularTarget(repoRoot, name) {
+  const link = findSymlink(repoRoot, name)
+
+  if (link) {
+    throw new CliError(`Refusing to write ${name} through a symbolic link.`, {
+      hint: `${name} in this repo points somewhere else. Replace it with a real file.`,
+    })
+  }
+
+  return join(repoRoot, name)
+}
+
 /**
  * Best guess at a project name: the git remote's repo name, falling back to the
  * directory name. Matching the repo name is what makes `envs pull` work on a
@@ -170,7 +186,9 @@ export function discoverEnvFiles(repoRoot) {
     .filter(name => !name.endsWith('.d.ts'))
     .filter(name => {
       try {
-        return statSync(join(repoRoot, name)).isFile()
+        // lstat, not stat: a `.env.local` that is a link to `~/.ssh/id_rsa` is a
+        // link, not a file, and discovery must not offer it for upload.
+        return lstatSync(join(repoRoot, name)).isFile()
       } catch {
         return false
       }
@@ -266,7 +284,13 @@ export function discoverSecretFiles(repoRoot) {
     .filter(name => isSafeRepoPath(name))
     .filter(name => {
       try {
-        const stats = statSync(join(repoRoot, name))
+        // A link anywhere on the path — `.config` itself, a subdirectory, or the
+        // file — could point outside the repo, so it is not offered.
+        if (findSymlink(repoRoot, name)) {
+          return false
+        }
+
+        const stats = lstatSync(join(repoRoot, name))
         // Skipping oversized files here means `envs init` never lists something
         // whose first push would fail.
         return stats.isFile() && stats.size <= MAX_BLOB_BYTES
@@ -330,6 +354,13 @@ export function ensureSecretDirIgnored(repoRoot) {
     return false
   }
 
+  // A .gitignore that is a link points outside the repo, or is shared with other
+  // repos; either way it is not this CLI's file to append to. Leaving `.config/`
+  // unignored only means discovery finds nothing there, the conservative side.
+  if (findSymlink(repoRoot, '.gitignore')) {
+    return false
+  }
+
   const path = join(repoRoot, '.gitignore')
   let existing = ''
 

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)