@byline/host-tanstack-start 5.0.0 → 5.1.0

package/src/admin-shell/chrome/sign-in-page.tsx

@@ -6,6 +6,8 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import { useEffect, useState } from 'react'
+
 import { SignInForm } from '@byline/admin/auth/components/sign-in-form'
 import { BylineAdminServicesProvider } from '@byline/admin/services'
 import { getAdminConfig } from '@byline/core'
@@ -15,10 +17,20 @@ import cx from 'clsx'
 
 import { buildLocaleDefinitions } from '../../i18n/locale-definitions.js'
 import { bylineAdminServices } from '../../integrations/byline-admin-services.js'
+import {
+  coordinateAuthAction,
+  expectedSession,
+  flagSessionChanged,
+  observeSession,
+  renewSingleFlight,
+} from '../../integrations/session-coordination.js'
+import { renewAdminSession } from '../../server-fns/auth/renew.js'
 import { setAdminLocaleFn } from '../../server-fns/i18n/index.js'
+import { SessionChangeBoundary } from './session-change-boundary.js'
 import styles from './sign-in-page.module.css'
 
 interface SignInPageProps {
+  reauthenticate?: boolean
   redirectTo: string
   activeLocale: LocaleCode
   homeUrl?: string
@@ -44,14 +56,54 @@ interface SignInPageProps {
  * Threads an optional host-owned `homeUrl` into `SignInForm` so the form's
  * action row can render a plain "Home" link beside the submit button.
  */
-export function SignInPage({ redirectTo, activeLocale, homeUrl }: SignInPageProps) {
+export function SignInPage({
+  redirectTo,
+  activeLocale,
+  homeUrl,
+  reauthenticate = false,
+}: SignInPageProps) {
+  const [checking, setChecking] = useState(!reauthenticate)
+  const [bootstrapError, setBootstrapError] = useState(false)
+  useEffect(() => {
+    if (reauthenticate) return
+    let active = true
+    void renewSingleFlight(() =>
+      coordinateAuthAction(async () => {
+        const result = await renewAdminSession({
+          data: { expectedSessionId: expectedSession() ?? undefined },
+        })
+        observeSession(result.sessionId)
+      })
+    )
+      .then(() => {
+        if (active) window.location.replace(redirectTo)
+      })
+      .catch((error) => {
+        if (error?.code === 'ERR_SESSION_CHANGED') flagSessionChanged()
+        else if (
+          ![
+            'ERR_UNAUTHENTICATED',
+            'ERR_INVALID_TOKEN',
+            'ERR_REVOKED_TOKEN',
+            'ERR_ACCOUNT_DISABLED',
+          ].includes(error?.code)
+        )
+          setBootstrapError(true)
+      })
+      .finally(() => {
+        if (active) setChecking(false)
+      })
+    return () => {
+      active = false
+    }
+  }, [redirectTo, reauthenticate])
   const { i18n } = getAdminConfig()
   const localeDefinitions = buildLocaleDefinitions(i18n.admin.locales, i18n.admin.localeDefinitions)
   const handleSetLocale = async (next: LocaleCode) => {
     await setAdminLocaleFn({ data: { locale: next } })
     window.location.reload()
   }
-  return (
+  const content = (
     <I18nProvider
       bundle={i18n.translations ?? {}}
       activeLocale={activeLocale}
@@ -61,14 +113,27 @@ export function SignInPage({ redirectTo, activeLocale, homeUrl }: SignInPageProp
     >
       <BylineAdminServicesProvider services={bylineAdminServices}>
         <main className={cx('byline-sign-in-page', styles.main)}>
+          <noscript>JavaScript is required to sign in or renew your admin session.</noscript>
           <div className={cx('byline-sign-in-page-bar', styles.bar)}>
             <LanguageMenu />
           </div>
           <div className={cx('byline-sign-in-page-inner', styles.inner)}>
-            <SignInForm redirectTo={redirectTo} homeUrl={homeUrl} />
+            {bootstrapError ? (
+              <div role="alert">
+                <p>Unable to check your session. Please try again.</p>
+                <button type="button" onClick={() => window.location.reload()}>
+                  Try again
+                </button>
+              </div>
+            ) : checking ? (
+              <p role="status">Checking your session…</p>
+            ) : (
+              <SignInForm redirectTo={redirectTo} homeUrl={homeUrl} />
+            )}
           </div>
         </main>
       </BylineAdminServicesProvider>
     </I18nProvider>
   )
+  return reauthenticate ? content : <SessionChangeBoundary>{content}</SessionChangeBoundary>
 }

package/src/integrations/byline-admin-services.ts

@@ -36,6 +36,7 @@ import {
 import { adminSignIn } from '../server-fns/auth/index.js'
 import { getCollectionDocumentVersion as serverGetCollectionDocumentVersion } from '../server-fns/collections/get.js'
 import { setAdminLocaleFn } from '../server-fns/i18n/index.js'
+import { acceptSession, coordinateAuthAction, notifySessionAction } from './session-coordination.js'
 
 /**
  * Diff helper adapter — the contract uses positional args; the underlying
@@ -62,7 +63,12 @@ const getCollectionDocumentVersion: BylineAdminServices['getCollectionDocumentVe
 
 export const bylineAdminServices: BylineAdminServices = {
   // Auth
-  adminSignIn,
+  adminSignIn: async (args) => {
+    const result = await coordinateAuthAction(() => adminSignIn(args))
+    acceptSession(result.sessionId)
+    notifySessionAction()
+    return result
+  },
 
   // Account self-service
   updateAccount,

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

@@ -0,0 +1,45 @@
+/**
+ * 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 { describe, expect, it } from 'vitest'
+
+import { createClientIpResolver, normalizeClientIp } from './client-ip.js'
+
+describe('client IP trust boundary', () => {
+  it('ignores spoofed forwarding headers in direct mode', async () => {
+    const resolve = createClientIpResolver({ resolvePeerIp: () => '192.0.2.1' })
+    expect(
+      await resolve(
+        new Request('https://app.test', {
+          headers: { 'x-forwarded-for': '198.51.100.1', 'x-real-ip': '198.51.100.2' },
+        })
+      )
+    ).toBe('192.0.2.1')
+  })
+  it('uses only the configured proxy header and fails closed on absent/invalid values', async () => {
+    const resolve = createClientIpResolver({
+      trustedProxyHeader: 'x-byline-client-ip',
+      resolvePeerIp: () => '127.0.0.1',
+    })
+    for (const value of ['', '192.0.2.1, 192.0.2.2', 'garbage']) {
+      expect(
+        await resolve(new Request('https://app.test', { headers: { 'x-byline-client-ip': value } }))
+      ).toBeNull()
+    }
+    expect(
+      await resolve(
+        new Request('https://app.test', { headers: { 'x-byline-client-ip': '2001:0db8::1' } })
+      )
+    ).toBe('2001:db8::1')
+  })
+  it('normalizes equivalent IP representations', () => {
+    expect(normalizeClientIp('::ffff:192.0.2.1')).toBe('192.0.2.1')
+    expect(normalizeClientIp('::ffff:c000:201')).toBe('192.0.2.1')
+    expect(normalizeClientIp('fe80::1%en0')).toBeNull()
+  })
+})

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()
+  })
+})