@hienlh/ppm 0.18.12 → 0.18.13

package/src/services/named-tunnel/cloudflared-cert.ts

@@ -0,0 +1,95 @@
+/**
+ * Parse `~/.cloudflared/cert.pem` — the credential `cloudflared tunnel login` writes.
+ * State is always derived by parsing the file, never `existsSync`: a truncated,
+ * foreign, or revoked cert must never look "authenticated" just because a file
+ * happens to sit at the expected path.
+ */
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+
+export interface ArgoCert {
+  zoneID: string;
+  accountID: string;
+  apiToken: string;
+}
+
+export type CertState =
+  | { kind: "absent" }
+  | { kind: "unparseable"; reason: string }
+  | { kind: "parsed"; cert: ArgoCert };
+
+const HEX32 = /^[0-9a-f]{32}$/;
+// The real-world label cloudflared ships today.
+const STRICT_BLOCK = /-----BEGIN ARGO TUNNEL TOKEN-----([\s\S]*?)-----END ARGO TUNNEL TOKEN-----/;
+// Fallback for a future cloudflared build that renames the label — accept any
+// "...TOKEN..." PEM block rather than hard-failing every login on a cosmetic
+// rename, while still preferring the known-good label as the first match.
+const GENERIC_TOKEN_BLOCK = /-----BEGIN ([A-Z0-9 ]*TOKEN[A-Z0-9 ]*)-----([\s\S]*?)-----END \1-----/;
+
+/**
+ * `cloudflared` decides this location, not PPM — it is a deliberate real-`homedir()`
+ * exception (see CLAUDE.md's "PPM Directory" section): `getPpmDir()` would point
+ * PPM's own data elsewhere and never find the user's actual login credential.
+ */
+export function getOriginCertPath(): string {
+  return process.env.TUNNEL_ORIGIN_CERT || resolve(homedir(), ".cloudflared", "cert.pem");
+}
+
+/** Extract the token PEM block's base64 payload, trying the strict label first. */
+function extractPayload(pem: string): string | null {
+  const strict = pem.match(STRICT_BLOCK);
+  if (strict) return strict[1]!;
+  const generic = pem.match(GENERIC_TOKEN_BLOCK);
+  if (generic) return generic[2]!;
+  return null;
+}
+
+/**
+ * Read and parse the origin cert. Never throws — every failure mode collapses
+ * to `unparseable` with a reason string that is safe to log (it never contains
+ * the base64 payload or any field value, so a leaked apiToken can't hide in it).
+ */
+export function readOriginCertState(path?: string): CertState {
+  const certPath = path ?? getOriginCertPath();
+  if (!existsSync(certPath)) return { kind: "absent" };
+
+  let raw: string;
+  try {
+    raw = readFileSync(certPath, "utf-8");
+  } catch {
+    return { kind: "unparseable", reason: "cert.pem could not be read" };
+  }
+
+  const payload = extractPayload(raw);
+  if (payload == null) return { kind: "unparseable", reason: "no TOKEN PEM block found" };
+
+  let decoded: string;
+  try {
+    decoded = Buffer.from(payload.replace(/\s+/g, ""), "base64").toString("utf-8");
+  } catch {
+    return { kind: "unparseable", reason: "PEM block is not valid base64" };
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(decoded);
+  } catch {
+    return { kind: "unparseable", reason: "PEM payload is not valid JSON" };
+  }
+
+  if (typeof json !== "object" || json === null) {
+    return { kind: "unparseable", reason: "PEM payload is not a JSON object" };
+  }
+  const obj = json as Record<string, unknown>;
+  const { zoneID, accountID, apiToken } = obj;
+  if (typeof zoneID !== "string" || !zoneID || typeof accountID !== "string" || !accountID ||
+      typeof apiToken !== "string" || !apiToken) {
+    return { kind: "unparseable", reason: "cert is missing zoneID/accountID/apiToken" };
+  }
+  if (!HEX32.test(zoneID) || !HEX32.test(accountID)) {
+    return { kind: "unparseable", reason: "zoneID/accountID are not 32-char hex ids" };
+  }
+
+  return { kind: "parsed", cert: { zoneID, accountID, apiToken } };
+}

package/src/services/named-tunnel/cloudflared-exec.ts

