@fonlan/dsh-web-auth 0.1.0

package/lib/client.js

@@ -0,0 +1,305 @@
+window.__ModuleLoader__.load({
+	id: "dsh-web-auth",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+"use strict";
+var dshWebAuthModule = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+    get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+  }) : x)(function(x) {
+    if (typeof require !== "undefined") return require.apply(this, arguments);
+    throw Error('Dynamic require of "' + x + '" is not supported');
+  });
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/client/index.tsx
+  var index_exports = {};
+  __export(index_exports, {
+    apply: () => apply,
+    inject: () => inject
+  });
+  var import_react = __require("react");
+  var import_jsx_runtime = __require("react/jsx-runtime");
+  var inject = ["slots"];
+  var CSS = `
+.dwa-card { display: flex; flex-direction: column; gap: 12px; padding: 16px; }
+.dwa-row { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+.dwa-status { font-size: 13px; line-height: 1.6; }
+.dwa-status[data-on] { color: var(--dsw-alias-label-primary, #e6e6e6); }
+.dwa-status[data-off] { color: var(--dsw-alias-state-warn-primary, #e0a53b); }
+.dwa-hint { color: var(--dsw-alias-label-tertiary, #8b93a7); font-size: 12px; line-height: 1.6; margin: 0; }
+.dwa-field { display: flex; flex-direction: column; gap: 5px; }
+.dwa-label { color: var(--dsw-alias-label-secondary, #aab2c5); font-size: 12px; font-weight: 600; }
+.dwa-input {
+  height: 34px; padding: 0 12px; border-radius: 8px; outline: none;
+  border: 1px solid var(--dsw-alias-border-l2, #2a3346);
+  background: var(--dsw-alias-bg-layer-3, #0d1017);
+  color: var(--dsw-alias-label-primary, #e6e6e6); font: inherit; font-size: 13px;
+}
+.dwa-input:focus { border-color: var(--dsw-alias-brand-primary, #4f8cff); }
+.dwa-actions { display: flex; align-items: center; gap: 10px; }
+.dwa-btn {
+  height: 32px; padding: 0 14px; border: none; border-radius: 8px; cursor: pointer;
+  background: var(--dsw-alias-button-info-fill, #4f8cff); color: #fff;
+  font: inherit; font-size: 13px; font-weight: 600;
+}
+.dwa-btn:hover:not(:disabled) { background: var(--dsw-alias-button-info-hover, #6b9dff); }
+.dwa-btn:disabled { opacity: .5; cursor: default; }
+.dwa-btn[data-ghost] {
+  background: transparent; color: var(--dsw-alias-label-secondary, #aab2c5);
+  border: 1px solid var(--dsw-alias-border-l2, #2a3346); font-weight: 500;
+}
+.dwa-msg { margin: 0; font-size: 12.5px; line-height: 1.6; }
+.dwa-msg[data-kind=ok] { color: var(--dsw-alias-state-success-primary, #4caf7d); }
+.dwa-msg[data-kind=err] { color: var(--dsw-alias-state-error-primary, #ff8f8f); }
+.dwa-divider { border: none; border-top: 1px solid var(--dsw-alias-border-l1, #232a38); margin: 2px 0; }
+`;
+  function injectStyle() {
+    const id = "dsh-web-auth/card.css";
+    if (document.getElementById(id) !== null) return;
+    const tag = document.createElement("style");
+    tag.id = id;
+    tag.dataset.plugin = "dsh-web-auth";
+    tag.textContent = CSS;
+    document.head.appendChild(tag);
+  }
+  async function changePassword(oldPassword, newPassword) {
+    try {
+      const response = await fetch("/api/web-auth/password", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ oldPassword, newPassword })
+      });
+      const data = await response.json();
+      if (response.ok && data.ok === true) return { ok: true, message: "\u5BC6\u7801\u5DF2\u4FEE\u6539\uFF0C\u6240\u6709\u4F1A\u8BDD\u5DF2\u5931\u6548\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55\u3002" };
+      if (data.error === "wrong-password") return { ok: false, message: "\u65E7\u5BC6\u7801\u9519\u8BEF\u3002" };
+      if (data.error === "password-too-short") return { ok: false, message: "\u65B0\u5BC6\u7801\u81F3\u5C11 8 \u4F4D\u3002" };
+      if (data.error === "rate-limited") return { ok: false, message: "\u5C1D\u8BD5\u8FC7\u4E8E\u9891\u7E41\uFF0C\u8BF7\u7A0D\u540E\u518D\u8BD5\u3002" };
+      return { ok: false, message: "\u4FEE\u6539\u5931\u8D25\uFF1A" + String(data.error ?? response.status) };
+    } catch {
+      return { ok: false, message: "\u7F51\u7EDC\u9519\u8BEF\uFF0C\u8BF7\u91CD\u8BD5\u3002" };
+    }
+  }
+  var LISTEN_OPTIONS = [
+    { value: "127.0.0.1", label: "127.0.0.1\uFF08\u4EC5\u672C\u673A\uFF09" },
+    { value: "0.0.0.0", label: "0.0.0.0\uFF08\u6240\u6709\u7F51\u5361\uFF0C\u5C40\u57DF\u7F51\u53EF\u8BBF\u95EE\uFF09" }
+  ];
+  function isListenHost(value) {
+    return value === "127.0.0.1" || value === "0.0.0.0";
+  }
+  function PasswordSection(_props) {
+    const [configured, setConfigured] = (0, import_react.useState)(null);
+    const [oldPassword, setOldPassword] = (0, import_react.useState)("");
+    const [newPassword, setNewPassword] = (0, import_react.useState)("");
+    const [confirm, setConfirm] = (0, import_react.useState)("");
+    const [busy, setBusy] = (0, import_react.useState)(false);
+    const [message, setMessage] = (0, import_react.useState)(null);
+    const [listenHost, setListenHost] = (0, import_react.useState)(null);
+    const [listenPick, setListenPick] = (0, import_react.useState)("127.0.0.1");
+    const [listenBusy, setListenBusy] = (0, import_react.useState)(false);
+    const [listenMsg, setListenMsg] = (0, import_react.useState)(null);
+    (0, import_react.useEffect)(() => {
+      let alive = true;
+      void fetch("/api/web-auth/status").then((response) => response.ok ? response.json() : null).then((data) => {
+        if (!alive) return;
+        setConfigured(data?.configured === true);
+        if (isListenHost(data?.host)) {
+          setListenHost(data.host);
+          setListenPick(data.host);
+        }
+      }).catch(() => {
+        if (alive) setConfigured(null);
+      });
+      return () => {
+        alive = false;
+      };
+    }, []);
+    const submit = async () => {
+      if (newPassword.length < 8) {
+        setMessage({ kind: "err", text: "\u65B0\u5BC6\u7801\u81F3\u5C11 8 \u4F4D\u3002" });
+        return;
+      }
+      if (newPassword !== confirm) {
+        setMessage({ kind: "err", text: "\u4E24\u6B21\u8F93\u5165\u7684\u65B0\u5BC6\u7801\u4E0D\u4E00\u81F4\u3002" });
+        return;
+      }
+      setBusy(true);
+      setMessage(null);
+      const result = await changePassword(oldPassword, newPassword);
+      setBusy(false);
+      setMessage({ kind: result.ok ? "ok" : "err", text: result.message });
+      if (result.ok) {
+        setConfigured(true);
+        setOldPassword("");
+        setNewPassword("");
+        setConfirm("");
+        window.setTimeout(() => {
+          window.location.href = "/login";
+        }, 1600);
+      }
+    };
+    const applyListen = async () => {
+      if (listenHost === listenPick) return;
+      setListenBusy(true);
+      setListenMsg(null);
+      try {
+        const response = await fetch("/api/web-auth/listen", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ host: listenPick })
+        });
+        const data = await response.json();
+        if (response.ok && data.ok === true) {
+          if (data.applying === true) {
+            setListenMsg({ kind: "ok", text: "\u5DF2\u5207\u6362\uFF0C\u6B63\u5728\u91CD\u65B0\u7ED1\u5B9A\u76D1\u542C\u7AEF\u53E3\uFF0C\u9875\u9762\u5C06\u77ED\u6682\u65AD\u8FDE\u2026" });
+            for (let i = 0; i < 15; i++) {
+              await new Promise((resolve) => setTimeout(resolve, 600));
+              try {
+                const check = await fetch("/api/web-auth/status");
+                const status = await check.json();
+                if (isListenHost(status.host) && status.host === listenPick) {
+                  setListenHost(listenPick);
+                  setListenMsg({ kind: "ok", text: "\u5DF2\u751F\u6548\uFF1A\u76D1\u542C\u5730\u5740\u4E3A " + listenPick + "\u3002" });
+                  return;
+                }
+              } catch {
+              }
+            }
+            setListenMsg({ kind: "ok", text: "\u5DF2\u5E94\u7528\uFF0C\u82E5\u9875\u9762\u8FDE\u63A5\u4E2D\u65AD\u8BF7\u7A0D\u5019\u5237\u65B0\uFF08\u76D1\u542C\u5730\u5740\uFF1A" + listenPick + "\uFF09\u3002" });
+          } else {
+            setListenHost(listenPick);
+            setListenMsg({ kind: "ok", text: "\u76D1\u542C\u5730\u5740\u672A\u53D8\u5316\u3002" });
+          }
+        } else {
+          const text = data.error === "invalid-host" ? "\u65E0\u6548\u7684\u76D1\u542C\u5730\u5740\u3002" : data.error === "unsupported" ? "\u5F53\u524D\u73AF\u5883\u4E0D\u652F\u6301\u4FEE\u6539\u76D1\u542C\u5730\u5740\u3002" : "\u5207\u6362\u5931\u8D25\uFF1A" + String(data.error ?? response.status);
+          setListenMsg({ kind: "err", text });
+        }
+      } catch {
+        setListenMsg({ kind: "err", text: "\u7F51\u7EDC\u9519\u8BEF\uFF0C\u8BF7\u91CD\u8BD5\u3002" });
+      } finally {
+        setListenBusy(false);
+      }
+    };
+    if (configured === null) {
+      return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "dwa-card", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dwa-hint", children: "\u52A0\u8F7D\u4E2D\u2026" }) });
+    }
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-card", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "dwa-row", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dwa-status", "data-on": configured ? void 0 : "", "data-off": configured ? "" : void 0, children: configured ? "\u8BBF\u95EE\u8BA4\u8BC1\uFF1A\u5DF2\u542F\u7528" : "\u8BBF\u95EE\u8BA4\u8BC1\uFF1A\u672A\u8BBE\u7F6E\u5BC6\u7801\uFF08\u5F53\u524D\u672A\u542F\u7528\uFF09" }) }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dwa-hint", children: "\u8BBE\u7F6E\u540E\uFF0C\u8BBF\u95EE\u672C\u670D\u52A1\u9700\u8981\u8F93\u5165\u5BC6\u7801\uFF1B\u4F1A\u8BDD\u6709\u6548\u671F 7 \u5929\uFF08\u6D3B\u52A8\u81EA\u52A8\u7EED\u671F\uFF09\u3002\u4FEE\u6539\u5BC6\u7801\u4F1A\u4F7F\u6240\u6709\u5DF2\u767B\u5F55\u4F1A\u8BDD\u7ACB\u5373\u5931\u6548\u3002" }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("hr", { className: "dwa-divider" }),
+      configured && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-field", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", { className: "dwa-label", htmlFor: "dwa-old", children: "\u65E7\u5BC6\u7801" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "input",
+          {
+            id: "dwa-old",
+            className: "dwa-input",
+            type: "password",
+            autoComplete: "current-password",
+            value: oldPassword,
+            onChange: (e) => setOldPassword(e.target.value)
+          }
+        )
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-field", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", { className: "dwa-label", htmlFor: "dwa-new", children: "\u65B0\u5BC6\u7801\uFF08\u81F3\u5C11 8 \u4F4D\uFF09" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "input",
+          {
+            id: "dwa-new",
+            className: "dwa-input",
+            type: "password",
+            autoComplete: "new-password",
+            value: newPassword,
+            onChange: (e) => setNewPassword(e.target.value)
+          }
+        )
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-field", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", { className: "dwa-label", htmlFor: "dwa-confirm", children: "\u786E\u8BA4\u65B0\u5BC6\u7801" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "input",
+          {
+            id: "dwa-confirm",
+            className: "dwa-input",
+            type: "password",
+            autoComplete: "new-password",
+            value: confirm,
+            onChange: (e) => setConfirm(e.target.value)
+          }
+        )
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-actions", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { className: "dwa-btn", disabled: busy, onClick: () => void submit(), children: "\u4FEE\u6539\u5BC6\u7801" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { className: "dwa-btn", "data-ghost": "", onClick: () => {
+          window.location.href = "/logout";
+        }, children: "\u9000\u51FA\u767B\u5F55" })
+      ] }),
+      message !== null && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dwa-msg", "data-kind": message.kind, role: "alert", children: message.text }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("hr", { className: "dwa-divider" }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-field", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", { className: "dwa-label", htmlFor: "dwa-listen", children: "\u76D1\u542C\u5730\u5740" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "select",
+          {
+            id: "dwa-listen",
+            className: "dwa-input",
+            value: listenPick,
+            disabled: listenBusy || listenHost === null,
+            onChange: (e) => setListenPick(e.target.value),
+            children: LISTEN_OPTIONS.map((option) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: option.value, children: option.label }, option.value))
+          }
+        )
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "dwa-actions", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        "button",
+        {
+          className: "dwa-btn",
+          disabled: listenBusy || listenHost === null || listenHost === listenPick,
+          onClick: () => void applyListen(),
+          children: "\u5E94\u7528\u76D1\u542C\u5730\u5740"
+        }
+      ) }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dwa-hint", children: "\u5207\u6362\u540E dsh \u4F1A\u7ACB\u5373\u91CD\u65B0\u7ED1\u5B9A\u76D1\u542C\u7AEF\u53E3\uFF08WebSocket \u77ED\u6682\u65AD\u8FDE\u540E\u81EA\u52A8\u91CD\u8FDE\uFF09\u3002\u6CE8\u610F\uFF1A\u82E5\u5F53\u524D\u901A\u8FC7\u5C40\u57DF\u7F51 IP \u8BBF\u95EE\uFF0C\u5207\u56DE 127.0.0.1 \u540E\u53EA\u80FD\u5728\u672C\u673A\u8BBF\u95EE\u3002" }),
+      listenMsg !== null && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dwa-msg", "data-kind": listenMsg.kind, role: "alert", children: listenMsg.text })
+    ] });
+  }
+  function apply(ctx) {
+    injectStyle();
+    const slots = ctx.slots;
+    slots.inject(
+      "settings.section",
+      () => slots.register(
+        {
+          name: "settings.section",
+          id: "web-auth",
+          order: 120,
+          label: () => "\u8BBF\u95EE\u8BA4\u8BC1"
+        },
+        PasswordSection
+      )
+    );
+  }
+  return __toCommonJS(index_exports);
+})();
+
+		return typeof dshWebAuthModule !== "undefined" ? dshWebAuthModule : module.exports;
+	}
+});

