@riceawa/dsh-lan-gateway 0.5.1 → 0.5.3

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

@@ -46,6 +46,7 @@ export interface LanGatewaySettings {
   tlsCertMaxAgeDays?: number
   allowInsecurePlaintext?: boolean
   trustedTerminator?: string
+  secureCookies?: boolean
 }
 
 /** GET /lan-gateway/config response. */
@@ -80,6 +81,7 @@ interface Labels {
   lastError: string
   [key: `field.${string}`]: string
   [key: `hint.${string}`]: string
+  [key: `opt.${string}`]: string
 }
 
 const LABELS: Record<'zh' | 'en', Labels> = {
@@ -114,6 +116,11 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     'hint.allowInsecurePlaintext': '危险：关闭 TLS 或受信终止代理时仍启动监听，密码与会话将以明文传输',
     'field.trustedTerminator': '受信 TLS 终止代理',
     'hint.trustedTerminator': '可选：声明前置代理标识，视为加密入口（如 nginx）。留空 = 未声明',
+    'field.secureCookies': '会话 cookie 的 Secure 属性',
+    'hint.secureCookies': '自动 = TLS 或已声明受信终止代理时加 Secure。受信代理只做明文鉴权、浏览器走 http 访问时须设为 false，否则浏览器拒收 Secure cookie，登录会无限弹回登录页',
+    'opt.auto': '自动',
+    'opt.true': '始终 Secure',
+    'opt.false': '不加 Secure（明文浏览器入口）',
     'field.cookieMaxAgeDays': '会话有效期（天）',
     'hint.cookieMaxAgeDays': '登录 cookie 的存活天数（默认 7）',
     'field.tlsEnabled': '启用 TLS（HTTPS）',
@@ -160,6 +167,11 @@ const LABELS: Record<'zh' | 'en', Labels> = {
     '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.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',
+    'opt.true': 'Always Secure',
+    'opt.false': 'No Secure (plaintext browser ingress)',
     'field.cookieMaxAgeDays': 'Session lifetime (days)',
     'hint.cookieMaxAgeDays': 'Login cookie lifetime (default 7)',
     'field.tlsEnabled': 'Enable TLS (HTTPS)',
@@ -186,7 +198,7 @@ function labels(): Labels {
 /* Field model                                                         */
 /* ------------------------------------------------------------------ */
 
-type FieldKind = 'boolean' | 'number' | 'text' | 'cidrs' | 'select'
+type FieldKind = 'boolean' | 'number' | 'text' | 'cidrs' | 'select' | 'tristate'
 
 interface FieldDef {
   field: keyof LanGatewaySettings
@@ -195,6 +207,18 @@ interface FieldDef {
   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).
+ */
+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' },
@@ -210,6 +234,7 @@ const FIELDS: readonly FieldDef[] = [
   { 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 {
@@ -218,6 +243,8 @@ function formatValue(def: FieldDef, value: unknown): string {
     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 : ''
   }
 }
@@ -242,6 +269,13 @@ function parseValue(def: FieldDef, text: string): Write | undefined {
     }
     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 }
   }
@@ -384,6 +418,11 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
           </div>
         )
       case 'select':
+      case 'tristate': {
+        // A tri-state renders as a three-way select because neither a checkbox
+        // (cannot express "unset") nor a text field (cannot express false)
+        // distinguishes auto from an explicit false.
+        const options = def.kind === 'tristate' ? TRISTATE_OPTIONS : (def.options ?? [])
         return (
           <div style={styles.field}>
             <label style={styles.label} htmlFor={`lan-gw-${field}`}>{label}</label>
@@ -394,7 +433,11 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
               disabled={saving}
               onChange={(e: ChangeEvent<HTMLSelectElement>) => stage(field, e.target.value)}
             >
-              {def.options?.map(option => <option key={option} value={option}>{option}</option>)}
+              {options.map(option => (
+                <option key={option} value={option}>
+                  {def.kind === 'tristate' ? t[`opt.${option}`] : option}
+                </option>
+              ))}
             </select>
             <span style={styles.hint}>{hint}</span>
             <button
@@ -407,6 +450,7 @@ export function LanGatewayCard(_props: LanGatewayCardProps): ReactNode {
             </button>
           </div>
         )
+      }
       default:
         return (
           <div style={styles.field}>

package/src/index.ts

@@ -158,6 +158,14 @@ export interface Config {
    * encrypted-ingress gate) without this listener sending HSTS.
    */
   trustedTerminator?: string
+  /**
+   * Explicit override for the session cookie's `Secure` attribute. Unset =
+   * automatic: Secure when the gateway serves TLS itself or a
+   * `trustedTerminator` is declared. Set `false` when the trusted proxy fronts
+   * a plaintext browser ingress — browsers refuse to store a Secure cookie over
+   * plain HTTP, so every login would bounce straight back to `/__login`.
+   */
+  secureCookies?: boolean
 }
 
 /**
@@ -189,6 +197,7 @@ export const Config: z<Config> = z.object({
   tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825),
   allowInsecurePlaintext: z.boolean().default(false),
   trustedTerminator: z.string(),
+  secureCookies: z.boolean(),
 })
 
 /** Facts the fail-closed start guard needs to judge a config. */
@@ -227,6 +236,28 @@ export function gatewayStartProblems(cfg: Config, facts: StartFacts): string[] {
   return problems
 }
 
+/**
+ * Resolve the effective `Secure` attribute for the session cookie: an explicit
+ * `secureCookies` always wins; unset falls back to automatic — Secure when the
+ * gateway terminates TLS itself or a trusted terminator is declared. The
+ * override exists for a trusted proxy that authenticates users but speaks plain
+ * HTTP to browsers: `encryptedIngress` is a fair proxy for "a proxy is in front"
+ * but not for "the browser leg is encrypted", and a Secure cookie on a plain
+ * HTTP origin is silently dropped, looping the login.
+ *
+ * Exported for tests.
+ */
+export function resolveSecureCookies(
+  cfg: Pick<Config, 'secureCookies' | 'tlsEnabled' | 'trustedTerminator'>,
+): boolean {
+  // Test for a real boolean, not just `!== undefined`: the settings route
+  // clears a key by posting null and schemastery passes that through rather
+  // than coercing it to undefined, so `null` reaches here on the save path.
+  // Only an explicit true/false overrides the automatic rule.
+  if (typeof cfg.secureCookies === 'boolean') return cfg.secureCookies
+  return cfg.tlsEnabled || cfg.trustedTerminator !== undefined
+}
+
 /** Resolve the TLS material for a config, or undefined when TLS is off. */
 function resolveTls(cfg: Config): TlsMaterial | undefined {
   if (!cfg.tlsEnabled) return undefined
@@ -241,8 +272,15 @@ function resolveTls(cfg: Config): TlsMaterial | undefined {
   return material
 }
 
-/** Config fields that require a listener restart when they change. */
-function listenerKey(cfg: Config): string {
+/**
+ * Config fields that require a listener restart when they change, plus whether
+ * a shared upstream session relay is available at all. The relay flag belongs
+ * in the key: a listener that started before the `connection` service appeared
+ * was built without a relay and must restart once the service attaches,
+ * otherwise it silently forwards every request anonymously (the upstream 401s)
+ * while the status line still claims the relay is active.
+ */
+function listenerKey(cfg: Config, relayAvailable: boolean): string {
   return JSON.stringify([
     cfg.gatewayPort,
     cfg.dshTargetPort,
@@ -258,6 +296,8 @@ function listenerKey(cfg: Config): string {
     cfg.tlsCertMaxAgeDays,
     cfg.allowInsecurePlaintext,
     cfg.trustedTerminator,
+    cfg.secureCookies,
+    relayAvailable,
   ])
 }
 
@@ -345,6 +385,7 @@ export function apply(ctx: Context, config: Config): void {
     const dshPort = cfg.dshTargetPort ?? ctx.webServer.port
     const tls = resolveTls(cfg)
     const encryptedIngress = cfg.tlsEnabled || cfg.trustedTerminator !== undefined
+    const secureCookies = resolveSecureCookies(cfg)
     const next = new LanGateway({
       gatewayPort: cfg.gatewayPort,
       dshPort,
@@ -352,13 +393,13 @@ export function apply(ctx: Context, config: Config): void {
       lanPasswordless: cfg.lanPasswordless,
       cookieMaxAgeDays: cfg.cookieMaxAgeDays,
       cookieName: cfg.cookieName,
-      secureCookies: encryptedIngress,
+      secureCookies,
       ...(tls !== undefined ? { tls } : {}),
       ...(makeRelay !== undefined ? { upstreamSession: makeRelay(dshPort) } : {}),
     }, state)
     await next.listen()
     gateway = next
-    startedWith = listenerKey(cfg)
+    startedWith = listenerKey(cfg, makeRelay !== undefined)
     ctx.logger.info(
       `dsh-lan-gateway: listening on 0.0.0.0:${cfg.gatewayPort}${tls !== undefined ? ' (TLS)' : ''}`
       + ` -> 127.0.0.1:${dshPort}${encryptedIngress ? '' : ' (plaintext, explicit allowInsecurePlaintext)'}`
@@ -387,7 +428,7 @@ export function apply(ctx: Context, config: Config): void {
           if (shouldRun) await startGateway(cfg)
         } else if (!shouldRun) {
           await stopGateway()
-        } else if (startedWith !== listenerKey(cfg)) {
+        } else if (startedWith !== listenerKey(cfg, makeRelay !== undefined)) {
           await stopGateway()
           await startGateway(cfg)
         }
@@ -427,9 +468,13 @@ export function apply(ctx: Context, config: Config): void {
   // gateway forwards without a relay, and lanPasswordless stays refused.
   ctx.inject(['connection'], (ccx) => {
     upstreamSessionAvailable = true
+    ctx.logger.info('dsh-lan-gateway: connection service attached; upstream session relay enabled')
     makeRelay = (dshPort) => new UpstreamSessionRelay({
       port: dshPort,
       authenticatedUrl: () => ccx.connection.authenticatedUrl(`http://127.0.0.1:${dshPort}`),
+      // The relay never throws, so a failing exchange is otherwise invisible
+      // and looks exactly like a base with no browser sessions.
+      log: (message) => ctx.logger.info(`dsh-lan-gateway relay: ${message}`),
     })
     // A listener that started before the connection service appeared must
     // restart so it picks up the relay (and the now-correct fail-closed facts).
@@ -551,8 +596,8 @@ export function apply(ctx: Context, config: Config): void {
           + `\n- login required for all sources: true${cfg.lanPasswordless ? ' (LAN/loopback exempt via lanPasswordless)' : ''}`
           + `\n- session epoch: ${state.sessionEpoch}`
           + `\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 ? `TLS terminated by trusted proxy (${cfg.trustedTerminator})` : encrypted ? 'encrypted' : cfg.allowInsecurePlaintext ? 'PLAINTEXT (explicit allowInsecurePlaintext)' : 'plaintext — will not start'}`
-          + `\n- session cookie: ${cfg.cookieName}, ${cfg.cookieMaxAgeDays}d`
+          + `\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
             ? `\n- manual override: ${manualOverride ? 'enabled' : 'disabled'}`
             : '')

package/src/upstream-session.ts

@@ -57,6 +57,14 @@ export interface UpstreamSessionRelayOptions {
    * upstream restart is picked up.
    */
   authenticatedUrl: () => string | undefined
+  /**
+   * Optional low-frequency debug sink: one line per acquisition attempt,
+   * exchange outcome, and invalidation. Every other failure path here is
+   * silent by design (the relay never throws), which makes a mis-named cookie
+   * or an unreachable upstream indistinguishable from "the base has no
+   * browser sessions" — wire `ctx.logger` to make that visible.
+   */
+  log?: (message: string) => void
 }
 
 /** Split `name=value; Path=/; …` into the `name=value` request-Cookie fragment. */
@@ -65,6 +73,24 @@ function nameValueOnly(setCookie: string): string {
   return (semi === -1 ? setCookie : setCookie.slice(0, semi)).trim()
 }
 
+/** The cookie name of a `Set-Cookie` string (`''` when it is malformed). */
+function cookieNameOf(setCookie: string): string {
+  const eq = setCookie.indexOf('=')
+  return eq === -1 ? '' : setCookie.slice(0, eq).trim()
+}
+
+/**
+ * Whether a `Set-Cookie` string is the upstream browser-session cookie. The
+ * name upstream mints is `dsh-auth-<base64url(sha256(authority))>`: the prefix
+ * is followed by the authority hash, never by `=` itself, so the test is a
+ * prefix plus at least one character — matching on `dsh-auth-=` finds nothing
+ * and silently relays every request anonymously.
+ */
+function isUpstreamSessionCookie(setCookie: string): boolean {
+  const name = cookieNameOf(setCookie)
+  return name.startsWith(UPSTREAM_COOKIE_PREFIX) && name.length > UPSTREAM_COOKIE_PREFIX.length
+}
+
 /** Pull the Max-Age attribute (seconds) out of a Set-Cookie string, if any. */
 function maxAgeSeconds(setCookie: string): number | undefined {
   const match = /\bMax-Age=(\d+)\b/i.exec(setCookie)
@@ -88,12 +114,14 @@ function exchange(
   url: string,
   authority: string,
   port: number,
+  log: (message: string) => void,
 ): Promise<ExchangeResult | undefined> {
   return new Promise((resolve) => {
     let target: URL
     try {
       target = new URL(url)
     } catch {
+      log(`exchange: unparseable authenticatedUrl ${url}`)
       resolve(undefined)
       return
     }
@@ -107,21 +135,33 @@ function exchange(
       const setCookies = response.headers['set-cookie']
       response.resume() // drain so the socket can be reused
       if (setCookies === undefined) {
+        log(`exchange ${target.pathname} -> ${response.statusCode} (no set-cookie)`)
         resolve(undefined)
         return
       }
-      const raw = (Array.isArray(setCookies) ? setCookies : [setCookies])
-        .find((value) => value.startsWith(`${UPSTREAM_COOKIE_PREFIX}=`))
+      const all = Array.isArray(setCookies) ? setCookies : [setCookies]
+      const raw = all.find(isUpstreamSessionCookie)
       if (raw === undefined) {
+        // Name what did come back: a missing session cookie is otherwise
+        // indistinguishable from an upstream that mints a differently-named one.
+        const names = all.map(cookieNameOf).filter((name) => name !== '')
+        log(`exchange ${target.pathname} -> ${response.statusCode} (no ${UPSTREAM_COOKIE_PREFIX}* cookie; got: ${names.join(', ') || 'none'})`)
         resolve(undefined)
         return
       }
       const header = nameValueOnly(raw)
       const maxAge = maxAgeSeconds(raw)
+      log(`exchange ${target.pathname} -> ${response.statusCode} (got ${cookieNameOf(raw)}, maxAge=${maxAge ?? 'n/a'})`)
       resolve({ header, expiresAt: Date.now() + (maxAge ?? 0) * 1000 })
     })
-    request.on('error', () => resolve(undefined))
-    request.setTimeout(5000, () => request.destroy(new Error('upstream-session exchange timeout')))
+    request.on('error', (error: Error) => {
+      log(`exchange error: ${error.message}`)
+      resolve(undefined)
+    })
+    request.setTimeout(5000, () => {
+      log('exchange timeout (5s)')
+      request.destroy(new Error('upstream-session exchange timeout'))
+    })
     request.end()
   })
 }
@@ -135,6 +175,7 @@ export class UpstreamSessionRelay implements UpstreamSession {
   private readonly port: number
   private readonly authority: string
   private readonly authenticatedUrl: () => string | undefined
+  private readonly log: (message: string) => void
   private held: HeldCookie | undefined
   private inflight: Promise<string | undefined> | undefined
 
@@ -142,6 +183,7 @@ export class UpstreamSessionRelay implements UpstreamSession {
     this.port = options.port
     this.authority = options.authority ?? `127.0.0.1:${options.port}`
     this.authenticatedUrl = options.authenticatedUrl
+    this.log = options.log ?? (() => { /* no debug sink configured */ })
   }
 
   /** Whether the held session is still comfortably inside its lifetime. */
@@ -158,6 +200,7 @@ export class UpstreamSessionRelay implements UpstreamSession {
   }
 
   invalidate(): void {
+    if (this.held !== undefined) this.log('invalidating held session (upstream rejected it)')
     this.held = undefined
   }
 
@@ -177,9 +220,22 @@ export class UpstreamSessionRelay implements UpstreamSession {
 
   private async doExchange(): Promise<string | undefined> {
     const url = this.authenticatedUrl()
-    if (url === undefined) return undefined
-    const result = await exchange(url, this.authority, this.port)
-    if (result !== undefined) this.held = result
+    if (url === undefined) {
+      // The launch URL is transiently unavailable (e.g. the connection service
+      // is mid-restart). Keep whatever is held: returning undefined here would
+      // forward with no cookie at all and draw a 401 upstream, which is worse
+      // than riding a session that is probably still valid.
+      this.log('authenticatedUrl() returned undefined; keeping current session')
+      return this.held?.header
+    }
+    this.log(`acquiring session from ${url}`)
+    const result = await exchange(url, this.authority, this.port, this.log)
+    if (result !== undefined) {
+      this.held = result
+      this.log('session acquired and cached')
+    } else {
+      this.log('exchange failed; keeping current session')
+    }
     // On a transient failure keep whatever session is still held rather than
     // dropping to anonymous.
     return this.held?.header