@byline/host-tanstack-start 4.19.0 → 5.1.0

package/src/integrations/client-ip.ts

@@ -0,0 +1,54 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { isIP } from 'node:net'
+
+import type { ClientIpResolver } from '@byline/auth'
+
+/** Normalize equivalent IPv6 spellings and IPv4-mapped IPv6 before choosing a rate-limit key. */
+export function normalizeClientIp(value: string | null | undefined): string | null {
+  if (!value || value.length > 64) return null
+  const ip = value.trim()
+  if (isIP(ip) === 4) return ip
+  if (isIP(ip) !== 6 || ip.includes('%')) return null
+  const normalized = new URL(`http://[${ip}]/`).hostname.slice(1, -1)
+  const mapped = /^::ffff:([0-9a-f]+):([0-9a-f]+)$/.exec(normalized)
+  if (mapped) {
+    const high = Number.parseInt(mapped[1]!, 16)
+    const low = Number.parseInt(mapped[2]!, 16)
+    return [high >>> 8, high & 255, low >>> 8, low & 255].join('.')
+  }
+  return normalized
+}
+
+/**
+ * Configure either a direct peer resolver or an explicitly trusted proxy header.
+ * Header mode requires the deployment to overwrite that header and block proxy bypass.
+ * Never falls back from a missing/invalid trusted header to another client-supplied header.
+ */
+export function createClientIpResolver(options: {
+  trustedProxyHeader?: string
+  resolvePeerIp: ClientIpResolver
+}): ClientIpResolver {
+  const header = options.trustedProxyHeader
+  if (header !== undefined && !/^[a-z0-9-]+$/i.test(header))
+    throw new Error('Invalid trusted IP header')
+  let lastDiagnostic = -Infinity
+  return async (request) => {
+    const ip = normalizeClientIp(
+      header === undefined ? await options.resolvePeerIp(request) : request.headers.get(header)
+    )
+    if (!ip && performance.now() - lastDiagnostic >= 60_000) {
+      lastDiagnostic = performance.now()
+      console.warn(
+        '[byline:client-ip] No valid single client IP; check the configured peer resolver or trusted proxy header.'
+      )
+    }
+    return ip
+  }
+}

package/src/integrations/framework-fetch-shape.test.node.ts

@@ -0,0 +1,56 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+
+import { describe, expect, it, vi } from 'vitest'
+
+// Exercise the installed framework serializer, not a copy of its fetch logic.
+// Its internal path is deliberately pinned here so an upgrade requires review.
+const frameworkRequire = createRequire(import.meta.resolve('@tanstack/react-start/client-rpc'))
+const coreManifest = frameworkRequire.resolve('@tanstack/start-client-core/package.json')
+const fetcherUrl = new URL('./dist/esm/client-rpc/serverFnFetcher.js', pathToFileURL(coreManifest))
+const { serverFnFetcher } = await import(/* @vite-ignore */ fetcherUrl.href)
+const storageUrl = new URL(
+  './dist/esm/index.js',
+  pathToFileURL(createRequire(coreManifest).resolve('@tanstack/start-storage-context/package.json'))
+)
+const { runWithStartContext } = await import(/* @vite-ignore */ storageUrl.href)
+
+describe('framework server-function fetch shape', () => {
+  it.each(['GET', 'POST', 'FormData'])(
+    'keeps %s requests reusable without stream cloning',
+    async (kind) => {
+      const form = new FormData()
+      form.set('upload', new Blob(['content']), 'fixture.txt')
+      const fetch = vi.fn(async (url: unknown, init: RequestInit) => {
+        expect(
+          typeof url === 'string' &&
+            (init.body === undefined ||
+              typeof init.body === 'string' ||
+              init.body instanceof FormData)
+        ).toBe(true)
+        return new Response('ok', { headers: { 'x-tss-raw': 'true' } })
+      })
+      await runWithStartContext({ startOptions: {} }, () =>
+        serverFnFetcher(
+          'http://localhost/server-fn/fixture',
+          [
+            {
+              method: kind === 'GET' ? 'GET' : 'POST',
+              data: kind === 'FormData' ? form : { title: 'example' },
+            },
+          ],
+          fetch
+        )
+      )
+      expect(fetch).toHaveBeenCalledOnce()
+    }
+  )
+})

