Security Overview
Causet’s security model is layered. Authentication controls who can call the API. Tenant isolation controls what data each tenant can access. Event validation prevents malformed or unauthorized state changes. Secrets management protects credentials. The ledger provides an audit trail.
Security layers
1. Authentication
Two authentication mechanisms are in use:
Clerk JWT — used by the web control plane (causet-cloud-control-plane) and the SaaS API (causet-saas-cloud). Users authenticate through Clerk and receive a JWT that carries their platform, application, and fork context. The runtime and query service validate these JWTs.
API keys — used for server-to-server communication. Application backends call the runtime and query service with an API key scoped to a platform. API keys are issued through the SaaS API and stored hashed.
2. Tenant isolation
Each fork of an application has an isolated PostgreSQL schema. Data from one tenant cannot be accessed by another through normal application code paths. All reads and writes are scoped to the authenticated tenant’s schema via SET LOCAL search_path.
3. Event validation
The compiler validates your DSL at compile time — undefined event types, missing required fields, and invalid expressions are caught before deployment. At runtime, the rules engine validates intent payloads against the action’s declared input schema. Preflight rules provide additional business-logic validation.
See Event Validation.
4. PII handling
The ledger is append-only. Event payloads written to the ledger cannot be deleted. This creates compliance obligations for applications that handle personal data. Design events to contain opaque IDs rather than PII values.
See PII Handling.
5. Secrets management
In production, credentials (database passwords, Clerk secret key, API keys) are stored in AWS Secrets Manager and injected at container startup. Do not put secrets in Docker images, IR artifacts, or version control.
See Secrets Management.
6. Audit trail
The event ledger provides a tamper-evident, append-only audit trail of all state changes. Every action that modifies entity state produces a ledger event with full payload, timestamp, entity ID, and correlation ID.
See Audit Log.
Threat model
| Threat | Mitigation |
|---|---|
| Unauthorized API access | Clerk JWT or API key required on all endpoints |
| Cross-tenant data access | Per-fork PostgreSQL schema, search_path scoped per request |
| Malformed event payloads | Compiler schema validation + runtime input validation |
| Credential exposure | Secrets Manager, no secrets in code or IR artifacts |
| Retroactive event modification | Append-only ledger, no UPDATE/DELETE on ledger_events |
| PII leakage via ledger | Design guidance: IDs not values in event payloads |
| Insider threat (DB admin) | Access logging, least-privilege IAM roles |
Section pages
- Event Validation — compiler and runtime validation, preflight rules
- Multi-Tenancy Security — per-fork schema isolation, JWT context
- Secrets Management — AWS Secrets Manager, local .env files
- PII Handling — keeping PII out of the ledger, GDPR considerations
- Audit Log — ledger as audit trail, querying, compliance