Metadata-Version: 2.5
Name: auth51-governance
Version: 0.1.0
Summary: The auth51 governance engine — classify action consequence into tiers, synthesize guarded workflows from observed runs, and validate a proposed workflow against the tier floor at registration.
Project-URL: Homepage, https://auth51.com
Project-URL: Repository, https://github.com/unforge-io/auth51-governance
Author-email: unforge <dev-admin@unforge.io>
License: Apache-2.0
Keywords: agentic-authorization,ai-agents,auth51,governance,workflow
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

|             | observed (≥ `min_support` runs)            | unobserved / under-supported |
|-------------|--------------------------------------------|------------------------------|
| READ        | free                                       | (no step)                    |
| WRITE       | free                                       | (no step)                    |
| SENSITIVE   | ordered (must follow legit predecessors)   | approval gate                |
| FINANCIAL   | ordered (value-bound in a later phase)     | approval gate                |
| DESTRUCTIVE | approval gate (never downgraded)           | approval gate                |

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

```python
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.
