dsh-zen-remote 2.2.8 → 2.3.1

package/src/wizard/caddy-process.ts

@@ -0,0 +1,228 @@
+/**
+ * Managed-Caddy process lifecycle (GW-3). The Caddyfile's content is
+ * caddy.ts's job; this module owns everything with a heartbeat:
+ *
+ *   start: ensureBinary (GW-2, cached after the first download) →
+ *          generateCaddyfile (typed refusals) → write the Caddyfile as a
+ *          `.part` sibling → `caddy validate --config <part> --adapter
+ *          caddyfile` → only on a clean validate rename it to the real
+ *          path → `caddy run --config <Caddyfile>`. The ticket's "validate
+ *          before write" is honored as validate-before-PUBLISH: the final
+ *          Caddyfile on disk only ever holds bytes Caddy accepted, and a
+ *          failed validate leaves neither a start nor a published file.
+ *
+ *   The Cloudflare API token travels in the child's ENVIRONMENT
+ *   (`CF_API_TOKEN`, what the generated `{env.CF_API_TOKEN}` placeholder
+ *   reads) — never in argv, which other processes on the machine can see.
+ *
+ *   Idempotency: start with a live process refuses (`already-running`) —
+ *   switching configuration stops first (design: 切换路时先停旧进程再启新的).
+ *   stop is idempotent; an exited child clears its own slot so a later
+ *   start works. The host wiring hands stop to ctx.effect, so the row's
+ *   disposal kills Caddy too.
+ *
+ * The subprocess service is structural (the tests feed a recorder), and
+ * `fetch` is injectable for the ensureBinary step.
+ */
+
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { ensureBinary, BinaryDownloadError, type DownloadProgress } from './binary-io.js'
+import { caddyDataDir, caddyfilePath, ingressDir, type BinaryPlatform } from './binary.js'
+import { generateCaddyfile, type CaddyfileInput } from './caddy.js'
+
+/** The slice of DSH's subprocess service the manager drives (structural so
+ * tests record instead of exec). */
+export interface SubprocessHandleLike {
+  terminate(): unknown
+  done: Promise<{ exitCode?: number | null; signal?: string | null }>
+}
+
+export interface SubprocessServiceLike {
+  spawn(options: {
+    argv: string[]
+    cwd?: string
+    env?: NodeJS.ProcessEnv
+    stdio?: unknown
+    graceMs?: number
+  }): SubprocessHandleLike
+}
+
+export interface CaddyManagerOptions {
+  /** The host's subprocess service (ctx.subprocess). */
+  subprocess: SubprocessServiceLike
+  /** `<DSH_HOME>` — binaries, Caddyfile and caddy-data all live under it. */
+  dshHome: string
+  /** Injected transport for the one-time binary download (tests point it
+   * at a mock server). */
+  fetchImpl?: typeof fetch
+  /** Forced platform mapping (tests). */
+  platform?: BinaryPlatform
+  /** Download progress relay (bytes, declared total or null). */
+  onProgress?: DownloadProgress
+  /** Stdio byte caps for the child, both streams. Default 64 KiB — enough
+   * for the startup banner and an error or two. */
+  maxLogBytes?: number
+}
+
+export type CaddyStartResult =
+  | { ok: true; binaryPath: string; caddyfile: string; alreadyRunning: false }
+  | {
+    ok: false
+    error: 'already-running' | 'missing-token' | 'bad-config' | 'download-failed' | 'validate-failed' | 'spawn-failed'
+    /** The generateCaddyfile error code for `bad-config`, or a short
+     * human-readable line for the transport/spawn failures. */
+    detail?: string
+    /** Official manual-install link, present for `download-failed`. */
+    installUrl?: string
+  }
+
+export interface CaddyManager {
+  /**
+   * Idempotent front door: a live Caddy refuses a second start (stop
+   * first to switch configuration). Throws nothing — every failure is a
+   * value. The storage directory is this manager's own (under dshHome) —
+   * callers supply only the user-facing fields.
+   */
+  start(input: Omit<CaddyfileInput, 'storageDir'> & { cfToken: unknown }): Promise<CaddyStartResult>
+  /** Idempotent terminate; safe before any start. */
+  stop(): void
+  /** Whether a child is currently held (true between spawn and exit). */
+  isRunning(): boolean
+  /** The live child's Caddyfile path, or undefined. */
+  runningCaddyfile(): string | undefined
+  /** Whether any start has succeeded in this manager's lifetime. */
+  hasStarted(): boolean
+}
+
+export function createCaddyManager(options: CaddyManagerOptions): CaddyManager {
+  const { subprocess, dshHome } = options
+  const maxLogBytes = options.maxLogBytes ?? 64 * 1024
+  let handle: SubprocessHandleLike | null = null
+  let caddyfileArg: string | undefined
+  let startedOnce = false
+
+  // GW-fix-2/L3: a WHITELIST, not the host's full environment — the host
+  // process carries the relay secret and DSH's own credentials in env, and
+  // a child that only needs to reach the internet and the local disk has
+  // no business inheriting them. Include Windows system/profile variables so
+  // Go's TLS root-cert store and winsock initialize cleanly on Windows.
+  const childEnv = (cfToken: string): NodeJS.ProcessEnv => {
+    const env: NodeJS.ProcessEnv = {}
+    for (const key of [
+      'PATH', 'HOME', 'TMPDIR', 'LANG', 'TZ',
+      'SystemRoot', 'SYSTEMROOT', 'windir', 'WINDIR',
+      'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA', 'TEMP', 'TMP',
+    ]) {
+      if (process.env[key] !== undefined) env[key] = process.env[key]
+    }
+    // The one secret this child needs, by env only (the Caddyfile reads
+    // {env.CF_API_TOKEN}) — never argv.
+    env.CF_API_TOKEN = cfToken
+    return env
+  }
+
+  const spawnChild = (argv: string[], env: NodeJS.ProcessEnv): SubprocessHandleLike =>
+    subprocess.spawn({
+      argv,
+      cwd: dshHome,
+      env,
+      stdio: {
+        stdin: 'ignore',
+        stdout: { maxBytes: maxLogBytes },
+        stderr: { maxBytes: maxLogBytes },
+      },
+      graceMs: 3000,
+    })
+
+  return {
+    async start(input) {
+      if (handle !== null) return { ok: false, error: 'already-running' }
+      const cfToken = typeof input.cfToken === 'string' && input.cfToken.trim() !== '' ? input.cfToken : undefined
+      if (cfToken === undefined) return { ok: false, error: 'missing-token' }
+      const generated = generateCaddyfile({ ...input, storageDir: caddyDataDir(dshHome) })
+      if (!generated.ok) return { ok: false, error: 'bad-config', detail: generated.error }
+
+      let binaryPath: string
+      try {
+        binaryPath = (await ensureBinary(dshHome, 'caddy', {
+          fetchImpl: options.fetchImpl,
+          platform: options.platform,
+          onProgress: options.onProgress,
+        })).path
+      } catch (error) {
+        if (error instanceof BinaryDownloadError) {
+          return { ok: false, error: 'download-failed', detail: error.message, installUrl: error.installUrl }
+        }
+        return { ok: false, error: 'download-failed', detail: String((error as Error)?.message ?? error) }
+      }
+
+      // Write → validate → publish: the `.part` file carries the exact
+      // bytes under validation, so what lands at the real path is exactly
+      // what Caddy accepted.
+      const finalPath = caddyfilePath(dshHome)
+      const partPath = `${finalPath}.part`
+      try {
+        mkdirSync(ingressDir(dshHome), { recursive: true })
+        writeFileSync(partPath, generated.caddyfile, { mode: 0o600 })
+        const validate = spawnChild([binaryPath, 'validate', '--config', partPath, '--adapter', 'caddyfile'], childEnv(cfToken))
+        const outcome = await validate.done
+        if ((outcome.exitCode ?? 1) !== 0) {
+          rmSync(partPath, { force: true })
+          return { ok: false, error: 'validate-failed' }
+        }
+        renameSync(partPath, finalPath)
+      } catch (error) {
+        rmSync(partPath, { force: true })
+        return { ok: false, error: 'spawn-failed', detail: String((error as Error)?.message ?? error) }
+      }
+
+      const env = childEnv(cfToken)
+      try {
+        const child = spawnChild([binaryPath, 'run', '--config', finalPath], env)
+        handle = child
+        caddyfileArg = finalPath
+        startedOnce = true
+        // An exited child clears its own slot: isRunning() goes honest and
+        // a later start() works without a manual stop.
+        void child.done.then(() => {
+          if (handle === child) {
+            handle = null
+            caddyfileArg = undefined
+          }
+        }).catch(() => {
+          if (handle === child) {
+            handle = null
+            caddyfileArg = undefined
+          }
+        })
+        return { ok: true, binaryPath, caddyfile: finalPath, alreadyRunning: false }
+      } catch (error) {
+        handle = null
+        caddyfileArg = undefined
+        return { ok: false, error: 'spawn-failed', detail: String((error as Error)?.message ?? error) }
+      }
+    },
+
+    stop() {
+      if (handle === null) return
+      const child = handle
+      handle = null
+      caddyfileArg = undefined
+      try {
+        void child.terminate()
+      } catch {
+        // A dead child's terminate is a no-op or a throw — either way done.
+      }
+    },
+
+    isRunning: () => handle !== null,
+    runningCaddyfile: () => caddyfileArg,
+    /** Whether a start has EVER succeeded in this row's lifetime — the
+     * three-state status needs it to tell 已退出 (degraded) from 未启动. */
+    hasStarted: () => startedOnce,
+  }
+}
+
+/** Re-exported so the wiring (and later the routes) need one import for
+ * the whole ingress-directory layout. */
+export { caddyDataDir, caddyfilePath, ingressDir }

