@byline/host-tanstack-start 5.1.2 → 5.1.3

package/src/routes/admin-layout-guard.test.node.ts

@@ -0,0 +1,136 @@
+/**
+ * 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 { isRedirect } from '@tanstack/react-router'
+
+import { ERR_ACCESS_EXPIRED, ERR_REVOKED_TOKEN, ERR_UNAUTHENTICATED } from '@byline/auth'
+import { describe, expect, it, vi } from 'vitest'
+
+import { loadAdminLayoutContext } from './admin-layout-guard.js'
+
+const context = { user: { sessionId: 'login-1' } }
+const signInPath = '/sign-in'
+const href = '/admin/collections/pages?page=2'
+
+function deps(overrides: Partial<Parameters<typeof loadAdminLayoutContext>[0]> = {}) {
+  return {
+    load: vi.fn().mockResolvedValue(context),
+    renewSession: vi.fn().mockResolvedValue(undefined),
+    isBrowser: true,
+    sessionChanged: () => false,
+    signInPath,
+    href,
+    ...overrides,
+  }
+}
+
+async function expectSignInRedirect(promise: Promise<unknown>) {
+  const error = await promise.then(
+    () => undefined,
+    (thrown: unknown) => thrown
+  )
+  expect(isRedirect(error)).toBe(true)
+  const options = (error as { options: { to?: string; search?: Record<string, unknown> } }).options
+  expect(options.to).toBe(signInPath)
+  expect(options.search).toEqual({ callbackUrl: href })
+}
+
+describe('loadAdminLayoutContext', () => {
+  it('returns the loaded context when the access credential verifies', async () => {
+    const d = deps()
+    await expect(loadAdminLayoutContext(d)).resolves.toBe(context)
+    expect(d.renewSession).not.toHaveBeenCalled()
+  })
+
+  it('renews in the browser after access expiry and retries the load once', async () => {
+    const d = deps({
+      load: vi
+        .fn()
+        .mockRejectedValueOnce(ERR_ACCESS_EXPIRED({ message: 'expired' }))
+        .mockResolvedValueOnce(context),
+    })
+    await expect(loadAdminLayoutContext(d)).resolves.toBe(context)
+    expect(d.renewSession).toHaveBeenCalledTimes(1)
+    expect(d.load).toHaveBeenCalledTimes(2)
+  })
+
+  it('redirects to sign-in on the server after access expiry without renewing', async () => {
+    const d = deps({
+      isBrowser: false,
+      load: vi.fn().mockRejectedValue(ERR_ACCESS_EXPIRED({ message: 'expired' })),
+    })
+    await expectSignInRedirect(loadAdminLayoutContext(d))
+    expect(d.renewSession).not.toHaveBeenCalled()
+    expect(d.load).toHaveBeenCalledTimes(1)
+  })
+
+  it('redirects to sign-in when browser renewal reports a terminal outcome', async () => {
+    const d = deps({
+      load: vi.fn().mockRejectedValue(ERR_ACCESS_EXPIRED({ message: 'expired' })),
+      renewSession: vi.fn().mockRejectedValue(ERR_REVOKED_TOKEN({ message: 'revoked' })),
+    })
+    await expectSignInRedirect(loadAdminLayoutContext(d))
+    expect(d.load).toHaveBeenCalledTimes(1)
+  })
+
+  it('redirects to sign-in when browser renewal fails for a non-auth reason', async () => {
+    const d = deps({
+      load: vi.fn().mockRejectedValue(ERR_ACCESS_EXPIRED({ message: 'expired' })),
+      renewSession: vi.fn().mockRejectedValue(new Error('network')),
+    })
+    await expectSignInRedirect(loadAdminLayoutContext(d))
+    expect(d.load).toHaveBeenCalledTimes(1)
+  })
+
+  it('propagates a non-auth failure from the retried load after a successful renewal', async () => {
+    const failure = new Error('analytics runtime unavailable')
+    const d = deps({
+      load: vi
+        .fn()
+        .mockRejectedValueOnce(ERR_ACCESS_EXPIRED({ message: 'expired' }))
+        .mockRejectedValueOnce(failure),
+    })
+    await expect(loadAdminLayoutContext(d)).rejects.toBe(failure)
+    expect(d.renewSession).toHaveBeenCalledTimes(1)
+  })
+
+  it('redirects to sign-in when the retried load still reports an auth error', async () => {
+    const d = deps({
+      load: vi
+        .fn()
+        .mockRejectedValueOnce(ERR_ACCESS_EXPIRED({ message: 'expired' }))
+        .mockRejectedValueOnce(ERR_UNAUTHENTICATED({ message: 'no session' })),
+    })
+    await expectSignInRedirect(loadAdminLayoutContext(d))
+    expect(d.renewSession).toHaveBeenCalledTimes(1)
+  })
+
+  it('redirects to sign-in without renewing when no session is present', async () => {
+    const d = deps({
+      load: vi.fn().mockRejectedValue(ERR_UNAUTHENTICATED({ message: 'no session' })),
+    })
+    await expectSignInRedirect(loadAdminLayoutContext(d))
+    expect(d.renewSession).not.toHaveBeenCalled()
+  })
+
+  it('redirects without renewing when the page already flagged a session change', async () => {
+    const d = deps({
+      sessionChanged: () => true,
+      load: vi.fn().mockRejectedValue(ERR_ACCESS_EXPIRED({ message: 'expired' })),
+    })
+    await expectSignInRedirect(loadAdminLayoutContext(d))
+    expect(d.renewSession).not.toHaveBeenCalled()
+  })
+
+  it('rethrows non-auth load failures unchanged', async () => {
+    const failure = new Error('database unavailable')
+    const d = deps({ load: vi.fn().mockRejectedValue(failure) })
+    await expect(loadAdminLayoutContext(d)).rejects.toBe(failure)
+    expect(d.renewSession).not.toHaveBeenCalled()
+  })
+})

package/src/routes/admin-layout-guard.ts

@@ -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
+ */
+
+/**
+ * Admin layout guard — decides between loading the authenticated layout
+ * context, renewing an expired session in the browser, and redirecting to
+ * sign-in.
+ *
+ * Renewal is explicit and browser-driven, so the two render contexts behave
+ * differently on `ERR_ACCESS_EXPIRED`:
+ *
+ *   - **Browser navigation** runs the coordinated renewal right here and
+ *     retries the load once. The user stays on the requested URL and sees
+ *     only the ordinary route pending state.
+ *   - **Server render** cannot rotate credentials (SSR never holds the
+ *     browser lock), and a server-side `beforeLoad` error would surface as
+ *     an HTTP 500, so the server redirects to the sign-in route. That route's
+ *     bootstrap performs the same renewal and returns to `callbackUrl`.
+ *
+ * Any renewal failure in the browser falls back to the same sign-in redirect:
+ * the sign-in bootstrap retries renewal once more and owns the terminal and
+ * service-failure presentation, so this guard adds no second error surface.
+ * Once renewal has succeeded, the retried load is treated like the initial
+ * one: auth outcomes redirect, everything else propagates.
+ */
+
+import { redirect } from '@tanstack/react-router'
+
+const AUTH_REDIRECT_CODES = new Set([
+  'ERR_UNAUTHENTICATED',
+  'ERR_ACCESS_EXPIRED',
+  'ERR_INVALID_TOKEN',
+  'ERR_REVOKED_TOKEN',
+  'ERR_ACCOUNT_DISABLED',
+  'ERR_SESSION_CHANGED',
+])
+
+export interface AdminLayoutGuardDeps<T> {
+  /** Load the full layout context; expected to verify the access credential first. */
+  load: () => Promise<T>
+  /** Coordinated browser renewal. Resolves on success and rejects on any failure. */
+  renewSession: () => Promise<void>
+  isBrowser: boolean
+  /** True when the page has already flagged a session change awaiting acknowledgement. */
+  sessionChanged: () => boolean
+  signInPath: string
+  /** The requested location, preserved as `callbackUrl` on redirect. */
+  href: string
+}
+
+export async function loadAdminLayoutContext<T>(deps: AdminLayoutGuardDeps<T>): Promise<T> {
+  const toSignIn = () =>
+    redirect({
+      to: deps.signInPath as never,
+      search: { callbackUrl: deps.href } as never,
+    })
+  try {
+    return await deps.load()
+  } catch (error) {
+    const code = errorCode(error)
+    const changed = deps.isBrowser && deps.sessionChanged()
+    if (!changed && !AUTH_REDIRECT_CODES.has(code)) throw error
+    if (changed || !deps.isBrowser || code !== 'ERR_ACCESS_EXPIRED') throw toSignIn()
+  }
+  try {
+    await deps.renewSession()
+  } catch {
+    // Terminal auth outcomes and service failures during renewal both hand
+    // over to the sign-in bootstrap, which owns retry and the terminal
+    // presentation.
+    throw toSignIn()
+  }
+  try {
+    return await deps.load()
+  } catch (error) {
+    // The session is renewed at this point. Only an auth outcome sends the
+    // user to sign-in; any other layout dependency failure reaches the
+    // route's error handling exactly as it would on the initial load.
+    if (AUTH_REDIRECT_CODES.has(errorCode(error))) throw toSignIn()
+    throw error
+  }
+}
+
+function errorCode(error: unknown): string {
+  return (error as { code?: unknown })?.code as string
+}

