> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wede.pt/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

> Technical security architecture, compliance alignment, and what Wede guarantees per vertical

## Architecture Overview

Wede is designed for regulated industries where security is not a feature - it is a precondition. Every architectural decision is made with the assumption that the data being transported is sensitive, the operations are critical, and the audit trail is legally required.

<Info>
  Wede transports payloads but never inspects them. Your data is encrypted by you before it reaches Wede. We handle delivery, integrity, and reconciliation - not content.
</Info>

***

## Authentication and Access

### API Keys

Every tenant receives two API keys at onboarding - one for production (`wede_live_`), one for sandbox (`wede_test_`). Keys are:

* Stored as **bcrypt hashes** - never in plain text, not even internally
* Validated on every request with constant-time comparison
* Scopeable per integration or environment
* Rotatable at any time via `POST /v1/tenant/api-keys/rotate` with a configurable grace period

```bash theme={null}
POST /v1/tenant/api-keys/rotate
{
  "environment": "production",
  "grace_hours": 24
}
```

The previous key remains valid for the configured grace period, allowing zero-downtime rotation.

### JWT Sessions

User sessions are issued as signed JWT tokens:

* Signed with a secret stored in **GCP Secret Manager** - never in environment variables
* Expire after **8 hours**
* Include a `token_version` claim tied to the user record
* Immediately invalidated when a user is suspended or their session is revoked - no waiting for expiry

### Brute Force Protection

Login attempts are rate-limited at two levels:

* **Global rate limit** - per tenant, configurable per plan
* **Per-account lockout** - after 5 consecutive failed attempts, the account is locked for 15 minutes. The user can unlock immediately via password reset without admin intervention.

***

## Transport Security

All communication with the Wede API is encrypted over **TLS 1.2+**. Unencrypted HTTP is rejected at the infrastructure level - not redirected.

This applies to all delivery channels: REST, structured protocols, voice, LoRa, and satellite. Each channel has independent transport-level security appropriate to its protocol.

***

## Role-Based Access Control

Wede implements a **7-level cascading RBAC** model. No level can grant permissions it does not itself hold. Privilege escalation is mathematically impossible.

| Level | Role                     | Scope                                                                 | Can configure?  |
| ----- | ------------------------ | --------------------------------------------------------------------- | --------------- |
| 1     | `wede_global_admin`      | Full platform — infrastructure, billing, all tenants                  | Yes             |
| 2     | `wede_tech_ops`          | Technical operations — no billing, no tenant config                   | Yes (technical) |
| 3     | `country_admin`          | Regional management — assigned countries only                         | Yes (regional)  |
| 4     | `company_admin`          | Full tenant — teams, users, billing view, dispatch                    | Yes             |
| 5     | `company_tech`           | Technical — SDK, API keys, integrations, teams, dispatch              | Yes             |
| 6     | `operational_supervisor` | Dispatch console, missions, backup — **executes, does not configure** | No              |
| 7     | `field_operator`         | Mission receipt, status updates, backup requests — **executes only**  | No              |

<Warning>
  `operational_supervisor` and `field_operator` are execution roles — they dispatch teams, update mission status, and request backup. They cannot create or modify parsers, catalogs, teams, or tenant settings. Assign `company_tech` or `company_admin` for configuration access.
</Warning>

<Info>
  `wede_global_admin`, `wede_tech_ops`, and `country_admin` are above-tenant roles — they do not belong to any specific organisation and **cannot dispatch teams**. Dispatch is always a tenant-level operation.
</Info>

Every API route enforces the minimum required permission. Attempting to access a route without the required permission returns `403 Forbidden` — the route does not exist from the caller's perspective.

### Cascade Principle

* Wede Global Admin defines the full universe of available features
* Each level receives a subset of the level above
* Delegation is explicit — not included by default
* Privilege escalation is structurally impossible — no level can grant what it does not hold

***

## Audit Trail

Every mutating operation in Wede is written to an **immutable audit log**:

* User identity and role
* Action performed (create, update, delete, dispatch, suspend)
* Resource type and ID
* Timestamp (UTC)
* IP address
* User agent
* Request ID for end-to-end traceability

Covered operations include: authentication, events, sync, webhooks, teams, dispatch, missions, parsers, users, zones, and tenant configuration changes.

Audit logs are available via the API (`GET /v1/audit`) and the dashboard. They cannot be modified or deleted - not even by Wede Global Admin.

***

## Data Isolation

Each tenant's data is logically isolated at the database level. Every query is scoped to `tenant_id`. Cross-tenant data access is structurally impossible via the API - not just access-controlled.

`country_admin` roles operate across tenants within their assigned countries via explicit `country_admin_assignments` - there is no implicit access.

