@shipfox/api-auth 2.0.0

package/src/presentation/auth/runner-session-auth.ts

@@ -0,0 +1,13 @@
+import {AUTH_RUNNER_SESSION, setRunnerSessionContext} from '@shipfox/api-auth-context';
+import type {AuthMethod} from '@shipfox/node-fastify';
+import {verifyRunnerSessionToken} from '#core/runner-session-token.js';
+import {createBearerTokenAuthMethod} from './bearer-token-auth.js';
+
+export function createRunnerSessionAuthMethod(): AuthMethod {
+  return createBearerTokenAuthMethod({
+    name: AUTH_RUNNER_SESSION,
+    verifyToken: verifyRunnerSessionToken,
+    invalidTokenError: {message: 'Invalid or expired runner session token', code: 'unauthorized'},
+    setContext: setRunnerSessionContext,
+  });
+}

package/src/presentation/dto/user.ts

@@ -0,0 +1,21 @@
+import type {LoginResponseDto, UserDto} from '@shipfox/api-auth-dto';
+import type {User} from '#core/entities/user.js';
+
+export function toUserDto(user: User): UserDto {
+  return {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    email_verified_at: user.emailVerifiedAt ? user.emailVerifiedAt.toISOString() : null,
+    status: user.status,
+    created_at: user.createdAt.toISOString(),
+    updated_at: user.updatedAt.toISOString(),
+  };
+}
+
+export function toAuthSessionDto(result: {token: string; user: User}): LoginResponseDto {
+  return {
+    token: result.token,
+    user: toUserDto(result.user),
+  };
+}

package/src/presentation/e2eRoutes/create-session.ts

@@ -0,0 +1,39 @@
+import {e2eCreateSessionBodySchema, e2eCreateSessionResponseSchema} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {createSessionForUser} from '#core/auth.js';
+import {EmailNotVerifiedError, InvalidCredentialsError, UserNotFoundError} from '#core/errors.js';
+import {setRefreshTokenCookie} from '#presentation/auth/refresh-cookie.js';
+import {toAuthSessionDto} from '#presentation/dto/user.js';
+
+export const createE2eSessionRoute = defineRoute({
+  method: 'POST',
+  path: '/sessions',
+  description: 'Create an authenticated browser session for E2E tests.',
+  schema: {
+    body: e2eCreateSessionBodySchema,
+    response: {
+      200: e2eCreateSessionResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof UserNotFoundError) {
+      throw new ClientError('User not found', 'user-not-found', {status: 404});
+    }
+    if (error instanceof EmailNotVerifiedError) {
+      throw new ClientError('Email not verified', 'email-not-verified', {status: 403});
+    }
+    if (error instanceof InvalidCredentialsError) {
+      throw new ClientError('User is not active', 'user-inactive', {status: 409});
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const result = await createSessionForUser({
+      ...(request.body.user_id ? {userId: request.body.user_id} : {}),
+      ...(request.body.email ? {email: request.body.email} : {}),
+    });
+
+    setRefreshTokenCookie(reply, result.refreshToken);
+    return toAuthSessionDto(result);
+  },
+});

package/src/presentation/e2eRoutes/create-user.ts

@@ -0,0 +1,38 @@
+import {e2eCreateUserBodySchema, e2eCreateUserResponseSchema} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {createUser} from '#core/auth.js';
+import {EmailTakenError} from '#core/errors.js';
+import {toUserDto} from '#presentation/dto/user.js';
+
+export const createE2eUserRoute = defineRoute({
+  method: 'POST',
+  path: '/users',
+  description: 'Create a user for E2E tests.',
+  schema: {
+    body: e2eCreateUserBodySchema,
+    response: {
+      201: e2eCreateUserResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof EmailTakenError) {
+      throw new ClientError('Email already registered', 'email-taken', {status: 409});
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const user = await createUser({
+      email: request.body.email,
+      password: request.body.password,
+      verified: request.body.verified,
+      ...(request.body.name ? {name: request.body.name} : {}),
+    });
+
+    reply.code(201);
+    return {
+      user: toUserDto(user),
+      email: user.email,
+      password: request.body.password,
+    };
+  },
+});

package/src/presentation/e2eRoutes/index.test.ts

@@ -0,0 +1,102 @@
+import {createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance} from 'fastify';
+import {authE2eRoutes} from './index.js';
+
+vi.mock('@shipfox/api-workspaces', () => ({
+  listMembershipsByUser: vi.fn(() => Promise.resolve([])),
+}));
+
+describe('auth E2E routes', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createApp({
+      routes: [authE2eRoutes],
+      swagger: false,
+    });
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('creates a verified user from explicit credentials', async () => {
+    const password = 'correct horse battery staple';
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/users',
+      payload: {email: `user-${crypto.randomUUID()}@example.test`, password, verified: true},
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().email).toBe(res.json().user.email);
+    expect(res.json().password).toBe(password);
+    expect(res.json().user.email_verified_at).not.toBeNull();
+  });
+
+  test('rejects missing credentials', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/users',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  test('transforms duplicate email into 409', async () => {
+    const email = `duplicate-${crypto.randomUUID()}@example.test`;
+    await app.inject({
+      method: 'POST',
+      url: '/auth/users',
+      payload: {email, password: 'correct horse battery staple', verified: true},
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/users',
+      payload: {email, password: 'correct horse battery staple', verified: true},
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('email-taken');
+  });
+
+  test('creates a browser session for an E2E-created user', async () => {
+    const userRes = await app.inject({
+      method: 'POST',
+      url: '/auth/users',
+      payload: {
+        email: `session-${crypto.randomUUID()}@example.test`,
+        password: 'correct horse battery staple',
+        verified: true,
+      },
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/sessions',
+      payload: {user_id: userRes.json().user.id},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().user.id).toBe(userRes.json().user.id);
+    expect(res.json().token).toBeDefined();
+    expect(res.headers['set-cookie']).toContain('shipfox_refresh_token=');
+  });
+
+  test('creates an unverified user', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/users',
+      payload: {
+        email: `unverified-${crypto.randomUUID()}@example.test`,
+        password: 'correct horse battery staple',
+        verified: false,
+      },
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().user.email_verified_at).toBeNull();
+  });
+});

