@byline/host-tanstack-start 4.19.0 → 5.1.0

package/src/server-fns/auth/sign-in.ts

@@ -18,13 +18,21 @@
  */
 
 import { createServerFn } from '@tanstack/react-start'
-import { getRequestHeader } from '@tanstack/react-start/server'
-
-import { setSessionCookies } from '@byline/client/server'
+import { getRequest, getRequestHeader } from '@tanstack/react-start/server'
+
+import type { SignInAdmission } from '@byline/auth'
+import {
+  readAccessTokenCookie,
+  readRefreshTokenCookie,
+  setSessionCookies,
+} from '@byline/client/server'
 import { getServerConfig } from '@byline/core'
+import { passwordSignInSchema } from '@byline/core/validation'
 
 import { readAdminLocaleCookie } from '../../i18n/locale-cookie.js'
 import { bylineCore } from '../../integrations/byline-core.js'
+import { normalizeClientIp } from '../../integrations/client-ip.js'
+import { wasSignInBodyChecked } from '../../integrations/sign-in-body.js'
 
 export interface SignInInput {
   email: string
@@ -33,17 +41,14 @@ export interface SignInInput {
 
 export interface SignInResult {
   userId: string
+  sessionId: string
 }
 
 export const adminSignIn = createServerFn({ method: 'POST' })
-  .validator((input: SignInInput) => {
-    if (typeof input?.email !== 'string' || input.email.length === 0) {
-      throw new Error('email is required')
-    }
-    if (typeof input?.password !== 'string' || input.password.length === 0) {
-      throw new Error('password is required')
-    }
-    return { email: input.email, password: input.password }
+  .validator((input: unknown) => {
+    const parsed = passwordSignInSchema.safeParse(input)
+    if (!parsed.success) throw new Response('Invalid sign-in input', { status: 400 })
+    return parsed.data
   })
   .handler(async ({ data }): Promise<SignInResult> => {
     const provider = getServerConfig().sessionProvider
@@ -51,21 +56,69 @@ export const adminSignIn = createServerFn({ method: 'POST' })
       throw new Error('no sessionProvider configured')
     }
 
-    // TanStack Start doesn't currently expose the raw request IP in a
-    // cross-runtime way; pass what we can observe and leave the ip field
-    // unset. Operators who need accurate client IPs for refresh-token
-    // provenance will typically run behind a reverse proxy that stamps
-    // `x-forwarded-for` — revisit when Phase 5 sees real deployments.
-    const userAgent = getRequestHeader('user-agent') ?? undefined
-    const forwardedFor = getRequestHeader('x-forwarded-for') ?? undefined
-    const ip = forwardedFor?.split(',')[0]?.trim() || undefined
-
-    const result = await provider.signInWithPassword({
-      email: data.email,
-      password: data.password,
-      userAgent,
-      ip,
-    })
+    const request = getRequest()
+    const protection = getServerConfig().passwordSignIn
+    if (!wasSignInBodyChecked(request)) {
+      throw new Response('Password sign-in request middleware is not configured', { status: 503 })
+    }
+    if (!protection) {
+      throw new Response('Password sign-in protection is not configured', { status: 503 })
+    }
+    const userAgent = getRequestHeader('user-agent')?.slice(0, 512)
+    let ip: string | null
+    try {
+      ip = normalizeClientIp(await protection.resolveClientIp(request))
+    } catch {
+      throw new Response('Client address unavailable', { status: 503 })
+    }
+    if (!ip) throw new Response('Client address unavailable', { status: 503 })
+    const tooMany = (seconds: number) =>
+      new Response('Too many sign-in attempts', {
+        status: 429,
+        headers: { 'Retry-After': String(seconds), 'Cache-Control': 'no-store' },
+      })
+    let release: (() => void) | null
+    try {
+      release = await protection.limiter.acquire()
+    } catch {
+      throw new Response('Sign-in temporarily unavailable', { status: 503 })
+    }
+    if (!release) throw tooMany(1)
+    const recordResult = (outcome: 'success' | 'failure') => {
+      try {
+        protection.limiter.recordResult?.({ email: data.email, ip }, outcome)
+      } catch {
+        /* Telemetry cannot change authentication outcomes. */
+      }
+    }
+    const result = await (async () => {
+      try {
+        let admission: SignInAdmission
+        try {
+          admission = await protection.limiter.consume({ email: data.email, ip })
+        } catch {
+          throw new Response('Sign-in temporarily unavailable', { status: 503 })
+        }
+        if (!admission.allowed) throw tooMany(admission.retryAfterSeconds)
+        try {
+          const result = await provider.signInWithPassword({
+            previousAccessToken: readAccessTokenCookie(),
+            previousRefreshToken: readRefreshTokenCookie(),
+            email: data.email,
+            password: data.password,
+            userAgent,
+            ip,
+          })
+          recordResult('success')
+          return result
+        } catch (error) {
+          recordResult('failure')
+          throw error
+        }
+      } finally {
+        release()
+      }
+    })()
 
     setSessionCookies(result)
 
@@ -82,7 +135,7 @@ export const adminSignIn = createServerFn({ method: 'POST' })
       // Swallow — locale sync is not load-bearing for the sign-in flow.
     }
 
-    return { userId: result.actor.id }
+    return { userId: result.actor.id, sessionId: result.sessionId }
   })
 
 /**

package/src/server-fns/auth/sign-out.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 { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  access: 'access' as string | undefined,
+  refresh: 'refresh' as string | undefined,
+  revoke: vi.fn(),
+  clear: vi.fn(),
+  clearPreview: vi.fn(),
+}))
+vi.mock('@tanstack/react-start', () => ({
+  createMiddleware: () => ({ client: () => ({}) }),
+  createServerFn: () => ({ middleware: () => ({ handler: (handler: any) => handler }) }),
+}))
+vi.mock('@byline/core', () => ({
+  getServerConfig: () => ({ sessionProvider: { revokeSession: mocks.revoke } }),
+}))
+vi.mock('@byline/client/server', () => ({
+  readAccessTokenCookie: () => mocks.access,
+  readRefreshTokenCookie: () => mocks.refresh,
+  clearSessionCookies: mocks.clear,
+  clearPreviewCookie: mocks.clearPreview,
+}))
+
+import { adminSignOut } from './sign-out.js'
+
+const call = adminSignOut as unknown as (args: {
+  context: { expectedSessionId?: string }
+}) => Promise<unknown>
+beforeEach(() => {
+  vi.resetAllMocks()
+  mocks.access = 'access'
+  mocks.refresh = 'refresh'
+})
+
+describe('confirmed logout', () => {
+  it('revokes with both observed credentials before clearing cookies', async () => {
+    mocks.revoke.mockImplementation(async () => {
+      expect(mocks.clear).not.toHaveBeenCalled()
+    })
+    await expect(call({ context: { expectedSessionId: 'A' } })).resolves.toEqual({ status: 'ok' })
+    expect(mocks.revoke).toHaveBeenCalledWith({
+      accessToken: 'access',
+      refreshToken: 'refresh',
+      expectedSessionId: 'A',
+    })
+    expect(mocks.clear).toHaveBeenCalledOnce()
+  })
+  it('still requests revocation when only the access cookie remains', async () => {
+    mocks.refresh = undefined
+    await call({ context: { expectedSessionId: 'A' } })
+    expect(mocks.revoke).toHaveBeenCalledWith({
+      accessToken: 'access',
+      refreshToken: undefined,
+      expectedSessionId: 'A',
+    })
+  })
+  it('does not clear credentials or report success when revocation fails', async () => {
+    mocks.revoke.mockRejectedValue(new Error('database unavailable'))
+    await expect(call({ context: { expectedSessionId: 'A' } })).rejects.toThrow(
+      'database unavailable'
+    )
+    expect(mocks.clear).not.toHaveBeenCalled()
+    expect(mocks.clearPreview).not.toHaveBeenCalled()
+  })
+  it('requires the page identity before revoking any observed credential', async () => {
+    await expect(call({ context: {} })).rejects.toMatchObject({ code: 'ERR_SESSION_CHANGED' })
+    expect(mocks.revoke).not.toHaveBeenCalled()
+    expect(mocks.clear).not.toHaveBeenCalled()
+  })
+  it('is idempotent when neither credential is present', async () => {
+    mocks.access = undefined
+    mocks.refresh = undefined
+    await expect(call({ context: {} })).resolves.toEqual({ status: 'ok' })
+    expect(mocks.revoke).not.toHaveBeenCalled()
+    expect(mocks.clear).toHaveBeenCalledOnce()
+  })
+})

package/src/server-fns/auth/sign-out.ts

@@ -9,9 +9,9 @@
 /**
  * Admin sign-out server function.
  *
- * Revokes the current refresh token (so a stolen copy cannot be reused),
+ * Revokes the login identified by either credential (so a stolen copy cannot be reused),
  * clears both session cookies, and clears the preview-mode cookie.
- * Idempotent — if the caller already lacks a refresh cookie, we still
+ * Idempotent — if the caller already lacks both credential cookies, we still
  * clear whatever's there and return successfully.
  *
  * Note: clearing `byline_preview` here is hygiene, not a security
@@ -21,32 +21,57 @@
  * Clearing it simply means the next sign-in starts in non-preview mode.
  */
 
-import { createServerFn } from '@tanstack/react-start'
+import { createMiddleware, createServerFn } from '@tanstack/react-start'
 
+import { ERR_SESSION_CHANGED } from '@byline/auth'
 import {
   clearPreviewCookie,
   clearSessionCookies,
+  readAccessTokenCookie,
   readRefreshTokenCookie,
 } from '@byline/client/server'
 import { getServerConfig } from '@byline/core'
 
-export const adminSignOut = createServerFn({ method: 'POST' }).handler(async () => {
-  const provider = getServerConfig().sessionProvider
-  const refreshToken = readRefreshTokenCookie()
+import {
+  coordinateAuthAction,
+  flagSessionChanged,
+  notifySessionAction,
+  sessionSnapshot,
+} from '../../integrations/session-coordination.js'
 
-  if (provider && refreshToken) {
-    // Best-effort revoke — `revokeSession` itself is idempotent for
-    // unknown/already-revoked tokens, so failures here would almost
-    // certainly be transport-level. Swallow and continue: the cookies
-    // get cleared regardless, so the caller's session ends.
+const signOutBoundary = createMiddleware({ type: 'function' }).client(async ({ next }) => {
+  const snapshot = sessionSnapshot()
+  return coordinateAuthAction(async () => {
     try {
-      await provider.revokeSession(refreshToken)
-    } catch {
-      // no-op
+      const result = await next({ sendContext: { expectedSessionId: snapshot.sessionId } })
+      notifySessionAction()
+      return result
+    } catch (error) {
+      if ((error as { code?: string })?.code === 'ERR_SESSION_CHANGED') flagSessionChanged()
+      throw error
     }
-  }
-
-  clearSessionCookies()
-  clearPreviewCookie()
-  return { status: 'ok' as const }
+  })
 })
+
+export const adminSignOut = createServerFn({ method: 'POST' })
+  .middleware([signOutBoundary])
+  .handler(async ({ context }) => {
+    const provider = getServerConfig().sessionProvider
+    const refreshToken = readRefreshTokenCookie()
+    const accessToken = readAccessTokenCookie()
+
+    if (refreshToken || accessToken) {
+      if (!provider) throw new Error('no sessionProvider configured')
+      if (!context.expectedSessionId)
+        throw ERR_SESSION_CHANGED({ message: 'logout requires the page login identity' })
+      await provider.revokeSession({
+        refreshToken,
+        accessToken,
+        expectedSessionId: context.expectedSessionId,
+      })
+    }
+
+    clearSessionCookies()
+    clearPreviewCookie()
+    return { status: 'ok' as const }
+  })

package/src/server-fns/collections/audit.ts

@@ -12,6 +12,7 @@ import { getAdminBylineClient } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger } from '@byline/core'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
 import { type ActorLabelMap, resolveActorLabels } from './actors.js'
 
 // ---------------------------------------------------------------------------
@@ -49,6 +50,7 @@ export interface AuditLogEntryDto {
 // ---------------------------------------------------------------------------
 
 export const getCollectionDocumentAuditLog = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
   .validator((input: { collection: string; id: string; params?: AuditLogSearchParams }) => input)
   .handler(async ({ data }) => {
     const { collection: path, id, params } = data

package/src/server-fns/collections/copy-to-locale.ts

@@ -14,6 +14,8 @@ import type { CopyToLocaleResult, DocumentLifecycleContext } from '@byline/core/
 import { copyToLocale } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import {
   type CollectionDocumentCommittedHookFailureResponse,
   toCommittedDocumentHookFailureResponse,
@@ -33,8 +35,10 @@ import {
  * failures propagate to TanStack Start's transport layer.
  */
 export const copyDocumentToLocale = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
   .validator(
     (input: {
+      expectedRevision: number
       collection: string
       id: string
       sourceLocale: string
@@ -43,43 +47,46 @@ export const copyDocumentToLocale = createServerFn({ method: 'POST' })
     }) => input
   )
   .handler(
-    async ({
-      data: input,
-    }): Promise<CopyToLocaleResult | CollectionDocumentCommittedHookFailureResponse> => {
-      const { collection: path, id, sourceLocale, targetLocale, overwrite } = input
-      const logger = getLogger()
-      const config = await ensureCollection(path)
-      if (!config) {
-        throw ERR_NOT_FOUND({
-          message: 'Collection not found',
-          details: { collectionPath: path },
-        }).log(logger)
-      }
+    withDocumentMutationErrors(
+      async ({
+        data: input,
+      }): Promise<CopyToLocaleResult | CollectionDocumentCommittedHookFailureResponse> => {
+        const { collection: path, id, sourceLocale, targetLocale, overwrite } = input
+        const logger = getLogger()
+        const config = await ensureCollection(path)
+        if (!config) {
+          throw ERR_NOT_FOUND({
+            message: 'Collection not found',
+            details: { collectionPath: path },
+          }).log(logger)
+        }
 
-      const serverConfig = getServerConfig()
-      const ctx: DocumentLifecycleContext = {
-        db: serverConfig.db,
-        definition: config.definition,
-        collectionId: config.collection.id,
-        collectionVersion: config.collection.version,
-        collectionPath: path,
-        logger,
-        defaultLocale: serverConfig.i18n.content.defaultLocale,
-        slugifier: serverConfig.slugifier,
-        requestContext: await getAdminRequestContext(),
-      }
+        const serverConfig = getServerConfig()
+        const ctx: DocumentLifecycleContext = {
+          db: serverConfig.db,
+          definition: config.definition,
+          collectionId: config.collection.id,
+          collectionVersion: config.collection.version,
+          collectionPath: path,
+          logger,
+          defaultLocale: serverConfig.i18n.content.defaultLocale,
+          slugifier: serverConfig.slugifier,
+          requestContext: await getAdminRequestContext(),
+        }
 
-      try {
-        return await copyToLocale(ctx, {
-          documentId: id,
-          sourceLocale,
-          targetLocale,
-          overwrite,
-        })
-      } catch (error) {
-        const committedFailure = toCommittedDocumentHookFailureResponse(error)
-        if (committedFailure != null) return committedFailure
-        throw error
+        try {
+          return await copyToLocale(ctx, {
+            documentId: id,
+            expectedRevision: input.expectedRevision,
+            sourceLocale,
+            targetLocale,
+            overwrite,
+          })
+        } catch (error) {
+          const committedFailure = toCommittedDocumentHookFailureResponse(error)
+          if (committedFailure != null) return committedFailure
+          throw error
+        }
       }
-    }
+    )
   )

package/src/server-fns/collections/create.ts

@@ -14,6 +14,8 @@ import type { CreateDocumentResult, DocumentLifecycleContext } from '@byline/cor
 import { createDocument } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
@@ -21,6 +23,7 @@ import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 // ---------------------------------------------------------------------------
 
 export const createCollectionDocument = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
   .validator(
     (input: {
       collection: string
@@ -30,56 +33,59 @@ export const createCollectionDocument = createServerFn({ method: 'POST' })
       availableLocales?: string[]
     }) => input
   )
-  .handler(async ({ data: input }) => {
-    const {
-      collection: path,
-      data: documentData,
-      locale,
-      path: explicitPath,
-      availableLocales,
-    } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
-
-    const serverConfig = getServerConfig()
-    const ctx: DocumentLifecycleContext = {
-      db: serverConfig.db,
-      definition: config.definition,
-      collectionId: config.collection.id,
-      collectionVersion: config.collection.version,
-      collectionPath: path,
-      logger,
-      defaultLocale: serverConfig.i18n.content.defaultLocale,
-      slugifier: serverConfig.slugifier,
-      requestContext: await getAdminRequestContext(),
-    }
-
-    let result: CreateDocumentResult
-    try {
-      result = await createDocument(ctx, {
-        data: structuredClone(documentData),
-        status: documentData.status,
-        locale: locale ?? serverConfig.i18n.content.defaultLocale,
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const {
+        collection: path,
+        data: documentData,
+        locale,
         path: explicitPath,
         availableLocales,
-      })
-    } catch (error) {
-      const committedFailure = toCommittedDocumentHookFailureResponse(error)
-      if (committedFailure != null) return committedFailure
-      throw error
-    }
+      } = input
+      const logger = getLogger()
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(logger)
+      }
+
+      const serverConfig = getServerConfig()
+      const ctx: DocumentLifecycleContext = {
+        db: serverConfig.db,
+        definition: config.definition,
+        collectionId: config.collection.id,
+        collectionVersion: config.collection.version,
+        collectionPath: path,
+        logger,
+        defaultLocale: serverConfig.i18n.content.defaultLocale,
+        slugifier: serverConfig.slugifier,
+        requestContext: await getAdminRequestContext(),
+      }
 
-    // The new document's id is returned so the create view can navigate
-    // straight to the edit view (create → edit).
-    return {
-      status: 'ok' as const,
-      documentId: result.documentId,
-      documentVersionId: result.documentVersionId,
-    }
-  })
+      let result: CreateDocumentResult
+      try {
+        result = await createDocument(ctx, {
+          data: structuredClone(documentData),
+          status: documentData.status,
+          locale: locale ?? serverConfig.i18n.content.defaultLocale,
+          path: explicitPath,
+          availableLocales,
+        })
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
+
+      // The new document's id is returned so the create view can navigate
+      // straight to the edit view (create → edit).
+      return {
+        status: 'ok' as const,
+        documentId: result.documentId,
+        documentVersionId: result.documentVersionId,
+        revision: result.revision,
+      }
+    })
+  )

package/src/server-fns/collections/delete-locale.ts

@@ -14,6 +14,8 @@ import type { DeleteLocaleResult, DocumentLifecycleContext } from '@byline/core/
 import { deleteLocale } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import {
   type CollectionDocumentCommittedHookFailureResponse,
   toCommittedDocumentHookFailureResponse,
@@ -34,40 +36,49 @@ import {
  * transport layer.
  */
 export const deleteDocumentLocale = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; id: string; locale: string }) => input)
+  .middleware([adminSessionMiddleware])
+  .validator(
+    (input: { expectedRevision: number; collection: string; id: string; locale: string }) => input
+  )
   .handler(
-    async ({
-      data: input,
-    }): Promise<DeleteLocaleResult | CollectionDocumentCommittedHookFailureResponse> => {
-      const { collection: path, id, locale } = input
-      const logger = getLogger()
-      const config = await ensureCollection(path)
-      if (!config) {
-        throw ERR_NOT_FOUND({
-          message: 'Collection not found',
-          details: { collectionPath: path },
-        }).log(logger)
-      }
+    withDocumentMutationErrors(
+      async ({
+        data: input,
+      }): Promise<DeleteLocaleResult | CollectionDocumentCommittedHookFailureResponse> => {
+        const { collection: path, id, locale } = input
+        const logger = getLogger()
+        const config = await ensureCollection(path)
+        if (!config) {
+          throw ERR_NOT_FOUND({
+            message: 'Collection not found',
+            details: { collectionPath: path },
+          }).log(logger)
+        }
 
-      const serverConfig = getServerConfig()
-      const ctx: DocumentLifecycleContext = {
-        db: serverConfig.db,
-        definition: config.definition,
-        collectionId: config.collection.id,
-        collectionVersion: config.collection.version,
-        collectionPath: path,
-        logger,
-        defaultLocale: serverConfig.i18n.content.defaultLocale,
-        slugifier: serverConfig.slugifier,
-        requestContext: await getAdminRequestContext(),
-      }
+        const serverConfig = getServerConfig()
+        const ctx: DocumentLifecycleContext = {
+          db: serverConfig.db,
+          definition: config.definition,
+          collectionId: config.collection.id,
+          collectionVersion: config.collection.version,
+          collectionPath: path,
+          logger,
+          defaultLocale: serverConfig.i18n.content.defaultLocale,
+          slugifier: serverConfig.slugifier,
+          requestContext: await getAdminRequestContext(),
+        }
 
-      try {
-        return await deleteLocale(ctx, { documentId: id, locale })
-      } catch (error) {
-        const committedFailure = toCommittedDocumentHookFailureResponse(error)
-        if (committedFailure != null) return committedFailure
-        throw error
+        try {
+          return await deleteLocale(ctx, {
+            documentId: id,
+            expectedRevision: input.expectedRevision,
+            locale,
+          })
+        } catch (error) {
+          const committedFailure = toCommittedDocumentHookFailureResponse(error)
+          if (committedFailure != null) return committedFailure
+          throw error
+        }
       }
-    }
+    )
   )