@fonlan/dsh-web-auth 0.1.4 → 0.1.7

package/README.md

@@ -11,6 +11,8 @@
 - **防爆破**：登录与改密接口按客户端 IP 限速（连续 5 次失败锁 1 分钟起，指数退避至 30 分钟；15 分钟内累计）
 - **反代友好**：Cookie `Secure` 自动跟随 `x-forwarded-proto`；限速信任回环对端的 `X-Forwarded-For`
 - **监听地址切换**：设置卡片可一键把 dsh 的监听地址在 `127.0.0.1`（仅本机）与 `0.0.0.0`（所有网卡 / 局域网可访问）之间切换，热生效、无需重启进程（写入 `web-auth` settings 命名空间 → host 半区应用 patch → HMR 重绑 webserver）
+- **远程设置解锁（可选）**：`unlockRemoteSettings` 组合配置在启动页注入 `__DSH_TRANSPORT__.ownsHost` 标志，让反代域名下的设置面（模型页、插件配置、常规设置等）完整可用，默认关闭（见下文安全权衡）
+- **启动令牌收口**：未登录浏览器带旧 `?token=` 链接访问一律重定向回登录页，只有插件自身的服务端 mint 走回环放行通道——既不需要手工引导，也不会再撞上 DSH 的 `401` 死页面（`0.1.7` 起）
 - 密码以 **scrypt 加盐哈希**存储（`$DSH_HOME/web-auth/password.hash`，0600），永不回显、不落明文配置
 
 ## 安装
@@ -42,7 +44,11 @@ dsh plugin --profile web update @fonlan/dsh-web-auth
 |---|---|
 | 未登录访问页面（GET/HEAD） | `302` → `/login?next=原路径`，登录后跳回 |
 | 未登录访问 API（POST 等） | `401` JSON |
+| DSH 启动令牌交换（`GET /?token=…`） | 仅**插件服务端的 mint 重入**（直连回环对端 + 内部标记头）或**已持有插件会话**的请求放行并改写为回环来源转发：DSH 自行校验令牌、签发自己的 `dsh-auth` cookie（`303` → 干净 `/`）；令牌无效则收到 DSH 自带的 `401` |
+| 浏览器直接打开打印的令牌 URL（未登录） | `302` → `/login?next=/`，**丢弃 `token` 参数**：令牌每次启动重新生成，旧书签/旧链接本就无效，放行只会把用户丢到 DSH 的 `401` 页面；登录后服务端 mint 会自动补发有效的 `dsh-auth` cookie |
+| DSH 会话 cookie 自动签发 | 插件在放行响应上**服务端代理 DSH 的令牌交换**（走本机回环 `/?token=`），把 `dsh-auth` Set-Cookie 随响应转发给浏览器——新浏览器无需再手工打开打印的 token URL；每分钟最多一次（结果会持续续期 DSH 的 30 天 cookie） |
 | 反代域名下已登录访问任意路径（含 `/api`、插件前缀） | 改写为回环来源放行，网关特权方法与插件围栏不再 403 |
+| 反代域名下的设置页（模型页等） | 默认报 `settings are unavailable in this browser`——dsh 客户端按页面 hostname 判定"非本机浏览器"，设置镜像保持进程本地。开启 `unlockRemoteSettings` 后启动页注入 `ownsHost`，设置面完整可用（读写仍过密码门 + 回环围栏） |
 | 跨站请求（即使带 Cookie） | 仍被围栏 `403` 拒绝 |
 | 未登录 WebSocket 升级 | 握手直接 `401` 拒绝 |
 | 登录失败 | 跳回登录页显示「密码错误」（统一文案） |
@@ -52,6 +58,8 @@ dsh plugin --profile web update @fonlan/dsh-web-auth
 | 切换监听地址（设置卡片） | 校验取值（仅 `127.0.0.1` / `0.0.0.0`）→ 写入 `web-auth` settings 命名空间（revision 设栅）→ host 半区应用 patch（profile 优先，home 兜底）→ HMR 热重载 webserver 重新绑定；**WebSocket 短暂断连后自动重连** |
 | `/logout` | 清除 Cookie，跳转登录页 |
 
