agreements 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 921978d679f2c21c42fda41e4caa14e844e5fbfbb57a10c78738811441814547
-  data.tar.gz: 342464faa1422920f63ca881f7d64728d35e6b88c7e595d351a06c181a7692cd
+  metadata.gz: b66e31588c3340afd328330ca457833673b95a0a37e446f21c8f792b1aa7bd9b
+  data.tar.gz: 301e25cb6b409ef8267c7aabf3f819e4877207bc85353ddcab988b48a6bf4aa4
 SHA512:
-  metadata.gz: c1cf67625ad815b0e3df2033a609cd510cf9c4ca97888b518c842546bb174b3c22abfd7bfc2670d0756337c3e24465b2e70b4a52887dbbf7e0a1a9c7c78a939b
-  data.tar.gz: 60cd61c042671c9bcb86f1e2f3c37ceeba9bfa2600aee3082766fe8b2124a38a7c81bc3b7ae5328f65f6265d6ac8ac6ef2f77416cd3d28547fd1c70bb47607a3
+  metadata.gz: a847857ad1cd3391d5f97b4e1491023dfc6d853bb76589c5f7b24ac58554ac7dbfe598360b66b1f92a05a2ce4aa99e9d081eac7c8bd2ece7390081d2ac6ffc70
+  data.tar.gz: edfdbb93fb962b18232e1794f1aee4303ea0c4941ab8e392df2dae446a013771c701274f36b3c17a088f2d6cb83237c6dea73630cb83e8e32c815d808e1879a2

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.4.1 - 2026-11-12
+
+- Rewrite the README around a quick start, guides and an API reference.
+- Clearer gem summary and description, and a documentation link on RubyGems.
+
 ## 0.4.0 - 2026-11-12
 
 - Add an optional `effective_at` to versions, so a version can be inserted when

data/README.md

@@ -1,64 +1,120 @@
 # agreements
 
