@riceawa/dsh-lan-gateway 0.5.4 → 0.6.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 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.4",
+  "version": "0.6.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -42,22 +42,34 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1 || ^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1 || ^0.1.5-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-settings": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-brand": "0.1.5-rc.2",
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/cordis-plugin-loader": "1.0.5",
+    "@deepseek-ai/cosmokit": "1.8.5",
+    "@deepseek-ai/dsh-brand": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.1.7-rc.2",
     "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-scope": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-settings": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-util-values": "0.1.5-rc.2",
-    "@deepseek-ai/schemastery": "3.18.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "3.18.4",
     "@types/node": "^22.0.0",
     "@types/react": "~18.3.1",
     "react": "^18.2.0",

package/src/auth.ts

@@ -77,6 +77,13 @@ function normalizeAddress(raw: string): string {
 
 /**
  * Classify a source address string into one of the three trust tiers.
+ *
+ * The input is a *socket* address — `req.socket.remoteAddress`, unwrapped from
+ * its `::ffff:` mapping — which is a different domain from the URL hostname
+ * `isLoopbackHost` in `request-policy.ts` judges. The two agree on the common
+ * inputs but are not interchangeable: this one never sees `[::1]`, and that one
+ * never sees a mapped form. Both spans are documented where each lives.
+ *
  * @param remoteAddress - the raw value of `req.socket.remoteAddress`.
  * @param lanCidrs - CIDR strings treated as trusted LAN space (IPv4).
  * @returns the classification. IPv4-mapped IPv6 addresses are unwrapped.
@@ -191,20 +198,6 @@ export function verifySession(
   }
 }
 
-/**
- * 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 {
-  return verifySession(secret, value, now, epoch) !== undefined
-}
-
 /**
  * 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

package/src/client/index.ts

@@ -7,10 +7,9 @@
  *    installs a getRandomValues-backed `randomUUID` on the Crypto prototype at
  *    module scope. With TLS enabled the origin is secure and the shim is a
  *    no-op.
- * 2. Settings card: registers the LAN gateway card into the official
- *    Settings → Plugins page (`settings.plugin.item` slot), editing the
- *    `lan-gateway` settings namespace so port, CIDRs, auth, and TLS are
- *    adjustable from the GUI.
+ * 2. Settings card: registers the LAN gateway card into the official Plugins
+ *    page (`plugins.item` slot) so port, CIDRs, auth, and TLS stay adjustable
+ *    from the GUI.
  */
 
 /** RFC 4122 v4 UUID from crypto.getRandomValues (available on insecure origins). */
@@ -62,12 +61,25 @@ export function installRandomUuidShim(): boolean {
 installRandomUuidShim()
 
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
-import { LanGatewayCard } from './lan-gateway-card.tsx'
+// Type-only, and never bundled: the Plugins page's slot contract (`plugins.item`)
+// and the settings domain's `configForms` service both resolve from the web
+// shell's frozen module table. Importing them is what subjects the registration
+// below to the platform's own contract instead of a local copy that drifts the
+// next time upstream renames a slot.
+import type {} from '@deepseek-ai/dsh-client-ui-plugin-manager/client'
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import { LanGatewayCard, cardTitle } from './lan-gateway-card.tsx'
 
 export const name = 'dsh-lan-gateway'
 
-/** Only the slots service: the card itself is self-loading (ModLens-style). */
-export const inject = ['slots']
+/**
+ * The profile entry id this plugin's bundle patch composes it under, and the
+ * settings namespace dsh ≥ 0.1.7 addresses every write by.
+ */
+const ENTRY_ID = 'dsh-lan-gateway'
+
+/** The slots service the card rides, and the settings mirror the gate reads. */
+export const inject = ['slots', 'configForms']
 
 /**
  * Mount the settings card and the UUID shim.
@@ -76,28 +88,26 @@ export const inject = ['slots']
 export function apply(ctx: ClientContext): void {
   installRandomUuidShim()
 
-  // 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 card rides the official Plugins page. Like ModLens it registers with no
+  // inject face and fetches its own loopback config route, so it depends on no
+  // settings, locale, or connection service.
   //
-  // 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.
+  // dsh 0.1.7 replaced the namespace-keyed `settings.plugin.item` slot with the
+  // list slot `plugins.item`, which is where a host-plane plugin's own
+  // configuration page belongs ("one companion package per host-plane
+  // namespace"); the page renders the contribution as the card's one-liner and,
+  // once opened, as the body of the plugin's own page. Registering into the
+  // retired slot left the card invisible on 0.1.7.
   //
-  // `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',
-      key: 'lan-gateway',
-      ...legacyListOptions,
-    }, LanGatewayCard)
-  })
+  // `whileServed` keeps the entry off the page until the Host's settings mirror
+  // serves this plugin's entry. That is the one gate worth having: without a
+  // Loader entry there is nothing to write to, and the card would appear only
+  // to fail every save with the route's 409.
+  ctx.effect(() => ctx.configForms.whileServed([ENTRY_ID], () =>
+    ctx.slots.inject('plugins.item', () => ctx.slots.register({
+      name: 'plugins.item',
+      id: ENTRY_ID,
+      order: 30,
+      label: () => cardTitle(),
+    }, LanGatewayCard))))
 }

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

@@ -1,53 +1,49 @@
 /**
- * The lan-gateway settings card shown in the official DSH Settings → Plugins
- * page (the `settings.plugin.item` slot).
+ * The lan-gateway settings card, rendered by the official DSH Plugins page
+ * through its `plugins.item` slot.
  *
  * ModLens-style: the card carries NO injected services. It reads and writes
  * the loopback-only `/lan-gateway/config` host route (the browser never sees
- * the settings seam or any secret), so the client bundle's only dependency is
- * the `slots` service that every plugin already has.
+ * the settings seam or any secret), so the only platform service it needs is
+ * the `slots` service every plugin already has.
  *
  * @module @riceawa/dsh-lan-gateway/client/card
  */
 
 import { useEffect, useState, type ChangeEvent, type ReactNode } from 'react'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only. The Plugins page owns the `plugins.item` contract, and its own
+// doc says a registrant merges that contract with `import type` instead of
+// importing the package at runtime. Taking the contract from its owner is also
+// what turns the next upstream rename of this slot into a compile error here,
+// rather than a card that quietly stops rendering.
+import type {} from '@deepseek-ai/dsh-client-ui-plugin-manager/client'
+import {
+  FIELDS,
+  TRISTATE_OPTIONS,
+  formatValue,
+  parseValue,
+  type FieldDef,
+  type LanGatewaySettings,
+} from '../config-fields.ts'
 
 /**
- * The official Settings → Plugins page declares the `settings.plugin.item`
- * 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.
+ * Props the renderer binds for this card. The Plugins page asks for either the
+ * card's one-liner (`summary`) or the body of its own page (`page`), and draws
+ * the page's title, icon, and crumb itself. The card needs no injected face —
+ * it fetches its own route.
  */
-declare module '@deepseek-ai/dsh-client-ui-slots' {
-  interface SlotMap {
-    /** One plugin's card inside the plugin configuration section. */
-    'settings.plugin.item': { kind: 'keyed'; scope: 'root'; owner: { children?: never } }
-  }
-}
-
-/** Props the renderer binds for this card (unused — the card is self-loading). */
-export type LanGatewayCardProps = PropsRuntime<'settings.plugin.item'>
+export type LanGatewayCardProps = PropsRuntime<'plugins.item'>
 
-/** The wire shape of the `lan-gateway` config section. */
-export interface LanGatewaySettings {
-  enabled?: boolean
-  gatewayPort?: number
-  dshTargetPort?: number
-  lanCidrs?: string[]
-  lanPasswordless?: boolean
-  cookieMaxAgeDays?: number
-  tlsEnabled?: boolean
-  tlsMode?: 'self-signed' | 'custom'
-  tlsCertPath?: string
-  tlsKeyPath?: string
-  tlsSelfSignedHosts?: string
-  tlsCertMaxAgeDays?: number
-  allowInsecurePlaintext?: boolean
-  trustedTerminator?: string
-  secureCookies?: boolean
-}
+/**
+ * The card's field table and value codecs live in `config-fields.ts`, shared
+ * with the host: the host's config route decides which submitted keys are
+ * editable and which empty value means "clear", and a table duplicated here
+ * would let the two disagree about a field the card can render but the route
+ * would refuse. Re-exported so the existing tests keep their import path.
+ */
+export { FIELDS, TRISTATE_OPTIONS, formatValue, parseValue }
+export type { FieldDef, LanGatewaySettings }
 
 /** GET /lan-gateway/config response. */
 interface RouteState {
@@ -70,7 +66,6 @@ interface Labels {
   saving: string
   discard: string
   reset: string
-  overridden: string
   readOnly: string
   saveFailed: string
   loadFailed: string
@@ -93,10 +88,9 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     saving: '保存中…',
     discard: '放弃',
     reset: '重置',
-    overridden: '已覆盖',
-    readOnly: '网关设置当前不可用（读不到配置路由）。',
+    readOnly: '网关设置只能在宿主机本机打开 dsh web 时修改：配置路由仅监听回环地址，经网关远程访问的浏览器会被拒绝。远程请改用 lan_gateway 工具。',
     saveFailed: '保存未生效，请检查输入后重试。',
-    loadFailed: '加载网关配置失败。',
+    loadFailed: '无法读取网关配置',
     emptyMeansClear: '留空 = 使用默认',
     running: '运行中',
     stopped: '已停止',
@@ -115,7 +109,7 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     'field.allowInsecurePlaintext': '允许明文 HTTP',
     'hint.allowInsecurePlaintext': '危险：关闭 TLS 或受信终止代理时仍启动监听，密码与会话将以明文传输',
     'field.trustedTerminator': '受信 TLS 终止代理',
-    'hint.trustedTerminator': '可选：声明前置代理标识，视为加密入口（如 nginx）。留空 = 未声明',
+    'hint.trustedTerminator': '可选：声明前置代理标识，视为加密入口（如 nginx）。留空 = 未声明。注意：登录限流以 TCP 源地址为键，代理之后所有浏览器共用一个额度（5 次/分钟）',
     'field.secureCookies': '会话 cookie 的 Secure 属性',
     'hint.secureCookies': '自动 = TLS 或已声明受信终止代理时加 Secure。受信代理只做明文鉴权、浏览器走 http 访问时须设为 false，否则浏览器拒收 Secure cookie，登录会无限弹回登录页',
     'opt.auto': '自动',
@@ -128,13 +122,13 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     'field.tlsMode': '证书来源',
     'hint.tlsMode': 'self-signed = 自动生成自签名证书；custom = 使用自己的证书',
     'field.tlsSelfSignedHosts': '自签名证书域名/IP',
-    'hint.tlsSelfSignedHosts': '逗号分隔，写入证书 SAN，如 localhost, 192.168.1.5',
+    'hint.tlsSelfSignedHosts': '逗号分隔，写入证书 SAN，如 localhost, 192.168.1.5。仅影响下次换发：已有证书沿用至到期，改动不会立刻生效',
     'field.tlsCertPath': '证书文件路径（custom）',
     'hint.tlsCertPath': 'PEM 格式证书（或证书链）的绝对路径',
     'field.tlsKeyPath': '私钥文件路径（custom）',
     'hint.tlsKeyPath': '与证书配套的 PEM 私钥绝对路径',
     'field.tlsCertMaxAgeDays': '自签名证书有效期（天）',
-    'hint.tlsCertMaxAgeDays': '默认 825（约 27 个月）',
+    'hint.tlsCertMaxAgeDays': '默认 825（约 27 个月）。仅影响下次换发：已有证书沿用至到期',
   },
   en: {
     title: 'LAN Gateway',
@@ -144,10 +138,9 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     saving: 'Saving…',
     discard: 'Discard',
     reset: 'Reset',
-    overridden: 'overridden',
-    readOnly: 'Gateway settings unavailable (config route unreachable).',
+    readOnly: 'Gateway settings can only be changed where dsh web runs locally: the config route listens on loopback only, so a browser reaching dsh through the gateway is refused. Use the lan_gateway tool remotely.',
     saveFailed: 'The save did not land — check the inputs and retry.',
-    loadFailed: 'Failed to load gateway configuration.',
+    loadFailed: 'Cannot read the gateway configuration',
     emptyMeansClear: 'Empty = default',
     running: 'Running',
     stopped: 'Stopped',
@@ -166,7 +159,7 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     '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',
+    'hint.trustedTerminator': 'Optional identifier for a front proxy (e.g. nginx) treated as the encrypted ingress. Empty = none declared. Note: login rate limiting keys on the TCP source address, so behind a proxy every browser shares one budget (5/min)',
     'field.secureCookies': 'Session cookie Secure attribute',
     'hint.secureCookies': 'Auto = Secure when TLS or a trusted terminator is declared. Set false when the trusted proxy only authenticates over plaintext and browsers reach it over http — otherwise browsers drop the Secure cookie and every login bounces back to the login page',
     'opt.auto': 'Auto',
@@ -179,13 +172,13 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     'field.tlsMode': 'Certificate source',
     'hint.tlsMode': 'self-signed = auto-generated certificate; custom = your own files',
     'field.tlsSelfSignedHosts': 'Self-signed hosts (SANs)',
-    'hint.tlsSelfSignedHosts': 'Comma separated DNS/IP names, e.g. localhost, 192.168.1.5',
+    'hint.tlsSelfSignedHosts': 'Comma separated DNS/IP names, e.g. localhost, 192.168.1.5. Applies to the next issuance only: an existing certificate is reused until it expires',
     'field.tlsCertPath': 'Certificate path (custom)',
     'hint.tlsCertPath': 'Absolute path to a PEM certificate (or chain)',
     'field.tlsKeyPath': 'Private key path (custom)',
     'hint.tlsKeyPath': 'Absolute path to the matching PEM private key',
     'field.tlsCertMaxAgeDays': 'Self-signed validity (days)',
-    'hint.tlsCertMaxAgeDays': 'Default 825 (about 27 months)',
+    'hint.tlsCertMaxAgeDays': 'Default 825 (about 27 months). Applies to the next issuance only: an existing certificate is reused until it expires',
   },
 }
 
@@ -194,91 +187,13 @@ function labels(): Labels {
   return lang.startsWith('zh') ? LABELS.zh : LABELS.en
 }
 
-/* ------------------------------------------------------------------ */
-/* Field model                                                         */
-/* ------------------------------------------------------------------ */
-
-type FieldKind = 'boolean' | 'number' | 'text' | 'cidrs' | 'select' | 'tristate'
-
-interface FieldDef {
-  field: keyof LanGatewaySettings
-  kind: FieldKind
-  optional?: boolean
-  options?: readonly string[]
-}
-
 /**
- * The card's field table and its two value codecs are exported for tests: the
- * tri-state codec is the load-bearing part of the settings round-trip (an
- * unset value must stay distinguishable from an explicit false, or the
- * plaintext-proxy escape hatch silently reverts).
+ * The card's title in the browser's language, for the Plugins page's list
+ * entry. A thunk so the label follows the page's locale without re-registering.
+ * @returns the localized card title.
  */
-export { TRISTATE_OPTIONS, FIELDS, formatValue, parseValue }
-export type { FieldDef, Write }
-
-/** The three states of a tri-state field, in display order. */
-const TRISTATE_OPTIONS = ['auto', 'true', 'false'] as const
-
-const FIELDS: readonly FieldDef[] = [
-  { field: 'enabled', kind: 'boolean' },
-  { field: 'gatewayPort', kind: 'number' },
-  { field: 'dshTargetPort', kind: 'number', optional: true },
-  { field: 'lanCidrs', kind: 'cidrs' },
-  { field: 'lanPasswordless', kind: 'boolean' },
-  { field: 'cookieMaxAgeDays', kind: 'number' },
-  { field: 'tlsEnabled', kind: 'boolean' },
-  { field: 'tlsMode', kind: 'select', options: ['self-signed', 'custom'] },
-  { field: 'tlsSelfSignedHosts', kind: 'text' },
-  { 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 },
-  { field: 'secureCookies', kind: 'tristate' },
-]
-
-function formatValue(def: FieldDef, value: unknown): string {
-  switch (def.kind) {
-    case 'boolean': return value === true ? 'true' : 'false'
-    case 'number': return typeof value === 'number' ? String(value) : ''
-    case 'cidrs': return Array.isArray(value) ? value.join(', ') : ''
-    case 'select': return typeof value === 'string' ? value : (def.options?.[0] ?? '')
-    // Tri-state: an unset value is a distinct third state ("auto"), never "false".
-    case 'tristate': return value === true ? 'true' : value === false ? 'false' : 'auto'
-    case 'text': return typeof value === 'string' ? value : ''
-  }
-}
-
-type Write = { kind: 'set'; value: unknown } | { kind: 'clear' }
-
-/** Parse draft text into a value for the POST body; undefined blocks saving. */
-function parseValue(def: FieldDef, text: string): Write | undefined {
-  const trimmed = text.trim()
-  switch (def.kind) {
-    case 'boolean':
-      if (trimmed === 'true') return { kind: 'set', value: true }
-      if (trimmed === 'false') return { kind: 'set', value: false }
-      return undefined
-    case 'number':
-      if (trimmed === '') return def.optional ? { kind: 'clear' } : undefined
-      if (!/^\d+$/.test(trimmed)) return undefined
-      return { kind: 'set', value: Number(trimmed) }
-    case 'cidrs': {
-      const cidrs = trimmed.split(',').map(s => s.trim()).filter(s => s !== '')
-      return cidrs.length === 0 ? { kind: 'clear' } : { kind: 'set', value: cidrs }
-    }
-    case 'select':
-      return def.options?.includes(trimmed) ? { kind: 'set', value: trimmed } : undefined
-    case 'tristate':
-      // 'auto' clears the key so it re-inherits the composition layer (and the
-      // resolution rule), which is what an unset tri-state means.
-      if (trimmed === 'auto') return { kind: 'clear' }
-      if (trimmed === 'true') return { kind: 'set', value: true }
-      if (trimmed === 'false') return { kind: 'set', value: false }
-      return undefined
-    case 'text':
-      return trimmed === '' ? (def.optional ? { kind: 'clear' } : undefined) : { kind: 'set', value: trimmed }
-  }
+export function cardTitle(): string {
+  return labels().title
 }
 
 /* ------------------------------------------------------------------ */
@@ -288,10 +203,14 @@ function parseValue(def: FieldDef, text: string): Write | undefined {
 /**
  * Render the LAN gateway card. Self-loading: fetches the config route on
  * mount, posts the edited config on save.
- * @param _props - unused; the card needs no injected face.
- * @returns the card, or nothing while the route is unreachable.
+ *
+ * `view` swaps between the card's one-liner and its page body, so the branch
+ * sits after the hooks: the Plugins page re-renders one contribution under the
+ * other view when the card is opened.
+ * @param props - the view the Plugins page is asking for.
+ * @returns the one-liner, the card, or nothing while the route is unreachable.
  */
-export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
+export function LanGatewayCard(props: LanGatewayCardProps): ReactNode {
   const t = labels()
   const [open, setOpen] = useState(false)
   const [route, setRoute] = useState<RouteState | null>(null)
@@ -314,7 +233,32 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
     return () => { cancelled = true }
   }, [])
 
-  if (loadFailed) return null
+  // The Plugins page lists this plugin as one card and opens its own page on
+  // demand: `summary` is the one-liner the list shows, `page` the body. The
+  // hooks above run for both views, because the same contribution flips
+  // between them.
+  if (props.view === 'summary') return t.description
+
+  // A remote browser reaches this card through the gateway, which answers 403
+  // for the plugin's own prefix by design, so the route is unreachable exactly
+  // where a user is most likely to go looking for the setting. Rendering
+  // nothing left them with a blank entry and no way to tell a missing card from
+  // a broken one; say what is wrong and where the card does work instead.
+  if (loadFailed) {
+    return (
+      <div style={styles.card}>
+        <div style={styles.header}>
+          <span style={styles.headerTop}>
+            <span style={styles.name}>{t.title}</span>
+          </span>
+          <span style={styles.description}>{t.loadFailed}</span>
+        </div>
+        <div style={styles.body}>
+          <p style={styles.hint}>{t.readOnly}</p>
+        </div>
+      </div>
+    )
+  }
   if (route === null) return null
 
   const { config } = route
@@ -352,18 +296,22 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
     setSaving(true)
     setFailed(null)
     try {
-      // Build the next full config: the loaded one with drafts applied.
-      const next: Record<string, unknown> = {}
-      for (const def of FIELDS) {
-        const text = drafts[def.field] ?? formatValue(def, config[def.field])
-        const write = parseValue(def, text)
+      // A patch of the edited fields only, never the whole config: the card
+      // cannot express every key the section may hold (a custom `cookieName`,
+      // say), and posting a synthesized full config made the route treat those
+      // keys as submitted — resetting each one to its schema default.
+      const patch: Record<string, unknown> = {}
+      for (const [field, text] of Object.entries(drafts)) {
+        const def = FIELDS.find(f => f.field === field)
+        if (def === undefined) continue
+        const write = parseValue(def, text ?? '')
         if (write === undefined) continue
-        next[def.field] = write.kind === 'clear' ? null : write.value
+        patch[field] = write.kind === 'clear' ? null : write.value
       }
       const response = await fetch('/lan-gateway/config', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(next),
+        body: JSON.stringify(patch),
       })
       const body = await response.json().catch(() => ({})) as Partial<RouteState> & { error?: string }
       if (!response.ok) {
@@ -473,7 +421,7 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
   const statusLine = `${route.running ? t.running : t.stopped} · ${t.tls}: ${route.tls} · :${route.port}`
 
   return (
-    <li style={open ? { ...styles.card, ...styles.cardOpen } : styles.card}>
+    <div style={open ? { ...styles.card, ...styles.cardOpen } : styles.card}>
       <button
         type="button"
         style={styles.header}
@@ -515,7 +463,7 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
           </div>
         )
         : null}
-    </li>
+    </div>
   )
 }