auth51-governance

The governance-time engine for auth51. It does three things, all pure and stdlib-only:

1. Classify an action's consequence into an ordered tier (READ < WRITE < SENSITIVE < FINANCIAL < DESTRUCTIVE).
2. Synthesize a guarded workflow from sampled run observations plus the roster's capability catalog. Guard strength follows the tier, not a single boolean.
3. Validate a proposed workflow against the tier floor, so the authority can reject a workflow that frees a dangerous capability regardless of who proposed it.

Why it's a separate library

Deriving and registering workflows is a governance-time act, not a runtime one — even though the learning signal (observations) comes from runs. Any client can produce observations: the reference workforce, a custom app on the auth51 client, or the auth51d gateway. They all feed the same engine here, and the authority stays the single source of truth for guard strength by calling validate_workflow at registration.

Kept dependency-light and portable, exactly like auth51-checksum, so both the authority and clients can depend on it without pulling a framework.

The guard ladder

Two properties over the old binary model: a real ladder (an identity edit ≠ a money movement), and high tiers never auto-free (a DESTRUCTIVE op seen once still needs a human; a FINANCIAL op is never free).

Usage

from auth51_governance import (
    Capability, obs_from_spans, synthesize, validate_workflow, ConsequenceTier,
)

# what the roster CAN do (classified from spec risk/tags, else the name)
caps = [
    Capability.classify("refunder", "RetrieveCustomer"),
    Capability.classify("refunder", "CreatePayout", risk="financial"),
    Capability.classify("admin", "DropDatabase"),
]

# what runs DID (from each run's spans)
runs = [obs_from_spans(spans) for spans in sampled_runs]

wf = synthesize("refund-flow", runs, caps)          # a guarded WorkflowDefinition dict

# at the authority, before registering:
violations = validate_workflow(wf, tier_of=lambda a, act: my_registry_tier(a, act))
assert not violations

Compiles down to the authority's step primitives

synthesize emits the same WorkflowStep shape the authority already enforces: dependencies (ordering), scopes (subset), and an approval-gate step. Each step also carries a tier annotation the authority stores and the value-binding phase will use.