Expand description
Engine-neutral policy enforcement for Apache DataFusion.
This crate is the DataFusion-aware, engine-agnostic core of the policy
stack — the policy analog of datafusion-openlineage. It owns the
decide/enforce split:
- Decide — the
PolicyEnginetrait: the contract a policy engine implements to answer what is allowed (coarse gate) and what constraints apply (row filters + column masks). It names no engine type; a Cedar adapter lives indatafusion-policy-cedar, and an OPA or OpenFGA adapter could implement the same trait. - Enforce — the
PolicyQueryPlanner(aQueryPlannerwrapper) and the pre-optimize plan rewrite (govern_plan, underfgac) that apply the engine’s answers to a session.
Everything here is expressed in neutral types — Decision, AttrValue,
PrincipalIdentity, TableFacts, DataFusion Exprs — so no policy
engine leaks through the seam.
Two layers:
- Layer 1 — coarse access gate (
PolicyEngine::is_allowed): does the principal have access to the tables/actions a query references? - Layer 2 — fine-grained governance (feature
fgac): row filters and column masks the engine derives, applied before optimization.
Re-exports§
pub use govern::TablePolicy;pub use govern::govern_plan;
Modules§
- govern
- Layer 2: fine-grained governance — inject row filters and column masks into a logical plan before optimization.
Structs§
- Abac
Policy Engine - A
PolicyEnginethat enforces UC ABACPolicyBindings directly. - Agent
Claims - Agent-identity claims (OIDC-A). A placeholder seam carried on
PrincipalClaims; agent principal-enrichment is deferred to the agent-PEP work, so the v1 identity provider ignores it. - Catalog
Fact Sink - A per-query sink the catalog writes
TableFactsinto and the Cedar policy reads. Interior-mutable and cheap to clone (Arc<DashMap>), so the same instance reaches bothbuild_delta(during resolution) and the policy layer (during evaluation) through aSessionConfigextension. - Catalog
Fact Sink Ext - The
SessionConfigextension carrying the per-queryCatalogFactSinkthe catalog writes resource facts into and the policy layer reads. - Column
Match - A
MATCH COLUMNSmatcher: the columns whose governed tags satisfyconditionare exposed to the function underalias. - Default
Principal Matcher - The default
PrincipalMatcher: strips anEntityType::"..."wrapper off both the binding name and the principal’s uid/groups before a case-sensitive compare, and treats theaccount userssentinel as matching every principal. - Eval
Context - Per-query, non-plan facts threaded into the
PolicyEnginelayer. - Fact
Store Ext - The
SessionConfigextension carrying the session’s taint ledger, attached to the per-query state so the policy layer can build theEvalContext. - Function
Resolver Ext - The
SessionConfigextension carrying the catalog function resolver, so the governance PEP can turn a policy-referenced masking / row-filter function name into a callableScalarUDF. - Governance
- A fully-assembled governance profile: the policy engine plus the optional
identity / function / fact-store providers, and the runtime
Posture. - Governance
Builder - Builder for
Governance. SeeGovernance::builder. - Governed
Table Provider - A
TableProviderthat presents a governed (secured-view) plan over a base provider. - Group
- A node in the neutral group hierarchy: a group uid and its direct parent
group uids. The transitive closure of a principal’s groups (each group plus
its ancestors) so
privileged_readers ⊂ readersresolves without a static entity bundle. - InMemory
Fact Store - In-memory
FactStorebacked by aDashMapkeyed by correlation id. - Policy
Binding - One parsed UC ABAC policy: principals × tag-matched securable/columns → a row-filter or column-mask function call.
- Policy
Builder - Builds and installs policy enforcement on a
SessionState. - Policy
Engine Ext - The
SessionConfigextension carrying the session’sPolicyEngine, so the engine is discoverable from config on every host regardless of which enforcement tier fires first:PolicyBuilder::instrumentsets it, and the provider-tier seam (govern_provider_from_config, underfgac) reads it back at table-resolution time. - Policy
Extension - Entry point for instrumenting a DataFusion session with Cedar policy enforcement.
- Policy
Query Planner - A
QueryPlannerthat governs and gates a query before physical planning. - Principal
Claims - Neutral, transport-free claims the host passes to an
IdentityProvider. - Principal
Enrichment - The facts an
IdentityProviderresolves for a principal: attributes to fold onto the principal, the principal’s direct group parents, and the transitive group hierarchy needed forinto resolve the ancestry. - Principal
Ext - The
SessionConfigextension carrying the per-request principal. - Principal
Identity - The principal on whose behalf a query executes, plus the attributes policies
may condition on (e.g.
role,region,name) and the group memberships they resolveinagainst. - Session
Config Eval Context Provider - An
EvalContextProviderthat assembles theEvalContextfrom the session’sSessionConfigextensions: the catalog fact sink and (underfgac) the correlation id + taint ledger. The correlation id is the session id, stable per connection. - Session
Config Principal Provider - A
PrincipalProviderthat reads thePrincipalIdentityattached to the session’sSessionConfigas aPrincipalExtextension. - Static
Policy Engine - A
PolicyEnginethat returns the same decision for every query. - Table
Facts - Catalog-derived attributes of one table, gathered at resolution time and
folded into the Cedar
Tableresource entity. The host builds this from its catalog metadata (UCTable.owner/properties/comment); the Cedar layer reads only this neutral shape. - TagCondition
- A governed-tag matcher:
hasTag(key)whenvalueisNone,hasTagValue(key, value)otherwise.
Enums§
- Attr
Value - An engine-neutral principal attribute value.
- Binding
Kind - Whether a binding installs a row filter or a column mask — the two UC ABAC policy kinds.
- Decision
- The coarse allow/deny outcome of an authorization decision.
- Function
Arg - One argument to a binding’s function: either a column bound by a
ColumnMatchalias, or a constant passed through as a literal. - Identity
Error - An error resolving identity facts. Small and crate-local so the host owns the
fail-closed decision (an
Errshould fail the session, not proceed un-enriched). - Plan
Action - An access-relevant operation discovered in a logical plan.
- Posture
- The runtime enforcement stance, chosen once at build time so an ungoverned session is never the accidental result of a forgotten wire-up.
Traits§
- Catalog
Function Resolver - Resolves a catalog function name into a callable DataFusion
ScalarUDF. - Constraint
Translator - Translates an engine’s residual into a DataFusion row-filter predicate.
- Eval
Context Provider - Assembles the per-query
EvalContextfrom the planningSession. - Fact
Store - Shared, session-scoped facts keyed by a correlation id (the session/trace id). v1 exposes only the monotonic taint ledger.
- Identity
Provider - The principal/identity PIP: given the authenticated principal uid (plus any validated claims), pull the slice of identity facts policies condition on — attributes and group membership.
- Policy
Engine - The decide contract every policy engine implements — the engine-agnostic seam the enforcement layer talks to.
- Policy
Session Ext SessionContextergonomics for policy instrumentation.- Principal
Matcher - Decides whether a
PolicyBinding’s principal lists match the queryingPrincipalIdentity— a small seam so a host can override the name-normalization / all-users semantics its directory uses. - Principal
Provider - Resolves the principal a query runs as, from the planning
Session.
Functions§
- authorize_
and_ govern - Govern
plan(row filters + column masks), then gate the optimized plan on the coarse access policy — the shared enforcement sequence. - authorize_
and_ govern_ with_ posture - Govern + gate
planunder an explicitPosture. - govern_
provider - Wrap
providerin a secured view enforcingpolicy.constrain(...). - govern_
provider_ from_ config - One-call host seam: assemble the engine (
PolicyEngineExt), principal (PrincipalExt), and eval context fromSessionConfigextensions, then delegate togovern_provider. - instrument_
session_ state - Instrument
statewith an explicit policy and providers. - normalize
- Normalize a
TableReferenceto its fully-qualified form so the key the catalog writes (catalog.schema.table, built from UC metadata) matches the key the plan’sTableScancarries (which may be bare/partial before resolution). Both therecordandgetsides normalize, so abare("t")and afull("c","s","t")referring to the same table resolve to one entry only when they share the same qualified name; refs that genuinely differ stay distinct. - plan_
actions - Walk
planand return the neutralPlanActions that must be authorized for it to run. An engine adapter lowers each action to its own request.