@maxal_studio/kratosjs-react 1.0.0

package/src/auth/authApiClient.ts

@@ -0,0 +1,109 @@
+import { AuthUser, AuthProvider, AuthTokens, LoginCredentials, LoginResult } from './types';
+
+/**
+ * API client for authentication endpoints.
+ * Tokens are managed via HTTP-only cookies set by the server — no localStorage involved.
+ */
+export class AuthApiClient {
+	constructor(private apiBaseUrl: string) {}
+
+	async getProviders(): Promise<AuthProvider[]> {
+		const response = await fetch(`${this.apiBaseUrl}/auth/providers`, {
+			credentials: 'include',
+		});
+		if (!response.ok) {
+			throw new Error('Failed to fetch providers');
+		}
+		const data = await response.json();
+		return data.providers || [];
+	}
+
+	/**
+	 * Attempt login. Returns a discriminated result: `authenticated` (session cookie set)
+	 * or `challenge` (a verification step like 2FA is required before tokens are issued).
+	 */
+	async login(provider: string, credentials: LoginCredentials): Promise<LoginResult> {
+		const response = await fetch(`${this.apiBaseUrl}/auth/login`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			credentials: 'include',
+			body: JSON.stringify({ provider, ...credentials }),
+		});
+
+		if (!response.ok) {
+			const error = await response.json();
+			throw new Error(error.error || 'Login failed');
+		}
+
+		return response.json();
+	}
+
+	/**
+	 * Respond to a pending login challenge. Returns the next `LoginResult` — either
+	 * `authenticated` (all steps cleared) or another `challenge` (chained step).
+	 */
+	async verifyChallenge(challengeToken: string, type: string, payload: unknown): Promise<LoginResult> {
+		const response = await fetch(`${this.apiBaseUrl}/auth/challenge`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			credentials: 'include',
+			body: JSON.stringify({ challengeToken, type, payload }),
+		});
+
+		if (!response.ok) {
+			const error = await response.json();
+			throw new Error(error.error || 'Verification failed');
+		}
+
+		return response.json();
+	}
+
+	async getCurrentUser(): Promise<AuthUser | null> {
+		const response = await fetch(`${this.apiBaseUrl}/auth/me`, {
+			credentials: 'include',
+		});
+
+		if (!response.ok) {
+			if (response.status === 401) {
+				const error: any = new Error('Unauthorized');
+				error.status = 401;
+				throw error;
+			}
+			throw new Error('Failed to get current user');
+		}
+
+		const data = await response.json();
+		return data.user || null;
+	}
+
+	async refreshToken(): Promise<AuthTokens | null> {
+		const response = await fetch(`${this.apiBaseUrl}/auth/refresh`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			credentials: 'include',
+			body: JSON.stringify({}),
+		});
+
+		if (!response.ok) {
+			return null;
+		}
+
+		const data = await response.json();
+		return data.tokens || null;
+	}
+
+	async logout(): Promise<void> {
+		try {
+			await fetch(`${this.apiBaseUrl}/auth/logout`, {
+				method: 'POST',
+				credentials: 'include',
+			});
+		} catch {
+			// Ignore errors — server-side cookie clearing is best-effort
+		}
+	}
+
+	getAuthHeaders(): HeadersInit {
+		return {};
+	}
+}

package/src/auth/authFlow.test.tsx

