Governance (CITADEL)

CITADEL is the cryptographic governance engine for the opensecstack ecosystem. Every privileged action across all SIN platforms passes through CITADEL's 5-gate MARSHAL decision engine before execution, and every decision is recorded in an append-only WORM audit chain with cryptographic integrity guarantees.

CITADEL runs on port 8099. Licence: AGPL-3.0.

What is CITADEL?

CITADEL provides the audit and authorisation layer that every other platform depends on. Its four active components are:

• MARSHAL — the 5-gate decision engine that evaluates every governance request (Kerkese)
• WORM chain — the append-only audit log with TripleHash integrity and Ed25519 chain anchors
• NDS — cryptographic separation-of-duties enforcement
• AUGUR — behavioural heuristics for pre-emptive anomaly detection

A fifth component, VIGIL (ecosystem health monitor, GREEN / AMBER / RED), is in design-stage for v2.0.

MARSHAL 5-gate engine

Every governance request — called a Kerkese — flows through five sequential gates. A gate failure stops evaluation immediately and returns the appropriate verdict.

Request → Gate 1 (AuthN) → Gate 2 (AuthZ) → Gate 3 (NDS) → Gate 4 (AUGUR) → Gate 5 (WORM)
                                                                                    ↓
                                                                            Always logged

WORM audit chain

The WORM (Write Once, Read Many) chain is an append-only PostgreSQL table with an immutability trigger that rejects any UPDATE or DELETEstatement. Every entry is cryptographically linked to the previous entry.

TripleHash computes a 128-byte composite digest for each entry using three independent algorithms simultaneously:

"cm"># Per-entry integrity
triple_hash = SHA-256(payload) || SHA-512(payload) || BLAKE3(payload)   "cm"># 128 bytes

"cm"># Chain linkage
chain_hash_n = SHA-256(chain_hash_{n-1} || payload_bytes)

"cm"># Ed25519 chain anchors — written every 100 entries
anchor = Ed25519_sign(master_key, chain_hash_at_entry_n)

All three hash algorithms must be broken simultaneously to forge an entry — an attacker cannot selectively modify only one hash component. The Ed25519 anchor every 100 entries binds the chain to the CITADEL signing key, enabling external notarisation.

After any disaster recovery — even from the coldest backup — the restored log can be cryptographically verified against the original chain anchors. Tampered recovery is detectable.

NDS — separation of duties

Gate 3 (NDS) enforces the separation-of-duties protocol. The constraint is actor.user_id ≠ verifier.user_id and the actor and verifier must belong to different role groups (group_sig_operator vs group_sig_verifier). This is enforced at the cryptographic protocol level, not by policy — a stolen operator credential cannot self-approve a privileged action because it cannot also control the verifier account.

A violation of this constraint causes an immediate HARD_STOPverdict and triggers an automatic P1 incident.

AUGUR behavioural heuristics

Gate 4 (AUGUR) applies pre-emptive behavioural analysis before any action reaches the WORM log. AUGUR reads from a read-only mirror database and does not affect MARSHAL gate decisions itself — it emits advisories (AUG-001 through AUG-009) that surface anomalies before they become violations.

Examples of patterns AUGUR flags:

• Actions submitted outside normal operating hours
• High-frequency submissions from a single actor within a short window
• DATA_EXPORT action requested without a linked open incident

Verdicts

MARSHAL returns one of three verdicts for every Kerkese evaluation:

Benchmarks

Measured on Go 1.24.4, Intel Core i7-7600U. All benchmarks use an in-memory mock store unless noted.

API reference

CITADEL exposes a minimal HTTP API on port 8099.

For how platforms connect to CITADEL, see the CITADEL Integration guide. All connector requests to CITADEL must include an X-Citadel-Signature HMAC-SHA256 header computed over key_id + timestamp + body_hash. Requests outside the ±300-second timestamp window are rejected.