agreements 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d0c0ec7930db8014c275731beebb35381ce05acc26e7b56ec68e3a6e1d8dcd1
+  data.tar.gz: ec47850af89352033e3ff2f9458073fcc33508b6cfeaddb97687a9f969b3b828
+SHA512:
+  metadata.gz: 48879a71eb8489ee500f01172ba0e25488730aeb263c41478b9f3f910cf6a7c6c12bd7c1ae03e8244b65fe9f733ec9e2949010ac0482ba51d1bcf59313663a65
+  data.tar.gz: a67ad2a4e8282b7b8a1f1fe71842e3797123eb3611d1a36c4dd60b163085a325846797431ff67c92aca9224fba3bd5c2cacaca804dd0255bc24628508f3d4351

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-08-25
+
+- Extract the agreement-version and acceptance primitives proven in EthicsPortal.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaroslav Shmarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,226 @@
+# agreements
+
+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?
+
+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
+
+```ruby
+# Gemfile
+gem "agreements"
+```
+
+```bash
+bundle install
+bin/rails generate agreements:install
+bin/rails db:migrate
+```
+
+The generator adds two tables and nothing else. There is no route, controller,
+view, initializer, JavaScript, CSS, or admin dashboard to integrate.
+
+Ruby >= 3.2 · Rails >= 7.1 and < 9 · PostgreSQL and SQLite
+
+## 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:
+
+```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" }
+  ]
+)
+```
+
+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.
+
+## Ask what is pending
+
+```ruby
+version = Agreements.current_version("user_terms")
+pending = Agreements.pending_version("user_terms", subject: current_user)
+```
+
+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.
+
+## Render the host-owned form
+
+Keep the page, routes, authorization, document-link markup, and copy in your
+application. Submit the exact displayed version as a hidden field:
+
+```erb
+<%= form.hidden_field :agreement_version_id, value: @version.id %>
+<%= form.check_box :confirmed, required: true %>
+```
+
+Then record only that version while it remains current:
+
+```ruby
+acceptance = Agreements.accept!(
+  "user_terms",
+  version_id: params.dig(:acceptance, :agreement_version_id),
+  subject: current_user,
+  actor: current_user,
+  authority: "self"
+)
+```
+
+`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.
+
+A missing, malformed, wrong-agreement, or stale ID raises
+`Agreements::VersionNotCurrent`. Its `current_version` is ready to render:
+
+```ruby
+rescue Agreements::VersionNotCurrent => error
+  @version = error.current_version
+  render :show, status: :unprocessable_content
+end
+```
+
+Authorization stays in the host. For an organization DPA, for example, verify
+the actor is the current owner before calling:
+
+```ruby
+Agreements.accept!(
+  "organization_dpa",
+  version_id: params.dig(:acceptance, :agreement_version_id),
+  subject: current_organization,
+  actor: current_user,
+  authority: "organization_owner"
+)
+```
+
+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
+```
+
+Call it from a host-owned before action after authentication and tenant context
+are established:
+
+```ruby
+def require_organization_dpa
+  require_agreement(
+    "organization_dpa",
+    subject: Current.organization,
+    location: organization_dpa_path(Current.organization)
+  )
+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:
+
+```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.
+
+## Evidence model
+
+`agreements_versions` contains:
+
+- agreement key;
+- human version label;
+- exact acceptance statement;
+- external document references and optional SHA-256 digests;
+- timestamps.
+
+`agreements_acceptances` contains:
+
+- agreement-version foreign key;
+- opaque subject and actor keys;
+- authority;
+- server acceptance time;
+- timestamps.
+
+Persisted versions and acceptances are read-only through the model API. The gem
+does not claim protection from a privileged database owner.
+
+For an exceptional audit request, query ordinary Active Record rows:
+
+```ruby
+Agreements::Acceptance
+  .includes(:agreement_version)
+  .where(subject_key: current_organization.to_global_id.to_s)
+```
+
+Build an export only when a real audit defines the required format and access
+controls.
+
+## Shipping version two
+
+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.
+
+Production deployments normally run migrations, not seeds. Changing a seed
+registry alone does not deploy a new version to an existing installation.
+
+## 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, 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.
+
+## 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.
+
+## License
+
+MIT.

data/SECURITY.md

