--- title: Security subtitle: Understand the security architecture in OrcaPulse slug: documentation/security --- # Security This page documents the security architecture in OrcaPulse: JWT authentication, password hashing, two-factor authentication, OAuth providers, AES-256 encryption, OTP verification, credit-based authorization, and error logging. ## What security covers OrcaPulse implements multiple layers of security across authentication, encryption, and access control. The system uses JWT-based stateless authentication, bcrypt password hashing, TOTP-based two-factor authentication, AES-256-CBC encryption for secrets and tokens, five OAuth provider integrations, and OTP-based email verification with attempt limiting. ## Authentication OrcaPulse uses JWT Bearer token authentication. When a user logs in or registers, the server generates a signed JWT containing the user ID, email, and role. This token is sent in the Authorization header on every subsequent request and verified by the protect middleware before any controller logic executes. Tokens expire after seven days. For impersonation sessions, the JWT also carries the impersonating admin's ID so actions are traceable back to the actual operator. - JWT signing: tokens are signed with a server-side secret and verified on every authenticated request. - Bearer scheme: tokens are passed via the Authorization header using the Bearer scheme. - Seven-day expiry: tokens expire after seven days, requiring re-authentication. - Impersonation tokens: carry both the target user ID and the admin's ID for audit purposes. ## Password hashing Passwords are hashed using bcrypt before being stored in the database. The User model uses a pre-save hook that automatically hashes the password field whenever it is modified, so plaintext passwords never reach the database. - bcrypt hashing: industry-standard slow hash function resistant to brute force and rainbow table attacks. - Automatic hashing: pre-save hook ensures passwords are always hashed before database writes. - Hidden by default: the password field is excluded from all query results unless explicitly selected. ## Two-factor authentication OrcaPulse supports TOTP-based two-factor authentication using the speakeasy library. Users set up 2FA by scanning a QR code generated by the platform, then verifying a code to confirm the setup. Once enabled, login requires both the password and a valid TOTP code. The 2FA secret is encrypted using AES-256-CBC before storage. During setup, a temporary encrypted secret is stored with a ten-minute expiration. After verification, the secret moves to permanent encrypted storage. - TOTP standard: time-based one-time passwords compatible with authenticator apps. - QR code setup: QR codes are generated server-side for easy authenticator app enrollment. - Encrypted secrets: 2FA secrets are encrypted at rest using AES-256-CBC with per-record initialization vectors. - Window tolerance: code verification allows a one-window tolerance to account for clock skew. ## OAuth providers OrcaPulse supports sign-in through five OAuth providers: Google, Microsoft, GitHub, Apple, and Facebook. Each provider is implemented with its own controller, callback handling, and user account linking. - Google: sign-in, Gmail integration with encrypted refresh tokens, PKCE support. - Microsoft: sign-in with Microsoft accounts via OAuth2 authorization flow. - GitHub: sign-in with GitHub accounts for developer-oriented users. - Apple: sign in with Apple for iOS and web-based authentication. - Facebook: sign-in with Facebook accounts for social-first users. State parameter validation prevents CSRF attacks. Provider-specific IDs prevent duplicate account linking. ## Encryption OrcaPulse uses AES-256-CBC encryption for sensitive data at rest. This includes 2FA secrets, integration API keys for third-party providers, and OAuth refresh tokens. Each encrypted value uses a randomly generated 16-byte initialization vector. - AES-256-CBC: 256-bit encryption in cipher block chaining mode. - Random IVs: each encryption operation generates a fresh random initialization vector. - Integration secrets: API keys for providers like ElevenLabs, Deepgram, OpenAI, and HubSpot are encrypted before storage. - Safe decryption: decryption errors are handled gracefully with null returns instead of application crashes. ## OTP and email verification OrcaPulse uses six-digit one-time passwords for email verification during signup, password reset requests, and account deletion confirmations. - Ten-minute expiry: OTPs are valid for ten minutes after generation. - Attempt limiting: five failed verification attempts invalidate the OTP. - Rate limiting: minimum one-minute gap between OTP generation requests. - Automatic cleanup: expired OTPs are purged every five minutes. ## Credit system authorization Beyond authentication, OrcaPulse uses a credit-based authorization system to gate access to premium operations. The checkCredits middleware verifies sufficient credits before allowing AI calls, workflow runs, SMS sends, email sends, and AI message generation. - Pre-operation check: credit balance is verified before executing any credit-consuming operation. - Automatic deduction: credits are deducted after successful completion, not before. - Auto-recharge: accounts with saved payment methods can automatically purchase credits when balances run low. - Transaction logging: every credit change is recorded with operation type, amount, timestamp, and balance. ## Error handling and logging The platform includes a centralized error handler middleware that catches and logs errors to a database collection. Each error record includes the request IP, user agent, authenticated user ID, request path, error message, and stack trace. - Database logging: errors are persisted to an ErrorLog collection with full request context. - Error normalization: Mongoose validation, duplicate key, and cast errors are mapped to clean HTTP responses. - Non-blocking persistence: error logging is fire-and-forget so it does not delay the error response. ## Current project shape The security implementation covers the core requirements: JWT authentication, bcrypt password hashing, TOTP 2FA, AES-256 encryption, five OAuth providers, OTP verification with rate limiting, credit-based authorization, and centralized error logging. Areas that could be strengthened in the future include general API rate limiting, additional security headers, migration of OTP storage to Redis, JWT refresh token rotation, and input sanitization for XSS protection. ## Next steps After Security, the next useful Operations page is Billing and Plans, which documents how the credit system, Stripe integration, and plan management work together.