package/src/presentation/e2eRoutes/index.ts

@@ -0,0 +1,10 @@
+import cookie from '@fastify/cookie';
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {createE2eSessionRoute} from './create-session.js';
+import {createE2eUserRoute} from './create-user.js';
+
+export const authE2eRoutes: RouteGroup = {
+  prefix: '/auth',
+  plugins: [cookie],
+  routes: [createE2eUserRoute, createE2eSessionRoute],
+};

package/src/presentation/routes/email-verification/verify-email-confirm.test.ts

@@ -0,0 +1,66 @@
+import {AUTH_EMAIL_VERIFICATION_SEND_REQUESTED} from '@shipfox/api-auth-dto';
+import type {FastifyInstance} from 'fastify';
+import {
+  cookieHeader,
+  createAuthTestApp,
+  extractToken,
+  getSetCookie,
+  latestEmailLinkTo,
+  resetCapturedMail,
+  signup,
+  uniqueEmail,
+} from '#test/routes.js';
+
+describe('POST /auth/verify-email/confirm', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('verifies a user email with a valid token and starts a session', async () => {
+    const email = uniqueEmail('verify-confirm');
+    const password = 'correct horse battery staple';
+    await signup(app, {email, password});
+    const token = extractToken(
+      await latestEmailLinkTo(email, AUTH_EMAIL_VERIFICATION_SEND_REQUESTED),
+    );
+
+    const confirm = await app.inject({
+      method: 'POST',
+      url: '/auth/verify-email/confirm',
+      payload: {token},
+    });
+    const refreshCookie = getSetCookie(confirm);
+    const refresh = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(refreshCookie)},
+    });
+
+    expect(confirm.statusCode).toBe(200);
+    expect(confirm.json().token).toEqual(expect.any(String));
+    expect(confirm.json().user.email).toBe(email);
+    expect(refreshCookie).toContain('shipfox_refresh_token=');
+    expect(refresh.statusCode).toBe(200);
+  });
+
+  test('transforms invalid token into 410', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/verify-email/confirm',
+      payload: {token: 'bad-token'},
+    });
+
+    expect(res.statusCode).toBe(410);
+    expect(res.json().code).toBe('token-invalid');
+  });
+});

package/src/presentation/routes/email-verification/verify-email-confirm.ts

