@jondotsoy/envs 0.1.9-alpha.1 → 0.1.9-alpha.3

package/README.md

@@ -43,7 +43,7 @@ A walkthrough with a screenshot of each action is in [docs/ui.md](docs/ui.md) (i
 | Command | What it does |
 | --- | --- |
 | `envs edit` | Runs `init` if `.envs/values.yml` does not exist yet, then runs `pull`, opens `values.yml` with `code -w` and, when the editor closes, runs `push`. If the editor fails, it does not `push`. |
-| `envs edit --ui` | Same `init` and `pull`, but instead of VS Code it starts a local server (`127.0.0.1`, random port) and opens a React web editor with the values of `values.yml` (worktree profiles, defaults and per-worktree values). The **Save** button in the top right corner writes `values.yml` and runs `push`. Its **History** panel lists the history points (newest first); hovering or clicking a point shows what restoring it would change in the editor (red: removed, green: changed or added), and its **Restore** button, after a confirmation, runs `envs restore` for that point. Open the address it prints (it carries a one-time access token); requests without the token, from another host name or from another site are refused (see [docs/ui.md](docs/ui.md)). Stop the server with Ctrl+C. |
+| `envs edit --ui` | Same `init` and `pull`, but instead of VS Code it starts a local server (`127.0.0.1`, random port) and opens a React web editor with the values of `values.yml` (worktree profiles, defaults and per-worktree values). The **Save** button in the top right corner writes `values.yml` and runs `push`. Its **History** panel lists the history points (newest first); hovering or clicking a point shows what restoring it would change in the editor (red: removed, green: changed or added), and its **Restore** button, after a confirmation, runs `envs restore` for that point. Open the address it prints (it carries a single-use access token: the first visit trades it for a session cookie, and using it prints a fresh single-use address; if the browser cannot be opened, the address is printed to open by hand; the token never appears in `ps`); requests without the token, from another host name or from another site are refused (see [docs/ui.md](docs/ui.md)). Stop the server with Ctrl+C. |
 | `envs init` | Creates `.envs/`, `.envs/.gitignore` (containing `*`) and an empty `.envs/values.yml`. Does not overwrite existing files. |
 | `envs pull` | Reads the `.env` of the main repo and of each worktree and writes it to `values.yml`. Variables that are no longer in a `.env` are removed from `values.yml` for that worktree. |
 | `envs push` | Writes `values.yml` to the `.env` of each worktree. Updates existing variables in place, appends new ones at the end, keeps comments, refuses (writing nothing) a variable name that is not valid or a value with a line break, and removes the orphan variables: those `envs` manages (they are, or were, in `values.yml` or its history) but that the worktree no longer resolves, for example after `envs restore`. Variables that `envs` never saw are left alone. |

package/SECURITY.md

@@ -27,8 +27,8 @@ I will reply as soon as possible and we will coordinate the fix and the disclosu
 | --- | --- | --- |
 | `envs init` | — | Creates `<root>/.envs/`, `<root>/.envs/.gitignore` and `<root>/.envs/values.yml`, only if they do not exist. Never overwrites. |
 | `envs pull` | `<worktree>/.env` of each worktree | Rewrites `<root>/.envs/values.yml`. The file is serialized again, so YAML comments are lost. |
-| `envs push` | `<root>/.envs/values.yml` | Creates or updates `<worktree>/.env` of each worktree that has values. Updates existing variables in place, appends new ones at the end and keeps the rest of the file, except the orphan variables: those `envs` manages (they are or were in `values.yml` or its history) that the worktree no longer resolves are removed. If there are `defaults`, this includes all worktrees. |
-| `envs edit` | Same as `pull` and `push` | Same as `pull` and `push`. It also runs `code -w <root>/.envs/values.yml`. With `--ui` it serves the web editor instead (see below). |
+| `envs push` | `<root>/.envs/values.yml` | Creates or updates `<worktree>/.env` of each worktree that has values. Updates existing variables in place, appends new ones at the end and keeps the rest of the file (it sets the mode of every `.env` it writes to `600`, so another user, such as a container mounting it, can no longer read it), except the orphan variables: those `envs` manages (they are or were in `values.yml` or its history) that the worktree no longer resolves are removed. If there are `defaults`, this includes all worktrees. |
+| `envs edit` | Same as `pull` and `push` | Same as `pull` and `push`. It also runs `code -w <root>/.envs/values.yml`. With `--ui` it serves the web editor instead and runs the system opener (`xdg-open`, `open` or `explorer`) on a temporary redirect page under the OS temp directory (see below). |
 | `envs use`, `envs restore` | `<root>/.envs/values.yml`, `<root>/.envs/history.ndjson` | Rewrite `values.yml` and then act as `push`. |
 | `envs config` | `<root>/.envs/config.yml` | Creates or updates `<root>/.envs/config.yml` (mode `600`). |
 
@@ -51,7 +51,14 @@ Additionally:
 
 ## Web editor (`envs edit --ui`)
 
-The server listens on `127.0.0.1` only and exposes the values of every `.env`, secrets included, so each request must pass these checks: a random per-run access token (in the printed URL, then an `HttpOnly`, `SameSite=Strict` cookie), a `Host` of this server (no DNS rebinding), an `Origin` of this server, `application/json` bodies and a body of at most 5 MiB; it never answers CORS preflights. Open only the address printed by the command and do not share it: it carries the token. See [docs/ui.md](docs/ui.md).
+The server listens on `127.0.0.1` only and exposes the values of every `.env`, secrets included, so each request must pass these checks: a random per-run access token (in the printed URL, **single-use**: the first visit trades it for a different session secret, set as an `HttpOnly`, `SameSite=Strict` cookie), a `Host` of this server (no DNS rebinding), an `Origin` of this server, `application/json` bodies and a body of at most 5 MiB; it never answers CORS preflights. Open only the address printed by the command and do not share it: it carries the token. See [docs/ui.md](docs/ui.md).
+
+How the access token is handled:
+
+- **Single-use.** Once the token in the URL is used it stops working (`401`), so a copy left in the browser history, the terminal or a screenshot is useless afterwards. Using it prints a fresh single-use URL to stdout (`New single-use URL: …`) to open the editor from another browser; every URL gives the same session. The session secret is never in a URL.
+- **Not in `ps`.** The URL is not passed as an argument to `xdg-open`/`open`/`explorer`, where any user could read it in the process list. The opener receives a private temporary page (a directory made with `mkdtemp`, file mode `600`) that redirects to the URL. The page is removed as soon as the token is used, after 60 seconds at most, when the process exits, or when the opener fails.
+- **If the browser cannot be opened** the command prints `Could not open the browser. Open this address manually: …`.
+- **Remaining exposure.** The token is printed to stdout and is in the address bar until it is used, so anyone who can read your screen or your terminal output in that moment can use it before you do. If the address is opened by someone else first, your own visit gets a `401`: stop the server (Ctrl+C) and start it again.
 
 ## The history
 
@@ -62,7 +69,7 @@ The server listens on `127.0.0.1` only and exposes the values of every `.env`, s
 `envs push` prints one line for each variable whose value changes, in the form `↻ NAME=VALUE → branch, ...`, and `envs pull` prints `↓ pulling branch, ... - N variables`. To keep secrets out of the terminal and CI logs:
 
 - The value is replaced by `********` when the variable name contains a sensitive word: `SECRET`, `PASSWORD`, `PASSWD`, `PWD`, `TOKEN`, `KEY` (including `API_KEY` and `PRIVATE_KEY`), `CREDENTIAL`, `AUTH`, `SALT` or `SIGNING`. The match is case-insensitive and applies to whole `_`-separated words, so `KEY_FOO` and `AWS_BUCKET_SECRET` are masked but `MONKEY` is not.
-- A URL keeps its host and loses its secrets: `postgres://user:********@host/db?token=********` (the password and the values of sensitive query parameters are masked). A secret stored in a variable with an innocuous name and no URL form is still printed as is.
+- A URL keeps its host and loses its secrets: `postgres://user:********@host/db?token=********` (the password and the values of sensitive query parameters are masked). A value in a well-known secret format (AWS key, GitHub or Slack token, `sk-…` key, private key) is masked whatever the variable is called; any other secret stored in a variable with an innocuous name and no URL form is still printed as is.
 - `envs pull` never prints values, only branch names and the number of variables.
 - `envs lint` messages never include the matched value.
 - Set `NO_COLOR` to a non-empty value to print the output without colors.

package/envs.js

@@ -17,8 +17,9 @@ function dotenvProblem(key, text) {
   if (!/^[\w.-]+$/.test(key)) {
     return "the name is not a valid variable name (only letters, digits, `_`, `.` and `-`)";
   }
-  if (text.includes("'") && text.includes('"') && text.includes("`")) {
-    return "the value has single, double and backtick quotes at once, so no .env quoting can hold it as is";
+  const needsBackticks = text.includes("'") && (text.includes('"') || /\\[nr]/.test(text));
+  if (needsBackticks && text.includes("`")) {
+    return "the value needs backtick quoting (it has a single quote and a double quote or a literal `\\n`) and also has a backtick, so no .env quoting can hold it as is";
   }
   if (/[\r\n]/.test(text)) {
     return "the value has a line break, which a .env file cannot hold safely (write it on one line, with `\\n` escapes if the application expects them)";
@@ -97,10 +98,10 @@ var init_lint_rules = __esm(() => {
     "xxx"
   ]);
   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"],
+    [/(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}/, "an AWS access key id"],
+    [/(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{36,}/, "a GitHub token"],
+    [/(?<![A-Za-z0-9])sk-[A-Za-z0-9_-]{20,}/, "an API secret key"],
+    [/(?<![A-Za-z0-9])xox[abprs]-[A-Za-z0-9-]{10,}/, "a Slack token"],
     [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, "a private key"]
   ];
   rules = [
@@ -498,7 +499,9 @@ function presentedToken(req) {
 }
 async function serveUi(ctx) {
   const assets = await loadAssets();
-  const token = randomBytes(24).toString("base64url");
+  let opened;
+  let token = randomBytes(24).toString("base64url");
+  const session = randomBytes(24).toString("base64url");
   const guard = (handler) => async (req) => {
     const port = server.port;
     const hosts = [`127.0.0.1:${port}`, `localhost:${port}`];
@@ -511,15 +514,18 @@ async function serveUi(ctx) {
     }
     const url = new URL(req.url);
     if (url.pathname === "/" && sameToken(url.searchParams.get("token"), token)) {
+      token = randomBytes(24).toString("base64url");
+      ctx.log(`New single-use URL: ${urlWith(token)}`);
+      opened?.then((cleanup) => cleanup?.(), () => {});
       return new Response(null, {
         status: 302,
         headers: {
           location: "/",
-          "set-cookie": `${TOKEN_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`
+          "set-cookie": `${TOKEN_COOKIE}=${session}; HttpOnly; SameSite=Strict; Path=/`
         }
       });
     }
-    if (!sameToken(presentedToken(req), token)) {
+    if (!sameToken(presentedToken(req), session)) {
       return new Response("Unauthorized: open the address printed by `envs edit --ui`.", { status: 401 });
     }
     if (req.method !== "GET" && req.method !== "HEAD" && !req.headers.get("content-type")?.toLowerCase().startsWith("application/json")) {
@@ -573,9 +579,15 @@ async function serveUi(ctx) {
       return asset ? new Response(asset) : new Response("Not found", { status: 404 });
     })
   });
-  const url = `http://127.0.0.1:${server.port}/?token=${token}`;
+  const urlWith = (t) => `http://127.0.0.1:${server.port}/?token=${t}`;
+  const url = urlWith(token);
   ctx.log(`Web editor running at ${url} (Ctrl+C to stop)`);
-  await ctx.openUrl?.(url);
+  try {
+    opened = ctx.openUrl?.(url);
+    await opened;
+  } catch {
+    ctx.log(`Could not open the browser. Open this address manually: ${url}`);
+  }
   await (ctx.waitForExit ?? (() => new Promise(() => {})))();
   await server.stop(true);
   return 0;
@@ -592,6 +604,8 @@ import { AsyncLocalStorage } from "async_hooks";
 import { chmod, mkdir, open, rename, unlink, writeFile } from "fs/promises";
 import { basename, dirname, join as join2 } from "path";
 import { stat } from "fs/promises";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
 import { createHash, createHmac, randomBytes as randomBytes2 } from "crypto";
 import { appendFile, truncate } from "fs/promises";
 var {$ } = globalThis.Bun;
@@ -871,7 +885,7 @@ function parseDotenv(text) {
       continue;
     let value = match[2].trim();
     const quote = value[0];
-    if ((quote === '"' || quote === "'") && value.lastIndexOf(quote) > 0) {
+    if ((quote === '"' || quote === "'" || quote === "`") && value.lastIndexOf(quote) > 0) {
       value = value.slice(1, value.lastIndexOf(quote));
     } else {
       value = value.replace(/\s+#.*$/, "");
@@ -1566,9 +1580,21 @@ Commands:
   },
   openUrl: async (url) => {
     const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+    const dir = mkdtempSync(join2(tmpdir(), "envs-"));
+    const cleanup = () => rmSync(dir, { recursive: true, force: true });
     try {
-      await Bun.spawn([opener, url], { stdio: ["ignore", "ignore", "ignore"] }).exited;
-    } catch {}
+      const page = join2(dir, "open.html");
+      writeFileSync(page, `<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${url}"><script>location.replace(${JSON.stringify(url)})</script>`, { mode: 384 });
+      process.once("exit", cleanup);
+      setTimeout(cleanup, 60000).unref();
+      const code = await Bun.spawn([opener, page], { stdio: ["ignore", "ignore", "ignore"] }).exited;
+      if (code !== 0)
+        throw new Error(`${opener} exited with code ${code}`);
+      return cleanup;
+    } catch (error) {
+      cleanup();
+      throw error;
+    }
   },
   waitForExit: () => new Promise((resolve) => {
     process.once("SIGINT", () => resolve());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jondotsoy/envs",
-  "version": "0.1.9-alpha.1",
+  "version": "0.1.9-alpha.3",
   "license": "MIT",
   "author": {
     "name": "Jonathan Delgado",