agreements 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbb4e3cb21a8e743ea9fab48f117242cad49d78e752258bbb992894498355be4
-  data.tar.gz: f2160a49ff3799851018060c773643c9b829bad4a1d3e22944913cef62dae501
+  metadata.gz: 81d911005203680cbf4a2c85a8da0c4bec60c04c9094e3e35af19c8e4fb595d7
+  data.tar.gz: 67a34497cc8a10c5f2803745e28b45949eb0ef550aa951b57f08f588c1c809cb
 SHA512:
-  metadata.gz: 70299f73fe7bc2b6760aae7b1389fa3913298175554ac001963270372c97af651bec611613ae51d367a320dd6d785b154517cccc1c468eece83f7b25e3c0212c
-  data.tar.gz: 7a27e58cf17b1068ecee2705f510f38f6900829eb77c5177b8a77237cb19be6e581b728f8a2eba56f973e8850977fa72e612af28dbdbafd1d787d11d86ad2e60
+  metadata.gz: 6f78483f20c53fdb31f4c0537c96016d216efb6b362ea35bdb8090752c6585a4ad76f19885cd81f051f55955d355bb58510edb0031266eef37bc32e89c45ed84
+  data.tar.gz: 6c64d27234a8d20e0bdece9b695ec67e3272da6df194abbe4f894490831f9659361e0891a3a70a38a2ed375e3caf773bacd13586fbc358381e53df39213ada35

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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,12 @@ view, initializer, JavaScript, CSS, or admin dashboard to integrate.
 
 Ruby >= 3.2 · Rails >= 7.1 and < 9 · PostgreSQL and SQLite
 
+### 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 +44,57 @@ 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!(
-  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" }
-  ]
-)
+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.
+
 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.
 
-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.
+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 +107,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 +153,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 +206,45 @@ 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.
 
 ## Evidence model
 

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,7 +13,7 @@ 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
 
@@ -51,13 +52,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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agreements
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.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:
     - - ">="
@@ -81,7 +135,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: []