HIF Inspection Tooling and Evidence Contract

Status: applied architecture, working draft 0.2

This document defines how software may inspect an interface against HIF without turning partial automation into a false conformance claim. It covers rule registries, adapters, evidence, findings, coverage, security, reports and the hand-off to expert review and remediation.

1. Purpose

Inspection tooling exists to:

• find reproducible defects early;
• connect evidence to stable HIF rules;
• explain user and system consequences;
• produce implementable remediation;
• preserve what the tool did and did not observe;
• route uncertain and subjective questions to qualified people;
• support comparison after a fix without reducing quality to one score.

The tool is not a substitute for participant research, assistive-technology testing, legal advice, security testing or a release decision.

2. Non-negotiable claims policy

An automated check MUST NOT claim whole-page, product, WCAG, legal or HIF conformance unless every requirement for that claim has been evaluated with an appropriate method and scope.

A passed check means only:

the observed test target met this rule under the recorded input, environment, assumptions and engine version.

It does not mean that:

• the requirement is satisfied in every state;
• equivalent content elsewhere passes;
• an unobserved user journey works;
• the implementation is understandable to people;
• a legal duty has been discharged.

The interface MUST label any aggregate value as risk, coverage or prioritisation support, not as a conformance score.

3. Evidence ladder

Every finding has exactly one primary evidence level.

The tool MUST NOT promote inferred evidence to detected, or a manual requirement to passed, merely because no defect was observed.

Confidence and severity are independent:

• confidence describes the strength of the conclusion;
• severity describes the consequence if the conclusion is true.

4. Adapter model

An adapter observes one bounded representation.

4.1 URL source adapter

The initial adapter fetches a public HTML response and selected HTTP headers. It can evaluate document language, viewport declaration, headings, landmarks, text-alternative decisions, detected accessible names, form labels, selected focus hazards, transport, response policy, payload size and response time.

It cannot prove:

• JavaScript-rendered states;
• focus behaviour or task completion;
• CSS geometry, hit areas or reflow;
• authenticated and consent-dependent states;
• motion, audio or timing;
• assistive-technology output;
• errors, interruption and recovery.

4.2 Image source adapter

The image adapter decodes a file locally and may measure dimensions, file size, luminance distribution and quantised palette structure. It can flag visual risks for review.

It cannot recover DOM semantics, source tokens, text size, reliable foreground/background pairs, focus order, hit targets, hidden states or motion. It MUST NOT present pixel statistics as a WCAG contrast result.

4.3 Browser worker

A browser worker is the next adapter tier. It SHOULD execute named states at controlled mobile and desktop profiles, collect the accessibility tree, computed styles, geometry, screenshots, console output, network records and performance traces. It MUST record browser, engine, viewport, input capabilities, locale, preferences and authentication boundary.

4.4 Journey and human adapters

Critical journeys require scripted keyboard, screen-reader, zoom/reflow, input, error and recovery passes. Perception, comprehension, trust, appropriateness and task success require expert or participant evidence as defined by the HIF Evaluation and Conformance method.

5. Rule contract

Every machine-addressable rule MUST define:

• stable identifier and version;
• title, category and scope;
• applicability;
• input aspects;
• test procedure;
• expected and non-applicable outcomes;
• assumptions and known limitations;
• default consequence severity;
• evidence level;
• rationale and remediation;
• mapped HIF and external requirements;
• passed, failed and inapplicable fixtures;
• change history and implementation consistency.

Accessibility rules SHOULD align with the W3C ACT Rules Format where the rule falls within its scope. An external standard mapping does not make the HIF rule itself normative for that external standard.

6. Finding contract

A finding MUST contain:

• rule ID;
• outcome: fail, warning or review;
• effective severity;
• evidence level;
• target and timestamp;
• engine and schema versions;
• concise evidence;
• user or system consequence;
• implementable remediation;
• related requirements.

Selectors, screenshots or values MAY be attached when they do not expose personal, confidential or secret data.

7. Coverage contract

Every report MUST state:

• observed inputs and final target;
• rules evaluated and passed;
• findings by evidence level;
• adapters used;
• unobserved states and requirements;
• run warnings and errors;
• environmental assumptions;
• manual follow-ups.

“No findings” MUST be accompanied by the coverage boundary. A failed fetch is not a passed audit. A rule that did not apply is not a passed rule.

8. Prioritisation

Priority MUST be derived from consequence, reach, frequency, reversibility, legal or safety exposure, confidence and remediation dependencies. Revenue, stakeholder seniority and ease of implementation MUST NOT inflate severity.

An aggregate risk index MAY support triage if:

• manual tasks are not counted as known defects;
• passed observed rules contribute to the denominator;
• the formula and limitations are visible;
• the underlying findings remain primary;
• teams cannot use the index as a release waiver.

9. Report and interchange

The canonical interchange format is HIF inspection report schema. It uses JSON Schema Draft 2020-12.

Reports SHOULD also export a readable Markdown form. Exports MUST retain rule IDs, evidence levels, coverage limitations and engine versions.

10. URL-fetch security

A service that accepts arbitrary URLs is a security boundary. It MUST:

• permit only HTTP and HTTPS;
• reject credentials and non-standard ports by default;
• resolve and reject private, loopback, link-local, reserved and non-public addresses;
• bind the connection to the validated address to resist DNS rebinding;
• repeat validation for every redirect;
• enforce redirect, time, response-size and media-type limits;
• disable active content execution in the fetcher;
• parse HTML without loading external entities;
• rate-limit untrusted callers;
• avoid retaining page bodies unless the engagement explicitly requires it;
• keep errors free of secrets and internal topology.

Production deployments SHOULD add network egress policy and isolated browser workers before enabling rendered-page inspection.

11. Release gates

An inspection implementation is releasable only when:

• every emitted rule ID exists in the registry;
• report output validates against the declared schema;
• pass, fail, non-applicable and malformed fixtures are covered;
• private-network, redirect and oversized-response tests pass;
• unsupported claims are absent from UI and exports;
• keyboard and forced-colour operation of the inspector itself pass;
• the English and Russian interfaces use controlled terminology;
• production checks prove both a public target and SSRF rejection.

12. Current applied baseline

The first implementation provides:

• public URL input;
• local image input;
• 31 URL checks;
• four image checks;
• eight mandatory manual follow-ups;
• severity and category filters;
• JSON and Markdown export;
• English and Russian interfaces;
• explicit coverage boundaries;
• a versioned report schema;
• server-side SSRF controls and deployment verification.

Version 0.2 extends the URL adapter with HSTS, direct HTTP-to-HTTPS redirection, MIME-sniffing protection, framing policy, CORP, ARIA naming and ID-reference integrity, section identification, duplicate IDs, mixed content, site-icon reachability, SVG presentation conformance and cross-origin dependency integrity.

A containerised browser worker is implemented and validated with mobile and desktop Chromium profiles, axe-core, paint/navigation/long-task measurements, JavaScript and CSS coverage, console errors and network failures. It is not part of the public adapter until an isolated runtime with a private authenticated route and deny-by-default network egress policy is provisioned. Application-level URL filtering does not replace that egress boundary.

Following browser-worker deployment, the priorities are journey plans, component/token ingestion, issue tracking, baselines, regression comparison and organisation-specific product profiles.

References

• W3C — Accessibility Conformance Testing Rules Format 1.1
• W3C — ACT Rules
• JSON Schema — Draft 2020-12
• OWASP — Server-Side Request Forgery Prevention Cheat Sheet
• HIF Evaluation and Conformance
• HIF Web Audit Playbook