***

## Payload Opacity

<Warning>
  Wede never reads, stores, or inspects the content of your event payloads. Encrypt before sending.
</Warning>

The `payload` field in every event is treated as an opaque binary blob. Wede transports it, preserves its integrity via SHA-256 hash, and delivers it - without ever accessing its content. This is by design and enforced at the architectural level.

This means Wede is compatible with end-to-end encrypted workflows in healthcare, banking, and government without any changes.

***

## Infrastructure

* **Cloud provider**: GCP europe-west1 (Belgium)
* **Database**: PostgreSQL 16 - Cloud SQL with automated backups
* **Secrets**: GCP Secret Manager - all credentials, keys, and tokens
* **Container runtime**: Cloud Run - auto-scaling, no persistent state
* **CDN and DNS**: Cloudflare - DDoS protection, global PoPs

All infrastructure is within the EU. Data does not leave the EU unless explicitly configured for a multi-region deployment.

***

## Compliance Alignment by Vertical

### Banking and Fintech - DORA

The EU Digital Operational Resilience Act (DORA) applies to financial entities and their ICT providers. Wede is designed as a DORA-aligned ICT layer:

| DORA Requirement          | Wede Implementation                                                         |
| ------------------------- | --------------------------------------------------------------------------- |
| ICT risk management       | Multi-channel fallback, zone connectivity monitoring, real-time alerts      |
| Incident reporting        | Immutable audit log, webhook notifications, structured incident lifecycle   |
| Operational continuity    | Offline-first SDK - operations continue without internet                    |
| Third-party ICT oversight | Full API documentation, contractual SLAs, audit trail exportable to PDF/CSV |
| Resilience testing        | Sandbox environment per tenant, connectivity simulation endpoints           |
| Data integrity            | SHA-256 hash per event, idempotency enforcement, reconciliation engine      |
| Access controls           | 7-level RBAC, API key rotation, JWT revocation, brute force protection      |
| Audit trail               | Immutable logs with user, action, timestamp, IP, request ID                 |

<Note>
  Wede operates as an ICT third-party provider under DORA Article 28. Full contractual documentation is available on request.
</Note>

### Healthcare - HIPAA and MDR

For healthcare deployments, Wede aligns with HIPAA Technical Safeguards (45 CFR § 164.312):

| HIPAA Safeguard                      | Wede Implementation                                                       |
| ------------------------------------ | ------------------------------------------------------------------------- |
| Access Controls (§ 164.312(a))       | RBAC with unique user IDs, automatic session expiry, role-scoped API keys |
| Audit Controls (§ 164.312(b))        | Session-level and operation-level audit logs, tamper-evident, exportable  |
| Integrity Controls (§ 164.312(c))    | SHA-256 per event, idempotency key, reconciliation without data loss      |
| Transmission Security (§ 164.312(e)) | TLS 1.2+ enforced, no unencrypted fallback paths                          |
| Authentication                       | JWT with token versioning, bcrypt passwords, brute force lockout          |

Wede does not store ePHI - payloads are opaque and pass through encrypted. This significantly reduces the compliance surface for healthcare integrators.

<Note>
  The 2025 proposed HIPAA Security Rule updates (expected final May 2026) make encryption at rest and in transit, MFA, and audit controls mandatory without exception. Wede meets all proposed requirements.
</Note>

### Government and Critical Infrastructure - NIS2

For government and infrastructure deployments:

| NIS2 Requirement      | Wede Implementation                                                          |
| --------------------- | ---------------------------------------------------------------------------- |
| Risk management       | Multi-layer resilience, zone-level connectivity monitoring                   |
| Incident handling     | Structured lifecycle, webhook notifications, audit export                    |
| Business continuity   | Offline-first SDK, multi-channel fallback, data sync on reconnection         |
| Supply chain security | Private core repository, public SDK only - no proprietary algorithm exposure |
| Access control        | Cascading RBAC, session revocation, API key rotation                         |
| Cryptography          | TLS 1.2+, bcrypt, SHA-256, secrets in GCP Secret Manager                     |
| Data residency        | Configurable per country and per zone - EU by default                        |

***

## What Wede Does Not Do

To be explicit about scope:

* Wede does **not** store payload content - payloads are opaque
* Wede does **not** provide MFA for end users - this is your responsibility at the application layer
* Wede does **not** perform penetration testing on your integration - you are responsible for your own security posture
* Wede does **not** guarantee anonymisation - if your payload contains PII, you are responsible for encrypting it before sending

***

## Security Contact

To report a security vulnerability: [security@wede.pt](mailto:security@wede.pt)

We respond to all security reports within 24 hours. We do not operate a public bug bounty programme at this time.