@shipfox/client-auth 0.2.0

package/src/pages/form-errors.test.ts

@@ -0,0 +1,114 @@
+import {ApiError} from '@shipfox/client-api';
+import {
+  loginErrorToFormError,
+  passwordResetConfirmErrorToFormError,
+  passwordResetRequestErrorToFormError,
+  signupErrorToFormError,
+  workspaceOnboardingErrorToFormError,
+} from './form-errors.js';
+
+function apiError(code: string, status = 400) {
+  return new ApiError({code, message: `${code} server message`, status});
+}
+
+describe('loginErrorToFormError', () => {
+  test('routes email-not-verified to the email field', () => {
+    const result = loginErrorToFormError(apiError('email-not-verified'));
+
+    expect(result).toEqual({
+      kind: 'field',
+      field: 'email',
+      message: 'Verify your email before signing in.',
+    });
+  });
+
+  test('routes invalid-credentials to a form-level alert', () => {
+    const result = loginErrorToFormError(apiError('invalid-credentials'));
+
+    expect(result).toEqual({kind: 'form', message: 'Email or password is incorrect.'});
+  });
+
+  test('routes rate-limited to a form-level alert', () => {
+    const result = loginErrorToFormError(apiError('rate-limited', 429));
+
+    expect(result).toEqual({
+      kind: 'form',
+      message: 'Too many attempts. Wait a bit and try again.',
+    });
+  });
+
+  test('routes limiter outages to a form-level alert', () => {
+    const result = loginErrorToFormError(apiError('auth-rate-limit-unavailable', 503));
+
+    expect(result).toEqual({
+      kind: 'form',
+      message: 'Sign-in protection is temporarily unavailable. Try again soon.',
+    });
+  });
+
+  test('routes unknown ApiError codes to a form-level alert', () => {
+    const result = loginErrorToFormError(apiError('unknown-code', 400));
+
+    expect(result).toEqual({kind: 'form', message: 'unknown-code server message'});
+  });
+
+  test('routes non-ApiError to a generic form-level alert', () => {
+    const result = loginErrorToFormError(new Error('boom'));
+
+    expect(result).toEqual({kind: 'form', message: 'Something went wrong. Try again.'});
+  });
+});
+
+describe('signupErrorToFormError', () => {
+  test('routes email-taken to the email field', () => {
+    const result = signupErrorToFormError(apiError('email-taken'));
+
+    expect(result).toEqual({
+      kind: 'field',
+      field: 'email',
+      message: 'An account already exists for this email.',
+    });
+  });
+
+  test('routes other ApiError codes to a form-level alert', () => {
+    const result = signupErrorToFormError(apiError('network-error'));
+
+    expect(result).toEqual({
+      kind: 'form',
+      message: 'We could not reach the API. Check your connection and try again.',
+    });
+  });
+});
+
+describe('passwordResetRequestErrorToFormError', () => {
+  test('always routes to a form-level alert', () => {
+    const result = passwordResetRequestErrorToFormError(apiError('rate-limited', 429));
+
+    expect(result).toEqual({
+      kind: 'form',
+      message: 'Too many attempts. Wait a bit and try again.',
+    });
+  });
+});
+
+describe('passwordResetConfirmErrorToFormError', () => {
+  test('routes token-invalid to a form-level alert', () => {
+    const result = passwordResetConfirmErrorToFormError(apiError('token-invalid'));
+
+    expect(result).toEqual({kind: 'form', message: 'This link is invalid or expired.'});
+  });
+
+  test('routes unknown errors to a generic form-level alert', () => {
+    const result = passwordResetConfirmErrorToFormError(new Error('boom'));
+
+    expect(result).toEqual({kind: 'form', message: 'Something went wrong. Try again.'});
+  });
+});
+
+describe('workspaceOnboardingErrorToFormError', () => {
+  test('routes any error to a form-level alert', () => {
+    const result = workspaceOnboardingErrorToFormError(apiError('conflict', 409));
+
+    expect(result).toEqual({kind: 'form', message: 'conflict server message'});
+  });
+});

