clickwrap 0.0.0 → 0.1.0

data/guides/naming.md

@@ -0,0 +1,320 @@
+# The public naming contract
+
+Every public name must say what it contains and where it came from. The test is literal: a
+15-year-old reading the initializer, a policy, an error message, a task's output, or a receipt
+should not need to know internal abbreviations to understand what the application does.
+
+This is not style. Clickwrap's value is evidence that is still true and still legible years
+after it was written, and the names are part of the evidence. A field called `ua` in a receipt
+from 2026 is a puzzle in 2031. A method called `dispose!` is a method nobody can review. An
+option called `full` is a decision nobody can audit.
+
+The rules below are normative for the whole gem — public methods, configuration settings, DSL
+keywords, error messages, generated comments, task output, and receipt fields — not only for
+request evidence.
+
+---
+
+## The eight rules
+
+### 1. Prefer a complete verb plus noun
+
+**Why:** a bare noun leaves the reader to guess the verb, and different readers guess
+differently. "With ip" — with it how? Recorded? Filtered? Required?
+
+```ruby
+# Before
+config.with_ip = true
+policy.ip = :on
+
+# After
+config.record_ip_address_by_default = true
+record_ip_address(because: "...", delete_after: 90.days)
+```
+
+### 2. Qualify the source
+
+**Why:** "resolver" says something gets resolved. It does not say from what, which is exactly
+the fact a reader needs in order to judge how much the value is worth. An address read from an
+HTTP request and an address supplied by a client are different facts and must not share a name.
+
+```ruby
+# Before
+config.ip_resolver = ->(x) { x.remote_ip }
+
+# After
+config.read_ip_address_from_http_request_with = ->(http_request) { http_request.remote_ip }
+```
+
+The same rule produces `read_browser_user_agent_from_http_request_with`, and it is why a
+host-assigned reader is labeled `host_configured_reader` in the receipt rather than being
+allowed to borrow the credibility of `rails_request_remote_ip`.
+
+### 3. Positive booleans
+
+**Why:** a negative boolean makes every reader do a double negative in their head, and
+`disable_ip_capture = false` is a line that has been misread in every codebase that has ever
+contained one.
+
+```ruby
+# Before
+config.disable_ip_capture = false
+config.no_geolocation = true
+
+# After
+config.record_ip_address_by_default = true
+config.record_ip_geolocation_country_by_default = false
+```
+
+### 4. Destructive methods name exactly what they delete
+
+**Why:** `dispose!` in a disposition report a year from now tells nobody which value went. Three
+methods that each name one field mean the report, the audit event, and the log line all say
+which category disappeared, rather than a euphemism covering several.
+
+```ruby
+# Before
+Clickwrap.dispose!(receipt)
+Clickwrap.purge_network_context!(receipt)
+Clickwrap.delete_personal_data!(receipt)
+
+# After
+Clickwrap.delete_recorded_ip_address!(receipt, because: "Retention period ended")
+Clickwrap.delete_recorded_browser_user_agent!(receipt, because: "Retention period ended")
+Clickwrap.delete_recorded_ip_geolocation!(receipt, because: "Retention period ended")
+```
+
+The implementation may centralize disposal internally — it does. Public calls, task output,
+audit events, and documentation keep the explicit field name.
+
+Every destructive method also takes a plain-English `because:`. It is stored on the disposition
+event and it is the only thing that will explain the deletion to somebody reading the record
+years from now.
+
+### 5. Distinguish configuration from fact
+
+**Why:** "we are set up to record this" and "this was recorded" are different claims, and a
+receipt that blurs them is worthless. The `_by_default` suffix marks a setting; the trailing
+question mark marks an observation about one event.
+
+```ruby
+config.record_ip_address_by_default   # configuration: what we intend to do
+receipt.recorded_ip_address?          # fact: what happened for this event
+```
+
+The same distinction runs through the six request-evidence states. `not_configured` is a
+configuration fact; `unavailable` is an observation; `deleted_after_retention` is a third thing
+entirely. None of them is blank.
+
+### 6. One option never secretly enables another category of data
+
+**Why:** this is the failure mode the gem exists to prevent. An option that turns on a category
+of personal data as a side effect makes the diff unreviewable and the upgrade dangerous — a
+later release can widen what the profile covers, and nobody reading the initializer would know.
+
+```ruby
+# Before
+record_ip_geolocation(precision: :full)
+record_request_context(level: :enhanced)
+
+# After
+record_ip_geolocation(
+  country: true,
+  region: true,
+  city: true,
+  postal_code: false,
+  latitude_and_longitude: true,
+  timezone: false,
+  continent: false,
+  metro_code: false,
+  accuracy_radius_in_kilometers: true,
+  because: "...",
+  retain_until: :security_evidence_retention_ends
+)
+```
+
+Nine fields, nine visible decisions, each with its own line in the privacy inventory.
+`latitude_and_longitude` is one coupled choice on purpose: half a coordinate is not a result.
+
+The installer follows the same rule. Interactive prompts ask about one category at a time, and
+non-interactive installs use individual flags such as
+`--record-ip-addresses-by-default`. The sole recipe,
+`--request-evidence-recipe=privacy-minimized`, writes every collection setting explicitly as
+`false`; it can never enable a data category. There is no `evidence-rich`, `full`, or other named
+recipe whose expansion could collect more in a later release.
+
+### 7. No unexplained acronyms or abbreviations
+
+**Why:** an abbreviation is a shared secret between the author and whoever was in the room. A
+receipt is read by people who were not.
+
+```ruby
+# Before
+receipt.ua
+receipt.geo
+event.addr
+capture!(:signup, ctx: request)
+
+# After
+receipt.browser_user_agent
+receipt.ip_geolocation_country_code
+receipt.ip_address
+Clickwrap.capture!(:signup, http_request: request)
+```
+
+Two abbreviations are permitted because they are the standards' own names and expanding them
+would be less clear, not more: `ip` inside `ip_address` and `ip_geolocation`, and `http` inside
+`http_request`.
+
+### 8. Every example must make sense read aloud
+
+**Why:** it is the cheapest review anyone can run, and it catches almost everything the other
+seven rules are trying to prevent.
+
+Read this aloud:
+
+> Clickwrap capture and, withdrawal authorization, actor current user, subject withdrawal, http
+> request request, submission clickwrap submission.
+
+It is a sentence. Now read the alternative:
+
+> Clickwrap capture, with ip, ctx request, full.
+
+If an example does not survive being read aloud by a developer who has never seen the gem, the
+name is wrong. Fix the name, not the example.
+
+---
+
+## Required vocabulary
+
+Use the left column. The right column is what has been rejected and why.
+
+| Use | Not | Because |
+|---|---|---|
+| `ip_address` | `ip`, `remote_address`, `network_address`, `addr` | Abbreviations, and "network address" hides which address |
+| `ip_geolocation` | `geo`, `location`, `coordinates` | "Location" reads as where the person is. It is an estimate about an address |
+| `ip_geolocation_latitude_and_longitude` | `precise_location`, `fine_location` | "Precise" is the opposite of true here |
+| `ip_geolocation_accuracy_radius_in_kilometers` | `accuracy` | A number with no unit and no meaning |
+| `ip_geolocation_provider_name`, `ip_geolocation_provider_source`, `ip_geolocation_database_version` | `provider`, `source` | In a receipt, "source" could mean four things |
+| `browser_user_agent` | `ua`, `client_info`, `browser` | The raw header is a specific thing; "browser" suggests a parsed result |
+| `http_request` | `context`, `ctx`, `env` | "Context" is where unreviewed data goes to hide |
+| `capture_channel` | `flow`, `source` | Unqualified nouns again |
+| `authentication_method` | `assurance` | Assurance supplied by whom, measured how? |
+| `recorded_at_by_server` | `signed_at`, `timestamped_at` | Nothing signed it. It is the application server's own clock, and the name has to keep saying so |
+| `estimated`, `client_supplied`, `server_observed`, `provider_reported` | dropping the qualifier | These four words are the difference between a fact and an overclaim |
+
+## Booleans read as questions
+
+```ruby
+receipt.recorded_ip_address?
+receipt.recorded_browser_user_agent?
+receipt.recorded_ip_geolocation_country?
+receipt.recorded_ip_geolocation_city?
+receipt.recorded_ip_geolocation_latitude_and_longitude?
+receipt.ip_geolocation_was_estimated?
+receipt.ip_geolocation_source_was_verified_by_host?
+receipt.ip_address_was_deleted?
+receipt.browser_user_agent_was_deleted?
+```
+
+The `was_` prefix on the last four is doing work: `ip_geolocation_was_estimated?` is a statement
+about the value that was stored, not about the resolver's current settings, and
+`ip_address_was_deleted?` is a fact about this record rather than about policy.
+
+The same grammar runs through the actor proxy, which is where most application code meets the
+gem:
+
+```ruby
+user.clickwraps.agreed_to?(:terms)
+user.clickwraps.acknowledged?(:privacy_notice)
+user.clickwraps.consented_to?(:product_updates)
+user.clickwraps.declared?(:independent_contractor, subject: scheme)
+user.clickwraps.attested?(:bank_accepted_transfer)
+user.clickwraps.authorized?(:withdrawal, subject: withdrawal)
+user.clickwraps.exempted_from?(:signup)
+```
+
+Six kinds, six predicates. There is no generic `accepted?`, because collapsing them would erase
+the distinction the six kinds exist to preserve — and `exempted_from?` is separate precisely so
+an exemption can never answer a human-action question.
+
+---
+
+## Prohibited option names
+
+These may not appear as public options, keywords, settings, or command-line flags. Each one is
+banned for a specific reason, not for taste.
+
+| Never | Why |
+|---|---|
+| `:network`, `:full`, `:enhanced`, `:forensic`, `:maximum` | They hide what will be collected behind a word that sounds like a quality level |
+| `record_location` | A developer could reasonably read it as GPS or physical location. It is neither |
+| `request_evidence: :network`, `track_everything`, `record_everything` | Category switches. See rule 6 |
+| `maximum_evidence`, `full_evidence`, `legal_proof: true` | They imply a verdict the gem cannot reach, and they enable data as a side effect |
+| An opaque privacy-profile switch keyed to a regulation | No runtime flag can make a legal determination on anyone's behalf, and the name would be the least accurate string in the codebase |
+| `include_sensitive_context: true` | One flag turning on three categories of personal data makes an operator's intent unreviewable. Use `include_ip_address:`, `include_browser_user_agent:`, `include_ip_geolocation:` |
+| `dispose!`, `purge!`, `cleanup!` as public API | See rule 4 |
+
+There is also no `--gdpr-*`, `--record-network-context`, `--record-everything`, or
+`--full-evidence` generator flag. Non-interactive installer options are as explicit as the
+settings they write:
+
+```text
+--record-ip-addresses-by-default
+--record-ip-geolocation-cities-by-default
+--record-ip-geolocation-latitude-and-longitude-by-default
+--delete-recorded-ip-addresses-after-days=90
+```
+
+---
+
+## The same standard for the rest of the initializer
+
+The rule is not a request-evidence rule. It produced the shape of the whole configuration
+object.
+
+| Shipped name | Rejected | Why |
+|---|---|---|
+| `actor_class_name` | `actor_class` | It holds a string, constantized lazily so the initializer works before the model loads. The name says which |
+| `current_actor_method_name` | `current_actor` | It is a method name, not an actor |
+| `find_current_tenant_with` | `tenant_resolver` | Verb plus source. It is a callable that finds something |
+| `store_document_contents_in` | `document_store` | Says what goes where |
+| `digest_canonical_receipts_with` | `integrity` | "Integrity" is a category, not a decision. This one names the algorithm's job |
+| `chain_event_history_with`, `anchor_event_history_with`, `timestamp_receipts_with` | one `integrity_level` setting | Three different mechanisms making three different claims. One setting would let a reader infer the strongest from the presence of the weakest |
+| `after_event_is_committed` | `after_commit` | Says which commit, and reads as a sentence |
+| `authorize_unredacted_request_evidence_access_with` | `access_control` | Long, and correct. It names exactly which access it authorizes |
+| `deliberately_store_request_evidence_unencrypted!(because:)` | `encryption: false` | Turning encryption off should be a sentence a reviewer can find in a diff, with the host's own reason attached — not a `false` |
+
+The last row is the pattern worth copying. When an option has a consequence somebody should
+have to think about, make the name carry the thinking.
+
+---
+
+## Reviewing a new name
+
+Before you add a public method, option, setting, or receipt field:
+
+- [ ] Read the example aloud. Does it parse as English?
+- [ ] Does the name say what it contains **and** where it came from?
+- [ ] Is the boolean positive?
+- [ ] If it deletes something, does the name say which thing?
+- [ ] Does it distinguish "we are configured to" from "this happened"?
+- [ ] Could enabling it turn on a category of personal data the reader did not name?
+- [ ] Are there abbreviations that are not `ip` or `http`?
+- [ ] If it goes into a receipt: will it still be legible in 2031, to somebody who has never
+      seen this codebase?
+- [ ] If it goes into a receipt: is it in `Clickwrap::Vocabulary`? Stable strings live there,
+      frozen, in one place, and they are **added to, never renamed or repurposed** — a value
+      that changed meaning underneath an old receipt would make it say something it never said.
+
+A name that fails any of these is cheaper to change now than after the first release, because
+after the first release it is in receipts.
+
+---
+
+## Sources
+
+| Source | Class |
+|---|---|
+| `docs/strategy/02-request-evidence.md`, "Public naming rules" — the normative source for this guide | Internal normative design document |
+| Every rule, rejection, and rationale above | Product-design inference |

