@shipfox/client-auth 3.0.1 → 5.0.0

package/src/components/redirect-context.test.ts

@@ -0,0 +1,51 @@
+import {parseRedirectContext} from './redirect-context.js';
+
+describe('parseRedirectContext', () => {
+  test('returns an ordinary safe return path', () => {
+    const context = parseRedirectContext('/workspaces/acme?tab=runs');
+
+    expect(context).toEqual({returnTo: '/workspaces/acme?tab=runs'});
+  });
+
+  test('separates an invitation token from generic redirect state', () => {
+    const context = parseRedirectContext('/invitations/accept?token=raw-invitation-token');
+
+    expect(context).toEqual({invitationToken: 'raw-invitation-token'});
+    expect(context.returnTo).toBeUndefined();
+  });
+
+  test('separates an invitation token after path normalization', () => {
+    const context = parseRedirectContext(
+      '/workspaces/../invitations/accept?token=raw-invitation-token',
+    );
+
+    expect(context).toEqual({invitationToken: 'raw-invitation-token'});
+  });
+
+  test.each([
+    'https://attacker.example',
+    '//attacker.example',
+    '/auth/login',
+    '/%61uth/login',
+    '/%E0%80%80',
+  ])('rejects malformed or unsafe redirect %s', (redirect) => {
+    const context = parseRedirectContext(redirect);
+
+    expect(context).toEqual({});
+  });
+
+  test.each([
+    ['/invitations/accept', {}],
+    ['/invitations/accept?token=', {}],
+    [
+      '/invitations/other?token=raw-invitation-token',
+      {
+        returnTo: '/invitations/other?token=raw-invitation-token',
+      },
+    ],
+  ])('does not treat %s as an invitation context', (redirect, expected) => {
+    const context = parseRedirectContext(redirect);
+
+    expect(context).toEqual(expected);
+  });
+});

package/src/components/redirect-context.ts

@@ -0,0 +1,26 @@
+import {sanitizeRedirectPath} from './redirect-target.js';
+
+const INVITATION_ACCEPT_PATH = '/invitations/accept';
+
+export interface RedirectContext {
+  invitationToken?: string;
+  returnTo?: string;
+}
+
+/**
+ * Separates a safe post-authentication destination from an invitation token.
+ * The token never remains in `returnTo`, so callers can keep it in their
+ * short-lived invitation flow instead of forwarding it through generic redirects.
+ */
+export function parseRedirectContext(value: unknown): RedirectContext {
+  const redirect = sanitizeRedirectPath(value);
+  if (!redirect) return {};
+
+  const decoded = decodeURIComponent(redirect);
+  const [path, queryString = ''] = decoded.split('?', 2);
+  if (path !== INVITATION_ACCEPT_PATH) return {returnTo: redirect};
+
+  const params = new URLSearchParams(queryString);
+  const invitationToken = params.get('token');
+  return invitationToken ? {invitationToken} : {};
+}

package/src/components/redirect-target.test.ts

