@monster-orange/den 0.4.4 → 0.4.6

package/src/shared/auth/sudo-vault.ts

@@ -2,10 +2,13 @@
  * Secrets-backed persistence for the local-dev sudo password.
  *
  * Goes through the configured secrets strategy (see src/shared/secrets),
- * addressing the named ref `sudo`. There is no built-in location: a
- * distribution that wants the saved password sets `secrets.refs.sudo` in its
- * config. Without it, the vault path is "not configured" and only the
- * interactive unlock is offered; nothing is spawned.
+ * addressing the named ref `sudo`. A distribution may set
+ * `secrets.refs.sudo` in its config; that ref always wins. Without one, the
+ * vault path is "not configured" until the person saves the password
+ * (LK-4): when a backend that keeps secrets (1Password, Doppler) is
+ * available, saving creates the item and writes the ref to their own
+ * user.yml, because the password is the person's, not the distribution's.
+ * Nothing is spawned until then.
  *
  * All read helpers fail *soft*: if the backend isn't installed, the user isn't
  * signed in, the ref is not configured or the value is missing, they return
@@ -21,22 +24,64 @@ import {
   secretsStatus,
   SecretsNotConfiguredError,
   type SecretRef,
+  type SecretsConfig,
   type SecretsProviderName,
 } from "../secrets/index.js";
-import { product } from "../product.js";
+import {
+  readDenConfig,
+  readUserConfig,
+  writeUserConfig,
+} from "../den-config.js";
+import { envKey, product } from "../product.js";
 
 /** Name of the sudo ref under `secrets.refs`. */
 export const SUDO_REF_NAME = "sudo";
 
-/** The configured sudo ref, or null when `secrets.refs.sudo` is not set. */
+/**
+ * The configured sudo ref, or null when `secrets.refs.sudo` is not set. The
+ * distribution's own ref wins over one in user.yml (the merged config lets
+ * user.yml override refs in general; not this one).
+ */
 export function sudoRef(): SecretRef | null {
   try {
-    return namedSecretRef(SUDO_REF_NAME, readSecretsConfig());
+    const cfg = readSecretsConfig();
+    let team: SecretsConfig["refs"];
+    try {
+      team = readDenConfig().secrets?.refs;
+    } catch {
+      team = undefined;
+    }
+    const fromTeam = team?.[SUDO_REF_NAME]
+      ? namedSecretRef(SUDO_REF_NAME, {
+          ...cfg,
+          refs: { [SUDO_REF_NAME]: team[SUDO_REF_NAME] },
+        })
+      : null;
+    return fromTeam ?? namedSecretRef(SUDO_REF_NAME, cfg);
   } catch {
     return null;
   }
 }
 