data/guides/organizations.md

@@ -0,0 +1,320 @@
+# Binding an organization through a human actor
+
+Clickwrap keeps the person who acted and the party they represented as two
+different facts:
+
+| Concept | Typical `organizations` record | What it means |
+|---|---|---|
+| actor | `current_user` | The human account that performed the clickwrap action |
+| represented party (`acting_for`) | `current_organization` | The organization the action is intended to bind |
+| tenant | usually `current_organization` | The application data boundary in which the action happened |
+| subject | optional domain record | The exact order, withdrawal, contract, or other object the statement covers |
+
+A `User` therefore does not disappear behind an organization. The event and
+receipt keep both references, plus the membership evidence used to authorize
+the represented action.
+
+## One policy line
+
+Choose the organization role your application and counsel have reviewed:
+
+```ruby
+Clickwrap.policy :organization_terms do
+  agree_to :organization_terms
+
+  permit_acting_for_organization when_actor_is_at_least: :admin
+
+  retain_with :ordinary_agreement_evidence
+end
+```
+
+Or name a purpose-specific permission from the `organizations` gem instead of
+coupling the decision to a broad role:
+
+```ruby
+Clickwrap.policy :data_processing_terms do
+  agree_to :data_processing_terms
+
+  permit_acting_for_organization \
+    when_actor_has_permission: :accept_data_processing_terms
+
+  retain_with :ordinary_agreement_evidence
+end
+```
+
+If both options are present, both must pass. A policy with neither is rejected
+at boot: organization membership by itself is not treated as legal authority.
+
+The permission-oriented form is usually the more durable design. It lets an
+application grant exactly “may accept these terms for this organization”
+without silently equating that power with every other thing an `admin` can do.
+
+## Present and capture the same represented party
+
+Make organizational capacity visible in both the interface copy and the Ruby
+call:
+
+```erb
+<%= form_with model: @agreement do |form| %>
+  <p>
+    You are accepting these terms for
+    <strong><%= current_organization.name %></strong>.
+  </p>
+
+  <%= form.clickwrap :organization_terms,
+        acting_for: current_organization,
+        submit: "Accept for #{current_organization.name}" %>
+<% end %>
+```
+
+Then pass the server-owned organization again at submit:
+
+```ruby
+def create
+  organization = current_organization
+
+  capture_clickwrap_and!(
+    :organization_terms,
+    acting_for: organization
+  ) do |pending_receipt|
+    organization.update!(
+      terms_accepted_with_clickwrap_event_id: pending_receipt.event_id
+    )
+  end
+
+  redirect_to organization_settings_path
+end
+```
+
+Do not permit an organization ID from the form and turn it into
+`acting_for:`. Resolve the organization from the authenticated server-side
+context. The signed presentation is also bound to that exact represented-party
+reference, so it cannot be moved to another organization between render and
+submit.
+
+If the application uses the organization as its Clickwrap tenant too, configure
+the resolver once — **and declare tenant semantics on every policy**, because
+the resolver alone reproduces a real production bug: an organization member's
+session resolves an ambient organization on every request, so a *personal*
+policy (a contractor declaration, a payout gate) would silently bind — or refuse —
+under whatever organization happened to be current:
+
+```ruby
+Clickwrap.configure do |config|
+  config.find_current_tenant_with = ->(controller) {
+    controller.current_organization
+  }
+end
+
+Clickwrap.policy :contractor_declaration do
+  tenant_is :not_applicable   # personal evidence: joining an org changes nothing
+
+  declare :independent_contractor,
+    document: :terms,
+    statement: "I provide these services as an independent contractor, not as an employee."
+
+  retain_with :ordinary_agreement_evidence
+end
+
+Clickwrap.policy :organization_terms do
+  tenant_is :required         # org-scoped evidence: the org is passed deliberately
+
+  agree_to :terms
+  permit_acting_for_organization when_actor_is_at_least: :admin
+
+  retain_with :ordinary_agreement_evidence
+end
+```
+
+`tenant_is :not_applicable` policies always record a nil tenant regardless of
+the ambient organization; `:required` policies refuse to present or capture
+without one; `:optional` (the default) passes the resolved value through.
+Presentation, capture, verification, withdrawal, and import all translate the
+ambient value through the same declaration. `acting_for:` stays explicit
+because “this happened inside Acme” and “this person intended to bind Acme”
+are not interchangeable claims.
+
+## What is checked at presentation and submit
+
+The built-in adapter has no hard runtime dependency on `organizations`; it is
+used only by a policy that calls `permit_acting_for_organization`. For a
+persisted organization it:
+
+1. requires a persisted `Organizations::Organization` (host subclasses are
+   accepted);
+2. requires the actor to have a current membership in that exact organization
+   before rendering the form;
+3. signs the presentation-time membership reference, role, source, criterion,
+   and verification time into the manifest;
+4. locks and rereads the membership inside the capture transaction;
+5. checks the configured minimum role and/or permission at both moments; and
+6. records both snapshots plus the available authentication method.
+
+That means an admin removed or demoted after the page was rendered is denied at
+submit. A role change that remains authorized is not flattened: the receipt
+keeps the role at presentation and the role at capture. A token rendered for
+one organization cannot be submitted for another, and an organizational
+acceptance never satisfies a personal-capacity query:
+
+```ruby
+user.clickwraps.current_for?(
+  :organization_terms,
+  tenant: organization,
+  acting_for: organization
+) # => true
+
+user.clickwraps.current_for?(
+  :organization_terms,
+  tenant: organization
+) # => false
+```
+
+## Create the organization and its evidence together
+
+A person may reach the form before the organization has a row or a membership.
+That is not the ordinary `acting_for:` case: Clickwrap cannot truthfully say it
+verified a membership that does not exist. Opt into the prospective flow in the
+policy, and include an explicit declaration for the real-world authority or
+content-rights claim the application needs:
+
+```ruby
+Clickwrap.policy :organization_creation do
+  declare :authority_and_content_rights,
+    statement: "I am authorized to create and act for this organization and may use the content I submit.",
+    document: nil,
+    protected_outcome_version: "created-organization-v1",
+    record_protected_outcome_with: ->(organization) {
+      Clickwrap.protected_outcome(
+        action: :created,
+        record: organization,
+        facts: {
+          name: organization.name,
+          logo_checksum: organization.logo.blob.checksum
+        }
+      )
+    }
+
+  permit_acting_for_organization(
+    when_actor_is_at_least: :owner,
+    including_when_this_action_creates_the_organization: true
+  )
+
+  retain_with :ordinary_agreement_evidence
+end
+```
+
+Pass the same new model as `acting_for:`. The form helper creates and signs a
+server-owned browser-flow identifier; there is no organization id, role, policy
+option, or evidence field for the browser to choose:
+
+```erb
+<%= form_with model: @organization do |form| %>
+  <%# name, logo, and other organization fields %>
+
+  <%= form.clickwrap :organization_creation,
+        acting_for: @organization,
+        submit: "Create organization" %>
+<% end %>
+```
+
+At submit, return the persisted organization after creating its owner
+membership in the protected block. The result may come from an ordinary
+creation service; it must have the same class the presentation bound:
+
+```ruby
+def create
+  @organization = Organizations::Organization.new(organization_params)
+
+  receipt = create_represented_party_with_clickwrap(
+    :organization_creation,
+    represented_party: @organization
+  ) do |pending_receipt|
+    @organization.save!
+    @organization.add_member!(current_user, role: :owner)
+    @organization.update!(creation_clickwrap_event_id: pending_receipt.event_id)
+    @organization
+  end
+
+  redirect_to organization_path(receipt.event.represented_party)
+end
+```
+
+The manifest labels presentation-time authority `not_yet_verifiable`. After the
+block returns the persisted record, the configured adapter verifies the new
+owner membership inside the same transaction, and the event is rebound to the final
+stable organization reference before its digest and projections are written.
+An evidence-write failure, model-validation failure, missing/insufficient
+membership, protected-outcome failure, or outer transaction rollback leaves no
+created organization or Clickwrap event. An identical nonce retry returns the
+original receipt without running the creation block twice.
+
+That post-creation owner check proves only the application state the block just
+created. It does not prove that the person already had real-world authorization
+to use a legal name or logo or to bind an external company. Record that claim as
+an explicit `declare` statement, choose its wording with counsel, and keep the
+protected outcome specific enough to identify the organization and submitted
+assets it covered.
+
+API clients use the same primitive with a server-owned flow id:
+
+```ruby
+Clickwrap.create_represented_party!(
+  :organization_creation,
+  actor: current_user,
+  represented_party: organization,
+  represented_party_creation_flow_id: server_session_flow_id,
+  http_request: request,
+  submission: Clickwrap.submission_from(params)
+) do |pending_receipt|
+  organization.save!
+  organization.add_member!(current_user, role: :owner)
+  organization.update!(creation_clickwrap_event_id: pending_receipt.event_id)
+  organization
+end
+```
+
+Pass that same `represented_party_creation_flow_id:` to `Clickwrap.present`.
+Do not derive it from form fields or accept it as the authority decision; it is
+opaque server session state used only to bind one prospective browser flow.
+
+## The legal boundary
+
+The `organizations` role or permission is an application authorization fact.
+Clickwrap records that fact and its provenance; it cannot decide whether an
+`admin`, officer, employee, guardian, or agent has legal capacity to bind a
+party for a particular agreement in a particular jurisdiction. Spain's Civil
+Code Article 1259, for example, makes authorization or legal representation a
+substantive issue and addresses later ratification; it does not say that a SaaS
+role named `admin` or `owner` supplies that authorization ([official current
+consolidated text](https://www.boe.es/eli/es/rd/1889/07/24/%281%29/con),
+[official BOE document view with Article 1259](https://www.boe.es/buscar/doc.php?id=BOE-A-1889-4763&lang=es)).
+EU eIDAS Article 25 also distinguishes the evidential treatment of an
+electronic signature from the specific handwritten-signature equivalence of a
+qualified electronic signature ([official consolidated EUR-Lex
+text](https://eur-lex.europa.eu/eli/reg/2014/910/en/cons)).
+
+Those are jurisdiction-specific legal sources, not a universal answer. Choose
+the criterion and statement with counsel, use interface copy that makes the
+represented capacity conspicuous, and keep any organization identity fields
+your evidentiary policy requires. The built-in adapter records stable
+database/GlobalID references; it does not claim that an organization display
+name is a verified legal name, that a membership role is statutory authority,
+or that an ordinary click is a qualified electronic signature.
+
+For a different authority system, keep the same actor/represented-party model
+and register a named server-side adapter with
+`config.register_represented_party_authority`.
+
+## Exact implementation sources
+
+These are source-code observations, not legal authorities:
+
+- The `organizations` gem's public organization and membership APIs are
+  documented at
+  https://github.com/rameerez/organizations/blob/fd0eace263c54cd3c8ab98a9505190df6856c6d6/README.md#the-complete-api
+- Its organization-to-membership association is implemented at
+  https://github.com/rameerez/organizations/blob/fd0eace263c54cd3c8ab98a9505190df6856c6d6/lib/organizations/models/organization.rb#L37-L41
+- Its membership role and permission checks are implemented at
+  https://github.com/rameerez/organizations/blob/fd0eace263c54cd3c8ab98a9505190df6856c6d6/lib/organizations/models/membership.rb#L106-L160
+- Its default role hierarchy and permission evaluation are implemented at
+  https://github.com/rameerez/organizations/blob/fd0eace263c54cd3c8ab98a9505190df6856c6d6/lib/organizations/roles.rb#L12-L146