# Firebase Auth Ecosystem

A comprehensive authentication and service ecosystem built on Firebase, designed to provide exceptional developer experience with powerful features out of the box.

## Overview

This ecosystem consists of four interconnected libraries that work seamlessly together:

1. **🔐 Auth Library** - Complete authentication solution with Firebase
2. **📧 Email Library** - Simple yet powerful email service
3. **🔔 Notifications Library** - Multi-channel notification system
4. **📝 Audit Logging Library** - Comprehensive activity tracking

## Why Use This Ecosystem?

### The Problem
Building authentication, email, notifications, and audit logging from scratch is time-consuming and error-prone. Existing solutions often require complex configurations, lack integration, or don't provide the developer experience modern applications demand.

### The Solution
This ecosystem provides:
- **One-line operations** for complex tasks
- **Seamless integration** between all libraries
- **Type-safe** throughout with full TypeScript support
- **Exceptional DX** with intuitive APIs
- **Production-ready** with security best practices
- **Highly customizable** while maintaining simplicity

## Quick Start

### 1. Automated Setup (Recommended)

Use our CLI tool to set up your project with all necessary files and configurations:

```bash
# Run the setup wizard
npx @catalystlabs/firebase-ecosystem fb-eco-setup

# This will create:
# - .env.local with all required environment variables
# - Firebase configuration files (firebase.json, firestore.rules, etc.)
# - middleware.ts for Next.js auth protection
# - Example components showing usage
```

### 2. Install the Package

```bash
# Using bun (recommended)
bun add @catalystlabs/firebase-ecosystem

# Using npm
npm install @catalystlabs/firebase-ecosystem

# Using yarn
yarn add @catalystlabs/firebase-ecosystem
```

### 3. Configure Environment Variables

Fill in your Firebase configuration in `.env.local`:

```env
# Firebase Configuration (from Firebase Console)
NEXT_PUBLIC_FIREBASE_API_KEY=your-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-auth-domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-storage-bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
NEXT_PUBLIC_FIREBASE_APP_ID=your-app-id

# Firebase Admin SDK (for server-side operations)
FIREBASE_ADMIN_PROJECT_ID=your-project-id
FIREBASE_ADMIN_CLIENT_EMAIL=your-service-account-email
FIREBASE_ADMIN_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"

# Optional: Email Provider
EMAIL_PROVIDER=resend
RESEND_API_KEY=your-resend-api-key

# Optional: Audit Logging with ClickHouse
AUDIT_STORAGE=clickhouse
CLICKHOUSE_HOST=http://localhost:8123
CLICKHOUSE_DATABASE=audit_logs
```

### 4. Optional: Database Setup

If using ClickHouse for audit logging:

```bash
# Generate ClickHouse setup script
npx @catalystlabs/firebase-ecosystem fb-eco-setup init-clickhouse

# Apply the generated SQL script
clickhouse-client < clickhouse-setup.sql
```

### 5. Create Initial Admin User

```bash
# Generate admin creation script
npx @catalystlabs/firebase-ecosystem fb-eco-setup create-admin

# Run the script with your admin credentials
node scripts/create-admin.js admin@company.com SecurePassword123!
```

## Library Overview

### 🔐 Auth Library

Complete authentication solution with user management, invitations, roles, and permissions.

```typescript
// One-line user invitation with role
await auth.inviteUser({
  email: 'newuser@company.com',
  role: 'editor',
  department: 'marketing',
  sendEmail: true
});

// Simple permission checks
if (user.hasRole('admin')) {
  // Admin-only code
}
```

[Full Auth Documentation →](./docs/auth/README.md)

### 📧 Email Library

Dead-simple email sending with templates, batch operations, and automatic footer injection.

```typescript
// Send a templated email
await email.send({
  to: 'user@example.com',
  template: 'welcome',
  data: { name: 'John' }
});

// Batch emails with personalization
await email.sendBatch({
  template: 'newsletter',
  recipients: subscribers.map(sub => ({
    to: sub.email,
    data: { name: sub.name }
  }))
});
```

[Full Email Documentation →](./docs/email/README.md)

### 🔔 Notifications Library

Multi-channel notifications with toast, bell, push, and email support.

