@byline/host-tanstack-start 0.9.3

package/src/admin-shell/collections/view-menu.tsx

@@ -0,0 +1,238 @@
+/**
+ * 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 { useEffect } from 'react'
+
+import type { CollectionAdminConfig, PreviewDocument } from '@byline/core'
+import { Button, HistoryIcon, IconButton, Label, Select } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { useNavigate } from '../chrome/loose-router.js'
+import { PreviewLink } from './preview-link.js'
+import styles from './view-menu.module.css'
+
+export type ViewMenuPaths = 'edit' | 'history' | 'api'
+
+export interface ContentLocaleOption {
+  code: string
+  label: string
+}
+
+/**
+ * Shared mini-navigation bar for document-level views (Edit, History, API).
+ * Renders a locale selector, the History icon button, Edit button, and API
+ * button with appropriate variant styling based on the currently active view.
+ * Changing the locale triggers a navigate to the current view's route so the
+ * loader re-fetches with the new locale — all three views react automatically.
+ *
+ * On the API route, an additional Depth selector appears — it drives the
+ * `populateDocuments` call inside the api loader and lets editors see
+ * what a client library `find({ populate: true, depth: N })` call would
+ * return. Capped at 3 in the UI to avoid runaway fan-out.
+ *
+ * `contentLocales` and `defaultContentLocale` are passed in from the host
+ * route shell (which reads them from the host's i18n config) so this
+ * component stays free of host-specific imports.
+ */
+export const ViewMenu = ({
+  collection,
+  documentId,
+  activeView,
+  locale,
+  depth,
+  contentLocales,
+  defaultContentLocale,
+  adminConfig,
+  doc,
+}: {
+  /** Collection path (e.g. "docs", "news"). */
+  collection: string
+  /** The document ID to navigate to. */
+  documentId: string
+  /** Which view is currently active — used to style the active button. */
+  activeView?: ViewMenuPaths
+  /** Current content locale. undefined means "All" (full multi-locale shape). */
+  locale?: string
+  /** Populate depth (api route only). undefined → 0 (no populate). */
+  depth?: number
+  /** Content locales the host advertises in language switchers. */
+  contentLocales: ReadonlyArray<ContentLocaleOption>
+  /** Fallback content locale used when the URL has none. */
+  defaultContentLocale: string
+  /**
+   * Admin config for the collection. When present and `adminConfig.preview`
+   * is configured (or the default URL convention applies), a `<PreviewLink>`
+   * external-link icon is rendered next to the History button.
+   */
+  adminConfig?: CollectionAdminConfig
+  /**
+   * The currently-loaded document. Required for the preview link's
+   * URL resolution; omit this prop to suppress the preview affordance
+   * entirely (e.g. on the create route, where no doc exists yet).
+   */
+  doc?: PreviewDocument
+}) => {
+  const navigate = useNavigate()
+
+  // Edit view must never use 'all' locale — strip it from the URL and fall
+  // back to the default locale if it somehow arrives via navigation.
+  useEffect(() => {
+    if (activeView === 'edit' && locale === 'all') {
+      navigate({
+        to: '/admin/collections/$collection/$id' as never,
+        params: { collection, id: documentId },
+        search: (prev: Record<string, unknown>) => ({
+          ...prev,
+          locale: defaultContentLocale,
+        }),
+      })
+    }
+  }, [activeView, locale, collection, documentId, defaultContentLocale, navigate])
+
+  const handleLocaleChange = (value: string | null) => {
+    if (value == null) return
+    // Always put locale explicitly in the URL — 'all' is stored as 'all',
+    // never as undefined, so the loader knows the intent unambiguously.
+    const search = (prev: Record<string, unknown>) => ({ ...prev, locale: value })
+    if (activeView === 'api') {
+      navigate({
+        to: '/admin/collections/$collection/$id/api' as never,
+        params: { collection, id: documentId },
+        search: search as never,
+      })
+    } else if (activeView === 'history') {
+      navigate({
+        to: '/admin/collections/$collection/$id/history' as never,
+        params: { collection, id: documentId },
+        search: search as never,
+      })
+    } else {
+      navigate({
+        to: '/admin/collections/$collection/$id' as never,
+        params: { collection, id: documentId },
+        search: search as never,
+      })
+    }
+  }
+
+  const handleDepthChange = (value: string | null) => {
+    if (value == null || activeView !== 'api') return
+    const n = Number.parseInt(value, 10)
+    const nextDepth = Number.isFinite(n) ? Math.max(0, Math.min(3, n)) : 0
+    navigate({
+      to: '/admin/collections/$collection/$id/api' as never,
+      params: { collection, id: documentId },
+      // Store 0 as undefined so the URL stays clean when the user picks
+      // "no populate" — avoids `?depth=0` in bookmarks / share links.
+      search: ((prev: Record<string, unknown>) => ({
+        ...prev,
+        depth: nextDepth === 0 ? undefined : nextDepth,
+      })) as never,
+    })
+  }
+
+  return (
+    <div className={cx('byline-view-menu', styles.root)}>
+      <Label
+        className={cx('muted byline-view-menu-label', styles.label)}
+        id="contentLocaleLabel"
+        htmlFor="contentLocale"
+        label="Content Locale:"
+      />
+      <Select<string>
+        name="contentLocale"
+        id="contentLocale"
+        className={cx('byline-view-menu-locale-select', styles.localeSelect)}
+        size="xs"
+        variant="outlined"
+        value={locale ?? defaultContentLocale}
+        items={[
+          ...(activeView !== 'edit' ? [{ value: 'all', label: 'All' }] : []),
+          ...contentLocales.map((loc) => ({ value: loc.code, label: loc.label })),
+        ]}
+        onValueChange={handleLocaleChange}
+      />
+      {activeView === 'api' && (
+        <>
+          <Label
+            className={cx('muted byline-view-menu-label', styles.label)}
+            id="populateDepthLabel"
+            htmlFor="populateDepth"
+            label="Depth:"
+          />
+          <Select<string>
+            name="populateDepth"
+            id="populateDepth"
+            className={cx('byline-view-menu-depth-select', styles.depthSelect)}
+            size="xs"
+            variant="outlined"
+            value={String(depth ?? 0)}
+            items={[
+              { value: '0', label: '0' },
+              { value: '1', label: '1' },
+              { value: '2', label: '2' },
+              { value: '3', label: '3' },
+            ]}
+            onValueChange={handleDepthChange}
+          />
+        </>
+      )}
+      {doc && (
+        <PreviewLink
+          collectionPath={collection}
+          doc={doc}
+          adminConfig={adminConfig}
+          locale={locale}
+          className={cx('byline-view-menu-icon-button', styles.iconButton)}
+        />
+      )}
+      <IconButton
+        className={cx('byline-view-menu-icon-button', styles.iconButton)}
+        size="xs"
+        variant={activeView === 'history' ? 'filled' : 'text'}
+        onClick={() =>
+          navigate({
+            to: '/admin/collections/$collection/$id/history' as never,
+            params: { collection, id: documentId },
+            search: locale ? { locale } : {},
+          })
+        }
+      >
+        <HistoryIcon className={cx('byline-view-menu-icon-button-icon', styles.iconButtonIcon)} />
+      </IconButton>
+      <Button
+        size="xs"
+        variant={activeView === 'edit' ? 'filled' : 'outlined'}
+        className={cx('byline-view-menu-button', styles.button)}
+        onClick={() =>
+          navigate({
+            to: '/admin/collections/$collection/$id' as never,
+            params: { collection, id: documentId },
+            search: locale ? { locale } : {},
+          })
+        }
+      >
+        Edit
+      </Button>
+      <Button
+        size="xs"
+        variant={activeView === 'api' ? 'filled' : 'outlined'}
+        className={cx('byline-view-menu-button', styles.button)}
+        onClick={() =>
+          navigate({
+            to: '/admin/collections/$collection/$id/api' as never,
+            params: { collection, id: documentId },
+            search: locale ? { locale } : {},
+          })
+        }
+      >
+        API
+      </Button>
+    </div>
+  )
+}

