servcraft 0.1.0 → 0.1.3

package/docs/modules/MEDIA-PROCESSING.md

@@ -0,0 +1,281 @@
+# Media Processing Module
+
+Image and video processing with job queue support.
+
+## Features
+
+- **Image Processing** - Resize, crop, format conversion
+- **Video Processing** - Transcoding, thumbnail extraction
+- **Job Queue** - Async processing with status tracking
+- **Concurrency Control** - Limit concurrent processing jobs
+- **Media Info** - Extract metadata from media files
+
+## Usage
+
+### Configuration
+
+```typescript
+import { MediaProcessingService } from 'servcraft/modules/media-processing';
+
+const mediaService = new MediaProcessingService({
+  ffmpegPath: '/usr/bin/ffmpeg',
+  ffprobePath: '/usr/bin/ffprobe',
+  tempDir: './temp',
+  maxConcurrent: 3,
+  gpuAcceleration: false,
+});
+```
+
+### Image Processing
+
+```typescript
+// Process image with operations
+const result = await mediaService.processImage(
+  '/uploads/original.jpg',
+  '/uploads/processed.jpg',
+  [
+    { type: 'resize', width: 800, height: 600 },
+    { type: 'format', format: 'webp', quality: 85 },
+  ]
+);
+
+// Result
+// {
+//   success: true,
+//   outputPath: '/uploads/processed.jpg',
+//   processingTime: 245
+// }
+```
+
+### Video Processing
+
+```typescript
+const result = await mediaService.processVideo(
+  '/uploads/video.mp4',
+  '/uploads/video-720p.mp4',
+  [
+    { type: 'resize', width: 1280, height: 720 },
+    { type: 'codec', video: 'h264', audio: 'aac' },
+    { type: 'bitrate', video: '2000k', audio: '128k' },
+  ]
+);
+```
+
+### Thumbnail Generation
+
+```typescript
+// Generate thumbnail from video
+const result = await mediaService.generateThumbnail(
+  '/uploads/video.mp4',
+  '/uploads/thumbnail.jpg',
+  {
+    width: 320,
+    height: 180,
+    time: '00:00:05', // Extract at 5 seconds
+  }
+);
+
+// Generate thumbnail from image
+const imageThumb = await mediaService.generateThumbnail(
+  '/uploads/image.jpg',
+  '/uploads/thumb.jpg',
+  { width: 150, height: 150, fit: 'cover' }
+);
+```
+
+### Media Info
+
+```typescript
+const info = await mediaService.getMediaInfo('/uploads/video.mp4');
+// {
+//   path: '/uploads/video.mp4',
+//   type: 'video',
+//   format: 'mp4',
+//   size: 15728640,
+//   width: 1920,
+//   height: 1080,
+//   duration: 120.5,
+//   bitrate: 1048576,
+//   codec: { video: 'h264', audio: 'aac' },
+//   fps: 30
+// }
+```
+
+### Job Queue
+
+```typescript
+// Create async job
+const job = await mediaService.createJob(
+  'video',
+  '/uploads/original.mp4',
+  '/uploads/processed.mp4',
+  [
+    { type: 'resize', width: 1280, height: 720 },
+    { type: 'format', format: 'mp4' },
+  ]
+);
+// {
+//   id: 'job-uuid',
+//   status: 'pending',
+//   progress: 0,
+//   createdAt: Date
+// }
+
+// Check job status
+const status = await mediaService.getJob(job.id);
+// {
+//   id: 'job-uuid',
+//   status: 'processing', // pending | processing | completed | failed
+//   progress: 45,
+//   ...
+// }
+
+// Poll until complete
+while (true) {
+  const job = await mediaService.getJob(jobId);
+  if (job.status === 'completed' || job.status === 'failed') {
+    break;
+  }
+  await sleep(1000);
+}
+```
+
+## Image Operations
+
+| Operation | Description | Options |
+|-----------|-------------|---------|
+| `resize` | Resize image | `width`, `height`, `fit` |
+| `crop` | Crop region | `x`, `y`, `width`, `height` |
+| `rotate` | Rotate image | `angle` |
+| `flip` | Flip image | `direction` (horizontal/vertical) |
+| `format` | Convert format | `format`, `quality` |
+| `grayscale` | Convert to grayscale | - |
+| `blur` | Apply blur | `sigma` |
+| `sharpen` | Sharpen image | `sigma` |
+| `watermark` | Add watermark | `image`, `position`, `opacity` |
+
+## Video Operations
+
+| Operation | Description | Options |
+|-----------|-------------|---------|
+| `resize` | Resize video | `width`, `height` |
+| `trim` | Trim video | `start`, `end` |
+| `codec` | Change codec | `video`, `audio` |
+| `bitrate` | Set bitrate | `video`, `audio` |
+| `fps` | Change framerate | `fps` |
+| `format` | Convert format | `format` |
+| `audio` | Audio options | `remove`, `volume` |
+| `watermark` | Add watermark | `image`, `position` |
+
+## Configuration Types
+
+```typescript
+interface MediaProcessingConfig {
+  ffmpegPath?: string;     // Path to ffmpeg
+  ffprobePath?: string;    // Path to ffprobe
+  tempDir?: string;        // Temporary files directory
+  maxConcurrent?: number;  // Max concurrent jobs
+  gpuAcceleration?: boolean; // Use GPU acceleration
+}
+
+interface ProcessingJob {
+  id: string;
+  mediaType: 'image' | 'video';
+  source: string;
+  output: string;
+  operations: Operation[];
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  progress: number;
+  error?: string;
+  createdAt: Date;
+  completedAt?: Date;
+  processingTime?: number;
+}
+
+interface ThumbnailOptions {
+  width?: number;
+  height?: number;
+  time?: string;    // For video: timestamp
+  fit?: 'cover' | 'contain' | 'fill';
+}
+```
+
+## Fastify Integration
+
+```typescript
+import fastifyMultipart from '@fastify/multipart';
+
+fastify.post('/api/process/image', async (request, reply) => {
+  const file = await request.file();
+  const { width, height, format } = request.query;
+
+  const inputPath = `/tmp/${file.filename}`;
+  const outputPath = `/uploads/processed-${Date.now()}.${format || 'jpg'}`;
+
+  // Save uploaded file
+  await saveFile(file, inputPath);
+
+  // Process image
+  const operations = [];
+  if (width || height) {
+    operations.push({ type: 'resize', width: +width, height: +height });
+  }
+  if (format) {
+    operations.push({ type: 'format', format });
+  }
+
+  const result = await mediaService.processImage(inputPath, outputPath, operations);
+
+  return result;
+});
+
+// Async job endpoint
+fastify.post('/api/process/video', async (request, reply) => {
+  const { source, operations } = request.body;
+
+  const job = await mediaService.createJob(
+    'video',
+    source,
+    `/uploads/processed-${Date.now()}.mp4`,
+    operations
+  );
+
+  return { jobId: job.id, status: job.status };
+});
+
+// Job status endpoint
+fastify.get('/api/jobs/:id', async (request, reply) => {
+  const job = await mediaService.getJob(request.params.id);
+
+  if (!job) {
+    return reply.status(404).send({ error: 'Job not found' });
+  }
+
+  return job;
+});
+```
+
+## Production Setup
+
+For production, install required libraries:
+
+```bash
+# Image processing
+npm install sharp
+
+# Video processing
+npm install fluent-ffmpeg
+
+# System dependencies
+apt-get install ffmpeg  # Ubuntu/Debian
+brew install ffmpeg     # macOS
+```
+
+## Best Practices
+
+1. **Async Processing** - Use job queue for large files
+2. **Temp Cleanup** - Clean up temporary files
+3. **Size Limits** - Set appropriate file size limits
+4. **Format Validation** - Validate input formats
+5. **Error Handling** - Handle processing failures gracefully
+6. **Resource Limits** - Control concurrent jobs

