Security Guide
Zero Trust and admin controls
How TheChatApp maps identity verification, least privilege, workspace segmentation, monitoring, key management, and data lifecycle controls to the current product architecture.
Control model
TheChatApp treats Zero Trust as a set of product and deployment controls rather than a single feature toggle. The relevant surfaces are identity, session handling, role-based administration, channel and group segmentation, KMS-backed key management, audit trails, retention, export, deletion, backups, and deployment isolation.
| Area | Current construct | Primary risk reduced |
|---|---|---|
| Identity | Local credentials, OIDC SSO where configured, SCIM lifecycle provisioning, server identity pinning, and progressive lockout. | Unverified users, stale accounts, and connection spoofing. |
| Administration | Tenant roles with separate permission flags and live permission-change propagation to connected clients. | Over-broad operator access and privilege drift. |
| Segmentation | Public/private channels, public/private/hidden user groups, group-linked channel privacy, group-scoped roles, and source-aware memberships. | Unnecessary lateral visibility inside the workspace. |
| Encryption | Authenticated realtime encryption, encrypted content/file/database storage, and KMS-backed key protection. | Offline database, file, backup, and tenant-directory exposure. |
| Monitoring | Security and compliance audit stores with classified events and optional hash-chain integrity. | Unnoticed privilege changes, failed auth, key operations, and destructive workflows. |
| Data lifecycle | Retention settings, deleted-file tombstones, encrypted exports, user deletion cleanup, full workspace wipe, legal hold where enabled, and encrypted backups. | Unbounded data exposure and uncontrolled data handling. |
Identity and sessions
Users can authenticate with local workspace credentials, and deployments can add OIDC SSO and SCIM provisioning where those features are enabled. Authentication failures feed progressive lockout and audit events, while successful sessions use random tokens stored as hashes server-side.
Native clients pin the server identity after first trust and warn on unexpected identity changes. Enterprise and portal sessions are tracked so invalidated sessions can be rejected even when a presented token is otherwise well formed.
- OIDC handles authentication and IdP session policy; SCIM handles user and group lifecycle.
- Manual, OIDC, and SCIM group memberships can coexist so IdP automation does not have to overwrite admin decisions.
- Server identity pinning reduces the chance that users silently connect to a replaced or intercepted server.
- Session and token material is protected at rest with platform secure storage on clients and hashed/tracked storage server-side where implemented.
Least-privilege administration
The tenant role model splits administrative ability into focused permissions. A user can be allowed to view the admin console, manage users, manage roles, manage authentication settings, manage server settings, manage privacy/data management, manage backups, manage encryption, view audit logs, manage web chat, view analytics, manage updates, manage the channel directory, or manage storage data management without automatically receiving every other power.
| Permission area | Examples of gated operations |
|---|---|
| User and role administration | Creating users, changing user state, assigning tenant roles, and creating or editing custom roles. |
| Authentication administration | Changing SSO/OIDC and authentication-related workspace settings. |
| Privacy and storage administration | Retention, export, deletion, wipe, storage, and file-data management workflows. |
| Backup administration | Creating, importing, restoring, deleting, scheduling, and rotating local backup keys. |
| Encryption administration | Managing encryption-related settings, backup recovery material, and key-protection status. |
| Audit and analytics | Viewing audit logs, reviewing operational events, and accessing analytics where available. |
| Update administration | Checking for updates and triggering rollback paths where the deployment supports them. |
Workspace segmentation
Channels and user groups are the main segmentation tools. Channels can be public or private. User groups can be public, private, or hidden, and their linked chat channel can separately be public or private.
| Construct | Control behavior |
|---|---|
| Private channels | Membership limits who can read and participate in the channel. |
| Public groups | Visible to everyone in the tenant for discovery and mention workflows. |
| Private groups | Visible to members and users with sufficient permission. |
| Hidden groups | Visible only to users with hidden-group visibility permission; useful for permission or org-structure groups that should not clutter discovery. |
| Group roles | Grant group-scoped powers such as managing members, subgroups, linked channels, mention restrictions, and hidden-group visibility. |
| Group-linked channels | Can mirror group membership and group chat visibility so team membership and conversation access stay aligned. |
Key management
Key-related administration is separate from general administration. Encryption settings, backup recovery workflows, and key-protection review are gated by encryption-management permission and produce audit events.
Server-side workspace keys are protected with KMS-backed wrapping. This helps reduce the risk from copied disks, backups, or tenant directories without the required KMS access.
- KMS credentials and permissions should be scoped, rotated, and monitored as sensitive deployment material.
- Backup recovery material should be stored outside the app and tested as part of restore procedures.
- Backup restore, recovery use, and key-related administrative changes are security-significant audit events.
- KMS-backed key protection reduces offline exposure, but it does not replace endpoint or administrator-account security.
Monitoring and audit
Audit events are classified centrally so new event types must be assigned to the appropriate store. Always-on security logs receive security-bearing events; compliance audit logs receive compliance-relevant events where the deployment is entitled for that store; privilege and sensitive lifecycle events are dual-written.
| Event family | Examples |
|---|---|
| Authentication and authorization | Login success/failure, SSO success/failure, logout, rate limits, unauthorized access, and admin access denied. |
| Cryptographic and protocol failures | Key exchange failure, plaintext packet rejection, signature verification failure, path traversal, and identity spoofing attempts. |
| Privilege and account lifecycle | User creation, role changes, deactivation/reactivation, deletion, SCIM user and group lifecycle, and SCIM API key rotation. |
| Key and backup lifecycle | Backup create/import/delete/restore/rollback, backup schedule changes, backup key rotation, and recovery use. |
| Data lifecycle | Data wipe scheduling/execution/cancellation, retention cleanup, export workflows, and deleted-file handling. |
Where audit integrity protection is enabled, audit entries are linked so later checks can detect tampering with the surviving chain. Retention pruning preserves a boundary value so integrity checks can continue after old entries are removed.
Data lifecycle
Admins can reduce retained data with message/file retention settings, deleted-file handling, user deletion cleanup, and full workspace wipe flows. File deletion keeps enough tombstone context for clients to explain that an attachment was removed while disabling downloads and clearing preview data.
Data export and backup workflows use encrypted archives and separate recovery material. Legal hold and compliance audit features are deployment/entitlement dependent and should be enabled before relying on them for regulated workflows.
Deployment boundaries
Self-hosted administrators control the host, firewall, TLS endpoint, backup location, update cadence, recovery material, and operator access. Cloud-hosted deployments move infrastructure operations to TheChatApp while customer administrators still control users, roles, groups, retention, workspace settings, and data workflows exposed to their plan.