package/src/integrations/session-client.test.node.ts

@@ -0,0 +1,121 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ renew: vi.fn() }))
+vi.mock('../server-fns/auth/renew.js', () => ({ renewAdminSession: mocks.renew }))
+vi.mock('@byline/client/server', () => ({ getAdminRequestContext: vi.fn() }))
+
+let middleware: typeof import('./session-middleware.js')
+let coordination: typeof import('./session-coordination.js')
+const boundary = (outcome: string) =>
+  new Response('result', { headers: { 'x-byline-auth-boundary': outcome } })
+const request = async (body: BodyInit = 'edit') => {
+  return middleware.adminSessionMiddleware.options.client?.({
+    next: (options: any) => options.fetch('http://localhost/business', { method: 'POST', body }),
+  } as any)
+}
+beforeEach(async () => {
+  vi.resetModules()
+  vi.resetAllMocks()
+  const storage = new Map<string, string>()
+  vi.stubGlobal('window', {
+    sessionStorage: {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, value),
+    },
+  })
+  vi.stubGlobal('navigator', {})
+  vi.stubGlobal('BroadcastChannel', undefined)
+  coordination = await import('./session-coordination.js')
+  middleware = await import('./session-middleware.js')
+  coordination.acceptSession('A')
+  mocks.renew.mockResolvedValue({ sessionId: 'A' })
+})
+afterEach(() => vi.unstubAllGlobals())
+
+describe('coordinated business resend', () => {
+  it('coalesces six expiry responses into one renewal and resends each operation once', async () => {
+    const fetch = vi.fn().mockImplementationOnce(() => boundary('renew'))
+    for (let i = 1; i < 6; i++) fetch.mockImplementationOnce(() => boundary('renew'))
+    fetch.mockImplementation(() => boundary('handled'))
+    vi.stubGlobal('fetch', fetch)
+    await Promise.all(Array.from({ length: 6 }, () => request()))
+    expect(mocks.renew).toHaveBeenCalledTimes(1)
+    expect(mocks.renew).toHaveBeenCalledWith({ data: { expectedSessionId: 'A' } })
+    expect(fetch).toHaveBeenCalledTimes(12)
+  })
+  it('re-serializes multipart uploads without cloning or teeing the request', async () => {
+    const bodies: Array<{ title: string; file: string }> = []
+    const clone = vi.spyOn(Request.prototype, 'clone')
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+        const form = await new Request(input, init).formData()
+        bodies.push({
+          title: String(form.get('title')),
+          file: await (form.get('upload') as Blob).text(),
+        })
+        return boundary(bodies.length === 1 ? 'renew' : 'handled')
+      })
+    )
+    const body = new FormData()
+    body.set('title', 'An editorial change')
+    body.set('upload', new Blob(['file-content']), 'example.txt')
+    await request(body)
+    expect(bodies).toHaveLength(2)
+    expect(bodies[0]).toEqual({ title: 'An editorial change', file: 'file-content' })
+    expect(bodies[1]).toEqual(bodies[0])
+    expect(clone).not.toHaveBeenCalled()
+    clone.mockRestore()
+  })
+  it('renews but requires an explicit retry for a one-shot stream body', async () => {
+    const fetch = vi.fn().mockResolvedValue(boundary('renew'))
+    vi.stubGlobal('fetch', fetch)
+    const stream = new ReadableStream({
+      start(controller) {
+        controller.close()
+      },
+    })
+    await expect(request(stream)).rejects.toThrow('Please retry the operation')
+    expect(fetch).toHaveBeenCalledOnce()
+    expect(mocks.renew).toHaveBeenCalledOnce()
+  })
+  it('never retries a post-handler error or an ambiguous network failure', async () => {
+    const fetch = vi
+      .fn()
+      .mockResolvedValue(
+        new Response('failed', { status: 500, headers: { 'x-byline-auth-boundary': 'handled' } })
+      )
+    vi.stubGlobal('fetch', fetch)
+    await request()
+    expect(fetch).toHaveBeenCalledOnce()
+    fetch.mockReset().mockRejectedValue(new Error('connection lost'))
+    await expect(request()).rejects.toThrow('connection lost')
+    expect(fetch).toHaveBeenCalledOnce()
+    expect(mocks.renew).not.toHaveBeenCalled()
+  })
+  it('does not replay work when the session changes during renewal', async () => {
+    const fetch = vi.fn().mockResolvedValue(boundary('renew'))
+    vi.stubGlobal('fetch', fetch)
+    mocks.renew.mockImplementation(async () => {
+      coordination.flagSessionChanged()
+      return { sessionId: 'A' }
+    })
+    await expect(request()).rejects.toThrow('Session changed')
+    expect(fetch).toHaveBeenCalledOnce()
+  })
+  it('stops after one resend even if access expires again', async () => {
+    const fetch = vi.fn().mockImplementation(() => boundary('renew'))
+    vi.stubGlobal('fetch', fetch)
+    await request()
+    expect(fetch).toHaveBeenCalledTimes(2)
+    expect(mocks.renew).toHaveBeenCalledOnce()
+  })
+})

