Ozhi - Audit System

A comprehensive pluggable audit system for SvelteKit applications with seamless integration for Drizzle ORM, Better-Auth, Resend, and Stripe.

Features

• 🔌 Pluggable Architecture - Easy to integrate without modifying existing code
• 🔐 Automatic Context Capture - User, session, IP, and request details via AsyncLocalStorage
• 📝 Type-Safe Events - Full TypeScript support with categorized events
• 🗄️ Optimized Database Schema - Efficient Drizzle schema with proper indexing
• 🪝 Multiple Integration Points - Middleware, wrapper functions and decorators (future)
• 🔔 Built-in Plugins - Notifications, Stripe enrichment, and security monitoring
• 🎯 Flexible Targeting - Track changes to any entity with before/after states

Installation & Usage

1. Install

pnpm add @valink-solutions-ltd/ozhi

2. Setup drizzle schema

In your src/lib/server/db/index.ts:

import { drizzle } from 'drizzle-orm/postgres-js';
import { postgres } from 'drizzle-orm/postgres-js';
import * as schema from "./schema";
import * as ohziSchema from '@valink-solutions-ltd/ozhi/db/schema';

const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client, {{ ...schema, ...ohziSchema }});

3. Configure Hooks

In your src/hooks.server.ts:

import { createAuditMiddleware } from '@valink-solutions-ltd/ozhi';
import { auditor } from '@valink-solutions-ltd/ozhi';
import {
	createNotificationPlugin,
	createStripePlugin,
	createSecurityPlugin
} from '@valink-solutions-ltd/ozhi/plugins';
import { resend } from 'resend';
import { stripe } from 'stripe';

// Configure plugins (optional)
auditor.registerPlugin(
	createSecurityPlugin({
		maxFailedAttempts: 5,
		timeWindowMs: 300000 // 5 minutes
	})
);

auditor.registerPlugin(
	createNotificationPlugin({
		resend,
		notifyEmail: '[email protected]',
		severityThreshold: AuditSeverity.HIGH
	})
);

auditor.registerPlugin(createStripePlugin({ stripe }));

// Initialize auditor
await auditor.initialize();

// Apply middleware
export const handle = createAuditMiddleware();

4. Start Auditing

Manual Audit Logging

import { audit } from '@valink-solutions-ltd/ozhi';
import { AuditCategory, AuditResult } from '@valink-solutions-ltd/ozhi/types';

// Log a successful action
await audit({
	action: 'user.profile.updated',
	category: AuditCategory.DATA_MODIFICATION,
	result: AuditResult.SUCCESS,
	target: {
		type: 'user',
		id: userId,
		name: userEmail
	},
	changes: {
		before: { role: 'user' },
		after: { role: 'admin' },
		fields: ['role']
	}
});

Wrapped Server Endpoints

import { withAudit } from '@valink-solutions-ltd/ozhi/middleware';
import type { RequestHandler } from './$types';

export const POST: RequestHandler = withAudit(
	'invoice.complete',
	AuditCategory.INVOICE,
	async ({ request }) => {
		const { invoiceId } = await request.json();
		// Your business logic here
		return json({ success: true });
	}
);

Form Actions with Decorators

import { auditFormAction } from '@valink-solutions-ltd/ozhi/helpers';
import type { Actions } from './$types';

export const actions = {
	delete: auditFormAction(
		'user.delete',
		AuditCategory.USER_MANAGEMENT
	)(async ({ params }) => {
		// Delete user logic
	})
} satisfies Actions;

Better-Auth Integration

Automatically audit authentication events:

import { betterAuth } from 'better-auth';
import { audit } from '@valink-solutions-ltd/ozhi';
import { AuditCategory, AuditResult } from '@valink-solutions-ltd/ozhi/types';

export const auth = betterAuth({
	// ... your config
	hooks: {
		after: {
			signIn: async ({ user, session }) => {
				await audit({
					action: 'auth.signin',
					category: AuditCategory.AUTH,
					result: AuditResult.SUCCESS,
					target: {
						type: 'user',
						id: user.id,
						name: user.email
					}
				});
			},
			signOut: async ({ user }) => {
				await audit({
					action: 'auth.signout',
					category: AuditCategory.AUTH,
					result: AuditResult.SUCCESS,
					target: {
						type: 'user',
						id: user.id,
						name: user.email
					}
				});
			}
		}
	}
});

Audit Categories

• AUTH - Authentication events (login, logout, password changes)
• PAYMENT - Payment processing events
• DATA_ACCESS - Read operations on sensitive data
• DATA_MODIFICATION - Create, update, delete operations
• SYSTEM - System-level events
• INVOICE - Invoice-related operations
• USER_MANAGEMENT - User administration events

Severity Levels

• LOW - Routine operations
• MEDIUM - Important business operations
• HIGH - Security-relevant or critical operations
• CRITICAL - High-risk operations requiring immediate attention

Plugin Development

Create custom plugins by implementing the AuditPlugin interface:

import type { AuditPlugin, AuditEvent } from '@valink-solutions-ltd/ozhi/types';

export function createCustomPlugin(): AuditPlugin {
	return {
		name: 'custom-plugin',

		initialize: async () => {
			// Setup code
		},

		beforeAudit: async (event: AuditEvent) => {
			// Modify or cancel events
			// Return null to cancel, or modified event
			return event;
		},

		afterAudit: async (event: AuditEvent) => {
			// React to audit events
		}
	};
}

Built-in Plugins

Notification Plugin

Sends email alerts for high-severity events:

createNotificationPlugin({
	resend: resendClient,
	notifyEmail: '[email protected]',
	severityThreshold: AuditSeverity.HIGH // Only alert for high and critical
});

Security Plugin

Monitors and alerts on suspicious activity:

createSecurityPlugin({
	maxFailedAttempts: 5,
	timeWindowMs: 300000 // 5 minutes
});

Stripe Plugin

Enriches payment events with Stripe metadata:

createStripePlugin({
	stripe: stripeClient
});

Querying Audit Logs

Use the built-in query builder:

import { queryAuditLogs } from '@valink-solutions-ltd/ozhi/query-builder';

const logs = await queryAuditLogs({
	userId: 'user_123',
	category: AuditCategory.PAYMENT,
	severity: [AuditSeverity.HIGH, AuditSeverity.CRITICAL],
	startDate: new Date('2024-01-01'),
	endDate: new Date('2024-12-31'),
	limit: 50,
	offset: 0
});

Best Practices

1. Use Consistent Action Names: Follow a dot-notation pattern (e.g., entity.action.detail)
2. Include Context: Always provide meaningful target information
3. Track Changes: Use the changes object for data modifications
4. Set Appropriate Severity: Let critical events trigger notifications
5. Leverage Metadata: Store additional context in metadata fields

Security Considerations

• Audit logs are tamper-evident once written
• Consider encrypting sensitive data in metadata fields
• Implement retention policies for compliance
• Use read-only database users for audit queries
• Monitor for unusual patterns using the security plugin

TypeScript Support

Full TypeScript support with exported types:

import type {
	AuditEvent,
	AuditContext,
	AuditCategory,
	AuditSeverity,
	AuditResult,
	AuditTarget,
	AuditChanges,
	AuditPlugin
} from '@valink-solutions-ltd/ozhi/types';

Architecture

The system uses:

• AsyncLocalStorage for request-scoped context
• Drizzle ORM for database operations
• Plugin Architecture for extensibility
• Middleware Pattern for automatic context injection

License

MIT

Contributing

Contributions are welcome! Please ensure all changes maintain backward compatibility and include appropriate tests.