package/lib/context-types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Structural cordis Context for the host half. A third-party plugin resolves
+ * outside the DSH monorepo's single cordis instance, so the upstream
+ * `declare module` augmentations do not reach this Context. The members
+ * below mirror the runtime shapes this plugin touches.
+ */
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+/** The webServer service face (subset of @deepseek-ai/dsh-host-webserver). */
+export interface WebServerService {
+    /** The underlying node:http server (gated by wrapping its listeners). */
+    server: Server;
+    /** The listening port (the OS-assigned value when config.port is 0). */
+    port: number;
+    /** The configured bind host ('127.0.0.1' or '0.0.0.0'). */
+    host: string;
+    /** Register an exact-path route; returns the disposer. */
+    register(route: {
+        kind: 'exact';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => void;
+    }): () => void;
+}
+/** The plugin context members this plugin consumes. */
+export interface PluginContext {
+    webServer: WebServerService;
+    logger: {
+        warn(message: string): void;
+        error(message: string): void;
+    };
+    /** Register a setup that returns a disposer, tied to this fiber. */
+    effect(setup: () => unknown, label?: string): void;
+    /**
+     * The composition root directory as a file URL (the profile directory the
+     * boot anchors on — the loader inherits it down the whole tree).
+     */
+    baseUrl: string;
+}

