agreements 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbb4e3cb21a8e743ea9fab48f117242cad49d78e752258bbb992894498355be4
-  data.tar.gz: f2160a49ff3799851018060c773643c9b829bad4a1d3e22944913cef62dae501
+  metadata.gz: 921978d679f2c21c42fda41e4caa14e844e5fbfbb57a10c78738811441814547
+  data.tar.gz: 342464faa1422920f63ca881f7d64728d35e6b88c7e595d351a06c181a7692cd
 SHA512:
-  metadata.gz: 70299f73fe7bc2b6760aae7b1389fa3913298175554ac001963270372c97af651bec611613ae51d367a320dd6d785b154517cccc1c468eece83f7b25e3c0212c
-  data.tar.gz: 7a27e58cf17b1068ecee2705f510f38f6900829eb77c5177b8a77237cb19be6e581b728f8a2eba56f973e8850977fa72e612af28dbdbafd1d787d11d86ad2e60
+  metadata.gz: c1cf67625ad815b0e3df2033a609cd510cf9c4ca97888b518c842546bb174b3c22abfd7bfc2670d0756337c3e24465b2e70b4a52887dbbf7e0a1a9c7c78a939b
+  data.tar.gz: 60cd61c042671c9bcb86f1e2f3c37ceeba9bfa2600aee3082766fe8b2124a38a7c81bc3b7ae5328f65f6265d6ac8ac6ef2f77416cd3d28547fd1c70bb47607a3

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.4.0 - 2026-11-12
+
+- Add an optional `effective_at` to versions, so a version can be inserted when
+  notice is given and become current on the date it takes effect. Requires a
+  new nullable column; see "Upgrading from 0.3" in the README.
+- Add `Agreements.upcoming_version` to show the next scheduled version.
+- Add `Agreements::TestHelper#accept_agreement` for host test suites.
+- Explain in the README what acceptance evidence does and does not prove.
+
+## 0.3.0 - 2026-11-12
+
+- Answer pending non-HTML requests with `403 Forbidden` instead of letting them
+  through. `require_agreement` returns `:forbidden` for them.
+- Reject `/\host` return paths, using Rails' `url_from`.
+- Accept an optional `key` on document references for translated link titles.
+- Depend on Action Pack, Active Record, Railties and Global ID instead of all
+  of Rails.
+- Document the safe data-migration pattern, Global ID app pinning and a `nil`
+  `current_version` on `VersionNotCurrent`.
+
 ## 0.2.0 - 2026-08-27
 
 - Record the exact localized acceptance statement and locale shown by the host.

data/README.md

@@ -29,6 +29,23 @@ view, initializer, JavaScript, CSS, or admin dashboard to integrate.
 
 Ruby >= 3.2 · Rails >= 7.1 and < 9 · PostgreSQL and SQLite
 
+### 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
@@ -38,29 +55,92 @@ locale such as `und` when the displayed locale is unknown.
 
 ## Define a version
 
-Agreement versions are deployed data. Create them in a data migration and keep
-the same registry in your seeds for fresh databases:
+Agreement versions are deployed data. Insert them in a data migration, and keep
+the same list in your seeds so fresh databases match production:
 
 ```ruby
-Agreements::Version.create!(
+class AddUserTerms20260816 < ActiveRecord::Migration[8.1]
+  class Version < ActiveRecord::Base
+    self.table_name = "agreements_versions"
+  end
+
+  VERSION = {
+    agreement_key: "user_terms",
+    version: "2026-08-16",
+    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-08-16" },
+      { key: "privacy_notice", title: "Privacy Notice", url: "https://example.com/privacy-2026-08-16" }
+    ]
+  }.freeze
+
+  def up
+    version = Version.find_or_create_by!(VERSION.slice(:agreement_key, :version)) do |record|
+      record.assign_attributes(VERSION)
+    end
+
+    unless version.acceptance_statement == VERSION[:acceptance_statement] &&
+           version.documents == VERSION[:documents].as_json
+      raise "#{version.agreement_key} #{version.version} already exists with different content"
+    end
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Agreement versions are evidence"
+  end
+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.
+
+### 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:
+
+```ruby
+VERSION = {
   agreement_key: "user_terms",
-  version: "2026-08-16",
-  acceptance_statement: "I accept the Terms of Service and acknowledge the Privacy Notice.",
-  documents: [
-    { title: "Terms of Service", url: "https://example.com/terms" },
-    { title: "Privacy Notice", url: "https://example.com/privacy" }
-  ]
-)
+  version: "2026-12-01",
+  effective_at: Time.utc(2026, 12, 1),
+  # acceptance_statement, documents ...
+}.freeze
 ```
 
-The newest inserted row for an agreement key is current immediately. There is
-no draft, publish, activate, or scheduling lifecycle. A correction or legal
-update is a new immutable row with a new version label.
+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
+```
 