package/src/pages/form-errors.ts

@@ -0,0 +1,45 @@
+import {ApiError} from '@shipfox/client-api';
+import {authErrorMessage} from './form-utils.js';
+
+export type FormErrorMapping<TField extends string> =
+  | {kind: 'field'; field: TField; message: string}
+  | {kind: 'form'; message: string};
+
+type LoginField = 'email' | 'password';
+type SignupField = 'email' | 'password' | 'name';
+type PasswordResetRequestField = 'email';
+type PasswordResetConfirmField = 'new_password';
+
+function apiCode(error: unknown): string | undefined {
+  return error instanceof ApiError ? error.code : undefined;
+}
+
+export function loginErrorToFormError(error: unknown): FormErrorMapping<LoginField> {
+  if (apiCode(error) === 'email-not-verified') {
+    return {kind: 'field', field: 'email', message: authErrorMessage(error)};
+  }
+  return {kind: 'form', message: authErrorMessage(error)};
+}
+
+export function signupErrorToFormError(error: unknown): FormErrorMapping<SignupField> {
+  if (apiCode(error) === 'email-taken') {
+    return {kind: 'field', field: 'email', message: authErrorMessage(error)};
+  }
+  return {kind: 'form', message: authErrorMessage(error)};
+}
+
+export function passwordResetRequestErrorToFormError(
+  error: unknown,
+): FormErrorMapping<PasswordResetRequestField> {
+  return {kind: 'form', message: authErrorMessage(error)};
+}
+
+export function passwordResetConfirmErrorToFormError(
+  error: unknown,
+): FormErrorMapping<PasswordResetConfirmField> {
+  return {kind: 'form', message: authErrorMessage(error)};
+}
+
+export function workspaceOnboardingErrorToFormError(error: unknown): FormErrorMapping<'name'> {
+  return {kind: 'form', message: authErrorMessage(error)};
+}

package/src/pages/form-utils.test.ts

@@ -0,0 +1,37 @@
+import {ApiError} from '@shipfox/client-api';
+import {authErrorMessage} from './form-utils.js';
+
+describe('authErrorMessage', () => {
+  test.each([
+    ['invalid-credentials', 'Email or password is incorrect.'],
+    ['email-not-verified', 'Verify your email before signing in.'],
+    ['email-taken', 'An account already exists for this email.'],
+    ['token-invalid', 'This link is invalid or expired.'],
+    ['rate-limited', 'Too many attempts. Wait a bit and try again.'],
+    [
+      'auth-rate-limit-unavailable',
+      'Sign-in protection is temporarily unavailable. Try again soon.',
+    ],
+    ['network-error', 'We could not reach the API. Check your connection and try again.'],
+  ])('maps %s to client copy', (code, message) => {
+    const error = new ApiError({code, message: 'Server copy', status: 400});
+
+    const result = authErrorMessage(error);
+
+    expect(result).toBe(message);
+  });
+
+  test('falls back to API error messages', () => {
+    const error = new ApiError({code: 'unknown-api-code', message: 'Try later', status: 429});
+
+    const result = authErrorMessage(error);
+
+    expect(result).toBe('Try later');
+  });
+
+  test('uses generic copy for unknown errors', () => {
+    const result = authErrorMessage(new Error('boom'));
+
+    expect(result).toBe('Something went wrong. Try again.');
+  });
+});

package/src/pages/form-utils.ts