@@ -0,0 +1,50 @@
+/**
+ * One-shot cloudflared invocations (`tunnel create`, `route dns`, `tunnel
+ * token`) — distinct from the long-running login process in
+ * `cloudflared-login.service.ts`, which needs incremental stdout/stderr reads
+ * instead of a single awaited result.
+ */
+import { ensureCloudflared } from "../cloudflared.service.ts";
+import { killProcessTree } from "../windows-process-tree.ts";
+
+export interface RunCloudflaredResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Short one-shot calls must never hang setup indefinitely on a network stall. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Spawn cloudflared with `args`, capture both streams, and enforce a timeout.
+ * Never logs `args` — phase 1b's argv builders already keep them secret-free
+ * (the run token travels via `--token-file`, never argv), so this stays that
+ * way rather than re-introducing a leak at the logging layer.
+ */
+export async function runCloudflared(
+  args: string[],
+  opts: { timeoutMs?: number } = {},
+): Promise<RunCloudflaredResult> {
+  const bin = await ensureCloudflared();
+  const proc = Bun.spawn([bin, ...args], { stdout: "pipe", stderr: "pipe" });
+
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killProcessTree(proc.pid);
+  }, timeoutMs);
+
+  try {
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (timedOut) throw new Error(`cloudflared timed out after ${timeoutMs}ms`);
+    return { code, stdout, stderr };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/services/named-tunnel/cloudflared-login-helpers.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure/self-contained helpers for the login session state machine, split out
+ * of `cloudflared-login.service.ts` purely to keep that file under the
+ * project's line-count guideline — none of these hold their own module state.
+ */
+import { existsSync, renameSync } from "node:fs";
+import { getOriginCertPath } from "./cloudflared-cert.ts";
+import { resolveTunnelConfig } from "./named-tunnel-config.ts";
+import { configService } from "../config.service.ts";
+import { extractLoginUrl, isLoginSuccess } from "./login-output-parser.ts";
+
+const VERIFY_TIMEOUT_MS = 8_000;
+
+export type CertLiveCheck = "valid" | "invalid" | "unreachable";
+
+/**
+ * Live-checks an apiToken against Cloudflare, distinguishing an authoritative
+ * rejection from simply failing to ask. This distinction is the whole point:
+ * the caller renames a stale cert.pem aside on "invalid" (Cloudflare itself
+ * said the token is dead) but must NOT do that on "unreachable" (a network
+ * blip, timeout, rate limit, or Cloudflare-side outage) — a user on a flaky
+ * connection who presses "Set up" must never have a perfectly working
+ * credential discarded just because the verify call itself didn't land.
+ */
+export async function verifyCertLive(apiToken: string): Promise<CertLiveCheck> {
+  let res: Response;
+  try {
+    res = await fetch("https://api.cloudflare.com/client/v4/user/tokens/verify", {
+      headers: { Authorization: `Bearer ${apiToken}` },
+      signal: AbortSignal.timeout(VERIFY_TIMEOUT_MS),
+    });
+  } catch {
+    return "unreachable"; // network error, DNS failure, or the bounded timeout firing
+  }
+
+  // 401/403: Cloudflare rejected the token outright. 429/5xx: rate-limited or
+  // Cloudflare's own outage — neither says anything about the token itself.
+  if (res.status === 401 || res.status === 403) return "invalid";
+  if (res.status === 429 || res.status >= 500) return "unreachable";
+
+  const json = (await res.json().catch(() => null)) as { success?: boolean } | null;
+  if (json?.success === true) return "valid";
+  if (json?.success === false) return "invalid";
+  return "unreachable"; // an unexpected response shape is not an authoritative rejection
+}
+
+/** True when no `tunnel` identity is pinned yet, or the cert matches the pinned one. */
+export function pinsMatch(cert: { zoneID: string; accountID: string }): boolean {
+  const resolved = resolveTunnelConfig(configService.get("tunnel"));
+  if (resolved.mode !== "named") return true;
+  return resolved.zoneID === cert.zoneID && resolved.accountID === cert.accountID;
+}
+
+/** Rename an existing cert.pem aside so a stale/foreign cert can never block a fresh login. */
+export function renameCertAside(): void {
+  const path = getOriginCertPath();
+  if (!existsSync(path)) return;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  renameSync(path, `${path}.bak-${stamp}`);
+}
+
+/**
+ * Read a login process's stdout/stderr stream incrementally: report the URL
+ * as soon as it appears, and signal success the moment the success line
+ * shows up (without waiting for the process to exit). `isSuperseded` lets the
+ * caller bail out the instant this stream stops being the "current" one
+ * (cancel/retry/timeout raced ahead of us).
+ */
+export async function pumpLoginStream(
+  stream: ReadableStream<Uint8Array>,
+  hooks: { isSuperseded: () => boolean; hasUrl: () => boolean; onUrl: (url: string) => void; onSuccess: () => void },
+): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (hooks.isSuperseded()) return;
+
+      const chunk = decoder.decode(value, { stream: true });
+      buffered += chunk;
+
+      if (!hooks.hasUrl()) {
+        const url = extractLoginUrl(chunk) ?? extractLoginUrl(buffered);
+        if (url) hooks.onUrl(url);
+      }
+      if (isLoginSuccess(chunk) || isLoginSuccess(buffered)) {
+        hooks.onSuccess();
+        return;
+      }
+    }
+  } catch {
+    // Stream closed underneath us (process killed) — a terminal state has
+    // already been (or is about to be) set by whichever timer/cancel did it.
+  }
+}

