@jondotsoy/envs 0.0.4 → 0.1.0

package/README.md

@@ -25,11 +25,28 @@ Ejecuta los comandos dentro del repo o de cualquiera de sus worktrees. Dentro de
 | `envs init` | Crea `.envs/`, `.envs/.gitignore` (con `*`) y un `.envs/values.yml` vacío. No sobrescribe archivos existentes. |
 | `envs pull` | Lee el `.env` del repo principal y de cada worktree y lo escribe en `values.yml`. Las variables que ya no están en un `.env` se quitan de `values.yml` para ese worktree. |
 | `envs push` | Escribe `values.yml` en el `.env` de cada worktree. Actualiza las variables existentes en su línea, agrega las nuevas al final y conserva comentarios y variables que no están en `values.yml`. |
+| `envs lint` | Revisa la seguridad y muestra un warning por cada problema. Termina con código 1 si hay alguno (útil en CI). Ver abajo. |
 | `envs edit` | Ejecuta `pull`, abre `values.yml` con `code -w` y, al cerrar el editor, ejecuta `push`. Si el editor falla, no hace `push`. |
 | `envs help` | Muestra la ayuda. |
 
 Los worktrees se identifican por el nombre de su rama (o el nombre de su carpeta si están en HEAD desacoplado). El repo principal usa el nombre de su rama, por ejemplo `main`.
 
