fastify-xauth-better

auditLog.log(event, data)

Writes a structured audit event to the AuthAuditLog Prisma model.

auditLog.log(event, data)

Writes a structured audit event to the AuthAuditLog table. Event name must be drawn from the 30-event vocabulary (see table below). IP address and user agent are automatically extracted from the request when provided.

Signature

instance.auditLog.log(
  event: string,
  data?: {
    userId?: string
    targetId?: string
    metadata?: Record<string, unknown>
    request?: FastifyRequest
  }
): Promise<AuthAuditLog>

Params

Name	Type	Required	Description
`event`	`string`	Yes	One of the 30 allowed audit event names (see table below)
`data.userId`	`string`	No	ID of the user performing the action
`data.targetId`	`string`	No	ID of the affected resource or user
`data.metadata`	`object`	No	Arbitrary JSON — stored as `Json` in Prisma
`data.request`	`FastifyRequest`	No	Fastify request — used to capture IP and user-agent automatically

Allowed events

The full 30-event vocabulary (ALLOWED_EVENTS):

Category	Events
Auth	`auth.login.success`, `auth.login.failed`, `auth.logout`, `auth.signup`
Password	`auth.password.changed`, `auth.password.reset`, `auth.password.reset.requested`, `auth.password.reset.completed`
Email	`auth.email.verified`
2FA	`auth.2fa.enabled`, `auth.2fa.disabled`
Session	`auth.session.created`, `auth.session.deleted`, `auth.session.revoked`
Token	`auth.token.created`, `auth.token.revoked`
Account	`auth.account.linked`, `auth.account.banned`
Org membership (auth)	`auth.org.joined`, `auth.org.left`, `auth.org.role.changed`
Organization	`org.created`, `org.updated`, `org.deleted`
Org members	`org.member.added`, `org.member.removed`, `org.member.role.changed`
Org invitations	`org.invitation.sent`, `org.invitation.accepted`, `org.invitation.revoked`

The auditLog.events config option is a subscription filter over this vocabulary — events not listed are silently skipped (log() returns null). The default subscription list covers 19 of these events.

Returns

Promise<AuthAuditLog> — the created Prisma record.

Throws

Error: Invalid audit event: {event}. Allowed events: ... — the event string is not in the allowed vocabulary

Examples

const userAuth = fastify.xAuthBetter.get("user");

fastify.post("/api/login-webhook", async (request) => {
  const { userId } = request.body;

  await userAuth.auditLog.log("auth.login.success", {
    userId,
    metadata: { method: "oauth", provider: "google" },
    request,
  });

  return { ok: true };
});

Log an org role change with target user

await userAuth.auditLog.log("auth.org.role.changed", {
  userId: request.user.id,          // who made the change
  targetId: memberId,               // who was changed
  metadata: {
    orgId: request.organization.id,
    previousRole: "member",
    newRole: "admin",
  },
  request,
});

AI Context

package: "@xenterprises/fastify-xauth-better"
method: fastify.xAuthBetter.get(name).auditLog.log(event, data)
use-when: Write a structured audit event to the AuthAuditLog table
events: 30-event vocabulary (auth.login.success/failed, auth.logout, auth.signup, auth.password.*, auth.email.verified, auth.2fa.*, auth.session.*, auth.token.*, auth.account.*, auth.org.*, org.*, org.member.*, org.invitation.*) — auditLog.events config is a subscription filter (default: 19 events)

Edit this pageorReport an issue

fastify-xauth-better

Production-ready Better Auth plugin for Fastify with multi-instance support, organizations, 2FA, audit logging, and email templates.

getSession(request)

Resolves the Better Auth session from a Fastify request without using middleware.