package/src/services/named-tunnel/cloudflared-login.service.ts

@@ -0,0 +1,182 @@
+/**
+ * Login session singleton behind the "log in to Cloudflare" popup.
+ *
+ * One process-per-machine at a time: a second `startLogin` call while one is
+ * live (`waiting`/`slow`) just returns the current snapshot instead of
+ * spawning a competing `cloudflared tunnel login`. Every terminal state
+ * (`success`/`timeout`/`cancelled`/`error`) drops the process ref, so the
+ * *next* call after a terminal state always starts a genuinely fresh process
+ * with a fresh URL — a killed session's URL is gone for good, there is no
+ * "cert appears later" path once the process is dead.
+ */
+import { readOriginCertState } from "./cloudflared-cert.ts";
+import { loginArgs } from "./named-tunnel-args.ts";
+import { ensureCloudflared } from "../cloudflared.service.ts";
+import { killProcessTree } from "../windows-process-tree.ts";
+import { broadcastGlobalEvent } from "../../server/ws/global.ts";
+import { verifyCertLive, pinsMatch, renameCertAside, pumpLoginStream } from "./cloudflared-login-helpers.ts";
+
+export type LoginState = "idle" | "waiting" | "slow" | "success" | "timeout" | "cancelled" | "error";
+export interface LoginSnapshot { state: LoginState; url: string | null; message: string | null }
+
+export const LOGIN_SLOW_MS = 60_000;
+export const LOGIN_TIMEOUT_MS = 300_000;
+const CERT_POLL_MS = 2_000;
+
+interface Session {
+  state: LoginState;
+  url: string | null;
+  message: string | null;
+  proc: ReturnType<typeof Bun.spawn> | null;
+  slowTimer: ReturnType<typeof setTimeout> | null;
+  killTimer: ReturnType<typeof setTimeout> | null;
+  certPollTimer: ReturnType<typeof setInterval> | null;
+}
+
+function freshSession(): Session {
+  return { state: "idle", url: null, message: null, proc: null, slowTimer: null, killTimer: null, certPollTimer: null };
+}
+
+let session: Session = freshSession();
+
+export function getLoginSnapshot(): LoginSnapshot {
+  return { state: session.state, url: session.url, message: session.message };
+}
+
+function clearTimers(): void {
+  if (session.slowTimer) clearTimeout(session.slowTimer);
+  if (session.killTimer) clearTimeout(session.killTimer);
+  if (session.certPollTimer) clearInterval(session.certPollTimer);
+  session.slowTimer = null;
+  session.killTimer = null;
+  session.certPollTimer = null;
+}
+
+/** Move to a terminal state: clear timers, drop the process ref, broadcast. */
+function setTerminal(state: LoginState, message: string | null): void {
+  clearTimers();
+  session.proc = null;
+  session.state = state;
+  session.message = message;
+  broadcastGlobalEvent({ type: "tunnel:login_state", state, message: message ?? undefined });
+}
+
+/** Wraps `pumpLoginStream` with this module's session-singleton hooks. */
+function pumpStream(stream: ReadableStream<Uint8Array>, proc: ReturnType<typeof Bun.spawn>): Promise<void> {
+  return pumpLoginStream(stream, {
+    isSuperseded: () => session.proc !== proc,
+    hasUrl: () => session.url != null,
+    onUrl: (url) => {
+      session.url = url;
+      broadcastGlobalEvent({ type: "tunnel:login_url", url });
+    },
+    onSuccess: () => setTerminal("success", "logged in"),
+  });
+}
+
+/**
+ * Start (or return the live) login session.
+ *
+ * The cert-present shortcut is intentionally re-verified on every call — not
+ * a bare `existsSync` — because a replaced or revoked cert must never
+ * silently pass as "already logged in".
+ */
+export async function startLogin(opts: { relogin?: boolean } = {}): Promise<LoginSnapshot> {
+  if (session.state === "waiting" || session.state === "slow") {
+    return getLoginSnapshot();
+  }
+
+  const relogin = !!opts.relogin;
+  if (!relogin) {
+    const certState = readOriginCertState();
+    if (certState.kind === "parsed") {
+      const liveCheck = await verifyCertLive(certState.cert.apiToken);
+
+      // WHY: a network blip must never discard a working credential. Only an
+      // authoritative "Cloudflare said no" (invalid) or a confirmed pin
+      // mismatch earns a rename-aside below; "unreachable" means the check
+      // itself failed to run, so cert.pem is left untouched and the user
+      // gets a clear, retryable error instead of an unwanted fresh login.
+      if (liveCheck === "unreachable") {
+        setTerminal("error", "không kết nối được Cloudflare để kiểm tra đăng nhập — thử lại");
+        return getLoginSnapshot();
+      }
+
+      if (liveCheck === "valid" && pinsMatch(certState.cert)) {
+        session = freshSession();
+        session.state = "success";
+        session.message = "already logged in";
+        return getLoginSnapshot();
+      }
+
+      // liveCheck === "invalid" (Cloudflare authoritatively rejected the
+      // token), or valid but pinned to a different account/zone: this cert
+      // can never pass the shortcut again as-is — move it aside now instead
+      // of leaving a bad file to keep silently triggering the same
+      // fallthrough on every future login attempt.
+      renameCertAside();
+    }
+  } else {
+    // Explicit ?relogin=1 — the user deliberately pressed "Đăng nhập lại",
+    // so this renames unconditionally regardless of network reachability.
+    renameCertAside();
+  }
+
+  const bin = await ensureCloudflared();
+  const proc = Bun.spawn([bin, ...loginArgs()], { stdout: "pipe", stderr: "pipe" });
+  session = { state: "waiting", url: null, message: null, proc, slowTimer: null, killTimer: null, certPollTimer: null };
+
+  session.slowTimer = setTimeout(() => {
+    if (session.proc !== proc) return;
+    session.state = "slow";
+    broadcastGlobalEvent({ type: "tunnel:login_state", state: "slow" });
+  }, LOGIN_SLOW_MS);
+
+  session.killTimer = setTimeout(() => {
+    if (session.proc !== proc) return;
+    killProcessTree(proc.pid);
+    setTerminal("timeout", "login timed out after 5 minutes");
+  }, LOGIN_TIMEOUT_MS);
+
+  session.certPollTimer = setInterval(() => {
+    if (session.proc !== proc) return;
+    if (readOriginCertState().kind === "parsed") setTerminal("success", "logged in");
+  }, CERT_POLL_MS);
+
+  Promise.all([pumpStream(proc.stdout, proc), pumpStream(proc.stderr, proc)])
+    .then(async () => {
+      if (session.proc !== proc) return; // already terminal
+      const code = await proc.exited;
+      if (session.proc !== proc) return;
+      if (code === 0) {
+        setTerminal("success", "logged in");
+      } else {
+        setTerminal("error", `cloudflared exited with code ${code}`);
+      }
+    })
+    .catch(() => {});
+
+  return getLoginSnapshot();
+}
+
+/** Kill the live process immediately (if any) and mark the session cancelled. */
+export function cancelLogin(): void {
+  if (session.proc) killProcessTree(session.proc.pid);
+  setTerminal("cancelled", "cancelled");
+}
+
+// Orphaned login process on server crash/restart would otherwise wait forever
+// for a browser callback that lands nowhere.
+process.on("exit", () => {
+  if (session.proc) {
+    try { killProcessTree(session.proc.pid); } catch {}
+  }
+});
+
+/**
+ * Aggregate for callers that need a single patchable seam (the HTTP routes) —
+ * route tests monkey-patch these properties directly rather than reaching for
+ * `mock.module`, which replaces the module for every importer process-wide and
+ * would poison the direct-function unit tests in this same file's test suite.
+ */
+export const cloudflaredLoginService = { getLoginSnapshot, startLogin, cancelLogin };

