Electronic signatures on logbook entries (AC 120-78B chapter 2)

- Sign an entry: review exactly what's certified, choose a current
  certificate (eligibility checked: pilot only for preventive maintenance,
  inspections need their result and time), re-enter the password or sign
  in again with SSO (prompt=login, within 5 minutes), and confirm the
  "Certified by" statement (43.9 return to service, 43.11(a)(5) for
  inspections, preventive maintenance for pilots)
- The signature stores signer, certificate, statement, UTC time, how they
  authenticated, IP/browser, a SHA-256 fingerprint of the entry's content
  and a readable snapshot; an HMAC seal covers the signature record. Status
  shows Valid / Superseded / Altered since signing. The signer is emailed
- Signed entries (and their sub-components) can't be edited or deleted;
  a correction entry, once signed, supersedes the original (kept)
- Owners invite an outside mechanic by email to sign one entry: one-time,
  14-day link; they create or use their own account and certificate and
  see only that entry
- Admins can disable accounts (signed out, can't sign in or sign; past
  signatures kept); users with signatures can't be deleted
- Printouts show the electronic signature and fingerprint; archives carry
  signatures (marked imported, with their origin) and corrections

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rickyandClaude Opus 5.5 committed 2026-11-07 13:12:04 -05:00
1 parent 7caa213e7a
commit d719f663bc
47 files changed
+1059 -17

No files matched your search

