From fa20562cacd90dddbe84b0ea032b37a4036e08ed Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 18 Oct 2026 22:59:12 +0200 Subject: [PATCH 01/24] docs(ship-feature): spec and plan for the a11y split, injection and exposure domains --- .../plans/2026-10-18-guardrails-a11y-split.md | 2030 +++++++++++++++++ ...2026-10-18-guardrails-a11y-split-design.md | 210 ++ 2 files changed, 2240 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md create mode 100644 docs/superpowers/specs/2026-10-18-guardrails-a11y-split-design.md diff --git a/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md b/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md new file mode 100644 index 0000000..83b8c26 --- /dev/null +++ b/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md @@ -0,0 +1,2030 @@ +# Guardrails a11y split, injection and exposure domains — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Move accessibility out of `/guardrails` into a standalone `/a11y` skill sharing the scan engine, add the `injection` and `exposure` scanner domains, extend the read-only probe with an `exposure` block, and patch every citer. + +**Architecture:** `scan.py` is split into a parametrized engine (`scanner.py`, a `Catalogue` of domains, prefixes and marker) and two thin catalogue CLIs (guardrails, a11y). Two new check modules follow the `apis.py` pattern (regex constants, `applies`, `check`, private `_x(project)` lists, `project.found`). The probe gains one `probe_exposure` entry in `PROBES` plus two shared fixes to `fetch`. Doctrine, routing rows, profiles, locks and docs are patched in the same branch. + +**Tech Stack:** Python 3 stdlib (`python3 -B`), bash test suites run through `make test suite=`, shellcheck, gitflow lib. + +**Spec:** `docs/superpowers/specs/2026-10-18-guardrails-a11y-split-design.md` + +**Contract:** `.claude/tasks/contracts/2026-10-18-guardrails-a11y-split-inj-exp-2210.md` + +## Global Constraints + +- Scanner: read-only, stdlib only, never executes project code, severities FAIL / WARN / MANUAL only, exit 0 / 1 / 2. A clean scan means "no static finding". +- Probe: GET, HEAD, OPTIONS only plus the existing opt-in POST burst; `--authorized` required; same-host redirects only; shared budget 200; secrets from env only; never print a response value, only key names. +- Code style: max 25 logic lines per function, 80 columns, 5 params, 5 locals. One check module per domain exposing `DOMAIN`, `applies(project)`, `check(project)`. +- Tests: every rule has a mutant at its default severity; every known false-positive class has a `benign` lock; the clean fixtures report ` 0 FAIL, 0 WARN`. Portable shell: no `sed -i`, no `grep -P`, no `stat -c`. +- Git: work on `feature/a11y-split-inj-exp`; commit per task with `git add `; never `git add -A`; never stage `settings.json` or the pre-existing hunks of `mods/model-router/routing.json`; never push by hand (hooks push). +- Rule, heading and label citers are patched in the same task that changes them (BDR-100). +- Locked single-line strings in SKILL.md files (loops-light) must stay on one line. +- Fixture payloads are realistic, never canonical textbook examples; fixture names stay neutral. +- Run `make test suite=` for the suites a task touches; one full `make test` in Task 9. + +## Review Focus + +1. A tagged SQL template (`` sql`select * from notes where id = ${id}` ``) must stay silent: pinned by the `tagged-sql-template` benign lock in Task 2. +2. A console call in a server file (`src/pages/api/notes.ts`) must stay silent while the same call in `src/components/` warns: pinned by `console-server-file` in Task 3. +3. A `' + b'' + b'' + b'') + if path == "/app.js": + return self._send(200, b"console.log(1);\n//# sourceMappingURL=app.js.map\n") + if path == "/app.js.map": + return self._send(200, b'{"version":3,"sources":["src/app.ts"],"mappings":""}') + if path == "/clean.js": + return self._send(200, b"console.log(2);\n") + if path == "/boom": + return self._send(500, b"Traceback (most recent call last):\n" + b' File "app.py", line 12, in handler\n') + if path == "/api/me": + return self._send(200, b'{"id": 1, "email": "t@t.io", ' + b'"password_hash": "x", "profile": {"api_key": "y"}}', + {"Content-Type": "application/json"}) +``` + +And replace `do_OPTIONS` so header names are lowercase on `/lower`: + +```python + def do_OPTIONS(self): + origin = self.headers.get("Origin", "") + upper = ("Access-Control-Allow-Origin", "Access-Control-Allow-Credentials") + names = tuple(n.lower() for n in upper) if self.path == "/lower" else upper + self._send(204, b"", {names[0]: origin, names[1]: "true"}) +``` + +Then add a test block before `echo "== JSON output"` (the inner heredocs use `EOF` exactly like the existing plan files in this suite): + +```bash +echo "== exposure probes" +cat > "$WORK/exposure.json" < "$WORK/badexp.json" +probe --authorized "$WORK/badexp.json" >/dev/null 2>&1 +check "an error route not starting with / exits 2" "$?" 2 +printf '{"base_url": "%s", "exposure": []}\n' "$BASE" > "$WORK/badexp2.json" +probe --authorized "$WORK/badexp2.json" >/dev/null 2>&1 +check "a non-object exposure block exits 2" "$?" 2 +cat > "$WORK/lower.json" <&1 | grep -c ' FAIL '` +Expected: at least 9 (the sourcemap, error-body and fields rows are absent; lowercase CORS reads CLOSED; the two exit-2 checks get 1). + +- [ ] **Step 3: Patch `probe.py`** + +Imports: add `import re` and change the parse import to `from urllib.parse import quote, urljoin, urlsplit`. + +Replace `_response_from` and `fetch`: + +```python +def _headers(message): + return {k.lower(): v for k, v in message.items()} + + +def _error_body(exc): + try: + return exc.read(BODY_CAP) + except (OSError, ValueError, AttributeError): + return b"" + + +def _response_from(resp): + return Response(resp.status, _headers(resp.headers), resp.read(BODY_CAP)) + + +def fetch(session, method, url, headers=None, body=None): + if session.budget <= 0: + return Response(None, {}, b"", "request budget exhausted") + session.budget -= 1 + req = urllib.request.Request( + url, data=body, method=method, headers=headers or {}) + try: + with session.opener.open(req, timeout=session.timeout) as resp: + return _response_from(resp) + except urllib.error.HTTPError as exc: + return Response(exc.code, _headers(exc.headers), _error_body(exc)) + except (urllib.error.URLError, OSError, ValueError) as exc: + return Response(None, {}, b"", str(exc)) +``` + +In `_cors_open`: `headers.get("access-control-allow-origin", "")` and `headers.get("access-control-allow-credentials", "")`. + +Add the constants after `BODY_CAP`: + +```python +SCRIPT_CAP = 10 +SCRIPT_SRC = re.compile(rb"]+src=[\"']([^\"']+)[\"']", re.I) +MAP_COMMENT = re.compile(rb"//[#@]\s*sourceMappingURL=(\S+)") +TRACE_MARKERS = re.compile( + rb"Traceback \(most recent call last\)|\bat [\w.$<> ]+ \([^)\n]*:\d+:\d+\)" + rb"|File \"[^\"\n]+\", line \d+|SQLSTATE\[|syntax error at or near" + rb"|node_modules/|/var/www/|Stack trace:|#\d+ /[\w/.-]+\.php\(\d+\)") +SENSITIVE_KEY = re.compile( + r"password|passwd|pwd|hash|salt|secret|token|api_?key|service_?role" + r"|private|ssn|iban|cvv|card_?number", re.I) +``` + +Add the probes before `PROBES = (…)` and append `probe_exposure` to the tuple: + +```python +def _same_host(context, url): + """Absolute url when it stays on context's host, else None.""" + text = url.decode("utf-8", "ignore") if isinstance(url, bytes) else url + full = urljoin(context, text) + return full if urlsplit(full).netloc == urlsplit(context).netloc else None + + +def _script_urls(session, base, cfg): + listed = cfg.get("scripts") + if listed is None: + page = fetch(session, "GET", base + "/") + listed = [m.group(1) for m in SCRIPT_SRC.finditer(page.body)] + urls = [u for u in (_same_host(base + "/", s) for s in listed) if u] + return list(dict.fromkeys(urls))[:SCRIPT_CAP] + + +def _map_candidates(script_url, resp): + urls = [script_url + ".map"] + header = resp.headers.get("sourcemap") or resp.headers.get("x-sourcemap") + if header: + urls.append(header) + comment = MAP_COMMENT.search(resp.body[-600:]) + if comment: + urls.append(comment.group(1)) + return [u for u in (_same_host(script_url, u) for u in urls) if u] + + +def _map_served(resp): + return resp.status == 200 and b'"sources"' in resp.body + + +def _sourcemap_probe(session, script_url): + pid = f"sourcemap:{urlsplit(script_url).path}" + resp = fetch(session, "GET", script_url) + if resp.error: + return Probe("exposure", pid, "ERROR", script_url, resp.error) + served = next((u for u in dict.fromkeys(_map_candidates(script_url, resp)) + if _map_served(fetch(session, "GET", u))), None) + if served: + return Probe("exposure", pid, "OPEN", served, + "source map served with its sources") + return Probe("exposure", pid, "CLOSED", script_url, + "no source map served for this script") + + +def _error_probe(session, base, path): + target = base + path + resp = fetch(session, "GET", target) + return _verdict( + ("exposure", f"error-body:{path}", target), resp, + bool(TRACE_MARKERS.search(resp.body)), + ("error body carries a stack trace or an internal path", + "error body carries no trace marker")) + + +def _error_paths(cfg): + random_path = "/guardrails-probe-" + os.urandom(6).hex() + return [random_path] + list(cfg.get("error_routes") or []) + + +def _keys(data, depth=0): + if depth > 4: + return [] + if isinstance(data, dict): + found = [k for k in data if isinstance(k, str)] + for value in data.values(): + found += _keys(value, depth + 1) + return found + if isinstance(data, list): + found = [] + for value in data[:5]: + found += _keys(value, depth + 1) + return found + return [] + + +def _sensitive_keys(body): + try: + data = json.loads(body or b"null") + except ValueError: + return [] + return sorted({k for k in _keys(data) if SENSITIVE_KEY.search(k)}) + + +def _bearer(): + token = os.environ.get("GUARDRAILS_JWT2") + return {"Authorization": f"Bearer {token}"} if token else None + + +def _fields_probe(session, base, route): + target = base + route["path"] + resp = fetch(session, "GET", target, _bearer()) + keys = _sensitive_keys(resp.body) if resp.status == 200 else [] + return _verdict( + ("exposure", f"fields:{route['path']}", target), resp, bool(keys), + ("response carries sensitive keys: " + ", ".join(keys), + "no sensitive key in the response")) + + +def probe_exposure(session, plan): + cfg = plan.get("exposure") + if cfg is None: + return [] + base = plan["base_url"].rstrip("/") + out = [_sourcemap_probe(session, u) + for u in _script_urls(session, base, cfg)] + out += [_error_probe(session, base, p) for p in _error_paths(cfg)] + out += [_fields_probe(session, base, r) for r in plan.get("routes", [])] + return out + + +PROBES = (probe_supabase, probe_cross_user, probe_routes, + probe_cors, probe_rate_limit, probe_exposure) +``` + +Extend plan validation: + +```python +def _exposure_error(cfg): + if cfg is None: + return "" + if not isinstance(cfg, dict): + return "exposure must be an object" + for key in ("scripts", "error_routes"): + items = cfg.get(key) or [] + if not all(isinstance(i, str) for i in items): + return f"exposure.{key} must be a list of strings" + if any(not r.startswith("/") for r in cfg.get("error_routes") or []): + return "exposure.error_routes entries must start with /" + return "" + + +def _plan_error(plan): + method = plan.get("rate_limit", {}).get("method", "GET").upper() + if method not in READ_METHODS and method != "POST": + return f"rate_limit method {method} is not a probe method" + return _exposure_error(plan.get("exposure")) +``` + +Module docstring: after the `GUARDRAILS_JWT2` line add ` (also sent as bearer by the fields probe when set)`; in the first paragraph add the sentence `With an exposure block in the plan it also reads what the page's scripts, error bodies and JSON responses give away.` + +- [ ] **Step 4: Run the suite** + +Run: `make test suite=lib/tests/guardrails-probe.test.sh` +Expected: `failed: 0`, including the untouched `json reports the open count` = 4 (`plan.json` has no `exposure` block) and `the burst is capped` = 25. + +- [ ] **Step 5: Commit** + +```bash +git add skills/guardrails/scripts/probe.py lib/tests/guardrails-probe.test.sh +git commit -m "feat(guardrails): exposure probe (source maps served, error bodies, sensitive keys); fetch keeps error bodies, headers lowercased" +``` + +--- + +### Task 6: The `/a11y` skill: SKILL.md, references, prompts, lazy rule, routing row, profiles, locks + +**Files:** +- Create: `skills/a11y/SKILL.md`, `skills/a11y/references/checks.md`, `skills/a11y/test-prompts.json`, `rules/a11y.md` +- Modify: `mods/model-router/routing.json` (one row), `lib/profiles/{audit,dev,web,web-full,full,max}.profile`, `lib/tests/model-routing.test.sh`, `lib/tests/loops-light.test.sh`, `lib/verify-secure-loop.md:1`, `lib/contract-interview.md:117`, `agents/bugfixer.md:3` +- Test: `make test suite='lib/tests/effort-routing.test.sh lib/tests/profile-census.test.sh lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/tests/skill-routing-census.test.sh'` + +**Interfaces:** +- Consumes: `skills/a11y/scripts/scan.py` (Task 4), `lib/contract-interview.md` (flow `a11y`), `lib/verify-secure-loop.md`, the `bugfixer` agent. +- Produces: the public `/a11y` command, report `.claude/audits/A11Y.md`, branch `bugfix/a11y-`, baseline `.claude/audits/.a11y-baseline.json`. + +- [ ] **Step 1: Write `skills/a11y/SKILL.md`** + +The description is one single-quoted line. The seven locked sentences (`lib/contract-interview.md`, `lib/verify-secure-loop.md`, `subagent_type="bugfixer"`, `EXPECT: A11Y-CLEAR`, `Positive control`, `Nothing is applied without the user's explicit acceptance`, `A11Y-NO-NEW`) and `lib/model-gate.md` must each sit on one line, as below. + +````markdown +--- +name: a11y +effort: high +description: 'Use when a web project needs its accessibility baseline checked and fixed: everything reachable by keyboard with a visible focus, an alt on every image, a label on every field. Runs a deterministic scanner (A11Y-* rules: img alt, field label, click without keyboard, focus outline removed, positive tabindex), judges each hit, walks the main flow with Tab only on --live (through /browse, else marked not done), writes .claude/audits/A11Y.md, then proposes fixes with the alt and label wording as visible choices, applies only the ones the user accepts (bugfixer executor, fresh verifier and security gates, the scanner as oracle) and re-scans to prove each one. Triggers: "a11y", "accessibilité", "accessibility basics", "clavier", "focus visible", "alt manquant", "label sur les champs", "tab order", "corrige l''accessibilité". Full WCAG conformance (axe, pa11y, W3C) → /web-validate; security guardrails → /guardrails.' +argument-hint: '[project path] [--exclude paths] [--live ] [--report-only]' +--- + +# /a11y + +Checks a project's accessibility baseline (`rules/a11y.md`), then fixes what +the user accepts and proves each fix. A scanner reads the tree as data and +finds what text can prove: a missing alt, an unlabeled field, a click with no +keyboard path, a focus outline removed, a positive tabindex. This skill judges +the hits, walks the main flow with the keyboard when a browser is available, +proposes fixes, applies the accepted ones and scans again until every accepted +fix is proven. + +The scanner proves absence of a baseline, never presence of accessibility. A +clean scan means "no static finding", and the report says exactly that. Full +WCAG conformance (contrast, structure, ARIA semantics, axe or pa11y runs) is +`/web-validate`'s job. + +## MODEL GATE (blocking, before any other step) + +Run `$HOME/.claude/lib/model-gate.md`. Judging hits and writing alt and label +text requires Fable or Opus. Verdict `small` → STOP: the gate prints the +remedy. ROUTING: follow `$HOME/.claude/lib/effort-shift.md` (phases via +`mcp__model-router__route`); each step below names its phase. + +## STEP 1: Scope + +Work in the project the user names, else the current directory. Say in one +line what you will scan. `--report-only` stops after STEP 5: audit, no fix. + +## STEP 2: Run the scanner + +``` +python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" +``` + +Add `--exclude a/b,c` to skip copies or vendored code, `--json` for machine +output. Exit 0 means no FAIL, 1 means at least one, 2 is a usage error. It +never executes project code. Severities: **FAIL**, the baseline is provably +missing; **WARN**, a pattern that is often wrong, judgment needed. + +## STEP 3: Judge every FAIL and WARN + +Read the file around each line. Label it CONFIRMED, FALSE POSITIVE (say why) +or ACCEPTED RISK (the user decides, never you). A decorative image with +`alt=""`, a field labeled through `aria-labelledby`, a click handler on a +`role="presentation"` overlay and an outline swapped for a visible border or +ring are the usual false positives; `references/checks.md` lists the blind +spots. Check them before calling a hit false. + +## STEP 4: Keyboard walk (on `--live`, read-only) + +With a dev server the user names, walk the main flow with Tab only through +`/browse`: every control reached in a sensible order, the focus visible at +each stop, Enter and Space working on what looks clickable, Escape closing +what opened. Record each stop that fails with the page and the element. +Without a browser tool, or without `--live`, the report marks the walk +"not done": a static scan cannot see a keyboard trap, a focus order or a +modal that loses focus. + +## STEP 5: Report + +Write `.claude/audits/A11Y.md`: one table with status PASS, FAIL, WARN or +N/A per rule, the evidence, the fix in one line, and the keyboard walk's +result (done, with its stops, or not done). PASS means "no static finding". +Keep it short; no filler sections. `--report-only`, or nothing CONFIRMED: +reply with counts, the FAILs with file:line and the walk's stops, then stop. + +## STEP 6: Propose fixes + +`mcp__model-router__route(phase="plan")`: wording is the deepest thinking in +this run, it goes to the plan row. + +One proposal per CONFIRMED finding, grouped by rule and file; merge pairs +that one change closes (one `:focus-visible` rule closes every outline +removal in a stylesheet). FALSE POSITIVE and ACCEPTED RISK get no proposal. +Each proposal: + +- **number, rule, file(s)**, and the problem in one line; +- **the fix**, concrete: file:line and the change. A missing alt gets a + description of what the image shows, or `alt=""` when it is decorative; an + unlabeled field gets a `label for`, a wrapping label or `aria-label`; a + clickable `div` becomes a `button`, or gains `role`, `tabindex` and a key + handler; a removed outline gets a `:focus-visible` style; +- **choices the user sees**: the alt text and the label wording, each with + your proposed value, named so the user can change it. These are content, + never invented silently: they ship only with the user's acceptance; +- **risk**: what it can break (`button` reset styles, a changed tab order). + `DECISION` when no wording is defensible (an image you cannot describe); +- **proof**: the scanner pairs that must disappear (`RULE:path`), and the + walk stop that must pass when `--live` ran. + +Save the proposals to `.claude/tasks/plans/-a11y-.md` and +append them to the report. In the reply, show them as a numbered list, one or +two lines each, DECISION marked. + +## STEP 7: Approval (gate, ends the turn) + +Nothing is applied without the user's explicit acceptance. Ask once, then +stop the turn: + +``` +Which fixes do I apply? "all" (every proposal except DECISION ones), +numbers ("1,3,5-7"), "none", or an amendment ("2 with the alt 'Team photo'"). +A DECISION proposal needs its number plus your wording. +``` + +On resume, `mcp__model-router__route(phase="reflect")`. "none" → stop, +proposals stay in the report. An amendment rewrites that proposal in the plan +file before anything else. Accepted set empty → stop. + +## STEP 8: Apply + +1. **Branch.** Not a git repository → stop: fixes need a diff to review. + On `main`/`develop`, `bash ~/.claude/lib/gitflow.sh start bugfix + a11y-`; on a working branch, stay. Never `finish`. +2. **Baseline**, before any edit: + `python3 -B --json > .claude/audits/.a11y-baseline.json`. + A derived file: never staged, never committed. +3. **Contract** per `$HOME/.claude/lib/contract-interview.md` (STEP 4 + template, `flow: a11y`). REQUEST = the user's acceptance verbatim plus the + accepted proposals. One criterion per accepted proposal, its oracle the + scanner itself: + ``` + 1. + CHECK: python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" '' --assert-absent 'RULE:path,RULE:path' + EXPECT: A11Y-CLEAR + EVIDENCE: pending + ``` + Add one criterion for the project suite when one exists + (`CHECK: && echo TESTS-GREEN`, `EXPECT: TESTS-GREEN`). The + keyboard walk is a criterion without CHECK: STEP 9 settles it. FILE SCOPE + = the files the accepted proposals name. Paths go in single quotes; a path + holding a single quote is named to the user, never written into a CHECK. +4. **Positive control.** Run each oracle once on the unfixed tree: it must + fail. An oracle that passes before the fix proves nothing; drop it, find + why, and say so. +5. **Dispatch the executor**, one fresh `bugfixer` for the accepted set + (batches of 8 proposals at most, one after the other on the same branch): + ``` + mcp__model-router__route(phase="orchestrate") # send with the Agent call + Agent(subagent_type="bugfixer") + prompt: "CONTRACT: + DIAGNOSIS: + FIX PLAN: + BRANCH: + Apply to the letter. No commit, no branch ops, no security dispatch. + Finish with the BUGFIX-EXEC REPORT." + ``` + `NEED-DECISION` routes per MID-RUN CLARIFICATION of the contract include: + a wording, visible or scope question goes to the user verbatim. + `BLOCKED` → surface it, stop. +6. **Gates** per `$HOME/.claude/lib/verify-secure-loop.md`, `CONTRACT` the + path above, `DIFF` the executor's working-tree diff, `TEST` the suite. + GATE 0 runs every scanner oracle (the per-fix proof), GATE 1 a fresh + verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are + the include's; loop decisions stay in this main loop. + +## STEP 9: Re-pass (prove it all) + +`mcp__model-router__route(phase="reflect")`. The gates proved each accepted +fix on its own; this pass proves the whole tree. + +1. Full scan against the baseline: + ``` + python3 -B --baseline .claude/audits/.a11y-baseline.json + ``` + Every accepted pair must show `FIXED`, and the run must end on + `A11Y-NO-NEW` (exit 0). A `NEW` hit is a regression the fix made. +2. Live: when STEP 4 ran, walk the same flow again once the user has reloaded + the dev server and says go. Each stop a proposal named must now pass. +3. Add an "after" column to `.claude/audits/A11Y.md`: proposal, before, + after, evidence. + +Anything not fixed, or a NEW hit → one more round from STEP 6, limited to +those items. Two rounds at most: after the second, stop with the residuals +open and say so plainly. Never report a fix the re-pass did not prove. + +## STEP 10: Commit and hand over + +1. **Commit gate.** Show files, `git diff --stat` and the message, wait for + the user's go: + ``` + A11Y: READY TO COMMIT + FILES : + MESSAGE : fix(a11y): + ``` + Then `git add ` (never `-A`, never the baseline file) and + commit, project convention else 50 words at most. +2. `mcp__model-router__route(phase="apply")` for the tail. Reply with: fixed + and proven (proposal, rule, file), still open and why, the walk's result, + the branch name. Merge waits for the user's explicit signal. +3. Offer to capitalize a reusable lesson (a false-positive class, a fix + pattern), entry pre-filled, written only on approval. +```` + +Measure the description: `awk 'NR==4' skills/a11y/SKILL.md | sed 's/^description: //' | wc -c` must print 1024 or less. + +- [ ] **Step 2: Write `skills/a11y/references/checks.md`** + +```markdown +# Accessibility checks + +Rule ids the scanner emits, what each proves, and the fix. Severity is the +default; a judged hit can be a false positive. + +| Rule | Sev | Catches | Fix | +|---|---|---|---| +| A11Y-IMG-ALT | FAIL | `img` or `Image` without `alt` | describe it, or `alt=""` if decorative | +| A11Y-FIELD-LABEL | FAIL | native input, select, textarea with no label | `label for`, wrapping label or `aria-label` | +| A11Y-CLICK-NO-KEYBOARD | FAIL | click handler on a div or span lacking role, tabindex or key handler | use a `button` | +| A11Y-FOCUS-OUTLINE | FAIL / WARN | focus outline removed; WARN when a `:focus-visible` style exists elsewhere | style `:focus-visible` instead | +| A11Y-TABINDEX-POSITIVE | WARN | `tabindex` above 0 | use 0 or -1 and fix the DOM order | + +## Blind spots + +The scanner is regex over markup and styles. It cannot see: + +- keyboard traps, focus order, a modal that keeps or loses focus, color + contrast: the `--live` walk covers the first three, `/web-validate` the + fourth +- a label wired through `aria-labelledby` to an element in another file +- components whose markup is built at runtime, minified bundles, anything + over 1 MB +- `.astro` files for the click rule (never flagged) + +By design the scanner ignores: fields that are never rendered (`hidden`, +`display: none`), click handlers that only stop propagation or sit on +`role="presentation"`, focus styles that swap the outline for a border or +shadow, and `img` tags inside comments. + +## Fix loop: oracles and re-pass + +Every accepted fix is proven by the scanner itself, never by the executor's +word. Two check modes replace the report and its exit code: + +| Mode | Passes when | Marker | Used by | +|---|---|---|---| +| `--assert-absent RULE:path,...` | none of these FAIL/WARN pairs remains, the domain was scanned, the tree is not empty | `A11Y-CLEAR ` | a contract `CHECK:` run by `lib/gates.sh` (GATE 0) | +| `--baseline before.json` | no FAIL/WARN hit appeared since the earlier `--json` run | `A11Y-NO-NEW` | STEP 9 re-pass | + +Pairs match on rule and file, not line: a fix moves lines. An empty tree +fails the assertion, because absence there proves nothing. Run every oracle +once before the fix: it must fail. The baseline lists `FIXED` and `NEW` +pairs with their hit counts; a `NEW` hit after a fix is a regression. +``` + +- [ ] **Step 3: Write `skills/a11y/test-prompts.json`** + +```json +[ + {"id": 1, "prompt": "vérifie l'accessibilité de base de ~/Documents/faunosteo : clavier, alt, labels", "expected": "Runs the a11y scanner on the path, reads each A11Y FAIL and WARN in context, marks the keyboard walk not done (no --live), writes .claude/audits/A11Y.md, proposes fixes with alt and label wording as visible choices, stops for approval"}, + {"id": 2, "prompt": "il manque des alt sur les images du site, corrige", "expected": "Scans, confirms each A11Y-IMG-ALT hit, proposes one alt text per image (or alt=\"\" for decorative ones) as a named choice, applies only after acceptance on a bugfix branch with --assert-absent oracles, re-scans against the baseline"}, + {"id": 3, "prompt": "Walk my app at http://localhost:3000 with the keyboard only and tell me where focus gets lost", "expected": "Static scan first, then the Tab walk through /browse on the named localhost target, records each stop with no visible focus or unreachable control, reports them next to the static findings, fixes nothing without approval"}, + {"id": 4, "prompt": "est-ce que mon site passe les critères WCAG AA ?", "expected": "Routes to /web-validate for WCAG conformance; runs /a11y only if the user asks for the keyboard/alt/label baseline"}, + {"id": 5, "prompt": "a11y --report-only sur ce projet", "expected": "Scan and judgment only, report written, counts and file:line in the reply, no proposal, no branch, no edit"} +] +``` + +- [ ] **Step 4: Write `rules/a11y.md`** + +```markdown +--- +paths: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.html", "**/*.css", "**/*.scss"] +--- + +# Accessibility baseline (audit and fix: `/a11y`) + +- Everything reachable and usable by keyboard, focus always visible. + `:focus-visible` styled, never `outline: none` without a replacement. +- Every image has an `alt` (empty when decorative). Every field has a label; + a placeholder is not a label. +``` + +- [ ] **Step 5: Add the routing row without sweeping the pre-existing hunks** + +```bash +git status --short mods/model-router/routing.json settings.json +``` + +If either file shows `M`, stash those two files first (and only them): + +```bash +git stash push -m "pre-existing: routing dialog decisions + settings env key" -- mods/model-router/routing.json settings.json +``` + +Then in `mods/model-router/routing.json`, in the `skills` block, add the line ` "a11y": "reflect",` right after ` "guardrails": "reflect",`. Validate: `python3 -I -c 'import json; json.load(open("mods/model-router/routing.json"))'`. + +```bash +git add mods/model-router/routing.json +git commit -m "chore(model-router): a11y skill row (reflect)" +git stash pop +git status --short mods/model-router/routing.json settings.json +``` + +The last status must show both files `M` again (the pre-existing diffs restored) and `git stash list` must be empty. A pop conflict means the a11y line sits next to a dialog hunk: keep both, `git add` nothing, continue. + +- [ ] **Step 6: Profiles, locks and flow enums** + +1. In `lib/profiles/audit.profile`, `dev.profile`, `web-full.profile`, `full.profile`, `max.profile`: add the line `a11y personal` right after the `guardrails …personal` line. In `lib/profiles/web.profile`: add it right after the `web-validate …personal` line. The name column is 34 characters wide: `a11y` plus 30 spaces. +2. `lib/tests/model-routing.test.sh`: add `a11y` at the end of the `for s in ship-feature … guardrails; do` list and change the comment to `# 1) gate wired in the 17 reflection skills (orchestrators, /analyze, /guardrails, /a11y)`. +3. `lib/tests/loops-light.test.sh`: find how `GSK` is defined near the top (`GSK="$R/skills/guardrails/SKILL.md"` or similar) and define `ASK` the same way for `skills/a11y/SKILL.md`. After the guardrails block add: + ```bash + echo "── skills/a11y/SKILL.md (fix loop reuses the bugfix circuit) ──" + tf "a11y contract include" "$ASK" "lib/contract-interview.md" + tf "a11y uses shared include" "$ASK" "lib/verify-secure-loop.md" + tf "a11y dispatches bugfixer" "$ASK" 'subagent_type="bugfixer"' + tf "a11y scanner is the oracle" "$ASK" "EXPECT: A11Y-CLEAR" + tf "a11y positive control" "$ASK" "Positive control" + tf "a11y approval gate" "$ASK" "Nothing is applied without the user's explicit acceptance" + tf "a11y re-pass baseline" "$ASK" "A11Y-NO-NEW" + ``` +4. `lib/verify-secure-loop.md` line 1: `(feat, bugfix, guardrails)` → `(feat, bugfix, guardrails, a11y)`. +5. `lib/contract-interview.md` line 117: `…|onboard|guardrails>` → `…|onboard|guardrails|a11y>`. +6. `agents/bugfixer.md` line 3: `dispatched by /bugfix (or /guardrails for accepted fixes)` → `dispatched by /bugfix (or /guardrails and /a11y for accepted fixes)`. + +- [ ] **Step 7: Run the censuses** + +Run: `make test suite='lib/tests/effort-routing.test.sh lib/tests/profile-census.test.sh lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/tests/skill-routing-census.test.sh'` +Expected: `all suites green`. A skill-routing WARN naming `a11y~web-validate` above 0.50 means the two descriptions still read alike: trim shared words from the a11y description (never from web-validate's, Task 8 handles that file) and re-measure. + +- [ ] **Step 8: Commit** + +```bash +git add skills/a11y/SKILL.md skills/a11y/references/checks.md skills/a11y/test-prompts.json rules/a11y.md lib/profiles/audit.profile lib/profiles/dev.profile lib/profiles/web.profile lib/profiles/web-full.profile lib/profiles/full.profile lib/profiles/max.profile lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/verify-secure-loop.md lib/contract-interview.md agents/bugfixer.md +git commit -m "feat(a11y): skill (scan, keyboard walk, report, fix loop on the bugfix circuit), lazy rules/a11y.md, profiles, locks" +``` + +--- + +### Task 7: `/guardrails` skill text, reference, prompts and the secure-by-default rule + +**Files:** +- Modify: `skills/guardrails/SKILL.md`, `skills/guardrails/references/checks.md`, `skills/guardrails/test-prompts.json`, `rules/secure-by-default.md` +- Test: `make test suite='lib/tests/loops-light.test.sh lib/tests/model-routing.test.sh lib/tests/skill-routing-census.test.sh lib/tests/doctrine-citers.test.sh'` + +- [ ] **Step 1: `skills/guardrails/SKILL.md` frontmatter** + +Replace the `description:` line with this single-quoted line (then measure it: `awk 'NR==4' skills/guardrails/SKILL.md | sed 's/^description: //' | wc -c` ≤ 1024): + +``` +description: 'Use when auditing a project against the baseline guardrails and fixing what fails: hosting (rate limit, CDN and firewall, spend cap), Supabase (RLS on every table, owner-scoped policies, no service_role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (SQL built from input, raw escapes, NoSQL operators, shell into DB tools), exposure (console data, source maps, hydrated state, error bodies, debug mode, wide responses), plus API hygiene (auth on every route, CORS, secrets, password storage). Deterministic scanner, judgment, .claude/audits/GUARDRAILS.md, then fixes applied only on acceptance (bugfixer, fresh verifier and security gates) and re-scanned to prove them; optional read-only live probe on a target the user owns. Triggers: "guardrails", "garde-fous", "RLS activée ?", "faille sql", "injection", "qu''est-ce qui fuit dans le navigateur", "plafond de dépense", "mots de passe en clair ?", "corrige les garde-fous", "sonde le projet en direct". Headers and TLS → /harden; secrets, CVE, dependencies → /cso; keyboard, alt, labels → /a11y.' +``` + +`argument-hint`: `'[project path] [--domain api,hosting,supabase,messaging,functions,injection,exposure] [--exclude paths] [--live ] [--report-only]'`. + +- [ ] **Step 2: `skills/guardrails/SKILL.md` body** + +1. STEP 1: `Domains: \`api\`, \`hosting\`, \`a11y\`, \`supabase\`, \`messaging\`, \`functions\`.` → `Domains: \`api\`, \`hosting\`, \`supabase\`, \`messaging\`, \`functions\`, \`injection\`, \`exposure\`.` +2. STEP 4: replace the `- **A11y**: …` bullet (two lines) with: + ``` + - **Injection**: for each INJ hit, trace the interpolated value to its + source. A constant, an allowlisted identifier or a value already cast to + a number is a FALSE POSITIVE; anything that can come from a request, + a file or another user's row is CONFIRMED. + - **Exposure**: open the main page in a browser and read what the console, + the network responses and the DOM carry: a token in a `data-*` + attribute, a user object logged, a full row in an API answer. With + `--live`, the probe answers for served source maps, error bodies and + sensitive keys; the rest is read by hand. + ``` +3. STEP 5.1: after `and a \`rate_limit\` route if the user wants that one burst.` add the sentence `Add an \`exposure\` block (\`{}\` for the defaults, \`error_routes\` for a route you own that answers an error to a malformed id, never a path you guess) so the probe reads source maps, error bodies and response keys.` +4. STEP 8 proposal examples: `the label text for a field.` → `the parameter binding for a query.`; `(label wording, CORS origins, owner column,\n rate-limit numbers)` → `(allowlisted filter fields, CORS origins, owner column,\n rate-limit numbers)`. +5. STEP 9 example: `("2 with the label 'Email'")` → `("2 with the fields ['id','status']")`. + +Every locked sentence from loops-light stays untouched and on one line. + +- [ ] **Step 3: `skills/guardrails/references/checks.md`** + +1. Delete the `## a11y` section (heading and table). +2. Add after the `## hosting` section: + ```markdown + ## injection + + | Rule | Sev | Catches | Fix | + |---|---|---|---| + | INJ-SQL-RAW-UNSAFE | FAIL | `$queryRawUnsafe`, `$executeRawUnsafe`, `knex.raw`, `.raw()`, `.extra()`, `sequelize.query`, `Sequelize.literal`, SQLAlchemy `text()` fed a variable; ActiveRecord `where("… #{}")` | bind the values, or the tagged `$queryRaw` | + | INJ-SQL-CONCAT | FAIL | a SQL statement string built with `${}`, `+`, an f-string, `%`, `.format`, PHP `$var`, Ruby `#{}`, `format!`, `Sprintf` | placeholders and a parameter list | + | INJ-SQL-DYNAMIC-EXEC | WARN | plpgsql `EXECUTE '…' \|\| x` | `format('… %I %L', …)` and `USING` | + | INJ-POSTGREST-FILTER | WARN | supabase-js `.or()`, `.filter()`, `.not()`, `.match()`, `.textSearch()` with an interpolated string | `.eq()` and friends, validated values | + | INJ-NOSQL-OPERATOR | WARN | Mongo `$where` with a string; a filter taken from `req.body`, `req.query` or `req.params` | allowlist the fields, cast to string, `sanitizeFilter` | + | INJ-SHELL-DB-TOOL | FAIL | a shell call naming psql, mysql, mysqldump, pg_dump, mongosh, redis-cli, sqlite3… with an interpolated argument | an argv array, no shell, validated input | + + ## exposure + + | Rule | Sev | Catches | Fix | + |---|---|---|---| + | EXP-CONSOLE-DATA | WARN | `console.log/info/debug/dir/table` in client-reachable code with a data argument (user, session, response, token, body…) | strip console calls in the production build, log server-side | + | EXP-SOURCEMAP-PUBLIC | FAIL / WARN | `productionBrowserSourceMaps: true`, vite `sourcemap: true`, `GENERATE_SOURCEMAP=true`, webpack `devtool` readable maps (FAIL in `webpack.prod*`, WARN elsewhere), a `.map` under `public/`; angular `sourceMap: true` (WARN) | off, or `hidden` and upload to the error tracker | + | EXP-HYDRATED-SENSITIVE | WARN | a token, secret, key, password or ssn-like key returned by `getServerSideProps`, `getStaticProps`, a Remix `loader`, a SvelteKit `load` or set on `window.__STATE__` | return only the fields the page renders | + | EXP-MARKUP-COMMENT | WARN | `` shipped to the browser (html, astro, php, ejs, hbs, twig, njk, liquid) with todo, fixme, debug, password, token, internal, staging, admin… | delete it, or move it to a code comment the build strips | + | EXP-DATA-ATTR-SENSITIVE | WARN | `data-*` attribute or hidden input named secret, api-key, password, jwt, private, credential (csrf excluded) | keep it server-side, send an opaque id | + | EXP-ERROR-STACK | FAIL | `err.stack`, the error object, `traceback.format_exc()` or `getTraceAsString()` in a response | generic message out, full error in the server log | + | EXP-ERROR-MESSAGE | WARN | `err.message`, `str(e)`, `$e->getMessage()` sent as is | map to a safe message; validation errors are fine, DB errors are not | + | EXP-DEBUG-ON | FAIL | `DEBUG = True`, `APP_DEBUG=true`, `FLASK_DEBUG=1`, `app.debug = True`, `consider_all_requests_local = true`, `errorhandler()` | env-driven, false in production | + | EXP-RESPONSE-WIDE | WARN | a route returning `select *` / `select('*')` / `findUnique` without `select` or `omit` on a users-like table | an explicit field list | + ``` +3. Blind spots list: replace `- keyboard traps, focus order, modal focus handling, color contrast` with + ``` + - a SQL string assembled across several lines, or passed through a + variable before the query call (trace it by hand) + - whether a template literal's tag parameterizes: tagged templates are + trusted + - built output (`dist/`, `.next/`) and runtime state such as + `__NEXT_DATA__`: only the live probe sees a served map or a hydrated + token + - what the console or an XHR carries once the page runs: a browser walk + ``` +4. "By design the scanner ignores" paragraph: remove `fields that are never rendered (\`hidden\`, \`display: none\`), click handlers that only stop propagation or sit on \`role="presentation"\`, focus styles that swap the outline for a border or shadow, ` and append `, tagged SQL templates, placeholders with a separate parameter list, an argv array handed to a DB tool, console calls in server code, \`sourcemap: 'hidden'\`, a debug flag read from the environment, and a hidden input named csrf, xsrf, authenticity or nonce` before the final period. +5. Live probe section: in the plan JSON example add, before the closing brace, `,\n "exposure": {"error_routes": ["/api/v1/notes/not-a-number"]}`; after the `Environment, from test keys only…` sentence add `The fields probe sends \`GUARDRAILS_JWT2\` as a bearer when it is set.`; add three rows to the probe table: + ``` + | sourcemap | `sourcemap:' b'' + b'' b'' b'') if path == "/app.js": @@ -1175,12 +1321,16 @@ In `lib/tests/guardrails-probe.test.sh`, inside the `do_GET` handler of `server. return self._send(200, b'{"version":3,"sources":["src/app.ts"],"mappings":""}') if path == "/clean.js": return self._send(200, b"console.log(2);\n") + if path == "/inline.js": + return self._send(200, b"console.log(3);\n//# sourceMappingURL=" + b"data:application/json;base64,eyJ2ZXJzaW9uIjozfQ==\n") if path == "/boom": return self._send(500, b"Traceback (most recent call last):\n" b' File "app.py", line 12, in handler\n') if path == "/api/me": return self._send(200, b'{"id": 1, "email": "t@t.io", ' - b'"password_hash": "x", "profile": {"api_key": "y"}}', + b'"password_hash": "x", "profile": {"api_key": "y"}, ' + b'"next_page_token": "abc", "hashtags": []}', {"Content-Type": "application/json"}) ``` @@ -1194,18 +1344,20 @@ And replace `do_OPTIONS` so header names are lowercase on `/lower`: self._send(204, b"", {names[0]: origin, names[1]: "true"}) ``` -Then add a test block before `echo "== JSON output"` (the inner heredocs use `EOF` exactly like the existing plan files in this suite): +Then add a test block before `echo "== JSON output"` (the inner heredocs use `EOF` exactly like the plan files already in this suite): ```bash echo "== exposure probes" cat > "$WORK/exposure.json" < "$WORK/unreachable.json" < "$WORK/badexp.json" probe --authorized "$WORK/badexp.json" >/dev/null 2>&1 check "an error route not starting with / exits 2" "$?" 2 printf '{"base_url": "%s", "exposure": []}\n' "$BASE" > "$WORK/badexp2.json" probe --authorized "$WORK/badexp2.json" >/dev/null 2>&1 check "a non-object exposure block exits 2" "$?" 2 +printf '{"base_url": "%s", "exposure": {"scripts": "/app.js"}}\n' "$BASE" > "$WORK/badexp3.json" +probe --authorized "$WORK/badexp3.json" >/dev/null 2>&1 +check "a scripts string instead of a list exits 2" "$?" 2 +printf '{"base_url": "%s", "routes": [{"path": ".evil.invalid/x"}]}\n' "$BASE" > "$WORK/badroute.json" +probe --authorized "$WORK/badroute.json" >/dev/null 2>&1 +check "a route path that could leave the host exits 2" "$?" 2 cat > "$WORK/lower.json" <&1 | grep -c ' FAIL '` -Expected: at least 9 (the sourcemap, error-body and fields rows are absent; lowercase CORS reads CLOSED; the two exit-2 checks get 1). +Expected: at least 12 (the sourcemap, error-body and fields rows are absent; lowercase CORS reads CLOSED; the four exit-2 checks get 1 or 0). - [ ] **Step 3: Patch `probe.py`** Imports: add `import re` and change the parse import to `from urllib.parse import quote, urljoin, urlsplit`. -Replace `_response_from` and `fetch`: +Replace `_response_from` and `fetch` (headers stay the `HTTPMessage`, whose `.get` is case-insensitive; the body of an HTTP error is read instead of dropped): ```python -def _headers(message): - return {k.lower(): v for k, v in message.items()} - - def _error_body(exc): try: return exc.read(BODY_CAP) @@ -1258,7 +1420,7 @@ def _error_body(exc): def _response_from(resp): - return Response(resp.status, _headers(resp.headers), resp.read(BODY_CAP)) + return Response(resp.status, resp.headers, resp.read(BODY_CAP)) def fetch(session, method, url, headers=None, body=None): @@ -1271,45 +1433,49 @@ def fetch(session, method, url, headers=None, body=None): with session.opener.open(req, timeout=session.timeout) as resp: return _response_from(resp) except urllib.error.HTTPError as exc: - return Response(exc.code, _headers(exc.headers), _error_body(exc)) + return Response(exc.code, exc.headers, _error_body(exc)) except (urllib.error.URLError, OSError, ValueError) as exc: return Response(None, {}, b"", str(exc)) ``` -In `_cors_open`: `headers.get("access-control-allow-origin", "")` and `headers.get("access-control-allow-credentials", "")`. +`_cors_open` is unchanged. Change the `Response.headers` annotation comment to `headers: object # http.client.HTTPMessage: .get() ignores case`. Add the constants after `BODY_CAP`: ```python SCRIPT_CAP = 10 -SCRIPT_SRC = re.compile(rb"]+src=[\"']([^\"']+)[\"']", re.I) -MAP_COMMENT = re.compile(rb"//[#@]\s*sourceMappingURL=(\S+)") +SCRIPT_SRC = re.compile(r"]+src=[\"']?([^\"'\s>]+)", re.I) +MAP_COMMENT = re.compile(r"//[#@]\s*sourceMappingURL=(\S+)") TRACE_MARKERS = re.compile( rb"Traceback \(most recent call last\)|\bat [\w.$<> ]+ \([^)\n]*:\d+:\d+\)" rb"|File \"[^\"\n]+\", line \d+|SQLSTATE\[|syntax error at or near" rb"|node_modules/|/var/www/|Stack trace:|#\d+ /[\w/.-]+\.php\(\d+\)") SENSITIVE_KEY = re.compile( - r"password|passwd|pwd|hash|salt|secret|token|api_?key|service_?role" - r"|private|ssn|iban|cvv|card_?number", re.I) + r"(?:^|_)(?:password|passwd|pwd|salt|secret|api_?key|service_?role" + r"|private_?key|(?:access|refresh|id|auth|api|session)_token|jwt|ssn" + r"|iban|cvv|card_?number)(?:$|_)") +IDENT = re.compile(r"^[A-Za-z_][\w-]{0,31}$") ``` -Add the probes before `PROBES = (…)` and append `probe_exposure` to the tuple: +Add the probes before `PROBES = (…)` and place `probe_exposure` BEFORE `probe_rate_limit` in the tuple (the burst is the largest budget consumer; exposure must not starve behind it): ```python def _same_host(context, url): """Absolute url when it stays on context's host, else None.""" - text = url.decode("utf-8", "ignore") if isinstance(url, bytes) else url - full = urljoin(context, text) + full = urljoin(context, url) return full if urlsplit(full).netloc == urlsplit(context).netloc else None -def _script_urls(session, base, cfg): - listed = cfg.get("scripts") - if listed is None: - page = fetch(session, "GET", base + "/") - listed = [m.group(1) for m in SCRIPT_SRC.finditer(page.body)] - urls = [u for u in (_same_host(base + "/", s) for s in listed) if u] - return list(dict.fromkeys(urls))[:SCRIPT_CAP] +def _page_scripts(session, base): + """(urls, note): same-host scripts of the base page, or why none.""" + page = fetch(session, "GET", base + "/") + if page.error: + return [], f"base page unreachable: {page.error}" + text = page.body.decode("utf-8", "ignore") + urls = [u for u in (_same_host(base + "/", s) + for s in SCRIPT_SRC.findall(text)) if u] + urls = list(dict.fromkeys(urls))[:SCRIPT_CAP] + return urls, "" if urls else "no same-host script on the base page" def _map_candidates(script_url, resp): @@ -1317,14 +1483,27 @@ def _map_candidates(script_url, resp): header = resp.headers.get("sourcemap") or resp.headers.get("x-sourcemap") if header: urls.append(header) - comment = MAP_COMMENT.search(resp.body[-600:]) + tail = resp.body[-600:].decode("utf-8", "ignore") + comment = MAP_COMMENT.search(tail) if comment: urls.append(comment.group(1)) - return [u for u in (_same_host(script_url, u) for u in urls) if u] + return list(dict.fromkeys(urls)) -def _map_served(resp): - return resp.status == 200 and b'"sources"' in resp.body +def _map_verdict(session, script_url, candidates): + """(verdict, target, note) over the candidate map urls, fail closed.""" + for url in candidates: + if url.startswith("data:"): + return "OPEN", script_url, "inline source map in the script" + target = _same_host(script_url, url) + if not target: + continue + resp = fetch(session, "GET", target) + if resp.error or resp.status is None: + return "ERROR", target, resp.error or "no response" + if resp.status == 200 and b'"sources"' in resp.body: + return "OPEN", target, "source map served with its sources" + return "CLOSED", script_url, "no source map served for this script" def _sourcemap_probe(session, script_url): @@ -1332,13 +1511,20 @@ def _sourcemap_probe(session, script_url): resp = fetch(session, "GET", script_url) if resp.error: return Probe("exposure", pid, "ERROR", script_url, resp.error) - served = next((u for u in dict.fromkeys(_map_candidates(script_url, resp)) - if _map_served(fetch(session, "GET", u))), None) - if served: - return Probe("exposure", pid, "OPEN", served, - "source map served with its sources") - return Probe("exposure", pid, "CLOSED", script_url, - "no source map served for this script") + verdict, target, note = _map_verdict( + session, script_url, _map_candidates(script_url, resp)) + return Probe("exposure", pid, verdict, target, note) + + +def _sourcemaps(session, base, cfg): + listed = cfg.get("scripts") + if listed is None: + urls, note = _page_scripts(session, base) + else: + urls, note = [base + s for s in listed][:SCRIPT_CAP], "" + if note: + return [Probe("exposure", "sourcemap", "SKIPPED", base, note)] + return [_sourcemap_probe(session, u) for u in urls] def _error_probe(session, base, path): @@ -1372,12 +1558,38 @@ def _keys(data, depth=0): return [] -def _sensitive_keys(body): +def _snake(key): + return re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", key).replace("-", "_").lower() + + +def _sensitive_keys(data): + return sorted({k for k in _keys(data) if SENSITIVE_KEY.search(_snake(k))}) + + +def _key_note(keys): + """Identifier-shaped key names only; anything else is counted.""" + shown = [k for k in keys if IDENT.match(k)] + hidden = len(keys) - len(shown) + return ", ".join(shown) + (f" (+{hidden} unprintable)" if hidden else "") + + +def _json_body(resp): try: - data = json.loads(body or b"null") + return json.loads(resp.body), True except ValueError: - return [] - return sorted({k for k in _keys(data) if SENSITIVE_KEY.search(k)}) + return None, False + + +def _fields_verdict(resp): + if resp.error: + return "ERROR", resp.error + data, is_json = _json_body(resp) + if resp.status != 200 or not is_json: + return "SKIPPED", f"HTTP {resp.status}: no JSON body to read" + keys = _sensitive_keys(data) + if keys: + return "OPEN", "response carries sensitive keys: " + _key_note(keys) + return "CLOSED", "no sensitive key in the response" def _bearer(): @@ -1387,12 +1599,8 @@ def _bearer(): def _fields_probe(session, base, route): target = base + route["path"] - resp = fetch(session, "GET", target, _bearer()) - keys = _sensitive_keys(resp.body) if resp.status == 200 else [] - return _verdict( - ("exposure", f"fields:{route['path']}", target), resp, bool(keys), - ("response carries sensitive keys: " + ", ".join(keys), - "no sensitive key in the response")) + verdict, note = _fields_verdict(fetch(session, "GET", target, _bearer())) + return Probe("exposure", f"fields:{route['path']}", verdict, target, note) def probe_exposure(session, plan): @@ -1400,31 +1608,39 @@ def probe_exposure(session, plan): if cfg is None: return [] base = plan["base_url"].rstrip("/") - out = [_sourcemap_probe(session, u) - for u in _script_urls(session, base, cfg)] + out = _sourcemaps(session, base, cfg) out += [_error_probe(session, base, p) for p in _error_paths(cfg)] out += [_fields_probe(session, base, r) for r in plan.get("routes", [])] return out PROBES = (probe_supabase, probe_cross_user, probe_routes, - probe_cors, probe_rate_limit, probe_exposure) + probe_cors, probe_exposure, probe_rate_limit) ``` -Extend plan validation: +Extend plan validation (replace `_plan_error`): ```python +def _plan_paths(plan): + cfg = plan.get("exposure") or {} + supa = plan.get("supabase") or {} + rate = plan.get("rate_limit") or {} + return ([r.get("path") if isinstance(r, dict) else r + for r in plan.get("routes", [])] + + list(supa.get("cross_user_paths") or []) + + [plan.get("cors_path", "/"), rate.get("path", "/")] + + list(cfg.get("scripts") or []) + + list(cfg.get("error_routes") or [])) + + def _exposure_error(cfg): if cfg is None: return "" if not isinstance(cfg, dict): return "exposure must be an object" for key in ("scripts", "error_routes"): - items = cfg.get(key) or [] - if not all(isinstance(i, str) for i in items): - return f"exposure.{key} must be a list of strings" - if any(not r.startswith("/") for r in cfg.get("error_routes") or []): - return "exposure.error_routes entries must start with /" + if cfg.get(key) is not None and not isinstance(cfg[key], list): + return f"exposure.{key} must be a list" return "" @@ -1432,21 +1648,24 @@ def _plan_error(plan): method = plan.get("rate_limit", {}).get("method", "GET").upper() if method not in READ_METHODS and method != "POST": return f"rate_limit method {method} is not a probe method" - return _exposure_error(plan.get("exposure")) + error = _exposure_error(plan.get("exposure")) + bad = [p for p in _plan_paths(plan) + if not isinstance(p, str) or not p.startswith("/")] + return error or (f"plan path {bad[0]!r} must start with /" if bad else "") ``` -Module docstring: after the `GUARDRAILS_JWT2` line add ` (also sent as bearer by the fields probe when set)`; in the first paragraph add the sentence `With an exposure block in the plan it also reads what the page's scripts, error bodies and JSON responses give away.` +Module docstring: after the `GUARDRAILS_JWT2` line add ` (also sent as bearer by the fields probe when set)`; in the first paragraph add `With an exposure block in the plan it also reads what the page's scripts, error bodies and JSON responses give away; a target it could not observe is ERROR or SKIPPED, never CLOSED.` - [ ] **Step 4: Run the suite** Run: `make test suite=lib/tests/guardrails-probe.test.sh` -Expected: `failed: 0`, including the untouched `json reports the open count` = 4 (`plan.json` has no `exposure` block) and `the burst is capped` = 25. +Expected: `failed: 0`, including the untouched `json reports the open count` = 4 (`plan.json` has no `exposure` block and its paths all start with `/`) and `the burst is capped` = 25. The `next_page_token` and `hashtags` keys of `/api/me` must not appear in the key list (segment matching). - [ ] **Step 5: Commit** ```bash git add skills/guardrails/scripts/probe.py lib/tests/guardrails-probe.test.sh -git commit -m "feat(guardrails): exposure probe (source maps served, error bodies, sensitive keys); fetch keeps error bodies, headers lowercased" +git commit -m "feat(guardrails): exposure probe (source maps served or inline, error bodies, sensitive keys) that fails closed; every plan path validated; fetch keeps error bodies" ``` --- @@ -1455,7 +1674,7 @@ git commit -m "feat(guardrails): exposure probe (source maps served, error bodie **Files:** - Create: `skills/a11y/SKILL.md`, `skills/a11y/references/checks.md`, `skills/a11y/test-prompts.json`, `rules/a11y.md` -- Modify: `mods/model-router/routing.json` (one row), `lib/profiles/{audit,dev,web,web-full,full,max}.profile`, `lib/tests/model-routing.test.sh`, `lib/tests/loops-light.test.sh`, `lib/verify-secure-loop.md:1`, `lib/contract-interview.md:117`, `agents/bugfixer.md:3` +- Modify: `rules/web-building.md` (two fragments point at `rules/a11y.md`), `mods/model-router/routing.json` (one row), `lib/profiles/{audit,dev,web,web-full,full,max}.profile`, `lib/tests/model-routing.test.sh`, `lib/tests/loops-light.test.sh`, `lib/verify-secure-loop.md:1`, `lib/contract-interview.md:117`, `agents/bugfixer.md:3` - Test: `make test suite='lib/tests/effort-routing.test.sh lib/tests/profile-census.test.sh lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/tests/skill-routing-census.test.sh'` **Interfaces:** @@ -1464,13 +1683,13 @@ git commit -m "feat(guardrails): exposure probe (source maps served, error bodie - [ ] **Step 1: Write `skills/a11y/SKILL.md`** -The description is one single-quoted line. The seven locked sentences (`lib/contract-interview.md`, `lib/verify-secure-loop.md`, `subagent_type="bugfixer"`, `EXPECT: A11Y-CLEAR`, `Positive control`, `Nothing is applied without the user's explicit acceptance`, `A11Y-NO-NEW`) and `lib/model-gate.md` must each sit on one line, as below. +The description is one single-quoted line (896 characters). The seven locked sentences (`lib/contract-interview.md`, `lib/verify-secure-loop.md`, `subagent_type="bugfixer"`, `EXPECT: A11Y-CLEAR`, `Positive control`, `Nothing is applied without the user's explicit acceptance`, `A11Y-NO-NEW`) and `lib/model-gate.md` must each sit on one line, as below. ````markdown --- name: a11y effort: high -description: 'Use when a web project needs its accessibility baseline checked and fixed: everything reachable by keyboard with a visible focus, an alt on every image, a label on every field. Runs a deterministic scanner (A11Y-* rules: img alt, field label, click without keyboard, focus outline removed, positive tabindex), judges each hit, walks the main flow with Tab only on --live (through /browse, else marked not done), writes .claude/audits/A11Y.md, then proposes fixes with the alt and label wording as visible choices, applies only the ones the user accepts (bugfixer executor, fresh verifier and security gates, the scanner as oracle) and re-scans to prove each one. Triggers: "a11y", "accessibilité", "accessibility basics", "clavier", "focus visible", "alt manquant", "label sur les champs", "tab order", "corrige l''accessibilité". Full WCAG conformance (axe, pa11y, W3C) → /web-validate; security guardrails → /guardrails.' +description: 'Use when a web project needs its accessibility baseline checked and fixed: everything reachable by keyboard with a visible focus, an alt on every image, a label on every field. Full WCAG conformance (axe, pa11y, W3C) → /web-validate; security guardrails → /guardrails. Deterministic scanner (A11Y-* rules: img alt, field label, click without keyboard, focus outline removed, positive tabindex), judgment, a Tab-only walk of the main flow on --live (through /browse, else marked not done), report .claude/audits/A11Y.md, then fixes proposed with the alt and label wording as visible choices, applied only on acceptance (bugfixer executor, fresh verifier and security gates, the scanner as oracle) and re-scanned to prove each one. Triggers: "a11y", "accessibilité", "accessibility basics", "clavier", "focus visible", "alt manquant", "label sur les champs", "tab order", "corrige l''accessibilité".' argument-hint: '[project path] [--exclude paths] [--live ] [--report-only]' --- @@ -1669,7 +1888,7 @@ open and say so plainly. Never report a fix the re-pass did not prove. pattern), entry pre-filled, written only on approval. ```` -Measure the description: `awk 'NR==4' skills/a11y/SKILL.md | sed 's/^description: //' | wc -c` must print 1024 or less. +Measure the description: `awk 'NR==4' skills/a11y/SKILL.md | sed 's/^description: //' | wc -c` must print 1024 or less (expected about 910 bytes). - [ ] **Step 2: Write `skills/a11y/references/checks.md`** @@ -1732,7 +1951,9 @@ pairs with their hit counts; a `NEW` hit after a fix is a regression. ] ``` -- [ ] **Step 4: Write `rules/a11y.md`** +- [ ] **Step 4: Write `rules/a11y.md` and point `rules/web-building.md` at it** + +`rules/a11y.md`: ```markdown --- @@ -1747,16 +1968,18 @@ paths: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.h a placeholder is not a label. ``` -- [ ] **Step 5: Add the routing row without sweeping the pre-existing hunks** +In `rules/web-building.md` (same globs, so both load together on UI files): the fragment `visible `:focus-visible` ring;` in the "Touch targets" bullet becomes `keyboard and focus per `rules/a11y.md`;` and the fragment `alt text on images` in the "Before declaring a public site done" paragraph becomes `accessibility baseline (`rules/a11y.md`)`. Nothing else in that file changes. + +- [ ] **Step 5: Add the routing row, committing that one file alone** ```bash -git status --short mods/model-router/routing.json settings.json +git status --short mods/model-router/routing.json ``` -If either file shows `M`, stash those two files first (and only them): +If it shows `M` (the pre-existing dialog decisions), stash that single file: ```bash -git stash push -m "pre-existing: routing dialog decisions + settings env key" -- mods/model-router/routing.json settings.json +git stash push -m "pre-existing routing dialog decisions" -- mods/model-router/routing.json ``` Then in `mods/model-router/routing.json`, in the `skills` block, add the line ` "a11y": "reflect",` right after ` "guardrails": "reflect",`. Validate: `python3 -I -c 'import json; json.load(open("mods/model-router/routing.json"))'`. @@ -1765,10 +1988,10 @@ Then in `mods/model-router/routing.json`, in the `skills` block, add the line ` git add mods/model-router/routing.json git commit -m "chore(model-router): a11y skill row (reflect)" git stash pop -git status --short mods/model-router/routing.json settings.json +git stash list ``` -The last status must show both files `M` again (the pre-existing diffs restored) and `git stash list` must be empty. A pop conflict means the a11y line sits next to a dialog hunk: keep both, `git add` nothing, continue. +After the pop, `git stash list` must be empty and `git status --short` must show routing.json `M` again (the pre-existing hunks restored, at line 106 and later; the a11y row sits at line 78). A pop that reports a conflict is a STOP: do not touch the index, do not continue the task; report the conflict to the user with `git status` and wait. `settings.json` is never stashed and never staged. - [ ] **Step 6: Profiles, locks and flow enums** @@ -1789,18 +2012,18 @@ The last status must show both files `M` again (the pre-existing diffs restored) 5. `lib/contract-interview.md` line 117: `…|onboard|guardrails>` → `…|onboard|guardrails|a11y>`. 6. `agents/bugfixer.md` line 3: `dispatched by /bugfix (or /guardrails for accepted fixes)` → `dispatched by /bugfix (or /guardrails and /a11y for accepted fixes)`. -- [ ] **Step 7: Run the censuses** +- [ ] **Step 7: Commit, then run the censuses on the committed tree** -Run: `make test suite='lib/tests/effort-routing.test.sh lib/tests/profile-census.test.sh lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/tests/skill-routing-census.test.sh'` -Expected: `all suites green`. A skill-routing WARN naming `a11y~web-validate` above 0.50 means the two descriptions still read alike: trim shared words from the a11y description (never from web-validate's, Task 8 handles that file) and re-measure. - -- [ ] **Step 8: Commit** +The effort-routing census reads `git ls-files`, so the a11y row is only checked once `skills/a11y/SKILL.md` is committed: commit first, then test. ```bash -git add skills/a11y/SKILL.md skills/a11y/references/checks.md skills/a11y/test-prompts.json rules/a11y.md lib/profiles/audit.profile lib/profiles/dev.profile lib/profiles/web.profile lib/profiles/web-full.profile lib/profiles/full.profile lib/profiles/max.profile lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/verify-secure-loop.md lib/contract-interview.md agents/bugfixer.md +git add skills/a11y/SKILL.md skills/a11y/references/checks.md skills/a11y/test-prompts.json rules/a11y.md rules/web-building.md lib/profiles/audit.profile lib/profiles/dev.profile lib/profiles/web.profile lib/profiles/web-full.profile lib/profiles/full.profile lib/profiles/max.profile lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/verify-secure-loop.md lib/contract-interview.md agents/bugfixer.md git commit -m "feat(a11y): skill (scan, keyboard walk, report, fix loop on the bugfix circuit), lazy rules/a11y.md, profiles, locks" ``` +Run: `make test suite='lib/tests/effort-routing.test.sh lib/tests/profile-census.test.sh lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/tests/skill-routing-census.test.sh'` +Expected: `all suites green`. A red census is fixed in place and committed as `fix(a11y): census` before moving on. A skill-routing WARN naming `a11y~web-validate` above 0.50 (the challenge measured 0.18 to 0.23) means the description drifted: trim shared words from the a11y description, never from web-validate's (Task 8 owns that file). + --- ### Task 7: `/guardrails` skill text, reference, prompts and the secure-by-default rule @@ -1811,10 +2034,10 @@ git commit -m "feat(a11y): skill (scan, keyboard walk, report, fix loop on the b - [ ] **Step 1: `skills/guardrails/SKILL.md` frontmatter** -Replace the `description:` line with this single-quoted line (then measure it: `awk 'NR==4' skills/guardrails/SKILL.md | sed 's/^description: //' | wc -c` ≤ 1024): +Replace the `description:` line with this single-quoted line (994 characters, 1002 bytes; then measure: `awk 'NR==4' skills/guardrails/SKILL.md | sed 's/^description: //' | wc -c` must print 1024 or less): ``` -description: 'Use when auditing a project against the baseline guardrails and fixing what fails: hosting (rate limit, CDN and firewall, spend cap), Supabase (RLS on every table, owner-scoped policies, no service_role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (SQL built from input, raw escapes, NoSQL operators, shell into DB tools), exposure (console data, source maps, hydrated state, error bodies, debug mode, wide responses), plus API hygiene (auth on every route, CORS, secrets, password storage). Deterministic scanner, judgment, .claude/audits/GUARDRAILS.md, then fixes applied only on acceptance (bugfixer, fresh verifier and security gates) and re-scanned to prove them; optional read-only live probe on a target the user owns. Triggers: "guardrails", "garde-fous", "RLS activée ?", "faille sql", "injection", "qu''est-ce qui fuit dans le navigateur", "plafond de dépense", "mots de passe en clair ?", "corrige les garde-fous", "sonde le projet en direct". Headers and TLS → /harden; secrets, CVE, dependencies → /cso; keyboard, alt, labels → /a11y.' +description: 'Use when auditing a project against the baseline guardrails and fixing what fails. Headers and TLS → /harden; secrets, CVE, dependencies → /cso; keyboard, alt, labels → /a11y. Domains: hosting (rate limit, CDN, spend cap), Supabase (RLS, owner policies, no service_role client-side), SMS and email (consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (SQL from input, raw escapes, NoSQL, shell into DB tools), exposure (console data, source maps, hydrated state, error bodies, debug mode, wide responses), plus API hygiene (auth, CORS, secrets, passwords). Scanner, judgment, .claude/audits/GUARDRAILS.md, fixes applied only on acceptance (bugfixer, verifier and security gates), re-scanned to prove them; optional read-only probe of a target you own. Triggers: "guardrails", "garde-fous", "RLS activée ?", "faille sql", "fuite navigateur", "plafond de dépense", "mots de passe en clair ?", "corrige les garde-fous", "sonde le projet en direct".' ``` `argument-hint`: `'[project path] [--domain api,hosting,supabase,messaging,functions,injection,exposure] [--exclude paths] [--live ] [--report-only]'`. @@ -1828,15 +2051,17 @@ description: 'Use when auditing a project against the baseline guardrails and fi source. A constant, an allowlisted identifier or a value already cast to a number is a FALSE POSITIVE; anything that can come from a request, a file or another user's row is CONFIRMED. - - **Exposure**: open the main page in a browser and read what the console, - the network responses and the DOM carry: a token in a `data-*` - attribute, a user object logged, a full row in an API answer. With - `--live`, the probe answers for served source maps, error bodies and - sensitive keys; the rest is read by hand. + - **Exposure**: read the code behind each EXP hit: is the logged object, + the hydrated key or the returned row really user data? With `--live` + against a production build (STEP 5), the probe answers for served + source maps, error bodies and sensitive keys; without it, say so. ``` -3. STEP 5.1: after `and a \`rate_limit\` route if the user wants that one burst.` add the sentence `Add an \`exposure\` block (\`{}\` for the defaults, \`error_routes\` for a route you own that answers an error to a malformed id, never a path you guess) so the probe reads source maps, error bodies and response keys.` -4. STEP 8 proposal examples: `the label text for a field.` → `the parameter binding for a query.`; `(label wording, CORS origins, owner column,\n rate-limit numbers)` → `(allowlisted filter fields, CORS origins, owner column,\n rate-limit numbers)`. -5. STEP 9 example: `("2 with the label 'Email'")` → `("2 with the fields ['id','status']")`. +3. STEP 5, paragraph 1: after `a staging or\nproduction URL only on an explicit, specific go.` add: `The \`exposure\` block runs against a production build or a staging URL (\`next build && next start\`, \`vite preview\`, framework debug off): a dev server serves source maps and tracebacks by design, so its exposure OPEN verdicts are dev artefacts, reported as such, with no proposal and no re-pass requirement.` +4. STEP 5.1: after `and a \`rate_limit\` route if the user wants that one burst.` add: `Add an \`exposure\` block (\`{}\` for the defaults, \`error_routes\` for a route you own that answers an error to a malformed id, never a path you guess) so the probe reads source maps, error bodies and response keys; every path in the plan starts with \`/\`.` +5. STEP 5.3: after `CLOSED means it was refused or empty.` add `SKIPPED and ERROR mean the target was not observed: never read either as proof of a fix.` +6. STEP 8: `A live OPEN verdict\nwith no static finding gets a proposal whose proof is the probe alone.` → `A live OPEN verdict\nwith no static finding gets a proposal whose proof is the probe alone,\nunless STEP 5 marked it a dev artefact.` +7. STEP 8 proposal examples: `the label text for a field.` → `the parameter binding for a query.`; `(label wording, CORS origins, owner column,\n rate-limit numbers)` → `(allowlisted filter fields, CORS origins, owner column,\n rate-limit numbers)`. +8. STEP 9 example: `("2 with the label 'Email'")` → `("2 with the fields ['id','status']")`. Every locked sentence from loops-light stays untouched and on one line. @@ -1847,12 +2072,16 @@ Every locked sentence from loops-light stays untouched and on one line. ```markdown ## injection + Patterns are per language: a Postgres `$1` placeholder, a tagged template + (`sql\`…\``, `sql\`…\``), an argv array and test or fixture paths are + silent by design. + | Rule | Sev | Catches | Fix | |---|---|---|---| - | INJ-SQL-RAW-UNSAFE | FAIL | `$queryRawUnsafe`, `$executeRawUnsafe`, `knex.raw`, `.raw()`, `.extra()`, `sequelize.query`, `Sequelize.literal`, SQLAlchemy `text()` fed a variable; ActiveRecord `where("… #{}")` | bind the values, or the tagged `$queryRaw` | - | INJ-SQL-CONCAT | FAIL | a SQL statement string built with `${}`, `+`, an f-string, `%`, `.format`, PHP `$var`, Ruby `#{}`, `format!`, `Sprintf` | placeholders and a parameter list | + | INJ-SQL-RAW-UNSAFE | FAIL | `$queryRawUnsafe`, `$executeRawUnsafe`, `knex.raw`, `sequelize.query`, `Sequelize.literal`, Django `.objects.raw()` / `.extra()`, SQLAlchemy `text()` fed a variable; ActiveRecord `where("… #{}")` | bind the values, or the tagged `$queryRaw` | + | INJ-SQL-CONCAT | FAIL | a SQL statement (select … from … where, insert into, update … set, delete … where, create/drop/alter) built with `${}`, `+`, an f-string, `%`, `.format`, PHP `$var`, Ruby `#{}`, `format!`, `Sprintf` | placeholders and a parameter list | | INJ-SQL-DYNAMIC-EXEC | WARN | plpgsql `EXECUTE '…' \|\| x` | `format('… %I %L', …)` and `USING` | - | INJ-POSTGREST-FILTER | WARN | supabase-js `.or()`, `.filter()`, `.not()`, `.match()`, `.textSearch()` with an interpolated string | `.eq()` and friends, validated values | + | INJ-POSTGREST-FILTER | WARN | supabase-js `.or()`, `.filter()`, `.not()`, `.match()`, `.textSearch()` with an interpolated string, in a file that uses supabase | `.eq()` and friends, validated values | | INJ-NOSQL-OPERATOR | WARN | Mongo `$where` with a string; a filter taken from `req.body`, `req.query` or `req.params` | allowlist the fields, cast to string, `sanitizeFilter` | | INJ-SHELL-DB-TOOL | FAIL | a shell call naming psql, mysql, mysqldump, pg_dump, mongosh, redis-cli, sqlite3… with an interpolated argument | an argv array, no shell, validated input | @@ -1860,15 +2089,15 @@ Every locked sentence from loops-light stays untouched and on one line. | Rule | Sev | Catches | Fix | |---|---|---|---| - | EXP-CONSOLE-DATA | WARN | `console.log/info/debug/dir/table` in client-reachable code with a data argument (user, session, response, token, body…) | strip console calls in the production build, log server-side | - | EXP-SOURCEMAP-PUBLIC | FAIL / WARN | `productionBrowserSourceMaps: true`, vite `sourcemap: true`, `GENERATE_SOURCEMAP=true`, webpack `devtool` readable maps (FAIL in `webpack.prod*`, WARN elsewhere), a `.map` under `public/`; angular `sourceMap: true` (WARN) | off, or `hidden` and upload to the error tracker | - | EXP-HYDRATED-SENSITIVE | WARN | a token, secret, key, password or ssn-like key returned by `getServerSideProps`, `getStaticProps`, a Remix `loader`, a SvelteKit `load` or set on `window.__STATE__` | return only the fields the page renders | + | EXP-CONSOLE-DATA | WARN | `console.log/info/debug/dir/table` in client-reachable code with a data argument (user, session, response, token, body…); string literals are ignored | strip console calls in the production build, log server-side | + | EXP-SOURCEMAP-PUBLIC | FAIL / WARN | `productionBrowserSourceMaps: true`, vite `sourcemap: true` or `'inline'`, `GENERATE_SOURCEMAP=true` in a committed non-dev env file, webpack `devtool` readable maps (FAIL in `webpack.prod*`, WARN elsewhere), a real `.map` under `public/` or `static/` (any size; vendored and `.min.` maps excluded); angular `sourceMap: true` (WARN) | off, or `hidden` and upload to the error tracker | + | EXP-HYDRATED-SENSITIVE | WARN | a token, secret, key, password or ssn-like key returned by `getServerSideProps`, `getStaticProps`, a Remix `loader`, a SvelteKit `load` or set on `window.__STATE__`; a TS type member is skipped | return only the fields the page renders | | EXP-MARKUP-COMMENT | WARN | `` shipped to the browser (html, astro, php, ejs, hbs, twig, njk, liquid) with todo, fixme, debug, password, token, internal, staging, admin… | delete it, or move it to a code comment the build strips | - | EXP-DATA-ATTR-SENSITIVE | WARN | `data-*` attribute or hidden input named secret, api-key, password, jwt, private, credential (csrf excluded) | keep it server-side, send an opaque id | - | EXP-ERROR-STACK | FAIL | `err.stack`, the error object, `traceback.format_exc()` or `getTraceAsString()` in a response | generic message out, full error in the server log | - | EXP-ERROR-MESSAGE | WARN | `err.message`, `str(e)`, `$e->getMessage()` sent as is | map to a safe message; validation errors are fine, DB errors are not | - | EXP-DEBUG-ON | FAIL | `DEBUG = True`, `APP_DEBUG=true`, `FLASK_DEBUG=1`, `app.debug = True`, `consider_all_requests_local = true`, `errorhandler()` | env-driven, false in production | - | EXP-RESPONSE-WIDE | WARN | a route returning `select *` / `select('*')` / `findUnique` without `select` or `omit` on a users-like table | an explicit field list | + | EXP-DATA-ATTR-SENSITIVE | WARN | `data-*` attribute or hidden input named secret, api-key, password, jwt, private, credential (csrf, xsrf, authenticity, nonce excluded) | keep it server-side, send an opaque id | + | EXP-ERROR-STACK | FAIL | in a route file: `err.stack`, the error object, `traceback.format_exc()` or `getTraceAsString()` in a response | generic message out, full error in the server log | + | EXP-ERROR-MESSAGE | WARN | in a route file: `err.message`, `str(e)`, `$e->getMessage()` sent as is | map to a safe message; validation errors are fine, DB errors are not | + | EXP-DEBUG-ON | FAIL | `DEBUG = True` in a settings module (not dev/local/test), `APP_DEBUG=true` / `FLASK_DEBUG=1` in a committed non-dev env file, `app.debug = True`, `consider_all_requests_local = true`, `errorhandler()` mounted without an environment guard | env-driven, false in production | + | EXP-RESPONSE-WIDE | WARN | a route returning `select *` / `select('*')` on a users-like table, or a single-line Prisma `findUnique/findFirst/findMany` without `select` or `omit` | an explicit field list | ``` 3. Blind spots list: replace `- keyboard traps, focus order, modal focus handling, color contrast` with ``` @@ -1879,16 +2108,18 @@ Every locked sentence from loops-light stays untouched and on one line. - built output (`dist/`, `.next/`) and runtime state such as `__NEXT_DATA__`: only the live probe sees a served map or a hydrated token + - a multi-line Prisma call or a value object spread into state: the + single-line rules stay silent - what the console or an XHR carries once the page runs: a browser walk ``` -4. "By design the scanner ignores" paragraph: remove `fields that are never rendered (\`hidden\`, \`display: none\`), click handlers that only stop propagation or sit on \`role="presentation"\`, focus styles that swap the outline for a border or shadow, ` and append `, tagged SQL templates, placeholders with a separate parameter list, an argv array handed to a DB tool, console calls in server code, \`sourcemap: 'hidden'\`, a debug flag read from the environment, and a hidden input named csrf, xsrf, authenticity or nonce` before the final period. -5. Live probe section: in the plan JSON example add, before the closing brace, `,\n "exposure": {"error_routes": ["/api/v1/notes/not-a-number"]}`; after the `Environment, from test keys only…` sentence add `The fields probe sends \`GUARDRAILS_JWT2\` as a bearer when it is set.`; add three rows to the probe table: +4. "By design the scanner ignores" paragraph: remove `fields that are never rendered (\`hidden\`, \`display: none\`), click handlers that only stop propagation or sit on \`role="presentation"\`, focus styles that swap the outline for a border or shadow, ` and append `, tagged SQL templates, placeholders with a separate parameter list, an argv array handed to a DB tool, console calls in server code, logging calls that carry a stack, \`sourcemap: 'hidden'\`, a debug flag read from the environment, dev, local and test env files and settings modules, minified files and built directories, and a hidden input or data attribute named csrf, xsrf, authenticity or nonce` before the final period. +5. Live probe section: in the plan JSON example add, before the closing brace, `,\n "exposure": {"error_routes": ["/api/v1/notes/not-a-number"]}`; after the `Environment, from test keys only…` sentence add `The fields probe sends \`GUARDRAILS_JWT2\` as a bearer when it is set. Every path in the plan starts with \`/\`: a path that could leave the named host is a usage error.`; add three rows to the probe table: ``` - | sourcemap | `sourcemap:' + b'' + b'' + b'' + b'') + if path == "/app.js": + return self._send(200, b"console.log(1);\n//# sourceMappingURL=app.js.map\n") + if path == "/app.js.map": + return self._send(200, b'{"version":3,"sources":["src/app.ts"],"mappings":""}') + if path == "/clean.js": + return self._send(200, b"console.log(2);\n") + if path == "/inline.js": + return self._send(200, b"console.log(3);\n//# sourceMappingURL=" + b"data:application/json;base64,eyJ2ZXJzaW9uIjozfQ==\n") + if path == "/boom": + return self._send(500, b"Traceback (most recent call last):\n" + b' File "app.py", line 12, in handler\n') + if path == "/api/me": + return self._send(200, b'{"id": 1, "email": "t@t.io", ' + b'"password_hash": "x", "profile": {"api_key": "y"}, ' + b'"next_page_token": "abc", "hashtags": []}', + {"Content-Type": "application/json"}) return self._send(404, b"") @@ -146,6 +169,72 @@ printf '{"base_url": "%s", "rate_limit": {"path": "/x", "method": "DELETE"}}\n' probe --authorized "$WORK/bad.json" >/dev/null 2>&1 check "a write method in the plan exits 2" "$?" 2 +echo "== exposure probes" +cat > "$WORK/exposure.json" < "$WORK/unreachable.json" < "$WORK/badexp.json" +probe --authorized "$WORK/badexp.json" >/dev/null 2>&1 +check "an error route not starting with / exits 2" "$?" 2 +printf '{"base_url": "%s", "exposure": []}\n' "$BASE" > "$WORK/badexp2.json" +probe --authorized "$WORK/badexp2.json" >/dev/null 2>&1 +check "a non-object exposure block exits 2" "$?" 2 +printf '{"base_url": "%s", "exposure": {"scripts": "/app.js"}}\n' "$BASE" > "$WORK/badexp3.json" +probe --authorized "$WORK/badexp3.json" >/dev/null 2>&1 +check "a scripts string instead of a list exits 2" "$?" 2 +printf '{"base_url": "%s", "routes": [{"path": ".evil.invalid/x"}]}\n' "$BASE" > "$WORK/badroute.json" +probe --authorized "$WORK/badroute.json" >/dev/null 2>&1 +check "a route path that could leave the host exits 2" "$?" 2 +printf '{"base_url": "%s", "routes": ["/x"]}\n' "$BASE" > "$WORK/badroute2.json" +probe --authorized "$WORK/badroute2.json" >/dev/null 2>&1 +check "a route that is not an object exits 2" "$?" 2 +printf '{"base_url": "%s", "exposure": true}\n' "$BASE" > "$WORK/badexp4.json" +probe --authorized "$WORK/badexp4.json" >/dev/null 2>&1 +check "a boolean exposure block exits 2 without a traceback" "$?" 2 +printf '{"base_url": "%s", "exposure": {"scripts": ["/does-not-exist.js"]}}\n' "$BASE" > "$WORK/stale.json" +OUT="$(probe --authorized "$WORK/stale.json")" +check "a listed script that answers 404 is SKIPPED, never CLOSED" \ + "$(verdict "$OUT" 'sourcemap:/does-not-exist.js')" SKIPPED +printf '{"base_url": "%s", "exposure": {"scripts": []}}\n' "$BASE" > "$WORK/noscript.json" +OUT="$(probe --authorized "$WORK/noscript.json")" +check "an empty scripts list still gives a SKIPPED sourcemap row" \ + "$(verdict "$OUT" 'sourcemap')" SKIPPED +cat > "$WORK/lower.json" <]+src=[\"']?([^\"'\s>]+)", re.I) +MAP_COMMENT = re.compile(r"//[#@]\s*sourceMappingURL=(\S+)") +TRACE_MARKERS = re.compile( + rb"Traceback \(most recent call last\)|\bat [\w.$<> ]+ \([^)\n]*:\d+:\d+\)" + rb"|File \"[^\"\n]+\", line \d+|SQLSTATE\[|syntax error at or near" + rb"|node_modules/|/var/www/|Stack trace:|#\d+ /[\w/.-]+\.php\(\d+\)") +SENSITIVE_KEY = re.compile( + r"(?:^|_)(?:password|passwd|pwd|salt|secret|api_?key|service_?role" + r"|private_?key|(?:access|refresh|id|auth|api|session)_token|jwt|ssn" + r"|iban|cvv|card_?number)(?:$|_)") +IDENT = re.compile(r"[A-Za-z_][\w-]{0,31}") # used with fullmatch @dataclass(frozen=True) class Response: status: int # None on a transport error - headers: dict + headers: object # http.client.HTTPMessage: .get() ignores case body: bytes error: str = "" @@ -71,8 +87,15 @@ class Session: self.budget = budget +def _error_body(exc): + try: + return exc.read(BODY_CAP) + except (OSError, ValueError, AttributeError): + return b"" + + def _response_from(resp): - return Response(resp.status, dict(resp.headers), resp.read(BODY_CAP)) + return Response(resp.status, resp.headers, resp.read(BODY_CAP)) def fetch(session, method, url, headers=None, body=None): @@ -85,7 +108,7 @@ def fetch(session, method, url, headers=None, body=None): with session.opener.open(req, timeout=session.timeout) as resp: return _response_from(resp) except urllib.error.HTTPError as exc: - return Response(exc.code, dict(exc.headers), b"") + return Response(exc.code, exc.headers, _error_body(exc)) except (urllib.error.URLError, OSError, ValueError) as exc: return Response(None, {}, b"", str(exc)) @@ -219,8 +242,169 @@ def probe_rate_limit(session, plan): return [_rate_verdict(target, codes)] +def _same_host(context, url): + """Absolute url when it stays on context's host, else None.""" + full = urljoin(context, url) + return full if urlsplit(full).netloc == urlsplit(context).netloc else None + + +def _page_scripts(session, base): + """(urls, note): same-host scripts of the base page, or why none.""" + page = fetch(session, "GET", base + "/") + if page.error: + return [], f"base page unreachable: {page.error}" + text = page.body.decode("utf-8", "ignore") + urls = [u for u in (_same_host(base + "/", s) + for s in SCRIPT_SRC.findall(text)) if u] + urls = list(dict.fromkeys(urls))[:SCRIPT_CAP] + return urls, "" if urls else "no same-host script on the base page" + + +def _map_candidates(script_url, resp): + urls = [script_url + ".map"] + header = resp.headers.get("sourcemap") or resp.headers.get("x-sourcemap") + if header: + urls.append(header) + tail = resp.body[-600:].decode("utf-8", "ignore") + comment = MAP_COMMENT.search(tail) + if comment: + urls.append(comment.group(1)) + return list(dict.fromkeys(urls)) + + +def _map_verdict(session, script_url, candidates): + """(verdict, target, note) over the candidate map urls, fail closed.""" + for url in candidates: + if url.startswith("data:"): + return "OPEN", script_url, "inline source map in the script" + target = _same_host(script_url, url) + if not target: + return "SKIPPED", url, "map url on another host, not fetched" + resp = fetch(session, "GET", target) + if resp.error or resp.status is None: + return "ERROR", target, resp.error or "no response" + if resp.status == 200 and b'"sources"' in resp.body: + return "OPEN", target, "source map served with its sources" + return "CLOSED", script_url, "no source map served for this script" + + +def _sourcemap_probe(session, script_url): + pid = f"sourcemap:{urlsplit(script_url).path}" + resp = fetch(session, "GET", script_url) + if resp.error: + return Probe("exposure", pid, "ERROR", script_url, resp.error) + if resp.status != 200: + return Probe("exposure", pid, "SKIPPED", script_url, + f"HTTP {resp.status}: script not served, map not read") + if len(resp.body) >= BODY_CAP: + return Probe("exposure", pid, "SKIPPED", script_url, + "script body truncated: its map comment was not read") + verdict, target, note = _map_verdict( + session, script_url, _map_candidates(script_url, resp)) + return Probe("exposure", pid, verdict, target, note) + + +def _sourcemaps(session, base, cfg): + listed = cfg.get("scripts") + if listed is None: + urls, note = _page_scripts(session, base) + else: + urls = [base + s for s in listed][:SCRIPT_CAP] + note = "" if urls else "no script listed in exposure.scripts" + if note: + return [Probe("exposure", "sourcemap", "SKIPPED", base, note)] + return [_sourcemap_probe(session, u) for u in urls] + + +def _error_probe(session, base, path): + target = base + path + resp = fetch(session, "GET", target) + return _verdict( + ("exposure", f"error-body:{path}", target), resp, + bool(TRACE_MARKERS.search(resp.body)), + ("error body carries a stack trace or an internal path", + "error body carries no trace marker")) + + +def _error_paths(cfg): + random_path = "/guardrails-probe-" + os.urandom(6).hex() + return [random_path] + list(cfg.get("error_routes") or []) + + +def _keys(data, depth=0): + if depth > 4: + return [] + if isinstance(data, dict): + found = [k for k in data if isinstance(k, str)] + for value in data.values(): + found += _keys(value, depth + 1) + return found + if isinstance(data, list): + found = [] + for value in data[:5]: + found += _keys(value, depth + 1) + return found + return [] + + +def _snake(key): + return re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", key).replace("-", "_").lower() + + +def _sensitive_keys(data): + return sorted({k for k in _keys(data) if SENSITIVE_KEY.search(_snake(k))}) + + +def _key_note(keys): + """Identifier-shaped key names only; anything else is counted.""" + shown = [k for k in keys if IDENT.fullmatch(k)] + hidden = len(keys) - len(shown) + return ", ".join(shown) + (f" (+{hidden} unprintable)" if hidden else "") + + +def _json_body(resp): + try: + return json.loads(resp.body), True + except ValueError: + return None, False + + +def _fields_verdict(resp): + if resp.error: + return "ERROR", resp.error + data, is_json = _json_body(resp) + if resp.status != 200 or not is_json: + return "SKIPPED", f"HTTP {resp.status}: no JSON body to read" + keys = _sensitive_keys(data) + if keys: + return "OPEN", "response carries sensitive keys: " + _key_note(keys) + return "CLOSED", "no sensitive key in the response" + + +def _bearer(): + token = os.environ.get("GUARDRAILS_JWT2") + return {"Authorization": f"Bearer {token}"} if token else None + + +def _fields_probe(session, base, route): + target = base + route["path"] + verdict, note = _fields_verdict(fetch(session, "GET", target, _bearer())) + return Probe("exposure", f"fields:{route['path']}", verdict, target, note) + + +def probe_exposure(session, plan): + cfg = plan.get("exposure") + if cfg is None: + return [] + base = plan["base_url"].rstrip("/") + out = _sourcemaps(session, base, cfg) + out += [_error_probe(session, base, p) for p in _error_paths(cfg)] + out += [_fields_probe(session, base, r) for r in plan.get("routes", [])] + return out + + PROBES = (probe_supabase, probe_cross_user, probe_routes, - probe_cors, probe_rate_limit) + probe_cors, probe_exposure, probe_rate_limit) def run_probes(session, plan): @@ -271,11 +455,44 @@ def _load_plan(path): return plan, "" +def _obj(plan, key): + value = plan.get(key) + return value if isinstance(value, dict) else {} + + +def _plan_paths(plan): + """Every path the probe would append to base_url (None when malformed).""" + routes = plan.get("routes") or [] + cfg, supa, rate = _obj(plan, "exposure"), _obj(plan, "supabase"), \ + _obj(plan, "rate_limit") + return ([r.get("path") if isinstance(r, dict) else None for r in routes] + + list(supa.get("cross_user_paths") or []) + + [plan.get("cors_path", "/"), rate.get("path", "/")] + + list(cfg.get("scripts") or []) + + list(cfg.get("error_routes") or [])) + + +def _exposure_error(cfg): + if cfg is None: + return "" + if not isinstance(cfg, dict): + return "exposure must be an object" + for key in ("scripts", "error_routes"): + if cfg.get(key) is not None and not isinstance(cfg[key], list): + return f"exposure.{key} must be a list" + return "" + + def _plan_error(plan): method = plan.get("rate_limit", {}).get("method", "GET").upper() if method not in READ_METHODS and method != "POST": return f"rate_limit method {method} is not a probe method" - return "" + error = _exposure_error(plan.get("exposure")) + if error: + return error + bad = [p for p in _plan_paths(plan) + if not isinstance(p, str) or not p.startswith("/")] + return f"plan path {bad[0]!r} must start with /" if bad else "" def parse_args(argv): From 811077da2b86c579fbc9928e0f93cd998f8ed856 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 19 Oct 2026 00:45:25 +0200 Subject: [PATCH 10/24] fix(guardrails): probe reads inline maps anywhere in the body, SKIPPED on an oversize map, validation never raises, bounded trace marker, .map guess from the path --- lib/tests/guardrails-probe.test.sh | 16 +++++++++++++++ skills/guardrails/scripts/probe.py | 32 ++++++++++++++++++++++-------- 2 files changed, 40 insertions(+), 8 deletions(-) diff --git a/lib/tests/guardrails-probe.test.sh b/lib/tests/guardrails-probe.test.sh index a4f988a..0b0587c 100644 --- a/lib/tests/guardrails-probe.test.sh +++ b/lib/tests/guardrails-probe.test.sh @@ -62,6 +62,7 @@ class H(BaseHTTPRequestHandler): return self._send(200, b'' b'' b'' + b'' b'' b'') if path == "/app.js": @@ -73,6 +74,9 @@ class H(BaseHTTPRequestHandler): if path == "/inline.js": return self._send(200, b"console.log(3);\n//# sourceMappingURL=" b"data:application/json;base64,eyJ2ZXJzaW9uIjozfQ==\n") + if path == "/biginline.js": + return self._send(200, b"console.log(4);\n//# sourceMappingURL=" + b"data:application/json;base64," + b"A" * 20000) if path == "/boom": return self._send(500, b"Traceback (most recent call last):\n" b' File "app.py", line 12, in handler\n') @@ -180,6 +184,8 @@ check "a served source map is OPEN" \ "$(verdict "$OUT" 'sourcemap:/app.js')" OPEN check "an inline data: source map is OPEN" \ "$(verdict "$OUT" 'sourcemap:/inline.js')" OPEN +check "a large inline source map is OPEN" \ + "$(verdict "$OUT" 'sourcemap:/biginline.js')" OPEN check "a script with no map is CLOSED" \ "$(verdict "$OUT" 'sourcemap:/clean.js')" CLOSED check "a foreign-host script is never probed" \ @@ -228,6 +234,16 @@ printf '{"base_url": "%s", "exposure": {"scripts": []}}\n' "$BASE" > "$WORK/nosc OUT="$(probe --authorized "$WORK/noscript.json")" check "an empty scripts list still gives a SKIPPED sourcemap row" \ "$(verdict "$OUT" 'sourcemap')" SKIPPED +printf '{"base_url": "%s", "rate_limit": null}\n' "$BASE" > "$WORK/badrl.json" +probe --authorized "$WORK/badrl.json" >/dev/null 2>&1 +check "a null rate_limit exits 2" "$?" 2 +printf '{"base_url": "%s", "routes": 5}\n' "$BASE" > "$WORK/badroutes.json" +probe --authorized "$WORK/badroutes.json" >/dev/null 2>&1 +check "a non-list routes exits 2" "$?" 2 +printf '{"base_url": "%s", "supabase": {"url": "%s", "cross_user_paths": "/x"}}\n' \ + "$BASE" "$BASE" > "$WORK/badcu.json" +probe --authorized "$WORK/badcu.json" >/dev/null 2>&1 +check "a string cross_user_paths exits 2" "$?" 2 cat > "$WORK/lower.json" <]+src=[\"']?([^\"'\s>]+)", re.I) MAP_COMMENT = re.compile(r"//[#@]\s*sourceMappingURL=(\S+)") TRACE_MARKERS = re.compile( - rb"Traceback \(most recent call last\)|\bat [\w.$<> ]+ \([^)\n]*:\d+:\d+\)" + rb"Traceback \(most recent call last\)" + rb"|\bat [\w.$<> ]{1,80} \([^)\n]*:\d+:\d+\)" rb"|File \"[^\"\n]+\", line \d+|SQLSTATE\[|syntax error at or near" rb"|node_modules/|/var/www/|Stack trace:|#\d+ /[\w/.-]+\.php\(\d+\)") SENSITIVE_KEY = re.compile( @@ -190,7 +191,7 @@ def _route_probe(session, base, route): def probe_routes(session, plan): base = plan["base_url"].rstrip("/") - routes = [r for r in plan.get("routes", []) if not r.get("public")] + routes = [r for r in plan.get("routes") or [] if not r.get("public")] return [_route_probe(session, base, r) for r in routes] @@ -261,12 +262,12 @@ def _page_scripts(session, base): def _map_candidates(script_url, resp): - urls = [script_url + ".map"] + bare = urlsplit(script_url)._replace(query="", fragment="").geturl() + urls = [bare + ".map"] header = resp.headers.get("sourcemap") or resp.headers.get("x-sourcemap") if header: urls.append(header) - tail = resp.body[-600:].decode("utf-8", "ignore") - comment = MAP_COMMENT.search(tail) + comment = MAP_COMMENT.search(resp.body.decode("utf-8", "ignore")) if comment: urls.append(comment.group(1)) return list(dict.fromkeys(urls)) @@ -283,6 +284,9 @@ def _map_verdict(session, script_url, candidates): resp = fetch(session, "GET", target) if resp.error or resp.status is None: return "ERROR", target, resp.error or "no response" + if resp.status == 200 and len(resp.body) >= BODY_CAP: + return ("SKIPPED", target, "map answered 200 but its body is " + "over 1 MB: sources not confirmed, fetch it by hand") if resp.status == 200 and b'"sources"' in resp.body: return "OPEN", target, "source map served with its sources" return "CLOSED", script_url, "no source map served for this script" @@ -399,7 +403,7 @@ def probe_exposure(session, plan): base = plan["base_url"].rstrip("/") out = _sourcemaps(session, base, cfg) out += [_error_probe(session, base, p) for p in _error_paths(cfg)] - out += [_fields_probe(session, base, r) for r in plan.get("routes", [])] + out += [_fields_probe(session, base, r) for r in plan.get("routes") or []] return out @@ -483,11 +487,23 @@ def _exposure_error(cfg): return "" +def _shape_error(plan): + if "rate_limit" in plan and not isinstance(plan["rate_limit"], dict): + return "rate_limit must be an object" + if plan.get("routes") is not None and \ + not isinstance(plan["routes"], list): + return "routes must be a list" + paths = _obj(plan, "supabase").get("cross_user_paths") + if paths is not None and not isinstance(paths, list): + return "supabase.cross_user_paths must be a list" + return "" + + def _plan_error(plan): - method = plan.get("rate_limit", {}).get("method", "GET").upper() + method = str(_obj(plan, "rate_limit").get("method", "GET")).upper() if method not in READ_METHODS and method != "POST": return f"rate_limit method {method} is not a probe method" - error = _exposure_error(plan.get("exposure")) + error = _exposure_error(plan.get("exposure")) or _shape_error(plan) if error: return error bad = [p for p in _plan_paths(plan) From 45e3454b9914201f6c012af980ba6b78bd14a440 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 19 Oct 2026 00:47:59 +0200 Subject: [PATCH 11/24] chore(model-router): a11y skill row (reflect) --- mods/model-router/routing.json | 1 + 1 file changed, 1 insertion(+) diff --git a/mods/model-router/routing.json b/mods/model-router/routing.json index aade9a9..ebb8393 100644 --- a/mods/model-router/routing.json +++ b/mods/model-router/routing.json @@ -75,6 +75,7 @@ "refactor": "reflect", "explain-diff": "reflect", "guardrails": "reflect", + "a11y": "reflect", "web-validate": "reflect", "harden": "reflect", "seo": "reflect", From 60d447e544f8a720a45f3412bf33f801e3d88734 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 19 Oct 2026 00:48:09 +0200 Subject: [PATCH 12/24] feat(a11y): skill (scan, keyboard walk, report, fix loop on the bugfix circuit), lazy rules/a11y.md, profiles, locks --- agents/bugfixer.md | 2 +- lib/contract-interview.md | 2 +- lib/profiles/audit.profile | 1 + lib/profiles/dev.profile | 1 + lib/profiles/full.profile | 1 + lib/profiles/max.profile | 1 + lib/profiles/web-full.profile | 1 + lib/profiles/web.profile | 1 + lib/tests/loops-light.test.sh | 10 ++ lib/tests/model-routing.test.sh | 4 +- lib/verify-secure-loop.md | 2 +- rules/a11y.md | 10 ++ rules/web-building.md | 4 +- skills/a11y/SKILL.md | 200 +++++++++++++++++++++++++++++++ skills/a11y/references/checks.md | 44 +++++++ skills/a11y/test-prompts.json | 7 ++ 16 files changed, 284 insertions(+), 7 deletions(-) create mode 100644 rules/a11y.md create mode 100644 skills/a11y/SKILL.md create mode 100644 skills/a11y/references/checks.md create mode 100644 skills/a11y/test-prompts.json diff --git a/agents/bugfixer.md b/agents/bugfixer.md index bcbc8f8..412725c 100644 --- a/agents/bugfixer.md +++ b/agents/bugfixer.md @@ -1,6 +1,6 @@ --- name: bugfixer -description: Bug-fix EXECUTOR — dispatched by /bugfix (or /guardrails for accepted fixes) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite, reports. No investigation, no questions, no commit. +description: Bug-fix EXECUTOR — dispatched by /bugfix (or /guardrails and /a11y for accepted fixes) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite, reports. No investigation, no questions, no commit. tools: Read, Edit, Write, Bash, Grep, Glob model: sonnet effort: medium diff --git a/lib/contract-interview.md b/lib/contract-interview.md index 870cd11..1c453a6 100644 --- a/lib/contract-interview.md +++ b/lib/contract-interview.md @@ -114,7 +114,7 @@ Template: ```markdown # CONTRACT — -- date: | flow: | branch: +- date: | flow: | branch: - status: active ## REQUEST (verbatim — IMMUTABLE) diff --git a/lib/profiles/audit.profile b/lib/profiles/audit.profile index 7e15b9f..61d8602 100644 --- a/lib/profiles/audit.profile +++ b/lib/profiles/audit.profile @@ -6,6 +6,7 @@ cso harden personal guardrails personal +a11y personal analyze personal # SEO / GEO / web standards diff --git a/lib/profiles/dev.profile b/lib/profiles/dev.profile index cc07f11..300b4e0 100644 --- a/lib/profiles/dev.profile +++ b/lib/profiles/dev.profile @@ -19,6 +19,7 @@ code-clean personal commit-change personal explain-diff personal guardrails personal +a11y personal # Dev-lifecycle skills (agent-skills trio) observability-and-instrumentation external diff --git a/lib/profiles/full.profile b/lib/profiles/full.profile index 55d18cc..b792eef 100644 --- a/lib/profiles/full.profile +++ b/lib/profiles/full.profile @@ -46,6 +46,7 @@ geo personal web-validate personal harden personal guardrails personal +a11y personal analyze personal cso diff --git a/lib/profiles/max.profile b/lib/profiles/max.profile index 5060c45..2792c78 100644 --- a/lib/profiles/max.profile +++ b/lib/profiles/max.profile @@ -47,6 +47,7 @@ geo personal web-validate personal harden personal guardrails personal +a11y personal analyze personal cso diff --git a/lib/profiles/web-full.profile b/lib/profiles/web-full.profile index 9376f75..1c49fcf 100644 --- a/lib/profiles/web-full.profile +++ b/lib/profiles/web-full.profile @@ -34,6 +34,7 @@ geo personal web-validate personal harden personal guardrails personal +a11y personal analyze personal # === Perf + canary =================================================== diff --git a/lib/profiles/web.profile b/lib/profiles/web.profile index ee53a99..7d32538 100644 --- a/lib/profiles/web.profile +++ b/lib/profiles/web.profile @@ -28,6 +28,7 @@ refactor personal # Validation companion (basic W3C/a11y check during build) web-validate personal +a11y personal # External: design skills emil-design-eng external diff --git a/lib/tests/loops-light.test.sh b/lib/tests/loops-light.test.sh index 6d8ecb9..9d546de 100644 --- a/lib/tests/loops-light.test.sh +++ b/lib/tests/loops-light.test.sh @@ -15,6 +15,7 @@ BSK="$REPO/skills/bugfix/SKILL.md" HOT="$REPO/agents/hotfixer.md" HSK="$REPO/skills/hotfix/SKILL.md" GSK="$REPO/skills/guardrails/SKILL.md" +ASK="$REPO/skills/a11y/SKILL.md" HSKL="$REPO/skills/hotfix/SKILL.md" PASS=0; FAIL=0 @@ -79,6 +80,15 @@ tf "guardrails positive control" "$GSK" "Positive control" tf "guardrails approval gate" "$GSK" "Nothing is applied without the user's explicit acceptance" tf "guardrails re-pass baseline" "$GSK" "GUARDRAILS-NO-NEW" +echo "── skills/a11y/SKILL.md (fix loop reuses the bugfix circuit) ──" +tf "a11y contract include" "$ASK" "lib/contract-interview.md" +tf "a11y uses shared include" "$ASK" "lib/verify-secure-loop.md" +tf "a11y dispatches bugfixer" "$ASK" 'subagent_type="bugfixer"' +tf "a11y scanner is the oracle" "$ASK" "EXPECT: A11Y-CLEAR" +tf "a11y positive control" "$ASK" "Positive control" +tf "a11y approval gate" "$ASK" "Nothing is applied without the user's explicit acceptance" +tf "a11y re-pass baseline" "$ASK" "A11Y-NO-NEW" + echo "── agents/bugfixer.md (bugfix executor — sonnet, no Agent) ──" tn "bugfixer lacks Agent tool" "$BUG" "Agent" tf "bugfixer model sonnet" "$BUG" "model: sonnet" diff --git a/lib/tests/model-routing.test.sh b/lib/tests/model-routing.test.sh index f24f890..5352078 100755 --- a/lib/tests/model-routing.test.sh +++ b/lib/tests/model-routing.test.sh @@ -9,8 +9,8 @@ has() { if grep -qF "$2" "$R/$1"; then ok; else ko "$1 missing: $2"; fi; } lacks() { if grep -qF "$2" "$R/$1"; then ko "$1 must NOT contain: $2"; else ok; fi; } fm_lacks() { if awk 'NR<=10' "$R/$1" | grep -qF "$2"; then ko "$1 frontmatter must NOT contain: $2"; else ok; fi; } -# 1) gate wired in the 16 reflection skills (orchestrators, /analyze, /guardrails) -for s in ship-feature init-project feat bugfix onboard seo geo web-validate harden audit-delta tour code-clean hotfix client-handover analyze guardrails; do +# 1) gate wired in the 17 reflection skills (orchestrators, /analyze, /guardrails, /a11y) +for s in ship-feature init-project feat bugfix onboard seo geo web-validate harden audit-delta tour code-clean hotfix client-handover analyze guardrails a11y; do has "skills/$s/SKILL.md" 'lib/model-gate.md' done # 2) gate NOT wired in the pure-execution/read-only skills (exclusion list) diff --git a/lib/verify-secure-loop.md b/lib/verify-secure-loop.md index f75721f..8af5f2d 100644 --- a/lib/verify-secure-loop.md +++ b/lib/verify-secure-loop.md @@ -1,4 +1,4 @@ -# Verify + secure loop — shared orchestrator include (feat, bugfix, guardrails) +# Verify + secure loop — shared orchestrator include (feat, bugfix, guardrails, a11y) Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes. Turns a finished diff into a verified, security-cleared change through two fresh diff --git a/rules/a11y.md b/rules/a11y.md new file mode 100644 index 0000000..0dec6ab --- /dev/null +++ b/rules/a11y.md @@ -0,0 +1,10 @@ +--- +paths: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.html", "**/*.css", "**/*.scss"] +--- + +# Accessibility baseline (audit and fix: `/a11y`) + +- Everything reachable and usable by keyboard, focus always visible. + `:focus-visible` styled, never `outline: none` without a replacement. +- Every image has an `alt` (empty when decorative). Every field has a label; + a placeholder is not a label. diff --git a/rules/web-building.md b/rules/web-building.md index 61fbc0e..809a0b4 100644 --- a/rules/web-building.md +++ b/rules/web-building.md @@ -27,7 +27,7 @@ paths: ["**/*.html", "**/*.astro", "**/*.css", "**/*.scss", "**/*.tsx", "**/*.js - Motion: transform and opacity only; feedback under 200 ms, ease-out on entrances, never from scale(0); `will-change` only during an active animation; pause loops off-screen; honor `prefers-reduced-motion`. -- Touch targets 44 px minimum; visible `:focus-visible` ring; status never +- Touch targets 44 px minimum; keyboard and focus per `rules/a11y.md`; status never by color alone, add text or an icon. - Errors next to the field; empty state = one clear action; destructive action confirmed first. @@ -36,7 +36,7 @@ paths: ["**/*.html", "**/*.astro", "**/*.css", "**/*.scss", "**/*.tsx", "**/*.js ## Before declaring a public site done Check: custom 404 · call to action in the first viewport · per-page title + description · share/OG image · favicons · robots.txt · sitemap · -alt text on images · layout tested at 375 px · loading states · form +accessibility baseline (`rules/a11y.md`) · layout tested at 375 px · loading states · form error messages · confirmation page · real legal mentions · cookie banner with a working refuse option · audience measurement · contact address · compressed images. diff --git a/skills/a11y/SKILL.md b/skills/a11y/SKILL.md new file mode 100644 index 0000000..760dcb5 --- /dev/null +++ b/skills/a11y/SKILL.md @@ -0,0 +1,200 @@ +--- +name: a11y +effort: high +description: 'Use when a web project needs its accessibility baseline checked and fixed: everything reachable by keyboard with a visible focus, an alt on every image, a label on every field. Full WCAG conformance (axe, pa11y, W3C) → /web-validate; security guardrails → /guardrails. Deterministic scanner (A11Y-* rules: img alt, field label, click without keyboard, focus outline removed, positive tabindex), judgment, a Tab-only walk of the main flow on --live (through /browse, else marked not done), report .claude/audits/A11Y.md, then fixes proposed with the alt and label wording as visible choices, applied only on acceptance (bugfixer executor, fresh verifier and security gates, the scanner as oracle) and re-scanned to prove each one. Triggers: "a11y", "accessibilité", "accessibility basics", "clavier", "focus visible", "alt manquant", "label sur les champs", "tab order", "corrige l''accessibilité".' +argument-hint: '[project path] [--exclude paths] [--live ] [--report-only]' +--- + +# /a11y + +Checks a project's accessibility baseline (`rules/a11y.md`), then fixes what +the user accepts and proves each fix. A scanner reads the tree as data and +finds what text can prove: a missing alt, an unlabeled field, a click with no +keyboard path, a focus outline removed, a positive tabindex. This skill judges +the hits, walks the main flow with the keyboard when a browser is available, +proposes fixes, applies the accepted ones and scans again until every accepted +fix is proven. + +The scanner proves absence of a baseline, never presence of accessibility. A +clean scan means "no static finding", and the report says exactly that. Full +WCAG conformance (contrast, structure, ARIA semantics, axe or pa11y runs) is +`/web-validate`'s job. + +## MODEL GATE (blocking, before any other step) + +Run `$HOME/.claude/lib/model-gate.md`. Judging hits and writing alt and label +text requires Fable or Opus. Verdict `small` → STOP: the gate prints the +remedy. ROUTING: follow `$HOME/.claude/lib/effort-shift.md` (phases via +`mcp__model-router__route`); each step below names its phase. + +## STEP 1: Scope + +Work in the project the user names, else the current directory. Say in one +line what you will scan. `--report-only` stops after STEP 5: audit, no fix. + +## STEP 2: Run the scanner + +``` +python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" +``` + +Add `--exclude a/b,c` to skip copies or vendored code, `--json` for machine +output. Exit 0 means no FAIL, 1 means at least one, 2 is a usage error. It +never executes project code. Severities: **FAIL**, the baseline is provably +missing; **WARN**, a pattern that is often wrong, judgment needed. + +## STEP 3: Judge every FAIL and WARN + +Read the file around each line. Label it CONFIRMED, FALSE POSITIVE (say why) +or ACCEPTED RISK (the user decides, never you). A decorative image with +`alt=""`, a field labeled through `aria-labelledby`, a click handler on a +`role="presentation"` overlay and an outline swapped for a visible border or +ring are the usual false positives; `references/checks.md` lists the blind +spots. Check them before calling a hit false. + +## STEP 4: Keyboard walk (on `--live`, read-only) + +With a dev server the user names, walk the main flow with Tab only through +`/browse`: every control reached in a sensible order, the focus visible at +each stop, Enter and Space working on what looks clickable, Escape closing +what opened. Record each stop that fails with the page and the element. +Without a browser tool, or without `--live`, the report marks the walk +"not done": a static scan cannot see a keyboard trap, a focus order or a +modal that loses focus. + +## STEP 5: Report + +Write `.claude/audits/A11Y.md`: one table with status PASS, FAIL, WARN or +N/A per rule, the evidence, the fix in one line, and the keyboard walk's +result (done, with its stops, or not done). PASS means "no static finding". +Keep it short; no filler sections. `--report-only`, or nothing CONFIRMED: +reply with counts, the FAILs with file:line and the walk's stops, then stop. + +## STEP 6: Propose fixes + +`mcp__model-router__route(phase="plan")`: wording is the deepest thinking in +this run, it goes to the plan row. + +One proposal per CONFIRMED finding, grouped by rule and file; merge pairs +that one change closes (one `:focus-visible` rule closes every outline +removal in a stylesheet). FALSE POSITIVE and ACCEPTED RISK get no proposal. +Each proposal: + +- **number, rule, file(s)**, and the problem in one line; +- **the fix**, concrete: file:line and the change. A missing alt gets a + description of what the image shows, or `alt=""` when it is decorative; an + unlabeled field gets a `label for`, a wrapping label or `aria-label`; a + clickable `div` becomes a `button`, or gains `role`, `tabindex` and a key + handler; a removed outline gets a `:focus-visible` style; +- **choices the user sees**: the alt text and the label wording, each with + your proposed value, named so the user can change it. These are content, + never invented silently: they ship only with the user's acceptance; +- **risk**: what it can break (`button` reset styles, a changed tab order). + `DECISION` when no wording is defensible (an image you cannot describe); +- **proof**: the scanner pairs that must disappear (`RULE:path`), and the + walk stop that must pass when `--live` ran. + +Save the proposals to `.claude/tasks/plans/-a11y-.md` and +append them to the report. In the reply, show them as a numbered list, one or +two lines each, DECISION marked. + +## STEP 7: Approval (gate, ends the turn) + +Nothing is applied without the user's explicit acceptance. Ask once, then +stop the turn: + +``` +Which fixes do I apply? "all" (every proposal except DECISION ones), +numbers ("1,3,5-7"), "none", or an amendment ("2 with the alt 'Team photo'"). +A DECISION proposal needs its number plus your wording. +``` + +On resume, `mcp__model-router__route(phase="reflect")`. "none" → stop, +proposals stay in the report. An amendment rewrites that proposal in the plan +file before anything else. Accepted set empty → stop. + +## STEP 8: Apply + +1. **Branch.** Not a git repository → stop: fixes need a diff to review. + On `main`/`develop`, `bash ~/.claude/lib/gitflow.sh start bugfix + a11y-`; on a working branch, stay. Never `finish`. +2. **Baseline**, before any edit: + `python3 -B --json > .claude/audits/.a11y-baseline.json`. + A derived file: never staged, never committed. +3. **Contract** per `$HOME/.claude/lib/contract-interview.md` (STEP 4 + template, `flow: a11y`). REQUEST = the user's acceptance verbatim plus the + accepted proposals. One criterion per accepted proposal, its oracle the + scanner itself: + ``` + 1. + CHECK: python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" '' --assert-absent 'RULE:path,RULE:path' + EXPECT: A11Y-CLEAR + EVIDENCE: pending + ``` + Add one criterion for the project suite when one exists + (`CHECK: && echo TESTS-GREEN`, `EXPECT: TESTS-GREEN`). The + keyboard walk is a criterion without CHECK: STEP 9 settles it. FILE SCOPE + = the files the accepted proposals name. Paths go in single quotes; a path + holding a single quote is named to the user, never written into a CHECK. +4. **Positive control.** Run each oracle once on the unfixed tree: it must + fail. An oracle that passes before the fix proves nothing; drop it, find + why, and say so. +5. **Dispatch the executor**, one fresh `bugfixer` for the accepted set + (batches of 8 proposals at most, one after the other on the same branch): + ``` + mcp__model-router__route(phase="orchestrate") # send with the Agent call + Agent(subagent_type="bugfixer") + prompt: "CONTRACT: + DIAGNOSIS: + FIX PLAN: + BRANCH: + Apply to the letter. No commit, no branch ops, no security dispatch. + Finish with the BUGFIX-EXEC REPORT." + ``` + `NEED-DECISION` routes per MID-RUN CLARIFICATION of the contract include: + a wording, visible or scope question goes to the user verbatim. + `BLOCKED` → surface it, stop. +6. **Gates** per `$HOME/.claude/lib/verify-secure-loop.md`, `CONTRACT` the + path above, `DIFF` the executor's working-tree diff, `TEST` the suite. + GATE 0 runs every scanner oracle (the per-fix proof), GATE 1 a fresh + verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are + the include's; loop decisions stay in this main loop. + +## STEP 9: Re-pass (prove it all) + +`mcp__model-router__route(phase="reflect")`. The gates proved each accepted +fix on its own; this pass proves the whole tree. + +1. Full scan against the baseline: + ``` + python3 -B --baseline .claude/audits/.a11y-baseline.json + ``` + Every accepted pair must show `FIXED`, and the run must end on + `A11Y-NO-NEW` (exit 0). A `NEW` hit is a regression the fix made. +2. Live: when STEP 4 ran, walk the same flow again once the user has reloaded + the dev server and says go. Each stop a proposal named must now pass. +3. Add an "after" column to `.claude/audits/A11Y.md`: proposal, before, + after, evidence. + +Anything not fixed, or a NEW hit → one more round from STEP 6, limited to +those items. Two rounds at most: after the second, stop with the residuals +open and say so plainly. Never report a fix the re-pass did not prove. + +## STEP 10: Commit and hand over + +1. **Commit gate.** Show files, `git diff --stat` and the message, wait for + the user's go: + ``` + A11Y: READY TO COMMIT + FILES : + MESSAGE : fix(a11y): + ``` + Then `git add ` (never `-A`, never the baseline file) and + commit, project convention else 50 words at most. +2. `mcp__model-router__route(phase="apply")` for the tail. Reply with: fixed + and proven (proposal, rule, file), still open and why, the walk's result, + the branch name. Merge waits for the user's explicit signal. +3. Offer to capitalize a reusable lesson (a false-positive class, a fix + pattern), entry pre-filled, written only on approval. diff --git a/skills/a11y/references/checks.md b/skills/a11y/references/checks.md new file mode 100644 index 0000000..7fd83c4 --- /dev/null +++ b/skills/a11y/references/checks.md @@ -0,0 +1,44 @@ +# Accessibility checks + +Rule ids the scanner emits, what each proves, and the fix. Severity is the +default; a judged hit can be a false positive. + +| Rule | Sev | Catches | Fix | +|---|---|---|---| +| A11Y-IMG-ALT | FAIL | `img` or `Image` without `alt` | describe it, or `alt=""` if decorative | +| A11Y-FIELD-LABEL | FAIL | native input, select, textarea with no label | `label for`, wrapping label or `aria-label` | +| A11Y-CLICK-NO-KEYBOARD | FAIL | click handler on a div or span lacking role, tabindex or key handler | use a `button` | +| A11Y-FOCUS-OUTLINE | FAIL / WARN | focus outline removed; WARN when a `:focus-visible` style exists elsewhere | style `:focus-visible` instead | +| A11Y-TABINDEX-POSITIVE | WARN | `tabindex` above 0 | use 0 or -1 and fix the DOM order | + +## Blind spots + +The scanner is regex over markup and styles. It cannot see: + +- keyboard traps, focus order, a modal that keeps or loses focus, color + contrast: the `--live` walk covers the first three, `/web-validate` the + fourth +- a label wired through `aria-labelledby` to an element in another file +- components whose markup is built at runtime, minified bundles, anything + over 1 MB +- `.astro` files for the click rule (never flagged) + +By design the scanner ignores: fields that are never rendered (`hidden`, +`display: none`), click handlers that only stop propagation or sit on +`role="presentation"`, focus styles that swap the outline for a border or +shadow, and `img` tags inside comments. + +## Fix loop: oracles and re-pass + +Every accepted fix is proven by the scanner itself, never by the executor's +word. Two check modes replace the report and its exit code: + +| Mode | Passes when | Marker | Used by | +|---|---|---|---| +| `--assert-absent RULE:path,...` | none of these FAIL/WARN pairs remains, the domain was scanned, the tree is not empty | `A11Y-CLEAR ` | a contract `CHECK:` run by `lib/gates.sh` (GATE 0) | +| `--baseline before.json` | no FAIL/WARN hit appeared since the earlier `--json` run | `A11Y-NO-NEW` | STEP 9 re-pass | + +Pairs match on rule and file, not line: a fix moves lines. An empty tree +fails the assertion, because absence there proves nothing. Run every oracle +once before the fix: it must fail. The baseline lists `FIXED` and `NEW` +pairs with their hit counts; a `NEW` hit after a fix is a regression. diff --git a/skills/a11y/test-prompts.json b/skills/a11y/test-prompts.json new file mode 100644 index 0000000..ccc5f1d --- /dev/null +++ b/skills/a11y/test-prompts.json @@ -0,0 +1,7 @@ +[ + {"id": 1, "prompt": "vérifie l'accessibilité de base de ~/Documents/faunosteo : clavier, alt, labels", "expected": "Runs the a11y scanner on the path, reads each A11Y FAIL and WARN in context, marks the keyboard walk not done (no --live), writes .claude/audits/A11Y.md, proposes fixes with alt and label wording as visible choices, stops for approval"}, + {"id": 2, "prompt": "il manque des alt sur les images du site, corrige", "expected": "Scans, confirms each A11Y-IMG-ALT hit, proposes one alt text per image (or alt=\"\" for decorative ones) as a named choice, applies only after acceptance on a bugfix branch with --assert-absent oracles, re-scans against the baseline"}, + {"id": 3, "prompt": "Walk my app at http://localhost:3000 with the keyboard only and tell me where focus gets lost", "expected": "Static scan first, then the Tab walk through /browse on the named localhost target, records each stop with no visible focus or unreachable control, reports them next to the static findings, fixes nothing without approval"}, + {"id": 4, "prompt": "est-ce que mon site passe les critères WCAG AA ?", "expected": "Routes to /web-validate for WCAG conformance; runs /a11y only if the user asks for the keyboard/alt/label baseline"}, + {"id": 5, "prompt": "a11y --report-only sur ce projet", "expected": "Scan and judgment only, report written, counts and file:line in the reply, no proposal, no branch, no edit"} +] From fe0b229efc0baad8b97c13f79fe8f10baf4a0792 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 19 Oct 2026 00:50:34 +0200 Subject: [PATCH 13/24] docs(guardrails): injection and exposure in the skill, the rule catalogue, the probe plan and secure-by-default; a11y handed to /a11y --- rules/secure-by-default.md | 25 +++++++---- skills/guardrails/SKILL.md | 33 ++++++++------ skills/guardrails/references/checks.md | 59 ++++++++++++++++++++------ skills/guardrails/test-prompts.json | 4 +- 4 files changed, 84 insertions(+), 37 deletions(-) diff --git a/rules/secure-by-default.md b/rules/secure-by-default.md index fa22fea..1a97ccc 100644 --- a/rules/secure-by-default.md +++ b/rules/secure-by-default.md @@ -1,4 +1,4 @@ -# Secure by default: five domains and every API +# Secure by default: six domains and every API Scope: any project that has a public surface, an API, a database, messaging, a cloud function or a UI. Applies at design, scaffolding, implementation and @@ -25,13 +25,20 @@ never claimed done: write it as a manual step in the project's deploy notes. - Hard spend cap if the host offers one. Otherwise a budget alert plus a written kill-switch step. -## 2. Accessibility -- Everything reachable and usable by keyboard, focus always visible. - `:focus-visible` styled, never `outline: none` without a replacement. -- Every image has an `alt` (empty when decorative). Every field has a label; - a placeholder is not a label. +## 2. Injection +- Raw escapes (`$queryRawUnsafe`, `knex.raw`, `text()`, `.raw()`) take + bound values only; dynamic SQL in a function goes through `format()` + with `%I` / `%L` and `USING`. +- A filter object never comes straight from the request: allowlist the + fields, cast the values. No shell command carries input into a DB tool. -## 3. Supabase +## 3. Exposure (what the browser can see) +- No data in the browser console, no source map in production, no debug + flag in a committed config. +- Hydrated state, `data-*` attributes, hidden fields and shipped HTML + comments carry no token, hash, key or secret. + +## 4. Supabase - RLS enabled on every table, in the migration that creates it. - Policies limited to the owner: `(select auth.uid())` per operation, role `authenticated`. No `using (true)` on writes, no anon write. @@ -40,13 +47,13 @@ never claimed done: write it as a manual step in the project's deploy notes. - Views `security_invoker`. `security definer` functions pin `search_path` and revoke execute from anon. Buckets private by default. -## 4. SMS and email +## 5. SMS and email - Prior consent recorded per contact: who, when, channel, source, wording. No send without a consent row; check the suppression list before each send. - Every email has an unsubscribe link and `List-Unsubscribe`. Every marketing SMS says STOP, and a STOP reply is processed and stored automatically. -## 5. Cloud functions +## 6. Cloud functions - No function re-triggers itself: never write to the resource that fires it, never invoke itself. If unavoidable, guard with an idempotency flag. - Max instances (or reserved concurrency) and a timeout on every function. diff --git a/skills/guardrails/SKILL.md b/skills/guardrails/SKILL.md index 877f10d..154cfce 100644 --- a/skills/guardrails/SKILL.md +++ b/skills/guardrails/SKILL.md @@ -1,8 +1,8 @@ --- name: guardrails effort: high -description: 'Use when auditing a project against the baseline guardrails and fixing what fails: hosting (rate limit, CDN and firewall, spend cap), accessibility (keyboard, visible focus, alt text, field labels), Supabase (RLS on every table, owner-scoped policies, no service_role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), plus API and access hygiene (auth on every route, CORS, secrets, password storage). Runs a deterministic scanner, judges each hit, writes .claude/audits/GUARDRAILS.md, then proposes fixes, applies only the ones the user accepts (bugfixer executor, fresh verifier and security gates) and re-scans to prove each one fixed. Optional read-only live probe confirms a hole from outside on a target the user owns and names. Triggers: "guardrails", "garde-fous", "RLS activée ?", "audit supabase", "consentement sms", "plafond de dépense", "mots de passe en clair ?", "teste la sécurité de base du projet", "corrige les garde-fous", "teste-le en conditions réelles", "sonde le projet en direct". Headers and TLS → /harden; secrets, CVE, OWASP → /cso; full WCAG → /web-validate.' -argument-hint: '[project path] [--domain api,hosting,a11y,supabase,messaging,functions] [--exclude paths] [--live ] [--report-only]' +description: 'Use when auditing a project against the baseline guardrails and fixing what fails. Headers and TLS → /harden; secrets, CVE, dependencies → /cso; keyboard, alt, labels → /a11y. Domains: hosting (rate limit, CDN, spend cap), Supabase (RLS, owner policies, no service_role client-side), SMS and email (consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (SQL from input, raw escapes, NoSQL, shell into DB tools), exposure (console data, source maps, hydrated state, error bodies, debug mode, wide responses), plus API hygiene (auth, CORS, secrets, passwords). Scanner, judgment, .claude/audits/GUARDRAILS.md, fixes applied only on acceptance (bugfixer, verifier and security gates), re-scanned to prove them; optional read-only probe of a target you own. Triggers: "guardrails", "garde-fous", "RLS activée ?", "faille sql", "fuite navigateur", "plafond de dépense", "mots de passe en clair ?", "corrige les garde-fous", "sonde le projet en direct".' +argument-hint: '[project path] [--domain api,hosting,supabase,messaging,functions,injection,exposure] [--exclude paths] [--live ] [--report-only]' --- # /guardrails @@ -28,8 +28,8 @@ ROUTING: follow `$HOME/.claude/lib/effort-shift.md` (phases via ## STEP 1: Scope Work in the project the user names, else the current directory. Say in one -line what you will scan. Domains: `api`, `hosting`, `a11y`, `supabase`, -`messaging`, `functions`. The scanner skips the ones that do not apply. +line what you will scan. Domains: `api`, `hosting`, `supabase`, +`messaging`, `functions`, `injection`, `exposure`. The scanner skips the ones that do not apply. `--report-only` stops after STEP 7: audit, no fix. ## STEP 2: Run the scanner @@ -71,21 +71,27 @@ Read the code for the domains that apply and answer, with file:line evidence: wording? Is a STOP reply wired from the provider webhook to the store? - **Functions**: trace every trigger to the resource it writes, including queues, storage events, schedulers and third-party webhooks. -- **A11y**: with a dev server running, walk the main flow with Tab only - (`/browse`). Otherwise mark the keyboard walk-through as not done. +- **Injection**: for each INJ hit, trace the interpolated value to its + source. A constant, an allowlisted identifier or a value already cast to + a number is a FALSE POSITIVE; anything that can come from a request, + a file or another user's row is CONFIRMED. +- **Exposure**: read the code behind each EXP hit: is the logged object, + the hydrated key or the returned row really user data? With `--live` + against a production build (STEP 5), the probe answers for served + source maps, error bodies and sensitive keys; without it, say so. ## STEP 5: Live probe (only on `--live`, read-only) The static scan shows a protection is missing in the code. A probe shows the door is actually open. Run it only when the user asks, and only against a target the user owns and names: their local dev server first, a staging or -production URL only on an explicit, specific go. Never a URL you inferred, +production URL only on an explicit, specific go. The `exposure` block runs against a production build or a staging URL (`next build && next start`, `vite preview`, framework debug off): a dev server serves source maps and tracebacks by design, so its exposure OPEN verdicts are dev artefacts, reported as such, with no proposal and no re-pass requirement. Never a URL you inferred, never a third party. 1. **Build the plan** `references/checks.md` describes. From the static findings fill a JSON plan: `base_url`, the Supabase `url` and `tables`, the `routes` (mark the ones meant to be public), `cors`, and a - `rate_limit` route if the user wants that one burst. Secrets never go in + `rate_limit` route if the user wants that one burst. Add an `exposure` block (`{}` for the defaults, `error_routes` for a route you own that answers an error to a malformed id, never a path you guess) so the probe reads source maps, error bodies and response keys; every path in the plan starts with `/`. Secrets never go in the plan or the command line: export `GUARDRAILS_ANON_KEY` and, for the cross-user probe, `GUARDRAILS_JWT2`, from test keys, never `service_role`. 2. **Run it**, confirming ownership with `--authorized`: @@ -100,7 +106,7 @@ never a third party. replays it. 3. **Cross the verdicts with the static findings.** A verdict is an observation, not a conclusion: OPEN means the request returned data or a - 200, CLOSED means it was refused or empty. A static FAIL confirmed OPEN in + 200, CLOSED means it was refused or empty. SKIPPED and ERROR mean the target was not observed: never read either as proof of a fix. A static FAIL confirmed OPEN in the probe leads the report. A CLOSED probe on a static FAIL still needs the fix: the dev target may differ from production. 4. **Guardrails on the probe itself**: read-only, test keys only, the @@ -137,9 +143,9 @@ route). FALSE POSITIVE and ACCEPTED RISK get no proposal. Each proposal: - **number, rule, file(s)**, and the problem in one line; - **the fix**, concrete: file:line and the change, the SQL for a migration, - the label text for a field. Root cause, never a mask: a missing RLS gets + the parameter binding for a query. Root cause, never a mask: a missing RLS gets owner policies in the same migration, not a disabled check; -- **choices the user sees** (label wording, CORS origins, owner column, +- **choices the user sees** (allowlisted filter fields, CORS origins, owner column, rate-limit numbers), each with your proposed value, named so the user can change it; - **risk**: what it can break. `BREAKING` when it changes a contract a client @@ -150,7 +156,8 @@ route). FALSE POSITIVE and ACCEPTED RISK get no proposal. Each proposal: that must turn CLOSED, and a project test when one fits naturally. MANUAL items stay user steps (STEP 6), never proposals. A live OPEN verdict -with no static finding gets a proposal whose proof is the probe alone. +with no static finding gets a proposal whose proof is the probe alone, +unless STEP 5 marked it a dev artefact. Save the proposals to `.claude/tasks/plans/-guardrails-.md` and append them to the report. In the reply, show them as a numbered list, @@ -163,7 +170,7 @@ stop the turn: ``` Which fixes do I apply? "all" (every proposal except DECISION ones), -numbers ("1,3,5-7"), "none", or an amendment ("2 with the label 'Email'"). +numbers ("1,3,5-7"), "none", or an amendment ("2 with the fields ['id','status']"). A DECISION proposal needs its number plus your choice. ``` diff --git a/skills/guardrails/references/checks.md b/skills/guardrails/references/checks.md index 1f9313b..aac9b34 100644 --- a/skills/guardrails/references/checks.md +++ b/skills/guardrails/references/checks.md @@ -26,15 +26,34 @@ default; a judged hit can be a false positive. | HOST-WAF-DDOS | MANUAL | firewall, DDoS and bot rules are dashboard settings | enable and confirm in the dashboard | | HOST-SPEND-CAP | MANUAL | hard spend cap is a plan setting | enable the cap; else budget alert plus a written kill switch | -## a11y +## injection + +Patterns are per language: a Postgres `$1` placeholder, a tagged template +(`sql\`…\``, `sql\`…\``), an argv array and test or fixture paths are +silent by design. | Rule | Sev | Catches | Fix | |---|---|---|---| -| A11Y-IMG-ALT | FAIL | `img` or `Image` without `alt` | describe it, or `alt=""` if decorative | -| A11Y-FIELD-LABEL | FAIL | native input, select, textarea with no label | `label for`, wrapping label or `aria-label` | -| A11Y-CLICK-NO-KEYBOARD | FAIL | click handler on a div or span lacking role, tabindex or key handler | use a `button` | -| A11Y-FOCUS-OUTLINE | FAIL / WARN | focus outline removed; WARN when a `:focus-visible` style exists elsewhere | style `:focus-visible` instead | -| A11Y-TABINDEX-POSITIVE | WARN | `tabindex` above 0 | use 0 or -1 and fix the DOM order | +| INJ-SQL-RAW-UNSAFE | FAIL | `$queryRawUnsafe`, `$executeRawUnsafe`, `knex.raw`, `sequelize.query`, `Sequelize.literal`, Django `.objects.raw()` / `.extra()`, SQLAlchemy `text()` fed a variable; ActiveRecord `where("… #{}")` | bind the values, or the tagged `$queryRaw` | +| INJ-SQL-CONCAT | FAIL | a SQL statement (select … from … where, insert into, update … set, delete … where, create/drop/alter) built with `${}`, `+`, an f-string, `%`, `.format`, PHP `$var`, Ruby `#{}`, `format!`, `Sprintf` | placeholders and a parameter list | +| INJ-SQL-DYNAMIC-EXEC | WARN | plpgsql `EXECUTE '…' \|\| x` | `format('… %I %L', …)` and `USING` | +| INJ-POSTGREST-FILTER | WARN | supabase-js `.or()`, `.filter()`, `.not()`, `.match()`, `.textSearch()` with an interpolated string, in a file that uses supabase | `.eq()` and friends, validated values | +| INJ-NOSQL-OPERATOR | WARN | Mongo `$where` with a string; a filter taken from `req.body`, `req.query` or `req.params` | allowlist the fields, cast to string, `sanitizeFilter` | +| INJ-SHELL-DB-TOOL | FAIL | a shell call naming psql, mysql, mysqldump, pg_dump, mongosh, redis-cli, sqlite3… with an interpolated argument | an argv array, no shell, validated input | + +## exposure + +| Rule | Sev | Catches | Fix | +|---|---|---|---| +| EXP-CONSOLE-DATA | WARN | `console.log/info/debug/dir/table` in client-reachable code with a data argument (user, session, response, token, body…); string literals are ignored | strip console calls in the production build, log server-side | +| EXP-SOURCEMAP-PUBLIC | FAIL / WARN | `productionBrowserSourceMaps: true`, vite `sourcemap: true` or `'inline'`, `GENERATE_SOURCEMAP=true` in a committed non-dev env file, webpack `devtool` readable maps (FAIL in `webpack.prod*`, WARN elsewhere), a real `.map` under `public/` or `static/` (any size; vendored and `.min.` maps excluded); angular `sourceMap: true` (WARN) | off, or `hidden` and upload to the error tracker | +| EXP-HYDRATED-SENSITIVE | WARN | a token, secret, key, password or ssn-like key returned by `getServerSideProps`, `getStaticProps`, a Remix `loader`, a SvelteKit `load` or set on `window.__STATE__`; a TS type member is skipped | return only the fields the page renders | +| EXP-MARKUP-COMMENT | WARN | `` shipped to the browser (html, astro, php, ejs, hbs, twig, njk, liquid) with todo, fixme, debug, password, token, internal, staging, admin… | delete it, or move it to a code comment the build strips | +| EXP-DATA-ATTR-SENSITIVE | WARN | `data-*` attribute or hidden input named secret, api-key, password, jwt, private, credential (csrf, xsrf, authenticity, nonce excluded) | keep it server-side, send an opaque id | +| EXP-ERROR-STACK | FAIL | in a route file: `err.stack`, the error object, `traceback.format_exc()` or `getTraceAsString()` in a response | generic message out, full error in the server log | +| EXP-ERROR-MESSAGE | WARN | in a route file: `err.message`, `str(e)`, `$e->getMessage()` sent as is | map to a safe message; validation errors are fine, DB errors are not | +| EXP-DEBUG-ON | FAIL | `DEBUG = True` in a settings module (not dev/local/test), `APP_DEBUG=true` / `FLASK_DEBUG=1` in a committed non-dev env file, `app.debug = True`, `consider_all_requests_local = true`, `errorhandler()` mounted without an environment guard | env-driven, false in production | +| EXP-RESPONSE-WIDE | WARN | a route returning `select *` / `select('*')` on a users-like table, or a single-line Prisma `findUnique/findFirst/findMany` without `select` or `omit` | an explicit field list | ## supabase @@ -85,7 +104,16 @@ The scanner is regex over text. It cannot see: - whether consent was actually collected before the stored timestamp - whether a STOP reply reaches your store from the provider webhook - loops through queues, storage events, schedulers or third-party webhooks -- keyboard traps, focus order, modal focus handling, color contrast +- a SQL string assembled across several lines, or passed through a + variable before the query call (trace it by hand) +- whether a template literal's tag parameterizes: tagged templates are + trusted +- built output (`dist/`, `.next/`) and runtime state such as + `__NEXT_DATA__`: only the live probe sees a served map or a hydrated + token +- a multi-line Prisma call or a value object spread into state: the + single-line rules stay silent +- what the console or an XHR carries once the page runs: a browser walk - client-reachable code in unusual layouts (the rule uses path and `use client` heuristics, `.astro` is never flagged) - values built at runtime, minified bundles, anything over 1 MB @@ -105,11 +133,9 @@ project: a contact form beside it and no subscriber storage gives WARN. The scanner skips log files and cache directories, and never follows symlinks. By design the scanner ignores: policies granted only to `service_role`, -fields that are never rendered (`hidden`, `display: none`), click handlers -that only stop propagation or sit on `role="presentation"`, focus styles -that swap the outline for a border or shadow, UI route components, keys +UI route components, keys inside git-ignored env files, and password literals in test, fixture and -i18n files. +i18n files, tagged SQL templates, placeholders with a separate parameter list, an argv array handed to a DB tool, console calls in server code, logging calls that carry a stack, `sourcemap: 'hidden'`, a debug flag read from the environment, dev, local and test env files and settings modules, minified files and built directories, and a hidden input or data attribute named csrf, xsrf, authenticity or nonce. ## Live Supabase checks (the user runs them in the SQL editor) @@ -176,12 +202,14 @@ one opt-in POST burst for the rate-limit check, and stops at a request budget. "cors": true, "cors_path": "/api/v1/notes", "rate_limit": {"path": "/api/v1/auth/login", "method": "POST", - "count": 20, "body": "{\"email\":\"t@t.io\",\"password\":\"x\"}"} + "count": 20, "body": "{\"email\":\"t@t.io\",\"password\":\"x\"}"}, + "exposure": {"error_routes": ["/api/v1/notes/not-a-number"]} } ``` Environment, from test keys only, never `service_role`: `GUARDRAILS_ANON_KEY` (anon-read), `GUARDRAILS_JWT2` (cross-user). +The fields probe sends `GUARDRAILS_JWT2` as a bearer when it is set. Every path in the plan starts with `/`: a path that could leave the named host is a usage error. | Probe | id | OPEN means | Read it against | |---|---|---|---| @@ -190,18 +218,21 @@ Environment, from test keys only, never `service_role`: | no-auth route | `no-auth:` | the route answered 200 with no token | API-ROUTE-NO-AUTH, object authz | | cors-reflect | `cors-reflect` | a foreign origin was reflected with credentials | API-CORS-WILDCARD | | rate-limit | `rate-limit` | the burst saw no 429 | HOST-NO-RATE-LIMIT | +| sourcemap | `sourcemap:' b'' b'' + b'' b'' b'') if path == "/app.js": @@ -77,6 +78,13 @@ class H(BaseHTTPRequestHandler): if path == "/biginline.js": return self._send(200, b"console.log(4);\n//# sourceMappingURL=" b"data:application/json;base64," + b"A" * 20000) + if path == "/err.js": + return self._send(200, b"console.log(5);\n//# sourceMappingURL=err.js.map\n") + if path == "/err.js.map": + return self._send(503, b"") + if path == "/api/session": + return self._send(200, b'{"id": 2, "token": "t", "profile": {"private": false}}', + {"Content-Type": "application/json"}) if path == "/boom": return self._send(500, b"Traceback (most recent call last):\n" b' File "app.py", line 12, in handler\n') @@ -176,7 +184,8 @@ check "a write method in the plan exits 2" "$?" 2 echo "== exposure probes" cat > "$WORK/exposure.json" < "$WORK/badcu.json" probe --authorized "$WORK/badcu.json" >/dev/null 2>&1 check "a string cross_user_paths exits 2" "$?" 2 +printf '{"base_url": "%s", "supabase": 5}\n' "$BASE" > "$WORK/badsb.json" +probe --authorized "$WORK/badsb.json" >/dev/null 2>&1 +check "a non-object supabase block exits 2" "$?" 2 cat > "$WORK/lower.json" < public/assets/app.js.map" mutant sourcemap-large-map FAIL EXP-SOURCEMAP-PUBLIC \ - "mkdir -p public; head -c 1100000 /dev/zero | tr '\\0' a > public/app.js.map" + "mkdir -p public; { printf '%s' '{\"version\":3,\"sources\":[\"src/app.ts\"],\"mappings\":\"'; head -c 1100000 /dev/zero | tr '\\0' A; printf '%s\n' '\"}'; } > public/app.js.map" mutant hydrated-sensitive WARN EXP-HYDRATED-SENSITIVE \ "printf '%s\n' 'export async function getServerSideProps() { return { props: { accessToken: process.env.CRM_TOKEN } }; }' > src/pages/account.tsx" mutant markup-comment WARN EXP-MARKUP-COMMENT \ @@ -241,6 +241,8 @@ benign() { # benign