@byline/host-tanstack-start 6.7.2 → 6.8.0

package/src/server-fns/auth/passkeys.test.node.ts

@@ -0,0 +1,247 @@
+import { AdminAuth, ERR_SESSION_CHANGED } from '@byline/auth'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  config: {} as any,
+  request: null as unknown as Request,
+  auth: vi.fn(),
+  user: vi.fn(),
+  setCookies: vi.fn(),
+  clearCookies: vi.fn(),
+  clearPreview: vi.fn(),
+  header: vi.fn(),
+  release: vi.fn(),
+  consume: vi.fn(),
+  acquire: vi.fn(),
+  passwordConsume: vi.fn(),
+  passwordRelease: vi.fn(),
+}))
+vi.mock('@tanstack/react-start', () => ({
+  createServerFn: () => {
+    const result: any = {
+      middleware: () => result,
+      validator: (validate: any) => {
+        result.validate = validate
+        return result
+      },
+      handler: (handler: any) => {
+        result.handler = handler
+        return result
+      },
+    }
+    return result
+  },
+}))
+vi.mock('@tanstack/react-start/server', () => ({
+  getRequest: () => mocks.request,
+  getRequestHeader: () => undefined,
+  setResponseHeader: mocks.header,
+}))
+vi.mock('@byline/core', () => ({ getServerConfig: () => mocks.config }))
+vi.mock('@byline/client/server', () => ({
+  getAdminRequestContext: mocks.auth,
+  readAccessTokenCookie: () => 'server-access',
+  readRefreshTokenCookie: () => 'server-refresh',
+  setSessionCookies: mocks.setCookies,
+  clearSessionCookies: mocks.clearCookies,
+  clearPreviewCookie: mocks.clearPreview,
+}))
+vi.mock('../../integrations/session-middleware.js', () => ({
+  adminSessionMiddleware: {},
+  adminSessionMutationMiddleware: {},
+}))
+vi.mock('../../integrations/byline-core.js', () => ({
+  bylineCore: () => ({ adminStore: { adminUsers: { getById: mocks.user } } }),
+}))
+vi.mock('../../i18n/locale-cookie.js', () => ({ readAdminLocaleCookie: () => null }))
+
+import { checkPasskeyBody } from '../../integrations/sign-in-body.js'
+import * as endpoints from './passkeys.js'
+
+const sid = '00000000-0000-4000-8000-000000000001'
+const userId = '00000000-0000-4000-8000-000000000002'
+const bearer = 'a'.repeat(43)
+const methods = [
+  'signInOptions',
+  'verifySignIn',
+  'passwordProof',
+  'proofOptions',
+  'verifyProof',
+  'enrollmentOptions',
+  'verifyEnrollment',
+  'listCredentials',
+  'renameCredential',
+  'removeCredential',
+]
+let provider: Record<string, ReturnType<typeof vi.fn>>
+const invoke = (endpoint: unknown, data: unknown = {}) => {
+  const fn = endpoint as {
+    validate?: (data: unknown) => unknown
+    handler: (args: any) => Promise<any>
+  }
+  return fn.handler({ data: fn.validate ? fn.validate(data) : data })
+}
+async function request(password = false) {
+  mocks.request = new Request('https://app.test/passkeys', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: '{}',
+  })
+  await checkPasskeyBody(mocks.request, password)
+}
+beforeEach(async () => {
+  vi.resetAllMocks()
+  provider = Object.fromEntries(methods.map((name) => [name, vi.fn().mockResolvedValue({})]))
+  mocks.auth.mockResolvedValue({
+    actor: new AdminAuth({ id: userId, abilities: [] }),
+    sessionId: sid,
+  })
+  mocks.user.mockResolvedValue({ id: userId, email: 'actor@example.test' })
+  mocks.acquire.mockResolvedValue(mocks.release)
+  mocks.consume.mockResolvedValue({ allowed: true, retryAfterSeconds: 0 })
+  mocks.passwordConsume.mockResolvedValue({ allowed: true, retryAfterSeconds: 0 })
+  mocks.config = {
+    passkeys: {},
+    sessionProvider: { capabilities: { passkeys: true }, passkeys: provider },
+    passkeyRequests: {
+      resolveClientIp: () => '192.0.2.1',
+      limiter: { acquire: mocks.acquire, consume: mocks.consume },
+    },
+    passwordSignIn: {
+      resolveClientIp: () => '192.0.2.1',
+      limiter: { acquire: async () => mocks.passwordRelease, consume: mocks.passwordConsume },
+    },
+  }
+  await request()
+})
+describe('passkey host endpoints', () => {
+  it('discovers only an enabled capability without starting a ceremony', async () => {
+    expect(await invoke(endpoints.getPasskeyCapability)).toEqual({ enabled: true })
+    delete mocks.config.passkeys
+    expect(await invoke(endpoints.getPasskeyCapability)).toEqual({ enabled: false })
+    expect(provider.signInOptions).not.toHaveBeenCalled()
+  })
+  it('keeps tokens server-side and writes cookies only after verified issuance', async () => {
+    const result = {
+      actor: { id: userId },
+      sessionId: sid,
+      accessToken: 'secret',
+      refreshToken: 'secret',
+    }
+    provider.verifySignIn.mockResolvedValue(result)
+    const response = { raw: 'untrusted' }
+    expect(await invoke(endpoints.passkeySignIn, { ceremonyId: bearer, response })).toEqual({
+      userId,
+      sessionId: sid,
+    })
+    expect(provider.verifySignIn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        previousAccessToken: 'server-access',
+        previousRefreshToken: 'server-refresh',
+        response,
+      })
+    )
+    expect(mocks.setCookies).toHaveBeenCalledWith(result)
+    expect(mocks.header).toHaveBeenCalledWith('Cache-Control', 'no-store')
+    provider.verifySignIn.mockRejectedValue(new Error('uncertain commit'))
+    await expect(invoke(endpoints.passkeySignIn, { ceremonyId: bearer, response })).rejects.toThrow(
+      'uncertain commit'
+    )
+    expect(mocks.setCookies).toHaveBeenCalledTimes(1)
+  })
+  it.each([undefined, false, true, 'false'])(
+    'forwards crossOrigin %s without rewriting signed response bytes',
+    async (crossOrigin) => {
+      const response = {
+        response: {
+          clientDataJSON: Buffer.from(JSON.stringify({ crossOrigin })).toString('base64url'),
+        },
+      }
+      await invoke(endpoints.passkeyProof, { expectedSessionId: sid, ceremonyId: bearer, response })
+      expect(provider.verifyProof.mock.calls[0][0].response).toBe(response)
+    }
+  )
+  it('applies both limiters with server-resolved email for password proof', async () => {
+    await request(true)
+    await invoke(endpoints.passkeyPasswordProof, {
+      expectedSessionId: sid,
+      password: 'legacy',
+      action: { purpose: 'enroll' },
+    })
+    expect(mocks.passwordConsume).toHaveBeenCalledWith({
+      email: 'actor@example.test',
+      ip: '192.0.2.1',
+    })
+    expect(mocks.consume).toHaveBeenCalledOnce()
+    expect(mocks.passwordRelease).toHaveBeenCalledOnce()
+    expect(provider.passwordProof).toHaveBeenCalledWith({
+      expectedSessionId: sid,
+      accessToken: 'server-access',
+      password: 'legacy',
+      action: { purpose: 'enroll' },
+    })
+  })
+  it('rejects a substituted expected login before proof or password lookup', async () => {
+    await request(true)
+    await expect(
+      invoke(endpoints.passkeyPasswordProof, {
+        expectedSessionId: userId,
+        password: 'legacy',
+        action: { purpose: 'enroll' },
+      })
+    ).rejects.toMatchObject({ code: 'ERR_SESSION_CHANGED' })
+    expect(mocks.user).not.toHaveBeenCalled()
+    expect(provider.passwordProof).not.toHaveBeenCalled()
+  })
+  it('does not let a client supply an email or access credential', () => {
+    expect(() =>
+      invoke(endpoints.passkeyPasswordProof, {
+        expectedSessionId: sid,
+        password: 'legacy',
+        action: { purpose: 'enroll' },
+        email: 'other@example.test',
+      })
+    ).toThrow()
+    expect(() =>
+      invoke(endpoints.passkeyList, { expectedSessionId: sid, accessToken: 'client-token' })
+    ).toThrow()
+  })
+  it.each([false, true])(
+    'clears cookies only when removal signs out the actor: %s',
+    async (signedOut) => {
+      provider.removeCredential.mockResolvedValue({ signedOut })
+      expect(
+        await invoke(endpoints.passkeyRemove, { expectedSessionId: sid, grantId: bearer })
+      ).toEqual({ signedOut })
+      expect(mocks.clearCookies).toHaveBeenCalledTimes(signedOut ? 1 : 0)
+      expect(mocks.clearPreview).toHaveBeenCalledTimes(signedOut ? 1 : 0)
+    }
+  )
+  it('does not clear cookies or retry an ambiguous removal', async () => {
+    provider.removeCredential.mockRejectedValue(new Error('connection lost'))
+    await expect(
+      invoke(endpoints.passkeyRemove, { expectedSessionId: sid, grantId: bearer })
+    ).rejects.toThrow('connection lost')
+    expect(provider.removeCredential).toHaveBeenCalledOnce()
+    expect(mocks.clearCookies).not.toHaveBeenCalled()
+  })
+  it.each(['middleware', 'protection', 'capability', 'capacity'])(
+    'fails closed before provider work without %s',
+    async (failure) => {
+      if (failure === 'middleware') mocks.request = new Request('https://app.test')
+      if (failure === 'protection') delete mocks.config.passkeyRequests
+      if (failure === 'capability') mocks.config.sessionProvider.capabilities.passkeys = false
+      if (failure === 'capacity') mocks.acquire.mockResolvedValue(null)
+      const error = await invoke(endpoints.passkeySignInOptions).catch((error) => error)
+      expect(error.status).toBe(failure === 'capability' ? 404 : failure === 'capacity' ? 429 : 503)
+      expect(provider.signInOptions).not.toHaveBeenCalled()
+    }
+  )
+  it('never retries provider session-change errors', async () => {
+    provider.verifyProof.mockRejectedValue(ERR_SESSION_CHANGED({ message: 'authority changed' }))
+    await expect(
+      invoke(endpoints.passkeyProof, { expectedSessionId: sid, ceremonyId: bearer, response: {} })
+    ).rejects.toMatchObject({ code: 'ERR_SESSION_CHANGED' })
+    expect(provider.verifyProof).toHaveBeenCalledOnce()
+  })
+})

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

