@shipfox/api-auth 2.0.0

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

@@ -0,0 +1,89 @@
+import type {FastifyInstance} from 'fastify';
+import {
+  cookieHeader,
+  createAuthTestApp,
+  listMembershipsByUserMock,
+  resetCapturedMail,
+  signupVerifyLogin,
+} from '#test/routes.js';
+
+describe('POST /auth/refresh', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createAuthTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns a fresh access token and rotates the refresh cookie', async () => {
+    const account = await signupVerifyLogin(app, 'refresh');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(account.refreshCookie)},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().token).toBeDefined();
+    expect(res.json().user.email).toBe(account.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 missing refresh cookie into 401', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+    });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json().code).toBe('unauthorized');
+    expect(res.headers['set-cookie']).toContain('shipfox_refresh_token=;');
+  });
+
+  test('tolerates a concurrent reuse within the grace window without rotating the cookie', async () => {
+    const account = await signupVerifyLogin(app, 'refresh-concurrent');
+    await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(account.refreshCookie)},
+    });
+
+    const raced = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(account.refreshCookie)},
+    });
+
+    // The racing tab gets a fresh access token but keeps the cookie the winning
+    // refresh already installed, so no Set-Cookie is emitted.
+    expect(raced.statusCode).toBe(200);
+    expect(raced.json().token).toBeDefined();
+    expect(raced.headers['set-cookie']).toBeUndefined();
+  });
+
+  test('transforms membership dependency outages into 503', async () => {
+    const account = await signupVerifyLogin(app, 'refresh-workspaces-down');
+    listMembershipsByUserMock.mockRejectedValueOnce(new Error('workspaces DB down'));
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/auth/refresh',
+      headers: {cookie: cookieHeader(account.refreshCookie)},
+    });
+
+    expect(res.statusCode).toBe(503);
+    expect(res.json().code).toBe('auth-dependency-unavailable');
+  });
+});

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

