clickwrap 0.0.0 → 0.1.0

data/lib/clickwrap/doctor.rb

@@ -0,0 +1,418 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # `bin/rails clickwrap:doctor` — a read-only diagnosis you can act on at 03:00.
+  #
+  #   ✓ 6 policies compiled
+  #   ✓ all referenced documents are published and digest-verified
+  #   ✓ every required gate has a remediation route
+  #   ✓ request-derived personal data is off by default
+  #   ! withdrawal_authorization records IP geolocation city without a review date
+  #   ! request-source trust is unverified
+  #   ✓ no overdue disposition
+  #   ✓ all checked event digests verify
+  #
+  # ============================================================================
+  # EVERY FINDING HERE IS AN OBJECTIVE FACT ABOUT CONFIGURATION OR DATA. This
+  # class must never print, return, or imply "compliant", "court-proof", "audit
+  # guaranteed", "approved", or "certified", and there is no overall verdict
+  # line: a run with no warnings means the specific things listed below were
+  # checked and nothing objectionable was found in them. It does not mean the
+  # application is lawful, that its retention periods are right, or that its
+  # evidence would persuade anyone. Those are not questions a library can
+  # answer, and a green tick that implied otherwise would be worse than no tool
+  # at all. PHRASES_THIS_REPORT_NEVER_PRINTS exists so a test can assert it.
+  # ============================================================================
+  class Doctor
+    Finding = Data.define(:status, :message) do
+      def ok? = status == :ok
+      def warning? = status == :warning
+      def problem? = status == :problem
+
+      def to_s = "#{SYMBOLS.fetch(status, "?")} #{message}"
+    end
+
+    SYMBOLS = { ok: "✓", warning: "!", problem: "✗" }.freeze
+
+    # Greped by the release test against every message this class produces.
+    PHRASES_THIS_REPORT_NEVER_PRINTS = (
+      Vocabulary::PROHIBITED_CLAIM_PHRASES + [
+        "compliant",
+        "compliance",
+        "court proof",
+        "audit guaranteed",
+        "audit approved",
+        "certified",
+        "approved",
+        "enforceable",
+        "legally valid"
+      ]
+    ).freeze
+
+    # How many recent events get their digests recomputed. A doctor run is
+    # something an operator does interactively, so it samples rather than
+    # verifying the whole table; `clickwrap:verify` is the exhaustive one.
+    DIGEST_SAMPLE_SIZE = 100
+
+    def report
+      findings = []
+      findings.concat(policy_findings)
+      findings.concat(document_findings)
+      findings.concat(optional_table_findings)
+      findings.concat(engine_mount_findings)
+      findings.concat(gate_findings)
+      findings.concat(request_evidence_findings)
+      findings.concat(review_date_findings)
+      findings.concat(resolver_findings)
+      findings.concat(source_trust_findings)
+      findings.concat(with_database("disposition") { disposition_findings })
+      findings.concat(with_database("legal holds") { legal_hold_findings })
+      findings.concat(with_database("event digests") { digest_findings })
+      findings.concat(with_database("integrity attestations") { integrity_attestation_findings })
+      findings.concat(with_database("external actions") { external_action_findings })
+      findings
+    end
+
+    # The README's rendering: one line per finding, in the order they were
+    # produced, with nothing summarizing them into a verdict.
+    def to_s = report.join("\n")
+
+    private
+
+    # --- Configuration --------------------------------------------------------
+
+    def policy_findings
+      count = Clickwrap.policies.size
+
+      if count.zero?
+        return [warning("no policies are compiled. Declare them with `Clickwrap.policy :key do ... end`, " \
+                        "conventionally in config/clickwrap.rb.")]
+      end
+
+      [ok("#{count} #{pluralize(count, "policy", "policies")} compiled")]
+    end
+
+    # Every document a policy references has to exist, be published, and still
+    # hash to what was recorded when it was published. A policy that presents a
+    # document nobody published is a runtime failure waiting for the first
+    # person who tries to sign up.
+    def document_findings
+      referenced = Clickwrap.policies.values.flat_map { |policy| policy.statements.flat_map(&:document_keys) }.uniq
+      return [ok("no policy references a document")] if referenced.empty?
+
+      problems = with_database("documents") { document_problems(referenced) }
+      return problems if problems.any?
+
+      [ok("all referenced documents are published and digest-verified " \
+          "(#{referenced.length} #{pluralize(referenced.length, "document", "documents")})")]
+    end
+
+    def document_problems(referenced)
+      referenced.flat_map do |key|
+        definitions = Clickwrap.documents.values.select { |definition| definition.key == key }
+
+        if definitions.empty?
+          next [problem("document :#{key} is referenced by a policy but never declared with " \
+                        "`Clickwrap.document :#{key}, version: \"...\", from: ...`")]
+        end
+
+        definitions.filter_map { |definition| document_problem(definition) }
+      end
+    end
+
+    def document_problem(definition)
+      document = Document.find_by(document_key: definition.key, tenant_key: definition.tenant_key)
+      version = document&.versions&.find_by(version_label: definition.version_label, locale: definition.locale)
+
+      if version.nil? || !version.published?
+        return problem("document #{definition} is declared but not published. Run " \
+                       "`bin/rails clickwrap:publish`.")
+      end
+
+      return nil if version.verify_content_digest
+
+      problem("the stored bytes for document #{definition} no longer match the digest recorded " \
+              "when it was published, so evidence citing it cannot be reproduced")
+    end
+
+    # A default install emits only the tables it can put a row in; each further
+    # capability brings its own migration. So this reports two different facts,
+    # and never conflates them: a capability that is ON with its tables missing
+    # is a problem with a command attached, and a capability that is simply not
+    # installed is a fact about this installation, stated once so an operator
+    # reading at 03:00 does not go looking for a table that was never meant to
+    # be there.
+    def optional_table_findings
+      SchemaRequirements.reset!
+      missing = SchemaRequirements.missing_for_configuration
+
+      SchemaRequirements::FEATURES.map do |feature|
+        installed = SchemaRequirements.installed?(feature)
+
+        if installed.nil?
+          warning("could not check whether the #{feature.flag} tables exist (no database)")
+        elsif installed
+          ok("the #{feature.flag} tables are installed")
+        elsif missing.include?(feature)
+          problem(feature.explanation)
+        else
+          ok("the #{feature.flag} tables are not installed, and nothing configured needs them")
+        end
+      end
+    end
+
+    # The mount is not only about gates. Every presentation links each document
+    # at its immutable engine route, and that link is signed into the manifest
+    # and kept as the exact document the person was offered. Unmounted, there
+    # is no such route: presenting refuses rather than signing a dead link, so
+    # a compiled policy on an unmounted application is a broken signup screen,
+    # not a stylistic choice.
+    def engine_mount_findings
+      return [] if Clickwrap.policies.empty?
+      return [ok("Clickwrap::Engine is mounted, so every document link a presentation signs resolves")] \
+        if engine_mounted?
+
+      [problem("Clickwrap::Engine is not mounted, so presenting any of the " \
+               "#{Clickwrap.policies.size} compiled #{pluralize(Clickwrap.policies.size, "policy",
+                                                                "policies")} refuses rather than " \
+               "sign a document link that resolves to nothing. Mount it with " \
+               "`mount Clickwrap::Engine => \"/agreements\"`, or bind your own document route into " \
+               "every presentation with `document_version_path_with:`.")]
+    end
+
+    # A `requires_clickwrap` gate refuses to compile without somewhere to send
+    # the person it stops, so the objective question left for the doctor is
+    # whether the engine — the default destination — is actually mounted.
+    def gate_findings
+      return [ok("every required gate has a remediation route (Clickwrap::Engine is mounted)")] if engine_mounted?
+
+      [warning("Clickwrap::Engine is not mounted, so every `requires_clickwrap` gate needs its own " \
+               "`remediation_path:`. Mount it with `mount Clickwrap::Engine => \"/agreements\"` or " \
+               "point each gate at a page you own.")]
+    end
+
+    def engine_mounted?
+      ControllerHelpers.engine_is_mounted?
+    rescue StandardError
+      false
+    end
+
+    def request_evidence_findings
+      config = Clickwrap.config
+
+      if config.records_any_request_evidence_by_default?
+        return [warning("request-derived personal data is recorded by default for every policy " \
+                        "(#{default_categories.join(", ")}). That is a decision worth re-reading: " \
+                        "a policy that does not need an IP address still gets one.")]
+      end
+
+      [ok("request-derived personal data is off by default")]
+    end
+
+    def default_categories
+      config = Clickwrap.config
+      categories = []
+      categories << "ip_address" if config.record_ip_address_by_default
+      categories << "browser_user_agent" if config.record_browser_user_agent_by_default
+      geolocation = config.enabled_default_ip_geolocation_fields
+      categories << "ip_geolocation #{geolocation.join("/")}" if geolocation.any?
+      categories
+    end
+
+    # A policy that keeps a person's IP address or estimated city with no date
+    # on which somebody looks at that decision again is how a temporary
+    # measure becomes permanent. The date is the host's; the doctor only
+    # notices its absence — for EVERY collected category, not only
+    # geolocation: an IP address past its review date is exactly as overdue
+    # as a city would be.
+    def review_date_findings
+      Clickwrap.policies.values.filter_map do |policy|
+        request_evidence = policy.request_evidence
+        collected = collected_request_evidence_categories(request_evidence)
+        next if collected.empty?
+
+        review_on = request_evidence.review_configuration_on
+
+        if review_on.nil?
+          warning("#{policy.key} records #{collected.join(", ")} without a review date. Add " \
+                  "`review_request_evidence_configuration_on` so this decision gets looked at again.")
+        elsif past?(review_on)
+          warning("#{policy.key} was due to have its request-evidence configuration " \
+                  "(#{collected.join(", ")}) reviewed on #{review_on}, and that date has passed")
+        end
+      end + default_review_date_findings
+    end
+
+    def collected_request_evidence_categories(request_evidence)
+      categories = []
+      categories << "ip_address" if request_evidence.records_ip_address?
+      categories << "browser_user_agent" if request_evidence.records_browser_user_agent?
+      if request_evidence.records_ip_geolocation?
+        categories << "ip_geolocation #{request_evidence.enabled_ip_geolocation_fields.join("/")}"
+      end
+      categories
+    end
+
+    def default_review_date_findings
+      config = Clickwrap.config
+      return [] unless config.records_any_request_evidence_by_default?
+
+      review_on = config.review_default_request_evidence_configuration_on
+
+      if review_on.nil?
+        [warning("request evidence is recorded by default with no " \
+                 "`review_default_request_evidence_configuration_on` date")]
+      elsif past?(review_on)
+        [warning("the default request-evidence configuration was due for review on #{review_on}, " \
+                 "and that date has passed")]
+      else
+        []
+      end
+    end
+
+    def resolver_findings
+      configured = Clickwrap.config.ip_geolocation_resolver
+      wanted = Clickwrap.policies.values.select { |policy| policy.request_evidence.records_ip_geolocation? }
+
+      if configured.nil?
+        return [ok("no IP-geolocation resolver is configured, and no policy asks for one")] if wanted.empty?
+
+        # A warning rather than a problem: capture still succeeds and the field
+        # is recorded as unavailable with a reason, which is the honest outcome.
+        # What it is not is what the policy asked for, so somebody should know.
+        return [warning("#{wanted.map(&:key).join(", ")} records IP geolocation but no " \
+                        "`ip_geolocation_resolver` is configured, so every capture will record it " \
+                        "as unavailable")]
+      end
+
+      [ok("an IP-geolocation resolver is configured (#{configured.class.name})")]
+    end
+
+    # An IP address read from a forwarded header is only as good as the proxy
+    # configuration in front of it. Clickwrap cannot check a host's Cloudflare,
+    # load balancer, or `config.hosts` setup; what it can check is whether the
+    # host ever recorded that they verified one.
+    def source_trust_findings
+      records_ip_address = Clickwrap.config.record_ip_address_by_default ||
+                           Clickwrap.policies.values.any? { |policy| policy.request_evidence.records_ip_address? }
+      return [] unless records_ip_address
+
+      if Clickwrap.config.trusted_proxy_configuration_digest.blank?
+        return [warning("request-source trust is unverified: IP addresses are recorded, but no " \
+                        "`trusted_proxy_configuration_digest` is set, so nothing records which " \
+                        "proxy configuration (Cloudflare, a load balancer, a CDN) the addresses " \
+                        "were read through")]
+      end
+
+      [ok("a reviewed trusted-proxy configuration digest is recorded with each recorded IP address")]
+    end
+
+    # --- Data -----------------------------------------------------------------
+
+    def disposition_findings
+      now = Clickwrap.now
+      overdue = Event.due_for_core_disposition(now).count +
+                RequestEvidence.with_ip_address_due(now).count +
+                RequestEvidence.with_browser_user_agent_due(now).count +
+                RequestEvidence.with_ip_geolocation_due(now).count
+
+      return [ok("no overdue disposition")] if overdue.zero?
+
+      [warning("#{overdue} #{pluralize(overdue, "record is", "records are")} past a retention rule " \
+               "and still here. Run `bin/rails clickwrap:retention:plan`, review it, then " \
+               "`bin/rails clickwrap:retention:apply PLAN=...`.")]
+    end
+
+    def legal_hold_findings
+      in_effect = LegalHold.in_effect.count
+      due = LegalHold.due_for_review(Clickwrap.now).count
+
+      return [ok("no legal holds are in effect")] if in_effect.zero?
+
+      if due.zero?
+        return [ok("#{in_effect} legal #{pluralize(in_effect, "hold", "holds")} in effect, none past review")]
+      end
+
+      [warning("#{due} legal #{pluralize(due, "hold is", "holds are")} past the review date they " \
+               "were placed with. A hold nobody revisits is how everything gets kept forever.")]
+    end
+
+    def digest_findings
+      events = Event.order(id: :desc).limit(DIGEST_SAMPLE_SIZE).to_a
+      return [ok("no events recorded yet")] if events.empty?
+
+      by_status = events.group_by(&:digest_integrity_status)
+      failed = by_status.fetch(:unaccounted_mismatch, [])
+
+      if failed.empty?
+        dispositions = by_status.fetch(:documented_core_disposition, []).length
+        verifying = by_status.fetch(:verified, []).length
+
+        return [ok("all #{events.length} checked event digests verify")] if dispositions.zero?
+
+        return [ok("#{verifying} checked event digests verify and #{dispositions} " \
+                   "#{pluralize(dispositions, "core disposition is", "core dispositions are")} " \
+                   "documented by valid linked events; no mismatch is unexplained")]
+      end
+
+      [problem("#{failed.length} of #{events.length} checked event digests do not match the bytes " \
+               "they cover and have no valid linked disposition event (first: #{failed.first.id}). " \
+               "That means those rows changed after they were written or carry an unexplained " \
+               "disposition marker; it does not on its own say who changed them.")]
+    end
+
+    def external_action_findings
+      unresolved = ExternalAction.unresolved.count
+      return [ok("no unresolved external actions")] if unresolved.zero?
+
+      stale = ExternalAction.needing_reconciliation.count
+
+      [warning("#{unresolved} external #{pluralize(unresolved, "action is", "actions are")} still " \
+               "pending or unknown (#{stale} older than 15 minutes). Run " \
+               "`bin/rails clickwrap:reconcile_external_actions` to list them.")]
+    end
+
+    def integrity_attestation_findings
+      counts = Integrity::AttestationReconciler.missing_counts
+      return [ok("no external integrity attestation adapters are configured")] if counts.empty?
+
+      missing = counts.sum { |_, count| count }
+      return [ok("every eligible event has an attestation attempt from each configured adapter")] if missing.zero?
+
+      details = counts.filter_map do |kind, count|
+        "#{count} #{kind.tr("_", " ")}" unless count.zero?
+      end.join(", ")
+
+      [warning("#{missing} configured integrity #{pluralize(missing, "attestation attempt is",
+                                                            "attestation attempts are")} " \
+               "missing (#{details}). Run `bin/rails clickwrap:integrity:attest_missing`; this can " \
+               "call external providers and does not change the committed evidence event.")]
+    end
+
+    # --- Plumbing -------------------------------------------------------------
+
+    # Half of what the doctor checks needs the database, and the reason someone
+    # is running it at 03:00 may well be that the database is unhappy. A failed
+    # check reports what it could not read instead of taking the whole report
+    # down with it.
+    def with_database(what)
+      yield
+    rescue StandardError => error
+      [warning("could not check #{what}: #{error.class}. #{error.message}")]
+    end
+
+    def past?(date)
+      return false if date.nil?
+
+      date.to_time <= Clickwrap.now
+    rescue StandardError
+      false
+    end
+
+    def pluralize(count, singular, plural) = count == 1 ? singular : plural
+
+    def ok(message) = Finding.new(status: :ok, message: message)
+    def warning(message) = Finding.new(status: :warning, message: message)
+    def problem(message) = Finding.new(status: :problem, message: message)
+  end
+end