@@ -0,0 +1,252 @@
+/**
+ * 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 { createServerFn } from '@tanstack/react-start'
+import { getRequest, setResponseHeader } from '@tanstack/react-start/server'
+
+import {
+  ERR_SESSION_CHANGED,
+  ERR_UNAUTHENTICATED,
+  isAdminAuth,
+  type PasskeyOperation,
+  type PasskeyProvider,
+} from '@byline/auth'
+import {
+  clearPreviewCookie,
+  clearSessionCookies,
+  getAdminRequestContext,
+  readAccessTokenCookie,
+  readRefreshTokenCookie,
+  setSessionCookies,
+} from '@byline/client/server'
+import { getServerConfig } from '@byline/core'
+import { z } from 'zod'
+
+import { bylineCore } from '../../integrations/byline-core.js'
+import {
+  adminSessionMiddleware,
+  adminSessionMutationMiddleware,
+} from '../../integrations/session-middleware.js'
+import { wasPasskeyBodyChecked } from '../../integrations/sign-in-body.js'
+import { withPasskeyAdmission } from './passkey-admission.js'
+import { reconcileLocaleAfterSignIn } from './reconcile-locale.js'
+
+const session = z.object({ expectedSessionId: z.uuid() })
+const bearer = z.string().regex(/^[A-Za-z0-9_-]{43}$/)
+const action = z.discriminatedUnion('purpose', [
+  z.object({ purpose: z.literal('enroll') }).strict(),
+  z
+    .object({ purpose: z.literal('remove'), targetUserId: z.uuid(), credentialRecordId: z.uuid() })
+    .strict(),
+])
+const name = z.string().trim().min(1).max(80)
+function validate<T>(schema: z.ZodType<T>) {
+  return (input: unknown): T => {
+    const parsed = schema.safeParse(input)
+    if (!parsed.success)
+      throw new Response('Invalid passkey input', {
+        status: 400,
+        headers: { 'Cache-Control': 'no-store' },
+      })
+    return parsed.data
+  }
+}
+
+function configuredProvider(): PasskeyProvider {
+  setResponseHeader('Cache-Control', 'no-store')
+  const config = getServerConfig()
+  const provider = config.sessionProvider
+  if (!config.passkeys || provider?.capabilities?.passkeys !== true || !provider.passkeys)
+    throw new Response('Passkeys are not enabled', {
+      status: 404,
+      headers: { 'Cache-Control': 'no-store' },
+    })
+  return provider.passkeys
+}
+
+async function currentSession(expectedSessionId: string) {
+  const auth = await getAdminRequestContext()
+  if (auth.sessionId !== expectedSessionId)
+    throw ERR_SESSION_CHANGED({ message: 'session changed before passkey operation' })
+  const accessToken = readAccessTokenCookie()
+  if (!accessToken) throw ERR_UNAUTHENTICATED({ message: 'access credential missing' })
+  return { accessToken, expectedSessionId }
+}
+
+function admitted<T>(
+  purpose: PasskeyOperation,
+  work: (provider: PasskeyProvider, metadata: { ip: string; userAgent?: string }) => Promise<T>,
+  expectedSessionId?: string
+) {
+  const provider = configuredProvider()
+  const config = getServerConfig()
+  const request = getRequest()
+  return withPasskeyAdmission({
+    provider,
+    purpose,
+    request,
+    bodyChecked: wasPasskeyBodyChecked(request, purpose === 'password-proof'),
+    protection: config.passkeyRequests,
+    ...(purpose === 'password-proof'
+      ? {
+          password: {
+            protection: config.passwordSignIn,
+            resolveActorEmail: async () => {
+              const auth = await getAdminRequestContext()
+              if (!auth.actor || !expectedSessionId || auth.sessionId !== expectedSessionId)
+                throw ERR_SESSION_CHANGED({ message: 'session changed before password proof' })
+              const user = await bylineCore().adminStore?.adminUsers.getById(auth.actor.id)
+              if (!user) throw ERR_UNAUTHENTICATED({ message: 'account unavailable' })
+              return user.email
+            },
+          },
+        }
+      : {}),
+    work: ({ ip }) =>
+      work(provider, { ip, userAgent: request.headers.get('user-agent')?.slice(0, 512) }),
+  })
+}
+
+/** Cosmetic capability discovery creates no ceremony and reads no account data. */
+export const getPasskeyCapability = createServerFn({ method: 'GET' }).handler(async () => {
+  setResponseHeader('Cache-Control', 'no-store')
+  const config = getServerConfig()
+  return {
+    enabled: !!(
+      config.passkeys &&
+      config.sessionProvider?.capabilities?.passkeys &&
+      config.sessionProvider.passkeys
+    ),
+  }
+})
+
+export const passkeySignInOptions = createServerFn({ method: 'POST' })
+  .validator(validate(z.object({}).strict()))
+  .handler(async () =>
+    admitted('sign-in-options', (provider, metadata) => provider.signInOptions(metadata))
+  )
+
+export const passkeySignIn = createServerFn({ method: 'POST' })
+  .validator(validate(z.object({ ceremonyId: bearer, response: z.unknown() }).strict()))
+  .handler(async ({ data }) =>
+    admitted('sign-in', async (provider, metadata) => {
+      const result = await provider.verifySignIn({
+        ...data,
+        ...metadata,
+        previousAccessToken: readAccessTokenCookie(),
+        previousRefreshToken: readRefreshTokenCookie(),
+      })
+      setSessionCookies(result)
+      try {
+        await reconcileLocaleAfterSignIn(result.actor.id)
+      } catch {
+        /* Locale is best effort. */
+      }
+      return { userId: result.actor.id, sessionId: result.sessionId }
+    })
+  )
+
+export const passkeyPasswordProof = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator(validate(session.extend({ password: z.string().min(1).max(128), action }).strict()))
+  .handler(async ({ data }) =>
+    admitted(
+      'password-proof',
+      async (provider) =>
+        provider.passwordProof({ ...data, ...(await currentSession(data.expectedSessionId)) }),
+      data.expectedSessionId
+    )
+  )
+
+export const passkeyProofOptions = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator(validate(session.extend({ action }).strict()))
+  .handler(async ({ data }) =>
+    admitted('proof-options', async (provider) =>
+      provider.proofOptions({ ...data, ...(await currentSession(data.expectedSessionId)) })
+    )
+  )
+
+export const passkeyProof = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator(validate(session.extend({ ceremonyId: bearer, response: z.unknown() }).strict()))
+  .handler(async ({ data }) =>
+    admitted('proof', async (provider) =>
+      provider.verifyProof({ ...data, ...(await currentSession(data.expectedSessionId)) })
+    )
+  )
+
+export const passkeyEnrollmentOptions = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator(validate(session.extend({ grantId: bearer }).strict()))
+  .handler(async ({ data }) =>
+    admitted('enrollment-options', async (provider) =>
+      provider.enrollmentOptions({ ...data, ...(await currentSession(data.expectedSessionId)) })
+    )
+  )
+
+export const passkeyEnrollment = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator(validate(session.extend({ ceremonyId: bearer, response: z.unknown(), name }).strict()))
+  .handler(async ({ data }) =>
+    admitted('enrollment', async (provider) =>
+      provider.verifyEnrollment({ ...data, ...(await currentSession(data.expectedSessionId)) })
+    )
+  )
+
+export const passkeyList = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator(validate(session.extend({ targetUserId: z.uuid().optional() }).strict()))
+  .handler(async ({ data }) =>
+    admitted('list', async (provider) =>
+      provider.listCredentials({ ...data, ...(await currentSession(data.expectedSessionId)) })
+    )
+  )
+
+export const passkeyRename = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator(validate(session.extend({ credentialRecordId: z.uuid(), name }).strict()))
+  .handler(async ({ data }) =>
+    admitted('rename', async (provider) =>
+      provider.renameCredential({ ...data, ...(await currentSession(data.expectedSessionId)) })
+    )
+  )
+
+export const passkeyRemove = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMutationMiddleware])
+  .validator(validate(session.extend({ grantId: bearer }).strict()))
+  .handler(async ({ data }) =>
+    admitted('remove', async (provider) => {
+      const result = await provider.removeCredential({
+        ...data,
+        ...(await currentSession(data.expectedSessionId)),
+      })
+      if (result.signedOut) {
+        clearSessionCookies()
+        clearPreviewCookie()
+      }
+      return result
+    })
+  )
+
+/** Cosmetic permissions for the manager; every mutation still rechecks authority. */
+export const passkeyManagementContext = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator(validate(session.strict()))
+  .handler(async ({ data }) =>
+    admitted('list', async () => {
+      await currentSession(data.expectedSessionId)
+      const { actor } = await getAdminRequestContext()
+      if (!isAdminAuth(actor)) throw ERR_UNAUTHENTICATED({ message: 'admin login required' })
+      return {
+        id: actor.id,
+        isSuperAdmin: actor.isSuperAdmin,
+        canManagePasskeys: actor.hasAbility('admin.users.managePasskeys'),
+      }
+    })
+  )

