@byline/admin 6.7.2 → 6.8.0

package/src/modules/auth/components/sign-in-form.test.tsx

@@ -0,0 +1,92 @@
+import { act, type ReactNode } from 'react'
+
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  enabled: true,
+  signIn: vi.fn(),
+  passkey: vi.fn(),
+  services: {} as any,
+}))
+vi.mock('../../../services/admin-services-context.js', () => ({
+  useBylineAdminServices: () => mocks.services,
+}))
+vi.mock('@byline/i18n/react', () => ({ useTranslation: () => ({ t: (key: string) => key }) }))
+vi.mock('@byline/core', () => ({ getAdminConfig: () => ({ routes: { admin: '/admin' } }) }))
+vi.mock('./passkey-browser.js', () => ({
+  signInWithPasskey: mocks.passkey,
+  passkeyErrorKey: () => 'passkeys.errors.cancelled',
+}))
+vi.mock('@byline/ui/react', () => {
+  const Box = ({ children }: { children: ReactNode }) => <div>{children}</div>
+  return {
+    Card: Object.assign(Box, {
+      Header: Box,
+      Title: Box,
+      Description: Box,
+      Content: Box,
+      Footer: Box,
+    }),
+    Alert: ({ children }: { children: ReactNode }) => <div role="alert">{children}</div>,
+    Button: ({ children, disabled, onClick, type }: any) => (
+      <button type={type} disabled={disabled} onClick={onClick}>
+        {children}
+      </button>
+    ),
+    Input: ({ label, ...rest }: any) => <input aria-label={label} {...rest} />,
+    InputPassword: ({
+      label,
+      showPasswordLabel: _show,
+      hidePasswordLabel: _hide,
+      ...rest
+    }: any) => <input type="password" aria-label={label} {...rest} />,
+    LoaderEllipsis: () => null,
+    PasskeyIcon: () => null,
+  }
+})
+
+import { SignInForm } from './sign-in-form.js'
+
+let root: Root
+let container: HTMLDivElement
+beforeEach(() => {
+  vi.resetAllMocks()
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  mocks.services = {
+    adminSignIn: mocks.signIn,
+    passkeys: { capability: async () => ({ enabled: mocks.enabled }) },
+  }
+  mocks.enabled = true
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+afterEach(async () => {
+  await act(async () => root.unmount())
+  container.remove()
+  vi.unstubAllGlobals()
+})
+it('retains password sign-in when passkeys are disabled or the host has no passkey services', async () => {
+  mocks.enabled = false
+  await act(async () => root.render(<SignInForm />))
+  expect(container.querySelector('input[type="password"]')).not.toBeNull()
+  expect(container.textContent).not.toContain('passkeys.signIn')
+  delete mocks.services.passkeys
+  await act(async () => root.render(<SignInForm />))
+  expect(container.querySelector('form')).not.toBeNull()
+})
+it('keeps password choice visible and restores controls after passkey cancellation', async () => {
+  mocks.passkey.mockRejectedValue(new Error('cancelled'))
+  await act(async () => root.render(<SignInForm />))
+  const button = [...container.querySelectorAll('button')].find(
+    (button) => button.textContent === 'passkeys.signIn'
+  )!
+  expect(button).toBeTruthy()
+  expect(container.querySelector('input[type="password"]')).not.toBeNull()
+  await act(async () => button.click())
+  expect(container.querySelector('[role="alert"]')?.textContent).toBe('passkeys.errors.cancelled')
+  expect(button.disabled).toBe(false)
+  expect(mocks.passkey).toHaveBeenCalledOnce()
+  expect(mocks.signIn).not.toHaveBeenCalled()
+})

package/src/modules/auth/components/sign-in-form.tsx

@@ -20,18 +20,28 @@
  * Stable override handles: `.byline-sign-in-card`, `.byline-sign-in-alert`,
  * `.byline-sign-in-form`, `.byline-sign-in-fields`,
  * `.byline-sign-in-actions`, `.byline-sign-in-button`,
- * `.byline-sign-in-home-link`.
+ * `.byline-sign-in-home-link`, `.byline-sign-in-alternate`,
+ * `.byline-sign-in-divider`, `.byline-passkey-sign-in-button`.
  */
 
-import { type FormEvent, useState } from 'react'
+import { type FormEvent, useEffect, useRef, useState } from 'react'
 
 import { getAdminConfig } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
-import { Alert, Button, Card, Input, InputPassword, LoaderEllipsis } from '@byline/ui/react'
+import {
+  Alert,
+  Button,
+  Card,
+  Input,
+  InputPassword,
+  LoaderEllipsis,
+  PasskeyIcon,
+} from '@byline/ui/react'
 import cx from 'clsx'
 
 import { useBylineAdminServices } from '../../../services/admin-services-context.js'
 import { normalizeRootRelativeRedirect, resolveSignInFormRedirect } from '../safe-redirect.js'
+import { passkeyErrorKey, signInWithPasskey } from './passkey-browser.js'
 import styles from './sign-in-form.module.css'
 
 export interface SignInFormProps {
@@ -46,13 +56,47 @@ export interface SignInFormProps {
 }
 
 export function SignInForm({ redirectTo, homeUrl }: SignInFormProps) {
-  const { adminSignIn } = useBylineAdminServices()
+  const { adminSignIn, passkeys } = useBylineAdminServices()
   const { t } = useTranslation('byline-admin')
   const [email, setEmail] = useState('')
   const [password, setPassword] = useState('')
   const [pending, setPending] = useState(false)
   const [error, setError] = useState<string | null>(null)
 
+  const mounted = useRef(false)
+  const [passkeysEnabled, setPasskeysEnabled] = useState(false)
+  useEffect(() => {
+    let active = true
+    mounted.current = true
+    void passkeys
+      ?.capability()
+      .then(({ enabled }) => {
+        if (active) setPasskeysEnabled(enabled)
+      })
+      .catch(() => {})
+    return () => {
+      active = false
+      mounted.current = false
+    }
+  }, [passkeys])
+
+  async function handlePasskey() {
+    if (!passkeys || pending) return
+    setPending(true)
+    setError(null)
+    try {
+      await signInWithPasskey(passkeys, () => mounted.current)
+    } catch (error) {
+      if (mounted.current) {
+        setError(t(passkeyErrorKey(error)))
+        setPending(false)
+      }
+      return
+    }
+    const destination = resolveSignInFormRedirect(redirectTo, getAdminConfig().routes.admin)
+    window.location.assign(normalizeRootRelativeRedirect(destination) ?? '/')
+  }
+
   async function handleSubmit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault()
     if (pending) return
@@ -144,6 +188,23 @@ export function SignInForm({ redirectTo, homeUrl }: SignInFormProps) {
           </div>
         </form>
       </Card.Content>
+      {passkeysEnabled && (
+        <Card.Footer className={cx('byline-sign-in-alternate', styles.alternate)}>
+          <div className={cx('byline-sign-in-divider', styles.divider)}>
+            <span>{t('auth.signIn.alternate')}</span>
+          </div>
+          <Button
+            type="button"
+            variant="outlined"
+            disabled={pending}
+            onClick={handlePasskey}
+            className={cx('byline-passkey-sign-in-button', styles['passkey-button'])}
+          >
+            <PasskeyIcon width="20px" height="20px" />
+            <span>{t('passkeys.signIn')}</span>
+          </Button>
+        </Card.Footer>
+      )}
     </Card>
   )
 }

package/src/modules/auth/index.ts

@@ -21,11 +21,19 @@
  * against `@byline/auth` rather than added here.
  */
 
+export { createAuthMaintenanceTasks } from './auth-maintenance.js'
 export {
   JwtSessionProvider,
   type JwtSessionProviderConfig,
   type NativeSessionEvent,
 } from './jwt-session-provider.js'
+export { createPasskeyRequestLimiter } from './passkey-rate-limiter.js'
+export {
+  assertPasskeyAttempt,
+  assertPasskeyBytes,
+  assertPasskeyClaim,
+  assertPasskeyTokenHash,
+} from './passkey-storage-validation.js'
 export { hashPassword, verifyPassword } from './password.js'
 export { resolveActor } from './resolve-actor.js'
 export {
@@ -35,7 +43,14 @@ export {
   type SignInRateLimitStore,
   type SignInSecurityEvent,
 } from './sign-in-rate-limiter.js'
+export type { AuthMaintenanceRepository } from './auth-maintenance-repository.js'
 export type { LoginSessionRow, LoginSessionsRepository } from './login-sessions-repository.js'
+export type {
+  PasskeyAttemptRow,
+  PasskeyClaimInput,
+  PasskeyCredentialRow,
+  PasskeysRepository,
+} from './passkeys-repository.js'
 export type {
   IssueRefreshTokenInput,
   RefreshTokenRow,

package/src/modules/auth/jwt-session-provider.ts

@@ -17,6 +17,8 @@ import {
   ERR_INVALID_TOKEN,
   ERR_REVOKED_TOKEN,
   ERR_SESSION_CHANGED,
+  type PasskeyProvider,
+  type PasskeySession,
   type RefreshSessionArgs,
   type RevokeSessionArgs,
   type SessionProvider,
@@ -25,13 +27,16 @@ import {
   type SignInResult,
   type SignInWithPasswordArgs,
 } from '@byline/auth'
+import type { PasskeyConfig } from '@byline/core'
 import { passwordSignInSchema } from '@byline/core/validation'
 import { compactVerify, jwtVerify, SignJWT } from 'jose'
 import { v7 as uuidv7 } from 'uuid'
 
+import { NativePasskeyProvider } from './native-passkey-provider.js'
 import { verifyPassword } from './password.js'
 import { resolveActor, resolveActorFromUser } from './resolve-actor.js'
 import type { AdminStore } from '../../store.js'
+import type { AdminUserWithPasswordRow } from '../admin-users/repository.js'
 
 const DEFAULT_ISSUER = 'byline'
 const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 15 * 60 // 15 minutes
@@ -43,12 +48,39 @@ const CAPABILITIES: SessionProviderCapabilities = {
   sso: false,
 }
 
-export interface NativeSessionEvent {
-  type: 'refresh_attempted' | 'refresh_completed' | 'refresh_contested'
-}
+export type NativeSessionEvent =
+  | { type: 'refresh_attempted' | 'refresh_completed' | 'refresh_contested' }
+  | {
+      type:
+        | 'passkey_attempted'
+        | 'passkey_completed'
+        | 'passkey_failed'
+        | 'passkey_admission_denied'
+      purpose:
+        | 'sign-in-options'
+        | 'sign-in'
+        | 'password-proof'
+        | 'proof-options'
+        | 'proof'
+        | 'enrollment-options'
+        | 'enrollment'
+        | 'list'
+        | 'rename'
+        | 'remove'
+      reason?:
+        | 'invalid-proof'
+        | 'stale-authority'
+        | 'forbidden'
+        | 'limit'
+        | 'unavailable'
+        | 'capacity'
+        | 'network'
+    }
 
 export interface JwtSessionProviderConfig {
-  /** Best-effort, token-free renewal telemetry. Errors never change authentication outcomes. */
+  /** Optional explicit WebAuthn trust configuration; disabled when absent. */
+  passkeys?: PasskeyConfig
+  /** Best-effort, token-free authentication telemetry. Errors never change authentication outcomes. */
   onEvent?: (event: NativeSessionEvent) => void
   /**
    * Adapter-backed admin repositories. Construct via the DB adapter's
@@ -76,7 +108,8 @@ export interface JwtSessionProviderConfig {
 }
 
 export class JwtSessionProvider implements SessionProvider {
-  public readonly capabilities = CAPABILITIES
+  public readonly capabilities: SessionProviderCapabilities
+  public readonly passkeys?: PasskeyProvider
 
   readonly #onEvent?: (event: NativeSessionEvent) => void
   readonly #store: AdminStore
@@ -102,6 +135,16 @@ export class JwtSessionProvider implements SessionProvider {
     this.#accessTtl = config.accessTokenTtlSeconds ?? DEFAULT_ACCESS_TOKEN_TTL_SECONDS
     this.#refreshTtl = config.refreshTokenTtlSeconds ?? DEFAULT_REFRESH_TOKEN_TTL_SECONDS
     this.#now = config.now ?? (() => new Date())
+    this.capabilities = config.passkeys ? { ...CAPABILITIES, passkeys: true } : CAPABILITIES
+    if (config.passkeys) {
+      this.passkeys = new NativePasskeyProvider(config.passkeys, {
+        store: this.#store,
+        now: this.#now,
+        authenticate: (session, store) => this.#authenticatePasskeySession(session, store),
+        signIn: (snapshot, args, recheck) => this.#completeSignIn(snapshot, args, recheck),
+        emit: (event) => this.#emitEvent(event),
+      })
+    }
   }
 
   // -----------------------------------------------------------------------
@@ -131,45 +174,19 @@ export class JwtSessionProvider implements SessionProvider {
       throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
     }
 
-    const previous = await this.#observedLogins(args)
-    const withLocks = <T>(work: (store: AdminStore) => Promise<T>) =>
-      previous.length
-        ? this.#store.withSessionLocks(
-            [row.id, ...previous.map((login) => login.admin_user_id)],
-            work
-          )
-        : this.#store.withSessionLock(row.id, (store) => work(store))
-    return withLocks(async (store) => {
-      const current = await store.adminUsers.getByIdForSignIn(row.id)
-      if (!current?.is_enabled) throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
-      // Password verification is deliberately outside the lock. Revalidate
-      // both the credential and generation before issuing under that lock.
-      if (
-        current.password_hash !== row.password_hash ||
-        current.session_version !== row.session_version
-      ) {
+    return this.#completeSignIn(row, args, async (_store, current) => {
+      if (current.password_hash !== row.password_hash) {
         throw ERR_INVALID_CREDENTIALS({ message: 'credentials changed during sign-in' })
       }
-      for (const observed of previous) {
-        const login = await store.loginSessions.findById(observed.id)
-        if (login && login.admin_user_id === observed.admin_user_id) {
-          await store.loginSessions.revoke(login.id, this.#now())
-        }
-      }
-      await store.adminUsers.recordLoginSuccess(row.id, args.ip ?? null)
-      const actor = await resolveActorFromUser(store, current)
-      if (!actor) throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
-      const tokens = await this.#issueTokens(store, {
-        adminUserId: row.id,
-        sessionVersion: current.session_version,
-        ip: args.ip ?? null,
-        userAgent: args.userAgent ?? null,
-      })
-      return { ...tokens, actor }
     })
   }
 
   async verifyAccessToken(token: string): Promise<{ actor: AdminAuth; sessionId: string }> {
+    const { actor, sessionId } = await this.#verifyAccessTokenAtStore(token, this.#store)
+    return { actor, sessionId }
+  }
+
+  async #verifyAccessTokenAtStore(token: string, store: AdminStore) {
     let payload: AccessTokenPayload
     try {
       const result = await jwtVerify<AccessTokenPayload>(token, this.#signingKey, {
@@ -196,14 +213,14 @@ export class JwtSessionProvider implements SessionProvider {
       throw ERR_INVALID_TOKEN({ message: 'unexpected token type' })
     }
 
-    const current = await this.#store.adminUsers.getByIdForSignIn(payload.sub)
+    const current = await store.adminUsers.getByIdForSignIn(payload.sub)
     if (!current?.is_enabled) {
       throw ERR_ACCOUNT_DISABLED({ message: 'account disabled or deleted' })
     }
     if (current.session_version !== payload.sv) {
       throw ERR_REVOKED_TOKEN({ message: 'account session generation changed' })
     }
-    const login = await this.#store.loginSessions.findById(payload.sid)
+    const login = await store.loginSessions.findById(payload.sid)
     if (
       !login ||
       login.admin_user_id !== payload.sub ||
@@ -213,9 +230,9 @@ export class JwtSessionProvider implements SessionProvider {
     ) {
       throw ERR_REVOKED_TOKEN({ message: 'login revoked or expired' })
     }
-    const actor = await resolveActorFromUser(this.#store, current)
+    const actor = await resolveActorFromUser(store, current)
     if (!actor) throw ERR_ACCOUNT_DISABLED({ message: 'account disabled or deleted' })
-    return { actor, sessionId: payload.sid }
+    return { actor, sessionId: payload.sid, user: current }
   }
 
   async refreshSession(args: RefreshSessionArgs): Promise<SessionTokens> {
@@ -339,14 +356,69 @@ export class JwtSessionProvider implements SessionProvider {
   // Internals
   // -----------------------------------------------------------------------
 
-  #emit(type: NativeSessionEvent['type']) {
+  #emit(type: 'refresh_attempted' | 'refresh_completed' | 'refresh_contested') {
+    this.#emitEvent({ type })
+  }
+
+  #emitEvent(event: NativeSessionEvent): void {
     try {
-      this.#onEvent?.({ type })
+      void Promise.resolve(this.#onEvent?.(event)).catch(() => {})
     } catch {
       /* Telemetry is not an authentication dependency. */
     }
   }
 
+  async #authenticatePasskeySession(session: PasskeySession, store = this.#store) {
+    const result = await this.#verifyAccessTokenAtStore(session.accessToken, store)
+    if (result.sessionId !== session.expectedSessionId)
+      throw ERR_SESSION_CHANGED({ message: 'session changed' })
+    return result
+  }
+
+  async #completeSignIn(
+    snapshot: AdminUserWithPasswordRow,
+    args: Pick<
+      SignInWithPasswordArgs,
+      'previousAccessToken' | 'previousRefreshToken' | 'ip' | 'userAgent'
+    >,
+    recheck: (store: AdminStore, current: AdminUserWithPasswordRow) => Promise<void>
+  ): Promise<SignInResult> {
+    const previous = await this.#observedLogins(args)
+    const withLocks = <T>(work: (store: AdminStore) => Promise<T>) =>
+      previous.length
+        ? this.#store.withSessionLocks(
+            [snapshot.id, ...previous.map((login) => login.admin_user_id)],
+            work
+          )
+        : this.#store.withSessionLock(snapshot.id, (store) => work(store))
+    return withLocks(async (store) => {
+      const current = await store.adminUsers.getByIdForSignIn(snapshot.id)
+      if (!current?.is_enabled) throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
+      // Proof verification is outside the lock. Revalidate the account generation
+      // and the method-specific credential snapshot before issuing under this lock.
+      if (current.session_version !== snapshot.session_version) {
+        throw ERR_INVALID_CREDENTIALS({ message: 'credentials changed during sign-in' })
+      }
+      await recheck(store, current)
+      for (const observed of previous) {
+        const login = await store.loginSessions.findById(observed.id)
+        if (login && login.admin_user_id === observed.admin_user_id) {
+          await store.loginSessions.revoke(login.id, this.#now())
+        }
+      }
+      await store.adminUsers.recordLoginSuccess(snapshot.id, args.ip ?? null)
+      const actor = await resolveActorFromUser(store, current)
+      if (!actor) throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
+      const tokens = await this.#issueTokens(store, {
+        adminUserId: snapshot.id,
+        sessionVersion: current.session_version,
+        ip: args.ip ?? null,
+        userAgent: args.userAgent ?? null,
+      })
+      return { ...tokens, actor }
+    })
+  }
+
   async #observedLogins(
     args: Pick<SignInWithPasswordArgs, 'previousAccessToken' | 'previousRefreshToken'>
   ) {