clickwrap 0.0.0 → 0.1.0

data/guides/integrity.md

@@ -0,0 +1,212 @@
+# Integrity: five tiers and what each one actually detects
+
+Clickwrap starts useful with an ordinary Rails database and lets serious applications add
+assurance without changing the capture API. What does not change with the tier is the
+vocabulary: each tier states exactly what it detects, and the receipt prints that sentence
+itself so nobody has to infer it from a green check mark.
+
+## Three things that are not the same thing
+
+This is the section to read before the tier table, because most overclaims start by blurring
+these together.
+
+**SHA-2 is a hash standard.** It says nothing about who computed a digest, when, or whether
+they were entitled to. [NIST FIPS 180-4](https://csrc.nist.gov/pubs/fips/180-4/upd1/final)
+*(technical standard)*. A hash is not a signature, not an identity, and not a time source.
+
+**RFC 3161 is a time-stamp protocol.** A time-stamp authority returns a token over a digest you
+gave it. What that token is worth depends entirely on that authority, its practice statement,
+its certificate status, and what a reader is willing to accept about it.
+[RFC 3161](https://www.rfc-editor.org/info/rfc3161/) *(technical standard)*.
+
+**eIDAS is a regulation about the legal effect of electronic signatures and seals.** Article 25
+assigns a distinct effect to signatures at its qualified level, which is a different thing
+again from a hash and from a timestamp token.
+[Regulation (EU) No 910/2014, Article 25](https://eur-lex.europa.eu/eli/reg/2014/910/2024-05-20/eng)
+*(law)*. Whether a given provider's output has that effect is a question about that provider,
+not about this gem.
+
+Two consequences that hold everywhere in Clickwrap:
+
+- **A local hash detects modification of the bytes it covers, and nothing more.** It does not
+  establish who produced those bytes, when, or that a party controlling both the application
+  and the database could not have written the record and its digest together. The baseline
+  receipt says exactly that, in the receipt.
+- **`recorded_at_by_server` is the application server's own clock.** It is called that
+  everywhere — in the column name, in the receipt, in the API — precisely so it is never
+  mistaken for a time attested by a third party. Clickwrap has no method, field, or option
+  named `signed_at`. A timestamp authority supplies something different, and when one is
+  configured its token and its own reported time are stored and labeled as the provider's.
+
+---
+
+## The five tiers
+
+| Tier | What you turn on | The exact claim |
+|---|---|---|
+| **Baseline** | Nothing. `config.digest_canonical_receipts_with = :sha256` is the default | The recorded digest detects accidental or ordinary modification of the bytes it covers. It does not establish who produced them, when, or that a party controlling both the application and the database could not have written both the record and the digest |
+| **Database hardening** | `bin/rails generate clickwrap:hardening --database` and a migration | Rejects unsupported mutation paths within the documented database threat model. On PostgreSQL this is real update and delete protection; on SQLite and MySQL the generator says plainly what the database can and cannot reject rather than emitting something that looks like protection and is not |
+| **Chained history** | `config.chain_event_history_with = :sha256` | Each event carries the digest of the one before it, so an event later rewritten or removed stops linking up with its successors. This makes a rewrite of history detectable for as long as the chain head remains trustworthy — and no more than that |
+| **Independent anchoring** | `config.anchor_event_history_with = MyAnchor.new` | The exact chain scope, sequence, event ID, and event digest committed for each event are offered to an outside publication service. The tier upgrades only when the adapter records and verifies that exact snapshot; the claim is only ever as strong as the publication and its verifier |
+| **Timestamp or trust-service provider** | `config.timestamp_receipts_with = MyRfc3161Provider.new` | Preserves exactly the assurance and validation status that provider supplies, verbatim. If the provider's own status is "unknown" or "expired", that is what travels into the receipt |
+
+Three notes on the honest edges of that table.
+
+**Chaining does not stop a fully privileged actor.** Whoever can write the events table can
+usually write the chain-head table too, and a head living in the same database as the chain
+cannot say otherwise. What the chain reliably catches is ordinary corruption, a well-meant
+`update_column`, a restored partial backup, and a row edited by hand — which is most of what
+actually goes wrong. It is precisely the remaining gap that the anchor adapter addresses.
+
+**Anchoring and timestamps are adapter contracts, not bundled providers.** Both configuration
+settings default to `nil`, so no provider call or attestation row exists until the host chooses
+an adapter. `Clickwrap::Integrity::Anchor` and `Clickwrap::Integrity::Timestamp` are reference
+base classes with explicit unavailable results; they are not installed implicitly. Clickwrap
+ships no RFC 3161 client — no ASN.1 encoder, no HTTP client, no certificate-chain validation —
+and adds no dependency that would. A host that needs one supplies an adapter that speaks to its
+chosen service.
+
+**The receipt's `integrity.tier` reports recorded, verified evidence — never configuration
+alone.** It is `third_party_timestamp` only when an independently-verifiable timestamp
+attestation over the event digest verifies; otherwise `external_event_anchoring` only when an
+outside-publication attestation over the exact chain snapshot verifies; otherwise
+`chained_history` when the event carries a chain scope; otherwise `baseline`. Database
+hardening is checked separately by `bin/rails clickwrap:doctor`. Unavailable, failed, and issued
+but unverified provider results remain visible in `integrity.attestations` without upgrading the
+tier.
+
+Enable what you need, explicitly:
+
+```ruby
+config.digest_canonical_receipts_with = :sha256   # or :sha384, :sha512
+config.chain_event_history_with       = :sha256
+config.anchor_event_history_with      = MyIndependentAnchor.new
+config.timestamp_receipts_with        = MyRfc3161TimestampProvider.new
+```
+
+Every digest stored anywhere carries its algorithm name as an `"<algorithm>:<hex>"` prefix, so
+a future release can add an algorithm without making old events unverifiable, and an auditor
+never has to guess which function produced a bare hex string.
+
+### External attestations happen after commit
+
+Timestamp and anchor providers cannot participate in the database transaction that records the
+event and the protected host action. Clickwrap therefore calls them after commit. A provider
+outage cannot undo a capture that already committed. Each ordinary result — `verified`,
+`issued_unverified`, or `unavailable` — becomes an immutable attestation row. An adapter
+exception becomes a `failed` row when the database is available and is also reported through
+`report_after_commit_failure_with`.
+
+There is one unavoidable crash window: a process can die after the event commits, or after a
+provider accepts a request but before the local attestation row commits. Inventory missing
+attempts with `clickwrap:doctor`, then reconcile them explicitly:
+
+```bash
+bin/rails clickwrap:integrity:attest_missing
+bin/rails clickwrap:integrity:attest_missing SINCE=2026-08-15T00:00:00Z LIMIT=100
+bin/rails clickwrap:integrity:attest_missing RETRY_FAILED_ATTESTATIONS=1
+```
+
+The task may call external providers. It skips events that already have a result; failed results
+are retried only with `RETRY_FAILED_ATTESTATIONS=1`. This is at-least-once recovery, not
+exactly-once delivery: if the provider accepted a request before the process died, a retry can
+create another valid provider record. Timestamp adapters should use the event digest, and anchor
+adapters the exact chain snapshot, as their provider-side idempotency input. Clickwrap preserves
+every result rather than claiming certainty it cannot have.
+
+Run verification continuously rather than at audit time:
+
+```bash
+bin/rails clickwrap:verify
+bin/rails clickwrap:verify EVENT_ID
+```
+
+---
+
+## Threat model: what happens if
+
+Each row is a scenario the design has to survive, drawn from the product threat model. "What
+Clickwrap does" is a statement about mechanism, not a guarantee about outcomes.
+
+### The submitted request
+
+| What happens if | What Clickwrap does |
+|---|---|
+| A crafted POST names a different policy, document, version, validity, or purpose | None of those are client inputs. The browser receives a signed presentation token and returns answers; the policy key, revision, document versions, validity window, subject binding, retention rule, and request-evidence fields are resolved server-side and rechecked inside the transaction |
+| A stale presentation is submitted after a deploy | The manifest binds the render to the submit. A token issued against an older revision is rejected with `presentation_invalid` or `presentation_expired`, so a deploy between GET and POST never records a version the actor was not offered |
+| An attacker swaps the actor, subject, or tenant inside a token | Each binding is checked: `presentation_actor_mismatch`, `presentation_subject_mismatch`, `presentation_tenant_mismatch`, plus `wrong_actor` / `wrong_subject` / `wrong_tenant` at verification |
+| A double-click or a replay creates a duplicate event or a second protected action | Idempotency keys and subject locks are acquired inside the transaction. An identical key returns the original result without running the block twice, even when the first success changed the fingerprinted subject; the replay is checked against the frozen committed event. A conflicting replay fails with a stable `replay_rejected` |
+| CSRF, session fixation, or a cross-account submission | Rails' own CSRF, session, and authentication protections remain host responsibilities. Clickwrap adds the actor/tenant/subject binding checks above on top of them |
+
+### The data at rest
+
+| What happens if | What Clickwrap does |
+|---|---|
+| A privileged application or database actor updates or deletes evidence | Events, statements, and document bindings refuse ordinary updates and destroys at the model layer. Four event columns have named mutable roles (`core_event_disposed_at`, `core_event_disposition_event_id`, `on_legal_hold`, `request_evidence_id`); reviewed core disposition also clears a fixed payload write set while atomically appending its digest-linked disposition event. Optional database hardening pushes the documented write sets into PostgreSQL. Neither stops somebody with full database access; digest/chain verification detects covered changes, and a verified outside publication narrows the gap further |
+| A fully privileged actor rewrites the hash chain along with the events | The chain alone cannot detect this, and this guide says so rather than implying otherwise. That is what the independent anchor adapter is for, and the claim is then only as strong as the anchor |
+| Signing or encryption keys rotate, or leak | Keys come from Rails credentials or a host key provider, and rotate with versioned key identifiers. The annex binding digest records its algorithm and a key identifier so a later reader can tell which key produced it |
+| The server clock is wrong | Nothing here can fix that, and nothing here pretends to. `recorded_at_by_server` is labeled as the server's clock. A timestamp provider is the mechanism that adds a second, independent opinion about time |
+| Algorithm or canonicalization changes make old events unreadable | Released formats are permanent: `KNOWN_SCHEMAS` only grows, a format change means a new explicit schema plus a verifier branch, and every previously released format keeps verifying. See [the golden-fixture policy](receipts-and-verification.md#the-golden-fixture-policy) |
+| A mutable document source changes behind a version label | Publishing reads exact bytes and refuses to reuse a version label for different bytes. Export never fetches a live URL and calls it historical evidence. Event documents carry the digests as they stood at capture, so a document row edited in place is a detectable finding rather than a silent substitution |
+
+### The optional request evidence
+
+| What happens if | What Clickwrap does |
+|---|---|
+| A spoofed `X-Forwarded-For` or `CF-*` header is recorded as trusted evidence | The reader is host-configured and the receipt records which reader ran. A value containing a comma is refused outright rather than stored as an observation. Cloudflare-derived fields are marked host-verified only when the host explicitly asserts a verified path. See [the trusted-proxy section](request-evidence.md#trusted-proxies-and-why-requestremote_ip-alone-is-not-enough) |
+| Client parameters masquerade as server-observed values | The form helper renders no hidden field for any of them, and submitted keys with those names are ignored. A native or API client's values stay labeled `client_reported_*` forever |
+| IP-derived coordinates are presented as a physical location, or used to pick governing law | Every stored estimate carries `was_estimated`, its provider, its resolution time, and any accuracy metadata, and the receipt prints a sentence saying it is one provider's estimate about an address. Clickwrap never infers jurisdiction, law, or eligibility from geolocation |
+| An opaque profile switch quietly enables new personal-data fields after an upgrade | There is no such switch. Every field is its own named setting, and enabling one never enables another category |
+| Geolocation is retained without its provenance, or presented as several independent proofs | Provenance is not a policy choice: provider, source, estimated status, resolution time, and any accuracy or database metadata travel with any stored result and with any failure to produce one. Provider-derived country, region, city, postal code, and coordinates are one correlated estimate, not independent witnesses |
+| A raw IP address or user-agent leaks through logs, errors, metrics, or a default export | Values are encrypted at rest by default, excluded from ordinary logs and metrics, absent from default exports, and never included in exception messages — a `fail_if_unavailable` error names the policy, the category, and the reason, never the value. OWASP's guidance on protected logging, sensitive-data discipline, and retention controls is the reference point ([Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)) *(vendor/industry guidance)* |
+| Personal request evidence is buried so deep in immutable payloads that required deletion is impossible | It is not in the immutable payload at all. The annex is a separate table with its own schedule, and the event's canonical body excludes every annex value, so deletion cannot break verification |
+
+### Retention and lifecycle
+
+| What happens if | What Clickwrap does |
+|---|---|
+| Deleting an actor cascades and destroys the evidence | `has_clickwraps` adds no `dependent: :destroy`. The actor link nullifies and a stable pseudonymous reference remains |
+| A retention job destroys held records, or keeps excess metadata | Every deletion path re-checks event, actor, and policy holds immediately before writing, and the applier re-derives eligibility rather than trusting the plan. Deletion nulls the value columns only, keeping the provenance that documents the deletion |
+| A fixed-duration job deletes regulated evidence before a host event such as liquidation starts the clock | Event-based rules exist for exactly this. A host calculation returning `nil` is reported as `unresolved`, never as due. See [the retention guide](retention-and-legal-holds.md#why-a-duration-alone-is-not-enough) |
+| An external provider succeeds but the response is lost | The outbox path records `record_provider_outcome_unknown!` as a distinct state from success and failure, and reconciliation resolves it later. A timeout never becomes a fictional success or a second debit |
+
+### The presentation and the surrounding page
+
+| What happens if | What Clickwrap does |
+|---|---|
+| A custom view removes the real control, or moves the notice below the call to action | The development linter reports `submit_control_before_clickwrap_block`, `consent_control_preselected`, and `document_link_missing`. These are heuristics that warn; they never block a render and never certify a page. See [the accessibility guide](accessibility.md) |
+| An analytics, notification, timestamp, or anchor call fails | After-commit work is an observer, never authorization. A failure is reported through `report_after_commit_failure_with` and cannot undo evidence and domain state that already committed. Timestamp/anchor attempts additionally record an immutable result when possible; the missing-attestation inventory and explicit reconciliation task cover a process or database failure in that post-commit window |
+| An export leaks a document, actor detail, or request secret | Operator access requires a host authorization callback plus a plain-English reason, and every access appends a `ReceiptAccess` row. Foreign event IDs return not found, so existence is not leaked |
+
+---
+
+## What to tell an auditor
+
+Say the tier, say its sentence, and say what is not in it.
+
+At baseline, that is: canonical receipts, immutable document and statement snapshots while their
+reviewed retention periods run, versioned SHA-256 digests, an append-oriented public API with
+named disposition transitions, and a verifier that runs without this application. It detects
+modification of the bytes it covers. It does not establish origin, does not establish time, and
+does not exclude fabrication by a party controlling every source.
+
+If you need stronger rewrite detection or a third party's statement about time, the mechanisms
+are chained history, a verified publication of exact chain snapshots, and a timestamp or
+trust-service provider — three separate things, each claiming only what it supplies.
+
+`bin/rails clickwrap:doctor` reports objective configuration and data facts and never prints a
+verdict. If it printed one, it would be the least trustworthy line in the output.
+
+---
+
+## Sources
+
+| Source | Class |
+|---|---|
+| [NIST FIPS 180-4](https://csrc.nist.gov/pubs/fips/180-4/upd1/final) — SHA-2 hash standard | Technical standard |
+| [RFC 3161](https://www.rfc-editor.org/info/rfc3161/) — time-stamp protocol | Technical standard |
+| [Regulation (EU) No 910/2014 (eIDAS), Article 25](https://eur-lex.europa.eu/eli/reg/2014/910/2024-05-20/eng) — legal effect of electronic signatures | Law |
+| [RFC 8785, JSON Canonicalization Scheme](https://www.rfc-editor.org/rfc/rfc8785) | Technical standard |
+| [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html) | Industry guidance |
+| [GDPR Article 32](https://eur-lex.europa.eu/eli/reg/2016/679/art_32/oj/eng) — security of processing | Law |
+| The tier ladder and every "what Clickwrap does" cell above | Product-design inference |

data/guides/migrating.md

@@ -0,0 +1,335 @@
+# Migrating without inventing history
+
+Importing is the single easiest place in this gem to manufacture evidence by accident. Every
+field a modern capture fills in is sitting right there with an obvious, plausible value: the
+current Terms text, today's document digest, the submit-button label from the current view, the
+assertion sentence from the current policy, an IP address from the user's last session.
+
+Writing any of them produces a row that is **indistinguishable from a real capture** and is, in
+the parts that matter, a fabrication. Nobody reading the receipt in a dispute three years from
+now would be able to tell.
+
+So the governing rule for every import path is: historical weakness stays visible rather than
+being laundered into modern certainty. An honest gap is worth more than a confident invention,
+because the gap is a fact about the evidence and the invention is a lie about it.
+
+---
+
+## What is never synthesized
+
+| Field | Why it cannot be filled in |
+|---|---|
+| The presentation manifest | Nobody signed one. There is no offer to reproduce, and a synthesized manifest would be a signed description of an offer nobody made |
+| The assertion | The sentence the old application generated or offered was not recorded. Using the current policy's wording would claim it offered text that may not have existed yet |
+| Submit-button text | The words on the control were not recorded |
+| IP address, browser user-agent, IP geolocation | These were never observed by this application. A later session's address is a different fact about a different request |
+| Document bytes and digests | Only linked when the caller can point at a version that is **actually published here**. A version label alone is a claim about a label, not about content |
+| The protected action | The old system did not bind evidence to an outcome |
+
+Every key you list in `unknown:` is recorded twice: as a structured field on the event, and in
+plain words inside the assertion text of each statement — which is inside the digested canonical
+body, so the admission travels *with* the evidence rather than beside it where it can be lost.
+
+Two more things the importer keeps apart on purpose:
+
+- **`occurred_at` and `recorded_at_by_server`.** The first is when the old record says it
+  happened; the second is when this row was written. Collapsing them would quietly upgrade a
+  migration into a contemporaneous observation. The distance between the two is itself evidence.
+- **Attribution.** An imported event records `imported_provider`, never `authenticated_session`
+  and never `unknown`. "This reached us from somewhere else" is a different fact from "we do not
+  know how they were attributed."
+
+An import can never claim `web_browser` as its capture channel. The permitted values are
+`imported_provider` and `system`, because no browser was involved and a receipt saying otherwise
+would be wrong.
+
+---
+
+## From `accepted_terms_at`
+
+The typical starting point is a boolean or a timestamp column and a version string.
+
+### Step 1: dry run one record
+
+Always. `dry_run: true` reads everything, writes nothing, and returns the same `Result` shape as
+the real thing, so your migration script reads identically either way.
+
+```ruby
+user = User.find(1)
+
+result = Clickwrap.import_legacy!(
+  :terms,
+  actor: user,
+  occurred_at: user.accepted_terms_at,
+  known: {
+    document_version: user.terms_version
+  },
+  unknown: %i[
+    exact_document_bytes
+    presentation
+    assertion
+    submit_button_text
+    request_evidence
+  ],
+  because: "Imported from users.accepted_terms_at",
+  source: "users.accepted_terms_at",
+  dry_run: true
+)
+
+result.planned?         # => true
+result.written?         # => false
+result.message
+# => "Would import terms for gid://my-app/User/1 (terms). Not recorded by the source and
+#     therefore unknown: assertion, exact_document_bytes, presentation, request_evidence,
+#     submit_button_text."
+result.idempotency_key  # => "imported_legacy:9f86d0…"
+```
+
+Read that message before you read anything else. It is the sentence that will end up in the
+receipt, and if it does not describe your legacy data accurately, your `unknown:` list is wrong.
+
+### Step 2: check the batch shape
+
+Run the dry run across a sample and look at three things:
+
+```ruby
+sample = User.where.not(accepted_terms_at: nil).limit(500)
+
+results = sample.map do |user|
+  Clickwrap.import_legacy!(:terms, actor: user, occurred_at: user.accepted_terms_at,
+                           known: { document_version: user.terms_version },
+                           unknown: %i[exact_document_bytes presentation assertion
+                                       submit_button_text request_evidence],
+                           because: "Imported from users.accepted_terms_at",
+                           dry_run: true)
+end
+
+results.count(&:planned?)
+results.group_by { |r| r.known["document_version"] }.transform_values(&:size)
+results.map(&:idempotency_key).uniq.size == results.size
+```
+
+- **How many are planned.** A record with no `occurred_at` raises rather than importing, because
+  Clickwrap will not substitute the time of the import. If the legacy row genuinely has no time,
+  do not import it as an act — record an exemption with `Clickwrap.exempt!` instead.
+- **Which version labels appear.** Any label that is not a published Clickwrap document version
+  will import as a label with no document bytes attached. That may be fine; it should not be a
+  surprise.
+- **That the idempotency keys are unique.** The key is derived from the policy, actor, subject,
+  tenant, `occurred_at`, and every `known:` value, so re-running the same script over the same
+  rows is a no-op rather than a second history for the same person. Change any of those inputs
+  and it is a different import — which is correct, since a different claim deserves a different
+  event rather than silently colliding with the first.
+
+### Step 3: import for real
+
+Drop `dry_run: true`.
+
+```ruby
+User.where.not(accepted_terms_at: nil).find_each do |user|
+  result = Clickwrap.import_legacy!(
+    :terms,
+    actor: user,
+    occurred_at: user.accepted_terms_at,
+    known: { document_version: user.terms_version },
+    unknown: %i[exact_document_bytes presentation assertion submit_button_text request_evidence],
+    because: "Imported from users.accepted_terms_at",
+    source: "users.accepted_terms_at"
+  )
+
+  Rails.logger.info(result.message)
+end
+```
+
+Re-running it is safe: an already-imported record returns `status: :already_imported` and writes
+nothing.
+
+### What the imported receipt looks like
+
+The assertion says, in the receipt, exactly what this is:
+
+> Imported from a pre-existing record: it states that this actor agreed to terms on
+> 2023-04-11T08:22:07.000000Z. The source system's original offer wording was not recorded, so
+> this receipt does not reproduce it. Not recorded by the source and therefore unknown: assertion,
+> exact_document_bytes, presentation, request_evidence, submit_button_text. Imported from
+> users.accepted_terms_at.
+
+And the provenance block carries the structured version, including a `not_collected` list naming
+`presentation_manifest`, `ip_address`, `browser_user_agent`, and `ip_geolocation`, plus a
+`means` sentence saying Clickwrap did not present this content and did not observe this action.
+
+The statement itself records `answered: false` and `answer: nil`. The action says what the old
+system claims happened; `answered` records whether *we* have the answer, and we do not.
+
+### Conventional `unknown:` keys
+
+The vocabulary is open — name anything your source did not record — but these are the keys the
+importers use, so a typo in a migration script is at least visibly a typo next to its
+neighbours:
+
+`exact_document_bytes`, `document_version`, `presentation`, `presentation_manifest`,
+`assertion`, `submit_button_text`, `protected_action`, `request_evidence`, `ip_address`,
+`browser_user_agent`, `capture_channel`, `authentication_context`.
+
+Listing `exact_document_bytes` or `document_version` in `unknown:` also stops the importer from
+attaching any document version at all, even if `known["document_version"]` is present. Saying
+"we do not know the bytes" and then linking bytes anyway would contradict itself.
+
+### Optional statements are excluded by default
+
+If the policy has optional consent statements, `import_legacy!` imports only the **required**
+ones unless you name statements explicitly:
+
+```ruby
+Clickwrap.import_legacy!(
+  :signup,
+  actor: user,
+  occurred_at: user.accepted_terms_at,
+  known: { document_version: user.terms_version },
+  unknown: %i[exact_document_bytes presentation assertion request_evidence],
+  because: "Imported from users.accepted_terms_at",
+  statements: %i[terms privacy_notice]
+)
+```
+
+A legacy boolean column recorded one decision. Reading it as a grant of an optional consent
+purpose it never mentioned would invent the exact thing an optional control exists to keep
+honest.
+
+---
+
+## From FinePrint
+
+[FinePrint](https://github.com/openstax/fine_print/blob/3b75fbcbcfb048ecd2f4ee7c4f0b9bd3d10f7603/README.md#L7-L25)
+*(pinned source code)* is established Rails prior art for versioned contracts, signatures,
+gates, and views. This importer exists because applications outgrow a question, not because they
+chose badly. FinePrint answers "did user U sign version N of contract X?", and it answers it
+well. What it never tried to record — the presentation, the exact wording beside the control,
+the call to action, the request context, the domain action the signature authorized — comes
+across as `unknown`.
+
+The importer deliberately does **not** depend on the `fine_print` gem, require any of its files,
+or reference any of its constants. It reads two tables through your own connection, if they are
+there, and discovers columns rather than assuming them. A migration tool that forces you to keep
+the gem you are migrating away from installed is a migration tool with a hostage.
+
+### Plan first
+
+```ruby
+report = Clickwrap::Import::FinePrint.plan(
+  policy_key: :signup,
+  find_actor_with: ->(user_type, user_id) { User.find_by(id: user_id) },
+  map_contract_with: ->(contract) { contract["name"] == "terms_of_use" ? :terms : nil },
+  because: "Migrating from FinePrint"
+)
+
+report.possible?    # => false when the tables are not in this database
+report.signatures   # => how many rows would be imported
+report.planned      # => the per-signature results
+report.contracts    # => one ContractMapping per FinePrint contract version
+report.message
+```
+
+`report.contracts` is the part to read carefully. Each `ContractMapping` reports the FinePrint
+contract name and version, the Clickwrap document key you mapped it to, and — crucially —
+`published?`: whether a matching Clickwrap document version actually exists here. That is what
+decides whether an imported event can carry real document bytes or must record the label alone.
+The summary message names every contract that has no published match.
+
+Two callbacks are yours to supply:
+
+- **`find_actor_with`** receives `(user_type, user_id)` and returns the actor record, a stable
+  actor reference string, or `nil` to skip that signature.
+- **`map_contract_with`** receives a contract row as a plain hash and returns the Clickwrap
+  document key it corresponds to. Only your application knows that its FinePrint contract named
+  `"terms_of_use"` is the document this gem calls `:terms`. Omit it and the contract's `name`
+  column is used as the key.
+
+`contract_names:` narrows to specific contracts and `limit:` caps the number of signatures —
+both useful for a staged migration.
+
+If the tables are not present, the report says so in a sentence and writes nothing, rather than
+raising. That keeps `clickwrap:doctor` and a migration checklist runnable on an application
+that never used FinePrint.
+
+### Then import
+
+```ruby
+report = Clickwrap::Import::FinePrint.import!(
+  policy_key: :signup,
+  find_actor_with: ->(_user_type, user_id) { User.find_by(id: user_id) },
+  map_contract_with: ->(contract) { contract["name"] == "terms_of_use" ? :terms : nil },
+  because: "Migrating from FinePrint"
+)
+
+report.imported.size
+report.already_imported.size
+```
+
+Each signature becomes an `imported_legacy` event through the same path as
+`Clickwrap.import_legacy!`, so it inherits every property above: idempotency, the two separate
+times, the explicit unknowns, and the assertion text that says the original wording was not
+recorded.
+
+### What FinePrint knew and what it did not
+
+| Recorded as `known` | Recorded as `unknown` |
+|---|---|
+| `source_system: "fine_print"` | `exact_document_bytes` |
+| `fine_print_signature_id` | `presentation_manifest` |
+| `fine_print_contract_id` | `assertion` |
+| `contract_name`, `contract_title` | `submit_button_text` |
+| `fine_print_contract_version` | `protected_action` |
+| `signed_by_type`, `signed_by_id` | `request_evidence`, `ip_address`, `browser_user_agent` |
+
+Note the deliberate naming: the version arrives as **`fine_print_contract_version`**, not
+`document_version`. The `document_version` key is what makes the legacy importer link published
+bytes, and a FinePrint version number is a label in another system's numbering — not a claim
+about which bytes this application published. If you want the bytes linked, publish the matching
+Clickwrap document version and pass `document_version` yourself.
+
+`occurred_at` comes from the signature row's `created_at` (falling back to `updated_at`). That is
+the best time available, and like every import it stays separate from when the Clickwrap event
+was written down.
+
+---
+
+## After the import
+
+Verify what you actually got, rather than assuming:
+
+```ruby
+receipt = user.clickwraps.receipts.last
+
+receipt.event.event_type          # => "imported_legacy"
+receipt.to_h["actor"]["attribution"]["method"]   # => "imported_provider"
+receipt.to_h["request_evidence"]  # => every category "not_configured"
+receipt.verify.success?
+```
+
+And run the ordinary health check:
+
+```bash
+bin/rails clickwrap:doctor
+bin/rails clickwrap:verify
+```
+
+An imported event satisfies `agreed_to?`, `acknowledged?`, and `current_for?` exactly as a live
+capture does. That is the point of a migration: your application answered "did this person
+agree?" with yes the day before the import, and an import that flipped the answer would force
+every existing user back through re-acceptance. What stays different is the evidence, not the
+answer — the event carries `imported_provider` attribution, its receipt names every unknown,
+and the state's `current_event_id` joins to that provenance in one query. If you want migrated
+users re-prompted when the documents move on, that is what `require_current_version: true`
+does, deliberately, per policy. (Exemptions remain the opposite case: no human acted, so they
+never satisfy a human-action predicate.)
+
+---
+
+## Sources
+
+| Source | Class |
+|---|---|
+| [FinePrint README at the audited commit](https://github.com/openstax/fine_print/blob/3b75fbcbcfb048ecd2f4ee7c4f0b9bd3d10f7603/README.md#L7-L25) | Pinned source code |
+| [FinePrint signature model at the audited commit](https://github.com/openstax/fine_print/blob/3b75fbcbcfb048ecd2f4ee7c4f0b9bd3d10f7603/app/models/fine_print/signature.rb#L1-L33) | Pinned source code |
+| The never-synthesize rule, the `unknown:` vocabulary, and the dry-run-first workflow | Product-design inference |