> For the complete documentation index, see [llms.txt](https://docs.oomus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oomus.org/security/overview.md).

# Security overview

Security is a fundamental design principle of Oomus CampaignID, not an afterthought layer. This page presents the platform's guiding principles and security mechanisms.

***

## Core principles

### Least privilege

Each component, user, and process only accesses the resources strictly necessary for its role:

* The DHIS2 accounts used by Oomus have **read-only**
* The generation workers cannot access billing data
* Standard users cannot modify system configurations

### Secrets outside the code

No sensitive information (keys, passwords, tokens) is ever stored in source code or Git repositories. All sensitive values are managed through environment variables and dedicated secrets managers.

### Strict file validation

All uploaded files (logos, templates) are validated at multiple levels:

* MIME type and magic bytes verification
* Maximum size check
* Content analysis (no disguised executable)
* Storage in an area isolated from the application code

### Environment isolation

Development, staging, and production environments are strictly isolated. Production data is never used in test environments.

***

## Authentication

Oomus CampaignID uses **JWT (JSON Web Token)** tokens with a short lifespan and automatic rotation:

* Short-lived access tokens — automatic renewal via refresh token
* **Two-factor authentication (2FA)** via TOTP (Google Authenticator, Authy) available for all accounts
* **Brute-force protection** : automatic lockout after repeated failed attempts
* **Session revocation** : individual or global logout (all devices)
* **Token versioning** : a password change immediately invalidates all active sessions

### Passwords

All user passwords are hashed with an adaptive hashing function compliant with NIST recommendations:

* Never stored in plain text, never logged
* Enhanced complexity policy applied at signup and on change
* Verification against breached password databases (via k-anonymity protocol)

***

## Authorization — institutional RBAC

Oomus CampaignID implements role-based access control (**RBAC**) at the institutional level.

### Standard roles

| Role                 | Description                          |
| -------------------- | ------------------------------------ |
| **Super Admin**      | Global platform administrator        |
| **Program Admin**    | Full management of a program         |
| **Operational user** | Viewing, job launching, distribution |

### Custom roles

On the National Campaign and Sovereign Enterprise plans, custom roles can be created with granular permissions on campaigns, generation, distribution, users, billing, and analytics.

### Access scope

Each user is associated with **a program** and cannot access data from other programs — strict data isolation by organization.

***

## Immutable audit trail

All significant actions performed on the platform are recorded in an **immutable audit trail** :

* Logins and authentication attempts
* Campaign and configuration changes
* Generation launches and distributions
* Role and plan changes
* MPI identity operations

**Features:** immutable, UTC timestamped, linked to the source IP, non-repudiable.

***

## Multi-level approval workflows

High-impact operations require explicit approval:

* **Simulation → Provisioning** : admin approval workflow
* **MPI merge** : requires written justification (audited)
* **Balance top-up** : request submitted for validation

***

## Protection of data in transit and at rest

* **In transit** : HTTPS/TLS recommended for all communications. HSTS headers enabled in production.
* **At rest** : PostgreSQL data with volume-level encryption recommended
* **Generated files** : S3-compatible object storage, access via time-limited signed URLs
* **Network isolation** : databases and internal services with no exposed external port
* **Security headers** : Content-Security-Policy, X-Frame-Options, X-Content-Type-Options on all API responses

***

## Next steps

* [Cryptographic guarantees](/security/cryptographic-guarantees.md) — Data security properties
* [Offline verification](/security/offline-verification.md) — Field portal security
* [Data protection](/security/data-protection.md) — Personal data management
* [Legal compliance](/compliance/legal-compliance.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.oomus.org/security/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.