@@ -0,0 +1,10 @@
+# Security
+
+Report vulnerabilities privately through GitHub's security advisory feature.
+
+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
+the current version for the expected agreement key.
+
+Persisted records are read-only through the model API. This does not protect
+against a privileged database owner or direct SQL mutation.

data/app/models/agreements/acceptance.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Agreements
+  class Acceptance < ApplicationRecord
+    belongs_to :agreement_version,
+               class_name: "Agreements::Version",
+               inverse_of: :acceptances
+
+    validates :subject_key, :actor_key, :authority, :accepted_at, presence: true
+    validates :authority, format: { with: /\A[a-z0-9_]+\z/ }
+
+    def readonly?
+      persisted?
+    end
+
+    def delete
+      raise ActiveRecord::ReadOnlyRecord, "Agreements::Acceptance is read only" if persisted?
+
+      super
+    end
+  end
+end

data/app/models/agreements/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Agreements
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/agreements/version.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Agreements
+  class Version < ApplicationRecord
+    SHA256_PATTERN = /\A[0-9a-f]{64}\z/i
+
+    has_many :acceptances,
+             class_name: "Agreements::Acceptance",
+             foreign_key: :agreement_version_id,
+             inverse_of: :agreement_version,
+             dependent: :restrict_with_exception
+
+    validates :agreement_key, presence: true, format: { with: /\A[a-z0-9_]+\z/ }, 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
+    end
+
+    def accepted_by?(subject)
+      acceptances.exists?(subject_key: Agreements.identity_key(subject))
+    end
+
+    def readonly?
+      persisted?
+    end
+
+    def delete
+      raise ActiveRecord::ReadOnlyRecord, "Agreements::Version is read only" if persisted?
+
+      super
+    end
+
+    private
+
+    def documents_are_external_references
+      unless documents.is_a?(Array) && documents.any?
+        errors.add(:documents, :invalid)
+        return
+      end
+
+      errors.add(:documents, :invalid) unless documents.all? { |document| valid_document?(document) }
+    end
+
+    def valid_document?(document)
+      attributes = document.stringify_keys if document.is_a?(Hash)
+      attributes && allowed_document_attributes?(attributes) && complete_document_attributes?(attributes)
+    end
+
+    def allowed_document_attributes?(attributes)
+      attributes.keys.all? { |key| %w[title url sha256].include?(key) }
+    end
+
+    def complete_document_attributes?(attributes)
+      attributes["title"].present? &&
+        external_https_url?(attributes["url"]) &&
+        valid_sha256?(attributes["sha256"])
+    end
+
+    def external_https_url?(url)
+      uri = URI.parse(url.to_s)
+      uri.is_a?(URI::HTTPS) && uri.host.present?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def valid_sha256?(sha256)
+      sha256.blank? || sha256.match?(SHA256_PATTERN)
+    end
+  end
+end

data/lib/agreements/enforcement.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Agreements
+  module Enforcement
+    extend ActiveSupport::Concern
+
+    private
+
+    def require_agreement(agreement_key, subject:, location:)
+      return unless agreement_enforcement_request?
+      return unless Agreements.pending_version(agreement_key, subject: subject)
+
+      remember_agreement_return_location
+      redirect_to location, status: :see_other
+      :redirected
+    end
+
+    def agreement_enforcement_request?
+      request.format.html? || request.format == Mime[:turbo_stream]
+    end
+
+    def remember_agreement_return_location
+      if request.get? || request.head?
+        session[:return_to_after_agreement] = request.fullpath
+      else
+        session.delete(:return_to_after_agreement)
+      end
+    end
+
+    def agreement_return_location
+      path = session.delete(:return_to_after_agreement)
+      path if path&.start_with?("/") && !path.start_with?("//")
+    end
+  end
+end

data/lib/agreements/engine.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Agreements
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/agreements/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Agreements
+  class Error < StandardError; end
+
+  class InvalidIdentity < Error; end
+
+  class VersionNotCurrent < Error
+    attr_reader :current_version
+
+    def initialize(current_version)
+      @current_version = current_version
+      super("The submitted agreement version is not current")
+    end
+  end
+end

