Module authz 

Provider-dispatch authorization: safety-class → scope affinity, caller trust discipline, and structured security decisions.

Modeled on axon’s axon-authz execution-affinity layer, adapted to Soma’s provider kinds and its stricter write-satisfies-read scope rule (crate::scopes::scopes_satisfy). This layer governs dynamic provider execution only — built-in actions keep their ACTION_SPECS scope checks in the MCP server layer.

Three invariants this module enforces by construction:

1. Affinity: every classified dispatch target has a minimum scope derived from what its handler can do (execute code, egress to the network, …), independent of the scope the tool manifest declares.
2. Trusted-local discipline: exactly one constructor (CallerContext::trusted_local_caller) can set trusted_local; the remote/scoped constructor hard-codes it to false, so a network caller can never claim local trust.
3. Deny-by-default: an unclassified target denies with a stable machine-readable reason instead of falling through to “allow”.

Modules

reasons

Stable machine-readable decision reasons. These are API: never rename an existing constant’s value, only add new ones.

Structs

CallerContext

Who is asking for a dispatch. Fields are private on purpose: the only way to obtain trusted_local = true is Self::trusted_local_caller.

SecurityDecision

A decision object, not a bool: allowed plus a stable machine-readable reason from reasons, plus human-oriented advisory warnings.

Enums

ExecutionMode

Where a handler executes relative to the Soma host process.

SafetyClass

What a dynamic provider’s handler is capable of doing when invoked, classified from the provider manifest kind.

Functions

authorize

Authorizes one dispatch: affinity scope + the trusted-local inline rule, deny-by-default for unclassified targets.

authorize_provider_kind

Convenience for the provider-dispatch chokepoint: classify a manifest kind, derive its execution mode, and authorize in one call.

required_scope_for_safety_class

Minimum scope a caller must hold to execute a target of this class, regardless of the scope declared on the individual tool. The tool’s own declared scope is still enforced separately on top of this floor.