# ModuleCrafter WA v4 security notes

No internet-facing application can honestly be called unhackable. v4 adds defensive controls for the common risks in this architecture and should still be patched, monitored, backed up and reviewed before high-volume production use.

## Database safety

- Application data access uses `mysql2` parameter placeholders for user-controlled values.
- Dynamic SQL fragments are limited to internal whitelists/migration constants.
- WHMCS modules use WHMCS Capsule query builder rather than interpolating client input into raw SQL.
- Use a dedicated database user that can access only the gateway database.

## Passwords and sessions

- bcrypt cost 12
- 12-128 character password policy
- at least three character classes
- password resets revoke login/SSO sessions
- activation tokens become invalid after password setup
- raw passwords are not stored in gateway tables

## Browser security

- CSRF protection on state-changing dashboard/admin forms
- HttpOnly + Secure cookies in production
- SameSite cookies
- Helmet security headers/CSP
- Express signature hidden
- login throttling
- escaped EJS output for untrusted values

## API credentials

- customer API keys are stored hashed
- raw API tokens are shown only when created
- Meta/provider credentials are encrypted at rest using APP_KEY-derived AES-256-GCM
- provisioning uses a separate secret and trust boundary
- HTTPS is mandatory for production gateway/WHMCS URLs

## Provisioning replay protection

The current `/provisioning/v4` contract requires:

- timestamp validation
- random one-time `X-MC-Nonce`
- HMAC-SHA256 over timestamp + nonce + exact body
- nonce hash persistence and duplicate rejection

v3 remains compatibility-hardened the same way. v1/v2 exist only for backward compatibility and should not be used by new seller modules.

## Worldwide phone input

Phone values are parsed with international numbering metadata. A local-format number requires explicit country context. The WHMCS Sender takes that context from the client's WHMCS ISO country automatically. The gateway does not guess a country solely from an ambiguous local number.

## Media safety

- inline media MIME allowlists
- configurable maximum byte size
- filename sanitization
- random private storage names
- media storage is not Express-static
- Apache `.htaccess` deny defense in depth
- cleanup after terminal send/failure plus stale-file cleanup
- linked-device remote URL fetches block loopback/private/link-local targets to reduce SSRF risk
- WHMCS invoice PDF data is transferred privately rather than publicly hosted

## API diagnostics privacy

`api_request_logs` stores request metadata such as route, HTTP status, request ID, duration, API key identifier and sanitized error text. It does not intentionally store Authorization headers, raw tokens, request bodies, invoice PDFs or message body content.

Customer clear actions remove visible API logs and terminal message history but do not reset quota or delete queued/sending messages. Platform security/admin audit logs are separate so operational cleanup cannot erase administrative accountability.

## Deployment requirements

- current Node.js 20+ security release
- supported MySQL/MariaDB
- supported WHMCS/PHP security releases
- unique 32+ character APP_KEY and PROVISIONING_SECRET
- `.env` permission such as `600`
- HTTPS certificate/AutoSSL
- regular DB and QR-session backups
- `npm audit` review after dependency installation
- test upgrades on staging before replacing a production installation