package/src/server-fns/auth/reconcile-locale.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 { readAdminLocaleCookie } from '../../i18n/locale-cookie.js'
+import { bylineCore } from '../../integrations/byline-core.js'
+
+/**
+ * Apply the `byline_admin_lng` cookie to `admin_users.preferred_locale`
+ * when the two diverge after sign-in. No-op when:
+ *
+ *   - The cookie is unset (the cascade falls through to the existing
+ *     column / Accept-Language / default anyway).
+ *   - The cookie carries a locale outside `i18n.admin.locales`
+ *     (stale value pointing at a removed locale — let the resolver
+ *     fall through cleanly).
+ *   - No admin store is configured (headless tooling paths).
+ *   - The stored value already matches the cookie.
+ */
+export async function reconcileLocaleAfterSignIn(adminUserId: string): Promise<void> {
+  const cookieLocale = readAdminLocaleCookie()
+  if (cookieLocale == null) return
+
+  const core = bylineCore()
+  const locales = core.config.i18n.admin.locales
+  if (!locales.includes(cookieLocale)) return
+
+  const adminStore = core.adminStore
+  if (adminStore == null) return
+
+  const row = await adminStore.adminUsers.getById(adminUserId)
+  if (!row) return
+  if (row.preferred_locale === cookieLocale) return
+
+  await adminStore.adminUsers.setPreferredLocale(adminUserId, cookieLocale)
+}

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