+47
View File
@@ -0,0 +1,47 @@
# An electronic signature on a logbook entry (AC 120-78B chapter 2).
#
# It records the signer, the certificate they signed with, the statement they
# certified, when, and how they proved who they were. content_digest is a
# SHA-256 of the entry's content at signing (content_snapshot is that content),
# so any later change shows; seal is an HMAC over the signature itself, keyed
# by this server, so the signature record can't be altered unnoticed either.
class EntrySignature < ApplicationRecord
AUTH_METHODS = { "password" => "password re-entered", "sso" => "single sign-on, signed in again" }.freeze
# "Certified by" conveys the intent to sign (2.2.2).
LABEL = "Certified by".freeze
belongs_to :logbook_entry
belongs_to :user, optional: true
validates :signer_name, :certificate_kind, :certificate_number, :statement, :signed_at, :content_digest, :content_snapshot, presence: true
validates :auth_method, inclusion: { in: AUTH_METHODS.keys + [ "imported" ] }
validates :logbook_entry_id, uniqueness: true
before_create { self.seal ||= compute_seal unless imported? }
before_update { throw :abort } # signatures are permanent (2.1.2.7)
before_destroy { throw :abort unless destroyed_by_association }
def self.seal_key = Rails.application.key_generator.generate_key("entry-signature-seal", 32)
def imported? = origin.present?
def certificate_label = UserCertificate::SHORT_LABELS.fetch(certificate_kind, certificate_kind)
def short_id = content_digest.first(12)
def compute_seal
payload = [ logbook_entry_id, user_id, signer_name, certificate_kind, certificate_number, statement,
signed_at.utc.iso8601(6), content_digest, auth_method ].join("\u001f")
OpenSSL::HMAC.hexdigest("SHA256", self.class.seal_key, payload)
end
def seal_valid? = imported? || (seal.present? && ActiveSupport::SecurityUtils.secure_compare(seal, compute_seal))
def content_matches? = content_digest == logbook_entry.content_digest
# :valid, :superseded, :altered (content or signature changed since signing)
def status
return :altered unless seal_valid? && content_matches?
logbook_entry.superseded_at ? :superseded : :valid
end
def status_label
{ valid: "Valid", superseded: "Superseded by a correction", altered: "Altered since signing" }[status]
end
end
+106
View File
@@ -26,6 +26,12 @@ class LogbookEntry < ApplicationRecord
# Sub-components it also covers (the oil filter on the engine…).
has_many :parts, -> { includes(component: :component_type).order(:id) }, class_name: "LogbookEntryPart",
dependent: :destroy, autosave: true
# Electronic signature (AC 120-78B): once signed the entry is locked; a
# correction is a new entry that supersedes it (2.2.8).
has_one :signature, class_name: "EntrySignature", dependent: :destroy
has_many :signing_invitations, dependent: :destroy
belongs_to :supersedes, class_name: "LogbookEntry", optional: true
has_one :superseded_by, class_name: "LogbookEntry", foreign_key: :supersedes_id, inverse_of: :supersedes, dependent: :nullify
has_many :inspection_records, dependent: :nullify
has_many :ad_compliances, dependent: :nullify
has_many :squawks, dependent: :nullify
@@ -38,6 +44,12 @@ class LogbookEntry < ApplicationRecord
validates :component_hours_at_entry, :component_since_overhaul_at_entry, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
normalizes :signoff_certificate_type, :inspection_result, :signoff_certificate_number, with: ->(v) { v.strip.presence }
# Fields that may still change on a signed entry: its link to a scanned
# page, the transcription check, and being superseded by a correction.
UNSIGNED_FIELDS = %w[document_id page_number verified superseded_at updated_at].freeze
before_update :keep_signed_content
before_destroy(prepend: true) { throw :abort if signed? && !destroyed_by_association }
scope :recent_first, -> { order(date: :desc, created_at: :desc) }
scope :unverified, -> { where(verified: false) }
@@ -49,6 +61,90 @@ class LogbookEntry < ApplicationRecord
def to_s = "#{date} — #{LOG_TYPES[log_type]}"
def signed? = signature.present?
def superseded? = superseded_at.present?
# What a signature covers: the entry's own content, in a fixed form, so
# the fingerprint changes if anything in it does.
def content_payload
num = ->(v) { v.nil? ? nil : format("%.1f", v) }
{
"v" => 1, "id" => id, "aircraft_id" => aircraft_id, "date" => date&.iso8601, "log_type" => log_type, "entry_type" => entry_type,
"text" => text.to_s, "airframe_hours" => num.(aircraft_hours_at_entry), "location" => signoff_location.to_s,
"signer" => [ signoff_person.to_s, signoff_certificate_type.to_s, signoff_certificate_number.to_s ],
"inspection_result" => inspection_result.to_s, "supersedes_id" => supersedes_id,
"component" => component_id && [ component_id, num.(component_hours_at_entry), num.(component_since_overhaul_at_entry) ],
"parts" => parts.reject(&:marked_for_destruction?).map { [ _1.component_id, num.(_1.hours_at_entry), num.(_1.since_overhaul_at_entry) ] }.sort_by { _1.first.to_i }
}
end
def content_digest = OpenSSL::Digest::SHA256.hexdigest(content_payload.to_json)
# Readable copy of what was signed, kept with the signature.
def content_snapshot
c = component
{
"aircraft" => { "tail_number" => aircraft.tail_number, "make" => aircraft.make, "model" => aircraft.model, "serial_number" => aircraft.serial_number },
"date" => date&.iso8601, "log" => LOG_TYPES[log_type], "entry_type" => ENTRY_TYPES[entry_type], "text" => text,
"airframe_total_time" => aircraft_hours_at_entry&.to_s, "time_basis" => aircraft.time_basis, "location" => signoff_location,
"inspection_result" => inspection_result_label,
"component" => c && { "type" => c.component_type&.name, "make" => c.manufacturer, "model" => c.model, "serial_number" => c.serial_number,
"total_time" => component_hours_at_entry&.to_s, "since_overhaul" => component_since_overhaul_at_entry&.to_s,
"since_label" => c.since_overhaul_abbreviation },
"parts" => parts.map { |p| { "type" => p.component.component_type&.name, "model" => p.component.model, "serial_number" => p.component.serial_number,
"total_time" => p.hours_at_entry&.to_s, "since" => p.since_overhaul_at_entry&.to_s } },
"supersedes" => supersedes && { "date" => supersedes.date&.iso8601, "fingerprint" => supersedes.signature&.content_digest }
}
end
# "an annual" / "a 100-hour": from a linked inspection record, else the text.
def inspection_kind_phrase
name = inspection_records.first&.inspection_type&.name.to_s.sub(/\s*\(.*\)\z/, "").sub(/\s*inspection\z/i, "").strip.downcase
name = "annual" if name.empty? && text.to_s.match?(/annual/i)
name = "100-hour" if name.empty? && text.to_s.match?(/100[- ]?h(ou)?r/i)
return "a ______________" if name.empty?
"#{name.match?(/\A[aeiou]/) ? 'an' : 'a'} #{name}"
end
# What the signer certifies, by the kind of entry and certificate.
def certification_statement(certificate_kind)
if entry_type == "INSPECTION"
if inspection_result == "discrepancies"
"I certify that this aircraft has been inspected in accordance with #{inspection_kind_phrase} inspection and a list of discrepancies " \
"and unairworthy items dated #{date&.strftime('%b %-d, %Y')} has been provided for the aircraft owner or operator."
else
"I certify that this aircraft has been inspected in accordance with #{inspection_kind_phrase} inspection and was determined to be in airworthy condition."
end
elsif certificate_kind == "PILOT"
"I certify that the preventive maintenance described in this entry was performed in accordance with 14 CFR Part 43, and I approve it for return to service."
elsif entry_type == "MAINTENANCE"
"I certify that the work described in this entry was performed in accordance with 14 CFR Part 43, and I approve it for return to service with respect to that work."
else
"I certify that this entry is correct."
end
end
# Why this certificate can't sign this entry ([] if it can).
def signing_problems(certificate)
problems = []
problems << "it's already signed" if signed?
problems << "it has been superseded by a correction" if superseded?
problems << "it has no description" if text.blank?
problems << "it has no date" if date.blank?
if entry_type == "INSPECTION"
problems << "an inspection entry needs its result (airworthy, or discrepancy list)" if inspection_result.blank?
problems << "an inspection entry needs the aircraft's total time" if aircraft_hours_at_entry.blank?
end
if certificate
problems << "that certificate has expired" if certificate.expired?
problems << "a pilot certificate can sign preventive maintenance only" if certificate.kind == "PILOT" && entry_type != "MAINTENANCE"
problems << "\"Other\" certificates can't sign maintenance or inspections" if certificate.kind == "OTHER" && RECORD_TYPES.include?(entry_type)
else
problems << "choose a certificate to sign with"
end
problems
end
# From the form: { component_id => { "include" => "1", "hours" => …, "since" => … } }.
# Only the aircraft's sub-components of the entry's component are kept.
def assign_parts(params, aircraft)
@@ -79,4 +175,14 @@ class LogbookEntry < ApplicationRecord
end
missing
end
private
def keep_signed_content
return unless signed? && signature.persisted?
locked = changed - UNSIGNED_FIELDS
return if locked.empty?
errors.add(:base, "This entry is signed, so it can't be changed. Make a correction entry instead")
throw :abort
end
end
+4
View File
@@ -6,4 +6,8 @@ class LogbookEntryPart < ApplicationRecord
validates :component_id, uniqueness: { scope: :logbook_entry_id }
validates :hours_at_entry, :since_overhaul_at_entry, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
# Part of a signed entry's content: locked with it.
before_save { throw :abort if logbook_entry&.signed? }
before_destroy { throw :abort if logbook_entry&.signed? && !destroyed_by_association }
end
+25
View File
@@ -0,0 +1,25 @@
# An invitation, by email, for someone outside the aircraft (a mechanic) to
# sign one logbook entry with their own account and certificate
# (AC 120-78B 3.2.8.11). The link works once and expires.
class SigningInvitation < ApplicationRecord
VALID_FOR = 14.days
belongs_to :logbook_entry
belongs_to :invited_by, class_name: "User", optional: true
belongs_to :user, optional: true
attr_reader :token
normalizes :email, with: ->(e) { e.strip.downcase }
validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
before_validation(on: :create) do
@token = SecureRandom.urlsafe_base64(32)
self.token_digest = self.class.digest(@token)
self.expires_at ||= VALID_FOR.from_now
end
def self.digest(token) = OpenSSL::Digest::SHA256.hexdigest(token.to_s)
def self.find_usable(token) = where(token_digest: digest(token), used_at: nil).where("expires_at > ?", Time.current).first
def aircraft = logbook_entry.aircraft
end
+5
View File
@@ -5,6 +5,11 @@ class User < ApplicationRecord
has_many :aircraft, through: :aircraft_roles
has_one :air_trail_connection, dependent: :destroy
has_many :certificates, -> { ordered }, class_name: "UserCertificate", dependent: :destroy
has_many :entry_signatures, dependent: :nullify
scope :active, -> { where(disabled_at: nil) }
def disabled? = disabled_at.present?
# Emailed sign-in links: valid 15 minutes, and spent by the next sign-in of
# any kind (or an email change), so each link works once. last_signed_in_at