+> **无需再处理 DSH 自己的启动令牌**：DSH 的浏览器会话认证（`dsh web` 启动时打印的 `http://127.0.0.1:3080/?token=…`）用 cookie 绑定 Host。插件会把所有已认证请求的 Host 改写为回环地址，而 DSH 的 cookie 必须与「DSH 看到的 Host」一致——`0.1.5` 起插件会在登录/会话期间**自动在服务端完成 DSH 令牌交换**并把 `dsh-auth` cookie 转交给浏览器（含持续续期），所以外部设备、新浏览器都不需要再手工访问带 token 的 URL。`0.1.7` 起这条路径进一步收紧：未登录浏览器带 `token` 访问会被重定向到 `/login` 并丢弃该参数（旧令牌在 dsh 重启后即失效，放行只会展示 DSH 自己的 `401` 页面），登录本身就已经完成 mint，不再需要任何手工引导步骤。
+
 ### 切换监听地址
 
 dsh 默认只监听 `127.0.0.1`。在 **设置 → 插件 → 插件配置 → 访问认证** 卡片底部可以把它切换为 `0.0.0.0`（所有网卡，局域网可访问），或切回仅本机——无需重启 dsh 进程：
@@ -63,6 +71,22 @@ dsh 默认只监听 `127.0.0.1`。在 **设置 → 插件 → 插件配置 →
 
 > 该能力依赖 webserver 行位于 profile/home patch 层（默认安装即如此）。若你的 webserver 配置来自自定义 `--patch` overlay，请直接编辑 overlay 文件。
 
+### 远程设置解锁（`unlockRemoteSettings`，默认关闭）
+
+**现象**：通过域名反代访问 dsh 时，设置 → 模型页报「加载提供方目录失败: settings are unavailable in this browser」，常规设置、插件配置等设置面同样不可用。这不是故障，是 dsh 的有意设计：设置文档（含 provider 凭据引用等敏感配置）只对"本机浏览器"开放——客户端在页面加载时按 `location.hostname` 判定是否回环（`localhost` / `127.x`），反代域名永远不算，设置镜像因此保持进程本地、根本不发起读取。注意这与服务端无关：本插件已把已认证请求改写为回环来源，`/api` 通道完全正常，只有客户端这道门在拦。
+
+**开启**：在 profile 的 `cordis.patch.yml`（`~/.dsh/profiles/<profile>/cordis.patch.yml`）加一条 config 覆盖：
+
+```yaml
+- id: web-auth
+  config:
+    unlockRemoteSettings: true
+```
+
+HMR 会监听到 patch 变化并热重载 web-auth 行（无需重启进程）。生效后，域名下已登录页面的启动 HTML 会携带一段内联脚本，设置 `window.__DSH_TRANSPORT__.ownsHost = true`——dsh 客户端把它读作"该页面由宿主直接提供"，设置镜像随之正常加载。只在成功渲染的 index 响应上注入（未登录请求在闸门处就被 302/401，根本到不了渲染）；已存在的 `__DSH_TRANSPORT__` 载体只会合并、不会被覆盖。不需要时删掉该配置即回退（同样热生效）。
+
+**安全权衡（请务必理解后再开启）**：`ownsHost` 是 dsh 画的"设置仅本机可改"边界；开启等于把这道边界改由本插件的密码门承担——**每个通过密码认证的浏览器**都能读写 host 设置文档（包括 provider API key 的引用、监听地址等）。若域名暴露在公网，请确保：强密码、反代全程 HTTPS、最好叠加反代层限流/IP 白名单。只在本机/内网使用或设置面不受影响时，保持默认关闭即可。
+
 ## 安全模型与风险（请务必阅读）
 
 - **认证是访问控制，不是安全边界**。dsh 的 agent 拥有 bash 执行能力（远程代码执行级别），即使有密码保护，也不要把它当成不可攻破的堡垒：密码强度、反代层 WAF/限流、IP 白名单仍然值得做。
@@ -77,7 +101,7 @@ dsh 默认只监听 `127.0.0.1`。在 **设置 → 插件 → 插件配置 →
 pnpm install
 npm run build      # host: tsc → lib/；client: esbuild → lib/client.js（ModuleLoader 格式）
 npm run typecheck