@@ -0,0 +1,29 @@
+import {ApiError} from '@shipfox/client-api';
+
+export function authErrorMessage(error: unknown): string {
+  if (!(error instanceof ApiError)) return 'Something went wrong. Try again.';
+
+  if (error.code === 'invalid-credentials') {
+    return 'Email or password is incorrect.';
+  }
+  if (error.code === 'email-not-verified') {
+    return 'Verify your email before signing in.';
+  }
+  if (error.code === 'email-taken') {
+    return 'An account already exists for this email.';
+  }
+  if (error.code === 'token-invalid') {
+    return 'This link is invalid or expired.';
+  }
+  if (error.code === 'rate-limited') {
+    return 'Too many attempts. Wait a bit and try again.';
+  }
+  if (error.code === 'auth-rate-limit-unavailable') {
+    return 'Sign-in protection is temporarily unavailable. Try again soon.';
+  }
+  if (error.code === 'network-error') {
+    return 'We could not reach the API. Check your connection and try again.';
+  }
+
+  return error.message || 'Something went wrong. Try again.';
+}

package/src/pages/invitation-context.ts

@@ -0,0 +1,57 @@
+import type {
+  PreviewInvitationPendingDto,
+  PreviewInvitationResponseDto,
+} from '@shipfox/api-workspaces-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {useQuery} from '@tanstack/react-query';
+
+const INVITATION_ACCEPT_PATH = '/invitations/accept';
+
+/**
+ * Extract an invitation token from a `redirect=` URL if it points at the
+ * canonical pre-auth invitation page. Returns undefined when the redirect is
+ * absent, malformed, or unrelated to invitations.
+ */
+export function extractInvitationToken(redirect: unknown): string | undefined {
+  if (typeof redirect !== 'string') return undefined;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(redirect);
+  } catch {
+    return undefined;
+  }
+  if (!decoded.startsWith('/')) return undefined;
+  const [path, queryString = ''] = decoded.split('?', 2);
+  if (path !== INVITATION_ACCEPT_PATH) return undefined;
+  const params = new URLSearchParams(queryString);
+  const token = params.get('token');
+  return token && token.length > 0 ? token : undefined;
+}
+
+async function fetchPreview(token: string): Promise<PreviewInvitationResponseDto> {
+  const params = new URLSearchParams({token});
+  return await apiRequest<PreviewInvitationResponseDto>(
+    `/invitations/preview?${params.toString()}`,
+  );
+}
+
+export function pendingInvitation(
+  data: PreviewInvitationResponseDto | undefined,
+): PreviewInvitationPendingDto | undefined {
+  return data?.status === 'pending' ? data : undefined;
+}
+
+/**
+ * Mirrors the hook in `@shipfox/client-invitations` but lives in `client-auth`
+ * to avoid a circular dependency. Signup/login pages call this to lock the
+ * email field when arriving from an invitation link.
+ */
+export function useInvitationContext(token: string | undefined) {
+  return useQuery({
+    queryKey: ['invitations', 'preview', token ?? ''] as const,
+    queryFn: () => fetchPreview(token as string),
+    enabled: Boolean(token),
+    retry: false,
+    staleTime: 30_000,
+  });
+}

package/src/pages/login-page.test.tsx

