@fonlan/dsh-web-auth 0.1.7 → 0.1.9

package/cordis.patch.yml

@@ -11,13 +11,13 @@
 # the auth gate wraps the HTTP listener after it is bound.
 #
 # The package also declares `dsh.client` (see package.json), so the web app
-# loads the browser half (the plugin's own Settings Card) automatically. The
-# card registers on the `settings.plugin.item` slot keyed by the `web-auth`
-# settings namespace (see src/settings.ts) — the 设置 → 插件 → 插件配置 tab
-# pairs the two.
+# loads the browser half (the plugin's own settings page) automatically. The
+# page registers on the `settings.section` slot as the 「访问认证」 entry in the
+# settings sidebar and binds the `web-auth` settings namespace
+# (see src/settings.ts) through the client settings scope.
 #
 # There is intentionally NO password here: passwords are maintained through
-# the GUI (login page first setup / settings card change), stored hashed
+# the GUI (login page first setup / settings page change), stored hashed
 # under $DSH_HOME/web-auth/. Until a password is set, auth stays disabled
 # (see the README for the warning this prints at boot).
 - insert:

package/lib/client/index.d.ts

@@ -4,11 +4,12 @@ import type { Context } from '@deepseek-ai/cordis';
  * `connection` and `remote` are required by `settingsScope.bind` (it resolves
  * the settings transport and the forwarded-invalidation subscription through
  * `ctx.get`), so the fiber must wait for them — exactly like
- * dsh-client-ui-settings-plugins does for its own cards.
+ * the settings shell does for its own sections. dsh >= 0.1.7 dropped
+ * `settingsScope` itself, so it is resolved optionally below.
  */
 export declare const inject: string[];
 /**
- * Client plugin body: register the settings card. The shell's declaration
+ * Client plugin body: register the settings page. The shell's declaration
  * may not be on the ledger yet, so the registration waits via slots.inject.
  * @param ctx - the client cordis context.
  */

package/lib/client.js

@@ -37,36 +37,14 @@ var dshWebAuthModule = (() => {
   });
   var import_react = __require("react");
   var import_jsx_runtime = __require("react/jsx-runtime");
