Scope providers: the bite on an identifier an attacker chose

.github/workflows/ci.yml

@@ -120,7 +120,7 @@ jobs:
           set -eu
           echo "authority: $AUTHORITY ($AUTHORITY_NA not applicable)"
           echo "templates: $TEMPLATES ($TEMPLATES_NA not applicable)"
-          test "$AUTHORITY" = "verified 20/20"
+          test "$AUTHORITY" = "verified 21/21"
           # G13 is N/A on SQLite, the action's default store: SQLite has no clock of its own
           # to diverge from; G15 is N/A because neither document declares `max_attempts`.
           # G16 is graded on both: verify brings its own precondition provider (SPEC-v0.7 §8.9).
@@ -136,7 +136,7 @@ jobs:
           # binds one, so its count is unchanged and its passing total moved 19 to 20 instead.
           test "$AUTHORITY_NA" = "2"
           test "$TEMPLATES" = "verified 11/11"
-          test "$TEMPLATES_NA" = "11"
+          test "$TEMPLATES_NA" = "12"
           test -s verify-badge.json
           test -s verify-report.json
           test -s verify-report.xml

CHANGELOG.md

@@ -29,8 +29,32 @@ any change to one appears here.
   The task reaches the authority decision and the receipt, and **never the action hash**: a field
   on `Action` would move every hash in existence and invalidate every stored approval.
 
+- **Scope providers** (SPEC-v0.9 §5). `Control.execute(scope=...)` and `@protect(scope=...)` take
+  a callable that answers what the calling principal's assigned scope is; **the kernel matches**
+  this action's resource into it, with the relation a grant's `resources:` already uses. It runs
+  **strictly before the reservation** and before the precondition recheck, so a provider that
+  hangs leaves nothing reserved and nothing executed. **G23** grades it.
+
+  This is the bite on an identifier an attacker chose: a grant permits `records.read` on
+  `customer:*`, and until now nothing had an opinion about *whose* record `customer:90210` is.
+
+  Two distinct refusals, never one: `scope_unavailable` when the provider raises, answers with the
+  wrong shape, or answers something the canonicalizer refuses; `out_of_scope` when it answered and
+  the resource is not covered. A non-callable `scope=` is `InvalidArgument`, at decoration time
+  under `@protect`.
+
+  Only the **hash** of what the provider returned reaches the receipt, under its own domain tag so
+  it can never equal a precondition fingerprint over the same mapping. A scope is a list of what a
+  principal may touch, and an evidence store is not the place to keep a second copy of it.
+
+  It **amends `SPEC-v0.7.md` §6.9**, which said v0.9's scope providers would configure the
+  precondition hook rather than add a second one. `SPEC-v0.9.md` §5.2.1 records the amendment and
+  the three mechanical differences that justify it.
+
 ### Changed
 
+- `ctrlrun.receipt/v6` carries `scope_hash` beside `task`, and `ctrlrun.guarantees/v5` carries
+  **G23** beside G24.
 - `ctrlrun.policy/v7`, `ctrlrun.receipt/v6` and `ctrlrun.guarantees/v5`. `tasks:` on a grant is
   refused in a `v6` document rather than ignored, because an older reader would grant the action
   on every task. `DIMENSIONS` grows from six entries to seven, and it is exported and iterated by

src/ctrlrun/receipt.py

@@ -100,7 +100,7 @@
 #: guarantee catalogue's own rule: a key listed here is a key `to_dict` projects, so naming one
 #: before something writes it is a `KeyError` on every receipt, which is the field-level form of
 #: a stub row. Item 7 asserts all three are present before the release.
