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 <noreply@anthropic.com>
This commit is contained in:
rickyandClaude Opus 5.5 committed 2026-11-07 15:35:41 -05:00
1 parent 90e68711a0
commit 76643de2e7
9 files changed
+145 -9

No files matched your search

@@ -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,
@@ -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
}
}
+10 -1
View File
@@ -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?
+69
View File
@@ -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
@@ -34,7 +34,7 @@
<li><strong>Software:</strong> Simple Aircraft Manager, version <%= info.revision %> (Ruby <%= RUBY_VERSION %>, Rails <%= Rails.version %>, SQLite <%= SQLite3::SQLITE_VERSION %>).</li>
<li><strong>Hosting and network:</strong>
<% if policy.hosting_description.present? %><div class="mt-1"><%= markdown(policy.hosting_description) %></div><% else %>[describe the server, location and network]<% end %>
<p class="mt-1">Access is over HTTPS<%= " with single sign-on (#{Sso.label})" if Sso.enabled? %>.</p></li>
<p class="mt-1"><%= 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 %></p></li>
<li><strong>Data:</strong> one SQLite database plus uploaded files (stored once per identical file) on the server's storage volume.</li>
<li><strong>Backups:</strong> 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 %></li>
</ul>
@@ -73,7 +73,7 @@
<h2 class="<%= h2 %>">7. Recordkeeping system controls</h2>
<ul class="<%= p_ %> list-disc pl-5">
<li><strong>Controlled access (3.2.1):</strong> personal accounts; roles per aircraft; passwords of at least 12 characters, refused if known from a data breach; optional authenticator-app codes; accounts locked for 15 minutes after 10 failed sign-ins (the user is emailed); rate-limited sign-in; sessions end after 30 days unused; changing an email or password needs the current password.</li>
<li><strong>Controlled access (3.2.1):</strong> personal accounts (<%= Sso.enabled? ? (Sso.password_login? ? "single sign-on with #{Sso.label} or password" : "single sign-on with #{Sso.label} only") : "email and password" %>); roles per aircraft; passwords of at least 12 characters, refused if known from a data breach; optional authenticator-app codes; accounts locked for 15 minutes after 10 failed sign-ins (the user is emailed); rate-limited sign-in; sessions end after 30 days unused; changing an email or password needs the current password.</li>
<li><strong>Record preservation (3.2.2):</strong> every change to a maintenance record is kept with who, when and what changed, in a hash chain per aircraft that can't be edited; signed entries are locked.</li>
<li><strong>Confidential information (3.2.3):</strong> records are visible only to the aircraft's users, and to share links an owner creates (scoped and optionally expiring).</li>
<li><strong>Data corruption (3.2.4):</strong> nightly, the history chains and every signature's seal and fingerprint are checked; administrators are emailed on any problem.</li>
+13 -5
View File
@@ -11,9 +11,12 @@
<%= f.field :responsible_name, label: "Responsible person", placeholder: "Jane Pilot" %>
<%= f.field :responsible_title, label: "Their role", placeholder: "Owner" %>
</div>
<%= f.field :hosting_description, as: :textarea, rows: 8, label: "Hosting and network",
hint: "Leave a blank line between paragraphs. Markdown works: **bold**, lists.",
placeholder: "Self-hosted on a server at the owner's home, behind a firewall and an authenticating proxy." %>
<div data-controller="insert-text" data-insert-text-text-value="<%= ProceduresTemplates.hosting %>">
<%= f.field :hosting_description, as: :textarea, rows: 8, label: "Hosting and network",
hint: "Leave a blank line between paragraphs. Markdown works: **bold**, lists.", data: { insert_text_target: "field" },
placeholder: "Where the server is, who can administer it, how it's reached and protected, how updates are installed." %>
<button type="button" class="btn-secondary btn-sm mt-2" data-action="insert-text#insert">Insert suggested text</button>
</div>
<%= f.field :offsite_backup_description, as: :textarea, rows: 2, label: (OffsiteConnection.connected? ? "Off-site backup (optional: Google Drive is connected)" : "Off-site backup"),
hint: (OffsiteConnection.connected? ? "The Google Drive backup is described automatically; add anything else here." : "Or set up the built-in Google Drive backup under Admin → Off-site Backup."),
placeholder: "The storage volume is backed up nightly with restic to an encrypted off-site repository; retention 30 days." %>
@@ -21,8 +24,12 @@
<%= f.field :audit_interval_months, as: :number, min: 1, max: 24, label: "Audit every (months)" %>
<%= f.field :audit_sample_size, as: :number, min: 1, max: 50, label: "Entries sampled per audit" %>
</div>
<%= f.field :additional_procedures, as: :textarea, rows: 12, label: "Additional procedures (optional)",
hint: "Leave a blank line between items. Markdown works: **bold** headings, lists." %>
<div data-controller="insert-text" data-insert-text-text-value="<%= ProceduresTemplates.additional %>">
<%= f.field :additional_procedures, as: :textarea, rows: 12, label: "Additional procedures (optional)",
hint: "Leave a blank line between items. Markdown works: **bold** headings, lists.", data: { insert_text_target: "field" } %>
<button type="button" class="btn-secondary btn-sm mt-2" data-action="insert-text#insert">Insert suggested text</button>
</div>
<p class="hint">Suggested text is filled in from this installation's settings, with [bracketed] blanks for what only you know. Edit it to match how you actually work, then save. A revision can't be adopted while a blank is left.</p>
<%= f.submit "Save" %>
<% end %>
@@ -38,6 +45,7 @@
<p class="text-sm"><%= link_to "Preview the draft", draft_admin_procedures_path, class: "link", target: "_blank" %> (generated from the current setup).</p>
<%= form_with url: adopt_admin_procedures_path, class: "flex flex-wrap items-end gap-2" do %>
<div class="min-w-0 flex-1"><%= label_tag :summary, "What changed", class: "label" %><%= text_field_tag :summary, nil, class: "input", placeholder: current ? "e.g. new mechanic added" : "Initial issue" %></div>
<% if @policy.unfilled_fields.any? %><p class="w-full text-sm text-amber-800">Fill in the [bracketed] blanks in: <%= @policy.unfilled_fields.to_sentence %>.</p><% end %>
<%= submit_tag "Adopt as revision #{(current&.number || 0) + 1}", class: "btn-primary", disabled: !@policy.complete?,
title: (@policy.complete? ? nil : "Fill in the operator, responsible person, hosting and off-site backup (or connect Google Drive) first") %>
<% end %>