From 76643de2e792d506b90b38605c1ebb672f427a0e Mon Sep 17 00:00:00 2001 From: Rick Barrette Date: Sat, 7 Nov 2026 15:35:19 -0500 Subject: [PATCH] Procedures: suggested text from the installation's settings; blanks block adoption - Insert suggested text for Hosting and network (HTTPS, sign-in mode, password/lockout rules, Docker) and Additional procedures (common Part 91 procedures; electronic-records date filled in), with [bracketed] blanks for what only the owner knows - A revision can't be adopted while a [blank] is left (Markdown links ok) - Generated sections state HTTPS and the sign-in mode from the config Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- .../admin/procedures_controller.rb | 3 + .../controllers/insert_text_controller.js | 17 +++++ app/models/recordkeeping_policy.rb | 11 ++- app/services/procedures_templates.rb | 69 +++++++++++++++++++ app/views/admin/procedures/_document.html.erb | 4 +- app/views/admin/procedures/show.html.erb | 18 +++-- docs/guide/administration.md | 1 + .../recordkeeping_procedures_test.rb | 29 ++++++++ 9 files changed, 145 insertions(+), 9 deletions(-) create mode 100644 app/javascript/controllers/insert_text_controller.js create mode 100644 app/services/procedures_templates.rb diff --git a/README.md b/README.md index 3b01c7e..4153556 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,7 @@ To back up or move a single aircraft with all its files, use **Access & Sharing | Electronic signatures | Logbook entries can be signed electronically along the lines of AC 120-78B chapter 2: the signer reviews the entry, picks their certificate, re-enters their password (or signs in again with SSO) and confirms a "Certified by" statement. The signature records who, which certificate, the statement, the time and a SHA-256 fingerprint of the entry, sealed by the server; the signer gets an email. Signed entries are locked: a correction is a new signed entry that supersedes the original. Owners can invite an outside mechanic to sign one entry with their own account. Disabled accounts can't sign; their past signatures stay. | | Records integrity | Every change to maintenance records is kept (who, when, field by field) in a hash chain per aircraft (Activity → Record history). Nightly: a verified SQLite backup in `storage/backups` (how many are kept: Admin → Settings), then a check of the history chains and every signature; admins are emailed on a problem (Admin → About). Software versions are recorded. A records package (Access & Sharing) bundles every entry as a PDF with signatures, a signature register, the history, the status report and the `.sam.zip` for the FAA or a buyer. Scans of paper logbooks can be marked as legacy records, with an "electronic records since" date per aircraft. | | Off-site backup | Nightly copy of the verified database snapshot (newest 30 kept) and every new uploaded file to Google Drive, using your own Google OAuth client and the `drive.file` scope (the app sees only its own files). Restore test from the admin page; failures emailed to admins; `bin/rails offsite:restore_files` brings files back after a restore. | -| Recordkeeping procedures and audits | Admin → Recordkeeping Procedures generates the procedures document AC 120-78B asks for (who is responsible, who may sign, signing, corrections, backups, access, audits, transfer, legacy records) from the system setup plus a few details you fill in; adopt it as numbered, unchangeable revisions, included in the records package. Admin → Records Audits is a periodic QC checklist (app checks plus a restore test, a sample of entries against source documents and a user review); admins get the due date in the weekly reminder. The users' instructions are the guide's [Electronic records and signing](docs/guide/records.md) page. | +| Recordkeeping procedures and audits | Admin → Recordkeeping Procedures generates the procedures document AC 120-78B asks for (who is responsible, who may sign, signing, corrections, backups, access, audits, transfer, legacy records) from the system setup plus a few details you fill in (with suggested text built from the installation's settings; a revision can't be adopted while a [bracketed] blank is left); adopt it as numbered, unchangeable revisions, included in the records package. Admin → Records Audits is a periodic QC checklist (app checks plus a restore test, a sample of entries against source documents and a user review); admins get the due date in the weekly reminder. The users' instructions are the guide's [Electronic records and signing](docs/guide/records.md) page. | | Major repairs and alterations | Form 337, STC, and ICA tracking; an STC's ICA can become a tracked recurring inspection. | | Weight & balance | History of empty weight and CG (linked to the alteration that changed them) and a loading calculator: takeoff and landing weight and CG against max gross and the CG envelope. The envelope can be entered as CG (inches) or as moment (lb-in/1000, as in POH moment charts and Garmin Pilot). | | Status report | A printable maintenance status (91.417(a)(2)): total times, life-limited parts, time since overhaul, inspections, ADs with method and revision, major alterations, open discrepancies. Also on maintenance share links. | diff --git a/app/controllers/admin/procedures_controller.rb b/app/controllers/admin/procedures_controller.rb index b23e09d..b5692ea 100644 --- a/app/controllers/admin/procedures_controller.rb +++ b/app/controllers/admin/procedures_controller.rb @@ -28,6 +28,9 @@ class Admin::ProceduresController < ApplicationController def adopt policy = RecordkeepingPolicy.current + if policy.unfilled_fields.any? + return redirect_to(admin_procedures_path, alert: "Fill in the [bracketed] blanks first: #{policy.unfilled_fields.to_sentence}.") + end return redirect_to(admin_procedures_path, alert: "Fill in the operator, responsible person, hosting and off-site backup (or connect Google Drive) first.") unless policy.complete? number = (ProceduresRevision.maximum(:number) || 0) + 1 revision = ProceduresRevision.create!(number: number, adopted_by: current_user, adopted_at: Time.current, diff --git a/app/javascript/controllers/insert_text_controller.js b/app/javascript/controllers/insert_text_controller.js new file mode 100644 index 0000000..fccd652 --- /dev/null +++ b/app/javascript/controllers/insert_text_controller.js @@ -0,0 +1,17 @@ +import { Controller } from "@hotwired/stimulus" + +// Fills a textarea with suggested text (asks before replacing what's there). +export default class extends Controller { + static targets = ["field"] + static values = { text: String } + + insert(event) { + event.preventDefault() + const field = this.fieldTarget + if (field.value.trim() && !confirm("Replace what's in the box with the suggested text?")) return + field.value = this.textValue + field.focus() + field.setSelectionRange(0, 0) + field.scrollTop = 0 + } +} diff --git a/app/models/recordkeeping_policy.rb b/app/models/recordkeeping_policy.rb index 89d3cce..a8ad4cb 100644 --- a/app/models/recordkeeping_policy.rb +++ b/app/models/recordkeeping_policy.rb @@ -7,7 +7,16 @@ class RecordkeepingPolicy < ApplicationRecord def self.current = first || create! - def complete? = [ operator_name, responsible_name, hosting_description ].all?(&:present?) && offsite_backup? + def complete? = [ operator_name, responsible_name, hosting_description ].all?(&:present?) && offsite_backup? && unfilled_fields.empty? + + FILLABLE = { hosting_description: "Hosting and network", offsite_backup_description: "Off-site backup", + additional_procedures: "Additional procedures", operator_name: "Owner / operator", + responsible_name: "Responsible person", responsible_title: "Their role" }.freeze + # A [bracketed] blank left from the suggested text (not a Markdown link). + BLANK = /\[[^\]\n]+\](?!\()/ + + # Labels of the fields that still have a blank to fill in. + def unfilled_fields = FILLABLE.select { |attr, _| self[attr].to_s.match?(BLANK) }.values # Off-site backup is described, or done by the app to Google Drive. def offsite_backup? = offsite_backup_description.present? || OffsiteConnection.connected? diff --git a/app/services/procedures_templates.rb b/app/services/procedures_templates.rb new file mode 100644 index 0000000..1f4af2d --- /dev/null +++ b/app/services/procedures_templates.rb @@ -0,0 +1,69 @@ +# Suggested text for the procedures fields the owner fills in: generated +# from the installation's configuration where the app knows the facts, with +# [bracketed] blanks for what only the owner knows. Inserted into the form +# for review; a revision can't be adopted while any blank is left. +module ProceduresTemplates + module_function + + def hosting + [ + "**Server.** The system runs #{docker? ? 'as a Docker container on a server' : 'on a server'} at [location, e.g. the owner's home or a hosting provider]. " \ + "Its data (the database, the uploaded files and the nightly verified database copies) is on that server's storage volume. " \ + "Only [the owner] has administrative access to the server.", + "**Network access.** [How the system is reached: e.g. directly from the internet at its own address, only on the home network, or over a VPN.] #{https_sentence}", + "**Sign-in.** #{sign_in_sentence} Password accounts require at least #{User::PASSWORD_MIN} characters, reject passwords found in known data breaches, " \ + "lock for #{User::LOCK_FOR.inspect} after #{User::LOCK_AFTER} failed attempts in a row, and can add an authenticator app. " \ + "Sessions end after #{Authentication::SESSION_IDLE_TIMEOUT.inspect} unused.", + "**Signing.** Signing an entry always requires the signer to re-enter their password (and authenticator code if enabled)#{' or to sign in again with single sign-on' if Sso.enabled?}.", + "**Updates.** Software updates are installed by [the owner] from [the project's published container images]. Each version is recorded by the system under Software versions.", + "**Secret key.** The application secret key (SECRET_KEY_BASE), needed to verify electronic signatures and to restore from backup, is kept by the owner off the server in [a password manager]." + ].join("\n\n") + end + + def additional + since = Aircraft.where.not(electronic_records_since: nil).minimum(:electronic_records_since) + [ + "**Who makes entries.** The owner enters maintenance records. A mechanic who performs work signs their own entry: through a signing invitation, with their own account in the system, " \ + "or by signing a printed entry in ink. The owner signs only preventive maintenance they performed under 14 CFR 43.3(g), with their pilot certificate.", + "**Outside signers.** Signing invitations are sent only to the mechanic's own email address, for the specific entry they performed. Each invitation can be used once and expires after 14 days. " \ + "If a mechanic forgets their password, the owner resets it or sends a new invitation; passwords are never shared or set on a mechanic's behalf. " \ + "Mechanics are encouraged to add an authenticator app. Accounts of mechanics no longer working on the aircraft are disabled at the next audit; their past signatures remain valid.", + "**Account problems.** If someone may have used another person's password, or an account is locked without explanation, the owner disables or unlocks it as appropriate, " \ + "has the user change their password, and reviews the record history for changes made by that account. " \ + "An authenticator app is reset only after confirming the person's identity by phone or in person.", + "**Share links.** Read-only share links are created only for a specific purpose (a mechanic, buyer, insurer or the FAA), with an expiry date where practical. " \ + "They are revoked when no longer needed and reviewed at each audit.", + "**Retention (14 CFR 91.417(b)).** Records of maintenance, preventive maintenance and alterations, and of 100-hour, annual and progressive inspections, are kept until the work is " \ + "repeated or superseded, or for one year after it was performed. Total time in service, current status of life-limited parts, time since last overhaul, current inspection status " \ + "and AD status are kept permanently and transferred with the aircraft. In practice nothing is deleted: signed entries cannot be deleted, and the record history and off-site copies are kept.", + "**Paper records.** The paper logbooks covering the period before #{since ? since.strftime('%B %-d, %Y') : '[the date electronic records began]'} are kept by the owner at [location] " \ + "and transferred with the aircraft. Their scans are marked as legacy records. Entries signed in ink after that date are scanned into Documents, and the paper is kept with the logbooks.", + "**Shop visits.** When a shop prefers paper, entries are printed from the system for signature and the signed copy is scanned in. " \ + "A shop or the FAA may be given a time-limited Maintenance Detail share link for read-only access.", + "**Sale of the aircraft.** The owner gives the buyer the paper logbooks and a records package from the system (the entries with their signatures, the record history, " \ + "the procedures and the data archive)." + ].join("\n\n") + end + + def https? = Rails.application.config.force_ssl + + def https_sentence + if https? + "Connections use HTTPS only: the system redirects plain HTTP and marks its cookies secure." + else + "The system is set not to enforce HTTPS itself (FORCE_SSL=false): [say how connections are protected, e.g. a TLS proxy in front, or the home network only]." + end + end + + def sign_in_sentence + if Sso.enabled? && !Sso.password_login? + "People sign in only with single sign-on (#{Sso.label}); password sign-in is turned off." + elsif Sso.enabled? + "People sign in with single sign-on (#{Sso.label}) or with their own email and password; there are no shared accounts." + else + "People sign in with their own email and password; there are no shared accounts." + end + end + + def docker? = File.exist?("/.dockerenv") +end diff --git a/app/views/admin/procedures/_document.html.erb b/app/views/admin/procedures/_document.html.erb index 074faf1..55225c8 100644 --- a/app/views/admin/procedures/_document.html.erb +++ b/app/views/admin/procedures/_document.html.erb @@ -34,7 +34,7 @@
  • Software: Simple Aircraft Manager, version <%= info.revision %> (Ruby <%= RUBY_VERSION %>, Rails <%= Rails.version %>, SQLite <%= SQLite3::SQLITE_VERSION %>).
  • Hosting and network: <% if policy.hosting_description.present? %>
    <%= markdown(policy.hosting_description) %>
    <% else %>[describe the server, location and network]<% end %> -

    Access is over HTTPS<%= " with single sign-on (#{Sso.label})" if Sso.enabled? %>.

  • +

    <%= ProceduresTemplates.https? ? "Connections use HTTPS only: the system redirects plain HTTP and marks its cookies secure." : "The system is set not to enforce HTTPS itself (FORCE_SSL=false); how connections are protected is described above." %> <%= ProceduresTemplates.sign_in_sentence %>

  • Data: one SQLite database plus uploaded files (stored once per identical file) on the server's storage volume.
  • Backups: every night the app makes a verified copy of the database in the storage volume (SQLite integrity check and record counts compared) and keeps the newest <%= Setting.integer("backups_kept") %>. Off-site: <% if OffsiteConnection.connected? %>after each nightly backup the app copies the verified database snapshot (compressed) to Google Drive (account <%= OffsiteConnection.current.account_email %>, folder “<%= OffsiteConnection::ROOT_FOLDER %>”), keeping the newest <%= Setting.integer("offsite_backups_kept") %>, together with every uploaded file (scans, documents, attachments) not already copied; files are never deleted from the off-site copy. A failed copy is emailed to the administrators. A restore test downloads the newest copy, opens it and checks it, and checks a sample of files against their checksums.<%= " #{policy.offsite_backup_description}" if policy.offsite_backup_description.present? %><% else %><%= policy.offsite_backup_description.presence || "[describe the off-site backup]" %><% end %>
  • @@ -73,7 +73,7 @@

    7. Recordkeeping system controls