@byline/host-tanstack-start 4.0.0 → 4.2.0

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

@@ -1,302 +0,0 @@
-/**
- * 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(),
-  getRequest: 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,
-  getRequest: mocks.getRequest,
-}))
-
-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()
-    // Default: no Start request in scope, so every call resolves fresh.
-    // The per-request memoization tests below override this with a
-    // stable request object.
-    mocks.getRequest.mockImplementation(() => {
-      throw new Error('No StartEvent found in AsyncLocalStorage')
-    })
-  })
-
-  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 without emitting Set-Cookie when no cookies are sent', async () => {
-    cookiesReturn({})
-
-    try {
-      await getAdminRequestContext()
-      expect.fail('expected ERR_UNAUTHENTICATED')
-    } catch (err) {
-      expect(err).toBeInstanceOf(AuthError)
-      expect((err as AuthError).code).toBe(AuthErrorCodes.UNAUTHENTICATED)
-    }
-    // Anonymous visitors must produce zero Set-Cookie headers so shared
-    // caches (Cloudflare) can cache public pages — a Set-Cookie on the
-    // response is a hard bypass signal for CDNs.
-    expect(setCookie).not.toHaveBeenCalled()
-  })
-
-  it('clears the stale access cookie when only an access token was sent', async () => {
-    cookiesReturn({ byline_access_token: 'stale' })
-    verifyAccessToken.mockRejectedValueOnce(new Error('expired'))
-
-    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)
-    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)
-  })
-
-  describe('per-request memoization', () => {
-    it('returns the same context instance — and requestId — for every call in one request', async () => {
-      mocks.getRequest.mockReturnValue({ id: 'request-a' })
-      cookiesReturn({
-        byline_access_token: 'valid-access',
-        byline_refresh_token: 'some-refresh',
-      })
-      verifyAccessToken.mockResolvedValue({ actor: stubActor() })
-
-      const first = await getAdminRequestContext()
-      const second = await getAdminRequestContext()
-
-      // Reads sharing a ReadContext bind one request authority; the token
-      // includes requestId, so it must be stable within a request.
-      expect(second).toBe(first)
-      expect(second.requestId).toBe(first.requestId)
-      expect(verifyAccessToken).toHaveBeenCalledTimes(1)
-    })
-
-    it('resolves independently across different requests', async () => {
-      cookiesReturn({
-        byline_access_token: 'valid-access',
-        byline_refresh_token: 'some-refresh',
-      })
-      verifyAccessToken.mockResolvedValue({ actor: stubActor() })
-
-      mocks.getRequest.mockReturnValue({ id: 'request-a' })
-      const first = await getAdminRequestContext()
-      mocks.getRequest.mockReturnValue({ id: 'request-b' })
-      const second = await getAdminRequestContext()
-
-      expect(second).not.toBe(first)
-      expect(second.requestId).not.toBe(first.requestId)
-      expect(verifyAccessToken).toHaveBeenCalledTimes(2)
-    })
-
-    it('burns at most one refresh rotation per request', async () => {
-      mocks.getRequest.mockReturnValue({ id: 'request-a' })
-      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 first = await getAdminRequestContext()
-      // A second unmemoized call would re-run the refresh dance against the
-      // request's stale cookie — now already rotated — and sign the admin out.
-      const second = await getAdminRequestContext()
-
-      expect(second).toBe(first)
-      expect(refreshSession).toHaveBeenCalledTimes(1)
-    })
-
-    it('memoizes the unauthenticated rejection within one request', async () => {
-      mocks.getRequest.mockReturnValue({ id: 'request-a' })
-      cookiesReturn({
-        byline_access_token: 'stale',
-        byline_refresh_token: 'bad-refresh',
-      })
-      verifyAccessToken.mockRejectedValue(new Error('expired'))
-      refreshSession.mockRejectedValue(new Error('revoked'))
-
-      await expect(getAdminRequestContext()).rejects.toMatchObject({
-        code: AuthErrorCodes.UNAUTHENTICATED,
-      })
-      await expect(getAdminRequestContext()).rejects.toMatchObject({
-        code: AuthErrorCodes.UNAUTHENTICATED,
-      })
-      expect(refreshSession).toHaveBeenCalledTimes(1)
-    })
-  })
-})

package/src/auth/auth-context.ts

@@ -1,142 +0,0 @@
-/**
- * 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.
- *
- * Resolution is memoized per request (`oncePerRequest`): every call within
- * one logical request returns the same `RequestContext` instance — same
- * actor snapshot, same `requestId`. Two invariants depend on this:
- *
- *   - The read-authorization layer binds each `ReadContext` to one
- *     immutable authority token that includes `requestId`; a fresh id per
- *     call makes any two reads sharing a `ReadContext` (the admin tree
- *     view, hook-threaded nested reads) throw
- *     'ReadContext cannot be reused across request authorities'.
- *   - The refresh path rotates the refresh token; a second unmemoized call
- *     in the same request would re-run the dance against the
- *     already-rotated cookie and sign the admin out.
- */
-
-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'
-import { oncePerRequest } from './request-scope.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> {
-  return oncePerRequest('byline:admin-request-context', resolveAdminRequestContext)
-}
-
-async function resolveAdminRequestContext(): 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) {
-    // Only emit cookie clears when the browser actually sent a stale access
-    // cookie — otherwise the response carries no Set-Cookie at all, which
-    // lets shared caches (Cloudflare) cache public pages for anonymous
-    // visitors. Set-Cookie on the response is a hard bypass signal for CDNs.
-    if (accessToken) {
-      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

@@ -1,113 +0,0 @@
-/**
- * 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,
-  })
-}

package/src/auth/preview-cookies.ts

@@ -1,73 +0,0 @@
-/**
- * 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 the front-end *preview mode* toggle.
- *
- * Preview mode lets a signed-in admin see draft (and other non-published)
- * versions on the public host pages without changing any markup or route
- * structure. The mechanic is intentionally narrow:
- *
- *   - A single httpOnly cookie (`byline_preview=1`) carries the user's
- *     "show me drafts" intent across requests within the same browser
- *     session.
- *   - The cookie's mere *presence* is the signal — there is no payload to
- *     verify. The actual safety check is the admin session: when the
- *     viewer client (or a server fn) sees the cookie, it tries to resolve
- *     `getAdminRequestContext()` and only elevates the read mode when a
- *     valid admin session resolves. A stale preview cookie on an
- *     anonymous browser falls through to public/published reads silently.
- *
- * Cookie attributes:
- *   - `httpOnly: true`   — inaccessible to JS; toggled only via server fns.
- *   - `sameSite: 'lax'`  — sent on top-level navigations only.
- *   - `secure: true` in production — https-only.
- *   - `path: '/'`        — visible to every public route.
- *   - `maxAge: 1 day`    — preview is meant to be a short-lived editorial
- *                          mode, not a permanent state. Admins can
- *                          re-enable from the admin UI when needed.
- */
-
-import { getCookie, setCookie } from '@tanstack/react-start/server'
-
-export const PREVIEW_COOKIE = 'byline_preview'
-const PREVIEW_MAX_AGE_SECONDS = 60 * 60 * 24 // 1 day
-
-const IS_PROD = process.env.NODE_ENV === 'production'
-
-/** True iff the preview cookie is currently set on the request. */
-export function readPreviewCookie(): boolean {
-  return getCookie(PREVIEW_COOKIE) === '1'
-}
-
-/**
- * Write the preview cookie. Callers should ensure the request is from a
- * valid admin session before invoking — the cookie itself is just a flag
- * and carries no proof of authorisation. See `enablePreviewModeFn` for
- * the canonical entry point.
- */
-export function setPreviewCookie(): void {
-  setCookie(PREVIEW_COOKIE, '1', {
-    httpOnly: true,
-    sameSite: 'lax',
-    secure: IS_PROD,
-    path: '/',
-    maxAge: PREVIEW_MAX_AGE_SECONDS,
-  })
-}
-
-/** Clear the preview cookie. Safe to call from any context. */
-export function clearPreviewCookie(): void {
-  setCookie(PREVIEW_COOKIE, '', {
-    httpOnly: true,
-    sameSite: 'lax',
-    secure: IS_PROD,
-    path: '/',
-    maxAge: 0,
-  })
-}