package/src/integrations/session-coordination.test.node.ts

@@ -0,0 +1,77 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+beforeEach(() => {
+  vi.resetModules()
+  vi.unstubAllGlobals()
+})
+function browserStorage() {
+  const values = new Map<string, string>()
+  vi.stubGlobal('window', {
+    sessionStorage: {
+      getItem: (k: string) => values.get(k) ?? null,
+      setItem: (k: string, v: string) => values.set(k, v),
+    },
+  })
+  return values
+}
+describe('browser session coordination', () => {
+  it('six concurrent renewals share one operation and a later request can renew again', async () => {
+    const { renewSingleFlight } = await import('./session-coordination.js')
+    let release!: () => void
+    const pending = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const work = vi.fn(() => pending)
+    const calls = Array.from({ length: 6 }, () => renewSingleFlight(work))
+    expect(work).toHaveBeenCalledOnce()
+    release()
+    await Promise.all(calls)
+    await renewSingleFlight(work)
+    expect(work).toHaveBeenCalledTimes(2)
+  })
+  it('rejects work captured before session change even after acknowledgement', async () => {
+    browserStorage()
+    const state = await import('./session-coordination.js')
+    state.acceptSession('A')
+    const old = state.sessionSnapshot()
+    expect(() => state.observeSession('B')).toThrow('Session changed')
+    expect(() => state.requireUnchanged(old)).toThrow()
+    state.acceptSession('B')
+    expect(() => state.requireUnchanged(old)).toThrow()
+    expect(() => state.requireUnchanged(state.sessionSnapshot())).not.toThrow()
+  })
+  it('retains successful sign-in intent across navigation and detects a different server login', async () => {
+    const values = browserStorage()
+    const before = await import('./session-coordination.js')
+    before.acceptSession('B')
+    vi.resetModules()
+    const after = await import('./session-coordination.js')
+    expect(after.expectedSession()).toBe('B')
+    expect(() => after.observeSession('A')).toThrow()
+    expect(values.get('byline.expected-login')).toBe('B')
+  })
+  it('serializes auth writes and releases the queue after failure without Web Locks', async () => {
+    vi.stubGlobal('navigator', {})
+    const { coordinateAuthAction } = await import('./session-coordination.js')
+    const order: number[] = []
+    const a = coordinateAuthAction(async () => {
+      order.push(1)
+      throw new Error('failed')
+    })
+    const b = coordinateAuthAction(async () => {
+      order.push(2)
+      return 'ok'
+    })
+    await expect(a).rejects.toThrow()
+    await expect(b).resolves.toBe('ok')
+    expect(order).toEqual([1, 2])
+  })
+})

package/src/integrations/session-coordination.ts

