agreement_engine 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/ci.yml +17 -0
- data/.ruby-version +1 -1
- data/CHANGELOG.md +36 -0
- data/README.md +278 -17
- data/app/controllers/agreement_engine/admin/documents_controller.rb +6 -32
- data/app/controllers/agreement_engine/admin/issues_controller.rb +50 -0
- data/app/controllers/agreement_engine/agreements_controller.rb +5 -5
- data/app/controllers/agreement_engine/consents_controller.rb +47 -0
- data/app/controllers/agreement_engine/documents_controller.rb +4 -7
- data/app/controllers/agreement_engine/receipts_controller.rb +31 -0
- data/app/controllers/agreement_engine/record_documents_controller.rb +47 -0
- data/app/controllers/agreement_engine/signatures_controller.rb +89 -0
- data/app/controllers/agreement_engine/verifications_controller.rb +18 -0
- data/app/mailers/agreement_engine/receipt_mailer.rb +18 -0
- data/app/models/agreement_engine/acceptance.rb +84 -0
- data/app/models/agreement_engine/consent_withdrawal.rb +13 -0
- data/app/models/agreement_engine/document.rb +81 -3
- data/app/views/agreement_engine/admin/documents/index.html.erb +1 -2
- data/app/views/agreement_engine/admin/documents/show.html.erb +52 -2
- data/app/views/agreement_engine/admin/issues/new.html.erb +51 -0
- data/app/views/agreement_engine/agreements/show.html.erb +4 -1
- data/app/views/agreement_engine/consents/show.html.erb +19 -0
- data/app/views/agreement_engine/documents/_issued_version.html.erb +5 -0
- data/app/views/agreement_engine/documents/{terms.html.erb → show.html.erb} +4 -4
- data/app/views/agreement_engine/receipt_mailer/copy.text.erb +5 -0
- data/app/views/agreement_engine/signatures/show.html.erb +37 -0
- data/app/views/agreement_engine/verifications/show.html.erb +22 -0
- data/config/locales/en.yml +44 -0
- data/config/routes.rb +12 -3
- data/db/migrate/20261120011146_add_issued_versions_to_agreement_engine_documents.rb +8 -0
- data/db/migrate/20261120022247_create_agreement_engine_acceptances.rb +22 -0
- data/db/migrate/20261120023407_create_agreement_engine_consent_withdrawals.rb +12 -0
- data/db/migrate/20261120024007_add_signature_fields_to_agreement_engine_acceptances.rb +7 -0
- data/db/migrate/20261120030101_add_subject_to_agreement_engine_documents.rb +9 -0
- data/db/migrate/20261120041730_add_carry_over_to_agreement_engine_acceptances.rb +8 -0
- data/db/migrate/20261120141925_add_period_to_agreement_engine_acceptances.rb +6 -0
- data/db/migrate/20261120143946_add_database_guards_to_agreement_engine.rb +9 -0
- data/db/migrate/20261120145611_add_one_signature_index_to_agreement_engine_acceptances.rb +5 -0
- data/docs/byte-form/examples/blank-standing/bytes.json +1 -0
- data/docs/byte-form/examples/blank-standing/input.json +15 -0
- data/docs/byte-form/examples/blank-standing/sha256 +1 -0
- data/docs/byte-form/examples/with-values/bytes.json +1 -0
- data/docs/byte-form/examples/with-values/input.json +15 -0
- data/docs/byte-form/examples/with-values/sha256 +1 -0
- data/docs/byte-form.md +44 -0
- data/exe/agreement_engine-verify +14 -0
- data/lib/agreement_engine/acceptance_event.rb +22 -0
- data/lib/agreement_engine/byte_form.rb +28 -0
- data/lib/agreement_engine/configuration.rb +35 -2
- data/lib/agreement_engine/consent.rb +26 -0
- data/lib/agreement_engine/database_guards.rb +46 -0
- data/lib/agreement_engine/document_type.rb +23 -0
- data/lib/agreement_engine/enforceable.rb +6 -7
- data/lib/agreement_engine/engine.rb +7 -0
- data/lib/agreement_engine/html_to_page.rb +63 -0
- data/lib/agreement_engine/integrity.rb +23 -0
- data/lib/agreement_engine/pages_elements.rb +29 -0
- data/lib/agreement_engine/period.rb +23 -0
- data/lib/agreement_engine/receipt.rb +43 -0
- data/lib/agreement_engine/seed.rb +37 -0
- data/lib/agreement_engine/signable.rb +25 -9
- data/lib/agreement_engine/upgrade.rb +75 -0
- data/lib/agreement_engine/verification.rb +13 -0
- data/lib/agreement_engine/version.rb +1 -1
- data/lib/agreement_engine.rb +43 -1
- data/lib/generators/agreement_engine/templates/initializer.rb +5 -4
- data/lib/tasks/agreement_engine.rake +18 -15
- metadata +64 -9
- data/app/views/agreement_engine/admin/documents/_form.html.erb +0 -44
- data/app/views/agreement_engine/admin/documents/edit.html.erb +0 -5
- data/app/views/agreement_engine/admin/documents/new.html.erb +0 -5
- data/app/views/agreement_engine/documents/privacy.html.erb +0 -16
- data/lib/agreement_engine/agreement.rb +0 -23
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 649f3e907422eb8da582df0baf7ec28f798d13687617621663cad2d40ec69897
|
|
4
|
+
data.tar.gz: 5f48e46767d04c2c4b2a6151917d39d5c38ddc0b11025b7735dde3c9f5ca0d50
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 53d4986715374f842a974bd9aaea335e5bc3b859201d57a543d4dc6cafaaf7b6476b9286999241f574081b0d2e1cc0d21b77e9b74a2507515a180f38faa9f74e
|
|
7
|
+
data.tar.gz: 82d7d17557575612209e8e5dbae6bde1b1254f363b97a899eee4398ab00ff2d73097319ecd19e555d27c7395696755754a7a7b43c1858418ae5baba7e35be1aa
|
data/.github/workflows/ci.yml
CHANGED
|
@@ -9,6 +9,23 @@ jobs:
|
|
|
9
9
|
test:
|
|
10
10
|
runs-on: ubuntu-latest
|
|
11
11
|
|
|
12
|
+
services:
|
|
13
|
+
postgres:
|
|
14
|
+
image: postgres:17
|
|
15
|
+
env:
|
|
16
|
+
POSTGRES_PASSWORD: postgres
|
|
17
|
+
POSTGRES_DB: agreement_engine_guards_test
|
|
18
|
+
ports:
|
|
19
|
+
- 5432:5432
|
|
20
|
+
options: >-
|
|
21
|
+
--health-cmd pg_isready
|
|
22
|
+
--health-interval 10s
|
|
23
|
+
--health-timeout 5s
|
|
24
|
+
--health-retries 5
|
|
25
|
+
|
|
26
|
+
env:
|
|
27
|
+
AGREEMENT_ENGINE_POSTGRES_URL: postgres://postgres:postgres@localhost:5432/agreement_engine_guards_test
|
|
28
|
+
|
|
12
29
|
steps:
|
|
13
30
|
- name: Checkout code
|
|
14
31
|
uses: actions/checkout@v6
|
data/.ruby-version
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
3.4.
|
|
1
|
+
3.4.13
|
data/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,42 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [0.2.0] - 2026-11-20
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- Registered document types with a key, title, kind and strength, read alongside the listed agreements
|
|
10
|
+
- Issuing a published keystone_ui-pages page version as a document version, with a frozen copy and a SHA-256 hash of its byte form
|
|
11
|
+
- Issued versions refuse edits and deletion
|
|
12
|
+
- A List element, bulleted or numbered, in the keystone_ui-pages builder
|
|
13
|
+
- A runtime dependency on keystone_ui-pages
|
|
14
|
+
- Acceptance records that keep the evidence of each acceptance and cannot be changed or deleted
|
|
15
|
+
- An evidence hook through which a host supplies the account, further person details and how the session signed in
|
|
16
|
+
- `accepted_current?` and `accepted_versions` on the signer
|
|
17
|
+
- Signing refuses a version that is no longer current, records one signature per person per version, and keeps the signature when its copy cannot be drawn or emailed
|
|
18
|
+
- Issuing refuses a page holding an element with no PDF drawing
|
|
19
|
+
- PostgreSQL triggers that reject changes to acceptances and issued versions, admin marks for broken or moved versions, and `agreement_engine:check_hashes`
|
|
20
|
+
- Periods on documents, recorded on each acceptance, with `AgreementEngine.in_force`
|
|
21
|
+
- A verify page and an `agreement_engine-verify` command, and the published byte-form rule with worked examples
|
|
22
|
+
- An upgrade task that moves Action Text documents into page versions and carries over each user's stored acceptance
|
|
23
|
+
- The signer's copy: a PDF with an evidence summary, the byte-form file, and an email for chosen types
|
|
24
|
+
- A PDF drawing for the List element
|
|
25
|
+
- A host handler told about each acceptance and signature once committed, including the first signature on a record's document
|
|
26
|
+
- Per-record documents filled from a template page with one host record's values, with a may-sign check, a return address and `issue_for!`, `current_for` and `signers_for`
|
|
27
|
+
- Documents are addressed by a random code in place of their database id
|
|
28
|
+
- Signature-strength document types with a signing page, a typed name, and consent required first
|
|
29
|
+
- A consent to electronic records type a host can enable, with a starting page, a consent page, withdrawal records and `holds_consent?`
|
|
30
|
+
|
|
31
|
+
### Changed
|
|
32
|
+
|
|
33
|
+
- Every page draws an issued version from its frozen copy through one partial, which fixes the accept page showing the old rich text
|
|
34
|
+
|
|
35
|
+
- `config.document_types` is the one place documents are declared, and setting `config.agreements` now fails at boot
|
|
36
|
+
- Every registered standing type has a public page, and the seed task issues a starting version for each
|
|
37
|
+
- The admin pages no longer offer the rich-text editor; versions are issued from published pages
|
|
38
|
+
|
|
39
|
+
- Whether a person has accepted is read from acceptance records, and accepting no longer writes the user's version columns
|
|
40
|
+
|
|
5
41
|
## [0.1.0] - 2026-02-12
|
|
6
42
|
|
|
7
43
|
### Added
|
data/README.md
CHANGED
|
@@ -20,31 +20,37 @@ rails db:migrate
|
|
|
20
20
|
|
|
21
21
|
## Setup
|
|
22
22
|
|
|
23
|
-
### 1.
|
|
23
|
+
### 1. Register document types
|
|
24
24
|
|
|
25
25
|
Create `config/initializers/agreement_engine.rb`:
|
|
26
26
|
|
|
27
27
|
```ruby
|
|
28
28
|
AgreementEngine.configure do |config|
|
|
29
|
-
config.
|
|
30
|
-
AgreementEngine::
|
|
31
|
-
|
|
32
|
-
title: "Terms Of Service",
|
|
33
|
-
version_column: :accepted_terms_of_service_version_id,
|
|
34
|
-
document_type: :terms_of_service,
|
|
35
|
-
prompt_when_updated: true
|
|
36
|
-
),
|
|
37
|
-
AgreementEngine::Agreement.new(
|
|
38
|
-
id: :privacy_policy,
|
|
39
|
-
title: "Privacy Policy",
|
|
40
|
-
version_column: :accepted_privacy_policy_version_id,
|
|
41
|
-
document_type: :privacy_policy,
|
|
42
|
-
prompt_when_updated: true
|
|
43
|
-
)
|
|
29
|
+
config.document_types = [
|
|
30
|
+
AgreementEngine::DocumentType.new(key: :terms_of_service, title: "Terms of Service", kind: :standing, strength: :click_accept, prompts: true),
|
|
31
|
+
AgreementEngine::DocumentType.new(key: :privacy_policy, title: "Privacy Policy", kind: :standing, strength: :click_accept, prompts: true)
|
|
44
32
|
]
|
|
45
33
|
end
|
|
46
34
|
```
|
|
47
35
|
|
|
36
|
+
This list is the one place documents are declared. The sign-in redirect, the
|
|
37
|
+
public pages, the admin pages and the seed task all read it. A standing type
|
|
38
|
+
that prompts sends signed-in people to accept its current version. Every
|
|
39
|
+
standing type has a public page at `/documents/<key>`, and `/terms` and
|
|
40
|
+
`/privacy` still serve the terms of service and privacy policy.
|
|
41
|
+
|
|
42
|
+
### Write and issue documents with keystone_ui-pages
|
|
43
|
+
|
|
44
|
+
Document content is written in the keystone_ui-pages builder, so the host
|
|
45
|
+
installs keystone_ui-pages and runs its migrations before this gem's. The
|
|
46
|
+
builder offers a List element, bulleted or numbered, for legal text.
|
|
47
|
+
|
|
48
|
+
An admin issues a published page version from **Issue a version** on the
|
|
49
|
+
documents list, with a version label and an effective date. Issuing keeps a
|
|
50
|
+
frozen copy of the page version and records the SHA-256 of its byte form, so
|
|
51
|
+
the issued version keeps its text after the page is edited, republished or
|
|
52
|
+
deleted. An issued version cannot be edited or deleted.
|
|
53
|
+
|
|
48
54
|
### 2. Include concerns
|
|
49
55
|
|
|
50
56
|
```ruby
|
|
@@ -72,6 +78,249 @@ mount AgreementEngine::Engine, at: "/"
|
|
|
72
78
|
rails agreement_engine:seed
|
|
73
79
|
```
|
|
74
80
|
|
|
81
|
+
The seed task issues a starting version for every registered standing type
|
|
82
|
+
that has none, from a page you then edit in the builder.
|
|
83
|
+
|
|
84
|
+
## Acceptance evidence
|
|
85
|
+
|
|
86
|
+
Every acceptance is kept as its own record, and a record cannot be changed or
|
|
87
|
+
deleted. Each one holds the time, the version accepted and its hash, the IP
|
|
88
|
+
address, the browser, the statement and button text shown, the
|
|
89
|
+
agreement_engine and keystone_ui-pages versions, and a snapshot of the
|
|
90
|
+
person's id, name and email as they were at that moment.
|
|
91
|
+
|
|
92
|
+
A host adds the account, further person details and how the session signed in
|
|
93
|
+
through one hook:
|
|
94
|
+
|
|
95
|
+
```ruby
|
|
96
|
+
AgreementEngine.configure do |config|
|
|
97
|
+
config.evidence_method = ->(controller, user) {
|
|
98
|
+
{
|
|
99
|
+
account: {id: controller.current_account.id, name: controller.current_account.name},
|
|
100
|
+
person: {phone: user.phone},
|
|
101
|
+
sign_in: {methods: controller.session_sign_in_methods}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
end
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Host code can ask `user.accepted_current?(:terms_of_service)` and list
|
|
108
|
+
`user.accepted_versions(:terms_of_service)`.
|
|
109
|
+
|
|
110
|
+
Whether a person has accepted is now read from these records, not from the
|
|
111
|
+
version columns on the user table, and accepting writes no column. Existing
|
|
112
|
+
acceptances in those columns are carried over by the upgrade task, which comes
|
|
113
|
+
in a later release.
|
|
114
|
+
|
|
115
|
+
## Consent to electronic records
|
|
116
|
+
|
|
117
|
+
A host that asks people to sign turns on the consent type the gem provides:
|
|
118
|
+
|
|
119
|
+
```ruby
|
|
120
|
+
AgreementEngine.configure do |config|
|
|
121
|
+
config.electronic_consent = true
|
|
122
|
+
end
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`rails agreement_engine:seed` then issues version 1.0 from a starting page
|
|
126
|
+
covering paper copies, withdrawing consent and what a person needs to open and
|
|
127
|
+
keep records. Review that text with your lawyer, edit the page in the builder,
|
|
128
|
+
and issue your own versions like any standing document.
|
|
129
|
+
|
|
130
|
+
A person gives or withdraws consent at `/consent`. A withdrawal is kept beside
|
|
131
|
+
the consent it ends, and host code asks `user.holds_consent?`.
|
|
132
|
+
|
|
133
|
+
## Signatures
|
|
134
|
+
|
|
135
|
+
A document type whose strength is `:signature` is signed rather than clicked:
|
|
136
|
+
|
|
137
|
+
```ruby
|
|
138
|
+
AgreementEngine::DocumentType.new(key: :statement_of_work, title: "Statement of Work", kind: :standing, strength: :signature)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Its signing page is at `/signatures/statement_of_work`. A person without
|
|
142
|
+
current consent to electronic records is sent to `/consent` first and brought
|
|
143
|
+
back afterwards. The page shows signing wording and asks for the person's typed
|
|
144
|
+
full name, and a submission without one is refused. The signature is kept as an
|
|
145
|
+
acceptance that also holds the typed name and the consent it relied on.
|
|
146
|
+
|
|
147
|
+
The signing form carries the hash of the version shown. A submission for a
|
|
148
|
+
version that is no longer current is refused and the current version is shown.
|
|
149
|
+
A person who withdrew consent is sent back to `/consent`. Submitting the same
|
|
150
|
+
form twice records one signature. A page holding an element with no PDF drawing
|
|
151
|
+
cannot be issued, and the refusal names the element.
|
|
152
|
+
|
|
153
|
+
## Documents for one record
|
|
154
|
+
|
|
155
|
+
A per-record type is filled from a template page with one of the host's
|
|
156
|
+
records, such as a quote, a contract or a plan, and accepted or signed in that
|
|
157
|
+
exact form.
|
|
158
|
+
|
|
159
|
+
```ruby
|
|
160
|
+
AgreementEngine.configure do |config|
|
|
161
|
+
config.document_types = [
|
|
162
|
+
AgreementEngine::DocumentType.new(key: :plan_sign_off, title: "Plan sign-off", kind: :per_record, strength: :signature, template: "plan-sign-off")
|
|
163
|
+
]
|
|
164
|
+
config.values_method = ->(record, type) { {client_name: record.client.name} }
|
|
165
|
+
config.may_sign_method = ->(controller, person, document) { document.subject.client.members.include?(person) }
|
|
166
|
+
config.return_check_method = ->(path) { path.start_with?("/plans/") }
|
|
167
|
+
end
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
The template is a keystone_ui-pages page whose text is bound to the named
|
|
171
|
+
values, and parts of it can be shown or hidden by a value.
|
|
172
|
+
|
|
173
|
+
```ruby
|
|
174
|
+
document = AgreementEngine.issue_for!(:plan_sign_off, plan)
|
|
175
|
+
agreement_engine.record_document_path(document, return_to: plan_path(plan))
|
|
176
|
+
AgreementEngine.current_for(:plan_sign_off, plan)
|
|
177
|
+
AgreementEngine.signers_for(:plan_sign_off, plan)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Issuing copies the template's live version and the record's values at that
|
|
181
|
+
moment, so a later change to the record changes neither the document nor its
|
|
182
|
+
hash. Issuing again for the same record keeps the earlier document and its
|
|
183
|
+
acceptances. A person the may-sign check refuses gets a not-found page. The
|
|
184
|
+
return address is followed only when it is a path on the host's own site that
|
|
185
|
+
the return check allows. Record documents never trigger the accept redirect and
|
|
186
|
+
never appear on the public pages.
|
|
187
|
+
|
|
188
|
+
## Documents that cover a period
|
|
189
|
+
|
|
190
|
+
A version can cover a period, given when it is issued as a start and end date
|
|
191
|
+
or as an ISO 8601 duration counted from acceptance. An admin sets it on the
|
|
192
|
+
issue form, and host code passes it to `issue_for!`:
|
|
193
|
+
|
|
194
|
+
```ruby
|
|
195
|
+
AgreementEngine.issue_for!(:service_agreement, contract, period: {"duration" => "P1Y"})
|
|
196
|
+
AgreementEngine.in_force(person: user, on: Date.current)
|
|
197
|
+
AgreementEngine.in_force(account_id: account.id, on: Date.current)
|
|
198
|
+
AgreementEngine.in_force(record: contract, on: Date.current)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
The period is part of the hash. The accept page, the signing page and the
|
|
202
|
+
signer's copy show it. Each acceptance records the dates that apply to it, and
|
|
203
|
+
an agreement with no period is in force from its acceptance onward.
|
|
204
|
+
|
|
205
|
+
## The signer's copy
|
|
206
|
+
|
|
207
|
+
A person can download a copy of any of their own acceptances:
|
|
208
|
+
|
|
209
|
+
- `agreement_engine.receipt_path(acceptance, format: :pdf)` is the issued version
|
|
210
|
+
drawn with the values it was issued with, followed by the hash, the time, the
|
|
211
|
+
typed name and the gem versions.
|
|
212
|
+
- `agreement_engine.byte_form_receipt_path(acceptance)` is the byte-form file the
|
|
213
|
+
hash was taken from, so `shasum -a 256` on it prints the recorded hash.
|
|
214
|
+
|
|
215
|
+
A host emails the copy for chosen types:
|
|
216
|
+
|
|
217
|
+
```ruby
|
|
218
|
+
AgreementEngine.configure do |config|
|
|
219
|
+
config.copy_email_types = [:plan_sign_off]
|
|
220
|
+
config.mailer_from = "agreements@example.com"
|
|
221
|
+
end
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
The PDF is drawn by keystone_ui-pages, so the host needs Propshaft and a
|
|
225
|
+
compiled stylesheet holding the keystone_ui tokens.
|
|
226
|
+
|
|
227
|
+
## Checking a copy
|
|
228
|
+
|
|
229
|
+
The rule that turns an issued version into the bytes it is hashed from is
|
|
230
|
+
published in `docs/byte-form.md`, with worked examples. Anyone can check a
|
|
231
|
+
byte-form file against a hash at `/verify`, which names no signer, or with the
|
|
232
|
+
command installed with the gem:
|
|
233
|
+
|
|
234
|
+
```
|
|
235
|
+
agreement_engine-verify copy.json <hash>
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Integrity
|
|
239
|
+
|
|
240
|
+
On PostgreSQL, the gem's migration adds triggers that reject any update or
|
|
241
|
+
delete of an acceptance, and of an issued version's frozen copy, hash or
|
|
242
|
+
effective date, even when run directly in SQL. Other databases keep the
|
|
243
|
+
refusal in the app only.
|
|
244
|
+
|
|
245
|
+
The admin page marks an issued version whose frozen copy no longer produces its
|
|
246
|
+
hash, and one whose page version has since changed or been deleted. Run
|
|
247
|
+
`rails agreement_engine:check_hashes` to list every issued version and
|
|
248
|
+
acceptance whose hashes disagree. It exits with a failure when it finds one, so
|
|
249
|
+
it can run on a schedule.
|
|
250
|
+
|
|
251
|
+
## Being told about acceptances
|
|
252
|
+
|
|
253
|
+
A host sets one handler, which is called once each acceptance or signature is
|
|
254
|
+
committed:
|
|
255
|
+
|
|
256
|
+
```ruby
|
|
257
|
+
AgreementEngine.configure do |config|
|
|
258
|
+
config.acceptance_handler = ->(event) {
|
|
259
|
+
StartPlanWork.call(event.subject) if event.document_type == :plan_sign_off && event.first_signature?
|
|
260
|
+
}
|
|
261
|
+
end
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
The event gives `document_type`, `document`, `person`, `account`, `strength`,
|
|
265
|
+
`subject` (the host record of a per-record document) and `first_signature?`.
|
|
266
|
+
An error the handler raises is reported through `Rails.error` and never reaches
|
|
267
|
+
the person, whose acceptance stays saved. A slow handler slows the accept and
|
|
268
|
+
signing pages, so queue long work from inside it.
|
|
269
|
+
|
|
270
|
+
## Upgrading an app that already uses agreement_engine
|
|
271
|
+
|
|
272
|
+
An app on 0.1 keeps its documents as Action Text and each user's accepted
|
|
273
|
+
version in columns on the user table. The upgrade keeps both and moves them
|
|
274
|
+
into the new records.
|
|
275
|
+
|
|
276
|
+
1. Move to `keystone_ui` 0.49 or later and install `keystone_ui-pages`, with its
|
|
277
|
+
migrations, Active Storage and a Propshaft stylesheet built with the
|
|
278
|
+
keystone_ui tokens.
|
|
279
|
+
2. Install this gem's migrations with
|
|
280
|
+
`rails agreement_engine:install:migrations` and run them. They add tables and
|
|
281
|
+
fields and change no existing document, Action Text or user rows.
|
|
282
|
+
3. Run `rails "agreement_engine:upgrade[User,terms_accepted_at]"`. The first
|
|
283
|
+
argument is the model that includes `AgreementEngine::Signable`. The second,
|
|
284
|
+
optional, names a column holding when each user accepted. Without it, the
|
|
285
|
+
carried-over acceptances record no time.
|
|
286
|
+
4. Read the task's output. It names each version holding content it could not
|
|
287
|
+
carry over, such as tables or images, so those pages can be fixed in the
|
|
288
|
+
builder.
|
|
289
|
+
|
|
290
|
+
The task makes one page per document type and one published page version per
|
|
291
|
+
dated version, holding its headings, paragraphs with links, bold and italic
|
|
292
|
+
text, and lists. Each version is then issued in place with its original label
|
|
293
|
+
and effective date, frozen and hashed. Each user's stored version becomes one
|
|
294
|
+
acceptance marked as carried over, with the person and account as they are at
|
|
295
|
+
upgrade time, so nobody is asked to accept again. Running it twice creates
|
|
296
|
+
nothing new.
|
|
297
|
+
|
|
298
|
+
5. Replace `config.agreements` with `config.document_types`, as in Setup
|
|
299
|
+
above. From 0.2 an app that still sets `config.agreements` fails at boot
|
|
300
|
+
with a message naming the replacement. The upgrade task finds each user's
|
|
301
|
+
stored version by the column the 0.1 install created for each type,
|
|
302
|
+
`accepted_<key>_version_id`.
|
|
303
|
+
6. Once the task has run and you have checked its result, remove the old
|
|
304
|
+
columns with a migration of your own:
|
|
305
|
+
|
|
306
|
+
```ruby
|
|
307
|
+
class RemoveAgreementEngineVersionColumnsFromUsers < ActiveRecord::Migration[8.0]
|
|
308
|
+
def change
|
|
309
|
+
remove_foreign_key :users, :agreement_engine_documents, column: :accepted_terms_of_service_version_id
|
|
310
|
+
remove_foreign_key :users, :agreement_engine_documents, column: :accepted_privacy_policy_version_id
|
|
311
|
+
remove_column :users, :accepted_terms_of_service_version_id, :bigint
|
|
312
|
+
remove_column :users, :accepted_privacy_policy_version_id, :bigint
|
|
313
|
+
end
|
|
314
|
+
end
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
Generate it with `bin/rails generate migration RemoveAgreementEngineVersionColumnsFromUsers`
|
|
318
|
+
and fill in its body.
|
|
319
|
+
|
|
320
|
+
What the app gains: editing documents in the page builder, a hash on every
|
|
321
|
+
issued version, a kept record of every acceptance with its evidence, consent to
|
|
322
|
+
electronic records, signatures, documents for one record and the signer's copy.
|
|
323
|
+
|
|
75
324
|
## Auth Configuration
|
|
76
325
|
|
|
77
326
|
AgreementEngine defaults to Devise conventions. Override for other auth systems:
|
|
@@ -94,7 +343,19 @@ The engine provides:
|
|
|
94
343
|
- `DELETE /agreements/:id` - Decline agreement (signs user out)
|
|
95
344
|
- `GET /terms` - Public terms of service page
|
|
96
345
|
- `GET /privacy` - Public privacy policy page
|
|
97
|
-
- `GET /
|
|
346
|
+
- `GET /documents/:document_type` - Public page for any registered standing type
|
|
347
|
+
- `GET /admin/documents` - List, view and delete document versions
|
|
348
|
+
- `GET /admin/issues/new` - Issue a published page version as a document version
|
|
349
|
+
- `GET /consent` - Read the consent to electronic records
|
|
350
|
+
- `POST /consent` - Give consent
|
|
351
|
+
- `DELETE /consent` - Withdraw consent
|
|
352
|
+
- `GET /signatures/:document_type` - Signing page for a signature-strength type
|
|
353
|
+
- `PATCH /signatures/:document_type` - Sign it
|
|
354
|
+
- `GET /verify` - Check a byte-form file against a hash
|
|
355
|
+
- `GET /receipts/:id.pdf` - A person's PDF copy of their acceptance
|
|
356
|
+
- `GET /receipts/:id/byte_form` - The byte-form file its hash was taken from
|
|
357
|
+
- `GET /records/:code` - Accept or sign one record's document
|
|
358
|
+
- `PATCH /records/:code` - Accept or sign it
|
|
98
359
|
|
|
99
360
|
## Development
|
|
100
361
|
|
|
@@ -5,7 +5,7 @@ module AgreementEngine
|
|
|
5
5
|
class DocumentsController < ::ApplicationController
|
|
6
6
|
skip_before_action :require_accepted_agreements!, raise: false
|
|
7
7
|
before_action :authenticate_admin!
|
|
8
|
-
before_action :set_document, only: [:show, :
|
|
8
|
+
before_action :set_document, only: [:show, :destroy]
|
|
9
9
|
|
|
10
10
|
def index
|
|
11
11
|
@documents = AgreementEngine::Document.order(created_at: :desc)
|
|
@@ -15,36 +15,14 @@ module AgreementEngine
|
|
|
15
15
|
def show
|
|
16
16
|
end
|
|
17
17
|
|
|
18
|
-
def
|
|
19
|
-
@document
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
def create
|
|
23
|
-
@document = AgreementEngine::Document.new(document_params)
|
|
24
|
-
|
|
25
|
-
if @document.save
|
|
26
|
-
redirect_to agreement_engine.admin_document_path(@document), notice: "Document was successfully created."
|
|
27
|
-
else
|
|
28
|
-
render :new, status: :unprocessable_entity
|
|
29
|
-
end
|
|
30
|
-
end
|
|
31
|
-
|
|
32
|
-
def edit
|
|
33
|
-
end
|
|
34
|
-
|
|
35
|
-
def update
|
|
36
|
-
if @document.update(document_params)
|
|
37
|
-
redirect_to agreement_engine.admin_document_path(@document), notice: "Document was successfully updated."
|
|
18
|
+
def destroy
|
|
19
|
+
if @document.destroy
|
|
20
|
+
redirect_to agreement_engine.admin_documents_path, notice: "Document was successfully deleted.", status: :see_other
|
|
38
21
|
else
|
|
39
|
-
|
|
22
|
+
redirect_to agreement_engine.admin_document_path(@document), alert: @document.errors.full_messages.to_sentence, status: :see_other
|
|
40
23
|
end
|
|
41
24
|
end
|
|
42
25
|
|
|
43
|
-
def destroy
|
|
44
|
-
@document.destroy
|
|
45
|
-
redirect_to agreement_engine.admin_documents_path, notice: "Document was successfully deleted.", status: :see_other
|
|
46
|
-
end
|
|
47
|
-
|
|
48
26
|
private
|
|
49
27
|
|
|
50
28
|
def authenticate_admin!
|
|
@@ -52,11 +30,7 @@ module AgreementEngine
|
|
|
52
30
|
end
|
|
53
31
|
|
|
54
32
|
def set_document
|
|
55
|
-
@document = AgreementEngine::Document.
|
|
56
|
-
end
|
|
57
|
-
|
|
58
|
-
def document_params
|
|
59
|
-
params.require(:document).permit(:document_type, :version, :summary, :effective_at, :content)
|
|
33
|
+
@document = AgreementEngine::Document.find_by!(code: params[:id])
|
|
60
34
|
end
|
|
61
35
|
|
|
62
36
|
def apply_scope(documents)
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module AgreementEngine
|
|
4
|
+
module Admin
|
|
5
|
+
class IssuesController < ::ApplicationController
|
|
6
|
+
skip_before_action :require_accepted_agreements!, raise: false
|
|
7
|
+
before_action :authenticate_admin!
|
|
8
|
+
|
|
9
|
+
def new
|
|
10
|
+
@page_versions = published_page_versions
|
|
11
|
+
end
|
|
12
|
+
|
|
13
|
+
def create
|
|
14
|
+
document = AgreementEngine::Document.issue!(
|
|
15
|
+
type: issue_params[:document_type],
|
|
16
|
+
page_version: KeystoneUi::Pages::Version.find(issue_params[:page_version_id]),
|
|
17
|
+
version: issue_params[:version],
|
|
18
|
+
effective_at: issue_params[:effective_at],
|
|
19
|
+
period: period
|
|
20
|
+
)
|
|
21
|
+
redirect_to agreement_engine.admin_document_path(document), notice: "Version #{document.version} was issued."
|
|
22
|
+
rescue ActiveRecord::RecordInvalid => invalid
|
|
23
|
+
@error = invalid.record.errors.full_messages.to_sentence
|
|
24
|
+
@page_versions = published_page_versions
|
|
25
|
+
render :new, status: :unprocessable_entity
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
private
|
|
29
|
+
|
|
30
|
+
def published_page_versions
|
|
31
|
+
KeystoneUi::Pages::Version.live.includes(:page).order(:page_id)
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
def authenticate_admin!
|
|
35
|
+
AgreementEngine.config.authenticate_admin!(self)
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
def issue_params
|
|
39
|
+
params.require(:issue).permit(:document_type, :page_version_id, :version, :effective_at, :period_starts_on, :period_ends_on, :period_duration)
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
def period
|
|
43
|
+
return {"duration" => issue_params[:period_duration]} if issue_params[:period_duration].present?
|
|
44
|
+
return if issue_params[:period_starts_on].blank? && issue_params[:period_ends_on].blank?
|
|
45
|
+
|
|
46
|
+
{"starts_on" => issue_params[:period_starts_on].presence, "ends_on" => issue_params[:period_ends_on].presence}.compact
|
|
47
|
+
end
|
|
48
|
+
end
|
|
49
|
+
end
|
|
50
|
+
end
|
|
@@ -14,7 +14,7 @@ module AgreementEngine
|
|
|
14
14
|
|
|
15
15
|
def update
|
|
16
16
|
if @version
|
|
17
|
-
|
|
17
|
+
AgreementEngine::Acceptance.record!(signer: agreement_engine_current_user, document: @version, request: request, statement: t("agreement_engine.agreements.show.description", agreement: @agreement.title), button_text: t("agreement_engine.agreements.show.accept"), evidence: AgreementEngine.config.evidence(self, agreement_engine_current_user))
|
|
18
18
|
end
|
|
19
19
|
redirect_to after_accepted_path, status: :see_other
|
|
20
20
|
end
|
|
@@ -37,17 +37,17 @@ module AgreementEngine
|
|
|
37
37
|
end
|
|
38
38
|
|
|
39
39
|
def set_agreement
|
|
40
|
-
@agreement = AgreementEngine.
|
|
40
|
+
@agreement = AgreementEngine.document_type(params[:id])
|
|
41
41
|
|
|
42
|
-
if @agreement.nil?
|
|
42
|
+
if @agreement.nil? || @agreement.per_record?
|
|
43
43
|
redirect_to main_app.root_path
|
|
44
|
-
elsif @agreement.
|
|
44
|
+
elsif agreement_engine_current_user.accepted_current?(@agreement.key)
|
|
45
45
|
redirect_to after_accepted_path
|
|
46
46
|
end
|
|
47
47
|
end
|
|
48
48
|
|
|
49
49
|
def set_version
|
|
50
|
-
@version = @agreement
|
|
50
|
+
@version = @agreement && AgreementEngine::Document.current(@agreement.key)
|
|
51
51
|
end
|
|
52
52
|
|
|
53
53
|
def after_accepted_path
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module AgreementEngine
|
|
4
|
+
class ConsentsController < ::ApplicationController
|
|
5
|
+
skip_before_action :require_accepted_agreements!, raise: false
|
|
6
|
+
before_action :require_signed_in
|
|
7
|
+
before_action :set_version
|
|
8
|
+
|
|
9
|
+
layout "agreement_engine/minimal"
|
|
10
|
+
|
|
11
|
+
def show
|
|
12
|
+
end
|
|
13
|
+
|
|
14
|
+
def create
|
|
15
|
+
AgreementEngine::Acceptance.record!(
|
|
16
|
+
signer: signer,
|
|
17
|
+
document: @version,
|
|
18
|
+
request: request,
|
|
19
|
+
statement: t("agreement_engine.consents.show.statement"),
|
|
20
|
+
button_text: t("agreement_engine.consents.show.consent"),
|
|
21
|
+
evidence: AgreementEngine.config.evidence(self, signer)
|
|
22
|
+
)
|
|
23
|
+
redirect_to session.delete(:agreement_engine_after_consent) || agreement_engine.consent_path, status: :see_other, notice: t(".given")
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
def destroy
|
|
27
|
+
consent = signer.held_consent
|
|
28
|
+
AgreementEngine::ConsentWithdrawal.create!(acceptance: consent, withdrawn_at: Time.current, ip_address: request.remote_ip, user_agent: request.user_agent) if consent
|
|
29
|
+
redirect_to agreement_engine.consent_path, status: :see_other, notice: t(".withdrawn")
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
private
|
|
33
|
+
|
|
34
|
+
def signer
|
|
35
|
+
AgreementEngine.config.current_user(self)
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
def require_signed_in
|
|
39
|
+
redirect_to main_app.root_path unless AgreementEngine.config.signed_in?(self)
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
def set_version
|
|
43
|
+
@version = AgreementEngine::Document.current(Consent::TYPE.key)
|
|
44
|
+
redirect_to main_app.root_path unless @version
|
|
45
|
+
end
|
|
46
|
+
end
|
|
47
|
+
end
|
|
@@ -2,14 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
module AgreementEngine
|
|
4
4
|
class DocumentsController < ::ApplicationController
|
|
5
|
-
def
|
|
6
|
-
@
|
|
7
|
-
|
|
8
|
-
end
|
|
5
|
+
def show
|
|
6
|
+
@type = AgreementEngine.document_type(params[:document_type])
|
|
7
|
+
return head(:not_found) unless @type&.standing?
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
@agreement = AgreementEngine.config.agreements.find { |a| a.id == :privacy_policy }
|
|
12
|
-
@version = AgreementEngine::Document.current(:privacy_policy)
|
|
9
|
+
@version = AgreementEngine::Document.current(@type.key)
|
|
13
10
|
end
|
|
14
11
|
end
|
|
15
12
|
end
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module AgreementEngine
|
|
4
|
+
class ReceiptsController < ::ApplicationController
|
|
5
|
+
skip_before_action :require_accepted_agreements!, raise: false
|
|
6
|
+
before_action :require_signed_in
|
|
7
|
+
before_action :set_acceptance
|
|
8
|
+
|
|
9
|
+
def show
|
|
10
|
+
send_data AgreementEngine::Receipt.pdf(@acceptance), filename: "#{file_name}.pdf", type: "application/pdf", disposition: "attachment"
|
|
11
|
+
end
|
|
12
|
+
|
|
13
|
+
def byte_form
|
|
14
|
+
send_data AgreementEngine::Receipt.byte_form(@acceptance), filename: "#{file_name}.json", type: "application/json"
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
private
|
|
18
|
+
|
|
19
|
+
def require_signed_in
|
|
20
|
+
redirect_to main_app.root_path unless AgreementEngine.config.signed_in?(self)
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
def set_acceptance
|
|
24
|
+
@acceptance = AgreementEngine.config.current_user(self).agreement_engine_acceptances.find(params[:id])
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
def file_name
|
|
28
|
+
"#{@acceptance.document.document_type}-#{@acceptance.document.version}"
|
|
29
|
+
end
|
|
30
|
+
end
|
|
31
|
+
end
|