enylock_cli 1.0.0

package/README.md

@@ -0,0 +1,238 @@
+# EnvLock
+
+[![npm version](https://img.shields.io/npm/v/envlock.svg?style=flat-rounded)](https://www.npmjs.com/package/envlock)
+[![npm downloads](https://img.shields.io/npm/dm/envlock.svg?style=flat-rounded)](https://www.npmjs.com/package/envlock)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+EnvLock is a secrets management system for development teams. It consists of a web dashboard, where projects and secrets are organized and controlled, and a command-line tool, which developers use to bring those secrets onto their own machines. It replaces the common practice of sharing `.env` files over chat or email with a controlled, auditable alternative.
+
+---
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation--usage)
+- [Getting Started](#getting-started)
+- [CLI Command Reference](#cli-command-reference)
+- [Security](#security)
+- [Contributing](#contributing)
+- [Support & Links](#support--links)
+
+---
+
+## How It Works
+
+EnvLock is made up of two parts that work together: a dashboard and a CLI.
+
+### The Dashboard
+
+The dashboard, at envlock.app, is where a project actually lives. From there, a project owner can:
+
+- Create a project and invite team members, assigning each person a role (owner, admin, member, or viewer).
+- Define environments within that project, typically development, staging, and production, each holding its own independent set of secrets.
+- Add, edit, and version secrets under any environment.
+- Issue and revoke access tokens, each one scoped to a specific project and to specific environments within it.
+
+Every change made on the dashboard is recorded in an audit log, so a team can see who added or modified a secret, and when.
+
+### The CLI
+
+The CLI is what a developer uses day to day, once a project has already been set up on the dashboard. Running `envlock login` opens a browser window where the developer approves access to a specific project and, depending on the role granted, specific environments within it. That approval only needs to happen once per project folder. After that, secrets can be pulled into a local `.env` file, or injected directly into a running process, without opening the dashboard again.
+
+In short: the dashboard is where secrets are organized and controlled, and the CLI is how they reach a developer's machine.
+
+---
+
+## Features
+
+- Authentication through a browser-based device authorization flow, rather than pasted API keys.
+- Access tokens scoped to a single project and specific environments, so a compromised token cannot expose secrets outside its intended scope.
+- Session credentials stored per project folder, so working on multiple EnvLock projects on the same machine does not cause conflicts.
+- An option to inject secrets directly into a running process's memory, so plaintext values never need to be written to disk.
+- Automatic `.gitignore` configuration on login, to prevent secrets from being committed by mistake.
+- A full audit log on the dashboard, recording who changed which secret and when.
+
+---
+
+## Requirements
+
+- Node.js 18 or later
+- An EnvLock account, created at envlock.app
+
+---
+
+## Installation & Usage
+
+EnvLock can be used in either of two ways.
+
+### Option A: Zero Install
+
+Run commands directly without a global install. This is the recommended path for CI/CD pipelines, such as GitHub Actions:
+
+```bash
+npx envlock login
+npx envlock pull
+```
+
+### Option B: Global Installation
+
+Install once, then run it from anywhere:
+
+```bash
+npm install -g envlock
+
+envlock login
+envlock pull
+```
+
+---
+
+## Getting Started
+
+### 1. Authenticate
+
+Run the login command inside your project directory:
+
+```bash
+envlock login
+```
+
+This will print a user code in your terminal, open your browser to complete approval, and prompt you to choose which project this directory should have access to. Once approved, your local `.gitignore` is updated automatically.
+
+### 2. Pull Secrets
+
+Write your project's secrets to a local `.env` file:
+
+```bash
+envlock pull
+```
+
+Pull from a specific environment:
+
+```bash
+envlock pull --env production
+```
+
+### 3. Run Commands with Secrets Injected
+
+Run your application with secrets passed directly into the process, without writing them to disk:
+
+```bash
+envlock run -- node app.js
+```
+
+Use a different environment:
+
+```bash
+envlock run --env staging -- npm run dev
+```
+
+---
+
+## CLI Command Reference
+
+Every command supports `--help` for details on its arguments and options.
+
+### Global Flags
+
+| Flag            | Description                                    |
+| --------------- | ---------------------------------------------- |
+| `-h, --help`    | Show help for the CLI or a specific subcommand |
+| `-V, --version` | Output the current version number              |
+
+### `envlock login`
+
+Authenticates the current project folder through the device authorization flow: displays a user code, opens the browser, and waits for approval.
+
+```bash
+envlock login
+```
+
+### `envlock pull`
+
+Downloads decrypted secrets and writes them locally as key-value pairs.
+
+| Option                | Description                                         | Default       |
+| --------------------- | --------------------------------------------------- | ------------- |
+| `-e, --env <name>`    | Environment to pull from                            | `development` |
+| `-o, --output <file>` | Target filename to write                            | `.env`        |
+| `--overwrite`         | Allow overwriting a file that already contains keys | `false`       |
+
+```bash
+envlock pull --output .env.local
+envlock pull --env production --overwrite
+```
+
+### `envlock run`
+
+Fetches decrypted secrets in memory and runs a command with them injected. Plaintext values are never written to disk.
+
+| Option             | Description                            | Default       |
+| ------------------ | -------------------------------------- | ------------- |
+| `-e, --env <name>` | Environment to retrieve variables from | `development` |
+
+Place `--` before your target command so its own arguments pass through correctly.
+
+```bash
+envlock run -- node index.js
+envlock run --env production -- npm start
+```
+
+### `envlock whoami`
+
+Shows which project and environment this directory is currently authenticated to.
+
+```bash
+envlock whoami
+```
+
+### `envlock logout`
+
+Removes the local session by deleting the credentials stored in `.envlock/`.
+
+```bash
+envlock logout
+```
+
+### `envlock help`
+
+Lists all available commands with a short description of each.
+
+```bash
+envlock help
+```
+
+---
+
+## Security
+
+- Session tokens stored locally in `.envlock/credentials.json` are saved with owner-only read/write permissions (`0o600`).
+- During login, the server holds an approved token in a pending state and deletes it the moment the CLI retrieves it, so it is never persisted longer than necessary.
+- The CLI ensures `.envlock/` and `.env*` patterns exist in your local `.gitignore`, reducing the chance of secrets being committed by accident.
+
+---
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome.
+
+```bash
+git clone https://github.com/leyroy/envlock_cli.git
+cd envlock_cli
+npm install
+npm link
+```
+
+`npm link` makes your local changes available as the global `envlock` command, so you can test them directly. Open a pull request once your change is ready; for larger changes, opening an issue first to discuss the approach is appreciated.
+
+---
+
+## Support & Links
+
+- Website: envlock.app
+- Repository: github.com/leyroy/envlock_cli
+- Issues: github.com/leyroy/envlock_cli/issues
+- Author: Ley Roy (atiwensolomon@gmail.com)
+- License: MIT

package/bin/envlock.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+// Entry point — delegates to the Commander program in src/index.js
+import "../src/index.js";

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "enylock_cli",
+  "version": "1.0.0",
+  "description": "Encrypted secrets management CLI — pull, run, and manage env vars from EnvLock",
+  "keywords": [
+    "secrets",
+    "env",
+    "dotenv",
+    "cli",
+    "envlock",
+    "security"
+  ],
+  "homepage": "https://envlock.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/enylockapp/envlock-cli"
+  },
+  "author": {
+    "name": "Ley Roy",
+    "email": "atiwensolomon@gmail.com",
+    "url": "https://ley-roy.vercel.app/"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "bin": {
+    "envlock": "./bin/envlock.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "open": "^10.1.0",
+    "ora": "^8.1.1"
+  }
+}

package/src/commands/login.js

@@ -0,0 +1,120 @@
+import chalk from "chalk";
+import ora from "ora";
+import open from "open";
+import { initDevice, pollToken } from "../lib/api.js";
+import { saveCredentials, loadCredentials } from "../lib/credentials.js";
+import { ensureGitignore, detectProjectType } from "../lib/gitignore.js";
+
+const POLL_INTERVAL_MS = 5000;
+
+/**
+ * `envlock login`
+ *
+ * Runs the device authorization flow:
+ *   1. Request a device code from the API
+ *   2. Open the browser to the verification URI
+ *   3. Poll until the user approves or the code expires
+ *   4. Save the token to .envlock/credentials.json
+ */
+export async function loginCommand() {
+  const cwd = process.cwd();
+
+  // Skip if already logged in
+  const existing = loadCredentials(cwd);
+  if (existing?.token) {
+    console.log(
+      chalk.yellow("⚠  Already logged in.") + " Run `envlock logout` first to switch accounts.",
+    );
+    return;
+  }
+
+  let deviceData;
+  try {
+    deviceData = await initDevice();
+  } catch (error) {
+    console.log(error);
+    console.error(chalk.red("✖ Could not reach EnvLock API:"), error.message);
+    process.exit(1);
+  }
+
+  const { device_code, user_code, verification_uri, expires_in, interval } = deviceData;
+  const pollIntervalMs = Math.max((interval ?? 5) * 1000, POLL_INTERVAL_MS);
+
+  console.log();
+  console.log(chalk.bold("  EnvLock CLI Login"));
+  console.log();
+  console.log("  1. Your browser will open to:");
+  console.log("     " + chalk.cyan(verification_uri));
+  console.log();
+  console.log("  2. Enter this code when prompted:");
+  console.log("     " + chalk.bold.green(user_code));
+  console.log();
+  console.log(chalk.dim(`  Code expires in ${Math.round(expires_in / 60)} minutes.`));
+  console.log();
+
+  // Attempt to open browser; non-fatal if it fails
+  try {
+    await open(`${verification_uri}?code=${encodeURIComponent(user_code)}`);
+  } catch {
+    console.log(chalk.dim("  (Could not open browser automatically — please open the URL above)"));
+  }
+
+  const spinner = ora("Waiting for browser approval…").start();
+
+  const deadline = Date.now() + expires_in * 1000;
+
+  // Poll until approved, denied, or expired
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs);
+
+    try {
+      const result = await pollToken(device_code);
+
+      if (result.status === "authorization_pending") {
+        continue; // still waiting
+      }
+
+      if (result.status === "approved" && result.access_token) {
+        spinner.succeed(chalk.green("Logged in successfully!"));
+
+        saveCredentials(cwd, {
+          token: result.access_token,
+          loggedInAt: new Date().toISOString(),
+        });
+
+        // Ensure .gitignore is updated
+        const added = ensureGitignore(cwd);
+        if (added.length > 0) {
+          console.log(chalk.dim(`  Added to .gitignore: ${added.join(", ")}`));
+        }
+
+        const projectType = detectProjectType(cwd);
+        if (projectType) {
+          console.log(chalk.dim(`  Detected ${projectType} project.`));
+        }
+
+        console.log();
+        console.log(chalk.bold("  Next steps:"));
+        console.log("    " + chalk.cyan("envlock pull") + " — write secrets to .env");
+        console.log(
+          "    " + chalk.cyan("envlock run -- <cmd>") + " — run a command with secrets injected",
+        );
+        console.log();
+        return;
+      }
+    } catch (err) {
+      if (err.status === 400 && (err.body?.error === "denied" || err.body?.error === "expired")) {
+        break;
+      }
+      // Transient network error — keep polling
+    }
+  }
+
+  spinner.fail(chalk.red("Login timed out or was denied."));
+  console.log("  Run `envlock login` to try again.");
+  process.exit(1);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/commands/logout.js

@@ -0,0 +1,24 @@
+import chalk from "chalk";
+import { clearCredentials, loadCredentials } from "../lib/credentials.js";
+
+/**
+ * `envlock logout`
+ *
+ * Removes the local credentials file from .envlock/credentials.json.
+ * The access token on the server is NOT revoked — this is intentional so
+ * automated pipelines that share the same token can continue running.
+ * To fully revoke, use the EnvLock dashboard.
+ */
+export function logoutCommand() {
+  const cwd = process.cwd();
+  const existing = loadCredentials(cwd);
+
+  if (!existing?.token) {
+    console.log(chalk.yellow("Not currently logged in for this directory."));
+    return;
+  }
+
+  clearCredentials(cwd);
+  console.log(chalk.green("✔ Logged out.") + " Credentials removed from .envlock/credentials.json");
+  console.log(chalk.dim("  Note: To fully revoke the token, visit the EnvLock dashboard."));
+}

package/src/commands/pull.js

@@ -0,0 +1,82 @@
+import { writeFileSync, readFileSync, existsSync } from "fs";
+import chalk from "chalk";
+import ora from "ora";
+import { fetchSecrets } from "../lib/api.js";
+import { requireCredentials } from "../lib/credentials.js";
+
+/**
+ * `envlock pull [--env <name>] [--output <file>] [--overwrite]`
+ *
+ * Fetches decrypted secrets from the EnvLock API and writes them to a .env file.
+ *
+ * @param {object} options
+ * @param {string} options.env        - Environment name (default: "development")
+ * @param {string} options.output     - Output file path (default: ".env")
+ * @param {boolean} options.overwrite - If false and the file exists, exit with a warning
+ */
+export async function pullCommand(options = {}) {
+  const cwd = process.cwd();
+  const creds = requireCredentials(cwd);
+
+  const environmentName = options.env ?? "development";
+  const outputFile = options.output ?? ".env";
+  const overwrite = options.overwrite ?? false;
+
+  // Guard against accidentally overwriting an existing file
+  if (!overwrite && existsSync(outputFile)) {
+    const existing = readFileSync(outputFile, "utf8").trim();
+    if (existing.length > 0) {
+      console.log(chalk.yellow(`⚠  ${outputFile} already exists.`) + " Use --overwrite to replace it.");
+      process.exit(1);
+    }
+  }
+
+  const spinner = ora(`Pulling ${chalk.bold(environmentName)} secrets…`).start();
+
+  let result;
+  try {
+    result = await fetchSecrets(creds.token, environmentName);
+  } catch (err) {
+    spinner.fail(chalk.red("Failed to fetch secrets"));
+    if (err.status === 401) {
+      console.error("  Token invalid or expired. Run `envlock login` to re-authenticate.");
+    } else if (err.status === 403) {
+      console.error(`  Access denied for the "${environmentName}" environment.`);
+    } else if (err.status === 404) {
+      console.error(`  Environment "${environmentName}" not found. Check your project settings.`);
+    } else {
+      console.error(" ", err.message);
+    }
+    process.exit(1);
+  }
+
+  const { secrets } = result;
+  const entries = Object.entries(secrets);
+
+  if (entries.length === 0) {
+    spinner.warn(chalk.yellow(`No secrets found in "${environmentName}".`));
+    return;
+  }
+
+  const content =
+    `# Generated by EnvLock — ${new Date().toISOString()}\n` +
+    `# Environment: ${environmentName}\n` +
+    `# DO NOT COMMIT — this file is in .gitignore\n\n` +
+    entries.map(([key, value]) => formatEnvLine(key, value)).join("\n") +
+    "\n";
+
+  writeFileSync(outputFile, content, "utf8");
+  spinner.succeed(
+    chalk.green(`✔ Wrote ${entries.length} secret${entries.length !== 1 ? "s" : ""}`) +
+      ` to ${chalk.bold(outputFile)}`
+  );
+}
+
+/**
+ * Formats a key=value pair, quoting the value if it contains spaces or special chars.
+ */
+function formatEnvLine(key, value) {
+  const needsQuotes = /[\s"'\\#$`]/.test(value) || value === "";
+  const escaped = needsQuotes ? `"${value.replace(/"/g, '\\"')}"` : value;
+  return `${key}=${escaped}`;
+}

package/src/commands/run.js

@@ -0,0 +1,65 @@
+import { spawn } from "child_process";
+import chalk from "chalk";
+import ora from "ora";
+import { fetchSecrets } from "../lib/api.js";
+import { requireCredentials } from "../lib/credentials.js";
+
+/**
+ * `envlock run [--env <name>] -- <command> [...args]`
+ *
+ * Injects decrypted secrets as environment variables and spawns a command.
+ * Secrets never touch the filesystem — they live only in the child process env.
+ *
+ * @param {string[]} args      - Command and its arguments (everything after --)
+ * @param {object}   options
+ * @param {string}   options.env  - Environment name (default: "development")
+ */
+export async function runCommand(args, options = {}) {
+  if (!args || args.length === 0) {
+    console.error(chalk.red("✖ No command provided."));
+    console.error("  Usage: envlock run [--env <name>] -- <command> [args...]");
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const creds = requireCredentials(cwd);
+  const environmentName = options.env ?? "development";
+
+  const spinner = ora(`Loading ${chalk.bold(environmentName)} secrets…`).start();
+
+  let secrets;
+  try {
+    const result = await fetchSecrets(creds.token, environmentName);
+    secrets = result.secrets;
+  } catch (err) {
+    spinner.fail(chalk.red("Failed to fetch secrets"));
+    if (err.status === 401) {
+      console.error("  Token invalid or expired. Run `envlock login` to re-authenticate.");
+    } else {
+      console.error(" ", err.message);
+    }
+    process.exit(1);
+  }
+
+  spinner.stop();
+
+  const [cmd, ...cmdArgs] = args;
+
+  // Merge fetched secrets into the current process environment
+  const childEnv = { ...process.env, ...secrets };
+
+  const child = spawn(cmd, cmdArgs, {
+    stdio: "inherit",
+    env: childEnv,
+    shell: process.platform === "win32", // shell required on Windows for built-ins
+  });
+
+  child.on("error", (err) => {
+    console.error(chalk.red(`✖ Failed to start command: ${err.message}`));
+    process.exit(1);
+  });
+
+  child.on("close", (code) => {
+    process.exit(code ?? 0);
+  });
+}

package/src/commands/whoami.js

@@ -0,0 +1,32 @@
+import chalk from "chalk";
+import { loadCredentials } from "../lib/credentials.js";
+
+/**
+ * `envlock whoami`
+ *
+ * Displays information about the currently stored credentials.
+ */
+export function whoamiCommand() {
+  const cwd = process.cwd();
+  const creds = loadCredentials(cwd);
+
+  if (!creds?.token) {
+    console.log(chalk.yellow("Not logged in.") + " Run `envlock login` to authenticate.");
+    return;
+  }
+
+  const tokenPreview =
+    creds.token.length > 16
+      ? creds.token.slice(0, 12) + "…" + creds.token.slice(-4)
+      : creds.token;
+
+  console.log();
+  console.log(chalk.bold("  Logged in"));
+  console.log();
+  console.log("  Token:    " + chalk.cyan(tokenPreview));
+  if (creds.loggedInAt) {
+    console.log("  Since:    " + new Date(creds.loggedInAt).toLocaleString());
+  }
+  console.log("  Scope:    " + chalk.dim(process.cwd()));
+  console.log();
+}

package/src/index.js

@@ -0,0 +1,66 @@
+import { Command } from "commander";
+import { loginCommand } from "./commands/login.js";
+import { logoutCommand } from "./commands/logout.js";
+import { pullCommand } from "./commands/pull.js";
+import { runCommand } from "./commands/run.js";
+import { whoamiCommand } from "./commands/whoami.js";
+
+const program = new Command();
+
+program
+  .name("envlock")
+  .description("Encrypted secrets management — pull, run, and manage env vars securely")
+  .version("1.0.0")
+  .enablePositionalOptions();
+
+
+program
+  .command("login")
+  .description("Authenticate via browser and store credentials for this project directory")
+  .action(loginCommand);
+
+program
+  .command("logout")
+  .description("Remove stored credentials from .envlock/credentials.json")
+  .action(logoutCommand);
+
+program
+  .command("pull")
+  .description("Fetch secrets from EnvLock and write them to a .env file")
+  .option("-e, --env <name>", "environment to pull (e.g. production, staging)", "development")
+  .option("-o, --output <file>", "output file path", ".env")
+  .option("--overwrite", "overwrite the output file if it already exists", false)
+  .action(pullCommand);
+
+program
+  .command("run")
+  .description("Run a command with secrets injected as environment variables (secrets never touch disk)")
+  .option("-e, --env <name>", "environment to load secrets from", "development")
+  .passThroughOptions()
+  .argument("[args...]", "command and arguments to run (after --)")
+  .addHelpText(
+    "after",
+    `
+Examples:
+  envlock run -- node server.js
+  envlock run --env production -- npm start
+`
+  )
+  .action((args, options) => {
+    // Strip leading "--" separator if Commander passes it through
+    const cleanArgs = args[0] === "--" ? args.slice(1) : args;
+    return runCommand(cleanArgs, options);
+  });
+
+
+program
+  .command("whoami")
+  .description("Show current authentication status and token info")
+  .action(whoamiCommand);
+
+program
+  .command("help", { isDefault: false, hidden: true })
+  .description("Show help information")
+  .action(() => program.help());
+
+program.parse(process.argv);

package/src/lib/api.js

@@ -0,0 +1,81 @@
+// Thin fetch wrapper for the EnvLock API.
+// BASE_URL defaults to production; override with ENVLOCK_API_URL for local dev.
+
+const BASE_URL = (process.env.ENVLOCK_API_URL ?? "https://envlock.app").replace(/\/$/, "");
+
+/**
+ * Generic JSON fetch with error normalisation.
+ * Returns the parsed response body on success; throws on non-2xx.
+ */
+async function apiFetch(path, options = {}) {
+  const url = `${BASE_URL}${path}`;
+  const res = await fetch(url, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...(options.headers ?? {}),
+    },
+  });
+
+  const body = await res.json().catch(() => ({}));
+
+  if (!res.ok) {
+    const message = body.error ?? `HTTP ${res.status}`;
+    const err = new Error(message);
+    err.status = res.status;
+    err.body = body;
+    throw err;
+  }
+
+  return body;
+}
+
+/**
+ * POST /api/cli/device/init
+ * Returns { device_code, user_code, verification_uri, expires_in, interval }
+ */
+export function initDevice() {
+  return apiFetch("/api/cli/device/init", {
+    method: "POST",
+    body: JSON.stringify({ client_id: "envlock-cli", scopes: "secrets:read" }),
+  });
+}
+
+/**
+ * POST /api/cli/device/token
+ * Returns { status: "approved", access_token } on success,
+ *         { status: "authorization_pending" } (428) while waiting,
+ *         or throws on denied / expired.
+ */
+export async function pollToken(deviceCode) {
+  const res = await fetch(`${BASE_URL}/api/cli/device/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ device_code: deviceCode }),
+  });
+
+  const body = await res.json().catch(() => ({}));
+
+  if (res.status === 428) {
+    // Still waiting for user to approve in browser
+    return { status: "authorization_pending" };
+  }
+
+  if (!res.ok) {
+    const err = new Error(body.error ?? `HTTP ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+
+  return body; // { status: "approved", access_token: "..." }
+}
+
+/**
+ * GET /api/cli/secrets?environment=<env>
+ * Returns { secrets: Record<string,string>, environment: string }
+ */
+export function fetchSecrets(token, environment = "development") {
+  return apiFetch(`/api/cli/secrets?environment=${encodeURIComponent(environment)}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+}

package/src/lib/credentials.js

@@ -0,0 +1,63 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from "fs";
+import { join } from "path";
+
+const ENVLOCK_DIR = ".envlock";
+const CREDENTIALS_FILE = "credentials.json";
+
+/**
+ * Returns the full path to .envlock/credentials.json relative to the given cwd.
+ */
+function credentialsPath(cwd) {
+  return join(cwd, ENVLOCK_DIR, CREDENTIALS_FILE);
+}
+
+/**
+ * Loads stored credentials from .envlock/credentials.json.
+ * Returns null if the file doesn't exist or is malformed.
+ */
+export function loadCredentials(cwd = process.cwd()) {
+  const filePath = credentialsPath(cwd);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persists credentials to .envlock/credentials.json, creating the directory
+ * if needed. Writes with mode 0o600 so only the owner can read it.
+ */
+export function saveCredentials(cwd = process.cwd(), data) {
+  const dir = join(cwd, ENVLOCK_DIR);
+  mkdirSync(dir, { recursive: true });
+  const filePath = join(dir, CREDENTIALS_FILE);
+  writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600, encoding: "utf8" });
+}
+
+/**
+ * Removes the credentials file. Ignores errors if the file doesn't exist.
+ */
+export function clearCredentials(cwd = process.cwd()) {
+  const filePath = credentialsPath(cwd);
+  if (existsSync(filePath)) {
+    try {
+      rmSync(filePath);
+    } catch {
+      // Non-fatal — the file may have already been removed
+    }
+  }
+}
+
+/**
+ * Returns credentials or throws a user-friendly error instructing login.
+ */
+export function requireCredentials(cwd = process.cwd()) {
+  const creds = loadCredentials(cwd);
+  if (!creds?.token) {
+    console.error("Not logged in. Run `envlock login` first.");
+    process.exit(1);
+  }
+  return creds;
+}

package/src/lib/gitignore.js

@@ -0,0 +1,52 @@
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+
+const GITIGNORE_FILE = ".gitignore";
+
+// Entries that envlock ensures are present in .gitignore
+const REQUIRED_ENTRIES = [".envlock/", ".env", ".env.*", "!.env.example"];
+
+/**
+ * Detects the project language/ecosystem from common config files.
+ * Used only for informational messaging — gitignore logic is the same regardless.
+ */
+function detectProjectType(cwd) {
+  const markers = {
+    "package.json": "Node.js",
+    "go.mod": "Go",
+    "Cargo.toml": "Rust",
+    "requirements.txt": "Python",
+    "pyproject.toml": "Python",
+    "composer.json": "PHP",
+    Gemfile: "Ruby",
+  };
+  for (const [file, lang] of Object.entries(markers)) {
+    if (existsSync(join(cwd, file))) return lang;
+  }
+  return null;
+}
+
+/**
+ * Ensures .envlock/ and common .env patterns are in .gitignore.
+ * Creates the file if it doesn't exist. Only appends missing entries.
+ * Returns an array of the entries that were actually added.
+ */
+export function ensureGitignore(cwd = process.cwd()) {
+  const gitignorePath = join(cwd, GITIGNORE_FILE);
+  const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+  const lines = existing.split("\n").map((l) => l.trim());
+
+  const missing = REQUIRED_ENTRIES.filter((entry) => !lines.includes(entry));
+  if (missing.length === 0) return [];
+
+  const section = [
+    "",
+    "# EnvLock — secrets management",
+    ...missing,
+  ].join("\n");
+
+  writeFileSync(gitignorePath, existing.trimEnd() + section + "\n", "utf8");
+  return missing;
+}
+
+export { detectProjectType };