envstash-cli 0.6.0 → 0.7.0

package/README.md

@@ -362,6 +362,25 @@ server you meant to exclude.
 was to a dev server: where the previous login went is not an instruction about
 where the next one should go.
 
+`https://www.envstash.co` is always tried first. If it cannot be reached — DNS
+fails, the connection is refused, or nothing completes a TLS handshake within 3
+seconds — the CLI uses `https://envstash-next.vercel.app` instead, the same
+production deployment under Vercel's domain, and says so once on stderr. The
+check sends no request, so it is as safe ahead of a write as a read. Its answer
+is remembered for 10 minutes, so the commands after it go straight to whichever
+host works; a domain that shakes hands and then never answers is caught by a
+5-second limit on reads as well.
+
+The two production addresses share one sign-in: signing in on either works for
+both, so there is no `--host` to pass for the fallback. Only the default host
+falls back; a `--host`, `--port`, `ENVSTASH_HOST`, or a repo's link file is used
+as given. An HTTP error is an answer and is not retried, and neither is a write
+whose connection drops after it was sent.
+
+A command that needs a sign-in and finds none signs in first when it is run at a
+terminal, then carries on. In CI, piped, with `--json`, or for a host a cloned
+repo's link file chose, it stops with "Not signed in" instead.
+
 To sign in to a local server, name it — `envs login --port 3001` — or let the
 CLI find it:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envstash-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Git-style CLI for EnvStash — keep your .env files in sync with your cloud account.",
   "keywords": [
     "env",

package/src/api.mjs

@@ -1,4 +1,120 @@
-import { CliError, sanitize } from './ui.mjs'
+import {
+  DEFAULT_HOST,
+  PRODUCTION_FALLBACK_HOST,
+  rememberedRoute,
+  rememberRoute,
+} from './config.mjs'
+import { canReach } from './reachability.mjs'
+import { CliError, errOut, sanitize, style } from './ui.mjs'
+
+export { PRODUCTION_FALLBACK_HOST }
+
+/**
+ * Failures where the request never reached a server, so repeating it against
+ * the fallback cannot apply a write twice. A reset or a timeout mid-response is
+ * deliberately absent: the first server may already have acted on it.
+ */
+const UNREACHABLE_CODES = new Set([
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'ECONNREFUSED',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'UND_ERR_CONNECT_TIMEOUT',
+])
+
+/**
+ * How long the default host gets to complete a TLS handshake before a command
+ * goes to the fallback instead. Nothing is sent, so this decides the route for
+ * writes as safely as for reads.
+ */
+export const PROBE_TIMEOUT_MS = 3000
+
+/**
+ * How long the default host gets to start answering a request, for a domain
+ * that shakes hands and then says nothing. Only requests that are safe to send
+ * twice get this budget, because an abort cannot tell "never arrived" from
+ * "arrived and still working".
+ */
+export const RESPONSE_TIMEOUT_MS = 5000
+
+/** How the default host is reached this process: 'direct', 'fallback', or undecided. */
+let route = null
+/** The probe in flight, so concurrent first requests share one. */
+let deciding = null
+/** Swappable so tests never touch the network. */
+let probe = canReach
+/** Set when a request was given up on while its connection was still open. */
+let abandoned = false
+
+/**
+ * True once a request to the default host was abandoned mid-connect. Aborting
+ * rejects the fetch on time, but the socket — or a system DNS lookup behind
+ * it, which cannot be cancelled at all — holds the process open well after the
+ * work is done.
+ */
+export function abandonedConnection() {
+  return abandoned
+}
+
+function onFallback() {
+  if (route === null) {
+    route = rememberedRoute()
+  }
+
+  return route === 'fallback'
+}
+
+/** Switch the rest of this command, and the next few, to the fallback. */
+function fallBack(host) {
+  route = 'fallback'
+  rememberRoute('fallback')
+  errOut(`  ${style.dim(`${host} is not answering — using ${PRODUCTION_FALLBACK_HOST}.`)}`)
+}
+
+/**
+ * Settle the route before the first request to the default host: from an
+ * earlier command's memory, or by probing. Deciding up front is what keeps a
+ * dead domain from ever reaching fetch, whose DNS lookup could not be undone.
+ */
+async function decideRoute(host) {
+  if (host !== DEFAULT_HOST || onFallback() || route === 'direct') {
+    return
+  }
+
+  deciding ??= (async () => {
+    if (await probe(DEFAULT_HOST, PROBE_TIMEOUT_MS)) {
+      route = 'direct'
+      rememberRoute('direct')
+    } else {
+      fallBack(DEFAULT_HOST)
+    }
+  })()
+
+  await deciding
+}
+
+/**
+ * The origin requests for `host` are actually going to. Differs from `host`
+ * only after the default host was found unreachable — which is what login needs
+ * to know, since the approval link it is handed comes from whichever answered.
+ */
+export function effectiveHost(host) {
+  return host === DEFAULT_HOST && onFallback() ? PRODUCTION_FALLBACK_HOST : host
+}
+
+/** Test hook: forget every routing decision, here and on disk, and set the probe. */
+export function resetHostFallback({ probe: nextProbe = canReach } = {}) {
+  route = null
+  deciding = null
+  probe = nextProbe
+  abandoned = false
+  rememberRoute(null)
+}
+
+function isUnreachable(error) {
+  return UNREACHABLE_CODES.has(error?.cause?.code) || UNREACHABLE_CODES.has(error?.code)
+}
 
 /** An error the server described in its JSON body. */
 export class ApiError extends CliError {
@@ -18,11 +134,8 @@ export class ApiError extends CliError {
  * is not JSON (a proxy error page, a 502 from the edge) is reported as a
  * transport problem rather than crashing on a parse.
  */
-export async function request(
-  host,
-  path,
-  { method = 'GET', token, body, signal, headers: extraHeaders } = {}
-) {
+export async function request(host, path, options = {}) {
+  const { method = 'GET', token, body, signal, headers: extraHeaders, repeatable } = options
   const headers = { accept: 'application/json', ...extraHeaders }
 
   if (token) {
@@ -33,23 +146,47 @@ export async function request(
     headers['content-type'] = 'application/json'
   }
 
+  await decideRoute(host)
+
+  // Not once on the fallback: there is nowhere further to go, and a slow
+  // answer is better than none.
+  const budgeted =
+    host === DEFAULT_HOST && !onFallback() && (method === 'GET' || repeatable === true)
+  const deadline = budgeted ? withDeadline(signal, RESPONSE_TIMEOUT_MS) : null
+
+  const init = {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: deadline?.signal ?? signal,
+  }
+
   let response
 
   try {
-    response = await fetch(`${host}${path}`, {
-      method,
-      headers,
-      body: body === undefined ? undefined : JSON.stringify(body),
-      signal,
-    })
+    response = await fetch(`${effectiveHost(host)}${path}`, init)
   } catch (error) {
-    if (error?.name === 'AbortError') {
+    const timedOut = deadline?.expired() === true
+
+    if (error?.name === 'AbortError' && !timedOut) {
       throw error
     }
 
-    throw new CliError(`Could not reach ${host}.`, {
+    // The backstop for a domain that passed the probe and then failed anyway.
+    if (host === DEFAULT_HOST && !onFallback() && (timedOut || isUnreachable(error))) {
+      abandoned ||= timedOut
+      fallBack(host)
+
+      return request(host, path, options)
+    }
+
+    throw new CliError(`Could not reach ${effectiveHost(host)}.`, {
       hint: 'Check your connection, or pass --host if you meant a different server.',
     })
+  } finally {
+    // Stopped once the headers are in: the budget is for starting to answer,
+    // and a large body still arriving is an answer.
+    deadline?.clear()
   }
 
   const text = await response.text()
@@ -69,7 +206,7 @@ export async function request(
     // header when a redirect crosses origins, so the server never saw it. Say
     // that instead of sending the user round the login loop again.
     const crossOriginRedirect =
-      token && response.status === 401 && redirectedAcrossOrigin(host, response)
+      token && response.status === 401 && redirectedAcrossOrigin(effectiveHost(host), response)
 
     if (crossOriginRedirect) {
       throw new ApiError(
@@ -101,6 +238,37 @@ export async function request(
   return payload ?? {}
 }
 
+/**
+ * An abort signal that fires after `ms`, or when the caller's own signal does.
+ * Built by hand rather than with AbortSignal.any/timeout so it runs on the
+ * Node 18 the package still supports, and so a caller's abort stays
+ * distinguishable from the deadline.
+ */
+function withDeadline(outer, ms) {
+  const controller = new AbortController()
+  let expired = false
+
+  const onOuterAbort = () => controller.abort(outer.reason)
+  const timer = setTimeout(() => {
+    expired = true
+    controller.abort()
+  }, ms)
+
+  if (outer?.aborted) {
+    onOuterAbort()
+  } else {
+    outer?.addEventListener('abort', onOuterAbort, { once: true })
+  }
+
+  return {
+    signal: controller.signal,
+    expired: () => expired,
+    // Only the timer: the caller's own abort still has to reach a body that
+    // is mid-read.
+    clear: () => clearTimeout(timer),
+  }
+}
+
 /**
  * The origin a request ended up on, when following redirects moved it off the
  * origin it started on. Returns null otherwise — including when the response
@@ -121,13 +289,22 @@ function redirectedAcrossOrigin(host, response) {
 }
 
 export const api = {
+  // A repeat of these is harmless — a second code nobody approves, a second
+  // look at the same one, a second revocation — so they may be retried on the
+  // fallback after a timeout, like reads.
   startDeviceAuth: (host, label) =>
-    request(host, '/api/cli/auth/device', { method: 'POST', body: { label } }),
+    request(host, '/api/cli/auth/device', { method: 'POST', body: { label }, repeatable: true }),
 
   pollDeviceAuth: (host, deviceCode, signal) =>
-    request(host, '/api/cli/auth/token', { method: 'POST', body: { deviceCode }, signal }),
+    request(host, '/api/cli/auth/token', {
+      method: 'POST',
+      body: { deviceCode },
+      signal,
+      repeatable: true,
+    }),
 
-  logout: (host, token) => request(host, '/api/cli/auth/logout', { method: 'POST', token }),
+  logout: (host, token) =>
+    request(host, '/api/cli/auth/logout', { method: 'POST', token, repeatable: true }),
 
   whoami: (host, token) => request(host, '/api/cli/whoami', { token }),
 

package/src/commands/diff.mjs

@@ -14,7 +14,7 @@ import { maskValue, out, sanitize, style } from '../ui.mjs'
  * revealing a secret a deliberate act.
  */
 export async function diff(flags, args) {
-  const context = resolveContext(flags)
+  const context = await resolveContext(flags)
   const cloudFiles = await fetchCloudFiles(context)
 
   const names = resolveFileNames({

package/src/commands/login.mjs

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process'
 import { hostname, userInfo } from 'node:os'
 import { setTimeout as sleep } from 'node:timers/promises'
 
-import { api } from '../api.mjs'
+import { api, effectiveHost } from '../api.mjs'
 import {
   clearAllCredentials,
   clearToken,
@@ -11,6 +11,7 @@ import {
   isKnownHost,
   readConfig,
   saveToken,
+  storedTokens,
 } from '../config.mjs'
 import { DEV_PORTS } from '../dev-host.mjs'
 import { isLinkChosenHost, resolveHostFor, resolveLoginHost } from '../session.mjs'
@@ -48,7 +49,9 @@ export async function login(flags) {
   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)
+  // Against the host that answered: if production fell back to its Vercel
+  // domain, the link legitimately points there.
+  const verificationUrl = safeVerificationUrl(started.verificationUrlComplete, effectiveHost(host))
 
   out()
   out(`  Your code:  ${style.bold(style.cyan(sanitize(started.userCode)))}`)
@@ -58,7 +61,7 @@ export async function login(flags) {
   // lets a terminal's double-click and link detection grab the whole thing.
   out(`  ${style.dim('Open this link to approve:')}`)
   out()
-  out(`  ${style.cyan(verificationUrl ?? `${host}/cli`)}`)
+  out(`  ${style.cyan(verificationUrl ?? `${effectiveHost(host)}/cli`)}`)
   out()
 
   if (!verificationUrl) {
@@ -303,11 +306,13 @@ export async function logout(flags) {
     return 0
   }
 
-  const token = getToken(host)
+  // Every token for this server: the two production names share one, but a
+  // machine that signed in under each before they did holds two.
+  const tokens = new Set([getToken(host), ...storedTokens(host)].filter(Boolean))
 
   // Revoke server-side first. A local delete alone leaves a live token that
   // still works for anyone who copied the config file.
-  if (token) {
+  for (const token of tokens) {
     try {
       await api.logout(host, token)
     } catch {

package/src/commands/misc.mjs

@@ -78,7 +78,7 @@ function sourceLabel(source) {
 
 /** `envs whoami` — which account this machine is signed in as. */
 export async function whoami(flags) {
-  const { host, token } = requireHostToken(flags)
+  const { host, token } = await requireHostToken(flags)
   const who = await api.whoami(host, token)
 
   if (flags.json) {
@@ -98,7 +98,7 @@ export async function whoami(flags) {
 
 /** `envs list` — every project in the account. */
 export async function list(flags) {
-  const { host, token } = requireHostToken(flags)
+  const { host, token } = await requireHostToken(flags)
   const { projects } = await api.listProjects(host, token)
 
   if (flags.json) {
@@ -136,7 +136,7 @@ export async function list(flags) {
  * 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 { host, token } = await requireHostToken(flags)
   const repoRoot = findRepoRoot()
   const existing = readLink(repoRoot)
   const name = args[0] ?? flags.project ?? resolveProject(repoRoot, undefined).name
@@ -181,7 +181,7 @@ export async function init(flags, args) {
  * 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 { host, token } = await requireHostToken(flags)
   const repoRoot = findRepoRoot()
   const existing = readLink(repoRoot)
   const name = args[0] ?? flags.project

package/src/commands/pull.mjs

@@ -34,7 +34,7 @@ export async function pull(flags, args) {
     })
   }
 
-  const context = resolveContext(flags)
+  const context = await resolveContext(flags)
   const scope = shared ? SHARED_SCOPE : context.project.name
 
   let cloudFiles

package/src/commands/push.mjs

@@ -50,7 +50,7 @@ export async function push(flags, args) {
     })
   }
 
-  const context = resolveContext(flags)
+  const context = await resolveContext(flags)
   const scope = shared ? SHARED_SCOPE : context.project.name
 
   // Before discovery, so files in a not-yet-ignored .config/ are picked up by

package/src/commands/remove.mjs

@@ -26,7 +26,7 @@ export async function remove(flags, args) {
     })
   }
 
-  const context = resolveContext(flags)
+  const context = await resolveContext(flags)
   const scope = shared ? SHARED_SCOPE : context.project.name
 
   out()

package/src/commands/status.mjs

@@ -25,7 +25,7 @@ const KEY_MARK = {
  * ever knowing what the value is.
  */
 export async function status(flags, args) {
-  const context = resolveContext(flags)
+  const context = await resolveContext(flags)
   const cloudFiles = await fetchCloudFiles(context)
 
   const names = resolveFileNames({

package/src/commands/sync.mjs

@@ -46,7 +46,7 @@ export async function sync(flags, args) {
   }
 
   const prefer = resolvePrefer(flags)
-  const context = resolveContext(flags)
+  const context = await resolveContext(flags)
   const scope = shared ? SHARED_SCOPE : context.project.name
 
   // Same reasoning as `push`: before discovery, so a file in a not-yet-ignored

package/src/config.mjs

@@ -13,6 +13,51 @@ import { CliError } from './ui.mjs'
  */
 export const DEFAULT_HOST = 'https://www.envstash.co'
 
+/**
+ * The same production deployment under Vercel's own domain. It exists so a
+ * problem with the custom domain — DNS, a lapsed registration, a certificate —
+ * does not take the CLI down with it while the app itself is healthy.
+ *
+ * Only the default host falls back, and only to this fixed address: a host the
+ * developer or a repo named is theirs to reach or not, and a fallback that
+ * followed it anywhere would be a way to redirect their token.
+ */
+export const PRODUCTION_FALLBACK_HOST = 'https://envstash-next.vercel.app'
+
+/**
+ * The key a host's credential is stored under. The two production names are
+ * one server with one database, so they share one credential: signing in on
+ * either works for both, and a fallback never finds itself signed out.
+ */
+function credentialKey(host) {
+  return host === PRODUCTION_FALLBACK_HOST ? DEFAULT_HOST : host
+}
+
+/**
+ * The stored entry for a host. Also reads the Vercel domain's own key, where a
+ * login from before the two were merged left its credential.
+ */
+function storedEntry(hosts, host) {
+  return (
+    hosts[credentialKey(host)] ??
+    (credentialKey(host) === DEFAULT_HOST ? hosts[PRODUCTION_FALLBACK_HOST] : undefined) ??
+    null
+  )
+}
+
+/**
+ * Every distinct token stored for a host's server, so a logout can revoke all
+ * of them — a machine that signed in under both production names before they
+ * shared a key holds two.
+ */
+export function storedTokens(host) {
+  const { hosts } = readConfig()
+  const keys =
+    credentialKey(host) === DEFAULT_HOST ? [DEFAULT_HOST, PRODUCTION_FALLBACK_HOST] : [host]
+
+  return [...new Set(keys.map(key => hosts[key]?.token).filter(Boolean))]
+}
+
 /** Where credentials live. Overridable so tests never touch a real ~/.envstash. */
 export function configDir() {
   return process.env.ENVSTASH_CONFIG_DIR ?? join(homedir(), '.envstash')
@@ -136,7 +181,9 @@ export function resolveHost(flagHost) {
     return normalizeHost(process.env.ENVSTASH_HOST)
   }
 
-  return normalizeHost(readConfig().defaultHost)
+  // The custom domain is always tried first. A default saved by signing in on
+  // the Vercel domain means production, not "skip the custom domain for good".
+  return credentialKey(normalizeHost(readConfig().defaultHost))
 }
 
 /**
@@ -155,7 +202,7 @@ export function getToken(host, { allowEnvToken = true } = {}) {
     return process.env.ENVSTASH_TOKEN
   }
 
-  return readConfig().hosts[host]?.token ?? null
+  return storedEntry(readConfig().hosts, host)?.token ?? null
 }
 
 export function requireToken(host, { allowEnvToken = true } = {}) {
@@ -184,10 +231,14 @@ export function requireToken(host, { allowEnvToken = true } = {}) {
 export function saveToken(host, token, email, { makeDefault = true } = {}) {
   const config = readConfig()
 
-  config.hosts[host] = { token, email }
+  config.hosts[credentialKey(host)] = { token, email }
+
+  if (credentialKey(host) === DEFAULT_HOST) {
+    delete config.hosts[PRODUCTION_FALLBACK_HOST]
+  }
 
   if (makeDefault) {
-    config.defaultHost = host
+    config.defaultHost = credentialKey(host)
   }
 
   writeConfig(config)
@@ -195,12 +246,17 @@ export function saveToken(host, token, email, { makeDefault = true } = {}) {
 
 export function clearToken(host) {
   const config = readConfig()
+  const keys =
+    credentialKey(host) === DEFAULT_HOST ? [DEFAULT_HOST, PRODUCTION_FALLBACK_HOST] : [host]
 
-  if (!config.hosts[host]) {
+  if (!keys.some(key => config.hosts[key])) {
     return false
   }
 
-  delete config.hosts[host]
+  for (const key of keys) {
+    delete config.hosts[key]
+  }
+
   writeConfig(config)
 
   return true
@@ -208,11 +264,54 @@ export function clearToken(host) {
 
 /** True when the developer has signed in to this host before. */
 export function isKnownHost(host) {
-  return Boolean(readConfig().hosts[host])
+  return Boolean(storedEntry(readConfig().hosts, host))
 }
 
 export function getStoredEmail(host) {
-  return readConfig().hosts[host]?.email ?? null
+  return storedEntry(readConfig().hosts, host)?.email ?? null
+}
+
+/**
+ * How long the route to production is remembered across commands, either way.
+ * Long enough that a run of commands pays for deciding once; short enough that
+ * a domain that recovers — or dies — is noticed soon after.
+ */
+export const ROUTE_MEMORY_MS = 10 * 60 * 1000
+
+function routePath() {
+  return join(configDir(), 'route.json')
+}
+
+/** `'direct'` or `'fallback'` while an earlier command's decision holds; otherwise null. */
+export function rememberedRoute(now = Date.now()) {
+  try {
+    const { route, until } = JSON.parse(readFileSync(routePath(), 'utf8'))
+    const fresh = Number.isFinite(until) && now < until && until - now <= ROUTE_MEMORY_MS
+
+    return fresh && (route === 'direct' || route === 'fallback') ? route : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Remember how production was reached, or forget it with null. Best-effort: a
+ * read-only home directory costs the next command a probe, not its run.
+ */
+export function rememberRoute(route, now = Date.now()) {
+  try {
+    if (!route) {
+      rmSync(routePath(), { force: true })
+      return
+    }
+
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 })
+    writeFileAtomic(routePath(), `${JSON.stringify({ route, until: now + ROUTE_MEMORY_MS })}\n`, {
+      mode: 0o600,
+    })
+  } catch {
+    // Nothing to do: the decision still holds for this process.
+  }
 }
 
 /** Remove the whole credential file. Backs `envs logout --all`. */

package/src/context.mjs

@@ -20,8 +20,8 @@ export const SHARED_SCOPE = '~shared'
  * Everything the sync commands need, resolved once: which server, which token,
  * which repo, which project.
  */
-export function resolveContext(flags) {
-  const { host, token } = requireHostToken(flags)
+export async function resolveContext(flags) {
+  const { host, token } = await requireHostToken(flags)
   const repoRoot = findRepoRoot()
   const link = readLink(repoRoot)
   const project = resolveProject(repoRoot, flags.project)

package/src/index.mjs

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { abandonedConnection } from './api.mjs'
 import { diff } from './commands/diff.mjs'
 import { login, logout } from './commands/login.mjs'
 import { init, link, list, version as versionCommand, whoami } from './commands/misc.mjs'
@@ -244,6 +245,15 @@ function changeDirectory(flags) {
  */
 function finish(code) {
   process.exitCode = code
+
+  // The one exception: a connection given up on for the fallback holds the
+  // process open for seconds after the work is done. Exit once both streams
+  // have flushed — the write callbacks fire after everything queued before
+  // them — so nothing is truncated and nobody waits on a dead socket.
+  if (abandonedConnection()) {
+    process.stdout.write('', () => process.stderr.write('', () => process.exit(code)))
+  }
+
   return code
 }
 

package/src/reachability.mjs

@@ -0,0 +1,70 @@
+import { promises as dns } from 'node:dns'
+import { connect } from 'node:tls'
+
+/**
+ * Whether `origin` completes a TLS handshake within `timeoutMs`.
+ *
+ * A probe rather than a request: nothing is sent, so a yes or a no is equally
+ * safe ahead of a write. And every part of it can be abandoned. Resolution goes
+ * through c-ares (`dns.Resolver`) rather than the system's getaddrinfo, which
+ * is what fetch uses — getaddrinfo runs on libuv's threadpool, and a lookup
+ * stuck there cannot be cancelled and holds the process open at exit until it
+ * returns, even after the command has finished. The handshake validates the
+ * certificate for the hostname, so a lapsed certificate counts as unreachable
+ * too, which is what the fallback exists for.
+ */
+export async function canReach(origin, timeoutMs) {
+  let url
+
+  try {
+    url = new URL(origin)
+  } catch {
+    return false
+  }
+
+  const resolver = new dns.Resolver({ timeout: timeoutMs, tries: 1 })
+  const started = Date.now()
+  let timer = null
+
+  const deadline = new Promise(resolve => {
+    timer = setTimeout(() => {
+      resolver.cancel()
+      resolve(false)
+    }, timeoutMs)
+  })
+
+  const attempt = (async () => {
+    const [address] = await resolver.resolve4(url.hostname)
+
+    if (!address) {
+      return false
+    }
+
+    return handshake(address, url, Math.max(1, timeoutMs - (Date.now() - started)))
+  })().catch(() => false)
+
+  try {
+    return await Promise.race([attempt, deadline])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function handshake(address, url, timeoutMs) {
+  return new Promise(resolve => {
+    const socket = connect({
+      host: address,
+      port: Number(url.port) || 443,
+      servername: url.hostname,
+    })
+
+    const settle = reachable => {
+      socket.destroy()
+      resolve(reachable)
+    }
+
+    socket.setTimeout(timeoutMs, () => settle(false))
+    socket.once('secureConnect', () => settle(socket.authorized))
+    socket.once('error', () => settle(false))
+  })
+}

package/src/session.mjs

@@ -1,22 +1,54 @@
-import { DEFAULT_HOST, requireToken, resolveHost } from './config.mjs'
+import { DEFAULT_HOST, getToken, requireToken, resolveHost } from './config.mjs'
 import { detectDevHost, isDevMode, resolvePortHost } from './dev-host.mjs'
 import { findRepoRoot, readLink } from './project.mjs'
-import { CliError } from './ui.mjs'
+import { CliError, errOut, style } from './ui.mjs'
 
 /**
- * Resolve host and token together.
+ * Resolve host and token together, signing in first when there is no token.
  *
  * 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) {
+export async 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' }) }
+  const allowEnvToken = source !== 'link'
+
+  if (!getToken(host, { allowEnvToken }) && shouldSignInFirst(source, flags)) {
+    errOut()
+    errOut(`  ${style.dim(`Not signed in to ${host} — signing in first.`)}`)
+
+    // Imported here, not at the top: login resolves hosts through this module.
+    const { login } = await import('./commands/login.mjs')
+
+    // Named explicitly so login signs in exactly where this command is going.
+    // --port is removed, not blanked: the host already says the same thing,
+    // and a present-but-empty --port is refused as a missing number.
+    const loginFlags = { ...flags, host }
+    delete loginFlags.port
+
+    await login(loginFlags)
+  }
+
+  return { host, token: requireToken(host, { allowEnvToken }) }
+}
+
+/**
+ * Whether a command with no token should run the login flow rather than stop.
+ *
+ * Only with a person at a terminal to approve it — CI and piped runs get the
+ * plain "not signed in" error they can act on. Not for a host a repo's link
+ * file chose, since starting a sign-in there is exactly what `envs login`
+ * refuses. And not under --json, whose stdout belongs to the JSON.
+ */
+export function shouldSignInFirst(source, flags, { tty, env } = {}) {
+  const interactive = tty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY)
+  const environment = env ?? process.env
+
+  return interactive && !environment.CI && source !== 'link' && !flags?.json
 }
 
 /**