This document summarizes the security model for the current WhatsApp Web Tool deployment.

• Primary web authentication uses JWT-backed sessions.
• In production, the session token is carried by an HttpOnly cookie.
• The frontend stores the user object locally, not the session secret.

The platform currently has two API-key ownership models:

1. Platform-managed keys

   • managed by admins in system settings
   • intended for platform-wide integrations

2. User-owned messaging keys

   • generated in the user dashboard
   • scoped to the owning user
   • route messaging activity through that user's isolated WhatsApp session

x-simple-auth exists only for non-production and should not be relied on for deployed environments.

• The root admin WhatsApp session is isolated from user sessions.
• It uses its own persisted auth directory and runtime state.
• It is intended for backend/admin operations only.

• Each user session has its own persisted LocalAuth identity.
• User sessions are restored independently from the root session.
• Browser launches are serialized to reduce profile lock races.
• Startup delay gives the root session priority before user session warmup.

• Root and user session lifecycle events are recorded separately.
• Users can view their own session logs.
• Admins can inspect root or targeted user session lifecycle events through the backend session log endpoint and admin tools.

Current roles include:

• SuperAdmin
• Admin
• Editor
• User
• MessagingOnly

Route protection is enforced with authentication middleware plus checkRole(...).

• Admins can manage user WhatsApp instances without reading user API keys.
• User API key CRUD is scoped to the authenticated owner.
• Message history is queryable per user for self-service logs and globally for admin operations.

External media URLs are validated before fetch:

• protocol must be http or https
• DNS resolution is checked
• private/reserved address ranges are rejected

The system records:

• message send history
• API key labels when available
• session lifecycle events

These logs support operations and incident review without exposing secrets unnecessarily in the normal UI.

• Passwords are hashed with bcryptjs
• The platform enforces a strong password policy

WhatsApp OTP is used for sensitive operations including:

• registration
• phone updates
• password changes
• vote verification flows

• Database access uses parameterized queries.
• Runtime configuration prefers database-backed system_settings.
• Landing page custom HTML is sanitized on write and on render.
• .wwebjs_auth should only be removed when intentionally resetting WhatsApp login state.

Last updated: 2026-05-22