package/src/routes/create-admin-layout-route.tsx

@@ -10,17 +10,19 @@
  * Admin shell layout — authenticated-only.
  *
  * `beforeLoad` resolves the current admin user (which internally verifies
- * the access credential without rotating cookies). Expired access is
- * renewed by the sign-in bootstrap. On unauthenticated
- * requests we redirect to `/sign-in` with a `callbackUrl` so the user
- * lands back on the page they originally requested.
+ * the access credential without rotating cookies). Expired access on a
+ * browser-side navigation is renewed in place and the load retried, so the
+ * user stays on the requested URL; expired access on a server render, and
+ * every other unauthenticated outcome, redirects to `/sign-in` with a
+ * `callbackUrl` so the user lands back on the page they originally
+ * requested. See `admin-layout-guard.ts` for the decision table.
  *
  * The resolved user is returned as route context so every nested admin
  * route (and the `AdminAppBar`) can read it without an extra fetch.
  */
 
 import { useEffect } from 'react'
-import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
+import { createFileRoute, Outlet } from '@tanstack/react-router'
 
 import { applyStoredTheme } from '@byline/admin/admin-account/components/theme'
 import { BylineFieldServicesProvider } from '@byline/admin/react'
@@ -43,55 +45,40 @@ import { bylineAdminServices } from '../integrations/byline-admin-services.js'
 import { BylineAiAdminProvider } from '../integrations/byline-ai.js'
 import { bylineFieldServices } from '../integrations/byline-field-services.js'
 import { observeSession, sessionIsChanged } from '../integrations/session-coordination.js'
