capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/guards/checks/promise_requires_approval.py

@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: Apache-2.0
+"""promise_requires_approval check: a class of statement the agent may make
+only inside its task authority or with a one-shot approval.
+
+Reads ``Action.representation_class``, one member of the closed set
+``representation_classes``. A class outside ``requires_approval`` passes. A
+class inside it passes on either of two bases, named in the evidence's
+``authority_basis``:
+
+- ``task_authority_ref``: the task authority already allows it. The sealed
+  task-authority record is read only when the engine's own digest of it
+  equals ``Action.task_authority_ref``
+  (``task_authority.bind_task_authority_record``), and its
+  ``body.authorized_representation_classes`` (``AUTHORIZED_PATH``) lists the
+  class. No approval event is needed. From 1.1.0 the wicket config names
+  the path (``authorized_path``): capsulectl's task authority seals the
+  classes the user ordered at ``body.ordered_representations``, and the
+  list counts only when every member is a class in
+  ``representation_classes``; a malformed list allows nothing. 1.0.0 names
+  none and reads ``AUTHORIZED_PATH`` as it always did.
+- ``authorized_by``: a bound approval for a statement outside the task
+  authority. ``Action.authorized_by`` is the SHA-256 digest of the WHOLE
+  sealed approval record, that record is supplied beside the action for one
+  decision (``GuardEngine.check(..., authorization_record=...)``), the
+  engine recomputes its digest itself (``authorization_record_digest``) and
+  reads it ONLY when that equals the reference, and the record's
+  ``body.representation_class`` (``CLASS_PATH``) names this action's class.
+
+Anything less fails: no reference, no record, a record the reference does
+not bind, a record with no digest, or an approval for another class. Never
+``n/a``: an unreadable approval is no approval. Under 1.1.0 a failure on an
+action that cites no task authority (an x-deal-v0 deal has none) reads
+"no order or approval of yours covers this promise"; 1.0.0 keeps its
+own reasons for that failure. Both name a class after its article ("an
+authenticity statement"). A class no approval may
+clear belongs to ``promise_never``, not here.
+
+A class outside the closed set fails closed. Applies only to the configured
+``action_classes``.
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+from agent_action_capsule import json_digest
+from agent_action_capsule.canonical import FloatInDigestError, UnsafeIntegerError
+
+from ..action import Action
+from ..capsule import ConstraintOutcome, NotApplicableEvidence, not_applicable_evidence
+from .base import CheckOutcome
+from .promise_never import with_article
+from .required_disclosure import require_known_classes
+from .task_authority import TaskAuthorityRecord, UnboundRecord, bind_task_authority_record
+
+__all__ = [
+    "AUTHORIZED_PATH",
+    "CLASS_PATH",
+    "AuthorizationBody",
+    "AuthorizationRecord",
+    "authorization_record_digest",
+    "check_promise_requires_approval",
+]
+
+_CHECK_ID = "promise_requires_approval"
+_METHOD = "authority_or_bound_approval_v0"
+
+# Where the approved class sits inside the sealed approval record, one member
+# name per level.
+CLASS_PATH: tuple[str, ...] = ("body", "representation_class")
+# Where the classes the task authority allows sit inside the sealed
+# task-authority record.
+AUTHORIZED_PATH: tuple[str, ...] = ("body", "authorized_representation_classes")
+
+
+class AuthorizationBody(TypedDict):
+    representation_class: str
+
+
+class AuthorizationRecord(TypedDict):
+    """The whole sealed approval record as decoded JSON, digested
+    byte-for-byte as supplied. Only the approved class is named here; any
+    other member the producer seals is covered by the digest and otherwise
+    unread."""
+
+    body: AuthorizationBody
+
+
+class PromiseEvidence(TypedDict):
+    representation_class: str
+    recognised: bool
+    requires_approval: bool
+    authority_basis: str | None
+    task_authority_ref: str | None
+    authorized_by: str | None
+
+
+def authorization_record_digest(record: AuthorizationRecord) -> str:
+    """The digest ``authorized_by`` carries for ``record``: SHA-256 over the
+    record's JCS bytes."""
+    return json_digest(record)
+
+
+class _Unapproved(Exception):
+    """The supplied approval does not approve this statement; the message says why."""
+
+
+def _approved_class(action: Action, record: AuthorizationRecord | None) -> str:
+    """The class the bound approval names. Raises ``_Unapproved`` when the
+    record is missing, unbound or names no class."""
+    ref = action.authorized_by
+    if ref is None:
+        raise _Unapproved("the action cites no approval (authorized_by)")
+    if record is None:
+        raise _Unapproved("no approval record was supplied for authorized_by")
+    try:
+        bound = authorization_record_digest(record) == ref
+    except (FloatInDigestError, UnsafeIntegerError) as exc:
+        raise _Unapproved(f"the supplied approval record has no digest ({exc})") from exc
+    if not bound:
+        raise _Unapproved("ref mismatch: the supplied approval record is not the record authorized_by names")
+    node: object = record
+    for name in CLASS_PATH:
+        # Decoded JSON: each level is checked before it is read.
+        if not isinstance(node, dict) or name not in node:
+            raise _Unapproved(f"the approval record names no class at {'.'.join(CLASS_PATH)}")
+        node = node[name]
+    if not isinstance(node, str):
+        raise _Unapproved(f"the approval record's {'.'.join(CLASS_PATH)} is not one class")
+    return node
+
+
+def _authority_allows(action: Action, record: TaskAuthorityRecord | None, cls: str,
+                      path: tuple[str, ...], known: list[str] | None = None) -> bool:
+    """Whether the bound task authority lists ``cls`` at ``path``. An unbound
+    or silent record allows nothing; the approval is then the only basis
+    left. With ``known`` (1.1.0), the list counts only when every member is
+    one of those class names: a list holding anything else is malformed and
+    allows nothing."""
+    try:
+        _, bound = bind_task_authority_record(action, record)
+    except UnboundRecord:
+        # No bound authority is not an error here: the approval is then the
+        # only basis, and a failure's reason names what the approval lacked.
+        return False
+    node: object = bound
+    for name in path:
+        # Decoded JSON: each level is checked before it is read.
+        if not isinstance(node, dict) or name not in node:
+            return False
+        node = node[name]
+    if not isinstance(node, list):
+        return False
+    if known is not None and not all(isinstance(c, str) and c in known for c in node):
+        return False
+    return cls in node
+
+
+def _outcome(result: str, reason: str, evidence: PromiseEvidence | NotApplicableEvidence) -> CheckOutcome:
+    return CheckOutcome(
+        constraint=ConstraintOutcome(
+            id=_CHECK_ID, result=result, reason=reason, evidence=evidence, check_type="policy", method=_METHOD
+        )
+    )
+
+
+def check_promise_requires_approval(
+    action: Action,
+    task_authority_record: TaskAuthorityRecord | None,
+    authorization_record: AuthorizationRecord | None,
+    *,
+    representation_classes: list[str],
+    requires_approval: list[str],
+    action_classes: list[str],
+    authorized_path: list[str] | None = None,
+) -> CheckOutcome:
+    require_known_classes(requires_approval, representation_classes, what="requires_approval")
+    if action.action_class not in action_classes:
+        return _outcome("n/a", "the rule is not configured for this action class",
+                        not_applicable_evidence(_CHECK_ID, in_scope=False))
+    cls = action.representation_class
+    if cls is None:
+        return _outcome("n/a", "the action carries no representation_class; the statement could not be classed",
+                        not_applicable_evidence(_CHECK_ID, in_scope=True, missing_field="representation_class"))
+    recognised = cls in representation_classes
+    needs = cls in requires_approval
+
+    def evidence(basis: str | None) -> PromiseEvidence:
+        return PromiseEvidence(representation_class=cls, recognised=recognised, requires_approval=needs,
+                               authority_basis=basis, task_authority_ref=action.task_authority_ref,
+                               authorized_by=action.authorized_by)
+
+    if not recognised:
+        return _outcome("fail", f"representation_class {cls!r} is not in {representation_classes}", evidence(None))
+    if not needs:
+        return _outcome("pass", f"{with_article(cls)} statement needs no approval", evidence(None))
+    path = AUTHORIZED_PATH if authorized_path is None else tuple(authorized_path)
+    known = representation_classes if authorized_path is not None else None
+    if _authority_allows(action, task_authority_record, cls, path, known):
+        return _outcome("pass", f"the task authority allows {with_article(cls)} statement", evidence("task_authority_ref"))
+    try:
+        approved = _approved_class(action, authorization_record)
+    except _Unapproved as exc:
+        why = str(exc)
+    else:
+        if approved == cls:
+            return _outcome("pass", f"the {cls} statement cites a bound approval for {cls}",
+                            evidence("authorized_by"))
+        why = f"the approval is for {approved}, not {cls}"
+    reason = f"{with_article(cls)} statement is outside the task authority and needs a bound approval: {why}"
+    if authorized_path is not None and action.task_authority_ref is None:
+        # What the user's card says (design note capsule-engine#194 §2): the
+        # evidence still records the class and what was cited.
+        reason = "no order or approval of yours covers this promise"
+    return _outcome("fail", reason, evidence(None))

