@riceawa/dsh-lan-gateway 0.5.2 → 0.5.3

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
@@ -265,6 +296,7 @@ function listenerKey(cfg: Config, relayAvailable: boolean): string {
     cfg.tlsCertMaxAgeDays,
     cfg.allowInsecurePlaintext,
     cfg.trustedTerminator,
+    cfg.secureCookies,
     relayAvailable,
   ])
 }
@@ -353,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,
@@ -360,7 +393,7 @@ 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)
@@ -435,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).
@@ -559,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. */
@@ -106,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
     }
@@ -125,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(isUpstreamSessionCookie)
+      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()
   })
 }
@@ -153,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
 
@@ -160,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. */
@@ -176,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
   }
 
@@ -195,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