Kavalan API Workflow

Complete Security Architecture & API Documentation

🔐 Security Architecture Overview

Security Features

  • JWT-based authentication with httpOnly cookies
  • AES-256 encryption for password storage
  • PBKDF2 key derivation with salt
  • Rate limiting (15 requests/minute)
  • Google Drive backup integration
  • Deletion password protection

Data Flow

  1. 1. User login → JWT token generation
  2. 2. Middleware validates token on each request
  3. 3. Passwords encrypted client-side before storage
  4. 4. Data backed up to Google Drive automatically
  5. 5. Deletion requires special password

🚀 API Endpoints Workflow

Authentication APIs

POST /api/auth/login

Purpose: User authentication and session creation

Input: email, password, rememberMe

Process:

  1. • Validates user credentials against database
  2. • Checks if user is verified
  3. • Generates JWT token with user ID and email
  4. • Sets httpOnly cookie with secure flags
  5. • Returns user data (excluding password)
✅ Advantages
  • • Secure cookie storage
  • • Password hashing with bcrypt
  • • Remember me functionality
  • • User verification check
⚠️ Disadvantages
  • • Single point of failure (But Google Drive is a good backup)
  • • No 2FA support (Prompts master password for every action)
  • • Limited session management (For High Security)

GET /api/auth/logout

Purpose: Session termination and cleanup

Process:

  1. • Deletes authentication cookie
  2. • Redirects to login page

GET /api/auth/verify-user

Purpose: Validate current session and get user data

Process:

  1. • Extracts JWT token from cookie
  2. • Verifies token signature
  3. • Fetches current user from database
  4. • Returns user data (excluding password)

📁 Folder Management APIs

GET /api/folders

Purpose: Retrieve user's password folders

Security: Requires x-user-id header (set by middleware)

Process:

  1. • Validates user ID from JWT token
  2. • Queries database for user's folders
  3. • Returns encrypted folder data

POST /api/folders

Purpose: Create new password folder

Input: name, salt, hashedKey

Process:

  1. • Validates user ID and folder name
  2. • Checks for duplicate folder names
  3. • Stores encrypted folder data
  4. • Creates Google Drive backup
✅ Advantages
  • • Automatic backup to Google Drive
  • • Duplicate prevention
  • • Encrypted folder keys
⚠️ Disadvantages
  • • Depends on Google Drive API
  • • No folder sharing

DELETE /api/folders/[id]

Purpose: Delete password folder

Security: Requires deletion password

Process:

  1. • Validates deletion password
  2. • Confirms folder ownership
  3. • Removes from database

🔑 Password Management APIs

GET /api/passwords?folder=[folderId]

Purpose: Retrieve passwords from specific folder

Security: Requires folder parameter and user validation

Process:

  1. • Validates user ID and folder access
  2. • Returns encrypted password data
  3. • Client-side decryption required

POST /api/passwords

Purpose: Store new password entry

Input: site, username, encryptedPassword, iv, folder

Process:

  1. • Validates user and folder access
  2. • Stores AES-encrypted password
  3. • Creates Google Drive backup
  4. • Returns password entry with ID
✅ Advantages
  • • Client-side encryption
  • • Automatic backup
  • • IV-based encryption
⚠️ Disadvantages
  • • No password strength validation
  • • Limited metadata storage

DELETE /api/passwords/[id]

Purpose: Remove password entry

Security: Requires deletion password

Process:

  1. • Validates deletion password
  2. • Confirms password ownership
  3. • Removes from database

🛡️ Security Analysis

Strengths

  • End-to-End Encryption: Passwords are encrypted client-side before transmission
  • Secure Authentication: JWT tokens with httpOnly cookies prevent XSS attacks
  • Rate Limiting: Prevents brute force attacks with 15 requests/minute limit
  • Backup System: Automatic Google Drive backup ensures data persistence
  • Deletion Protection: Special passwords required for destructive operations

Vulnerabilities

  • No 2FA: Single-factor authentication only
  • Client-Side Key Management: Encryption keys stored in browser memory
  • Google Drive Dependency: Backup system depends on external service
  • No Audit Logging: No tracking of password access or modifications
  • Limited Session Management: No ability to revoke sessions remotely

💡 Security Recommendations

Immediate Improvements

  • • Implement 2FA with TOTP
  • • Add audit logging
  • • Implement session management
  • • Add password strength validation

Advanced Features

  • • Hardware security module (HSM)
  • • Zero-knowledge architecture
  • • Biometric authentication
  • • Secure key escrow

Infrastructure

  • • Implement API versioning
  • • Add request/response validation
  • • Implement proper error handling
  • • Add health check endpoints