-_V6_KEYS: Final = (*_V5_KEYS, "task")
+_V6_KEYS: Final = (*_V5_KEYS, "task", "scope_hash")
 _KEYS: Final = {
     _V1: _V1_KEYS,
     _V2: _V2_KEYS,
@@ -476,6 +476,12 @@ class Receipt:
     #: which is every 0.8.0 call. **Not part of the action hash** (§6.3.1): a field on `Action`
     #: would move every hash in existence and invalidate every stored approval.
     task: str | None = None
+    #: SPEC-v0.9 §5.5: `"sha256:…"` over what the scope provider returned, or `None` where none
+    #: was configured. **The hash and never the scope**: a scope is a list of what a principal
+    #: may touch, and an evidence store is not the place to accumulate a second copy of an
+    #: authorization system's state (`v0.7 §6.10`). Its own domain tag, so it can never equal a
+    #: precondition fingerprint over the same mapping.
+    scope_hash: str | None = None
     #: The schema this receipt is written under (§6.11). A receipt this binary builds is
     #: `RECEIPT_SCHEMA`; one read from a store keeps the label its document declared, or `""`
     #: where it declared none, which renders with no `schema` key at all.
@@ -568,6 +574,7 @@ def _full_document(self) -> dict[str, Any]:
             # conditional key is a `KeyError`, and a reader tells "no task" from "this binary
             # predates tasks" by the schema label.
             "task": self.task,
+            "scope_hash": self.scope_hash,
         }
 
     def to_json(self) -> str:
@@ -658,6 +665,11 @@ def from_dict(cls, document: Mapping[str, Any]) -> Receipt:
                 if schema == _V6 and isinstance(document.get("task"), str)
                 else None
             ),
+            scope_hash=(
+                document.get("scope_hash")
+                if schema == _V6 and isinstance(document.get("scope_hash"), str)
+                else None
+            ),
             schema=schema,
         )
 

src/ctrlrun/verify/guarantees.py

@@ -151,6 +151,15 @@ class Guarantee:
         "unapproved policy decides no",
         ("v0.6 §7.1", "v0.8 §10 T354", "v0.8 §10 T355"),
     ),
+    Guarantee(
+        "G23",
+        # 32 characters exactly, against `report._TITLE_WIDTH`. "a failing scope provider" and
+        # not "an out-of-scope record": what G23 grades is the **unavailable** half, because
+        # that is the one where a kernel could plausibly fail open by treating an unreadable
+        # scope as an empty constraint (SPEC-v0.9 §5.6, §8).
+        "a failing scope provider refuses",
+        ("v0.9 §5.6", "v0.9 §9 T388", "v0.9 §9 T390"),
+    ),
     Guarantee(
         "G24",
         # 26 characters against `report._TITLE_WIDTH`'s 32. "grant refused" and not "action
@@ -248,6 +257,21 @@ class Guarantee:
 #: SPEC-v0.9 §8, G24. A statement about the operator's **document**, like every reason in this
 #: module: it says what the document does not declare, not what the kernel is not configured for.
 NO_TASKS: Final = "no grant names a task"
+#: SPEC-v0.9 §8.1, G23. A statement about the **document**, which is what §8.1's argument
+#: actually requires: it forbids an `N/A` about whether a *provider* is configured, because that
+#: is a fact about an operator's code. Whether any action this configuration admits carries a
+#: resource is a fact about their document, and a scope names resources, so an action with none
+#: can never be in one.
+NO_RESOURCE_TO_SCOPE: Final = "no action this configuration admits carries a resource"
+
+#: SPEC-v0.9 §8.1 — G23's note, printed beneath its row the way `REVOCATION_NOTE` is. Whether a
+#: deployment configures a scope provider is a fact about its own code, which verify cannot read,
+#: so verify supplies one and says so rather than reporting `N/A` about something it never saw.
+SCOPE_PROVIDER_NOTE: Final = (
+    "G23 is graded against a scope provider verify supplies: whether this deployment configures "
+    "one is a fact about its own code, which verify cannot read. The gateway and the ACS hook "
+    "cannot name a provider at all (SPEC-v0.9 §5.2.2)"
+)
 
 #: SPEC-v0.7 §8.9, G16's note, printed once beneath the table as `EFFECT_TEMPLATE_NOTE` is. G16
 #: is graded against verify's own stand-in for the operator's provider, because a provider is
@@ -351,8 +375,11 @@ class Guarantee:
     "NO_EXPIRES_AT",
     "NO_GRANT_COVERS_SELECTION",
     "NO_GRANT_MATCHES",
+    "NO_RESOURCE_TO_SCOPE",
+    "NO_TASKS",
     "PER_CONNECTION_BACKEND",
     "PROCESSES",
+    "SCOPE_PROVIDER_NOTE",
     "STORE_READS_APPLICATION_CLOCK",
     "SYNTHETIC_PREFIX",
     "Guarantee",

src/ctrlrun/verify/scenarios.py

@@ -63,7 +63,7 @@
     Subject,
     contained_dimension,
 )