-npm run test       # 32 项单元 + 集成测试（node:test，真实 HTTP/WS 全流程）
+npm run test       # 单元 + 集成测试（node:test，真实 HTTP/WS 全流程）
 ```
 
 仓库结构：
@@ -86,6 +110,7 @@ npm run test       # 32 项单元 + 集成测试（node:test，真实 HTTP/WS
 - `src/gate.ts` — 把认证闸门包到 node:http 服务器的 request/upgrade 监听器外层
 - `src/handlers.ts` — 登录页/登录/登出/改密/状态/监听切换 路由处理
 - `src/profile-patch.ts` — 监听地址切换：webserver 行的 patch 层文本改写（保留注释与 `!!js` 表达式）
+- `src/remote-unlock.ts` — 远程设置解锁：`unlockRemoteSettings` 开启时经 `webServer.tapIndex` 注入 `ownsHost` 启动页脚本
 - `src/settings.ts` — `web-auth` settings 命名空间注册 + listenHost 变更应用（卡片的分发键与数据源）
 - `src/index.ts` — cordis 插件装配（host 半区）
 - `src/client/index.tsx` — 设置卡片（浏览器半区，`settings.plugin.item` 插槽，keyed by `web-auth` 命名空间）

package/lib/context-types.d.ts

@@ -9,8 +9,12 @@ import type { IncomingMessage, Server, ServerResponse } from 'node:http';
 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 bound listening port (the OS-assigned value when config.port is 0).
+     * Undefined until the socket is bound, which happens concurrently with
+     * plugin loading — read it per request, never capture it at apply time.
+     */
+    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. */
@@ -19,6 +23,12 @@ export interface WebServerService {
         path: string;
         handler: (req: IncomingMessage, res: ServerResponse) => void;
     }): () => void;
+    /**
+     * Register a raw-HTML index transform over the boot page render (applied
+     * after the structured injection rows, in registration order); returns
+     * the disposer removing it.
+     */
+    tapIndex(transform: (html: string) => string): () => void;
 }
 /** The plugin context members this plugin consumes. */
 export interface PluginContext {

package/lib/gate.d.ts

@@ -18,8 +18,13 @@ 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;
+    /**
+     * Hook after an allowed request (cookie refresh / DSH cookie mint).
+     * May be async: the gate awaits it BEFORE forwarding, so response
+     * headers it appends reach the client; it must never throw, and a
+     * 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;
 }

package/lib/gate.js

@@ -22,10 +22,16 @@ export function installGate(server, handlers) {
     const upgradeListeners = server.listeners('upgrade');
     server.removeAllListeners('request');
     server.removeAllListeners('upgrade');
-    server.on('request', (req, res) => {
+    server.on('request', async (req, res) => {
         if (!handlers.allow(req, res))
             return;
-        handlers.passed?.(req, res);
+        try {
+            await handlers.passed?.(req, res);
+        }
+        catch {
+            // A failing passed() hook must never block the downstream dispatch
+            // (response headers it could not attach are a soft failure).
+        }
         for (const listener of requestListeners) {
             ;
             listener(req, res);

package/lib/handlers.d.ts

@@ -21,6 +21,14 @@ export interface HandlerEnv {
     state: AuthState;
     limiter: RateLimiter;
     now?: () => number;
+    /**
+     * Mint DSH's own browser-session cookie (the one dsh-client-connection
+     * validates against the process launch token) server-side, returning the
+     * raw Set-Cookie value to relay to the user's browser, or undefined when
+     * the exchange cannot run (no connection service, unreachable loopback,
+     * fetch failure). See buildDshCookieMinter in index.ts.
+     */
+    mintDshCookie?(): Promise<string | undefined>;
     /**
      * Loopback authority ("127.0.0.1:<port>") used to rewrite the Host/Origin
      * of AUTHENTICATED requests (any path prefix).
@@ -87,7 +95,16 @@ export declare function setSessionCookie(res: ServerResponse, secret: Buffer, no
 export interface Gate {
     allow(req: IncomingMessage, res: ServerResponse): boolean;
     allowUpgrade(req: IncomingMessage): boolean;
+    passed?(req: IncomingMessage, res: ServerResponse): void | Promise<void>;
 }
+/** Number of `token` query parameters in the request URL. */
+export declare function tokenQueryCount(req: IncomingMessage): number;
+/**
+ * Marker header the server-side mint (buildDshCookieMinter) stamps on its
+ * loopback re-entry, letting the gate distinguish it from a browser that
+ * merely carries a (possibly stale) printed `?token=` URL.
+ */
+export declare const MINT_REENTRY_HEADER = "x-dsh-web-auth-mint";
 /**
  * Build the gate used to wrap the HTTP server listeners. Whitelisted paths
  * (login page/form, logout) pass through; everything else requires a valid

package/lib/handlers.js

@@ -97,13 +97,44 @@ export function setSessionCookie(res, secret, now, secure) {
     ];
     if (secure)
         parts.push('Secure');
-    res.setHeader('set-cookie', parts.join('; '));
+    // appendHeader (not setHeader): the gate may have already attached the
+    // DSH cookie to this response — a setHeader would silently drop it.
+    res.appendHeader('set-cookie', parts.join('; '));
 }
 function clearCookie(res, secure) {
     const parts = [COOKIE_NAME + '=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0'];
     if (secure)
         parts.push('Secure');
-    res.setHeader('set-cookie', parts.join('; '));
+    res.appendHeader('set-cookie', parts.join('; '));
+}
+/** Minimum interval between server-side DSH cookie mints (debounce). */
+const DSH_MINT_DEBOUNCE_MS = 1000;
+/** Number of `token` query parameters in the request URL. */
+export function tokenQueryCount(req) {
+    try {
+        return new URL(req.url ?? '/', 'http://x').searchParams.getAll('token').length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Marker header the server-side mint (buildDshCookieMinter) stamps on its
+ * loopback re-entry, letting the gate distinguish it from a browser that
+ * merely carries a (possibly stale) printed `?token=` URL.
+ */
+export const MINT_REENTRY_HEADER = 'x-dsh-web-auth-mint';
+/**
+ * Whether this tokened request is the server-side mint's own loopback
+ * re-entry: the marker header AND a direct loopback TCP peer (not
+ * clientIp's XFF-aware view — a proxied remote client must not pass even
+ * if it forges the header, and the mint never traverses the proxy).
+ */
+function isMintReentry(req) {
+    if (req.headers[MINT_REENTRY_HEADER] !== '1')
+        return false;
+    const direct = req.socket.remoteAddress ?? '';
+    return direct === '127.0.0.1' || direct === '::1' || direct === '::ffff:127.0.0.1';
 }
 /**
  * Build the gate used to wrap the HTTP server listeners. Whitelisted paths
@@ -114,6 +145,8 @@ function clearCookie(res, secure) {
  */
 export function createGate(env) {
     const now = env.now ?? Date.now;
+    /** Last server-side DSH cookie mint attempt (epoch ms). */
+    let lastMintAt = 0;
     const whitelisted = (method, pathname) => {
         if (pathname === '/login')
             return method === 'GET' || method === 'HEAD' || method === 'POST';
@@ -122,6 +155,32 @@ export function createGate(env) {
         return false;
     };
     const sessionOf = (req) => verifySession(cookieValue(req.headers.cookie, COOKIE_NAME), env.state.secret, now());
+    /**
+     * Mint DSH's browser-session cookie and attach it to the response when due
+     * (debounced globally, ~1/s — the mint is one cheap loopback exchange).
+     * Runs for ANY allowed request, authenticated or not: the minted DSH
+     * cookie alone never opens the gate (every other path still requires the
+     * plugin session), and minting early (login page, setup redirect) means a
+     * fresh browser carries both cookies by the time it first reaches DSH.
+     */
+    const maybeMintDshCookie = async (res) => {
+        const mint = env.mintDshCookie;
+        if (mint === undefined)
+            return;
+        const t = now();
+        if (t - lastMintAt < DSH_MINT_DEBOUNCE_MS)
+            return;
+        lastMintAt = t;
+        try {
+            const cookie = await mint();
+            if (cookie !== undefined && !res.headersSent) {
+                res.appendHeader('set-cookie', cookie);
+            }
+        }
+        catch (error) {
+            console.error('[dsh-web-auth] DSH cookie mint failed:', error);
+        }
+    };
     /**
      * Present AUTHENTICATED traffic as loopback to every downstream
      * browser-trust fence, without tracking plugin path prefixes. The /api
@@ -155,6 +214,30 @@ export function createGate(env) {
             const method = req.method ?? 'GET';
             if (whitelisted(method, pathname))
                 return true;
+            // DSH launch-token exchange: GET / with a `token` query param is DSH's
+            // own bootstrap surface (the URL printed at startup). DSH validates the
+            // token itself and either mints its browser-session cookie (303 → clean
+            // /) or answers its own 401. Forward WITHOUT a plugin session only for
+            // the server-side mint's loopback re-entry (marker header + direct
+            // loopback peer, see buildDshCookieMinter) or when the browser already
+            // holds a plugin session — the minted cookie alone cannot open the gate
+            // (every other path still demands the session) — and always present the
+            // forwarded request as loopback, so the cookie DSH mints binds to the
+            // same authority every authenticated request uses after the rewrite.
+            // Any OTHER tokened request is a remote browser with a launch token that
+            // is stale the moment dsh restarts (the token is per-boot); letting it
+            // through renders DSH's raw 401 dead-end page. Redirect to /login
+            // instead: the server-side mint relays a fresh DSH cookie on the login
+            // 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)) {
+                    rewriteAsLoopback(req);
+                    return true;
+                }
+                redirect(res, '/login?next=' + encodeURIComponent(sanitizeNext(pathname) ?? '/'));
+                return false;
+            }
             const session = sessionOf(req);
             if (session !== undefined) {
                 if (needsSessionRefresh(session, now())) {
@@ -177,6 +260,9 @@ export function createGate(env) {
                 return false;
             rewriteAsLoopback(req);
             return true;
+        },
+        async passed(req, res) {
+            await maybeMintDshCookie(res);
         }
     };
 }

package/lib/index.d.ts

@@ -1,10 +1,27 @@
 import type { PluginContext } from './context-types.ts';
+import z from '@deepseek-ai/schemastery';
 /** Stable Cordis plugin name. */
 export declare const name = "web-auth";
 /** Services required before the gate can be installed. */
 export declare const inject: string[];
+/** The plugin's composition config (patch-layer `config:` overrides). */
+export interface WebAuthConfig {
+    /**
+     * Inject the `__DSH_TRANSPORT__.ownsHost` flag into the served boot page
+     * so pages reached through a reverse proxy/domain load the host settings
+     * document and the settings plane works remotely. Default off: the flag
+     * is a dsh security boundary, and turning it over lets every
+     * session-authenticated browser read and write the host settings document
+     * from wherever the domain is reachable. See remote-unlock.ts.
+     */
+    unlockRemoteSettings: boolean;
+}
+/** Schema resolving the composition config (cordis Standard-Schema path). */
+export declare const Config: z<WebAuthConfig>;
 /**
  * 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).
  */
-export declare function apply(ctx: PluginContext): void;
+export declare function apply(ctx: PluginContext, config: WebAuthConfig): void;

package/lib/index.js

@@ -10,25 +10,38 @@
  * state.ts. Until a password is configured the gate is OPEN and a boot
  * warning is logged; the login page then offers first-password setup.
  *
+ * Opt-in composition config (`unlockRemoteSettings`, Config schema below)
+ * injects the `__DSH_TRANSPORT__.ownsHost` flag into the served boot page
+ * (webServer.tapIndex) so pages reached through a reverse proxy/domain can
+ * load the host settings document — see remote-unlock.ts.
+ *
  * Install (bundle layer):  dsh plugin --profile web add ./dsh-web-auth
  */
 import { installGate } from "./gate.js";
 import { RateLimiter } from "./auth-core.js";
 import { readSecret, readPasswordHash, resolveDshHome, rotateSecret, writePasswordHash } from "./state.js";
-import { createGate, handleChangePassword, handleListenChange, handleLoginPage, handleLoginPost, handleLogout, handleStatus } from "./handlers.js";
+import { MINT_REENTRY_HEADER, createGate, handleChangePassword, handleListenChange, handleLoginPage, handleLoginPost, handleLogout, handleStatus } from "./handlers.js";
 import { LISTEN_APPLY_DELAY_MS, prepareWebserverHostPatch, resolveListenPatchPath, writeWebserverHostPatch } from "./profile-patch.js";
 import { installWebAuthSettings } from "./settings.js";
+import { injectOwnsHost } from "./remote-unlock.js";
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
 /** Stable Cordis plugin name. */
 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). */
+export const Config = z.object({
+    unlockRemoteSettings: z.boolean().default(false)
+});
 /**
  * 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).
  */
-export function apply(ctx) {
+export function apply(ctx, config) {
     const dshHome = resolveDshHome();
     const state = {
         secret: readSecret(dshHome),
@@ -43,10 +56,26 @@ export function apply(ctx) {
     const env = {
         state,
         limiter: new RateLimiter(),
+        // Server-side mint of DSH's own browser-session cookie: relayed to the
+        // browser on allowed responses so DSH's launch-token auth no longer
+        // requires opening the printed ?token= URL per browser. Bound lazily —
+        // a headless/CLI profile without the connection service simply never
+        // mints (each request then fails DSH auth silently, as before).
+        mintDshCookie: buildDshCookieMinter(ctx),
         // Authenticated /api requests are presented to the gateway's trust fence
         // as loopback, so the privileged-method pinning (settings.*, credentials.*,
         // discoverModels, …) passes through the reverse proxy. See handlers.ts.
-        loopbackAuthority: '127.0.0.1:' + String(ctx.webServer.port),
+        // Read per request, never captured: `webServer.port` is the *bound* port
+        // and plugins load concurrently with the webserver's bind, so it is still
+        // unassigned while this plugin applies (evaluating it here would freeze
+        // the authority into an unparseable "127.0.0.1:undefined" that every
+        // downstream fence then rejects). No port yet means no rewrite — the
+        // request's own Host is already a valid authority, which is also how a
+        // profile whose webserver is not listening at all stays consistent.
+        get loopbackAuthority() {
+            const port = ctx.webServer.port;
+            return port === undefined ? undefined : '127.0.0.1:' + String(port);
+        },
         // Live listen-host switching: the webserver's bind host is composition
         // config owned by the profile patch layer (or the home patch when it
         // spells the webserver row), so the change is written there and the HMR
@@ -84,6 +113,12 @@ export function apply(ctx) {
     ctx.effect(() => {
         return () => disposeGate?.();
     }, 'web-auth: auth gate');
+    // ── 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) {
+        ctx.effect(() => ctx.webServer.tapIndex(injectOwnsHost), 'web-auth: remote settings unlock tap');
+    }
     // ── routes (exact table; /api/web-auth/password wins over the /api prefix) ─
     const routes = [
         {
@@ -131,6 +166,53 @@ export function apply(ctx) {
         ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: route.path, handler: route.handler }), `web-auth: ${route.path} route`);
     }
 }
+/**
+ * Server-side DSH browser-session cookie mint.
+ *
+ * dsh-client-connection exposes the process launch-token URL through its
+ * `connection` service (authenticatedUrl — the same call dsh-web-app uses to
+ * print the startup URL). This minter fetches that URL over the server's own
+ * loopback: the gate's token-exchange branch forwards it (still rewriting
+ * Host to loopback), DSH validates the token and answers a 303 with the
+ * signed `dsh-auth-<sha256(loopback)>` cookie — exactly the cookie every
+ * authenticated request needs after the Host rewrite. The Set-Cookie value is
+ * returned so the gate can relay it to the user's browser on ordinary
+ * responses, meaning new browsers/endpoints no longer need the printed token
+ * (and DSH's 30-day cookie is refreshed continuously).
+ *
+ * Returns undefined when the exchange cannot run (no connection service,
+ * non-loopback-only bind, fetch failure) — the caller degrades to the old
+ * behavior where the cookie must arrive via the printed token URL.
+ */
+function buildDshCookieMinter(ctx) {
+    let connection;
+    ctx.inject(['connection'], (cctx) => {
+        connection = cctx.connection;
+    });
+    return async () => {
+        if (connection === undefined)
+            return undefined;
+        const host = ctx.webServer.host === '0.0.0.0' || ctx.webServer.host === '::' ? '127.0.0.1' : ctx.webServer.host;
+        try {
+            const url = connection.authenticatedUrl(`http://${host}:${String(ctx.webServer.port)}`);
+            // The marker header is what the gate's token branch keys on to forward
+            // this re-entry without a plugin session; without it the loopback
+            // tokened GET would be redirected to /login like any stale bookmark.
+            const response = await fetch(url, { redirect: 'manual', headers: { [MINT_REENTRY_HEADER]: '1' } });
+            const cookies = response.headers.getSetCookie?.() ?? [];
+            const all = cookies.length > 0
+                ? cookies
+                : (response.headers.get('set-cookie') ?? '').length > 0
+                    ? [response.headers.get('set-cookie') ?? '']
+                    : [];
+            return all.find((cookie) => cookie.startsWith('dsh-auth-')) ?? all[0];
+        }
+        catch (error) {
+            console.error('[dsh-web-auth] could not mint DSH browser-session cookie:', error instanceof Error ? error.message : String(error));
+            return undefined;
+        }
+    };
+}
 /**
  * Bind the live listen-host controller to this deployment's patch layer.
  * Resolves which layer owns the webserver row (home outranks the profile),

package/lib/remote-unlock.d.ts

@@ -0,0 +1,58 @@
+/**
+ * dsh-web-auth — remote settings unlock (opt-in composition config).
+ *
+ * dsh decides "is this page the operator's local browser?" on the CLIENT,
+ * once per page load: dsh-client-connection computes `isLoopback` from the
+ * page's location hostname (or the transport's `ownsHost` flag), and the
+ * settings UI keeps its describe mirror process-local unless the page counts
+ * as loopback — every settings surface (models directory, plugin config, …)
+ * then answers "settings are unavailable in this browser". Pages reached
+ * through a reverse proxy/domain can never pass the hostname check, so the
+ * settings plane stays unreachable there EVEN THOUGH this plugin already
+ * presents every session-authenticated request to the server-side fences as
+ * loopback (the Host rewrite in handlers.ts): the two trust decisions are
+ * read on opposite sides of the wire.
+ *
+ * This module closes that gap with the one server-side signal the client
+ * honors: the webserver renders the boot page through a tap chain
+ * (`webServer.tapIndex`, the raw-HTML escape hatch DSH exposes for exactly
+ * this), and the client entry reads `globalThis.__DSH_TRANSPORT__.ownsHost`
+ * as the "this transport owns the host" flag. A tap that appends a tiny
+ * inline script setting the flag makes a proxied page present as a
+ * host-owned page: the settings mirror loads over the (already
+ * authenticated, already loopback-presented) /api plane and the settings
+ * UI works remotely.
+ *
+ * Deliberate scope:
+ * - Runs ONLY on rendered index responses. Unauthenticated requests are
+ *   answered by the gate (302 /login) or DSH's own index auth before any
+ *   render, so a proxied page receives the script only after passing both
+ *   the plugin session and DSH's browser-session cookie.
+ * - Only ADDS the flag: an existing `__DSH_TRANSPORT__` carrier (fetch /
+ *   openStream / loadBundle on an embedding platform) is merged, never
+ *   replaced.
+ * - Off unless the composition opts in (`unlockRemoteSettings: true`):
+ *   the flag IS the security boundary dsh drew — enabling it lets every
+ *   authenticated browser read and write the host settings document from
+ *   wherever the domain is reachable. The deployment owner makes that
+ *   call, in the patch layer, next to the listen host it extends.
+ */
+/** Marker attribute on the injected script tag (also the idempotency key). */
+export declare const OWNS_HOST_MARKER = "data-dsh-web-auth=\"owns-host\"";
+/**
+ * The injected script: set `ownsHost` on the page transport, creating the
+ * transport object only when the page carries none. A classic (non-module)
+ * inline script — parsed before the deferred module entry executes, which is
+ * where dsh-client-connection reads the flag once.
+ */
+export declare const OWNS_HOST_SCRIPT = "<script data-dsh-web-auth=\"owns-host\">window.__DSH_TRANSPORT__ = window.__DSH_TRANSPORT__ || {}; window.__DSH_TRANSPORT__.ownsHost = true;</script>";
+/**
+ * Append the ownsHost script to a rendered index.html body, before
+ * `</body>` (falling back to the end when the body tag is missing — the
+ * html-to-html contract of `webServer.tapIndex` expects a pure transform).
+ * Idempotent: a body that already carries the marker is returned as-is, so
+ * double registration across an HMR reload can never double-inject.
+ * @param html - the rendered index.html body.
+ * @returns the body with the script in place.
+ */
+export declare function injectOwnsHost(html: string): string;