@@ -0,0 +1,96 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/** Browser coordination metadata only. No access or refresh credentials are exposed to JavaScript. */
+const storageKey = 'byline.expected-login'
+let expected: string | null = null
+let epoch = 0
+let changed = false
+let renewal: Promise<void> | undefined
+const listeners = new Set<() => void>()
+export const sessionChangedError = () =>
+  new Error('Session changed. Acknowledge the active account before continuing.')
+export function expectedSession() {
+  if (typeof window === 'undefined') return null
+  if (!expected) expected = window.sessionStorage.getItem(storageKey)
+  return expected
+}
+export function sessionSnapshot() {
+  return { sessionId: expectedSession(), epoch }
+}
+export function requireUnchanged(snapshot: ReturnType<typeof sessionSnapshot>) {
+  if (changed || snapshot.epoch !== epoch || snapshot.sessionId !== expectedSession())
+    throw sessionChangedError()
+}
+export function flagSessionChanged() {
+  changed = true
+  epoch++
+  for (const listener of listeners) listener()
+}
+export function acceptSession(sessionId: string) {
+  if (typeof window === 'undefined') return
+  if (typeof sessionId !== 'string' || !sessionId)
+    throw new Error('Provider omitted login identity')
+  window.sessionStorage.setItem(storageKey, sessionId)
+  expected = sessionId
+  changed = false
+  epoch++
+  for (const listener of listeners) listener()
+}
+export function observeSession(sessionId: string) {
+  const old = expectedSession()
+  if (old && old !== sessionId) {
+    flagSessionChanged()
+    throw sessionChangedError()
+  }
+  if (!old) acceptSession(sessionId)
+}
+export function sessionEpoch() {
+  return epoch
+}
+export function sessionIsChanged() {
+  return changed
+}
+export function subscribeSessionChange(listener: () => void) {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+export function renewSingleFlight(work: () => Promise<void>) {
+  if (!renewal)
+    renewal = work().finally(() => {
+      renewal = undefined
+    })
+  return renewal
+}
+
+let authQueue: Promise<unknown> = Promise.resolve()
+export function coordinateAuthAction<T>(work: () => Promise<T>): Promise<T> {
+  const run = authQueue
+    .catch(() => {})
+    .then(async () => {
+      if (typeof navigator !== 'undefined' && navigator.locks)
+        return navigator.locks.request('byline.auth', work)
+      return work()
+    })
+  authQueue = run
+  return run
+}
+let channel: BroadcastChannel | undefined
+export function startSessionNotifications() {
+  if (typeof BroadcastChannel === 'undefined' || channel) return
+  channel = new BroadcastChannel('byline.session')
+  channel.onmessage = () => {
+    flagSessionChanged()
+  }
+}
+export function notifySessionAction() {
+  startSessionNotifications()
+  channel?.postMessage({ type: 'session-changed' })
+}

package/src/integrations/session-middleware.test.node.ts

@@ -0,0 +1,87 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { ERR_ACCESS_EXPIRED, ERR_REVOKED_TOKEN } from '@byline/auth'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  request: {},
+  headers: new Map<string, string>(),
+  auth: vi.fn(),
+  renew: vi.fn(),
+}))
+vi.mock('@tanstack/react-start/server', () => ({
+  getRequest: () => mocks.request,
+  setResponseHeader: (k: string, v: string) => mocks.headers.set(k, v),
+}))
+vi.mock('@byline/client/server', () => ({ getAdminRequestContext: mocks.auth }))
+vi.mock('../server-fns/auth/renew.js', () => ({ renewAdminSession: mocks.renew }))
+
+import { adminSessionMiddleware } from './session-middleware.js'
+import { recordSessionRequestKind } from './session-request-kind.js'
+
+const server = adminSessionMiddleware.options.server!
+const invoke = (next: any, expected: unknown = 'login-A', method = 'POST') =>
+  server({ next, context: { bylineExpectedSessionId: expected }, method } as any)
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.headers.clear()
+  recordSessionRequestKind(mocks.request, 'serverFn')
+  mocks.auth.mockResolvedValue({ sessionId: 'login-A', actor: { id: 'account-X' } })
+})
+describe('pre-handler session boundary', () => {
+  it.each([null, undefined, '', 'login-B'])(
+    'rejects missing or changed expected sid %s before any side effect',
+    async (expected) => {
+      const write = vi.fn()
+      // Explicit undefined must not invoke the helper default.
+      await expect(
+        server({
+          next: write,
+          context: { bylineExpectedSessionId: expected },
+          method: 'POST',
+        } as any)
+      ).rejects.toMatchObject({ code: 'ERR_SESSION_CHANGED' })
+      expect(write).not.toHaveBeenCalled()
+      expect(mocks.headers.get('x-byline-auth-boundary')).toBe('changed')
+    }
+  )
+  it('signals renewal only for expiry before the handler starts', async () => {
+    const write = vi.fn()
+    mocks.auth.mockRejectedValue(ERR_ACCESS_EXPIRED({ message: 'expired' }))
+    await expect(invoke(write)).rejects.toThrow()
+    expect(write).not.toHaveBeenCalled()
+    expect(mocks.headers.get('x-byline-auth-boundary')).toBe('renew')
+  })
+  it('does not renew revoked credentials or database errors', async () => {
+    for (const error of [ERR_REVOKED_TOKEN({ message: 'revoked' }), new Error('db unavailable')]) {
+      const write = vi.fn()
+      mocks.auth.mockRejectedValue(error)
+      await expect(invoke(write)).rejects.toThrow()
+      expect(write).not.toHaveBeenCalled()
+      expect(mocks.headers.has('x-byline-auth-boundary')).toBe(false)
+    }
+  })
+  it('never turns an expiry error thrown after a side effect into a retry signal', async () => {
+    const write = vi.fn(async () => {
+      mocks.headers.set('x-byline-auth-boundary', 'renew')
+      throw ERR_ACCESS_EXPIRED({ message: 'handler error' })
+    })
+    await expect(invoke(write)).rejects.toThrow()
+    expect(write).toHaveBeenCalledOnce()
+    expect(mocks.headers.get('x-byline-auth-boundary')).toBe('handled')
+  })
+  it('allows server-classified SSR reads, but not SSR mutations without expected sid', async () => {
+    recordSessionRequestKind(mocks.request, 'router')
+    const read = vi.fn(async () => ({}))
+    await invoke(read, null, 'GET')
+    expect(read).toHaveBeenCalledOnce()
+    await expect(invoke(read, null)).rejects.toMatchObject({ code: 'ERR_SESSION_CHANGED' })
+    expect(read).toHaveBeenCalledOnce()
+  })
+})