@@ -0,0 +1,168 @@
+import React from 'react';
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { AuthProvider, useAuth } from './AuthContext';
+import { LoginPage } from './LoginPage';
+import { AuthChallengeRegistryProvider } from '../contexts/AuthChallengeRegistryContext';
+import { resolveRegistries } from '../app';
+import { definePluginClient } from '../plugin';
+import type { AuthChallengeProps } from './types';
+
+// Minimal fetch Response stand-in for the auth client.
+function resp(data: any, ok = true, status = 200) {
+	return { ok, status, json: async () => data } as Response;
+}
+
+const challengeResp = {
+	status: 'challenge',
+	challenge: { type: '2fa-totp', challengeToken: 'ct-1', data: { hint: 'authenticator' } },
+};
+const authResp = {
+	status: 'authenticated',
+	user: { id: '1', email: 'alice@example.com' },
+	tokens: { expiresIn: 900 },
+};
+
+/** Route fetch by URL; /auth/me + /auth/refresh resolve to "not logged in". */
+function makeFetch(routes: { login: () => Response; challenge?: () => Response }) {
+	return vi.fn(async (url: string | URL) => {
+		const u = String(url);
+		if (u.includes('/auth/login')) return routes.login();
+		if (u.includes('/auth/challenge')) return (routes.challenge ?? (() => resp(authResp)))();
+		if (u.includes('/auth/me')) return resp({}, false, 401);
+		if (u.includes('/auth/refresh')) return resp(null, false, 401);
+		if (u.includes('/auth/providers'))
+			return resp({ providers: [{ name: 'email', label: 'Email', type: 'credentials' }] });
+		if (u.includes('/meta')) return resp({ title: 'Test Panel' });
+		return resp({}, false, 404);
+	});
+}
+
+beforeEach(() => {
+	if (!window.matchMedia) {
+		window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addEventListener: () => {},
+			removeEventListener: () => {},
+			addListener: () => {},
+			removeListener: () => {},
+			dispatchEvent: () => false,
+		})) as any;
+	}
+});
+
+function Consumer() {
+	const { user, pendingChallenge, login, verifyChallenge } = useAuth();
+	return (
+		<div>
+			<div data-testid="user">{user ? user.email : 'none'}</div>
+			<div data-testid="challenge">{pendingChallenge ? pendingChallenge.type : 'none'}</div>
+			<button onClick={() => login('email', { email: 'a@b.c', password: 'x' })}>do-login</button>
+			<button onClick={() => verifyChallenge({ code: '123456' })}>do-verify</button>
+		</div>
+	);
+}
+
+describe('AuthContext multi-step login', () => {
+	it('a challenge login sets pendingChallenge and leaves the user null', async () => {
+		vi.stubGlobal('fetch', makeFetch({ login: () => resp(challengeResp) }));
+
+		render(
+			<AuthProvider apiBaseUrl="/api">
+				<Consumer />
+			</AuthProvider>,
+		);
+		await waitFor(() => expect(screen.getByTestId('user').textContent).toBe('none'));
+
+		await userEvent.click(screen.getByText('do-login'));
+
+		await waitFor(() => expect(screen.getByTestId('challenge').textContent).toBe('2fa-totp'));
+		expect(screen.getByTestId('user').textContent).toBe('none');
+	});
+
+	it('verifying the challenge sets the user and clears pendingChallenge', async () => {
+		vi.stubGlobal('fetch', makeFetch({ login: () => resp(challengeResp), challenge: () => resp(authResp) }));
+
+		render(
+			<AuthProvider apiBaseUrl="/api">
+				<Consumer />
+			</AuthProvider>,
+		);
+		await waitFor(() => expect(screen.getByTestId('user').textContent).toBe('none'));
+
+		await userEvent.click(screen.getByText('do-login'));
+		await waitFor(() => expect(screen.getByTestId('challenge').textContent).toBe('2fa-totp'));
+
+		await userEvent.click(screen.getByText('do-verify'));
+		await waitFor(() => expect(screen.getByTestId('user').textContent).toBe('alice@example.com'));
+		expect(screen.getByTestId('challenge').textContent).toBe('none');
+	});
+});
+
+describe('LoginPage challenge rendering', () => {
+	it('renders the registered challenge component for the pending type', async () => {
+		vi.stubGlobal('fetch', makeFetch({ login: () => resp(challengeResp) }));
+
+		const TotpUI = ({ onSubmit, submitting }: AuthChallengeProps) => (
+			<div>
+				<div>Enter your authenticator code</div>
+				<button onClick={() => onSubmit({ code: '123456' })} disabled={submitting}>
+					submit-code
+				</button>
+			</div>
+		);
+
+		render(
+			<AuthProvider apiBaseUrl="/api">
+				<AuthChallengeRegistryProvider customAuthChallenges={{ '2fa-totp': TotpUI }}>
+					<LoginPage apiBaseUrl="/api" />
+				</AuthChallengeRegistryProvider>
+			</AuthProvider>,
+		);
+
+		const email = await screen.findByPlaceholderText('you@company.com');
+		await userEvent.type(email, 'a@b.c');
+		await userEvent.type(screen.getByPlaceholderText('Enter your password'), 'secret');
+		await userEvent.click(screen.getByRole('button', { name: 'Sign in' }));
+
+		expect(await screen.findByText('Enter your authenticator code')).toBeTruthy();
+	});
+
+	it('shows a fallback when no component is registered for the challenge type', async () => {
+		vi.stubGlobal('fetch', makeFetch({ login: () => resp(challengeResp) }));
+
+		render(
+			<AuthProvider apiBaseUrl="/api">
+				<AuthChallengeRegistryProvider customAuthChallenges={{}}>
+					<LoginPage apiBaseUrl="/api" />
+				</AuthChallengeRegistryProvider>
+			</AuthProvider>,
+		);
+
+		const email = await screen.findByPlaceholderText('you@company.com');
+		await userEvent.type(email, 'a@b.c');
+		await userEvent.type(screen.getByPlaceholderText('Enter your password'), 'secret');
+		await userEvent.click(screen.getByRole('button', { name: 'Sign in' }));
+
+		expect(await screen.findByText(/No UI is registered for challenge type/)).toBeTruthy();
+	});
+});
+
+describe('resolveRegistries authChallenges', () => {
+	it('merges plugin authChallenges and lets app entries win', () => {
+		const PluginUI = () => null;
+		const AppUI = () => null;
+		const plugin = definePluginClient({ name: '2fa', authChallenges: { '2fa-totp': PluginUI } });
+
+		const registries = resolveRegistries({
+			plugins: [plugin],
+			authChallenges: { 'email-code': AppUI },
+		});
+
+		expect(registries.authChallenges['2fa-totp']).toBe(PluginUI);
+		expect(registries.authChallenges['email-code']).toBe(AppUI);
+	});
+});