@@ -0,0 +1,128 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {act, fireEvent, screen} from '@testing-library/react';
+import {GuestGuard} from '#components/auth-guard.js';
+import {pageUserFactory} from '#test/factories/user.js';
+import {renderAuthPage} from '#test/pages.js';
+import {jsonResponse, requestUrl} from '#test/utils.js';
+import {LoginPage} from './login-page.js';
+
+describe('LoginPage', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', getAccessToken: undefined});
+  });
+
+  test('renders account recovery and signup links', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(
+        jsonResponse({code: 'unauthorized', message: 'Unauthorized'}, {status: 401}),
+      );
+    configureApiClient({fetchImpl});
+
+    renderAuthPage('/auth/login', <LoginPage />);
+
+    expect(await screen.findByRole('heading', {name: 'Connect to Shipfox'})).toBeInTheDocument();
+    expect(screen.getByRole('link', {name: 'Create an account'})).toHaveAttribute(
+      'href',
+      '/auth/signup',
+    );
+    expect(screen.getByRole('link', {name: 'Forgot password?'})).toHaveAttribute(
+      'href',
+      '/auth/reset',
+    );
+  });
+
+  test('keeps credentials when switching to signup', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(
+        jsonResponse({code: 'unauthorized', message: 'Unauthorized'}, {status: 401}),
+      );
+    configureApiClient({fetchImpl});
+
+    renderAuthPage('/auth/login', <LoginPage />);
+    fireEvent.change(await screen.findByLabelText('Email'), {
+      target: {value: 'new@example.com'},
+    });
+    fireEvent.change(screen.getByLabelText('Password'), {
+      target: {value: 'long secure password'},
+    });
+    fireEvent.click(screen.getByRole('link', {name: 'Create an account'}));
+
+    expect(
+      await screen.findByRole('heading', {name: 'Create your Shipfox account'}),
+    ).toBeInTheDocument();
+    expect(screen.getByLabelText('Email')).toHaveValue('new@example.com');
+    expect(screen.getByLabelText('Password')).toHaveValue('long secure password');
+  });
+
+  test('preserves invitation state when switching to signup', async () => {
+    const invitationToken = 'invite-token';
+    const redirect = `/invitations/accept?token=${encodeURIComponent(invitationToken)}`;
+    const fetchImpl = vi.fn().mockImplementation((input: RequestInfo | URL) => {
+      const url = requestUrl(input);
+      if (url === 'https://api.example.test/auth/me') {
+        return Promise.resolve(
+          jsonResponse({code: 'unauthorized', message: 'Unauthorized'}, {status: 401}),
+        );
+      }
+      if (url.includes('/invitations/preview?')) {
+        return Promise.resolve(
+          jsonResponse({
+            status: 'pending',
+            workspace_id: 'workspace-1',
+            workspace_name: 'Invite Workspace',
+            email: 'invitee@example.com',
+            invited_by_display: 'owner@example.com',
+            expires_at: '2026-05-18T00:00:00.000Z',
+          }),
+        );
+      }
+      throw new Error(`Unexpected request: ${url}`);
+    });
+    configureApiClient({fetchImpl});
+
+    renderAuthPage(`/auth/login?redirect=${encodeURIComponent(redirect)}`, <LoginPage />);
+    await screen.findByRole('heading', {name: 'Join Invite Workspace'});
+
+    expect(screen.getByRole('link', {name: 'Create an account'})).toHaveAttribute(
+      'href',
+      `/auth/signup?redirect=${encodeURIComponent(redirect)}`,
+    );
+  });
+
+  test('posts valid credentials and navigates home', async () => {
+    const user = pageUserFactory.build({email: 'login@example.com'});
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(
+        jsonResponse({code: 'unauthorized', message: 'Unauthorized'}, {status: 401}),
+      )
+      .mockImplementationOnce(() => {
+        return jsonResponse({
+          token: 'access-token',
+          user,
+        });
+      })
+      .mockImplementationOnce(() => {
+        return jsonResponse({memberships: []});
+      });
+    configureApiClient({fetchImpl});
+
+    renderAuthPage(
+      '/auth/login',
+      <GuestGuard>
+        <LoginPage />
+      </GuestGuard>,
+    );
+    fireEvent.change(await screen.findByLabelText('Email'), {
+      target: {value: 'login@example.com'},
+    });
+    fireEvent.change(screen.getByLabelText('Password'), {target: {value: 'correct horse'}});
+    // Let TanStack Form publish field changes before submit validation reads them.
+    await act(() => Promise.resolve());
+    fireEvent.click(screen.getByRole('button', {name: 'Log in'}));
+
+    expect(await screen.findByRole('heading', {name: 'Authenticated home'})).toBeInTheDocument();
+  });
+});

package/src/pages/login-page.tsx