```typescript
// Show a notification with progress
notifications.show({
  title: 'Upload in progress',
  progress: { value: 45, label: 'Uploading...' },
  avatar: { src: user.photoURL }
});

// Update notification dynamically
notifications.update(id, {
  progress: { value: 100 },
  status: { type: 'completed' }
});
```

[Full Notifications Documentation →](./docs/notifications/README.md)

### 📝 Audit Logging Library

Track all user actions with automatic context capture and powerful querying.

```typescript
// Log an action
await audit.log({
  action: 'document.update',
  resource: 'documents/123',
  metadata: { changes: diff }
});

// Query audit logs
const logs = await audit.query({
  actor: userId,
  action: 'document.*',
  timeRange: { start: lastWeek }
});
```

[Full Audit Documentation →](./docs/audit/README.md)

## Integration Example

Here's how all libraries work together:

```typescript
// User accepts an invitation
const { user } = await auth.acceptInvitation(token);

// Send welcome email
await email.send({
  to: user.email,
  template: 'welcome',
  data: { name: user.displayName }
});

// Show success notification
notifications.show({
  title: 'Welcome aboard!',
  message: 'Your account has been created',
  type: 'success'
});

// Log the event
await audit.log({
  action: 'user.invitation.accepted',
  actor: user.uid,
  metadata: { invitationId: token }
});
```

## Roles, Permissions & User Metadata

### Understanding the Auth System

The auth library uses Firebase Custom Claims to manage roles, permissions, and user metadata. This provides a secure, token-based authorization system.

### User Structure

```typescript
interface User {
  // Firebase Auth fields
  uid: string;
  email: string;
  displayName?: string;
  photoURL?: string;
  
  // Custom claims (stored in JWT token)
  role?: 'admin' | 'editor' | 'viewer' | string;
  permissions?: string[];
  department?: string;
  
  // Additional metadata (stored in Firestore)
  metadata?: {
    firstName?: string;
    lastName?: string;
    phoneNumber?: string;
    address?: string;
    preferences?: Record<string, any>;
    onboardingCompleted?: boolean;
    [key: string]: any;
  };
}
```

### Setting Up Roles and Permissions

#### 1. Define Your Role Hierarchy

```typescript
// lib/auth/config/roles.ts
export const ROLES = {
  ADMIN: 'admin',
  MANAGER: 'manager',
  EDITOR: 'editor',
  VIEWER: 'viewer',
} as const;

export const ROLE_PERMISSIONS = {
  [ROLES.ADMIN]: [
    'users.*',      // All user operations
    'content.*',    // All content operations
    'settings.*',   // All settings
    'audit.read',   // View audit logs
  ],
  [ROLES.MANAGER]: [
    'users.read',
    'users.update',
    'content.*',
    'invites.create',
  ],
  [ROLES.EDITOR]: [
    'content.create',
    'content.update',
    'content.read',
  ],
  [ROLES.VIEWER]: [
    'content.read',
  ],
};
```

#### 2. Assign Roles During User Creation

```typescript
// When inviting a user
await auth.inviteUser({
  email: 'newuser@company.com',
  role: 'editor',
  department: 'marketing',
  permissions: ['content.create', 'content.update'],
  metadata: {
    firstName: 'Jane',
    lastName: 'Doe',
    managerId: currentUser.uid,
  }
});

// When creating user programmatically (server-side)
const user = await admin.auth().createUser({
  email: 'user@example.com',
  password: 'temporaryPassword',
});

await admin.auth().setCustomUserClaims(user.uid, {
  role: 'manager',
  department: 'sales',
  permissions: ROLE_PERMISSIONS.manager,
});
```

#### 3. Check Permissions in Your App

```typescript
// Using hooks
const { user, hasRole, hasPermission } = useAuth();

// Check single role
if (hasRole('admin')) {
  // Show admin UI
}

// Check multiple roles
if (hasRole(['admin', 'manager'])) {
  // Show management UI
}

// Check specific permission
if (hasPermission('users.create')) {
  // Show create user button
}

// Using components
<RequireRole role="admin">
  <AdminDashboard />
</RequireRole>

<RequirePermission permission="content.edit">
  <EditButton />
</RequirePermission>
```

### Managing User Metadata

#### 1. Update User Profile