package/lib/remote-unlock.js

@@ -0,0 +1,65 @@
+/**
+ * dsh-web-auth — remote settings unlock (opt-in composition config).
+ *
+ * dsh decides "is this page the operator's local browser?" on the CLIENT,
+ * once per page load: dsh-client-connection computes `isLoopback` from the
+ * page's location hostname (or the transport's `ownsHost` flag), and the
+ * settings UI keeps its describe mirror process-local unless the page counts
+ * as loopback — every settings surface (models directory, plugin config, …)
+ * then answers "settings are unavailable in this browser". Pages reached
+ * through a reverse proxy/domain can never pass the hostname check, so the
+ * settings plane stays unreachable there EVEN THOUGH this plugin already
+ * presents every session-authenticated request to the server-side fences as
+ * loopback (the Host rewrite in handlers.ts): the two trust decisions are
+ * read on opposite sides of the wire.
+ *
+ * This module closes that gap with the one server-side signal the client
+ * honors: the webserver renders the boot page through a tap chain
+ * (`webServer.tapIndex`, the raw-HTML escape hatch DSH exposes for exactly
+ * this), and the client entry reads `globalThis.__DSH_TRANSPORT__.ownsHost`
+ * as the "this transport owns the host" flag. A tap that appends a tiny
+ * inline script setting the flag makes a proxied page present as a
+ * host-owned page: the settings mirror loads over the (already
+ * authenticated, already loopback-presented) /api plane and the settings
+ * UI works remotely.
+ *
+ * Deliberate scope:
+ * - Runs ONLY on rendered index responses. Unauthenticated requests are
+ *   answered by the gate (302 /login) or DSH's own index auth before any
+ *   render, so a proxied page receives the script only after passing both
+ *   the plugin session and DSH's browser-session cookie.
+ * - Only ADDS the flag: an existing `__DSH_TRANSPORT__` carrier (fetch /
+ *   openStream / loadBundle on an embedding platform) is merged, never
+ *   replaced.
+ * - Off unless the composition opts in (`unlockRemoteSettings: true`):
+ *   the flag IS the security boundary dsh drew — enabling it lets every
+ *   authenticated browser read and write the host settings document from
+ *   wherever the domain is reachable. The deployment owner makes that
+ *   call, in the patch layer, next to the listen host it extends.
+ */
+/** Marker attribute on the injected script tag (also the idempotency key). */
+export const OWNS_HOST_MARKER = 'data-dsh-web-auth="owns-host"';
+/**
+ * The injected script: set `ownsHost` on the page transport, creating the
+ * transport object only when the page carries none. A classic (non-module)
+ * inline script — parsed before the deferred module entry executes, which is
+ * where dsh-client-connection reads the flag once.
+ */
+export const OWNS_HOST_SCRIPT = `<script ${OWNS_HOST_MARKER}>window.__DSH_TRANSPORT__ = window.__DSH_TRANSPORT__ || {}; window.__DSH_TRANSPORT__.ownsHost = true;</script>`;
+/**
+ * Append the ownsHost script to a rendered index.html body, before
+ * `</body>` (falling back to the end when the body tag is missing — the
+ * html-to-html contract of `webServer.tapIndex` expects a pure transform).
+ * Idempotent: a body that already carries the marker is returned as-is, so
+ * double registration across an HMR reload can never double-inject.
+ * @param html - the rendered index.html body.
+ * @returns the body with the script in place.
+ */
+export function injectOwnsHost(html) {
+    if (html.includes(OWNS_HOST_MARKER))
+        return html;
+    const closeBody = /<\/body\b[^>]*>/i.exec(html);
+    if (closeBody === null)
+        return html + OWNS_HOST_SCRIPT;
+    return html.slice(0, closeBody.index) + OWNS_HOST_SCRIPT + html.slice(closeBody.index);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonlan/dsh-web-auth",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "DSH web plugin: password-gate authentication (login page + HttpOnly signed cookie) for exposing dsh web behind a reverse proxy",
   "type": "module",
   "license": "MIT",