+import { renewExpectedSession } from '../integrations/session-renewal.js'
 import { getAnalyticsRuntime } from '../server-fns/analytics/index.js'
 import { getCurrentAdminUser } from '../server-fns/auth/index.js'
 import { getScheduledPublicationRuntime } from '../server-fns/collections/index.js'
 import { getActiveLocaleFn, setAdminLocaleFn } from '../server-fns/i18n/index.js'
+import { loadAdminLayoutContext } from './admin-layout-guard.js'
 import { getSignInRoutePath } from './sign-in-path.js'
 
 export function createAdminLayoutRoute(path: string) {
   const Route: any = createFileRoute(path as never)({
-    beforeLoad: async ({ location }: { location: { href: string } }) => {
-      const signInPath = getSignInRoutePath()
-      try {
-        const user = await getCurrentAdminUser()
-        if (typeof window !== 'undefined') observeSession(user.sessionId)
-        // Resolve the active interface locale once on the server so SSR
-        // and the hydrated client render the same translations and
-        // there's no locale flicker. Going through the server fn (rather
-        // than calling `resolveRequestLocale` directly) keeps
-        // `@tanstack/react-start/server` out of the client bundle — the
-        // same pattern `getCurrentAdminUser` uses for `getAdminRequestContext`.
-        const [activeLocale, scheduledPublicationRuntime, analyticsRuntime] = await Promise.all([
-          getActiveLocaleFn(),
-          getScheduledPublicationRuntime(),
-          getAnalyticsRuntime(),
-        ])
-        return { user, activeLocale, scheduledPublicationRuntime, analyticsRuntime }
-      } catch (error) {
-        const code = (error as { code?: string })?.code
-        if (
-          !(typeof window !== 'undefined' && sessionIsChanged()) &&
-          ![
-            'ERR_UNAUTHENTICATED',
-            'ERR_ACCESS_EXPIRED',
-            'ERR_INVALID_TOKEN',
-            'ERR_REVOKED_TOKEN',
-            'ERR_ACCOUNT_DISABLED',
-            'ERR_SESSION_CHANGED',
-          ].includes(code ?? '')
-        )
-          throw error
-        // `getCurrentAdminUser` (via `getAdminRequestContext`) throws
-        // `ERR_UNAUTHENTICATED` or a related auth error when no valid
-        // session is present. Redirect to sign-in with the original path
-        // so we can send the user back after they authenticate.
-        throw redirect({
-          to: signInPath as never,
-          search: { callbackUrl: location.href } as never,
-        })
-      }
-    },
+    beforeLoad: ({ location }: { location: { href: string } }) =>
+      loadAdminLayoutContext({
+        load: async () => {
+          const user = await getCurrentAdminUser()
+          if (typeof window !== 'undefined') observeSession(user.sessionId)
+          // Resolve the active interface locale once on the server so SSR
+          // and the hydrated client render the same translations and
+          // there's no locale flicker. Going through the server fn (rather
+          // than calling `resolveRequestLocale` directly) keeps
+          // `@tanstack/react-start/server` out of the client bundle — the
+          // same pattern `getCurrentAdminUser` uses for `getAdminRequestContext`.
+          const [activeLocale, scheduledPublicationRuntime, analyticsRuntime] = await Promise.all([
+            getActiveLocaleFn(),
+            getScheduledPublicationRuntime(),
+            getAnalyticsRuntime(),
+          ])
+          return { user, activeLocale, scheduledPublicationRuntime, analyticsRuntime }
+        },
+        renewSession: renewExpectedSession,
+        isBrowser: typeof window !== 'undefined',
+        sessionChanged: sessionIsChanged,
+        signInPath: getSignInRoutePath(),
+        href: location.href,
+      }),
     component: function AdminLayoutComponent() {
       const { user, activeLocale, scheduledPublicationRuntime, analyticsRuntime } =
         Route.useRouteContext() as {

package/src/server-fns/auth/current-user.test.node.ts

@@ -0,0 +1,85 @@
+/**
+ * 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, ERR_UNAUTHENTICATED } from '@byline/auth'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  context: vi.fn(),
+  refresh: 'refresh' as string | undefined,
+  getById: vi.fn(),
+}))
+vi.mock('@tanstack/react-start', () => ({
+  createServerFn: () => ({ handler: (handler: any) => ({ handler }) }),
+}))
+vi.mock('@byline/client/server', () => ({
+  getAdminRequestContext: mocks.context,
+  readRefreshTokenCookie: () => mocks.refresh,
+}))
+vi.mock('../../integrations/byline-core.js', () => ({
+  bylineCore: () => ({ adminStore: { adminUsers: { getById: mocks.getById } } }),
+}))
+
+import { getCurrentAdminSessionSoft } from './current-user.js'
+
+const endpoint = getCurrentAdminSessionSoft as unknown as { handler: () => Promise<any> }
+const row = {
+  id: 'admin-1',
+  email: 'editor@example.test',
+  given_name: null,
+  family_name: null,
+  is_super_admin: false,
+}
+
+beforeEach(() => {
+  vi.resetAllMocks()
+  mocks.refresh = 'refresh'
+})
+
+describe('getCurrentAdminSessionSoft', () => {
+  it('returns the user and no renewal hint when the access credential verifies', async () => {
+    mocks.context.mockResolvedValue({
+      actor: { id: 'admin-1', abilities: new Set(['collections.news.read']) },
+      sessionId: 'login-1',
+    })
+    mocks.getById.mockResolvedValue(row)
+    await expect(endpoint.handler()).resolves.toEqual({
+      user: { ...row, sessionId: 'login-1', abilities: ['collections.news.read'] },
+      renewable: false,
+    })
+  })
+
+  it('reports a renewable session when access expired and a refresh credential is present', async () => {
+    mocks.context.mockRejectedValue(ERR_ACCESS_EXPIRED({ message: 'expired' }))
+    await expect(endpoint.handler()).resolves.toEqual({ user: null, renewable: true })
+  })
+
+  it('does not report renewable when access expired without a refresh credential', async () => {
+    mocks.refresh = undefined
+    mocks.context.mockRejectedValue(ERR_ACCESS_EXPIRED({ message: 'expired' }))
+    await expect(endpoint.handler()).resolves.toEqual({ user: null, renewable: false })
+  })
+
+  it.each([
+    ERR_UNAUTHENTICATED({ message: 'anonymous' }),
+    ERR_REVOKED_TOKEN({ message: 'revoked' }),
+    new Error('database unavailable'),
+  ])('stays anonymous and non-renewable on %s', async (error) => {
+    mocks.context.mockRejectedValue(error)
+    await expect(endpoint.handler()).resolves.toEqual({ user: null, renewable: false })
+  })
+
+  it('stays anonymous when the session points at a deleted admin', async () => {
+    mocks.context.mockResolvedValue({
+      actor: { id: 'gone', abilities: new Set() },
+      sessionId: 'login-1',
+    })
+    mocks.getById.mockResolvedValue(null)
+    await expect(endpoint.handler()).resolves.toEqual({ user: null, renewable: false })
+  })
+})

package/src/server-fns/auth/current-user.ts

@@ -21,7 +21,7 @@
 import { createServerFn } from '@tanstack/react-start'
 
 import { type Actor, AuthError } from '@byline/auth'
-import { getAdminRequestContext } from '@byline/client/server'
+import { getAdminRequestContext, readRefreshTokenCookie } from '@byline/client/server'
 
 import { bylineCore } from '../../integrations/byline-core.js'
 
@@ -76,30 +76,59 @@ export const getCurrentAdminUser = createServerFn({ method: 'GET' }).handler(
 )
 
 /**
- * Soft variant for public-page consumers (e.g. the content admin bar that
- * renders only when the visitor is signed in). Returns `null` instead of
+ * Soft variants for public-page consumers (e.g. the content admin bar that
+ * renders only when the visitor is signed in). Return `null` instead of
  * throwing when there is no session — anonymous visitors are the common
  * case here, so a thrown error would be wrong shape for a public route
  * loader. Other failure modes (DB unavailable, session points to a
  * deleted admin) are still coerced to `null` so the bar simply hides.
+ *
+ * `getCurrentAdminSessionSoft` additionally reports `renewable`: true when
+ * the access credential has expired but a refresh credential is present.
+ * Public reads never rotate credentials, so without this hint a signed-in
+ * editor's admin bar and preview mode silently vanish after the access
+ * lifetime. The host's `AdminSessionRecovery` component consumes it to run
+ * the coordinated browser renewal and re-run the page's loaders.
+ *
+ * `getCurrentAdminUserSoft` keeps the original `CurrentAdminUser | null`
+ * shape for existing integrations.
  */
+export interface CurrentAdminSession {
+  user: CurrentAdminUser | null
+  /** Access expired with a refresh credential present: the browser may renew and reload data. */
+  renewable: boolean
+}
+
+export const getCurrentAdminSessionSoft = createServerFn({ method: 'GET' }).handler(
+  async (): Promise<CurrentAdminSession> => resolveSoftSession()
+)
+
 export const getCurrentAdminUserSoft = createServerFn({ method: 'GET' }).handler(
-  async (): Promise<CurrentAdminUser | null> => {
+  async (): Promise<CurrentAdminUser | null> => (await resolveSoftSession()).user
+)
+
+const anonymous: CurrentAdminSession = { user: null, renewable: false }
+
+async function resolveSoftSession(): Promise<CurrentAdminSession> {
+  try {
+    let actor: Actor
+    let sessionId: string | undefined
     try {
-      let actor: Actor
-      let sessionId: string | undefined
-      try {
-        ;({ actor, sessionId } = await getAdminRequestContext())
-      } catch (err) {
-        if (err instanceof AuthError) return null
-        throw err
+      ;({ actor, sessionId } = await getAdminRequestContext())
+    } catch (err) {
+      if (err instanceof AuthError) {
+        const renewable = err.code === 'ERR_ACCESS_EXPIRED' && readRefreshTokenCookie() != null
+        return { user: null, renewable }
       }
-      if (!actor) return null
+      throw err
+    }
+    if (!actor) return anonymous
 
-      const row = await bylineCore().adminStore?.adminUsers.getById(actor.id)
-      if (!row) return null
+    const row = await bylineCore().adminStore?.adminUsers.getById(actor.id)
+    if (!row) return anonymous
 
-      return {
+    return {
+      user: {
         sessionId: sessionId!,
         id: row.id,
         email: row.email,
@@ -107,9 +136,10 @@ export const getCurrentAdminUserSoft = createServerFn({ method: 'GET' }).handler
         family_name: row.family_name,
         is_super_admin: row.is_super_admin,
         abilities: Array.from(actor.abilities),
-      }
-    } catch {
-      return null
+      },
+      renewable: false,
     }
+  } catch {
+    return anonymous
   }
-)
+}

package/src/server-fns/auth/index.ts

@@ -7,7 +7,9 @@
  */
 
 export {
+  type CurrentAdminSession,
   type CurrentAdminUser,
+  getCurrentAdminSessionSoft,
   getCurrentAdminUser,
   getCurrentAdminUserSoft,
 } from './current-user.js'