package/src/services/named-tunnel/hostname-rules.ts

@@ -0,0 +1,58 @@
+/**
+ * Hostname shape rules for the named tunnel.
+ *
+ * Exactly one label above the zone, never the apex, never `www`. Two reasons,
+ * not just a rule to copy: `cloudflared route dns` never errors on a hostname
+ * outside the zone — it silently appends the zone instead (e.g. asking for
+ * `ppm-probe.ppm.sh` under zone `hienle.tech` creates `ppm-probe.ppm.sh.hienle.tech`),
+ * so PPM must refuse before calling it; and Cloudflare's free Universal SSL
+ * certificate only covers one level of subdomain, so a deeper label parses fine
+ * here but serves a TLS error to every visitor.
+ */
+
+export type HostnameCheck = { ok: true } | { ok: false; reason: string };
+
+const LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+const MAX_HOSTNAME_LENGTH = 253;
+
+/** Default proposal shown to the user: `ppm.<zone>`. */
+export function proposeHostname(zone: string): string {
+  return `ppm.${zone.trim().toLowerCase()}`;
+}
+
+/** Combine a user-typed prefix with the pinned zone. */
+export function buildHostname(prefix: string, zone: string): string {
+  return `${prefix.trim().toLowerCase()}.${zone.trim().toLowerCase()}`;
+}
+
+export function validateHostname(hostname: string, zone: string): HostnameCheck {
+  const host = hostname.trim().toLowerCase();
+  const z = zone.trim().toLowerCase();
+  if (!host || !z) return { ok: false, reason: "hostname and zone are required" };
+  if (host.length > MAX_HOSTNAME_LENGTH) return { ok: false, reason: "hostname exceeds 253 characters" };
+
+  if (host === z) {
+    return { ok: false, reason: "hostname cannot be the zone apex — a PPM token must never rewrite the zone's own record" };
+  }
+  if (host === `www.${z}`) {
+    return { ok: false, reason: "www is reserved" };
+  }
+  if (!host.endsWith(`.${z}`)) {
+    return { ok: false, reason: `hostname must be a subdomain of ${z} — cloudflared silently mis-routes anything else` };
+  }
+
+  // Everything above the zone must be exactly one label — Cloudflare's free
+  // certificate only covers one level, and a deeper label serves a TLS error.
+  const prefix = host.slice(0, host.length - z.length - 1);
+  if (prefix.includes(".")) {
+    return { ok: false, reason: "hostname must be exactly one label above the zone" };
+  }
+
+  for (const label of host.split(".")) {
+    if (!LABEL.test(label)) {
+      return { ok: false, reason: `invalid DNS label: "${label}"` };
+    }
+  }
+
+  return { ok: true };
+}

