unplugin-https-reverse-proxy 4.1.0-beta.2 → 4.1.0-beta.3

package/dist/vite.cjs

@@ -13678,16 +13678,28 @@ var import_node_process2 = __toESM(require("process"), 1);
 function resolveHelperEntry(options) {
   const { moduleDir, nodeBin = import_node_process2.default.execPath, exists: exists2 = import_node_fs2.existsSync } = options;
   for (const name of ["privileged-helper.js", "privileged-helper.cjs", "privileged-helper.mjs"]) {
-    const candidate = (0, import_node_path2.join)(moduleDir, name);
-    if (exists2(candidate))
+    const candidate = findUp(moduleDir, name, exists2);
+    if (candidate)
       return { entry: nodeBin, args: [candidate] };
   }
-  const source = (0, import_node_path2.join)(moduleDir, "privileged-helper.ts");
-  const tsxCli = (0, import_node_path2.join)(moduleDir, "../node_modules/tsx/dist/cli.mjs");
-  if (exists2(source) && exists2(tsxCli))
+  const source = findUp(moduleDir, "privileged-helper.ts", exists2);
+  const tsxCli = findUp(moduleDir, "node_modules/tsx/dist/cli.mjs", exists2);
+  if (source && tsxCli)
     return { entry: nodeBin, args: [tsxCli, source] };
   throw new Error(`privileged helper entry not found in ${moduleDir}. Build the package first.`);
 }
+function findUp(from, relative, exists2) {
+  let current = from;
+  while (true) {
+    const candidate = (0, import_node_path2.join)(current, relative);
+    if (exists2(candidate))
+      return candidate;
+    const parent = (0, import_node_path2.dirname)(current);
+    if (parent === current)
+      return void 0;
+    current = parent;
+  }
+}
 
 // src/privileged/session.ts
 var import_node_buffer = require("buffer");
@@ -13986,18 +13998,42 @@ function spawnElevatedOnWindows(options) {
 function createHelperToken() {
   return (0, import_node_crypto.randomBytes)(24).toString("hex");
 }
-function authenticateSudo(sudoCommand = "sudo") {
+function describePasswordReason(target, https) {
+  const port = https ? "443" : "80";
+  return [
+    `reverse proxy needs administrator permission for ${target}`,
+    `  \xB7 bind port ${port}${https ? ` for https://${target}` : ""}`,
+    `  \xB7 add ${target} to the hosts file`,
+    "",
+    "This is the only prompt; the rest of the dev server keeps running as you.",
+    "Press Ctrl+C at the prompt to skip the proxy and keep the dev server."
+  ];
+}
+function authenticateSudo(sudoCommand = "sudo", options = {}) {
   if ((0, import_node_os3.platform)() === "win32")
     return { ok: true };
   if ((0, import_node_child_process2.spawnSync)(sudoCommand, ["-n", "true"], { stdio: "ignore" }).status === 0)
     return { ok: true };
+  if (options.target) {
+    for (const line of describePasswordReason(options.target, options.https ?? false))
+      import_node_process5.default.stderr.write(`${line}
+`);
+    import_node_process5.default.stderr.write("\n");
+  }
   if ((0, import_node_child_process2.spawnSync)(sudoCommand, ["-v"], { stdio: "inherit" }).status === 0)
     return { ok: true };
   return {
     ok: false,
+    denied: true,
     message: "administrator permission is required to edit the hosts file and bind ports 80/443"
   };
 }
+var PrivilegeDeniedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PrivilegeDeniedError";
+  }
+};
 async function startPrivilegedHelper(options) {
   var _a4, _b3;
   const {
@@ -14013,9 +14049,11 @@ async function startPrivilegedHelper(options) {
     connectTimeoutMs = 12e4
   } = options;
   if (!skipAuth && !direct) {
-    const auth = authenticateSudo(sudoCommand);
-    if (!auth.ok)
-      throw new Error(auth.message);
+    const auth = authenticateSudo(sudoCommand, options.reason);
+    if (!auth.ok) {
+      const message = auth.message ?? "administrator permission is required";
+      throw auth.denied ? new PrivilegeDeniedError(message) : new Error(message);
+    }
   }
   const forwarded = collectForwardedEnv(env2);
   const forwardedArgs = Object.entries(forwarded).map(([key, value2]) => `${key}=${value2}`);
@@ -14120,6 +14158,7 @@ async function openHelperSession(scope2) {
     caddyStoragePath: scope2.caddyStoragePath,
     caddyBin: scope2.caddyBin,
     caddyConfigPath: scope2.caddyConfigPath,
+    reason: scope2.reason,
     log: scope2.log
   });
   await writeToken(scope2.runtimeDir, token);
@@ -14206,6 +14245,7 @@ function openPrivilegedSession(runtimeDir, options) {
     // execute a path supplied over the socket.
     caddyBin: options.caddyBin,
     caddyConfigPath: options.caddyConfigPath,
+    reason: options.reason,
     log: options.log
   });
 }