@@ -0,0 +1,37 @@
+import {
+  verifyEmailConfirmBodySchema,
+  verifyEmailConfirmResponseSchema,
+} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {confirmEmailVerification} from '#core/auth.js';
+import {TokenInvalidError} from '#core/errors.js';
+import {setRefreshTokenCookie} from '#presentation/auth/refresh-cookie.js';
+import {toAuthSessionDto} from '#presentation/dto/user.js';
+
+export const verifyEmailConfirmRoute = defineRoute({
+  method: 'POST',
+  path: '/verify-email/confirm',
+  description: 'Verify a user email address with the link sent by email.',
+  schema: {
+    body: verifyEmailConfirmBodySchema,
+    response: {
+      200: verifyEmailConfirmResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof TokenInvalidError) {
+      throw new ClientError('Verification token is invalid or expired', 'token-invalid', {
+        status: 410,
+      });
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const {token} = request.body;
+
+    const result = await confirmEmailVerification({token});
+    setRefreshTokenCookie(reply, result.refreshToken);
+
+    return toAuthSessionDto(result);
+  },
+});

package/src/presentation/routes/email-verification/verify-email-resend.test.ts

@@ -0,0 +1,100 @@
+import {
+  AUTH_EMAIL_VERIFICATION_SEND_REQUESTED,
+  EMAIL_VERIFICATION_RESEND_COOLDOWN_SECONDS,
+} from '@shipfox/api-auth-dto';
+import {eq} from 'drizzle-orm';
+import type {FastifyInstance} from 'fastify';
+import {db} from '#db/db.js';
+import {emailVerifications} from '#db/schema/email-verifications.js';
+import {
+  createAuthTestApp,
+  outboxEventsTo,
+  resetCapturedMail,
+  signup,
+  uniqueEmail,
+  verifyEmail,
+} from '#test/routes.js';
+
+describe('POST /auth/verify-email/resend', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns 200 without sending during cooldown for an unverified account', async () => {
+    const email = uniqueEmail('verify-resend');
+    await signup(app, {email, password: 'correct horse battery staple'});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/verify-email/resend',
+      payload: {email: email.toUpperCase()},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().next_resend_available_at).toEqual(expect.any(String));
+    expect(await outboxEventsTo(email, AUTH_EMAIL_VERIFICATION_SEND_REQUESTED)).toHaveLength(1);
+  });
+
+  test('returns 200 and sends a new token after cooldown', async () => {
+    const email = uniqueEmail('verify-resend-ready');
+    const signupRes = await signup(app, {email, password: 'correct horse battery staple'});
+    const staleCreatedAt = new Date(
+      Date.now() - (EMAIL_VERIFICATION_RESEND_COOLDOWN_SECONDS + 1) * 1000,
+    );
+    await db()
+      .update(emailVerifications)
+      .set({createdAt: staleCreatedAt})
+      .where(eq(emailVerifications.userId, signupRes.json().user.id));
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/verify-email/resend',
+      payload: {email},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().next_resend_available_at).toEqual(expect.any(String));
+    expect(await outboxEventsTo(email, AUTH_EMAIL_VERIFICATION_SEND_REQUESTED)).toHaveLength(2);
+  });
+
+  test('returns 200 without sending mail for a verified account', async () => {
+    const email = uniqueEmail('verify-resend-verified');
+    await signup(app, {email, password: 'correct horse battery staple'});
+    await verifyEmail(app, email);
+    resetCapturedMail();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/verify-email/resend',
+      payload: {email},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().next_resend_available_at).toEqual(expect.any(String));
+    expect(await outboxEventsTo(email, AUTH_EMAIL_VERIFICATION_SEND_REQUESTED)).toHaveLength(1);
+  });
+
+  test('returns the same response shape for a missing account', async () => {
+    const email = uniqueEmail('verify-resend-missing');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/verify-email/resend',
+      payload: {email},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({next_resend_available_at: expect.any(String)});
+    expect(await outboxEventsTo(email, AUTH_EMAIL_VERIFICATION_SEND_REQUESTED)).toHaveLength(0);
+  });
+});

package/src/presentation/routes/email-verification/verify-email-resend.ts

@@ -0,0 +1,26 @@
+import {verifyEmailResendBodySchema, verifyEmailResendResponseSchema} from '@shipfox/api-auth-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {resendEmailVerification} from '#core/auth.js';
+import {createAuthRateLimitPreHandler} from '#presentation/routes/rate-limit.js';
+
+export const verifyEmailResendRoute = defineRoute({
+  method: 'POST',
+  path: '/verify-email/resend',
+  description: 'Send a new email verification link if the account can be verified.',
+  schema: {
+    body: verifyEmailResendBodySchema,
+    response: {
+      200: verifyEmailResendResponseSchema,
+    },
+  },
+  preHandler: createAuthRateLimitPreHandler('email-send'),
+  handler: async (request, reply) => {
+    const {email} = request.body;
+
+    const result = await resendEmailVerification({email});
+
+    reply.code(200).send({
+      next_resend_available_at: result.nextResendAvailableAt.toISOString(),
+    });
+  },
+});

package/src/presentation/routes/index.ts