data/lib/clickwrap/document_definition.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # A declared document version, before it is published.
+  #
+  #   Clickwrap.document :terms,
+  #     from: Rails.root.join("app/content/legal/terms.md")
+  #
+  #   Clickwrap.document :terms,
+  #     version: "2026-08-15",
+  #     locale: :en,
+  #     effective_at: Time.utc(2026, 8, 15),
+  #     from: Rails.root.join("app/content/legal/terms.en.md")
+  #
+  #   Clickwrap.document :terms,
+  #     from: Rails.root.join("app/content/legal/terms.md"),
+  #     link: "/legal/terms"
+  #
+  # `link:` is where a PERSON reads this document — the host's own formatted
+  # page, with its typography, its navigation, and its language switcher —
+  # rather than the engine's plain rendering of the published bytes. It is the
+  # path Clickwrap presents beside the control AND the path it signs into the
+  # presentation manifest, so the evidence never cites a different target from
+  # the link somebody could actually press.
+  #
+  # The trade is explicit and belongs to the host: a host page shows whatever
+  # is current, so the signed path is a stable address rather than an immutable
+  # snapshot. The bytes are still frozen, digested, and recorded — what changes
+  # is which URL the receipt says was offered. A host that wants the immutable
+  # rendering in the evidence simply leaves `link:` off and gets the engine's
+  # per-version route, as before.
+  #
+  # The declaration says which bytes to publish. `bin/rails clickwrap:publish`
+  # reads them once, digests them, and freezes a database snapshot. From then
+  # on the snapshot is the evidence; the file on disk is only where it came
+  # from. Changing the file does not change published evidence, and reusing a
+  # version label for different bytes is refused rather than silently accepted.
+  #
+  # `version:` is optional exactly when the source can name its own: a file or
+  # inline content whose leading YAML front matter carries `clickwrap_version:`
+  # (or `last_updated:`) IS the single source of truth for its label, so
+  # bumping a legal text is one edit in one file. A source with no front-matter
+  # version and no explicit `version:` is refused at boot with a sentence —
+  # Clickwrap never invents a label, because a policy that requires a current
+  # version cannot be satisfied by a guess.
+  class DocumentDefinition
+    SOURCE_KINDS = %i[file inline resolver].freeze
+
+    MEDIA_TYPES_BY_EXTENSION = {
+      ".md" => "text/markdown",
+      ".markdown" => "text/markdown",
+      ".html" => "text/html",
+      ".htm" => "text/html",
+      ".txt" => "text/plain",
+      ".json" => "application/json",
+      ".pdf" => "application/pdf"
+    }.freeze
+
+    REFUSED_VERSION_LABELS = %w[unversioned current latest head none default].freeze
+
+    # A `link:` is rendered as an href and signed into evidence, so it has to be
+    # somewhere a browser can navigate. Anything else — `javascript:`, `data:`,
+    # a bare word — would be a scheme the gem itself painted into a page.
+    LINK_SCHEMES = %r{\A(?:/[^/]|/\z|https://|http://)}
+
+    attr_reader :key, :version_label, :locale, :media_type, :effective_at,
+                :tenant_key, :source_kind, :source_reference, :inline_content,
+                :resolver, :renderer, :link
+
+    def initialize(key:, version: nil, locale: :en, media_type: nil, effective_at: nil,
+                   tenant: nil, from: nil, content: nil, resolver: nil, renderer: nil,
+                   link: nil)
+      @key = normalize_key(key)
+      @locale = locale.to_s
+      @effective_at = effective_at
+      @tenant_key = tenant&.to_s
+      @renderer = renderer
+      @link = normalize_link(link)
+
+      assign_source(from:, content:, resolver:)
+      @version_label = normalize_version(version || version_label_from_front_matter)
+      @media_type = (media_type || infer_media_type).to_s
+
+      validate!
+      freeze
+    end
+
+    # Reads the exact bytes this definition points at. Called at publish time,
+    # never at export time: an export that re-read a mutable source and called
+    # the result historical evidence would be a lie.
+    def read_bytes
+      case source_kind
+      when :inline then inline_content.to_s.dup
+      when :file then read_file_bytes
+      when :resolver then read_resolver_bytes
+      end
+    end
+
+    def identity = [tenant_key, key, version_label, locale]
+
+    def to_s
+      "#{key} #{version_label} (#{locale})"
+    end
+
+    private
+
+    def assign_source(from:, content:, resolver:)
+      provided = { from:, content:, resolver: }.compact
+
+      if provided.length > 1
+        raise DefinitionError,
+              "Document #{key} #{version_label} declares #{provided.keys.join(" and ")}. " \
+              "Give it exactly one source."
+      end
+
+      if from
+        @source_kind = :file
+        @source_reference = from.to_s
+      elsif content
+        @source_kind = :inline
+        @inline_content = content.to_s
+        @source_reference = "inline"
+      elsif resolver
+        @source_kind = :resolver
+        @resolver = resolver
+        @source_reference = "resolver"
+      else
+        raise DefinitionError,
+              "Document #{key} #{version_label} has no source. Use `from:` with a path, " \
+              "`content:` with a string, or `resolver:` with something that returns bytes."
+      end
+    end
+
+    def read_file_bytes
+      unless File.exist?(source_reference)
+        raise DocumentNotPublishedError,
+              "Document #{self} points at #{source_reference}, which does not exist."
+      end
+
+      File.binread(source_reference)
+    end
+
+    # No explicit `version:` was given, so the source itself must name one
+    # through its leading YAML front matter. Every refusal here is a boot
+    # failure with the fix in the sentence, because a silently invented label
+    # would let "unversioned" evidence masquerade as versioned.
+    def version_label_from_front_matter
+      case source_kind
+      when :file then file_front_matter_version_label
+      when :inline then inline_front_matter_version_label
+      else
+        raise DefinitionError,
+              "Document #{key} has no `version:`, and a `resolver:` source cannot name its own " \
+              "version at boot because its bytes are only read at publish time. Pass `version:` " \
+              "explicitly, for example version: \"2026-08-15\"."
+      end
+    end
+
+    def file_front_matter_version_label
+      unless File.exist?(source_reference)
+        raise DefinitionError,
+              "Document #{key} has no `version:` and its file #{source_reference} does not " \
+              "exist yet, so there is no front matter to read one from. Create the file with a " \
+              "`clickwrap_version:` or `last_updated:` front-matter key, or pass `version:` " \
+              "explicitly."
+      end
+
+      FrontMatter.version_label_in(File.read(source_reference)) ||
+        raise(DefinitionError,
+              "Document #{key} has no `version:` and #{source_reference} has no " \
+              "`clickwrap_version:` or `last_updated:` front-matter key. The version label has " \
+              "no other source of truth — add one of those keys to the file's front matter " \
+              "(`clickwrap_version:` wins when both are present), or pass `version:` explicitly.")
+    end
+
+    def inline_front_matter_version_label
+      FrontMatter.version_label_in(inline_content) ||
+        raise(DefinitionError,
+              "Document #{key} has no `version:` and its inline `content:` has no " \
+              "`clickwrap_version:` or `last_updated:` front-matter key. Add one to the " \
+              "content's leading front matter, or pass `version:` explicitly.")
+    end
+
+    def read_resolver_bytes
+      bytes = resolver.respond_to?(:call) ? resolver.call(self) : resolver.read(self)
+
+      if bytes.nil? || bytes.to_s.empty?
+        raise DocumentNotPublishedError,
+              "The resolver for document #{self} returned no bytes."
+      end
+
+      bytes.to_s
+    end
+
+    def infer_media_type
+      return "text/plain" unless source_kind == :file
+
+      MEDIA_TYPES_BY_EXTENSION.fetch(File.extname(source_reference).downcase, "text/plain")
+    end
+
+    def normalize_key(value)
+      normalized = value.to_s
+      raise DefinitionError, "A document needs a key, for example :terms" if normalized.empty?
+
+      normalized
+    end
+
+    # A version label is the application's own name for a frozen set of bytes.
+    # Clickwrap does not interpret it — a date, a semantic version, and a git
+    # SHA are all fine — but it refuses the placeholder labels applications
+    # reach for when they have not really versioned anything, because a policy
+    # that requires a current version cannot be satisfied by "unversioned".
+    def normalize_version(value)
+      normalized = value.to_s.strip
+
+      if normalized.empty?
+        raise DefinitionError,
+              "Document #{key} needs a `version:` label, for example \"2026-08-15\"."
+      end
+
+      if REFUSED_VERSION_LABELS.include?(normalized.downcase)
+        raise DefinitionError,
+              "Document #{key} cannot use the version label #{normalized.inspect}: it names a " \
+              "moving target rather than a frozen set of bytes. Use a date, a release tag, or " \
+              "any label you will never reuse for different content."
+      end
+
+      normalized
+    end
+
+    def normalize_link(value)
+      return nil if value.nil?
+
+      normalized = value.to_s.strip
+      return nil if normalized.empty?
+
+      unless normalized.match?(LINK_SCHEMES)
+        raise DefinitionError,
+              "Document #{key} has a `link:` of #{value.inspect}. A link is the page a person " \
+              "reads this document on, so it must be a root-relative path (\"/legal/terms\") or " \
+              "an absolute http(s) URL. Clickwrap renders it as an href and signs it into the " \
+              "presentation manifest, and it will not sign a scheme it cannot navigate to."
+      end
+
+      normalized.freeze
+    end
+
+    def validate!
+      return unless effective_at && !effective_at.respond_to?(:to_time)
+
+      raise DefinitionError,
+            "Document #{self} has an `effective_at:` that is not a time."
+    end
+  end
+end