package/lib/context-types.js

@@ -0,0 +1 @@
+export {};

package/lib/gate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * dsh-web-auth — HTTP gate: wraps the node:http server's request/upgrade
+ * listeners so EVERY request (routes, static fallback, WebSocket upgrades)
+ * passes the auth check before the original dispatch sees it.
+ *
+ * The webserver package registers exactly one 'request' listener (its route
+ * dispatcher) and one 'upgrade' listener. The gate captures them, removes
+ * them, and re-installs a single wrapper: denied requests are answered by
+ * the gate itself; allowed requests are forwarded to the captured listeners
+ * in original order. Disposal restores the originals.
+ *
+ * Installation is deferred until the server is actually listening, so the
+ * captured listener set is the final one. A WeakSet guard makes re-entry
+ * (HMR re-mount) a no-op.
+ */
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+export interface GateHandlers {
+    /** Decide whether one request may proceed; false = gate answers it. */
+    allow(req: IncomingMessage, res: ServerResponse): boolean;
+    /** Hook after an allowed request (cookie refresh). */
+    passed?(req: IncomingMessage, res: ServerResponse): void;
+    /** Decide whether one WebSocket upgrade may proceed. */
+    allowUpgrade(req: IncomingMessage): boolean;
+}
+/** Standard HTTP rejection for a denied WebSocket upgrade. */
+export declare function rejectUpgrade(socket: Duplex, status?: number, body?: string): void;
+/**
+ * Install the auth gate on a listening HTTP server. Returns the disposer
+ * restoring the original listeners (idempotent).
+ */
+export declare function installGate(server: Server, handlers: GateHandlers): () => void;

