@shipfox/api-auth 2.0.0

package/src/presentation/routes/password/password-reset-confirm.test.ts

@@ -0,0 +1,63 @@
+import {AUTH_PASSWORD_RESET_SEND_REQUESTED} from '@shipfox/api-auth-dto';
+import type {FastifyInstance} from 'fastify';
+import {
+  createAuthTestApp,
+  extractToken,
+  getSetCookie,
+  latestEmailLinkTo,
+  login,
+  resetCapturedMail,
+  signupVerifyLogin,
+} from '#test/routes.js';
+
+describe('POST /auth/password-reset/confirm', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('updates credentials with a reset token', async () => {
+    const account = await signupVerifyLogin(app, 'reset-confirm');
+    await app.inject({
+      method: 'POST',
+      url: '/auth/password-reset',
+      payload: {email: account.email},
+    });
+    const resetToken = extractToken(
+      await latestEmailLinkTo(account.email, AUTH_PASSWORD_RESET_SEND_REQUESTED),
+    );
+
+    const confirm = await app.inject({
+      method: 'POST',
+      url: '/auth/password-reset/confirm',
+      payload: {token: resetToken, new_password: 'reset password is long'},
+    });
+    const loginRes = await login(app, {email: account.email, password: 'reset password is long'});
+
+    expect(confirm.statusCode).toBe(200);
+    expect(confirm.json().token).toBeDefined();
+    expect(confirm.json().user.email).toBe(account.email);
+    expect(getSetCookie(confirm)).toContain('shipfox_refresh_token=');
+    expect(loginRes.statusCode).toBe(200);
+  });
+
+  test('transforms invalid token into 410', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/password-reset/confirm',
+      payload: {token: 'bad-token', new_password: 'reset password is long'},
+    });
+
+    expect(res.statusCode).toBe(410);
+    expect(res.json().code).toBe('token-invalid');
+  });
+});

package/src/presentation/routes/password/password-reset-confirm.ts

@@ -0,0 +1,35 @@
+import {
+  passwordResetConfirmBodySchema,
+  passwordResetConfirmResponseSchema,
+} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {confirmPasswordReset} 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 passwordResetConfirmRoute = defineRoute({
+  method: 'POST',
+  path: '/password-reset/confirm',
+  description: 'Set a new password using the link sent by email.',
+  schema: {
+    body: passwordResetConfirmBodySchema,
+    response: {
+      200: passwordResetConfirmResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof TokenInvalidError) {
+      throw new ClientError('Reset token is invalid or expired', 'token-invalid', {status: 410});
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const {token, new_password} = request.body;
+
+    const result = await confirmPasswordReset({token, newPassword: new_password});
+    setRefreshTokenCookie(reply, result.refreshToken);
+
+    return toAuthSessionDto(result);
+  },
+});

package/src/presentation/routes/password/password-reset-request.test.ts

@@ -0,0 +1,56 @@
+import {AUTH_PASSWORD_RESET_SEND_REQUESTED} from '@shipfox/api-auth-dto';
+import type {FastifyInstance} from 'fastify';
+import {
+  capturedMail,
+  createAuthTestApp,
+  latestEmailLinkTo,
+  outboxEventsTo,
+  resetCapturedMail,
+  signupVerifyLogin,
+  uniqueEmail,
+} from '#test/routes.js';
+
+describe('POST /auth/password-reset', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns 204 and sends reset mail for an active account', async () => {
+    const account = await signupVerifyLogin(app, 'reset-request');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/password-reset',
+      payload: {email: account.email.toUpperCase()},
+    });
+
+    expect(res.statusCode).toBe(204);
+    expect(await latestEmailLinkTo(account.email, AUTH_PASSWORD_RESET_SEND_REQUESTED)).toContain(
+      '/auth/reset?token=',
+    );
+    expect(capturedMail()).toHaveLength(0);
+  });
+
+  test('returns 204 without revealing missing accounts', async () => {
+    const email = uniqueEmail('missing-reset');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/password-reset',
+      payload: {email},
+    });
+
+    expect(res.statusCode).toBe(204);
+    expect(await outboxEventsTo(email, AUTH_PASSWORD_RESET_SEND_REQUESTED)).toHaveLength(0);
+  });
+});

