@riceawa/dsh-lan-gateway 0.5.4 → 0.6.0

package/src/index.ts

@@ -43,12 +43,24 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { randomBytes } from 'node:crypto'
-import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { IncomingMessage, ServerResponse } from 'http'
 import z from '@deepseek-ai/schemastery'
-import type { SettingsScope } from '@deepseek-ai/dsh-settings'
+// Type-only: the `settings` service (0.1.7 addresses a write by profile entry
+// id) and the Loader's `fiber.entry`, which is where this plugin reads its own
+// entry id from.
+import type SettingsService from '@deepseek-ai/dsh-settings'
+import type {} from '@deepseek-ai/cordis-plugin-loader'
 import { DEFAULT_LAN_CIDR_STRINGS, originMatchesHost } from './auth.ts'
+import {
+  CONFIG_FIELD_KEYS,
+  OPTIONAL_CONFIG_KEYS,
+} from './config-fields.ts'
 import { LanGateway } from './gateway.ts'
 import { readBody } from './login.ts'
+import {
+  isLoopbackHost,
+  READ_ONLY_METHODS,
+} from './request-policy.ts'
 import {
   loadState,
   saveState,
@@ -57,10 +69,10 @@ import {
 } from './state.ts'
 import {
   describeCert,
-  loadCustomCert,
-  loadOrCreateSelfSigned,
   loadOrRenewSelfSigned,
+  loadCustomCert,
   parseSelfSignedHosts,
+  readSelfSignedStatus,
   regenerateSelfSigned,
   type TlsMaterial,
 } from './tls.ts'
@@ -132,12 +144,17 @@ export interface Config {
   /**
    * Removed capability: authentication is always required. Retained only so an
    * explicit legacy `authRequired: false` is rejected loudly instead of
-   * silently ignored.
+   * silently ignored. Not card-editable and never written back to the user
+   * section — the config route builds its patch from the editable key set.
    */
   authRequired?: boolean
   /** Session cookie lifetime in days. */
   cookieMaxAgeDays: number
-  /** Cookie name. */
+  /**
+   * Cookie name. Deliberately not card-editable — see the editable key set in
+   * `config-fields.ts`; the config route applies a patch, so an operator's
+   * custom name survives every save from the Settings card.
+   */
   cookieName: string
   /** Whether the gateway listener speaks TLS. */
   tlsEnabled: boolean
@@ -147,7 +164,13 @@ export interface Config {
   tlsCertPath?: string
   /** Custom mode: path to the PEM private key. */
   tlsKeyPath?: string
-  /** Self-signed mode: comma/space separated DNS names and IPs for the SANs. */
+  /**
+   * Self-signed mode: comma/space separated DNS names and IPs for the SANs.
+   *
+   * Read when a certificate is generated, not when it is served: changing it
+   * does not replace a certificate that already exists and is still valid. Use
+   * `lan_gateway tls-regenerate` for that.
+   */
   tlsSelfSignedHosts?: string
   /**
    * Self-signed certificate validity in days (default 825 ≈ 27 months).
@@ -160,6 +183,8 @@ export interface Config {
    * self-signed certificate is either clicked through or trusted by hand,
    * there is nothing to gain from the shorter window and a re-trust to lose
    * every time it lapses.
+   *
+   * Like `tlsSelfSignedHosts`, this applies to the next generation only.
    */
   tlsCertMaxAgeDays: number
   /**
@@ -171,6 +196,11 @@ export interface Config {
    * An identifier for a trusted TLS-terminating proxy in front of the gateway.
    * Declaring one marks the ingress encrypted (Secure cookies, passes the
    * encrypted-ingress gate) without this listener sending HSTS.
+   *
+   * Note the coupling with login rate limiting: the limiter is keyed by
+   * `socket.remoteAddress`, and `X-Forwarded-For` is deliberately untrusted, so
+   * behind such a proxy every browser shares one bucket — the login budget
+   * becomes per-deployment, not per-client.
    */
   trustedTerminator?: string
   /**
@@ -183,38 +213,112 @@ export interface Config {
   secureCookies?: boolean
 }
 
+/** A `.volatile()` config field as the Loader hands it to `apply`. */
+export interface ConfigRef<T> {
+  /** The current value; updated in place when the profile entry is written. */
+  get(): T
+}
+
+/**
+ * The config object `apply` receives: dsh 0.1.7 hands every `.volatile()` field
+ * over as a reference rather than a value, so the plugin reads its live config
+ * through `readConfig`. A field declared optional and left unset resolves to
+ * `undefined` instead of a reference, hence the union inside `ConfigRef`.
+ */
+export type ConfigRefs = { [K in keyof Required<Config>]: ConfigRef<Config[K]> }
+
 /**
- * The `lan-gateway` user-settings namespace, mirroring the composition schema.
- * A plain string literal: dsh-settings dropped the `settingsNamespace()` brand
- * helper in 0.1.2-rc.1 and `register` validates the literal itself, so this
- * shape works against both that release line and the older branded one.
+ * Schemastery configuration validated by the Loader.
+ *
+ * Every field is `.volatile()`, which is what lets the Settings service write
+ * it: 0.1.7 projects only volatile fields into forms and refuses an edit to any
+ * other path (`not volatile`). The mark also changes the runtime shape — a
+ * volatile field arrives as a reference (see `ConfigRefs`), never as the plain
+ * value the rest of this file expects — so read it through `readConfig`.
  */
-const NS = 'lan-gateway'
-
-/** Optional config keys: an empty submitted value clears them back to the composition layer. */
-const OPTIONAL_CONFIG_KEYS = new Set(['dshTargetPort', 'tlsCertPath', 'tlsKeyPath', 'trustedTerminator'])
-
-/** Schemastery configuration validated by the Loader. */
-export const Config: z<Config> = z.object({
-  enabled: z.boolean().default(false),
-  gatewayPort: z.natural().min(1).max(65535).default(3081),
-  dshTargetPort: z.natural().min(1).max(65535),
-  lanCidrs: z.array(String).default([...DEFAULT_LAN_CIDR_STRINGS]),
-  lanPasswordless: z.boolean().default(false),
-  authRequired: z.boolean().default(true),
-  cookieMaxAgeDays: z.natural().min(1).max(365).default(7),
-  cookieName: z.string().default('dsh_gw_auth'),
-  tlsEnabled: z.boolean().default(false),
-  tlsMode: z.union([z.const('self-signed'), z.const('custom')]).default('self-signed'),
-  tlsCertPath: z.string(),
-  tlsKeyPath: z.string(),
-  tlsSelfSignedHosts: z.string().default('localhost'),
-  tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825),
-  allowInsecurePlaintext: z.boolean().default(false),
-  trustedTerminator: z.string(),
-  secureCookies: z.boolean(),
+export const Config = z.object({
+  enabled: z.boolean().default(false).volatile(),
+  gatewayPort: z.natural().min(1).max(65535).default(3081).volatile(),
+  dshTargetPort: z.natural().min(1).max(65535).volatile(),
+  lanCidrs: z.array(String).default([...DEFAULT_LAN_CIDR_STRINGS]).volatile(),
+  lanPasswordless: z.boolean().default(false).volatile(),
+  authRequired: z.boolean().default(true).volatile(),
+  cookieMaxAgeDays: z.natural().min(1).max(365).default(7).volatile(),
+  cookieName: z.string().default('dsh_gw_auth').volatile(),
+  tlsEnabled: z.boolean().default(false).volatile(),
+  tlsMode: z.union([z.const('self-signed'), z.const('custom')]).default('self-signed').volatile(),
+  tlsCertPath: z.string().volatile(),
+  tlsKeyPath: z.string().volatile(),
+  tlsSelfSignedHosts: z.string().default('localhost').volatile(),
+  tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825).volatile(),
+  allowInsecurePlaintext: z.boolean().default(false).volatile(),
+  trustedTerminator: z.string().volatile(),
+  secureCookies: z.boolean().volatile(),
 })
 
+/**
+ * Unwrap the config references into the plain values every other function in
+ * this file reads. Called on each access rather than once, because a settings
+ * write updates the references in place.
+ * @param refs - the config object handed to `apply`.
+ * @returns one detached plain snapshot.
+ */
+export function readConfig(refs: ConfigRefs): Config {
+  const dshTargetPort = refs.dshTargetPort?.get()
+  const authRequired = refs.authRequired?.get()
+  const tlsCertPath = refs.tlsCertPath?.get()
+  const tlsKeyPath = refs.tlsKeyPath?.get()
+  const tlsSelfSignedHosts = refs.tlsSelfSignedHosts?.get()
+  const trustedTerminator = refs.trustedTerminator?.get()
+  const secureCookies = refs.secureCookies?.get()
+  return {
+    enabled: refs.enabled.get(),
+    gatewayPort: refs.gatewayPort.get(),
+    lanCidrs: [...refs.lanCidrs.get()],
+    lanPasswordless: refs.lanPasswordless.get(),
+    cookieMaxAgeDays: refs.cookieMaxAgeDays.get(),
+    cookieName: refs.cookieName.get(),
+    tlsEnabled: refs.tlsEnabled.get(),
+    tlsMode: refs.tlsMode.get(),
+    tlsCertMaxAgeDays: refs.tlsCertMaxAgeDays.get(),
+    allowInsecurePlaintext: refs.allowInsecurePlaintext.get(),
+    // `exactOptionalPropertyTypes` is on, so an absent optional key must stay
+    // absent rather than be assigned `undefined`. Every field here has a schema
+    // default or is genuinely optional, so an absent reference means unset.
+    ...(dshTargetPort !== undefined ? { dshTargetPort } : {}),
+    ...(authRequired !== undefined ? { authRequired } : {}),
+    ...(tlsCertPath !== undefined ? { tlsCertPath } : {}),
+    ...(tlsKeyPath !== undefined ? { tlsKeyPath } : {}),
+    ...(tlsSelfSignedHosts !== undefined ? { tlsSelfSignedHosts } : {}),
+    ...(trustedTerminator !== undefined ? { trustedTerminator } : {}),
+    ...(secureCookies !== undefined ? { secureCookies } : {}),
+  }
+}
+
+/**
+ * Build the reference-shaped config `apply` receives, exactly as the Loader
+ * builds it. Exported for tests that drive `apply` directly.
+ * @param raw - a config object; missing fields take their schema defaults.
+ * @returns one reference per volatile field.
+ */
+export function configRefs(raw: object): ConfigRefs {
+  return Config(raw) as unknown as ConfigRefs
+}
+
+/**
+ * Validate a raw config object the way the Loader does, and unwrap it.
+ *
+ * `Config` marks every field volatile, so a validation hands the values back as
+ * references (typed deeply-readonly by schemastery); this returns the plain
+ * shape the rest of the file reads. Used to judge a config the Settings card is
+ * about to save, before it is persisted.
+ * @param raw - a config object; missing fields take their schema defaults.
+ * @returns the validated plain config.
+ */
+export function validateConfig(raw: object): Config {
+  return readConfig(configRefs(raw))
+}
+
 /** Facts the fail-closed start guard needs to judge a config. */
 export interface StartFacts {
   /** Whether the dsh base enforces browser-session auth (auto-detected). */
@@ -315,35 +419,29 @@ function listenerKey(cfg: Config, relayAvailable: boolean): string {
   ])
 }
 
-/** One-line TLS description for status output. */
+/**
+ * One-line TLS description for status output.
+ *
+ * Never generates: this is the read path behind `GET /lan-gateway/config` and
+ * `lan_gateway status`, and a status query that mints an RSA key and writes a
+ * certificate to disk is not a read. The material is created when the listener
+ * starts, or by `lan_gateway tls-regenerate`.
+ */
 function tlsStatusLine(cfg: Config): string {
   if (!cfg.tlsEnabled) return 'off'
   if (cfg.tlsMode === 'custom') {
     return `custom (${cfg.tlsCertPath ?? '?'}, ${cfg.tlsKeyPath ?? '?'})`
   }
   try {
-    const hosts = parseSelfSignedHosts(cfg.tlsSelfSignedHosts)
-    const { material } = loadOrCreateSelfSigned({ hosts, days: cfg.tlsCertMaxAgeDays })
-    const info = describeCert(material.cert)
+    const status = readSelfSignedStatus()
+    if (status === undefined) return 'self-signed (not generated yet — created when the listener starts)'
+    const info = describeCert(status.cert)
     return `self-signed [${info.subject}] exp ${info.validTo}`
   } catch (error) {
     return `self-signed (unavailable: ${error instanceof Error ? error.message : String(error)})`
   }
 }
 
-/** Whether `hostname` is loopback (127/8, localhost, ::1). */
-function isLoopbackHost(hostname: string): boolean {
-  if (hostname === 'localhost' || hostname === '[::1]' || hostname === '::1') return true
-  const parts = hostname.split('.')
-  return (
-    parts.length === 4
-    && parts[0] === '127'
-    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
-  )
-}
-
-const READ_ONLY_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
-
 /**
  * Same-origin loopback fence for the native `/lan-gateway/config` route. The
  * gateway refuses to relay this prefix, so the only way in is the native
@@ -370,22 +468,107 @@ export function isTrustedConfigRequest(req: IncomingMessage): boolean {
   return true
 }
 
-export function apply(ctx: Context, config: Config): void {
+/**
+ * Turn a submitted config patch into the next user section: only keys the card
+ * can edit, only real values, and `null` (or an emptied optional) removes the
+ * key rather than storing it.
+ *
+ * The patch is built from the *submitted* object, never from a schema call's
+ * output. Schemastery fills defaults into whatever it validates and passes
+ * unknown keys through, so deriving the section from `Config(submitted)` wrote
+ * `authRequired: true` (a capability that exists only to be refused) and any
+ * stray key into the user's settings on every save — and, because it also
+ * materialized `cookieName`, reset an operator's custom cookie name to the
+ * schema default.
+ *
+ * A `null` value is the card's clear: the key is dropped from the patch, which
+ * leaves it absent from the section, so it re-inherits the composition layer.
+ */
+export function buildConfigPatch(submitted: Record<string, unknown>): {
+  patch: Record<string, unknown>
+  clear: string[]
+  unknown: string[]
+} {
+  const patch: Record<string, unknown> = {}
+  const clear: string[] = []
+  const unknown: string[] = []
+  for (const [key, value] of Object.entries(submitted)) {
+    if (!CONFIG_FIELD_KEYS.has(key)) {
+      unknown.push(key)
+      continue
+    }
+    if (value === null || value === undefined) {
+      clear.push(key)
+      continue
+    }
+    if (typeof value === 'string' && value === '' && OPTIONAL_CONFIG_KEYS.has(key)) {
+      clear.push(key)
+      continue
+    }
+    // An empty string on a non-optional text field is a real value the card
+    // refuses to submit, but a hand-written POST could send one; let the schema
+    // reject it rather than inventing a meaning here.
+    patch[key] = value
+  }
+  return { patch, clear, unknown }
+}
+
+export function apply(ctx: Context, config: ConfigRefs): void {
   let state = loadState()
   let gateway: LanGateway | undefined
   let startedWith: string | undefined
   let lastError: string | undefined
+  /**
+   * The operator's run intent, used only while no settings service is attached.
+   * With settings present, `enabled` in the settings section *is* the intent —
+   * the card and the tool write the same field, so there is one truth rather
+   * than two that disagree.
+   */
   let manualOverride: boolean | undefined
   /** Whether the base enforces browser-session auth; set once `connection` is seen. */
   let upstreamSessionAvailable = false
+  /**
+   * Identifies the current `connection` handler. A provider that detaches and a
+   * new one that attaches run their disposers in an order the plugin does not
+   * control, and a stale disposer clearing `makeRelay` would strand the live
+   * provider — so a disposer only acts if it is still the latest generation.
+   */
+  let connectionGeneration = 0
   /** Builds a fresh shared-session relay for a dsh port, once the base supports sessions. */
   let makeRelay: ((dshPort: number) => UpstreamSession) | undefined
-  /** The authoritative config: settings section when attached, else composition. */
-  let configSource: () => Config = () => config
-  /** Serializes listener start/stop/restart so settings changes cannot race. */
-  let syncing: Promise<void> = Promise.resolve()
+  /** Whether the settings service is attached, so writes reach the profile entry. */
+  let settingsAttached = false
+  /**
+   * This plugin's own Loader entry id. dsh 0.1.7 addresses a settings write by
+   * the *entry id* — the `lan-gateway` namespace this plugin used to register
+   * with is gone along with `settingsScope`.
+   */
+  let settingsEntryId: string | undefined
+  /**
+   * The settings service, for the one write a merge patch cannot express: a key
+   * must be *removed* to re-inherit the composition layer, and only its
+   * path-addressed `mutate` can unset one.
+   */
+  let settingsProvider: SettingsService | undefined
+  /**
+   * One queue for every lifecycle side effect. Settings changes, tool commands,
+   * credential changes, TLS regeneration and plugin disposal all land here, so
+   * two of them can never interleave a stop with a start.
+   */
+  let lifecycle: Promise<void> = Promise.resolve()
+  /** Set by the dispose hook; a start that completes after it must undo itself. */
+  let disposed = false
 
-  const effective = (): Config => configSource()
+  const effective = (): Config => readConfig(config)
+
+  /** Queue one lifecycle action behind every action already running. */
+  const enqueue = (reason: string, action: () => Promise<void>): Promise<void> => {
+    lifecycle = lifecycle.then(action).catch((error: unknown) => {
+      lastError = error instanceof Error ? error.message : String(error)
+      ctx.logger.warn(`dsh-lan-gateway: ${reason}: ${lastError}`)
+    })
+    return lifecycle
+  }
 
   const startGateway = async (cfg: Config): Promise<void> => {
     if (gateway !== undefined) return
@@ -420,6 +603,13 @@ export function apply(ctx: Context, config: Config): void {
       },
     }, state)
     await next.listen()
+    // The listen above is asynchronous and the tree can be disposed while it is
+    // in flight. Publishing the listener after that would leave a socket owned
+    // by nobody — the dispose hook already ran and saw `gateway` undefined.
+    if (disposed) {
+      await next.close()
+      return
+    }
     gateway = next
     startedWith = listenerKey(cfg, makeRelay !== undefined)
     ctx.logger.info(
@@ -445,46 +635,72 @@ export function apply(ctx: Context, config: Config): void {
     }
   }
 
+  /** The config the listener should be running under, intent included. */
+  const desiredConfig = (): Config => {
+    const cfg = effective()
+    // Without a settings service there is nowhere to record the tool's intent,
+    // so it lives in memory as an override on the composition entry. With one
+    // attached, the profile entry's `enabled` already carries it and an override
+    // would shadow the card — the defect this replaces.
+    if (settingsAttached) return cfg
+    return manualOverride === undefined ? cfg : { ...cfg, enabled: manualOverride }
+  }
+
   /** Reconcile the listener with the effective config (start/stop/restart). */
   const syncGateway = (reason: string): Promise<void> => {
-    syncing = syncing.then(async () => {
+    return enqueue(reason, async () => {
       lastError = undefined
-      const cfg = effective()
-      const shouldRun = manualOverride ?? cfg.enabled
-      try {
-        if (gateway === undefined) {
-          if (shouldRun) await startGateway(cfg)
-        } else if (!shouldRun) {
-          await stopGateway()
-        } else if (startedWith !== listenerKey(cfg, makeRelay !== undefined)) {
-          await stopGateway()
-          await startGateway(cfg)
-        }
-      } catch (error) {
-        lastError = error instanceof Error ? error.message : String(error)
-        ctx.logger.warn(`dsh-lan-gateway: ${reason}: ${lastError}`)
+      if (disposed) return
+      const cfg = desiredConfig()
+      if (gateway === undefined) {
+        if (cfg.enabled) await startGateway(cfg)
+      } else if (!cfg.enabled) {
+        await stopGateway()
+      } else if (startedWith !== listenerKey(cfg, makeRelay !== undefined)) {
+        await stopGateway()
+        await startGateway(cfg)
       }
     })
-    return syncing
   }
 
-  // The tunables also live in the `lan-gateway` settings section: while the
-  // settings service exists, the section (composition base + user overrides)
-  // is the authoritative config, and every committed change re-syncs the
-  // listener — so the Settings → Plugins page adjusts the gateway live.
-  // Registered directly (not via installSettingsSection) so the scope handle
-  // is available to the /lan-gateway/config route for writes.
-  let settingsScope: SettingsScope<Config> | undefined
+  /** Record the run intent where it will survive: the profile entry, or memory. */
+  const setRunIntent = async (enabled: boolean): Promise<void> => {
+    if (settingsAttached && settingsProvider !== undefined && settingsEntryId !== undefined) {
+      // The same field the Settings card writes, in this plugin's own profile
+      // entry. A merge patch, so nothing else in the entry is disturbed.
+      await settingsProvider.update(settingsEntryId, { enabled })
+      // The write updates the config references in place and the loader then
+      // emits `loader/volatile-update`, which queues the reconcile; waiting on
+      // that here would deadlock behind this same write.
+      return
+    }
+    manualOverride = enabled
+  }
+
+  // The tunables live in this plugin's own profile entry, and dsh 0.1.7 reaches
+  // it by *entry id*: the `lan-gateway` settings namespace this plugin used to
+  // register (and the scope handle it wrote through) no longer exist. The entry
+  // id is the Loader's, so it comes from the fiber; without a Loader there is no
+  // entry to write and the composition value stands alone.
   ctx.inject(['settings'], (sctx) => {
-    const scope = sctx.settings.register(NS, Config, { base: config })
-    settingsScope = scope
-    configSource = () => scope.get()
-    sctx.effect(() => scope.watch(() => { void syncGateway('settings change') }))
+    const entryId = ctx.fiber.entry?.options.id
+    if (entryId === undefined) return
+    settingsEntryId = entryId
+    settingsProvider = sctx.settings
+    settingsAttached = true
+    // This plugin ships its own card, so it owns its page policy.
+    sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber))
+    // A committed write updates the volatile references in place (no remount)
+    // and emits this, so the listener follows the new config.
+    sctx.effect(() => ctx.on('loader/volatile-update', () => { void syncGateway('settings change') }))
     sctx.effect(() => () => {
-      // The settings provider went away (disposal / provider reload): fall
-      // back to the composition entry so the plugin keeps working as composed.
-      configSource = () => config
-      settingsScope = undefined
+      // The settings service went away (disposal / provider reload): the
+      // composition entry is authoritative again, and the tool's intent falls
+      // back to memory. Reconcile so the listener follows it.
+      settingsEntryId = undefined
+      settingsProvider = undefined
+      settingsAttached = false
+      void syncGateway('settings detach')
     })
     void syncGateway('settings attach')
   })
@@ -495,6 +711,7 @@ export function apply(ctx: Context, config: Config): void {
   // relay exchanges. Optional: on an older base the callback never runs, the
   // gateway forwards without a relay, and lanPasswordless stays refused.
   ctx.inject(['connection'], (ccx) => {
+    const generation = ++connectionGeneration
     upstreamSessionAvailable = true
     ctx.logger.info('dsh-lan-gateway: connection service attached; upstream session relay enabled')
     makeRelay = (dshPort) => new UpstreamSessionRelay({
@@ -504,6 +721,15 @@ export function apply(ctx: Context, config: Config): void {
       // and looks exactly like a base with no browser sessions.
       log: (message) => ctx.logger.info(`dsh-lan-gateway relay: ${message}`),
     })
+    ccx.effect(() => () => {
+      // The provider went away. Drop the relay factory rather than hold one
+      // bound to a disposed context, and let the listenerKey see the change so
+      // the running listener does not keep serving through a dead provider.
+      if (generation !== connectionGeneration) return
+      makeRelay = undefined
+      upstreamSessionAvailable = false
+      void syncGateway('connection detach')
+    })
     // A listener that started before the connection service appeared must
     // restart so it picks up the relay (and the now-correct fail-closed facts).
     void syncGateway('connection attach')
@@ -516,6 +742,17 @@ export function apply(ctx: Context, config: Config): void {
   // reach it — a genuine local user, or a local process that could already read
   // ~/.dsh.
   const configRouteHandler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const snapshot = (): Record<string, unknown> => {
+      const cfg = effective()
+      return {
+        config: cfg,
+        running: gateway !== undefined,
+        port: cfg.gatewayPort,
+        tls: tlsStatusLine(cfg),
+        upstreamSessionAvailable,
+        lastError: lastError ?? null,
+      }
+    }
     const send = (status: number, body: unknown): void => {
       res.writeHead(status, { 'content-type': 'application/json' })
       res.end(JSON.stringify(body))
@@ -525,15 +762,7 @@ export function apply(ctx: Context, config: Config): void {
       return
     }
     if (req.method === 'GET') {
-      const cfg = effective()
-      send(200, {
-        config: cfg,
-        running: gateway !== undefined,
-        port: cfg.gatewayPort,
-        tls: tlsStatusLine(cfg),
-        upstreamSessionAvailable,
-        lastError: lastError ?? null,
-      })
+      send(200, snapshot())
       return
     }
     if (req.method !== 'POST') {
@@ -553,20 +782,23 @@ export function apply(ctx: Context, config: Config): void {
       send(400, { error: 'body must be a config object' })
       return
     }
-    // The schema callable validates and fills defaults; it throws with a
-    // descriptive message on any invalid value.
-    let candidate: Config
-    try {
-      candidate = Config(submitted as Config)
-    } catch (error) {
-      send(400, { error: error instanceof Error ? error.message : String(error) })
-      return
-    }
-    if (settingsScope === undefined) {
+    // A settings write is addressed by this plugin's profile entry id; without
+    // one (no Loader, or no settings service) the composition value is all there
+    // is, and the operator edits the profile patch instead.
+    const settings = settingsProvider
+    const entryId = settingsEntryId
+    if (settings === undefined || entryId === undefined) {
       send(409, { error: 'settings service unavailable — edit the profile patch (cordis.patch.yml) instead' })
       return
     }
-    // Fail the save early (before persisting) when the candidate is unusable.
+    // The patch names only the keys the card can edit; a clear is expressed by
+    // omitting the key from the patch, which is what `unset` does to the section
+    // as it stands. Unknown keys are reported rather than silently stored.
+    const { patch, clear, unknown } = buildConfigPatch(submitted as Record<string, unknown>)
+    // Validate the candidate the patch would produce — schema defaults included,
+    // exactly as the listener will resolve it — so the save fails closed on an
+    // unusable combination instead of persisting it.
+    const candidate = validateConfig({ ...effective(), ...patch })
     // A structural problem (legacy authRequired:false, lanPasswordless without
     // a session-capable base) is invalid however it is reached; a start
     // condition (plaintext without TLS/terminator/opt-in) only blocks a save
@@ -579,28 +811,26 @@ export function apply(ctx: Context, config: Config): void {
       send(409, { error: `config cannot start: ${problems.join(' ')}` })
       return
     }
-    // Build the next user section: drop null/undefined and empty optionals
-    // (an empty path field re-inherits the composition layer).
-    const section: Record<string, unknown> = {}
-    for (const [key, value] of Object.entries(candidate)) {
-      if (value === null || value === undefined) continue
-      if (typeof value === 'string' && value === '' && OPTIONAL_CONFIG_KEYS.has(key)) continue
-      section[key] = value
-    }
     try {
-      await settingsScope.replace(section)
-      // Let the listener restart settle before reporting, so `running` is
-      // accurate instead of a mid-restart snapshot.
+      const ops = [
+        ...Object.entries(patch).map(([key, value]) => ({ op: 'set' as const, path: [key], value })),
+        ...clear.map(key => ({ op: 'unset' as const, path: [key] })),
+      ]
+      // Path-addressed edits, not a merge patch: a clear has to *remove* the
+      // key so it re-inherits the composition layer. Storing null instead would
+      // leave a null where the config expects a string, and `!== undefined`
+      // tests elsewhere would then read that null as a declared value.
+      if (ops.length > 0) await settings.mutate(entryId, ops)
+      // The write commits through the section's watcher; reconcile explicitly so
+      // the response reports a settled listener rather than a mid-restart one.
       await syncGateway('config route save')
-      const cfg = effective()
-      send(200, {
-        config: cfg,
-        running: gateway !== undefined,
-        port: cfg.gatewayPort,
-        tls: tlsStatusLine(cfg),
-        upstreamSessionAvailable,
-        lastError: lastError ?? null,
-      })
+      const next = { ...snapshot() }
+      if (unknown.length > 0) {
+        // Not an error: an older client may post fields this build dropped. Say
+        // so rather than dropping them silently.
+        next['ignored'] = unknown
+      }
+      send(200, next)
     } catch (error) {
       send(409, { error: error instanceof Error ? error.message : String(error) })
     }
@@ -612,7 +842,7 @@ export function apply(ctx: Context, config: Config): void {
 
   const controller: GatewayController = {
     status(): ToolResult {
-      const cfg = effective()
+      const cfg = desiredConfig()
       const dshPort = cfg.dshTargetPort ?? ctx.webServer.port
       const encrypted = cfg.tlsEnabled || cfg.trustedTerminator !== undefined
       return {
@@ -627,21 +857,21 @@ export function apply(ctx: Context, config: Config): void {
           + `\n- upstream session relay: ${upstreamSessionAvailable ? 'active (dsh browser-session auth present)' : 'absent (older dsh base)'}`
           + `\n- ingress: ${cfg.tlsEnabled ? `TLS (${tlsStatusLine(cfg)})` : cfg.trustedTerminator !== undefined ? `trusted proxy (${cfg.trustedTerminator}, ${resolveSecureCookies(cfg) ? 'TLS' : 'plaintext'} browser ingress)` : encrypted ? 'encrypted' : cfg.allowInsecurePlaintext ? 'PLAINTEXT (explicit allowInsecurePlaintext)' : 'plaintext — will not start'}`
           + `\n- session cookie: ${cfg.cookieName}, ${cfg.cookieMaxAgeDays}d, ${resolveSecureCookies(cfg) ? 'Secure' : 'no Secure attribute (plaintext browser ingress)'}`
-          + (manualOverride !== undefined
+          + (manualOverride !== undefined && !settingsAttached
             ? `\n- manual override: ${manualOverride ? 'enabled' : 'disabled'}`
             : '')
           + (lastError !== undefined ? `\n- last error: ${lastError}` : ''),
       }
     },
     async enable(): Promise<ToolResult> {
-      manualOverride = true
+      await setRunIntent(true)
       await syncGateway('tool enable')
       return gateway !== undefined
         ? { ok: true, message: `Gateway enabled: listening on ${gateway.boundAddress()}` }
         : { ok: false, message: `Failed to enable gateway: ${lastError ?? 'unknown error'}` }
     },
     async disable(): Promise<ToolResult> {
-      manualOverride = false
+      await setRunIntent(false)
       await syncGateway('tool disable')
       return { ok: true, message: 'Gateway disabled.' }
     },
@@ -650,26 +880,29 @@ export function apply(ctx: Context, config: Config): void {
         return { ok: false, message: 'Password must be at least 8 characters.' }
       }
       const setting = password !== undefined && password.length > 0
-      const previous = state
-      state = setPassword(state, setting ? password : undefined)
+      const hadPassword = state.password !== undefined
+      state = await setPassword(state, setting ? password : undefined)
       saveState(state)
       gateway?.setState(state)
       if (!setting) {
         // Clearing the credential must not leave an open gateway serving
         // sessions the old password authorized: stop the listener. A password
         // is required to run, so a later enable fails closed.
-        manualOverride = false
-        if (gateway !== undefined) {
-          await stopGateway()
+        await setRunIntent(false)
+        return enqueue('password cleared', async () => {
+          if (gateway !== undefined) await stopGateway()
           lastError = 'Password cleared — the gateway listener was stopped (a password is required to run).'
-          void syncGateway('password cleared')
-        }
-        return {
+        }).then(() => ({
           ok: true,
           message: 'Password cleared. Session epoch advanced and the gateway listener was stopped — set a password before enabling it again.',
-        }
+        }))
       }
-      void (previous === undefined ? syncGateway('password set') : Promise.resolve())
+      // The first password turns a dormant "enabled but unpassworded" intent
+      // into a startable one, so reconcile: the listener was refused a moment
+      // ago for a reason that no longer holds. A later password change needs no
+      // reconcile (the listener is already running or already refused for some
+      // other reason), and reconciling anyway would be harmless but noisy.
+      if (!hadPassword) await syncGateway('password set')
       return {
         ok: true,
         message: 'Password set. Session epoch advanced — every previously issued session is now invalid; all sources must sign in again.',
@@ -697,29 +930,40 @@ export function apply(ctx: Context, config: Config): void {
       if (hosts.length === 0) {
         return { ok: false, message: 'tlsSelfSignedHosts must name at least one host (DNS name or IP).' }
       }
-      try {
-        regenerateSelfSigned({ hosts, days: cfg.tlsCertMaxAgeDays })
-        if (gateway !== undefined) {
-          await stopGateway()
-          await startGateway(effective())
+      let failure: string | undefined
+      // Through the queue like every other lifecycle action: minting the
+      // certificate and restarting must not interleave with a settings-driven
+      // restart, which is how two listeners ended up racing for one port.
+      await enqueue('tls regenerate', async () => {
+        try {
+          regenerateSelfSigned({ hosts, days: cfg.tlsCertMaxAgeDays })
+          if (gateway !== undefined) {
+            await stopGateway()
+            await startGateway(effective())
+          }
           lastError = undefined
+        } catch (error) {
+          failure = error instanceof Error ? error.message : String(error)
         }
-        return { ok: true, message: 'Self-signed certificate regenerated (new key). Listener restarted with the new certificate.' }
-      } catch (error) {
-        return {
-          ok: false,
-          message: `Failed to regenerate TLS certificate: ${error instanceof Error ? error.message : String(error)}`,
-        }
-      }
+      })
+      return failure === undefined
+        ? { ok: true, message: 'Self-signed certificate regenerated (new key). Listener restarted with the new certificate.' }
+        : { ok: false, message: `Failed to regenerate TLS certificate: ${failure}` }
     },
   }
 
   // Register the management tool once.
   ctx.tools.register(lanGatewayTool(controller))
 
-  // Own the gateway lifecycle with the cordis tree.
+  // Own the gateway lifecycle with the cordis tree. The dispose hook only marks
+  // the tree gone and queues the stop: everything that could be mid-flight is
+  // already holding the queue, and `startGateway` undoes its own listener when
+  // it notices the flag.
   ctx.effect(() => {
     void syncGateway('boot')
-    return stopGateway
+    return async () => {
+      disposed = true
+      await enqueue('dispose', stopGateway)
+    }
   }, 'dsh-lan-gateway: listener lifecycle')
 }