-Document references accept `title`, an HTTPS `url`, and an optional 64-character
-`sha256`. 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.
+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.
+
+Subjects cannot accept a scheduled version early. Someone who accepts the
+current version during the notice period is asked again on the effective date.
+
+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.
+
+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.
 
 ## Ask what is pending
 
@@ -73,6 +153,19 @@ 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.
 
+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:
+
+```ruby
+# config/application.rb
+config.global_id.app = "my-app"
+```
+
+Before you rename a model, plan how to carry its acceptances over. Acceptance
+rows are read only through the model API.
+
 ## Render the host-owned form
 
 Keep the page, routes, authorization, document-link markup, and copy in your
@@ -106,10 +199,13 @@ host. Do not accept either value from browser parameters. Retries, double
 clicks, and concurrent submissions return the original acceptance evidence.
 
 A missing, malformed, wrong-agreement, or stale ID raises
-`Agreements::VersionNotCurrent`. Its `current_version` is ready to render:
+`Agreements::VersionNotCurrent`. Its `current_version` is ready to render. It
+is `nil` when no version exists for that key yet:
 
 ```ruby
 rescue Agreements::VersionNotCurrent => error
+  raise ActiveRecord::RecordNotFound unless error.current_version
+
   @version = error.current_version
   render :show, status: :unprocessable_content
 end
@@ -156,16 +252,68 @@ def require_organization_dpa
 end
 ```
 