-from ..control import Control, context, idempotency_token, protect
+from ..control import SCOPE_UNAVAILABLE, Control, context, idempotency_token, protect
 from ..effect import (
     EffectRecord,
     EffectState,
@@ -1087,6 +1087,7 @@ def execute(
         approval_id: str | None,
         preconditions: Callable[[Action], Mapping[str, Any]] | None = None,
         task: str | None = None,
+        scope: Callable[[Action], Mapping[str, Any]] | None = None,
     ) -> Receipt:
         # SPEC-v0.9 §6.3.2 — the active selection's task unless a scenario named one, so a
         # document that binds its grant to a task does not turn every other guarantee red. G24
@@ -1096,13 +1097,13 @@ def execute(
             task = self._task
         if approval_id is None:
             return control.execute(
-                action, executor, effect_key, preconditions=preconditions, task=task
+                action, executor, effect_key, preconditions=preconditions, task=task, scope=scope
             )
         from ..control import with_approval
 
         with with_approval(approval_id):
             return control.execute(
-                action, executor, effect_key, preconditions=preconditions, task=task
+                action, executor, effect_key, preconditions=preconditions, task=task, scope=scope
             )
 
     def refused(
@@ -3702,6 +3703,93 @@ def body(detail: dict[str, Any]) -> None:
         finally:
             store.close()
 
+    # --- G23: a scope provider that cannot answer refuses ---------------------------------
+
+    def g23(self) -> GuaranteeResult:
+        """SPEC-v0.9 §5.6, §8, and §8.1 on why this one is never `N/A`.
+
+        A scope provider is a Python callable an operator passes at decoration or call time, so
+        no document states whether one is configured and `verify` reads a document. Rather than
+        report `N/A` for a fact it cannot observe, verify **constructs the scenario**: it wires a
+        provider that raises and grades what the kernel does, the way `v0.4 §3` has it construct
+        every other scenario.
+
+        Both halves, `v0.4 §1.3`. The positive control is a provider that answers and admits the
+        resource, without which a kernel refusing every scoped action would grade `PASS`.
+        """
+        selection = self.select()
+        if selection is None:
+            return self.na("G23", self.unselected(reg.EVERY_ACTION_DENIED))
+        # A scope names resources, so an action carrying none can never be in one (§5.6, and
+        # `v0.3 §4.4`'s rule for a grant that declares `resources:`). Where nothing this document
+        # admits has a resource, there is no scope question to grade, and saying so is a
+        # statement about the document rather than about the operator's code.
+        if selection.resource is None:
+            scoped = self.select(needs_effect=False, grant_filter=None)
+            if scoped is None or scoped.resource is None:
+                return self.na("G23", reg.NO_RESOURCE_TO_SCOPE)
+            selection = scoped
+        control, store, recorder, _ = self._control_for("G23", selection)
+        resource = selection.resource
+
+        def body(detail: dict[str, Any]) -> None:
+            detail["resource"] = resource
+            detail["note"] = reg.SCOPE_PROVIDER_NOTE
+            # The control: a provider that answers, admitting exactly this resource.
+            answering = _Executor()
+            action = selection.build()
+            receipt = self.execute(
+                control,
+                action,
+                answering,
+                selection.effect_key,
+                self.approve(control, store, action, selection),
+                scope=lambda _action: {"resources": [str(resource)]},
+            )
+            _expect_control(
+                receipt.result is ReceiptResult.COMMITTED and answering.calls == 1,
+                "a provider that answers, admitting this resource, lets the action run",
+                f"it ended {receipt.result} after {answering.calls} executor calls",
+            )
+
+            def unavailable(_action: Action) -> Mapping[str, Any]:
+                raise RuntimeError(f"{reg.SYNTHETIC_PREFIX}: the scope source is unreachable")
+
+            later = selection.build()
+            blocked = _Executor()
+            refusal = self.refused(
+                lambda: self.execute(
+                    control, later, blocked, selection.effect_key, None, scope=unavailable
+                ),
+                (ActionDenied,),
+                "ActionDenied(reason='scope_unavailable') when the provider raises",
+                "the action ran with no scope answer",
+            )
+            reason = getattr(refusal, "reason", "")
+            _expect(
+                reason == SCOPE_UNAVAILABLE,
+                "ActionDenied(reason='scope_unavailable')",
+                f"ActionDenied(reason={reason!r})",
+            )
+            _expect(
+                blocked.calls == 0,
+                "the executor is not reached when the scope cannot be read",
+                f"the executor was called {blocked.calls} times",
+            )
+            # **Nothing reserved**, which is the half of G23 that the ordering exists for: a
+            # provider called after the reservation would leave a lease to lapse.
+            record = store.get_effect(str(selection.effect_key))
+            _expect(
+                record is None or record.state is not EffectState.RESERVED,
+                "nothing is left reserved when the scope provider fails",
+                f"the effect record is {None if record is None else record.state}",
+            )
+
+        try:
+            return self.graded("G23", selection, store, recorder, body)
+        finally:
+            store.close()
+
     # --- G24: a task-bound grant is refused off its task ----------------------------------
 
     def g24(self) -> GuaranteeResult:

tests/test_demo.py

@@ -107,6 +107,8 @@
     "authority_grant_id",
     # SPEC-v0.9 §6, a `ctrlrun.receipt/v6` field.
     "task",
+    # SPEC-v0.9 §5.5, a `ctrlrun.receipt/v6` field.
+    "scope_hash",
 )
 
 

tests/test_preconditions.py

@@ -2001,6 +2001,16 @@ def _guarantee_titles() -> str:
 #: provider to recheck with, a provider that produced nothing to compare, and a 0.6 process the
 #: new one has no way to see.
 ANOTHER_SUBJECT: dict[str, tuple[str, ...]] = {
+    "docstrings": (
+        # SPEC-v0.9 §5. The subject is the **scope provider**, not the precondition recheck, and
+        # the claim is true of it in a way it is not true of the recheck: the scope fetch happens
+        # strictly before the reservation, so a provider that hangs leaves nothing reserved and
+        # nothing executed. That is a closed hole and not a narrowed window, which is precisely
+        # why this guard exists to keep the two apart. §5.8 states the window the scope provider
+        # *does* widen, and says so there rather than claiming otherwise here.
+        "It runs **strictly before the reservation** and before the precondition recheck, so a "
+        "provider that hangs can only fail closed.",
+    ),
     "CHANGELOG.md": (
         '"a moved fingerprint is refused" before the reservation, under `ctrlrun.guarantees/v3`.',
         # "fail-closed" beside the approver string `ctrlrun:precondition-not-recorded`.
@@ -2335,7 +2345,7 @@ def test_every_schema_renders_under_its_own_label_and_key_set():
         "ctrlrun.receipt/v3": 26,
         "ctrlrun.receipt/v4": 28,
         "ctrlrun.receipt/v5": 30,
-        "ctrlrun.receipt/v6": 31,
+        "ctrlrun.receipt/v6": 32,
         "ctrlrun.receipt/v9": 26,
         "": 25,
     }

tests/test_protect.py

@@ -696,6 +696,8 @@ def read(customer_id: str) -> None: ...
         "authority_grant_id",
         # SPEC-v0.9 §6, a `ctrlrun.receipt/v6` field.
         "task",
+        # SPEC-v0.9 §5.5, a `ctrlrun.receipt/v6` field.
+        "scope_hash",
     }
     assert document["schema"] == RECEIPT_SCHEMA
     assert document["receipt_id"].startswith("ctr_")