package/docs/modules/MFA.md

@@ -0,0 +1,266 @@
+# MFA Module
+
+Multi-Factor Authentication with support for TOTP, SMS, Email, and Backup Codes.
+
+## Features
+
+- **TOTP** - Time-based One-Time Password (Google Authenticator compatible)
+- **SMS** - SMS-based verification codes
+- **Email** - Email-based verification codes
+- **Backup Codes** - Single-use recovery codes
+- **Account Lockout** - Protection against brute-force attacks
+- **Redis Challenges** - Temporary challenge storage with TTL
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      MFA Service                            │
+├─────────────────────────────────────────────────────────────┤
+│  TOTP Setup    │  SMS/Email    │  Backup Codes  │  Verify   │
+└────────┬───────┴───────┬───────┴───────┬────────┴─────┬─────┘
+         │               │               │              │
+         ▼               ▼               ▼              ▼
+┌─────────────┐  ┌─────────────┐  ┌───────────┐  ┌───────────┐
+│   Prisma    │  │    Redis    │  │   Prisma  │  │   Redis   │
+│  (Settings) │  │ (Challenge) │  │  (Codes)  │  │ (Attempts)│
+└─────────────┘  └─────────────┘  └───────────┘  └───────────┘
+```
+
+## Storage
+
+| Data | Storage | TTL |
+|------|---------|-----|
+| User MFA Settings | PostgreSQL (Prisma) | Permanent |
+| TOTP Secrets | PostgreSQL (Prisma) | Permanent |
+| Backup Codes | PostgreSQL (Prisma) | Permanent |
+| Active Challenges | Redis | 5 minutes |
+| Failed Attempts | Redis | 15 minutes |
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { getMFAService, createMFAService } from 'servcraft/modules/mfa';
+
+// Use default configuration
+const mfa = getMFAService();
+
+// Or create with custom config
+const mfa = createMFAService({
+  issuer: 'MyApp',
+  totpWindow: 1,
+  backupCodesCount: 10,
+});
+```
+
+### TOTP Setup
+
+```typescript
+// 1. Initiate TOTP setup
+const setup = await mfa.setupTOTP(userId, userEmail);
+// Returns: { secret, qrCode, manualEntry, uri }
+
+// 2. Display QR code to user (setup.qrCode is a data URL)
+// User scans with Google Authenticator
+
+// 3. Verify initial setup with a code from the app
+const verified = await mfa.verifyTOTPSetup(userId, '123456');
+
+// 4. Later, verify during login
+const result = await mfa.verifyChallenge(userId, '123456', 'totp');
+if (result.success) {
+  // Allow login
+}
+```
+
+### SMS MFA
+
+```typescript
+// 1. Setup SMS (sends verification code)
+await mfa.setupSMS(userId, '+1234567890');
+
+// 2. Verify phone number
+const verified = await mfa.verifySMSSetup(userId, '123456');
+
+// 3. During login, create challenge
+const challenge = await mfa.createChallenge(userId, 'sms');
+// SMS is sent automatically
+
+// 4. Verify the code user received
+const result = await mfa.verifyChallenge(userId, code, 'sms', challenge.id);
+```
+
+### Email MFA
+
+```typescript
+// 1. Setup Email MFA
+await mfa.setupEmail(userId, 'user@example.com');
+
+// 2. Verify email
+const verified = await mfa.verifyEmailSetup(userId, '123456');
+
+// 3. During login
+const challenge = await mfa.createChallenge(userId, 'email');
+const result = await mfa.verifyChallenge(userId, code, 'email', challenge.id);
+```
+
+### Backup Codes
+
+```typescript
+// Generate backup codes (display once to user)
+const { codes, generatedAt } = await mfa.generateBackupCodes(userId);
+// codes: ['ABCD-1234', 'EFGH-5678', ...]
+
+// Check remaining codes
+const remaining = await mfa.getRemainingBackupCodes(userId);
+
+// Verify backup code during login
+const result = await mfa.verifyChallenge(userId, 'ABCD-1234', 'backup_codes');
+// Code is marked as used after successful verification
+```
+
+### User MFA Status
+
+```typescript
+// Check if MFA is enabled
+const enabled = await mfa.isMFAEnabled(userId);
+
+// Get enabled methods
+const methods = await mfa.getEnabledMethods(userId);
+// ['totp', 'backup_codes']
+
+// Get full MFA status
+const userMFA = await mfa.getUserMFA(userId);
+```
+
+### Disable MFA
+
+```typescript
+// Disable TOTP (requires valid code)
+await mfa.disableTOTP(userId, '123456');
+
+// Disable all MFA methods
+await mfa.disableAllMFA(userId);
+```
+
+## Configuration
+
+```typescript
+interface MFAConfig {
+  issuer: string;       // App name shown in authenticator (default: 'Servcraft')
+  totpWindow: number;   // Time window tolerance (default: 1)
+  backupCodesCount: number; // Number of backup codes (default: 10)
+}
+```
+
+## Security Features
+
+### Account Lockout
+
+After 5 failed verification attempts, the account is locked for 15 minutes:
+
+```typescript
+const result = await mfa.verifyChallenge(userId, wrongCode);
+// result: {
+//   success: false,
+//   remainingAttempts: 2,
+//   lockedUntil: undefined
+// }
+
+// After 5 failures:
+// result: {
+//   success: false,
+//   remainingAttempts: 0,
+//   lockedUntil: Date (now + 15 minutes)
+// }
+```
+
+### Challenge Expiration
+
+Challenges expire after 5 minutes:
+
+```typescript
+const challenge = await mfa.createChallenge(userId, 'sms');
+// challenge.expiresAt = now + 5 minutes
+
+// After expiration, verification fails
+const result = await mfa.verifyChallenge(userId, code, 'sms', challenge.id);
+// result.success = false
+```
+
+## API Response Types
+
+```typescript
+interface TOTPSetup {
+  secret: string;      // Raw TOTP secret
+  qrCode: string;      // QR code as data URL
+  manualEntry: string; // Formatted secret for manual entry
+  uri: string;         // otpauth:// URI
+}
+
+interface MFAChallenge {
+  id: string;
+  userId: string;
+  method: MFAMethod;
+  expiresAt: Date;
+  attempts: number;
+  maxAttempts: number;
+  verified: boolean;
+}
+
+interface MFAVerifyResult {
+  success: boolean;
+  method: MFAMethod;
+  remainingAttempts?: number;
+  lockedUntil?: Date;
+}
+
+type MFAMethod = 'totp' | 'sms' | 'email' | 'backup_codes';
+```
+
+## Redis Key Structure
+
+| Key Pattern | Purpose | TTL |
+|-------------|---------|-----|
+| `mfa:challenge:{id}` | Active verification challenge | 5 min |
+| `mfa:attempts:{userId}` | Failed attempt counter | 15 min |
+
+## Integration with Auth Flow
+
+```typescript
+// Login flow with MFA
+async function login(email: string, password: string, mfaCode?: string) {
+  // 1. Verify credentials
+  const user = await authService.verifyCredentials(email, password);
+
+  // 2. Check if MFA is required
+  if (await mfa.isMFAEnabled(user.id)) {
+    if (!mfaCode) {
+      const methods = await mfa.getEnabledMethods(user.id);
+      return { requiresMFA: true, methods };
+    }
+
+    // 3. Verify MFA code
+    const result = await mfa.verifyChallenge(user.id, mfaCode);
+    if (!result.success) {
+      throw new UnauthorizedError('Invalid MFA code', {
+        remainingAttempts: result.remainingAttempts,
+        lockedUntil: result.lockedUntil,
+      });
+    }
+  }
+
+  // 4. Issue tokens
+  return authService.generateTokens(user);
+}
+```
+
+## Best Practices
+
+1. **Always offer backup codes** - Users can lose access to their phone
+2. **Display codes only once** - Show backup codes only when generated
+3. **Log MFA events** - Track setup, verification, and failures for audit
+4. **Rate limit challenges** - Prevent challenge spam with rate limiting
+5. **Secure TOTP secrets** - Encrypt at rest in database