@monster-orange/den 0.2.8 → 0.3.0

package/src/shared/edge/status.ts

@@ -6,7 +6,13 @@
 import * as fs from "fs";
 import * as path from "path";
 import { certNames, edgeDomains, edgeNames, routeUrl } from "./render.js";
+import {
+  includedRouters,
+  stackRouters,
+  type IncludedRouters,
+} from "./included.js";
 import { caTrusted, containerState } from "./runtime.js";
+import { caDir } from "./tls.js";
 import type { EdgeConfig, EdgePorts } from "./types.js";
 
 export interface EdgeStatus {
@@ -23,8 +29,34 @@ export interface EdgeStatus {
   /** Names on the issued cert, or the planned ones when none is issued yet. */
   certNames: string[];
   certIssued: boolean;
-  /** Whether the CA is trusted on this machine (null: can't tell). */
+  /** Whether the CA is trusted on this machine (null: can't tell, or none). */
   caTrusted: boolean | null;
+  /**
+   * The edge.tls strategy; whether nothing chose it (implicit mkcert);
+   * where it came from (edge.tls, the legacy caroot/issue_cert keys, or
+   * neither); and the CA directory (mkcert: the one it issues from; files:
+   * `ca` when set; none: null).
+   */
+  tls: {
+    strategy: EdgeConfig["tls"]["strategy"];
+    implicit: boolean;
+    from: EdgeConfig["tlsFrom"];
+    ca: string | null;
+  };
+  /**
+   * Routers in the included dynamic files (`edge include`), each with its
+   * source file: Traefik serves them, Den doesn't generate them.
+   */
+  included: IncludedRouters["routers"];
+  /** Included files that could not be parsed (listed, never fatal). */
+  includedErrors: IncludedRouters["errors"];
+  /**
+   * Routers in the stacks' route files (`stack-*.yml`, written by `stack
+   * up` into the edge's dynamic directory), each with its file (0.3.0-dev.32).
+   */
+  stacks: IncludedRouters["routers"];
+  /** Stack route files that could not be parsed (listed, never fatal). */
+  stackErrors: IncludedRouters["errors"];
 }
 
 export interface EdgeStatusDeps {
@@ -32,6 +64,10 @@ export interface EdgeStatusDeps {
   caTrusted: (cfg: EdgeConfig) => boolean | null;
   /** Names on the issued cert (its stamp file), or null when none is issued. */
   issuedNames: (cfg: EdgeConfig) => string[] | null;
+  /** The included files' routers (read from disk by default). */
+  included?: (cfg: EdgeConfig) => IncludedRouters;
+  /** The stacks' route files' routers (read from disk by default). */
+  stacks?: (cfg: EdgeConfig) => IncludedRouters;
 }
 
 /** The names stamp `ensureCerts` writes beside the cert. */
@@ -45,8 +81,19 @@ const defaultDeps: EdgeStatusDeps = {
   containerState,
   caTrusted,
   issuedNames: issuedCertNames,
+  included: includedRouters,
+  stacks: stackRouters,
 };
 
+/** Den's own routes: `<name>.<domain>` → upstream (no Docker asked). */
+export function edgeRoutes(cfg: EdgeConfig): EdgeStatus["routes"] {
+  return Object.entries(cfg.routes).map(([name, upstream]) => ({
+    name,
+    url: routeUrl(name, cfg),
+    upstream,
+  }));
+}
+
 export function edgeStatus(
   cfg: EdgeConfig,
   deps: EdgeStatusDeps = defaultDeps,
@@ -54,6 +101,8 @@ export function edgeStatus(
   const n = edgeNames(cfg.org);
   const state = deps.containerState(n.container);
   const issued = deps.issuedNames(cfg);
+  const inc = (deps.included ?? includedRouters)(cfg);
+  const stk = (deps.stacks ?? stackRouters)(cfg);
   return {
     org: cfg.org,
     container: n.container,
@@ -62,13 +111,24 @@ export function edgeStatus(
     ports: cfg.ports,
     network: n.network,
     domains: edgeDomains(cfg),
-    routes: Object.entries(cfg.routes).map(([name, upstream]) => ({
-      name,
-      url: routeUrl(name, cfg),
-      upstream,
-    })),
-    certNames: issued ?? certNames(cfg),
+    routes: edgeRoutes(cfg),
+    certNames: issued ?? (cfg.tls.strategy === "none" ? [] : certNames(cfg)),
     certIssued: issued !== null,
-    caTrusted: deps.caTrusted(cfg),
+    caTrusted: cfg.tls.strategy === "none" ? null : deps.caTrusted(cfg),
+    tls: {
+      strategy: cfg.tls.strategy,
+      implicit: cfg.tlsFrom === "implicit",
+      from: cfg.tlsFrom,
+      ca:
+        cfg.tls.strategy === "mkcert"
+          ? caDir(cfg)
+          : cfg.tls.strategy === "files"
+            ? cfg.tls.ca
+            : null,
+    },
+    included: inc.routers,
+    includedErrors: inc.errors,
+    stacks: stk.routers,
+    stackErrors: stk.errors,
   };
 }

package/src/shared/edge/tls.ts

@@ -0,0 +1,328 @@
+/**
+ * The edge's TLS strategies (TLS-1a), registered through the generic
+ * strategy registry (src/shared/strategies/registry.ts) as kind "tls",
+ * exactly as a plugin would register one: `{ id, kind, detect(),
+ * capabilities }`.
+ *
+ *  - `none`: http only. No https entrypoint, no cert work, no mkcert.
+ *  - `mkcert`: the edge issues its own wildcard cert from a local CA, its
+ *    own under the state dir (minted on first use) or `ca`, an existing one
+ *    it never mints or uninstalls. The only strategy with `trust`/`untrust`.
+ *  - `files`: the distribution's included dynamic config and mounts hold the
+ *    certs; Den issues none. `ca` names the CA that signed them, so health
+ *    checks trust it.
+ *
+ * `secret` (cert and key from the selected secrets strategy) and `acme` are
+ * later plugins; they register here the same way.
+ *
+ * Capabilities:
+ *  - `https`: the edge has an https entrypoint;
+ *  - `issuesCert`: Den issues the edge's own cert (the TLS store it renders);
+ *  - `ensure(cfg)`: make sure the cert exists for certNames(cfg);
+ *  - `trust(cfg)` / `untrust(cfg)`: mkcert only;
+ *  - `status(cfg)`: the names on the cert and whether its CA is trusted.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import {
+  getStrategy,
+  onPath,
+  registerStrategy,
+  strategyIds,
+  type DetectResult,
+  type StrategyEntry,
+} from "../strategies/registry.js";
+import { must, sh } from "./exec.js";
+import { certNames } from "./render.js";
+import type { EdgeConfig, EdgeTls } from "./types.js";
+
+export const TLS_KIND = "tls";
+
+export type TlsEnsureResult =
+  | {
+      kind: "cert";
+      certFile: string;
+      keyFile: string;
+      issued: boolean;
+      names: string[];
+    }
+  | { kind: "dynamic" | "none"; issued: false; names: [] };
+
+export interface TlsCapabilities {
+  label: string;
+  https: boolean;
+  issuesCert: boolean;
+  ensure(cfg: EdgeConfig): TlsEnsureResult;
+  trust?(cfg: EdgeConfig): number;
+  untrust?(cfg: EdgeConfig): number;
+  status(cfg: EdgeConfig): { names: string[]; trusted: boolean | null };
+}
+
+export type TlsStrategy = StrategyEntry<typeof TLS_KIND, TlsCapabilities>;
+
+// ── The CA ───────────────────────────────────────────────────────────────────
+
+/** The configured CA (`edge.tls.ca`, formerly `edge.caroot`), or null. */
+export function tlsCa(cfg: EdgeConfig): string | null {
+  return cfg.tls.strategy === "none" ? null : cfg.tls.ca;
+}
+
+export function caDir(cfg: EdgeConfig): string {
+  return tlsCa(cfg) ?? path.join(cfg.stateDir, "ca");
+}
+
+/** True when the edge uses an existing CA (`ca`) rather than its own. */
+export function sharedCa(cfg: EdgeConfig): boolean {
+  return tlsCa(cfg) !== null;
+}
+
+/**
+ * A shared CA must already exist with its key: mkcert silently creates a new
+ * CA in an empty CAROOT, and devices that trust the shared one would not
+ * trust that. The org's own CA may be created on first use.
+ */
+export function assertCaUsable(cfg: EdgeConfig): void {
+  if (!sharedCa(cfg)) return;
+  const dir = caDir(cfg);
+  if (!fs.existsSync(dir))
+    throw new Error(
+      `edge.tls.ca ${dir} does not exist. The edge never creates a CA there; ` +
+        `point it at the existing CA (\`mkcert -CAROOT\`).`,
+    );
+  for (const f of ["rootCA.pem", "rootCA-key.pem"])
+    if (!fs.existsSync(path.join(dir, f)))
+      throw new Error(
+        `edge.tls.ca ${dir} has no ${f}. Refusing to run: mkcert would mint a ` +
+          `new CA that other devices don't trust.`,
+      );
+}
+
+/** Whether the CA is in the macOS system keychain (null: can't tell). */
+export function caTrusted(cfg: EdgeConfig): boolean | null {
+  if (cfg.tls.strategy === "none") return null;
+  const pem = path.join(caDir(cfg), "rootCA.pem");
+  if (!fs.existsSync(pem)) return false;
+  if (process.platform !== "darwin") return null;
+  return sh("security", ["verify-cert", "-c", pem]).code === 0;
+}
+
+// ── mkcert ───────────────────────────────────────────────────────────────────
+
+export const MKCERT_MISSING = "mkcert is not installed";
+
+/** detect() first: a missing mkcert is a reason, never a spawn error. */
+function requireMkcert(): void {
+  const d = mkcert.detect();
+  if (!d.available)
+    throw new Error(
+      `${d.reason}. Install it (https://github.com/FiloSottile/mkcert, e.g. ` +
+        "`brew install mkcert`), or set edge.tls to none or files.",
+    );
+}
+
+function mkcertEnv(cfg: EdgeConfig): NodeJS.ProcessEnv {
+  return { CAROOT: caDir(cfg) };
+}
+
+const NO_CERT = { issued: false, names: [] } as const;
+
+const none: TlsStrategy = {
+  id: "none",
+  kind: TLS_KIND,
+  detect: () => ({ available: true, reason: "http only" }),
+  capabilities: {
+    label: "none (http only)",
+    https: false,
+    issuesCert: false,
+    ensure: () => ({ kind: "none", ...NO_CERT, names: [] }),
+    status: () => ({ names: [], trusted: null }),
+  },
+};
+
+const mkcert: TlsStrategy = {
+  id: "mkcert",
+  kind: TLS_KIND,
+  detect: (env: NodeJS.ProcessEnv = process.env): DetectResult =>
+    onPath("mkcert", env)
+      ? { available: true }
+      : { available: false, reason: MKCERT_MISSING },
+  capabilities: {
+    label: "mkcert",
+    https: true,
+    issuesCert: true,
+    /** Issue (or re-issue when names changed) the edge cert from the CA. */
+    ensure(cfg) {
+      const names = certNames(cfg);
+      assertCaUsable(cfg);
+      const dir = path.join(cfg.stateDir, "certs");
+      const certFile = path.join(dir, "edge.pem");
+      const keyFile = path.join(dir, "edge-key.pem");
+      const stamp = path.join(dir, "names.txt");
+      const want = names.join("\n");
+      if (
+        fs.existsSync(certFile) &&
+        fs.existsSync(stamp) &&
+        fs.readFileSync(stamp, "utf-8") === want
+      )
+        return { kind: "cert", certFile, keyFile, issued: false, names };
+      requireMkcert();
+      fs.mkdirSync(dir, { recursive: true });
+      if (!sharedCa(cfg))
+        fs.mkdirSync(caDir(cfg), { recursive: true, mode: 0o700 });
+      must("mkcert", ["-cert-file", certFile, "-key-file", keyFile, ...names], {
+        env: mkcertEnv(cfg),
+      });
+      fs.mkdirSync(path.dirname(stamp), { recursive: true });
+      fs.writeFileSync(stamp, want, "utf-8");
+      return { kind: "cert", certFile, keyFile, issued: true, names };
+    },
+    /** Install the CA into the system + browser trust stores (prompts). */
+    trust(cfg) {
+      assertCaUsable(cfg);
+      requireMkcert();
+      if (!sharedCa(cfg))
+        fs.mkdirSync(caDir(cfg), { recursive: true, mode: 0o700 });
+      return sh("mkcert", ["-install"], { env: mkcertEnv(cfg), inherit: true })
+        .code;
+    },
+    untrust(cfg) {
+      if (sharedCa(cfg))
+        throw new Error(
+          `edge.tls.ca is a shared CA (${caDir(cfg)}); other tools and devices ` +
+            `rely on it being trusted, so the edge never uninstalls it.`,
+        );
+      requireMkcert();
+      return sh("mkcert", ["-uninstall"], {
+        env: mkcertEnv(cfg),
+        inherit: true,
+      }).code;
+    },
+    status: (cfg) => ({ names: certNames(cfg), trusted: caTrusted(cfg) }),
+  },
+};
+
+const files: TlsStrategy = {
+  id: "files",
+  kind: TLS_KIND,
+  detect: () => ({ available: true }),
+  capabilities: {
+    label: "files (included config)",
+    https: true,
+    issuesCert: false,
+    ensure: () => ({ kind: "dynamic", ...NO_CERT, names: [] }),
+    status: (cfg) => ({ names: [], trusted: caTrusted(cfg) }),
+  },
+};
+
+for (const s of [none, mkcert, files]) registerStrategy(s);
+
+/** Every registered TLS strategy id (built-ins first). */
+export function tlsStrategyIds(): string[] {
+  return strategyIds(TLS_KIND);
+}
+
+/** The registered TLS strategy `id`, or undefined. */
+export function tlsStrategy(id: string): TlsStrategy | undefined {
+  return getStrategy<typeof TLS_KIND, TlsCapabilities>(TLS_KIND, id);
+}
+
+/** The strategy the edge config selects (always registered once parsed). */
+export function tlsStrategyFor(cfg: EdgeConfig): TlsStrategy {
+  const s = tlsStrategy(cfg.tls.strategy);
+  if (!s)
+    throw new Error(`TLS strategy "${cfg.tls.strategy}" is not registered`);
+  return s;
+}
+
+/** True when the edge serves https (every strategy but none). */
+export function servesHttps(cfg: EdgeConfig): boolean {
+  return cfg.tls.strategy !== "none";
+}
+
+/** True when Den issues the edge's own cert (mkcert). */
+export function issuesCert(cfg: EdgeConfig): boolean {
+  return cfg.tls.strategy === "mkcert";
+}
+
+const TRUST_NEEDS_MKCERT =
+  "edge trust needs edge.tls.strategy: mkcert (or files with a ca)";
+
+function trustRefusal(cfg: EdgeConfig, verb: "trust" | "untrust"): Error {
+  return new Error(
+    `${TRUST_NEEDS_MKCERT.replace("trust", verb)} (this edge's is ${cfg.tls.strategy}: ` +
+      (cfg.tls.strategy === "none"
+        ? "it serves http only, there is no CA to trust)."
+        : "its certs come from your included config; trust their CA yourself)."),
+  );
+}
+
+/**
+ * Trust capabilities for the edge: mkcert's own, or, for `files` with an
+ * existing `ca` (the legacy caroot + issue_cert: false shape), mkcert's
+ * against that CA: `edge trust` installs it, as caroot always did, and
+ * untrust refuses it as a shared CA.
+ */
+function trustCapabilities(cfg: EdgeConfig): TlsCapabilities | null {
+  const c = tlsStrategyFor(cfg).capabilities;
+  if (c.trust) return c;
+  if (cfg.tls.strategy === "files" && sharedCa(cfg)) return mkcert.capabilities;
+  return null;
+}
+
+/** `edge trust`: mkcert, or files with an existing ca. */
+export function edgeTrust(cfg: EdgeConfig): number {
+  const t = trustCapabilities(cfg)?.trust;
+  if (!t) throw trustRefusal(cfg, "trust");
+  return t(cfg);
+}
+
+/** `edge untrust`: mkcert only, and never for a shared CA. */
+export function edgeUntrust(cfg: EdgeConfig): number {
+  const u = trustCapabilities(cfg)?.untrust;
+  if (!u) throw trustRefusal(cfg, "untrust");
+  return u(cfg);
+}
+
+// ── Config warnings ──────────────────────────────────────────────────────────
+
+export const IMPLICIT_TLS_WARNING =
+  "edge.tls is not set; defaulting to mkcert with a local CA. Set edge.tls explicitly.";
+
+/** The explicit `edge.tls` line that says what `tls` says. */
+export function tlsYaml(tls: EdgeTls): string {
+  if (tls.strategy === "none") return "tls: none";
+  const ca = tls.ca ? `, ca: ${tls.ca}` : "";
+  if (tls.strategy === "mkcert") return `tls: { strategy: mkcert${ca} }`;
+  return `tls: { strategy: files${ca}, include: <edge.include>, mounts: <edge.mounts> }`;
+}
+
+/** Config warnings about the edge's TLS, for `validate` and `doctor`. */
+export function edgeTlsWarnings(cfg: EdgeConfig): string[] {
+  if (cfg.tlsFrom === "implicit") return [IMPLICIT_TLS_WARNING];
+  if (cfg.tlsFrom === "legacy")
+    return [
+      "edge.caroot and edge.issue_cert are deprecated; they still work. " +
+        `Say the same with edge.${tlsYaml(cfg.tls)}`,
+    ];
+  return [];
+}
+
+let warnedImplicit = false;
+
+/**
+ * The implicit-mkcert warning, at most once per run: from `validate` and
+ * from the paths that would mint a cert (`edge up`, `stack up`).
+ */
+export function warnImplicitTlsOnce(
+  cfg: EdgeConfig,
+  warn: (line: string) => void = (l) => console.warn(`⚠️  ${l}`),
+): void {
+  if (cfg.tlsFrom !== "implicit" || warnedImplicit) return;
+  warnedImplicit = true;
+  warn(IMPLICIT_TLS_WARNING);
+}
+
+/** Test seam: forget that the warning was given. */
+export function __resetTlsWarningForTests(): void {
+  warnedImplicit = false;
+}

package/src/shared/edge/types.ts

@@ -1,6 +1,6 @@
 /**
- * The org's HTTPS edge: one Traefik that terminates TLS with the org's own CA
- * (mkcert, separate CAROOT) and routes `<name>.<domain>` to local services.
+ * The org's edge: one Traefik that terminates TLS as `edge.tls` says (none,
+ * mkcert or files) and routes `<name>.<domain>` to local services.
  * File-provider routes, plus Docker labels when `docker_labels` opts in
  * (through a read-only socket proxy; the edge never mounts the socket).
  *
@@ -15,6 +15,11 @@ export interface EdgePorts {
   https: number;
 }
 
+export type EdgeTls =
+  | { strategy: "none" }
+  | { strategy: "mkcert"; ca: string | null }
+  | { strategy: "files"; ca: string | null };
+
 export interface EdgeConfig {
   /** Org slug — names the edge container and its Docker network. */
   org: string;
@@ -35,14 +40,25 @@ export interface EdgeConfig {
   /** Where the org's CA, certs and generated config live. */
   stateDir: string;
   /**
-   * An existing mkcert CA to use instead of the org's own under `stateDir`
-   * (e.g. a CA other devices already trust). The edge refuses to run if its
-   * key is missing, so mkcert can never mint a replacement, and it never
-   * uninstalls a shared CA.
+   * The state dir the config names, when DEN_EDGE_DIR overrides it with
+   * another (0.3.0-dev.40): an unlabelled edge is adopted only from that one.
+   */
+  defaultStateDir?: string;
+  /**
+   * How the edge gets its certificates: the `edge.tls` strategy (see
+   * tls.ts). `none`: http only, no https entrypoint. `mkcert`: the edge
+   * issues its own wildcard cert from a local CA (its own under `stateDir`,
+   * or `ca`, an existing one it never mints or uninstalls). `files`: the
+   * included dynamic config and mounts hold the certs; `ca` is the CA that
+   * signed them, if Den should trust it for health checks.
+   */
+  tls: EdgeTls;
+  /**
+   * Where `tls` came from: `explicit` (edge.tls), `legacy` (edge.caroot /
+   * edge.issue_cert, mapped), or `implicit` (neither: mkcert with a local CA,
+   * deprecated, warned once per run).
    */
-  caroot: string | null;
-  /** Issue the edge's own wildcard cert. Off when included config holds the certs. */
-  issueCert: boolean;
+  tlsFrom: "explicit" | "legacy" | "implicit";
   /** Catch-all HTTP→HTTPS redirect. Off when included config decides per name. */
   httpsRedirect: boolean;
   /**

package/src/shared/environment-manager/default-workspace.ts

@@ -73,6 +73,16 @@ function blueprintServices(
   return services;
 }
 
+/**
+ * The blueprint's `stack_namespace`, carried into the seeded workspace so
+ * its stacks keep that namespace on this machine ({} when it sets none).
+ */
+function blueprintStackNamespace(
+  bp: ResolvedWorkspaceBlueprint,
+): Pick<WorkspaceConfig, "stack_namespace"> {
+  return bp.stackNamespace ? { stack_namespace: bp.stackNamespace } : {};
+}
+
 /**
  * The clone slug seeding would give each repo the catalog has no `gh` for:
  * `<org>/<repo>` with its workspace's resolved org. A repo in several
@@ -174,7 +184,8 @@ function sameEntry(a: unknown, b: unknown): boolean {
 /**
  * Whether seeding now would change nothing: every workspace the blueprint
  * seeds holds exactly what seeding writes (same repos, all managed on the
- * blueprint's branch, same autostart defaults), records the blueprint as
+ * blueprint's branch, same autostart defaults, its stack_namespace),
+ * records the blueprint as
  * applied, and (multi blueprint) is active. A workspace the user changed
  * since (a repo switched to a local checkout, one added or removed) is not
  * "already seeded": seeding would reset it.
@@ -196,6 +207,8 @@ export function blueprintAlreadySeeded(
       bp.repos.some((r, i) => applied[i] !== r)
     )
       return false;
+    if (bp.stackNamespace && ws.stack_namespace !== bp.stackNamespace)
+      return false;
     return sameEntry(ws.services ?? {}, blueprintServices(bp));
   });
 }
@@ -222,6 +235,7 @@ export function seedDefaultWorkspace(): string[] {
     ...(file.workspaces.default ?? {}),
     services: blueprintServices(bp),
     seeded_repos: [...repos],
+    ...blueprintStackNamespace(bp),
   };
   if (!file.active?.length) {
     file.active = ["default"];
@@ -248,6 +262,7 @@ export function seedBlueprintWorkspaces(): { name: string; repos: string[] }[] {
       ...(prev ?? {}),
       services: blueprintServices(bp),
       seeded_repos: [...bp.repos],
+      ...blueprintStackNamespace(bp),
     };
   }
   const names = bps.map((b) => b.name);