-It redirects pending HTML/Turbo requests and remembers only GET or HEAD return
-locations. A blocked mutation is never replayed after acceptance. Consume the
-safe same-origin path after a successful acceptance:
+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`.
+
+The return value lets you skip work that should not run after a halted
+request, such as Pundit's `verify_authorized`:
+
+```ruby
+skip_authorization if require_agreement("organization_dpa", subject: Current.organization, location: path)
+```
+
+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:
 
 ```ruby
 redirect_to agreement_return_location || dashboard_path
 ```
 
-API and headless behavior remains host-owned: use `pending_version` and return
-the response contract your application supports.
+If your API has its own error format, check before `require_agreement` runs:
+
+```ruby
+def require_organization_dpa
+  if api_request?
+    if Agreements.pending_version("organization_dpa", subject: Current.organization)
+      render json: { error: "agreement_required" }, status: :forbidden
+    end
+    return
+  end
+
+  require_agreement("organization_dpa", subject: Current.organization, location: organization_dpa_path(Current.organization))
+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
+
+Once enforcement is on, most of your tests need subjects that have already
+accepted. Include the test helper:
+
+```ruby
+# test/test_helper.rb
+require "agreements/test_helper"
+
+class ActiveSupport::TestCase
+  include Agreements::TestHelper
+end
+```
+
+```ruby
+accept_agreement("user_terms", subject: user)
+accept_agreement("organization_dpa", subject: organization, actor: owner, authority: "organization_owner")
+```
+
+`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.
 
 ## Evidence model
 
@@ -175,6 +323,7 @@ the response contract your application supports.
 - human version label;
 - exact acceptance statement;
 - external document references and optional SHA-256 digests;
+- optional effective date;
 - timestamps.
 
 `agreements_acceptances` contains:
@@ -204,12 +353,43 @@ controls.
 
 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.
-4. Deploy. The new row becomes current and subjects missing it are prompted.
+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.
 
 Production deployments normally run migrations, not seeds. Changing a seed
 registry alone does not deploy a new version to an existing installation.
 
+## 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:
+
+- **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.
+- **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.
+- **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.
@@ -223,7 +403,9 @@ registry alone does not deploy a new version to an existing installation.
   layouts, routes, or copy.
 
 Those are real product categories. They are not prerequisites for proving an
-ordinary Terms or organization-DPA acceptance.
+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
 

data/app/models/agreements/version.rb

@@ -5,6 +5,7 @@ require "uri"
 module Agreements
   class Version < ApplicationRecord
     SHA256_PATTERN = /\A[0-9a-f]{64}\z/i
+    KEY_PATTERN = /\A[a-z0-9_]+\z/
 
     has_many :acceptances,
              class_name: "Agreements::Acceptance",
@@ -12,12 +13,33 @@ module Agreements
              inverse_of: :agreement_version,
              dependent: :restrict_with_exception
 
-    validates :agreement_key, presence: true, format: { with: /\A[a-z0-9_]+\z/ }, uniqueness: { scope: :version }
+    validates :agreement_key, presence: true, format: { with: KEY_PATTERN }, uniqueness: { scope: :version }
     validates :version, :acceptance_statement, presence: true
     validate :documents_are_external_references
 
-    def self.current_for(agreement_key)
-      where(agreement_key: agreement_key).order(created_at: :desc, id: :desc).first
+    # Filtering by time in Ruby keeps the SQL identical, so the query cache
+    # serves repeated checks within a request. Each key has only a few versions.
+    def self.current_for(agreement_key, now: Time.current)
+      versions = where(agreement_key: agreement_key).to_a
+      versions.select { |version| version.in_effect?(now) }.max_by(&:precedence)
+    end
+
+    def self.upcoming_for(agreement_key, now: Time.current)
+      scheduled = where(agreement_key: agreement_key).to_a.reject { |version| version.in_effect?(now) }
+      next_from = scheduled.map(&:effective_from).min
+      scheduled.select { |version| version.effective_from == next_from }.max_by(&:precedence)
+    end
+
+    def precedence
+      [effective_from, created_at, id]
+    end
+
+    def effective_from
+      effective_at || created_at
+    end
+
+    def in_effect?(now = Time.current)
+      effective_from <= now
     end
 
     def accepted_by?(subject)
@@ -51,13 +73,18 @@ module Agreements
     end
 
     def allowed_document_attributes?(attributes)
-      attributes.keys.all? { |key| %w[title url sha256].include?(key) }
+      attributes.keys.all? { |key| %w[key title url sha256].include?(key) }
     end
 
     def complete_document_attributes?(attributes)
       attributes["title"].present? &&
         external_https_url?(attributes["url"]) &&
-        valid_sha256?(attributes["sha256"])
+        valid_sha256?(attributes["sha256"]) &&
+        valid_document_key?(attributes["key"])
+    end
+
+    def valid_document_key?(key)
+      key.nil? || key.to_s.match?(KEY_PATTERN)
     end
 
     def external_https_url?(url)

data/lib/agreements/enforcement.rb

@@ -9,9 +9,13 @@ module Agreements
     private
 
     def require_agreement(agreement_key, subject:, location:)
-      return unless agreement_enforcement_request?
       return unless Agreements.pending_version(agreement_key, subject: subject)
 
+      unless agreement_enforcement_request?
+        head :forbidden
+        return :forbidden
+      end
+
       remember_agreement_return_location
       redirect_to location, status: :see_other
       :redirected
@@ -30,8 +34,7 @@ module Agreements
     end
 
     def agreement_return_location
-      path = session.delete(:return_to_after_agreement)
-      path if path&.start_with?("/") && !path.start_with?("//")
+      url_from(session.delete(:return_to_after_agreement))
     end
   end
 end

data/lib/agreements/engine.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "global_id/railtie"
+
 module Agreements
   class Engine < ::Rails::Engine
   end

data/lib/agreements/test_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Agreements
+  module TestHelper
+    def accept_agreement(agreement_key, subject:, actor: subject, authority: "self", locale: "en")
+      version = Agreements.current_version(agreement_key)
+      raise ArgumentError, "no current #{agreement_key} version; insert one in your test setup" unless version
+
+      Agreements.accept!(
+        agreement_key,
+        version_id: version.id,
+        subject: subject,
+        actor: actor,
+        authority: authority,
+        acceptance_statement: version.acceptance_statement,
+        locale: locale
+      )
+    end
+  end
+end

data/lib/agreements/version.rb

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

data/lib/agreements.rb

@@ -17,6 +17,10 @@ module Agreements
       Version.current_for(agreement_key)
     end
 
+    def upcoming_version(agreement_key)
+      Version.upcoming_for(agreement_key)
+    end
+
     def pending_version(agreement_key, subject:)
       current_version(agreement_key).then do |version|
         version unless version.nil? || version.accepted_by?(subject)

data/lib/generators/agreements/install/templates/create_agreements_tables.rb.tt

@@ -7,6 +7,7 @@ class CreateAgreementsTables < ActiveRecord::Migration<%= migration_version %>
       t.string :version, null: false
       t.text :acceptance_statement, null: false
       t.json :documents, null: false, default: []
+      t.datetime :effective_at
       t.timestamps
 
       t.index %i[agreement_key version], unique: true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agreements
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -10,7 +10,61 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: globalid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -54,6 +108,7 @@ files:
 - lib/agreements/errors.rb
 - lib/agreements/identity.rb
 - lib/agreements/recorder.rb
+- lib/agreements/test_helper.rb
 - lib/agreements/version.rb
 - lib/generators/agreements/install/install_generator.rb
 - lib/generators/agreements/install/templates/create_agreements_tables.rb.tt
@@ -81,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Auditable acceptance of externally hosted legal agreements for Rails.
 test_files: []