07 — Policy Engine

Deep dive on the governable pillar (flagship §3). Three layers: Cedar for permission decisions, a ReBAC graph for sharing relationships, and governance policies for data rules — all policy-as-code, with simulation to prove properties.

1. Why a real policy engine (not ad-hoc ACLs)

Commodity file apps bolt permissions onto rows and hope. That can’t express “external users may view but not download files tagged confidential, except the legal team, unless under legal hold.” BitVault makes authorization and governance first-class, versioned, testable code — the difference between a toy and an enterprise platform.

2. Evaluation architecture

flowchart TB
    classDef e fill:#fde68a,stroke:#b45309,color:#111827;
    classDef d fill:#bbf7d0,stroke:#15803d,color:#111827;
    classDef c fill:#c7d2fe,stroke:#3730a3,color:#111827;
    req["request (gateway / S3 API / data plane)"]:::e --> pdp["PDP: Policy Decision Point"]:::e
    pdp --> cedar["Cedar (permissions, PARC, deny-by-default)"]:::e
    pdp --> rebac["ReBAC graph (sharing relationships)"]:::e
    pdp --> gov["governance policies (retention/residency/DLP/sharing)"]:::e
    attrs["context: tenant, tags, classification, residency, hold"]:::c --> pdp
    pdp --> dec{"permit / forbid (+ obligations)"}:::d
    cache["Redis decision cache (short TTL, ADR-0010)"]:::c <--> pdp
    git["policies-as-code in Git → deployed (GitOps)"]:::c --> pdp

• PDP on the hot path at the gateway/S3 API (flagship §5), with short-TTL decision caching (ADR-0010); governance checks also run in the data plane (uploads, shares, lifecycle).
• Policies are code in Git, versioned and deployed like everything else (platform/06 GitOps) — reviewable, auditable, rollback-able.

3. Sub-features

POL-1 — Cedar authorization

• Cedar evaluates (principal, action, resource, context) → permit/forbid; deny-by-default, RBAC+ABAC in one language, formally verified, 42–60× faster than Rego. Maps directly to BitVault’s principal/node/action model (ADR-0007/ADR-0010).

POL-2 — ReBAC sharing graph

• A Zanzibar/OpenFGA-style relationship graph: user → editor → folder → (inherited) child, groups, transitive shares — the Google-Drive sharing model RBAC can’t express. Consistency via zookies (avoid the “new enemy” problem on permission changes).

POL-3 — Governance policies as code

• Same engine for data rules: retention, residency (ADR-0020), external-sharing constraints, DLP actions (02 enterprise), classification-based handling. Decisions can carry obligations (“permit, but watermark / log / require MFA”).

POL-4 — Policy simulation & formal analysis

• Because Cedar is formally verifiable, offer “what-if” (would this change alter any decision?) and invariant proofs (“prove no policy permits public read of /legal”) via automated reasoning — prove safety instead of testing by luck.

4. Tradeoffs / Alternatives

• Cedar vs OPA/Rego: Cedar wins on safety/perf/readability for authorization; OPA is more flexible/general (and great for infra policy — K8s admission, platform/). We use Cedar for app authz + governance, and may keep OPA for infra — right tool per layer.
• ReBAC build vs buy: OpenFGA (open-source Zanzibar) is a credible managed-graph option vs a from-scratch graph; either way the modeling is the hard, valuable part.
• PDP placement: embedded (low latency, must distribute policy) vs sidecar/service (central, network hop). We embed on the hot path with cached decisions + GitOps policy distribution.

Scaling: decision caching + ReBAC graph sharding by tenant; policy bundles distributed via GitOps; simulation runs offline (CI gate on policy PRs).