Skip to main content

olai_datafusion_policy/
session.rs

1//! The customer-facing entry point: [`PolicyExtension::builder`].
2//!
3//! One builder assembles the pieces a policy integration needs — a
4//! [`PolicyEngine`], a [`PrincipalProvider`], and an [`EvalContextProvider`] — and
5//! installs them on a `SessionState` by wrapping its [`QueryPlanner`] with a
6//! [`PolicyQueryPlanner`]. This is the policy analog of
7//! `datafusion_openlineage`'s `OpenLineage::builder(…).instrument(state)`: the
8//! host composes it onto a session without knowing the enforcement internals,
9//! and it nests with other query-planner-wrapping extensions (lineage) because
10//! each wrapper delegates its physical phase to the next planner in the chain.
11//!
12//! Per-request state (the principal, the catalog facts / taint ledger) flows in
13//! through `SessionConfig` typed extensions the host attaches, read back by the
14//! provider traits — so the crate never depends on host types. The default
15//! providers ([`SessionConfigPrincipalProvider`], [`SessionConfigEvalContextProvider`])
16//! read the extension newtypes this crate owns ([`PrincipalExt`],
17//! [`CatalogFactSinkExt`], and — under `fgac` — [`FactStoreExt`]); the host
18//! populates them.
19
20use std::sync::Arc;
21
22use async_trait::async_trait;
23use datafusion::catalog::Session;
24use datafusion::execution::SessionStateBuilder;
25use datafusion::execution::context::{QueryPlanner, SessionContext, SessionState};
26use datafusion::logical_expr::LogicalPlan;
27
28use datafusion_common::{Result, exec_err};
29
30use crate::engine::{PolicyEngine, StaticPolicyEngine};
31use crate::facts::{CatalogFactSink, EvalContext};
32use crate::governance::Posture;
33use crate::principal::PrincipalIdentity;
34use crate::rule::PolicyQueryPlanner;
35use crate::types::Decision;
36
37/// The `SessionConfig` extension carrying the per-request principal.
38///
39/// A distinct newtype so `SessionConfig::get_extension` (which keys by
40/// `TypeId`) resolves it unambiguously. The host attaches it (see
41/// `with_principal`); [`SessionConfigPrincipalProvider`] reads it back.
42#[derive(Debug, Clone)]
43pub struct PrincipalExt(pub PrincipalIdentity);
44
45/// The `SessionConfig` extension carrying the per-query [`CatalogFactSink`] the
46/// catalog writes resource facts into and the policy layer reads.
47#[derive(Debug, Clone, Default)]
48pub struct CatalogFactSinkExt(pub CatalogFactSink);
49
50/// The `SessionConfig` extension carrying the session's [`PolicyEngine`], so
51/// the engine is discoverable from config on every host regardless of which
52/// enforcement tier fires first: [`PolicyBuilder::instrument`] sets it, and
53/// the provider-tier seam
54/// (`govern_provider_from_config`, under `fgac`) reads it back at
55/// table-resolution time.
56#[derive(Debug, Clone)]
57pub struct PolicyEngineExt(pub Arc<dyn PolicyEngine>);
58
59/// The `SessionConfig` extension carrying the session's taint ledger, attached
60/// to the per-query state so the policy layer can build the [`EvalContext`].
61#[cfg(feature = "fgac")]
62#[derive(Clone)]
63pub struct FactStoreExt(pub Arc<dyn crate::FactStore>);
64
65/// The `SessionConfig` extension carrying the catalog function resolver, so the
66/// governance PEP can turn a policy-referenced masking / row-filter function name
67/// into a callable [`ScalarUDF`](datafusion::logical_expr::ScalarUDF).
68#[cfg(feature = "fgac")]
69#[derive(Clone)]
70pub struct FunctionResolverExt(pub Arc<dyn crate::CatalogFunctionResolver>);
71
72/// Resolves the principal a query runs as, from the planning [`Session`].
73///
74/// Mirrors `datafusion_openlineage`'s `LineageContextProvider`: the provider
75/// only sees a `&dyn Session`, so per-request data reaches it through a typed
76/// `SessionConfig` extension. The default [`SessionConfigPrincipalProvider`]
77/// reads the [`PrincipalExt`] extension; a host can supply its own.
78#[async_trait]
79pub trait PrincipalProvider: std::fmt::Debug + Send + Sync {
80    async fn principal(&self, state: &dyn Session) -> Option<PrincipalIdentity>;
81}
82
83/// Assembles the per-query [`EvalContext`] from the planning [`Session`].
84///
85/// The policy layer needs the catalog facts, the correlation id, and (under
86/// `fgac`) the taint ledger — none of which live on the plan. This trait
87/// is the seam that gathers them; the default
88/// [`SessionConfigEvalContextProvider`] reads them from `SessionConfig`
89/// extensions the host attached.
90#[async_trait]
91pub trait EvalContextProvider: std::fmt::Debug + Send + Sync {
92    async fn eval_context(&self, state: &dyn Session) -> EvalContext;
93}
94
95/// A [`PrincipalProvider`] that reads the [`PrincipalIdentity`] attached to the
96/// session's `SessionConfig` as a [`PrincipalExt`] extension.
97#[derive(Debug, Default)]
98pub struct SessionConfigPrincipalProvider;
99
100#[async_trait]
101impl PrincipalProvider for SessionConfigPrincipalProvider {
102    async fn principal(&self, state: &dyn Session) -> Option<PrincipalIdentity> {
103        state
104            .config()
105            .get_extension::<PrincipalExt>()
106            .map(|ext| ext.0.clone())
107    }
108}
109
110/// An [`EvalContextProvider`] that assembles the [`EvalContext`] from the
111/// session's `SessionConfig` extensions: the catalog fact sink and (under
112/// `fgac`) the correlation id + taint ledger. The correlation id is the
113/// session id, stable per connection.
114#[derive(Debug, Default)]
115pub struct SessionConfigEvalContextProvider;
116
117#[async_trait]
118impl EvalContextProvider for SessionConfigEvalContextProvider {
119    async fn eval_context(&self, state: &dyn Session) -> EvalContext {
120        let catalog_facts = state
121            .config()
122            .get_extension::<CatalogFactSinkExt>()
123            .map(|ext| ext.0.clone())
124            .unwrap_or_default();
125
126        #[cfg(feature = "fgac")]
127        {
128            EvalContext {
129                catalog_facts,
130                correlation_id: Some(state.session_id().to_string()),
131                fact_store: state
132                    .config()
133                    .get_extension::<FactStoreExt>()
134                    .map(|ext| ext.0.clone()),
135                function_resolver: state
136                    .config()
137                    .get_extension::<FunctionResolverExt>()
138                    .map(|ext| ext.0.clone()),
139            }
140        }
141        #[cfg(not(feature = "fgac"))]
142        {
143            EvalContext {
144                catalog_facts,
145                correlation_id: Some(state.session_id().to_string()),
146            }
147        }
148    }
149}
150
151/// Inject fine-grained governance (row filters + column masks) into a plan
152/// before optimization.
153///
154/// With the `fgac` feature this delegates to [`crate::govern::govern_plan`];
155/// without it (the default), it is a no-op that returns the plan unchanged — the
156/// coarse access gate still applies.
157#[cfg(feature = "fgac")]
158async fn govern_plan(
159    plan: &LogicalPlan,
160    policy: &dyn PolicyEngine,
161    principal: &PrincipalIdentity,
162    eval: &EvalContext,
163) -> Result<LogicalPlan> {
164    crate::govern::govern_plan(plan, policy, principal, eval).await
165}
166
167#[cfg(not(feature = "fgac"))]
168async fn govern_plan(
169    plan: &LogicalPlan,
170    _policy: &dyn PolicyEngine,
171    _principal: &PrincipalIdentity,
172    _eval: &EvalContext,
173) -> Result<LogicalPlan> {
174    Ok(plan.clone())
175}
176
177/// Govern `plan` (row filters + column masks), then gate the optimized plan on
178/// the coarse access policy — the shared enforcement sequence.
179///
180/// Returns the *governed* logical plan on `Allow` (the caller may execute or
181/// further plan it), or an authorization error on `Deny`. This is the single
182/// code path used both by [`PolicyQueryPlanner`] (the statement path) and by
183/// hosts enforcing on a write path that bypasses physical planning (e.g. a
184/// managed-table bulk-ingest append): one policy, one implementation.
185///
186/// `state` is used to optimize the governed plan so the gate sees the
187/// projections/filters pushed down to the table scan — authorizing against the
188/// data actually accessed.
189///
190/// A shorthand for [`authorize_and_govern_with_posture`] at [`Posture::Enforcing`]
191/// — the historical, always-enforce behavior.
192pub async fn authorize_and_govern(
193    state: &dyn Session,
194    plan: &LogicalPlan,
195    policy: &dyn PolicyEngine,
196    principal: &PrincipalIdentity,
197    eval: &EvalContext,
198) -> Result<LogicalPlan> {
199    authorize_and_govern_with_posture(state, plan, policy, principal, eval, Posture::Enforcing)
200        .await
201}
202
203/// Govern + gate `plan` under an explicit [`Posture`].
204///
205/// - [`Posture::Enforcing`] — govern the plan, gate the optimized form, and
206///   error on `Deny`; returns the governed plan on `Allow`. Identical to
207///   [`authorize_and_govern`].
208/// - [`Posture::Permissive`] — evaluate *everything* (constraints are computed,
209///   taints recorded, the coarse gate decided) and emit structured logs, but
210///   enforce nothing: the original plan is returned unchanged and a `Deny` does
211///   not error. The dry-run / rollout mode. A policy-*resolution* error still
212///   propagates — an engine that cannot answer is a misconfiguration, not a
213///   would-block signal.
214/// - [`Posture::Disabled`] — never reaches here (the planner isn't installed).
215///
216/// `Permissive` deliberately reuses the same evaluation path as `Enforcing` so
217/// the logged decisions are exactly the ones enforcement *would* have applied.
218pub async fn authorize_and_govern_with_posture(
219    state: &dyn Session,
220    plan: &LogicalPlan,
221    policy: &dyn PolicyEngine,
222    principal: &PrincipalIdentity,
223    eval: &EvalContext,
224    posture: Posture,
225) -> Result<LogicalPlan> {
226    let governed = govern_plan(plan, policy, principal, eval).await?;
227    let optimized = state.optimize(&governed)?;
228    let decision = policy.is_allowed(&optimized, principal, eval).await?;
229
230    match posture {
231        Posture::Enforcing => {
232            if decision == Decision::Deny {
233                return exec_err!(
234                    "Principal '{}' is not authorized to execute this query",
235                    principal.uid
236                );
237            }
238            Ok(governed)
239        }
240        Posture::Permissive => {
241            let would_block = decision == Decision::Deny;
242            // Whether governance would have altered the plan (masks / filters).
243            let would_constrain = !plan_shapes_equal(plan, &governed);
244            tracing::info!(
245                target: "breakwater::governance",
246                posture = "permissive",
247                principal = %principal.uid,
248                decision = ?decision,
249                would_block,
250                would_constrain,
251                "governance evaluated in permissive mode; enforcing nothing"
252            );
253            // Return the original plan: no masks, no filters, no deny.
254            Ok(plan.clone())
255        }
256        // The planner is never installed under Disabled, so enforcement code is
257        // unreachable; be safe and pass the plan through untouched.
258        Posture::Disabled => Ok(plan.clone()),
259    }
260}
261
262/// Whether two logical plans are structurally identical (used only to log
263/// whether `Permissive` governance *would* have rewritten the plan). Compares
264/// the debug rendering — cheap and only on the permissive path.
265fn plan_shapes_equal(a: &LogicalPlan, b: &LogicalPlan) -> bool {
266    format!("{a:?}") == format!("{b:?}")
267}
268
269/// Entry point for instrumenting a DataFusion session with Cedar policy
270/// enforcement.
271///
272/// Construct a [`PolicyBuilder`] with [`PolicyExtension::builder`].
273#[derive(Debug)]
274pub struct PolicyExtension;
275
276impl PolicyExtension {
277    /// Start configuring policy instrumentation.
278    pub fn builder() -> PolicyBuilder {
279        PolicyBuilder::default()
280    }
281}
282
283/// Builds and installs policy enforcement on a [`SessionState`].
284///
285/// Set a policy and, optionally, the principal / eval-context providers; then
286/// call [`Self::instrument`]. The providers default to the `SessionConfig`
287/// read-backs, and the policy defaults to `StaticPolicyEngine(Allow)` (an ungoverned
288/// session).
289#[derive(Default)]
290pub struct PolicyBuilder {
291    policy: Option<Arc<dyn PolicyEngine>>,
292    principal: Option<Arc<dyn PrincipalProvider>>,
293    eval: Option<Arc<dyn EvalContextProvider>>,
294    posture: Option<Posture>,
295}
296
297impl std::fmt::Debug for PolicyBuilder {
298    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
299        f.debug_struct("PolicyBuilder")
300            .field("has_policy", &self.policy.is_some())
301            .field("has_principal", &self.principal.is_some())
302            .field("has_eval", &self.eval.is_some())
303            .field("posture", &self.posture.unwrap_or(Posture::Enforcing))
304            .finish()
305    }
306}
307
308impl PolicyBuilder {
309    /// Set the policy to enforce. Defaults to `StaticPolicyEngine(Allow)`.
310    pub fn policy(mut self, policy: Arc<dyn PolicyEngine>) -> Self {
311        self.policy = Some(policy);
312        self
313    }
314
315    /// Set the enforcement [`Posture`]. Defaults to [`Posture::Enforcing`]
316    /// (the historical fail-closed behavior). [`Governance`](crate::Governance)
317    /// sets this from its own posture.
318    pub fn posture(mut self, posture: Posture) -> Self {
319        self.posture = Some(posture);
320        self
321    }
322
323    /// Set the per-request principal provider. Defaults to
324    /// [`SessionConfigPrincipalProvider`].
325    pub fn principal(mut self, principal: Arc<dyn PrincipalProvider>) -> Self {
326        self.principal = Some(principal);
327        self
328    }
329
330    /// Set the per-query eval-context provider. Defaults to
331    /// [`SessionConfigEvalContextProvider`].
332    pub fn eval_context(mut self, eval: Arc<dyn EvalContextProvider>) -> Self {
333        self.eval = Some(eval);
334        self
335    }
336
337    /// Install the enforcement on `state`, returning the wired `SessionState`.
338    ///
339    /// Wraps the session's current [`QueryPlanner`] with a [`PolicyQueryPlanner`]
340    /// that runs govern → optimize → gate before delegating physical planning to
341    /// the wrapped planner — so a pre-existing custom planner (e.g. a Unity DDL
342    /// planner, or a lineage planner) is preserved as the inner planner. Also
343    /// stashes the planner as a typed `SessionConfig` extension so a host can
344    /// recover it with `get_extension::<PolicyQueryPlanner>()` (the `QueryPlanner`
345    /// trait isn't `Any`-downcastable). One `Arc`, two roles.
346    pub fn instrument(self, state: SessionState) -> SessionState {
347        let policy = self
348            .policy
349            .unwrap_or_else(|| Arc::new(StaticPolicyEngine::new(Decision::Allow)));
350        let principal = self
351            .principal
352            .unwrap_or_else(|| Arc::new(SessionConfigPrincipalProvider));
353        let eval = self
354            .eval
355            .unwrap_or_else(|| Arc::new(SessionConfigEvalContextProvider));
356
357        let posture = self.posture.unwrap_or(Posture::Enforcing);
358
359        let inner: Arc<dyn QueryPlanner + Send + Sync> = state.query_planner().clone();
360        let planner = Arc::new(PolicyQueryPlanner::with_posture(
361            policy.clone(),
362            principal,
363            eval,
364            posture,
365            inner,
366        ));
367
368        let mut session_config = state.config().clone();
369        session_config.set_extension(planner.clone());
370        // Make the engine discoverable from config (PolicyEngineExt) so the
371        // provider-tier seam can reach it at table-resolution time.
372        session_config.set_extension(Arc::new(PolicyEngineExt(policy)));
373        SessionStateBuilder::from(state)
374            .with_config(session_config)
375            .with_query_planner(planner)
376            .build()
377    }
378}
379
380/// Instrument `state` with an explicit policy and providers.
381///
382/// A thin wrapper over [`PolicyExtension::builder`] for callers that already
383/// hold the pieces. Prefer the builder for new code.
384pub fn instrument_session_state(
385    state: SessionState,
386    policy: Arc<dyn PolicyEngine>,
387    principal: Arc<dyn PrincipalProvider>,
388    eval: Arc<dyn EvalContextProvider>,
389) -> SessionState {
390    PolicyExtension::builder()
391        .policy(policy)
392        .principal(principal)
393        .eval_context(eval)
394        .instrument(state)
395}
396
397/// `SessionContext` ergonomics for policy instrumentation.
398///
399/// [`with_policy`](Self::with_policy) installs the enforcement on a context in
400/// one consume-and-return call, mirroring `datafusion_openlineage`'s
401/// `OpenLineageSqlExt::with_lineage` and DataFusion's own
402/// `SessionContext::enable_url_table(self) -> Self`. `None` uses defaults (a
403/// `StaticPolicyEngine(Allow)` and the `SessionConfig` read-back providers).
404pub trait PolicySessionExt: Sized {
405    /// Instrument this context with policy enforcement and return it.
406    ///
407    /// Pass a configured [`PolicyBuilder`] to control the policy and providers,
408    /// or `None` for defaults. Because the argument is
409    /// `impl Into<Option<PolicyBuilder>>`, both `ctx.with_policy(None)` and
410    /// `ctx.with_policy(PolicyExtension::builder()…)` are valid call sites.
411    fn with_policy(self, builder: impl Into<Option<PolicyBuilder>>) -> Self;
412}
413
414impl PolicySessionExt for SessionContext {
415    fn with_policy(self, builder: impl Into<Option<PolicyBuilder>>) -> Self {
416        let builder = builder.into().unwrap_or_default();
417        SessionContext::new_with_state(builder.instrument(self.state()))
418    }
419}