@riceawa/dsh-lan-gateway 0.3.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@riceawa/dsh-lan-gateway",
-  "description": "LAN/internet reverse-proxy gateway for the DeepSeek Harness web GUI: binds 0.0.0.0, forwards to the loopback dsh web server with header rewrite to pass the /api trust fence. LAN sources are password-free; non-LAN sources get a login page + HMAC cookie. Optional TLS with auto-generated self-signed or user-supplied certificates, and a Settings → Plugins card for live adjustment of port, CIDRs, auth, and TLS. Includes an insecure-origin UUID shim client bundle: on gateway-served plain-HTTP origins browsers lack crypto.randomUUID, so the client half patches a getRandomValues-backed randomUUID onto the Crypto prototype, fixing workspace open over LAN without touching DSH source.",
-  "version": "0.3.0",
+  "description": "LAN/internet reverse-proxy gateway for the DeepSeek Harness web GUI: binds 0.0.0.0 and forwards to the loopback dsh web server. Default-deny: every source (loopback, LAN, internet) must sign in with an HMAC session cookie unless lanPasswordless is explicitly enabled; against dsh >= 0.1.2-rc.1 the gateway relays one shared upstream browser session, so the harness's own authorization still gates every request. Fail-closed start guard (password required, plaintext needs an explicit opt-in), session revocation by epoch (password changes and secret rotation kill cookies and live WebSockets), same-site/Origin fence on HTTP and WebSocket upgrades, optional TLS (auto self-signed or user-supplied certs), and a Settings → Plugins card for live adjustment of port, CIDRs, auth, and TLS. Includes an insecure-origin UUID shim client bundle: on gateway-served plain-HTTP origins browsers lack crypto.randomUUID, so the client half patches a getRandomValues-backed randomUUID onto the Crypto prototype, fixing workspace open over LAN without touching DSH source.",
+  "version": "0.5.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/skills/lan-gateway.md

@@ -1,7 +1,7 @@
 ---
 name: lan-gateway
-description: Manage remote (non-LAN) access to the DeepSeek Harness web GUI through the dsh-lan-gateway plugin. Use when the user asks to open the web GUI to the LAN/internet, set or change the remote-access password, rotate the session secret, or check whether remote access is currently enabled and what it is listening on.
-whenToUse: The user wants the web GUI reachable from their LAN or the wider internet, wants to enable/disable that, set the login password for remote visitors, rotate the session cookie secret, or learn the current gateway status (port, target, password state, trusted CIDRs).
+description: Manage remote (non-LAN) access to the DeepSeek Harness web GUI through the dsh-lan-gateway plugin. Use when the user asks to open the web GUI to the LAN/internet, set or change the remote-access password, rotate the session secret, or check whether remote access is currently enabled, on what port, and whether the harness base supports the shared upstream session relay.
+whenToUse: The user wants the web GUI reachable from their LAN or the wider internet, wants to enable/disable that, set the login password for remote visitors, rotate the session cookie secret, or learn the current gateway status (port, target, password state, ingress encryption, upstream-session relay, session epoch).
 user-invocable: true
 ---
 
@@ -10,47 +10,65 @@ user-invocable: true
 The `dsh-lan-gateway` plugin lets the DeepSeek Harness web GUI be reached from the
 LAN and the wider internet. dsh itself binds only to loopback (the web CLI
 hard-refuses `0.0.0.0`), so this plugin runs its own reverse-proxy gateway on
-`0.0.0.0` that forwards to the loopback web server while rewriting Host/Origin so
-the `/api` trust fence still passes.
+`0.0.0.0` that forwards to the loopback web server while rewriting Host/Origin.
 
-## Access tiers
+Since v0.5.0 the model is **default-deny** (post-QVD-2026-57410 hardening):
 
