@fonlan/dsh-web-auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fonlan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# dsh-web-auth
+
+为 [DSH](https://github.com/deepseek-ai/deepseek-harness) Web GUI 增加**密码访问认证**的插件：所有 HTTP 请求与 WebSocket 升级都必须携带有效会话，未登录一律跳转到登录页。装上它之后，把 dsh 反代到公网（或直接暴露端口）才不至于裸奔。
+
+## 特性
+
+- **登录页 + HttpOnly 签名 Cookie**（HMAC-SHA256，7 天滑动续期），浏览器自动携带，HTTP / WebSocket / SSE / 静态资源全覆盖
+- **首次设置**：未配置密码时，登录页显示「设置访问密码」表单（引导流程，见下文安全说明）
+- **GUI 改密**：设置 → 插件配置 →「访问认证」卡片，需旧密码；改密后**轮换签名密钥，所有已登录会话立即下线**
+- **退出登录**：设置卡片按钮，或访问 `/logout`
+- **防爆破**：登录与改密接口按客户端 IP 限速（连续 5 次失败锁 1 分钟起，指数退避至 30 分钟；15 分钟内累计）
+- **反代友好**：Cookie `Secure` 自动跟随 `x-forwarded-proto`；限速信任回环对端的 `X-Forwarded-For`
+- **监听地址切换**：设置卡片可一键把 dsh 的监听地址在 `127.0.0.1`（仅本机）与 `0.0.0.0`（所有网卡 / 局域网可访问）之间切换，热生效、无需重启进程（写入 patch 层由 HMR 应用，webserver 自动重新绑定）
+- 密码以 **scrypt 加盐哈希**存储（`$DSH_HOME/web-auth/password.hash`，0600），永不回显、不落明文配置
+
+## 安装
+
+```bash
+dsh plugin --profile web add @fonlan/dsh-web-auth
+```
+
+从 npm 安装：`dsh plugin add` 会把包写入 profile 的依赖与 bundle 栈（`cordis.patch.yml` 自动 insert 插件行，host 半区 + 浏览器半区一次挂载）。升级到新版本：
+
+```bash
+dsh plugin --profile web update @fonlan/dsh-web-auth
+```
+
+> 安装后**需要重启 dsh web 进程**才生效（当前会话会短暂断连重连）。
+
+## 激活（首次设置密码）
+
+重启后打开 dsh web，会被重定向到登录页：
+
+1. 未设置过密码时，登录页显示「设置访问密码」——输入 **≥8 位**的新密码并确认
+2. 设置成功后立即签发会话并跳回原页面；此后每次访问都要输密码
+
+改密入口在 **设置 → 插件配置 → 访问认证**（需先登录）。
+
+## 行为细节
+
+| 场景 | 行为 |
+|---|---|
+| 未登录访问页面（GET/HEAD） | `302` → `/login?next=原路径`，登录后跳回 |
+| 未登录访问 API（POST 等） | `401` JSON |
+| 反代域名下已登录访问任意路径（含 `/api`、插件前缀） | 改写为回环来源放行，网关特权方法与插件围栏不再 403 |
+| 跨站请求（即使带 Cookie） | 仍被围栏 `403` 拒绝 |
+| 未登录 WebSocket 升级 | 握手直接 `401` 拒绝 |
+| 登录失败 | 跳回登录页显示「密码错误」（统一文案） |
+| 连续失败 | 按 IP 限速，提示「尝试过于频繁」 |
+| 会话过期 | 跳回登录页；滑动续期：剩余不足 24h 自动刷新 |
+| 修改密码 | 校验旧密码 → 轮换签名密钥 → **全员下线**，跳转登录页 |
+| 切换监听地址（设置卡片） | 校验取值（仅 `127.0.0.1` / `0.0.0.0`）→ 写 patch 层（profile 优先，home 兜底）→ HMR 热重载 webserver 重新绑定；**WebSocket 短暂断连后自动重连** |
+| `/logout` | 清除 Cookie，跳转登录页 |
+
+### 切换监听地址
+
+dsh 默认只监听 `127.0.0.1`。在 **设置 → 插件配置 → 访问认证** 卡片底部可以把它切换为 `0.0.0.0`（所有网卡，局域网可访问），或切回仅本机——无需重启 dsh 进程：
+
+- 切换写入当前部署的 patch 层：profile 的 `cordis.patch.yml`；若 home 层（`$DSH_HOME/cordis.patch.yml`）已声明 webserver 行则写 home 层（home 优先级更高，改在低层会被覆盖）。文件里其余内容（注释、`!!js` 端口表达式）原样保留。
+- dsh 的 HMR 会监听到 patch 文件变化并热重载 webserver 行：**关闭旧监听、按新地址重新绑定**，全程无需重启进程。重启进程后该设置依然生效（它就在 patch 文件里）。
+- 切换瞬间所有连接（包括当前页面与 WebSocket）会断开重连，属正常现象；卡片会轮询状态确认新地址生效。
+- 注意：若你正通过**局域网 IP**（`0.0.0.0` 模式）访问并切回 `127.0.0.1`，切回后只能在本机访问，请改用 `127.0.0.1` 重新打开页面。
+
+> 该能力依赖 webserver 行位于 profile/home patch 层（默认安装即如此）。若你的 webserver 配置来自自定义 `--patch` overlay，请直接编辑 overlay 文件。
+
+## 安全模型与风险（请务必阅读）
+
+- **认证是访问控制，不是安全边界**。dsh 的 agent 拥有 bash 执行能力（远程代码执行级别），即使有密码保护，也不要把它当成不可攻破的堡垒：密码强度、反代层 WAF/限流、IP 白名单仍然值得做。
+- **首密窗口期**：未设置密码时，**任何人**都能访问登录页并抢注密码（设计如此，作为 bootstrap 通道）。启动日志会打印警告；请装好插件后**第一时间设置密码**。生产环境建议先用 `127.0.0.1` + SSH 端口转发完成首密设置，再开放公网。
+- **会话是无状态的**（HMAC 签名），服务端无法单独吊销某一个会话；`/logout` 只清浏览器 Cookie。密码泄露时请**修改密码**——这会轮换密钥并让所有会话失效。
+- 密码哈希与签名密钥存放于 `$DSH_HOME/web-auth/`（默认 `~/.dsh/web-auth/`），权限 0600；删除 `password.hash` 即回到未配置状态（认证关闭）。
+- 限速为**进程内存级**，多实例部署时各自独立，重启清零；如需更强防护请依赖反代层限流。
+
+## 开发
+
+```bash
+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 全流程）
+```
+
+仓库结构：
+
+- `src/auth-core.ts` — 纯逻辑：scrypt 哈希、Cookie 签名/校验、限速器、`next` 校验
+- `src/gate.ts` — 把认证闸门包到 node:http 服务器的 request/upgrade 监听器外层
+- `src/handlers.ts` — 登录页/登录/登出/改密/状态/监听切换 路由处理
+- `src/profile-patch.ts` — 监听地址切换：webserver 行的 patch 层文本改写（保留注释与 `!!js` 表达式）
+- `src/index.ts` — cordis 插件装配（host 半区）
+- `src/client/index.tsx` — 设置卡片（浏览器半区，settings.section 插槽）
+- `cordis.patch.yml` — bundle 补丁层（insert 插件行）
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,23 @@
+# dsh-web-auth bundle patch
+#
+# This file is the `dsh.bundle.patch` layer of this package: installing it
+# into a profile (
+#
+#   dsh plugin --profile <name> add ./dsh-web-auth
+#
+# ) appends the package to `dsh.profile.bundles`, and the profile boot merges
+# this patch — a single `insert` of the plugin row — like any bundle layer.
+# The row's `inject` makes the Loader start the webServer service first, so
+# 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 settings section card) automatically.
+#
+# There is intentionally NO password here: passwords are maintained through
+# the GUI (login page first setup / settings card 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:
+    - id: web-auth
+      name: '@fonlan/dsh-web-auth'
+      inject: [webServer]

package/lib/auth-core.d.ts

@@ -0,0 +1,78 @@
+/** Cookie name carrying the signed session. */
+export declare const COOKIE_NAME = "dsh_web_auth";
+/** Session lifetime: 7 days (sliding — refreshed on activity). */
+export declare const SESSION_TTL_SECONDS: number;
+/** Refresh the cookie only when less than this much lifetime remains. */
+export declare const SESSION_REFRESH_THRESHOLD_SECONDS: number;
+/** Minimum password length accepted by the login/setup forms. */
+export declare const MIN_PASSWORD_LENGTH = 8;
+export interface PasswordHashOptions {
+    /** scrypt cost N (must be a power of two). */
+    N?: number;
+    r?: number;
+    p?: number;
+    keylen?: number;
+    randomBytes?: (size: number) => Uint8Array;
+}
+export interface ParsedPasswordHash {
+    N: number;
+    r: number;
+    p: number;
+    salt: Buffer;
+    hash: Buffer;
+}
+/** Hash a password with a fresh random salt. */
+export declare function hashPassword(password: string, options?: PasswordHashOptions): string;
+/** Parse a hash produced by {@link hashPassword}; undefined when malformed. */
+export declare function parsePasswordHash(stored: string): ParsedPasswordHash | undefined;
+/** Timing-safe password check against a stored hash. */
+export declare function verifyPassword(password: string, stored: string): boolean;
+export interface SessionPayload {
+    v: 1;
+    /** Expiry as epoch seconds. */
+    exp: number;
+}
+/** Sign a cookie value for the given secret (32+ random bytes). */
+export declare function signSession(secret: Buffer, exp: number): string;
+/** Verify and decode a cookie value; undefined when invalid or expired. */
+export declare function verifySession(value: string | undefined, secret: Buffer, now?: number): SessionPayload | undefined;
+/** Whether a live session still has enough runway that no refresh is needed. */
+export declare function needsSessionRefresh(session: SessionPayload, now?: number): boolean;
+/** Exponential backoff policy: 5 fails → 1 min, doubling, 30 min cap. */
+export declare const RATE_LIMIT: {
+    readonly maxFails: 5;
+    readonly initialBlockMs: number;
+    readonly maxBlockMs: number;
+    /** Failures older than this no longer count toward the next block. */
+    readonly windowMs: number;
+    /** Idle buckets are dropped after this long without activity. */
+    readonly idleTtlMs: number;
+};
+export declare class RateLimiter {
+    private buckets;
+    /**
+     * Whether the key may attempt now. When blocked, the returned
+     * retryAfterSeconds tells the caller how long to wait.
+     */
+    check(key: string, now?: number): {
+        allowed: boolean;
+        retryAfterSeconds?: number;
+    };
+    /** Record one failure; returns the block state for the key. */
+    recordFailure(key: string, now?: number): {
+        blockedUntil: number;
+    };
+    /** Clear a key's history (successful login). */
+    reset(key: string): void;
+    /** Drop buckets idle for the TTL (blocked buckets stay until they expire). */
+    private prune;
+    /** Test seam: number of tracked keys. */
+    get size(): number;
+}
+/**
+ * Accept only same-origin absolute paths as a `next` redirect target: must
+ * start with a single "/", not with "//" (protocol-relative), and contain no
+ * backslash or control characters. Everything else (absolute URLs, scheme
+ * tricks) is rejected, preventing open-redirect through the login page.
+ */
+export declare function sanitizeNext(raw: unknown): string | undefined;

package/lib/auth-core.js

@@ -0,0 +1,175 @@
+/**
+ * dsh-web-auth — authentication core (pure logic, no cordis/harness deps).
+ *
+ * Password hashing (scrypt + salt), session cookie signing (HMAC-SHA256),
+ * per-peer rate limiting with exponential backoff, and same-origin
+ * redirect-target validation. Everything here is a pure function of its
+ * inputs so the test tree can exercise it without a server.
+ */
+import { createHmac, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+/** Cookie name carrying the signed session. */
+export const COOKIE_NAME = 'dsh_web_auth';
+/** Session lifetime: 7 days (sliding — refreshed on activity). */
+export const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60;
+/** Refresh the cookie only when less than this much lifetime remains. */
+export const SESSION_REFRESH_THRESHOLD_SECONDS = 24 * 60 * 60;
+/** Minimum password length accepted by the login/setup forms. */
+export const MIN_PASSWORD_LENGTH = 8;
+/** Hash a password with a fresh random salt. */
+export function hashPassword(password, options = {}) {
+    const N = options.N ?? 16384;
+    const r = options.r ?? 8;
+    const p = options.p ?? 1;
+    const keylen = options.keylen ?? 32;
+    const salt = Buffer.from(options.randomBytes ? Array.from(options.randomBytes(16)) : randomBytes(16));
+    const derived = scryptSync(password, salt, keylen, { N, r, p });
+    return ['scrypt', String(N), String(r), String(p), salt.toString('base64url'), derived.toString('base64url')].join('$');
+}
+/** Parse a hash produced by {@link hashPassword}; undefined when malformed. */
+export function parsePasswordHash(stored) {
+    const parts = stored.split('$');
+    if (parts.length !== 6 || parts[0] !== 'scrypt')
+        return undefined;
+    const N = Number(parts[1]);
+    const r = Number(parts[2]);
+    const p = Number(parts[3]);
+    if (!Number.isInteger(N) || !Number.isInteger(r) || !Number.isInteger(p))
+        return undefined;
+    let salt;
+    let hash;
+    try {
+        salt = Buffer.from(parts[4], 'base64url');
+        hash = Buffer.from(parts[5], 'base64url');
+    }
+    catch {
+        return undefined;
+    }
+    if (salt.length === 0 || hash.length === 0)
+        return undefined;
+    return { N, r, p, salt, hash };
+}
+/** Timing-safe password check against a stored hash. */
+export function verifyPassword(password, stored) {
+    const parsed = parsePasswordHash(stored);
+    if (parsed === undefined)
+        return false;
+    try {
+        const derived = scryptSync(password, parsed.salt, parsed.hash.length, { N: parsed.N, r: parsed.r, p: parsed.p });
+        return timingSafeEqual(derived, parsed.hash);
+    }
+    catch {
+        return false;
+    }
+}
+/** Sign a cookie value for the given secret (32+ random bytes). */
+export function signSession(secret, exp) {
+    const payload = Buffer.from(JSON.stringify({ v: 1, exp }), 'utf8').toString('base64url');
+    const sig = createHmac('sha256', secret).update(payload).digest('base64url');
+    return payload + '.' + sig;
+}
+/** Verify and decode a cookie value; undefined when invalid or expired. */
+export function verifySession(value, secret, now = Date.now()) {
+    if (value === undefined)
+        return undefined;
+    const dot = value.indexOf('.');
+    if (dot <= 0)
+        return undefined;
+    const payload = value.slice(0, dot);
+    const sig = value.slice(dot + 1);
+    const expected = createHmac('sha256', secret).update(payload).digest('base64url');
+    const sigBuf = Buffer.from(sig, 'base64url');
+    const expBuf = Buffer.from(expected, 'base64url');
+    if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const session = parsed;
+    if (session.v !== 1 || typeof session.exp !== 'number')
+        return undefined;
+    if (session.exp * 1000 <= now)
+        return undefined;
+    return { v: 1, exp: session.exp };
+}
+/** Whether a live session still has enough runway that no refresh is needed. */
+export function needsSessionRefresh(session, now = Date.now()) {
+    return session.exp * 1000 - now < SESSION_REFRESH_THRESHOLD_SECONDS * 1000;
+}
+/** Exponential backoff policy: 5 fails → 1 min, doubling, 30 min cap. */
+export const RATE_LIMIT = {
+    maxFails: 5,
+    initialBlockMs: 60 * 1000,
+    maxBlockMs: 30 * 60 * 1000,
+    /** Failures older than this no longer count toward the next block. */
+    windowMs: 15 * 60 * 1000,
+    /** Idle buckets are dropped after this long without activity. */
+    idleTtlMs: 60 * 60 * 1000
+};
+export class RateLimiter {
+    buckets = new Map();
+    /**
+     * Whether the key may attempt now. When blocked, the returned
+     * retryAfterSeconds tells the caller how long to wait.
+     */
+    check(key, now = Date.now()) {
+        this.prune(now);
+        const bucket = this.buckets.get(key);
+        if (bucket === undefined)
+            return { allowed: true };
+        if (bucket.blockedUntil > now) {
+            return { allowed: false, retryAfterSeconds: Math.ceil((bucket.blockedUntil - now) / 1000) };
+        }
+        return { allowed: true };
+    }
+    /** Record one failure; returns the block state for the key. */
+    recordFailure(key, now = Date.now()) {
+        const bucket = this.buckets.get(key);
+        const stale = bucket !== undefined && now - bucket.lastFailureAt > RATE_LIMIT.windowMs;
+        const fails = bucket === undefined || stale ? 1 : bucket.fails + 1;
+        const blockedUntil = fails >= RATE_LIMIT.maxFails
+            ? now + Math.min(RATE_LIMIT.initialBlockMs * 2 ** (fails - RATE_LIMIT.maxFails), RATE_LIMIT.maxBlockMs)
+            : 0;
+        this.buckets.set(key, { fails, blockedUntil, lastFailureAt: now });
+        return { blockedUntil };
+    }
+    /** Clear a key's history (successful login). */
+    reset(key) {
+        this.buckets.delete(key);
+    }
+    /** Drop buckets idle for the TTL (blocked buckets stay until they expire). */
+    prune(now) {
+        for (const [key, bucket] of this.buckets) {
+            if (bucket.blockedUntil <= now && now - bucket.lastFailureAt > RATE_LIMIT.idleTtlMs) {
+                this.buckets.delete(key);
+            }
+        }
+    }
+    /** Test seam: number of tracked keys. */
+    get size() {
+        return this.buckets.size;
+    }
+}
+// ── redirect target validation ──────────────────────────────────────────────
+/**
+ * Accept only same-origin absolute paths as a `next` redirect target: must
+ * start with a single "/", not with "//" (protocol-relative), and contain no
+ * backslash or control characters. Everything else (absolute URLs, scheme
+ * tricks) is rejected, preventing open-redirect through the login page.
+ */
+export function sanitizeNext(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    if (raw.length === 0 || raw.length > 2048)
+        return undefined;
+    if (!raw.startsWith('/') || raw.startsWith('//'))
+        return undefined;
+    if (/[\\\u0000-\u001f]/.test(raw))
+        return undefined;
+    if (/[\s?]*:/.test(raw))
+        return undefined;
+    return raw;
+}

package/lib/client/index.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Services provided by other browser plugins before this one mounts. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the settings section. The shell's declaration
+ * may not be on the ledger yet, so the registration waits via slots.inject.
+ * @param ctx - the client cordis context.
+ */
+export declare function apply(ctx: Context): void;