@byline/host-tanstack-start 5.0.0 → 5.1.1

package/src/admin-shell/chrome/admin-app-bar.tsx

@@ -1,5 +1,3 @@
-'use client'
-
 /**
  * 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
@@ -22,6 +20,8 @@ import { Branding } from './branding.js'
 import { Breadcrumbs } from './breadcrumbs/breadcrumbs.js'
 import { useBreadcrumbs } from './breadcrumbs/breadcrumbs-provider.js'
 
+;('use client')
+
 interface AdminAppBarProps {
   user: CurrentAdminUser
 }
@@ -37,16 +37,18 @@ export function AdminAppBar({ user }: AdminAppBarProps) {
   const { breadCrumbSettings } = useBreadcrumbs()
   const { t } = useTranslation('byline-admin')
   const [signingOut, setSigningOut] = useState(false)
+  const [signOutError, setSignOutError] = useState(false)
 
   async function handleSignOut() {
     if (signingOut) return
     setSigningOut(true)
+    setSignOutError(false)
     try {
       await adminSignOut()
-    } catch (err) {
-      // Even on transport failure, the server-side handler clears the
-      // cookies best-effort. Navigate to sign-in regardless.
-      console.warn('sign-out request failed', err)
+    } catch {
+      setSignOutError(true)
+      setSigningOut(false)
+      return
     }
     // Full-page navigation so the admin guard re-runs with cleared cookies.
     window.location.assign(getSignInRoutePath())
@@ -71,6 +73,9 @@ export function AdminAppBar({ user }: AdminAppBarProps) {
             {displayNameFor(user)}
           </span>
         </span>
+        {signOutError && (
+          <span role="alert">Sign-out could not be confirmed. Please try again.</span>
+        )}
         <Button size="xs" intent="secondary" onClick={handleSignOut} disabled={signingOut}>
           {signingOut ? t('common.actions.signingOut') : t('common.actions.signOut')}
         </Button>

package/src/admin-shell/chrome/optional-i18n-provider.tsx

@@ -0,0 +1,61 @@
+/**
+ * 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 { type ReactNode, useContext } from 'react'
+
+import { getAdminConfig } from '@byline/core'
+import type { TranslationBundle } from '@byline/i18n'
+import { I18nContext, I18nProvider } from '@byline/i18n/react'
+
+/**
+ * Guarantees a translation context for chrome that can render *outside*
+ * the admin layout's `<I18nProvider>`.
+ *
+ * When a provider is already above us it is reused as-is, preserving the
+ * user's active locale. Only when none is present does this self-mount.
+ *
+ * Resilient by design: components using this are the ones shown when
+ * something has already gone wrong, so throwing here would mask the real
+ * condition. If the admin config can't be read it falls back to an
+ * English-default provider with an empty bundle — with a provider always
+ * present, `useTranslation` never throws, and a missing key renders as the
+ * raw key rather than crashing (see `I18nProvider`'s `onMissing`).
+ *
+ * `route-error.tsx` carries its own equivalent copy of this logic; it was
+ * left in place deliberately rather than refactored alongside an unrelated
+ * change, and can adopt this component whenever that file is next touched.
+ */
+export function OptionalI18nProvider({ children }: { children: ReactNode }) {
+  // Already inside a provider — reuse it (keeps the active locale) and skip
+  // the self-mount entirely.
+  if (useContext(I18nContext) != null) {
+    return <>{children}</>
+  }
+  let bundle: TranslationBundle = {}
+  let locale = 'en'
+  try {
+    const { i18n } = getAdminConfig()
+    bundle = i18n.translations ?? {}
+    // No active provider, so render in the default locale — recovering the
+    // per-user active locale isn't worth another lookup that could itself throw.
+    locale = i18n.admin.defaultLocale
+  } catch {
+    // Config unavailable (very early boot / broken provider chain) — fall
+    // through with the English defaults above.
+  }
+  return (
+    <I18nProvider
+      bundle={bundle}
+      activeLocale={locale}
+      defaultLocale={locale}
+      localeDefinitions={[]}
+    >
+      {children}
+    </I18nProvider>
+  )
+}

package/src/admin-shell/chrome/session-change-boundary.module.css