package/lib/gate.js

@@ -0,0 +1,55 @@
+const gated = new WeakSet();
+/** Standard HTTP rejection for a denied WebSocket upgrade. */
+export function rejectUpgrade(socket, status = 401, body = 'unauthorized') {
+    socket.end([
+        `HTTP/1.1 ${status} ${status === 401 ? 'Unauthorized' : 'Forbidden'}`,
+        'Connection: close',
+        'Content-Type: text/plain; charset=utf-8',
+        'Content-Length: ' + Buffer.byteLength(body),
+        '',
+        body
+    ].join('\r\n'));
+}
+/**
+ * Install the auth gate on a listening HTTP server. Returns the disposer
+ * restoring the original listeners (idempotent).
+ */
+export function installGate(server, handlers) {
+    if (gated.has(server))
+        return () => { };
+    gated.add(server);
+    const requestListeners = server.listeners('request');
+    const upgradeListeners = server.listeners('upgrade');
+    server.removeAllListeners('request');
+    server.removeAllListeners('upgrade');
+    server.on('request', (req, res) => {
+        if (!handlers.allow(req, res))
+            return;
+        handlers.passed?.(req, res);
+        for (const listener of requestListeners) {
+            ;
+            listener(req, res);
+        }
+    });
+    server.on('upgrade', (req, socket, head) => {
+        if (!handlers.allowUpgrade(req)) {
+            rejectUpgrade(socket);
+            return;
+        }
+        for (const listener of upgradeListeners) {
+            ;
+            listener(req, socket, head);
+        }
+    });
+    return () => {
+        if (!gated.has(server))
+            return;
+        gated.delete(server);
+        server.removeAllListeners('request');
+        server.removeAllListeners('upgrade');
+        for (const listener of requestListeners)
+            server.on('request', listener);
+        for (const listener of upgradeListeners)
+            server.on('upgrade', listener);
+    };
+}

