envpass-cli 0.0.0-stage → 0.1.6

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# envpass-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client library and CLI for [envpass](https://envpass.dev): encrypted environment variables for every project, service and environment.
+
+## CLI
+
+```bash
+bunx envpass-cli login                         # sign in through your browser
+bunx envpass-cli link -w acme -p shop -e dev   # save defaults to .envpass.json (no secrets inside)
+bunx envpass-cli pull                          # write .env
+bunx envpass-cli pull -e prod -o -             # print to stdout
+bunx envpass-cli run -e dev -- bun dev         # run with values injected, masked in output
+```
+
+`npx envpass-cli …` works the same way.
+
+In CI, use a service token instead of `login`:
+
+```bash
+ENVPASS_TOKEN=ep_live_… npx envpass-cli pull -e prod
+```
+
+| Option | Environment variable | |
+|---|---|---|
+| `-w, --workspace` | `ENVPASS_WORKSPACE` | Workspace slug (not needed with a service token) |
+| `-p, --project` | `ENVPASS_PROJECT` | Project slug (not needed with a service token) |
+| `-e, --env` | `ENVPASS_ENV` | Environment slug |
+| `-s, --service` | `ENVPASS_SERVICE` | Service slug, or `shared` |
+| `--url` | `ENVPASS_URL` | Server, default `https://envpass.dev` |
+| | `ENVPASS_TOKEN` | Service token or CLI session token |
+
+## Library
+
+```ts
+import { createEnvpass, loadEnv } from "envpass-cli"
+
+await loadEnv({ environment: "prod" })
+
+const envpass = createEnvpass({ token: process.env.ENVPASS_TOKEN })
+const entries = await envpass.resolve({ environment: "prod", service: "api" })
+
+const { data } = await envpass.api.GET("/api/v1/workspaces")
+```
+
+`envpass.api` is a fully typed client for the whole REST API, generated from the OpenAPI spec.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { parseArgs } from "node:util";
+import { createEnvpass, EnvpassError } from "./client.js";
+import { baseUrl, forgetToken, resolveScope, saveToken, storedToken, writeProjectLink, } from "./config.js";
+import { deviceLogin, openBrowser } from "./device.js";
+import { maskingStream } from "./mask.js";
+const { version } = createRequire(import.meta.url)("../package.json");
+const HELP = `envpass ${version}: encrypted environment variables for every project, service and environment
+
+Usage
+  envpass login                      Sign in through your browser
+  envpass logout                     Forget the saved login
+  envpass whoami                     Show who the current token belongs to
+  envpass link -w <ws> -p <project>  Save defaults to .envpass.json in this directory
+  envpass pull [-e env] [-o .env]    Write resolved values to a file ("-" for stdout)
+  envpass run [-e env] -- <command>  Run a command with the values injected
+
+Options
+  -w, --workspace <slug>   Workspace (not needed with a service token)
+  -p, --project <slug>     Project (not needed with a service token)
+  -e, --env <slug>         Environment, e.g. dev or prod
+  -s, --service <slug>     Service layer, or "shared"
+  -o, --out <file>         pull: output file (default .env)
+  -f, --format <format>    pull: dotenv, shell or json (default dotenv)
+      --no-mask            run: show secret values in the command's output
+      --no-browser         login: print the link instead of opening a browser
+      --url <url>          envpass server (default https://envpass.dev, or ENVPASS_URL)
+
+Environment
+  ENVPASS_TOKEN            A service token (ep_live_…) or CLI session token
+  ENVPASS_WORKSPACE, ENVPASS_PROJECT, ENVPASS_ENV, ENVPASS_SERVICE
+`;
+function fail(message, code = 1) {
+    process.stderr.write(`envpass: ${message}\n`);
+    process.exit(code);
+}
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            workspace: { type: "string", short: "w" },
+            project: { type: "string", short: "p" },
+            env: { type: "string", short: "e" },
+            service: { type: "string", short: "s" },
+            out: { type: "string", short: "o" },
+            format: { type: "string", short: "f" },
+            url: { type: "string" },
+            "no-mask": { type: "boolean" },
+            "no-browser": { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+        },
+    });
+    const [command, ...rest] = positionals;
+    if (values.version)
+        return void process.stdout.write(`${version}\n`);
+    if (values.help || !command || command === "help")
+        return void process.stdout.write(HELP);
+    const url = baseUrl(values.url);
+    const flags = {
+        workspace: values.workspace,
+        project: values.project,
+        environment: values.env,
+        service: values.service,
+    };
+    switch (command) {
+        case "login": {
+            const token = await deviceLogin(url, (code) => {
+                const link = code.verification_uri_complete ?? code.verification_uri;
+                process.stderr.write(`\nOpen ${link}\nand confirm the code: ${code.user_code}\n\nWaiting for approval…\n`);
+                if (!values["no-browser"])
+                    openBrowser(link);
+            });
+            const path = saveToken(url, token);
+            const me = await createEnvpass({ baseUrl: url, token }).me();
+            process.stderr.write(`Signed in. Token saved to ${path}\n`);
+            if (me.workspaces.length) {
+                process.stderr.write(`Workspaces: ${me.workspaces.map((w) => w.slug).join(", ")}\n`);
+            }
+            return;
+        }
+        case "logout": {
+            const token = storedToken(url);
+            if (token) {
+                await fetch(`${url}/api/auth/sign-out`, {
+                    method: "POST",
+                    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+                    body: "{}",
+                }).catch(() => undefined);
+            }
+            const removed = forgetToken(url);
+            process.stderr.write(removed ? `Signed out of ${url}\n` : `No saved login for ${url}\n`);
+            return;
+        }
+        case "whoami": {
+            const client = createEnvpass({ baseUrl: url });
+            if (!client.hasToken)
+                fail("Not signed in. Run `envpass login` or set ENVPASS_TOKEN.");
+            const me = await client.me();
+            if (me.token) {
+                process.stdout.write(`Service token ${me.token.id} (${me.token.access}) for project ${me.token.projectId}\n`);
+            }
+            else {
+                process.stdout.write(`User ${me.userId}\n`);
+                for (const ws of me.workspaces)
+                    process.stdout.write(`  ${ws.slug}${ws.isOwner ? " (owner)" : ""}\n`);
+            }
+            return;
+        }
+        case "link": {
+            const scope = resolveScope(flags);
+            if (!scope.workspace || !scope.project)
+                fail("Pass --workspace and --project.");
+            const path = writeProjectLink(scope);
+            process.stderr.write(`Saved ${path}. It holds no secrets and is safe to commit.\n`);
+            return;
+        }
+        case "pull": {
+            const format = (values.format ?? "dotenv");
+            if (!["dotenv", "shell", "json"].includes(format))
+                fail("--format must be dotenv, shell or json");
+            const client = createEnvpass({ baseUrl: url });
+            if (!client.hasToken)
+                fail("Not signed in. Run `envpass login` or set ENVPASS_TOKEN.");
+            const text = format === "json"
+                ? `${JSON.stringify(Object.fromEntries((await client.resolve(flags)).map((e) => [e.key, e.value])), null, 2)}\n`
+                : await client.resolveText(flags, format);
+            const out = values.out ?? ".env";
+            if (out === "-")
+                return void process.stdout.write(text);
+            writeFileSync(out, text, { mode: 0o600 });
+            const count = text
+                .split("\n")
+                .filter((line) => line.includes("=") || line.includes(":")).length;
+            process.stderr.write(`Wrote ${out} (${count} values). Keep it out of git.\n`);
+            return;
+        }
+        case "run": {
+            const separator = argv.indexOf("--");
+            const commandArgs = separator === -1 ? rest : argv.slice(separator + 1);
+            const [program, ...programArgs] = commandArgs;
+            if (!program)
+                fail("Usage: envpass run [-e env] -- <command> [args…]");
+            const client = createEnvpass({ baseUrl: url });
+            if (!client.hasToken)
+                fail("Not signed in. Run `envpass login` or set ENVPASS_TOKEN.");
+            const entries = await client.resolve(flags);
+            const env = { ...process.env, ...Object.fromEntries(entries.map((e) => [e.key, e.value])) };
+            const mask = !values["no-mask"];
+            const child = spawn(program, programArgs, {
+                env,
+                stdio: mask ? ["inherit", "pipe", "pipe"] : "inherit",
+            });
+            if (mask) {
+                const secrets = entries.map((e) => e.value);
+                child.stdout?.pipe(maskingStream(secrets)).pipe(process.stdout);
+                child.stderr?.pipe(maskingStream(secrets)).pipe(process.stderr);
+            }
+            for (const signal of ["SIGINT", "SIGTERM"]) {
+                process.on(signal, () => child.kill(signal));
+            }
+            child.on("error", (error) => fail(`Could not start ${program}: ${error.message}`, 127));
+            child.on("exit", (code, signal) => {
+                if (signal)
+                    process.kill(process.pid, signal);
+                else
+                    process.exit(code ?? 0);
+            });
+            return;
+        }
+        default:
+            fail(`Unknown command "${command}". Run \`envpass --help\`.`);
+    }
+}
+main(process.argv.slice(2)).catch((error) => {
+    if (error instanceof EnvpassError)
+        fail(`${error.message}${error.code ? ` (${error.code})` : ""}`);
+    fail(error instanceof Error ? error.message : String(error));
+});

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import { type ProjectLink } from "./config.js";
+import type { components, paths } from "./schema.js";
+export type Source = components["schemas"]["SecretSource"];
+export type ResolvedEntry = {
+    key: string;
+    value: string;
+    source: Source;
+};
+export type ExportFormat = "dotenv" | "json" | "shell";
+export type EnvpassOptions = {
+    baseUrl?: string;
+    token?: string;
+    userAgent?: string;
+};
+export declare class EnvpassError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+export declare function createEnvpass(options?: EnvpassOptions): {
+    url: string;
+    hasToken: boolean;
+    api: import("openapi-fetch").Client<paths, `${string}/${string}`>;
+    me(): Promise<{
+        actor: "user" | "token";
+        userId: string;
+        token: {
+            id: string;
+            workspaceId: string;
+            projectId: string;
+            serviceId: string | null;
+            access: "read" | "write";
+        } | null;
+        workspaces: {
+            id: string;
+            name: string;
+            slug: string;
+            isOwner: boolean;
+        }[];
+    }>;
+    resolve(scope?: ProjectLink): Promise<ResolvedEntry[]>;
+    resolveText(scope?: ProjectLink, format?: Exclude<ExportFormat, "json">): Promise<string>;
+};
+export type Envpass = ReturnType<typeof createEnvpass>;
+export declare function loadEnv(scope?: ProjectLink & EnvpassOptions & {
+    override?: boolean;
+}): Promise<{
+    [k: string]: string;
+}>;