-Auditable acceptance of externally hosted legal agreements for Rails.
+[![Gem Version](https://img.shields.io/gem/v/agreements)](https://rubygems.org/gems/agreements)
+[![CI](https://github.com/yshmarov/agreements/actions/workflows/ci.yml/badge.svg)](https://github.com/yshmarov/agreements/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](MIT-LICENSE)
 
-`agreements` answers one durable question:
-
-> Which agreement version and localized statement did this subject accept,
-> who performed the acceptance, under what authority, and when?
-
-It deliberately does not host legal documents or provide a legal CMS. Your
-legal or marketing site remains authoritative; the gem stores immutable
-version metadata and append-only acceptance evidence in your own database.
-
-## Install
+Record who accepted which version of your Terms, Privacy Notice or Data
+Processing Agreement, and ask again when the documents change. For Rails.
 
 ```ruby
-# Gemfile
-gem "agreements"
+Agreements.pending_version("user_terms", subject: current_user)
+# => nil when the user accepted the current Terms, or the version they still need to accept
 ```
 
-```bash
-bundle install
-bin/rails generate agreements:install
-bin/rails db:migrate
+## Why you need it
+
+Most apps store terms acceptance as a timestamp, such as
+`users.accepted_terms_at`. That works until somebody asks a real question:
+
+- **Which version** of the Terms did this user accept, and what did it say?
+- **What exactly did they tick?** In which language?
+- **Who accepted for the company?** Was it the account owner or an ordinary
+  member?
+- **The Terms changed last month.** Who still has to accept the new version?
+- **The form was open during a deploy.** Did the user accept the old version or
+  the new one?
+
+Procurement teams, auditors and lawyers ask these questions. A timestamp cannot
+answer them. This gem can, with two database tables and a few method calls.
+
+## What it looks like in your app
+
+1. **First deploy.** Every signed-in user who has not accepted your Terms is
+   sent to your acceptance page on their next page view. They tick the box and
+   continue to the page they wanted.
+2. **Your lawyer updates the Terms.** You publish the new document and add the
+   new version with the date it takes effect, for example in 14 days. Nothing
+   changes for users before that date. You can show a notice in the meantime.
+3. **On the effective date,** each user is asked once to accept the new version.
+4. **An auditor asks** "Who accepted the DPA for Acme, and what did they see?"
+   You answer with one query:
+
+```text
+agreement:  organization_dpa, version 2026-09-13
+subject:    gid://my-app/Organization/42      the party bound by the agreement
+actor:      gid://my-app/User/7               the person who clicked
+authority:  organization_owner                why that person could accept
+statement:  "J'accepte le contrat de traitement des données au nom de cette organisation."
+locale:     fr
+accepted:   2026-09-14 09:12:03 UTC
 ```
 
-The generator adds two tables and nothing else. There is no route, controller,
-view, initializer, JavaScript, CSS, or admin dashboard to integrate.
+Records cannot be changed or deleted through the model API.
 
-Ruby >= 3.2 · Rails >= 7.1 and < 9 · PostgreSQL and SQLite
+## Is it for you?
 
-### Upgrading from 0.3
+**Use it when**
 
-Version 0.4 adds a nullable `effective_at` column to `agreements_versions`:
+- you have Terms, a Privacy Notice or a DPA, and you must prove acceptance later;
+- a company accepts an agreement through one of its users (B2B SaaS);
+- your documents change, and you must ask people again;
+- you show the acceptance checkbox in more than one language.
 
-```bash
-bin/rails generate migration AddEffectiveAtToAgreementsVersions effective_at:datetime
-bin/rails db:migrate
-```
+**Use something else when**
 
-Existing rows keep `effective_at` empty and stay in effect from their creation.
+- you need signatures for contracts. Use an e-signature service;
+- you need to record and withdraw GDPR consent, such as marketing consent;
+- you need IP addresses, signed receipts or a ready-made form builder.
+  [clickwrap](https://github.com/rameerez/clickwrap) covers that bigger scope.
 
-### Upgrading from 0.2
+## Trust
 
-Version 0.3 has no schema change. `require_agreement` now answers a pending
-non-HTML request with `403 Forbidden` instead of letting it through. If your
-API already checks `pending_version` before calling it, nothing changes.
+- **In production.** [EthicsPortal](https://ethicsportal.eu), whistleblower
+  software for EU organisations, uses it for user Terms and organisation DPAs.
+  The gem was extracted from that code in August 2026.
+- **Small.** About 250 lines of Ruby. You can read all of it in one sitting.
+- **Tested** in CI on every push: Ruby 3.2 to 4.0 with Rails 7.1 to 8.1 on
+  SQLite, and Rails 8.1 on PostgreSQL.
+- **Safe releases.** Releases are built and published from
+  [GitHub Actions](.github/workflows/release.yml) with RubyGems trusted
+  publishing. Gem ownership requires multi-factor authentication.
+- **Few dependencies.** Action Pack, Active Record, Railties and Global ID. No
+  JavaScript, no background jobs, no external services.
+- **Your data stays in your database.** The gem makes no network calls and
+  collects no telemetry. It does not store IP addresses or user agents.
+- **Security:** see [SECURITY.md](SECURITY.md). Report vulnerabilities through
+  [private reporting](https://github.com/yshmarov/agreements/security/advisories/new).
+- **Changes** are listed in the [CHANGELOG](CHANGELOG.md). See
+  [Versioning](#versioning) for what may break before 1.0.
 
-### Upgrading from 0.1
+## Quick start
 
-Version 0.2 adds non-null `acceptance_statement` and `locale` columns to
-`agreements_acceptances`. Add them in a host migration before upgrading. For
-existing evidence, copy each version's canonical statement and use an honest
-locale such as `und` when the displayed locale is unknown.
+Ruby 3.2 or later, Rails 7.1 or later. The example uses a `Current.user`, as
+created by the Rails 8 authentication generator. Use your own current user.
+
+### 1. Install
+
+```ruby
+# Gemfile
+gem "agreements"
+```
 
-## Define a version
+```bash
+bundle install
+bin/rails generate agreements:install
+bin/rails db:migrate
+```
+
+The generator adds one migration with two tables: `agreements_versions` and
+`agreements_acceptances`. It adds no routes, views or configuration.
 
-Agreement versions are deployed data. Insert them in a data migration, and keep
-the same list in your seeds so fresh databases match production:
+### 2. Add your first version
+
+A version is data that you deploy. Add it in a migration:
 
 ```ruby
+# db/migrate/20260816000000_add_user_terms_2026_08_16.rb
 class AddUserTerms20260816 < ActiveRecord::Migration[8.1]
   class Version < ActiveRecord::Base
     self.table_name = "agreements_versions"
@@ -91,193 +147,221 @@ class AddUserTerms20260816 < ActiveRecord::Migration[8.1]
 end
 ```
 
-The migration defines its own model so it keeps working when the gem's model
-changes later. The final check stops a deploy if a version label already exists
-with different content: a deployed version must never change. Use the same
-create-then-check loop in your seeds.
-
-A version without `effective_at` is current as soon as it is inserted. There is
-no draft, publish or activate step. A correction or legal update is a new
-immutable row with a new version label.
+- Use your own Rails version in `Migration[8.1]`.
+- The documents stay on your website. The gem stores only their title, URL and
+  an optional SHA-256 digest.
+- The migration defines its own model, so it keeps working when the gem changes.
+- The final check stops a deploy if the version already exists with different
+  content. A deployed version must never change.
+- Add the same versions to `db/seeds.rb`, so a fresh database has them too.
 
-### Give notice before a version takes effect
-
-Terms often promise notice before a change applies, for example "at least 14
-days before the changes take effect". Insert the version when you send the
-notice, with the date it takes effect:
+### 3. Add the acceptance page
 
 ```ruby
-VERSION = {
-  agreement_key: "user_terms",
-  version: "2026-12-01",
-  effective_at: Time.utc(2026, 12, 1),
-  # acceptance_statement, documents ...
-}.freeze
+# config/routes.rb
+resource :terms_acceptance, only: %i[show create]
 ```
 
-Until that time the previous version stays current, nobody is asked to accept,
-and `accept!` refuses the new version. From that time the new version is
-current and every subject who has not accepted it is pending. Show the notice
-in your app with:
-
 ```ruby
-Agreements.upcoming_version("user_terms") # => the next scheduled version, or nil
-```
+# app/controllers/terms_acceptances_controller.rb
+class TermsAcceptancesController < ApplicationController
+  skip_before_action :require_terms
+
+  def show
+    @version = Agreements.current_version("user_terms")
+    raise ActiveRecord::RecordNotFound unless @version
+  end
 
-The current version is the one that took effect most recently: its
-`effective_at`, or its creation time when `effective_at` is empty. When two
-versions take effect at the same time, the one inserted later wins.
+  def create
+    @version = Agreements.current_version("user_terms")
+    return render(:show, status: :unprocessable_content) unless params.dig(:acceptance, :confirmed) == "1"
+
+    Agreements.accept!(
+      "user_terms",
+      version_id: params.dig(:acceptance, :agreement_version_id),
+      subject: Current.user,
+      actor: Current.user,
+      authority: "self",
+      acceptance_statement: t("terms_acceptances.statement"),
+      locale: I18n.locale.to_s
+    )
+    redirect_to agreement_return_location || root_path, status: :see_other
+  rescue Agreements::VersionNotCurrent => error
+    raise ActiveRecord::RecordNotFound unless error.current_version
+
+    @version = error.current_version
+    flash.now[:alert] = t("terms_acceptances.changed")
+    render :show, status: :unprocessable_content
+  end
+end
+```
 
-Subjects cannot accept a scheduled version early. Someone who accepts the
-current version during the notice period is asked again on the effective date.
+```erb
+<%# app/views/terms_acceptances/show.html.erb %>
+<%= form_with scope: :acceptance, url: terms_acceptance_path do |form| %>
+  <%= form.hidden_field :agreement_version_id, value: @version.id %>
+
+  <%= form.label :confirmed do %>
+    <%= form.check_box :confirmed, required: true %>
+    <%= t("terms_acceptances.statement") %>
+  <% end %>
+
+  <ul>
+    <% @version.documents.each do |document| %>
+      <li><%= link_to document["title"], document["url"], target: "_blank" %></li>
+    <% end %>
+  </ul>
+
+  <%= form.submit t("terms_acceptances.accept") %>
+<% end %>
+```
 
-A scheduled version cannot have acceptances before it takes effect. To cancel
-it, delete it in a data migration with a migration-local model before its
-effective date. After that date it is evidence like any other version.
+```yaml
+# config/locales/en.yml
+en:
+  terms_acceptances:
+    statement: I accept the Terms of Service and acknowledge the Privacy Notice.
+    accept: Accept and continue
+    changed: The Terms changed while this page was open. Please review them again.
+```
 
-Document references accept `title`, an HTTPS `url`, an optional 64-character
-`sha256`, and an optional `key`. Use `key` (lowercase letters, digits and
-underscores) to look up a translated link title, so your views do not depend on
-the English `title`. The gem validates a supplied digest but does not fetch
-remote pages, calculate hashes, or retain document bytes. Hashing and archival
-belong in the trusted legal-document publishing process.
+- `require_terms` is defined in step 4. Add both steps before you restart the
+  server.
+- The hidden field sends the version the user saw. If a newer version became
+  current in the meantime, `accept!` raises `Agreements::VersionNotCurrent` and
+  the page shows the new version.
+- `acceptance_statement` is the exact sentence the user saw, in their language.
+  It is stored with the acceptance.
+- Pass `subject`, `actor` and `authority` from the server. Never take them from
+  request parameters.
+- A double click or a retry returns the first acceptance. It does not create a
+  second one.
 
-## Ask what is pending
+### 4. Require acceptance
 
 ```ruby
-version = Agreements.current_version("user_terms")
-pending = Agreements.pending_version("user_terms", subject: current_user)
-```
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include Agreements::Enforcement
 
-Subjects and actors may be records responding to `to_global_id`, or explicit
-non-empty opaque strings. The gem stores only the resulting keys; it does not
-own authentication, tenancy, roles, or authorization.
+  before_action :require_terms, if: -> { Current.user }
 
-A Global ID contains your application name and the model class, for example
-`gid://my-app/User/1`. If either changes, old acceptances no longer match and
-every subject is asked to accept again. Pin the application name now so a
-module rename cannot change it:
+  private
 
-```ruby
-# config/application.rb
-config.global_id.app = "my-app"
+  def require_terms
+    require_agreement("user_terms", subject: Current.user, location: main_app.terms_acceptance_path)
+  end
+end
 ```
 
-Before you rename a model, plan how to carry its acceptances over. Acceptance
-rows are read only through the model API.
+When the user has not accepted the current version:
 
-## Render the host-owned form
+- an HTML or Turbo Stream request is redirected to the acceptance page. After
+  acceptance, `agreement_return_location` sends the user back to the page they
+  asked for (GET and HEAD requests only; a form submission is never replayed);
+- any other request (JSON, CSV, PDF) gets an empty `403 Forbidden`.
 
-Keep the page, routes, authorization, document-link markup, and copy in your
-application. Submit the exact displayed version as a hidden field:
+Use `main_app.` for the location so the check also works inside mounted
+engines.
 
-```erb
-<%= form.hidden_field :agreement_version_id, value: @version.id %>
-<%= form.check_box :confirmed, required: true %>
-```
+### 5. Update your tests
 
-Then record only that version while it remains current:
+With enforcement on, most tests need users who have already accepted:
 
 ```ruby
-statement = I18n.t("agreements.user_terms.statement")
+# test/test_helper.rb
+require "agreements/test_helper"
 
-acceptance = Agreements.accept!(
-  "user_terms",
-  version_id: params.dig(:acceptance, :agreement_version_id),
-  subject: current_user,
-  actor: current_user,
-  authority: "self",
-  acceptance_statement: statement,
-  locale: I18n.locale.to_s
-)
+class ActiveSupport::TestCase
+  include Agreements::TestHelper
+end
 ```
 
-`Agreements.accept!` resolves the current version server-side, requires the
-submitted ID to match it, derives opaque keys from the server-owned subject and
-actor, and records the exact localized plain-text statement selected by the
-host. Do not accept either value from browser parameters. Retries, double
-clicks, and concurrent submissions return the original acceptance evidence.
+```ruby
+accept_agreement("user_terms", subject: users(:alice))
+```
 
-A missing, malformed, wrong-agreement, or stale ID raises
-`Agreements::VersionNotCurrent`. Its `current_version` is ready to render. It
-is `nil` when no version exists for that key yet:
+Add the current versions to your fixtures or test setup first. The helper raises
+when no current version exists.
 
-```ruby
-rescue Agreements::VersionNotCurrent => error
-  raise ActiveRecord::RecordNotFound unless error.current_version
+## Guides
 
-  @version = error.current_version
-  render :show, status: :unprocessable_content
-end
-```
+### Agreements for a company (DPA)
 
-Authorization stays in the host. For an organization DPA, for example, verify
-the actor is the current owner before calling:
+The organisation is the **subject**: it is bound by the agreement. The user who
+clicks is the **actor**. Check in your app that the actor may accept, then
+record the authority you checked:
 
 ```ruby
 Agreements.accept!(
   "organization_dpa",
   version_id: params.dig(:acceptance, :agreement_version_id),
-  subject: current_organization,
-  actor: current_user,
+  subject: Current.organization,
+  actor: Current.user,
   authority: "organization_owner",
-  acceptance_statement: I18n.t("agreements.organization_dpa.statement"),
+  acceptance_statement: t("dpa_acceptances.statement", organization: Current.organization.name),
   locale: I18n.locale.to_s
 )
 ```
 
-Uniqueness belongs to the organization subject, so a later ownership transfer
-does not invalidate an existing acceptance.
-
-## Enforce an agreement
-
-Include the small controller concern in your application controller:
-
-```ruby
-class ApplicationController < ActionController::Base
-  include Agreements::Enforcement
-end
-```
+The acceptance belongs to the organisation. If ownership moves to another user
+later, the organisation does not have to accept again.
 
-Call it from a host-owned before action after authentication and tenant context
-are established:
+`require_agreement` returns `nil`, `:redirected` or `:forbidden`. Use it to
+skip work after a halted request, for example Pundit's `verify_authorized`:
 
 ```ruby
-def require_organization_dpa
-  require_agreement(
-    "organization_dpa",
-    subject: Current.organization,
-    location: organization_dpa_path(Current.organization)
-  )
-end
+skip_authorization if require_agreement("organization_dpa", subject: Current.organization, location: dpa_path)
 ```
 
-When the agreement is pending:
-
-- an HTML or Turbo Stream request is redirected to `location` with
-  `303 See Other`, and the method returns `:redirected`;
-- any other request (JSON, CSV, PDF, API) gets an empty `403 Forbidden`, and
-  the method returns `:forbidden`.
+### Change your Terms with notice
 
-The return value lets you skip work that should not run after a halted
-request, such as Pundit's `verify_authorized`:
+Terms often promise notice before a change applies, such as "at least 14 days
+before the changes take effect". Add the new version when you send the notice,
+with the date it takes effect:
 
 ```ruby
-skip_authorization if require_agreement("organization_dpa", subject: Current.organization, location: path)
+VERSION = {
+  agreement_key: "user_terms",
+  version: "2026-12-01",
+  effective_at: Time.utc(2026, 12, 1),
+  acceptance_statement: "I accept the Terms of Service and acknowledge the Privacy Notice.",
+  documents: [{ key: "terms_of_service", title: "Terms of Service", url: "https://example.com/terms-2026-12-01" }]
+}.freeze
 ```
 
-Only GET and HEAD return locations are remembered. A blocked mutation is never
-replayed after acceptance. Consume the safe same-origin path after a successful
-acceptance:
+- Until `effective_at`, the previous version stays current. Nobody is asked to
+  accept, and `accept!` refuses the new version.
+- `Agreements.upcoming_version("user_terms")` returns the scheduled version, so
+  you can show a notice in the app.
+- From `effective_at`, the new version is current, and everyone who has not
+  accepted it is asked once.
+- Without `effective_at`, a version is current as soon as it is inserted.
+- The current version is the one that took effect most recently. If two take
+  effect at the same time, the one inserted later wins.
+- To cancel a scheduled version before its date, delete it in a data migration
+  with a migration-local model. It cannot have acceptances yet.
+- Publish the new document URL before the version takes effect. Use a new URL
+  for each version, so old acceptances keep pointing at the text people saw.
+
+### Show translated document links
+
+Give each document a `key`. Look up the link title in your locale files, so
+your views do not depend on the English `title`:
 
-```ruby
-redirect_to agreement_return_location || dashboard_path
+```erb
+<% @version.documents.each do |document| %>
+  <%= link_to t("documents.#{document["key"]}"), document["url"] %>
+<% end %>
 ```
 
-If your API has its own error format, check before `require_agreement` runs:
+### APIs and JSON
+
+`require_agreement` answers non-HTML requests with an empty `403`. If your API
+has its own error format, check first:
 
 ```ruby
-def require_organization_dpa
+def require_dpa
   if api_request?
     if Agreements.pending_version("organization_dpa", subject: Current.organization)
       render json: { error: "agreement_required" }, status: :forbidden
@@ -285,139 +369,172 @@ def require_organization_dpa
     return
   end
 
-  require_agreement("organization_dpa", subject: Current.organization, location: organization_dpa_path(Current.organization))
+  require_agreement("organization_dpa", subject: Current.organization, location: main_app.dpa_path)
 end
 ```
 
-When no version exists for a key, nothing is pending and nothing is blocked.
-Insert the first version before you rely on enforcement.
-
-## Test your application
+### Answer an audit request
 
-Once enforcement is on, most of your tests need subjects that have already
-accepted. Include the test helper:
+Acceptances are ordinary Active Record rows:
 
 ```ruby
-# test/test_helper.rb
-require "agreements/test_helper"
-
-class ActiveSupport::TestCase
-  include Agreements::TestHelper
-end
+Agreements::Acceptance
+  .includes(:agreement_version)
+  .where(subject_key: organization.to_global_id.to_s)
+  .order(:accepted_at)
 ```
 
+The gem has no admin screen and no export. Build one when a real audit tells
+you which format and access controls it needs.
+
+### Keep subject keys stable
+
+Subjects and actors are stored as Global ID strings, such as
+`gid://my-app/User/1`. The string contains your app name and the model class.
+If either changes, old acceptances no longer match and everyone is asked again.
+Pin the app name now:
+
 ```ruby
-accept_agreement("user_terms", subject: user)
-accept_agreement("organization_dpa", subject: organization, actor: owner, authority: "organization_owner")
+# config/application.rb
+config.global_id.app = "my-app"
 ```
 
-`accept_agreement` accepts the current version with its canonical statement and
-the `en` locale. It raises when no current version exists, so insert versions
-in your fixtures or setup first.
+Before you rename a model, plan how to carry its acceptances over. You can also
+pass your own non-empty string as subject or actor.
 
-## Evidence model
+## API reference
 
-`agreements_versions` contains:
+### Module methods
 
-- agreement key;
-- human version label;
-- exact acceptance statement;
-- external document references and optional SHA-256 digests;
-- optional effective date;
-- timestamps.
+| Method | Returns |
+|---|---|
+| `Agreements.current_version(key)` | The `Agreements::Version` in effect now, or `nil` |
+| `Agreements.upcoming_version(key)` | The next scheduled version, or `nil` |
+| `Agreements.pending_version(key, subject:)` | The current version if `subject` has not accepted it, otherwise `nil` |
+| `Agreements.accept!(key, version_id:, subject:, actor:, authority:, acceptance_statement:, locale:)` | The new or existing `Agreements::Acceptance` |
+| `Agreements.identity_key(record_or_string)` | The stored key for a subject or actor |
 
-`agreements_acceptances` contains:
+`accept!` raises:
 
-- agreement-version foreign key;
-- opaque subject and actor keys;
-- authority;
-- exact localized acceptance statement and locale;
-- server acceptance time;
-- timestamps.
+- `Agreements::VersionNotCurrent` when `version_id` is missing, malformed, for
+  another agreement or no longer current. `error.current_version` is the
+  version to show, or `nil` when none exists;
+- `Agreements::InvalidIdentity` when a subject or actor is neither a non-empty
+  string nor a record with `to_global_id`;
+- `ActiveRecord::RecordInvalid` when `authority`, `acceptance_statement` or
+  `locale` is blank, or `authority` has characters other than `a-z`, `0-9` and `_`.
 
-Persisted versions and acceptances are read-only through the model API. The gem
-does not claim protection from a privileged database owner.
+### Controller methods (`include Agreements::Enforcement`)
 
-For an exceptional audit request, query ordinary Active Record rows:
+| Method | Behaviour |
+|---|---|
+| `require_agreement(key, subject:, location:)` | `nil` when nothing is pending. Otherwise redirects HTML and Turbo Stream requests to `location` (returns `:redirected`) or renders `403` for others (returns `:forbidden`) |
+| `agreement_return_location` | The same-origin path saved by `require_agreement`, read once, or `nil` |
 
-```ruby
-Agreements::Acceptance
-  .includes(:agreement_version)
-  .where(subject_key: current_organization.to_global_id.to_s)
-```
+### Test helper (`require "agreements/test_helper"`)
+
+| Method | Behaviour |
+|---|---|
+| `accept_agreement(key, subject:, actor: subject, authority: "self", locale: "en")` | Accepts the current version with its canonical statement |
 
-Build an export only when a real audit defines the required format and access
-controls.
+### Models
 
-## Shipping version two
+`Agreements::Version`
 
-1. Publish immutable/versioned legal-document URLs and any verified digests.
-2. Add the finished bundle to the host's seed registry.
-3. Add a host data migration that inserts the same immutable version, with
-   `effective_at` if your terms promise notice.
-4. Deploy. The new row becomes current at once, or on its effective date, and
-   subjects missing it are prompted.
+| Attribute | Notes |
+|---|---|
+| `agreement_key` | `a-z`, `0-9` and `_`, for example `user_terms` |
+| `version` | Your label, for example `2026-08-16`. Unique per key |
+| `acceptance_statement` | The canonical statement for this version |
+| `documents` | At least one `{ title:, url:, sha256:, key: }`. `url` must be HTTPS. `sha256` and `key` are optional |
+| `effective_at` | Optional. The version is current from this time |
 
-Production deployments normally run migrations, not seeds. Changing a seed
-registry alone does not deploy a new version to an existing installation.
+`Agreements::Acceptance`
+
+| Attribute | Notes |
+|---|---|
+| `agreement_version` | The accepted version |
+| `subject_key`, `actor_key` | Global ID strings or your own strings |
+| `authority` | Why the actor could accept, for example `self` or `organization_owner` |
+| `acceptance_statement`, `locale` | The exact sentence shown and its language |
+| `accepted_at` | Server time of acceptance |
+
+Both models are read-only once saved. Updates and deletes through the model API
+raise `ActiveRecord::ReadOnlyRecord`. A database user with direct SQL access
+can still change rows.
 
 ## What the evidence proves
 
 The gem records which version and which sentence a subject accepted, who did
-it, under what authority, and when. That is the part your application can
-prove later. Some questions it cannot answer for you:
+it, under what authority, and when. Some questions it cannot answer for you:
 
 - **The whole page counts.** Courts look at the entire screen, not only the
   checkbox. In *Berman v. Freedom Financial Network* (9th Cir. 2022) the terms
   did not bind the user: the notice was small grey text, the links did not
   look like links, and the button said "Continue" without saying that it meant
-  acceptance. Your layout, contrast and button text decide this. The gem does
-  not see them.
+  acceptance. Your layout, contrast and button text decide this.
 - **It is not a qualified electronic signature.** Under eIDAS (Regulation (EU)
   No 910/2014, Article 25), an electronic signature cannot be denied legal
   effect only because it is electronic or not qualified. A checkbox is still
   not a qualified electronic signature, and this gem does not create one.
 - **Acknowledging a privacy notice is not consent.** Under the GDPR you inform
-  people (Article 13). Consent (Articles 6 and 7) is a separate, specific and
-  withdrawable choice. Keep the two apart in your copy and your records.
+  people (Article 13). Consent (Articles 6 and 7) is a separate, specific
+  choice that people can withdraw. Keep the two apart.
 - **The text of your terms still matters.** In the EU, an unfair term in a
   consumer contract does not bind the consumer (Directive 93/13/EEC), however
   clearly it was accepted.
-- **Identity and authority are yours to check.** The gem stores the actor and
-  the authority you pass. It does not verify who the person is or whether they
-  may bind an organization.
-
-Your counsel decides what your agreements need. The gem keeps the record of
-what was accepted.
-
-## Not this gem
-
-- Legal-document hosting, editing, rendering, uploads, or a CMS.
-- Draft/publish/activation workflows or an admin dashboard.
-- Electronic signatures or identity proofing.
-- IP addresses, user agents, fingerprints, geolocation, or request provenance.
-- Presentation manifests, browser snapshots, scroll tracking, or one-time nonces.
-- Consent withdrawal, declarations, attestations, authorizations, retention,
-  legal holds, integrity chains, or compliance reporting.
-- Application-specific onboarding, marketing consent, tenancy, ownership,
-  layouts, routes, or copy.
-
-Those are real product categories. They are not prerequisites for proving an
-ordinary Terms or organization-DPA acceptance. If you need consent withdrawal,
-signed receipts, request evidence or a form builder, look at
-[clickwrap](https://github.com/rameerez/clickwrap).
-
-## Later, only after a concrete trigger
-
-- **Atomic protected actions:** if evidence must accompany a payout, data
-  handoff, or contract execution, commit the evidence and action in one
-  transaction.
-- **Standalone receipts:** if counsel or an auditor requests a repeatable
-  package, export the smallest proven evidence set as canonical JSON or HTML.
-- **Automated digest verification:** if exact bytes must be reproduced, verify
-  and archive them in the trusted document-publishing pipeline, not during a
-  user's acceptance request.
+- **Identity and authority are your checks.** The gem stores the actor and the
+  authority you pass. It does not verify who the person is or whether they may
+  bind an organisation.
+
+Your lawyer decides what your agreements need. The gem keeps the record.
+
+## What this gem does not do
+
+- Host, edit or render legal documents.
+- Drafts, approval workflows or an admin dashboard.
+- Electronic signatures or identity checks.
+- IP addresses, user agents or other request data.
+- Consent withdrawal, retention rules or reports.
+- Your routes, views, copy, onboarding or authorization.
+
+## Versioning
+
+The gem follows semantic versioning. Before 1.0, a minor release (0.x.0) may
+change behaviour or the schema. Each such release lists the change and the
+upgrade steps in the [CHANGELOG](CHANGELOG.md) and below. Patch releases
+(0.x.y) never break your app.
+
+### Upgrading from 0.3
+
+Version 0.4 adds a nullable `effective_at` column to `agreements_versions`:
+
+```bash
+bin/rails generate migration AddEffectiveAtToAgreementsVersions effective_at:datetime
+bin/rails db:migrate
+```
+
+Existing rows keep `effective_at` empty and stay in effect from their creation.
+
+### Upgrading from 0.2
+
+Version 0.3 has no schema change. `require_agreement` now answers a pending
+non-HTML request with `403 Forbidden` instead of letting it through. If your
+API already checks `pending_version` before calling it, nothing changes.
+
+### Upgrading from 0.1
+
+Version 0.2 adds non-null `acceptance_statement` and `locale` columns to
+`agreements_acceptances`. Add them in a migration before upgrading. For existing
+rows, copy each version's canonical statement and use `und` as the locale when
+the displayed language is unknown.
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/yshmarov/agreements/issues). See
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup and scope.
 
 ## License
 
-MIT.
+[MIT](MIT-LICENSE). Maintained by [Yaroslav Shmarov](https://github.com/yshmarov).

data/SECURITY.md

@@ -1,6 +1,17 @@
 # Security
 
-Report vulnerabilities privately through GitHub's security advisory feature.
+## Reporting
+
+Report vulnerabilities privately through
+[GitHub private reporting](https://github.com/yshmarov/agreements/security/advisories/new).
+Do not open a public issue.
+
+## Supported versions
+
+Security fixes go to the latest release. Before 1.0 that is the latest 0.x
+version.
+
+## Scope
 
 The gem resolves actor, subject, authority, and acceptance time from values the
 host passes server-side. A submitted version ID is accepted only when it matches

data/lib/agreements/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agreements
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agreements
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -84,11 +84,12 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '9'
 description: |
-  A small Rails engine that stores immutable external agreement-version
-  metadata and append-only localized acceptance evidence. It distinguishes
-  the subject bound by an agreement from the actor accepting under recorded
-  authority, rejects stale rendered versions, and leaves documents,
-  authentication, authorization, routes, and UI in the host application.
+  Versioned acceptance of legal agreements for Rails. Stores which version
+  and which localized sentence was accepted, by whom, for whom (a user or a
+  company), under what authority and when. Redirects users who still have to
+  accept, supports a notice period before new terms take effect, and rejects
+  submissions of an outdated version. Two tables, no UI, no external services.
+  In production at EthicsPortal.
 email:
 - yashm@outlook.com
 executables: []
@@ -120,6 +121,7 @@ metadata:
   homepage_uri: https://github.com/yshmarov/agreements
   source_code_uri: https://github.com/yshmarov/agreements/tree/main
   changelog_uri: https://github.com/yshmarov/agreements/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/yshmarov/agreements#readme
   bug_tracker_uri: https://github.com/yshmarov/agreements/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -138,5 +140,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: Auditable acceptance of externally hosted legal agreements for Rails.
+summary: Record who accepted which version of your Terms, Privacy Notice or DPA, and
+  ask again when they change.
 test_files: []