envspot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnvSpot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# EnvSpot CLI (`envspot`)
+
+Minimal reference for the **`login` · `link` · `run`** surface. Full command reference: **[`../docs/cli-reference.md`](../docs/cli-reference.md)**. Historical SD-02 sequence + rationale: **[`../docs/historical/SD-02-cli-sequence.md`](../docs/historical/SD-02-cli-sequence.md)**.
+
+## Trust model (matches SD-01 §8 / SD-02 §7)
+
+- **Plaintext secrets** — only in process memory during `run`, after **`GET /api/cli/decrypt`** over TLS. Nothing is written to disk as a secret bundle.
+- **No DEK / no master key on the client** — unwrap and decrypt happen server-side.
+- **`.envspot.json`** — project id + environment label only; safe to commit unless you treat the project id as sensitive.
+- **Token** — stored with **keytar** (OS keychain); on **401** / `token_invalid`, `run` clears the stored credential and exits **4** so you re-`login`.
+
+## User-Agent
+
+All requests send **`User-Agent: envspot-cli/<semver>`** (`cli/src/config.ts`) for server-side audits (SD-01 §5.2).
+
+## Resolved product choices
+
+Exit codes, retries, **403** tier responses, and operational note on auth-tag / decrypt failures: **[`../docs/historical/sd-open-questions-resolved.md`](../docs/historical/sd-open-questions-resolved.md)**.
+
+## Build
+
+```bash
+cd cli && npm ci && npm run build
+```
+
+Bin: **`envspot`** → **`./dist/index.js`**.

package/dist/auth-store.js

@@ -0,0 +1,67 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import keytar from "keytar";
+export const KEYTAR_SERVICE = "EnvSpot";
+export const KEYTAR_ACCOUNT = "cli-device-access-token";
+export const CONFIG_DIR = join(homedir(), ".envspot");
+export const LEGACY_AUTH_JSON = join(CONFIG_DIR, "auth.json");
+/** Non-spec escape hatch when keytar cannot load (unsupported CI image, missing libsecret). */
+export function devAuthJsonEnabled() {
+    return process.env.ENVSPOT_DEV_AUTH_JSON === "1";
+}
+export async function clearStoredCredential() {
+    try {
+        rmSync(LEGACY_AUTH_JSON, { force: true });
+    }
+    catch {
+        /* noop */
+    }
+    try {
+        await keytar.deletePassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+    }
+    catch {
+        /* noop — may be “not found” */
+    }
+}
+function readDevFileToken() {
+    try {
+        const raw = readFileSync(LEGACY_AUTH_JSON, "utf8");
+        const j = JSON.parse(raw);
+        return typeof j.token === "string" && j.token.trim().length > 0
+            ? j.token.trim()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the CLI bearer token + its source. `ENVSPOT_TOKEN` (CI) wins, then dev-file, then keychain. */
+export async function resolveToken() {
+    const envToken = process.env.ENVSPOT_TOKEN?.trim();
+    if (envToken)
+        return { token: envToken, source: "env" };
+    if (devAuthJsonEnabled()) {
+        const token = readDevFileToken();
+        return { token, source: token ? "dev-file" : "none" };
+    }
+    try {
+        const token = await keytar.getPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT);
+        return { token, source: token ? "keychain" : "none" };
+    }
+    catch {
+        return { token: null, source: "none" };
+    }
+}
+export async function getStoredToken() {
+    return (await resolveToken()).token;
+}
+export async function setStoredToken(plaintextToken) {
+    if (devAuthJsonEnabled()) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        writeFileSync(LEGACY_AUTH_JSON, `${JSON.stringify({ token: plaintextToken }, null, 2)}\n`, "utf8");
+        console.error("Warning: ENVSPOT_DEV_AUTH_JSON=1 writes ~/.envspot/auth.json — not spec; unset for OS keychain (keytar).");
+        return;
+    }
+    await keytar.setPassword(KEYTAR_SERVICE, KEYTAR_ACCOUNT, plaintextToken);
+}

package/dist/cli-api-error.js