data/lib/agreements/identity.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Agreements
+  module Identity
+    module_function
+
+    def key(identity)
+      value = identity.is_a?(String) ? identity : global_id_for(identity)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise InvalidIdentity, "identity must be a non-empty String or respond to #to_global_id"
+    end
+
+    def global_id_for(identity)
+      identity.to_global_id.to_s if identity.respond_to?(:to_global_id)
+    end
+    private_class_method :global_id_for
+  end
+end

data/lib/agreements/recorder.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Agreements
+  class Recorder
+    def self.call(agreement_version:, subject:, actor:, authority:)
+      Acceptance.create_or_find_by!(
+        agreement_version: agreement_version,
+        subject_key: Agreements.identity_key(subject)
+      ) do |acceptance|
+        acceptance.actor_key = Agreements.identity_key(actor)
+        acceptance.authority = authority
+        acceptance.accepted_at = Time.current
+      end
+    end
+  end
+end

data/lib/agreements/version.rb

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

data/lib/agreements.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "agreements/version"
+require "agreements/errors"
+require "agreements/identity"
+require "agreements/recorder"
+require "agreements/enforcement"
+require "agreements/engine"
+
+module Agreements
+  def self.table_name_prefix
+    "agreements_"
+  end
+
+  class << self
+    def current_version(agreement_key)
+      Version.current_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)
+      end
+    end
+
+    def accept!(agreement_key, version_id:, subject:, actor:, authority:)
+      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
+      )
+    end
+
+    def identity_key(identity)
+      Identity.key(identity)
+    end
+  end
+
+  private_constant :Recorder
+end

data/lib/generators/agreements/install/install_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require_relative "../migration_helpers"
+
+module Agreements
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      include MigrationHelpers
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Installs the agreement versions and acceptances migration."
+
+      def create_migration_file
+        migration_template "create_agreements_tables.rb.tt", "db/migrate/create_agreements_tables.rb"
+      end
+
+      def post_install
+        say "\nagreements installed. Run `bin/rails db:migrate`.", :green
+        say "Define finished agreement versions in host data migrations and seeds."
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class CreateAgreementsTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :agreements_versions<%= primary_key_type_option %> do |t|
+      t.string :agreement_key, null: false
+      t.string :version, null: false
+      t.text :acceptance_statement, null: false
+      t.json :documents, null: false, default: []
+      t.timestamps
+
+      t.index %i[agreement_key version], unique: true
+      t.index %i[agreement_key created_at]
+    end
+
+    create_table :agreements_acceptances<%= primary_key_type_option %> do |t|
+      t.references :agreement_version,
+                   null: false,
+                   index: false,
+                   foreign_key: { to_table: :agreements_versions }<%= reference_type_option %>
+      t.string :subject_key, null: false
+      t.string :actor_key, null: false
+      t.string :authority, null: false
+      t.datetime :accepted_at, null: false
+      t.timestamps
+
+      t.index %i[agreement_version_id subject_key],
+              unique: true,
+              name: "index_agreements_acceptances_on_version_and_subject"
+      t.index :subject_key
+    end
+  end
+end

data/lib/generators/agreements/migration_helpers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Agreements
+  module Generators
+    module MigrationHelpers
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      def primary_key_type_option
+        type = primary_key_type
+        type ? ", id: :#{type}" : ""
+      end
+
+      def reference_type_option
+        type = primary_key_type
+        type ? ", type: :#{type}" : ""
+      end
+
+      def primary_key_type
+        config = Rails.configuration.generators
+        config.options[config.orm][:primary_key_type]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: agreements
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yaroslav Shmarov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  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'
+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.
+email:
+- yashm@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- SECURITY.md
+- app/models/agreements/acceptance.rb
+- app/models/agreements/application_record.rb
+- app/models/agreements/version.rb
+- lib/agreements.rb
+- lib/agreements/enforcement.rb
+- lib/agreements/engine.rb
+- lib/agreements/errors.rb
+- lib/agreements/identity.rb
+- lib/agreements/recorder.rb
+- lib/agreements/version.rb
+- lib/generators/agreements/install/install_generator.rb
+- lib/generators/agreements/install/templates/create_agreements_tables.rb.tt
+- lib/generators/agreements/migration_helpers.rb
+homepage: https://github.com/yshmarov/agreements
+licenses:
+- MIT
+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
+  bug_tracker_uri: https://github.com/yshmarov/agreements/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Auditable acceptance of externally hosted legal agreements for Rails.
+test_files: []