@scalemule/ledvery-react

React hooks for Ledvery OIDC authentication using the BFF (Backend-for-Frontend) pattern.

All authentication tokens stay in httpOnly cookies managed by the server. This package never reads or stores tokens in browser JavaScript.

Installation

npm install @scalemule/ledvery-react

Prerequisites

Your Next.js (or similar) server must expose the BFF routes via @scalemule/nextjs createLedveryRoutes():

| Route | Method | Response | |-------|--------|----------| | {bffBasePath}/login?returnTo=... | GET | 302 → Ledvery authorize | | {bffBasePath}/callback?code=...&state=... | GET | 302 → returnTo / postLoginRedirect | | {bffBasePath}/session | GET | 200 { session: { sub, email, ... } \| null } | | {bffBasePath}/logout | GET | 302 → postLogoutRedirect (server-configured) |

Usage

import { LedveryProvider, useLedverySession, useLedveryLogin, useLedveryLogout } from '@scalemule/ledvery-react'

function App() {
  return (
    <LedveryProvider config={{ bffBasePath: '/api/auth/ledvery' }}>
      <Profile />
    </LedveryProvider>
  )
}

function Profile() {
  const { session, isAuthenticated, isLoading } = useLedverySession()
  const { login } = useLedveryLogin()
  const { logout } = useLedveryLogout()

  if (isLoading) return <div>Loading...</div>
  if (!isAuthenticated) return <button onClick={() => login()}>Sign in with Ledvery</button>

  return (
    <div>
      <p>Welcome, {session?.name ?? session?.email}</p>
      <button onClick={logout}>Sign out</button>
    </div>
  )
}

API

<LedveryProvider>

Wraps your app. Fetches the session on mount via GET {bffBasePath}/session.

| Prop | Type | Default | |------|------|---------| | config.bffBasePath | string | '/api/auth/ledvery' | | config.postLoginRedirect | string | '/' |

Hooks

| Hook | Returns | |------|---------| | useLedverySession() | { session, isAuthenticated, isLoading, error } | | useLedveryLogin() | { login: (returnTo?) => void } | | useLedveryLogout() | { logout: () => void } | | useRefreshToken() | { refresh: () => Promise<void> } — re-reads /session | | useOidcFlow() | { flowState, error } |

Flow States

idle → loading_session → authenticated | error

Calling login() transitions to redirecting_to_idp (full-page navigation).

License

MIT