envspot 0.1.0

package/dist/paths.js

@@ -0,0 +1,68 @@
+import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+export const LINK_PRIMARY = ".envspot.json";
+export const LINK_LEGACY = ".envspot";
+/** Mongo ObjectId hex (24 chars). Project ids are ObjectIds, not UUIDs. */
+const OBJECT_ID_HEX_RE = /^[0-9a-f]{24}$/;
+export function isObjectIdHex(value) {
+    return OBJECT_ID_HEX_RE.test(value);
+}
+export function parseLinkFile(contents) {
+    try {
+        const parsed = JSON.parse(contents);
+        const raw = typeof parsed.projectId === "string" ? parsed.projectId : null;
+        if (!raw)
+            return null;
+        const id = raw.trim().toLowerCase();
+        if (!isObjectIdHex(id))
+            return null;
+        const rawEnv = typeof parsed.environment === "string"
+            ? parsed.environment.trim()
+            : typeof parsed.environment === "number"
+                ? String(parsed.environment)
+                : "dev";
+        const environment = rawEnv.length ? rawEnv : "dev";
+        return { projectId: id, environment };
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the canonical link file (`.envspot.json`) in `dir`. Returns its path. */
+export function writeLinkConfig(dir, payload) {
+    const filePath = join(dir, LINK_PRIMARY);
+    writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return filePath;
+}
+/** Walk cwd → parents for `.envspot.json` / `.envspot` */
+export function findEnvspotLink(startDir) {
+    let dir = resolve(startDir ?? process.cwd());
+    let sawUnparsable = false;
+    for (;;) {
+        for (const name of [LINK_PRIMARY, LINK_LEGACY]) {
+            const p = join(dir, name);
+            if (!existsSync(p))
+                continue;
+            try {
+                const txt = readFileSync(p, "utf8");
+                const link = parseLinkFile(txt);
+                if (link)
+                    return { link, dir };
+                sawUnparsable = true;
+            }
+            catch {
+                /* try sibling name */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // A link file exists but its projectId didn't parse (e.g. a pre-Mongo UUID).
+    // Nudge toward a relink rather than letting callers report a bare "not linked".
+    if (sawUnparsable) {
+        console.warn("Found an .envspot.json but its projectId isn't a valid project id (old format?). Run: envspot link");
+    }
+    return null;
+}

package/dist/project-detect.js

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+const MANIFESTS = [
+    "package.json",
+    "pyproject.toml",
+    "go.mod",
+    "Cargo.toml",
+    "fly.toml",
+    "Dockerfile",
+    ".git",
+];
+/** Nearest ancestor (within `maxUp`) that looks like a project root, else null. */
+export function findProjectRoot(startDir, maxUp = 3) {
+    let dir = resolve(startDir);
+    for (let up = 0; up <= maxUp; up++) {
+        if (MANIFESTS.some((m) => existsSync(join(dir, m))))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** `package.json` paths (relative to `root`) within `maxDepth`, skipping node_modules/.git. */
+export function findPackageJsons(root, maxDepth = 3) {
+    const found = [];
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name === "node_modules" || e.name === ".git")
+                continue;
+            const full = join(dir, e.name);
+            if (e.isFile() && e.name === "package.json") {
+                found.push(relative(root, full) || "package.json");
+            }
+            else if (e.isDirectory()) {
+                walk(full, depth + 1);
+            }
+        }
+    };
+    walk(root, 0);
+    return found.sort();
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function readPackageName(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return typeof pkg.name === "string" && pkg.name.trim() ? pkg.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Suggested project display name + slug from package.json#name or the dir name. */
+export function deriveProjectName(root) {
+    const pkgName = readPackageName(root);
+    if (pkgName) {
+        if (pkgName.startsWith("@")) {
+            const [scope, rest] = pkgName.slice(1).split("/");
+            const name = rest || scope || "";
+            const slug = slugify(`${scope}-${rest ?? ""}`);
+            if (name && slug)
+                return { name, slug };
+        }
+        else {
+            const slug = slugify(pkgName);
+            if (slug)
+                return { name: pkgName, slug };
+        }
+    }
+    // No usable package.json name (or it slugified to empty) → fall back to the dir.
+    const dirName = basename(resolve(root));
+    return { name: dirName || "project", slug: slugify(dirName) || "project" };
+}

package/dist/run-handler.js

@@ -0,0 +1,94 @@
+import { basename } from "node:path";
+import { spawn } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { getStoredToken } from "./auth-store.js";
+import { authRequired } from "./errors.js";
+import { fetchProjectSecrets, resolveLinkScope } from "./secrets.js";
+import { isHeadlessToken } from "./token-kind.js";
+/** Arguments after `envspot run` (i.e. `process.argv.slice(3)` when argv[2]==='run'). */
+export function parseRunTailArgs(parts) {
+    let env;
+    let i = 0;
+    while (i < parts.length) {
+        const a = parts[i];
+        if (a === "--") {
+            const child = parts.slice(i + 1);
+            if (child.length === 0) {
+                return {
+                    ok: false,
+                    message: "Missing command after `--`. Example: envspot run -- npm start",
+                };
+            }
+            return { ok: true, env, child };
+        }
+        if (a === "-e" || a === "--env") {
+            const v = parts[i + 1];
+            if (!v?.trim())
+                return {
+                    ok: false,
+                    message: "`--env` requires a non-empty environment name.",
+                };
+            env = v.trim();
+            i += 2;
+            continue;
+        }
+        if (a.startsWith("--env=")) {
+            const v = a.slice("--env=".length).trim();
+            if (!v)
+                return { ok: false, message: "`--env=` requires a non-empty value." };
+            env = v;
+            i += 1;
+            continue;
+        }
+        return {
+            ok: false,
+            message: `Unexpected token before '--': "${a}". Use: envspot run [--env <name>] -- <command>`,
+        };
+    }
+    return {
+        ok: false,
+        message: "Missing `--` before the wrapped command (e.g. envspot run -- npm start).",
+    };
+}
+/** Spawn the wrapped command with secrets injected; resolves with its exit code. */
+function spawnWithSecrets(command, args, secrets) {
+    return new Promise((resolve) => {
+        const childProc = spawn(command, args, {
+            env: { ...process.env, ...secrets },
+            stdio: "inherit",
+            shell: false,
+        });
+        childProc.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                const b = basename(command.replace(/\\/g, "/"));
+                console.error(`Couldn't run \`${b}\`: command not found.\nIs it installed and on your PATH?`);
+                resolve(127);
+            }
+            else {
+                console.error(`Failed to spawn child: ${err.message}`);
+                resolve(1);
+            }
+        });
+        childProc.on("close", (c, signal) => {
+            if (signal) {
+                const signum = osConstants.signals[signal] ?? 0;
+                resolve(signum ? 128 + signum : (c ?? 1));
+            }
+            else {
+                resolve(c ?? 0);
+            }
+        });
+    });
+}
+/** Inject the linked project's secrets and exec the wrapped command; resolves with its exit code. */
+export async function executeRun(parts) {
+    const token = await getStoredToken();
+    if (!token)
+        throw authRequired();
+    // A headless token self-scopes to one project + env, so CI needs no link
+    // file; a session bearer reads the linked project.
+    const secrets = isHeadlessToken(token)
+        ? await fetchProjectSecrets(token)
+        : await fetchProjectSecrets(token, resolveLinkScope(parts.env));
+    return spawnWithSecrets(parts.child[0], parts.child.slice(1), secrets);
+}

package/dist/secrets.js

@@ -0,0 +1,50 @@
+import { cliApiError } from "./cli-api-error.js";
+import { notLinked } from "./errors.js";
+import { apiUrl, backoffTransport, fetchWithCliHeaders, parseJsonSafely, rethrowTransport, } from "./http.js";
+import { findEnvspotLink } from "./paths.js";
+import { isHeadlessToken } from "./token-kind.js";
+/** Resolve the session-bearer scope from the nearest `.envspot.json`, applying
+ *  an optional env override. Throws `notLinked` when no link file is found. */
+export function resolveLinkScope(envOverride) {
+    const linked = findEnvspotLink(process.cwd());
+    if (!linked)
+        throw notLinked();
+    return {
+        projectId: linked.link.projectId,
+        environment: envOverride?.trim() || linked.link.environment,
+    };
+}
+/**
+ * Fetch a project's decrypted secrets as a `{ KEY: value }` map. Routes by
+ * token kind: a headless token self-scopes via /api/v1/secrets (CI; `scope` is
+ * ignored), a device-login session bearer reads the linked project + env via
+ * /api/cli/secrets. Throws a typed `CliError` on failure.
+ */
+export async function fetchProjectSecrets(token, scope) {
+    const url = isHeadlessToken(token)
+        ? apiUrl("/api/v1/secrets")
+        : `${apiUrl("/api/cli/secrets")}?${new URLSearchParams({
+            project: scope?.projectId ?? "",
+            env: scope?.environment ?? "",
+        }).toString()}`;
+    let res;
+    try {
+        res = await backoffTransport(async () => fetchWithCliHeaders(url, { method: "GET" }, token));
+    }
+    catch (e) {
+        rethrowTransport(e);
+    }
+    const analyzed = await parseJsonSafely(res);
+    if (!res.ok) {
+        throw await cliApiError(res.status, analyzed.json, scope?.projectId);
+    }
+    const out = {};
+    const secrets = analyzed.json?.secrets;
+    if (secrets && typeof secrets === "object") {
+        for (const [k, v] of Object.entries(secrets)) {
+            if (typeof v === "string")
+                out[k] = v;
+        }
+    }
+    return out;
+}

package/dist/token-kind.js

@@ -0,0 +1,14 @@
+/**
+ * CLI bearers come in two kinds, distinguished by mint prefix:
+ *   - `esc_` device-login session bearer (org-wide; uses /api/cli/*)
+ *   - `esh_` headless token (project+env scoped, read-only; uses /api/v1/secrets)
+ * The CLI routes secret reads to the matching endpoint by kind.
+ */
+export function isHeadlessToken(token) {
+    return token.startsWith("esh_");
+}
+/** Endpoint that validates a token of this kind — used to probe auth without
+ *  false-failing on the wrong-kind endpoint (status check, token login). */
+export function probePathForToken(token) {
+    return isHeadlessToken(token) ? "/api/v1/secrets" : "/api/cli/projects";
+}

package/dist/whoami.js

@@ -0,0 +1,93 @@
+import { getStoredToken } from "./auth-store.js";
+import { cliApiError } from "./cli-api-error.js";
+import { CliError, ERR, notLoggedIn } from "./errors.js";
+import { apiUrl, backoffTransport, fetchWithCliHeaders, parseJsonSafely, rethrowTransport, } from "./http.js";
+import { findEnvspotLink } from "./paths.js";
+import { isHeadlessToken } from "./token-kind.js";
+/** Bearer signing tolerates this much clock skew; past it, auth gets flaky. */
+const CLOCK_SKEW_TOLERANCE_MS = 5 * 60 * 1000;
+/** Mask a stored token for display: kind prefix + a few chars, rest hidden.
+ *  The server never sees plaintext, so the prefix is computed here. */
+export function maskToken(token) {
+    // A short/corrupt credential must not print in full behind a fake mask.
+    if (token.length <= 10)
+        return "••••";
+    return `${token.slice(0, 10)}••••`;
+}
+/** E0074 warning when the server's `Date` header drifts past tolerance from the
+ *  local clock, or null when in range / the header is missing or unparseable. */
+export function clockSkewWarning(serverDateHeader, nowMs) {
+    if (!serverDateHeader)
+        return null;
+    const serverMs = Date.parse(serverDateHeader);
+    if (Number.isNaN(serverMs))
+        return null;
+    const skewMs = nowMs - serverMs;
+    if (Math.abs(skewMs) <= CLOCK_SKEW_TOLERANCE_MS)
+        return null;
+    const minutes = Math.round(Math.abs(skewMs) / 60_000);
+    return (`warning[E0074]: System clock differs from envspot.com by ${minutes}m ` +
+        `(local: ${new Date(nowMs).toISOString()}, server: ${new Date(serverMs).toISOString()}).\n` +
+        `  help: Bearer signing tolerates 5 minutes of skew; past that, expect intermittent auth failures. Ensure NTP is running.\n` +
+        `  docs: https://docs.envspot.com/errors/E0074`);
+}
+function titleCaseTier(tier) {
+    return tier.length ? tier[0].toUpperCase() + tier.slice(1) : tier;
+}
+/** Render the human-readable whoami block. Pure: the caller resolves the local
+ *  link so this never touches the filesystem. */
+export function formatWhoami(data, token, link) {
+    const named = data.user.name ? ` (${data.user.name})` : "";
+    const lines = [
+        `Signed in as ${data.user.email}${named}`,
+        `Workspace:   ${data.org.slug} (${titleCaseTier(data.org.tier)})`,
+    ];
+    if (isHeadlessToken(token)) {
+        // A headless token carries its own project + env + scope binding; that is
+        // the authoritative "where am I pointed", so it lives on the Token line.
+        lines.push(`Token:       ${maskToken(token)} (project: ${data.project?.slug ?? "unknown"} · env: ${data.project?.env ?? "?"} · scope: ${data.scope ?? "?"})`);
+    }
+    else {
+        lines.push(`Active link: ${link ? `${link.projectId} · ${link.environment}  (from ./.envspot.json)` : "none  (run `envspot link`)"}`);
+        lines.push(`Token:       ${maskToken(token)} (CLI session, no scope restriction)`);
+    }
+    return lines.join("\n");
+}
+/** `envspot whoami` — print the bound user + workspace (and, for a headless
+ *  token, its project/env/scope). `nowMs` is injectable for deterministic
+ *  clock-skew tests. */
+export async function executeWhoami(opts, nowMs = Date.now()) {
+    const token = await getStoredToken();
+    if (!token)
+        throw notLoggedIn();
+    let res;
+    try {
+        res = await backoffTransport(async () => fetchWithCliHeaders(apiUrl("/api/cli/whoami"), { method: "GET" }, token));
+    }
+    catch (e) {
+        rethrowTransport(e);
+    }
+    const analyzed = await parseJsonSafely(res);
+    if (!res.ok)
+        throw await cliApiError(res.status, analyzed.json);
+    // A 200 with an empty or non-JSON body (proxy page, truncated response) would
+    // otherwise null-deref in formatWhoami or print "null" under --json.
+    const data = analyzed.json;
+    if (!data || typeof data.user !== "object" || data.user === null) {
+        throw new CliError(ERR.UNEXPECTED, "Malformed response from envspot (expected whoami JSON).");
+    }
+    // Emit the skew warning before the --json early return: CI uses --json, and
+    // that is exactly where clock skew silently breaks bearer auth. It goes to
+    // stderr, so it never pollutes the JSON on stdout.
+    const warning = clockSkewWarning(res.headers.get("date"), nowMs);
+    if (warning)
+        console.error(warning);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(data)}\n`);
+        return;
+    }
+    const link = isHeadlessToken(token)
+        ? null
+        : (findEnvspotLink(process.cwd())?.link ?? null);
+    console.log(formatWhoami(data, token, link));
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "envspot",
+  "version": "0.1.0",
+  "description": "CLI for envspot — encrypted environment variables for your team",
+  "license": "MIT",
+  "author": "EnvSpot",
+  "homepage": "https://envspot.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EnvSpot/envspot.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/EnvSpot/envspot/issues"
+  },
+  "keywords": [
+    "envspot",
+    "env",
+    "environment-variables",
+    "secrets",
+    "secrets-management",
+    "dotenv",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "envspot": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "keytar": "^7.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0"
+  }
+}