envstash-cli 0.1.0

package/src/commands/login.mjs

@@ -0,0 +1,286 @@
+import { execFile } from 'node:child_process'
+import { hostname, userInfo } from 'node:os'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+import { api } from '../api.mjs'
+import {
+  clearAllCredentials,
+  clearToken,
+  getStoredEmail,
+  getToken,
+  isKnownHost,
+  readConfig,
+  saveToken,
+} from '../config.mjs'
+import { DEV_PORTS } from '../dev-host.mjs'
+import { isLinkChosenHost, resolveHostFor, resolveLoginHost } from '../session.mjs'
+import { CliError, out, style } from '../ui.mjs'
+
+/**
+ * `envs login` — the OAuth device flow.
+ *
+ * The CLI never handles a password or an OAuth callback: it asks the server for
+ * a code, the human approves that code in an already-authenticated browser, and
+ * the CLI polls until a token appears. That means no local web server on a
+ * random port and no redirect URI to register, so it works identically over SSH
+ * and inside a container where no browser can be opened at all.
+ */
+export async function login(flags) {
+  // Printed before the code and the link, so the host is on screen before the
+  // browser opens rather than only in the success line afterwards.
+  const host = await resolveLoginHost(flags, {
+    onDevHost: devHost => {
+      out()
+      out(
+        devHost
+          ? `  ${style.dim('Dev server:')} ${style.bold(devHost)}`
+          : `  ${style.dim(`No dev server on ${DEV_PORTS.join(', ')} — using production.`)}`
+      )
+    },
+  })
+
+  const fromLink = isLinkChosenHost(flags, host)
+
+  assertLoginHostIsTrusted(host, fromLink)
+
+  const label = flags.label ?? defaultLabel()
+
+  const started = await api.startDeviceAuth(host, label)
+  // The server picks this URL and the CLI is about to hand it to the operating
+  // system, so it is checked before it is shown or opened rather than after.
+  const verificationUrl = safeVerificationUrl(started.verificationUrlComplete, host)
+
+  out()
+  out(`  Your code:  ${style.bold(style.cyan(started.userCode))}`)
+  out()
+  out(`  ${style.dim('Open')} ${style.blue(verificationUrl ?? `${host}/cli`)}`)
+  out()
+
+  if (!verificationUrl) {
+    out(`  ${style.yellow('!')} ${style.dim(`${host} returned a link pointing somewhere else.`)}`)
+    out(`  ${style.dim('Enter the code above by hand instead.')}`)
+    out()
+  }
+
+  const opened =
+    flags['no-browser'] || !verificationUrl ? false : await openBrowser(verificationUrl)
+
+  if (!opened && !flags['no-browser'] && verificationUrl) {
+    out(`  ${style.dim('Could not open a browser — visit the link above.')}`)
+    out()
+  }
+
+  // On a TTY the waiting line is erased once approval lands. When stdout is
+  // redirected there is no cursor to move, so print a plain line instead —
+  // otherwise the escape sequence lands in the log as a literal "[K".
+  const interactive = Boolean(process.stdout.isTTY)
+
+  if (interactive) {
+    process.stdout.write(`  ${style.dim('Waiting for approval…')}`)
+  } else {
+    out('  Waiting for approval…')
+  }
+
+  const token = await pollForToken(host, started)
+
+  if (interactive) {
+    process.stdout.write('\r\u001b[K')
+  }
+
+  const who = await api.whoami(host, token)
+  // A host this repo chose is not promoted to the machine-wide default. That
+  // promotion is what previously turned one hostile repo into every later
+  // command in every other repo talking to it.
+  saveToken(host, token, who.email, { makeDefault: !fromLink })
+
+  out(`  ${style.green('✓')} Signed in to ${style.bold(host)} as ${style.bold(who.email)}`)
+  out()
+
+  return 0
+}
+
+/**
+ * Poll until the browser decides. `pending` is the expected answer for most of
+ * this loop; anything else is terminal and `request` has already turned it into
+ * a CliError with the server's own wording.
+ */
+async function pollForToken(host, started) {
+  const intervalMs = Math.max(1, started.intervalSeconds ?? 2) * 1000
+  const deadline = new Date(started.expiresAt).getTime()
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs)
+
+    const result = await api.pollDeviceAuth(host, started.deviceCode)
+
+    if (result.status === 'approved' && result.token) {
+      return result.token
+    }
+  }
+
+  throw new CliError('That login code expired before it was approved.', {
+    hint: 'Run `envs login` again.',
+  })
+}
+
+/** Name the device so the approval screen and the token list are recognisable. */
+function defaultLabel() {
+  try {
+    return `${userInfo().username}@${hostname()}`
+  } catch {
+    return 'unknown device'
+  }
+}
+
+/**
+ * Refuse to sign in to a host that only a cloned repo asked for.
+ *
+ * A link file is committed so a teammate can clone and sync with no setup, and
+ * that is worth keeping — but it means the host can come from a file the
+ * developer never wrote. Signing in is the one moment where that matters most,
+ * because it is the moment a fresh credential is created. Refusing rather than
+ * prompting keeps this working the same way in CI and in a terminal, and fails
+ * closed either way. A host already in the config has been agreed to before, so
+ * it goes through untouched.
+ */
+function assertLoginHostIsTrusted(host, fromLink) {
+  if (!fromLink || isKnownHost(host)) {
+    return
+  }
+
+  throw new CliError(`.envstash.json in this repo points at ${host}.`, {
+    hint: `You have not signed in there before. If you trust it, run: envs login --host ${host}`,
+  })
+}
+
+/**
+ * The verification link, if the server is entitled to send it.
+ *
+ * Requires http/https and the same origin the CLI dialled. The honest server
+ * builds this URL from the incoming request, so a legitimate response always
+ * matches; a mismatch means the answer came from somewhere that wants the
+ * browser pointed elsewhere. Returning null rather than throwing keeps a login
+ * usable — the code is on screen and can be typed in by hand.
+ */
+export function safeVerificationUrl(raw, host) {
+  try {
+    const url = new URL(String(raw))
+
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+      return null
+    }
+
+    return url.origin === new URL(host).origin ? url.toString() : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Open a URL in the user's browser, resolving false when that is not possible —
+ * over SSH, in Docker, in CI. The link is always printed first, so a failure
+ * here costs the user a copy-paste, not the login.
+ */
+const OPEN_TIMEOUT_MS = 2000
+
+function openBrowser(url) {
+  const command =
+    process.platform === 'darwin'
+      ? { file: 'open', args: [url] }
+      : process.platform === 'win32'
+        ? // Not `cmd /c start`: cmd re-parses the command line it is given, and
+          // Node only quotes arguments containing a space, so a URL carrying an
+          // `&` would split into a second command. rundll32 takes the URL as a
+          // plain argument and no shell ever sees it.
+          { file: 'rundll32', args: ['url.dll,FileProtocolHandler', url] }
+        : { file: 'xdg-open', args: [url] }
+
+  return new Promise(resolve => {
+    let child = null
+    let settled = false
+    let timer = null
+
+    const settle = opened => {
+      if (settled) {
+        return
+      }
+
+      settled = true
+      clearTimeout(timer)
+
+      // Detach only once this promise has settled. Unref-ing a child we are
+      // still awaiting lets the event loop empty while the await is pending,
+      // and Node exits with status 13 and no message — `envs login` dying
+      // silently before it ever printed "Waiting for approval".
+      child?.unref?.()
+      resolve(opened)
+    }
+
+    try {
+      child = execFile(command.file, command.args, { stdio: 'ignore' }, error => settle(!error))
+      child.on('error', () => settle(false))
+    } catch {
+      settle(false)
+      return
+    }
+
+    // Some openers do not return until the browser itself is closed. Once the
+    // URL has been handed over, that counts as opened: waiting for a window to
+    // be closed would stall the login behind it forever.
+    timer = setTimeout(() => settle(true), OPEN_TIMEOUT_MS)
+  })
+}
+
+/** `envs logout` lives here too — it is the other half of the same credential. */
+export async function logout(flags) {
+  const host = resolveHostFor(flags)
+
+  if (flags.all) {
+    // Revoke every host before deleting anything. Revocation needs the raw
+    // token, and these are the only copies of them — clearing first left the
+    // tokens live for good with no way to reach them, while telling the user
+    // they had signed out everywhere.
+    for (const [storedHost, entry] of Object.entries(readConfig().hosts)) {
+      if (!entry?.token) {
+        continue
+      }
+
+      try {
+        await api.logout(storedHost, entry.token)
+      } catch {
+        out(
+          `  ${style.yellow('!')} Could not reach ${storedHost} to revoke its token; removing it locally.`
+        )
+      }
+    }
+
+    const removed = clearAllCredentials()
+    out(removed ? `  ${style.green('✓')} Removed all stored credentials.` : '  Nothing to remove.')
+    return 0
+  }
+
+  const token = getToken(host)
+
+  // Revoke server-side first. A local delete alone leaves a live token that
+  // still works for anyone who copied the config file.
+  if (token) {
+    try {
+      await api.logout(host, token)
+    } catch {
+      out(
+        `  ${style.yellow('!')} Could not reach ${host} to revoke the token; removing it locally.`
+      )
+    }
+  }
+
+  const email = getStoredEmail(host)
+  const removed = clearToken(host)
+
+  out(
+    removed
+      ? `  ${style.green('✓')} Signed out of ${host}${email ? ` (${email})` : ''}.`
+      : `  Not signed in to ${host}.`
+  )
+
+  return 0
+}

package/src/commands/misc.mjs

@@ -0,0 +1,149 @@
+import { api } from '../api.mjs'
+import { getStoredEmail } from '../config.mjs'
+import { discoverEnvFiles, findRepoRoot, readLink, resolveProject, writeLink } from '../project.mjs'
+import { requireHostToken, resolveHostFor } from '../session.mjs'
+import { out, pad, pluralize, style } from '../ui.mjs'
+
+/** `envs whoami` — which account this machine is signed in as. */
+export async function whoami(flags) {
+  const { host, token } = requireHostToken(flags)
+  const who = await api.whoami(host, token)
+
+  if (flags.json) {
+    out(JSON.stringify({ host, ...who }, null, 2))
+    return 0
+  }
+
+  out()
+  out(`  ${style.bold(who.email)}${who.name ? style.dim(` (${who.name})`) : ''}`)
+  out(`  ${style.dim(host)}`)
+  out()
+
+  return 0
+}
+
+/** `envs list` — every project in the account. */
+export async function list(flags) {
+  const { host, token } = requireHostToken(flags)
+  const { projects } = await api.listProjects(host, token)
+
+  if (flags.json) {
+    out(JSON.stringify(projects, null, 2))
+    return 0
+  }
+
+  out()
+
+  if (!projects || projects.length === 0) {
+    out(`  ${style.dim('No projects yet. Run')} envs init ${style.dim('in a repo to create one.')}`)
+    out()
+    return 0
+  }
+
+  const width = Math.max(...projects.map(project => project.name.length)) + 4
+
+  for (const project of projects) {
+    out(
+      `  ${pad(style.bold(project.name), width)}${style.dim(
+        `${pluralize(project.fileCount, 'file')}, ${pluralize(project.secretCount, 'key')}`
+      )}`
+    )
+  }
+
+  out()
+
+  return 0
+}
+
+/**
+ * `envs init` — create the project and write the link file.
+ *
+ * The link file is committed, which is the point: a teammate cloning the repo
+ * gets the project name and file list for free and only has to run `envs pull`.
+ */
+export async function init(flags, args) {
+  const { host, token } = requireHostToken(flags)
+  const repoRoot = findRepoRoot()
+  const existing = readLink(repoRoot)
+  const name = args[0] ?? flags.project ?? resolveProject(repoRoot, undefined).name
+
+  await api.createProject(host, token, name)
+
+  const files = existing?.files?.length ? existing.files : discoverEnvFiles(repoRoot)
+  const path = writeLink(repoRoot, {
+    project: name,
+    files,
+    host: flags.host ? resolveHostFor(flags) : (existing?.host ?? null),
+  })
+
+  out()
+  out(`  ${style.green('✓')} Project ${style.bold(name)} ready on ${style.dim(host)}`)
+  out(`  ${style.dim('Wrote')} ${path.replace(`${repoRoot}/`, '')}`)
+
+  if (files.length > 0) {
+    out()
+    out(`  ${style.dim('Tracking:')}`)
+    for (const file of files) {
+      out(`    ${style.dim('·')} ${file}`)
+    }
+  } else {
+    out()
+    out(`  ${style.dim('No .env files found yet. Create one, then run')} envs push`)
+  }
+
+  out()
+  out(`  ${style.dim('Next:')} envs push`)
+  out()
+
+  return 0
+}
+
+/**
+ * `envs link` — point this repo at an existing project without creating one.
+ * The counterpart to `init` for a repo whose secrets are already in the cloud.
+ */
+export async function link(flags, args) {
+  const { host, token } = requireHostToken(flags)
+  const repoRoot = findRepoRoot()
+  const existing = readLink(repoRoot)
+  const name = args[0] ?? flags.project
+
+  if (!name) {
+    const { projects } = await api.listProjects(host, token)
+
+    out()
+    out(`  ${style.dim('Usage:')} envs link <project>`)
+    out()
+
+    if (projects?.length) {
+      out(`  ${style.dim('Available projects:')}`)
+      for (const project of projects) {
+        out(`    ${style.dim('·')} ${project.name}`)
+      }
+      out()
+    }
+
+    return 1
+  }
+
+  // Fails loudly if the project does not exist, rather than writing a link file
+  // that points at nothing.
+  await api.projectStatus(host, token, name)
+
+  const files = existing?.files?.length ? existing.files : discoverEnvFiles(repoRoot)
+  const path = writeLink(repoRoot, { project: name, files, host: existing?.host ?? null })
+
+  out()
+  out(`  ${style.green('✓')} Linked to ${style.bold(name)}`)
+  out(`  ${style.dim('Wrote')} ${path.replace(`${repoRoot}/`, '')}`)
+  out()
+  out(`  ${style.dim('Next:')} envs pull`)
+  out()
+
+  return 0
+}
+
+/** Shown by `envs` with no arguments when a credential already exists. */
+export function storedEmailFor(flags) {
+  return getStoredEmail(resolveHostFor(flags))
+}

package/src/commands/pull.mjs

@@ -0,0 +1,123 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { api, ApiError } from '../api.mjs'
+import { loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import { serializeEnv } from '../env-file.mjs'
+import { resolveInsideRepo } from '../repo-path.mjs'
+import { compareProject, FILE_STATE } from '../status.mjs'
+import { CliError, out, pluralize, style } from '../ui.mjs'
+
+/**
+ * `envs pull` — write the cloud's version of each file to disk.
+ *
+ * A file with local changes is skipped, not overwritten. Pulling is the command
+ * most likely to be run reflexively on a new machine, and silently replacing an
+ * uncommitted `.env` destroys work that exists nowhere else — `.env` files are
+ * git-ignored by definition, so there is no undo.
+ */
+export async function pull(flags, args) {
+  const context = resolveContext(flags)
+
+  let cloudFiles
+
+  try {
+    const response = await api.projectStatus(context.host, context.token, context.project.name)
+    cloudFiles = response.files ?? []
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      throw new CliError(`No project named "${context.project.name}" in your account.`, {
+        hint: 'Run `envs init` to create it, or pass --project to target another one.',
+      })
+    }
+
+    throw error
+  }
+
+  const names = resolveFileNames({
+    repoRoot: context.repoRoot,
+    link: context.link,
+    cloudFiles,
+    requested: args,
+  }).filter(name => cloudFiles.some(file => file.name === name))
+
+  if (names.length === 0) {
+    out()
+    out(
+      `  ${style.dim('Nothing to pull —')} ${style.bold(context.project.name)} ${style.dim('has no files in the cloud.')}`
+    )
+    out()
+    return 0
+  }
+
+  const localFiles = loadLocalFiles(context.repoRoot, names)
+  const comparison = compareProject({
+    cloudFiles: cloudFiles.filter(file => names.includes(file.name)),
+    localFiles,
+  })
+
+  out()
+
+  let written = 0
+  let skipped = 0
+
+  for (const file of comparison) {
+    const hasLocalWork = file.counts.modified > 0 || file.counts.local_only > 0
+
+    if (file.state === FILE_STATE.IN_SYNC) {
+      out(`  ${style.dim('=')} ${file.name} ${style.dim('already up to date')}`)
+      continue
+    }
+
+    if (hasLocalWork && !flags.force) {
+      skipped += 1
+      out(
+        `  ${style.yellow('!')} ${file.name} ${style.dim(
+          `has local changes (${file.counts.modified} changed, ${file.counts.local_only} local-only) — skipped`
+        )}`
+      )
+      continue
+    }
+
+    const response = await api.getFile(context.host, context.token, context.project.name, file.name)
+    const body = serializeEnv(response.entries ?? [])
+    // Re-checked 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 path is inside the repo.
+    const path = resolveInsideRepo(context.repoRoot, file.name)
+
+    if (flags['dry-run']) {
+      out(
+        `  ${style.dim('would write')} ${file.name} ${style.dim(`(${pluralize(response.entries?.length ?? 0, 'key')})`)}`
+      )
+      continue
+    }
+
+    mkdirSync(dirname(path), { recursive: true })
+    // 0600: a pulled .env holds live credentials and has no business being
+    // readable by other accounts on a shared machine.
+    writeFileSync(path, body, { mode: 0o600 })
+    written += 1
+
+    out(
+      `  ${style.green('✓')} ${file.name} ${style.dim(`(${pluralize(response.entries?.length ?? 0, 'key')})`)}`
+    )
+  }
+
+  out()
+
+  if (skipped > 0) {
+    out(
+      `  ${style.dim('Skipped')} ${pluralize(skipped, 'file')} ${style.dim('with local changes.')}`
+    )
+    out(
+      `  ${style.dim('Review with')} envs diff${style.dim(', then')} envs pull --force ${style.dim('to overwrite.')}`
+    )
+    out()
+  } else if (!flags['dry-run'] && written > 0) {
+    out(`  ${style.dim(`Wrote ${pluralize(written, 'file')}.`)}`)
+    out()
+  }
+
+  return 0
+}

package/src/commands/push.mjs

@@ -0,0 +1,125 @@
+import { api, ApiError } from '../api.mjs'
+import { loadLocalFiles, resolveContext, resolveFileNames } from '../context.mjs'
+import { compareProject, FILE_STATE } from '../status.mjs'
+import { CliError, out, pluralize, style } from '../ui.mjs'
+
+/**
+ * `envs push` — send local files up.
+ *
+ * Keys present in the cloud but absent locally are left alone unless `--prune`
+ * is passed. Pushing a partial `.env` is normal — a developer working on one
+ * feature often has only the keys they need — and treating absence as deletion
+ * would let that quietly destroy a teammate's key.
+ */
+export async function push(flags, args) {
+  const context = resolveContext(flags)
+  const cloudFiles = await fetchCloudFiles(context)
+
+  const names = resolveFileNames({
+    repoRoot: context.repoRoot,
+    link: context.link,
+    cloudFiles,
+    requested: args,
+  })
+
+  const localFiles = loadLocalFiles(context.repoRoot, names)
+  const presentNames = names.filter(name => localFiles.get(name) !== null)
+
+  if (presentNames.length === 0) {
+    throw new CliError('No local env files to push.', {
+      hint: 'Create a .env file, or name one explicitly: `envs push .env.local`',
+    })
+  }
+
+  const comparison = compareProject({
+    cloudFiles: cloudFiles.filter(file => presentNames.includes(file.name)),
+    localFiles: new Map(presentNames.map(name => [name, localFiles.get(name)])),
+  })
+
+  out()
+
+  let pushed = 0
+
+  for (const file of comparison) {
+    const entries = localFiles.get(file.name) ?? []
+
+    if (file.state === FILE_STATE.IN_SYNC && !flags.force) {
+      out(`  ${style.dim('=')} ${file.name} ${style.dim('already up to date')}`)
+      continue
+    }
+
+    const willDelete = flags.prune ? file.counts.cloud_only : 0
+
+    if (flags['dry-run']) {
+      out(
+        `  ${style.dim('would push')} ${file.name} ${style.dim(
+          `(${file.counts.local_only} new, ${file.counts.modified} changed` +
+            `${willDelete ? `, ${willDelete} deleted` : ''})`
+        )}`
+      )
+      continue
+    }
+
+    const result = await api.putFile(
+      context.host,
+      context.token,
+      context.project.name,
+      file.name,
+      entries,
+      Boolean(flags.prune)
+    )
+
+    pushed += 1
+
+    const parts = []
+
+    if (result.created) {
+      parts.push(style.green(`${result.created} new`))
+    }
+
+    if (result.updated) {
+      parts.push(style.yellow(`${result.updated} changed`))
+    }
+
+    if (result.deleted) {
+      parts.push(style.red(`${result.deleted} deleted`))
+    }
+
+    if (parts.length === 0) {
+      parts.push(style.dim('no changes'))
+    }
+
+    out(`  ${style.green('✓')} ${file.name}  ${parts.join(style.dim(', '))}`)
+
+    if (!flags.prune && file.counts.cloud_only > 0) {
+      out(
+        `      ${style.dim(
+          `${pluralize(file.counts.cloud_only, 'key')} in the cloud not present locally — left untouched (--prune to remove)`
+        )}`
+      )
+    }
+  }
+
+  out()
+
+  if (!flags['dry-run'] && pushed > 0) {
+    out(`  ${style.dim(`Pushed ${pluralize(pushed, 'file')} to ${context.project.name}.`)}`)
+    out()
+  }
+
+  return 0
+}
+
+async function fetchCloudFiles(context) {
+  try {
+    const response = await api.projectStatus(context.host, context.token, context.project.name)
+    return response.files ?? []
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      // First push to a new project: the server creates it on write.
+      return []
+    }
+
+    throw error
+  }
+}