A browser click cannot assert CERTAIN, and the graph takes keyboard input

Three findings from operating the UI.

The web form could write CERTAIN with an empty rationale. In the store that
sat level with an OFAC designation --- and `docs/data-sources.md` says the
ceilings are enforced in code rather than merely documented, and that only a
published legal fact may assert CERTAIN. The form even labels the field
"why --- required below medium" and then did not require it. Now capped at
HIGH, and above MEDIUM needs a reason. The reply says when it lowered a
claim and why: a silent downgrade is its own defect, because the writer
believes the store holds CERTAIN and it does not.

Twenty-seven graph nodes, none in the tab order. Selecting an address is the
primary interaction of this tool and it was reachable only by pointing at
it. The roster list gave a keyboard path to the same action, but a graph
nobody can enter is not an accessible graph --- it is a picture with a
workaround beside it. Nodes are now buttons with labels that include the
address and, for a frontier, the fact that nobody looked past it. That last
part matters: the dashed border carries the difference between "the money
stopped" and "we stopped", and a dashed border is invisible to a reader who
cannot see it.

Focus was invisible everywhere --- the reset removed the browser default and
nothing replaced it, so a keyboard user could cross 79 controls without ever
seeing where they were.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FXWQ25VgFeMuuMhGWjvdof

Author: Toby1009

src/chainscope/server/local.py

@@ -580,18 +580,31 @@ def tag(self, body: dict[str, Any]) -> dict[str, Any]:
         origin = f"browser:{self.options.agent_name}"
         supplied = str(body.get("source", "")).strip()
         source = f"{origin} (reported: {supplied})" if supplied else origin
+        # Inside the guard, not before it. Moving this lookup out of the try
+        # turned an unknown level from a named error into a bare KeyError ---
+        # caught by the test that exists to keep that message helpful.
+        try:
+            claimed = Confidence[str(body.get("confidence", "medium")).upper()]
+        except KeyError as exc:
+            raise ValueError(
+                f"unknown confidence {body.get('confidence')!r}; use one of: "
+                + ", ".join(c.name.lower() for c in Confidence)
+            ) from exc
+        rationale = str(body.get("rationale", "")).strip()
+        confidence = _browser_ceiling(claimed, rationale)
+
         try:
             attribution = Attribution(
                 label=label,
                 category=Category(str(body.get("category", "service"))),
-                confidence=Confidence[str(body.get("confidence", "medium")).upper()],
+                confidence=confidence,
                 # MANUAL: a person clicked this while reading the page. That is
                 # exactly the judgement the method field is meant to record.
                 method=Method.MANUAL,
                 source=source,
                 address=address,
                 chain=self._chain(body.get("chain")),
-                rationale=str(body.get("rationale", "")),
+                rationale=rationale,
                 # From the server, never the request --- the same reasoning as
                 # `source` above. A browser-written claim carried no analyst, so
                 # `report` filed a label a person had typed alongside bulk
@@ -617,7 +630,22 @@ def tag(self, body: dict[str, Any]) -> dict[str, Any]:
                 "category": attribution.category.value,
                 "confidence": attribution.confidence.name,
                 "source": attribution.source,
-            }
+            },
+            # Said out loud when the claim was written weaker than it was
+            # asked for. A silent downgrade is its own defect: the writer
+            # believes the store holds CERTAIN, and it does not.
+            "downgraded": (
+                None
+                if confidence == claimed
+                else (
+                    f"asked for {claimed.name}, recorded {confidence.name}: "
+                    + (
+                        "only a published legal fact may assert CERTAIN"
+                        if claimed > Confidence.HIGH
+                        else "above MEDIUM needs a rationale"
+                    )
+                )
+            ),
         }
 
     # ------------------------------------------------------- the browsable UI
@@ -974,6 +1002,31 @@ def _landing_for(options: ServerOptions) -> str:
     return site.landing_page(options.store.exists(), str(options.store), transfers)
 
 