@@ -0,0 +1,112 @@
+/**
+ * SessionChangeBoundary — viewport-centred interstitial shown when the
+ * active login identity no longer matches the one this page was rendered
+ * for. Rare by design: it only appears on an account mismatch.
+ *
+ * Override handles:
+ *   .byline-session-change            — outer <main>, centres the card in the viewport
+ *   .byline-session-change-card       — the bordered card itself
+ *   .byline-session-change-title      — heading
+ *   .byline-session-change-body       — explanatory paragraph
+ *   .byline-session-change-account    — "Active account: …" line
+ *   .byline-session-change-error      — error paragraph (role="alert")
+ *   .byline-session-change-actions    — button row
+ */
+
+.main,
+:global(.byline-session-change) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100dvh;
+  padding: 1.5rem;
+  /* Bias the card just above the geometric centre — a dialog sitting dead
+     centre optically reads as slightly low. The extra bottom padding lifts it
+     by half its own value, and being proportional it degrades gracefully on
+     short viewports instead of clipping the card off the top. */
+  padding-bottom: calc(1.5rem + 12vh);
+}
+
+.card,
+:global(.byline-session-change-card) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  width: 100%;
+  max-width: 30rem;
+  padding: 1.5rem;
+  border: var(--border-width-thin) var(--border-style-solid) var(--gray-100);
+  border-radius: var(--border-radius-md);
+  background-color: var(--canvas-25);
+}
+
+:is([data-theme="dark"], :global(.dark)) .card,
+:is([data-theme="dark"], :global(.dark)) :global(.byline-session-change-card) {
+  border-color: var(--gray-700);
+  background-color: var(--canvas-800);
+}
+
+.title,
+:global(.byline-session-change-title) {
+  margin: 0;
+  font-size: var(--font-size-xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-snug);
+  letter-spacing: var(--letter-spacing-tight);
+  color: var(--gray-900);
+}
+
+:is([data-theme="dark"], :global(.dark)) .title,
+:is([data-theme="dark"], :global(.dark)) :global(.byline-session-change-title) {
+  color: var(--gray-100);
+}
+
+.body,
+:global(.byline-session-change-body) {
+  margin: 0;
+  font-size: var(--font-size-sm);
+  line-height: var(--line-height-relaxed);
+  color: var(--gray-700);
+}
+
+:is([data-theme="dark"], :global(.dark)) .body,
+:is([data-theme="dark"], :global(.dark)) :global(.byline-session-change-body) {
+  color: var(--gray-400);
+}
+
+.account,
+:global(.byline-session-change-account) {
+  margin: 0;
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--line-height-normal);
+  color: var(--gray-900);
+  overflow-wrap: anywhere;
+}
+
+:is([data-theme="dark"], :global(.dark)) .account,
+:is([data-theme="dark"], :global(.dark)) :global(.byline-session-change-account) {
+  color: var(--gray-100);
+}
+
+.error,
+:global(.byline-session-change-error) {
+  margin: 0;
+  font-size: var(--font-size-sm);
+  line-height: var(--line-height-relaxed);
+  color: var(--red-600);
+}
+
+:is([data-theme="dark"], :global(.dark)) .error,
+:is([data-theme="dark"], :global(.dark)) :global(.byline-session-change-error) {
+  color: var(--red-400);
+}
+
+.actions,
+:global(.byline-session-change-actions) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.75rem;
+  margin-top: 0.25rem;
+}

package/src/admin-shell/chrome/session-change-boundary.test.tsx