@@ -0,0 +1,54 @@
+import {refreshResponseSchema} from '@shipfox/api-auth-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {refreshAccessToken} from '#core/auth.js';
+import {AuthDependencyUnavailableError, TokenInvalidError} from '#core/errors.js';
+import {
+  clearRefreshTokenCookie,
+  getRefreshTokenCookie,
+  setRefreshTokenCookie,
+} from '#presentation/auth/refresh-cookie.js';
+import {toAuthSessionDto} from '#presentation/dto/user.js';
+
+export const refreshRoute = defineRoute({
+  method: 'POST',
+  path: '/refresh',
+  description: 'Refresh the current browser session access token.',
+  schema: {
+    response: {
+      200: refreshResponseSchema,
+    },
+  },
+  errorHandler: (error, _request, reply) => {
+    if (error instanceof TokenInvalidError) {
+      clearRefreshTokenCookie(reply);
+      throw new ClientError('Refresh token is invalid or expired', 'unauthorized', {
+        status: 401,
+      });
+    }
+    if (error instanceof AuthDependencyUnavailableError) {
+      throw new ClientError(
+        'Authentication dependency unavailable',
+        'auth-dependency-unavailable',
+        {
+          status: 503,
+        },
+      );
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const refreshToken = getRefreshTokenCookie(request);
+    if (!refreshToken) {
+      clearRefreshTokenCookie(reply);
+      throw new ClientError('Refresh token is invalid or expired', 'unauthorized', {status: 401});
+    }
+
+    const result = await refreshAccessToken({refreshToken});
+
+    // Absent on a grace-window hit: keep the existing cookie rather than overwrite it.
+    if (result.refreshToken) {
+      setRefreshTokenCookie(reply, result.refreshToken);
+    }
+    return toAuthSessionDto(result);
+  },
+});

package/src/presentation/subscribers/email-send-requested.test.ts

@@ -0,0 +1,77 @@
+import type {Mailer, MailMessage} from '@shipfox/node-mailer';
+import {onEmailVerificationSendRequested, onPasswordResetSendRequested} from './index.js';
+
+const testMailer = vi.hoisted(
+  (): {
+    captured: MailMessage[];
+    send: ReturnType<typeof vi.fn<Mailer['send']>>;
+    mailer: Mailer;
+  } => {
+    const captured: MailMessage[] = [];
+    const send = vi.fn<Mailer['send']>((message) => {
+      captured.push(message);
+      return Promise.resolve();
+    });
+    return {captured, send, mailer: {send}};
+  },
+);
+
+vi.mock('#config.js', () => ({
+  mailer: testMailer.mailer,
+}));
+
+describe('auth email subscribers', () => {
+  beforeEach(() => {
+    testMailer.captured.length = 0;
+    testMailer.send.mockReset();
+    testMailer.send.mockImplementation((message) => {
+      testMailer.captured.push(message);
+      return Promise.resolve();
+    });
+  });
+
+  test('sends a rendered email verification message', async () => {
+    await onEmailVerificationSendRequested({
+      email: 'verify@example.com',
+      verifyLink: 'https://app.example.test/auth/verify-email?token=verify-token',
+    });
+
+    expect(testMailer.captured).toHaveLength(1);
+    expect(testMailer.captured[0]).toMatchObject({
+      to: 'verify@example.com',
+      subject: 'Verify your email',
+    });
+    expect(testMailer.captured[0]?.text).toContain('/auth/verify-email?token=verify-token');
+    expect(testMailer.captured[0]?.html).toContain('/auth/verify-email?token');
+    expect(testMailer.captured[0]?.html).toContain('verify-token');
+  });
+
+  test('sends a rendered password reset message', async () => {
+    await onPasswordResetSendRequested({
+      email: 'reset@example.com',
+      resetLink: 'https://app.example.test/auth/reset?token=reset-token',
+      expiresInHours: 1,
+    });
+
+    expect(testMailer.captured).toHaveLength(1);
+    expect(testMailer.captured[0]).toMatchObject({
+      to: 'reset@example.com',
+      subject: 'Reset your password',
+    });
+    expect(testMailer.captured[0]?.text).toContain('/auth/reset?token=reset-token');
+    expect(testMailer.captured[0]?.html).toContain('/auth/reset?token');
+    expect(testMailer.captured[0]?.html).toContain('reset-token');
+  });
+
+  test('rethrows mailer failures so the outbox dispatcher retries', async () => {
+    const failure = new Error('smtp unavailable');
+    testMailer.send.mockRejectedValueOnce(failure);
+
+    const promise = onEmailVerificationSendRequested({
+      email: 'verify-failure@example.com',
+      verifyLink: 'https://app.example.test/auth/verify-email?token=verify-token',
+    });
+
+    await expect(promise).rejects.toBe(failure);
+  });
+});

package/src/presentation/subscribers/index.ts

@@ -0,0 +1,2 @@
+export {onEmailVerificationSendRequested} from './on-email-verification-send-requested.js';
+export {onPasswordResetSendRequested} from './on-password-reset-send-requested.js';

package/src/presentation/subscribers/on-email-verification-send-requested.ts

@@ -0,0 +1,10 @@
+import type {AuthEmailVerificationSendRequestedEvent} from '@shipfox/api-auth-dto';
+import {renderEmail} from '@shipfox/node-email';
+import {mailer} from '#config.js';
+
+export async function onEmailVerificationSendRequested(
+  payload: AuthEmailVerificationSendRequestedEvent,
+): Promise<void> {
+  const email = await renderEmail('verify-email', {verifyLink: payload.verifyLink});
+  await mailer.send({to: payload.email, ...email});
+}

package/src/presentation/subscribers/on-password-reset-send-requested.ts

@@ -0,0 +1,13 @@
+import type {AuthPasswordResetSendRequestedEvent} from '@shipfox/api-auth-dto';
+import {renderEmail} from '@shipfox/node-email';
+import {mailer} from '#config.js';
+
+export async function onPasswordResetSendRequested(
+  payload: AuthPasswordResetSendRequestedEvent,
+): Promise<void> {
+  const email = await renderEmail('reset-password', {
+    resetLink: payload.resetLink,
+    expiresInHours: payload.expiresInHours,
+  });
+  await mailer.send({to: payload.email, ...email});
+}

package/test/env.ts

@@ -0,0 +1,10 @@
+process.env.POSTGRES_HOST ??= 'localhost';
+process.env.POSTGRES_PORT ??= '5432';
+process.env.POSTGRES_USERNAME ??= 'shipfox';
+process.env.POSTGRES_PASSWORD ??= 'password';
+process.env.POSTGRES_DATABASE = 'api_test';
+process.env.POSTGRES_MAX_CONNECTIONS ??= '5';
+process.env.AUTH_JWT_SECRET = 'test-secret';
+process.env.AUTH_JOB_LEASE_TOKEN_SECRET = 'test-lease-secret';
+process.env.AUTH_RUNNER_SESSION_TOKEN_SECRET = 'test-runner-session-secret';
+process.env.TZ = 'UTC';

package/test/factories/index.ts

@@ -0,0 +1 @@
+export {userFactory} from './user.js';

package/test/factories/user.ts

@@ -0,0 +1,36 @@
+import {Factory} from 'fishery';
+import type {User} from '#core/entities/user.js';
+import {hashPassword} from '#core/password.js';
+import {createUser, markEmailVerified} from '#db/users.js';
+
+export const userFactory = Factory.define<User & {plainPassword: string}>(
+  ({sequence, onCreate, params}) => {
+    const plainPassword = params.plainPassword ?? 'correct horse battery staple';
+
+    onCreate(async (user) => {
+      const hashedPassword = await hashPassword({password: plainPassword});
+      const created = await createUser({
+        email: user.email,
+        hashedPassword,
+        name: user.name,
+      });
+      if (user.emailVerifiedAt) {
+        const verified = await markEmailVerified({userId: created.id});
+        return {...(verified ?? created), plainPassword};
+      }
+      return {...created, plainPassword};
+    });
+
+    return {
+      id: crypto.randomUUID(),
+      email: `user-${sequence}-${crypto.randomUUID()}@example.com`,
+      hashedPassword: 'placeholder',
+      name: `User ${sequence}`,
+      emailVerifiedAt: null,
+      status: 'active',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      plainPassword,
+    };
+  },
+);

package/test/globalSetup.ts

@@ -0,0 +1,18 @@
+import './env.js';
+import {runMigrations} from '@shipfox/node-drizzle';
+import {closePostgresClient, createPostgresClient} from '@shipfox/node-postgres';
+import {sql} from 'drizzle-orm';
+import {closeDb, db} from '#db/db.js';
+import {migrationsPath} from '#db/migrations.js';
+
+export async function setup() {
+  createPostgresClient();
+
+  await runMigrations(db(), migrationsPath, '__drizzle_migrations_auth');
+  await db().execute(
+    sql`TRUNCATE auth_outbox, auth_email_verifications, auth_password_resets, auth_rate_limits, auth_refresh_tokens, auth_users CASCADE`,
+  );
+
+  closeDb();
+  await closePostgresClient();
+}

package/test/index.ts

@@ -0,0 +1 @@
+export {userFactory} from './factories/index.js';

package/test/routes.ts

@@ -0,0 +1,275 @@
+import type {OutgoingHttpHeaders} from 'node:http';
+import {
+  AUTH_EMAIL_VERIFICATION_SEND_REQUESTED,
+  type AUTH_PASSWORD_RESET_SEND_REQUESTED,
+} from '@shipfox/api-auth-dto';
+import {type AppConfig, createApp, type FastifyInstance} from '@shipfox/node-fastify';
+import type {Mailer, MailMessage} from '@shipfox/node-mailer';
+import {and, desc, eq, sql} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {authOutbox} from '#db/schema/outbox.js';
+import {createJwtAuthMethod} from '#presentation/auth/jwt-auth.js';
+import {authRoutes} from '#presentation/routes/index.js';
+
+const testConfig = vi.hoisted(
+  (): {
+    captured: MailMessage[];
+    mailer: Mailer;
+    secret: string;
+    clientBaseUrl: string;
+  } => {
+    const captured: MailMessage[] = [];
+    const mailer: Mailer = {
+      send: (message) => {
+        captured.push(message);
+        return Promise.resolve();
+      },
+    };
+    return {
+      captured,
+      mailer,
+      secret: 'route-tests-secret',
+      clientBaseUrl: 'https://app.example.test',
+    };
+  },
+);
+
+const workspaceTestDoubles = vi.hoisted(() => {
+  class InvitationEmailMismatchError extends Error {
+    constructor(message = 'Invitation email does not match') {
+      super(message);
+      this.name = 'InvitationEmailMismatchError';
+    }
+  }
+
+  class TokenAlreadyUsedError extends Error {
+    constructor(message = 'Invitation token has already been used') {
+      super(message);
+      this.name = 'TokenAlreadyUsedError';
+    }
+  }
+
+  class TokenExpiredError extends Error {
+    constructor(message = 'Invitation token has expired') {
+      super(message);
+      this.name = 'TokenExpiredError';
+    }
+  }
+
+  class TokenInvalidError extends Error {
+    constructor(message = 'Invitation token is invalid') {
+      super(message);
+      this.name = 'TokenInvalidError';
+    }
+  }
+
+  return {
+    acceptWorkspaceInvitation: vi.fn(),
+    peekInvitationByRawToken: vi.fn(),
+    listMembershipsByUser: vi.fn(() => Promise.resolve([])),
+    InvitationEmailMismatchError,
+    TokenAlreadyUsedError,
+    TokenExpiredError,
+    TokenInvalidError,
+  };
+});
+
+vi.mock('#config.js', () => ({
+  config: {
+    AUTH_JWT_SECRET: testConfig.secret,
+    AUTH_JWT_EXPIRES_IN: '15m',
+    AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: 14,
+    AUTH_REFRESH_ROTATION_GRACE_SECONDS: 30,
+    AUTH_REFRESH_COOKIE_NAME: 'shipfox_refresh_token',
+    CLIENT_BASE_URL: testConfig.clientBaseUrl,
+  },
+  mailer: testConfig.mailer,
+}));
+
+vi.mock('@shipfox/api-workspaces', () => ({
+  acceptWorkspaceInvitation: workspaceTestDoubles.acceptWorkspaceInvitation,
+  peekInvitationByRawToken: workspaceTestDoubles.peekInvitationByRawToken,
+  InvitationEmailMismatchError: workspaceTestDoubles.InvitationEmailMismatchError,
+  listMembershipsByUser: workspaceTestDoubles.listMembershipsByUser,
+  TokenAlreadyUsedError: workspaceTestDoubles.TokenAlreadyUsedError,
+  TokenExpiredError: workspaceTestDoubles.TokenExpiredError,
+  TokenInvalidError: workspaceTestDoubles.TokenInvalidError,
+}));
+
+const {acceptWorkspaceInvitation, peekInvitationByRawToken, listMembershipsByUser} = await import(
+  '@shipfox/api-workspaces'
+);
+
+const TOKEN_RE = /token=([\w\-_=]+)/;
+type AuthEmailEventType =
+  | typeof AUTH_EMAIL_VERIFICATION_SEND_REQUESTED
+  | typeof AUTH_PASSWORD_RESET_SEND_REQUESTED;
+
+export const ROUTE_TEST_SECRET = testConfig.secret;
+export const acceptWorkspaceInvitationMock = vi.mocked(acceptWorkspaceInvitation);
+export const peekInvitationByRawTokenMock = vi.mocked(peekInvitationByRawToken);
+export const listMembershipsByUserMock = vi.mocked(listMembershipsByUser);
+export const workspaceErrors = {
+  InvitationEmailMismatchError: workspaceTestDoubles.InvitationEmailMismatchError,
+  TokenAlreadyUsedError: workspaceTestDoubles.TokenAlreadyUsedError,
+  TokenExpiredError: workspaceTestDoubles.TokenExpiredError,
+  TokenInvalidError: workspaceTestDoubles.TokenInvalidError,
+};
+
+export function resetCapturedMail(): void {
+  testConfig.captured.length = 0;
+  acceptWorkspaceInvitationMock.mockReset();
+  peekInvitationByRawTokenMock.mockReset();
+  listMembershipsByUserMock.mockReset();
+  listMembershipsByUserMock.mockResolvedValue([]);
+}
+
+export function capturedMail(): MailMessage[] {
+  return testConfig.captured;
+}
+
+export async function outboxEventsTo(email: string, eventType: AuthEmailEventType) {
+  return await db()
+    .select()
+    .from(authOutbox)
+    .where(
+      and(eq(authOutbox.eventType, eventType), sql`${authOutbox.payload}->>'email' = ${email}`),
+    )
+    .orderBy(desc(authOutbox.createdAt));
+}
+
+export function uniqueEmail(prefix: string): string {
+  return `${prefix}-${crypto.randomUUID()}@example.com`;
+}
+
+export function extractToken(url: string): string {
+  const match = url.match(TOKEN_RE);
+  expect(match?.[1]).toBeDefined();
+  return match?.[1] ?? '';
+}
+
+export function getSetCookie(res: {headers: OutgoingHttpHeaders}): string {
+  const header = res.headers['set-cookie'];
+  const value = Array.isArray(header) ? header[0] : typeof header === 'string' ? header : undefined;
+  expect(value).toBeDefined();
+  return value ?? '';
+}
+
+export function cookieHeader(setCookie: string): string {
+  const [cookie] = setCookie.split(';');
+  expect(cookie).toBeDefined();
+  return cookie ?? '';
+}
+
+export function latestMailTo(email: string): MailMessage {
+  const message = [...testConfig.captured].reverse().find((mail) => mail.to === email);
+  expect(message).toBeDefined();
+  return message as MailMessage;
+}
+
+export async function latestEmailLinkTo(
+  email: string,
+  eventType: AuthEmailEventType,
+): Promise<string> {
+  const event = (await outboxEventsTo(email, eventType))[0];
+  expect(event).toBeDefined();
+  const payload = event?.payload as {verifyLink?: string; resetLink?: string} | undefined;
+  const link =
+    eventType === AUTH_EMAIL_VERIFICATION_SEND_REQUESTED ? payload?.verifyLink : payload?.resetLink;
+  expect(link).toBeDefined();
+  return link ?? '';
+}
+
+export async function createAuthTestApp(params?: {
+  fastifyOptions?: AppConfig['fastifyOptions'];
+}): Promise<FastifyInstance> {
+  const appConfig: AppConfig = {
+    auth: [createJwtAuthMethod()],
+    routes: [authRoutes],
+    swagger: false,
+  };
+  if (params?.fastifyOptions) appConfig.fastifyOptions = params.fastifyOptions;
+  return await createApp(appConfig);
+}
+
+export async function signup(
+  app: FastifyInstance,
+  params: {email: string; password: string; name?: string},
+) {
+  return await app.inject({
+    method: 'POST',
+    url: '/auth/signup',
+    payload: {name: 'Test User', ...params},
+  });
+}
+
+export async function verifyEmail(app: FastifyInstance, email: string): Promise<void> {
+  const token = extractToken(
+    await latestEmailLinkTo(email, AUTH_EMAIL_VERIFICATION_SEND_REQUESTED),
+  );
+
+  const res = await app.inject({
+    method: 'POST',
+    url: '/auth/verify-email/confirm',
+    payload: {token},
+  });
+
+  expect(res.statusCode).toBe(200);
+}
+
+export async function login(app: FastifyInstance, params: {email: string; password: string}) {
+  return await app.inject({
+    method: 'POST',
+    url: '/auth/login',
+    payload: params,
+  });
+}
+
+export async function signupVerifyLogin(
+  app: FastifyInstance,
+  prefix: string,
+): Promise<{
+  email: string;
+  password: string;
+  refreshCookie: string;
+  token: string;
+  userId: string;
+}> {
+  const email = uniqueEmail(prefix);
+  const password = 'correct horse battery staple';
+  await signup(app, {email, password, name: prefix});
+  await verifyEmail(app, email);
+
+  const loginRes = await login(app, {email, password});
+
+  expect(loginRes.statusCode).toBe(200);
+  return {
+    email,
+    password,
+    refreshCookie: getSetCookie(loginRes),
+    token: loginRes.json().token,
+    userId: loginRes.json().user.id,
+  };
+}
+
+export async function createVerifiedSession(prefix: string): Promise<{
+  email: string;
+  password: string;
+  refreshCookie: string;
+  token: string;
+  userId: string;
+}> {
+  const {createUser, createSessionForUser} = await import('#core/auth.js');
+  const email = uniqueEmail(prefix);
+  const password = 'correct horse battery staple';
+  const user = await createUser({email, password, name: prefix, verified: true});
+  const session = await createSessionForUser({userId: user.id});
+
+  return {
+    email,
+    password,
+    refreshCookie: `shipfox_refresh_token=${session.refreshToken}`,
+    token: session.token,
+    userId: user.id,
+  };
+}

package/test/setup.ts

@@ -0,0 +1,17 @@
+import './env.js';
+import {closePostgresClient, createPostgresClient} from '@shipfox/node-postgres';
+import {afterAll, afterEach, beforeAll, vi} from '@shipfox/vitest/vi';
+import {closeDb} from '#db/db.js';
+
+beforeAll(() => {
+  createPostgresClient();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+afterAll(async () => {
+  closeDb();
+  await closePostgresClient();
+});

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/node",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}