@dloizides/auth-web 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+## 1.2.0 (2026-05-22)
+
+Additive release for Phase 3d of the unified-auth plan — the event-scoped PIN
+UI. Adds the native, branded event-PIN login surface so an app (Kefi) can offer
+"sign in with your event PIN" for operational staff (door / DJ / media) without
+the user ever bouncing to Keycloak's hosted UI. No breaking changes; every
+1.1.0 export is unchanged.
+
+### Added
+
+- **`<PinForm>`** — the ready-made, themeable single-step event-PIN login form,
+  built on `usePinLogin`. A PIN field + a "sign in" button; the
+  `eventExternalId` is a prop (the event context comes from the route/page, it
+  is never typed by the user). Styled by the same `AuthTheme` token bag as the
+  other forms; copy is supplied through the i18n-agnostic `PinFormLabels` bag
+  (English `DEFAULT_PIN_LABELS` fallback). `onSuccess` hands back the signed-in
+  `BffUser`.
+- **`usePinLogin`** — the headless PIN hook (the custom-layout escape hatch). A
+  single-step flow: `submit(pin)` → `POST /bff/pin/login` → `BffUser`, with
+  `reset()`. Mirrors `useOtpLogin` (mounted-guard, memoised result,
+  latest-`eventExternalId` ref).
+- **`PinFormLabels`** + **`DEFAULT_PIN_LABELS`** — the PIN label bag.
+- New `AuthTestIds` entries for every PIN interactive element.
+- Re-exports `BffPinLoginRequest` from `@dloizides/auth-client`.
+
+### Changed
+
+- Peer dependency `@dloizides/auth-client` raised to `>=3.2.0` — the version
+  that adds `BffAuthClient.pinLogin`.
+
+## 1.1.0 (2026-05-22)
+
+Additive release for Phase 2d of the unified-auth plan — the email-OTP UI. Adds
+the native, branded email-OTP login surface so an app can offer "sign in with a
+code" without the user ever bouncing to Keycloak's hosted UI. No breaking
+changes; every 1.0.0 export is unchanged.
+
+### Added
+
+- **`<OtpForm>`** — the ready-made, themeable two-step email-OTP login form,
+  built on `useOtpLogin`. Step 1 collects the email and sends a code; step 2
+  collects the code, verifies it, and offers "resend code" and "use a different
+  email". Styled by the same `AuthTheme` token bag as the other forms; copy is
+  supplied through the i18n-agnostic `OtpFormLabels` bag (English
+  `DEFAULT_OTP_LABELS` fallback). `onSuccess` hands back the signed-in `BffUser`.
+- **`useOtpLogin`** — the headless OTP hook (the custom-layout escape hatch). A
+  small forward state machine over `OtpLoginStep`: `requestCode(identifier)` →
+  `EnterCode`, then `verifyCode(otp)` → `BffUser`, with `resend()` and
+  `reset()`. Mirrors `useBffAuth` (mounted-guard, memoised result).
+- **`OtpLoginStep`** — the `RequestCode` / `EnterCode` step enum.
+- **`OtpFormLabels`** + **`DEFAULT_OTP_LABELS`** — the OTP label bag.
+- New `AuthTestIds` entries for every OTP interactive element.
+- Re-exports `BffOtpRequestRequest`, `BffOtpVerifyRequest` and
+  `BffOtpRequestResult` from `@dloizides/auth-client`.
+
+### Changed
+
+- Peer dependency `@dloizides/auth-client` raised to `>=3.1.0` — the version
+  that ships `BffAuthClient.requestOtp` / `.verifyOtp` (`POST /bff/otp/request`
+  and `POST /bff/otp/verify`).
+
+### Notes
+
+- Still strictly thin: UI + the same-origin `/bff/*` client. The OTP client
+  methods carry the `X-BFF-Csrf` header like every other state-changing call;
+  no token handling, no secrets in the browser.
+- This release adds the OTP surface to the package only. Wiring an app onto it
+  (the Kefi pilot) is Phase 3.
+
+## 1.0.0 (2026-05-22)
+
+Initial release — the frontend half of the unified-auth plan (Phase 1b).
+
+`@dloizides/auth-web` is the shared, themeable, branded auth UI for the
+dloizides.com portfolio. It is extracted and generalised from the per-app auth
+code that lived inside `apps/katalogos-web` so katalogos, erevna and kefi can
+share one implementation instead of copy-pasting auth adapters.
+
+### Added
+
+- **Themeable components**
+  - `<LoginForm>` — password login, built on `useBffAuth`.
+  - `<ForgotPasswordForm>` — request-a-reset-link, built on
+    `useBffForgotPassword`; no-enumeration confirmation state.
+  - `<ResetPasswordForm>` — choose-a-new-password, built on
+    `useResetPasswordForm`.
+  - All three are styled by an `AuthTheme` design-token bag so visually
+    distinct apps share one implementation.
+- **Theming** — `AuthThemeProvider`, `useAuthTheme`, `defaultAuthTheme`, and
+  the `AuthTheme` token contract (colors / radii / spacing / typography).
+  Precedence: explicit `theme` prop → `<AuthThemeProvider>` context → default.
+- **i18n-agnostic label bags** — `LoginFormLabels`, `ForgotPasswordFormLabels`,
+  `ResetPasswordFormLabels` plus English `DEFAULT_*` constants. The package
+  ships no `t()` / `FM()`; consuming apps pass already-localised strings.
+- **Headless hooks** (the custom-layout escape hatch)
+  - `useBffAuth` — login / logout / `/bff/me` session, lifecycle status.
+  - `useBffForgotPassword`, `useBffResetPassword` — React Query mutations.
+  - `useResetPasswordForm` — reset-password form-state + validation logic.
+- **`createBffAuthClient`** — one-line wiring of a same-origin `BffAuthClient`
+  with a lazily-resolved `fetch` (load-time side-effect-free).
+- **Role-based post-login router** — `resolvePostLoginRoute(user, table)` and
+  `collectUserRoles`. The consuming app supplies the role → route table.
+- **Password policy** — `validatePasswordPolicy`, `isPasswordValid`,
+  `PasswordPolicyError`; mirrors the TenantService backend rules.
+- **Test IDs** — `AuthTestIds` + `withTestIdPrefix` for E2E targeting.
+- Re-exports `BffAuthClient`, `createFetchHttpClient` and the BFF request /
+  response types from `@dloizides/auth-client` so consumers have a single
+  import surface.
+
+### Notes
+
+- Strictly thin: UI + a same-origin `/bff/*` fetch client + the router helper.
+  **No secrets, no token handling, no Keycloak calls** — the per-app BFF owns
+  all of that server-side.
+- Built on `@dloizides/auth-client` (peer dependency `>=3.0.0`), which ships
+  `BffAuthClient`.
+- This release creates the package only. Porting `apps/katalogos-web` onto it
+  is Phase 1c.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dloizides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# @dloizides/auth-web
+
+Themeable, branded auth UI for the dloizides.com portfolio — the frontend half
+of the unified-auth plan.
+
+Every app gets a **native, branded login experience**: the login / forgot /
+reset forms live inside the app's own frontend; the user is **never redirected
+to Keycloak's hosted login UI**. All credential exchange happens server-side in
+a per-app **BFF** (`bff-katalogos`, `bff-erevna`, ...). This package talks only
+to a same-origin `/bff/*` — **no secrets, no token handling, no Keycloak calls
+in the browser.**
+
+Built on [`@dloizides/auth-client`](https://www.npmjs.com/package/@dloizides/auth-client),
+which provides the lower-level `BffAuthClient`.
+
+## Install
+
+```bash
+npm install @dloizides/auth-web
+```
+
+Peer dependencies: `react`, `react-native` (optional), `@tanstack/react-query`,
+`@dloizides/auth-client` (`>=3.0.0`).
+
+## Two ways to consume it
+
+### 1. Ready-made themeable components
+
+```tsx
+import {
+  AuthThemeProvider,
+  LoginForm,
+  createBffAuthClient,
+  resolvePostLoginRoute,
+} from '@dloizides/auth-web';
+
+import { katalogosAuthTheme } from './theme';      // your AuthTheme token bag
+import { roleRoutes } from './roleRoutes';          // your RoleRouteTable
+import { authLabels } from './authLabels';          // your localised labels
+
+const client = createBffAuthClient();               // same-origin /bff/*
+
+function LoginScreen() {
+  const router = useRouter();
+  return (
+    <AuthThemeProvider theme={katalogosAuthTheme}>
+      <LoginForm
+        client={client}
+        labels={authLabels.login}
+        onForgotPassword={() => router.push('/forgot-password')}
+        onSuccess={(user) => {
+          const route = resolvePostLoginRoute(user, roleRoutes);
+          router.replace(route ?? '/no-access');
+        }}
+      />
+    </AuthThemeProvider>
+  );
+}
+```
+
+`<ForgotPasswordForm>` and `<ResetPasswordForm>` follow the same shape.
+
+### Email-OTP login — `<OtpForm>`
+
+A native, branded "sign in with a code" surface — the user is never bounced to
+Keycloak's hosted UI. It is a two-step form: step 1 collects the email and asks
+the BFF to email a one-time code; step 2 collects the code, verifies it, and
+offers "resend code" / "use a different email".
+
+```tsx
+import { OtpForm, createBffAuthClient, resolvePostLoginRoute } from '@dloizides/auth-web';
+
+const client = createBffAuthClient();
+
+function OtpLoginScreen() {
+  const router = useRouter();
+  return (
+    <OtpForm
+      client={client}
+      labels={authLabels.otp}
+      onSuccess={(user) => {
+        const route = resolvePostLoginRoute(user, roleRoutes);
+        router.replace(route ?? '/no-access');
+      }}
+    />
+  );
+}
+```
+
+`<OtpForm>` POSTs to the same-origin `/bff/otp/request` and `/bff/otp/verify`
+endpoints (added in `Bff.AspNetCore`). The BFF runs the OTP direct-grant against
+Keycloak server-side; the browser receives only the httpOnly session cookie.
+
+### Event-PIN login — `<PinForm>`
+
+A native, branded "sign in with your event PIN" surface for operational staff
+(door / DJ / media on Kefi). It is a single-step form: a PIN field + a "sign
+in" button. The `eventExternalId` is a prop — the event context comes from the
+route/page, never typed by the user. The `(event, pin)` pair alone identifies
+the staff member; no username/password ever leaves the browser.
+
+```tsx
+import { PinForm, createBffAuthClient, resolvePostLoginRoute } from '@dloizides/auth-web';
+
+const client = createBffAuthClient();
+
+function PinLoginScreen({ eventExternalId }: { eventExternalId: string }) {
+  const router = useRouter();
+  return (
+    <PinForm
+      client={client}
+      eventExternalId={eventExternalId}
+      labels={authLabels.pin}
+      onSuccess={(user) => {
+        const route = resolvePostLoginRoute(user, roleRoutes);
+        router.replace(route ?? '/no-access');
+      }}
+    />
+  );
+}
+```
+
+`<PinForm>` POSTs to the same-origin `/bff/pin/login` endpoint (added in
+`Bff.AspNetCore`). The BFF runs the event-scoped PIN direct-grant against
+Keycloak server-side; the browser receives only the httpOnly session cookie.
+
+### 2. Headless hooks (custom layout)
+
+```tsx
+import { useBffAuth, createBffAuthClient } from '@dloizides/auth-web';
+
+const client = createBffAuthClient();
+
+function CustomLogin() {
+  const { login, isSubmitting, error } = useBffAuth({ client, probeOnMount: false });
+  // ...render your own form, call login({ username, password })
+}
+```
+
+For a custom OTP layout, `useOtpLogin` exposes the two-step machine:
+
+```tsx
+import { useOtpLogin, OtpLoginStep, createBffAuthClient } from '@dloizides/auth-web';
+
+const client = createBffAuthClient();
+
+function CustomOtpLogin() {
+  const otp = useOtpLogin({ client });
+  // step 1: otp.requestCode(email)  → otp.step becomes OtpLoginStep.EnterCode
+  // step 2: otp.verifyCode(code)    → resolves to the signed-in BffUser
+  //         otp.resend() / otp.reset() for the step-2 affordances
+}
+```
+
+For a custom PIN layout, `usePinLogin` exposes the single-step flow:
+
+```tsx
+import { usePinLogin, createBffAuthClient } from '@dloizides/auth-web';
+
+const client = createBffAuthClient();
+
+function CustomPinLogin({ eventExternalId }: { eventExternalId: string }) {
+  const pin = usePinLogin({ client, eventExternalId });
+  // pin.submit(pinValue) → resolves to the signed-in BffUser
+  // pin.reset()          → clears the error
+}
+```
+
+## Theming
+
+The package owns no brand. Each app maps its own theme system onto the flat
+`AuthTheme` token bag (`colors`, `radii`, `spacing`, `typography`) and supplies
+it via `<AuthThemeProvider>` or a `theme` prop on an individual component.
+Precedence: **prop → context → `defaultAuthTheme`**.
+
+```ts
+import { defaultAuthTheme, type AuthTheme } from '@dloizides/auth-web';
+
+export const katalogosAuthTheme: AuthTheme = {
+  ...defaultAuthTheme,
+  colors: { ...defaultAuthTheme.colors, primary: '#c2410c' },
+};
+```
+
+Because all three forms share one `useAuthStyles` token-to-style mapping,
+re-theming `<LoginForm>` automatically re-themes the others.
+
+## Internationalisation
+
+`@dloizides/auth-web` ships **no** i18n framework. Every user-facing string is
+supplied through a typed `labels` prop. Apps pass strings already localised
+with their own `FM()` / `t()`. Each label bag is partial — unspecified keys
+fall back to the English `DEFAULT_*` constants.
+
+## Role-based post-login routing
+
+```ts
+import { resolvePostLoginRoute, type RoleRouteTable } from '@dloizides/auth-web';
+
+const roleRoutes: RoleRouteTable = {
+  routes: [
+    { role: 'superUser', route: '/admin/super' },
+    { role: 'admin',     route: '/admin' },
+    { role: 'user',      route: '/dashboard' },
+  ],
+  fallback: '/no-access',
+};
+
+// The first table entry whose role the user holds wins — list most privileged first.
+const route = resolvePostLoginRoute(user, roleRoutes);
+```
+
+## API surface
+
+| Export | Kind |
+|--------|------|
+| `LoginForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `OtpForm`, `PinForm` | Components |
+| `AuthThemeProvider`, `useAuthTheme`, `defaultAuthTheme`, `AuthTheme` | Theming |
+| `DEFAULT_LOGIN_LABELS`, `DEFAULT_FORGOT_PASSWORD_LABELS`, `DEFAULT_RESET_PASSWORD_LABELS`, `DEFAULT_OTP_LABELS`, `DEFAULT_PIN_LABELS` | Label bags |
+| `useBffAuth`, `useBffForgotPassword`, `useBffResetPassword`, `useResetPasswordForm`, `useOtpLogin`, `usePinLogin` | Headless hooks |
+| `OtpLoginStep` | OTP step enum |
+| `createBffAuthClient`, `BffAuthClient` (re-export) | Client |
+| `resolvePostLoginRoute`, `collectUserRoles`, `RoleRouteTable` | Router |
+| `validatePasswordPolicy`, `isPasswordValid`, `PasswordPolicyError` | Password policy |
+| `AuthTestIds`, `withTestIdPrefix` | Test IDs |
+
+## License
+
+MIT