aetos-verify 0.3.3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- aetos/__init__.py +43 -0
- aetos/application/__init__.py +9 -0
- aetos/application/agent/__init__.py +1 -0
- aetos/application/agent/action_gate.py +174 -0
- aetos/application/agent/action_policy.py +213 -0
- aetos/application/agent/agent_service.py +558 -0
- aetos/application/agent/orchestrator.py +395 -0
- aetos/application/assemblers/__init__.py +0 -0
- aetos/application/assemblers/audit.py +26 -0
- aetos/application/assemblers/decision_report.py +62 -0
- aetos/application/assemblers/human_report.py +95 -0
- aetos/application/assemblers/policy_verdict.py +112 -0
- aetos/application/audit.py +153 -0
- aetos/application/boundary/__init__.py +25 -0
- aetos/application/boundary/gate.py +202 -0
- aetos/application/boundary/scorer.py +294 -0
- aetos/application/boundary/tone.py +82 -0
- aetos/application/dto/__init__.py +0 -0
- aetos/application/dto/audit.py +28 -0
- aetos/application/dto/decision_report.py +50 -0
- aetos/application/dto/human_report.py +41 -0
- aetos/application/dto/policy_verdict.py +56 -0
- aetos/application/dto/verdict_snapshot.py +140 -0
- aetos/application/extraction/__init__.py +56 -0
- aetos/application/extraction/candidate.py +54 -0
- aetos/application/extraction/confidence.py +54 -0
- aetos/application/extraction/detectors/__init__.py +76 -0
- aetos/application/extraction/detectors/blast_radius.py +92 -0
- aetos/application/extraction/detectors/common.py +124 -0
- aetos/application/extraction/detectors/criticality.py +110 -0
- aetos/application/extraction/detectors/evidence_count.py +277 -0
- aetos/application/extraction/detectors/exit_criteria.py +91 -0
- aetos/application/extraction/detectors/owner.py +139 -0
- aetos/application/extraction/detectors/precedent.py +49 -0
- aetos/application/extraction/detectors/reversibility.py +303 -0
- aetos/application/extraction/detectors/rollback.py +88 -0
- aetos/application/extraction/detectors/time_pressure.py +202 -0
- aetos/application/extraction/evidence.py +548 -0
- aetos/application/extraction/review.py +133 -0
- aetos/application/extraction/span_evidence.py +229 -0
- aetos/application/extraction/validation.py +164 -0
- aetos/application/facts/__init__.py +5 -0
- aetos/application/facts/assembler.py +164 -0
- aetos/application/grounding/__init__.py +64 -0
- aetos/application/grounding/challenge.py +91 -0
- aetos/application/grounding/detector.py +376 -0
- aetos/application/grounding/gate.py +116 -0
- aetos/application/grounding/mode.py +113 -0
- aetos/application/grounding/prompts.py +72 -0
- aetos/application/grounding/service.py +334 -0
- aetos/application/policy/__init__.py +33 -0
- aetos/application/policy/evaluator.py +114 -0
- aetos/application/policy/opinion.py +85 -0
- aetos/application/policy/rule.py +117 -0
- aetos/application/policy/rules/__init__.py +13 -0
- aetos/application/policy/rules/criticality_rule.py +50 -0
- aetos/application/policy/rules/exit_criteria_rule.py +74 -0
- aetos/application/policy/rules/no_owner_rule.py +81 -0
- aetos/application/policy/rules/no_rollback.py +120 -0
- aetos/application/policy/verdict.py +102 -0
- aetos/application/ports.py +233 -0
- aetos/application/provider.py +46 -0
- aetos/application/services/__init__.py +33 -0
- aetos/application/services/answer_service.py +159 -0
- aetos/application/services/claim_check.py +55 -0
- aetos/application/services/dialogue.py +295 -0
- aetos/application/services/evaluate_decision.py +98 -0
- aetos/application/services/evaluation_service.py +166 -0
- aetos/application/services/extraction_service.py +57 -0
- aetos/application/services/fact_validation_service.py +118 -0
- aetos/application/services/human_assertion.py +85 -0
- aetos/application/services/qa_loop.py +242 -0
- aetos/application/services/question_phraser.py +138 -0
- aetos/application/services/smart_colleague.py +210 -0
- aetos/application/verdict_state.py +138 -0
- aetos/domain/__init__.py +0 -0
- aetos/domain/agent.py +538 -0
- aetos/domain/chain_subject.py +70 -0
- aetos/domain/entities/__init__.py +18 -0
- aetos/domain/entities/contradiction.py +54 -0
- aetos/domain/entities/decision.py +379 -0
- aetos/domain/facts/__init__.py +28 -0
- aetos/domain/facts/decision_facts.py +68 -0
- aetos/domain/facts/fact.py +65 -0
- aetos/domain/facts/source.py +23 -0
- aetos/domain/facts/vocabulary.py +95 -0
- aetos/domain/ports/__init__.py +11 -0
- aetos/domain/ports/clock.py +19 -0
- aetos/domain/ports/id_generator.py +19 -0
- aetos/domain/values/__init__.py +83 -0
- aetos/domain/values/_identity.py +120 -0
- aetos/domain/values/_numeric.py +84 -0
- aetos/domain/values/_reliability.py +21 -0
- aetos/domain/values/_timestamp.py +67 -0
- aetos/domain/values/_validation.py +19 -0
- aetos/domain/values/actor.py +34 -0
- aetos/domain/values/confidence.py +61 -0
- aetos/domain/values/evidence.py +34 -0
- aetos/domain/values/human_response.py +40 -0
- aetos/domain/values/provenance.py +40 -0
- aetos/domain/values/recommendation.py +39 -0
- aetos/guard.py +215 -0
- aetos/infrastructure/__init__.py +0 -0
- aetos/infrastructure/adapters/__init__.py +105 -0
- aetos/infrastructure/adapters/chat_anthropic.py +101 -0
- aetos/infrastructure/adapters/chat_ollama.py +105 -0
- aetos/infrastructure/adapters/chat_openai.py +102 -0
- aetos/infrastructure/adapters/decision_repository.py +596 -0
- aetos/infrastructure/adapters/ecc_p256_signer.py +92 -0
- aetos/infrastructure/adapters/ed25519_signer.py +143 -0
- aetos/infrastructure/adapters/ollama_fact_extractor.py +492 -0
- aetos/infrastructure/adapters/ollama_phraser.py +102 -0
- aetos/infrastructure/adapters/system_clock.py +72 -0
- aetos/infrastructure/adapters/system_id_generator.py +61 -0
- aetos/infrastructure/hashing.py +15 -0
- aetos/infrastructure/migrations.py +247 -0
- aetos/interfaces/__init__.py +0 -0
- aetos/interfaces/api/__init__.py +5 -0
- aetos/interfaces/api/app.py +131 -0
- aetos/interfaces/api/auth.py +100 -0
- aetos/interfaces/api/colleague_demo.py +383 -0
- aetos/interfaces/api/composition.py +268 -0
- aetos/interfaces/api/demo_page.py +350 -0
- aetos/interfaces/api/grounding_routes.py +84 -0
- aetos/interfaces/api/provider_factory.py +247 -0
- aetos/interfaces/api/routes.py +851 -0
- aetos/interfaces/api/schemas.py +368 -0
- aetos/interfaces/cli/__init__.py +0 -0
- aetos/interfaces/cli/demo.py +142 -0
- aetos/interfaces/exporter/__init__.py +0 -0
- aetos/interfaces/verifier/__init__.py +0 -0
- aetos/interfaces/verifier/body_attestation.py +524 -0
- aetos/interfaces/verifier/build_pack.py +703 -0
- aetos/interfaces/verifier/chain_verifier.py +174 -0
- aetos/interfaces/verifier/cli.py +272 -0
- aetos/interfaces/verifier/pack_schema.py +796 -0
- aetos/interfaces/verifier/report.py +117 -0
- aetos/interfaces/verifier/signature_verifier.py +252 -0
- aetos/interfaces/verifier/trust_anchor.py +144 -0
- aetos/interfaces/verifier/verify_pack.py +275 -0
- aetos/interfaces/verify_portal.py +282 -0
- aetos/py.typed +0 -0
- aetos_verify-0.3.3.dist-info/METADATA +323 -0
- aetos_verify-0.3.3.dist-info/RECORD +148 -0
- aetos_verify-0.3.3.dist-info/WHEEL +5 -0
- aetos_verify-0.3.3.dist-info/entry_points.txt +2 -0
- aetos_verify-0.3.3.dist-info/licenses/LICENSE +201 -0
- aetos_verify-0.3.3.dist-info/top_level.txt +1 -0
aetos/__init__.py
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""AETOS — tamper-evident, offline-verifiable receipts for AI-assisted decisions.
|
|
2
|
+
|
|
3
|
+
The **distribution** name is ``aetos-verify``; the **import package** is
|
|
4
|
+
``aetos``. See ``docs/adr/0034-v1-0-scope-and-naming.md``.
|
|
5
|
+
|
|
6
|
+
The version lives in exactly one place — ``pyproject.toml`` — and is read back
|
|
7
|
+
from the installed distribution metadata here. Nothing under ``src/`` may write
|
|
8
|
+
it as a literal. The reason is not tidiness: the value is embedded in every
|
|
9
|
+
exported pack (``metadata.aetos_version``), so a literal that drifts makes the
|
|
10
|
+
artefact a buyer receives misreport the version that produced it.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from importlib.metadata import PackageNotFoundError
|
|
16
|
+
from importlib.metadata import version as _distribution_version
|
|
17
|
+
|
|
18
|
+
DISTRIBUTION = "aetos-verify"
|
|
19
|
+
UNKNOWN_VERSION = "0.0.0+unknown"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def resolve_version(
|
|
23
|
+
distribution: str = DISTRIBUTION,
|
|
24
|
+
fallback: str = UNKNOWN_VERSION,
|
|
25
|
+
) -> str:
|
|
26
|
+
"""Return the installed version of ``distribution``, else ``fallback``.
|
|
27
|
+
|
|
28
|
+
``fallback`` covers a source checkout that was never installed. Reporting
|
|
29
|
+
``0.0.0+unknown`` is honest; reporting a stale literal is not — which is
|
|
30
|
+
what happened here. ``build_pack.py`` carried ``_AETOS_VERSION = "0.2.0"``
|
|
31
|
+
while the manifest said ``0.3.0``, so both shipped demo packs recorded
|
|
32
|
+
``aetos_version: "0.2.0"``, and no test referenced the literal, so nothing
|
|
33
|
+
could notice.
|
|
34
|
+
"""
|
|
35
|
+
try:
|
|
36
|
+
return _distribution_version(distribution)
|
|
37
|
+
except PackageNotFoundError:
|
|
38
|
+
return fallback
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
__version__ = resolve_version()
|
|
42
|
+
|
|
43
|
+
__all__ = ["DISTRIBUTION", "UNKNOWN_VERSION", "__version__", "resolve_version"]
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""Application layer: service orchestration and policy logic.
|
|
2
|
+
|
|
3
|
+
This package deliberately performs no eager re-exports: importing it — or
|
|
4
|
+
any of its submodules — must not pull the whole service layer, and in
|
|
5
|
+
particular must not transitively load the human-assertion path (ADR-011
|
|
6
|
+
I-6 / ADR-013 condition 7: ``EvidenceGuard`` stays unaware of human
|
|
7
|
+
authority). Import concrete submodules directly, e.g. ``from
|
|
8
|
+
aetos.application.services import EvaluationService``.
|
|
9
|
+
"""
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# Agent application layer
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
"""ActionGate: the application-layer decision point for agent actions (ADR-013, Day 2).
|
|
2
|
+
|
|
3
|
+
ActionGate answers one question: may this proposed action proceed, and on
|
|
4
|
+
whose authority? It composes the domain primitives into the application
|
|
5
|
+
boundary (``PROPOSAL != EXECUTION``):
|
|
6
|
+
|
|
7
|
+
- The ordered :class:`ActionPolicy` is always evaluated first, so its
|
|
8
|
+
triggered rules travel with every decision as audit context.
|
|
9
|
+
- A sealed :class:`HumanActionOverride`, when present, takes precedence
|
|
10
|
+
over the policy — the human is the ultimate authority and their record
|
|
11
|
+
is the authority itself (``HUMAN_OVERRIDE != SYSTEM_ENDORSEMENT``). A
|
|
12
|
+
human may veto an allowed action, break glass on a **soft deny**, or
|
|
13
|
+
resolve a ``NEED_HUMAN``; the decision then carries ``HUMAN_OVERRIDE``
|
|
14
|
+
provenance (``ALLOW != HUMAN_ENDORSEMENT``).
|
|
15
|
+
- A **hard deny** (policy verdict ``DENY`` with ``overridable=False``) is
|
|
16
|
+
absolute: it encodes a safety-critical prohibition and no human override
|
|
17
|
+
may lift it — the gate returns the policy's deny unchanged. Soft denies
|
|
18
|
+
(``overridable=True``, the default) are the ones a human may override.
|
|
19
|
+
- ``NEED_HUMAN`` is a first-class rule outcome: a rule may actively demand
|
|
20
|
+
human approval for an action class (e.g. production deploys) instead of
|
|
21
|
+
letting the gate fall back to it. The distinction is visible in
|
|
22
|
+
``triggered_rules`` — an active need carries the rule id, a fallback
|
|
23
|
+
(no rule decided) carries none. ``NEED_HUMAN`` never carries an
|
|
24
|
+
authorization, so no ``EXECUTED`` receipt can be built from it
|
|
25
|
+
(``NO_AUTHORIZATION -> NO_EXECUTED_RECEIPT``).
|
|
26
|
+
|
|
27
|
+
The gate never mutates state and never executes anything — it only
|
|
28
|
+
produces an immutable :class:`GateDecision`.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
from dataclasses import dataclass
|
|
34
|
+
from enum import Enum, unique
|
|
35
|
+
|
|
36
|
+
from aetos.application.agent.action_policy import ActionPolicy
|
|
37
|
+
from aetos.domain.agent import (
|
|
38
|
+
ActionProposal,
|
|
39
|
+
ActionVerdict,
|
|
40
|
+
AuthorizationKind,
|
|
41
|
+
AuthorizationRecord,
|
|
42
|
+
HumanActionOverride,
|
|
43
|
+
)
|
|
44
|
+
from aetos.domain.values import Timestamp, require_instance
|
|
45
|
+
|
|
46
|
+
__all__ = [
|
|
47
|
+
"ActionGate",
|
|
48
|
+
"DecisionSource",
|
|
49
|
+
"GateDecision",
|
|
50
|
+
]
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
@unique
|
|
54
|
+
class DecisionSource(Enum):
|
|
55
|
+
"""Whose authority produced the gate's decision."""
|
|
56
|
+
|
|
57
|
+
POLICY = "policy"
|
|
58
|
+
HUMAN_OVERRIDE = "human_override"
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass(frozen=True, slots=True)
|
|
62
|
+
class GateDecision:
|
|
63
|
+
"""The gate's immutable decision on a proposed action.
|
|
64
|
+
|
|
65
|
+
``authorization`` is present exactly when the verdict is ``ALLOW`` or
|
|
66
|
+
``DENY``; its provenance kind always matches the decision source
|
|
67
|
+
(``SYSTEM_POLICY`` for a policy decision, ``HUMAN_OVERRIDE`` for a
|
|
68
|
+
sealed human override).
|
|
69
|
+
|
|
70
|
+
``overridable`` says whether a human override may still change this
|
|
71
|
+
decision. Only a ``DENY`` can be non-overridable: a hard policy deny
|
|
72
|
+
is absolute, while soft denies, allows and need-human states remain
|
|
73
|
+
open to human authority.
|
|
74
|
+
"""
|
|
75
|
+
|
|
76
|
+
verdict: ActionVerdict
|
|
77
|
+
authorization: AuthorizationRecord | None
|
|
78
|
+
source: DecisionSource
|
|
79
|
+
triggered_rules: tuple[str, ...]
|
|
80
|
+
overridable: bool = True
|
|
81
|
+
|
|
82
|
+
def __post_init__(self) -> None:
|
|
83
|
+
require_instance(self.verdict, ActionVerdict, "GateDecision.verdict")
|
|
84
|
+
if self.authorization is not None:
|
|
85
|
+
require_instance(
|
|
86
|
+
self.authorization,
|
|
87
|
+
AuthorizationRecord,
|
|
88
|
+
"GateDecision.authorization",
|
|
89
|
+
)
|
|
90
|
+
require_instance(self.source, DecisionSource, "GateDecision.source")
|
|
91
|
+
for index, rule_id in enumerate(self.triggered_rules):
|
|
92
|
+
require_instance(rule_id, str, f"GateDecision.triggered_rules[{index}]")
|
|
93
|
+
require_instance(self.overridable, bool, "GateDecision.overridable")
|
|
94
|
+
if self.verdict is ActionVerdict.NEED_HUMAN and self.authorization is not None:
|
|
95
|
+
raise ValueError(
|
|
96
|
+
"a NEED_HUMAN verdict must not carry an authorization: "
|
|
97
|
+
"NEED_HUMAN is a gate state, not an authorization"
|
|
98
|
+
)
|
|
99
|
+
if self.verdict is not ActionVerdict.NEED_HUMAN and self.authorization is None:
|
|
100
|
+
raise ValueError("an ALLOW or DENY verdict must carry an authorization")
|
|
101
|
+
if not self.overridable and self.verdict is not ActionVerdict.DENY:
|
|
102
|
+
raise ValueError(
|
|
103
|
+
"only a DENY decision may be non-overridable; "
|
|
104
|
+
f"got verdict {self.verdict.value!r}"
|
|
105
|
+
)
|
|
106
|
+
if self.authorization is not None:
|
|
107
|
+
expected = (
|
|
108
|
+
AuthorizationKind.HUMAN_OVERRIDE
|
|
109
|
+
if self.source is DecisionSource.HUMAN_OVERRIDE
|
|
110
|
+
else AuthorizationKind.SYSTEM_POLICY
|
|
111
|
+
)
|
|
112
|
+
if self.authorization.kind is not expected:
|
|
113
|
+
raise ValueError(
|
|
114
|
+
"GateDecision.authorization provenance must match the "
|
|
115
|
+
"decision source: "
|
|
116
|
+
f"{self.source.value} requires {expected.value}, "
|
|
117
|
+
f"got {self.authorization.kind.value}"
|
|
118
|
+
)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class ActionGate:
|
|
122
|
+
"""Decide whether a proposed agent action may proceed.
|
|
123
|
+
|
|
124
|
+
Authority flows from the human, then the policy:
|
|
125
|
+
|
|
126
|
+
- A sealed :class:`HumanActionOverride`, when present, takes
|
|
127
|
+
precedence over the policy — the human is the ultimate authority and
|
|
128
|
+
their record is the authority itself (``HUMAN_OVERRIDE !=
|
|
129
|
+
SYSTEM_ENDORSEMENT``). A human may veto an allowed action, break
|
|
130
|
+
glass on a soft deny, or resolve a ``NEED_HUMAN``.
|
|
131
|
+
- A **hard deny** (policy verdict ``DENY`` with ``overridable=False``)
|
|
132
|
+
is absolute: it encodes a safety-critical prohibition and no human
|
|
133
|
+
override may lift it. The gate returns the policy's deny unchanged.
|
|
134
|
+
- Without an override the ordered policy decides, and the gate fails
|
|
135
|
+
closed to ``NEED_HUMAN`` when no rule decides.
|
|
136
|
+
"""
|
|
137
|
+
|
|
138
|
+
def __init__(self, policy: ActionPolicy) -> None:
|
|
139
|
+
self._policy: ActionPolicy = policy
|
|
140
|
+
|
|
141
|
+
def evaluate(
|
|
142
|
+
self,
|
|
143
|
+
proposal: ActionProposal,
|
|
144
|
+
*,
|
|
145
|
+
override: HumanActionOverride | None = None,
|
|
146
|
+
timestamp: Timestamp | None = None,
|
|
147
|
+
) -> GateDecision:
|
|
148
|
+
"""Decide whether the proposed action may proceed.
|
|
149
|
+
|
|
150
|
+
``override`` is the sealed human override for this proposal, when
|
|
151
|
+
one exists. ``timestamp`` overrides the authorization time used by
|
|
152
|
+
the policy (defaults to the proposal's own timestamp).
|
|
153
|
+
|
|
154
|
+
The policy is always evaluated first: its triggered rules travel
|
|
155
|
+
with the decision as audit context even when a human override
|
|
156
|
+
decides. An override is ignored only when the policy issued a hard
|
|
157
|
+
deny (``DENY`` with ``overridable=False``).
|
|
158
|
+
"""
|
|
159
|
+
verdict = self._policy.evaluate(proposal, timestamp=timestamp)
|
|
160
|
+
hard_deny = verdict.verdict is ActionVerdict.DENY and not verdict.overridable
|
|
161
|
+
if override is not None and not hard_deny:
|
|
162
|
+
return GateDecision(
|
|
163
|
+
verdict=override.verdict,
|
|
164
|
+
authorization=override.to_authorization(),
|
|
165
|
+
source=DecisionSource.HUMAN_OVERRIDE,
|
|
166
|
+
triggered_rules=verdict.triggered_rules,
|
|
167
|
+
)
|
|
168
|
+
return GateDecision(
|
|
169
|
+
verdict=verdict.verdict,
|
|
170
|
+
authorization=verdict.authorization,
|
|
171
|
+
source=DecisionSource.POLICY,
|
|
172
|
+
triggered_rules=verdict.triggered_rules,
|
|
173
|
+
overridable=verdict.overridable,
|
|
174
|
+
)
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
"""ActionPolicy: deterministic authorization for agent actions (ADR-013, Day 2).
|
|
2
|
+
|
|
3
|
+
The first application-layer piece of ActionGate (``PROPOSAL != EXECUTION``):
|
|
4
|
+
a policy is an ordered list of rules, and each rule independently evaluates
|
|
5
|
+
a single :class:`ActionProposal`. The first rule that produces a terminal
|
|
6
|
+
verdict (``ALLOW``, ``DENY`` or ``NEED_HUMAN``) decides the action; rules
|
|
7
|
+
that do not apply return ``PASS`` and are skipped.
|
|
8
|
+
|
|
9
|
+
- ``ALLOW`` / ``DENY`` produce an :class:`AuthorizationRecord` with
|
|
10
|
+
:attr:`AuthorizationKind.SYSTEM_POLICY` provenance (``ALLOW !=
|
|
11
|
+
HUMAN_ENDORSEMENT``, ADR-013); the record's reference points at the rule
|
|
12
|
+
that fired.
|
|
13
|
+
- ``NEED_HUMAN`` is a first-class rule outcome: a rule may actively demand
|
|
14
|
+
human approval for an action class (e.g. production deploys). It is a
|
|
15
|
+
gate state, never an authorization — no ``AuthorizationRecord`` is
|
|
16
|
+
produced, so no ``EXECUTED`` receipt can ever be built from it
|
|
17
|
+
(``NO_AUTHORIZATION -> NO_EXECUTED_RECEIPT``).
|
|
18
|
+
- Overridability: a ``DENY`` declares whether a human override may lift it
|
|
19
|
+
(``overridable``, default ``True`` = soft deny). A safety-critical rule
|
|
20
|
+
sets ``overridable=False`` to make its deny absolute. Only a ``DENY``
|
|
21
|
+
may be non-overridable.
|
|
22
|
+
- With no rules, or when every rule passes, the policy fails closed to
|
|
23
|
+
``NEED_HUMAN`` — a silent allow is impossible.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
from collections.abc import Sequence
|
|
29
|
+
from dataclasses import dataclass
|
|
30
|
+
from enum import Enum, unique
|
|
31
|
+
from typing import Protocol, runtime_checkable
|
|
32
|
+
|
|
33
|
+
from aetos.domain.agent import (
|
|
34
|
+
ActionProposal,
|
|
35
|
+
ActionVerdict,
|
|
36
|
+
AuthorizationKind,
|
|
37
|
+
AuthorizationRecord,
|
|
38
|
+
)
|
|
39
|
+
from aetos.domain.values import Timestamp, require_instance
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@unique
|
|
43
|
+
class RuleVerdict(Enum):
|
|
44
|
+
"""The verdict a single rule may return."""
|
|
45
|
+
|
|
46
|
+
ALLOW = "allow"
|
|
47
|
+
DENY = "deny"
|
|
48
|
+
NEED_HUMAN = "need_human"
|
|
49
|
+
PASS = "pass" # noqa: S105 - enum member, not a credential; rule does not apply.
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
@dataclass(frozen=True, slots=True)
|
|
53
|
+
class RuleOutcome:
|
|
54
|
+
"""The result of evaluating a single rule against a proposal.
|
|
55
|
+
|
|
56
|
+
``overridable`` declares whether a human override may change this
|
|
57
|
+
outcome. It only matters for a ``DENY``: the default is a soft deny
|
|
58
|
+
that a human override may lift (break glass), while a safety-critical
|
|
59
|
+
rule sets ``overridable=False`` to make its deny absolute. Only a
|
|
60
|
+
``DENY`` may declare itself non-overridable.
|
|
61
|
+
"""
|
|
62
|
+
|
|
63
|
+
verdict: RuleVerdict
|
|
64
|
+
rule_id: str
|
|
65
|
+
reason: str
|
|
66
|
+
overridable: bool = True
|
|
67
|
+
|
|
68
|
+
def __post_init__(self) -> None:
|
|
69
|
+
require_instance(self.verdict, RuleVerdict, "RuleOutcome.verdict")
|
|
70
|
+
require_instance(self.rule_id, str, "RuleOutcome.rule_id")
|
|
71
|
+
require_instance(self.reason, str, "RuleOutcome.reason")
|
|
72
|
+
require_instance(self.overridable, bool, "RuleOutcome.overridable")
|
|
73
|
+
if not self.overridable and self.verdict is not RuleVerdict.DENY:
|
|
74
|
+
raise ValueError(
|
|
75
|
+
"only a DENY outcome may be non-overridable; "
|
|
76
|
+
f"got verdict {self.verdict.value!r}"
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
@runtime_checkable
|
|
81
|
+
class ActionRule(Protocol):
|
|
82
|
+
"""A single, self-contained authorization rule.
|
|
83
|
+
|
|
84
|
+
A rule only evaluates a proposal; it never mutates state, never
|
|
85
|
+
persists and never executes the action (``PROPOSAL != EXECUTION``).
|
|
86
|
+
"""
|
|
87
|
+
|
|
88
|
+
@property
|
|
89
|
+
def rule_id(self) -> str:
|
|
90
|
+
"""Stable identifier of this rule."""
|
|
91
|
+
... # pragma: no cover - protocol body, never executed
|
|
92
|
+
|
|
93
|
+
def evaluate(self, proposal: ActionProposal) -> RuleOutcome:
|
|
94
|
+
"""Evaluate the rule against an immutable action proposal."""
|
|
95
|
+
... # pragma: no cover - protocol body, never executed
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
@dataclass(frozen=True, slots=True)
|
|
99
|
+
class PolicyVerdict:
|
|
100
|
+
"""The immutable result of evaluating a proposal against a policy.
|
|
101
|
+
|
|
102
|
+
``authorization`` is present exactly when the verdict is ``ALLOW`` or
|
|
103
|
+
``DENY``. A ``NEED_HUMAN`` verdict never carries an authorization —
|
|
104
|
+
it is a gate state, not an authorization.
|
|
105
|
+
|
|
106
|
+
``overridable`` tells the gate whether a human override may change the
|
|
107
|
+
outcome. Only a ``DENY`` may be non-overridable: a hard deny (e.g. a
|
|
108
|
+
safety-critical prohibition) is absolute and cannot be lifted by a
|
|
109
|
+
human override.
|
|
110
|
+
"""
|
|
111
|
+
|
|
112
|
+
verdict: ActionVerdict
|
|
113
|
+
authorization: AuthorizationRecord | None
|
|
114
|
+
triggered_rules: tuple[str, ...]
|
|
115
|
+
overridable: bool = True
|
|
116
|
+
|
|
117
|
+
def __post_init__(self) -> None:
|
|
118
|
+
require_instance(self.verdict, ActionVerdict, "PolicyVerdict.verdict")
|
|
119
|
+
if self.authorization is not None:
|
|
120
|
+
require_instance(
|
|
121
|
+
self.authorization,
|
|
122
|
+
AuthorizationRecord,
|
|
123
|
+
"PolicyVerdict.authorization",
|
|
124
|
+
)
|
|
125
|
+
for index, rule_id in enumerate(self.triggered_rules):
|
|
126
|
+
require_instance(rule_id, str, f"PolicyVerdict.triggered_rules[{index}]")
|
|
127
|
+
require_instance(self.overridable, bool, "PolicyVerdict.overridable")
|
|
128
|
+
if self.verdict is ActionVerdict.NEED_HUMAN and self.authorization is not None:
|
|
129
|
+
raise ValueError(
|
|
130
|
+
"a NEED_HUMAN verdict must not carry an authorization: "
|
|
131
|
+
"NEED_HUMAN is a gate state, not an authorization"
|
|
132
|
+
)
|
|
133
|
+
if self.verdict is not ActionVerdict.NEED_HUMAN and self.authorization is None:
|
|
134
|
+
raise ValueError("an ALLOW or DENY verdict must carry an authorization")
|
|
135
|
+
if not self.overridable and self.verdict is not ActionVerdict.DENY:
|
|
136
|
+
raise ValueError(
|
|
137
|
+
"only a DENY verdict may be non-overridable; "
|
|
138
|
+
f"got verdict {self.verdict.value!r}"
|
|
139
|
+
)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
class ActionPolicy:
|
|
143
|
+
"""Authorize or deny agent actions based on an ordered set of rules.
|
|
144
|
+
|
|
145
|
+
Rules are evaluated in order; the first rule that does not ``PASS``
|
|
146
|
+
decides the verdict. When no rule decides (no rules configured, or
|
|
147
|
+
every rule passes) the policy fails closed to ``NEED_HUMAN``.
|
|
148
|
+
"""
|
|
149
|
+
|
|
150
|
+
def __init__(self, *, rules: Sequence[ActionRule] = ()) -> None:
|
|
151
|
+
self._rules: tuple[ActionRule, ...] = tuple(rules)
|
|
152
|
+
|
|
153
|
+
def evaluate(
|
|
154
|
+
self,
|
|
155
|
+
proposal: ActionProposal,
|
|
156
|
+
*,
|
|
157
|
+
timestamp: Timestamp | None = None,
|
|
158
|
+
) -> PolicyVerdict:
|
|
159
|
+
"""Evaluate a proposal and return an immutable policy verdict.
|
|
160
|
+
|
|
161
|
+
``timestamp`` overrides the authorization time; it defaults to the
|
|
162
|
+
proposal's own timestamp.
|
|
163
|
+
"""
|
|
164
|
+
authorized_at = proposal.proposed_at if timestamp is None else timestamp
|
|
165
|
+
triggered: list[str] = []
|
|
166
|
+
for rule in self._rules:
|
|
167
|
+
outcome = rule.evaluate(proposal)
|
|
168
|
+
if outcome.verdict is RuleVerdict.PASS:
|
|
169
|
+
continue
|
|
170
|
+
triggered.append(outcome.rule_id)
|
|
171
|
+
if outcome.verdict is RuleVerdict.ALLOW:
|
|
172
|
+
return PolicyVerdict(
|
|
173
|
+
verdict=ActionVerdict.ALLOW,
|
|
174
|
+
authorization=self._authorization(
|
|
175
|
+
ActionVerdict.ALLOW, outcome.rule_id, authorized_at
|
|
176
|
+
),
|
|
177
|
+
triggered_rules=tuple(triggered),
|
|
178
|
+
)
|
|
179
|
+
if outcome.verdict is RuleVerdict.DENY:
|
|
180
|
+
return PolicyVerdict(
|
|
181
|
+
verdict=ActionVerdict.DENY,
|
|
182
|
+
authorization=self._authorization(
|
|
183
|
+
ActionVerdict.DENY, outcome.rule_id, authorized_at
|
|
184
|
+
),
|
|
185
|
+
triggered_rules=tuple(triggered),
|
|
186
|
+
overridable=outcome.overridable,
|
|
187
|
+
)
|
|
188
|
+
# RuleVerdict.NEED_HUMAN — terminal, but never an authorization.
|
|
189
|
+
return PolicyVerdict(
|
|
190
|
+
verdict=ActionVerdict.NEED_HUMAN,
|
|
191
|
+
authorization=None,
|
|
192
|
+
triggered_rules=tuple(triggered),
|
|
193
|
+
)
|
|
194
|
+
# No rule decided (no rules, or all PASS) — fail closed.
|
|
195
|
+
return PolicyVerdict(
|
|
196
|
+
verdict=ActionVerdict.NEED_HUMAN,
|
|
197
|
+
authorization=None,
|
|
198
|
+
triggered_rules=(),
|
|
199
|
+
)
|
|
200
|
+
|
|
201
|
+
@staticmethod
|
|
202
|
+
def _authorization(
|
|
203
|
+
verdict: ActionVerdict,
|
|
204
|
+
reference: str,
|
|
205
|
+
authorized_at: Timestamp,
|
|
206
|
+
) -> AuthorizationRecord:
|
|
207
|
+
"""Build the SYSTEM_POLICY authorization for an ALLOW/DENY verdict."""
|
|
208
|
+
return AuthorizationRecord(
|
|
209
|
+
kind=AuthorizationKind.SYSTEM_POLICY,
|
|
210
|
+
verdict=verdict,
|
|
211
|
+
reference=reference,
|
|
212
|
+
authorized_at=authorized_at,
|
|
213
|
+
)
|