@monster-orange/den 0.2.7 → 0.3.0

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/catalog.ts

@@ -14,7 +14,13 @@ import * as path from "path";
 import * as yaml from "yaml";
 import type { ServiceCatalog, ServiceCatalogEntry } from "../types/index.js";
 import { getDistRoot } from "../paths.js";
-import { requireGithubOrg } from "../den-config.js";
+import { readDenConfig, requireGithubOrg } from "../den-config.js";
+import {
+  parseRemote,
+  repoSource,
+  type WorkOrgsConfig,
+} from "../org-sources.js";
+import { checkedRemote, isGitRemote } from "./git-remote.js";
 
 /** Fallback GitHub org when `config/den.yml` doesn't set `github_org`. */
 
@@ -77,6 +83,51 @@ export function resolveRepoGhSlug(
   return `${owner()}/${repoName}`;
 }
 
+/**
+ * What `repoName` clones from (ORG-1d): a GitHub slug or a git URL (see
+ * git-remote.ts). The repo's source decides: a GitHub source gives its slug
+ * (`gh`, else `<owner>/<repo>`). A repo with no source and a `remote:` gives
+ * that remote, through plain git. Anything else is the legacy GitHub slug
+ * (resolveRepoGhSlug), so a catalog without `remote:` clones as before.
+ */
+export function resolveRepoCloneSource(
+  repoName: string,
+  catalog: ServiceCatalog = readCatalog(),
+  owner: () => string = () => requireGithubOrg(),
+  orgs: WorkOrgsConfig | undefined = readDenConfig().orgs,
+): string {
+  const entry = catalog[repoName];
+  const gh = entry?.gh?.trim();
+  const remote = entry?.remote?.trim();
+  const src = repoSource(repoName, catalog, orgs ?? {});
+  if (src?.host === "github") {
+    if (gh) return gh;
+    const fromRemote = remote ? parseRemote(remote) : null;
+    return fromRemote?.host === "github"
+      ? `${fromRemote.owner}/${repoName}`
+      : `${src.owner ?? ""}/${repoName}`;
+  }
+  if (remote) return checkedRemote(repoName, remote);
+  if (src)
+    throw new Error(
+      `${repoName}: its org's source is on ${src.host}, which Den clones only ` +
+        `from a remote: — set ${repoName}.remote in the service catalog`,
+    );
+  return resolveRepoGhSlug(repoName, catalog, owner);
+}
+
+/**
+ * Whether a clone source may be written back as the catalog's `gh` (the
+ * empty-slug repair): only a GitHub slug, and only for an entry with no
+ * `gh` and no `remote` of its own.
+ */
+export function needsGhRepair(
+  entry: ServiceCatalogEntry | undefined,
+  source: string,
+): boolean {
+  return !isGitRemote(source) && !entry?.gh?.trim() && !entry?.remote?.trim();
+}
+
 export function removeCatalogEntry(repoName: string): void {
   const catalog = readCatalog();
   delete catalog[repoName];

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

@@ -22,8 +22,10 @@ import {
 import {
   githubOrgFor,
   readOrgContext,
+  resolveWorkspaceOrg,
   type OrgContext,
 } from "./workspace-org.js";
+import { orgHasGithub } from "../org-sources.js";
 import type {
   ServiceCatalog,
   WorkspaceConfig,
@@ -71,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
@@ -83,11 +95,17 @@ export function catalogFill(
   ctx: OrgContext = readOrgContext(),
 ): Map<string, string> {
   const fill = new Map<string, string>();
-  for (const ws of workspaces)
+  for (const ws of workspaces) {
+    // ORG-1d: an org with no GitHub source has no slug to give; its repos
+    // clone from their catalog `remote:`.
+    const org = resolveWorkspaceOrg(ws.name, ctx).org;
+    if (org && !orgHasGithub(org, ctx.config.orgs)) continue;
     for (const repo of ws.repos) {
-      if (catalog[repo]?.gh || fill.has(repo)) continue;
+      if (catalog[repo]?.gh || catalog[repo]?.remote || fill.has(repo))
+        continue;
       fill.set(repo, `${githubOrgFor(ws.name, ctx)}/${repo}`);
     }
+  }
   return fill;
 }
 
@@ -166,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.
@@ -188,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));
   });
 }
@@ -214,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"];
@@ -240,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);

package/src/shared/environment-manager/git-remote.ts

@@ -0,0 +1,49 @@
+/**
+ * What a managed clone is made from (ORG-1d): a GitHub slug (`owner/repo`,
+ * cloned from github.com with the user's gh as credential helper) or a git
+ * URL from the catalog's `remote:` (cloned through plain git and the user's
+ * own credential helper, never Den's or gh's: SEC-0).
+ *
+ * Clone commands run through a shell, so a remote must pass REMOTE_RE: a URL
+ * with a known transport, scp-style `user@host:path`, or an absolute path,
+ * and nothing a shell or git would read as a command (`ext::`, quotes, `$`,
+ * spaces, a leading `-`).
+ */
+
+/** A GitHub slug, as the clone guards accept it. */
+export const SAFE_SLUG_RE = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/;
+
+const REMOTE_RE =
+  /^(?:(?:https?|ssh|git|file):\/\/[A-Za-z0-9._~@:%+/-]+|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[A-Za-z0-9._~+/-]+|\/[A-Za-z0-9._~@+/-]+)$/;
+
+/** True when `spec` is a git URL rather than a GitHub slug. */
+export function isGitRemote(spec: string): boolean {
+  return !SAFE_SLUG_RE.test(spec);
+}
+
+/** True when `remote` is a git URL Den will hand to git. */
+export function isSafeRemote(remote: string): boolean {
+  return REMOTE_RE.test(remote) && !remote.includes("..");
+}
+
+/**
+ * `remote` for display: any user info (`https://user:token@host/…`) masked.
+ * Remotes can carry a token, so one is never printed as written.
+ */
+export function redactRemote(remote: string): string {
+  return remote.replace(/^([a-z+]+:\/\/)[^@/]+@/i, "$1***@");
+}
+
+/**
+ * The checked remote for `repo`, or a throw naming its catalog key (and not
+ * its value, which may hold a token).
+ */
+export function checkedRemote(repo: string, remote: string): string {
+  const r = remote.trim();
+  if (!isSafeRemote(r))
+    throw new Error(
+      `service catalog: ${repo}.remote is not a git URL Den can clone ` +
+        `(https://, ssh://, git://, file://, user@host:path or an absolute path)`,
+    );
+  return r;
+}