+def _browser_ceiling(claimed: Confidence, rationale: str) -> Confidence:
+    """What a claim typed into a browser is allowed to assert.
+
+    `docs/data-sources.md` says the ceilings are enforced in code rather than
+    merely documented, and that only a published legal fact --- a sanctions
+    designation --- may assert CERTAIN. The web form was outside that rule: a
+    click could write CERTAIN with an empty rationale, and in the store that
+    then sat level with an OFAC listing.
+
+    Two limits, both from rules this package already states elsewhere:
+
+    * CERTAIN is refused outright. A person reading a page is making a
+      judgement, however well founded, and judgement is not a legal fact.
+    * Above MEDIUM needs a reason. The form already labels that field "why ---
+      required below medium" and then did not require it; a HIGH claim whose
+      rationale is empty tells a later reader nothing about why to believe it.
+
+    Lowering rather than raising, always, and the caller reports what it did.
+    """
+    capped = min(claimed, Confidence.HIGH)
+    if capped > Confidence.MEDIUM and not rationale:
+        return Confidence.MEDIUM
+    return capped
+
+
 def _check_address(address: str, chain: ChainId) -> None:
     """Reject an address this chain cannot possibly hold, before spending a request.
 

tests/unit/test_a_browser_click_is_not_a_legal_fact.py

@@ -0,0 +1,54 @@
+"""What a claim typed into the web form is allowed to assert.
+
+`docs/data-sources.md` says the confidence ceilings are enforced in code
+rather than merely documented, and that only a published legal fact --- a
+sanctions designation --- may assert CERTAIN. The web form sat outside that
+rule: a click could write CERTAIN with an empty rationale, and in the store
+it then sat level with an OFAC listing.
+
+The form even labels the field "why --- required below medium" and then did
+not require it.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from chainscope.core.attribution import Confidence
+from chainscope.server.local import _browser_ceiling
+
+
+def test_certain_is_refused_however_it_is_justified() -> None:
+    """A person reading a page is making a judgement, not stating a fact."""
+    assert _browser_ceiling(Confidence.CERTAIN, "I am completely sure") <= Confidence.HIGH
+
+
+def test_above_medium_needs_a_reason() -> None:
+    assert _browser_ceiling(Confidence.HIGH, "") == Confidence.MEDIUM
+
+
+def test_a_reason_earns_high() -> None:
+    assert _browser_ceiling(Confidence.HIGH, "named in the bridge contract") == Confidence.HIGH
+
+
+@pytest.mark.parametrize("level", [Confidence.SPECULATIVE, Confidence.LOW, Confidence.MEDIUM])
+def test_weaker_claims_pass_through_untouched(level: Confidence) -> None:
+    """The ceiling lowers; it must never raise, and must not demand a reason
+    for a claim that is already modest."""
+    assert _browser_ceiling(level, "") == level
+
+
+def test_it_never_raises() -> None:
+    for level in Confidence:
+        for reason in ("", "because"):
+            assert _browser_ceiling(level, reason) <= level
+
+
+def test_the_downgrade_is_reported_not_silent() -> None:
+    """A silent downgrade is its own defect: the writer believes the store
+    holds CERTAIN and it does not."""
+    from pathlib import Path
+
+    handler = Path("src/chainscope/server/local.py").read_text()
+    assert '"downgraded"' in handler
+    assert "only a published legal fact may assert CERTAIN" in handler

tests/unit/test_the_graph_is_reachable_by_keyboard.py

