@shipfox/api-auth 2.0.0

package/src/presentation/routes/registration/signup.test.ts

@@ -0,0 +1,284 @@
+import {AUTH_EMAIL_VERIFICATION_SEND_REQUESTED} from '@shipfox/api-auth-dto';
+import type {FastifyInstance} from 'fastify';
+import {verifyUserToken} from '#core/jwt.js';
+import {
+  acceptWorkspaceInvitationMock,
+  capturedMail,
+  createAuthTestApp,
+  getSetCookie,
+  latestEmailLinkTo,
+  listMembershipsByUserMock,
+  outboxEventsTo,
+  peekInvitationByRawTokenMock,
+  ROUTE_TEST_SECRET,
+  resetCapturedMail,
+  signup,
+  uniqueEmail,
+} from '#test/routes.js';
+
+describe('POST /auth/signup', () => {
+  let app: FastifyInstance;
+  const password = 'correct horse battery staple';
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns 201 with a pending user and sends verification mail', async () => {
+    const email = uniqueEmail('signup');
+
+    const res = await signup(app, {
+      email: email.toUpperCase(),
+      password,
+      name: '  New User  ',
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().user.email).toBe(email);
+    expect(res.json().user.name).toBe('New User');
+    expect(res.json().user.email_verified_at).toBeNull();
+    expect(await latestEmailLinkTo(email, AUTH_EMAIL_VERIFICATION_SEND_REQUESTED)).toContain(
+      '/auth/verify-email?token=',
+    );
+    expect(capturedMail()).toHaveLength(0);
+  });
+
+  test.each([
+    ['missing', undefined],
+    ['blank after trimming', '   '],
+    ['with control characters', 'New\nUser'],
+    ['with format characters', 'New\u202eUser'],
+  ])('rejects a %s display name', async (_case, name) => {
+    const email = uniqueEmail('signup-name-invalid');
+    const payload: {email: string; password: string; name?: string} = {email, password};
+    if (name !== undefined) {
+      payload.name = name;
+    }
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/signup',
+      payload,
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  test('transforms duplicate email into 409', async () => {
+    const email = uniqueEmail('duplicate');
+    await signup(app, {email, password});
+
+    const res = await signup(app, {email, password});
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('email-taken');
+  });
+
+  test('accepts a valid invitation during signup and skips verification email', async () => {
+    const email = uniqueEmail('signup-invite');
+    const invitationToken = `invite-${crypto.randomUUID()}`;
+    const workspaceId = crypto.randomUUID();
+    const membershipId = crypto.randomUUID();
+    peekInvitationByRawTokenMock.mockResolvedValueOnce({
+      id: crypto.randomUUID(),
+      workspaceId,
+      email,
+      hashedToken: 'hashed',
+      expiresAt: new Date(Date.now() + 86_400_000),
+      acceptedAt: null,
+      acceptedByUserId: null,
+      invitedByUserId: crypto.randomUUID(),
+      invitedByDisplay: 'owner@example.com',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    acceptWorkspaceInvitationMock.mockImplementationOnce(async (params) => ({
+      invitation: {
+        id: crypto.randomUUID(),
+        workspaceId,
+        email,
+        hashedToken: 'hashed',
+        expiresAt: new Date(Date.now() + 86_400_000),
+        acceptedAt: new Date(),
+        acceptedByUserId: params.userId,
+        invitedByUserId: crypto.randomUUID(),
+        invitedByDisplay: 'owner@example.com',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      membership: {
+        id: membershipId,
+        userId: params.userId,
+        userEmail: email,
+        userName: 'Invitee',
+        workspaceId,
+        workspaceName: 'Acme',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      alreadyMember: false,
+    }));
+    listMembershipsByUserMock.mockResolvedValueOnce([
+      {
+        id: membershipId,
+        userId: crypto.randomUUID(),
+        userEmail: email,
+        userName: 'Invitee',
+        workspaceId,
+        workspaceName: 'Acme',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    ]);
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/signup',
+      payload: {
+        email,
+        password,
+        name: 'Invitee',
+        invitation_token: invitationToken,
+      },
+    });
+    const body = res.json();
+    const claims = await verifyUserToken({token: body.token, secret: ROUTE_TEST_SECRET});
+
+    expect(res.statusCode).toBe(201);
+    expect(getSetCookie(res)).toContain('shipfox_refresh_token=');
+    expect(body.user.email).toBe(email);
+    expect(body.user.email_verified_at).toEqual(expect.any(String));
+    expect(body.membership).toEqual({
+      id: membershipId,
+      user_id: body.user.id,
+      workspace_id: workspaceId,
+    });
+    expect(body.accept_error).toBeUndefined();
+    expect(claims.memberships).toEqual([{workspaceId, role: 'admin'}]);
+    expect(await outboxEventsTo(email, AUTH_EMAIL_VERIFICATION_SEND_REQUESTED)).toHaveLength(0);
+    expect(capturedMail()).toHaveLength(0);
+  });
+
+  test('returns partial success when invitation acceptance fails after user creation', async () => {
+    const email = uniqueEmail('signup-invite-partial');
+    const workspaceId = crypto.randomUUID();
+    peekInvitationByRawTokenMock.mockResolvedValueOnce({
+      id: crypto.randomUUID(),
+      workspaceId,
+      email,
+      hashedToken: 'hashed',
+      expiresAt: new Date(Date.now() + 86_400_000),
+      acceptedAt: null,
+      acceptedByUserId: null,
+      invitedByUserId: crypto.randomUUID(),
+      invitedByDisplay: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    acceptWorkspaceInvitationMock.mockRejectedValueOnce(new Error('accept unavailable'));
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/signup',
+      payload: {
+        email,
+        password,
+        name: 'Invitee',
+        invitation_token: `invite-${crypto.randomUUID()}`,
+      },
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().membership).toBeNull();
+    expect(res.json().accept_error).toEqual(
+      expect.objectContaining({
+        code: 'AcceptFailed',
+      }),
+    );
+    expect(res.json().token).toEqual(expect.any(String));
+  });
+
+  test.each([
+    {
+      name: 'invalid token',
+      invitation: undefined,
+      expectedStatus: 410,
+      expectedCode: 'invitation-token-invalid',
+    },
+    {
+      name: 'already accepted token',
+      invitation: {
+        acceptedAt: new Date(),
+        expiresAt: new Date(Date.now() + 86_400_000),
+        email: uniqueEmail('signup-invite-used'),
+      },
+      expectedStatus: 410,
+      expectedCode: 'invitation-token-used',
+    },
+    {
+      name: 'expired token',
+      invitation: {
+        acceptedAt: null,
+        expiresAt: new Date(Date.now() - 60_000),
+        email: uniqueEmail('signup-invite-expired'),
+      },
+      expectedStatus: 410,
+      expectedCode: 'invitation-token-expired',
+    },
+    {
+      name: 'email mismatch',
+      invitation: {
+        acceptedAt: null,
+        expiresAt: new Date(Date.now() + 86_400_000),
+        email: uniqueEmail('signup-invite-other'),
+      },
+      expectedStatus: 403,
+      expectedCode: 'invitation-email-mismatch',
+    },
+  ])('rejects signup with invitation for $name', async ({
+    invitation,
+    expectedStatus,
+    expectedCode,
+  }) => {
+    const email = uniqueEmail('signup-invite-error');
+    if (invitation === undefined) {
+      peekInvitationByRawTokenMock.mockResolvedValueOnce(undefined);
+    } else {
+      peekInvitationByRawTokenMock.mockResolvedValueOnce({
+        id: crypto.randomUUID(),
+        workspaceId: crypto.randomUUID(),
+        email: invitation.email,
+        hashedToken: 'hashed',
+        expiresAt: invitation.expiresAt,
+        acceptedAt: invitation.acceptedAt,
+        acceptedByUserId: null,
+        invitedByUserId: crypto.randomUUID(),
+        invitedByDisplay: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      });
+    }
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/signup',
+      payload: {
+        email,
+        password,
+        name: 'Invitee',
+        invitation_token: `invite-${crypto.randomUUID()}`,
+      },
+    });
+
+    expect(res.statusCode).toBe(expectedStatus);
+    expect(res.json().code).toBe(expectedCode);
+    expect(acceptWorkspaceInvitationMock).not.toHaveBeenCalled();
+  });
+});

package/src/presentation/routes/registration/signup.ts

@@ -0,0 +1,81 @@
+import {signupBodySchema, signupResponseSchema} from '@shipfox/api-auth-dto';
+import {
+  InvitationEmailMismatchError,
+  TokenAlreadyUsedError,
+  TokenExpiredError,
+  TokenInvalidError as WorkspacesTokenInvalidError,
+} from '@shipfox/api-workspaces';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {signup, signupWithInvitation} from '#core/auth.js';
+import {EmailTakenError} from '#core/errors.js';
+import {setRefreshTokenCookie} from '#presentation/auth/refresh-cookie.js';
+import {toUserDto} from '#presentation/dto/user.js';
+
+export const signupRoute = defineRoute({
+  method: 'POST',
+  path: '/signup',
+  description:
+    'Create a user account. Sends a verification email unless an invitation token is supplied.',
+  schema: {
+    body: signupBodySchema,
+    response: {
+      201: signupResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof EmailTakenError) {
+      throw new ClientError('Email already registered', 'email-taken', {status: 409});
+    }
+    if (error instanceof WorkspacesTokenInvalidError) {
+      throw new ClientError('Invitation token is invalid', 'invitation-token-invalid', {
+        status: 410,
+      });
+    }
+    if (error instanceof TokenAlreadyUsedError) {
+      throw new ClientError('Invitation has already been accepted', 'invitation-token-used', {
+        status: 410,
+      });
+    }
+    if (error instanceof TokenExpiredError) {
+      throw new ClientError('Invitation has expired', 'invitation-token-expired', {status: 410});
+    }
+    if (error instanceof InvitationEmailMismatchError) {
+      throw new ClientError(
+        'Signup email does not match the invitation',
+        'invitation-email-mismatch',
+        {status: 403},
+      );
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const {email, password, name, invitation_token} = request.body;
+
+    if (invitation_token === undefined) {
+      const user = await signup({email, password, name});
+      reply.code(201);
+      return {user: toUserDto(user)};
+    }
+
+    const result = await signupWithInvitation({
+      email,
+      password,
+      name,
+      invitationToken: invitation_token,
+    });
+    setRefreshTokenCookie(reply, result.refreshToken);
+    reply.code(201);
+    return {
+      user: toUserDto(result.user),
+      token: result.token,
+      membership: result.membership
+        ? {
+            id: result.membership.id,
+            user_id: result.membership.userId,
+            workspace_id: result.membership.workspaceId,
+          }
+        : null,
+      ...(result.acceptError ? {accept_error: result.acceptError} : {}),
+    };
+  },
+});

package/src/presentation/routes/session/login.test.ts

@@ -0,0 +1,77 @@
+import type {FastifyInstance} from 'fastify';
+import {
+  createAuthTestApp,
+  listMembershipsByUserMock,
+  login,
+  resetCapturedMail,
+  signup,
+  uniqueEmail,
+  verifyEmail,
+} from '#test/routes.js';
+
+describe('POST /auth/login', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns 200 with a token and user after verification', async () => {
+    const email = uniqueEmail('login');
+    const password = 'correct horse battery staple';
+    await signup(app, {email, password});
+    await verifyEmail(app, email);
+
+    const res = await login(app, {email: email.toUpperCase(), password});
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().token).toBeDefined();
+    expect(res.json().user.email).toBe(email);
+    expect(res.headers['set-cookie']).toContain('shipfox_refresh_token=');
+    expect(res.headers['set-cookie']).toContain('HttpOnly');
+    expect(res.headers['set-cookie']).toContain('Secure');
+    expect(res.headers['set-cookie']).toContain('SameSite=Lax');
+    expect(res.headers['set-cookie']).toContain('Path=/auth');
+  });
+
+  test('transforms invalid credentials into 401', async () => {
+    const email = uniqueEmail('bad-login');
+
+    const res = await login(app, {email, password: 'wrong password'});
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().code).toBe('invalid-credentials');
+  });
+
+  test('transforms unverified email into 403', async () => {
+    const email = uniqueEmail('unverified-login');
+    const password = 'correct horse battery staple';
+    await signup(app, {email, password});
+
+    const res = await login(app, {email, password});
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('email-not-verified');
+  });
+
+  test('transforms membership dependency outages into 503', async () => {
+    const email = uniqueEmail('login-workspaces-down');
+    const password = 'correct horse battery staple';
+    await signup(app, {email, password});
+    await verifyEmail(app, email);
+    listMembershipsByUserMock.mockRejectedValueOnce(new Error('workspaces DB down'));
+
+    const res = await login(app, {email, password});
+
+    expect(res.statusCode).toBe(503);
+    expect(res.json().code).toBe('auth-dependency-unavailable');
+  });
+});