package/src/wizard/caddy.ts

@@ -0,0 +1,97 @@
+/**
+ * Caddyfile generation (GW-3), pure logic — every byte the managed Caddy
+ * will run comes out of {@link generateCaddyfile}, so the validation and
+ * the injection guards live HERE and the process half (caddy-process.ts)
+ * only writes, validates and spawns what this answered.
+ *
+ * Shape (design.md 路 A), with one deliberate correction to the design
+ * sketch: the global DNS-01 option in a real Caddyfile is `acme_dns
+ * <provider> <token-placeholder>` — the sketch's bare `dns cloudflare`
+ * line is site-block `tls` syntax and is not valid as a global option.
+ * The DNS-01 challenge itself is the point: the certificate is ordered
+ * through Cloudflare's API (the token rides the `CF_API_TOKEN`
+ * environment variable, never the file), so neither 80 nor 443 needs to
+ * be reachable from outside for issuance; only the HTTPS service port
+ * must be.
+ *
+ * Injection posture: every interpolated value passes a charset gate —
+ * the domain through config.ts's `hostOf` (the exact validator the row
+ * layer applies), the storage path free of control characters, quotes and
+ * braces (Caddyfile's block delimiters), the env-var name as a legal
+ * POSIX name. Nothing else from the outside world reaches the output.
+ */
+
+import { hostOf } from '../config.js'
+
+/** The default environment variable the Cloudflare token rides in on. */
+export const CF_TOKEN_ENV_DEFAULT = 'CF_API_TOKEN'
+
+export interface CaddyfileInput {
+  /** Public ingress domain, bare hostname (validated like the row field). */
+  domain: unknown
+  /** HTTPS port the managed Caddy listens on. [1, 65535]. */
+  httpsPort: unknown
+  /** The gateway's ACTUAL listening port — the caller reads it from the
+   * running gateway, never the configured one (it may have retried). */
+  gatewayPort: unknown
+  /** Caddy storage directory (certificates + ACME account). */
+  storageDir: unknown
+  /** Environment variable name the Cloudflare token arrives in. */
+  cfTokenEnvName?: unknown
+}
+
+export type CaddyfileResult =
+  | { ok: true; caddyfile: string; domain: string; httpsPort: number; gatewayPort: number }
+  | { ok: false; error: 'bad-domain' | 'bad-https-port' | 'bad-gateway-port' | 'bad-storage' | 'bad-token-env' }
+
+/** Integers in [1, 65535] only. */
+function portOf(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 65535 ? value : undefined
+}
+
+/** Storage paths go into the Caddyfile quoted; anything that could break
+ * out of the quoting or forge a block delimiter is refused — control
+ * characters (newlines foremost), quotes, braces. */
+function storageDirOf(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value === '') return undefined
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f"{}]/.test(value)) return undefined
+  return value
+}
+
+/** Env names: POSIX uppercase convention, strictly. */
+const ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/
+
+/**
+ * Build the complete Caddyfile for the managed Caddy. Refuses (typed)
+ * instead of throwing so the caller can map each refusal to a form error.
+ */
+export function generateCaddyfile(input: CaddyfileInput): CaddyfileResult {
+  const domain = hostOf(input.domain)
+  if (domain === undefined) return { ok: false, error: 'bad-domain' }
+  const httpsPort = portOf(input.httpsPort)
+  if (httpsPort === undefined) return { ok: false, error: 'bad-https-port' }
+  const gatewayPort = portOf(input.gatewayPort)
+  if (gatewayPort === undefined) return { ok: false, error: 'bad-gateway-port' }
+  const storageDir = storageDirOf(input.storageDir)
+  if (storageDir === undefined) return { ok: false, error: 'bad-storage' }
+  const tokenEnv = typeof input.cfTokenEnvName === 'string' && ENV_NAME_PATTERN.test(input.cfTokenEnvName)
+    ? input.cfTokenEnvName
+    : CF_TOKEN_ENV_DEFAULT
+  if (input.cfTokenEnvName !== undefined && input.cfTokenEnvName !== '' && tokenEnv !== input.cfTokenEnvName) {
+    return { ok: false, error: 'bad-token-env' }
+  }
+  const caddyfile = [
+    '{',
+    `\tacme_dns cloudflare {env.${tokenEnv}}`,
+    `\tstorage file_system "${storageDir}"`,
+    '\tadmin off',
+    '}',
+    '',
+    `https://${domain}:${httpsPort} {`,
+    `\treverse_proxy 127.0.0.1:${gatewayPort}`,
+    '}',
+    '',
+  ].join('\n')
+  return { ok: true, caddyfile, domain, httpsPort, gatewayPort }
+}