package/src/auth/auth-context.test.node.ts

@@ -0,0 +1,200 @@
+/**
+ * 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
+ */
+
+/**
+ * Unit coverage for the admin request-context resolver. Mocks the
+ * TanStack Start cookie helpers and the `bylineCore.sessionProvider` so
+ * the branches can be exercised without a live Postgres or JWT
+ * machinery.
+ */
+
+import { AdminAuth, AuthError, AuthErrorCodes } from '@byline/auth'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// ---------------------------------------------------------------------------
+// Mocks — must be declared before the module under test is imported.
+// `vi.mock` is hoisted to the top of the file, so the fakes themselves
+// have to go through `vi.hoisted` to be available when the factory runs.
+// ---------------------------------------------------------------------------
+
+const mocks = vi.hoisted(() => ({
+  verifyAccessToken: vi.fn(),
+  refreshSession: vi.fn(),
+  getCookie: vi.fn(),
+  setCookie: vi.fn(),
+  getRequestHeader: vi.fn(),
+}))
+
+vi.mock('@byline/core', async () => {
+  const actual = await vi.importActual<typeof import('@byline/core')>('@byline/core')
+  return {
+    ...actual,
+    getServerConfig: () => ({
+      sessionProvider: {
+        verifyAccessToken: mocks.verifyAccessToken,
+        refreshSession: mocks.refreshSession,
+      },
+    }),
+  }
+})
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getCookie: mocks.getCookie,
+  setCookie: mocks.setCookie,
+  getRequestHeader: mocks.getRequestHeader,
+}))
+
+const { verifyAccessToken, refreshSession, getCookie, setCookie } = mocks
+
+// Import AFTER mocks are declared.
+import { getAdminRequestContext } from './auth-context.js'
+
+// ---------------------------------------------------------------------------
+
+function cookiesReturn(values: Record<string, string | undefined>) {
+  getCookie.mockImplementation((name: string) => values[name])
+}
+
+function stubActor() {
+  return new AdminAuth({
+    id: 'admin-1',
+    abilities: ['collections.pages.read'],
+  })
+}
+
+describe('getAdminRequestContext', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns the actor directly when the access token verifies', async () => {
+    cookiesReturn({
+      byline_access_token: 'valid-access',
+      byline_refresh_token: 'some-refresh',
+    })
+    const actor = stubActor()
+    verifyAccessToken.mockResolvedValueOnce({ actor })
+
+    const ctx = await getAdminRequestContext()
+
+    expect(ctx.actor).toBe(actor)
+    expect(ctx.readMode).toBe('any')
+    expect(refreshSession).not.toHaveBeenCalled()
+    expect(setCookie).not.toHaveBeenCalled()
+  })
+
+  it('refreshes when the access token fails verification', async () => {
+    cookiesReturn({
+      byline_access_token: 'stale-access',
+      byline_refresh_token: 'valid-refresh',
+    })
+    const actor = stubActor()
+    verifyAccessToken.mockRejectedValueOnce(new Error('expired')).mockResolvedValueOnce({ actor })
+    refreshSession.mockResolvedValueOnce({
+      accessToken: 'fresh-access',
+      refreshToken: 'fresh-refresh',
+      accessTokenExpiresAt: new Date(Date.now() + 15 * 60_000),
+      refreshTokenExpiresAt: new Date(Date.now() + 30 * 24 * 60 * 60_000),
+    })
+
+    const ctx = await getAdminRequestContext()
+
+    expect(ctx.actor).toBe(actor)
+    expect(refreshSession).toHaveBeenCalledWith({ refreshToken: 'valid-refresh' })
+    // Both access + refresh cookies should have been written with maxAge > 0.
+    expect(setCookie).toHaveBeenCalledTimes(2)
+    const accessCall = setCookie.mock.calls.find((c) => c[0] === 'byline_access_token')
+    expect(accessCall?.[1]).toBe('fresh-access')
+    expect(accessCall?.[2]?.maxAge).toBeGreaterThan(0)
+  })
+
+  it('refreshes when the access cookie is missing but a refresh cookie exists', async () => {
+    cookiesReturn({ byline_refresh_token: 'only-refresh' })
+    const actor = stubActor()
+    refreshSession.mockResolvedValueOnce({
+      accessToken: 'fresh-access',
+      refreshToken: 'fresh-refresh',
+      accessTokenExpiresAt: new Date(Date.now() + 15 * 60_000),
+      refreshTokenExpiresAt: new Date(Date.now() + 30 * 24 * 60 * 60_000),
+    })
+    verifyAccessToken.mockResolvedValueOnce({ actor })
+
+    const ctx = await getAdminRequestContext()
+
+    expect(ctx.actor).toBe(actor)
+    // The access-token path was skipped (no cookie) so verifyAccessToken ran
+    // only for the freshly-issued token.
+    expect(verifyAccessToken).toHaveBeenCalledTimes(1)
+    expect(verifyAccessToken).toHaveBeenCalledWith('fresh-access')
+  })
+
+  it('throws ERR_UNAUTHENTICATED and clears cookies when no session exists', async () => {
+    cookiesReturn({})
+
+    try {
+      await getAdminRequestContext()
+      expect.fail('expected ERR_UNAUTHENTICATED')
+    } catch (err) {
+      expect(err).toBeInstanceOf(AuthError)
+      expect((err as AuthError).code).toBe(AuthErrorCodes.UNAUTHENTICATED)
+    }
+    // Cookie clear = setCookie with empty value and maxAge 0 for both names.
+    const clears = setCookie.mock.calls.filter((c) => c[2]?.maxAge === 0)
+    const clearedNames = new Set(clears.map((c) => c[0]))
+    expect(clearedNames.has('byline_access_token')).toBe(true)
+    expect(clearedNames.has('byline_refresh_token')).toBe(true)
+  })
+
+  it('clears cookies and throws when refresh itself fails', async () => {
+    cookiesReturn({
+      byline_access_token: 'stale',
+      byline_refresh_token: 'bad-refresh',
+    })
+    verifyAccessToken.mockRejectedValueOnce(new Error('expired'))
+    refreshSession.mockRejectedValueOnce(new Error('revoked'))
+
+    try {
+      await getAdminRequestContext()
+      expect.fail('expected ERR_UNAUTHENTICATED')
+    } catch (err) {
+      expect(err).toBeInstanceOf(AuthError)
+      expect((err as AuthError).code).toBe(AuthErrorCodes.UNAUTHENTICATED)
+    }
+    const clears = setCookie.mock.calls.filter((c) => c[2]?.maxAge === 0)
+    expect(clears.length).toBe(2)
+  })
+
+  it('clears cookies and throws when the refreshed access token fails to verify', async () => {
+    cookiesReturn({
+      byline_access_token: 'stale',
+      byline_refresh_token: 'valid',
+    })
+    verifyAccessToken
+      .mockRejectedValueOnce(new Error('expired'))
+      .mockRejectedValueOnce(new Error('still bad'))
+    refreshSession.mockResolvedValueOnce({
+      accessToken: 'fresh-but-somehow-bad',
+      refreshToken: 'fresh-refresh',
+      accessTokenExpiresAt: new Date(Date.now() + 15 * 60_000),
+      refreshTokenExpiresAt: new Date(Date.now() + 30 * 24 * 60 * 60_000),
+    })
+
+    try {
+      await getAdminRequestContext()
+      expect.fail('expected ERR_UNAUTHENTICATED')
+    } catch (err) {
+      expect((err as AuthError).code).toBe(AuthErrorCodes.UNAUTHENTICATED)
+    }
+    const clears = setCookie.mock.calls.filter((c) => c[2]?.maxAge === 0)
+    expect(clears.length).toBe(2)
+  })
+})