@@ -0,0 +1,48 @@
+import { clearStoredCredential } from "./auth-store.js";
+import { upgradePageHint } from "./config.js";
+import { CliError, ERR, forbiddenProject, sessionExpired } from "./errors.js";
+function codeFromJson(j) {
+    if (!j)
+        return undefined;
+    return typeof j.code === "string" ? j.code : undefined;
+}
+/**
+ * Map a non-OK `{ ok:false, code }` response from the `/api/cli/*` endpoints to
+ * a typed CliError carrying the documented exit code. Clears the stored
+ * credential on 401 so the next command re-authenticates. `projectRef` flavors
+ * the forbidden message when the failure is project-scoped.
+ *
+ * The server collapses KMS/decrypt faults into a generic 500, so the old
+ * granular exit codes 8/9 are no longer distinguishable here.
+ */
+export async function cliApiError(status, json, projectRef) {
+    const code = codeFromJson(json);
+    if (status === 401 || code === "UNAUTHORIZED") {
+        await clearStoredCredential();
+        return sessionExpired();
+    }
+    if (status === 429 || code === "RATE_LIMITED") {
+        return new CliError(ERR.RATE_LIMITED, "Rate limit hit.", "Try again shortly.");
+    }
+    if (code === "ENV_NOT_ALLOWED" || code === "SECRET_LIMIT") {
+        const detail = code === "SECRET_LIMIT"
+            ? "You've reached your plan's secret limit."
+            : "That environment isn't available on your plan.";
+        return new CliError(ERR.TIER_EXCEEDED, detail, `Upgrade: ${upgradePageHint()}`);
+    }
+    if (code === "SESSION_BEARER_REQUIRED") {
+        // A headless token reached a session-only endpoint — wrong kind, not a
+        // project-access problem.
+        return new CliError(ERR.AUTH_REQUIRED, "This command needs a device login.", "Run: envspot login");
+    }
+    if (status === 403 ||
+        status === 404 ||
+        code === "FORBIDDEN" ||
+        code === "NOT_FOUND") {
+        return forbiddenProject(projectRef ?? "this project");
+    }
+    if (status === 400 || code === "INVALID_REQUEST" || code === "INVALID_KEYS") {
+        return new CliError(ERR.INVALID_INPUT, "The request was rejected as invalid.", "Check the project, environment, and key names.");
+    }
+    return new CliError(ERR.UNEXPECTED, `Request failed (${status}).`);
+}

package/dist/config.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export function packageVersion() {
+    const pjPath = join(__dirname, "..", "package.json");
+    const pj = JSON.parse(readFileSync(pjPath, "utf8"));
+    return pj.version;
+}
+export function cliUserAgent() {
+    return `envspot-cli/${packageVersion()}`;
+}
+export function apiBase() {
+    if (process.env.ENVSPOT_API_URL?.trim())
+        return process.env.ENVSPOT_API_URL.trim();
+    if (process.env.ENV_SPOT_API_URL?.trim())
+        return process.env.ENV_SPOT_API_URL.trim();
+    if (process.env.ENVV_API_URL?.trim())
+        return process.env.ENVV_API_URL.trim();
+    if (process.env.NODE_ENV === "development")
+        return "http://localhost:3000";
+    return "https://api.envspot.com";
+}
+/** Browser/dashboard origin for CLI login approval (dashboard lives here, not on API origin). */
+export function appOrigin() {
+    const explicit = process.env.ENVSPOT_APP_URL?.trim();
+    if (explicit)
+        return explicit.replace(/\/$/, "");
+    const api = apiBase();
+    const u = /^https?:\/\/[^/]+/i.exec(api);
+    const hostOnly = u ? u[0] : api.replace(/\/$/, "");
+    if (/\blocalhost\b/i.test(hostOnly) || /\b127\.0\.0\.1\b/.test(hostOnly)) {
+        return hostOnly;
+    }
+    return "https://envspot.com";
+}
+export function statusPageHint() {
+    return process.env.ENVSPOT_STATUS_URL?.trim() || "https://status.envspot.com";
+}
+export function upgradePageHint(jsonUpgradeUrl) {
+    const u = typeof jsonUpgradeUrl === "string" && jsonUpgradeUrl.trim().length > 0
+        ? jsonUpgradeUrl.trim()
+        : null;
+    return u ?? "https://envspot.com/dashboard/billing";
+}

package/dist/device-flow.js

