Raxol.Agent.Authorization.Engine (Raxol Agent v2.6.0)

Copy Markdown View Source

Pure ALLOW/ASK/DENY authorization reducer.

Evaluates an ordered list of Raxol.Agent.Authorization.Policy at a phase and folds them into one Decision (the omnigent PolicyEngine model):

  • DENY short-circuits: the label writes accumulated from prior ALLOWs are kept, the decision is DENY with the reason. No further policies run.
  • ALLOW applies its (whitelisted) writes to the running labels via a monotonic merge, then continues.
  • ASK accumulates an approval request and holds its writes in ESCROW (applied only on approval), then continues.

Final action: DENY if any policy denied, else ASK if any policy asked, else ALLOW. "Stricter session first" is just list order -- prepend session policies; there is no separate tiering engine.

Approval memory and the spawn tree

Approving an ASK can be remembered (per Policy.scope): :session for the engine's lifetime, :root per evaluation route. Passing the root of a spawn tree as route and scoping :root makes one approval cover the whole tree.

State threading

evaluate/5 is pure -- it returns a Decision but does NOT mutate state. Callers commit/2 an ALLOW (or DENY) decision to fold its labels in, or approve/2 an ASK decision to release escrow and remember the approval.

Summary

Functions

approve(decision, state)

Approve an ASK decision: release escrowed writes into the labels and remember the approval per each ask's scope.

commit(decision, state)

Fold a decision's labels into state (used for ALLOW/DENY outcomes).

evaluate(policies, phase, context, state, opts \\ [])

Evaluate ordered policies at phase with context against state.

new(opts \\ [])

Build engine state. Options: :labels, :monotonic.

Functions

approve(decision, state)

@spec approve(
  Raxol.Agent.Authorization.Engine.Decision.t(),
  Raxol.Agent.Authorization.Engine.State.t()
) ::
  Raxol.Agent.Authorization.Engine.State.t()

Approve an ASK decision: release escrowed writes into the labels and remember the approval per each ask's scope.

commit(decision, state)

@spec commit(
  Raxol.Agent.Authorization.Engine.Decision.t(),
  Raxol.Agent.Authorization.Engine.State.t()
) ::
  Raxol.Agent.Authorization.Engine.State.t()

Fold a decision's labels into state (used for ALLOW/DENY outcomes).

evaluate(policies, phase, context, state, opts \\ [])

@spec evaluate(
  [Raxol.Agent.Authorization.Policy.t()],
  Raxol.Agent.Authorization.Policy.phase(),
  map(),
  Raxol.Agent.Authorization.Engine.State.t(),
  keyword()
) :: Raxol.Agent.Authorization.Engine.Decision.t()

Evaluate ordered policies at phase with context against state.

Options: :route -- evaluation route for :root-scoped approval memory. Returns a Decision; does not mutate state.

new(opts \\ [])

@spec new(keyword()) :: Raxol.Agent.Authorization.Engine.State.t()

Build engine state. Options: :labels, :monotonic.