@@ -0,0 +1,91 @@
+/**
+ * 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 { act } from 'react'
+
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ current: vi.fn() }))
+vi.mock('../../server-fns/auth/current-user.js', () => ({ getCurrentAdminUser: mocks.current }))
+vi.mock('../../routes/sign-in-path.js', () => ({ getSignInRoutePath: () => '/sign-in' }))
+
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+
+import { acceptSession, expectedSession } from '../../integrations/session-coordination.js'
+import { SessionChangeBoundary } from './session-change-boundary.js'
+
+const user = (sessionId: string, email: string) => ({
+  sessionId,
+  email,
+  id: email,
+  given_name: null,
+  family_name: null,
+  is_super_admin: false,
+  abilities: [],
+})
+let root: Root
+let container: HTMLDivElement
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  vi.stubGlobal('BroadcastChannel', undefined)
+  window.sessionStorage.clear()
+  acceptSession('expected-B')
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  vi.unstubAllGlobals()
+})
+// Mounted inside a real provider so the assertions below read the shipped
+// English strings, and so the boundary's `OptionalI18nProvider` exercises its
+// reuse path (an existing context is preserved rather than self-mounted).
+async function render() {
+  await act(async () => {
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+      >
+        <SessionChangeBoundary user={user('late-A', 'x@example.test')}>
+          <button type="button">Publish</button>
+        </SessionChangeBoundary>
+      </I18nProvider>
+    )
+  })
+}
+describe('session-change acknowledgement', () => {
+  it('blocks business UI on the first post-sign-in render when cookies select a different login', async () => {
+    mocks.current.mockResolvedValue(user('late-A', 'x@example.test'))
+    await render()
+    expect(container.textContent).not.toContain('Publish')
+    expect(container.querySelector('[role="alertdialog"]')).not.toBeNull()
+    expect(container.textContent).toContain('Active account: x@example.test')
+    expect(expectedSession()).toBe('expected-B')
+  })
+  it('requires renewed acknowledgement when the server account changes again', async () => {
+    mocks.current.mockResolvedValue(user('late-A', 'x@example.test'))
+    await render()
+    mocks.current.mockResolvedValue(user('new-C', 'z@example.test'))
+    await act(async () => {
+      container.querySelector('button')?.click()
+    })
+    expect(container.textContent).toContain(
+      'The active session changed again. Review the account before continuing.'
+    )
+    expect(expectedSession()).toBe('expected-B')
+    expect(container.textContent).not.toContain('Publish')
+  })
+})

package/src/admin-shell/chrome/session-change-boundary.tsx

@@ -0,0 +1,155 @@
+/**
+ * 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 { type ReactNode, useEffect, useState, useSyncExternalStore } from 'react'
+
+import { useTranslation } from '@byline/i18n/react'
+import { Button } from '@byline/ui/react'
+import cx from 'clsx'
+
+import {
+  acceptSession,
+  expectedSession,
+  flagSessionChanged,
+  observeSession,
+  sessionEpoch,
+  sessionIsChanged,
+  startSessionNotifications,
+  subscribeSessionChange,
+} from '../../integrations/session-coordination.js'
+import { getSignInRoutePath } from '../../routes/sign-in-path.js'
+import { type CurrentAdminUser, getCurrentAdminUser } from '../../server-fns/auth/current-user.js'
+import { OptionalI18nProvider } from './optional-i18n-provider.js'
+import styles from './session-change-boundary.module.css'
+
+/** Blocks the page until the user explicitly acknowledges freshly verified login identity. */
+export function SessionChangeBoundary({
+  user,
+  children,
+}: {
+  user?: CurrentAdminUser
+  children: ReactNode
+}) {
+  const epoch = useSyncExternalStore(subscribeSessionChange, sessionEpoch, () => 0)
+  const changed = sessionIsChanged()
+  const [current, setCurrent] = useState(user)
+  const [error, setError] = useState<string>()
+  const [busy, setBusy] = useState(false)
+  const mismatch =
+    typeof window !== 'undefined' &&
+    !!user &&
+    !!expectedSession() &&
+    expectedSession() !== user.sessionId
+  useEffect(() => {
+    startSessionNotifications()
+    if (user) {
+      try {
+        observeSession(user.sessionId)
+      } catch {
+        /* Interstitial owns this mismatch. */
+      }
+    }
+  }, [user])
+  useEffect(() => {
+    if (!changed && !mismatch) return
+    void getCurrentAdminUser()
+      .then((verified) => {
+        if (sessionEpoch() !== epoch) return
+        setCurrent(verified)
+        setError(undefined)
+      })
+      .catch(() => setError('sessionChange.errors.unavailable'))
+  }, [changed, mismatch, epoch])
+  if (!changed && !mismatch) return children
+  async function acknowledge() {
+    setBusy(true)
+    try {
+      const verified = await getCurrentAdminUser()
+      // Require a second acknowledgement if the identity changed while this interstitial was open.
+      if (!current || current.sessionId !== verified.sessionId) {
+        setCurrent(verified)
+        setError('sessionChange.errors.changedAgain')
+        return
+      }
+      acceptSession(verified.sessionId)
+      window.location.reload() // Discard queued edits and old page state; never replay them.
+    } catch {
+      flagSessionChanged()
+      setError('sessionChange.errors.unverifiable')
+    } finally {
+      setBusy(false)
+    }
+  }
+  return (
+    <OptionalI18nProvider>
+      <SessionChangeInterstitial
+        current={current}
+        errorKey={error}
+        busy={busy}
+        onAcknowledge={acknowledge}
+      />
+    </OptionalI18nProvider>
+  )
+}
+
+/**
+ * Presentation half. Split out so the error state can be carried as a
+ * translation *key* through the logic above and resolved here, inside the
+ * provider — the boundary itself renders outside any `<I18nProvider>` at
+ * both of its mount sites.
+ */
+function SessionChangeInterstitial({
+  current,
+  errorKey,
+  busy,
+  onAcknowledge,
+}: {
+  current?: CurrentAdminUser
+  errorKey?: string
+  busy: boolean
+  onAcknowledge: () => void
+}) {
+  const { t } = useTranslation('byline-admin')
+  return (
+    <main
+      className={cx('byline-session-change', styles.main)}
+      role="alertdialog"
+      aria-modal="true"
+      aria-labelledby="session-change-title"
+    >
+      <div className={cx('byline-session-change-card', styles.card)}>
+        <h1 id="session-change-title" className={cx('byline-session-change-title', styles.title)}>
+          {t('sessionChange.title')}
+        </h1>
+        <p className={cx('byline-session-change-body', styles.body)}>{t('sessionChange.body')}</p>
+        {current && (
+          <p className={cx('byline-session-change-account', styles.account)}>
+            {t('sessionChange.activeAccount', { email: current.email })}
+          </p>
+        )}
+        {errorKey && (
+          <p className={cx('byline-session-change-error', styles.error)} role="alert">
+            {t(errorKey)}
+          </p>
+        )}
+        <div className={cx('byline-session-change-actions', styles.actions)}>
+          <Button type="button" disabled={busy || !current} onClick={onAcknowledge}>
+            {t('sessionChange.continue')}
+          </Button>
+          <Button
+            variant="outlined"
+            intent="noeffect"
+            render={<a href={`${getSignInRoutePath()}?reauthenticate=1`} />}
+          >
+            {t('sessionChange.signInAgain')}
+          </Button>
+        </div>
+      </div>
+    </main>
+  )
+}

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