envstash-cli 0.1.0

package/src/project.mjs

@@ -0,0 +1,159 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+
+import { keepSafeRepoPaths } from './repo-path.mjs'
+import { CliError } from './ui.mjs'
+
+/** The per-repo link file. Safe to commit — it names files, never values. */
+export const LINK_FILE = '.envstash.json'
+
+/**
+ * Files that look like `.env` but are meant to be committed and contain no real
+ * secrets. Auto-including them would push placeholder values over the top of a
+ * teammate's real ones.
+ */
+const TEMPLATE_SUFFIXES = ['.example', '.sample', '.template', '.dist']
+
+/**
+ * Walk up from `startDir` looking for a repo root.
+ *
+ * The link file is checked before `.git` so a nested package inside a monorepo
+ * can own its own project; falling back to `.git` then `package.json` covers the
+ * ordinary single-repo case.
+ */
+export function findRepoRoot(startDir = process.cwd()) {
+  let current = resolve(startDir)
+
+  for (const marker of [LINK_FILE, '.git', 'package.json']) {
+    let cursor = current
+
+    while (true) {
+      if (existsSync(join(cursor, marker))) {
+        return cursor
+      }
+
+      const parent = dirname(cursor)
+
+      if (parent === cursor) {
+        break
+      }
+
+      cursor = parent
+    }
+  }
+
+  return current
+}
+
+export function readLink(repoRoot) {
+  const path = join(repoRoot, LINK_FILE)
+
+  if (!existsSync(path)) {
+    return null
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return {
+      project: typeof parsed.project === 'string' ? 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
+      // than carried around and rejected later.
+      files: Array.isArray(parsed.files) ? keepSafeRepoPaths(parsed.files) : [],
+    }
+  } catch {
+    throw new CliError(`${path} is not valid JSON.`, {
+      hint: 'Fix it by hand, or delete it and run `envs init`.',
+    })
+  }
+}
+
+export function writeLink(repoRoot, link) {
+  const path = join(repoRoot, LINK_FILE)
+  const body = {
+    project: link.project,
+    files: link.files,
+    ...(link.host ? { host: link.host } : {}),
+  }
+
+  writeFileSync(path, `${JSON.stringify(body, null, 2)}\n`)
+
+  return path
+}
+
+/**
+ * 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
+ * fresh clone with no configuration.
+ */
+export function guessProjectName(repoRoot) {
+  try {
+    const remote = execFileSync('git', ['config', '--get', 'remote.origin.url'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+
+    if (remote) {
+      const name = basename(remote.replace(/\.git$/, ''))
+
+      if (name) {
+        return name
+      }
+    }
+  } catch {
+    // No git, no remote, or git not installed — fall through to the directory.
+  }
+
+  return basename(repoRoot)
+}
+
+/**
+ * Discover `.env*` files in the repo root.
+ *
+ * Deliberately not recursive: walking a whole tree would wander into
+ * node_modules and vendored fixtures, and a monorepo's nested files are better
+ * declared explicitly in the link file than guessed at.
+ */
+export function discoverEnvFiles(repoRoot) {
+  let names
+
+  try {
+    names = readdirSync(repoRoot)
+  } catch {
+    return []
+  }
+
+  return names
+    .filter(name => name === '.env' || name.startsWith('.env.'))
+    .filter(name => !TEMPLATE_SUFFIXES.some(suffix => name.endsWith(suffix)))
+    .filter(name => !name.endsWith('.d.ts'))
+    .filter(name => {
+      try {
+        return statSync(join(repoRoot, name)).isFile()
+      } catch {
+        return false
+      }
+    })
+    .sort()
+}
+
+/**
+ * Resolve which project this invocation targets: `--project` wins, then the link
+ * file, then the repo-name guess.
+ */
+export function resolveProject(repoRoot, flagProject) {
+  if (flagProject) {
+    return { name: flagProject, source: 'flag' }
+  }
+
+  const link = readLink(repoRoot)
+
+  if (link?.project) {
+    return { name: link.project, source: 'link' }
+  }
+
+  return { name: guessProjectName(repoRoot), source: 'guess' }
+}

package/src/repo-path.mjs

@@ -0,0 +1,78 @@
+import { isAbsolute, relative, resolve } from 'node:path'
+
+import { CliError } from './ui.mjs'
+
+/**
+ * The one place the CLI decides whether a file name may touch the disk.
+ *
+ * Every name the sync commands handle arrives from somewhere the developer did
+ * not type: the server's status response, or a `.envstash.json` that came with a
+ * cloned repo. Both were previously joined to the repo root and read or written
+ * unchecked, so either could reach `../../.ssh/authorized_keys`.
+ *
+ * The server has always validated names on the way in — `isValidFileName` in
+ * src/lib/secrets/store.ts, whose comment names this exact attack. But that
+ * check protects the server's data, not the developer's machine, and it says
+ * nothing about what a *different* server returns. This is the same rule on the
+ * side of the trust boundary that owns the filesystem.
+ *
+ * Deliberately identical to the server's grammar, so nothing legitimately
+ * stored can be rejected here: POSIX-relative, and every segment drawn from
+ * `[A-Za-z0-9._-]`.
+ */
+const SEGMENT = /^[A-Za-z0-9._-]+$/
+
+const MAX_LENGTH = 255
+
+export function isSafeRepoPath(name) {
+  if (typeof name !== 'string' || name === '' || name.length > MAX_LENGTH) {
+    return false
+  }
+
+  // Backslash before anything else: on Windows it separates paths, and `..\..`
+  // traverses just as well as `../..` while containing no forward slash at all.
+  if (name.includes('\\') || name.includes('\0') || isAbsolute(name)) {
+    return false
+  }
+
+  return name
+    .split('/')
+    .every(
+      segment => segment !== '' && segment !== '.' && segment !== '..' && SEGMENT.test(segment)
+    )
+}
+
+/**
+ * Resolve `name` under `repoRoot`, or refuse.
+ *
+ * Checked twice on purpose. The grammar above rejects the names an attacker
+ * would choose; the containment check below is what still holds if the grammar
+ * is ever loosened, because it compares resolved paths rather than trusting a
+ * pattern.
+ */
+export function resolveInsideRepo(repoRoot, name) {
+  if (!isSafeRepoPath(name)) {
+    throw refuse(name)
+  }
+
+  const root = resolve(repoRoot)
+  const target = resolve(root, name)
+  const inside = relative(root, target)
+
+  if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) {
+    throw refuse(name)
+  }
+
+  return target
+}
+
+/** 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) {
+  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

@@ -0,0 +1,92 @@
+import { requireToken, resolveHost } from './config.mjs'
+import { detectDevHost, isDevMode } from './dev-host.mjs'
+import { findRepoRoot, readLink } from './project.mjs'
+
+/**
+ * Resolve host and token together.
+ *
+ * A repo's link file may pin a host, which is what lets one machine work against
+ * a self-hosted or local instance for one project and production for another.
+ * The `--host` flag and `ENVSTASH_HOST` still override it.
+ */
+export function requireHostToken(flags) {
+  const { host, source } = resolveHostSource(flags)
+
+  // A host the repo chose does not get to spend a credential the developer
+  // supplied. Stored tokens are keyed by host and so are already safe; this is
+  // what stops ENVSTASH_TOKEN from following a cloned repo to its own server.
+  return { host, token: requireToken(host, { allowEnvToken: source !== 'link' }) }
+}
+
+/**
+ * Resolve the host and say where the decision came from.
+ *
+ * The source matters as much as the value: `flag` and `env` are the developer
+ * speaking, `default` is a host they signed in to on purpose, and `link` is a
+ * file that arrived with somebody else's repo. Callers treat the last one with
+ * less trust.
+ */
+export function resolveHostSource(flags) {
+  if (flags?.host || process.env.ENVSTASH_HOST) {
+    return { host: resolveHost(flags?.host), source: flags?.host ? 'flag' : 'env' }
+  }
+
+  try {
+    const link = readLink(findRepoRoot())
+
+    if (link?.host) {
+      return { host: resolveHost(link.host), source: 'link' }
+    }
+  } catch {
+    // A malformed link file is reported by the commands that actually read it.
+  }
+
+  return { host: resolveHost(undefined), source: 'default' }
+}
+
+export function resolveHostFor(flags) {
+  return resolveHostSource(flags).host
+}
+
+/**
+ * True when `host` is the one this repo's link file asked for.
+ *
+ * Compared against the resolved host rather than read straight from the link,
+ * so a host that dev-mode detection or a flag settled on is correctly reported
+ * as the developer's choice even when a link file also names one.
+ */
+export function isLinkChosenHost(flags, host) {
+  const resolved = resolveHostSource(flags)
+
+  return resolved.source === 'link' && resolved.host === host
+}
+
+/**
+ * Host for an interactive login.
+ *
+ * The usual precedence with one step inserted: in dev mode a running local
+ * server beats the stored default, so `pnpm cli:dev login` opens the server the
+ * developer is running. An explicit `--host` or `ENVSTASH_HOST` still wins over
+ * detection — asking for a specific server should never be second-guessed — and
+ * production remains the last resort when no dev server answers.
+ *
+ * `onDevHost` reports what detection found so the command can say so. Deciding
+ * and printing are split because the decision is what the tests care about.
+ */
+export async function resolveLoginHost(flags, { onDevHost } = {}) {
+  if (flags?.host || process.env.ENVSTASH_HOST) {
+    return resolveHost(flags?.host)
+  }
+
+  if (isDevMode(flags)) {
+    const devHost = await detectDevHost()
+
+    onDevHost?.(devHost)
+
+    if (devHost) {
+      return devHost
+    }
+  }
+
+  return resolveHostFor(flags)
+}

package/src/status.mjs

@@ -0,0 +1,152 @@
+import { digestValue } from './env-file.mjs'
+
+/**
+ * Per-key verdicts.
+ *
+ * `local_only` and `cloud_only` are deliberately not called "added" and
+ * "deleted". Without a record of the last sync there is no way to know which
+ * side moved: a key present only locally is either one you just added or one a
+ * teammate removed. Naming the observation instead of inventing an intent keeps
+ * `envs status` from lying.
+ */
+export const KEY_STATE = {
+  SAME: 'same',
+  MODIFIED: 'modified',
+  LOCAL_ONLY: 'local_only',
+  CLOUD_ONLY: 'cloud_only',
+}
+
+export const FILE_STATE = {
+  IN_SYNC: 'in_sync',
+  DIFFERS: 'differs',
+  /** Exists in the cloud, absent on disk — `envs pull` would create it. */
+  CLOUD_ONLY: 'cloud_only',
+  /** Exists on disk, absent from the cloud — `envs push` would create it. */
+  UNTRACKED: 'untracked',
+}
+
+/**
+ * Compare one file's local entries against the cloud's key digests.
+ *
+ * `localEntries` is null when the file does not exist on disk; `cloudKeys` is
+ * null when the cloud has no such file.
+ */
+export function compareFile(name, localEntries, cloudKeys) {
+  if (localEntries === null && cloudKeys === null) {
+    return null
+  }
+
+  const keys = []
+  const localMap = new Map((localEntries ?? []).map(entry => [entry.key, entry.value]))
+  const cloudMap = new Map((cloudKeys ?? []).map(entry => [entry.key, entry.digest]))
+
+  for (const [key, value] of localMap) {
+    const cloudDigest = cloudMap.get(key)
+
+    if (cloudDigest === undefined) {
+      keys.push({ key, state: KEY_STATE.LOCAL_ONLY })
+      continue
+    }
+
+    keys.push({
+      key,
+      state: digestValue(value) === cloudDigest ? KEY_STATE.SAME : KEY_STATE.MODIFIED,
+    })
+  }
+
+  for (const key of cloudMap.keys()) {
+    if (!localMap.has(key)) {
+      keys.push({ key, state: KEY_STATE.CLOUD_ONLY })
+    }
+  }
+
+  keys.sort((a, b) => a.key.localeCompare(b.key))
+
+  const counts = countStates(keys)
+
+  return { name, state: fileState(localEntries, cloudKeys, counts), keys, counts }
+}
+
+function countStates(keys) {
+  const counts = { same: 0, modified: 0, local_only: 0, cloud_only: 0 }
+
+  for (const entry of keys) {
+    counts[entry.state] += 1
+  }
+
+  return counts
+}
+
+function fileState(localEntries, cloudKeys, counts) {
+  if (cloudKeys === null) {
+    return FILE_STATE.UNTRACKED
+  }
+
+  if (localEntries === null) {
+    return FILE_STATE.CLOUD_ONLY
+  }
+
+  const drifted = counts.modified + counts.local_only + counts.cloud_only
+
+  return drifted === 0 ? FILE_STATE.IN_SYNC : FILE_STATE.DIFFERS
+}
+
+/**
+ * Compare a whole project.
+ *
+ * The file set is the union of what the cloud knows about and what is on disk,
+ * so a file that exists on only one side still shows up — that is precisely the
+ * case a developer needs to be told about.
+ */
+export function compareProject({ cloudFiles, localFiles }) {
+  const names = new Set([...cloudFiles.map(file => file.name), ...localFiles.keys()])
+
+  const files = []
+
+  for (const name of [...names].sort()) {
+    const cloud = cloudFiles.find(file => file.name === name)
+    const comparison = compareFile(name, localFiles.get(name) ?? null, cloud?.keys ?? null)
+
+    if (comparison) {
+      files.push(comparison)
+    }
+  }
+
+  return files
+}
+
+/** True when anything at all is out of sync. */
+export function isOutOfSync(files) {
+  return files.some(file => file.state !== FILE_STATE.IN_SYNC)
+}
+
+/**
+ * Exit code for the read-only commands: 1 when anything is out of sync.
+ *
+ * This diverges from `git status`, which always exits 0 and makes signalling
+ * opt-in via `git diff --exit-code`. Drift in a secrets store is a condition you
+ * almost always want a hook or a CI job to catch, so it fails by default and
+ * `--exit-zero` opts out for scripts running under `set -e`.
+ *
+ * `--exit-code` is still accepted, and is now a no-op that names the default.
+ */
+export function driftExitCode(flags, files) {
+  if (flags['exit-zero'] || flags['no-exit-code']) {
+    return 0
+  }
+
+  return isOutOfSync(files) ? 1 : 0
+}
+
+export function summarize(files) {
+  const totals = { files: files.length, modified: 0, local_only: 0, cloud_only: 0, same: 0 }
+
+  for (const file of files) {
+    totals.modified += file.counts.modified
+    totals.local_only += file.counts.local_only
+    totals.cloud_only += file.counts.cloud_only
+    totals.same += file.counts.same
+  }
+
+  return totals
+}

package/src/ui.mjs

@@ -0,0 +1,82 @@
+/**
+ * Terminal output helpers.
+ *
+ * Colour is opt-out via NO_COLOR and opt-in via FORCE_COLOR, and is disabled
+ * whenever stdout is not a TTY — so `envs status > report.txt` and CI logs get
+ * clean text instead of escape sequences.
+ */
+const colorEnabled = (() => {
+  if (process.env.NO_COLOR) {
+    return false
+  }
+
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0') {
+    return true
+  }
+
+  return Boolean(process.stdout.isTTY) && process.env.TERM !== 'dumb'
+})()
+
+function wrap(open, close) {
+  return text => (colorEnabled ? `\u001b[${open}m${text}\u001b[${close}m` : String(text))
+}
+
+export const style = {
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  blue: wrap(34, 39),
+  magenta: wrap(35, 39),
+  cyan: wrap(36, 39),
+}
+
+export function out(message = '') {
+  process.stdout.write(`${message}\n`)
+}
+
+export function errOut(message = '') {
+  process.stderr.write(`${message}\n`)
+}
+
+/** A recoverable, already-explained failure. `run` prints these without a stack. */
+export class CliError extends Error {
+  constructor(message, { hint, exitCode = 1 } = {}) {
+    super(message)
+    this.name = 'CliError'
+    this.hint = hint
+    this.exitCode = exitCode
+  }
+}
+
+export function fail(message, options) {
+  throw new CliError(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.
+ */
+export function maskValue(value) {
+  if (value === '') {
+    return style.dim('(empty)')
+  }
+
+  if (value.length <= 12) {
+    return style.dim('•'.repeat(8))
+  }
+
+  return `${value.slice(0, 4)}${style.dim('•'.repeat(8))}${value.slice(-4)}`
+}
+
+/** Pad to a display width, ignoring colour codes. */
+export function pad(text, width) {
+  const visibleLength = String(text).replace(/\u001b\[\d+m/g, '').length
+  return `${text}${' '.repeat(Math.max(0, width - visibleLength))}`
+}
+
+export function pluralize(count, singular, plural = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : plural}`
+}