@cjhyy/code-shell-server 0.8.0

package/dist/mobile-remote/access-passcode.js

@@ -0,0 +1,354 @@
+import { createHmac, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_LOCKOUT_MS = 60_000;
+const DEFAULT_TOKEN_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const COOKIE_NAME = "cs_access";
+const SCRYPT_KEYLEN = 32;
+/**
+ * The public-tunnel access gate. A single shared passcode (set by the desktop
+ * user) guards the tunnel; a phone that enters it correctly receives a signed
+ * "remember" token stored in a cookie so it is not re-challenged. Security
+ * properties this unit guarantees:
+ *  - the passcode is only ever stored as a salted scrypt hash (no plaintext);
+ *  - remember-tokens are HMACs over a per-passcode secret, so rotating the
+ *    passcode invalidates every outstanding token;
+ *  - brute-force is rate-limited: N consecutive wrong attempts lock the gate
+ *    for a window, during which even the correct passcode is refused.
+ * The trusted-device + pairing layers still sit behind this (defense in depth).
+ */
+export class AccessPasscode {
+    filePath;
+    now;
+    maxAttempts;
+    lockoutMs;
+    tokenMaxAgeMs;
+    failures = 0;
+    lockedUntil = 0;
+    constructor(opts) {
+        this.filePath = opts.filePath;
+        this.now = opts.now ?? Date.now;
+        this.maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.lockoutMs = opts.lockoutMs ?? DEFAULT_LOCKOUT_MS;
+        this.tokenMaxAgeMs = opts.tokenMaxAgeMs ?? DEFAULT_TOKEN_MAX_AGE_MS;
+    }
+    isSet() {
+        return this.read() !== undefined;
+    }
+    /** Set (or rotate) the passcode. Rotating `secret` invalidates old tokens. */
+    set(passcode) {
+        const salt = randomBytes(16).toString("hex");
+        const hash = this.hashPasscode(passcode, salt);
+        const secret = randomBytes(32).toString("hex");
+        this.write({ hash, salt, secret });
+        this.failures = 0;
+        this.lockedUntil = 0;
+    }
+    /**
+     * Verify a passcode. On success returns a fresh remember-token and resets the
+     * failure counter; on failure (or while rate-limited) returns null and counts
+     * a failure. While locked out, even a correct passcode returns null.
+     */
+    verify(passcode) {
+        const record = this.read();
+        if (!record)
+            return null;
+        if (this.isLocked())
+            return null;
+        const candidate = this.hashPasscode(passcode, record.salt);
+        if (!safeEqualHex(candidate, record.hash)) {
+            this.failures++;
+            if (this.failures >= this.maxAttempts) {
+                this.lockedUntil = this.now() + this.lockoutMs;
+            }
+            return null;
+        }
+        this.failures = 0;
+        this.lockedUntil = 0;
+        return this.issueToken(record);
+    }
+    /** Validate a remember-token: HMAC signature must match AND be over the
+     *  current secret (so it dies when the passcode is rotated), AND the signed
+     *  issue timestamp must be within the validity window (so a stolen/synced
+     *  cookie cannot grant access indefinitely). */
+    verifyToken(token) {
+        const record = this.read();
+        if (!record)
+            return false;
+        const dot = token.lastIndexOf(".");
+        if (dot <= 0)
+            return false;
+        const payload = token.slice(0, dot);
+        const sig = token.slice(dot + 1);
+        const expected = this.sign(payload, record.secret);
+        if (!safeEqualHex(sig, expected))
+            return false;
+        // The timestamp is covered by the HMAC, so it is trustworthy once the
+        // signature checks out.
+        const issuedAt = Number(payload.slice(payload.indexOf(".") + 1));
+        if (!Number.isFinite(issuedAt))
+            return false;
+        return this.now() - issuedAt <= this.tokenMaxAgeMs;
+    }
+    /**
+     * HTTP gate. Returns true (allow) when the request carries a valid remember
+     * token (cookie) or the correct passcode (query/header); on a fresh correct
+     * passcode it also sets the remember cookie so the phone is not re-challenged.
+     * Returns false after writing either a redirect or a 401 challenge — the
+     * caller must stop in both cases.
+     */
+    gate(req, res) {
+        if (!this.isSet()) {
+            // No passcode configured → tunnel must not be reachable. Refuse.
+            res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+            res.end("access passcode not configured");
+            return false;
+        }
+        const cookieToken = readCookie(req.headers.cookie, COOKIE_NAME);
+        if (cookieToken && this.verifyToken(cookieToken))
+            return true;
+        const supplied = readPasscodeParam(req);
+        let wrongAttempt = false;
+        if (supplied) {
+            const token = this.verify(supplied);
+            if (token) {
+                res.setHeader("Set-Cookie", 
+                // SameSite=Lax (not Strict): the phone arrives via a QR-scan-launched
+                // top-level navigation into trycloudflare.com, which Strict treats as
+                // cross-site and refuses to send the cookie on — re-challenging the
+                // user every visit. Lax sends it on top-level navigations. Secure
+                // because the tunnel terminates TLS (always https).
+                `${COOKIE_NAME}=${token}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${Math.floor(this.tokenMaxAgeMs / 1000)}`);
+                const cleanLocation = acceptsHtml(req) ? locationWithoutPasscode(req.url) : undefined;
+                if (cleanLocation) {
+                    // The HTML challenge has a no-query JavaScript path below, but keep a
+                    // server-side redirect as a no-JS fallback. Never render the app while
+                    // the plaintext passcode is still visible in the navigation URL.
+                    res.writeHead(303, {
+                        Location: cleanLocation,
+                        "Cache-Control": "no-store",
+                    });
+                    res.end();
+                    return false;
+                }
+                return true;
+            }
+            wrongAttempt = true;
+        }
+        // A browser navigating to a page needs a form to type the passcode into —
+        // a bare text/plain 401 was a dead end (the user saw the error with no way
+        // to enter the passcode). Non-navigation requests (WS upgrade, fetch) keep
+        // the lightweight text 401.
+        if (acceptsHtml(req)) {
+            res.writeHead(401, { "content-type": "text/html; charset=utf-8" });
+            res.end(challengePage(req.url, wrongAttempt, this.isLocked()));
+            return false;
+        }
+        res.writeHead(401, { "content-type": "text/plain; charset=utf-8" });
+        res.end("访问口令无效或缺失");
+        return false;
+    }
+    /** True if a WS upgrade carrying these headers/url is allowed (no body to
+     *  write). Used by the WS gate which cannot send a challenge page. */
+    allows(req) {
+        if (!this.isSet())
+            return false;
+        const cookieToken = readCookie(req.headers.cookie, COOKIE_NAME);
+        if (cookieToken && this.verifyToken(cookieToken))
+            return true;
+        const supplied = readPasscodeParam(req);
+        if (supplied)
+            return this.verify(supplied) !== null;
+        return false;
+    }
+    isLocked() {
+        if (this.lockedUntil === 0)
+            return false;
+        if (this.now() >= this.lockedUntil) {
+            this.lockedUntil = 0;
+            this.failures = 0;
+            return false;
+        }
+        return true;
+    }
+    issueToken(record) {
+        const payload = `${randomBytes(12).toString("hex")}.${this.now()}`;
+        const sig = this.sign(payload, record.secret);
+        return `${payload}.${sig}`;
+    }
+    sign(payload, secret) {
+        return createHmac("sha256", secret).update(payload).digest("hex");
+    }
+    hashPasscode(passcode, salt) {
+        return scryptSync(passcode, salt, SCRYPT_KEYLEN).toString("hex");
+    }
+    read() {
+        if (!existsSync(this.filePath))
+            return undefined;
+        try {
+            const parsed = JSON.parse(readFileSync(this.filePath, "utf-8"));
+            if (parsed.hash && parsed.salt && parsed.secret) {
+                return { hash: parsed.hash, salt: parsed.salt, secret: parsed.secret };
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    write(record) {
+        mkdirSync(dirname(this.filePath), { recursive: true });
+        writeFileSync(this.filePath, JSON.stringify(record, null, 2), "utf-8");
+    }
+}
+function readCookie(cookieHeader, name) {
+    if (!cookieHeader)
+        return undefined;
+    const header = Array.isArray(cookieHeader) ? cookieHeader.join("; ") : cookieHeader;
+    for (const part of header.split(/;\s*/)) {
+        const eq = part.indexOf("=");
+        if (eq <= 0)
+            continue;
+        if (part.slice(0, eq) === name) {
+            const raw = part.slice(eq + 1);
+            // The Cookie header is attacker-controlled on the mobile-remote boundary.
+            // decodeURIComponent THROWS URIError on a malformed %-sequence (e.g.
+            // `cs_access=%ZZ`); unguarded it escapes gate() and crashes the request
+            // handler (DoS). Fall back to the raw value like browsers do for bad cookies.
+            try {
+                return decodeURIComponent(raw);
+            }
+            catch {
+                return raw;
+            }
+        }
+    }
+    return undefined;
+}
+function readPasscodeParam(req) {
+    // Header takes precedence (used by the WS/fetch path), then ?passcode= query.
+    // Node represents duplicate headers as string[]; handle that like readCookie
+    // does (take the first value) instead of silently falling through to query.
+    const rawHeader = req.headers["x-access-passcode"];
+    const headerVal = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+    if (typeof headerVal === "string" && headerVal)
+        return headerVal;
+    if (!req.url)
+        return undefined;
+    const qIdx = req.url.indexOf("?");
+    if (qIdx < 0)
+        return undefined;
+    const params = new URLSearchParams(req.url.slice(qIdx + 1));
+    return params.get("passcode") ?? undefined;
+}
+function acceptsHtml(req) {
+    const accept = req.headers.accept;
+    const value = Array.isArray(accept) ? accept.join(",") : accept;
+    return typeof value === "string" && value.includes("text/html");
+}
+function locationWithoutPasscode(url) {
+    if (!url)
+        return undefined;
+    const qIdx = url.indexOf("?");
+    if (qIdx < 0)
+        return undefined;
+    const path = url.slice(0, qIdx) || "/";
+    const params = new URLSearchParams(url.slice(qIdx + 1));
+    if (!params.has("passcode"))
+        return undefined;
+    params.delete("passcode");
+    const query = params.toString();
+    return query ? `${path}?${query}` : path;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * The passcode challenge page. Submits via GET back to the SAME path so any
+ * existing query (notably `?pairing=<token>`) is preserved — the form re-adds
+ * `passcode`, and on success gate() sets the remember cookie and the next load
+ * serves the real /mobile page with the pairing token intact.
+ */
+function challengePage(url, wrong, locked) {
+    // Carry forward existing params except a stale passcode.
+    const qIdx = (url ?? "").indexOf("?");
+    const path = qIdx >= 0 ? url.slice(0, qIdx) : (url ?? "/mobile");
+    const params = new URLSearchParams(qIdx >= 0 ? url.slice(qIdx + 1) : "");
+    params.delete("passcode");
+    const hidden = [...params.entries()]
+        .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`)
+        .join("");
+    const note = locked
+        ? "尝试过多,已临时锁定,请稍后再试。"
+        : wrong
+            ? "口令不正确,请重试。"
+            : "请输入访问口令以继续。";
+    return `<!doctype html>
+<html lang="zh"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>访问口令</title>
+<style>
+  :root{color-scheme:light dark}
+  body{font-family:-apple-system,system-ui,sans-serif;margin:0;min-height:100vh;
+    display:flex;align-items:center;justify-content:center;background:#0b0b0c;color:#e7e7e9}
+  .card{width:min(92vw,360px);padding:28px 24px;border-radius:16px;background:#19191c;
+    box-shadow:0 8px 40px rgba(0,0,0,.4)}
+  h1{font-size:18px;margin:0 0 6px}
+  p{font-size:13px;color:#a1a1aa;margin:0 0 18px}
+  p.err{color:#f87171}
+  input[type=password]{width:100%;box-sizing:border-box;padding:12px 14px;font-size:16px;
+    border-radius:10px;border:1px solid #333;background:#0f0f11;color:#fff;margin-bottom:14px}
+  button{width:100%;padding:12px;font-size:15px;border:0;border-radius:10px;
+    background:#3b82f6;color:#fff;font-weight:600}
+  button:disabled{opacity:.5}
+</style></head>
+<body><form class="card" method="GET" action="${escapeHtml(path)}">
+  <h1>手机遥控</h1>
+  <p class="${wrong || locked ? "err" : ""}">${note}</p>
+  ${hidden}
+  <input id="passcode" type="password" name="passcode" placeholder="访问口令" autofocus required ${locked ? "disabled" : ""}>
+  <button type="submit" ${locked ? "disabled" : ""}>进入</button>
+</form>
+<script>
+  const form = document.querySelector("form");
+  const input = document.querySelector("#passcode");
+  const note = document.querySelector("p");
+  form?.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    const value = input?.value ?? "";
+    if (!value) return;
+    try {
+      const response = await fetch(window.location.href, {
+        headers: { "X-Access-Passcode": value, Accept: "application/json" },
+        credentials: "same-origin",
+      });
+      if (!response.ok) {
+        if (note) note.textContent = "口令不正确或尝试过多，请稍后重试。";
+        if (note) note.className = "err";
+        if (input) input.value = "";
+        return;
+      }
+      window.location.replace(${JSON.stringify(path + (params.size ? `?${params.toString()}` : ""))});
+    } catch {
+      if (note) note.textContent = "连接失败，请重试。";
+      if (note) note.className = "err";
+    }
+  });
+</script></body></html>`;
+}
+/** Constant-time hex comparison that tolerates length mismatch. */
+function safeEqualHex(a, b) {
+    if (a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/mobile-remote/cloudflared-binary.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Pinned cloudflared release. We do NOT track `latest`: the downloaded asset is
+ * chmod +x'd and executed with the desktop user's privileges, so the bytes must
+ * be verifiable against a known SHA-256. `latest` would move under us and make
+ * any embedded digest wrong on the next release (breaking installs) or, worse,
+ * silently accept whatever `latest` now points at. Bump this tag AND the digests
+ * below together (see scripts note in the PR / CLAUDE memory).
+ */
+export declare const CLOUDFLARED_VERSION = "2026.6.1";
+/**
+ * SHA-256 of each release asset we download, for {@link CLOUDFLARED_VERSION}.
+ * Keyed by the asset FILENAME. For macOS this is the `.tgz` archive (verified
+ * before extraction); for Linux/Windows it's the raw binary. Regenerate on every
+ * version bump:
+ *   for a in cloudflared-darwin-amd64.tgz cloudflared-darwin-arm64.tgz \
+ *            cloudflared-linux-amd64 cloudflared-linux-arm64 \
+ *            cloudflared-windows-amd64.exe; do
+ *     curl -sSL "https://github.com/cloudflare/cloudflared/releases/download/$V/$a" | shasum -a 256
+ *   done
+ */
+export declare const CLOUDFLARED_SHA256: Record<string, string>;
+/** The filename portion of an asset URL — the key into {@link CLOUDFLARED_SHA256}. */
+export declare function cloudflaredAssetName(arch: string, platform?: NodeJS.Platform): string;
+/**
+ * Verify `path`'s SHA-256 against the pinned digest for `assetName`. Throws (with
+ * the file left for the caller to clean up) on an unknown asset or a mismatch —
+ * never chmod/execute unverified bytes.
+ */
+export declare function verifyAssetDigest(path: string, assetName: string): void;
+/**
+ * Map a Node `process.platform` + `process.arch` to the official cloudflared
+ * release asset URL.
+ *
+ *  - macOS: `cloudflared-darwin-<arch>.tgz` (a tarball with one binary).
+ *  - Windows: `cloudflared-windows-<arch>.exe` (a RAW .exe, no extraction).
+ *  - Linux: `cloudflared-linux-<arch>` (a raw binary).
+ *
+ * Pure + injectable so tests pin the URL without touching the network. Unknown
+ * arch falls back to amd64.
+ */
+export declare function cloudflaredDownloadUrl(arch: string, platform?: NodeJS.Platform): string;
+/** Injectable download function. Writes the fetched bytes to `dest`. */
+export type DownloadFn = (url: string, dest: string, onProgress?: (pct: number) => void) => Promise<void>;
+export interface CloudflaredBinaryOptions {
+    /** Base dir, typically `<userData>/mobile-remote`. */
+    baseDir: string;
+    /** Override `process.arch` for tests. */
+    arch?: string;
+    /** Override the network download for tests. */
+    download?: DownloadFn;
+}
+/**
+ * Manages the cloudflared binary on disk: existence/executable check and a
+ * download-once-then-atomic-rename install. No process spawning, no network
+ * service — that lives in tunnel-manager. Network + arch are injected so the
+ * unit is fully deterministic in tests.
+ */
+export declare class CloudflaredBinary {
+    private readonly baseDir;
+    private readonly arch;
+    private readonly download;
+    constructor(opts: CloudflaredBinaryOptions);
+    /** `<baseDir>/bin/cloudflared` (`.exe` on Windows). */
+    binaryPath(): string;
+    /** True when the binary exists (and, on POSIX, has the owner-exec bit set).
+     *  Windows has no exec bit, so existence is the only meaningful check. */
+    isInstalled(): boolean;
+    /**
+     * Ensure the binary is present and executable, returning its path. If already
+     * installed, skips the download. Otherwise downloads to a `.download` temp
+     * name, chmods it executable, and atomically renames to the final path — so a
+     * failed/partial download never leaves a half-written binary in place. On any
+     * failure the temp file is removed and the error rethrown.
+     */
+    ensureBinary(onProgress?: (pct: number) => void): Promise<string>;
+}

package/dist/mobile-remote/cloudflared-binary.js

@@ -0,0 +1,242 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
+import { get as httpsGet } from "node:https";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Pinned cloudflared release. We do NOT track `latest`: the downloaded asset is
+ * chmod +x'd and executed with the desktop user's privileges, so the bytes must
+ * be verifiable against a known SHA-256. `latest` would move under us and make
+ * any embedded digest wrong on the next release (breaking installs) or, worse,
+ * silently accept whatever `latest` now points at. Bump this tag AND the digests
+ * below together (see scripts note in the PR / CLAUDE memory).
+ */
+export const CLOUDFLARED_VERSION = "2026.6.1";
+/**
+ * SHA-256 of each release asset we download, for {@link CLOUDFLARED_VERSION}.
+ * Keyed by the asset FILENAME. For macOS this is the `.tgz` archive (verified
+ * before extraction); for Linux/Windows it's the raw binary. Regenerate on every
+ * version bump:
+ *   for a in cloudflared-darwin-amd64.tgz cloudflared-darwin-arm64.tgz \
+ *            cloudflared-linux-amd64 cloudflared-linux-arm64 \
+ *            cloudflared-windows-amd64.exe; do
+ *     curl -sSL "https://github.com/cloudflare/cloudflared/releases/download/$V/$a" | shasum -a 256
+ *   done
+ */
+export const CLOUDFLARED_SHA256 = {
+    "cloudflared-darwin-amd64.tgz": "d7a66b525fe76820da6e5406611b61e48b40de682368ac00454d9158f085be4b",
+    "cloudflared-darwin-arm64.tgz": "f6d4c439c6c782b83264951d327989ce5e23373acc5942b872411601fedb020d",
+    "cloudflared-linux-amd64": "5861a10a438fe8ddcfebb3b830f83966cbf193edafce0fe2eeb198fbae1f7a22",
+    "cloudflared-linux-arm64": "59816ce9b16db71f5bc2a86d59b3632a96c8c3ee934bde2bc8641ee83a6070eb",
+    "cloudflared-windows-amd64.exe": "5253e66f1f493c4e13539749f1aa86fd0c61e3072900fec29a44ba046a6d97e2",
+};
+/** The filename portion of an asset URL — the key into {@link CLOUDFLARED_SHA256}. */
+export function cloudflaredAssetName(arch, platform = process.platform) {
+    const a = arch === "arm64" ? "arm64" : "amd64";
+    if (platform === "win32")
+        return "cloudflared-windows-amd64.exe";
+    if (platform === "linux")
+        return `cloudflared-linux-${a}`;
+    return `cloudflared-darwin-${a}.tgz`;
+}
+/** SHA-256 of a file on disk, lowercase hex. */
+function sha256File(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+/**
+ * Verify `path`'s SHA-256 against the pinned digest for `assetName`. Throws (with
+ * the file left for the caller to clean up) on an unknown asset or a mismatch —
+ * never chmod/execute unverified bytes.
+ */
+export function verifyAssetDigest(path, assetName) {
+    const expected = CLOUDFLARED_SHA256[assetName];
+    if (!expected) {
+        throw new Error(`cloudflared 资产无内置校验值: ${assetName}`);
+    }
+    const actual = sha256File(path);
+    if (actual !== expected) {
+        throw new Error(`cloudflared 校验失败(${assetName}): 期望 ${expected}, 实际 ${actual}`);
+    }
+}
+/**
+ * Map a Node `process.platform` + `process.arch` to the official cloudflared
+ * release asset URL.
+ *
+ *  - macOS: `cloudflared-darwin-<arch>.tgz` (a tarball with one binary).
+ *  - Windows: `cloudflared-windows-<arch>.exe` (a RAW .exe, no extraction).
+ *  - Linux: `cloudflared-linux-<arch>` (a raw binary).
+ *
+ * Pure + injectable so tests pin the URL without touching the network. Unknown
+ * arch falls back to amd64.
+ */
+export function cloudflaredDownloadUrl(arch, platform = process.platform) {
+    // Pinned version (NOT /latest/) so the asset matches an embedded SHA-256.
+    const base = `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}`;
+    return `${base}/${cloudflaredAssetName(arch, platform)}`;
+}
+/** True when the release asset is a tarball needing extraction (macOS only). */
+function assetIsTarball(platform = process.platform) {
+    return platform === "darwin";
+}
+/**
+ * Manages the cloudflared binary on disk: existence/executable check and a
+ * download-once-then-atomic-rename install. No process spawning, no network
+ * service — that lives in tunnel-manager. Network + arch are injected so the
+ * unit is fully deterministic in tests.
+ */
+export class CloudflaredBinary {
+    baseDir;
+    arch;
+    download;
+    constructor(opts) {
+        this.baseDir = opts.baseDir;
+        this.arch = opts.arch ?? process.arch;
+        this.download = opts.download ?? defaultDownload;
+    }
+    /** `<baseDir>/bin/cloudflared` (`.exe` on Windows). */
+    binaryPath() {
+        const name = process.platform === "win32" ? "cloudflared.exe" : "cloudflared";
+        return join(this.baseDir, "bin", name);
+    }
+    /** True when the binary exists (and, on POSIX, has the owner-exec bit set).
+     *  Windows has no exec bit, so existence is the only meaningful check. */
+    isInstalled() {
+        const p = this.binaryPath();
+        if (!existsSync(p))
+            return false;
+        if (process.platform === "win32")
+            return true;
+        try {
+            return (statSync(p).mode & 0o100) === 0o100;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Ensure the binary is present and executable, returning its path. If already
+     * installed, skips the download. Otherwise downloads to a `.download` temp
+     * name, chmods it executable, and atomically renames to the final path — so a
+     * failed/partial download never leaves a half-written binary in place. On any
+     * failure the temp file is removed and the error rethrown.
+     */
+    async ensureBinary(onProgress) {
+        const finalPath = this.binaryPath();
+        if (this.isInstalled())
+            return finalPath;
+        const tmpPath = `${finalPath}.download`;
+        mkdirSync(join(this.baseDir, "bin"), { recursive: true });
+        try {
+            const url = cloudflaredDownloadUrl(this.arch);
+            await this.download(url, tmpPath, onProgress);
+            if (!existsSync(tmpPath) || statSync(tmpPath).size === 0) {
+                throw new Error("下载的 cloudflared 为空");
+            }
+            chmodSync(tmpPath, 0o755);
+            renameSync(tmpPath, finalPath);
+            return finalPath;
+        }
+        catch (err) {
+            rmSync(tmpPath, { force: true });
+            throw err;
+        }
+    }
+}
+/**
+ * Default download: the official macOS asset is a `.tgz` tarball containing a
+ * single `cloudflared` binary, so we fetch the tarball to a scratch dir, extract
+ * it with the system `tar`, then place the extracted binary at `dest`. The
+ * caller (ensureBinary) chmods + atomically renames `dest` into place, so a
+ * failed extract never yields a runnable-but-broken binary. Network + extract
+ * scratch is fully cleaned up.
+ */
+const defaultDownload = async (url, dest, onProgress) => {
+    // The asset filename is the key into the embedded SHA-256 table.
+    const assetName = cloudflaredAssetName(process.arch);
+    // Windows/Linux assets are RAW binaries — stream straight to dest, no tar.
+    if (!assetIsTarball()) {
+        await httpsDownloadTo(url, dest, onProgress);
+        if (!existsSync(dest) || statSync(dest).size === 0) {
+            throw new Error("下载的 cloudflared 为空");
+        }
+        // Verify BEFORE the caller chmods +x and renames into place. A mismatch
+        // throws; ensureBinary removes the temp file so nothing runnable survives.
+        verifyAssetDigest(dest, assetName);
+        return;
+    }
+    // macOS asset is a .tgz with a single `cloudflared` binary → extract.
+    const scratch = mkdtempSync(join(tmpdir(), "cloudflared-dl-"));
+    const tgzPath = join(scratch, "cloudflared.tgz");
+    try {
+        await httpsDownloadTo(url, tgzPath, onProgress);
+        if (!existsSync(tgzPath) || statSync(tgzPath).size === 0) {
+            throw new Error("下载的 cloudflared 归档为空");
+        }
+        // Verify the ARCHIVE against its embedded digest before extracting — never
+        // hand attacker-controlled bytes to `tar`.
+        verifyAssetDigest(tgzPath, assetName);
+        await runTarExtract(tgzPath, scratch);
+        const extracted = join(scratch, "cloudflared");
+        if (!existsSync(extracted)) {
+            throw new Error("归档中未找到 cloudflared 二进制");
+        }
+        copyFileSync(extracted, dest);
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+};
+/** Stream an https GET (following GitHub→CDN redirects) to a file with coarse
+ *  progress. */
+function httpsDownloadTo(url, dest, onProgress) {
+    return new Promise((resolve, reject) => {
+        const request = (target, redirects) => {
+            if (redirects > 5) {
+                reject(new Error("下载重定向过多"));
+                return;
+            }
+            const req = httpsGet(target, (res) => {
+                const status = res.statusCode ?? 0;
+                if (status >= 300 && status < 400 && res.headers.location) {
+                    res.resume();
+                    request(res.headers.location, redirects + 1);
+                    return;
+                }
+                if (status !== 200) {
+                    res.resume();
+                    reject(new Error(`下载失败,HTTP ${status}`));
+                    return;
+                }
+                const total = Number(res.headers["content-length"] ?? 0);
+                let received = 0;
+                const out = createWriteStream(dest);
+                res.on("data", (chunk) => {
+                    received += chunk.length;
+                    if (total > 0 && onProgress) {
+                        onProgress(Math.min(100, Math.round((received / total) * 100)));
+                    }
+                });
+                res.pipe(out);
+                out.on("finish", () => out.close(() => resolve()));
+                out.on("error", reject);
+                res.on("error", reject);
+            });
+            req.on("error", reject);
+        };
+        request(url, 0);
+    });
+}
+/** Extract a `.tgz` into `cwd` using the system tar (always present on macOS). */
+function runTarExtract(tgzPath, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("tar", ["-xzf", tgzPath, "-C", cwd]);
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`tar 解压失败(code=${code ?? "?"})`));
+        });
+    });
+}