package/src/auth/auth-context.ts

@@ -0,0 +1,119 @@
+/**
+ * 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
+ */
+
+/**
+ * Request-scoped auth context for admin server functions.
+ *
+ * Reads the session cookies, verifies the access token, transparently
+ * refreshes when needed, and returns a `RequestContext` carrying the
+ * authenticated `AdminAuth`. Every admin server fn calls this as its
+ * first step — it is the single point where the admin transport boundary
+ * meets the actor/ability machinery.
+ *
+ * Flow, in order:
+ *
+ *   1. Read the access cookie.
+ *   2. If present, try `sessionProvider.verifyAccessToken`. On success,
+ *      return the context — no DB write, no cookie churn.
+ *   3. On verify failure (or missing access cookie), read the refresh
+ *      cookie. If present, call `sessionProvider.refreshSession` — this
+ *      rotates the refresh token atomically and issues a new access
+ *      token. Write both fresh cookies to the response.
+ *   4. Verify the new access token (populate the actor) and return the
+ *      context.
+ *   5. Any failure along the way clears both cookies so the browser
+ *      stops sending a session the server has already rejected, and
+ *      throws `ERR_UNAUTHENTICATED`.
+ *
+ * Burns a refresh-token rotation only when the access token actually
+ * fails verification — not on every request. The "one session" UX is
+ * the consequence of this helper working invisibly behind each call.
+ */
+
+import { ERR_UNAUTHENTICATED, type RequestContext } from '@byline/auth'
+import { getServerConfig } from '@byline/core'
+import { v7 as uuidv7 } from 'uuid'
+
+import {
+  clearSessionCookies,
+  readAccessTokenCookie,
+  readRefreshTokenCookie,
+  setSessionCookies,
+} from './auth-cookies.js'
+
+function requireSessionProvider() {
+  const provider = getServerConfig().sessionProvider
+  if (!provider) {
+    throw new Error(
+      'No sessionProvider configured on ServerConfig. ' +
+        'Construct a JwtSessionProvider in your server config and pass it to initBylineCore().'
+    )
+  }
+  return provider
+}
+
+export async function getAdminRequestContext(): Promise<RequestContext> {
+  const provider = requireSessionProvider()
+
+  const accessToken = readAccessTokenCookie()
+
+  // Happy path: valid access token.
+  if (accessToken) {
+    try {
+      const { actor } = await provider.verifyAccessToken(accessToken)
+      return {
+        actor,
+        requestId: uuidv7(),
+        readMode: 'any',
+      }
+    } catch {
+      // Fall through to refresh — we'll burn a rotation only when the
+      // access token genuinely can't verify.
+    }
+  }
+
+  // Refresh path: swap the refresh cookie for a fresh token pair.
+  const refreshToken = readRefreshTokenCookie()
+  if (!refreshToken) {
+    // No session at all — clear anything stale and reject.
+    clearSessionCookies()
+    throw ERR_UNAUTHENTICATED({ message: 'no admin session' })
+  }
+
+  let refreshed: Awaited<ReturnType<typeof provider.refreshSession>>
+  try {
+    refreshed = await provider.refreshSession({ refreshToken })
+  } catch (err) {
+    clearSessionCookies()
+    throw ERR_UNAUTHENTICATED({
+      message: 'admin session could not be refreshed',
+      cause: err,
+    })
+  }
+
+  // Write the new cookies so subsequent requests skip the refresh path.
+  setSessionCookies(refreshed)
+
+  // Verify the freshly-minted access token to extract the actor.
+  let verified: Awaited<ReturnType<typeof provider.verifyAccessToken>>
+  try {
+    verified = await provider.verifyAccessToken(refreshed.accessToken)
+  } catch (err) {
+    clearSessionCookies()
+    throw ERR_UNAUTHENTICATED({
+      message: 'refreshed access token did not verify',
+      cause: err,
+    })
+  }
+
+  return {
+    actor: verified.actor,
+    requestId: uuidv7(),
+    readMode: 'any',
+  }
+}

