clickwrap 0.0.0 → 0.1.0

data/exe/clickwrap

@@ -0,0 +1,374 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The standalone verifier.
+#
+#   clickwrap verify receipt.json --documents ./receipt-documents
+#
+# ==============================================================================
+# THIS COMMAND MUST WORK WITH NOTHING. No Rails, no host application, no
+# database, no configuration, no network, and no access to the code that wrote
+# the receipt. That is the entire point of it: a receipt whose only verifier is
+# the application that produced it is a receipt whose verification nobody
+# independent can repeat. Someone should be able to install this gem on a laptop
+# years from now, point it at a JSON file and a folder of documents, and get an
+# answer.
+#
+# So this file requires four things and nothing else: canonical JSON, the digest
+# helpers, the receipt verifier, and the standard library. Adding an
+# ActiveSupport call, a Rails constant, or a gem dependency here would quietly
+# break the promise the receipt itself makes in its `verifier_instructions`.
+# ==============================================================================
+#
+# What a successful run establishes is bounded, and the output says so: the
+# bytes in this file still hash to the digest recorded inside it, and the
+# document files supplied still hash to the digests the receipt cites. It does
+# not establish who wrote the receipt, when, or that whoever controlled the
+# application and its database could not have written both the record and its
+# digest.
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require "json"
+
+require "clickwrap/version"
+require "clickwrap/errors"
+require "clickwrap/canonical_json"
+require "clickwrap/digest"
+
+# The command-line front end. Argument parsing by hand rather than through
+# OptionParser: there is one command with one option, and a hand-written parser
+# is easier to read than the configuration of a general one.
+module ClickwrapCommandLine
+  SUCCESS = 0
+  FAILURE = 1
+  INCOMPLETE = 2
+
+  # Three states, not two. A check that could not run — a document whose bytes
+  # nobody supplied — is neither a pass nor a failure, and collapsing it into
+  # either one turns "we did not look" into "we looked and it was fine".
+  SYMBOLS = { true => "✓", false => "✗", nil => "–" }.freeze
+
+  USAGE = <<~TEXT.freeze
+    clickwrap #{Clickwrap::VERSION} — verify a Clickwrap receipt without the application that wrote it.
+
+    Usage:
+      clickwrap verify RECEIPT.json [--documents DIR] [--json]
+      clickwrap --help
+      clickwrap --version
+
+    Options:
+      --documents DIR   Folder holding BOTH artifacts for every cited document. Name them
+                        KEY-VERSION-LOCALE.source.EXT and
+                        KEY-VERSION-LOCALE.rendered.EXT. The source and the exact rendered
+                        representation are checked against their separate recorded digests.
+      --json            Print the result as JSON instead of lines of text.
+
+    Exit status:
+      0  every required check passed
+      1  a check failed or the receipt could not be read
+      2  no check failed, but at least one required artifact was not supplied
+
+    What a pass means: the canonical bytes still hash to the digest recorded inside the
+    receipt, and the documents supplied still hash to the digests it cites. It does not
+    establish who produced the receipt, when, or that a party controlling the original
+    application and its database could not have written both the record and its digest.
+  TEXT
+
+  module_function
+
+  def run(argv)
+    return help if argv.empty? || argv.first == "--help" || argv.first == "-h"
+    return version if ["--version", "-v"].include?(argv.first)
+
+    command = argv.shift
+
+    case command
+    when "verify" then verify(argv)
+    else
+      warn("Unknown command #{command.inspect}.\n\n#{USAGE}")
+      FAILURE
+    end
+  end
+
+  def help
+    say(USAGE)
+    SUCCESS
+  end
+
+  def version
+    say("clickwrap #{Clickwrap::VERSION} (receipt schema #{Clickwrap::CANONICAL_SCHEMA_VERSION})")
+    SUCCESS
+  end
+
+  def verify(argv)
+    options = parse_verify_options(argv)
+    return FAILURE if options.nil?
+
+    receipt_json = read_receipt(options[:receipt_path])
+    return FAILURE if receipt_json.nil?
+
+    parsed = parse_json(receipt_json, options[:receipt_path])
+    return FAILURE if parsed.nil?
+
+    documents, sources = load_documents(parsed, options[:documents_directory])
+    return FAILURE if documents.nil?
+
+    result = verifier.verify(receipt_json, documents: documents)
+    options[:json] ? report_as_json(parsed, result, sources) : report(parsed, result, sources)
+    return FAILURE if result.failed?
+    return INCOMPLETE if result.incomplete?
+
+    SUCCESS
+  rescue Clickwrap::Error => error
+    warn("#{error.class.name.split("::").last}: #{error.message}")
+    FAILURE
+  end
+
+  # --- Arguments ------------------------------------------------------------
+
+  def parse_verify_options(argv)
+    options = { receipt_path: nil, documents_directory: nil, json: false }
+
+    until argv.empty?
+      argument = argv.shift
+
+      case argument
+      when "--documents"
+        options[:documents_directory] = argv.shift
+      when /\A--documents=(.+)\z/
+        options[:documents_directory] = Regexp.last_match(1)
+      when "--json"
+        options[:json] = true
+      else
+        options[:receipt_path] = argument
+      end
+    end
+
+    return options if options[:receipt_path]
+
+    warn("clickwrap verify needs the path to a receipt file.\n\n#{USAGE}")
+    nil
+  end
+
+  # --- Reading --------------------------------------------------------------
+
+  def read_receipt(path)
+    unless File.file?(path)
+      warn("There is no file at #{path}.")
+      return nil
+    end
+
+    File.read(path, encoding: Encoding::UTF_8)
+  end
+
+  def parse_json(text, path)
+    JSON.parse(text)
+  rescue JSON::ParserError => error
+    warn("#{path} is not valid JSON: #{error.message}")
+    nil
+  end
+
+  # Matches each document the receipt cites to a file in the bundle.
+  #
+  # The receipt names a key, a version label, and a locale, so those are tried
+  # first, most specific first, and a file whose name merely starts with the key
+  # is the last resort. A document with no matching file is reported as not
+  # checked — never as verified, and never as failed, because "we did not look"
+  # and "we looked and it was wrong" are different answers.
+  def load_documents(receipt, directory)
+    entries = Array(receipt["documents"])
+    return [{}, {}] if directory.nil? || entries.empty?
+
+    unless File.directory?(directory)
+      warn("There is no directory at #{directory}.")
+      return [nil, nil]
+    end
+
+    files = Dir.children(directory).select { |name| File.file?(File.join(directory, name)) }
+    documents = {}
+    sources = {}
+    @ambiguous_documents = {}
+
+    entries.each do |entry|
+      key = entry["key"].to_s
+      version = entry["version"].to_s
+      locale = entry["locale"].to_s
+      identity = [key, version, locale].reject(&:empty?).join("@")
+      next if key.empty? || documents.key?(identity)
+
+      source_name = match_artifact_file(files, key, version, locale, "source")
+      rendered_name = match_artifact_file(files, key, version, locale, "rendered")
+
+      if source_name || rendered_name
+        documents[identity] = {}
+        if source_name
+          documents[identity]["source"] = File.binread(File.join(directory, source_name))
+          sources["#{identity}:source"] = source_name
+        end
+        if rendered_name
+          documents[identity]["rendered"] = File.binread(File.join(directory, rendered_name))
+          sources["#{identity}:rendered"] = rendered_name
+        end
+        next
+      end
+
+      # A single generic file can only mean the representation the receipt
+      # records as offered. When source and rendered digests are identical the
+      # verifier can safely use those same bytes for both; otherwise callers
+      # must use the explicit .source/.rendered names above.
+      name = match_file(files, key, version, locale)
+      next if name.nil?
+
+      documents[identity] = File.binread(File.join(directory, name))
+      sources["#{identity}:rendered"] = name
+    end
+
+    [documents, sources]
+  end
+
+  # Finds the one file that holds a document's bytes, or nothing.
+  #
+  # "Or nothing" is deliberate, and so is the ambiguity check. Two files can
+  # easily reduce to the same name — `terms.md` beside a stray `terms.bak`, or
+  # two locales dropped in the same folder — and a verifier that quietly picked
+  # one would report that a document verified while having read a file the
+  # operator never meant to offer. That is the one failure mode a verification
+  # tool must not have, so an ambiguous match is reported as ambiguous and the
+  # document is left unchecked rather than checked against a guess.
+  def match_file(files, key, version, locale)
+    candidates = ["#{key}-#{version}-#{locale}", "#{key}-#{version}", "#{key}.#{locale}", key]
+
+    candidates.each do |candidate|
+      matches = files.select { |name| basename(name).casecmp?(candidate) }
+      return matches.first if matches.length == 1
+      return ambiguous(key, matches) if matches.length > 1
+    end
+
+    prefixed = files.select { |name| basename(name).downcase.start_with?("#{key.downcase}-") }
+    return prefixed.first if prefixed.length == 1
+    return ambiguous(key, prefixed) if prefixed.length > 1
+
+    nil
+  end
+
+  def match_artifact_file(files, key, version, locale, artifact)
+    candidates = ["#{key}-#{version}-#{locale}", "#{key}-#{version}", "#{key}.#{locale}", key]
+
+    candidates.each do |candidate|
+      pattern = /\A#{Regexp.escape(candidate)}[.-]#{Regexp.escape(artifact)}(?:\..+)?\z/i
+      matches = files.grep(pattern)
+      return matches.first if matches.length == 1
+      return ambiguous("#{key}:#{artifact}", matches) if matches.length > 1
+    end
+
+    nil
+  end
+
+  def ambiguous(key, matches)
+    @ambiguous_documents[key] = matches.sort
+    nil
+  end
+
+  def basename(name) = File.basename(name, File.extname(name))
+
+  def ambiguous_documents = @ambiguous_documents ||= {}
+
+  # --- Reporting ------------------------------------------------------------
+
+  def report(receipt, result, sources)
+    say("Receipt #{receipt["event_id"]} (schema #{result.schema || receipt["schema"]})")
+    say
+
+    Array(result.checks).each { |check| say("  #{SYMBOLS.fetch(status(check), "?")} #{describe(check)}") }
+
+    say
+    sources.each { |key, name| say("  document #{key} read from #{name}") }
+    say("  no document files were supplied, so no document digest was checked") if sources.empty?
+
+    ambiguous_documents.each do |key, matches|
+      say("  ! document #{key} was NOT checked: #{matches.join(" and ")} both match that key.")
+      say("    Leave exactly one file per document so the check reads what you meant.")
+    end
+
+    say
+    Array(result.failures).each { |failure| say("  #{failure}") } if result.failed?
+    say case result.status
+        when "verified" then "VERIFIED — #{summary(result)}."
+        when "incomplete" then "INCOMPLETE — #{summary(result)}; supply the missing artifacts and run again."
+        else "FAILED — #{summary(result)}; see the failing checks above."
+        end
+    say
+    say("A passing digest detects modification of the bytes it covers. It does not establish who")
+    say("produced them, when, or that whoever controlled the original application and its database")
+    say("could not have written both the record and the digest.")
+  end
+
+  def report_as_json(receipt, result, sources)
+    say(
+      JSON.pretty_generate(
+        "event_id" => receipt["event_id"],
+        "schema" => result.schema || receipt["schema"],
+        "success" => result.success?,
+        "status" => result.status,
+        "checks" => Array(result.checks).map do |check|
+          { "name" => value(check, :name), "passed" => status(check), "detail" => value(check, :detail) }
+        end,
+        "failures" => Array(result.failures).map(&:to_s),
+        "documents_read" => sources,
+        "verifier_version" => Clickwrap::VERIFIER_VERSION
+      )
+    )
+  end
+
+  def summary(result)
+    checks = Array(result.checks)
+    passed = checks.count { |check| status(check) == true }
+    skipped = checks.count { |check| status(check).nil? }
+    sentence = "#{passed} of #{checks.length} checks passed"
+
+    skipped.zero? ? sentence : "#{sentence}, #{skipped} could not be run"
+  end
+
+  def describe(check)
+    detail = value(check, :detail)
+    name = value(check, :name)
+
+    detail.to_s.empty? ? name.to_s : "#{name}: #{detail}"
+  end
+
+  # true (checked and passed), false (checked and failed), nil (not checked).
+  def status(check)
+    passed = value(check, :passed)
+    return nil if passed.nil?
+
+    passed == true
+  end
+
+  # Check entries may arrive with symbol or string keys, or as objects that
+  # answer the same names. Reading all three costs four lines and saves the
+  # command from breaking on a detail nobody should have to think about.
+  def value(check, name)
+    return check.public_send(name) if check.respond_to?(name) && !check.is_a?(Hash)
+    return check[name] if check.respond_to?(:key?) && check.key?(name)
+    return check[name.to_s] if check.respond_to?(:key?) && check.key?(name.to_s)
+
+    nil
+  end
+
+  def verifier
+    require "clickwrap/receipt_verifier"
+    Clickwrap::ReceiptVerifier
+  rescue LoadError => error
+    raise Clickwrap::Error, "This build of clickwrap has no receipt verifier available (#{error.message})."
+  end
+
+  def say(text = "") = $stdout.puts(text)
+
+  # Anything that is not the report itself goes to standard error, so
+  # `clickwrap verify ... > result.txt` captures the result and nothing else.
+  def warn(text) = Kernel.warn(text)
+end
+
+exit(ClickwrapCommandLine.run(ARGV))