capsule_engine/guards/checks/recipient_role.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: Apache-2.0
+"""recipient_role check: membership of the disclosure recipient's role.
+
+Reads ``Action.recipient_role``, one member of the closed set ``roles``
+the wicket pins (``fulfilling_merchant``, ``third_party``, ``self``; a
+seller's set is ``buyer``, ``third_party``, ``self``), and passes when it is
+one of ``allowed_roles``. A role outside ``roles`` fails closed and the
+evidence says it was not recognised. It records the role, never who the
+recipient is. Applies only to the configured ``action_classes``.
+
+``role_classes`` (optional) names roles that pass only for some classes of
+data: ``{platform: [email]}`` passes a disclosure to a platform when every
+class in ``Action.disclosed_classes`` is ``email``. One that gives any other
+class fails, and so does one that names no class, since it cannot be shown
+to give only those. A wicket that sets it records the classes it read and the
+roles' classes in the evidence; one that does not keeps the evidence it had.
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+from ..action import Action
+from ..capsule import ConstraintOutcome, NotApplicableEvidence, not_applicable_evidence
+from .base import CheckOutcome
+
+__all__ = ["check_recipient_role"]
+
+_CHECK_ID = "recipient_role"
+_METHOD = "set_membership_v0"
+
+
+class RoleEvidence(TypedDict):
+    recipient_role: str
+    recognised: bool
+    allowed_roles: list[str]
+
+
+class RoleClassesEvidence(RoleEvidence):
+    role_classes: dict[str, list[str]]
+    disclosed_classes: list[str] | None
+
+
+def _outcome(
+    result: str, reason: str, evidence: RoleEvidence | RoleClassesEvidence | NotApplicableEvidence
+) -> CheckOutcome:
+    return CheckOutcome(
+        constraint=ConstraintOutcome(
+            id=_CHECK_ID, result=result, reason=reason, evidence=evidence, check_type="policy", method=_METHOD
+        )
+    )
+
+
+def _either(words: list[str]) -> str:
+    """``a``, ``a or b``, ``a, b or c``; ``no role`` for none."""
+    if not words:
+        return "no role"
+    return words[0] if len(words) == 1 else f"{', '.join(words[:-1])} or {words[-1]}"
+
+
+def _passing(allowed: list[str], role_classes: dict[str, list[str]]) -> str:
+    """The roles that pass, once: ``fulfilling_merchant or self, or a
+    platform given only email``."""
+    limited = [f"a {role} given only {_either(classes)}" for role, classes in sorted(role_classes.items())]
+    if not allowed:
+        return _either(limited)
+    return _either(allowed) + "".join(f", or {phrase}" for phrase in limited)
+
+
+def check_recipient_role(
+    action: Action,
+    *,
+    roles: list[str],
+    allowed_roles: list[str],
+    action_classes: list[str],
+    role_classes: dict[str, list[str]] | None = None,
+) -> CheckOutcome:
+    limited = {role: sorted(classes) for role, classes in (role_classes or {}).items()}
+    misplaced = sorted(set(limited) - set(roles)) + sorted(set(limited) & set(allowed_roles))
+    if misplaced or any(not classes for classes in limited.values()):
+        raise ValueError(
+            "role_classes must name roles in roles and not in allowed_roles, each with at least one class; "
+            f"got {sorted(limited)}"
+        )
+    if action.action_class not in action_classes:
+        return _outcome("n/a", "the rule is not configured for this action class",
+                        not_applicable_evidence(_CHECK_ID, in_scope=False))
+    role = action.recipient_role
+    if role is None:
+        return _outcome("n/a", "the action carries no recipient_role; the recipient's role could not be checked",
+                        not_applicable_evidence(_CHECK_ID, in_scope=True, missing_field="recipient_role"))
+    recognised = role in roles
+    allowed = sorted(allowed_roles)
+    evidence: RoleEvidence | RoleClassesEvidence = RoleEvidence(
+        recipient_role=role, recognised=recognised, allowed_roles=allowed
+    )
+    if role_classes is not None:
+        disclosed = list(action.disclosed_classes) if action.disclosed_classes is not None else None
+        evidence = RoleClassesEvidence(**evidence, role_classes=limited, disclosed_classes=disclosed)
+    passing = _passing(allowed, limited)
+    # A role outside the closed set fails even if ``allowed_roles`` names it.
+    if not recognised:
+        return _outcome("fail", f"recipient_role {role!r} is not a role this rule knows; personal data "
+                        f"passes only to {passing}", evidence)
+    if role in allowed:
+        return _outcome("pass", f"the recipient is the {role}", evidence)
+    if role in limited:
+        classes = limited[role]
+        if action.disclosed_classes is None:
+            return _outcome("fail", f"the recipient is a {role}, which may be given only {_either(classes)}; "
+                            "the disclosure names no class of data", evidence)
+        others = [c for c in action.disclosed_classes if c not in classes]
+        if others:
+            return _outcome("fail", f"the recipient is a {role}, which may be given only {_either(classes)}; "
+                            f"this disclosure also gives {_either(others)}", evidence)
+        return _outcome("pass", f"the recipient is a {role}, given only {_either(list(action.disclosed_classes))}",
+                        evidence)
+    return _outcome("fail", f"the recipient is a {role}; personal data passes only to {passing}", evidence)

capsule_engine/guards/checks/recurring_charge.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+"""recurring_charge check: a read of the action's declared recurrence.
+
+Fails when ``Action.recurrence`` is present and is not one of the configured
+``one_time_values`` -- that is, when the payment sets up a charge that
+repeats. Applies only to the configured ``action_classes``.
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+from ..action import Action
+from ..capsule import ConstraintOutcome, NotApplicableEvidence, not_applicable_evidence
+from .base import CheckOutcome
+
+__all__ = ["check_recurring_charge"]
+
+_CHECK_ID = "recurring_charge"
+_METHOD = "structured_field_v0"
+
+
+class RecurrenceEvidence(TypedDict):
+    recurrence: str
+    one_time_values: list[str]
+
+
+def _outcome(result: str, reason: str, evidence: NotApplicableEvidence | RecurrenceEvidence) -> CheckOutcome:
+    return CheckOutcome(
+        constraint=ConstraintOutcome(
+            id=_CHECK_ID, result=result, reason=reason, evidence=evidence, check_type="policy", method=_METHOD
+        )
+    )
+
+
+def check_recurring_charge(action: Action, *, one_time_values: list[str], action_classes: list[str]) -> CheckOutcome:
+    if action.action_class not in action_classes:
+        return _outcome(
+            "n/a", "the rule is not configured for this action class", not_applicable_evidence(_CHECK_ID, in_scope=False)
+        )
+    if action.recurrence is None:
+        return _outcome(
+            "n/a",
+            "the action carries no recurrence; whether it repeats could not be read",
+            not_applicable_evidence(_CHECK_ID, in_scope=True, missing_field="recurrence"),
+        )
+    evidence = RecurrenceEvidence(recurrence=action.recurrence, one_time_values=sorted(one_time_values))
+    if action.recurrence in one_time_values:
+        return _outcome("pass", f"recurrence {action.recurrence!r} is a one-time payment", evidence)
+    return _outcome("fail", f"recurrence {action.recurrence!r} sets up a repeating charge", evidence)