```typescript
// Update custom claims (server-side only)
await admin.auth().setCustomUserClaims(uid, {
  role: 'manager',
  department: 'engineering',
});

// Update Firestore metadata (client or server)
await updateUserMetadata(user.uid, {
  firstName: 'John',
  lastName: 'Smith',
  preferences: {
    theme: 'dark',
    notifications: true,
  },
  onboardingCompleted: true,
});
```

#### 2. Extend User Metadata

```typescript
// Define your app-specific metadata
interface AppUserMetadata {
  // Profile
  firstName: string;
  lastName: string;
  phoneNumber?: string;
  
  // Organization
  teamId?: string;
  managerId?: string;
  officeLocation?: string;
  
  // Preferences
  preferences: {
    theme: 'light' | 'dark';
    language: string;
    timezone: string;
    emailNotifications: boolean;
  };
  
  // App-specific
  onboardingStep?: number;
  lastActiveProject?: string;
  subscription?: {
    plan: 'free' | 'pro' | 'enterprise';
    validUntil: Date;
  };
}

// Use with type safety
const { user } = useAuth<AppUserMetadata>();
console.log(user.metadata?.subscription?.plan);
```

### Security Rules for Roles

The setup script creates Firestore rules that respect roles:

```javascript
// firestore.rules
function hasRole(role) {
  return request.auth.token.role == role;
}

function hasPermission(permission) {
  return permission in request.auth.token.permissions;
}

// Only admins can read all users
match /users/{userId} {
  allow read: if request.auth.uid == userId || hasRole('admin');
  allow write: if request.auth.uid == userId || hasPermission('users.update');
}
```

### Best Practices

1. **Use Custom Claims Sparingly**: Limited to 1000 bytes total
2. **Store Large Data in Firestore**: Use metadata for extensive user data
3. **Cache Permissions**: The auth library caches claims automatically
4. **Validate Server-Side**: Always verify permissions on the server
5. **Audit Changes**: All permission changes are automatically logged

## Architecture

```
firebase-auth-ecosystem/
├── lib/
│   ├── auth/          # Authentication library
│   ├── email/         # Email service library
│   ├── notifications/ # Notification system
│   └── audit/         # Audit logging library
├── app/               # Next.js application
├── components/        # Shared UI components
└── docs/             # Documentation
```

## Features

### 🔐 Authentication
- User registration and login
- Social authentication providers
- Magic link authentication
- User invitations with pre-assigned roles
- Role-based access control (RBAC)
- Department-based permissions
- Custom claims and permissions
- Session management
- Account linking

### 📧 Email
- Multiple email providers (Resend, SendGrid, SES)
- Template management with variables
- Batch sending with personalization
- Automatic footer injection (HIPAA, unsubscribe)
- Email scheduling
- Delivery tracking
- Error handling and retries

### 🔔 Notifications
- Toast notifications
- Notification center (bell icon)
- Push notifications
- Email notifications
- Real-time updates
- Progress indicators
- Status tracking
- Custom avatars and badges
- Action buttons

### 📝 Audit Logging
- Automatic action tracking
- Actor identification
- Resource tracking
- Metadata storage
- Time-based queries
- Action pattern matching
- Compliance reporting
- Data retention policies

## Security

- **Authentication**: Firebase Authentication with custom claims
- **Authorization**: Role-based and permission-based access control
- **Data Protection**: Automatic PII redaction in logs
- **Compliance**: HIPAA-compliant email footers and audit trails
- **Best Practices**: Security headers, CSRF protection, rate limiting

## Performance

- **Tree-shaking**: Import only what you need
- **Lazy Loading**: Components load on demand
- **Caching**: Smart caching for user data and permissions
- **Batch Operations**: Efficient bulk operations
- **Real-time**: WebSocket connections for live updates

## Development Scripts

### Build and dev scripts
- `bun dev` – start dev server
- `bun build` – bundle application for production
- `bun analyze` – analyzes application bundle

### Testing scripts
- `bun typecheck` – checks TypeScript types
- `bun lint` – runs ESLint
- `bun test` – runs all tests

## Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](./LICENSE) for details.

## Support

- 📚 [Documentation](./docs)
- 💬 [Discussions](https://github.com/yourusername/firebase-auth-ecosystem/discussions)
- 🐛 [Issue Tracker](https://github.com/yourusername/firebase-auth-ecosystem/issues)
- 📧 [Email Support](mailto:support@example.com)

---

Built with ❤️ using Next.js, Firebase, and Mantine UI