package/dist/client.js

@@ -0,0 +1,81 @@
+import createFetchClient from "openapi-fetch";
+import { baseUrl, resolveScope, resolveToken } from "./config.js";
+export class EnvpassError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "EnvpassError";
+    }
+}
+function errorFrom(status, body) {
+    const error = body?.error;
+    return new EnvpassError(error?.message ?? `Request failed with status ${status}`, status, error?.code);
+}
+export function createEnvpass(options = {}) {
+    const url = baseUrl(options.baseUrl);
+    const token = resolveToken(url, options.token);
+    const headers = { "user-agent": options.userAgent ?? "envpass-node" };
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    const api = createFetchClient({ baseUrl: url, headers });
+    function scopeQuery(scope) {
+        if (!scope.environment) {
+            throw new EnvpassError("No environment. Pass --env, set ENVPASS_ENV, or run `envpass link`.", 400, "invalid");
+        }
+        return {
+            workspace: scope.workspace,
+            project: scope.project,
+            environment: scope.environment,
+            service: scope.service,
+        };
+    }
+    return {
+        url,
+        hasToken: Boolean(token),
+        api,
+        async me() {
+            const { data, error, response } = await api.GET("/api/v1/me");
+            if (!data)
+                throw errorFrom(response.status, error);
+            return data;
+        },
+        async resolve(scope = {}) {
+            const query = scopeQuery(resolveScope(scope));
+            const { data, error, response } = await api.GET("/api/v1/resolve", {
+                params: { query: { ...query, format: "json" } },
+            });
+            if (!data || typeof data === "string")
+                throw errorFrom(response.status, error);
+            return data.entries;
+        },
+        async resolveText(scope = {}, format = "dotenv") {
+            const query = scopeQuery(resolveScope(scope));
+            const response = await fetch(`${url}/api/v1/resolve?${new URLSearchParams(Object.entries({ ...query, format }).filter((entry) => Boolean(entry[1])))}`, { headers });
+            const text = await response.text();
+            if (!response.ok) {
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = undefined;
+                }
+                throw errorFrom(response.status, body);
+            }
+            return text;
+        },
+    };
+}
+export async function loadEnv(scope = {}) {
+    const { baseUrl: url, token, userAgent, override = false, ...link } = scope;
+    const client = createEnvpass({ baseUrl: url, token, userAgent });
+    const entries = await client.resolve(link);
+    for (const entry of entries) {
+        if (override || process.env[entry.key] === undefined)
+            process.env[entry.key] = entry.value;
+    }
+    return Object.fromEntries(entries.map((entry) => [entry.key, entry.value]));
+}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_URL = "https://envpass.dev";
+export type ProjectLink = {
+    workspace?: string;
+    project?: string;
+    environment?: string;
+    service?: string;
+};
+export declare function baseUrl(explicit?: string): string;
+export declare function saveToken(url: string, token: string): string;
+export declare function forgetToken(url: string): boolean;
+export declare function storedToken(url: string): string | undefined;
+export declare function resolveToken(url: string, explicit?: string): string | undefined;
+export declare function writeProjectLink(link: ProjectLink, dir?: string): string;
+export declare function resolveScope(flags: ProjectLink, start?: string): ProjectLink;