@@ -0,0 +1,184 @@
+import {loginBodySchema} from '@shipfox/api-auth-dto';
+import {Button, ButtonLink} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {FormField, FormFieldInput, fieldError} from '@shipfox/react-ui/form-field';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Text} from '@shipfox/react-ui/typography';
+import {useForm} from '@tanstack/react-form';
+import {Link, useSearch} from '@tanstack/react-router';
+import {useAtom} from 'jotai';
+import {useEffect, useRef, useState} from 'react';
+import {AuthShell} from '#/components/auth-shell.js';
+import {useLoginAuth} from '#hooks/api/login-auth.js';
+import {authFormDraftAtom, initialAuthFormDraft} from '#state/auth.js';
+import {loginErrorToFormError} from './form-errors.js';
+import {
+  extractInvitationToken,
+  pendingInvitation,
+  useInvitationContext,
+} from './invitation-context.js';
+
+export function LoginPage() {
+  const login = useLoginAuth();
+  const search = useSearch({strict: false}) as {redirect?: unknown};
+  const invitationToken = extractInvitationToken(search.redirect);
+  const invitationPreview = useInvitationContext(invitationToken);
+  const invitationPending = pendingInvitation(invitationPreview.data);
+  const [authFormDraft, setAuthFormDraft] = useAtom(authFormDraftAtom);
+  const [formError, setFormError] = useState<string | undefined>();
+  const draftRef = useRef(authFormDraft);
+  draftRef.current = authFormDraft;
+  // Set just before clearing the draft on success so the unmount cleanup
+  // below does not repersist the just-submitted credentials.
+  const skipDraftPersistRef = useRef(false);
+
+  const form = useForm({
+    defaultValues: {email: authFormDraft.email, password: authFormDraft.password},
+    onSubmit: async ({value}) => {
+      setFormError(undefined);
+      try {
+        await login.mutateAsync(value);
+        skipDraftPersistRef.current = true;
+        setAuthFormDraft(initialAuthFormDraft);
+      } catch (error) {
+        const mapped = loginErrorToFormError(error);
+        if (mapped.kind === 'field') {
+          form.setFieldMeta(mapped.field, (prev) => ({
+            ...prev,
+            errorMap: {...prev.errorMap, onServer: mapped.message},
+          }));
+        } else {
+          setFormError(mapped.message);
+        }
+      }
+    },
+  });
+
+  // Lock the email field when arriving from an invitation link so the user
+  // can't log in as a different account than the one the invitation targets.
+  useEffect(() => {
+    if (invitationPending && form.state.values.email !== invitationPending.email) {
+      form.setFieldValue('email', invitationPending.email);
+      setAuthFormDraft((current) => ({...current, email: invitationPending.email}));
+    }
+  }, [invitationPending, form, setAuthFormDraft]);
+
+  // Sync TanStack Form values back into the Jotai draft on unmount so a
+  // navigation to /signup or /reset preserves what the user typed. Skipped
+  // after a successful login because we just intentionally cleared the draft.
+  useEffect(() => {
+    return () => {
+      if (skipDraftPersistRef.current) return;
+      const {email, password} = form.state.values;
+      if (email !== draftRef.current.email || password !== draftRef.current.password) {
+        setAuthFormDraft({email, password});
+      }
+    };
+  }, [form, setAuthFormDraft]);
+
+  const isInvitationEmailLocked = Boolean(invitationPending);
+  const invitationRedirect = invitationToken
+    ? `/invitations/accept?token=${encodeURIComponent(invitationToken)}`
+    : undefined;
+  const headerTitle = invitationPending
+    ? `Join ${invitationPending.workspace_name}`
+    : 'Connect to Shipfox';
+  const headerDescription = invitationPending
+    ? 'Log in to accept your invitation.'
+    : 'Log in to access Shipfox.';
+
+  function persistDraft() {
+    const {email, password} = form.state.values;
+    setAuthFormDraft({email, password});
+  }
+
+  return (
+    <AuthShell title={headerTitle} description={headerDescription}>
+      <form
+        className="flex flex-col gap-18"
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          void form.handleSubmit();
+        }}
+      >
+        {formError ? (
+          <Callout role="alert" type="error">
+            {formError}
+          </Callout>
+        ) : null}
+        <form.Field
+          name="email"
+          validators={{onBlur: loginBodySchema.shape.email, onSubmit: loginBodySchema.shape.email}}
+        >
+          {(field) => (
+            <FormField label="Email" id="email" error={fieldError(field)}>
+              <FormFieldInput
+                autoComplete="email"
+                name="email"
+                type="email"
+                value={field.state.value}
+                onChange={(event) => field.handleChange(event.target.value)}
+                onBlur={() => {
+                  field.handleBlur();
+                  persistDraft();
+                }}
+                readOnly={isInvitationEmailLocked}
+                iconRight={
+                  isInvitationEmailLocked ? (
+                    <Icon
+                      aria-hidden="true"
+                      className="size-16 text-foreground-neutral-disabled"
+                      name="lockLine"
+                    />
+                  ) : undefined
+                }
+              />
+            </FormField>
+          )}
+        </form.Field>
+        <form.Field
+          name="password"
+          validators={{
+            onBlur: loginBodySchema.shape.password,
+            onSubmit: loginBodySchema.shape.password,
+          }}
+        >
+          {(field) => (
+            <FormField label="Password" id="password" error={fieldError(field)}>
+              <FormFieldInput
+                autoComplete="current-password"
+                name="password"
+                type="password"
+                value={field.state.value}
+                onChange={(event) => field.handleChange(event.target.value)}
+                onBlur={() => {
+                  field.handleBlur();
+                  persistDraft();
+                }}
+              />
+            </FormField>
+          )}
+        </form.Field>
+        <ButtonLink asChild variant="subtle" className="-mt-8 self-end">
+          <Link to="/auth/reset">Forgot password?</Link>
+        </ButtonLink>
+        <Button className="w-full" isLoading={login.isPending} type="submit">
+          {login.isPending ? 'Logging in...' : 'Log in'}
+        </Button>
+      </form>
+      <Text size="sm" className="text-center text-foreground-neutral-subtle">
+        New to Shipfox?{' '}
+        <ButtonLink asChild variant="interactive" underline>
+          <Link
+            to="/auth/signup"
+            search={invitationRedirect ? {redirect: invitationRedirect} : undefined}
+          >
+            Create an account
+          </Link>
+        </ButtonLink>
+      </Text>
+    </AuthShell>
+  );
+}