-- **Loopback** (`127.0.0.1`, `::1`) — no password.
-- **LAN** (RFC1918 `10/8`, `172.16/12`, `192.168/16`, link-local `169.254/16`, `fe80::/10`)
-  — no password.
-- **Anything else** (the public internet, CGNAT, Tailscale) — must sign in at the
-  login page and receive the session cookie.
-
-You can extend the trusted LAN ranges by editing the plugin's `lanCidrs` config.
+- **Every source — loopback, LAN, internet — must sign in** at the gateway login
+  page and present the HMAC session cookie. Nothing is granted by source alone.
+- **LAN passwordless is an explicit opt-in** (`lanPasswordless: true`). When on,
+  sources in `lanCidrs` (and loopback) skip the gateway login page. The listener
+  refuses to enable `lanPasswordless` unless the dsh base enforces browser-session
+  auth (dsh ≥ 0.1.2-rc.1), where the gateway relays one shared upstream session and
+  upstream authorization still gates every request.
+- **Encrypted ingress is required to start.** The listener refuses to run over
+  plaintext unless TLS is on (`tlsEnabled`), a trusted terminator is declared
+  (`trustedTerminator`), or `allowInsecurePlaintext: true` is set explicitly.
+- A password is always required to run the gateway.
 
 ## Drive it through the `lan_gateway` tool
 
-Do not edit state files by hand — use the `lan_gateway` tool. The gateway refuses
-to listen until a password is set (unless `authRequired` is explicitly false).
+Do not edit state files by hand — use the `lan_gateway` tool.
 
 - `lan_gateway` with `command: "status"` — is it listening, on which port, toward
-  which dsh port, password set?, trusted CIDRs, cookie lifetime.
-- `lan_gateway` with `command: "set-password"` and `password: "<new pass>"`
-  (min 8 chars) — set the remote-access password. Pass an empty password to clear.
-- `lan_gateway` with `command: "enable"` — start listening on the gateway port.
+  which dsh port, password set?, session epoch, upstream-session relay state,
+  ingress encryption, last error.
+- `lan_gateway` with `command: "enable"` — start listening. If it refuses (no
+  password, legacy `authRequired: false`, plaintext without opt-in, `lanPasswordless`
+  without a session-capable base), the message tells you what to change.
 - `lan_gateway` with `command: "disable"` — stop listening (dsh itself stays up).
+- `lan_gateway` with `command: "set-password"` and `password: "<new pass>"`
+  (min 8 chars) — set the login password. Setting it revokes every existing session
+  (all sources, LAN included, must sign in again). Pass an empty password to clear —
+  clearing stops the listener (a password is required to run).
 - `lan_gateway` with `command: "rotate-secret"` — invalidate every issued login
-  cookie (users must sign in again).
+  cookie and every live WebSocket (users must sign in again).
+- `lan_gateway` with `command: "tls-regenerate"` — mint a fresh self-signed
+  certificate and hot-restart the listener (tlsMode must be `self-signed`).
 
 ## After enabling
 
 Tell the user the gateway URL they can share:
 
-- On the LAN: `http://<lan-ip>:<gatewayPort>/` (default port `3081`).
-- From outside: the machine's public address or a Tailscale IP on port
-  `3081` — that path requires the password.
+- On the LAN: `http://<lan-ip>:<gatewayPort>/` (default port `3081`) — requires the
+  login password unless `lanPasswordless` is enabled for their network.
+- From outside: the machine's public address or a Tailscale IP on port `3081` —
+  that path always requires the password.
+
+Remind the user which encrypted-ingress choice they are on: TLS / a trusted
+terminator / explicit plaintext. If they enabled plaintext, restate the exposure
+once (passwords and sessions travel in clear).
 
 ## Troubleshooting
 
-- Gateway won't start: set a password first (`lan_gateway set-password`), check
-  the port is free, confirm `ctx.webServer.port` (default dsh web port `3080`)
-  is where dsh is actually listening.
-- Remote visitors see a redirect loop or 403: check the login cookie
-  (`dsh_gw_auth`) and that their source is classified as `internet`. A `403` on
-  `/api` from a browser is the gateway's own origin/CSRF fence — a real page
-  load carries the right Origin; a hand-crafted cross-site request does not.
+- Gateway won't start: set a password first (`lan_gateway set-password`); check the
+  fail-closed conditions — legacy `authRequired: false` must be removed, plaintext
+  needs `allowInsecurePlaintext: true` or TLS/`trustedTerminator`, and
+  `lanPasswordless` needs dsh ≥ 0.1.2-rc.1. `lan_gateway status` shows the last error.
+- Remote visitors see a redirect loop or 403: check the login cookie (`dsh_gw_auth`)
+  and that their source is classified as `internet`. A `403` on `/api` from a
+  browser is the gateway's own origin/CSRF fence — a real page load carries the
+  right Origin; a hand-crafted cross-site request (or a non-browser client posting
+  without an Origin) does not.
+- Sessions don't survive a password change / `rotate-secret`: that is by design —
+  the revocation epoch advanced and all cookies (and live WebSockets) were revoked.