@@ -29,10 +29,9 @@ import {
 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'
+import { reconcileLocaleAfterSignIn } from './reconcile-locale.js'
 
 export interface SignInInput {
   email: string
@@ -137,33 +136,3 @@ export const adminSignIn = createServerFn({ method: 'POST' })
 
     return { userId: result.actor.id, sessionId: result.sessionId }
   })
-
-/**
- * Apply the `byline_admin_lng` cookie to `admin_users.preferred_locale`
- * when the two diverge after sign-in. No-op when:
- *
- *   - The cookie is unset (the cascade falls through to the existing
- *     column / Accept-Language / default anyway).
- *   - The cookie carries a locale outside `i18n.admin.locales`
- *     (stale value pointing at a removed locale — let the resolver
- *     fall through cleanly).
- *   - No admin store is configured (headless tooling paths).
- *   - The stored value already matches the cookie.
- */
-async function reconcileLocaleAfterSignIn(adminUserId: string): Promise<void> {
-  const cookieLocale = readAdminLocaleCookie()
-  if (cookieLocale == null) return
-
-  const core = bylineCore()
-  const locales = core.config.i18n.admin.locales
-  if (!locales.includes(cookieLocale)) return
-
-  const adminStore = core.adminStore
-  if (adminStore == null) return
-
-  const row = await adminStore.adminUsers.getById(adminUserId)
-  if (!row) return
-  if (row.preferred_locale === cookieLocale) return
-
-  await adminStore.adminUsers.setPreferredLocale(adminUserId, cookieLocale)
-}