+### `envs lint`
+
+Nunca imprime los valores, solo la variable y su ubicación (`envs.DB_PASSWORD.main`).
+
+| Regla | Detecta |
+| --- | --- |
+| `tracked-values`, `unignored-values` | `values.yml` está versionado en git o no está ignorado. |
+| `tracked-dotenv`, `unignored-dotenv` | El `.env` de un worktree está versionado o no está ignorado. |
+| `open-permissions` | `values.yml` es legible por otros usuarios (usa `chmod 600`). |
+| `executable-files` | `values.yml` o un `.env` tiene permiso de ejecución (usa `chmod -x`). |
+| `writable-files` | `values.yml` o un `.env` es escribible por el grupo u otros usuarios (usa `chmod go-w`). |
+| `weak-secret` | Variable sensible (`PASSWORD`, `TOKEN`, `SECRET`, `API_KEY`…) vacía o con un valor típico (`changeme`, `admin`…). |
+| `shared-secret` | Variable sensible en `defaults`, que se escribe en todos los worktrees. |
+| `secret-pattern` | Valor con formato de secreto conocido (AWS, GitHub, Slack, `sk-…`, clave privada). |
+| `url-credentials`, `insecure-url` | URL remota con contraseña embebida, o con `http://`, `ws://` o `ftp://`. |
+
 ## Formato de `values.yml`
 
 ```yaml
@@ -47,7 +64,7 @@ envs:
 
 - `defaults`: valor por defecto de cada variable. `push` lo escribe en el `.env` de todos los worktrees.
 - `envs.<VARIABLE>.<worktree>`: valor de la variable en ese worktree. Sobrescribe al valor de `defaults`.
-- Todos los valores son strings, así que los números van entre comillas (`"3000"`).
+- Los valores pueden ser strings, números o booleanos (`PORT: 3000`, `DEBUG: true`); `push` los escribe en el `.env` como texto (`PORT=3000`, `DEBUG=true`). `pull` convierte `true`/`false` y los números canónicos (`3000`, `0.5`) a booleanos y números; el resto (`007`, `1e3`) queda como string.
 
 El schema (JSON Schema) está en [`schema/values.schema.json`](schema/values.schema.json). Para que VS Code valide el archivo con la extensión YAML, agrega al inicio de `values.yml`:
 

package/envs.js

@@ -4,13 +4,228 @@
 // src/envs.ts
 import { mkdir } from "fs/promises";
 import { basename, dirname, join } from "path";
+import { stat } from "fs/promises";
 var {$ } = globalThis.Bun;
+
+// src/lint-rules.ts
+var SENSITIVE_KEY = /(^|_)(SECRET|PASSWORD|PASSWD|PWD|TOKEN|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY|CREDENTIALS?|AUTH|SALT|SIGNING)(_|$)/i;
+var WEAK_VALUES = new Set([
+  "",
+  "changeme",
+  "change-me",
+  "change_me",
+  "password",
+  "passw0rd",
+  "secret",
+  "admin",
+  "root",
+  "test",
+  "default",
+  "example",
+  "123456",
+  "12345678",
+  "qwerty",
+  "todo",
+  "xxx"
+]);
+var SECRET_PATTERNS = [
+  [/AKIA[0-9A-Z]{16}/, "an AWS access key id"],
+  [/gh[pousr]_[A-Za-z0-9]{36,}/, "a GitHub token"],
+  [/sk-[A-Za-z0-9_-]{20,}/, "an API secret key"],
+  [/xox[abprs]-[A-Za-z0-9-]{10,}/, "a Slack token"],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, "a private key"]
+];
+function isSensitiveKey(key) {
+  return SENSITIVE_KEY.test(key);
+}
+function entries({ values }) {
+  const result = [];
+  for (const [key, value] of Object.entries(values.defaults ?? {})) {
+    result.push({ key, text: String(value), location: `defaults.${key}`, shared: true });
+  }
+  for (const [key, byWorktree] of Object.entries(values.envs ?? {})) {
+    for (const [worktree, value] of Object.entries(byWorktree ?? {})) {
+      result.push({
+        key,
+        text: String(value),
+        location: `envs.${key}.${worktree}`,
+        shared: false
+      });
+    }
+  }
+  return result;
+}
+function parseUrl(text) {
+  const match = text.match(/^([a-z][a-z0-9+.-]*):\/\/([^/\s]*)/i);
+  if (!match)
+    return;
+  const scheme = match[1].toLowerCase();
+  const authority = match[2];
+  const hostname = authority.slice(authority.lastIndexOf("@") + 1).replace(/:\d+$/, "").replace(/^\[|\]$/g, "");
+  return {
+    scheme,
+    hasPassword: /^[^@]*:[^@]+@/.test(authority),
+    local: /^(localhost|127\.\d+\.\d+\.\d+|::1|0\.0\.0\.0)$/.test(hostname)
+  };
+}
+var valuesFile = ".envs/values.yml";
+function envFiles(ctx) {
+  return [
+    { location: valuesFile, mode: ctx.valuesMode },
+    ...ctx.dotenvs.map((d) => ({ location: `${d.name}/.env`, mode: d.mode }))
+  ];
+}
+var rules = [
+  {
+    id: "tracked-values",
+    description: "values.yml is tracked by git.",
+    async check(ctx) {
+      if (!await ctx.isTracked(ctx.root, valuesFile))
+        return [];
+      return [
+        {
+          location: valuesFile,
+          message: "values.yml is tracked by git, so its secrets are in the history. Run `git rm --cached .envs/values.yml`."
+        }
+      ];
+    }
+  },
+  {
+    id: "unignored-values",
+    description: "values.yml is neither tracked nor ignored by git.",
+    async check(ctx) {
+      if (await ctx.isTracked(ctx.root, valuesFile))
+        return [];
+      if (await ctx.isIgnored(ctx.root, valuesFile))
+        return [];
+      return [
+        {
+          location: valuesFile,
+          message: "values.yml is not ignored by git and could be committed by accident. Add `*` to .envs/.gitignore."
+        }
+      ];
+    }
+  },
+  {
+    id: "open-permissions",
+    description: "values.yml is readable by other users.",
+    check({ valuesMode }) {
+      if (valuesMode === undefined || (valuesMode & 63) === 0)
+        return [];
+      return [
+        {
+          location: valuesFile,
+          message: `values.yml is readable by other users (mode ${(valuesMode & 511).toString(8)}). Run \`chmod 600 .envs/values.yml\`.`
+        }
+      ];
+    }
+  },
+  {
+    id: "executable-files",
+    description: "values.yml or a worktree's .env has execute permission.",
+    check: (ctx) => envFiles(ctx).filter((f) => f.mode !== undefined && (f.mode & 73) !== 0).map((f) => ({
+      location: f.location,
+      message: `The file is executable (mode ${(f.mode & 511).toString(8)}); env files are data and must not be. Run \`chmod -x\` on it.`
+    }))
+  },
+  {
+    id: "writable-files",
+    description: "values.yml or a worktree's .env is writable by other users.",
+    check: (ctx) => envFiles(ctx).filter((f) => f.mode !== undefined && (f.mode & 18) !== 0).map((f) => ({
+      location: f.location,
+      message: `The file is writable by group or other users (mode ${(f.mode & 511).toString(8)}), who could change your environment. Run \`chmod go-w\` on it.`
+    }))
+  },
+  {
+    id: "tracked-dotenv",
+    description: "A worktree's .env is tracked by git.",
+    async check(ctx) {
+      const found = [];
+      for (const { name, path } of ctx.dotenvs) {
+        if (!await ctx.isTracked(path, ".env"))
+          continue;
+        found.push({
+          location: `${name}/.env`,
+          message: "The .env is tracked by git. Run `git rm --cached .env` and add it to .gitignore."
+        });
+      }
+      return found;
+    }
+  },
+  {
+    id: "unignored-dotenv",
+    description: "A worktree's .env is neither tracked nor ignored by git.",
+    async check(ctx) {
+      const found = [];
+      for (const { name, path } of ctx.dotenvs) {
+        if (await ctx.isTracked(path, ".env"))
+          continue;
+        if (await ctx.isIgnored(path, ".env"))
+          continue;
+        found.push({
+          location: `${name}/.env`,
+          message: "The .env is not ignored by git. Add `.env` to .gitignore."
+        });
+      }
+      return found;
+    }
+  },
+  {
+    id: "weak-secret",
+    description: "A sensitive variable is empty or has an easily guessed value.",
+    check: (ctx) => entries(ctx).filter((e) => isSensitiveKey(e.key) && WEAK_VALUES.has(e.text.trim().toLowerCase())).map((e) => ({
+      location: e.location,
+      message: `${e.key} has an empty or easily guessed value.`
+    }))
+  },
+  {
+    id: "shared-secret",
+    description: "A sensitive variable is in defaults, so it goes to every worktree.",
+    check: (ctx) => entries(ctx).filter((e) => e.shared && isSensitiveKey(e.key)).map((e) => ({
+      location: e.location,
+      message: `${e.key} looks sensitive but is written to every worktree; set it per worktree under envs instead.`
+    }))
+  },
+  {
+    id: "secret-pattern",
+    description: "A value has the format of a well-known secret.",
+    check: (ctx) => entries(ctx).flatMap((e) => SECRET_PATTERNS.filter(([pattern]) => pattern.test(e.text)).map(([, name]) => ({
+      location: e.location,
+      message: `${e.key} looks like ${name}.`
+    })))
+  },
+  {
+    id: "url-credentials",
+    description: "A remote URL embeds a password.",
+    check: (ctx) => entries(ctx).filter((e) => {
+      const url = parseUrl(e.text);
+      return url?.hasPassword && !url.local;
+    }).map((e) => ({
+      location: e.location,
+      message: `${e.key} embeds a password in its URL.`
+    }))
+  },
+  {
+    id: "insecure-url",
+    description: "A remote URL uses an unencrypted protocol.",
+    check: (ctx) => entries(ctx).filter((e) => {
+      const url = parseUrl(e.text);
+      return url && !url.local && ["http", "ws", "ftp"].includes(url.scheme);
+    }).map((e) => ({
+      location: e.location,
+      message: `${e.key} uses ${parseUrl(e.text).scheme}:// instead of an encrypted protocol.`
+    }))
+  }
+];
+
+// src/envs.ts
 var HELP = `Usage: envs <command>
 
 Commands:
   init    Create the .envs/ directory (.gitignore, values.yml)
   pull    Read each worktree's .env and write it into .envs/values.yml
   push    Write defaults and .envs/values.yml into the .env of each worktree
+  lint    Warn about insecure values and unprotected secret files
   edit    Pull, open .envs/values.yml in VS Code (code -w), then push
   help    Show this help message
 `;