package/src/auth/types.ts

@@ -0,0 +1,104 @@
+import type { ComponentType } from 'react';
+
+/**
+ * Authenticated user interface
+ */
+export interface AuthUser {
+	/** Unique identifier */
+	id: string;
+	/** Email address */
+	email: string;
+	/** Display name */
+	name?: string;
+	/** Role/title (e.g., 'admin', 'editor') */
+	role?: string;
+	/** Avatar image URL */
+	avatarUrl?: string;
+	/** Preferred theme */
+	theme?: string;
+	/** Provider-specific metadata */
+	_auth?: Record<string, any>;
+	/** Additional custom fields */
+	[key: string]: any;
+}
+
+/**
+ * Authentication provider configuration
+ */
+export interface AuthProvider {
+	/** Provider name */
+	name: string;
+	/** Display label */
+	label: string;
+	/** Icon name (Lucide) */
+	icon?: string;
+	/** Provider type */
+	type: 'credentials' | 'oauth';
+	/** Button styling */
+	buttonStyle?: {
+		backgroundColor?: string;
+		textColor?: string;
+		borderColor?: string;
+	};
+	/** Required fields for credentials type */
+	fields?: string[];
+}
+
+/**
+ * Authentication tokens
+ */
+export interface AuthTokens {
+	/** JWT access token */
+	accessToken: string;
+	/** JWT refresh token */
+	refreshToken: string;
+	/** Access token expiration in seconds */
+	expiresIn: number;
+}
+
+/**
+ * Login credentials
+ */
+export interface LoginCredentials {
+	email: string;
+	password: string;
+}
+
+/**
+ * A pending login challenge returned by the server (e.g. 2FA). The `challengeToken` is an
+ * opaque continuation token the client must echo back to `/auth/challenge` — never decode
+ * it for trust decisions. `data` carries non-secret hints for the challenge UI.
+ */
+export interface PendingChallenge {
+	type: string;
+	challengeToken: string;
+	data?: unknown;
+}
+
+/**
+ * Discriminated result of a login attempt or a challenge verification, mirroring the
+ * backend `LoginResult`. `authenticated` → the session cookie is set; `challenge` → one or
+ * more steps remain and no session cookie was set.
+ */
+export type LoginResult =
+	| { status: 'authenticated'; user: AuthUser; tokens: { expiresIn: number } }
+	| { status: 'challenge'; challenge: PendingChallenge };
+
+/**
+ * Props passed to a challenge UI component registered under `authChallenges`.
+ */
+export interface AuthChallengeProps {
+	/** Non-secret data sent by the server with the challenge. */
+	data?: unknown;
+	/** Submit the user's response; resolves when verified (or rejects on error). */
+	onSubmit: (payload: unknown) => Promise<void>;
+	/** Abandon the challenge and return to the login form. */
+	onCancel: () => void;
+	/** Verification error to display, if any. */
+	error?: string | null;
+	/** Whether a verification request is in flight. */
+	submitting?: boolean;
+}
+
+/** A React component that renders a challenge step. */
+export type AuthChallengeComponent = ComponentType<AuthChallengeProps>;

package/src/components/ActionFormModal.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import { SerializedForm } from '@maxal_studio/kratosjs';
+import { ResourceFormModal } from './modals/ResourceFormModal';
+
+export interface ActionFormModalProps {
+	isOpen: boolean;
+	onClose: () => void;
+	actionName: string;
+	actionLabel?: string;
+	formSchema: SerializedForm;
+	recordIds: string[];
+	isBulk?: boolean;
+	requiresConfirmation?: boolean;
+	modalDescription?: string;
+	apiBaseUrl: string;
+	resourceSlug: string;
+	onSuccess?: () => void;
+	depth?: number;
+	onCloseAll?: () => void;
+}
+
+/**
+ * Thin wrapper over ResourceFormModal for actions that collect form input.
+ */
+export function ActionFormModal(props: ActionFormModalProps) {
+	return (
+		<ResourceFormModal
+			isOpen={props.isOpen}
+			onClose={props.onClose}
+			mode="action"
+			resourceSlug={props.resourceSlug}
+			apiBaseUrl={props.apiBaseUrl}
+			formSchema={props.formSchema}
+			recordIds={props.recordIds}
+			actionName={props.actionName}
+			actionLabel={props.actionLabel}
+			isBulk={props.isBulk}
+			requiresConfirmation={props.requiresConfirmation}
+			modalDescription={props.modalDescription}
+			onSuccess={props.onSuccess}
+			depth={props.depth}
+			onCloseAll={props.onCloseAll}
+		/>
+	);
+}