@@ -14406,12 +14446,13 @@ function splitHostPort(addr) {
   return { host: addr.slice(0, lastColon), port: addr.slice(lastColon + 1) };
 }
 var defaultDependencies = {
-  openSession: (runtimeDir) => openPrivilegedSession(runtimeDir, {
+  openSession: (runtimeDir, reason) => openPrivilegedSession(runtimeDir, {
     log: (message) => consola.debug(message),
     // Both paths are fixed here, before any socket traffic: the privileged
     // helper must never execute something named in a request.
     caddyBin: caddyPath,
-    caddyConfigPath: caddyFilePath
+    caddyConfigPath: caddyFilePath,
+    reason
   })
 };
 var CaddyInstant = class {
@@ -14438,11 +14479,11 @@ var CaddyInstant = class {
    * reused across instances so a second dev server does not ask for a
    * password again.
    */
-  async session() {
+  async session(reason) {
     if (this._session && !this._session.client.connected)
       this._session = void 0;
     if (!this._session)
-      this._session = await this.deps.openSession(TEMP_DIR);
+      this._session = await this.deps.openSession(TEMP_DIR, reason);
     return this._session;
   }
   async getCaddyfile() {
@@ -14547,9 +14588,9 @@ Run \`${caddyPath} trust\` manually if the browser warns about the certificate.`
     this._target = target;
     if (!this.inited)
       await this.init();
-    const session = await this.session();
     const sourceHost = splitHostPort(source).host;
     const targetHost = splitHostPort(target).host;
+    const session = await this.session({ target: targetHost, https });
     await session.client.call("hosts.add", { ip: sourceHost, host: targetHost });
     consola.success("update host success\n");
     const normalizeBase = (b) => {
@@ -14981,6 +15022,15 @@ var hmrSseBridgeClientScript = `
 })();
 `;
 
+// src/privilege-state.ts
+var denied = false;
+function markPrivilegeDenied() {
+  denied = true;
+}
+function isPrivilegeDenied() {
+  return denied;
+}
+
 // src/index.ts
 var config;
 var caddy;
@@ -15020,16 +15070,27 @@ async function printForwardProxy() {
 }
 var vitePrintUrls = once((options, source, target, base = "/", _printUrls) => {
   _printUrls == null ? void 0 : _printUrls();
+  if (isPrivilegeDenied())
+    return;
   if (caddy)
     return;
-  caddy = new CaddyInstant();
-  caddy.run(source, target, {
+  const instance = new CaddyInstant();
+  caddy = instance;
+  instance.run(source, target, {
     base,
     ...options
   }).then(async () => {
     await printForwardProxy();
     consola.success(`  ${import_picocolors2.default.green("\u279C")}  ${import_picocolors2.default.bold("run caddy reverse proxy success")}: ${colorUrl(`${options.https ? "https" : "http"}://${target}${base}`)}`);
   }).catch((e) => {
+    if (caddy === instance)
+      caddy = void 0;
+    if (e instanceof PrivilegeDeniedError) {
+      markPrivilegeDenied();
+      consola.warn("reverse proxy skipped: administrator permission was not granted.");
+      consola.info("Restart the dev server to enable it again.");
+      return;
+    }
     throw e;
   });
 });
@@ -15109,6 +15170,8 @@ var unpluginFactory = (options) => ({
       ...(_a4 = import_node_process8.default.VUE_CLI_SERVICE) == null ? void 0 : _a4.projectOptions.devServer
     };
     const source = `${devServer.host}:${devServer.port}`;
+    if (isPrivilegeDenied())
+      return;
     if (caddy)
       return;
     let base = "/";
@@ -15130,8 +15193,9 @@ var unpluginFactory = (options) => ({
     } else {
       options.https = false;
     }
-    caddy = new CaddyInstant();
-    caddy.run(source, target, {
+    const instance = new CaddyInstant();
+    caddy = instance;
+    instance.run(source, target, {
       base,
       ...options
     }).then(() => {
@@ -15140,6 +15204,14 @@ var unpluginFactory = (options) => ({
         consola.success(`  ${import_picocolors2.default.green("\u279C")}  ${import_picocolors2.default.bold("run caddy reverse proxy success")}: ${colorUrl(`${options.https ? "https" : "http"}://${target}${base}`)}`);
       });
     }).catch((e) => {
+      if (caddy === instance)
+        caddy = void 0;
+      if (e instanceof PrivilegeDeniedError) {
+        markPrivilegeDenied();
+        consola.warn("reverse proxy skipped: administrator permission was not granted.");
+        consola.info("Restart the dev server to enable it again.");
+        return;
+      }
       throw e;
     });
   },
@@ -15170,9 +15242,10 @@ var unpluginFactory = (options) => ({
       }))) == null ? void 0 : _b3.content) == null ? void 0 : _c2.server
     };
     const source = `${devServer.host}:${devServer.port}`;
+    if (isPrivilegeDenied())
+      return;
     if (caddy)
       return;
-    caddy = new CaddyInstant();
     let base = "/";
     const publicPath = (_d2 = compiler.options.output) == null ? void 0 : _d2.publicPath;
     if (typeof publicPath === "string" && publicPath) {
@@ -15182,13 +15255,23 @@ var unpluginFactory = (options) => ({
       base = `/${base}`;
     if (base !== "/" && !base.endsWith("/"))
       base = `${base}/`;
-    caddy.run(source, target, {
+    const instance = new CaddyInstant();
+    caddy = instance;
+    instance.run(source, target, {
       base,
       ...options
     }).then(async () => {
       await printForwardProxy();
       consola.success(`  ${import_picocolors2.default.green("\u279C")}  ${import_picocolors2.default.bold("run caddy reverse proxy success")}: ${colorUrl(`${options.https ? "https" : "http"}://${target}${base}`)}`);
     }).catch((e) => {
+      if (caddy === instance)
+        caddy = void 0;
+      if (e instanceof PrivilegeDeniedError) {
+        markPrivilegeDenied();
+        consola.warn("reverse proxy skipped: administrator permission was not granted.");
+        consola.info("Restart the dev server to enable it again.");
+        return;
+      }
       throw e;
     });
   }

package/dist/vite.js

@@ -1,8 +1,9 @@
 import {
   unpluginFactory
-} from "./chunk-7CA3EIIX.js";
+} from "./chunk-HBXMM25C.js";
 import "./chunk-EY3HXBJ4.js";
 import "./chunk-C5A7XLKL.js";
+import "./chunk-WOMR3ZLM.js";
 import "./chunk-RKHJN6KY.js";
 
 // src/vite.ts

package/dist/webpack.cjs

@@ -13678,16 +13678,28 @@ var import_node_process2 = __toESM(require("process"), 1);
 function resolveHelperEntry(options) {
   const { moduleDir, nodeBin = import_node_process2.default.execPath, exists: exists2 = import_node_fs2.existsSync } = options;
   for (const name of ["privileged-helper.js", "privileged-helper.cjs", "privileged-helper.mjs"]) {
-    const candidate = (0, import_node_path2.join)(moduleDir, name);
-    if (exists2(candidate))
+    const candidate = findUp(moduleDir, name, exists2);
+    if (candidate)
       return { entry: nodeBin, args: [candidate] };
   }
-  const source = (0, import_node_path2.join)(moduleDir, "privileged-helper.ts");
-  const tsxCli = (0, import_node_path2.join)(moduleDir, "../node_modules/tsx/dist/cli.mjs");
-  if (exists2(source) && exists2(tsxCli))
+  const source = findUp(moduleDir, "privileged-helper.ts", exists2);
+  const tsxCli = findUp(moduleDir, "node_modules/tsx/dist/cli.mjs", exists2);
+  if (source && tsxCli)
     return { entry: nodeBin, args: [tsxCli, source] };
   throw new Error(`privileged helper entry not found in ${moduleDir}. Build the package first.`);
 }
+function findUp(from, relative, exists2) {
+  let current = from;
+  while (true) {
+    const candidate = (0, import_node_path2.join)(current, relative);
+    if (exists2(candidate))
+      return candidate;
+    const parent = (0, import_node_path2.dirname)(current);
+    if (parent === current)
+      return void 0;
+    current = parent;
+  }
+}
 
 // src/privileged/session.ts
 var import_node_buffer = require("buffer");
@@ -13986,18 +13998,42 @@ function spawnElevatedOnWindows(options) {
 function createHelperToken() {
   return (0, import_node_crypto.randomBytes)(24).toString("hex");
 }
-function authenticateSudo(sudoCommand = "sudo") {
+function describePasswordReason(target, https) {
+  const port = https ? "443" : "80";
+  return [
+    `reverse proxy needs administrator permission for ${target}`,
+    `  \xB7 bind port ${port}${https ? ` for https://${target}` : ""}`,
+    `  \xB7 add ${target} to the hosts file`,
+    "",
+    "This is the only prompt; the rest of the dev server keeps running as you.",
+    "Press Ctrl+C at the prompt to skip the proxy and keep the dev server."
+  ];
+}
+function authenticateSudo(sudoCommand = "sudo", options = {}) {
   if ((0, import_node_os3.platform)() === "win32")
     return { ok: true };
   if ((0, import_node_child_process2.spawnSync)(sudoCommand, ["-n", "true"], { stdio: "ignore" }).status === 0)
     return { ok: true };
+  if (options.target) {
+    for (const line of describePasswordReason(options.target, options.https ?? false))
+      import_node_process5.default.stderr.write(`${line}
+`);
+    import_node_process5.default.stderr.write("\n");
+  }
   if ((0, import_node_child_process2.spawnSync)(sudoCommand, ["-v"], { stdio: "inherit" }).status === 0)
     return { ok: true };
   return {
     ok: false,
+    denied: true,
     message: "administrator permission is required to edit the hosts file and bind ports 80/443"
   };
 }
+var PrivilegeDeniedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PrivilegeDeniedError";
+  }
+};
 async function startPrivilegedHelper(options) {
   var _a4, _b3;
   const {
@@ -14013,9 +14049,11 @@ async function startPrivilegedHelper(options) {
     connectTimeoutMs = 12e4
   } = options;
   if (!skipAuth && !direct) {
-    const auth = authenticateSudo(sudoCommand);
-    if (!auth.ok)
-      throw new Error(auth.message);
+    const auth = authenticateSudo(sudoCommand, options.reason);
+    if (!auth.ok) {
+      const message = auth.message ?? "administrator permission is required";
+      throw auth.denied ? new PrivilegeDeniedError(message) : new Error(message);
+    }
   }
   const forwarded = collectForwardedEnv(env2);
   const forwardedArgs = Object.entries(forwarded).map(([key, value2]) => `${key}=${value2}`);
@@ -14120,6 +14158,7 @@ async function openHelperSession(scope2) {
     caddyStoragePath: scope2.caddyStoragePath,
     caddyBin: scope2.caddyBin,
     caddyConfigPath: scope2.caddyConfigPath,
+    reason: scope2.reason,
     log: scope2.log
   });
   await writeToken(scope2.runtimeDir, token);
@@ -14206,6 +14245,7 @@ function openPrivilegedSession(runtimeDir, options) {
     // execute a path supplied over the socket.
     caddyBin: options.caddyBin,
     caddyConfigPath: options.caddyConfigPath,
+    reason: options.reason,
     log: options.log
   });
 }
@@ -14406,12 +14446,13 @@ function splitHostPort(addr) {
   return { host: addr.slice(0, lastColon), port: addr.slice(lastColon + 1) };
 }
 var defaultDependencies = {
-  openSession: (runtimeDir) => openPrivilegedSession(runtimeDir, {
+  openSession: (runtimeDir, reason) => openPrivilegedSession(runtimeDir, {
     log: (message) => consola.debug(message),
     // Both paths are fixed here, before any socket traffic: the privileged
     // helper must never execute something named in a request.
     caddyBin: caddyPath,
-    caddyConfigPath: caddyFilePath
+    caddyConfigPath: caddyFilePath,
+    reason
   })
 };
 var CaddyInstant = class {
@@ -14438,11 +14479,11 @@ var CaddyInstant = class {
    * reused across instances so a second dev server does not ask for a
    * password again.
    */
-  async session() {
+  async session(reason) {
     if (this._session && !this._session.client.connected)
       this._session = void 0;
     if (!this._session)
-      this._session = await this.deps.openSession(TEMP_DIR);
+      this._session = await this.deps.openSession(TEMP_DIR, reason);
     return this._session;
   }
   async getCaddyfile() {
@@ -14547,9 +14588,9 @@ Run \`${caddyPath} trust\` manually if the browser warns about the certificate.`
     this._target = target;
     if (!this.inited)
       await this.init();
-    const session = await this.session();
     const sourceHost = splitHostPort(source).host;
     const targetHost = splitHostPort(target).host;
+    const session = await this.session({ target: targetHost, https });
     await session.client.call("hosts.add", { ip: sourceHost, host: targetHost });
     consola.success("update host success\n");
     const normalizeBase = (b) => {
@@ -14981,6 +15022,15 @@ var hmrSseBridgeClientScript = `
 })();
 `;
 
+// src/privilege-state.ts
+var denied = false;
+function markPrivilegeDenied() {
+  denied = true;
+}
+function isPrivilegeDenied() {
+  return denied;
+}
+
 // src/index.ts
 var config;
 var caddy;
@@ -15020,16 +15070,27 @@ async function printForwardProxy() {
 }
 var vitePrintUrls = once((options, source, target, base = "/", _printUrls) => {
   _printUrls == null ? void 0 : _printUrls();
+  if (isPrivilegeDenied())
+    return;
   if (caddy)
     return;
-  caddy = new CaddyInstant();
-  caddy.run(source, target, {
+  const instance = new CaddyInstant();
+  caddy = instance;
+  instance.run(source, target, {
     base,
     ...options
   }).then(async () => {
     await printForwardProxy();
     consola.success(`  ${import_picocolors2.default.green("\u279C")}  ${import_picocolors2.default.bold("run caddy reverse proxy success")}: ${colorUrl(`${options.https ? "https" : "http"}://${target}${base}`)}`);
   }).catch((e) => {
+    if (caddy === instance)
+      caddy = void 0;
+    if (e instanceof PrivilegeDeniedError) {
+      markPrivilegeDenied();
+      consola.warn("reverse proxy skipped: administrator permission was not granted.");
+      consola.info("Restart the dev server to enable it again.");
+      return;
+    }
     throw e;
   });
 });
@@ -15109,6 +15170,8 @@ var unpluginFactory = (options) => ({
       ...(_a4 = import_node_process8.default.VUE_CLI_SERVICE) == null ? void 0 : _a4.projectOptions.devServer
     };
     const source = `${devServer.host}:${devServer.port}`;
+    if (isPrivilegeDenied())
+      return;
     if (caddy)
       return;
     let base = "/";
@@ -15130,8 +15193,9 @@ var unpluginFactory = (options) => ({
     } else {
       options.https = false;
     }
-    caddy = new CaddyInstant();
-    caddy.run(source, target, {
+    const instance = new CaddyInstant();
+    caddy = instance;
+    instance.run(source, target, {
       base,
       ...options
     }).then(() => {
@@ -15140,6 +15204,14 @@ var unpluginFactory = (options) => ({
         consola.success(`  ${import_picocolors2.default.green("\u279C")}  ${import_picocolors2.default.bold("run caddy reverse proxy success")}: ${colorUrl(`${options.https ? "https" : "http"}://${target}${base}`)}`);
       });
     }).catch((e) => {
+      if (caddy === instance)
+        caddy = void 0;
+      if (e instanceof PrivilegeDeniedError) {
+        markPrivilegeDenied();
+        consola.warn("reverse proxy skipped: administrator permission was not granted.");
+        consola.info("Restart the dev server to enable it again.");
+        return;
+      }
       throw e;
     });
   },
@@ -15170,9 +15242,10 @@ var unpluginFactory = (options) => ({
       }))) == null ? void 0 : _b3.content) == null ? void 0 : _c2.server
     };
     const source = `${devServer.host}:${devServer.port}`;
+    if (isPrivilegeDenied())
+      return;
     if (caddy)
       return;
-    caddy = new CaddyInstant();
     let base = "/";
     const publicPath = (_d2 = compiler.options.output) == null ? void 0 : _d2.publicPath;
     if (typeof publicPath === "string" && publicPath) {
@@ -15182,13 +15255,23 @@ var unpluginFactory = (options) => ({
       base = `/${base}`;
     if (base !== "/" && !base.endsWith("/"))
       base = `${base}/`;
-    caddy.run(source, target, {
+    const instance = new CaddyInstant();
+    caddy = instance;
+    instance.run(source, target, {
       base,
       ...options
     }).then(async () => {
       await printForwardProxy();
       consola.success(`  ${import_picocolors2.default.green("\u279C")}  ${import_picocolors2.default.bold("run caddy reverse proxy success")}: ${colorUrl(`${options.https ? "https" : "http"}://${target}${base}`)}`);
     }).catch((e) => {
+      if (caddy === instance)
+        caddy = void 0;
+      if (e instanceof PrivilegeDeniedError) {
+        markPrivilegeDenied();
+        consola.warn("reverse proxy skipped: administrator permission was not granted.");
+        consola.info("Restart the dev server to enable it again.");
+        return;
+      }
       throw e;
     });
   }

package/dist/webpack.js

@@ -1,8 +1,9 @@
 import {
   unpluginFactory
-} from "./chunk-7CA3EIIX.js";
+} from "./chunk-HBXMM25C.js";
 import "./chunk-EY3HXBJ4.js";
 import "./chunk-C5A7XLKL.js";
+import "./chunk-WOMR3ZLM.js";
 import "./chunk-RKHJN6KY.js";
 
 // src/webpack.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unplugin-https-reverse-proxy",
   "type": "module",
-  "version": "4.1.0-beta.2",
+  "version": "4.1.0-beta.3",
   "description": "",
   "license": "MIT",
   "homepage": "https://github.com/zcf0508/unplugin-https-reverse-proxy#readme",

package/src/caddy/index.ts

@@ -132,16 +132,17 @@ function splitHostPort(addr: string): { host: string, port: string } {
 
 /** Injection point for tests: opens the privileged helper without sudo. */
 export interface CaddyDependencies {
-  openSession: (runtimeDir: string) => Promise<OpenedPrivilegedSession>
+  openSession: (runtimeDir: string, reason?: { target: string, https: boolean }) => Promise<OpenedPrivilegedSession>
 }
 
 const defaultDependencies: CaddyDependencies = {
-  openSession: runtimeDir => openPrivilegedSession(runtimeDir, {
+  openSession: (runtimeDir, reason) => openPrivilegedSession(runtimeDir, {
     log: message => consola.debug(message),
     // Both paths are fixed here, before any socket traffic: the privileged
     // helper must never execute something named in a request.
     caddyBin: caddyPath,
     caddyConfigPath: caddyFilePath,
+    reason,
   }),
 }
 
@@ -182,14 +183,14 @@ export class CaddyInstant {
    * reused across instances so a second dev server does not ask for a
    * password again.
    */
-  private async session(): Promise<OpenedPrivilegedSession> {
+  private async session(reason?: { target: string, https: boolean }): Promise<OpenedPrivilegedSession> {
     // A crashed helper leaves the cached client permanently disconnected; drop
     // it so the next call starts a fresh helper instead of failing forever.
     if (this._session && !this._session.client.connected)
       this._session = undefined
 
     if (!this._session)
-      this._session = await this.deps.openSession(TEMP_DIR)
+      this._session = await this.deps.openSession(TEMP_DIR, reason)
     return this._session
   }
 
@@ -313,10 +314,10 @@ export class CaddyInstant {
     if (!this.inited)
       await this.init()
 
-    const session = await this.session()
-
     const sourceHost = splitHostPort(source).host
     const targetHost = splitHostPort(target).host
+
+    const session = await this.session({ target: targetHost, https })
     await session.client.call('hosts.add', { ip: sourceHost, host: targetHost })
     consola.success('update host success\n')
 

package/src/caddy/privileged.ts

@@ -82,6 +82,8 @@ export interface PrivilegedSessionOptions {
   caddyBin: string
   /** Caddyfile the helper may load. */
   caddyConfigPath: string
+  /** Shown before the password prompt so the request is not a surprise. */
+  reason?: { target: string, https: boolean }
 }
 
 /** Where Caddy keeps its PKI, per platform. */
@@ -113,6 +115,7 @@ export function openPrivilegedSession(
     // execute a path supplied over the socket.
     caddyBin: options.caddyBin,
     caddyConfigPath: options.caddyConfigPath,
+    reason: options.reason,
     log: options.log,
   })
 }