package/src/presentation/routes/session/login.ts

@@ -0,0 +1,50 @@
+import {loginBodySchema, loginResponseSchema} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {login} from '#core/auth.js';
+import {
+  AuthDependencyUnavailableError,
+  EmailNotVerifiedError,
+  InvalidCredentialsError,
+} from '#core/errors.js';
+import {setRefreshTokenCookie} from '#presentation/auth/refresh-cookie.js';
+import {toAuthSessionDto} from '#presentation/dto/user.js';
+import {createAuthRateLimitPreHandler} from '#presentation/routes/rate-limit.js';
+
+export const loginRoute = defineRoute({
+  method: 'POST',
+  path: '/login',
+  description: 'Sign in with an email address and password.',
+  schema: {
+    body: loginBodySchema,
+    response: {
+      200: loginResponseSchema,
+    },
+  },
+  preHandler: createAuthRateLimitPreHandler('login'),
+  errorHandler: (error) => {
+    if (error instanceof InvalidCredentialsError) {
+      throw new ClientError('Invalid credentials', 'invalid-credentials', {status: 401});
+    }
+    if (error instanceof EmailNotVerifiedError) {
+      throw new ClientError('Email not verified', 'email-not-verified', {status: 403});
+    }
+    if (error instanceof AuthDependencyUnavailableError) {
+      throw new ClientError(
+        'Authentication dependency unavailable',
+        'auth-dependency-unavailable',
+        {
+          status: 503,
+        },
+      );
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const {email, password} = request.body;
+
+    const result = await login({email, password});
+    setRefreshTokenCookie(reply, result.refreshToken);
+
+    return toAuthSessionDto(result);
+  },
+});

package/src/presentation/routes/session/logout.test.ts

@@ -0,0 +1,55 @@
+import type {FastifyInstance} from 'fastify';
+import {
+  cookieHeader,
+  createAuthTestApp,
+  resetCapturedMail,
+  signupVerifyLogin,
+} from '#test/routes.js';
+
+describe('POST /auth/logout', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns 204 and revokes the current refresh session', async () => {
+    const account = await signupVerifyLogin(app, 'logout');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/logout',
+      headers: {cookie: cookieHeader(account.refreshCookie)},
+      payload: {},
+    });
+    const refresh = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(account.refreshCookie)},
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(204);
+    expect(res.headers['set-cookie']).toContain('shipfox_refresh_token=;');
+    expect(refresh.statusCode).toBe(401);
+  });
+
+  test('returns 204 when the refresh cookie is missing', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/logout',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(204);
+    expect(res.headers['set-cookie']).toContain('shipfox_refresh_token=;');
+  });
+});