data/guides/README.md

@@ -0,0 +1,30 @@
+# Clickwrap guides
+
+The [README](../README.md) is the tour: it gets you from install to a verified receipt and
+shows each capability briefly. These guides are the depth behind the parts that are easy to
+get subtly wrong, and they assume you have already read the README section they expand on.
+
+| Guide | Read it when |
+|---|---|
+| [Integrating](integrating.md) | When you are wiring the gem into a real application — or pointing an AI agent at the job. The battle-tested playbook from a full production migration: install order, real legal content, test setup, Devise bridges, custom surfaces, protecting a money path, importing history, and the dual-write rollout doctrine. |
+| [Request evidence](request-evidence.md) | Before you enable IP address, browser user-agent, or any IP-geolocation field. It is the data dictionary: one row per field, where it comes from, what it does not establish, who can read it, and what happens to it when it is deleted. |
+| [Receipts and verification](receipts-and-verification.md) | When you need to hand a receipt to somebody outside your application, or explain exactly what a green verification result covers. Also the canonicalization profile, if you are writing a verifier of your own. |
+| [Retention and legal holds](retention-and-legal-holds.md) | When your retention periods come from a real obligation rather than a round number, when a duration cannot express the schedule, or before the first time you run a disposition against production data. |
+| [Integrity](integrity.md) | When someone asks how strong the audit trail is, or which of the five tiers you are actually on. Includes the threat model as a list of "what happens if" scenarios. |
+| [Consent and lifecycle](consent-and-lifecycle.md) | When you are choosing between `agree_to`, `acknowledge`, and `consent_to` for a specific screen, or when you need the full state and action table for a kind. |
+| [Migrating](migrating.md) | When you have an `accepted_terms_at` column or a FinePrint installation and you want the history without inventing the parts of it nobody recorded. |
+| [Accessibility](accessibility.md) | Before your accessibility review, so you know exactly which line is the reference views' responsibility and which is your page's. |
+| [Naming](naming.md) | Before you propose a public method, option, configuration setting, or receipt field — or before you review a pull request that adds one. |
+| [Organizations](organizations.md) | When a human user accepts or authorizes something on behalf of an organization. Separates actor, represented party, tenant, subject, membership evidence, and the legal-authority boundary. |
+
+Two things hold across all of them.
+
+**Clickwrap is evidence mechanics.** It records what was offered, what was answered, and what
+committed alongside it. Your application and its counsel own the words, the lawful basis, the
+retention periods, the identity questions, and every legal conclusion. Nothing in these guides
+is advice about any of that.
+
+**Every external claim here carries an exact URL and a source class.** Law, court decisions,
+regulator guidance, technical standards, vendor documentation, and this project's own design
+inferences are labeled separately, because they carry very different weight. Source-code
+citations are pinned to commit `a1ffe9b` of this repository rather than to a moving branch.