@@ -0,0 +1,29 @@
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {authCookiePlugin} from '#presentation/auth/refresh-cookie.js';
+import {verifyEmailConfirmRoute} from './email-verification/verify-email-confirm.js';
+import {verifyEmailResendRoute} from './email-verification/verify-email-resend.js';
+import {changePasswordRoute} from './password/change-password.js';
+import {passwordResetConfirmRoute} from './password/password-reset-confirm.js';
+import {passwordResetRequestRoute} from './password/password-reset-request.js';
+import {signupRoute} from './registration/signup.js';
+import {loginRoute} from './session/login.js';
+import {logoutRoute} from './session/logout.js';
+import {meRoute} from './session/me.js';
+import {refreshRoute} from './session/refresh.js';
+
+export const authRoutes: RouteGroup = {
+  prefix: '/auth',
+  plugins: [authCookiePlugin],
+  routes: [
+    signupRoute,
+    verifyEmailConfirmRoute,
+    verifyEmailResendRoute,
+    loginRoute,
+    refreshRoute,
+    logoutRoute,
+    meRoute,
+    changePasswordRoute,
+    passwordResetRequestRoute,
+    passwordResetConfirmRoute,
+  ],
+};

package/src/presentation/routes/password/change-password.test.ts

@@ -0,0 +1,106 @@
+import type {FastifyInstance} from 'fastify';
+import {signUserToken} from '#core/jwt.js';
+import {verifyPassword} from '#core/password.js';
+import {findUserByEmail} from '#db/users.js';
+import {
+  cookieHeader,
+  createAuthTestApp,
+  createVerifiedSession,
+  ROUTE_TEST_SECRET,
+  resetCapturedMail,
+  signupVerifyLogin,
+} from '#test/routes.js';
+
+describe('POST /auth/change-password', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('updates credentials and rejects the old password', async () => {
+    const account = await createVerifiedSession('change-password');
+
+    const change = await app.inject({
+      method: 'POST',
+      url: '/auth/change-password',
+      headers: {
+        authorization: `Bearer ${account.token}`,
+        cookie: cookieHeader(account.refreshCookie),
+      },
+      payload: {
+        current_password: account.password,
+        new_password: 'new password is long',
+      },
+    });
+    const updatedUser = await findUserByEmail({email: account.email});
+    const refresh = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(account.refreshCookie)},
+      payload: {},
+    });
+    const oldPasswordValid = await verifyPassword({
+      password: account.password,
+      hash: updatedUser?.hashedPassword ?? '',
+    });
+    const newPasswordValid = await verifyPassword({
+      password: 'new password is long',
+      hash: updatedUser?.hashedPassword ?? '',
+    });
+
+    expect(change.statusCode).toBe(204);
+    expect(updatedUser).toBeDefined();
+    expect(oldPasswordValid).toBe(false);
+    expect(newPasswordValid).toBe(true);
+    expect(refresh.statusCode).toBe(200);
+  });
+
+  test('transforms invalid current password into 401', async () => {
+    const account = await signupVerifyLogin(app, 'change-password-bad');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/change-password',
+      headers: {authorization: `Bearer ${account.token}`},
+      payload: {
+        current_password: 'not the current password',
+        new_password: 'new password is long',
+      },
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().code).toBe('invalid-credentials');
+  });
+
+  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: 'POST',
+      url: '/auth/change-password',
+      headers: {authorization: `Bearer ${token}`},
+      payload: {
+        current_password: 'old password',
+        new_password: 'new password is long',
+      },
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+});

package/src/presentation/routes/password/change-password.ts

@@ -0,0 +1,45 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import {changePasswordBodySchema} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {changePassword} from '#core/auth.js';
+import {InvalidCredentialsError, UserNotFoundError} from '#core/errors.js';
+import {getClientContext} from '#presentation/auth/jwt-auth.js';
+import {getRefreshTokenCookie} from '#presentation/auth/refresh-cookie.js';
+
+export const changePasswordRoute = defineRoute({
+  method: 'POST',
+  path: '/change-password',
+  description: 'Change the signed-in user password.',
+  auth: AUTH_USER,
+  schema: {
+    body: changePasswordBodySchema,
+    response: {
+      204: z.void(),
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof UserNotFoundError) {
+      throw new ClientError('User not found', 'not-found', {status: 404});
+    }
+    if (error instanceof InvalidCredentialsError) {
+      throw new ClientError('Invalid credentials', 'invalid-credentials', {status: 401});
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const client = getClientContext(request);
+    if (!client) {
+      throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+    }
+
+    await changePassword({
+      userId: client.userId,
+      currentPassword: request.body.current_password,
+      newPassword: request.body.new_password,
+      refreshToken: getRefreshTokenCookie(request),
+    });
+
+    reply.code(204);
+  },
+});