@@ -67,6 +282,18 @@ function parseDotenv(text) {
   }
   return result;
 }
+function parseValue(value) {
+  if (value === "true")
+    return true;
+  if (value === "false")
+    return false;
+  if (/^-?\d+(\.\d+)?$/.test(value)) {
+    const number = Number(value);
+    if (String(number) === value)
+      return number;
+  }
+  return value;
+}
 function formatDotenvValue(value) {
   if (value !== "" && !/[\s#"'\\$]/.test(value))
     return value;
@@ -155,7 +382,7 @@ async function pull(ctx) {
         delete byWorktree[name];
     }
     for (const [key, value] of Object.entries(parsed)) {
-      (envs[key] ??= {})[name] = value;
+      (envs[key] ??= {})[name] = parseValue(value);
     }
     ctx.log(`Pulled ${name}`);
   }
@@ -166,6 +393,51 @@ async function pull(ctx) {
   await Bun.write(valuesPath, Bun.YAML.stringify(values, null, 2));
   return 0;
 }
+async function isIgnored(dir, file) {
+  const result = await $`git check-ignore -q ${file}`.cwd(dir).nothrow().quiet();
+  return result.exitCode === 0;
+}
+async function isTracked(dir, file) {
+  const result = await $`git ls-files --error-unmatch ${file}`.cwd(dir).nothrow().quiet();
+  return result.exitCode === 0;
+}
+async function lint(ctx) {
+  const read = await readValues(ctx);
+  if (!read)
+    return 1;
+  const root = await findRoot(ctx.cwd);
+  const worktrees = await listWorktrees(ctx.cwd);
+  const modeOf = async (path) => process.platform === "win32" ? undefined : (await stat(path)).mode;
+  const dotenvs = [];
+  for (const worktree of worktrees) {
+    const path = join(worktree.path, ".env");
+    if (await Bun.file(path).exists()) {
+      dotenvs.push({ ...worktree, mode: await modeOf(path) });
+    }
+  }
+  const lintContext = {
+    values: read.values,
+    root,
+    valuesMode: await modeOf(read.path),
+    dotenvs,
+    isTracked,
+    isIgnored
+  };
+  let count = 0;
+  for (const rule of rules) {
+    for (const { location, message } of await rule.check(lintContext)) {
+      ctx.error(`warning [${rule.id}] ${location}: ${message}`);
+      count++;
+    }
+  }
+  if (count === 0) {
+    ctx.log("No security problems found.");
+    return 0;
+  }
+  ctx.error(`
+${count} warning(s) found.`);
+  return 1;
+}
 async function edit(ctx) {
   const pulled = await pull(ctx);
   if (pulled !== 0)
@@ -190,6 +462,8 @@ async function run(args, ctx = defaultContext()) {
       return await push(ctx);
     case "pull":
       return await pull(ctx);
+    case "lint":
+      return await lint(ctx);
     case "edit":
       return await edit(ctx);
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jondotsoy/envs",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "license": "MIT",
   "author": {
     "name": "Jonathan Delgado",