package/src/presentation/routes/password/password-reset-request.ts

@@ -0,0 +1,25 @@
+import {passwordResetRequestBodySchema} from '@shipfox/api-auth-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {requestPasswordReset} from '#core/auth.js';
+import {createAuthRateLimitPreHandler} from '#presentation/routes/rate-limit.js';
+
+export const passwordResetRequestRoute = defineRoute({
+  method: 'POST',
+  path: '/password-reset',
+  description: 'Send a password reset email when an account is eligible.',
+  schema: {
+    body: passwordResetRequestBodySchema,
+    response: {
+      204: z.void(),
+    },
+  },
+  preHandler: createAuthRateLimitPreHandler('email-send'),
+  handler: async (request, reply) => {
+    const {email} = request.body;
+
+    await requestPasswordReset({email});
+
+    reply.code(204);
+  },
+});

package/src/presentation/routes/rate-limit.test.ts

@@ -0,0 +1,341 @@
+import {AUTH_PASSWORD_RESET_SEND_REQUESTED} from '@shipfox/api-auth-dto';
+import type {AppConfig, FastifyInstance} from '@shipfox/node-fastify';
+import {and, eq, sql} from 'drizzle-orm';
+import {
+  type AuthRateLimitAction,
+  type AuthRateLimitScope,
+  hashAuthRateLimitIdentifier,
+} from '#core/rate-limit.js';
+import {db} from '#db/db.js';
+import {authRateLimits} from '#db/schema/rate-limits.js';
+import {
+  createAuthTestApp,
+  outboxEventsTo,
+  resetCapturedMail,
+  signupVerifyLogin,
+  uniqueEmail,
+} from '#test/routes.js';
+
+let ipCounter = 1;
+
+function uniqueIp(): string {
+  ipCounter += 1;
+  return `203.0.113.${ipCounter}`;
+}
+
+async function seedExhaustedBucket(params: {
+  action: AuthRateLimitAction;
+  scope: AuthRateLimitScope;
+  identifier: string;
+  limit: number;
+  windowSeconds: number;
+}): Promise<void> {
+  const now = new Date();
+  const windowStart = windowStartFor(now, params.windowSeconds);
+  const identifierHmac = hashAuthRateLimitIdentifier({
+    action: params.action,
+    scope: params.scope,
+    identifier: params.identifier,
+  });
+  await db()
+    .insert(authRateLimits)
+    .values({
+      action: params.action,
+      scope: params.scope,
+      identifierHmac,
+      windowStart,
+      count: params.limit,
+      expiresAt: new Date(windowStart.getTime() + params.windowSeconds * 1000),
+    });
+}
+
+async function countBucket(params: {
+  action: AuthRateLimitAction;
+  scope: AuthRateLimitScope;
+  identifier: string;
+}): Promise<number> {
+  const identifierHmac = hashAuthRateLimitIdentifier({
+    action: params.action,
+    scope: params.scope,
+    identifier: params.identifier,
+  });
+  const rows = await db()
+    .select({count: sql<number>`count(*)::int`})
+    .from(authRateLimits)
+    .where(
+      and(
+        eq(authRateLimits.action, params.action),
+        eq(authRateLimits.scope, params.scope),
+        eq(authRateLimits.identifierHmac, identifierHmac),
+      ),
+    );
+
+  return rows[0]?.count ?? 0;
+}
+
+async function bucketAttemptCount(params: {
+  action: AuthRateLimitAction;
+  scope: AuthRateLimitScope;
+  identifier: string;
+}): Promise<number> {
+  const identifierHmac = hashAuthRateLimitIdentifier({
+    action: params.action,
+    scope: params.scope,
+    identifier: params.identifier,
+  });
+  const rows = await db()
+    .select({count: authRateLimits.count})
+    .from(authRateLimits)
+    .where(
+      and(
+        eq(authRateLimits.action, params.action),
+        eq(authRateLimits.scope, params.scope),
+        eq(authRateLimits.identifierHmac, identifierHmac),
+      ),
+    );
+
+  return rows[0]?.count ?? 0;
+}
+
+function windowStartFor(now: Date, windowSeconds: number): Date {
+  const windowMs = windowSeconds * 1000;
+  return new Date(Math.floor(now.getTime() / windowMs) * windowMs);
+}
+
+type LoggerInstance = NonNullable<NonNullable<AppConfig['fastifyOptions']>['loggerInstance']>;
+
+function createCapturingLogger(logs: unknown[]): LoggerInstance {
+  const logger = {
+    child: () => logger,
+    level: 'info',
+    silent: (...args: unknown[]) => {
+      logs.push(['silent', ...args]);
+    },
+    fatal: (...args: unknown[]) => {
+      logs.push(['fatal', ...args]);
+    },
+    error: (...args: unknown[]) => {
+      logs.push(['error', ...args]);
+    },
+    warn: (...args: unknown[]) => {
+      logs.push(['warn', ...args]);
+    },
+    info: (...args: unknown[]) => {
+      logs.push(['info', ...args]);
+    },
+    debug: (...args: unknown[]) => {
+      logs.push(['debug', ...args]);
+    },
+    trace: (...args: unknown[]) => {
+      logs.push(['trace', ...args]);
+    },
+  };
+  return logger as unknown as LoggerInstance;
+}
+
+describe('auth rate-limit routes', () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    resetCapturedMail();
+    app = await createAuthTestApp({fastifyOptions: {trustProxy: true}});
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('blocks exhausted login IP buckets before login work runs', async () => {
+    const ip = uniqueIp();
+    await seedExhaustedBucket({
+      action: 'login',
+      scope: 'ip',
+      identifier: ip,
+      limit: 60,
+      windowSeconds: 5 * 60,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/login',
+      headers: {'x-forwarded-for': ip},
+      payload: {email: uniqueEmail('login-ip-block'), password: 'wrong password'},
+    });
+
+    expect(res.statusCode).toBe(429);
+    expect(res.json()).toEqual({
+      code: 'rate-limited',
+      details: {retry_after_seconds: expect.any(Number)},
+    });
+    expect(res.headers['retry-after']).toEqual(expect.any(String));
+  });
+
+  it('blocks exhausted login email buckets after the IP bucket passes', async () => {
+    const ip = uniqueIp();
+    const email = uniqueEmail('login-email-block');
+    await seedExhaustedBucket({
+      action: 'login',
+      scope: 'email',
+      identifier: email,
+      limit: 10,
+      windowSeconds: 15 * 60,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/login',
+      headers: {'x-forwarded-for': ip},
+      payload: {email, password: 'wrong password'},
+    });
+
+    expect(res.statusCode).toBe(429);
+    expect(res.json().code).toBe('rate-limited');
+    expect(await countBucket({action: 'login', scope: 'ip', identifier: ip})).toBe(1);
+  });
+
+  it('shares the email-send bucket across password reset and verification resend', async () => {
+    const account = await signupVerifyLogin(app, 'email-send-shared');
+    resetCapturedMail();
+
+    for (let index = 0; index < 3; index += 1) {
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/password-reset',
+        headers: {'x-forwarded-for': uniqueIp()},
+        payload: {email: account.email},
+      });
+      expect(res.statusCode).toBe(204);
+    }
+    const blockedReset = await app.inject({
+      method: 'POST',
+      url: '/auth/password-reset',
+      headers: {'x-forwarded-for': uniqueIp()},
+      payload: {email: account.email},
+    });
+    const blockedResend = await app.inject({
+      method: 'POST',
+      url: '/auth/verify-email/resend',
+      headers: {'x-forwarded-for': uniqueIp()},
+      payload: {email: account.email},
+    });
+
+    expect(blockedReset.statusCode).toBe(429);
+    expect(blockedResend.statusCode).toBe(429);
+    expect(await outboxEventsTo(account.email, AUTH_PASSWORD_RESET_SEND_REQUESTED)).toHaveLength(3);
+  });
+
+  it('blocks exhausted email-send IP buckets before consuming email buckets', async () => {
+    const ip = uniqueIp();
+    const blockedEmail = uniqueEmail('email-send-ip-blocked');
+    await seedExhaustedBucket({
+      action: 'email-send',
+      scope: 'ip',
+      identifier: ip,
+      limit: 30,
+      windowSeconds: 60 * 60,
+    });
+
+    const blocked = await app.inject({
+      method: 'POST',
+      url: '/auth/password-reset',
+      headers: {'x-forwarded-for': ip},
+      payload: {email: blockedEmail},
+    });
+
+    expect(blocked.statusCode).toBe(429);
+    expect(blocked.json().code).toBe('rate-limited');
+    expect(await bucketAttemptCount({action: 'email-send', scope: 'ip', identifier: ip})).toBe(31);
+    expect(
+      await countBucket({action: 'email-send', scope: 'email', identifier: blockedEmail}),
+    ).toBe(0);
+  });
+
+  it('does not consume buckets for invalid bodies', async () => {
+    const ip = uniqueIp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/login',
+      headers: {'x-forwarded-for': ip},
+      payload: {email: 'not-an-email', password: 'wrong password'},
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(await countBucket({action: 'login', scope: 'ip', identifier: ip})).toBe(0);
+  });
+
+  it('fails closed when limiter storage is unavailable', async () => {
+    const ip = uniqueIp();
+    const identifierHmac = hashAuthRateLimitIdentifier({
+      action: 'login',
+      scope: 'ip',
+      identifier: ip,
+    });
+    const windowStart = windowStartFor(new Date(), 5 * 60);
+    await db()
+      .insert(authRateLimits)
+      .values({
+        action: 'login',
+        scope: 'ip',
+        identifierHmac,
+        windowStart,
+        count: 1,
+        expiresAt: new Date(windowStart.getTime() + 5 * 60 * 1000),
+      });
+
+    await db().transaction(async (tx) => {
+      await tx.execute(sql`
+        SELECT 1
+        FROM auth_rate_limits
+        WHERE identifier_hmac = ${identifierHmac}
+        FOR UPDATE
+      `);
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/login',
+        headers: {'x-forwarded-for': ip},
+        payload: {email: uniqueEmail('limiter-unavailable'), password: 'wrong password'},
+      });
+
+      expect(res.statusCode).toBe(503);
+      expect(res.json()).toEqual({code: 'auth-rate-limit-unavailable'});
+    });
+  });
+
+  it('does not log raw email addresses or IP addresses for blocked requests', async () => {
+    await app.close();
+    const logs: unknown[] = [];
+    app = await createAuthTestApp({
+      fastifyOptions: {loggerInstance: createCapturingLogger(logs), trustProxy: true},
+    });
+    const ip = uniqueIp();
+    const email = uniqueEmail('log-privacy');
+    await seedExhaustedBucket({
+      action: 'login',
+      scope: 'email',
+      identifier: email,
+      limit: 10,
+      windowSeconds: 15 * 60,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/login',
+      headers: {'x-forwarded-for': ip},
+      payload: {email, password: 'wrong password'},
+    });
+    const authLogs = logs.filter((entry) => {
+      const serializedEntry = JSON.stringify(entry);
+      return (
+        serializedEntry.includes('Auth rate limit blocked request') ||
+        serializedEntry.includes('Rate limit exceeded')
+      );
+    });
+    const serializedLogs = JSON.stringify(authLogs);
+
+    expect(res.statusCode).toBe(429);
+    expect(serializedLogs).toContain('identifierHmacPrefix');
+    expect(serializedLogs).not.toContain(email);
+    expect(serializedLogs).not.toContain(ip);
+  });
+});