package/src/auth/auth-cookies.ts

@@ -0,0 +1,113 @@
+/**
+ * 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
+ */
+
+/**
+ * Cookie helpers for admin session management.
+ *
+ * Two separate httpOnly cookies, one for each token half:
+ *
+ *   - `byline_access_token`  — short-lived JWT; sent on every request.
+ *   - `byline_refresh_token` — long-lived opaque string; sent back only
+ *                              when the access cookie is missing or
+ *                              expired, to mint a new access token.
+ *
+ * Presenting "one session" to the user is a function of the middleware —
+ * `getAdminRequestContext()` transparently refreshes the access cookie
+ * using the refresh cookie, so the UI layer doesn't have to care.
+ *
+ * All cookies set here use:
+ *   - `httpOnly: true`   — inaccessible to JavaScript (XSS-hardened).
+ *   - `sameSite: 'lax'`  — sent on top-level navigations but not
+ *                          cross-origin subrequests (reasonable default
+ *                          for an admin SSR app).
+ *   - `secure: true` in production — https-only; dev keeps it off so
+ *                          cookies work on http://localhost.
+ *   - `path: '/'`        — available everywhere in the app.
+ */
+
+import { getCookie, setCookie } from '@tanstack/react-start/server'
+
+export const ACCESS_TOKEN_COOKIE = 'byline_access_token'
+export const REFRESH_TOKEN_COOKIE = 'byline_refresh_token'
+
+const IS_PROD = process.env.NODE_ENV === 'production'
+
+/** Read the access-token cookie. Returns undefined when not present. */
+export function readAccessTokenCookie(): string | undefined {
+  return getCookie(ACCESS_TOKEN_COOKIE)
+}
+
+/** Read the refresh-token cookie. Returns undefined when not present. */
+export function readRefreshTokenCookie(): string | undefined {
+  return getCookie(REFRESH_TOKEN_COOKIE)
+}
+
+export interface SessionCookieTokens {
+  accessToken: string
+  refreshToken: string
+  accessTokenExpiresAt: Date
+  refreshTokenExpiresAt: Date
+}
+
+/**
+ * Write both access and refresh cookies. Called after sign-in and after
+ * every transparent refresh in `getAdminRequestContext()`.
+ *
+ * `maxAge` is derived from each token's own expiry claim so the browser
+ * drops the cookies at the same moment the server would reject them —
+ * saves round trips when the refresh token has fully expired.
+ */
+export function setSessionCookies(tokens: SessionCookieTokens): void {
+  const now = Date.now()
+  const accessMaxAgeSeconds = Math.max(
+    0,
+    Math.floor((tokens.accessTokenExpiresAt.getTime() - now) / 1000)
+  )
+  const refreshMaxAgeSeconds = Math.max(
+    0,
+    Math.floor((tokens.refreshTokenExpiresAt.getTime() - now) / 1000)
+  )
+
+  setCookie(ACCESS_TOKEN_COOKIE, tokens.accessToken, {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: IS_PROD,
+    path: '/',
+    maxAge: accessMaxAgeSeconds,
+  })
+
+  setCookie(REFRESH_TOKEN_COOKIE, tokens.refreshToken, {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: IS_PROD,
+    path: '/',
+    maxAge: refreshMaxAgeSeconds,
+  })
+}
+
+/**
+ * Clear both session cookies. Called on sign-out and on any auth failure
+ * during `getAdminRequestContext()` (ensures the browser does not keep
+ * trying a token that the server has already rejected).
+ */
+export function clearSessionCookies(): void {
+  setCookie(ACCESS_TOKEN_COOKIE, '', {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: IS_PROD,
+    path: '/',
+    maxAge: 0,
+  })
+  setCookie(REFRESH_TOKEN_COOKIE, '', {
+    httpOnly: true,
+    sameSite: 'lax',
+    secure: IS_PROD,
+    path: '/',
+    maxAge: 0,
+  })
+}