@riceawa/dsh-lan-gateway 0.5.3 → 0.5.5

package/src/login.ts

@@ -14,12 +14,9 @@ export const LOGIN_PATH = '/__login' as const
 /** Path the gateway owns and never forwards: signs the session out. */
 export const LOGOUT_PATH = '/__logout' as const
 
-/** The cookie name used for the signed session. */
-export const COOKIE_NAME = 'dsh_gw_auth' as const
-
 export interface LoginPageOptions {
   error?: string
-  /** Optional login attempt counter to show when rate-limited. */
+  /** The attempt was refused by the rate limiter, not by a wrong password. */
   limited?: boolean
 }
 
@@ -95,19 +92,6 @@ export function serveLoginGet(res: ServerResponse, extraHeaders: OutgoingHttpHea
   res.end(renderLoginPage())
 }
 
-/** Parse an application/x-www-form-urlencoded body into its fields. */
-export function parseFormBody(body: string): Record<string, string> {
-  const out: Record<string, string> = {}
-  for (const pair of body.split('&')) {
-    if (pair === '') continue
-    const eq = pair.indexOf('=')
-    const key = eq === -1 ? pair : pair.slice(0, eq)
-    const value = eq === -1 ? '' : pair.slice(eq + 1)
-    out[decodeURIComponent(key.replaceAll('+', ' '))] = decodeURIComponent(value.replaceAll('+', ' '))
-  }
-  return out
-}
-
 /** Read a request body up to a byte ceiling, rejecting anything larger. */
 export function readBody(req: IncomingMessage, maxBytes: number, res: ServerResponse): Promise<string | undefined> {
   return new Promise((resolve) => {

package/src/request-policy.ts

@@ -0,0 +1,315 @@
+/**
+ * Every request decision the gateway makes, as pure functions over headers,
+ * paths and config — the same treatment `auth.ts` already gives
+ * `classifySource` / `signCookie` / `originMatchesHost`. `LanGateway` keeps the
+ * `http.Server`, the socket bookkeeping and the relay; who may pass, which path
+ * the gateway owns, and what the forwarded headers look like are decided here,
+ * where a test can reach them with a literal object instead of a live socket.
+ *
+ * Nothing here reads a clock, a socket or a config file.
+ *
+ * @module @riceawa/dsh-lan-gateway/request-policy
+ */
+
+import type { IncomingHttpHeaders, OutgoingHttpHeaders } from 'node:http'
+import { originMatchesHost, type SourceClass } from './auth.ts'
+import { isUpstreamCookiePair, isUpstreamSessionCookie } from './upstream-session.ts'
+
+/** The request facts a policy decision reads. */
+export interface RequestHead {
+  /**
+   * Optional *and* explicitly undefined-able, matching how Node declares
+   * `IncomingMessage.method`. Under `exactOptionalPropertyTypes` those are two
+   * different types, and the shorter `method?: string` would reject a plain
+   * `IncomingMessage` at every call site.
+   */
+  method?: string | undefined
+  headers: IncomingHttpHeaders
+}
+
+/** Methods a browser never attaches a CSRF-meaningful body to; safe without an Origin. */
+export const READ_ONLY_METHODS: ReadonlySet<string> = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/**
+ * Headers a proxy must not forward in either direction (RFC 9110 §7.6.1), plus
+ * the non-standard proxy-connection.
+ */
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+])
+
+/**
+ * Hop-by-hop headers a successful upgrade must still carry: 101 is exactly the
+ * exchange that negotiates Connection/Upgrade, so they survive there and
+ * nowhere else.
+ */
+const UPGRADE_HANDSHAKE_HEADERS = new Set(['connection', 'upgrade'])
+
+/**
+ * Headers by which a client asserts where a request came from. The gateway
+ * classifies on `socket.remoteAddress` and never reads these, so relaying a
+ * caller's own values only hands the next hop a forgeable claim.
+ */
+const FORWARDING_HEADERS = [
+  'forwarded',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-port',
+  'x-forwarded-proto',
+  'x-real-ip',
+]
+
+/** Prefixes the gateway owns and must never relay to dsh. */
+export function isOwnedPath(pathname: string): boolean {
+  return pathname === '/lan-gateway' || pathname.startsWith('/lan-gateway/')
+}
+
+/**
+ * The pathname a request is routed by: the one dsh's router resolves it to
+ * (WHATWG URL parsing, which strips the query and collapses dot segments),
+ * with trailing slashes then removed for the gateway's own surface tests.
+ *
+ * The decision paths below (owned prefix, login, logout) must use this rather
+ * than the raw request target. dsh normalizes before matching, so a raw-string
+ * test disagrees with it on `/foo/../lan-gateway/config` — that is not an owned
+ * path by string prefix, stays in the relay, and lands on the plugin's own
+ * config route once Host has been rewritten to loopback. Forwarding still
+ * relays the raw target: dsh applies the same normalization itself.
+ *
+ * WHATWG parsing does not drop a trailing slash, and neither does dsh's
+ * router, so `/__login/` is not the login page to either of them. The gateway
+ * recognizes its own surfaces there anyway: `/__logout/` must still sign out,
+ * and `/lan-gateway/config/` must be refused rather than relayed into dsh's
+ * single-page fallback. Blocking a trailing-slash spelling of an owned prefix
+ * errs toward refusing, which costs nothing — no upstream route lives under it.
+ */
+export function pathOf(url: string): string {
+  try {
+    return new URL(url, 'http://gateway.invalid').pathname.replace(/\/+$/, '') || '/'
+  } catch {
+    // Unparseable here means unparseable for dsh too; the raw target routes
+    // nowhere and is relayed as-is.
+    return url
+  }
+}
+
+/**
+ * Whether `hostname` is loopback (127/8, localhost, ::1).
+ *
+ * This validates a URL *hostname* — the loopback fence on the gateway's own
+ * config route, where the input is the browser's Host header — so it accepts
+ * the spellings a URL parser produces, `[::1]` included. `classifySource` in
+ * `auth.ts` answers a different question about a different input (a socket
+ * address, unwrapped from its `::ffff:` mapping, and including LAN space); the
+ * two are related but not interchangeable, and neither should be rewritten in
+ * terms of the other without moving its input domain too.
+ */
+export 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)
+  )
+}
+
+/** Whether this source must present a gateway session (default: everyone). */
+export function requiresLogin(source: SourceClass, lanPasswordless: boolean): boolean {
+  return !(lanPasswordless && source !== 'internet')
+}
+
+/** Parse the session cookie out of a Cookie header. */
+export function sessionCookie(headers: IncomingHttpHeaders, cookieName: string): string | undefined {
+  const header = headers.cookie
+  if (typeof header !== 'string') return undefined
+  for (const part of header.split(';')) {
+    const trimmed = part.trim()
+    if (trimmed.startsWith(`${cookieName}=`)) {
+      return trimmed.slice(cookieName.length + 1)
+    }
+  }
+  return undefined
+}
+
+/**
+ * The cross-site test shared by every gateway-owned entry point, applied before
+ * any Host/Origin rewriting: an explicit cross-site fetch, or an Origin that
+ * does not name the authority the browser actually used.
+ *
+ * Only claims a cross-site page cannot suppress are read, which is what makes
+ * this usable on the login POST too (see {@link loginOriginAllowed}).
+ */
+export function isCrossSiteRequest(headers: IncomingHttpHeaders): boolean {
+  if (headers['sec-fetch-site'] === 'cross-site') return true
+  const origin = headers.origin
+  if (origin !== undefined && !originMatchesHost(origin, headers.host)) return true
+  return false
+}
+
+/**
+ * The gateway's own cross-site gate, shared by HTTP and WebSocket upgrades and
+ * applied before any Host/Origin rewriting. Browsers attach Origin to
+ * state-changing requests and to every WebSocket handshake; reads without an
+ * Origin (navigations, non-browser clients holding a session) stay allowed.
+ */
+export function sameSiteAllowed(req: RequestHead, upgrade: boolean): boolean {
+  if (isCrossSiteRequest(req.headers)) return false
+  const origin = req.headers.origin
+  if (upgrade) return origin !== undefined
+  if (!READ_ONLY_METHODS.has(req.method ?? 'GET')) return origin !== undefined
+  return true
+}
+
+/**
+ * The fence on the login POST. Issuing a session is as much a state change as
+ * retiring one — and a cross-site form post burns the victim's source address
+ * through the login rate limiter — so the login route runs the same cross-site
+ * test as everything else.
+ *
+ * It deliberately stops short of {@link sameSiteAllowed}'s "a state-changing
+ * request must carry an Origin" rule: a browser always sends an Origin on a
+ * form POST, but curl, the dsh CLI and other non-browser clients legitimately
+ * do not, and requiring one would lock them out of signing in. What remains is
+ * what a cross-site page cannot forge or strip: `sec-fetch-site`, and an Origin
+ * that disagrees with the Host the request names.
+ */
+export function loginOriginAllowed(headers: IncomingHttpHeaders): boolean {
+  return !isCrossSiteRequest(headers)
+}
+
+/**
+ * Drop every `dsh-auth-*` pair from a Cookie header, returning the remainder
+ * (possibly '').
+ *
+ * The relay's session is appended to the client's own cookie, and upstream
+ * reads the FIRST name match. A client that holds any `dsh-auth-<hash>` —
+ * typically one minted before dsh's signing secret was reset, so still present
+ * but no longer verifying — would therefore shadow the relay's session on every
+ * request. That draws a 401, the gateway reads the 401 as "upstream revoked our
+ * session" and discards it, the next request re-acquires, and the client's
+ * stale cookie shadows that one too: a loop that never converges. Stripping the
+ * namespace makes the relay's copy the only one.
+ *
+ * This filters the namespace; `isUpstreamSessionCookie` decides which cookie may
+ * be *accepted* from upstream. The two are deliberately different rules.
+ */
+export function withoutUpstreamSessionPairs(cookie: string): string {
+  return cookie
+    .split(';')
+    .map((pair) => pair.trim())
+    .filter((pair) => pair !== '' && !isUpstreamCookiePair(pair))
+    .join('; ')
+}
+
+/** How the outbound request headers are built. */
+export interface UpstreamRequestOptions {
+  /** The loopback dsh port the Host/Origin rewrite names. */
+  dshPort: number
+  /** Keep the WebSocket handshake's Connection/Upgrade headers. */
+  keepUpgrade: boolean
+  /** The shared upstream session to ride, when the relay holds one. */
+  upstreamCookie?: string | undefined
+}
+
+/**
+ * Build the outbound headers for one relayed request: rewrite Host/Origin to
+ * the loopback upstream, drop hop-by-hop and caller-supplied forwarding
+ * headers, clear the upstream cookie namespace the relay owns, and attach the
+ * relayed session.
+ */
+export function upstreamRequestHeaders(
+  headers: IncomingHttpHeaders,
+  options: UpstreamRequestOptions,
+): OutgoingHttpHeaders {
+  const out: OutgoingHttpHeaders = { ...headers }
+  out.host = `127.0.0.1:${options.dshPort}`
+  if (typeof out.origin === 'string') {
+    out.origin = `http://127.0.0.1:${options.dshPort}`
+  }
+  delete out['proxy-connection']
+  if (!options.keepUpgrade) {
+    delete out.connection
+    delete out.upgrade
+  }
+  for (const name of FORWARDING_HEADERS) delete out[name]
+  if (typeof out.cookie === 'string') {
+    const kept = withoutUpstreamSessionPairs(out.cookie)
+    if (kept === '') delete out.cookie
+    else out.cookie = kept
+  }
+  const relayed = options.upstreamCookie
+  if (relayed !== undefined && relayed !== '') {
+    const existing = out.cookie
+    out.cookie = typeof existing === 'string' && existing !== ''
+      ? `${existing}; ${relayed}`
+      : relayed
+  }
+  return out
+}
+
+/**
+ * Filter one direction's worth of headers through the same cookie rule, so the
+ * HTTP and WebSocket branches cannot drift apart on it.
+ */
+function stripUpstreamCookies(entry: string): boolean {
+  return !isUpstreamSessionCookie(entry.trim())
+}
+
+/**
+ * The headers to send back to the client: hop-by-hop headers dropped, and the
+ * upstream session cookie withheld. Upstream's one cookie-minting route is the
+ * launch-token exchange at `/`, so a client that already holds a gateway session
+ * could otherwise post the token through the gateway and walk away with a
+ * durable upstream credential the relay exists to keep on this side. Cookies
+ * from other routes (plugins) still pass through.
+ */
+export function downstreamResponseHeaders(upstream: IncomingHttpHeaders): OutgoingHttpHeaders {
+  const headers: OutgoingHttpHeaders = {}
+  for (const [key, value] of Object.entries(upstream)) {
+    if (value === undefined) continue
+    const lower = key.toLowerCase()
+    if (HOP_BY_HOP_HEADERS.has(lower)) continue
+    if (lower === 'set-cookie') {
+      const list = (Array.isArray(value) ? value : [value]).filter(stripUpstreamCookies)
+      if (list.length > 0) headers[key] = list
+      continue
+    }
+    headers[key] = value
+  }
+  return headers
+}
+
+/**
+ * The headers of a 101 Switching Protocols response, replayed to the client on
+ * the socket the gateway just spliced.
+ *
+ * {@link downstreamResponseHeaders} cannot be reused verbatim here: a successful
+ * upgrade has to keep Connection/Upgrade, which are hop-by-hop on every other
+ * response. The cookie rule is not relaxed with them — the relay's session is
+ * withheld on this path too, so upstream cannot hand a client a durable
+ * credential by attaching it to the handshake.
+ */
+export function upgradeResponseHeaders(upstream: IncomingHttpHeaders): OutgoingHttpHeaders {
+  const headers: OutgoingHttpHeaders = {}
+  for (const [key, value] of Object.entries(upstream)) {
+    if (value === undefined) continue
+    const lower = key.toLowerCase()
+    if (HOP_BY_HOP_HEADERS.has(lower) && !UPGRADE_HANDSHAKE_HEADERS.has(lower)) continue
+    if (lower === 'set-cookie') {
+      const list = (Array.isArray(value) ? value : [value]).filter(stripUpstreamCookies)
+      if (list.length > 0) headers[key] = list
+      continue
+    }
+    headers[key] = value
+  }
+  return headers
+}