data/guides/accessibility.md

@@ -0,0 +1,249 @@
+# Accessibility: what the reference views do, and what stays yours
+
+Clickwrap ships tested reference views. They are a good starting point and they are one
+fragment of one page. **Nothing in this gem certifies your application under
+[WCAG 2.2](https://www.w3.org/TR/WCAG22/) *(technical standard)* or any other accessibility
+standard**, and no library that sees a single partial could. Accessibility applies to the whole
+experience: placement, contrast, clutter, reading order, focus management across the page,
+error recovery, and whether the surrounding design lets somebody find the control at all.
+
+What follows is the exact division of responsibility, so your review can spend its time on the
+part that is actually yours.
+
+---
+
+## What the reference views do
+
+All of this is in `app/views/clickwrap/shared/_fields.html.erb`,
+`_statement.html.erb`, and `_error_summary.html.erb`, and is exercised by
+the gem's own suite.
+
+### Labels and programmatic names
+
+Every control has one label, tied together by ID, and the label carries the words:
+
+```erb
+<%= check_box_tag combined.control_name, "1", false, id: combined.control_id, ... %>
+<%= label_tag combined.control_id, clickwrap_combined_sentence(combined) %>
+```
+
+The label **is** the sentence — including the document links, which sit inside it. Pressing the
+words toggles the control, and assistive technology announces the sentence and the box together.
+There is no `aria-label` standing in for a visible label, and no placeholder doing a label's job.
+
+For an explicit yes/no decision, the group is a real `<fieldset>` with a `<legend>` carrying the
+assertion, and each radio has its own `<label>`.
+
+### The default is one line
+
+An ordinary signup renders one checkbox carrying one sentence:
+
+> ☐ I agree to the [Terms of Service](#) and I acknowledge the [Privacy Policy](#).
+
+That is a deliberate accessibility decision as much as a visual one. Two boxes, two "Required"
+flags, two version labels, and four stacked links are four times the interface for the same
+decision — and everything a screen-reader user has to hear before reaching the button is
+something a sighted user gets to skip.
+
+### One control never covers two *different kinds of* answer
+
+The composed line is one control answering several statements, and it is allowed to be, because
+the server signs which statements it covered and answers all of them from the one box. What it
+may never absorb is an answer somebody could reasonably want to give differently: an optional
+consent (which the line would silently make required), a recorded yes/no, a purpose with a
+withdrawal route, or copy the application wrote itself. Each of those keeps its own control below
+the line — and the development linter flags
+`combined_statement_rendered_as_its_own_control` if a page offers a *second* control for a
+statement the signed line already covers, because that box offers a choice nobody has.
+
+### Controls start unselected
+
+There is no `checked` attribute anywhere in the statement partial, and there never will be. A
+pre-ticked box records the page's default rather than a person's action. The development linter
+flags `consent_control_preselected` if it finds one in rendered output.
+
+### Focus is visible and keyboard operation works
+
+The shipped stylesheet defines a visible focus indicator rather than removing the browser's.
+Every control is a native input; nothing is a `div` with a click handler. Tab order is document
+order because the markup is in reading order.
+
+### Error relationships are programmatic
+
+When a statement fails validation, its control gets `aria-invalid="true"` and
+`aria-describedby` pointing at the paragraph carrying the message. The paragraph has the
+matching `id`. The `fieldset` gets the same treatment for choice groups.
+
+### There is an error summary, and it takes focus
+
+```erb
+<div class="clickwrap-error-summary" role="alert" tabindex="-1" autofocus>
+```
+
+`role="alert"` so assistive technology announces it when the failed submission re-renders,
+`tabindex="-1"` so it can hold focus, and `autofocus` so the browser moves focus there on load —
+**without a line of JavaScript**. Each entry is a link to the control it is about, so the fix is
+one press away rather than a scroll and a hunt. One control gets one entry however many acts it
+answered: three lines pointing at the same checkbox is a list of the page's internals, not of a
+person's problems.
+
+### Meaning is never carried by color alone
+
+Error messages carry a text prefix (`clickwrap.ui.error_prefix`) before the message. The styling
+underlines and colors these; the meaning survives without either.
+
+Nothing prints the word "Required" beside a control. The `required` attribute is there as
+progressive enhancement, and **the server decides** either way — but a required control on a
+signup form is not information anybody is missing, and a page that has to say it is a page
+expecting to be argued with. An optional consent stays unlabelled for the same reason and
+because it is unticked, unrequired, and separate: three signals that say it already.
+
+### It works with no JavaScript
+
+No Stimulus controller is required for correctness. Validation, error rendering, focus on the
+summary, and evidence capture all work in a browser that never runs a script. HTML `required`
+is progressive enhancement only — **the server decides**, and a client that ignores the
+attribute, never sends the field, or posts by hand meets the same server-side check.
+
+### Document links come before the action
+
+Links to each document render above the submit control — inside the sentence on the composed
+line, under the statement on an itemized one — carry the document's own name rather than "click
+here", and open in a new tab with `rel="noopener"` so a half-filled form is not lost. A link
+that only appears after the call to action has been pressed is not a link to anything.
+
+The "opens in a new tab" hint is rendered as an `sr-only` span rather than visible text: a
+sighted person gets their browser's own new-tab behavior and does not need it spelled out beside
+every link, and a screen-reader user gets the words. It is still rendered **only** when the link
+really does open a new tab, so hosts that change how links open —
+`config.document_link_html_options_with`, or `config.hotwire_native_document_links` for a native
+app — change the hint with them, and a `:same_screen` native link announces nothing it does not
+do.
+
+There is no version label beside a control. Versions are on the receipt, where somebody is
+reading the record and can act on them.
+
+### Locale-aware selection, with no silent fallback
+
+Human-facing text resolves to the requested locale before presentation, and a missing required
+translation fails closed rather than rendering a raw I18n key, a blank, or an unexpected
+language.
+
+---
+
+## What the host still owns
+
+Everything below is outside what the gem can see, and all of it can defeat a correct partial.
+
+| Yours | Why it matters |
+|---|---|
+| **Placement on the page** | A conspicuous control in a cluttered layout is not conspicuous. Where the block sits relative to the rest of the form is a design decision Clickwrap cannot make |
+| **Contrast and type size** | The reference stylesheet is a starting point in your color system, not a contrast audit of it. Check the rendered values against your own palette |
+| **The call-to-action wording** | You pass `submit:`. Whether that text tells the person what pressing it does is your judgment |
+| **Reading order of the whole page** | The partial is in order internally. Whether the surrounding markup keeps it that way is not something a partial can control |
+| **Page-level focus management** | The error summary takes focus on re-render. If your framework, modal, or Turbo Frame moves focus afterwards, that is yours to reconcile |
+| **Zoom, reflow, and small viewports** | Test at 200% and 400%, and at 320 CSS pixels wide |
+| **Motion, timeouts, and interruptions** | Presentation tokens are short-lived by default (`config.presentation_valid_for`, two hours). If a person needs longer than your timeout allows, that is your flow to fix |
+| **The document itself** | Whether the Terms, notice, or declaration is readable — plain language, headings, structure — is content, and content is yours |
+| **Native and API surfaces** | Hotwire Native web screens use the same component; a fully custom native or JSON presentation renders your own controls against the presenter's primitives, and inherits none of the above |
+| **Ejected views** | `bin/rails generate clickwrap:views` copies these partials into your app, where they shadow the gem's. From that moment every property above is yours to keep |
+| **Assistive-technology testing with real users** | No automated check substitutes for it |
+
+---
+
+## The linter is a heuristic, not a verdict
+
+In development and test only, `Clickwrap::Linter` scans policies, manifests, and rendered
+fragments for objectively checkable mistakes. It warns; it never raises, never blocks a render,
+and never certifies anything. A clean run means "none of the specific hazards below were
+detected in what was inspected," and nothing else.
+
+| Finding | What it noticed |
+|---|---|
+| `submit_control_before_clickwrap_block` | A submit control appears above the statements it is supposed to accept |
+| `consent_control_preselected` | A rendered control carries `checked` |
+| `document_link_missing` | A statement cites a document that nothing links to |
+| `assertion_text_blank` | A statement would render with no sentence |
+| `consent_statement_bundles_purposes` | A consent assertion contains "and", "and/or", "as well as", or "plus" — probably two purposes in one control |
+| `optional_consent_required_for_another_action` | An optional consent has been made mandatory in practice by another statement's `requires:` |
+| `rendered_manifest_differs_from_policy` | What was rendered does not match what the policy declared |
+
+Every finding carries a stable symbol so a test can assert on it without matching English, and a
+full-sentence explanation so somebody reading the log knows what to do.
+
+---
+
+## Reviewer checklist
+
+Run this against a real page in a real browser, not against the partial.
+
+**Structure and naming**
+
+- [ ] Every control has a visible label whose text is exactly what the server offered — the
+      composed sentence, or the statement's own assertion. Pressing the label text toggles the
+      control.
+- [ ] No control covers a statement the signed presentation did not say it covers, and no
+      statement the composed line covers has a second control of its own.
+- [ ] Choice groups are a `fieldset` with a `legend`.
+- [ ] Every control has an accessible name in the accessibility tree — check it, do not assume.
+
+**State**
+
+- [ ] Every control renders unselected on first load and after a failed submission.
+- [ ] Nothing on your surrounding page conveys "required" by color or an asterisk alone.
+
+**Keyboard and focus**
+
+- [ ] Every control, link, and the submit button is reachable and operable by keyboard alone.
+- [ ] The focus indicator is visible against your actual background, at every step.
+- [ ] Tab order matches visual order across the whole form, not just the Clickwrap block.
+
+**Errors**
+
+- [ ] Submit with nothing selected. An error summary appears, receives focus, and each entry
+      links to its control.
+- [ ] Each failing control has `aria-invalid="true"` and `aria-describedby` pointing at a
+      message that exists.
+- [ ] Error text is readable with color disabled or in grayscale.
+
+**Documents**
+
+- [ ] Every document is linked, above the submit control, with the document's own name.
+- [ ] The `sr-only` "opens in a new tab" hint is announced — check it in a screen reader, not
+      only in the markup, and check that your own CSS has not turned `.clickwrap-sr-only` into
+      `display: none`, which would remove it from the accessibility tree entirely.
+- [ ] Following a link and returning does not lose the form state.
+
+**Without JavaScript**
+
+- [ ] Disable JavaScript. Render, fail validation, correct, and submit successfully.
+- [ ] The error summary still receives focus.
+
+**Page level**
+
+- [ ] At 400% zoom and at 320 CSS pixels wide, nothing overlaps and nothing is cut off.
+- [ ] Contrast of label text, link text, error text, and the focus indicator meets your target
+      against your real palette.
+- [ ] Screen-reader pass: the whole sentence, its document links, and any error are all
+      announced, in an order that makes sense — and a link inside the sentence does not break
+      the sentence into fragments that stop reading as one statement.
+- [ ] The submit button's text says what pressing it does.
+
+**Locale**
+
+- [ ] Each supported locale renders, including the document links and version labels.
+- [ ] A missing translation fails loudly in development rather than rendering a key.
+
+None of the above certifies anything. It is the list of things that are cheap to check and
+expensive to miss.
+
+---
+
+## Sources
+
+| Source | Class |
+|---|---|
+| [WCAG 2.2](https://www.w3.org/TR/WCAG22/) | Technical standard |
+| [15 U.S.C. § 7001(d)](https://www.law.cornell.edu/uscode/text/15/7001) — accurate reflection, accessibility, and reproducibility of electronic records | Law |
+| [Berman v. Freedom Financial Network](https://cdn.ca9.uscourts.gov/datastore/opinions/2022/04/05/20-16900.pdf), [Toth v. Everly Well](https://www.ca1.uscourts.gov/sites/ca1/files/opnfiles/23-1727P-01A.pdf) — US appellate decisions assess conspicuous notice and unambiguous assent in the context of the whole interface; no control, color, or placement is a universal safe harbor | Cases |
+| The division of responsibility and the checklist above | Product-design inference |