feat(audit): add centralized audit event emission middleware

- Integrates: reusable audit emitter module and plugin in app/server/src/modules/audit/emitter.ts and app/server/src/plugins/audit.ts, plus server/type wiring in app/server/src/index.ts and app/server/src/types/fastify.d.ts.

- Security/Behavior: standardizes audit persistence across signup/signin/signout, refresh compromise handling, OAuth linkage/disconnect, MFA enable/disable, and passkey flows with consistent request metadata capture.

- Validation: added audit plugin behavior coverage in app/server/test/audit-plugin.test.ts; runtime execution remains pending because local dependency installation is not present in this environment.

Author: ganeshwhere

app/server/src/index.ts

@@ -23,6 +23,7 @@ export async function buildServer(): Promise<FastifyInstance> {
   await server.register(import('./plugins/rate-limiter'))
   await server.register(import('./plugins/database'))
   await server.register(import('./plugins/cache'))
+  await server.register(import('./plugins/audit'))
   await server.register(import('./plugins/email'))
   await server.register(import('./plugins/email-queue'))
   await server.register(import('./plugins/webhook-queue'))

app/server/src/modules/audit/emitter.ts

@@ -0,0 +1,45 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify'
+
+export const auditEventCatalog = [
+  'user.created',
+  'user.updated',
+  'user.deleted',
+  'user.signed_in',
+  'user.signed_out',
+  'session.created',
+  'session.revoked',
+  'session.compromised',
+  'oauth.connected',
+  'oauth.disconnected',
+  'passkey.registered',
+  'passkey.removed',
+  'mfa.enabled',
+  'mfa.disabled',
+  'password.changed',
+  'password.reset',
+  'email.verified',
+] as const
+
+export type AuditEventName = (typeof auditEventCatalog)[number]
+
+export type AuditEventInput = {
+  projectId: string
+  event: AuditEventName | (string & {})
+  userId?: string
+  metadata?: Record<string, unknown>
+  request?: FastifyRequest
+}
+
+export async function emitAuditEvent(
+  server: FastifyInstance,
+  input: AuditEventInput,
+): Promise<void> {
+  await server.dbAdapter.createAuditLog({
+    projectId: input.projectId,
+    userId: input.userId,
+    event: input.event,
+    ipAddress: input.request?.ip,
+    userAgent: input.request?.headers['user-agent'] as string | undefined,
+    metadata: input.metadata ?? {},
+  })
+}

app/server/src/modules/auth/refresh.ts

@@ -78,16 +78,17 @@ async function handleReuseDetection(
 ): Promise<never> {
   await request.server.dbAdapter.revokeSessionFamily(marker.tokenFamily)
 
-  await request.server.dbAdapter.createAuditLog({
-    projectId: marker.projectId,
-    userId: marker.userId,
-    event: 'session.compromised',
-    ipAddress: request.ip,
-    userAgent: request.headers['user-agent'] as string | undefined,
-    metadata: {
-      reason: 'refresh_token_reuse_detected',
-    },
-  })
+  if (typeof request.server.emitAuditEvent === 'function') {
+    await request.server.emitAuditEvent({
+      projectId: marker.projectId,
+      userId: marker.userId,
+      event: 'session.compromised',
+      request,
+      metadata: {
+        reason: 'refresh_token_reuse_detected',
+      },
+    })
+  }
 
   if (typeof request.server.emitWebhookEvent === 'function') {
     try {

app/server/src/modules/auth/signin.ts

@@ -149,6 +149,28 @@ export async function signinHandler(
     }
   }
 
+  if (typeof request.server.emitAuditEvent === 'function') {
+    await request.server.emitAuditEvent({
+      projectId,
+      userId: user.id,
+      event: 'user.signed_in',
+      request,
+      metadata: {
+        method: 'password',
+      },
+    })
+
+    await request.server.emitAuditEvent({
+      projectId,
+      userId: user.id,
+      event: 'session.created',
+      request,
+      metadata: {
+        sessionId: session.id,
+      },
+    })
+  }
+
   reply.send({
     data: {
       user,

app/server/src/modules/auth/signout.ts

@@ -68,6 +68,28 @@ export async function signoutHandler(
         request.log.warn({ error }, 'Failed to enqueue signout webhook events')
       }
     }
+
+    if (typeof request.server.emitAuditEvent === 'function') {
+      await request.server.emitAuditEvent({
+        projectId: payload.pid,
+        userId: payload.sub,
+        event: 'user.signed_out',
+        request,
+        metadata: {
+          sessionId: session.id,
+        },
+      })
+
+      await request.server.emitAuditEvent({
+        projectId: payload.pid,
+        userId: payload.sub,
+        event: 'session.revoked',
+        request,
+        metadata: {
+          sessionId: session.id,
+        },
+      })
+    }
   }
 
   clearRefreshTokenCookie(reply, config.nodeEnv === 'production')

app/server/src/modules/auth/signup.ts

@@ -123,6 +123,28 @@ export async function signupHandler(
     }
   }
 
+  if (typeof request.server.emitAuditEvent === 'function') {
+    await request.server.emitAuditEvent({
+      projectId,
+      userId: user.id,
+      event: 'user.created',
+      request,
+      metadata: {
+        method: 'password',
+      },
+    })
+
+    await request.server.emitAuditEvent({
+      projectId,
+      userId: user.id,
+      event: 'session.created',
+      request,
+      metadata: {
+        sessionId: session.id,
+      },
+    })
+  }
+
   reply.code(201).send({
     data: {
       user,

app/server/src/modules/mfa/handlers.ts

@@ -139,7 +139,7 @@ export async function mfaTotpEnableHandler(
   request: FastifyRequest,
   reply: FastifyReply,
 ): Promise<void> {
-  const { userId } = await getCurrentUser(request)
+  const { userId, projectId } = await getCurrentUser(request)
   const parsed = mfaCodeBodySchema.parse(request.body)
 
   const pendingRaw = await request.server.cache.get(setupCacheKey(userId))
@@ -177,6 +177,18 @@ export async function mfaTotpEnableHandler(
     300,
   )
 
+  if (typeof request.server.emitAuditEvent === 'function') {
+    await request.server.emitAuditEvent({
+      projectId,
+      userId,
+      event: 'mfa.enabled',
+      request,
+      metadata: {
+        method: 'totp',
+      },
+    })
+  }
+
   reply.send({
     data: {
       success: true,
@@ -189,7 +201,7 @@ export async function mfaTotpDisableHandler(
   request: FastifyRequest,
   reply: FastifyReply,
 ): Promise<void> {
-  const { userId } = await getCurrentUser(request)
+  const { userId, projectId } = await getCurrentUser(request)
   const parsed = mfaCodeBodySchema.parse(request.body)
 
   const valid = await verifyActiveMfaCode(request, userId, parsed.code)
@@ -202,6 +214,18 @@ export async function mfaTotpDisableHandler(
   await request.server.cache.delete(setupCacheKey(userId))
   await request.server.cache.delete(backupViewCacheKey(userId))
 
+  if (typeof request.server.emitAuditEvent === 'function') {
+    await request.server.emitAuditEvent({
+      projectId,
+      userId,
+      event: 'mfa.disabled',
+      request,
+      metadata: {
+        method: 'totp',
+      },
+    })
+  }
+
   reply.send({
     data: {
       success: true,

app/server/src/modules/oauth/disconnect.ts

@@ -62,16 +62,17 @@ export async function oauthDisconnectHandler(
     }
   }
 
-  await request.server.dbAdapter.createAuditLog({
-    projectId: auth.pid,
-    userId: auth.sub,
-    event: 'oauth.disconnected',
-    ipAddress: request.ip,
-    userAgent: request.headers['user-agent'] as string | undefined,
-    metadata: {
-      provider: providerId,
-    },
-  })
+  if (typeof request.server.emitAuditEvent === 'function') {
+    await request.server.emitAuditEvent({
+      projectId: auth.pid,
+      userId: auth.sub,
+      event: 'oauth.disconnected',
+      request,
+      metadata: {
+        provider: providerId,
+      },
+    })
+  }
 
   reply.send({
     data: {

app/server/src/modules/oauth/handlers.ts

@@ -304,6 +304,40 @@ export async function oauthCallbackHandler(
     }
   }
 
+  if (typeof request.server.emitAuditEvent === 'function') {
+    if (oauthResult.linkedAccountCreated) {
+      await request.server.emitAuditEvent({
+        projectId: state.projectId,
+        userId: user.id,
+        event: 'oauth.connected',
+        request,
+        metadata: {
+          provider: providerConfig.id,
+        },
+      })
+    }
+
+    await request.server.emitAuditEvent({
+      projectId: state.projectId,
+      userId: user.id,
+      event: 'user.signed_in',
+      request,
+      metadata: {
+        method: `oauth:${providerConfig.id}`,
+      },
+    })
+
+    await request.server.emitAuditEvent({
+      projectId: state.projectId,
+      userId: user.id,
+      event: 'session.created',
+      request,
+      metadata: {
+        sessionId: session.id,
+      },
+    })
+  }
+
   const location = appendHash(
     appendQuery(state.redirectUrl, {
       provider: providerConfig.id,