package/lib/handlers.d.ts

@@ -0,0 +1,121 @@
+/**
+ * dsh-web-auth — request handlers: the gate decision (whitelist + session
+ * check), the /login page + form processing (including first-password setup),
+ * /logout, and the JSON change-password API for the settings card.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type RateLimiter } from './auth-core.ts';
+import { type ListenHost } from './profile-patch.ts';
+/** Maximum accepted request body for the login form / API. */
+export declare const MAX_BODY_BYTES: number;
+export interface AuthState {
+    /** Current session-signing secret (rotated on password change). */
+    secret: Buffer;
+    /** Current password hash (re-read per attempt so GUI changes apply live). */
+    readHash(): string | undefined;
+    writeHash(hash: string): void;
+    /** Replace the signing secret; returns the new secret. */
+    rotateSecret(): Buffer;
+}
+export interface HandlerEnv {
+    state: AuthState;
+    limiter: RateLimiter;
+    now?: () => number;
+    /**
+     * Loopback authority ("127.0.0.1:<port>") used to rewrite the Host/Origin
+     * of AUTHENTICATED requests (any path prefix).
+     * The /api gateway pins its privileged methods (settings.*, credentials.*,
+     * llm.discoverModels, agentPreset.*, host.*) to loopback because its
+     * trustedHosts fence is DNS-rebinding defense, NOT authentication — the
+     * upstream comment says the plane stays loopback "until a real
+     * authentication layer exists". Plugin surfaces that mirror the /api fence
+     * (dsh-better-sidebar's /sidebar routes) behave the same way. This plugin
+     * IS that layer: a request carrying a valid session cookie is same-origin
+     * by construction (SameSite=Lax), so it may present as loopback. Requests
+     * without a session never reach the fences (the gate rejects them first).
+     */
+    loopbackAuthority?: string;
+    /**
+     * Listen-address controller (bound by the host half when the profile
+     * patch layer is reachable). Absent = the settings card cannot change
+     * the bind host.
+     */
+    listen?: ListenController;
+}
+/**
+ * Live listen-host switching: the webserver's bind host is composition
+ * config, so the change is written into the owning patch layer (profile or
+ * home cordis.patch.yml) and HMR hot-applies it — the webserver row
+ * reloads, closes its listener, and rebinds. The controller is split into
+ * prepare (reportable failures) and commit (after the response flushed,
+ * failures logged) because the reload tears down every connection,
+ * including the one carrying the confirmation.
+ */
+export interface ListenController {
+    /** The currently resolved bind host (the webserver's runtime config). */
+    current(): string | undefined;
+    /**
+     * Read + transform the owning patch layer for `host`, returning the next
+     * file content. Throws when the patch file cannot be prepared — the
+     * change is refused before anything is written.
+     */
+    prepare(host: ListenHost): string;
+    /**
+     * Write the prepared content (typically deferred a beat after the
+     * response). Failures are logged, never thrown: the caller already
+     * confirmed the change to the client.
+     */
+    commit(content: string): void;
+}
+export declare function pathnameOf(req: IncomingMessage): string;
+/** Read one cookie by name from the Cookie header. */
+export declare function cookieValue(header: string | undefined, name: string): string | undefined;
+/**
+ * The client address for rate limiting. X-Forwarded-For is honored ONLY when
+ * the direct peer is loopback (the reverse proxy sits on the same host), so
+ * a remote attacker hitting dsh directly cannot forge a fresh identity.
+ */
+export declare function clientIp(req: IncomingMessage): string;
+/** Whether the browser's connection is HTTPS (reverse-proxied or direct). */
+export declare function isSecureRequest(req: IncomingMessage): boolean;
+/** Collect the request body; undefined when it exceeds the cap (413). */
+export declare function readBody(req: IncomingMessage, maxBytes?: number): Promise<string | undefined>;
+/** Parse application/x-www-form-urlencoded. */
+export declare function parseUrlEncoded(body: string): Record<string, string>;
+/** Set (or refresh) the session cookie on a response. */
+export declare function setSessionCookie(res: ServerResponse, secret: Buffer, now: number, secure: boolean): void;
+export interface Gate {
+    allow(req: IncomingMessage, res: ServerResponse): boolean;
+    allowUpgrade(req: IncomingMessage): boolean;
+}
+/**
+ * Build the gate used to wrap the HTTP server listeners. Whitelisted paths
+ * (login page/form, logout) pass through; everything else requires a valid
+ * session cookie. Page requests (GET/HEAD) are redirected to /login with the
+ * original URL as `next`; other methods get a plain 401 JSON. WebSocket
+ * upgrades without a session are rejected at the handshake.
+ */
+export declare function createGate(env: HandlerEnv): Gate;
+export declare function handleLoginPage(req: IncomingMessage, res: ServerResponse, env: HandlerEnv): void;
+export declare function handleLoginPost(req: IncomingMessage, res: ServerResponse, env: HandlerEnv): Promise<void>;
+export declare function handleLogout(req: IncomingMessage, res: ServerResponse, env: HandlerEnv): void;
+export declare function handleStatus(req: IncomingMessage, res: ServerResponse, env: HandlerEnv): void;
+export interface ChangePasswordBody {
+    oldPassword?: string;
+    newPassword?: string;
+}
+export declare function handleChangePassword(req: IncomingMessage, res: ServerResponse, env: HandlerEnv): Promise<void>;
+export interface ListenChangeBody {
+    host?: unknown;
+}
+/**
+ * Switch the web server's bind host between '127.0.0.1' and '0.0.0.0'.
+ *
+ * The change is applied to the owning patch layer (profile or home
+ * cordis.patch.yml); HMR then reloads the webserver row, which closes and
+ * rebinds the listener. The response is written BEFORE the patch file is
+ * committed — the reload tears down every connection, including this one —
+ * so the client gets its confirmation first and the write lands a beat
+ * later (see {@link ListenController}).
+ */
+export declare function handleListenChange(req: IncomingMessage, res: ServerResponse, env: HandlerEnv): Promise<void>;