capsule_engine/guards/checks/refundability.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+"""refundability check: can the payment be refunded?
+
+Reads ``Action.refundable`` and fails when it is ``False``. It records the
+value it read and the rail beside it (``None`` when the action names none);
+it does not read the refund terms themselves. Applies only to the configured
+``action_classes``.
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+from ..action import Action
+from ..capsule import ConstraintOutcome, NotApplicableEvidence, not_applicable_evidence
+from .base import CheckOutcome
+
+__all__ = ["check_refundability"]
+
+_CHECK_ID = "refundability"
+_METHOD = "declared_boolean_v0"
+
+
+class RefundabilityEvidence(TypedDict):
+    refundable: bool
+    rail: str | None
+
+
+def _outcome(result: str, reason: str, evidence: RefundabilityEvidence | NotApplicableEvidence) -> CheckOutcome:
+    return CheckOutcome(
+        constraint=ConstraintOutcome(
+            id=_CHECK_ID, result=result, reason=reason, evidence=evidence, check_type="policy", method=_METHOD
+        )
+    )
+
+
+def check_refundability(action: Action, *, action_classes: list[str]) -> CheckOutcome:
+    if action.action_class not in action_classes:
+        return _outcome("n/a", "the rule is not configured for this action class",
+                        not_applicable_evidence(_CHECK_ID, in_scope=False))
+    if action.refundable is None:
+        return _outcome("n/a", "the action carries no refundable; whether it can be undone could not be checked",
+                        not_applicable_evidence(_CHECK_ID, in_scope=True, missing_field="refundable"))
+    evidence = RefundabilityEvidence(refundable=action.refundable, rail=action.rail)
+    if action.refundable:
+        return _outcome("pass", "the payment is refundable", evidence)
+    return _outcome("fail", "the payment is not refundable", evidence)