package/src/integrations/session-middleware.ts

@@ -0,0 +1,107 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createMiddleware } from '@tanstack/react-start'
+import { getRequest, setResponseHeader } from '@tanstack/react-start/server'
+
+import {
+  AuthError,
+  ERR_ACCESS_EXPIRED,
+  ERR_SESSION_CHANGED,
+  ERR_UNAUTHENTICATED,
+} from '@byline/auth'
+import { getAdminRequestContext } from '@byline/client/server'
+
+import { renewAdminSession } from '../server-fns/auth/renew.js'
+import {
+  coordinateAuthAction,
+  flagSessionChanged,
+  observeSession,
+  renewSingleFlight,
+  requireUnchanged,
+  sessionSnapshot,
+} from './session-coordination.js'
+import { sessionRequestKind } from './session-request-kind.js'
+
+const outcomeHeader = 'x-byline-auth-boundary'
+/** The boundary owns the retry signal; handler errors cannot turn into retryable outcomes. */
+export const adminSessionMiddleware = createMiddleware({ type: 'function' })
+  .client(async ({ next }) => {
+    if (typeof window === 'undefined')
+      return next({ sendContext: { bylineExpectedSessionId: null as string | null } })
+    const snapshot = sessionSnapshot()
+    requireUnchanged(snapshot)
+    return next({
+      sendContext: { bylineExpectedSessionId: snapshot.sessionId },
+      fetch: async (input, init) => {
+        // Re-serialize reusable BodyInit values (including FormData/Blob) on retry.
+        // Never clone/tee a Request: an unread branch can buffer an entire upload.
+        const reusable = !(input instanceof Request) && !(init?.body instanceof ReadableStream)
+        let response = await fetch(input, init)
+        if (response.headers.get(outcomeHeader) === 'changed') {
+          flagSessionChanged()
+          throw ERR_SESSION_CHANGED({ message: 'session changed' })
+        }
+        if (response.headers.get(outcomeHeader) === 'renew') {
+          requireUnchanged(snapshot)
+          await renewSingleFlight(() =>
+            coordinateAuthAction(async () => {
+              const result = await renewAdminSession({
+                data: { expectedSessionId: snapshot.sessionId ?? undefined },
+              }).catch((error) => {
+                if (error?.code === 'ERR_SESSION_CHANGED') flagSessionChanged()
+                throw error
+              })
+              if (snapshot.sessionId && result.sessionId !== snapshot.sessionId) {
+                flagSessionChanged()
+                throw ERR_SESSION_CHANGED({ message: 'session changed during renewal' })
+              }
+              observeSession(result.sessionId)
+            })
+          )
+          requireUnchanged(snapshot)
+          if (!reusable)
+            throw ERR_ACCESS_EXPIRED({ message: 'Session renewed. Please retry the operation.' })
+          response = await fetch(input, init)
+          if (response.headers.get(outcomeHeader) === 'changed') flagSessionChanged()
+        }
+        requireUnchanged(snapshot)
+        return response
+      },
+    })
+  })
+  .server(async ({ next, context, method }) => {
+    const kind = sessionRequestKind(getRequest())
+    if (!kind) throw new Error('sessionRequestMiddleware is not configured')
+    let auth: Awaited<ReturnType<typeof getAdminRequestContext>>
+    try {
+      auth = await getAdminRequestContext()
+    } catch (error) {
+      if (error instanceof AuthError && error.code === 'ERR_ACCESS_EXPIRED')
+        setResponseHeader(outcomeHeader, 'renew')
+      throw error
+    }
+    const expected = context.bylineExpectedSessionId
+    if ((kind === 'serverFn' || method !== 'GET') && (!expected || expected !== auth.sessionId)) {
+      setResponseHeader(outcomeHeader, 'changed')
+      throw ERR_SESSION_CHANGED({ message: 'session changed before operation' })
+    }
+    if (!auth.sessionId) throw ERR_UNAUTHENTICATED({ message: 'provider omitted login identity' })
+    // Strip the reserved signal after any handler outcome, including exceptions.
+    try {
+      const result = await next()
+      const response = (result as { result?: unknown }).result
+      if (response instanceof Response) response.headers.delete(outcomeHeader)
+      return result
+    } catch (error) {
+      if (error instanceof Response) error.headers.delete(outcomeHeader)
+      throw error
+    } finally {
+      setResponseHeader(outcomeHeader, 'handled')
+    }
+  })

package/src/integrations/session-request-kind.ts

@@ -0,0 +1,18 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/** Server-owned classification. A browser header cannot opt a request into SSR privileges. */
+const key = Symbol.for('byline.sessionRequestKinds')
+const kinds: WeakMap<object, string> = (globalThis as any)[key] ?? new WeakMap()
+;(globalThis as any)[key] = kinds
+export function recordSessionRequestKind(request: object, kind: string) {
+  kinds.set(request, kind)
+}
+export function sessionRequestKind(request: object) {
+  return kinds.get(request)
+}

package/src/integrations/session-request-middleware.ts

@@ -0,0 +1,17 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { createMiddleware } from '@tanstack/react-start'
+
+import { recordSessionRequestKind } from './session-request-kind.js'
+
+/** Register after CSRF. Classifies SSR separately from remotely invoked business functions. */
+export const sessionRequestMiddleware = createMiddleware().server(async (ctx) => {
+  recordSessionRequestKind(ctx.request, ctx.handlerType)
+  return ctx.next()
+})