@@ -23,6 +23,7 @@ describe('sanitizeRedirectPath', () => {
     ['no leading slash', 'foo'],
     ['protocol-relative URL', '//evil.com'],
     ['triple-slash URL', '///evil.com'],
+    ['backslash external URL', '/\\evil.com'],
     ['absolute https URL', 'https://evil.com'],
     ['javascript scheme', 'javascript:alert(1)'],
     ['plain /auth/login', '/auth/login'],
@@ -30,6 +31,7 @@ describe('sanitizeRedirectPath', () => {
     ['/auth/reset with token', '/auth/reset?token=x'],
     ['/auth with query bypass', '/auth?token=x'],
     ['/auth with fragment bypass', '/auth#foo'],
+    ['normalized auth path', '/workspaces/../auth/logout'],
   ])('rejects %s', (_label, input) => {
     test('returns undefined', () => {
       const result = sanitizeRedirectPath(input);
@@ -51,6 +53,12 @@ describe('sanitizeRedirectPath', () => {
       expect(result).toBeUndefined();
     });
 
+    test('rejects a percent-encoded normalized auth path', () => {
+      const result = sanitizeRedirectPath('/workspaces/%2e%2e/auth/logout');
+
+      expect(result).toBeUndefined();
+    });
+
     test('rejects malformed percent-encoded input', () => {
       const result = sanitizeRedirectPath('/%E0%80%80');
 

package/src/components/redirect-target.ts

@@ -1,21 +1,22 @@
-const SEARCH_OR_HASH_RE = /[?#]/u;
+const REDIRECT_ORIGIN = 'https://shipfox-redirect.invalid';
 
-// Returns the input string only if it is a same-origin internal path safe to
-// navigate to after authentication. We decode before checking so percent-encoded
-// variants like `/%61uth/login` cannot bypass the `/auth/*` rejection.
+// Resolves and canonicalizes an internal path before returning it, so browser URL
+// parsing cannot turn a seemingly safe path into an external or auth route.
 export function sanitizeRedirectPath(value: unknown): string | undefined {
-  if (typeof value !== 'string') return undefined;
+  if (typeof value !== 'string' || !value.startsWith('/')) return undefined;
   let decoded: string;
   try {
     decoded = decodeURIComponent(value);
   } catch {
     return undefined;
   }
-  if (!decoded.startsWith('/')) return undefined;
-  if (decoded.startsWith('//')) return undefined;
-  // Strip search/hash before the /auth check so /auth?token=x and /auth#x
-  // cannot bypass the prefix match.
-  const pathOnly = decoded.split(SEARCH_OR_HASH_RE, 1)[0] ?? decoded;
-  if (pathOnly === '/auth' || pathOnly.startsWith('/auth/')) return undefined;
-  return value;
+  let target: URL;
+  try {
+    target = new URL(decoded, REDIRECT_ORIGIN);
+  } catch {
+    return undefined;
+  }
+  if (target.origin !== REDIRECT_ORIGIN) return undefined;
+  if (target.pathname === '/auth' || target.pathname.startsWith('/auth/')) return undefined;
+  return `${target.pathname}${target.search}${target.hash}`;
 }

package/src/continuation.test.ts

@@ -0,0 +1,15 @@
+import {
+  AuthActions,
+  AuthShell,
+  EmailCodeVerification,
+  parseRedirectContext,
+} from '@shipfox/client-auth/continuation';
+
+describe('client-auth continuation exports', () => {
+  test('publishes every continuation primitive through its public subpath', () => {
+    expect(AuthActions).toBeTypeOf('function');
+    expect(AuthShell).toBeTypeOf('function');
+    expect(EmailCodeVerification).toBeTypeOf('function');
+    expect(parseRedirectContext).toBeTypeOf('function');
+  });
+});

package/src/continuation.ts

@@ -0,0 +1,6 @@
+export {AuthActions, AuthShell, type AuthShellProps} from '@shipfox/client-shell/runtime';
+export {
+  EmailCodeVerification,
+  type EmailCodeVerificationProps,
+} from './components/email-code-verification.js';
+export {parseRedirectContext, type RedirectContext} from './components/redirect-context.js';

package/src/hooks/api/auth-mapper.test.ts

@@ -0,0 +1,77 @@
+import type {SignupResponseDto} from '@shipfox/api-auth-dto';
+import {toSignupResult} from './auth-mapper.js';
+
+const baseUser: SignupResponseDto['user'] = {
+  id: '11111111-1111-4111-8111-111111111111',
+  email: 'signup@example.com',
+  name: null,
+  email_verified_at: null,
+  status: 'active',
+  created_at: '2026-04-27T00:00:00.000Z',
+  updated_at: '2026-04-27T00:00:00.000Z',
+};
+
+describe('toSignupResult', () => {
+  test('maps only the user when no challenge, membership, or accept error is present', () => {
+    const result = toSignupResult({user: baseUser});
+
+    expect(result).toEqual({user: {id: baseUser.id, email: baseUser.email}});
+  });
+
+  test('maps the user name and email verification when present', () => {
+    const result = toSignupResult({
+      user: {...baseUser, name: 'Ada', email_verified_at: '2026-04-27T00:00:00.000Z'},
+    });
+
+    expect(result.user).toEqual({
+      id: baseUser.id,
+      email: baseUser.email,
+      name: 'Ada',
+      emailVerifiedAt: '2026-04-27T00:00:00.000Z',
+    });
+  });
+
+  test('maps the email challenge into camelCase fields', () => {
+    const result = toSignupResult({
+      user: baseUser,
+      email_challenge: {
+        id: '22222222-2222-4222-8222-222222222222',
+        next_resend_available_at: '2026-04-27T00:01:00.000Z',
+      },
+    });
+
+    expect(result.emailChallenge).toEqual({
+      id: '22222222-2222-4222-8222-222222222222',
+      nextResendAvailableAt: '2026-04-27T00:01:00.000Z',
+    });
+  });
+
+  test('maps the invitation membership into camelCase fields', () => {
+    const result = toSignupResult({
+      user: baseUser,
+      membership: {
+        id: '33333333-3333-4333-8333-333333333333',
+        user_id: baseUser.id,
+        workspace_id: '44444444-4444-4444-8444-444444444444',
+      },
+    });
+
+    expect(result.membership).toEqual({
+      id: '33333333-3333-4333-8333-333333333333',
+      userId: baseUser.id,
+      workspaceId: '44444444-4444-4444-8444-444444444444',
+    });
+  });
+
+  test('maps the invitation accept error as-is', () => {
+    const result = toSignupResult({
+      user: baseUser,
+      accept_error: {code: 'invitation-expired', message: 'This invitation has expired.'},
+    });
+
+    expect(result.acceptError).toEqual({
+      code: 'invitation-expired',
+      message: 'This invitation has expired.',
+    });
+  });
+});

package/src/hooks/api/auth-mapper.ts

@@ -0,0 +1,39 @@
+import type {SignupResponseDto} from '@shipfox/api-auth-dto';
+import {
+  toAuthenticatedSession,
+  toUserIdentity,
+  type UserIdentity,
+} from '@shipfox/client-shell/runtime';
+
+export {toAuthenticatedSession};
+
+export interface SignupResult {
+  user: UserIdentity;
+  emailChallenge?: {id: string; nextResendAvailableAt: string};
+  membership?: {id: string; userId: string; workspaceId: string};
+  acceptError?: {code: string; message: string};
+}
+
+export function toSignupResult(dto: SignupResponseDto): SignupResult {
+  return {
+    user: toUserIdentity(dto.user),
+    ...(dto.email_challenge
+      ? {
+          emailChallenge: {
+            id: dto.email_challenge.id,
+            nextResendAvailableAt: dto.email_challenge.next_resend_available_at,
+          },
+        }
+      : {}),
+    ...(dto.membership
+      ? {
+          membership: {
+            id: dto.membership.id,
+            userId: dto.membership.user_id,
+            workspaceId: dto.membership.workspace_id,
+          },
+        }
+      : {}),
+    ...(dto.accept_error ? {acceptError: dto.accept_error} : {}),
+  };
+}

package/src/hooks/api/login-auth.test.ts

@@ -37,7 +37,7 @@ describe('loginAuth', () => {
     const result = await loginAuth(body);
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;
-    expect(result.token).toBe('access-token');
+    expect(result.accessToken).toBe('access-token');
     expect(request.url).toBe('https://api.example.test/auth/login');
     expect(request.method).toBe('POST');
     expect(requestBody).toEqual(body);

package/src/hooks/api/login-auth.ts

@@ -1,41 +1,22 @@
-import type {LoginBodyDto, LoginResponseDto} from '@shipfox/api-auth-dto';
-import {apiRequest} from '@shipfox/client-api';
-import {useMutation, useQueryClient} from '@tanstack/react-query';
-import {useSetAtom} from 'jotai';
-import {authStateAtom, toAuthenticatedState} from '#state/auth.js';
-import {authRefreshQueryKey} from './refresh-auth.js';
-import {listUserWorkspaces, userWorkspacesQueryKey} from './workspace-auth.js';
+import {type LoginBodyDto, loginResponseSchema} from '@shipfox/api-auth-dto';
+import {checkedApiRequest} from '@shipfox/client-api';
+import {useMutation} from '@tanstack/react-query';
+import {useAuthTransition} from '#state/auth.js';
+import {toAuthenticatedSession} from './auth-mapper.js';
 
 export async function loginAuth(body: LoginBodyDto) {
-  return await apiRequest<LoginResponseDto>('/auth/login', {method: 'POST', body});
+  const response = await checkedApiRequest(loginResponseSchema, '/auth/login', {
+    method: 'POST',
+    body,
+  });
+  return toAuthenticatedSession(response);
 }
 
 export function useLoginAuth() {
-  const queryClient = useQueryClient();
-  const setState = useSetAtom(authStateAtom);
+  const {enterAuthenticated} = useAuthTransition();
 
   return useMutation({
     mutationFn: loginAuth,
-    onSuccess: async (result) => {
-      queryClient.setQueryData(authRefreshQueryKey, result);
-      // Resolve workspaces before flipping auth state to authenticated. A
-      // single atomic setState avoids the intermediate window where the user
-      // appears authenticated with zero workspaces, which sent users with
-      // workspaces straight to `/setup/workspaces/new` after form login.
-      let memberships: Awaited<ReturnType<typeof listUserWorkspaces>>['memberships'] = [];
-      try {
-        const workspaces = await queryClient.fetchQuery({
-          queryKey: userWorkspacesQueryKey,
-          queryFn: () => listUserWorkspaces(result.token),
-          retry: false,
-          staleTime: 0,
-        });
-        memberships = workspaces.memberships;
-        queryClient.setQueryData(userWorkspacesQueryKey, workspaces);
-      } catch {
-        // The user is authenticated even if workspace hydration fails.
-      }
-      setState(toAuthenticatedState(result, memberships));
-    },
+    onSuccess: enterAuthenticated,
   });
 }

package/src/hooks/api/logout-auth.ts

@@ -1,8 +1,6 @@
 import {apiRequest} from '@shipfox/client-api';
-import {useMutation, useQueryClient} from '@tanstack/react-query';
-import {useSetAtom} from 'jotai';
-import {authStateAtom} from '#state/auth.js';
-import {authRefreshQueryKey} from './refresh-auth.js';
+import {useMutation} from '@tanstack/react-query';
+import {useAuthTransition} from '#state/auth.js';
 
 async function logoutAuth() {
   try {
@@ -13,14 +11,10 @@ async function logoutAuth() {
 }
 
 export function useLogoutAuth() {
-  const queryClient = useQueryClient();
-  const setState = useSetAtom(authStateAtom);
+  const {enterGuest} = useAuthTransition();
 
   return useMutation({
     mutationFn: logoutAuth,
-    onSettled: () => {
-      setState({status: 'guest'});
-      queryClient.removeQueries({queryKey: authRefreshQueryKey});
-    },
+    onSettled: enterGuest,
   });
 }

package/src/hooks/api/password-reset-auth.test.ts

@@ -60,7 +60,7 @@ describe('confirmPasswordReset', () => {
     const result = await confirmPasswordReset(body);
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;
-    expect(result.token).toBe('reset-access-token');
+    expect(result.accessToken).toBe('reset-access-token');
     expect(request.url).toBe('https://api.example.test/auth/password-reset/confirm');
     expect(request.method).toBe('POST');
     expect(requestBody).toEqual(body);

package/src/hooks/api/password-reset-auth.ts

@@ -1,24 +1,27 @@
-import type {
-  PasswordResetConfirmBodyDto,
-  PasswordResetConfirmResponseDto,
-  PasswordResetRequestBodyDto,
+import {
+  type PasswordResetConfirmBodyDto,
+  type PasswordResetRequestBodyDto,
+  passwordResetConfirmResponseSchema,
 } from '@shipfox/api-auth-dto';
-import {apiRequest} from '@shipfox/client-api';
-import {useMutation, useQueryClient} from '@tanstack/react-query';
-import {useSetAtom} from 'jotai';
-import {authStateAtom, toAuthenticatedState} from '#state/auth.js';
-import {authRefreshQueryKey} from './refresh-auth.js';
-import {listUserWorkspaces, userWorkspacesQueryKey} from './workspace-auth.js';
+import {apiRequest, checkedApiRequest} from '@shipfox/client-api';
+import {useMutation} from '@tanstack/react-query';
+import {useAuthTransition} from '#state/auth.js';
+import {toAuthenticatedSession} from './auth-mapper.js';
 
 export async function requestPasswordReset(body: PasswordResetRequestBodyDto) {
   await apiRequest<void>('/auth/password-reset', {method: 'POST', body});
 }
 
 export async function confirmPasswordReset(body: PasswordResetConfirmBodyDto) {
-  return await apiRequest<PasswordResetConfirmResponseDto>('/auth/password-reset/confirm', {
-    method: 'POST',
-    body,
-  });
+  const response = await checkedApiRequest(
+    passwordResetConfirmResponseSchema,
+    '/auth/password-reset/confirm',
+    {
+      method: 'POST',
+      body,
+    },
+  );
+  return toAuthenticatedSession(response);
 }
 
 export function useRequestPasswordResetAuth() {
@@ -26,26 +29,10 @@ export function useRequestPasswordResetAuth() {
 }
 
 export function useConfirmPasswordResetAuth() {
-  const queryClient = useQueryClient();
-  const setState = useSetAtom(authStateAtom);
+  const {enterAuthenticated} = useAuthTransition();
 
   return useMutation({
     mutationFn: confirmPasswordReset,
-    onSuccess: async (result) => {
-      setState(toAuthenticatedState(result));
-      queryClient.setQueryData(authRefreshQueryKey, result);
-      try {
-        const workspaces = await queryClient.fetchQuery({
-          queryKey: userWorkspacesQueryKey,
-          queryFn: () => listUserWorkspaces(result.token),
-          retry: false,
-          staleTime: 0,
-        });
-        setState(toAuthenticatedState(result, workspaces.memberships));
-        queryClient.setQueryData(userWorkspacesQueryKey, workspaces);
-      } catch {
-        // The user is authenticated even if workspace hydration fails.
-      }
-    },
+    onSuccess: enterAuthenticated,
   });
 }

package/src/hooks/api/signup-auth.ts

@@ -1,9 +1,14 @@
-import type {SignupBodyDto, SignupResponseDto} from '@shipfox/api-auth-dto';
-import {apiRequest} from '@shipfox/client-api';
+import {type SignupBodyDto, signupResponseSchema} from '@shipfox/api-auth-dto';
+import {checkedApiRequest} from '@shipfox/client-api';
 import {useMutation} from '@tanstack/react-query';
+import {toSignupResult} from './auth-mapper.js';
 
 async function signupAuth(body: SignupBodyDto) {
-  return await apiRequest<SignupResponseDto>('/auth/signup', {method: 'POST', body});
+  const response = await checkedApiRequest(signupResponseSchema, '/auth/signup', {
+    method: 'POST',
+    body,
+  });
+  return toSignupResult(response);
 }
 
 export function useSignupAuth() {

package/src/hooks/api/verify-email-auth.ts

@@ -1,25 +1,28 @@
-import type {
-  VerifyEmailConfirmBodyDto,
-  VerifyEmailConfirmResponseDto,
-  VerifyEmailResendBodyDto,
-  VerifyEmailResendResponseDto,
+import {
+  type VerifyEmailConfirmBodyDto,
+  type VerifyEmailResendBodyDto,
+  verifyEmailConfirmResponseSchema,
+  verifyEmailResendResponseSchema,
 } from '@shipfox/api-auth-dto';
-import {apiRequest} from '@shipfox/client-api';
-import {useMutation, useQueryClient} from '@tanstack/react-query';
-import {useSetAtom} from 'jotai';
-import {authStateAtom, toAuthenticatedState} from '#state/auth.js';
-import {authRefreshQueryKey} from './refresh-auth.js';
-import {listUserWorkspaces, userWorkspacesQueryKey} from './workspace-auth.js';
+import {checkedApiRequest} from '@shipfox/client-api';
+import {useMutation} from '@tanstack/react-query';
+import {useAuthTransition} from '#state/auth.js';
+import {toAuthenticatedSession} from './auth-mapper.js';
 
 async function verifyEmailAuth(body: VerifyEmailConfirmBodyDto) {
-  return await apiRequest<VerifyEmailConfirmResponseDto>('/auth/verify-email/confirm', {
-    method: 'POST',
-    body,
-  });
+  const response = await checkedApiRequest(
+    verifyEmailConfirmResponseSchema,
+    '/auth/verify-email/confirm',
+    {
+      method: 'POST',
+      body,
+    },
+  );
+  return toAuthenticatedSession(response);
 }
 
 async function resendEmailVerificationAuth(body: VerifyEmailResendBodyDto) {
-  return await apiRequest<VerifyEmailResendResponseDto>('/auth/verify-email/resend', {
+  return await checkedApiRequest(verifyEmailResendResponseSchema, '/auth/verify-email/resend', {
     method: 'POST',
     body,
   });
@@ -30,26 +33,10 @@ export function useResendEmailVerificationAuth() {
 }
 
 export function useVerifyEmailAuth() {
-  const queryClient = useQueryClient();
-  const setState = useSetAtom(authStateAtom);
+  const {enterAuthenticated} = useAuthTransition();
 
   return useMutation({
     mutationFn: verifyEmailAuth,
-    onSuccess: async (result) => {
-      setState(toAuthenticatedState(result));
-      queryClient.setQueryData(authRefreshQueryKey, result);
-      try {
-        const workspaces = await queryClient.fetchQuery({
-          queryKey: userWorkspacesQueryKey,
-          queryFn: () => listUserWorkspaces(result.token),
-          retry: false,
-          staleTime: 0,
-        });
-        setState(toAuthenticatedState(result, workspaces.memberships));
-        queryClient.setQueryData(userWorkspacesQueryKey, workspaces);
-      } catch {
-        // The user is authenticated even if workspace hydration fails.
-      }
-    },
+    onSuccess: enterAuthenticated,
   });
 }

package/src/hooks/api/workspace-auth.ts

@@ -1,11 +1,16 @@
-import type {CreateWorkspaceBodyDto, WorkspaceResponseDto} from '@shipfox/api-workspaces-dto';
-import {apiRequest} from '@shipfox/client-api';
+import {type CreateWorkspaceBodyDto, workspaceResponseSchema} from '@shipfox/api-workspaces-dto';
+import {checkedApiRequest} from '@shipfox/client-api';
 import {listUserWorkspaces, userWorkspacesQueryKey} from '@shipfox/client-shell/runtime';
 import {useMutation} from '@tanstack/react-query';
 import {useRefreshAuth} from './refresh-auth.js';
+import {toWorkspace} from './workspace-mapper.js';
 
 export async function createWorkspace(body: CreateWorkspaceBodyDto) {
-  return await apiRequest<WorkspaceResponseDto>('/workspaces', {method: 'POST', body});
+  const response = await checkedApiRequest(workspaceResponseSchema, '/workspaces', {
+    method: 'POST',
+    body,
+  });
+  return toWorkspace(response);
 }
 
 export {listUserWorkspaces, userWorkspacesQueryKey};

package/src/hooks/api/workspace-mapper.test.ts

@@ -0,0 +1,21 @@
+import type {WorkspaceResponseDto} from '@shipfox/api-workspaces-dto';
+import {toWorkspace} from './workspace-mapper.js';
+
+describe('toWorkspace', () => {
+  test.each([
+    'active',
+    'suspended',
+    'deleted',
+  ] as const)('maps a %s workspace to its domain shape', (status) => {
+    const dto: WorkspaceResponseDto = {
+      id: '11111111-1111-4111-8111-111111111111',
+      name: 'Acme',
+      status,
+      settings: {},
+      created_at: '2026-04-27T00:00:00.000Z',
+      updated_at: '2026-04-27T00:00:00.000Z',
+    };
+
+    expect(toWorkspace(dto)).toEqual({id: dto.id, name: dto.name, status});
+  });
+});

package/src/hooks/api/workspace-mapper.ts

@@ -0,0 +1,11 @@
+import type {WorkspaceResponseDto} from '@shipfox/api-workspaces-dto';
+
+export interface Workspace {
+  id: string;
+  name: string;
+  status: 'active' | 'suspended' | 'deleted';
+}
+
+export function toWorkspace(dto: WorkspaceResponseDto): Workspace {
+  return {id: dto.id, name: dto.name, status: dto.status};
+}

package/src/index.ts

@@ -1,6 +1,5 @@
 export * from './components/auth-guard.js';
 export * from './components/auth-provider.js';
-export * from './components/auth-shell.js';
 export {WorkspaceCrumb, type WorkspaceCrumbProps} from './components/workspace-crumb.js';
 export {WorkspaceSwitcher, type WorkspaceSwitcherProps} from './components/workspace-switcher.js';
 export * from './hooks/index.js';