Security model (overview)

Goal

Understand the layered security architecture of AngaraBase: which controls exist, how they interact, and how to verify your instance is running in a secure configuration.

Prerequisites

A running AngaraBase instance (local or staging).
SQL session access (pgwire).
Basic understanding of roles and tables in your database.

Security model (layers)

AngaraBase uses a layered defence model. Each layer is independent and composable — no single layer bypass compromises the whole.

Layer 1 — Transport and identity

TLS protects the wire protocol.
Auth modes (trust, scram, cert) control how clients prove identity.
Fail-closed: remote bind without TLS is rejected when tls.require_on_remote_bind = true.

See authentication.md for setup and verification.

Layer 2 — Authorization and data visibility

RBAC (roles, grants, privileges) decides whether an operation is allowed at all.
RLS (row-level security policies) decides which rows are visible or modifiable.
Deny-by-default: enabling RLS without policies blocks all rows, including for the table owner.

See authorization.md for SQL surface and introspection.

Layer 3 — Controlled privilege escalation

Break-glass is the only way to bypass RLS — even SUPERUSER cannot.
Activation requires a mandatory REASON and TTL.
Every query during break-glass generates a dedicated audit entry.

See break-glass.md for the full lifecycle.

Layer 4 — Audit and accountability

Audit chain is append-only and tamper-evident (SHA-256 chain hash).
Scope: auth, DDL, DCL, policy changes, break-glass lifecycle.
DML audit policy: configurable off|allowlist|denylist per table.

See audit.md for configuration and verification.

Layer 5 — Data-at-rest protection

TDE (Transparent Data Encryption) covers pages, WAL, and audit sink.
Fail-closed: missing or invalid key material prevents startup and audit I/O.

See encryption.md for TDE setup and key management.

Layer 6 — Client-encrypted columns (v0)

Server stores ciphertext + metadata (alg, mode, key_id) but never the keys.
DETERMINISTIC mode allows equality predicates; RANDOMIZED rejects server-side predicates (0A000).

See encryption.md for the SQL surface and operator rules.

How features work together

Combination	Behaviour
RBAC + RLS	RBAC decides “is this operation allowed at all”; RLS further restricts “which rows”.
Break-glass + audit	Temporary elevation is accepted only with a reason and full traceability in the audit chain.
TDE + audit	When TDE is enabled, audit bytes on disk are encrypted; `sys.audit_log` remains readable only with the correct key.
Client encryption + SQL bounds	Deterministic mode allows a limited predicate path; randomized mode fail-closes unsupported server-side operations.

Quick security verification

Step 1 — Check effective settings

SELECT name, value
FROM sys.settings
WHERE name LIKE 'tls.%'
 OR name LIKE 'security.%'
 OR name LIKE 'audit.%'
ORDER BY name;

Returns effective security knobs without exposing secrets.

Step 2 — Check security surfaces

SELECT * FROM angara_user_roles() LIMIT 20;
SELECT * FROM angara_table_policies('public.users');
SELECT * FROM angara_break_glass_status();
SELECT * FROM angara_audit_verify_chain();

Validates that key introspection/verification functions are available and responsive.

Step 3 — Validate RLS explanation surface

SELECT * FROM angara_effective_rls_predicate('public.users');

Returns the effective predicate and helps explain row-visibility behaviour.

Expected result

sys.settings shows security knobs without secrets.
Security functions return data (or empty results) without internal errors.
Unsupported operations terminate with an explicit SQLSTATE (0A000, 42501, or 22023) — never a silent bypass.

Troubleshooting

42501 insufficient_privilege on security DDL/ops Check user roles and session context; see authorization.md.
0A000 feature_not_supported in policy/encrypted path This is a bounded contract (not a bug) — use the supported syntax or mode.
TDE enabled but audit/data I/O fails Verify master key presence and correctness; fail-closed is expected. See encryption.md.
Need a bug-report artifact? Follow the bundle steps in ../reference/support.md.

AngaraBook