package/src/presentation/routes/session/logout.ts

@@ -0,0 +1,23 @@
+import {logoutBodySchema} from '@shipfox/api-auth-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {logout} from '#core/auth.js';
+import {clearRefreshTokenCookie, getRefreshTokenCookie} from '#presentation/auth/refresh-cookie.js';
+
+export const logoutRoute = defineRoute({
+  method: 'POST',
+  path: '/logout',
+  description: 'Sign out of the current session.',
+  schema: {
+    body: logoutBodySchema,
+    response: {
+      204: z.void(),
+    },
+  },
+  handler: async (request, reply) => {
+    await logout({refreshToken: getRefreshTokenCookie(request)});
+    clearRefreshTokenCookie(reply);
+
+    reply.code(204);
+  },
+});

package/src/presentation/routes/session/me.test.ts

@@ -0,0 +1,56 @@
+import type {FastifyInstance} from 'fastify';
+import {signUserToken} from '#core/jwt.js';
+import {
+  createAuthTestApp,
+  ROUTE_TEST_SECRET,
+  resetCapturedMail,
+  signupVerifyLogin,
+} from '#test/routes.js';
+
+describe('GET /auth/me', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns the signed-in user', async () => {
+    const account = await signupVerifyLogin(app, 'me');
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/auth/me',
+      headers: {authorization: `Bearer ${account.token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().user.email).toBe(account.email);
+  });
+
+  test('transforms a token for a missing user into 404', async () => {
+    const token = await signUserToken({
+      userId: crypto.randomUUID(),
+      email: 'missing@example.com',
+      memberships: [],
+      secret: ROUTE_TEST_SECRET,
+      expiresIn: '15m',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/auth/me',
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+});

package/src/presentation/routes/session/me.ts

@@ -0,0 +1,35 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import {meResponseSchema} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {getCurrentUser} from '#core/auth.js';
+import {UserNotFoundError} from '#core/errors.js';
+import {getClientContext} from '#presentation/auth/jwt-auth.js';
+import {toUserDto} from '#presentation/dto/user.js';
+
+export const meRoute = defineRoute({
+  method: 'GET',
+  path: '/me',
+  description: 'Get the signed-in user.',
+  auth: AUTH_USER,
+  schema: {
+    response: {
+      200: meResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof UserNotFoundError) {
+      throw new ClientError('User not found', 'not-found', {status: 404});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const client = getClientContext(request);
+    if (!client) {
+      throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+    }
+
+    const result = await getCurrentUser({userId: client.userId});
+
+    return {user: toUserDto(result.user)};
+  },
+});