agreements 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d0c0ec7930db8014c275731beebb35381ce05acc26e7b56ec68e3a6e1d8dcd1
-  data.tar.gz: ec47850af89352033e3ff2f9458073fcc33508b6cfeaddb97687a9f969b3b828
+  metadata.gz: 81d911005203680cbf4a2c85a8da0c4bec60c04c9094e3e35af19c8e4fb595d7
+  data.tar.gz: 67a34497cc8a10c5f2803745e28b45949eb0ef550aa951b57f08f588c1c809cb
 SHA512:
-  metadata.gz: 48879a71eb8489ee500f01172ba0e25488730aeb263c41478b9f3f910cf6a7c6c12bd7c1ae03e8244b65fe9f733ec9e2949010ac0482ba51d1bcf59313663a65
-  data.tar.gz: a67ad2a4e8282b7b8a1f1fe71842e3797123eb3611d1a36c4dd60b163085a325846797431ff67c92aca9224fba3bd5c2cacaca804dd0255bc24628508f3d4351
+  metadata.gz: 6f78483f20c53fdb31f4c0537c96016d216efb6b362ea35bdb8090752c6585a4ad76f19885cd81f051f55955d355bb58510edb0031266eef37bc32e89c45ed84
+  data.tar.gz: 6c64d27234a8d20e0bdece9b695ec67e3272da6df194abbe4f894490831f9659361e0891a3a70a38a2ed375e3caf773bacd13586fbc358381e53df39213ada35

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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.
+- Publish releases through RubyGems trusted publishing.
+
 ## 0.1.0 - 2026-08-25
 
 - Extract the agreement-version and acceptance primitives proven in EthicsPortal.

data/README.md

@@ -4,8 +4,8 @@ Auditable acceptance of externally hosted legal agreements for Rails.
 
 `agreements` answers one durable question:
 
-> Which agreement version did this subject accept, who performed the
-> acceptance, under what authority, and when?
+> 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
@@ -29,31 +29,72 @@ 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
+`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.
+
 ## 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
 
@@ -66,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
@@ -79,25 +133,33 @@ application. Submit the exact displayed version as a hidden field:
 Then record only that version while it remains current:
 
 ```ruby
+statement = I18n.t("agreements.user_terms.statement")
+
 acceptance = Agreements.accept!(
   "user_terms",
   version_id: params.dig(:acceptance, :agreement_version_id),
   subject: current_user,
   actor: current_user,
-  authority: "self"
+  authority: "self",
+  acceptance_statement: statement,
+  locale: I18n.locale.to_s
 )
 ```
 
 `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 one acceptance per subject and version. Retries, double
-clicks, and concurrent submissions return the original acceptance.
+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.
 
 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
@@ -112,7 +174,9 @@ Agreements.accept!(
   version_id: params.dig(:acceptance, :agreement_version_id),
   subject: current_organization,
   actor: current_user,
-  authority: "organization_owner"
+  authority: "organization_owner",
+  acceptance_statement: I18n.t("agreements.organization_dpa.statement"),
+  locale: I18n.locale.to_s
 )
 ```
 
@@ -142,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
 
@@ -168,6 +261,7 @@ the response contract your application supports.
 - agreement-version foreign key;
 - opaque subject and actor keys;
 - authority;
+- exact localized acceptance statement and locale;
 - server acceptance time;
 - timestamps.
 
@@ -201,7 +295,7 @@ registry alone does not deploy a new version to an existing installation.
 - Draft/publish/activation workflows or an admin dashboard.
 - Electronic signatures or identity proofing.
 - IP addresses, user agents, fingerprints, geolocation, or request provenance.
-- Presentation manifests, snapshots, scroll tracking, or one-time nonces.
+- 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,

data/app/models/agreements/acceptance.rb

@@ -6,7 +6,7 @@ module Agreements
                class_name: "Agreements::Version",
                inverse_of: :acceptances
 
-    validates :subject_key, :actor_key, :authority, :accepted_at, presence: true
+    validates :subject_key, :actor_key, :authority, :acceptance_statement, :locale, :accepted_at, presence: true
     validates :authority, format: { with: /\A[a-z0-9_]+\z/ }
 
     def readonly?

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/recorder.rb

@@ -2,13 +2,15 @@
 
 module Agreements
   class Recorder
-    def self.call(agreement_version:, subject:, actor:, authority:)
+    def self.call(agreement_version:, evidence:)
       Acceptance.create_or_find_by!(
         agreement_version: agreement_version,
-        subject_key: Agreements.identity_key(subject)
+        subject_key: Agreements.identity_key(evidence.fetch(:subject))
       ) do |acceptance|
-        acceptance.actor_key = Agreements.identity_key(actor)
-        acceptance.authority = authority
+        acceptance.actor_key = Agreements.identity_key(evidence.fetch(:actor))
+        acceptance.authority = evidence.fetch(:authority)
+        acceptance.acceptance_statement = evidence.fetch(:acceptance_statement)
+        acceptance.locale = evidence.fetch(:locale)
         acceptance.accepted_at = Time.current
       end
     end

data/lib/agreements/version.rb

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

data/lib/agreements.rb

@@ -23,15 +23,21 @@ module Agreements
       end
     end
 
-    def accept!(agreement_key, version_id:, subject:, actor:, authority:)
+    # Explicit keywords keep this evidence boundary distinct from browser params.
+    # rubocop:disable-next Metrics/ParameterLists
+    def accept!(agreement_key, version_id:, subject:, actor:, authority:, acceptance_statement:, locale:)
       version = current_version(agreement_key)
       raise VersionNotCurrent, version unless version&.id.to_s == version_id.to_s
 
       Recorder.call(
         agreement_version: version,
-        subject: subject,
-        actor: actor,
-        authority: authority
+        evidence: {
+          subject: subject,
+          actor: actor,
+          authority: authority,
+          acceptance_statement: acceptance_statement,
+          locale: locale
+        }
       )
     end
 

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

@@ -21,6 +21,8 @@ class CreateAgreementsTables < ActiveRecord::Migration<%= migration_version %>
       t.string :subject_key, null: false
       t.string :actor_key, null: false
       t.string :authority, null: false
+      t.text :acceptance_statement, null: false
+      t.string :locale, null: false
       t.datetime :accepted_at, null: false
       t.timestamps
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agreements
 version: !ruby/object:Gem::Version
-  version: 0.1.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:
     - - ">="
@@ -31,10 +85,10 @@ dependencies:
         version: '9'
 description: |
   A small Rails engine that stores immutable external agreement-version
-  metadata and append-only 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.
+  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.
 email:
 - yashm@outlook.com
 executables: []
@@ -81,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Auditable acceptance of externally hosted legal agreements for Rails.
 test_files: []