@forjio/auth-ui

Shared auth forms for the Forjio family. Login, signup, forgot- password, reset-password — all with the same look as every other Forjio product, all wired to the standard @forjio/sdk/auth-handlers backend endpoints (override via endpoints prop if your product mounts them somewhere else).

Sister package to @forjio/website-ui

• @forjio/portal-ui. Extracted from saas-plugipay on 2026-05-19 as the canonical reference build per TEMPLATE.md Step 4.

Install

npm i @forjio/auth-ui lucide-react

Peer deps: react, react-dom, next (App Router), lucide-react. Tailwind is not a peer dep but the components use shadcn-style utility classes (bg-primary, text-muted-foreground, etc.) so the host product needs a Tailwind config that exposes the shadcn token set.

Usage

// app/(auth)/login/page.tsx
'use client';
import { AuthForm } from '@forjio/auth-ui';

export default function LoginPage() {
  return <AuthForm mode="login" brand="Kalium" />;
}

// app/(auth)/signup/page.tsx
'use client';
import { AuthForm } from '@forjio/auth-ui';

export default function SignupPage() {
  return <AuthForm mode="signup" brand="Kalium" />;
}

// app/(auth)/forgot-password/page.tsx
'use client';
import { ForgotPasswordForm } from '@forjio/auth-ui';

export default function ForgotPasswordPage() {
  return <ForgotPasswordForm />;
}

// app/(auth)/reset-password/page.tsx
'use client';
import { ResetPasswordForm } from '@forjio/auth-ui';

export default function ResetPasswordPage() {
  return <ResetPasswordForm />;
}

Props

AuthForm

| Prop | Default | Notes | |-------------------|----------------------------------|------------------------------------------------------| | mode | required | 'login' or 'signup' | | brand | required | Brand name shown in copy (e.g. 'Kalium') | | endpoints | family defaults | Override paths if backend mounts differ | | providers | null (fail-open shows all) | { google?, apple?, facebook? } bools — host fetches | | defaultReturnTo | /dashboard | Redirect after success; ?return_to= overrides |

ForgotPasswordForm / ResetPasswordForm

| Prop | Default | Notes | |-------------|------------------|------------------------------------| | endpoints | family defaults | Override paths if backend differs |

Endpoint defaults

{
  login:          '/api/v1/auth/login',
  signup:         '/api/v1/auth/signup',
  forgotPassword: '/api/v1/auth/password-reset/request',
  resetPassword:  '/api/v1/auth/password-reset/complete',
  socialStart:    '/api/v1/auth/huudis/start',
}

These match the routes mounted by @forjio/sdk/auth-handlers. New products should mount the same paths and not override the prop.

Social login

AuthForm renders Google, Apple, and Facebook buttons. Each is gated on providers (fail-open — undefined/null shows all three). Each button links to socialStart?provider=<name>&return_to=….

MFA hand-off

The product BFF does not do inline MFA. When a user with MFA enabled signs in, the @forjio/sdk /login route returns 401 with body { error: { code: 'MFA_REQUIRED', … } }. AuthForm detects this and redirects the browser to the Huudis hosted-login flow (socialStart?return_to=…, no provider=), where Huudis performs the two-factor challenge. No TOTP form is rendered product-side.

Why Tailwind classes (not inline styles)?

Auth forms are visually opinionated — inputs, buttons, error states, labels — and every Forjio product uses shadcn-flavored Tailwind. Inline styles would diverge from the host's design system. The shadcn token set (bg-primary, text-muted-foreground, border-border) is stable across all 8 active products. Sister @forjio/portal-ui uses inline styles because its surface is structural chrome where Tailwind would collide with the host.

License

UNLICENSED — private Forjio family package.