package/src/presentation/routes/rate-limit.ts

@@ -0,0 +1,119 @@
+import {ClientError, type FastifyReply, type FastifyRequest} from '@shipfox/node-fastify';
+import {
+  type AuthRateLimitAction,
+  AuthRateLimitExceededError,
+  type AuthRateLimitPolicy,
+  type AuthRateLimitScope,
+  AuthRateLimitUnavailableError,
+  checkAuthRateLimit,
+} from '#core/rate-limit.js';
+
+const policies: Record<AuthRateLimitAction, Record<AuthRateLimitScope, AuthRateLimitPolicy>> = {
+  login: {
+    ip: {limit: 60, windowSeconds: 5 * 60},
+    email: {limit: 10, windowSeconds: 15 * 60},
+  },
+  'email-send': {
+    ip: {limit: 30, windowSeconds: 60 * 60},
+    email: {limit: 3, windowSeconds: 60 * 60},
+  },
+};
+
+interface EmailBody {
+  email: string;
+}
+
+function routeName(request: FastifyRequest): string {
+  return request.routeOptions.url ?? request.url.split('?')[0] ?? 'unknown';
+}
+
+async function enforceRateLimit(params: {
+  request: FastifyRequest;
+  reply: FastifyReply;
+  action: AuthRateLimitAction;
+  scope: AuthRateLimitScope;
+  identifier: string;
+}): Promise<void> {
+  try {
+    await checkAuthRateLimit({
+      action: params.action,
+      scope: params.scope,
+      identifier: params.identifier,
+      ...policies[params.action][params.scope],
+    });
+  } catch (error) {
+    if (error instanceof AuthRateLimitExceededError) {
+      params.request.log.warn(
+        {
+          action: error.action,
+          scope: error.scope,
+          route: routeName(params.request),
+          retryAfterSeconds: error.retryAfterSeconds,
+          identifierHmacPrefix: error.identifierHmacPrefix,
+        },
+        'Auth rate limit blocked request',
+      );
+      params.reply.header('Retry-After', String(error.retryAfterSeconds));
+      throw new ClientError('Rate limit exceeded', 'rate-limited', {
+        status: 429,
+        details: {retry_after_seconds: error.retryAfterSeconds},
+        data: {
+          action: error.action,
+          scope: error.scope,
+          route: routeName(params.request),
+          identifierHmacPrefix: error.identifierHmacPrefix,
+        },
+        cause: error,
+      });
+    }
+
+    if (error instanceof AuthRateLimitUnavailableError) {
+      params.request.log.error(
+        {
+          action: error.action,
+          scope: error.scope,
+          route: routeName(params.request),
+          identifierHmacPrefix: error.identifierHmacPrefix,
+          err: error,
+        },
+        'Auth rate limiter unavailable',
+      );
+      throw new ClientError(
+        'Authentication rate limiter unavailable',
+        'auth-rate-limit-unavailable',
+        {
+          status: 503,
+          data: {
+            action: error.action,
+            scope: error.scope,
+            route: routeName(params.request),
+            identifierHmacPrefix: error.identifierHmacPrefix,
+          },
+          cause: error,
+        },
+      );
+    }
+
+    throw error;
+  }
+}
+
+export function createAuthRateLimitPreHandler(action: AuthRateLimitAction) {
+  return async (request: FastifyRequest<{Body: EmailBody}>, reply: FastifyReply): Promise<void> => {
+    await enforceRateLimit({
+      request,
+      reply,
+      action,
+      scope: 'ip',
+      identifier: request.ip,
+    });
+
+    await enforceRateLimit({
+      request,
+      reply,
+      action,
+      scope: 'email',
+      identifier: request.body.email,
+    });
+  };
+}