@@ -0,0 +1,65 @@
+"""Selecting an address must not require a mouse.
+
+Measured on the running page: 27 nodes, none in the tab order. Selecting an
+address is the primary interaction of this tool, and it was reachable only by
+pointing at it. The roster list gave a keyboard path to the same action, but a
+graph nobody can enter is not an accessible graph --- it is a picture with a
+workaround beside it.
+
+Focus was also invisible: the CSS reset removed the browser's default ring and
+nothing replaced it, so a keyboard user could move through 79 controls without
+ever seeing where they were.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+GRAPH = Path("web/src/components/graph.tsx")
+CSS = Path("web/src/app/globals.css")
+
+
+@pytest.fixture(scope="module")
+def graph() -> str:
+    return GRAPH.read_text()
+
+
+def test_nodes_are_in_the_tab_order(graph: str) -> None:
+    assert "tabIndex={0}" in graph
+
+
+def test_nodes_announce_themselves(graph: str) -> None:
+    """A screen reader saying "button" 27 times is not a graph."""
+    assert 'role="button"' in graph
+    assert "aria-label=" in graph
+
+
+def test_a_frontier_node_says_so_in_its_label(graph: str) -> None:
+    """The dashed border is invisible to a reader who cannot see it, and it
+    carries the difference between "the money stopped" and "nobody looked"."""
+    # The node's label, not the svg's --- take the one beside role="button".
+    block = graph.split('role="button"')[1][:500]
+    assert "aria-label=" in block
+    assert "frontier" in block, "a dashed border is invisible to a screen reader"
+
+
+def test_enter_and_space_select(graph: str) -> None:
+    """Both, because a role="button" is expected to answer both."""
+    block = graph.split("onKeyDown=")[1][:220]
+    assert '"Enter"' in block and '" "' in block
+    assert "preventDefault" in block, "Space would scroll the page as well"
+
+
+def test_focus_is_visible() -> None:
+    css = CSS.read_text()
+    assert ":focus-visible" in css
+    assert "outline:" in css.split(":focus-visible")[1][:160]
+
+
+def test_focused_nodes_are_visible_against_their_own_border() -> None:
+    """A card already has a border, so the ring has to differ from it."""
+    css = CSS.read_text()
+    block = css.split(".card:focus-visible rect")[1][:200]
+    assert "stroke-width" in block

web/src/app/globals.css

@@ -540,3 +540,21 @@ label.asset input { accent-color: var(--cs-accent); }
   .busy-fill.sliding { animation-duration: 2.4s; }
   .spin { animation-duration: 1.6s; }
 }
+
+/* Focus, made visible.
+   The reset stripped the browser default and nothing replaced it, so a
+   keyboard user could move through 79 controls without ever seeing where
+   they were. Two-colour ring so it survives on both the pale panels and the
+   dark stark callout. */
+:focus-visible {
+  outline: 2px solid var(--cs-accent);
+  outline-offset: 2px;
+  border-radius: 1px;
+}
+.card:focus-visible { outline: none; }
+.card:focus-visible rect {
+  stroke: var(--cs-accent);
+  stroke-width: 3px;
+  paint-order: stroke;
+}
+.callout.stark :focus-visible { outline-color: var(--cs-bg); }

web/src/components/graph.tsx

@@ -181,6 +181,22 @@ export function Graph({
                 className={classes.join(" ")}
                 transform={`translate(${node.x},${node.y})`}
                 onClick={() => onSelect(node.address)}
+                // Selecting an address is the primary interaction here, and
+                // it was reachable only with a mouse: 27 nodes, none in the
+                // tab order. The roster list gave a keyboard path to the same
+                // action, but a graph nobody can enter is not an accessible
+                // graph --- it is a picture with a workaround.
+                tabIndex={0}
+                role="button"
+                aria-label={`${node.label || (node.seed ? "seed" : "unlabelled")}, ${
+                  node.as_written || node.address
+                }${node.frontier ? ", frontier — its counterparties were never fetched" : ""}`}
+                onKeyDown={(event) => {
+                  if (event.key === "Enter" || event.key === " ") {
+                    event.preventDefault();
+                    onSelect(node.address);
+                  }
+                }}
               >
                 <rect width={CARD_W} height={CARD_H} rx={0} />
                 <text className="name" x={10} y={19}>