package/src/state.ts

@@ -9,7 +9,7 @@
 
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto'
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
 import { homedir } from 'node:os'
 
 /** The state directory: `~/.dsh/lan-gateway`. */
@@ -37,17 +37,43 @@ export interface GatewayState {
    * immediately. Old state files without the field load as epoch 0.
    */
   sessionEpoch: number
+  /**
+   * Revoked session ids, each mapped to the epoch millis at which that
+   * session's own cookie expires. Signing out revokes the single id the
+   * browser presented, so the account's other sessions keep working, and it
+   * has to be persisted: the cookie it names stays unforgeable until it
+   * expires, and a restart must not resurrect it. Entries lapse once the
+   * cookie they name could no longer be presented anyway, which bounds the
+   * list by the sessions that are still live somewhere. Absent on state
+   * written before 0.5.4.
+   */
+  revokedSessions?: Record<string, number>
 }
 
 const STATE_FILENAME = 'state.json'
 
-/** Whether a password is present and passes scrypt verification. */
-export function verifyPassword(state: GatewayState, password: string): boolean {
+/** Promise wrapper around the threaded `scrypt`, which runs off the main loop. */
+function deriveKey(password: string, salt: Buffer, keylen: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    scrypt(password, salt, keylen, (error, derived) => {
+      if (error !== null) reject(error)
+      else resolve(derived)
+    })
+  })
+}
+
+/**
+ * Whether a password is present and passes scrypt verification. Asynchronous
+ * on purpose: `scryptSync` occupies the event loop for tens of milliseconds
+ * per attempt, and that loop is shared with the dsh process the gateway is
+ * forwarding to.
+ */
+export async function verifyPassword(state: GatewayState, password: string): Promise<boolean> {
   if (state.password === undefined) return false
   const { hash, salt } = state.password
   try {
     const expected = Buffer.from(hash, 'hex')
-    const actual = scryptSync(password, Buffer.from(salt, 'hex'), expected.length)
+    const actual = await deriveKey(password, Buffer.from(salt, 'hex'), expected.length)
     return expected.length === actual.length && timingSafeEqual(expected, actual)
   } catch {
     return false
@@ -58,24 +84,76 @@ export function verifyPassword(state: GatewayState, password: string): boolean {
  * Set (or clear) the password, re-salted on every write. Both operations bump
  * the session epoch so every cookie issued under the previous epoch dies — a
  * password change must invalidate sessions the old password authorized.
+ *
+ * Deriving the key is asynchronous for the same reason
+ * {@link verifyPassword} is: `scryptSync` occupies the event loop for tens of
+ * milliseconds, and that loop is shared with the dsh process the gateway
+ * forwards to. Every caller is already async.
  */
-export function setPassword(state: GatewayState, password: string | undefined): GatewayState {
-  const base = { ...state, sessionEpoch: state.sessionEpoch + 1 }
-  if (password === undefined) {
-    return { cookieSecret: base.cookieSecret, sessionEpoch: base.sessionEpoch }
+export async function setPassword(state: GatewayState, password: string | undefined): Promise<GatewayState> {
+  // The new epoch invalidates every cookie on its own account, so the list of
+  // individually revoked sessions has nothing left to say: drop it rather than
+  // carry entries that can never match again.
+  const base: GatewayState = {
+    cookieSecret: state.cookieSecret,
+    sessionEpoch: state.sessionEpoch + 1,
   }
+  if (password === undefined) return base
   const salt = randomBytes(16)
-  const hash = scryptSync(password, salt, 64)
+  const hash = await deriveKey(password, salt, 64)
   return {
     ...base,
     password: { hash: hash.toString('hex'), salt: salt.toString('hex') },
   }
 }
 
+/**
+ * Record a session id as revoked.
+ * @param expiresMs - the revoked cookie's own expiry. Past it the cookie is
+ *   rejected on its own account, so the entry is no longer needed; dropping
+ *   expired entries here is what keeps the list bounded.
+ * @param now - epoch millis to judge the existing entries against, injected so
+ *   a test can age the list without fake timers.
+ */
+export function revokeSession(
+  state: GatewayState,
+  sid: string,
+  expiresMs: number,
+  now: number = Date.now(),
+): GatewayState {
+  const revoked: Record<string, number> = {}
+  for (const [id, exp] of Object.entries(state.revokedSessions ?? {})) {
+    if (exp > now) revoked[id] = exp
+  }
+  revoked[sid] = expiresMs
+  return { ...state, revokedSessions: revoked }
+}
+
+/** Whether `sid` names a session that has been signed out. */
+export function isSessionRevoked(state: GatewayState, sid: string | undefined): boolean {
+  if (sid === undefined) return false
+  return Object.hasOwn(state.revokedSessions ?? {}, sid)
+}
+
 function defaultState(): GatewayState {
   return { cookieSecret: randomBytes(32).toString('base64'), sessionEpoch: 0 }
 }
 
+/** Keep the still-live entries of a persisted revocation list, or undefined. */
+function parseRevokedSessions(raw: unknown): Record<string, number> | undefined {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return undefined
+  const now = Date.now()
+  const out: Record<string, number> = {}
+  let anyLive = false
+  for (const [sid, exp] of Object.entries(raw)) {
+    if (typeof exp === 'number' && Number.isFinite(exp) && exp > now) {
+      out[sid] = exp
+      anyLive = true
+    }
+  }
+  return anyLive ? out : undefined
+}
+
 /** Load state; on first run (or a corrupt file) generate a fresh secret. */
 export function loadState(home: string = homedir()): GatewayState {
   const dir = stateDir(home)
@@ -91,6 +169,9 @@ export function loadState(home: string = homedir()): GatewayState {
         : 0
       const base: GatewayState = { cookieSecret: parsed.cookieSecret, sessionEpoch }
       if (parsed.password !== undefined) base.password = parsed.password
+      // Anything the file lists past its own expiry has lapsed on its own.
+      const revoked = parseRevokedSessions(parsed.revokedSessions)
+      if (revoked !== undefined) base.revokedSessions = revoked
       return base
     }
     return defaultState()

package/src/tls.ts

@@ -71,6 +71,27 @@ export function loadOrCreateSelfSigned(
   return { material, created: true }
 }
 
+/**
+ * Load the self-signed material a listener should serve: generate it on first
+ * use, reuse the persisted pair otherwise, and replace a persisted certificate
+ * whose validity has already lapsed.
+ *
+ * Nothing renews a self-signed certificate in place, and a browser refuses a
+ * lapsed one outright, so without this a certificate that ran out would keep
+ * being served until an operator happened to read the expiry date out of
+ * `status` and act on it. Renewing mints a fresh key, so a client that had
+ * trusted the old certificate has to trust the new one — but that is the case
+ * either way, the old one having lapsed.
+ */
+export function loadOrRenewSelfSigned(
+  opts: SelfSignedTlsOptions,
+  home: string = homedir(),
+): { material: TlsMaterial; renewed: boolean } {
+  const { material, created } = loadOrCreateSelfSigned(opts, home)
+  if (created || !isCertExpired(material.cert)) return { material, renewed: false }
+  return { material: regenerateSelfSigned(opts, home), renewed: true }
+}
+
 /**
  * Force-regenerate the self-signed certificate (new key + cert), replacing
  * the persisted files. Used by `lan_gateway tls-regenerate`.
@@ -84,6 +105,29 @@ export function regenerateSelfSigned(opts: SelfSignedTlsOptions, home: string =
   return material
 }
 
+/**
+ * Read the persisted self-signed certificate for a status report, or undefined
+ * when none has been generated yet.
+ *
+ * Nothing is created or written here. The status path answers a question about
+ * a listener that is already running (or was), and minting a key pair — an RSA
+ * generation plus two file writes — to answer a read would both be slow and
+ * leave material on disk for a gateway that never started. Generation belongs
+ * to {@link loadOrRenewSelfSigned} and {@link regenerateSelfSigned}.
+ * @param home - dsh home override (tests).
+ * @returns the certificate material as persisted, or undefined.
+ */
+export function readSelfSignedStatus(home: string = homedir()): TlsMaterial | undefined {
+  const dir = tlsDir(home)
+  const certPath = join(dir, SELF_SIGNED_CERT_FILE)
+  const keyPath = join(dir, SELF_SIGNED_KEY_FILE)
+  if (!existsSync(certPath) || !existsSync(keyPath)) return undefined
+  const cert = readFileSync(certPath, 'utf8')
+  const key = readFileSync(keyPath, 'utf8')
+  new X509Certificate(cert) // sanity: must parse as a certificate
+  return { cert, key }
+}
+
 function generateSelfSignedMaterial(opts: SelfSignedTlsOptions): TlsMaterial {
   const hosts = opts.hosts.map(h => h.trim()).filter(h => h !== '')
   if (hosts.length === 0) {
@@ -146,6 +190,18 @@ export interface CertInfo {
   san?: string
 }
 
+/**
+ * Whether a PEM certificate's validity window has already closed. A lapsed
+ * certificate is a hard failure browsers will not let the user proceed past,
+ * so the listener replaces one rather than keep serving it.
+ */
+export function isCertExpired(certPem: string, now: number = Date.now()): boolean {
+  const expiresAt = Date.parse(new X509Certificate(certPem).validTo)
+  // An unparseable date reads as "not expired": serving the certificate we were
+  // handed beats discarding it over a date-parsing quirk.
+  return Number.isFinite(expiresAt) && expiresAt <= now
+}
+
 /** Describe a PEM certificate (throws on malformed input). */
 export function describeCert(certPem: string): CertInfo {
   const cert = new X509Certificate(certPem)

package/src/upstream-session.ts

@@ -35,10 +35,14 @@ interface HeldCookie {
   expiresAt: number
 }
 
-/** The minimal shared-session contract the gateway consumes. */
+/**
+ * The minimal shared-session contract the gateway consumes.
+ *
+ * Two methods, and deliberately no reader: a caller that needs the value
+ * already holds the one `cookie()` returned, and a second way to read the
+ * cache only invites the caller to skip the acquisition it just awaited.
+ */
 export interface UpstreamSession {
-  /** The current `name=value` without triggering a re-acquisition. */
-  peek(): string | undefined
   /** The current `name=value`, re-acquiring when missing or stale. Never throws. */
   cookie(): Promise<string | undefined>
   /** Forget a session upstream rejected, so the next request re-acquires. */
@@ -73,20 +77,49 @@ function nameValueOnly(setCookie: string): string {
   return (semi === -1 ? setCookie : setCookie.slice(0, semi)).trim()
 }
 
+/**
+ * The pathname of a URL, for logging. Never the whole URL: the authenticated
+ * URL carries the launch token as a query parameter, and that token is a
+ * bearer credential for the upstream harness.
+ */
+function pathOf(url: string): string {
+  try {
+    return new URL(url).pathname
+  } catch {
+    return '<unparseable>'
+  }
+}
+
 /** 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 one `name=value` fragment of a request `Cookie` header names the
+ * upstream session namespace, and so must be dropped before the relay's own
+ * copy is appended. This is the *filter* rule: it matches the whole reserved
+ * namespace, name only, whether or not the pair is a well-formed session.
+ */
+export function isUpstreamCookiePair(pair: string): boolean {
+  return pair.trim().startsWith(UPSTREAM_COOKIE_PREFIX)
+}
+
 /**
  * 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.
+ *
+ * This is the *accept* rule, and it is stricter than {@link isUpstreamCookiePair}
+ * on purpose: filtering drops a whole namespace the gateway owns, whereas
+ * accepting a session has to recognize the one cookie upstream actually mints.
+ * Both live here because this module owns the protocol fact; a consumer that
+ * re-derives it is how the two rules drifted apart before.
  */
-function isUpstreamSessionCookie(setCookie: string): boolean {
+export function isUpstreamSessionCookie(setCookie: string): boolean {
   const name = cookieNameOf(setCookie)
   return name.startsWith(UPSTREAM_COOKIE_PREFIX) && name.length > UPSTREAM_COOKIE_PREFIX.length
 }
@@ -121,7 +154,7 @@ function exchange(
     try {
       target = new URL(url)
     } catch {
-      log(`exchange: unparseable authenticatedUrl ${url}`)
+      log('exchange: authenticatedUrl is not parseable')
       resolve(undefined)
       return
     }
@@ -195,10 +228,6 @@ export class UpstreamSessionRelay implements UpstreamSession {
     return Date.now() < held.expiresAt - 60_000
   }
 
-  peek(): string | undefined {
-    return this.held?.header
-  }
-
   invalidate(): void {
     if (this.held !== undefined) this.log('invalidating held session (upstream rejected it)')
     this.held = undefined
@@ -228,7 +257,9 @@ export class UpstreamSessionRelay implements UpstreamSession {
       this.log('authenticatedUrl() returned undefined; keeping current session')
       return this.held?.header
     }
-    this.log(`acquiring session from ${url}`)
+    // Log only the path: the URL carries the launch token in its query string,
+    // and that token is a bearer credential for the upstream harness.
+    this.log(`acquiring session from ${pathOf(url)}`)
     const result = await exchange(url, this.authority, this.port, this.log)
     if (result !== undefined) {
       this.held = result