package/src/auth.ts

@@ -114,16 +114,29 @@ function base64url(input: Buffer): string {
  * Issue a signed session cookie value.
  * @param secret - the HMAC signing secret (base64 string).
  * @param expiresMs - epoch millis at which the session expires.
+ * @param epoch - the session revocation epoch the cookie is minted under; a
+ *   cookie whose epoch no longer matches the live state is rejected by
+ *   {@link verifyCookie}. Defaults to 0 (epoch-less, legacy) for callers that
+ *   do not participate in revocation.
  * @returns a `payload.signature` string suitable for the cookie value.
  */
-export function signCookie(secret: string, expiresMs: number): string {
-  const payload = base64url(Buffer.from(JSON.stringify({ exp: expiresMs })))
+export function signCookie(secret: string, expiresMs: number, epoch: number = 0): string {
+  const payload = base64url(Buffer.from(JSON.stringify({ exp: expiresMs, epoch })))
   const sig = createHmac('sha256', secret).update(payload).digest('base64url')
   return `${payload}.${sig}`
 }
 
-/** Whether a cookie value is a valid, unexpired session signed with `secret`. */
-export function verifyCookie(secret: string, value: string | undefined, now: number): boolean {
+/**
+ * Whether a cookie value is a valid, unexpired session signed with `secret`
+ * and minted under `epoch`. Epoch-less cookies (legacy payloads) count as
+ * epoch 0, so an upgrade from a pre-0.5.0 state does not log everyone out.
+ */
+export function verifyCookie(
+  secret: string,
+  value: string | undefined,
+  now: number,
+  epoch: number = 0,
+): boolean {
   if (value === undefined) return false
   const dot = value.indexOf('.')
   if (dot === -1) return false
@@ -139,8 +152,28 @@ export function verifyCookie(secret: string, value: string | undefined, now: num
   if (expected.length !== actual.length) return false
   if (!timingSafeEqual(expected, actual)) return false
   try {
-    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as { exp?: unknown }
-    return typeof decoded.exp === 'number' && decoded.exp > now
+    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as { exp?: unknown; epoch?: unknown }
+    if (typeof decoded.exp !== 'number' || decoded.exp <= now) return false
+    const cookieEpoch = typeof decoded.epoch === 'number' ? decoded.epoch : 0
+    return cookieEpoch === epoch
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Whether a browser Origin header names the same authority (hostname:port) as
+ * a request Host header. Both sides run through WHATWG URL parsing so case and
+ * an implicit scheme-default port never decide the match — the comparison the
+ * gateway uses to tell same-origin browser requests from cross-site ones.
+ * @param origin - the `Origin` header value, or undefined.
+ * @param host - the `Host` header value, or undefined.
+ * @returns true only when both parse and name the same host[:port].
+ */
+export function originMatchesHost(origin: string | undefined, host: string | undefined): boolean {
+  if (origin === undefined || host === undefined) return false
+  try {
+    return new URL(origin).host === new URL(`http://${host}`).host
   } catch {
     return false
   }

package/src/client/index.ts

@@ -79,11 +79,25 @@ export function apply(ctx: ClientContext): void {
   // The card rides the official Plugins → Configurable tab. Like ModLens, it
   // registers with no inject face and fetches its own loopback config route,
   // so it has no settings/locale/connection service dependencies.
+  //
+  // The `settings.plugin.item` slot is keyed BY the settings namespace the
+  // card edits (rc.8 contract): the configurable tab only dispatches entries
+  // whose `options.key` is both present and served by the Host's settings
+  // describe mirror. Registering with `id` alone throws
+  // `keyed slot "settings.plugin.item" requires options.key` and the card
+  // silently disappears from Settings → Plugins.
+  //
+  // `id`/`order` ride the legacy list-slot shape (older DSH versions
+  // dispatched this slot by id): harmless metadata on the keyed slot, and
+  // what keeps the card mounting if this plugin ever loads into an older
+  // deployment. Spread from a typed constant so the keyed registration type
+  // stays exact.
+  const legacyListOptions = { id: 'lan-gateway', order: 30 } as const
   ctx.slots.inject('settings.plugin.item', function* () {
     yield ctx.slots.register({
       name: 'settings.plugin.item',
-      id: 'lan-gateway',
-      order: 30,
+      key: 'lan-gateway',
+      ...legacyListOptions,
     }, LanGatewayCard)
   })
 }

package/src/client/lan-gateway-card.tsx

@@ -15,14 +15,15 @@ import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 
 /**
  * The official Settings → Plugins page declares the `settings.plugin.item`
- * list slot (kind list, root scope, empty owner share) in its own package.
- * The published package ships no `src/`, so the entry is re-declared here —
- * the runtime slot is real; this only restores the compile-time table.
+ * slot keyed by the settings namespace each card edits (newer DSH releases;
+ * older releases dispatched it as a list slot by `id`). The published package
+ * ships no `src/`, so the entry is re-declared here — the runtime slot is
+ * real; this only restores the compile-time table.
  */
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
     /** One plugin's card inside the plugin configuration section. */
-    'settings.plugin.item': { kind: 'list'; scope: 'root'; owner: { children?: never } }
+    'settings.plugin.item': { kind: 'keyed'; scope: 'root'; owner: { children?: never } }
   }
 }
 
@@ -35,7 +36,7 @@ export interface LanGatewaySettings {
   gatewayPort?: number
   dshTargetPort?: number
   lanCidrs?: string[]
-  authRequired?: boolean
+  lanPasswordless?: boolean
   cookieMaxAgeDays?: number
   tlsEnabled?: boolean
   tlsMode?: 'self-signed' | 'custom'
@@ -43,6 +44,8 @@ export interface LanGatewaySettings {
   tlsKeyPath?: string
   tlsSelfSignedHosts?: string
   tlsCertMaxAgeDays?: number
+  allowInsecurePlaintext?: boolean
+  trustedTerminator?: string
 }
 
 /** GET /lan-gateway/config response. */
@@ -105,8 +108,12 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     'hint.dshTargetPort': '留空则自动跟随 dsh web 端口（默认 3080）',
     'field.lanCidrs': '免密 LAN 网段',
     'hint.lanCidrs': '逗号分隔的 CIDR，如 10.0.0.0/8, 192.168.0.0/16',
-    'field.authRequired': '非 LAN 访问需要密码',
-    'hint.authRequired': '公网来源必须登录后才能访问',
+    'field.lanPasswordless': 'LAN 免登录',
+    'hint.lanPasswordless': 'LAN/回环来源跳过网关登录页，但仍共用同一上游会话（需 dsh ≥ 0.1.2）',
+    'field.allowInsecurePlaintext': '允许明文 HTTP',
+    'hint.allowInsecurePlaintext': '危险：关闭 TLS 或受信终止代理时仍启动监听，密码与会话将以明文传输',
+    'field.trustedTerminator': '受信 TLS 终止代理',
+    'hint.trustedTerminator': '可选：声明前置代理标识，视为加密入口（如 nginx）。留空 = 未声明',
     'field.cookieMaxAgeDays': '会话有效期（天）',
     'hint.cookieMaxAgeDays': '登录 cookie 的存活天数（默认 7）',
     'field.tlsEnabled': '启用 TLS（HTTPS）',
@@ -147,8 +154,12 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     'hint.dshTargetPort': 'Leave empty to follow the dsh web port (default 3080)',
     'field.lanCidrs': 'Password-free LAN CIDRs',
     'hint.lanCidrs': 'Comma separated CIDRs, e.g. 10.0.0.0/8, 192.168.0.0/16',
-    'field.authRequired': 'Password required for non-LAN',
-    'hint.authRequired': 'Internet sources must sign in before reaching the GUI',
+    'field.lanPasswordless': 'LAN skip login',
+    'hint.lanPasswordless': 'LAN/loopback sources skip the gateway login page but still ride one shared upstream session (needs dsh >= 0.1.2)',
+    'field.allowInsecurePlaintext': 'Allow plaintext HTTP',
+    'hint.allowInsecurePlaintext': 'Dangerous: start the listener even without TLS or a trusted terminator; passwords and sessions travel in clear',
+    'field.trustedTerminator': 'Trusted TLS terminator',
+    'hint.trustedTerminator': 'Optional identifier for a front proxy (e.g. nginx) treated as the encrypted ingress. Empty = none declared',
     'field.cookieMaxAgeDays': 'Session lifetime (days)',
     'hint.cookieMaxAgeDays': 'Login cookie lifetime (default 7)',
     'field.tlsEnabled': 'Enable TLS (HTTPS)',
@@ -189,7 +200,7 @@ const FIELDS: readonly FieldDef[] = [
   { field: 'gatewayPort', kind: 'number' },
   { field: 'dshTargetPort', kind: 'number', optional: true },
   { field: 'lanCidrs', kind: 'cidrs' },
-  { field: 'authRequired', kind: 'boolean' },
+  { field: 'lanPasswordless', kind: 'boolean' },
   { field: 'cookieMaxAgeDays', kind: 'number' },
   { field: 'tlsEnabled', kind: 'boolean' },
   { field: 'tlsMode', kind: 'select', options: ['self-signed', 'custom'] },
@@ -197,6 +208,8 @@ const FIELDS: readonly FieldDef[] = [
   { field: 'tlsCertPath', kind: 'text', optional: true },
   { field: 'tlsKeyPath', kind: 'text', optional: true },
   { field: 'tlsCertMaxAgeDays', kind: 'number' },
+  { field: 'allowInsecurePlaintext', kind: 'boolean' },
+  { field: 'trustedTerminator', kind: 'text', optional: true },
 ]
 
 function formatValue(def: FieldDef, value: unknown): string {
@@ -423,13 +436,13 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
         aria-expanded={open}
         onClick={() => { setOpen(!open) }}
       >
-        <span style={styles.headText}>
+        <span style={styles.headerTop}>
           <span style={styles.name}>{t.title}</span>
-          <span style={styles.description}>{t.description}</span>
+          <span style={styles.status} title={statusLine}>{statusLine}</span>
+          {dirty ? <span style={styles.pending}>{t.unsaved}</span> : null}
+          <span style={open ? { ...styles.chevron, ...styles.chevronOpen } : styles.chevron}>{open ? '▾' : '▸'}</span>
         </span>
-        <span style={styles.status}>{statusLine}</span>
-        {dirty ? <span style={styles.pending}>{t.unsaved}</span> : null}
-        <span style={open ? { ...styles.chevron, ...styles.chevronOpen } : styles.chevron}>{open ? '▾' : '▸'}</span>
+        <span style={styles.description}>{t.description}</span>
       </button>
       {open
         ? (
@@ -501,8 +514,9 @@ const styles: Record<string, React.CSSProperties> = {
   },
   header: {
     display: 'flex',
-    alignItems: 'center',
-    gap: '12px',
+    flexDirection: 'column',
+    alignItems: 'stretch',
+    gap: '6px',
     width: '100%',
     padding: '14px 16px',
     border: 0,
@@ -512,10 +526,31 @@ const styles: Record<string, React.CSSProperties> = {
     textAlign: 'left',
     cursor: 'pointer',
   },
-  headText: { display: 'flex', flexDirection: 'column', gap: '4px', flex: 1, minWidth: 0 },
-  name: { fontSize: '15px', fontWeight: 600, lineHeight: 1.4, color: L.labelPrimary },
-  description: { fontSize: '13px', lineHeight: 1.5, color: L.labelTertiary },
-  status: { fontSize: '11px', color: L.labelTertiary, whiteSpace: 'nowrap' },
+  headerTop: { display: 'flex', alignItems: 'center', gap: '12px', width: '100%' },
+  name: { flex: '1 1 auto', minWidth: 0, fontSize: '15px', fontWeight: 600, lineHeight: 1.4, color: L.labelPrimary },
+  // The status carries a verbose TLS cert summary; cap it and ellipsize so it
+  // can never swallow the row or squeeze the title (the old nowrap alone
+  // caused the description to be pushed into a thin wrapping column).
+  status: {
+    flex: '0 1 auto',
+    minWidth: 0,
+    maxWidth: '60%',
+    fontSize: '11px',
+    lineHeight: 1.4,
+    color: L.labelTertiary,
+    whiteSpace: 'nowrap',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+  },
+  description: {
+    display: 'block',
+    fontSize: '13px',
+    lineHeight: 1.5,
+    color: L.labelTertiary,
+    whiteSpace: 'nowrap',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+  },
   pending: {
     flex: 'none',
     borderRadius: '999px',