@@ -0,0 +1,106 @@
+import { hostname } from "node:os";
+import { appOrigin, packageVersion } from "./config.js";
+import { CliError, ERR } from "./errors.js";
+import { apiUrl, backoffTransport, fetchWithCliHeaders, isLikelyTransportFailure, parseJsonSafely, rethrowTransport, } from "./http.js";
+const LOGIN_AGAIN = "Run: envspot login";
+const POLL_INTERVAL_MS = 2000;
+/** Server pairing TTL is 10 min; poll a little past it before giving up. */
+const POLL_WINDOW_MS = 10 * 60 * 1000 + 15_000;
+/**
+ * Begin a device-pairing flow. The server mints the userCode + deviceCode; we
+ * only describe this device. Returns both codes — the userCode goes in the
+ * browser approve URL, the deviceCode is the polling secret.
+ */
+export async function startDeviceFlow() {
+    let res;
+    try {
+        res = await backoffTransport(async () => fetchWithCliHeaders(apiUrl("/api/cli/login/start"), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                hostname: hostname().slice(0, 128),
+                platform: process.platform,
+                version: packageVersion(),
+            }),
+        }));
+    }
+    catch (e) {
+        rethrowTransport(e);
+    }
+    const { json } = await parseJsonSafely(res);
+    if (res.ok &&
+        json &&
+        typeof json.userCode === "string" &&
+        typeof json.deviceCode === "string") {
+        return {
+            userCode: json.userCode,
+            deviceCode: json.deviceCode,
+            expiresAt: typeof json.expiresAt === "string" ? json.expiresAt : "",
+        };
+    }
+    if (res.status === 429) {
+        throw new CliError(ERR.RATE_LIMITED, "Rate limit hit.", "Try again shortly.");
+    }
+    throw new CliError(ERR.UNEXPECTED, `Couldn't start CLI login (${res.status}).`, LOGIN_AGAIN);
+}
+/** Dashboard approve URL for a userCode. `from` deep-links a specialized mode
+ *  (e.g. the cli-init approve card). */
+export function approveUrl(userCode, opts) {
+    const params = new URLSearchParams({ code: userCode });
+    if (opts?.from)
+        params.set("from", opts.from);
+    return `${appOrigin()}/dashboard/cli/approve?${params.toString()}`;
+}
+/**
+ * Poll until the browser approves the pairing, returning the minted bearer
+ * token (and, for an init pairing, the created projectId). Throws a typed
+ * CliError on expiry, a lost session, or timeout.
+ */
+export async function pollForBearer(deviceCode, opts) {
+    const now = opts?.now ?? (() => Date.now());
+    const intervalMs = opts?.intervalMs ?? POLL_INTERVAL_MS;
+    const deadline = now() + POLL_WINDOW_MS;
+    while (now() < deadline) {
+        await new Promise((r) => setTimeout(r, intervalMs));
+        let res;
+        try {
+            res = await fetchWithCliHeaders(apiUrl("/api/cli/login/poll"), {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ deviceCode }),
+            });
+        }
+        catch (e) {
+            // A transient blip mid-window shouldn't abort an approval the user may
+            // have already granted — retry on the next tick.
+            if (isLikelyTransportFailure(e))
+                continue;
+            throw e;
+        }
+        const { json } = await parseJsonSafely(res);
+        if (res.status === 410) {
+            throw new CliError(ERR.UNEXPECTED, "Pairing expired.", LOGIN_AGAIN);
+        }
+        if (res.status === 404) {
+            throw new CliError(ERR.UNEXPECTED, "Lost the pairing session.", LOGIN_AGAIN);
+        }
+        if (res.status === 409) {
+            throw new CliError(ERR.UNEXPECTED, "This pairing was already used.", LOGIN_AGAIN);
+        }
+        if (res.status === 429) {
+            const retry = Number(res.headers.get("retry-after")) || 2;
+            await new Promise((r) => setTimeout(r, Math.min(retry * 1000, 30_000)));
+            continue;
+        }
+        if (res.ok &&
+            json?.status === "redeemed" &&
+            typeof json.bearerToken === "string") {
+            return {
+                bearerToken: json.bearerToken,
+                projectId: typeof json.projectId === "string" ? json.projectId : undefined,
+            };
+        }
+        // ok + status:"pending" (or any other transient ok) → keep waiting.
+    }
+    throw new CliError(ERR.UNEXPECTED, "Timed out waiting for browser approval.", LOGIN_AGAIN);
+}

package/dist/device-login.js

