@fonlan/dsh-web-auth 0.1.4 → 0.1.5

package/README.md

@@ -42,6 +42,8 @@ dsh plugin --profile web update @fonlan/dsh-web-auth
 |---|---|
 | 未登录访问页面（GET/HEAD） | `302` → `/login?next=原路径`，登录后跳回 |
 | 未登录访问 API（POST 等） | `401` JSON |
+| DSH 启动令牌交换（`GET /?token=…`） | 放行并改写为回环来源转发：DSH 自行校验令牌、签发自己的 `dsh-auth` cookie（`303` → 干净 `/`）；令牌无效则收到 DSH 自带的 `401` |
+| DSH 会话 cookie 自动签发 | 插件在放行响应上**服务端代理 DSH 的令牌交换**（走本机回环 `/?token=`），把 `dsh-auth` Set-Cookie 随响应转发给浏览器——新浏览器无需再手工打开打印的 token URL；每分钟最多一次（结果会持续续期 DSH 的 30 天 cookie） |
 | 反代域名下已登录访问任意路径（含 `/api`、插件前缀） | 改写为回环来源放行，网关特权方法与插件围栏不再 403 |
 | 跨站请求（即使带 Cookie） | 仍被围栏 `403` 拒绝 |
 | 未登录 WebSocket 升级 | 握手直接 `401` 拒绝 |
@@ -52,6 +54,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.5）签发的 cookie 过期后，需要手动以 `https://<域名>/?token=<dsh web 启动打印的令牌>` 打开一次完成引导。
+
 ### 切换监听地址
 
 dsh 默认只监听 `127.0.0.1`。在 **设置 → 插件 → 插件配置 → 访问认证** 卡片底部可以把它切换为 `0.0.0.0`（所有网卡，局域网可访问），或切回仅本机——无需重启 dsh 进程：

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,10 @@ 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;
 /**
  * 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,26 @@ 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;
+    }
 }
 /**
  * Build the gate used to wrap the HTTP server listeners. Whitelisted paths
@@ -114,6 +127,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 +137,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 +196,19 @@ 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. Let it through WITHOUT a plugin session —
+            // the minted cookie alone cannot open the gate (every other path still
+            // demands the session) — but still present it as loopback, so the
+            // cookie DSH mints binds to the same authority every authenticated
+            // request uses after the rewrite. This is also how the server-side
+            // mint (mintDshCookie) re-enters the server.
+            if (method === 'GET' && pathname === '/' && tokenQueryCount(req) > 0) {
+                rewriteAsLoopback(req);
+                return true;
+            }
             const session = sessionOf(req);
             if (session !== undefined) {
                 if (needsSessionRefresh(session, now())) {
@@ -177,6 +231,9 @@ export function createGate(env) {
                 return false;
             rewriteAsLoopback(req);
             return true;
+        },
+        async passed(req, res) {
+            await maybeMintDshCookie(res);
         }
     };
 }

package/lib/index.js

@@ -43,6 +43,12 @@ 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.
@@ -131,6 +137,50 @@ 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)}`);
+            const response = await fetch(url, { redirect: 'manual' });
+            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/package.json

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