package/dist/config.js

@@ -0,0 +1,87 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+export const DEFAULT_URL = "https://envpass.dev";
+const PROJECT_FILE = ".envpass.json";
+export function baseUrl(explicit) {
+    return (explicit ?? process.env.ENVPASS_URL ?? DEFAULT_URL).replace(/\/+$/, "");
+}
+function credentialsPath() {
+    const root = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(root, "envpass", "credentials.json");
+}
+function readCredentials() {
+    const path = credentialsPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveToken(url, token) {
+    const path = credentialsPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const credentials = readCredentials();
+    credentials[url] = { token, savedAt: new Date().toISOString() };
+    writeFileSync(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return path;
+}
+export function forgetToken(url) {
+    const path = credentialsPath();
+    const credentials = readCredentials();
+    if (!credentials[url])
+        return false;
+    delete credentials[url];
+    if (Object.keys(credentials).length === 0)
+        rmSync(path, { force: true });
+    else
+        writeFileSync(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    return true;
+}
+export function storedToken(url) {
+    return readCredentials()[url]?.token;
+}
+export function resolveToken(url, explicit) {
+    return explicit ?? process.env.ENVPASS_TOKEN ?? storedToken(url);
+}
+function findProjectFile(start = process.cwd()) {
+    let dir = resolve(start);
+    for (;;) {
+        const candidate = join(dir, PROJECT_FILE);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function readProjectLink(start) {
+    const path = findProjectFile(start);
+    if (!path)
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`${path} is not valid JSON`);
+    }
+}
+export function writeProjectLink(link, dir = process.cwd()) {
+    const path = join(dir, PROJECT_FILE);
+    writeFileSync(path, `${JSON.stringify(link, null, 2)}\n`);
+    return path;
+}
+export function resolveScope(flags, start) {
+    const file = readProjectLink(start);
+    return {
+        workspace: flags.workspace ?? process.env.ENVPASS_WORKSPACE ?? file.workspace,
+        project: flags.project ?? process.env.ENVPASS_PROJECT ?? file.project,
+        environment: flags.environment ?? process.env.ENVPASS_ENV ?? file.environment,
+        service: flags.service ?? process.env.ENVPASS_SERVICE ?? file.service,
+    };
+}

package/dist/device.d.ts

@@ -0,0 +1,13 @@
+type DeviceCode = {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+};
+export declare function openBrowser(url: string): void;
+export declare function deviceLogin(url: string, onCode: (code: DeviceCode) => void, options?: {
+    fetch?: typeof fetch;
+}): Promise<string>;
+export {};

package/dist/device.js

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+const CLI_CLIENT_ID = "envpass-cli";
+export function openBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(command, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        return;
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function deviceLogin(url, onCode, options = {}) {
+    const http = options.fetch ?? fetch;
+    const start = await http(`${url}/api/auth/device/code`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ client_id: CLI_CLIENT_ID }),
+    });
+    if (!start.ok)
+        throw new Error(`Could not start login (${start.status})`);
+    const code = (await start.json());
+    onCode(code);
+    let interval = Math.max(1, code.interval) * 1000;
+    const deadline = Date.now() + code.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval);
+        const poll = await http(`${url}/api/auth/device/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: code.device_code,
+                client_id: CLI_CLIENT_ID,
+            }),
+        });
+        const body = (await poll.json());
+        if (body.access_token)
+            return body.access_token;
+        if (body.error === "authorization_pending")
+            continue;
+        if (body.error === "slow_down") {
+            interval += 5000;
+            continue;
+        }
+        if (body.error === "access_denied")
+            throw new Error("Login was denied in the browser.");
+        if (body.error === "expired_token")
+            throw new Error("The login code expired. Run `envpass login` again.");
+        throw new Error(body.error_description ?? body.error ?? `Login failed (${poll.status})`);
+    }
+    throw new Error("The login code expired. Run `envpass login` again.");
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createEnvpass, type Envpass, EnvpassError, type EnvpassOptions, type ExportFormat, loadEnv, type ResolvedEntry, type Source, } from "./client.js";
+export { DEFAULT_URL, type ProjectLink } from "./config.js";
+export { maskText } from "./mask.js";
+export type { components, paths } from "./schema.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createEnvpass, EnvpassError, loadEnv, } from "./client.js";
+export { DEFAULT_URL } from "./config.js";
+export { maskText } from "./mask.js";

package/dist/mask.d.ts

@@ -0,0 +1,3 @@
+import { Transform } from "node:stream";
+export declare function maskText(text: string, secrets: readonly string[]): string;
+export declare function maskingStream(values: readonly string[]): Transform;

package/dist/mask.js

@@ -0,0 +1,59 @@
+import { Transform } from "node:stream";
+const MASK = "***";
+const MIN_LENGTH = 4;
+export function maskText(text, secrets) {
+    let out = text;
+    for (const secret of secrets) {
+        if (secret.length >= MIN_LENGTH)
+            out = out.split(secret).join(MASK);
+    }
+    return out;
+}
+function partialSuffix(text, secrets) {
+    let longest = 0;
+    for (const secret of secrets) {
+        const max = Math.min(secret.length - 1, text.length);
+        for (let k = max; k > longest; k--) {
+            if (text.endsWith(secret.slice(0, k))) {
+                longest = k;
+                break;
+            }
+        }
+    }
+    return longest;
+}
+export function maskingStream(values) {
+    const secrets = [...new Set(values.filter((v) => v.length >= MIN_LENGTH))].sort((a, b) => b.length - a.length);
+    let pending = "";
+    let timer;
+    const stream = new Transform({
+        transform(chunk, _encoding, callback) {
+            if (timer)
+                clearTimeout(timer);
+            pending = maskText(pending + chunk.toString("utf8"), secrets);
+            const keep = partialSuffix(pending, secrets);
+            const emit = pending.slice(0, pending.length - keep);
+            pending = pending.slice(emit.length);
+            if (emit)
+                this.push(emit);
+            if (pending) {
+                timer = setTimeout(() => {
+                    const rest = pending;
+                    pending = "";
+                    if (rest)
+                        stream.push(rest);
+                }, 100);
+            }
+            callback();
+        },
+        flush(callback) {
+            if (timer)
+                clearTimeout(timer);
+            if (pending)
+                this.push(pending);
+            pending = "";
+            callback();
+        },
+    });
+    return stream;
+}