mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-06-11 02:33:10 +08:00
Compare commits
5 Commits
pr-2026
...
feat/front
| Author | SHA1 | Date | |
|---|---|---|---|
|
95d58fc2dd | ||
|
|
cd52c3b7f2 | ||
|
|
4e4ccebacb | ||
|
|
85b4114248 | ||
|
|
b54a4fc2d0 |
@@ -1,126 +0,0 @@
|
||||
# AURA trust-check adapter
|
||||
|
||||
Opt-in, **read-only** counterparty reputation for agent hosts. One HTTP GET
|
||||
answers *"can I trust this agent before I delegate work or settle a payment?"*
|
||||
|
||||
- **Zero dependencies** — pure Python stdlib. Vendor the `aura/` folder, no `pip install`.
|
||||
- **Read-only** — the only network call is `GET /check?did=...`. No auth, no API key.
|
||||
- **No coupling** — does not sign, hold keys, move funds, or touch your wallet.
|
||||
- **Off by default** — nothing runs until you call it. Disabled = delete the import.
|
||||
|
||||
## Enable (opt-in)
|
||||
|
||||
It's a gate you call explicitly at a trust boundary — there is no global hook,
|
||||
no monkey-patching, no background calls. Wrap the action you want to protect:
|
||||
|
||||
```python
|
||||
from aura import before_settle, AuraUntrusted
|
||||
|
||||
def settle(counterparty_did: str, amount: float) -> None:
|
||||
try:
|
||||
before_settle(counterparty_did) # rejects high_risk + unknown
|
||||
except AuraUntrusted as e:
|
||||
log.warning("blocked: %s", e)
|
||||
return # your policy decides what to do
|
||||
pay(counterparty_did, amount) # your existing logic, untouched
|
||||
```
|
||||
|
||||
Prefer to read the verdict yourself instead of raising?
|
||||
|
||||
```python
|
||||
from aura import aura_verdict
|
||||
|
||||
v = aura_verdict(counterparty_did)
|
||||
print(v.verdict) # trusted | caution | high_risk | new | unknown
|
||||
print(v.reason) # human-readable explanation
|
||||
print(v.score) # composite 0..1, or None when there's no history
|
||||
print(v.ok) # True for trusted/caution
|
||||
|
||||
# v.dimensions tells you *which* axis is weak, not just the aggregate:
|
||||
if v.dimensions and v.dimensions.get("financial_integrity", 1) < 0.4:
|
||||
require_manual_review() # placeholder for your own policy
|
||||
```
|
||||
|
||||
> `v.ok` reflects the *verdict class* (True for `trusted`/`caution`), not the
|
||||
> outcome of `require_trust()` — the gate's default `allow` also lets `new`
|
||||
> through. Use the gate's return/raise for the decision, `v.ok` for display.
|
||||
|
||||
## Verdicts
|
||||
|
||||
| verdict | meaning | `ok` |
|
||||
|---|---|---|
|
||||
| `trusted` | strong on-chain track record (composite ≥ 0.70) | ✅ |
|
||||
| `caution` | mixed history (0.40–0.70) | ✅ |
|
||||
| `high_risk` | poor track record (< 0.40) | ❌ |
|
||||
| `new` | registered identity, no interactions yet | ❌ |
|
||||
| `unknown` | no track record — or AURA was unreachable | ❌ |
|
||||
|
||||
## Policy knobs
|
||||
|
||||
```python
|
||||
# Reject brand-new agents too (strict):
|
||||
before_settle(did, allow=("trusted", "caution"))
|
||||
|
||||
# Treat an *unreachable* AURA as a pass (fail-open). Off by default —
|
||||
# absence of evidence is not evidence of trust.
|
||||
before_settle(did, fail_open=True)
|
||||
|
||||
# Point at a self-hosted / staging gateway:
|
||||
before_settle(did, base_url="https://my-aura-mirror.example", timeout=5)
|
||||
```
|
||||
|
||||
`require_trust` is an alias of `before_settle` for non-payment call sites.
|
||||
|
||||
## Failure behavior
|
||||
|
||||
`aura_verdict()` **never raises on a network or parse error** — it returns an
|
||||
`unknown` verdict with the reason set. The gate then decides:
|
||||
|
||||
- **default (`fail_open=False`)** — `unknown` is rejected → an unreachable AURA
|
||||
blocks the action. *Fail-closed.*
|
||||
- **`fail_open=True`** — `unknown` from an unreachable endpoint is allowed
|
||||
through, so AURA can never take your flow down. *Fail-open.*
|
||||
|
||||
This keeps the trust signal **purely additive**: if you remove the adapter or
|
||||
AURA is down, your existing allow/deny logic runs exactly as before.
|
||||
|
||||
## Tests
|
||||
|
||||
Offline — every call replays a recorded `/check` body, no network:
|
||||
|
||||
```bash
|
||||
python -m pytest aura/tests -q
|
||||
```
|
||||
|
||||
Covers all five verdict classes, the gate's allow-list + `fail_open`, the
|
||||
unreachable path, and input validation. See `tests/fixtures.py` for the
|
||||
recorded response shapes.
|
||||
|
||||
## Boundary & threats
|
||||
|
||||
See [THREAT_MODEL.md](./THREAT_MODEL.md) — what the verdict does and does not
|
||||
prove, and the failure modes a verifier should account for.
|
||||
|
||||
## Carry the AURA badge
|
||||
|
||||
Show your live trust verdict in your own README — it updates automatically and
|
||||
links back to your AURA profile:
|
||||
|
||||
```markdown
|
||||
[](https://agent.auraopenprotocol.org/check?did=YOUR_DID)
|
||||
```
|
||||
|
||||
A shields-style badge colored by verdict (`trusted` green, `caution` amber,
|
||||
`high_risk` red, `new` blue, `unknown` grey). Add `&score=1` to show the
|
||||
composite score. No DID yet? The bare badge is a generic mark:
|
||||
|
||||
```markdown
|
||||
[](https://auraopenprotocol.org)
|
||||
```
|
||||
|
||||
## What's behind the verdict
|
||||
|
||||
[AURA Open Protocol](https://auraopenprotocol.org) — W3C DID identity plus 8
|
||||
on-chain reputation dimensions on Base L2 (`task_completion`, `delivery_speed`,
|
||||
`output_quality`, `honesty`, `financial_integrity`, `security_compliance`,
|
||||
`collaboration`, `dispute_history`). Docs: https://dev.auraopenprotocol.org
|
||||
@@ -1,55 +0,0 @@
|
||||
# Threat model — AURA trust-check adapter
|
||||
|
||||
A short, honest boundary statement. The verdict is **one backward-looking
|
||||
signal**, not a security guarantee. Read this before treating `trusted` as a
|
||||
green light for anything irreversible.
|
||||
|
||||
## What the verdict proves
|
||||
|
||||
- The DID has (or lacks) an on-chain interaction history on AURA, summarized
|
||||
into a composite score and per-dimension breakdown.
|
||||
- It is **backward-looking**: a statement about past recorded behavior, not a
|
||||
prediction or an authorization for the *current* proposed action.
|
||||
|
||||
## What it explicitly does NOT prove
|
||||
|
||||
- **Not action-safety.** A `trusted` agent can still propose a malicious or
|
||||
buggy transaction. Pair this with a forward-looking action-risk check
|
||||
(contract simulation, policy engine) and keep the two signals separate so
|
||||
the policy decision stays auditable.
|
||||
- **Not execution quality.** It says nothing about whether *this* call will
|
||||
succeed.
|
||||
- **Not identity proof of the live caller.** It checks a DID's reputation, not
|
||||
that the entity you're talking to controls that DID (see "Spoofed DID").
|
||||
|
||||
## Failure modes a caller must account for
|
||||
|
||||
| # | Threat | Mitigation in this adapter | Residual risk owned by caller |
|
||||
|---|---|---|---|
|
||||
| 1 | **Endpoint unreachable / timeout** | Returns `unknown` (never raises). Gate is fail-closed by default. | Choose `fail_open` deliberately; pick a sane `timeout`. |
|
||||
| 2 | **Spoofed DID** — caller claims a DID it doesn't control | Out of scope: adapter checks reputation, not control of the key. | Verify DID control (signature challenge / auth) **before** trusting the verdict. |
|
||||
| 3 | **Stale verdict** — score lags very recent bad behavior | Each call is live (no caching here). | If you cache the result, bound the TTL; don't reuse a verdict across sessions. |
|
||||
| 4 | **Endpoint MITM / response tampering** | HTTPS to a pinned host (`agent.auraopenprotocol.org`). Verdict strings are validated against a fixed allow-list; unknown values collapse to `unknown`. | Don't point `base_url` at an untrusted mirror. Consider TLS pinning if your runtime supports it. |
|
||||
| 5 | **Score gaming / Sybil** — cheap DIDs farming a `trusted` score | Inherited from AURA's on-chain cost + dispute dimension; not solvable in the adapter. | Weight `dimensions` (e.g. require non-trivial `interactions` / `dispute_history`) for high-value actions rather than trusting the aggregate alone. |
|
||||
| 6 | **Over-trust** — using the verdict as sole gate for irreversible value | `new`/`unknown` rejected by default; `dimensions` exposed. | For high-value settlement, combine with action-risk + escrow + manual review. |
|
||||
|
||||
## Data handled
|
||||
|
||||
- **Sent:** only the counterparty DID, as a query parameter to `/check`. No
|
||||
PII, no payloads, no secrets, no keys.
|
||||
- **Stored:** nothing. The adapter is stateless; it holds the DID only for the
|
||||
duration of the call.
|
||||
- **Received:** the public `/check` JSON body. Surfaced verbatim on `.raw`.
|
||||
|
||||
## Trust boundary summary
|
||||
|
||||
```
|
||||
your host --(DID only, HTTPS GET)--> AURA /check --> verdict
|
||||
| |
|
||||
| forward-looking action-risk check (separate, yours) |
|
||||
v v
|
||||
policy decision (auditable, your code)
|
||||
```
|
||||
|
||||
The adapter sits on the read-only reputation edge. Signing, fund movement,
|
||||
and the final allow/deny decision stay in your code, where they can be audited.
|
||||
@@ -1,36 +0,0 @@
|
||||
"""
|
||||
AURA trust-check adapter — opt-in, read-only counterparty reputation.
|
||||
|
||||
from aura import before_settle, AuraUntrusted
|
||||
|
||||
try:
|
||||
before_settle(counterparty_did)
|
||||
settle_payment(counterparty_did, amount)
|
||||
except AuraUntrusted as e:
|
||||
abort(str(e))
|
||||
|
||||
Zero dependencies (pure stdlib). Does not sign, hold keys, or move funds.
|
||||
See README.md for the enable section and THREAT_MODEL.md for the boundary.
|
||||
"""
|
||||
|
||||
from .adapter import (
|
||||
DEFAULT_ALLOW,
|
||||
DEFAULT_BASE_URL,
|
||||
AuraUntrusted,
|
||||
AuraVerdict,
|
||||
aura_verdict,
|
||||
before_settle,
|
||||
require_trust,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"aura_verdict",
|
||||
"before_settle",
|
||||
"require_trust",
|
||||
"AuraVerdict",
|
||||
"AuraUntrusted",
|
||||
"DEFAULT_BASE_URL",
|
||||
"DEFAULT_ALLOW",
|
||||
]
|
||||
|
||||
__version__ = "0.1.0"
|
||||
@@ -1,206 +0,0 @@
|
||||
"""
|
||||
AURA trust-check adapter — a zero-dependency, read-only reputation lookup.
|
||||
|
||||
Drop this module into any agent/host project to gate a sensitive action
|
||||
(settlement, delegation, tool execution) behind a backward-looking trust
|
||||
verdict for the *counterparty* agent. It does NOT sign, hold keys, move
|
||||
funds, or touch your wallet. It makes one HTTP GET and returns a verdict.
|
||||
|
||||
Design boundary (intentional):
|
||||
- read-only: the only network call is GET /check?did=...
|
||||
- no auth: /check is a public endpoint; no API key, no secret
|
||||
- no coupling: pure stdlib (urllib). No third-party imports, no SDK.
|
||||
- fail-closed: on network failure the verdict is `unknown`, and the
|
||||
default gate (before_settle) rejects `unknown` — so an
|
||||
unreachable AURA never silently waves a counterparty
|
||||
through. Flip `fail_open=True` to invert that.
|
||||
|
||||
Public API:
|
||||
aura_verdict(did) -> AuraVerdict (never raises on network)
|
||||
before_settle(did, allow=...) -> AuraVerdict (raises AuraUntrusted)
|
||||
require_trust = before_settle (alias)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Callable, Optional
|
||||
|
||||
__all__ = [
|
||||
"aura_verdict",
|
||||
"before_settle",
|
||||
"require_trust",
|
||||
"AuraVerdict",
|
||||
"AuraUntrusted",
|
||||
"DEFAULT_BASE_URL",
|
||||
"DEFAULT_ALLOW",
|
||||
]
|
||||
|
||||
DEFAULT_BASE_URL = "https://agent.auraopenprotocol.org"
|
||||
DEFAULT_TIMEOUT = 8 # seconds
|
||||
|
||||
# Verdicts safe to proceed with by default. Rejects `high_risk` (poor track
|
||||
# record) and `unknown` (no verifiable history / endpoint unreachable).
|
||||
DEFAULT_ALLOW = ("trusted", "caution", "new")
|
||||
|
||||
# All verdict classes the /check endpoint can return.
|
||||
VERDICTS = ("trusted", "caution", "high_risk", "new", "unknown")
|
||||
|
||||
|
||||
class AuraUntrusted(Exception):
|
||||
"""Raised by before_settle() when a counterparty fails the trust gate."""
|
||||
|
||||
def __init__(self, verdict: "AuraVerdict") -> None:
|
||||
self.verdict = verdict
|
||||
super().__init__(
|
||||
f"trust gate rejected {verdict.did}: {verdict.verdict} — {verdict.reason}"
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class AuraVerdict:
|
||||
"""
|
||||
Result of a zero-auth trust check on a counterparty DID.
|
||||
|
||||
Fields:
|
||||
did the DID that was checked
|
||||
verdict one of trusted | caution | high_risk | new | unknown
|
||||
reason human-readable explanation
|
||||
score composite 0..1, or None when there is no history
|
||||
has_history True once the agent has on-chain interactions
|
||||
dimensions per-dimension breakdown (which axis is weak), or None
|
||||
raw the untouched JSON body, for callers that want more
|
||||
"""
|
||||
|
||||
did: str
|
||||
verdict: str
|
||||
reason: str = ""
|
||||
score: Optional[float] = None
|
||||
has_history: bool = False
|
||||
dimensions: Optional[dict[str, float]] = None
|
||||
# False only when AURA could not be reached (network/parse failure) and the
|
||||
# verdict is a synthetic `unknown`. A reachable AURA that genuinely returns
|
||||
# `unknown` has reachable=True. before_settle's fail_open keys on this, not
|
||||
# on the verdict alone, so it can't wave through unverified counterparties.
|
||||
reachable: bool = True
|
||||
raw: dict[str, Any] = field(default_factory=dict, repr=False)
|
||||
|
||||
@property
|
||||
def ok(self) -> bool:
|
||||
"""True for verdicts safe to proceed with (trusted / caution)."""
|
||||
return self.verdict in ("trusted", "caution")
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
"""The minimal {verdict, reason, score} contract, plus did/ok."""
|
||||
return {
|
||||
"did": self.did,
|
||||
"verdict": self.verdict,
|
||||
"reason": self.reason,
|
||||
"score": self.score,
|
||||
"ok": self.ok,
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_payload(cls, did: str, body: dict[str, Any]) -> "AuraVerdict":
|
||||
verdict = str(body.get("verdict", "unknown"))
|
||||
if verdict not in VERDICTS:
|
||||
verdict = "unknown"
|
||||
return cls(
|
||||
did=body.get("did", did),
|
||||
verdict=verdict,
|
||||
reason=str(body.get("reason", "")),
|
||||
score=body.get("score"),
|
||||
has_history=bool(body.get("has_history", False)),
|
||||
dimensions=body.get("dimensions"),
|
||||
raw=body,
|
||||
)
|
||||
|
||||
@classmethod
|
||||
def unreachable(cls, did: str, reason: str) -> "AuraVerdict":
|
||||
"""A synthetic `unknown` verdict for network/parse failures."""
|
||||
return cls(did=did, verdict="unknown", reason=reason, reachable=False)
|
||||
|
||||
|
||||
# Indirection point so tests can inject canned responses without a network.
|
||||
# Signature: (url: str, timeout: float) -> dict (raises on transport error)
|
||||
def _http_get_json(url: str, timeout: float) -> dict[str, Any]:
|
||||
req = urllib.request.Request(url, headers={"User-Agent": "aura-adapter/1.0"})
|
||||
with urllib.request.urlopen(req, timeout=timeout) as resp: # noqa: S310 (https only)
|
||||
return json.loads(resp.read().decode("utf-8"))
|
||||
|
||||
|
||||
def aura_verdict(
|
||||
did: str,
|
||||
*,
|
||||
base_url: str = DEFAULT_BASE_URL,
|
||||
timeout: float = DEFAULT_TIMEOUT,
|
||||
_fetch: Callable[[str, float], dict[str, Any]] = _http_get_json,
|
||||
) -> AuraVerdict:
|
||||
"""
|
||||
Look up the trust verdict for a counterparty DID. Never raises on a
|
||||
network/parse failure — returns an `unknown` verdict instead, leaving the
|
||||
proceed/abort decision to the caller's policy (see before_settle).
|
||||
|
||||
v = aura_verdict("did:aura:z6Mk...")
|
||||
print(v.verdict, v.reason, v.score)
|
||||
|
||||
`_fetch` is an injection seam for tests; production callers ignore it.
|
||||
"""
|
||||
if not did or not str(did).startswith("did:"):
|
||||
raise ValueError(f"invalid DID: {did!r} (must start with 'did:')")
|
||||
|
||||
url = f"{base_url.rstrip('/')}/check?" + urllib.parse.urlencode({"did": did})
|
||||
try:
|
||||
body = _fetch(url, timeout)
|
||||
except (urllib.error.URLError, TimeoutError, OSError) as e:
|
||||
return AuraVerdict.unreachable(did, f"AURA unreachable: {e}")
|
||||
except (json.JSONDecodeError, ValueError) as e:
|
||||
return AuraVerdict.unreachable(did, f"AURA returned non-JSON: {e}")
|
||||
|
||||
if not isinstance(body, dict):
|
||||
return AuraVerdict.unreachable(did, "AURA returned an unexpected shape")
|
||||
return AuraVerdict.from_payload(did, body)
|
||||
|
||||
|
||||
def before_settle(
|
||||
did: str,
|
||||
*,
|
||||
allow: tuple[str, ...] = DEFAULT_ALLOW,
|
||||
fail_open: bool = False,
|
||||
base_url: str = DEFAULT_BASE_URL,
|
||||
timeout: float = DEFAULT_TIMEOUT,
|
||||
_fetch: Callable[[str, float], dict[str, Any]] = _http_get_json,
|
||||
) -> AuraVerdict:
|
||||
"""
|
||||
Gate a sensitive action behind a trust check. Returns the verdict on pass,
|
||||
raises AuraUntrusted on fail.
|
||||
|
||||
try:
|
||||
before_settle(counterparty_did) # rejects high_risk + unknown
|
||||
settle_payment(counterparty_did, amount)
|
||||
except AuraUntrusted as e:
|
||||
abort(str(e))
|
||||
|
||||
Tighten to reject brand-new agents too:
|
||||
before_settle(did, allow=("trusted", "caution"))
|
||||
|
||||
fail_open=True makes an *unreachable* AURA pass through (transport failure
|
||||
only — a reachable AURA that returns `unknown` is still rejected). Off by
|
||||
default — absence of evidence is not evidence of trust.
|
||||
"""
|
||||
v = aura_verdict(did, base_url=base_url, timeout=timeout, _fetch=_fetch)
|
||||
|
||||
if v.verdict in allow:
|
||||
return v
|
||||
# fail_open only excuses a transport failure, never a reachable `unknown`.
|
||||
if fail_open and not v.reachable:
|
||||
return v
|
||||
raise AuraUntrusted(v)
|
||||
|
||||
|
||||
# Alias — same gate, name that reads better at non-payment call sites.
|
||||
require_trust = before_settle
|
||||
@@ -1,94 +0,0 @@
|
||||
"""
|
||||
Canned /check responses — one per verdict class.
|
||||
|
||||
These are recorded shapes of real GET /check?did=... responses, used so the
|
||||
test suite runs offline with no network. Pass `make_fetch(...)` as the
|
||||
`_fetch` argument to aura_verdict / before_settle to replay them.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Callable
|
||||
|
||||
# did -> recorded /check JSON body
|
||||
RECORDED: dict[str, dict[str, Any]] = {
|
||||
"did:aura:trusted-bot": {
|
||||
"did": "did:aura:trusted-bot",
|
||||
"verdict": "trusted",
|
||||
"reason": "strong on-chain track record (composite 0.86)",
|
||||
"has_history": True,
|
||||
"score": 0.86,
|
||||
"interactions": 142,
|
||||
"dimensions": {
|
||||
"task_completion": 0.92,
|
||||
"delivery_speed": 0.81,
|
||||
"output_quality": 0.88,
|
||||
"honesty": 0.90,
|
||||
"financial_integrity": 0.95,
|
||||
"security_compliance": 0.79,
|
||||
"collaboration": 0.84,
|
||||
"dispute_history": 0.83,
|
||||
},
|
||||
},
|
||||
"did:aura:caution-bot": {
|
||||
"did": "did:aura:caution-bot",
|
||||
"verdict": "caution",
|
||||
"reason": "mixed history (composite 0.55)",
|
||||
"has_history": True,
|
||||
"score": 0.55,
|
||||
"interactions": 31,
|
||||
"dimensions": {"financial_integrity": 0.41, "task_completion": 0.62},
|
||||
},
|
||||
"did:aura:risky-bot": {
|
||||
"did": "did:aura:risky-bot",
|
||||
"verdict": "high_risk",
|
||||
"reason": "poor track record (composite 0.22)",
|
||||
"has_history": True,
|
||||
"score": 0.22,
|
||||
"interactions": 18,
|
||||
"dimensions": {"financial_integrity": 0.12, "dispute_history": 0.20},
|
||||
},
|
||||
"did:aura:fresh-bot": {
|
||||
"did": "did:aura:fresh-bot",
|
||||
"verdict": "new",
|
||||
"reason": "registered identity, no interactions yet",
|
||||
"has_history": False,
|
||||
"score": None,
|
||||
"interactions": 0,
|
||||
},
|
||||
"did:aura:ghost-bot": {
|
||||
"did": "did:aura:ghost-bot",
|
||||
"verdict": "unknown",
|
||||
"reason": "no track record — unverified counterparty",
|
||||
"has_history": False,
|
||||
"score": None,
|
||||
"interactions": 0,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def make_fetch(
|
||||
table: dict[str, dict[str, Any]] | None = None,
|
||||
) -> Callable[[str, float], dict[str, Any]]:
|
||||
"""
|
||||
Build a `_fetch` stand-in that replays RECORDED bodies by DID parsed from
|
||||
the query string. Unknown DIDs replay the `unknown` body.
|
||||
"""
|
||||
table = RECORDED if table is None else table
|
||||
|
||||
def _fetch(url: str, timeout: float) -> dict[str, Any]:
|
||||
from urllib.parse import parse_qs, urlparse
|
||||
|
||||
did = parse_qs(urlparse(url).query).get("did", [""])[0]
|
||||
return table.get(did, RECORDED["did:aura:ghost-bot"])
|
||||
|
||||
return _fetch
|
||||
|
||||
|
||||
def raising_fetch(exc: Exception) -> Callable[[str, float], dict[str, Any]]:
|
||||
"""Build a `_fetch` that always raises — simulates an unreachable AURA."""
|
||||
|
||||
def _fetch(url: str, timeout: float) -> dict[str, Any]:
|
||||
raise exc
|
||||
|
||||
return _fetch
|
||||
@@ -1,133 +0,0 @@
|
||||
"""
|
||||
Offline tests for the AURA trust-check adapter.
|
||||
|
||||
Runs with plain `pytest` (or `python -m pytest`). No network: every call
|
||||
replays a recorded /check body via the `_fetch` injection seam.
|
||||
|
||||
Coverage:
|
||||
- one assertion per verdict class (trusted / caution / high_risk / new / unknown)
|
||||
- the before_settle gate: allow-list pass/reject, custom allow, fail_open
|
||||
- the network-failure path (fail-closed by default, pass with fail_open)
|
||||
- input validation
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import urllib.error
|
||||
|
||||
import pytest
|
||||
|
||||
from aura.adapter import AuraUntrusted, aura_verdict, before_settle
|
||||
from aura.tests.fixtures import make_fetch, raising_fetch
|
||||
|
||||
FETCH = make_fetch()
|
||||
|
||||
|
||||
# ── verdict classes ─────────────────────────────────────────────────────────
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"did,expected,ok",
|
||||
[
|
||||
("did:aura:trusted-bot", "trusted", True),
|
||||
("did:aura:caution-bot", "caution", True),
|
||||
("did:aura:risky-bot", "high_risk", False),
|
||||
("did:aura:fresh-bot", "new", False),
|
||||
("did:aura:ghost-bot", "unknown", False),
|
||||
],
|
||||
)
|
||||
def test_verdict_classes(did, expected, ok):
|
||||
v = aura_verdict(did, _fetch=FETCH)
|
||||
assert v.verdict == expected
|
||||
assert v.ok is ok
|
||||
assert v.did == did
|
||||
assert isinstance(v.reason, str) and v.reason
|
||||
|
||||
|
||||
def test_minimal_dict_contract():
|
||||
v = aura_verdict("did:aura:trusted-bot", _fetch=FETCH)
|
||||
d = v.as_dict()
|
||||
assert set(d) >= {"verdict", "reason", "score"}
|
||||
assert d["verdict"] == "trusted"
|
||||
assert d["score"] == 0.86
|
||||
|
||||
|
||||
def test_dimensions_exposed_for_history():
|
||||
v = aura_verdict("did:aura:risky-bot", _fetch=FETCH)
|
||||
assert v.has_history is True
|
||||
assert v.dimensions["financial_integrity"] == 0.12
|
||||
|
||||
|
||||
def test_new_agent_has_no_score():
|
||||
v = aura_verdict("did:aura:fresh-bot", _fetch=FETCH)
|
||||
assert v.score is None
|
||||
assert v.has_history is False
|
||||
|
||||
|
||||
# ── the before_settle gate ───────────────────────────────────────────────────
|
||||
|
||||
def test_gate_allows_trusted():
|
||||
v = before_settle("did:aura:trusted-bot", _fetch=FETCH)
|
||||
assert v.verdict == "trusted"
|
||||
|
||||
|
||||
def test_gate_allows_caution_and_new_by_default():
|
||||
assert before_settle("did:aura:caution-bot", _fetch=FETCH).verdict == "caution"
|
||||
assert before_settle("did:aura:fresh-bot", _fetch=FETCH).verdict == "new"
|
||||
|
||||
|
||||
def test_gate_rejects_high_risk():
|
||||
with pytest.raises(AuraUntrusted) as ei:
|
||||
before_settle("did:aura:risky-bot", _fetch=FETCH)
|
||||
assert ei.value.verdict.verdict == "high_risk"
|
||||
|
||||
|
||||
def test_gate_rejects_unknown_by_default():
|
||||
with pytest.raises(AuraUntrusted):
|
||||
before_settle("did:aura:ghost-bot", _fetch=FETCH)
|
||||
|
||||
|
||||
def test_strict_allow_rejects_new():
|
||||
with pytest.raises(AuraUntrusted):
|
||||
before_settle("did:aura:fresh-bot", allow=("trusted", "caution"), _fetch=FETCH)
|
||||
|
||||
|
||||
# ── network-failure path ──────────────────────────────────────────────────────
|
||||
|
||||
def test_unreachable_returns_unknown_not_raise():
|
||||
fetch = raising_fetch(urllib.error.URLError("connection refused"))
|
||||
v = aura_verdict("did:aura:trusted-bot", _fetch=fetch)
|
||||
assert v.verdict == "unknown"
|
||||
assert "unreachable" in v.reason.lower()
|
||||
|
||||
|
||||
def test_gate_fail_closed_on_unreachable():
|
||||
fetch = raising_fetch(urllib.error.URLError("connection refused"))
|
||||
with pytest.raises(AuraUntrusted):
|
||||
before_settle("did:aura:trusted-bot", _fetch=fetch)
|
||||
|
||||
|
||||
def test_gate_fail_open_passes_on_unreachable():
|
||||
fetch = raising_fetch(urllib.error.URLError("connection refused"))
|
||||
v = before_settle("did:aura:trusted-bot", fail_open=True, _fetch=fetch)
|
||||
assert v.verdict == "unknown"
|
||||
assert v.reachable is False
|
||||
|
||||
|
||||
def test_fail_open_does_not_pass_reachable_unknown():
|
||||
# A reachable AURA that returns `unknown` (ghost DID) is still rejected even
|
||||
# with fail_open — fail_open only excuses transport failures.
|
||||
with pytest.raises(AuraUntrusted):
|
||||
before_settle("did:aura:ghost-bot", fail_open=True, _fetch=FETCH)
|
||||
|
||||
|
||||
def test_reachable_verdict_marked_reachable():
|
||||
v = aura_verdict("did:aura:ghost-bot", _fetch=FETCH)
|
||||
assert v.reachable is True
|
||||
|
||||
|
||||
# ── input validation ──────────────────────────────────────────────────────────
|
||||
|
||||
@pytest.mark.parametrize("bad", ["", "not-a-did", "z6Mk-no-prefix", None])
|
||||
def test_rejects_bad_did(bad):
|
||||
with pytest.raises(ValueError):
|
||||
aura_verdict(bad, _fetch=FETCH)
|
||||
446
skills/frontend-a11y/SKILL.md
Normal file
446
skills/frontend-a11y/SKILL.md
Normal file
@@ -0,0 +1,446 @@
|
||||
---
|
||||
name: frontend-a11y
|
||||
description: >
|
||||
Accessibility patterns for React and Next.js — semantic HTML, ARIA attributes,
|
||||
form labeling, keyboard navigation, focus management, and screen reader support.
|
||||
Use when building any interactive UI component or form.
|
||||
origin: community
|
||||
---
|
||||
|
||||
# Frontend Accessibility Patterns
|
||||
|
||||
Practical accessibility patterns for React and Next.js. Covers the issues most commonly flagged in code review: missing form labels, incorrect ARIA usage, non-semantic interactive elements, and broken keyboard navigation.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- Building or reviewing form components (`<input>`, `<select>`, `<textarea>`)
|
||||
- Creating interactive elements (modals, dropdowns, tooltips, tabs)
|
||||
- Using `<div>` or `<span>` with `onClick`
|
||||
- Adding `aria-*` attributes to any element
|
||||
- Implementing keyboard navigation or focus management
|
||||
- Receiving accessibility feedback from code review tools (CodeRabbit, ESLint a11y)
|
||||
- Building components that must support screen readers
|
||||
|
||||
## Form Accessibility
|
||||
|
||||
Missing `htmlFor` / `id` pairing and disconnected error messages are the most common issues flagged in code review.
|
||||
|
||||
### Label Connection
|
||||
|
||||
```tsx
|
||||
// BAD: label has no connection to input — screen readers cannot associate them
|
||||
<label>Email</label>
|
||||
<input type="email" />
|
||||
|
||||
// GOOD: htmlFor matches input id
|
||||
<label htmlFor="email">Email</label>
|
||||
<input id="email" type="email" />
|
||||
```
|
||||
|
||||
### Required Fields
|
||||
|
||||
```tsx
|
||||
// BAD: visual-only asterisk conveys nothing to screen readers
|
||||
<label htmlFor="email">Email *</label>
|
||||
<input id="email" type="email" />
|
||||
|
||||
// GOOD: required enables native browser validation; aria-required signals it to screen readers
|
||||
<label htmlFor="email">
|
||||
Email <span aria-hidden="true">*</span>
|
||||
</label>
|
||||
<input id="email" type="email" required aria-required="true" />
|
||||
```
|
||||
|
||||
### Error Messages
|
||||
|
||||
```tsx
|
||||
// BAD: error text exists visually but is not linked to the input
|
||||
<input id="email" type="email" />
|
||||
<span className="error">Invalid email address</span>
|
||||
|
||||
// GOOD: aria-describedby connects input to its error message
|
||||
// aria-invalid signals the invalid state to screen readers
|
||||
<input
|
||||
id="email"
|
||||
type="email"
|
||||
aria-describedby="email-error"
|
||||
aria-invalid={!!error}
|
||||
/>
|
||||
{error && (
|
||||
<span id="email-error" role="alert">
|
||||
{error}
|
||||
</span>
|
||||
)}
|
||||
```
|
||||
|
||||
### Complete Accessible Form
|
||||
|
||||
```tsx
|
||||
interface LoginFormProps {
|
||||
onSubmit: (email: string, password: string) => void;
|
||||
}
|
||||
|
||||
export function LoginForm({ onSubmit }: LoginFormProps) {
|
||||
const [email, setEmail] = useState('');
|
||||
const [password, setPassword] = useState('');
|
||||
const [errors, setErrors] = useState<{ email?: string; password?: string }>({});
|
||||
|
||||
const handleSubmit = (e: React.FormEvent) => {
|
||||
e.preventDefault();
|
||||
const newErrors: typeof errors = {};
|
||||
if (!email) newErrors.email = 'Email is required';
|
||||
if (!password) newErrors.password = 'Password is required';
|
||||
if (Object.keys(newErrors).length) {
|
||||
setErrors(newErrors);
|
||||
return;
|
||||
}
|
||||
onSubmit(email, password);
|
||||
};
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit} noValidate>
|
||||
<div>
|
||||
<label htmlFor="email">
|
||||
Email <span aria-hidden="true">*</span>
|
||||
</label>
|
||||
<input
|
||||
id="email"
|
||||
type="email"
|
||||
value={email}
|
||||
onChange={e => setEmail(e.target.value)}
|
||||
aria-required="true"
|
||||
aria-describedby={errors.email ? 'email-error' : undefined}
|
||||
aria-invalid={!!errors.email}
|
||||
autoComplete="email"
|
||||
/>
|
||||
{errors.email && (
|
||||
<span id="email-error" role="alert">
|
||||
{errors.email}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<label htmlFor="password">
|
||||
Password <span aria-hidden="true">*</span>
|
||||
</label>
|
||||
<input
|
||||
id="password"
|
||||
type="password"
|
||||
value={password}
|
||||
onChange={e => setPassword(e.target.value)}
|
||||
aria-required="true"
|
||||
aria-describedby={errors.password ? 'password-error' : undefined}
|
||||
aria-invalid={!!errors.password}
|
||||
autoComplete="current-password"
|
||||
/>
|
||||
{errors.password && (
|
||||
<span id="password-error" role="alert">
|
||||
{errors.password}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
|
||||
<button type="submit">Log in</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Semantic HTML
|
||||
|
||||
Use the element that matches the intent. Screen readers and keyboard users depend on native semantics.
|
||||
|
||||
```tsx
|
||||
// BAD: div has no role, no keyboard support, no accessible name
|
||||
<div onClick={handleClick}>Submit</div>
|
||||
|
||||
// GOOD: button is focusable, activates on Enter/Space, announces as "button"
|
||||
<button type="button" onClick={handleClick}>Submit</button>
|
||||
```
|
||||
|
||||
```tsx
|
||||
// BAD: non-semantic navigation
|
||||
<div onClick={() => navigate('/home')}>Home</div>
|
||||
|
||||
// GOOD: anchor supports right-click, middle-click, and keyboard navigation
|
||||
<a href="/home">Home</a>
|
||||
```
|
||||
|
||||
```tsx
|
||||
// BAD: heading hierarchy skipped (h1 to h4)
|
||||
<h1>Dashboard</h1>
|
||||
<h4>Recent Activity</h4>
|
||||
|
||||
// GOOD: sequential heading levels
|
||||
<h1>Dashboard</h1>
|
||||
<h2>Recent Activity</h2>
|
||||
```
|
||||
|
||||
## ARIA Attributes
|
||||
|
||||
Use ARIA only when native HTML semantics are insufficient. Wrong ARIA is worse than no ARIA.
|
||||
|
||||
### aria-label vs aria-labelledby
|
||||
|
||||
```tsx
|
||||
// aria-label: inline string label — use when no visible label text exists
|
||||
<button aria-label="Close modal">
|
||||
<XIcon />
|
||||
</button>
|
||||
|
||||
// aria-labelledby: references another element's text — use when a visible label exists
|
||||
<section aria-labelledby="section-title">
|
||||
<h2 id="section-title">Recent Orders</h2>
|
||||
{/* content */}
|
||||
</section>
|
||||
```
|
||||
|
||||
### aria-describedby
|
||||
|
||||
```tsx
|
||||
// Provides supplementary description beyond the label
|
||||
<button
|
||||
aria-describedby="delete-warning"
|
||||
onClick={handleDelete}
|
||||
>
|
||||
Delete account
|
||||
</button>
|
||||
<p id="delete-warning">This action cannot be undone.</p>
|
||||
```
|
||||
|
||||
### aria-live for Dynamic Content
|
||||
|
||||
```tsx
|
||||
// Use aria-live to announce content that updates without a page reload
|
||||
// polite: waits for user to finish current action before announcing
|
||||
// assertive: interrupts immediately — use only for urgent errors
|
||||
|
||||
export function StatusMessage({ message, isError }: { message: string; isError?: boolean }) {
|
||||
return (
|
||||
<div role="status" aria-live={isError ? 'assertive' : 'polite'} aria-atomic="true">
|
||||
{message}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### aria-expanded and aria-controls
|
||||
|
||||
```tsx
|
||||
export function Accordion({ title, children }: { title: string; children: React.ReactNode }) {
|
||||
const [isOpen, setIsOpen] = useState(false);
|
||||
const contentId = useId();
|
||||
|
||||
return (
|
||||
<div>
|
||||
<button aria-expanded={isOpen} aria-controls={contentId} onClick={() => setIsOpen(prev => !prev)}>
|
||||
{title}
|
||||
</button>
|
||||
<div id={contentId} hidden={!isOpen}>
|
||||
{children}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Keyboard Navigation
|
||||
|
||||
Every interactive element must be reachable and operable by keyboard alone.
|
||||
|
||||
### Custom Dropdown
|
||||
|
||||
```tsx
|
||||
export function Dropdown({ options, onSelect }: { options: string[]; onSelect: (value: string) => void }) {
|
||||
const [isOpen, setIsOpen] = useState(false);
|
||||
const [activeIndex, setActiveIndex] = useState(0);
|
||||
const listId = useId();
|
||||
|
||||
if (!options.length) return null;
|
||||
|
||||
const handleKeyDown = (e: React.KeyboardEvent) => {
|
||||
switch (e.key) {
|
||||
case 'ArrowDown':
|
||||
e.preventDefault();
|
||||
setActiveIndex(i => Math.min(i + 1, options.length - 1));
|
||||
break;
|
||||
case 'ArrowUp':
|
||||
e.preventDefault();
|
||||
setActiveIndex(i => Math.max(i - 1, 0));
|
||||
break;
|
||||
case 'Enter':
|
||||
case ' ':
|
||||
e.preventDefault();
|
||||
if (isOpen) onSelect(options[activeIndex]);
|
||||
setIsOpen(prev => !prev);
|
||||
break;
|
||||
case 'Escape':
|
||||
setIsOpen(false);
|
||||
break;
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<div
|
||||
role="combobox"
|
||||
aria-expanded={isOpen}
|
||||
aria-haspopup="listbox"
|
||||
aria-controls={listId}
|
||||
tabIndex={0}
|
||||
onKeyDown={handleKeyDown}
|
||||
onClick={() => setIsOpen(prev => !prev)}
|
||||
>
|
||||
<span>{options[activeIndex]}</span>
|
||||
{isOpen && (
|
||||
<ul id={listId} role="listbox">
|
||||
{options.map((option, index) => (
|
||||
<li
|
||||
key={option}
|
||||
role="option"
|
||||
aria-selected={index === activeIndex}
|
||||
onClick={() => {
|
||||
onSelect(option);
|
||||
setIsOpen(false);
|
||||
}}
|
||||
>
|
||||
{option}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Focus Management
|
||||
|
||||
Focus must move logically when UI state changes — especially for modals and route transitions.
|
||||
|
||||
### Modal Focus Restoration
|
||||
|
||||
> This example covers initial focus and restoration. For a full focus trap (Tab/Shift+Tab cycling within the modal), use a library like [`focus-trap-react`](https://github.com/focus-trap/focus-trap-react) which handles edge cases like dynamic content and nested portals.
|
||||
|
||||
```tsx
|
||||
export function Modal({ isOpen, onClose, title, children }: { isOpen: boolean; onClose: () => void; title: string; children: React.ReactNode }) {
|
||||
const modalRef = useRef<HTMLDivElement>(null);
|
||||
const previousFocusRef = useRef<HTMLElement | null>(null);
|
||||
|
||||
useEffect(() => {
|
||||
if (isOpen) {
|
||||
// Save currently focused element and move focus into modal
|
||||
previousFocusRef.current = document.activeElement as HTMLElement;
|
||||
modalRef.current?.focus();
|
||||
} else {
|
||||
// Restore focus to the element that opened the modal
|
||||
previousFocusRef.current?.focus();
|
||||
}
|
||||
}, [isOpen]);
|
||||
|
||||
if (!isOpen) return null;
|
||||
|
||||
return (
|
||||
<div ref={modalRef} role="dialog" aria-modal="true" aria-labelledby="modal-title" tabIndex={-1} onKeyDown={e => e.key === 'Escape' && onClose()}>
|
||||
<h2 id="modal-title">{title}</h2>
|
||||
{children}
|
||||
<button onClick={onClose}>Close</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Images and Icons
|
||||
|
||||
```tsx
|
||||
// BAD: decorative icon announced as unlabeled image
|
||||
<img src="/icon.svg" />
|
||||
|
||||
// GOOD: decorative image hidden from screen readers
|
||||
<img src="/decoration.png" alt="" aria-hidden="true" />
|
||||
|
||||
// GOOD: meaningful image with descriptive alt text
|
||||
<img src="/chart.png" alt="Monthly revenue increased 23% from January to March" />
|
||||
|
||||
// GOOD: icon button with accessible label
|
||||
<button aria-label="Delete item">
|
||||
<TrashIcon aria-hidden="true" />
|
||||
</button>
|
||||
```
|
||||
|
||||
## Reduced Motion
|
||||
|
||||
Respect users who have requested reduced motion in their OS settings.
|
||||
|
||||
```tsx
|
||||
export function useReducedMotion(): boolean {
|
||||
const [prefersReduced, setPrefersReduced] = useState(false);
|
||||
|
||||
useEffect(() => {
|
||||
const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
|
||||
setPrefersReduced(mq.matches);
|
||||
const handler = (e: MediaQueryListEvent) => setPrefersReduced(e.matches);
|
||||
mq.addEventListener('change', handler);
|
||||
return () => mq.removeEventListener('change', handler);
|
||||
}, []);
|
||||
|
||||
return prefersReduced;
|
||||
}
|
||||
|
||||
// Usage
|
||||
export function AnimatedCard({ children }: { children: React.ReactNode }) {
|
||||
const reduceMotion = useReducedMotion();
|
||||
|
||||
return (
|
||||
<div
|
||||
style={{
|
||||
transition: reduceMotion ? 'none' : 'transform 300ms ease'
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
```tsx
|
||||
// BAD: onClick on non-interactive element with no keyboard support
|
||||
<div onClick={handleClick}>Click me</div>
|
||||
|
||||
// BAD: aria-label on a div that has no role
|
||||
<div aria-label="Navigation">...</div>
|
||||
|
||||
// BAD: placeholder used as a substitute for label
|
||||
<input placeholder="Enter your email" />
|
||||
|
||||
// BAD: positive tabIndex creates unpredictable tab order
|
||||
<button tabIndex={3}>Submit</button>
|
||||
|
||||
// BAD: aria-hidden on a focusable element — keyboard users get trapped
|
||||
<button aria-hidden="true">Open</button>
|
||||
|
||||
// BAD: role="button" on div without keyboard handler
|
||||
<div role="button" onClick={handleClick}>Submit</div>
|
||||
// Missing: tabIndex={0}, onKeyDown for Enter/Space
|
||||
```
|
||||
|
||||
## Checklist
|
||||
|
||||
Before submitting any interactive component for review:
|
||||
|
||||
- [ ] Every `<input>`, `<select>`, and `<textarea>` has a connected `<label>` via `htmlFor`/`id`
|
||||
- [ ] Error messages are linked with `aria-describedby` and marked `role="alert"`
|
||||
- [ ] No `onClick` on `<div>` or `<span>` without `role`, `tabIndex`, and `onKeyDown`
|
||||
- [ ] Icon-only buttons have `aria-label`
|
||||
- [ ] Decorative images use `alt=""` and `aria-hidden="true"`
|
||||
- [ ] Modals restore focus on close (for full focus trapping with Tab/Shift+Tab cycling, use a library like `focus-trap-react`)
|
||||
- [ ] Dynamic content updates use `aria-live`
|
||||
- [ ] `prefers-reduced-motion` is respected for animations
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `frontend-patterns` — general React component and state patterns
|
||||
- `design-system` — design token and component consistency
|
||||
- `motion-ui` — animation patterns with accessibility considerations
|
||||
Reference in New Issue
Block a user