package/src/services/named-tunnel/login-output-parser.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure parsers for `cloudflared tunnel login` stdout/stderr chunks.
+ *
+ * cloudflared prints the browser URL and progress lines on stderr, not
+ * stdout (verified 2026-09-05, cloudflared 2026.3.0) — callers must feed both
+ * streams through these functions, never stdout alone.
+ */
+
+/** Primary shape: the real dash.cloudflare.com/argotunnel URL cloudflared prints today. */
+const PRIMARY_URL = /https:\/\/dash\.cloudflare\.com\/argotunnel\?[^\s]+/;
+
+/** Exact success line cloudflared prints on a successful login, exit code 0. */
+const SUCCESS_LINE = /You have successfully logged in\./;
+
+/**
+ * Extract the login URL from a stdout/stderr chunk (or accumulated buffer).
+ * Falls back to the first `https://` token on any line mentioning
+ * "argotunnel" so a cosmetic rename of the URL shape never leaves the flow
+ * stuck at `waiting` with no way for the user to open the browser page.
+ */
+export function extractLoginUrl(text: string): string | null {
+  const primary = text.match(PRIMARY_URL);
+  if (primary) return primary[0];
+
+  for (const line of text.split(/\r?\n/)) {
+    if (!/argotunnel/i.test(line)) continue;
+    const fallback = line.match(/https:\/\/[^\s]+/);
+    if (fallback) return fallback[0];
+  }
+  return null;
+}
+
+/** True once cloudflared has printed its success line. */
+export function isLoginSuccess(text: string): boolean {
+  return SUCCESS_LINE.test(text);
+}

package/src/services/named-tunnel/named-tunnel-args.ts