-  var inject = ["slots", "settingsScope", "connection", "remote"];
+  var inject = ["slots"];
   var WEB_AUTH_NS = "web-auth";
   var CSS = `
-.dwa-card {
-  border: 1px solid var(--dsw-alias-border-l2, #2a3346);
-  background: var(--dsw-alias-bg-layer-3, #0d1017);
-  border-radius: 12px;
-  list-style: none;
-  transition: border-color .16s, background .16s;
-}
-.dwa-card:hover { border-color: var(--dsw-alias-label-dimmed, #4a5468); }
-.dwa-card[data-open] {
-  background: var(--dsw-alias-bg-layer-2, #141a26);
-  border-color: var(--dsw-alias-label-dimmed, #4a5468);
-}
-.dwa-head {
-  appearance: none; width: 100%; font: inherit; color: inherit; text-align: left; cursor: pointer;
-  background: transparent; border: 0; border-radius: 12px;
-  align-items: center; gap: 12px; padding: 14px 16px; display: flex;
-}
-.dwa-head:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary, #4f8cff); outline-offset: -2px; }
-.dwa-headText { flex-direction: column; flex: 1; gap: 4px; min-width: 0; display: flex; }
-.dwa-title { color: var(--dsw-alias-label-primary, #e6e6e6); font-size: 15px; font-weight: 600; line-height: 1.4; }
-.dwa-sub { color: var(--dsw-alias-label-tertiary, #8b93a7); font-size: 13px; line-height: 1.5; }
-.dwa-chevron {
-  color: var(--dsw-alias-label-tertiary, #8b93a7); flex: none;
-  transition: transform .16s; display: flex; align-items: center; justify-content: center;
-}
-.dwa-chevron[data-open] { transform: rotate(180deg); }
-.dwa-body { border-top: 1px solid var(--dsw-alias-border-l2, #2a3346); margin: 0 16px; padding: 12px 0 8px; display: flex; flex-direction: column; gap: 12px; }
+.dwa-page { display: flex; flex-direction: column; gap: 16px; max-width: 720px; }
+.dwa-page-head { display: flex; flex-direction: column; gap: 6px; }
+.dwa-page-title { color: var(--dsw-alias-label-primary, #e6e6e6); margin: 0; font-size: 15px; font-weight: 600; line-height: 1.4; }
+.dwa-page-sub { color: var(--dsw-alias-label-tertiary, #8b93a7); margin: 0; font-size: 13px; line-height: 1.5; }
+.dwa-body { display: flex; flex-direction: column; gap: 12px; }
 .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); }
@@ -99,7 +77,7 @@ var dshWebAuthModule = (() => {
 .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";
+    const id = "dsh-web-auth/settings-section.css";
     if (document.getElementById(id) !== null) return;
     const tag = document.createElement("style");
     tag.id = id;
@@ -141,7 +119,7 @@ var dshWebAuthModule = (() => {
       return null;
     }
   }
-  function AuthCard(props) {
+  function WebAuthSettingsSection(props) {
     const { scope } = props;
     const snapshot = (0, import_react.useSyncExternalStore)(
       (listener) => scope.subscribe(listener),
@@ -157,7 +135,6 @@ var dshWebAuthModule = (() => {
     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);
-    const [open, setOpen] = (0, import_react.useState)(false);
     (0, import_react.useEffect)(() => {
       let alive = true;
       void fetchStatus().then((status) => {
@@ -220,34 +197,12 @@ var dshWebAuthModule = (() => {
         setListenBusy(false);
       }
     };
-    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-card", "data-open": open ? "" : void 0, children: [
-      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
-        "button",
-        {
-          type: "button",
-          className: "dwa-head",
-          "aria-expanded": open,
-          "aria-label": (open ? "\u6536\u8D77" : "\u5C55\u5F00") + "\uFF1A\u8BBF\u95EE\u8BA4\u8BC1",
-          onClick: () => setOpen(!open),
-          children: [
-            /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { className: "dwa-headText", children: [
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "dwa-title", children: "\u8BBF\u95EE\u8BA4\u8BC1" }),
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "dwa-sub", children: "Web \u8BBF\u95EE\u5BC6\u7801\u4E0E\u76D1\u542C\u5730\u5740" })
-            ] }),
-            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "dwa-chevron", "data-open": open ? "" : void 0, "aria-hidden": "true", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("svg", { width: "14", height: "14", viewBox: "0 0 14 14", fill: "none", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-              "path",
-              {
-                d: "M3.5 5.25L7 8.75L10.5 5.25",
-                stroke: "currentColor",
-                strokeWidth: "1.5",
-                strokeLinecap: "round",
-                strokeLinejoin: "round"
-              }
-            ) }) })
-          ]
-        }
-      ),
-      open && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-body", children: [
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-page", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("header", { className: "dwa-page-head", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("h3", { className: "dwa-page-title", children: "\u8BBF\u95EE\u8BA4\u8BC1" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dwa-page-sub", children: "Web \u8BBF\u95EE\u5BC6\u7801\u4E0E\u76D1\u542C\u5730\u5740" })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dwa-body", 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 === null ? "\u52A0\u8F7D\u4E2D\u2026" : 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" }),
@@ -330,20 +285,25 @@ var dshWebAuthModule = (() => {
     ] });
   }
   function apply(ctx) {
-    injectStyle();
-    const services = ctx;
-    const scope = services.settingsScope.bind({ namespace: WEB_AUTH_NS });
-    services.slots.inject(
-      "settings.plugin.item",
-      () => services.slots.register(
-        {
-          name: "settings.plugin.item",
-          key: WEB_AUTH_NS,
-          inject: () => ({ scope })
-        },
-        AuthCard
-      )
-    );
+    ctx.inject(["settingsScope"], (raw) => {
+      const c = raw;
+      if (c.settingsScope === void 0) return;
+      injectStyle();
+      const scope = c.settingsScope.bind({ namespace: WEB_AUTH_NS });
+      c.slots.inject(
+        "settings.section",
+        () => c.slots.register(
+          {
+            name: "settings.section",
+            id: "web-auth",
+            order: 120,
+            label: "\u8BBF\u95EE\u8BA4\u8BC1",
+            inject: () => ({ scope })
+          },
+          WebAuthSettingsSection
+        )
+      );
+    });
   }
   return __toCommonJS(index_exports);
 })();

package/lib/gate.d.ts

@@ -25,8 +25,13 @@ export interface GateHandlers {
      * rejection must not prevent the downstream dispatch.
      */
     passed?(req: IncomingMessage, res: ServerResponse): void | Promise<void>;
-    /** Decide whether one WebSocket upgrade may proceed. */
-    allowUpgrade(req: IncomingMessage): boolean;
+    /**
+     * Decide whether one WebSocket upgrade may proceed. May be async: the gate
+     * awaits the decision before forwarding, letting a handler repair the
+     * request (for example by resolving a session cookie onto its headers)
+     * instead of only approving or refusing it.
+     */
+    allowUpgrade(req: IncomingMessage): boolean | Promise<boolean>;
 }
 /** Standard HTTP rejection for a denied WebSocket upgrade. */
 export declare function rejectUpgrade(socket: Duplex, status?: number, body?: string): void;

package/lib/gate.js

@@ -38,14 +38,24 @@ export function installGate(server, handlers) {
         }
     });
     server.on('upgrade', (req, socket, head) => {
-        if (!handlers.allowUpgrade(req)) {
-            rejectUpgrade(socket);
-            return;
-        }
-        for (const listener of upgradeListeners) {
-            ;
-            listener(req, socket, head);
-        }
+        void (async () => {
+            let allowed;
+            try {
+                allowed = await handlers.allowUpgrade(req);
+            }
+            catch {
+                allowed = false;
+            }
+            if (!allowed) {
+                if (!socket.destroyed && socket.writable)
+                    rejectUpgrade(socket);
+                return;
+            }
+            for (const listener of upgradeListeners) {
+                ;
+                listener(req, socket, head);
+            }
+        })();
     });
     return () => {
         if (!gated.has(server))

package/lib/handlers.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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.
+ * /logout, and the JSON change-password API for the settings page.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { type RateLimiter } from './auth-core.ts';
@@ -45,7 +45,7 @@ export interface HandlerEnv {
     loopbackAuthority?: string;
     /**
      * Listen-address controller (bound by the host half when the profile
-     * patch layer is reachable). Absent = the settings card cannot change
+     * patch layer is reachable). Absent = the settings page cannot change
      * the bind host.
      */
     listen?: ListenController;
@@ -94,9 +94,21 @@ export declare function parseUrlEncoded(body: string): Record<string, string>;
 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;
+    allowUpgrade(req: IncomingMessage): boolean | Promise<boolean>;
     passed?(req: IncomingMessage, res: ServerResponse): void | Promise<void>;
 }
+/**
+ * Name of DSH's authority-bound browser-session cookie for one authority.
+ * Mirrors the host's own `dsh-auth-<base64url(sha256(authority))>` scheme; if
+ * the scheme ever drifts this only misreads "carried" as "missing", which
+ * costs one harmless extra redirect, never a denial.
+ *
+ * Exported for the integration suite, which models a browser jar: the gate's
+ * "already carries the cookie" check is name-based, so a test that stores a
+ * differently-named cookie would silently exercise the late-mint path instead
+ * of the steady state.
+ */
+export declare function dshAuthCookieName(authority: string): string;
 /** Number of `token` query parameters in the request URL. */
 export declare function tokenQueryCount(req: IncomingMessage): number;
 /**

package/lib/handlers.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { COOKIE_NAME, MIN_PASSWORD_LENGTH, SESSION_TTL_SECONDS, hashPassword, needsSessionRefresh, sanitizeNext, signSession, verifyPassword, verifySession } from "./auth-core.js";
 import { renderLoginPage } from "./login-page.js";
 import { ALLOWED_LISTEN_HOSTS, isAllowedListenHost } from "./profile-patch.js";
@@ -109,6 +110,35 @@ function clearCookie(res, secure) {
 }
 /** Minimum interval between server-side DSH cookie mints (debounce). */
 const DSH_MINT_DEBOUNCE_MS = 1000;
+/** Per-peer cooldown between late-mint redirects (loop breaker). */
+const LATE_MINT_COOLDOWN_MS = 5000;
+/**
+ * Name of DSH's authority-bound browser-session cookie for one authority.
+ * Mirrors the host's own `dsh-auth-<base64url(sha256(authority))>` scheme; if
+ * the scheme ever drifts this only misreads "carried" as "missing", which
+ * costs one harmless extra redirect, never a denial.
+ *
+ * Exported for the integration suite, which models a browser jar: the gate's
+ * "already carries the cookie" check is name-based, so a test that stores a
+ * differently-named cookie would silently exercise the late-mint path instead
+ * of the steady state.
+ */
+export function dshAuthCookieName(authority) {
+    return 'dsh-auth-' + createHash('sha256').update(authority).digest('base64url');
+}
+/**
+ * Whether the request already carries a DSH browser-session cookie for the
+ * loopback authority every authenticated request is rewritten to. Unknown
+ * authority (webserver not bound yet) counts as carried: no intervention.
+ */
+function carriesLoopbackDshCookie(req, authority) {
+    if (authority === undefined)
+        return true;
+    const raw = req.headers.cookie;
+    if (raw === undefined)
+        return false;
+    return cookieValue(raw, dshAuthCookieName(authority)) !== undefined;
+}
 /** Number of `token` query parameters in the request URL. */
 export function tokenQueryCount(req) {
     try {
@@ -181,6 +211,54 @@ export function createGate(env) {
             console.error('[dsh-web-auth] DSH cookie mint failed:', error);
         }
     };
+    /** Last late-mint redirect per peer address (loop breaker). */
+    const lateMintAt = new Map();
+    /**
+     * One late-mint redirect per peer per cooldown window. A client that keeps
+     * refusing the relayed cookie must not be bounced forever; after the first
+     * bounce it passes through and DSH's own response (401 + the relayed
+     * cookie) is the fallback, exactly the pre-existing behavior.
+     */
+    const lateMintDue = (req) => {
+        const peer = req.socket.remoteAddress ?? '';
+        const t = now();
+        const last = lateMintAt.get(peer);
+        if (last !== undefined && t - last < LATE_MINT_COOLDOWN_MS)
+            return false;
+        lateMintAt.set(peer, t);
+        return true;
+    };
+    /**
+     * Answer a session-authenticated request that carries no DSH browser-
+     * session cookie for the loopback authority: mint the cookie server-side
+     * and bounce once through the same URL so the browser stores it. Without
+     * this, a browser holding only the plugin session reaches DSH and gets its
+     * raw 401 dead end ("reopen the URL printed by dsh web"), recovering only
+     * if the user happens to visit again; the redirect makes the first visit
+     * succeed. Falls back to /login when the mint is unavailable — that page
+     * retries the mint and offers the password form.
+     */
+    const respondWithLateMint = async (req, res) => {
+        const mint = env.mintDshCookie;
+        const cookie = mint === undefined ? undefined : await mint().catch(() => undefined);
+        // Share the mint throttle with the opportunistic mint in `passed()`: the
+        // retry that follows this bounce would otherwise spend a second loopback
+        // exchange to mint the very cookie it just stored.
+        if (cookie !== undefined)
+            lastMintAt = now();
+        if (res.headersSent)
+            return;
+        if (cookie === undefined) {
+            redirect(res, '/login?next=' + encodeURIComponent(sanitizeNext(req.url) ?? '/'));
+            return;
+        }
+        res.writeHead(302, {
+            'cache-control': 'no-store',
+            location: req.url ?? '/',
+            'set-cookie': cookie
+        });
+        res.end();
+    };
     /**
      * Present AUTHENTICATED traffic as loopback to every downstream
      * browser-trust fence, without tracking plugin path prefixes. The /api
@@ -231,10 +309,22 @@ export function createGate(env) {
             // response, so the post-login / request is already authenticated and
             // the browser never needs the token itself.
             if (method === 'GET' && pathname === '/' && tokenQueryCount(req) > 0) {
-                if (sessionOf(req) !== undefined || isMintReentry(req)) {
+                if (isMintReentry(req)) {
                     rewriteAsLoopback(req);
                     return true;
                 }
+                const tokenedSession = sessionOf(req);
+                if (tokenedSession !== undefined) {
+                    if (needsSessionRefresh(tokenedSession, now())) {
+                        setSessionCookie(res, env.state.secret, now(), isSecureRequest(req));
+                    }
+                    rewriteAsLoopback(req);
+                    if (!carriesLoopbackDshCookie(req, env.loopbackAuthority) && lateMintDue(req)) {
+                        void respondWithLateMint(req, res);
+                        return false;
+                    }
+                    return true;
+                }
                 redirect(res, '/login?next=' + encodeURIComponent(sanitizeNext(pathname) ?? '/'));
                 return false;
             }
@@ -244,6 +334,12 @@ export function createGate(env) {
                     setSessionCookie(res, env.state.secret, now(), isSecureRequest(req));
                 }
                 rewriteAsLoopback(req);
+                if ((method === 'GET' || method === 'HEAD') &&
+                    !carriesLoopbackDshCookie(req, env.loopbackAuthority) &&
+                    lateMintDue(req)) {
+                    void respondWithLateMint(req, res);
+                    return false;
+                }
                 return true;
             }
             if (method === 'GET' || method === 'HEAD') {
@@ -255,10 +351,30 @@ export function createGate(env) {
             }
             return false;
         },
-        allowUpgrade(req) {
+        async allowUpgrade(req) {
             if (sessionOf(req) === undefined)
                 return false;
             rewriteAsLoopback(req);
+            // A WebSocket upgrade carries cookies only through its request headers,
+            // and there is no redirect to repair a missing one — so resolve the DSH
+            // browser cookie onto this very request before the host's own gate reads
+            // it. Without this, a browser that reached the app through a cached page
+            // (no HTTP round-trip, so no late-mint) has every /api/remote.mux upgrade
+            // refused: all remote calls fail, surfacing as errors like the welcome
+            // acknowledgement failing to save.
+            if (!carriesLoopbackDshCookie(req, env.loopbackAuthority)) {
+                const mint = env.mintDshCookie;
+                const cookie = mint === undefined ? undefined : await mint().catch(() => undefined);
+                if (cookie !== undefined) {
+                    // Same shared throttle as the other mint sites (see respondWithLateMint).
+                    lastMintAt = now();
+                    const pair = cookie.split(';')[0]?.trim();
+                    if (pair !== undefined && pair.length > 0) {
+                        req.headers.cookie =
+                            req.headers.cookie === undefined ? pair : req.headers.cookie + '; ' + pair;
+                    }
+                }
+            }
             return true;
         },
         async passed(req, res) {
@@ -353,7 +469,7 @@ export function handleLogout(req, res, env) {
     clearCookie(res, isSecureRequest(req));
     redirect(res, '/login?loggedOut=1');
 }
-// ── GET /api/web-auth/status — settings-card state ─────────────────────────
+// ── GET /api/web-auth/status — settings page state ─────────────────────────
 export function handleStatus(req, res, env) {
     const body = { configured: env.state.readHash() !== undefined };
     const current = env.listen?.current();

package/lib/index.d.ts

@@ -16,12 +16,47 @@ export interface WebAuthConfig {
      */
     unlockRemoteSettings: boolean;
 }
-/** Schema resolving the composition config (cordis Standard-Schema path). */
-export declare const Config: z<WebAuthConfig>;
+/**
+ * One `volatile()` config field as the loader hands it to `apply()`: a live
+ * handle, not the value it currently holds. Spelled structurally rather than as
+ * cosmokit's `Volatile<T>` — cosmokit is a transitive dependency here, and
+ * importing it would put a second cosmokit/schemastery pair into the emitted
+ * declaration.
+ */
+export interface LiveSettingsField<T> {
+    get(): T;
+}
+/** Hand-written entry config (profile patch / test fixture): the field is optional. */
+export interface WebAuthConfigInput {
+    unlockRemoteSettings?: boolean | null;
+}
+/** The resolved entry config `apply()` receives: the field is a live handle. */
+export interface ResolvedWebAuthConfig {
+    unlockRemoteSettings: LiveSettingsField<boolean>;
+}
+/**
+ * Composition config schema (cordis Standard-Schema path).
+ *
+ * `.volatile()` is REQUIRED here, not cosmetic: dsh >= 0.1.7 derives the
+ * plugin's settings page from this schema, and `dsh-settings` SKIPS an entry
+ * whose schema declares no volatile field (`volatileForm(schema)` is undefined)
+ * while refusing every write to a non-volatile path — so without it this
+ * plugin's page disappears from Settings entirely, whichever page renders it.
+ *
+ * The schema is annotated through the package's own default export with locally
+ * declared type arguments: schemastery >= 3.18.3 carries a third `Mode` type
+ * parameter, so a `volatile()` field's OUTPUT type is `Volatile<T>` and the
+ * old `z<WebAuthConfig>` annotation no longer compiles; naming it here also
+ * keeps the declaration build portable (TS2742 otherwise).
+ */
+export type WebAuthConfigSchema = z<WebAuthConfigInput, ResolvedWebAuthConfig>;
+/** Resolved schema for the loader and the settings plane. */
+export declare const Config: WebAuthConfigSchema;
 /**
  * Mount the auth gate and its routes.
  * @param ctx - plugin context carrying the webServer service (listening).
  * @param config - validated composition config (Config schema defaults when
- *   the patch row spells none).
+ *   the patch row spells none); `unlockRemoteSettings` may arrive as a live
+ *   volatile handle and is unwrapped below.
  */
-export declare function apply(ctx: PluginContext, config: WebAuthConfig): void;
+export declare function apply(ctx: PluginContext, config: WebAuthConfig | ResolvedWebAuthConfig): void;

package/lib/index.js

@@ -4,7 +4,7 @@
  * Host half: wraps the webserver's HTTP/upgrade listeners so every request
  * (routes, static fallback, WebSocket upgrades) must carry a valid session
  * cookie, serves the /login page (including first-password setup), /logout,
- * and the JSON change-password API used by the settings card (client half).
+ * and the JSON change-password API used by the settings page (client half).
  *
  * State lives under $DSH_HOME/web-auth/ (password.hash, secret) — see
  * state.ts. Until a password is configured the gate is OPEN and a boot
@@ -31,17 +31,37 @@ import z from '@deepseek-ai/schemastery';
 export const name = 'web-auth';
 /** Services required before the gate can be installed. */
 export const inject = ['webServer'];
-/** Schema resolving the composition config (cordis Standard-Schema path). */
+/** Resolved schema for the loader and the settings plane. */
 export const Config = z.object({
-    unlockRemoteSettings: z.boolean().default(false)
+    unlockRemoteSettings: z.boolean().default(false).volatile()
 });
+/**
+ * Read a config field that may be a plain value or a live (`.volatile()`) node.
+ *
+ * The loader resolves a volatile field to a cosmokit cell (`{ get() }`), which
+ * is an object and therefore always truthy — reading it directly would turn the
+ * opt-in flag on everywhere. Hand-written configs (patch fixtures, tests) pass
+ * plain values, so both shapes are accepted here.
+ */
+function liveValue(node, fallback) {
+    if (node === undefined || node === null)
+        return fallback;
+    const getter = node.get;
+    if (typeof getter === 'function') {
+        const value = getter.call(node);
+        return value === undefined ? fallback : value;
+    }
+    return node;
+}
 /**
  * Mount the auth gate and its routes.
  * @param ctx - plugin context carrying the webServer service (listening).
  * @param config - validated composition config (Config schema defaults when
- *   the patch row spells none).
+ *   the patch row spells none); `unlockRemoteSettings` may arrive as a live
+ *   volatile handle and is unwrapped below.
  */
 export function apply(ctx, config) {
+    const unlockRemoteSettings = liveValue(config.unlockRemoteSettings, false);
     const dshHome = resolveDshHome();
     const state = {
         secret: readSecret(dshHome),
@@ -86,10 +106,10 @@ export function apply(ctx, config) {
         // away; failures are logged, never thrown — the client was confirmed.
         listen: buildListenController(ctx)
     };
-    // The plugin's own Settings Card (设置 → 插件配置 → web-auth) rides the
-    // `web-auth` settings namespace: registering it makes the tab dispatch the
-    // card, and committed listenHost changes are applied here. Attaches only
-    // when a settings service exists (CLI/headless profiles skip it).
+    // The plugin's own settings page (设置 → 侧栏「访问认证」) rides the
+    // `web-auth` settings namespace: binding the namespace is how the page reads
+    // and writes it, and committed listenHost changes are applied here. Attaches
+    // only when a settings service exists (CLI/headless profiles skip it).
     installWebAuthSettings(ctx, env.listen);
     if (state.readHash() === undefined) {
         // console.error, not ctx.logger.warn: the cordis default logger level
@@ -116,7 +136,7 @@ export function apply(ctx, config) {
     // ── remote settings unlock (opt-in): inject ownsHost into the boot page ───
     // A config-only patch change restarts this fiber (cordis update →
     // dispose + re-apply), so the tap flips live with the composition.
-    if (config.unlockRemoteSettings) {
+    if (unlockRemoteSettings) {
         ctx.effect(() => ctx.webServer.tapIndex(injectOwnsHost), 'web-auth: remote settings unlock tap');
     }
     // ── routes (exact table; /api/web-auth/password wins over the /api prefix) ─

package/lib/settings.d.ts

@@ -1,10 +1,10 @@
 /**
  * dsh-web-auth — the `web-auth` settings namespace.
  *
- * The namespace exists so the plugin's browser half can register its own
- * Settings Card: the settings section ("插件配置" tab) dispatches
- * `settings.plugin.item` for every namespace the Host serves, keyed by the
- * namespace string, and the client registers its card under the same key.
+ * The namespace exists so the plugin's browser half can read and write its
+ * own settings page: the page registers on the `settings.section` slot (the
+ * 「访问认证」 entry in the settings sidebar) and binds this namespace through
+ * the client settings scope, which is the only write path to `listenHost`.
  * The namespace carries the one genuine configuration value the plugin owns:
  * the web server's bind host (`listenHost`). The password is deliberately
  * NOT here — it is a secret stored hashed under `$DSH_HOME/web-auth/` and

package/lib/settings.js

@@ -1,10 +1,10 @@
 /**
  * dsh-web-auth — the `web-auth` settings namespace.
  *
- * The namespace exists so the plugin's browser half can register its own
- * Settings Card: the settings section ("插件配置" tab) dispatches
- * `settings.plugin.item` for every namespace the Host serves, keyed by the
- * namespace string, and the client registers its card under the same key.
+ * The namespace exists so the plugin's browser half can read and write its
+ * own settings page: the page registers on the `settings.section` slot (the
+ * 「访问认证」 entry in the settings sidebar) and binds this namespace through
+ * the client settings scope, which is the only write path to `listenHost`.
  * The namespace carries the one genuine configuration value the plugin owns:
  * the web server's bind host (`listenHost`). The password is deliberately
  * NOT here — it is a secret stored hashed under `$DSH_HOME/web-auth/` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonlan/dsh-web-auth",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "DSH web plugin: password-gate authentication (login page + HttpOnly signed cookie) for exposing dsh web behind a reverse proxy",
   "type": "module",
   "license": "MIT",
@@ -59,21 +59,21 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
-    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "dependencies": {
     "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
-    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.4",
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "esbuild": "^0.24.0",