package/src/pages/logout-page.tsx

@@ -0,0 +1,33 @@
+import {Text} from '@shipfox/react-ui/typography';
+import {useNavigate, useRouter, useSearch} from '@tanstack/react-router';
+import {useEffect} from 'react';
+import {AuthShell} from '#/components/auth-shell.js';
+import {sanitizeRedirectPath} from '#/components/redirect-target.js';
+import {useLogoutAuth} from '#hooks/api/logout-auth.js';
+
+export function LogoutPage() {
+  const logout = useLogoutAuth();
+  const navigate = useNavigate();
+  const router = useRouter();
+  const search = useSearch({strict: false}) as {redirect?: unknown};
+  const target = sanitizeRedirectPath(search.redirect);
+
+  useEffect(() => {
+    logout.mutateAsync().finally(() => {
+      if (target !== undefined) {
+        // Same-origin runtime path; let history drive route resolution.
+        router.history.replace(target);
+      } else {
+        navigate({to: '/auth/login', replace: true});
+      }
+    });
+  }, [logout.mutateAsync, navigate, router, target]);
+
+  return (
+    <AuthShell title="Logging out" description="Ending your Shipfox session.">
+      <Text size="sm" className="text-center text-foreground-neutral-subtle">
+        You will be sent back to login in a moment.
+      </Text>
+    </AuthShell>
+  );
+}