@@ -0,0 +1,110 @@
+/**
+ * cloudflared argv builders for the named-tunnel flow, plus the two artifact
+ * files they depend on. Every builder here guarantees its own artifacts (mirrors
+ * `cloudflared.service.ts`'s `getQuickTunnelArgs` → `ensureQuickTunnelConfig`
+ * pattern) rather than assuming an earlier phase already created them.
+ *
+ * The run token never appears in argv, ever — it is written to a 0600 file and
+ * passed via `--token-file`, so it can't leak through `ppm status`, a process
+ * list, or a crash dump that captures cmdlines.
+ */
+import { resolve } from "node:path";
+import { hostname as osHostname } from "node:os";
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { getPpmDir } from "../ppm-dir.ts";
+import { getOriginCertPath } from "./cloudflared-cert.ts";
+
+const namedTunnelConfigPath = () => resolve(getPpmDir(), "cloudflared-named.yml");
+const namedTunnelTokenPath = () => resolve(getPpmDir(), "named-tunnel.token");
+const isWindows = process.platform === "win32";
+
+/**
+ * Ensure `getPpmDir()` exists without letting a pre-existing directory throw
+ * EEXIST (Windows read-only-attribute folders — Desktop/Documents/Downloads —
+ * have thrown on a recursive mkdir here before even though the dir was already
+ * present and usable).
+ */
+function ensurePpmDir(): void {
+  if (existsSync(getPpmDir())) return;
+  try {
+    mkdirSync(getPpmDir(), { recursive: true, mode: 0o700 });
+  } catch (e: any) {
+    if (e?.code !== "EEXIST") throw e;
+  }
+}
+
+/** Best-effort chmod — POSIX enforces the mode; Windows has no equivalent bit. */
+function chmodBestEffort(path: string, mode: number): void {
+  if (isWindows) return;
+  try { chmodSync(path, mode); } catch {}
+}
+
+/**
+ * Create `~/.ppm/cloudflared-named.yml` if absent; returns its path.
+ * A comment-only file still parses but logs `ERR Configuration file ... was
+ * empty` on every command (harmless noise, verified live); a *missing* file
+ * exits 1. `no-autoupdate: true` is a real, valid key so the file is never
+ * comment-only.
+ */
+export function ensureNamedTunnelConfig(): string {
+  const path = namedTunnelConfigPath();
+  if (!existsSync(path)) {
+    ensurePpmDir();
+    writeFileSync(path, "no-autoupdate: true\n", { mode: 0o600 });
+  }
+  chmodBestEffort(path, 0o600);
+  return path;
+}
+
+/** Write the run token to a 0600 file; returns its path. Overwritten on every call. */
+export function writeNamedTunnelToken(token: string): string {
+  ensurePpmDir();
+  const path = namedTunnelTokenPath();
+  writeFileSync(path, token, { mode: 0o600 });
+  chmodBestEffort(path, 0o600);
+  return path;
+}
+
+/** `tunnel login` has no cert yet, so no `--origincert` — that flag would point nowhere. */
+export function loginArgs(): string[] {
+  return ["tunnel", "login"];
+}
+
+/** Global flags (`--origincert`/`--config`) always precede the subcommand. */
+function managementPrefix(): string[] {
+  return ["--origincert", getOriginCertPath(), "--config", ensureNamedTunnelConfig()];
+}
+
+export function createTunnelArgs(name: string): string[] {
+  return [...managementPrefix(), "tunnel", "create", name];
+}
+
+export function tunnelTokenArgs(name: string): string[] {
+  return [...managementPrefix(), "tunnel", "token", name];
+}
+
+/**
+ * `--overwrite-dns` only when the caller has confirmed this is our own tunnel's
+ * UUID being re-pointed (e.g. after a reset) — never passed blindly, since it
+ * silently steals a CNAME that might belong to something else.
+ */
+export function routeDnsArgs(name: string, hostname: string, overwrite: boolean): string[] {
+  const flags = overwrite ? ["--overwrite-dns"] : [];
+  return [...managementPrefix(), "tunnel", "route", "dns", ...flags, name, hostname];
+}
+
+/**
+ * Argv for the long-running named-tunnel process. No `--token` literal ever
+ * appears here — only a path to a 0600 file cloudflared reads itself.
+ */
+export function namedRunArgs(token: string, port: number): string[] {
+  const cfg = ensureNamedTunnelConfig();
+  const tokenPath = writeNamedTunnelToken(token);
+  return ["--config", cfg, "tunnel", "run", "--token-file", tokenPath, "--url", `http://127.0.0.1:${port}`];
+}
+
+/** Stable, DNS-safe tunnel name derived from this machine's hostname. */
+export function tunnelNameForHost(): string {
+  const sanitized = osHostname().toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  return `ppm-${sanitized}`.slice(0, 32);
+}