+/**
+ * LK-4: where a password saved with no `secrets.refs.sudo` goes, for a
+ * backend that keeps it: a new 1Password item in the person's default
+ * vault, or a Doppler key. Null for `env` (process memory only: nothing
+ * survives a restart) and `none`.
+ */
+export function newSudoRef(
+  backend: SecretsProviderName,
+): Partial<SecretRef> | null {
+  switch (backend) {
+    case "1password":
+      return { item: `${product().title} admin password`, field: "password" };
+    case "doppler":
+      return { key: envKey("LOCAL_ADMIN_PWD") };
+    default:
+      return null;
+  }
+}
+
 /** True when the sudo ref is configured AND its backend is ready. */
 export async function isSecretsBackendReady(): Promise<boolean> {
   if (!sudoRef()) return false;
@@ -58,12 +103,64 @@ export async function hasSudoInVault(): Promise<boolean> {
   return (await readSudoFromVault()) !== null;
 }
 
-/** Save (or overwrite) the sudo password. Throws on backend errors. */
-export async function saveSudoToVault(password: string): Promise<void> {
+/**
+ * A backend error, without the command line it ran: a CLI's failure message
+ * can quote its arguments, and a password can be one of them.
+ */
+function withoutSecret(err: unknown, password: string): Error {
+  const msg = String((err as Error)?.message ?? err)
+    .split("\n")
+    .filter((l) => !/^Command failed:/.test(l))
+    .join(" ")
+    .split(password)
+    .join("***")
+    .trim();
+  return new Error(msg || "the secrets backend refused it");
+}
+
+/**
+ * Save (or overwrite) the sudo password. With no `secrets.refs.sudo` and a
+ * backend that keeps secrets (LK-4), it creates the item and then writes
+ * the ref to user.yml (`ref: "created"`); a failed save writes nothing.
+ * Throws on backend errors, never with the password in the message.
+ */
+export async function saveSudoToVault(
+  password: string,
+): Promise<{ ref: "configured" | "created" }> {
   const ref = sudoRef();
-  if (!ref)
+  if (ref) {
+    try {
+      await getSecretsProvider().set(ref, password);
+    } catch (err) {
+      throw withoutSecret(err, password);
+    }
+    return { ref: "configured" };
+  }
+  const st = secretsStatus(readSecretsConfig(), process.env);
+  // Only a backend someone chose (an unset provider is never used here).
+  const fresh =
+    !st.implicit && st.detect.available ? newSudoRef(st.backend) : null;
+  const made = fresh
+    ? namedSecretRef(
+        SUDO_REF_NAME,
+        { refs: { [SUDO_REF_NAME]: fresh } },
+        st.backend,
+      )
+    : null;
+  if (!fresh || !made)
     throw new SecretsNotConfiguredError(notConfiguredMessage(SUDO_REF_NAME));
-  await getSecretsProvider().set(ref, password);
+  try {
+    await getSecretsProvider().set(made, password);
+  } catch (err) {
+    throw withoutSecret(err, password);
+  }
+  const user = readUserConfig();
+  const secrets = user.secrets ?? {};
+  writeUserConfig({
+    ...user,
+    secrets: { ...secrets, refs: { ...secrets.refs, [SUDO_REF_NAME]: fresh } },
+  });
+  return { ref: "created" };
 }
 
 /** What the UI's unlock form may offer: `/api/sudo-password/vault-status`. */
@@ -74,6 +171,12 @@ export interface SudoVaultStatus {
   label: string;
   /** `secrets.refs.sudo` is set for this backend. */
   configured: boolean;
+  /**
+   * Saving works without editing YAML: the ref is configured, or (LK-4) it
+   * isn't and the backend keeps secrets, so saving creates the item and
+   * writes the ref to user.yml.
+   */
+  canSave: boolean;
   /**
    * The backend can work here, whether or not a sudo ref is configured
    * (`configured` says that). With no ref: detect() only (a PATH check,
@@ -106,6 +209,7 @@ export async function sudoVaultStatus(): Promise<SudoVaultStatus> {
     backend: st.backend,
     label: st.label,
     configured: !!ref,
+    canSave: backendAvailable && (!!ref || !!newSudoRef(st.backend)),
     backendAvailable,
     ...(reason ? { reason } : {}),
     configFile: product().configFile,

package/src/shared/cli-command.ts

@@ -0,0 +1,186 @@
+/**
+ * SEC-2a: the commands a page prints for a person to run, and the names it
+ * gives the machines involved (the signed-out page, SEC-2 spec "exact
+ * copy"). One helper builds every printed command, so none is ever a bare
+ * `<cli>` that the server's user can't run:
+ *
+ *  - `<cli>` when the first `<cli>` on PATH is this distribution's own
+ *    (its bin/<cli> shim, or Den's bin/den in Den's own checkout), else the
+ *    shim's absolute path;
+ *  - each argument shell-quoted only when it needs it;
+ *  - an ssh one-liner quotes the remote command once more, for the shell
+ *    on the far side.
+ *
+ * Two host values (Vision): the label people read (`web.machine_name`, else
+ * the short os.hostname()) and the ssh target (the Host the browser used,
+ * minus the port). The browser's Host is never the label: it is often a
+ * service name, not a machine.
+ *
+ * Pure but for the filesystem probes, which are injectable for tests.
+ */
+import * as fs from "fs";
+import * as net from "net";
+import * as path from "path";
+
+export interface CliResolveDeps {
+  /** The PATH to search (the server's own: its user's). */
+  pathEnv?: string;
+  isExecutable?: (file: string) => boolean;
+  realpath?: (file: string) => string | null;
+}
+
+const defaultExecutable = (file: string): boolean => {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+const defaultRealpath = (file: string): string | null => {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * This distribution's command: its bin/<cli> shim, or (Den's own checkout,
+ * or a distribution without a shim) the engine's bin/den. Null when
+ * neither exists.
+ */
+export function distributionBin(
+  cli: string,
+  distRoot: string,
+  engineRoot: string,
+  isExecutable: (file: string) => boolean = defaultExecutable,
+): string | null {
+  for (const f of [
+    path.join(distRoot, "bin", cli),
+    path.join(engineRoot, "bin", "den"),
+  ])
+    if (isExecutable(f)) return f;
+  return null;
+}
+
+/** The first `name` on `pathEnv` that is executable, or null. */
+export function findOnPath(
+  name: string,
+  pathEnv: string,
+  isExecutable: (file: string) => boolean = defaultExecutable,
+): string | null {
+  for (const dir of pathEnv.split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    const f = path.join(dir, name);
+    if (isExecutable(f)) return f;
+  }
+  return null;
+}
+
+/**
+ * What a printed command starts with: `cli` when the first `cli` on PATH
+ * resolves to this distribution's bin, else that bin's absolute path. With
+ * no bin found at all, `cli` (there is nothing better to print).
+ */
+export function cliPrefix(
+  cli: string,
+  distRoot: string,
+  engineRoot: string,
+  deps: CliResolveDeps = {},
+): string {
+  const isExec = deps.isExecutable ?? defaultExecutable;
+  const real = deps.realpath ?? defaultRealpath;
+  const bin = distributionBin(cli, distRoot, engineRoot, isExec);
+  if (!bin) return cli;
+  const hit = findOnPath(cli, deps.pathEnv ?? process.env.PATH ?? "", isExec);
+  if (hit) {
+    const a = real(hit);
+    const b = real(bin);
+    if (a !== null && a === b) return cli;
+  }
+  return bin;
+}
+
+/** `s` as one word for a POSIX shell: as it is when safe, else single-quoted. */
+export function shellQuote(s: string): string {
+  if (s !== "" && /^[A-Za-z0-9_@%+=:,./-]+$/.test(s)) return s;
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** A command line: `prefix` (cliPrefix) and its arguments, each quoted as needed. */
+export function cliCommand(prefix: string, ...args: string[]): string {
+  return [prefix, ...args].map(shellQuote).join(" ");
+}
+
+/** `ssh <target> '<remote>'`: the remote command quoted once more, for the far shell. */
+export function sshCommand(target: string, remote: string): string {
+  return `ssh ${shellQuote(target)} ${shellQuote(remote)}`;
+}
+
+/** A Host header's hostname: lowercase, no port, no IPv6 brackets. "" when none. */
+export function hostOfHeader(host: string | undefined): string {
+  const h = String(host ?? "")
+    .trim()
+    .toLowerCase();
+  if (!h) return "";
+  const v6 = /^\[([^\]]+)\](?::\d+)?$/.exec(h);
+  if (v6) return v6[1];
+  return h.replace(/:\d+$/, "").replace(/\.$/, "");
+}
+
+/** Whether `host` is an IP address literal (v4 or v6), not a name. */
+export function isIpLiteral(host: string): boolean {
+  return net.isIP(host.replace(/^\[|\]$/g, "")) !== 0;
+}
+
+/** The ssh target: the Host the browser used, minus the port; else `fallback`. */
+export function sshTarget(
+  hostHeader: string | undefined,
+  fallback: string,
+): string {
+  const h = hostOfHeader(hostHeader);
+  return /^[a-z0-9._:-]+$/.test(h) && !h.startsWith("-") ? h : fallback;
+}
+
+/** `Mac-Studio.localdomain` → `Mac-Studio`; an IP literal stays whole. */
+export function shortHostname(hostname: string): string {
+  const h = hostname.trim();
+  if (!h || isIpLiteral(h)) return h;
+  return h.split(".")[0] || h;
+}
+
+/** The longest `web.machine_name` accepted. */
+export const MACHINE_NAME_MAX = 64;
+
+/**
+ * `web.machine_name` as stored: a trimmed one-line label of printable
+ * characters, at most MACHINE_NAME_MAX long; null when unset or blank.
+ * Throws naming the key for anything else.
+ */
+export function parseMachineName(v: unknown): string | null {
+  if (v === undefined || v === null) return null;
+  if (typeof v !== "string")
+    throw new Error(
+      `web.machine_name must be a name (text), got ${JSON.stringify(v)}`,
+    );
+  const s = v.trim();
+  if (!s) return null;
+  if (
+    s.length > MACHINE_NAME_MAX ||
+    [...s].some((c) => c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f)
+  )
+    throw new Error(
+      `web.machine_name must be one line of at most ${MACHINE_NAME_MAX} characters`,
+    );
+  return s;
+}
+
+/** The label people read: `web.machine_name`, else the short hostname. */
+export function machineLabel(
+  machineName: string | null | undefined,
+  hostname: string,
+): string {
+  const m = (machineName ?? "").trim();
+  return m || shortHostname(hostname) || "this machine";
+}

package/src/shared/confirm-code.ts

@@ -0,0 +1,34 @@
+/**
+ * SEC-2a: the short codes people read and type, in Crockford's base32.
+ * Pure helpers, shared by the CLI (`web login` makes the confirmation
+ * code) and the server (login-waits.ts checks it; pair-requests.ts makes
+ * pairing codes), so the CLI imports no server module.
+ */
+import { randomInt } from "crypto";
+
+/** Crockford's base32: no I, L, O or U. */
+export const PAIR_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/** A `web login` confirmation code's length, without its dash. */
+export const CONFIRM_CODE_LEN = 8;
+
+/** A fresh confirmation code: `ABCD-EFGH` (Crockford base32, 40 bits). */
+export function newConfirmCode(
+  rand: (n: number) => number = randomInt,
+): string {
+  let s = "";
+  for (let i = 0; i < CONFIRM_CODE_LEN; i++) s += PAIR_ALPHABET[rand(32)];
+  return `${s.slice(0, 4)}-${s.slice(4)}`;
+}
+
+/** A typed confirmation code: any case, dashes and spaces ignored, O as 0, I and L as 1. */
+export function normalizeConfirmCode(input: string): string | null {
+  const s = String(input ?? "")
+    .toUpperCase()
+    .replace(/[\s-]/g, "")
+    .replace(/O/g, "0")
+    .replace(/[IL]/g, "1");
+  if (s.length !== CONFIRM_CODE_LEN) return null;
+  for (const c of s) if (!PAIR_ALPHABET.includes(c)) return null;
+  return s;
+}

package/src/shared/constants.ts

@@ -112,3 +112,10 @@ export const SKIP_TEST_DIRS = [
 
 /** Default den web server port. */
 export const DEFAULT_PORT = 7777;
+
+/**
+ * Ports a new distribution's web server never takes when `create` picks
+ * one because DEFAULT_PORT is in use: the edge's and other well-known Den
+ * instances' ports.
+ */
+export const RESERVED_DEN_PORTS: readonly number[] = [7778, 7791, 7799];

package/src/shared/den-config.ts

@@ -391,6 +391,13 @@ export interface UserConfig {
     /** More runtime catalog entries (AG-0.5, agents/catalog.ts). */
     runtime_catalog?: unknown;
   };
+  /**
+   * The web server's per-machine keys (src/shared/web-session.ts
+   * readWebAuthConfig): allow_plain_http_remote, edge_unattested,
+   * github_client_id, and (SEC-2a) machine_name, the name the signed-out
+   * page gives this machine.
+   */
+  web?: Record<string, unknown>;
 }
 
 const ALL_ENVIRONMENTS: Environment[] = [

package/src/shared/dev-metrics/emit.ts

@@ -11,7 +11,13 @@
  * dev-metrics.emit.test.ts against golden envelopes captured via
  * DEV_METRICS_ENVELOPE_OUT):
  *   1. ALWAYS append one compact JSON line to <repoRoot>/.dev-metrics/events.jsonl.
- *   2. THEN best-effort ship to Sentry (Tier-1 -> log item, Tier-2 -> event item).
+ *   2. THEN, only when the engineer opted in, best-effort ship to Sentry
+ *      (Tier-1 -> log item, Tier-2 -> event item).
+ *
+ * Local only by default (den#2): nothing leaves the machine unless
+ * config/local/user.yml says `metrics: { share: true }` (the boolean, nothing
+ * else). A DSN, in the env or a synced dev-metrics.config, is where to send
+ * once opted in; on its own it never sends.
  *
  * Guarantees: never throws, never blocks the caller (the Sentry ship is
  * fire-and-forget, bounded to ~2s). CI=true / DEV_METRICS_DISABLED=1 suppress
@@ -25,8 +31,9 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import { execFileSync } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import { createHash, randomUUID } from "crypto";
+import * as yaml from "yaml";
 import { getDistRoot } from "../paths.js";
 
 import { product } from "../product.js";
@@ -116,6 +123,28 @@ function suppressShip(): boolean {
   return process.env.CI === "true" || process.env.DEV_METRICS_DISABLED === "1";
 }
 
+/**
+ * The opt-in (den#2): `metrics.share` is exactly `true` in the engineer's
+ * config/local/user.yml under the repo root. Read on each ship, so turning
+ * it off takes effect at once; any error reads as "not opted in".
+ */
+export function shareOptedIn(root: string = repoRoot()): boolean {
+  try {
+    const raw = fs.readFileSync(
+      path.join(root, "config", "local", "user.yml"),
+      "utf-8",
+    );
+    const doc = yaml.parse(raw) as unknown;
+    if (!doc || typeof doc !== "object") return false;
+    const m = (doc as { metrics?: unknown }).metrics;
+    return (
+      !!m && typeof m === "object" && (m as { share?: unknown }).share === true
+    );
+  } catch {
+    return false;
+  }
+}
+
 function resolveDsn(root: string): string {
   const env = process.env.DEV_METRICS_SENTRY_DSN;
   if (env) return env;
@@ -212,11 +241,38 @@ export function buildEnvelope(
   return `{}\n${itemHeader}\n${payload}\n`;
 }
 
+/**
+ * Send from a short-lived detached process instead of this one. The CLI
+ * records its run in the `exit` handler, where an async fetch never runs;
+ * a detached sender outlives the CLI and gives up after SHIP_TIMEOUT_MS.
+ * The long-lived server keeps the in-process fetch.
+ */
+let shipDetached = false;
+export function shipFromDetachedSender(): void {
+  shipDetached = true;
+}
+
+const SENDER = `fetch(process.env.DM_URL,{method:"POST",headers:{"Content-Type":"application/x-sentry-envelope","X-Sentry-Auth":process.env.DM_AUTH},body:process.env.DM_BODY,signal:AbortSignal.timeout(${SHIP_TIMEOUT_MS})}).catch(()=>{}).finally(()=>process.exit(0))`;
+
+function sendDetached(url: string, auth: string, body: string): void {
+  try {
+    spawn(process.execPath, ["-e", SENDER], {
+      detached: true,
+      stdio: "ignore",
+      // Only what the sender needs: none of the caller's environment.
+      env: { DM_URL: url, DM_AUTH: auth, DM_BODY: body },
+    }).unref();
+  } catch {
+    /* fail-open: the JSONL line is already buffered */
+  }
+}
+
 function ship(
   record: Record<string, string>,
   epoch: number,
   root: string,
 ): void {
+  if (!shareOptedIn(root)) return;
   const dsn = resolveDsn(root);
   if (!dsn) return;
   const parsed = parseDsn(dsn);
@@ -236,6 +292,7 @@ function ship(
 
   const url = `${parsed.scheme}://${parsed.host}/api/${parsed.projectId}/envelope/`;
   const auth = `Sentry sentry_key=${parsed.key}, sentry_version=7, sentry_client=dev-metrics-${product().cli}/1.0`;
+  if (shipDetached) return sendDetached(url, auth, envelope);
   // Fire-and-forget: never awaited, so the caller never blocks. Bounded by a 2s
   // abort so a hung ingest can't leak a pending request in the long-lived server.
   void fetch(url, {

package/src/shared/edge/config.ts

@@ -29,10 +29,13 @@
  *     mounts: { <host path>: <container path> }   # read-only
  *     networks: [<external network>]
  *     args: [--accesslog=true]
+ *     proxy_protocol:               # a TCP-passthrough front proxy that
+ *       trusted_ips: [172.18.0.5]   # sends the PROXY protocol (SEC-2a)
  *   web:
  *     port: 7777             # the web UI; routed as `<brand name>`
  */
 import * as fs from "fs";
+import * as net from "net";
 import * as os from "os";
 import * as path from "path";
 import * as yaml from "yaml";
@@ -69,6 +72,7 @@ interface RawEdge {
   mounts?: Record<string, string>;
   networks?: string[];
   args?: string[];
+  proxy_protocol?: { trusted_ips?: unknown } | null;
 }
 
 function readYaml(file: string): Record<string, unknown> {
@@ -367,5 +371,40 @@ function computeEdgeConfig(root: string): EdgeConfig {
       ]),
     ],
     args: [...list(team.args, "args"), ...list(user.args, "args")],
+    proxyProtocolTrustedIps: proxyProtocolIps(
+      user.proxy_protocol ?? team.proxy_protocol,
+    ),
   };
 }
+
+/**
+ * `edge.proxy_protocol.trusted_ips`: a list of IPs or CIDRs (SEC-2a), or
+ * none. Throws naming the key on anything else.
+ */
+export function proxyProtocolIps(v: RawEdge["proxy_protocol"]): string[] {
+  if (v === undefined || v === null) return [];
+  if (typeof v !== "object" || Array.isArray(v))
+    throw new Error(
+      "edge.proxy_protocol must be a map: { trusted_ips: [...] }",
+    );
+  for (const k of Object.keys(v))
+    if (k !== "trusted_ips")
+      throw new Error(
+        `edge.proxy_protocol: unknown key "${k}" (known: trusted_ips)`,
+      );
+  const ips = list(v.trusted_ips, "proxy_protocol.trusted_ips");
+  for (const ip of ips) {
+    const [addr, bits, more] = ip.split("/");
+    const fam = net.isIP(addr);
+    const max = fam === 6 ? 128 : 32;
+    if (
+      !fam ||
+      more !== undefined ||
+      (bits !== undefined && (!/^\d{1,3}$/.test(bits) || Number(bits) > max))
+    )
+      throw new Error(
+        `edge.proxy_protocol.trusted_ips: "${ip}" is not an IP address or CIDR`,
+      );
+  }
+  return ips;
+}