@@ -0,0 +1,18 @@
+import { clearStoredCredential, devAuthJsonEnabled, setStoredToken, } from "./auth-store.js";
+import { approveUrl, pollForBearer, startDeviceFlow } from "./device-flow.js";
+import { openApproveUrl } from "./open-browser.js";
+import * as out from "./output.js";
+export async function runInteractiveDeviceLogin() {
+    const { userCode, deviceCode } = await startDeviceFlow();
+    const url = approveUrl(userCode);
+    out.step("Authenticate this device:");
+    console.log(`  Visit: ${url}`);
+    console.log(`  Enter code when prompted (if blank): ${userCode}\n`);
+    openApproveUrl(url);
+    const { bearerToken } = await pollForBearer(deviceCode);
+    await clearStoredCredential();
+    await setStoredToken(bearerToken.trim());
+    out.success(devAuthJsonEnabled()
+        ? "Logged in — token saved to ~/.envspot/auth.json (ENVSPOT_DEV_AUTH_JSON)."
+        : "Logged in — token saved to the OS credential store.");
+}

package/dist/dump.js

@@ -0,0 +1,37 @@
+import { getStoredToken } from "./auth-store.js";
+import { authRequired } from "./errors.js";
+import * as out from "./output.js";
+import { fetchProjectSecrets, resolveLinkScope } from "./secrets.js";
+import { isHeadlessToken } from "./token-kind.js";
+const SIMPLE_VALUE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/** Render a dotenv-round-trippable `KEY=value`. Single quotes are literal in dotenv + shells; double quotes only for newline/embedded-`'` values. */
+export function formatEnvLine(key, value) {
+    if (SIMPLE_VALUE.test(value))
+        return `${key}=${value}`;
+    if (!value.includes("'") && !/[\n\r]/.test(value)) {
+        return `${key}='${value}'`;
+    }
+    const escaped = value
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/"/g, '\\"');
+    return `${key}="${escaped}"`;
+}
+/** `envspot dump` — print the linked project's secrets as `KEY=value` to stdout. */
+export async function executeDump(opts) {
+    const token = await getStoredToken();
+    if (!token)
+        throw authRequired();
+    if (process.stdout.isTTY) {
+        out.warn("dump prints secrets to stdout. Prefer `envspot run` to keep them off disk; redirect (> .env) only if a tool requires a file.");
+    }
+    // Headless token self-scopes (CI, no link); session bearer reads the link.
+    const secrets = isHeadlessToken(token)
+        ? await fetchProjectSecrets(token)
+        : await fetchProjectSecrets(token, resolveLinkScope(opts.env));
+    const lines = Object.keys(secrets)
+        .sort()
+        .map((k) => formatEnvLine(k, secrets[k]));
+    if (lines.length > 0)
+        process.stdout.write(`${lines.join("\n")}\n`);
+}

package/dist/env-parse.js

@@ -0,0 +1,61 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_FILE_NAMES = [
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.production",
+];
+function unquote(raw) {
+    const v = raw.trim();
+    // Double-quoted: dotenv-style — expand \n \r \t and \" (matches dump output).
+    if (v.length >= 2 && /^"[\s\S]*"$/.test(v)) {
+        return v
+            .slice(1, -1)
+            .replace(/\\n/g, "\n")
+            .replace(/\\r/g, "\r")
+            .replace(/\\t/g, "\t")
+            .replace(/\\"/g, '"');
+    }
+    // Single-quoted: literal, no expansion.
+    if (v.length >= 2 && /^'[\s\S]*'$/.test(v))
+        return v.slice(1, -1);
+    return v;
+}
+/** Parse a `.env` file into usable keys + a reasoned list of ignored lines. */
+export function parseEnvFile(content) {
+    const keys = [];
+    const ignored = [];
+    const lines = content.split(/\r?\n/);
+    lines.forEach((line, i) => {
+        const lineNumber = i + 1;
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            // Ignore blanks but not the empty final segment left by a trailing newline.
+            if (i < lines.length - 1)
+                ignored.push({ lineNumber, reason: "blank" });
+            return;
+        }
+        if (trimmed.startsWith("#")) {
+            ignored.push({ lineNumber, reason: "comment" });
+            return;
+        }
+        const eq = trimmed.indexOf("=");
+        if (eq === -1) {
+            ignored.push({ lineNumber, reason: "no '=' sign" });
+            return;
+        }
+        const key = trimmed.slice(0, eq).trim();
+        if (!KEY_RE.test(key)) {
+            ignored.push({ lineNumber, reason: "invalid key" });
+            return;
+        }
+        keys.push({ key, value: unquote(trimmed.slice(eq + 1)) });
+    });
+    return { keys, ignored };
+}
+/** Names of the `.env*` files that exist in `dir`, in a stable order. */
+export function discoverEnvFiles(dir) {
+    return ENV_FILE_NAMES.filter((name) => existsSync(join(dir, name)));
+}

