Compliance & Security

Compliance & Security

Message Center is designed for regulated environments — telecoms, financial services, healthcare, and government — where audit trails, access control, and network isolation are baseline requirements, not optional add-ons.

Immutable Audit Log

Every significant action in Message Center is written to a tamper-evident audit log. Records cannot be edited or deleted through any API or UI surface.

What is recorded:

• Campaign lifecycle events (created, approved, rejected, archived, restored, deleted)
• Moderation decisions (who approved or rejected, when, with moderator notes)
• Sender name and revision changes (creation, approval, rejection of each revision)
• Membership changes (invitations, role assignments, role changes, removals)
• Authentication events (login, logout, password changes, account lockout)
• Administrative actions (workspace creation, super admin operations)

What each record captures:

• Who — the authenticated user (ID, email, workspace membership at time of action)
• When — timestamp with millisecond precision
• What — action code, resource type and ID, before/after values for changed fields
• From where — IP address, user agent string, request ID for log correlation

Retention: configurable via the AUDIT_RETENTION_DAYS environment variable (default: 90 days). Retention is enforced by a MongoDB TTL index — no manual cleanup required. Changing the retention period takes effect after running make migrate to recreate the index with the new value.

Resilience: if MongoDB is temporarily unavailable when an event is generated, the event is written to a local fallback file ($TMPDIR/core-admin-audit-fallback.jsonl) and automatically drained back into MongoDB on the next successful write. The drain is streaming — it never accumulates audit lines in memory regardless of file size.

Role-Based Access Control

Every user action is gated by RBAC at the API level, not just in the UI. A user with insufficient permissions will receive 403 Forbidden on the API call, regardless of how they obtained the URL.

The access model:

• Each workspace member has exactly one role: author, moderator, admin, or super admin
• Roles are per-workspace — a user can be an author in one workspace and an admin in another
• The moderator flag is a supplementary permission that can be granted to authors, giving them approve/reject rights without a full role change
• Super admins have cross-workspace visibility but still cannot exceed their own workspace boundaries without explicit membership

Key RBAC enforcement points:

• Creating a campaign requires author, admin, or super_admin role
• Approving/rejecting a campaign requires moderator, admin, super_admin, or is_moderator flag
• Managing workspace members (invite, remove, change roles) requires admin or super_admin
• Deleting a campaign entirely requires super_admin
• Cross-workspace audit visibility requires super_admin

No campaign can bypass the moderation queue — there is no "auto-approve" flag or API shortcut.

mTLS Gateway Authentication

The connection between Message Center and the SMS Gateway uses mutual TLS (mTLS). Both sides present X.509 client certificates, verified against a shared CA.

What this protects:

• An attacker who obtains the service account credentials alone cannot submit campaigns to the gateway — they also need the client certificate and private key
• An attacker who intercepts the mTLS session cannot impersonate the gateway without its server certificate
• All campaign submission traffic is encrypted at the transport layer

Certificate rotation without downtime: Message Center checks the certificate file's last-modified time before each connection. Updated certificates are picked up automatically at the next request — no service restart required.

The connection pool is built with undici (Node.js native HTTP client). Two connection pools exist: a regular pool (60-second body timeout) and a dedicated upload pool (30-minute timeout for large recipient file transfers). This prevents large uploads from occupying connection budget shared with campaign management operations.

Air-Gapped Deployment

Message Center has no external runtime dependencies:

• No external APIs — all functionality works without internet access
• No CDN or cloud asset delivery — static assets are bundled at build time
• No telemetry or analytics calls — no data leaves the installation unless explicitly configured
• No SaaS dependencies — MongoDB, the SMS Gateway stack, and Message Center itself all run on your infrastructure

This makes Message Center suitable for:

• Government and defense deployments with strict network isolation requirements
• Financial institutions prohibited from using cloud-hosted messaging services
• Telecom operators with internal network policies that restrict outbound internet connections
• Healthcare organizations processing patient-identifiable contact data

The only outbound connections Message Center makes are to MongoDB and to the SMS Gateway stack — both of which you control.

Data Residency

Because Message Center is self-hosted, all data — phone numbers, campaign content, audit logs, user credentials, message delivery reports — remains in your infrastructure. No data is sent to third parties.

Specific data categories and where they live:

Password and Session Security

• Passwords are hashed with bcrypt at cost factor 12 — sufficient for current hardware threat models
• Sessions are issued as HTTP-only JWT cookies — inaccessible to JavaScript running in the browser
• Session lifetime is 8 hours by default (configurable via NEXTAUTH_JWT_MAX_AGE)
• Accounts can be blocked by admins (sets blocked_at timestamp); blocked users are rejected at login regardless of valid credentials
• Content Security Policy (CSP) is enforced via Next.js middleware, preventing injection of unauthorized scripts

GDPR and Regional Regulations

Message Center does not make specific legal compliance claims — regulatory applicability depends on your jurisdiction and use case. However, several design decisions support common compliance requirements:

Data minimization: Message Center stores metadata about campaigns (status, timing, sender, creator) but does not re-persist recipient phone numbers in its own database. Numbers are forwarded to the SMS Core which manages its own delivery records.

Audit completeness: The audit log captures who performed what action and when, supporting subject access requests and accountability requirements.

Retention controls: Configurable audit log retention (AUDIT_RETENTION_DAYS) allows you to align with local data retention policies without manual database operations.

Access controls: RBAC and workspace isolation ensure that users can only access data in workspaces they are members of, reducing the blast radius of a compromised account.

No third-party data sharing: The self-hosted model means no recipient data is transmitted to third-party services.

Security Hardening Recommendations

For production deployments:

1. Minimize super admin accounts — use workspace admin roles for routine operations; reserve super admin for system-level tasks
2. Rotate mTLS certificates on a regular schedule (annually at minimum); Message Center picks up the new certificate without restart
3. Rotate NEXTAUTH_SECRET if a server compromise is suspected — this invalidates all existing sessions
4. Monitor the [audit-fallback] sentinel — a growing fallback file indicates MongoDB connectivity issues; address promptly to preserve audit integrity
5. Set AUDIT_RETENTION_DAYS to match your compliance policy before go-live; changing it later requires a migration re-run
6. Review workspace membership periodically — departed employees may retain workspace access until explicitly removed

Next Steps

• Deployment Overview — installation and Kubernetes manifests
• Environment Variables — security-relevant configuration reference
• Roles and Permissions — full RBAC permission matrix