package/dist/errors.js

@@ -0,0 +1,84 @@
+function code(exitCode) {
+    return { exitCode, slug: `E${String(exitCode).padStart(4, "0")}` };
+}
+export const ERR = {
+    UNEXPECTED: code(1),
+    AUTH_REQUIRED: code(2),
+    NOT_LINKED: code(2),
+    TRANSPORT: code(3),
+    SESSION_EXPIRED: code(4),
+    FORBIDDEN: code(5),
+    TIER_EXCEEDED: code(6),
+    RATE_LIMITED: code(7),
+    KMS_UNAVAILABLE: code(8),
+    DECRYPT_FAILED: code(9),
+    INVALID_INPUT: code(50),
+    TTY_REQUIRED: code(51),
+    MONOREPO_AMBIGUOUS: code(54),
+    NOT_LOGGED_IN: code(70),
+    OFFLINE: code(75),
+    INIT_LOCKED: code(76),
+    // Fly wrapper pre-flight failures. The slug is the user-facing contract
+    // (the docs URLs key off it); the >255 exit codes truncate to 8 bits at the
+    // OS boundary, which is fine for these interactive setup-time errors.
+    FLYCTL_MISSING: code(600),
+    FLY_TOML_MISSING: code(601),
+};
+export class CliError extends Error {
+    exitCode;
+    slug;
+    help;
+    constructor(errorCode, message, help) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = errorCode.exitCode;
+        this.slug = errorCode.slug;
+        this.help = help;
+    }
+}
+export function authRequired() {
+    return new CliError(ERR.AUTH_REQUIRED, "You aren't logged in.", "Run: envspot login");
+}
+export function notLinked() {
+    return new CliError(ERR.NOT_LINKED, "This directory isn't linked.", "Run: envspot link");
+}
+/** `whoami` has its own not-logged-in code (exits 70) so the friendly
+ *  "run login or init" message is distinct from the bare E0002 path. */
+export function notLoggedIn() {
+    return new CliError(ERR.NOT_LOGGED_IN, "Not logged in.", "Run `envspot login` or `envspot init` to authenticate.");
+}
+export function flyctlNotInstalled() {
+    return new CliError(ERR.FLYCTL_MISSING, "flyctl is not installed.", "Install flyctl: https://fly.io/docs/getting-started/installing-flyctl/");
+}
+export function flyTomlNotFound() {
+    return new CliError(ERR.FLY_TOML_MISSING, "No fly.toml found in this directory.", "Run in a Fly app directory, or pass --app <name>.");
+}
+/** A headless (read-only, CI) token was used for a command that needs an
+ *  interactive device login (writes, listing, linking). */
+export function deviceLoginRequired(action) {
+    return new CliError(ERR.AUTH_REQUIRED, `${action} needs a device login (headless tokens are read-only).`, "Run: envspot login");
+}
+export function sessionExpired() {
+    return new CliError(ERR.SESSION_EXPIRED, "Session expired or revoked.", "Run: envspot login");
+}
+export function forbiddenProject(projectRef) {
+    return new CliError(ERR.FORBIDDEN, `You don't have access to project ${projectRef}.`, "Run: envspot login (if switching accounts), then retry.");
+}
+export function ttyRequired(command, help) {
+    return new CliError(ERR.TTY_REQUIRED, `${command} requires an interactive terminal (TTY).`, help);
+}
+/**
+ * Print a CLI error and return its process exit code. Non-CliError throwables
+ * are wrapped as E0001. `write` defaults to `console.error` and is injectable
+ * for tests.
+ */
+export function reportCliError(e, write = (m) => console.error(m)) {
+    const err = e instanceof CliError
+        ? e
+        : new CliError(ERR.UNEXPECTED, e instanceof Error ? e.message : String(e));
+    const lines = [`error[${err.slug}]: ${err.message}`];
+    if (err.help)
+        lines.push(`  help: ${err.help}`);
+    write(lines.join("\n"));
+    return err.exitCode;
+}