diff --git a/app/controllers/admin/integrations_controller.rb b/app/controllers/admin/integrations_controller.rb new file mode 100644 index 0000000..b64e5ee --- /dev/null +++ b/app/controllers/admin/integrations_controller.rb @@ -0,0 +1,93 @@ +# Admin → Integrations: tokens for other systems (e.g. Redmine), limited to +# chosen aircraft and scopes, each with an optional webhook (docs/api.md). +# The token and webhook secret are shown once, right after they're made. +class Admin::IntegrationsController < ApplicationController + before_action :require_admin! + before_action :set_integration, only: %i[show edit update destroy new_secret] + + def index + @integrations = ApiToken.integration.order(revoked_at: :desc, name: :asc).includes(:webhook_endpoints) + end + + def new + @integration = ApiToken.new(kind: "integration", scopes: %w[read]) + @endpoint = WebhookEndpoint.new(events: []) + end + + def create + @integration = ApiToken.new(integration_params.merge(kind: "integration", user: current_user)) + @endpoint = build_endpoint(@integration) + ApiToken.transaction do + @integration.save! + @endpoint&.save! + end + @secret = @endpoint&.secret + render :created + rescue ActiveRecord::RecordInvalid + @endpoint ||= WebhookEndpoint.new(events: []) + render :new, status: :unprocessable_entity + end + + def show + @endpoint = @integration.webhook_endpoints.first + @deliveries = @endpoint ? @endpoint.deliveries.recent.limit(25) : [] + end + + def edit + @endpoint = @integration.webhook_endpoints.first || WebhookEndpoint.new(events: []) + end + + def update + @endpoint = @integration.webhook_endpoints.first + ApiToken.transaction do + @integration.update!(integration_params) + if webhook_params[:url].present? + @endpoint ||= @integration.webhook_endpoints.new(secret: WebhookEndpoint.new_secret) + @endpoint.update!(webhook_params) + else + @endpoint&.destroy! + end + end + redirect_to admin_integration_path(@integration), notice: t("flash.admin_integrations.saved") + rescue ActiveRecord::RecordInvalid + @endpoint ||= WebhookEndpoint.new(events: []) + render :edit, status: :unprocessable_entity + end + + # A new webhook secret, shown once. + def new_secret + @endpoint = @integration.webhook_endpoints.first or return redirect_to(admin_integration_path(@integration)) + @endpoint.update!(secret: WebhookEndpoint.new_secret) + @secret = @endpoint.secret + render :created + end + + def destroy + @integration.revoke! + @integration.webhook_endpoints.update_all(enabled: false) + redirect_to admin_integrations_path, notice: t("flash.admin_integrations.revoked", name: @integration.name) + end + + private + + def set_integration = @integration = ApiToken.integration.find(params[:id]) + + def integration_params + p = params.require(:api_token).permit(:name, scopes: [], aircraft_ids: []) + p[:scopes] = Array(p[:scopes]) & ApiToken::SCOPES.keys + p[:aircraft_ids] = Aircraft.where(id: Array(p[:aircraft_ids])).ids + p + end + + def webhook_params + p = params.fetch(:webhook, {}).permit(:url, :enabled, events: []) + p[:events] = Array(p[:events]) & WebhookEndpoint::EVENTS.keys + p[:enabled] = p[:enabled] != "0" + p + end + + def build_endpoint(integration) + return if webhook_params[:url].blank? + integration.webhook_endpoints.new(webhook_params.merge(secret: WebhookEndpoint.new_secret)) + end +end diff --git a/app/controllers/api/v1/aircraft_controller.rb b/app/controllers/api/v1/aircraft_controller.rb new file mode 100644 index 0000000..4d9a0ba --- /dev/null +++ b/app/controllers/api/v1/aircraft_controller.rb @@ -0,0 +1,49 @@ +module Api + module V1 + # The fleet this token reaches, and each aircraft's own lists. + class AircraftController < BaseController + before_action -> { require_scope!(:read) } + + def index + render_page(aircraft_scope) { ApiPresenter.aircraft(_1) } + end + + def show + render json: { data: ApiPresenter.aircraft(find_aircraft(params[:id])) } + end + + # The parts tree (?all=1 includes disposed parts). + def components + aircraft = find_aircraft(params[:id]) + scope = aircraft.components.includes(:component_type) + scope = scope.where.not(status: "DISPOSED") unless params[:all].present? + render_page(scope) { ApiPresenter.component(_1) } + end + + # Everything coming due, soonest first (hours projected to dates). + def due + aircraft = find_aircraft(params[:id]) + render json: { data: DueList.new(aircraft).items.map { ApiPresenter.due_item(_1) } } + end + + def inspections + aircraft = find_aircraft(params[:id]) + render json: { data: Compliance.inspection_rows(aircraft).map { ApiPresenter.inspection(_1) } } + end + + def ads + aircraft = find_aircraft(params[:id]) + render json: { data: Compliance.ad_rows(aircraft).map { ApiPresenter.ad(_1) } } + end + + # Logbook entries, oldest first (paged); ?log=AC|ENG|PROP|OTHER, ?signed=true|false. + def logbook_entries + aircraft = find_aircraft(params[:id]) + scope = aircraft.logbook_entries.includes(:signature) + scope = scope.where(log_type: params[:log]) if params[:log].present? + scope = params[:signed] == "true" ? scope.where.associated(:signature) : scope.where.missing(:signature) if params[:signed].present? + render_page(scope) { ApiPresenter.logbook_entry(_1) } + end + end + end +end diff --git a/app/controllers/api/v1/base_controller.rb b/app/controllers/api/v1/base_controller.rb new file mode 100644 index 0000000..9e191dd --- /dev/null +++ b/app/controllers/api/v1/base_controller.rb @@ -0,0 +1,123 @@ +# The REST API, version 1 (docs/api.md). JSON in and out; a token in +# "Authorization: Bearer sam_…" instead of a browser session, so no cookies +# and no CSRF tokens. +# +# A personal token acts as its owner. An integration token acts for the +# person named in "SAM-On-Behalf-Of: " (required for writes), and +# reaches only its aircraft that person can also see. +module Api + module V1 + class BaseController < ActionController::API + include RejectsNullBytes + + MAX_PAGE = 200 + + before_action :authenticate + rate_limit to: 600, within: 1.minute, by: -> { @api_token&.id || request.remote_ip }, + with: -> { render_error(:too_many_requests, "rate_limited", "Too many requests; slow down.") } + around_action :idempotent, if: -> { request.post? || request.patch? || request.delete? } + + rescue_from ActiveRecord::RecordNotFound do + render_error(:not_found, "not_found", "Not found, or not available to this token.") + end + rescue_from ActionController::ParameterMissing, ActionDispatch::Http::Parameters::ParseError do |e| + render_error(:bad_request, "bad_request", e.message.truncate(200)) + end + rescue_from ActiveRecord::RecordInvalid do |e| + render_invalid(e.record) + end + rescue_from ActiveSupport::MessageVerifier::InvalidSignature, ActiveModel::RangeError, + ActiveRecord::NotNullViolation, ActiveRecord::InvalidForeignKey do + render_error(:unprocessable_entity, "invalid", "Some values couldn't be saved.") + end + + private + + attr_reader :api_token + + def acting_user = Current.api_user + + def authenticate + token = request.authorization.to_s[/\ABearer\s+(\S+)\z/i, 1] + @api_token = ApiToken.authenticate(token) + return render_error(:unauthorized, "unauthorized", "A valid API token is required.") unless @api_token + + Current.api_token = @api_token + Current.ip_address = request.remote_ip + Current.api_user = @api_token.personal? ? @api_token.user : on_behalf_of + @api_token.used!(request.remote_ip) + end + + # The person an integration is acting for, if it named one. + def on_behalf_of + email = request.headers["SAM-On-Behalf-Of"].to_s.strip.downcase.presence or return + User.active.find_by(email_address: email) || + render_error(:unprocessable_entity, "unknown_user", "SAM-On-Behalf-Of doesn't match an active user.") + end + + def require_scope!(scope) + return if api_token.allows?(scope) + render_error(:forbidden, "missing_scope", "This token doesn't have the #{scope} scope.") + end + + # Writes always name a person, so the record history shows who. + def require_person! + return if acting_user + render_error(:unprocessable_entity, "on_behalf_of_required", "Writes with an integration token need SAM-On-Behalf-Of.") + end + + def aircraft_scope = api_token.aircraft_scope(acting_user) + + def find_aircraft(id = params[:aircraft_id]) = aircraft_scope.find(id) + + def role_on(aircraft) = acting_user&.role_for(aircraft) + def owner_of?(aircraft) = role_on(aircraft).in?(%w[admin owner]) + + # ?limit= (1–200, default 50), ?after= to continue, ?updated_since=. + def paginate(scope) + limit = params.fetch(:limit, 50).to_i.clamp(1, MAX_PAGE) + scope = scope.where(scope.arel_table[:id].gt(params[:after].to_i)) if params[:after].present? + if params[:updated_since].present? + since = Time.iso8601(params[:updated_since].to_s) rescue (raise ActionController::BadRequest, "updated_since must be an ISO 8601 time") + scope = scope.where(scope.arel_table[:updated_at].gteq(since)) + end + records = scope.reorder(:id).limit(limit + 1).to_a + more = records.size > limit + records = records.first(limit) + [ records, (records.last.id if more) ] + end + + def render_page(scope, &present) + records, next_after = paginate(scope) + render json: { data: records.map(&present), next_after: next_after } + end + + def render_error(status, code, message, fields: nil) + render json: { error: { code: code, message: message, fields: fields }.compact }, status: status + end + + def render_invalid(record) + render_error(:unprocessable_entity, "invalid", record.errors.full_messages.to_sentence, fields: record.errors.to_hash) + end + + # The same Idempotency-Key again (a retry) gets the first answer; the + # same key with a different request is a conflict. + def idempotent + key = request.headers["Idempotency-Key"].to_s.strip + return yield if key.empty? || api_token.nil? + return render_error(:bad_request, "bad_request", "Idempotency-Key is too long.") if key.length > 100 + + digest = OpenSSL::Digest::SHA256.hexdigest([ request.method, request.path, request.raw_post ].join("\n")) + if (seen = api_token.idempotency_keys.find_by(key: key)) + return render_error(:conflict, "idempotency_conflict", "This Idempotency-Key was used for a different request.") if seen.request_digest != digest + response.headers["Idempotent-Replay"] = "true" + return render(json: seen.response_body, status: seen.response_status) + end + yield + return if response.status >= 500 + api_token.idempotency_keys.create(key: key, request_digest: digest, response_status: response.status, + response_body: response.body, created_at: Time.current) + end + end + end +end diff --git a/app/controllers/api/v1/me_controller.rb b/app/controllers/api/v1/me_controller.rb new file mode 100644 index 0000000..4b8eaaa --- /dev/null +++ b/app/controllers/api/v1/me_controller.rb @@ -0,0 +1,16 @@ +module Api + module V1 + # What this token is and who it's acting as: a quick check for a new integration. + class MeController < BaseController + def show + render json: { data: { + token: { name: api_token.name, kind: api_token.kind, hint: api_token.token_hint, scopes: api_token.scopes, + aircraft_ids: (api_token.aircraft_ids if api_token.integration?) }.compact, + acting_as: acting_user && { id: acting_user.id, name: acting_user.display_name, email: acting_user.email_address }, + aircraft_ids: aircraft_scope.ids, + api_version: "v1", app_version: Rails.root.join("VERSION").read.strip + } } + end + end + end +end diff --git a/app/controllers/api/v1/squawks_controller.rb b/app/controllers/api/v1/squawks_controller.rb new file mode 100644 index 0000000..4270e6c --- /dev/null +++ b/app/controllers/api/v1/squawks_controller.rb @@ -0,0 +1,66 @@ +module Api + module V1 + # Squawks: list and report on an aircraft; find by external_ref; update. + # Resolving happens through a signed logbook entry, not here. + class SquawksController < BaseController + before_action -> { require_scope!(:read) }, only: %i[index show lookup] + before_action -> { require_scope!("squawks:write") }, :require_person!, only: %i[create update] + + # GET /aircraft/:aircraft_id/squawks?status=open|resolved|all (default open) + def index + scope = find_aircraft.squawks.includes(:reported_by).with_attached_attachments + scope = case params.fetch(:status, "open") + when "open" then scope.active + when "resolved" then scope.resolved + else scope + end + render_page(scope) { ApiPresenter.squawk(_1) } + end + + # GET /squawks?external_ref=redmine:issue:4512 + def lookup + ref = params.require(:external_ref) + scope = Squawk.where(aircraft: aircraft_scope, external_ref: ref).includes(:reported_by).with_attached_attachments + render json: { data: scope.map { ApiPresenter.squawk(_1) } } + end + + def show + render json: { data: ApiPresenter.squawk(find_squawk) } + end + + # POST /aircraft/:aircraft_id/squawks + def create + aircraft = find_aircraft + squawk = aircraft.squawks.new(create_params.merge(reported_by: acting_user, resolved: false)) + squawk.component_id = nil unless aircraft.components.exists?(id: squawk.component_id) + squawk.save! + SquawkReported.call(squawk, by: acting_user) + render json: { data: ApiPresenter.squawk(squawk) }, status: :created + end + + # PATCH /squawks/:id: external_ref by anyone who may write; the rest + # (issue, priority, component, notes) by the aircraft's owners, as in the app. + def update + squawk = find_squawk + return render_error(:unprocessable_entity, "resolved", "A resolved squawk can't be changed.") if squawk.resolved? + attrs = params.require(:squawk).permit(:external_ref, :issue_reported, :priority, :component_id, :notes) + if (attrs.keys - %w[external_ref]).any? && !owner_of?(squawk.aircraft) + return render_error(:forbidden, "owners_only", "Only the aircraft's owners can change a squawk's details.") + end + attrs[:component_id] = nil if attrs.key?(:component_id) && !squawk.aircraft.components.exists?(id: attrs[:component_id]) + squawk.update!(attrs) + render json: { data: ApiPresenter.squawk(squawk) } + end + + private + + def find_squawk = Squawk.where(aircraft: aircraft_scope).find(params[:id]) + + def create_params + params.require(:squawk).permit(:issue_reported, :priority, :component_id, :external_ref).tap do |p| + p[:priority] = p.fetch(:priority, 2).to_i + end + end + end + end +end diff --git a/app/controllers/api_tokens_controller.rb b/app/controllers/api_tokens_controller.rb new file mode 100644 index 0000000..151f9f4 --- /dev/null +++ b/app/controllers/api_tokens_controller.rb @@ -0,0 +1,19 @@ +# Profile → API tokens: personal tokens for the REST API (docs/api.md). The +# token is shown once, on the page right after it's made (not kept in the +# flash or anywhere else). +class ApiTokensController < ApplicationController + def create + @token = current_user.api_tokens.new(name: params.dig(:api_token, :name), kind: "personal", + scopes: Array(params.dig(:api_token, :scopes)) & ApiToken::SCOPES.keys) + if @token.save + render :created + else + redirect_to edit_profile_path(anchor: "api"), alert: @token.errors.full_messages.to_sentence + end + end + + def destroy + current_user.api_tokens.personal.active.find(params[:id]).revoke! + redirect_to edit_profile_path(anchor: "api"), notice: t("flash.api_tokens.revoked") + end +end diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb index 2040b6c..c5c08bb 100644 --- a/app/controllers/application_controller.rb +++ b/app/controllers/application_controller.rb @@ -4,8 +4,8 @@ class ApplicationController < ActionController::Base include TimeZones allow_browser versions: :modern + include RejectsNullBytes prepend_before_action :redirect_to_setup - prepend_before_action :reject_null_bytes before_action { Current.ip_address = request.remote_ip } # for record history helper_method :current_user @@ -36,20 +36,6 @@ class ApplicationController < ActionController::Base private - # No form sends a null byte; some libraries (password hashing, file paths) - # raise on one, so refuse the request up front. - def reject_null_bytes - head :bad_request if contains_null_byte?(request.params) - end - - def contains_null_byte?(value) - case value - when String then value.include?("\0") - when Hash then value.any? { |k, v| contains_null_byte?(k) || contains_null_byte?(v) } - when Array then value.any? { contains_null_byte?(_1) } - else false - end - end def current_user = Current.user diff --git a/app/controllers/concerns/rejects_null_bytes.rb b/app/controllers/concerns/rejects_null_bytes.rb new file mode 100644 index 0000000..afc51a1 --- /dev/null +++ b/app/controllers/concerns/rejects_null_bytes.rb @@ -0,0 +1,22 @@ +# No form or API client sends a null byte; some libraries (password hashing, +# file paths) raise on one, so such requests are refused up front. +module RejectsNullBytes + extend ActiveSupport::Concern + + included { prepend_before_action :reject_null_bytes } + + private + + def reject_null_bytes + head :bad_request if contains_null_byte?(request.params) + end + + def contains_null_byte?(value) + case value + when String then value.include?("\0") + when Hash then value.any? { |k, v| contains_null_byte?(k) || contains_null_byte?(v) } + when Array then value.any? { contains_null_byte?(_1) } + else false + end + end +end diff --git a/app/controllers/squawks_controller.rb b/app/controllers/squawks_controller.rb index faaad7a..07d2b32 100644 --- a/app/controllers/squawks_controller.rb +++ b/app/controllers/squawks_controller.rb @@ -21,11 +21,7 @@ class SquawksController < ApplicationController end @squawk = @aircraft.squawks.new(squawk_params.merge(reported_by: current_user)) if @squawk.save - log_event("squawk", t("flash.squawks.squawk_reported_2", priority_label: @squawk.priority_label), notes: @squawk.issue_reported.truncate(200)) - if @squawk.grounding? - PushNotifier.notify(@aircraft.users.merge(User.active).where.not(id: current_user.id), :grounding_squawk, path: aircraft_squawks_path(@aircraft), - tag: "squawk-#{@squawk.id}", tail: @aircraft.tail_number, issue: @squawk.issue_reported.truncate(120)) - end + SquawkReported.call(@squawk, by: current_user) redirect_to aircraft_squawks_path(@aircraft), notice: t("flash.squawks.squawk_reported") else render :new, status: :unprocessable_entity diff --git a/app/jobs/webhook_delivery_job.rb b/app/jobs/webhook_delivery_job.rb new file mode 100644 index 0000000..fb741e2 --- /dev/null +++ b/app/jobs/webhook_delivery_job.rb @@ -0,0 +1,57 @@ +require "net/http" + +# Posts one webhook delivery. The body is signed so the receiver can check +# it came from here and wasn't replayed: +# SAM-Signature: t=,v1=." with the endpoint's secret> +# Anything but a 2xx answer is retried with growing waits, then marked failed. +class WebhookDeliveryJob < ApplicationJob + queue_as :default + ATTEMPTS = 8 + + class Failed < StandardError; end + + retry_on Failed, wait: :polynomially_longer, attempts: ATTEMPTS do |job, error| + WebhookDelivery.find_by(id: job.arguments.first)&.update!(status: "failed", last_error: error.message.truncate(250)) + end + + def perform(delivery_id) + delivery = WebhookDelivery.includes(:webhook_endpoint).find_by(id: delivery_id) or return + return if delivery.status == "delivered" + endpoint = delivery.webhook_endpoint + delivery.increment!(:attempts) + response = post(endpoint, delivery) + if response.code.to_i.between?(200, 299) + delivery.update!(status: "delivered", response_status: response.code.to_i, delivered_at: Time.current, last_error: nil) + else + delivery.update!(response_status: response.code.to_i, last_error: "HTTP #{response.code}") + raise Failed, "HTTP #{response.code}" + end + rescue OutboundAddress::Blocked => e + # Pointed at an address the server won't send to: retrying won't help. + delivery.update!(status: "failed", last_error: "blocked address (#{e.reason})") + rescue Timeout::Error, SocketError, SystemCallError, OpenSSL::SSL::SSLError, EOFError, IOError => e + delivery.update!(last_error: "#{e.class.name.demodulize}: #{e.message}".truncate(250)) + raise Failed, e.message + end + + private + + def post(endpoint, delivery) + uri = URI.parse(endpoint.url) + timestamp = Time.current.to_i + signature = OpenSSL::HMAC.hexdigest("SHA256", endpoint.secret, "#{timestamp}.#{delivery.payload}") + req = Net::HTTP::Post.new(uri) + req["Content-Type"] = "application/json" + req["User-Agent"] = "SimpleAircraftManager-Webhooks" + req["SAM-Event"] = delivery.event + req["SAM-Delivery"] = delivery.id.to_s + req["SAM-Signature"] = "t=#{timestamp},v1=#{signature}" + req.body = delivery.payload + http = Net::HTTP.new(uri.host, uri.port) + http.ipaddr = OutboundAddress.resolve!(uri.host, allow_private: true) # set up by an admin: the private network is fine + http.use_ssl = uri.scheme == "https" + http.open_timeout = 5 + http.read_timeout = 10 + http.start { _1.request(req) } + end +end diff --git a/app/models/api_idempotency_key.rb b/app/models/api_idempotency_key.rb new file mode 100644 index 0000000..0c0c11b --- /dev/null +++ b/app/models/api_idempotency_key.rb @@ -0,0 +1,9 @@ +# A write sent with an Idempotency-Key header, and the answer it got: the +# same key again (a retry) gets the same answer instead of a second record. +class ApiIdempotencyKey < ApplicationRecord + KEEP_FOR = 24.hours + + belongs_to :api_token + + def self.purge_old = where(created_at: ...KEEP_FOR.ago).delete_all +end diff --git a/app/models/api_token.rb b/app/models/api_token.rb new file mode 100644 index 0000000..88dd8a1 --- /dev/null +++ b/app/models/api_token.rb @@ -0,0 +1,80 @@ +# A key for the REST API (docs/api.md). Only its SHA-256 digest is kept; the +# token itself is shown once, when it's made. +# +# personal: acts as its owner, with exactly their aircraft and role. +# integration: made by an admin for another system (e.g. Redmine), limited to +# chosen aircraft and scopes. Its writes name the person they're +# for (SAM-On-Behalf-Of), so the record history always shows who. +class ApiToken < ApplicationRecord + KINDS = %w[personal integration].freeze + SCOPES = LabelSet.new("api_token.scopes", %w[read squawks:write]) + PREFIX = "sam_" + + belongs_to :user + has_many :webhook_endpoints, dependent: :destroy + has_many :idempotency_keys, class_name: "ApiIdempotencyKey", dependent: :delete_all + + attr_reader :token # the plain token, only right after create + + normalizes :name, with: ->(n) { n.to_s.strip } + validates :name, presence: true, length: { maximum: 80 } + validates :kind, inclusion: { in: KINDS } + validate :scopes_known + validate :integration_made_by_admin, on: :create + + before_validation :generate, on: :create + + scope :active, -> { where(revoked_at: nil) } + scope :personal, -> { where(kind: "personal") } + scope :integration, -> { where(kind: "integration") } + + def self.digest(token) = OpenSSL::Digest::SHA256.hexdigest(token.to_s) + + # The token for this string, if it's in use (and its owner is too). + def self.authenticate(token) + return unless token.to_s.start_with?(PREFIX) + found = active.includes(:user).find_by(token_digest: digest(token)) + found if found && (found.integration? || !found.user.disabled?) + end + + def personal? = kind == "personal" + def integration? = kind == "integration" + def revoked? = revoked_at.present? + def revoke! = update!(revoked_at: Time.current) + def allows?(scope) = scopes.include?(scope.to_s) + + # The aircraft this token reaches, acting for `user` (who must also have + # access, for an integration acting on someone's behalf). + def aircraft_scope(acting_user) + if personal? + user.accessible_aircraft + else + reachable = Aircraft.where(id: Array(aircraft_ids)) + acting_user ? reachable.where(id: acting_user.accessible_aircraft.select(:id)) : reachable + end + end + + # Last use, at most once a minute (no write per request). + def used!(ip) + return if last_used_at && last_used_at > 1.minute.ago && last_used_ip == ip + update_columns(last_used_at: Time.current, last_used_ip: ip) + end + + private + + def generate + @token = "#{PREFIX}#{SecureRandom.base58(40)}" + self.token_digest = self.class.digest(@token) + self.token_hint = @token.first(PREFIX.length + 6) + self.scopes = Array(scopes).map(&:to_s).compact_blank.uniq + end + + def scopes_known + errors.add(:scopes, :blank) if scopes.blank? + errors.add(:scopes, :inclusion) if (Array(scopes) - SCOPES.keys).any? + end + + def integration_made_by_admin + errors.add(:kind, :admins_only) if integration? && !user&.admin? + end +end diff --git a/app/models/current.rb b/app/models/current.rb index 2e743c1..8e8516f 100644 --- a/app/models/current.rb +++ b/app/models/current.rb @@ -1,4 +1,7 @@ class Current < ActiveSupport::CurrentAttributes - attribute :session, :ip_address - delegate :user, to: :session, allow_nil: true + # api_token / api_user: an API request (see Api::V1::BaseController), which + # acts as a person without a browser session. + attribute :session, :ip_address, :api_token, :api_user + + def user = api_user || session&.user end diff --git a/app/models/entry_signature.rb b/app/models/entry_signature.rb index 9dccdc7..9c142f5 100644 --- a/app/models/entry_signature.rb +++ b/app/models/entry_signature.rb @@ -18,6 +18,12 @@ class EntrySignature < ApplicationRecord validates :auth_method, inclusion: { in: AUTH_METHODS.keys + [ "imported" ] } validates :logbook_entry_id, uniqueness: true before_create { self.seal ||= compute_seal unless imported? } + # Integrations hear about it (webhooks); not for signatures carried over by an import. + after_create_commit do + next if imported? + entry = logbook_entry + Webhooks.publish("entry.signed", aircraft: entry.aircraft, data: ApiPresenter.logbook_entry(entry)) + end before_update { throw :abort } # signatures are permanent (2.1.2.7) before_destroy { throw :abort unless destroyed_by_association } diff --git a/app/models/help_guide.rb b/app/models/help_guide.rb index 09e9454..d008089 100644 --- a/app/models/help_guide.rb +++ b/app/models/help_guide.rb @@ -3,7 +3,7 @@ class HelpGuide DIR = Rails.root.join("docs/guide") ORDER = %w[README getting-started profile aircraft flights squawks oil-and-fuel components logbook records - inspections ads documents major-records sharing administration disclaimer changelog].freeze + inspections ads documents major-records sharing administration api disclaimer changelog].freeze OPTIONS = { parse: { smart: true }, render: { hardbreaks: false, unsafe: false }, diff --git a/app/models/record_version.rb b/app/models/record_version.rb index cff1516..7ebc411 100644 --- a/app/models/record_version.rb +++ b/app/models/record_version.rb @@ -4,6 +4,7 @@ # editing a version breaks the chain and the nightly check reports it. class RecordVersion < ApplicationRecord belongs_to :user, optional: true + belongs_to :api_token, optional: true scope :chronological, -> { order(:id) } @@ -15,10 +16,12 @@ class RecordVersion < ApplicationRecord def self.append!(item:, aircraft_id:, event:, changes:) now = Time.current payload = { "item_type" => item.class.name, "item_id" => item.id, "event" => event, "changes" => changes, - "user_id" => Current.user&.id, "at" => now.utc.iso8601(6) }.to_json + "user_id" => Current.user&.id, "at" => now.utc.iso8601(6) } + payload["api_token_id"] = Current.api_token.id if Current.api_token # made through the API (part of the hashed payload) + payload = payload.to_json prev = where(aircraft_id: aircraft_id).order(:id).last&.chain_hash create!(aircraft_id: aircraft_id, item_type: item.class.name, item_id: item.id, event: event, user_id: Current.user&.id, - ip_address: Current.ip_address, payload: payload, prev_hash: prev, chain_hash: digest(prev, payload), created_at: now) + ip_address: Current.ip_address, api_token_id: Current.api_token&.id, payload: payload, prev_hash: prev, chain_hash: digest(prev, payload), created_at: now) end def changes_hash = JSON.parse(payload)["changes"] diff --git a/app/models/squawk.rb b/app/models/squawk.rb index 1b7494b..381ba82 100644 --- a/app/models/squawk.rb +++ b/app/models/squawk.rb @@ -11,6 +11,15 @@ class Squawk < ApplicationRecord belongs_to :logbook_entry, optional: true has_many_attached :attachments + # Integrations hear about squawks (webhooks), once the change is saved. + after_create_commit { Webhooks.publish("squawk.created", aircraft: aircraft, data: ApiPresenter.squawk(self)) } + after_update_commit do + next if (saved_changes.keys - %w[updated_at]).empty? + event = saved_change_to_resolved? && resolved? ? "squawk.resolved" : "squawk.updated" + Webhooks.publish(event, aircraft: aircraft, data: ApiPresenter.squawk(self)) + end + + normalizes :external_ref, with: ->(r) { r.to_s.strip.first(200).presence } validates :priority, inclusion: { in: PRIORITIES.keys } validates :issue_reported, presence: true validates_uploads :attachments diff --git a/app/models/user.rb b/app/models/user.rb index 14b75ee..184a3a9 100644 --- a/app/models/user.rb +++ b/app/models/user.rb @@ -3,6 +3,7 @@ class User < ApplicationRecord has_many :sessions, dependent: :destroy has_many :aircraft_roles, dependent: :destroy has_many :push_subscriptions, dependent: :delete_all + has_many :api_tokens, dependent: :destroy normalizes :time_zone, with: ->(z) { z.strip.presence } validates :time_zone, inclusion: { in: ->(_) { ActiveSupport::TimeZone.all.map(&:name) } }, allow_nil: true diff --git a/app/models/webhook_delivery.rb b/app/models/webhook_delivery.rb new file mode 100644 index 0000000..3297857 --- /dev/null +++ b/app/models/webhook_delivery.rb @@ -0,0 +1,11 @@ +# One event sent (or being sent) to a webhook endpoint; the recent ones are +# listed for the admin, with the answer the other system gave. +class WebhookDelivery < ApplicationRecord + KEEP_FOR = 30.days + + belongs_to :webhook_endpoint + + scope :recent, -> { order(created_at: :desc) } + + def self.purge_old = where(created_at: ...KEEP_FOR.ago).delete_all +end diff --git a/app/models/webhook_endpoint.rb b/app/models/webhook_endpoint.rb new file mode 100644 index 0000000..f5fecc5 --- /dev/null +++ b/app/models/webhook_endpoint.rb @@ -0,0 +1,28 @@ +# Where an integration wants to hear about changes (squawks, signed entries): +# SAM posts JSON there, signed with the shared secret (see WebhookDeliveryJob). +class WebhookEndpoint < ApplicationRecord + EVENTS = LabelSet.new("webhook_endpoint.events", %w[squawk.created squawk.updated squawk.resolved entry.signed]) + + belongs_to :api_token + has_many :deliveries, class_name: "WebhookDelivery", dependent: :delete_all + + encrypts :secret + + normalizes :url, with: ->(u) { u.to_s.strip } + validates :url, presence: true, format: { with: %r{\Ahttps?://[^\s/]+(:\d+)?(/\S*)?\z}i } + validates :secret, presence: true, length: { minimum: 16 } + validate :events_known + + scope :enabled, -> { where(enabled: true) } + + def self.new_secret = SecureRandom.hex(32) + + def subscribed?(event) = events.include?(event.to_s) + + private + + def events_known + errors.add(:events, :blank) if events.blank? + errors.add(:events, :inclusion) if (Array(events) - EVENTS.keys).any? + end +end diff --git a/app/presenters/api_presenter.rb b/app/presenters/api_presenter.rb new file mode 100644 index 0000000..0f44073 --- /dev/null +++ b/app/presenters/api_presenter.rb @@ -0,0 +1,69 @@ +# What the API and webhooks send for each kind of record (docs/api.md). +# Times are ISO 8601 UTC, hours decimals, codes rather than translated labels. +module ApiPresenter + module_function + + def aircraft(a) + aw = a.airworthiness + { id: a.id, tail_number: a.tail_number, make: a.make, model: a.model, serial_number: a.serial_number, + icao_type: a.icao_type, status: a.status, + airworthiness: { status: aw.status, issues: aw.issues.map { { category: _1.category, severity: _1.severity, title: _1.title } } }, + time_basis: a.time_basis, hours: dec(a.current_hours), tach: dec(a.tach_time), hobbs: dec(a.hobbs_time), + updated_at: time(a.updated_at) } + end + + def component(c) + { id: c.id, aircraft_id: c.aircraft_id, parent_id: c.parent_component_id, type: c.component_type&.name, + manufacturer: c.manufacturer, model: c.model, serial_number: c.serial_number.presence, + location: c.install_location.presence, status: c.status, date_in_service: c.date_in_service&.iso8601, + hours_in_service: dec(c.hours_in_service), hours_since_overhaul: dec(c.hours_since_overhaul), + overhaul_date: c.overhaul_date&.iso8601, overhaul_kind: c.overhaul_kind.presence, + tbo: { hours: c.tbo_hours, days: c.tbo_days, months: c.tbo_months, on_condition: c.on_condition, critical: c.tbo_critical }.compact, + replacement: { hours: c.replacement_hours, days: c.replacement_days, months: c.replacement_months, critical: c.replacement_critical }.compact, + expires_on: c.expires_on&.iso8601, updated_at: time(c.updated_at) } + end + + def due_item(i) + { key: i.key, title: i.title, kind: i.kind, due_date: i.date.iso8601, projected: i.projected, + due_hours: dec(i.due_hours), overdue: i.overdue? } + end + + def squawk(s) + { id: s.id, aircraft_id: s.aircraft_id, component_id: s.component_id, issue_reported: s.issue_reported, + priority: s.priority, grounding: s.grounding?, deferred: s.deferred?, resolved: !!s.resolved, + resolved_at: time(s.resolved_at), notes: s.notes.presence, logbook_entry_id: s.logbook_entry_id, + reported_by: s.reported_by&.display_name, external_ref: s.external_ref, + attachments: s.attachments.map { _1.filename.to_s }, + created_at: time(s.created_at), updated_at: time(s.updated_at) } + end + + def logbook_entry(e) + sig = e.signature + { id: e.id, aircraft_id: e.aircraft_id, component_id: e.component_id, log: e.log_type, entry_type: e.entry_type, + date: e.date.iso8601, text: e.text, aircraft_hours: dec(e.aircraft_hours_at_entry), + inspection_result: e.inspection_result.presence, verified: e.verified, superseded: e.superseded_at.present?, + signed: sig.present?, signature: sig && signature(sig), + signoff: sig ? nil : { person: e.signoff_person.presence, certificate_type: e.signoff_certificate_type.presence, + certificate_number: e.signoff_certificate_number.presence }.compact.presence, + created_at: time(e.created_at), updated_at: time(e.updated_at) } + end + + def signature(sig) + { signer_name: sig.signer_name, certificate_kind: sig.certificate_kind, certificate_number: sig.certificate_number, + signed_at: time(sig.signed_at) } + end + + def inspection(row) + { inspection_type_id: row.type.id, name: row.type.name, status: row.status, next_due_date: row.next_due_date&.iso8601, + next_due_hours: dec(row.next_due_hours), last_done: row.latest&.date&.iso8601 } + end + + def ad(row) + { airworthiness_directive_id: row.ad.id, name: row.ad.name, description: row.ad.short_description.presence, + status: row.status, next_due_date: row.next_due_date&.iso8601, next_due_hours: dec(row.next_due_hours), + last_complied: row.latest&.date_complied&.iso8601 } + end + + def dec(value) = value&.to_d&.round(1)&.to_f + def time(value) = value&.utc&.iso8601 +end diff --git a/app/services/air_trail_client.rb b/app/services/air_trail_client.rb index 174ca6b..354006c 100644 --- a/app/services/air_trail_client.rb +++ b/app/services/air_trail_client.rb @@ -30,9 +30,6 @@ class AirTrailClient @allow_private = allow_private || self.class.allowed_hosts.include?(@base.host.to_s.downcase) end - # Host name → IP addresses (replaceable in tests, which have no DNS). - class_attribute :resolver, default: ->(host) { Addrinfo.getaddrinfo(host, nil, nil, :STREAM).map(&:ip_address) } - def self.allowed_hosts = ENV.fetch("AIRTRAIL_ALLOWED_HOSTS", "").split(",").map { _1.strip.downcase }.compact_blank def me = request(:get, "/api/v1/me").fetch("data") @@ -85,24 +82,13 @@ class AirTrailClient raise NetworkError, I18n.t("services.air_trail.can_t_reach_airtrail_at", host: @base.host, message: e.message) end - # The address to connect to: the host's first, once all of its addresses are - # ones this connection may reach. + # The address to connect to (see OutboundAddress). def address(host) - ips = resolver.call(host).map { IPAddr.new(_1.sub(/%.*/, "")) }.uniq - raise SocketError, "no address" if ips.empty? - ips.each do |ip| - ip = ip.native # ::ffff:10.0.0.1 → 10.0.0.1 - reason = if ip.loopback? || ip.link_local? || UNREACHABLE.any? { _1.include?(ip) } then :never - elsif (ip.private? || CGNAT.include?(ip)) && !@allow_private then :private - end - raise BlockedAddress, I18n.t("services.air_trail.blocked_#{reason}", host: host) if reason - end - ips.first.to_s + OutboundAddress.resolve!(host, allow_private: @allow_private) + rescue OutboundAddress::Blocked => e + raise BlockedAddress, I18n.t("services.air_trail.blocked_#{e.reason}", host: host) end - UNREACHABLE = [ IPAddr.new("0.0.0.0/8"), IPAddr.new("::/128"), IPAddr.new("224.0.0.0/4"), IPAddr.new("ff00::/8") ].freeze - CGNAT = IPAddr.new("100.64.0.0/10") # shared address space, e.g. Tailscale - def handle(response) status = response.code.to_i json = begin diff --git a/app/services/outbound_address.rb b/app/services/outbound_address.rb new file mode 100644 index 0000000..9a1e53a --- /dev/null +++ b/app/services/outbound_address.rb @@ -0,0 +1,34 @@ +# Checks where the server is about to send a request (AirTrail, webhooks): +# resolves the host and returns the address to connect to, so the name can't +# be pointed elsewhere in between. Never the server itself, link-local +# addresses (cloud metadata) or multicast; the private network only when +# allowed (admins, or hosts the admin listed). +module OutboundAddress + class Blocked < StandardError + attr_reader :reason # :never | :private + + def initialize(reason, host) + @reason = reason + super("#{host}: #{reason}") + end + end + + UNREACHABLE = [ IPAddr.new("0.0.0.0/8"), IPAddr.new("::/128"), IPAddr.new("224.0.0.0/4"), IPAddr.new("ff00::/8") ].freeze + CGNAT = IPAddr.new("100.64.0.0/10") # shared address space, e.g. Tailscale + + # Host name → IP addresses (replaceable in tests, which have no DNS). + mattr_accessor :resolver, default: ->(host) { Addrinfo.getaddrinfo(host, nil, nil, :STREAM).map(&:ip_address) } + + module_function + + def resolve!(host, allow_private:) + ips = resolver.call(host).map { IPAddr.new(_1.sub(/%.*/, "")) }.uniq + raise SocketError, "no address for #{host}" if ips.empty? + ips.each do |ip| + ip = ip.native # ::ffff:10.0.0.1 → 10.0.0.1 + raise Blocked.new(:never, host) if ip.loopback? || ip.link_local? || UNREACHABLE.any? { _1.include?(ip) } + raise Blocked.new(:private, host) if (ip.private? || CGNAT.include?(ip)) && !allow_private + end + ips.first.to_s + end +end diff --git a/app/services/squawk_reported.rb b/app/services/squawk_reported.rb new file mode 100644 index 0000000..c5ddfee --- /dev/null +++ b/app/services/squawk_reported.rb @@ -0,0 +1,16 @@ +# What happens when a squawk is reported, from the form or the API: the +# aircraft's activity log, and a push notification to its other people when +# it grounds the aircraft. +module SquawkReported + module_function + + def call(squawk, by:) + aircraft = squawk.aircraft + aircraft.log_event!("squawk", I18n.t("flash.squawks.squawk_reported_2", priority_label: squawk.priority_label), + user: by, notes: squawk.issue_reported.truncate(200)) + return unless squawk.grounding? + PushNotifier.notify(aircraft.users.merge(User.active).where.not(id: by&.id), :grounding_squawk, + path: Rails.application.routes.url_helpers.aircraft_squawks_path(aircraft), + tag: "squawk-#{squawk.id}", tail: aircraft.tail_number, issue: squawk.issue_reported.truncate(120)) + end +end diff --git a/app/services/webhooks.rb b/app/services/webhooks.rb new file mode 100644 index 0000000..ce68081 --- /dev/null +++ b/app/services/webhooks.rb @@ -0,0 +1,18 @@ +# Tells integrations about changes (docs/api.md, "Webhooks"): each enabled +# endpoint subscribed to the event, whose token is active and reaches the +# aircraft, gets a delivery, sent by WebhookDeliveryJob after the change is +# saved. +module Webhooks + module_function + + def publish(event, aircraft:, data:) + endpoints = WebhookEndpoint.enabled.joins(:api_token).merge(ApiToken.active).includes(:api_token) + .select { _1.subscribed?(event) && Array(_1.api_token.aircraft_ids).include?(aircraft.id) } + return if endpoints.empty? + body = { event: event, id: SecureRandom.uuid, created_at: Time.current.utc.iso8601, aircraft_id: aircraft.id, data: data }.to_json + endpoints.each do |endpoint| + delivery = endpoint.deliveries.create!(event: event, payload: body) + WebhookDeliveryJob.perform_later(delivery.id) + end + end +end diff --git a/app/views/admin/integrations/_form.html.erb b/app/views/admin/integrations/_form.html.erb new file mode 100644 index 0000000..2beba56 --- /dev/null +++ b/app/views/admin/integrations/_form.html.erb @@ -0,0 +1,32 @@ +<%= form_with model: integration, url: (integration.persisted? ? admin_integration_path(integration) : admin_integrations_path), scope: :api_token, + class: "card card-body max-w-2xl space-y-5", data: { turbo: false } do |f| %> + <%= f.errors_summary %> + <% if endpoint&.errors&.any? %>
<%= endpoint.errors.full_messages.to_sentence %>
<% end %> + <%= f.field :name, hint: t(".name_hint") %> +
+ <%= t(".scopes") %> + <% ApiToken::SCOPES.each do |key, label| %> + + <% end %> +
+
+ <%= t(".aircraft") %> +

<%= t(".aircraft_hint") %>

+ <% Aircraft.ordered.each do |a| %> + + <% end %> +
+
+ <%= t(".webhook") %> +

<%= t(".webhook_hint") %>

+ <%= url_field_tag "webhook[url]", endpoint&.url, class: "input", placeholder: "https://redmine.example.com/sam/webhook", "aria-label": t(".webhook_url") %> + <% WebhookEndpoint::EVENTS.each do |key, label| %> + + <% end %> + <% if endpoint&.persisted? %> + <%= hidden_field_tag "webhook[enabled]", "0", id: nil %> + + <% end %> +
+ <%= f.submit integration.persisted? ? t(".save") : t(".create"), class: "btn-primary" %> +<% end %> diff --git a/app/views/admin/integrations/created.html.erb b/app/views/admin/integrations/created.html.erb new file mode 100644 index 0000000..8ed14e1 --- /dev/null +++ b/app/views/admin/integrations/created.html.erb @@ -0,0 +1,15 @@ +<% content_for :title, @integration.name %> +
+

<%= @integration.name %>

+

<%= t(".copy_now") %>

+ <% if @integration.token %> + + + <% end %> + <% if @secret %> + + +

<%= t(".secret_hint") %>

+ <% end %> +

<%= link_to t(".done"), admin_integration_path(@integration), class: "btn-primary" %>

+
diff --git a/app/views/admin/integrations/edit.html.erb b/app/views/admin/integrations/edit.html.erb new file mode 100644 index 0000000..8ab9a9c --- /dev/null +++ b/app/views/admin/integrations/edit.html.erb @@ -0,0 +1,3 @@ +<% content_for :title, @integration.name %> +

<%= @integration.name %>

+<%= render "form", integration: @integration, endpoint: @endpoint %> diff --git a/app/views/admin/integrations/index.html.erb b/app/views/admin/integrations/index.html.erb new file mode 100644 index 0000000..3b17d8d --- /dev/null +++ b/app/views/admin/integrations/index.html.erb @@ -0,0 +1,17 @@ +<% content_for :title, t(".integrations") %> +

<%= t(".integrations") %>

<%= link_to t(".new_integration"), new_admin_integration_path, class: "btn-primary" %>
+

<%= t(".what_html", docs: link_to(t(".api_docs"), help_page_path("api"), class: "link")) %>

+<% if @integrations.any? %> +
+ + <% @integrations.each do |i| %> + + + + + <% end %> +
<%= t(".name") %><%= t(".aircraft") %><%= t(".webhook") %><%= t(".last_used") %>
<%= link_to i.name, admin_integration_path(i), class: "link font-medium" %> <% if i.revoked? %><%= t(".revoked") %><% end %> +
<%= i.token_hint %>…
<%= Aircraft.where(id: Array(i.aircraft_ids)).order(:tail_number).pluck(:tail_number).join(", ").presence || "—" %><%= (e = i.webhook_endpoints.first) ? e.url : "—" %><%= i.last_used_at ? t(".ago", ago: time_ago_in_words(i.last_used_at)) : t(".never") %>
+<% else %> + <%= empty_state t(".none_yet") %> +<% end %> diff --git a/app/views/admin/integrations/new.html.erb b/app/views/admin/integrations/new.html.erb new file mode 100644 index 0000000..b8ca22c --- /dev/null +++ b/app/views/admin/integrations/new.html.erb @@ -0,0 +1,3 @@ +<% content_for :title, t(".new_integration") %> +

<%= t(".new_integration") %>

+<%= render "form", integration: @integration, endpoint: @endpoint %> diff --git a/app/views/admin/integrations/show.html.erb b/app/views/admin/integrations/show.html.erb new file mode 100644 index 0000000..7c6f579 --- /dev/null +++ b/app/views/admin/integrations/show.html.erb @@ -0,0 +1,49 @@ +<% content_for :title, @integration.name %> +
+

<%= @integration.name %> <% if @integration.revoked? %><%= t(".revoked") %><% end %>

+ <% unless @integration.revoked? %> +
+ <%= link_to t(".edit"), edit_admin_integration_path(@integration), class: "btn-secondary" %> + <%= button_to t(".revoke"), admin_integration_path(@integration), method: :delete, class: "btn-danger", + form: { data: { turbo_confirm: t(".revoke_confirm", name: @integration.name) } } %> +
+ <% end %> +
+
+
+

<%= t(".token") %>

+
+
<%= t(".hint") %>
<%= @integration.token_hint %>…
+
<%= t(".scopes") %>
<%= @integration.scopes.map { ApiToken::SCOPES[_1] }.to_sentence %>
+
<%= t(".aircraft") %>
<%= Aircraft.where(id: Array(@integration.aircraft_ids)).order(:tail_number).pluck(:tail_number).join(", ").presence || "—" %>
+
<%= t(".created") %>
<%= fmt_time(@integration.created_at) %> · <%= @integration.user.display_name %>
+
<%= t(".last_used") %>
<%= @integration.last_used_at ? "#{fmt_time(@integration.last_used_at)} · #{@integration.last_used_ip}" : t(".never") %>
+
+
+
+

<%= t(".webhook") %>

+ <% if @endpoint %> +
+
<%= t(".url") %>
<%= @endpoint.url %> <% unless @endpoint.enabled %><%= t(".paused") %><% end %>
+
<%= t(".events") %>
<%= @endpoint.events.map { WebhookEndpoint::EVENTS[_1] }.to_sentence %>
+
+ <% unless @integration.revoked? %> +
<%= button_to t(".new_secret"), new_secret_admin_integration_path(@integration), class: "btn-secondary btn-sm", + form: { data: { turbo: false, turbo_confirm: t(".new_secret_confirm") } } %>
+ <% end %> + <% else %> +

<%= t(".no_webhook") %>

+ <% end %> +
+
+<% if @deliveries.any? %> +
+

<%= t(".recent_deliveries") %>

+ + <% @deliveries.each do |d| %> + + + <% end %>
<%= t(".when") %><%= t(".event") %><%= t(".result") %>
<%= fmt_time(d.created_at) %><%= d.event %> "badge-green", "failed" => "badge-red" }.fetch(d.status, "badge-gray") %>"><%= t(".status.#{d.status}") %> + <%= d.response_status %> <%= d.last_error %> <% if d.attempts > 1 %>· <%= t(".attempts", count: d.attempts) %><% end %>
+
+<% end %> diff --git a/app/views/api_tokens/created.html.erb b/app/views/api_tokens/created.html.erb new file mode 100644 index 0000000..94b4729 --- /dev/null +++ b/app/views/api_tokens/created.html.erb @@ -0,0 +1,8 @@ +<% content_for :title, t(".title") %> +
+

<%= t(".title") %>

+

<%= t(".copy_now", name: @token.name) %>

+ "> +

<%= t(".how_to_use_html") %>

+

<%= link_to t(".done"), edit_profile_path(anchor: "api"), class: "btn-primary" %>

+
diff --git a/app/views/layouts/application.html.erb b/app/views/layouts/application.html.erb index 4605eda..fbcdd9e 100644 --- a/app/views/layouts/application.html.erb +++ b/app/views/layouts/application.html.erb @@ -46,7 +46,7 @@ <%= link_to t(".help"), help_path, class: "block px-4 py-2.5 hover:bg-slate-100" %> <% if current_user.admin? %>

<%= t(".admin") %>

- <% [ [ t(".users"), admin_users_path ], [ t(".component_types"), admin_component_types_path ], [ t(".airports"), admin_airports_path ], [ t(".logbook_templates"), admin_logbook_templates_path ], [ t(".settings"), edit_admin_settings_path ], [ t(".off_site_backup"), admin_offsite_backup_path ], [ t(".recordkeeping_procedures"), admin_procedures_path ], [ t(".records_audits"), admin_audits_path ], [ t(".about"), admin_about_path ] ].each do |label, path| %> + <% [ [ t(".users"), admin_users_path ], [ t(".integrations"), admin_integrations_path ], [ t(".component_types"), admin_component_types_path ], [ t(".airports"), admin_airports_path ], [ t(".logbook_templates"), admin_logbook_templates_path ], [ t(".settings"), edit_admin_settings_path ], [ t(".off_site_backup"), admin_offsite_backup_path ], [ t(".recordkeeping_procedures"), admin_procedures_path ], [ t(".records_audits"), admin_audits_path ], [ t(".about"), admin_about_path ] ].each do |label, path| %> <%= link_to label, path, class: "block px-4 py-2.5 hover:bg-slate-100" %> <% end %> <% end %> @@ -67,7 +67,7 @@ <%= t(".admin") %>
- <% [ [ t(".users"), admin_users_path ], [ t(".component_types"), admin_component_types_path ], [ t(".airports"), admin_airports_path ], [ t(".logbook_templates"), admin_logbook_templates_path ], [ t(".settings"), edit_admin_settings_path ], [ t(".off_site_backup"), admin_offsite_backup_path ], [ t(".recordkeeping_procedures"), admin_procedures_path ], [ t(".records_audits"), admin_audits_path ], [ t(".about"), admin_about_path ] ].each do |label, path| %> + <% [ [ t(".users"), admin_users_path ], [ t(".integrations"), admin_integrations_path ], [ t(".component_types"), admin_component_types_path ], [ t(".airports"), admin_airports_path ], [ t(".logbook_templates"), admin_logbook_templates_path ], [ t(".settings"), edit_admin_settings_path ], [ t(".off_site_backup"), admin_offsite_backup_path ], [ t(".recordkeeping_procedures"), admin_procedures_path ], [ t(".records_audits"), admin_audits_path ], [ t(".about"), admin_about_path ] ].each do |label, path| %> <%= link_to label, path, class: [ "block px-4 py-2 text-sm hover:bg-slate-100", ("font-semibold text-sky-700" if current_page?(path)) ] %> <% end %>
diff --git a/app/views/profiles/edit.html.erb b/app/views/profiles/edit.html.erb index 6b5cac9..24116ab 100644 --- a/app/views/profiles/edit.html.erb +++ b/app/views/profiles/edit.html.erb @@ -136,6 +136,34 @@ +
+

<%= t(".api_tokens") %>

+

<%= t(".api_tokens_what_html", docs: link_to(t(".api_docs"), help_page_path("api"), class: "link")) %>

+ <% tokens = @user.api_tokens.personal.active.order(:created_at) %> + <% if tokens.any? %> +
    + <% tokens.each do |token| %> +
  • + <%= token.name %> <%= token.token_hint %>… + <%= token.scopes.map { ApiToken::SCOPES[_1] }.to_sentence %> · + <%= token.last_used_at ? t(".api_token_used", ago: time_ago_in_words(token.last_used_at)) : t(".api_token_unused") %> + <%= button_to t(".revoke"), api_token_path(token), method: :delete, class: "btn-secondary btn-sm", + form: { data: { turbo_confirm: t(".revoke_token", name: token.name) } } %> +
  • + <% end %> +
+ <% end %> + <%= form_with model: ApiToken.new, url: api_tokens_path, class: "mt-3 space-y-2", data: { turbo: false } do |f| %> + <%= f.text_field :name, class: "input", placeholder: t(".api_token_name"), required: true, maxlength: 80, "aria-label": t(".api_token_name") %> +
+ <% ApiToken::SCOPES.each do |key, label| %> + + <% end %> +
+ <%= f.submit t(".create_api_token"), class: "btn-secondary" %> + <% end %> +
+

<%= t(".integrations") %>

diff --git a/config/locales/en.yml b/config/locales/en.yml index 238ced6..0b51611 100644 --- a/config/locales/en.yml +++ b/config/locales/en.yml @@ -4,7 +4,26 @@ # a controller name are its views (t(".key") in the view). en: + api_tokens: + created: + title: Your new API token + copy_now: "Copy the token for %{name} now: it isn't shown again (only its first characters are kept, to tell tokens apart)." + token: API token + how_to_use_html: 'Send it with each request: Authorization: Bearer <token>. See the API reference in Help.' + done: Done labels: + api_token: + scopes: + read: Read aircraft, parts, due items, squawks and logbook entries + 'squawks:write': Report and update squawks + webhook_endpoint: + events: + squawk: + created: A squawk is reported + updated: A squawk is changed + resolved: A squawk is resolved + entry: + signed: A logbook entry is signed aircraft: statuses: AVAILABLE: Available @@ -286,6 +305,10 @@ en: signed_locked: This entry is signed, so it can't be changed. Make a correction entry instead squawk: confirm: 'Confirm: %{check}' + api_token: + attributes: + kind: + admins_only: "integration tokens can only be made by an administrator" ad_compliance: needs_owner: Must belong to an aircraft or component attributes: @@ -705,6 +728,11 @@ en: envelope_weights: Envelope weights must be more than 0 fuel_weight: Fuel weight per gallon must be between 4 and 9 lb flash: + admin_integrations: + saved: Integration saved. + revoked: "%{name} revoked: its token no longer works and its webhook is stopped." + api_tokens: + revoked: Token revoked. Programs using it can no longer connect. push_subscriptions: not_saved: "This browser's push service (%{host}) isn't one the app sends to." unknown_device: Unknown browser @@ -1180,6 +1208,69 @@ en: matches: Matches update: Update admin: + integrations: + show: + revoked: Revoked + edit: Edit + revoke: Revoke + revoke_confirm: "Revoke %{name}? Its token stops working at once and its webhook stops. This can't be undone; make a new integration to reconnect." + token: Token + hint: Starts with + scopes: May + aircraft: Aircraft + created: Created + last_used: Last used + never: never + webhook: Webhook + url: Address + paused: Paused + events: Events + new_secret: New secret + new_secret_confirm: "Make a new webhook secret? The other system needs the new one; webhooks signed with the old one will fail its check." + no_webhook: "None: the system only calls the API." + recent_deliveries: Recent webhooks + when: When + event: Event + result: Result + attempts: + one: "%{count} attempt" + other: "%{count} attempts" + status: + pending: Pending + delivered: Delivered + failed: Failed + created: + copy_now: "Copy these now: they aren't shown again." + token: API token + webhook_secret: Webhook secret + secret_hint: The other system checks each webhook with it (see the API reference). + done: Done + new: + new_integration: New integration + form: + name_hint: The system it's for, e.g. Redmine. + scopes: What it may do + aircraft: Aircraft it may reach + aircraft_hint: When it acts for a person, only those of these aircraft that person can see. + webhook: Webhook (optional) + webhook_hint: "Where to post changes. Each post is signed with a secret shown once after saving (header SAM-Signature)." + webhook_url: Webhook address + webhook_enabled: Send webhooks + save: Save + create: Create integration + index: + integrations: Integrations + new_integration: New integration + what_html: "Let another system, such as Redmine, work with the aircraft through the REST API (%{docs}). Each integration has its own token, limited to the aircraft and actions you choose; its changes name the person they're for, so the record history shows who. It can be told about changes by webhook." + api_docs: API reference + name: Name + aircraft: Aircraft + webhook: Webhook + last_used: Last used + revoked: Revoked + ago: "%{ago} ago" + never: never + none_yet: No integrations yet. about: show: about: About @@ -2471,6 +2562,7 @@ en: sign_out: Sign out layouts: application: + integrations: Integrations skip_to_content_html: simple_aircraft_manager: Simple Aircraft Manager sam: SAM @@ -2946,6 +3038,15 @@ en: subject: Reset your password profiles: edit: + revoke: Revoke + api_tokens: API tokens + api_tokens_what_html: "Keys for scripts and other programs to read your aircraft and report squawks through the REST API, acting as you (%{docs}). Treat a token like a password: anyone who has it can do what it allows." + api_docs: API reference + api_token_used: used %{ago} ago + api_token_unused: never used + revoke_token: "Revoke %{name}? Programs using it stop working." + api_token_name: Name (what it's for) + create_api_token: Create token your_profile: Your Profile account: Account email: Email diff --git a/config/recurring.yml b/config/recurring.yml index a96d1ae..2564774 100644 --- a/config/recurring.yml +++ b/config/recurring.yml @@ -18,6 +18,9 @@ production: purge_abandoned_uploads: command: "ActiveStorage::Blob.unattached.where(created_at: ..2.days.ago).find_each(&:purge_later)" schedule: every day at 4am <%= zone %> + purge_api_records: + command: "ApiIdempotencyKey.purge_old; WebhookDelivery.purge_old" + schedule: every day at 4:15am <%= zone %> dedupe_storage: command: "ActiveStorage::Blob.service.try(:sweep)" schedule: every day at 4:30am <%= zone %> diff --git a/config/routes.rb b/config/routes.rb index a2d80b4..f9e0ade 100644 --- a/config/routes.rb +++ b/config/routes.rb @@ -27,6 +27,7 @@ Rails.application.routes.draw do # Home-screen shortcuts: the form for your aircraft, or a choice of aircraft. get "go/log-flight", to: "shortcuts#log_flight", as: :log_flight_shortcut get "go/report-squawk", to: "shortcuts#report_squawk", as: :report_squawk_shortcut + resources :api_tokens, path: "profile/api_tokens", only: %i[create destroy] resources :certificates, path: "profile/certificates", controller: "user_certificates", only: %i[create update destroy] resource :air_trail_connection, path: "profile/airtrail", only: %i[show create update destroy] do post :test @@ -171,12 +172,34 @@ Rails.application.routes.draw do post "about/test_reminder", to: "about#test_reminder", as: :test_reminder post "about/check_records", to: "about#check_records", as: :check_records resources :users, except: :show + resources :integrations do + post :new_secret, on: :member + end resources :component_types, except: :show resources :airports, except: :show do collection { post :refresh } end end + # REST API (docs/api.md): bearer tokens, JSON. + namespace :api, defaults: { format: :json } do + namespace :v1 do + get "me", to: "me#show" + resources :aircraft, only: %i[index show] do + member do + get :components + get :due + get :inspections + get :ads + get :logbook_entries + end + resources :squawks, only: %i[index create] + end + get "squawks", to: "squawks#lookup" + resources :squawks, only: %i[show update] + end + end + get "up" => "rails/health#show", as: :rails_health_check get "manifest" => "rails/pwa#manifest", as: :pwa_manifest get "offline" => "offline#show", as: :offline diff --git a/db/migrate/20261115010000_create_api.rb b/db/migrate/20261115010000_create_api.rb new file mode 100644 index 0000000..a339969 --- /dev/null +++ b/db/migrate/20261115010000_create_api.rb @@ -0,0 +1,56 @@ +# The REST API (docs/api.md): tokens, webhooks, idempotent writes, and links +# from SAM records to the other system's ids ("redmine:issue:4512"). +class CreateApi < ActiveRecord::Migration[8.1] + def change + create_table :api_tokens do |t| + t.string :name, null: false + t.string :kind, null: false, default: "personal" # personal | integration + t.references :user, null: false, foreign_key: true # the owner (personal) or the admin who made it (integration) + t.string :token_digest, null: false + t.string :token_hint, null: false # the first characters, to tell tokens apart + t.json :scopes, null: false, default: [] + t.json :aircraft_ids # integration: the aircraft it may reach + t.datetime :last_used_at + t.string :last_used_ip + t.datetime :revoked_at + t.timestamps + t.index :token_digest, unique: true + end + + create_table :webhook_endpoints do |t| + t.references :api_token, null: false, foreign_key: true + t.string :url, null: false + t.text :secret, null: false + t.json :events, null: false, default: [] + t.boolean :enabled, null: false, default: true + t.timestamps + end + + create_table :webhook_deliveries do |t| + t.references :webhook_endpoint, null: false, foreign_key: true + t.string :event, null: false + t.text :payload, null: false + t.string :status, null: false, default: "pending" # pending | delivered | failed + t.integer :attempts, null: false, default: 0 + t.integer :response_status + t.string :last_error + t.datetime :delivered_at + t.timestamps + t.index [ :webhook_endpoint_id, :created_at ] + end + + create_table :api_idempotency_keys do |t| + t.references :api_token, null: false, foreign_key: true + t.string :key, null: false + t.string :request_digest, null: false + t.integer :response_status, null: false + t.text :response_body, null: false + t.datetime :created_at, null: false + t.index [ :api_token_id, :key ], unique: true + end + + add_column :squawks, :external_ref, :string + add_index :squawks, :external_ref + add_column :record_versions, :api_token_id, :integer + end +end diff --git a/db/schema.rb b/db/schema.rb index b78c23b..56b6583 100644 --- a/db/schema.rb +++ b/db/schema.rb @@ -10,7 +10,7 @@ # # It's strongly recommended that you check this file into your version control system. -ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do +ActiveRecord::Schema[8.1].define(version: 2026_11_15_010000) do create_table "active_storage_attachments", force: :cascade do |t| t.string "name", null: false t.string "record_type", null: false @@ -289,6 +289,34 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do t.index ["component_id", "airworthiness_directive_id"], name: "idx_component_ads", unique: true end + create_table "api_idempotency_keys", force: :cascade do |t| + t.integer "api_token_id", null: false + t.string "key", null: false + t.string "request_digest", null: false + t.integer "response_status", null: false + t.text "response_body", null: false + t.datetime "created_at", null: false + t.index ["api_token_id", "key"], name: "index_api_idempotency_keys_on_api_token_id_and_key", unique: true + t.index ["api_token_id"], name: "index_api_idempotency_keys_on_api_token_id" + end + + create_table "api_tokens", force: :cascade do |t| + t.string "name", null: false + t.string "kind", default: "personal", null: false + t.integer "user_id", null: false + t.string "token_digest", null: false + t.string "token_hint", null: false + t.json "scopes", default: [], null: false + t.json "aircraft_ids" + t.datetime "last_used_at" + t.string "last_used_ip" + t.datetime "revoked_at" + t.datetime "created_at", null: false + t.datetime "updated_at", null: false + t.index ["token_digest"], name: "index_api_tokens_on_token_digest", unique: true + t.index ["user_id"], name: "index_api_tokens_on_user_id" + end + create_table "app_revisions", force: :cascade do |t| t.string "revision", null: false t.datetime "built_at" @@ -347,13 +375,13 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do t.boolean "tbo_critical", default: true, null: false t.boolean "on_condition", default: false, null: false t.boolean "replacement_critical", default: false, null: false - t.boolean "replacement_from_install", default: false, null: false t.datetime "created_at", null: false t.datetime "updated_at", null: false t.date "expires_on" t.string "overhaul_kind" t.integer "replacement_months" t.integer "tbo_months" + t.boolean "replacement_from_install", default: false, null: false t.index ["aircraft_id"], name: "index_components_on_aircraft_id" t.index ["component_type_id"], name: "index_components_on_component_type_id" t.index ["parent_component_id"], name: "index_components_on_parent_component_id" @@ -719,6 +747,7 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do t.string "prev_hash" t.string "chain_hash", null: false t.datetime "created_at", null: false + t.integer "api_token_id" t.index ["aircraft_id"], name: "index_record_versions_on_aircraft_id" t.index ["item_type", "item_id"], name: "index_record_versions_on_item_type_and_item_id" end @@ -802,9 +831,11 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do t.text "deferral_notes" t.integer "logbook_entry_id" t.string "client_key" + t.string "external_ref" t.index ["aircraft_id", "client_key"], name: "index_squawks_on_aircraft_id_and_client_key", unique: true t.index ["aircraft_id"], name: "index_squawks_on_aircraft_id" t.index ["component_id"], name: "index_squawks_on_component_id" + t.index ["external_ref"], name: "index_squawks_on_external_ref" t.index ["logbook_entry_id"], name: "index_squawks_on_logbook_entry_id" t.index ["reported_by_id"], name: "index_squawks_on_reported_by_id" end @@ -843,6 +874,32 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do t.index ["sso_uid"], name: "index_users_on_sso_uid", unique: true end + create_table "webhook_deliveries", force: :cascade do |t| + t.integer "webhook_endpoint_id", null: false + t.string "event", null: false + t.text "payload", null: false + t.string "status", default: "pending", null: false + t.integer "attempts", default: 0, null: false + t.integer "response_status" + t.string "last_error" + t.datetime "delivered_at" + t.datetime "created_at", null: false + t.datetime "updated_at", null: false + t.index ["webhook_endpoint_id", "created_at"], name: "index_webhook_deliveries_on_webhook_endpoint_id_and_created_at" + t.index ["webhook_endpoint_id"], name: "index_webhook_deliveries_on_webhook_endpoint_id" + end + + create_table "webhook_endpoints", force: :cascade do |t| + t.integer "api_token_id", null: false + t.string "url", null: false + t.text "secret", null: false + t.json "events", default: [], null: false + t.boolean "enabled", default: true, null: false + t.datetime "created_at", null: false + t.datetime "updated_at", null: false + t.index ["api_token_id"], name: "index_webhook_endpoints_on_api_token_id" + end + create_table "weight_balance_records", force: :cascade do |t| t.integer "aircraft_id", null: false t.date "date", null: false @@ -884,6 +941,8 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do add_foreign_key "aircraft_roles", "users" add_foreign_key "airport_updates", "users", column: "requested_by_id", on_delete: :nullify add_foreign_key "airworthiness_directives", "documents", on_delete: :nullify + add_foreign_key "api_idempotency_keys", "api_tokens" + add_foreign_key "api_tokens", "users" add_foreign_key "audit_runs", "users", column: "performed_by_id", on_delete: :nullify add_foreign_key "components", "aircraft" add_foreign_key "components", "component_types" @@ -935,6 +994,8 @@ ActiveRecord::Schema[8.1].define(version: 2026_11_14_010000) do add_foreign_key "squawks", "logbook_entries", on_delete: :nullify add_foreign_key "squawks", "users", column: "reported_by_id", on_delete: :nullify add_foreign_key "user_certificates", "users" + add_foreign_key "webhook_deliveries", "webhook_endpoints" + add_foreign_key "webhook_endpoints", "api_tokens" add_foreign_key "weight_balance_records", "aircraft" add_foreign_key "weight_balance_records", "documents", on_delete: :nullify add_foreign_key "weight_balance_records", "major_records", on_delete: :nullify diff --git a/docs/guide/README.md b/docs/guide/README.md index 74fdd3f..1a9e34a 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -29,6 +29,7 @@ The same pages are in the app under **Help** in the menu. ## Administrators - [Administration](administration.md): users, settings, templates, backups and off-site backup to Google Drive, recordkeeping procedures and audits +- [REST API](api.md): tokens, endpoints and webhooks, for scripts and other systems such as Redmine ## Legal diff --git a/docs/guide/api.md b/docs/guide/api.md new file mode 100644 index 0000000..da2d083 --- /dev/null +++ b/docs/guide/api.md @@ -0,0 +1,125 @@ +# REST API + +Other programs can work with the aircraft through the API: a script that pulls what's coming due, or another system such as Redmine that tracks work orders. The API reads the same records you see in the app and goes through the same rules. Anything it changes is in the record history, with the person it was for. + +The API never signs a logbook entry, never changes or deletes a signed one, and never changes users, roles or the record history. Signing always happens in the app, by the person certifying the work ([Electronic records and signing](records.md)). + +## Tokens + +Each request carries a token: + +``` +Authorization: Bearer sam_… +``` + +There are two kinds: + +| Kind | Made in | Acts as | Reaches | +|---|---|---|---| +| **Personal** | Profile → API tokens | you | your aircraft, with your role | +| **Integration** | Admin → Integrations (administrators) | the person named in `SAM-On-Behalf-Of` | the aircraft chosen for it, and only those that person can also see | + +A token is shown once, when it's made; only its first characters are kept, to tell tokens apart. Revoke a token you no longer need, or one that may have been seen by someone else. Profile and Admin → Integrations show when each token was last used, and from where. + +An integration acting for someone names them by email in each request: + +``` +SAM-On-Behalf-Of: mechanic@example.com +``` + +Reading works without it (limited to the integration's aircraft). Every write needs it, so each change names a person. + +### Scopes + +| Scope | Allows | +|---|---| +| `read` | Aircraft, parts, due items, inspections, ADs, squawks and logbook entries | +| `squawks:write` | Reporting squawks and updating them | + +## Requests and answers + +- Base address: `https:///api/v1` +- JSON in and out. Times are ISO 8601 in UTC, hours are decimals, and values are codes (`ENG`, `IN-USE`) rather than translated labels. +- Lists answer `{ "data": [ … ], "next_after": 123 }`. Ask for more with `?after=123`; `?limit=` sets the page size (up to 200, default 50); `?updated_since=2026-11-01T00:00:00Z` lists only what changed since then. +- Errors answer `{ "error": { "code": "invalid", "message": "…", "fields": { "issue_reported": ["can't be blank"] } } }` with the matching HTTP status: 400 bad request, 401 no or wrong token, 403 not allowed (`missing_scope`, `owners_only`), 404 not found or not reachable with this token, 409 `idempotency_conflict`, 422 invalid, 429 too many requests (600 a minute per token). + +### Safe retries + +Send an `Idempotency-Key` header (any unique string up to 100 characters) with each write. If the answer is lost and you send the same request with the same key again, you get the first answer back (with `Idempotent-Replay: true`) instead of a second record. Keys are kept for 24 hours. The same key with a different request is refused (409). + +### Linking to the other system + +Squawks have an `external_ref`: your own id for them, such as `redmine:issue:4512`. Set it when reporting or later, and find squawks by it with `GET /squawks?external_ref=…`. The other system then doesn't need to store SAM's ids. + +## Endpoints + +| | | +|---|---| +| `GET /me` | The token, who it acts as, and the aircraft it reaches | +| `GET /aircraft` | The aircraft: tail number, make and model, status, airworthiness, hours | +| `GET /aircraft/:id` | One aircraft | +| `GET /aircraft/:id/components` | Its parts: type, serial, hours, since overhaul, TBO and replacement limits, parent part (`?all=1` includes disposed parts) | +| `GET /aircraft/:id/due` | Everything coming due, soonest first; items due by hours get a projected date | +| `GET /aircraft/:id/inspections` | Each inspection's status and next due date and hours | +| `GET /aircraft/:id/ads` | Each AD's status and next due date and hours | +| `GET /aircraft/:id/logbook_entries` | Logbook entries, with their signatures (`?log=AC`, `ENG`, `PROP` or `OTHER`; `?signed=true` or `false`) | +| `GET /aircraft/:id/squawks` | Squawks (`?status=open`, the default, or `resolved` or `all`) | +| `POST /aircraft/:id/squawks` | Report a squawk | +| `GET /squawks?external_ref=…` | Find squawks by your id for them | +| `GET /squawks/:id` | One squawk | +| `PATCH /squawks/:id` | Update a squawk | + +### Reporting a squawk + +``` +POST /api/v1/aircraft/12/squawks +Authorization: Bearer sam_… +SAM-On-Behalf-Of: pilot@example.com +Idempotency-Key: 7f9c1e2a-… +Content-Type: application/json + +{ "squawk": { "issue_reported": "Left mag drop 200 rpm", "priority": 0, "component_id": 41, "external_ref": "redmine:issue:4512" } } +``` + +`priority` is 0 (ground the aircraft), 1 (fix soon), 2 (fix at the next inspection, the default) or 3 (fix eventually). Like a squawk reported in the app, a grounding squawk notifies the aircraft's other people. Anyone who may report squawks on the aircraft can report one. + +The answer is `201` with the squawk: + +```json +{ "data": { "id": 88, "aircraft_id": 12, "component_id": 41, "issue_reported": "Left mag drop 200 rpm", "priority": 0, + "grounding": true, "deferred": false, "resolved": false, "external_ref": "redmine:issue:4512", … } } +``` + +### Updating a squawk + +`PATCH /squawks/:id` with `{ "squawk": { … } }`. Anyone who may write can set `external_ref`; changing `issue_reported`, `priority`, `component_id` or `notes` needs an owner of the aircraft, as in the app. A resolved squawk can't be changed. Squawks are resolved by a signed logbook entry, in the app. + +## Webhooks + +An integration can be told about changes. In Admin → Integrations, give it a webhook address and choose the events. SAM then posts JSON there after each change: + +| Event | When | +|---|---| +| `squawk.created` | A squawk is reported | +| `squawk.updated` | A squawk is changed | +| `squawk.resolved` | A squawk is resolved | +| `entry.signed` | A logbook entry is signed | + +Only events on the integration's aircraft are sent. The body: + +```json +{ "event": "squawk.created", "id": "6c1f…", "created_at": "2026-11-20T15:04:05Z", "aircraft_id": 12, + "data": { …the squawk, as the API returns it… } } +``` + +With the headers `SAM-Event`, `SAM-Delivery` (a number, the same on every retry) and `SAM-Signature: t=,v1=`. Check each post before trusting it: compute the HMAC-SHA256 of `.` with the webhook secret (shown once when the webhook is set up; Admin → Integrations → New secret makes another) and compare it with `v1`. Reject posts whose `t` is more than a few minutes old. + +```ruby +t, v1 = request.headers["SAM-Signature"].scan(/t=(\d+),v1=(\h+)/).first +expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{t}.#{request.raw_post}") +valid = ActiveSupport::SecurityUtils.secure_compare(expected, v1.to_s) && (Time.now.to_i - t.to_i).abs < 300 +``` + +Answer any 2xx status to accept it. Anything else, or no answer within 10 seconds, is retried with growing waits (8 tries over about a day), then marked failed. Admin → Integrations lists recent webhooks and what the other system answered. The same event may arrive more than once; use `SAM-Delivery` or the event's `id` to ignore repeats. + +A webhook address may be on your private network (where Redmine often runs), but never the server itself or a link-local address. diff --git a/test/integration/api_management_test.rb b/test/integration/api_management_test.rb new file mode 100644 index 0000000..f70589b --- /dev/null +++ b/test/integration/api_management_test.rb @@ -0,0 +1,103 @@ +require "test_helper" + +# Making and revoking API tokens: personal ones on Profile, integrations +# (with their webhooks) under Admin. +class ApiManagementTest < ActionDispatch::IntegrationTest + setup do + @admin = create_user("admin@example.com", admin: true) + @pilot = create_user("pilot@example.com") + @a = create_aircraft(owner: @admin, pilot: @pilot, tail_number: "N12345") + end + + test "a personal token is shown once, listed by its first characters, and can be revoked" do + sign_in @pilot + get edit_profile_path + assert_select "#api form[action='#{api_tokens_path}']" + post api_tokens_path, params: { api_token: { name: "My script", scopes: %w[read squawks:write bogus] } } + assert_response :success + token = @pilot.api_tokens.last + shown = css_select("input[readonly]").first["value"] + assert_equal token, ApiToken.authenticate(shown) + assert_equal %w[read squawks:write], token.scopes + + get edit_profile_path + assert_select "#api", text: /My script/ + assert_no_match shown, response.body, "not shown again" + delete api_token_path(token) + assert token.reload.revoked? + assert_nil ApiToken.authenticate(shown) + end + + test "you can't revoke someone else's token" do + other = ApiToken.create!(name: "theirs", kind: "personal", user: @admin, scopes: %w[read]) + sign_in @pilot + delete api_token_path(other) + assert_response :not_found + assert_not other.reload.revoked? + end + + test "an admin makes an integration with a webhook; the token and secret are shown once" do + sign_in @admin + get admin_integrations_path + assert_response :success + post admin_integrations_path, params: { api_token: { name: "Redmine", scopes: %w[read squawks:write], aircraft_ids: [ @a.id ] }, + webhook: { url: "https://redmine.example.com/sam", events: %w[squawk.created entry.signed] } } + assert_response :success + integration = ApiToken.integration.last + assert_equal [ "Redmine", [ @a.id ], @admin ], [ integration.name, integration.aircraft_ids, integration.user ] + token, secret = css_select("input[readonly]").map { _1["value"] } + assert_equal integration, ApiToken.authenticate(token) + endpoint = integration.webhook_endpoints.sole + assert_equal [ secret, %w[squawk.created entry.signed] ], [ endpoint.secret, endpoint.events ] + + get admin_integration_path(integration) + assert_response :success + assert_no_match token, response.body + assert_no_match secret, response.body + end + + test "editing an integration changes its reach and webhook; a new secret replaces the old" do + integration = ApiToken.create!(name: "Redmine", kind: "integration", user: @admin, scopes: %w[read], aircraft_ids: []) + sign_in @admin + patch admin_integration_path(integration), params: { api_token: { name: "Redmine", scopes: %w[read], aircraft_ids: [ @a.id ] }, + webhook: { url: "https://redmine.example.com/sam", events: %w[squawk.resolved] } } + assert_redirected_to admin_integration_path(integration) + assert_equal [ @a.id ], integration.reload.aircraft_ids + old = integration.webhook_endpoints.sole.secret + post new_secret_admin_integration_path(integration) + assert_not_equal old, integration.webhook_endpoints.sole.reload.secret + patch admin_integration_path(integration), params: { api_token: { name: "Redmine", scopes: %w[read], aircraft_ids: [ @a.id ] }, webhook: { url: "" } } + assert_empty integration.webhook_endpoints.reload, "clearing the address removes the webhook" + end + + test "an invalid integration shows the form again" do + sign_in @admin + post admin_integrations_path, params: { api_token: { name: "", scopes: [] }, webhook: { url: "not a url", events: [] } } + assert_response :unprocessable_entity + assert_equal 0, ApiToken.count + end + + test "revoking an integration stops its token and webhook" do + integration = ApiToken.create!(name: "Redmine", kind: "integration", user: @admin, scopes: %w[read], aircraft_ids: [ @a.id ]) + endpoint = integration.webhook_endpoints.create!(url: "https://redmine.example.com/", secret: "s" * 32, events: %w[squawk.created]) + sign_in @admin + delete admin_integration_path(integration) + assert integration.reload.revoked? + assert_not endpoint.reload.enabled + end + + test "integrations are for admins only" do + sign_in @pilot + get admin_integrations_path + assert_redirected_to root_path + post admin_integrations_path, params: { api_token: { name: "x", scopes: %w[read] } } + assert_equal 0, ApiToken.count + end + + test "the API reference is in the user guide" do + sign_in @pilot + get help_page_path("api") + assert_response :success + assert_select "h1", "REST API" + end +end diff --git a/test/integration/api_test.rb b/test/integration/api_test.rb new file mode 100644 index 0000000..47d918d --- /dev/null +++ b/test/integration/api_test.rb @@ -0,0 +1,198 @@ +require "test_helper" + +# The REST API (docs/api.md): tokens, what each kind may reach, the read +# endpoints, squawk writes, idempotent retries and webhooks. +class ApiTest < ActionDispatch::IntegrationTest + setup do + @admin = create_user("admin@example.com", admin: true) + @owner = create_user("owner@example.com") + @pilot = create_user("pilot@example.com") + @outsider = create_user("outsider@example.com") + @a = create_aircraft(owner: @owner, pilot: @pilot, tail_number: "N12345") + @other = create_aircraft(owner: @outsider, tail_number: "N99999") + end + + test "no token, a wrong one or a revoked one is refused" do + get "/api/v1/me" + assert_response :unauthorized + get "/api/v1/me", headers: bearer("sam_nope") + assert_response :unauthorized + token = personal(@pilot) + token.revoke! + get "/api/v1/me", headers: bearer(token.token) + assert_response :unauthorized + end + + test "a personal token acts as its owner and reaches exactly their aircraft" do + token = personal(@pilot) + get "/api/v1/me", headers: bearer(token.token) + assert_response :success + assert_equal "pilot@example.com", body.dig("data", "acting_as", "email") + get "/api/v1/aircraft", headers: bearer(token.token) + assert_equal [ "N12345" ], body["data"].map { _1["tail_number"] } + get "/api/v1/aircraft/#{@other.id}", headers: bearer(token.token) + assert_response :not_found + assert token.reload.last_used_at, "last use is recorded" + end + + test "a disabled user's token stops working" do + token = personal(@pilot) + @pilot.update_column(:disabled_at, Time.current) + get "/api/v1/me", headers: bearer(token.token) + assert_response :unauthorized + end + + test "an integration reaches only its aircraft, narrowed to the person it acts for" do + token = integration(aircraft: [ @a, @other ]) + get "/api/v1/aircraft", headers: bearer(token.token) + assert_equal %w[N12345 N99999], body["data"].map { _1["tail_number"] }.sort + get "/api/v1/aircraft", headers: bearer(token.token, as: @pilot) + assert_equal [ "N12345" ], body["data"].map { _1["tail_number"] } + get "/api/v1/aircraft", headers: bearer(token.token, as: "nobody@example.com") + assert_response :unprocessable_entity + assert_equal "unknown_user", body.dig("error", "code") + assert_raises(ActiveRecord::RecordInvalid) { ApiToken.create!(name: "x", kind: "integration", user: @owner, scopes: %w[read]) } + end + + test "the read endpoints describe the aircraft, its parts, what's due, squawks and entries" do + engine = @a.components.create!(component_type: ComponentType.create!(name: "Engine"), manufacturer: "Lycoming", model: "O-320", + serial_number: "L-1", date_in_service: Date.new(2020, 1, 1), hours_in_service: 100, tbo_hours: 2000) + @a.squawks.create!(issue_reported: "Left brake soft", priority: 1, reported_by: @pilot, external_ref: "redmine:issue:1") + @a.logbook_entries.create!(date: Date.current, log_type: "ENG", entry_type: "MAINTENANCE", text: "Oil changed") + h = bearer(personal(@owner).token) + + get "/api/v1/aircraft/#{@a.id}", headers: h + assert_equal "N12345", body.dig("data", "tail_number") + assert body.dig("data", "airworthiness", "status") + get "/api/v1/aircraft/#{@a.id}/components", headers: h + assert_equal [ [ engine.id, "Engine", "L-1", 2000 ] ], body["data"].map { [ _1["id"], _1["type"], _1["serial_number"], _1.dig("tbo", "hours") ] } + get "/api/v1/aircraft/#{@a.id}/due", headers: h + assert_kind_of Array, body["data"] + get "/api/v1/aircraft/#{@a.id}/squawks", headers: h + assert_equal [ "Left brake soft" ], body["data"].map { _1["issue_reported"] } + get "/api/v1/squawks", params: { external_ref: "redmine:issue:1" }, headers: h + assert_equal 1, body["data"].size + get "/api/v1/aircraft/#{@a.id}/logbook_entries", params: { log: "ENG" }, headers: h + assert_equal [ [ "Oil changed", false ] ], body["data"].map { [ _1["text"], _1["signed"] ] } + get "/api/v1/aircraft/#{@a.id}/inspections", headers: h + assert_response :success + get "/api/v1/aircraft/#{@a.id}/ads", headers: h + assert_response :success + end + + test "lists page with after and limit" do + 5.times { |i| @a.squawks.create!(issue_reported: "Issue #{i}", priority: 2) } + h = bearer(personal(@owner).token) + get "/api/v1/aircraft/#{@a.id}/squawks", params: { limit: 2 }, headers: h + first = body + assert_equal 2, first["data"].size + get "/api/v1/aircraft/#{@a.id}/squawks", params: { limit: 2, after: first["next_after"] }, headers: h + assert_equal 2, body["data"].size + assert_empty first["data"].map { _1["id"] } & body["data"].map { _1["id"] } + end + + test "a pilot can report a squawk; it's announced and attributed to them, via the token" do + token = personal(@pilot) + post "/api/v1/aircraft/#{@a.id}/squawks", params: { squawk: { issue_reported: "Mag drop 200 rpm", priority: 0, external_ref: "redmine:issue:9" } }, + headers: bearer(token.token), as: :json + assert_response :created + squawk = Squawk.find(body.dig("data", "id")) + assert_equal [ @pilot, true, "redmine:issue:9" ], [ squawk.reported_by, squawk.grounding?, squawk.external_ref ] + version = squawk.versions.last + assert_equal [ @pilot.id, token.id ], [ version.user_id, version.api_token_id ] + assert_equal token.id, JSON.parse(version.payload)["api_token_id"], "in the hashed payload" + assert @a.events.exists?(category: "squawk") + end + + test "integration writes must say who they're for, and need the write scope" do + reader = integration(aircraft: [ @a ], scopes: %w[read]) + writer = integration(aircraft: [ @a ], scopes: %w[read squawks:write]) + params = { squawk: { issue_reported: "Oil leak" } } + post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: bearer(writer.token), as: :json + assert_equal "on_behalf_of_required", body.dig("error", "code") + post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: bearer(reader.token, as: @pilot), as: :json + assert_equal "missing_scope", body.dig("error", "code") + post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: bearer(writer.token, as: @outsider), as: :json + assert_response :not_found, "the person must have access to the aircraft" + post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: bearer(writer.token, as: @pilot), as: :json + assert_response :created + end + + test "only owners change a squawk's details; anyone who may write can set its external_ref" do + squawk = @a.squawks.create!(issue_reported: "Light out", priority: 2) + pilot_h = bearer(personal(@pilot).token) + patch "/api/v1/squawks/#{squawk.id}", params: { squawk: { priority: 0 } }, headers: pilot_h, as: :json + assert_response :forbidden + patch "/api/v1/squawks/#{squawk.id}", params: { squawk: { external_ref: "redmine:issue:7" } }, headers: pilot_h, as: :json + assert_response :success + patch "/api/v1/squawks/#{squawk.id}", params: { squawk: { priority: 1, notes: "Bulb ordered" } }, headers: bearer(personal(@owner).token), as: :json + assert_equal [ 1, "Bulb ordered", "redmine:issue:7" ], squawk.reload.then { [ _1.priority, _1.notes, _1.external_ref ] } + end + + test "a retry with the same Idempotency-Key gets the first answer, not a second squawk" do + h = bearer(personal(@pilot).token).merge("Idempotency-Key" => "abc-123") + params = { squawk: { issue_reported: "Door seal torn" } } + post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: h, as: :json + first = body.dig("data", "id") + post "/api/v1/aircraft/#{@a.id}/squawks", params: params, headers: h, as: :json + assert_equal [ first, "true" ], [ body.dig("data", "id"), response.headers["Idempotent-Replay"] ] + assert_equal 1, @a.squawks.count + post "/api/v1/aircraft/#{@a.id}/squawks", params: { squawk: { issue_reported: "Different" } }, headers: h, as: :json + assert_response :conflict + end + + test "errors are JSON with the fields at fault" do + post "/api/v1/aircraft/#{@a.id}/squawks", params: { squawk: { issue_reported: "" } }, headers: bearer(personal(@pilot).token), as: :json + assert_response :unprocessable_entity + assert_equal "invalid", body.dig("error", "code") + assert body.dig("error", "fields", "issue_reported") + post "/api/v1/aircraft/#{@a.id}/squawks", params: "{not json", headers: bearer(personal(@pilot).token).merge("Content-Type" => "application/json") + assert_response :bad_request + end + + test "webhooks go to integrations that reach the aircraft, signed with their secret" do + token = integration(aircraft: [ @a ]) + endpoint = token.webhook_endpoints.create!(url: "https://hooks.example.com/sam", secret: "s" * 32, events: %w[squawk.created squawk.resolved]) + other = integration(aircraft: [ @other ]).webhook_endpoints.create!(url: "https://elsewhere.example.com/", secret: "t" * 32, events: %w[squawk.created]) + stub_request(:post, "https://hooks.example.com/sam").to_return(status: 204) + + perform_enqueued_jobs { @a.squawks.create!(issue_reported: "Prop nick", priority: 1) } + assert_requested(:post, "https://hooks.example.com/sam") do |req| + t, sig = req.headers["Sam-Signature"].scan(/t=(\d+),v1=(\h+)/).first + sig == OpenSSL::HMAC.hexdigest("SHA256", "s" * 32, "#{t}.#{req.body}") && JSON.parse(req.body)["event"] == "squawk.created" + end + assert_equal [ "delivered", 204 ], endpoint.deliveries.last.then { [ _1.status, _1.response_status ] } + assert_empty other.deliveries, "not for an integration that doesn't reach the aircraft" + end + + test "a failing webhook is retried, then marked failed" do + endpoint = integration(aircraft: [ @a ]).webhook_endpoints.create!(url: "https://hooks.example.com/sam", secret: "s" * 32, events: %w[squawk.created]) + stub_request(:post, "https://hooks.example.com/sam").to_return(status: 500) + perform_enqueued_jobs { @a.squawks.create!(issue_reported: "Tire worn", priority: 2) } + delivery = endpoint.deliveries.last + assert_equal [ "failed", WebhookDeliveryJob::ATTEMPTS ], [ delivery.status, delivery.attempts ] + end + + test "a webhook pointed at the server itself is never sent" do + endpoint = integration(aircraft: [ @a ]).webhook_endpoints.create!(url: "http://127.0.0.1:3000/hook", secret: "s" * 32, events: %w[squawk.created]) + perform_enqueued_jobs { @a.squawks.create!(issue_reported: "Seat rail", priority: 2) } + assert_equal "failed", endpoint.deliveries.last.status + assert_not_requested :post, "http://127.0.0.1:3000/hook" + end + + private + + def personal(user) = ApiToken.create!(name: "script", kind: "personal", user: user, scopes: %w[read squawks:write]) + + def integration(aircraft:, scopes: %w[read squawks:write]) + ApiToken.create!(name: "Redmine", kind: "integration", user: @admin, scopes: scopes, aircraft_ids: aircraft.map(&:id)) + end + + def bearer(token, as: nil) + { "Authorization" => "Bearer #{token}" }.tap do |h| + h["SAM-On-Behalf-Of"] = as.respond_to?(:email_address) ? as.email_address : as if as + end + end + + def body = JSON.parse(response.body) +end diff --git a/test/integration/internet_exposure_test.rb b/test/integration/internet_exposure_test.rb index ab181bc..954279d 100644 --- a/test/integration/internet_exposure_test.rb +++ b/test/integration/internet_exposure_test.rb @@ -57,11 +57,11 @@ class InternetExposureTest < ActionDispatch::IntegrationTest private def resolving_to(*ips) - old = AirTrailClient.resolver - AirTrailClient.resolver = ->(_) { ips } + old = OutboundAddress.resolver + OutboundAddress.resolver = ->(_) { ips } yield ensure - AirTrailClient.resolver = old + OutboundAddress.resolver = old end def with_env(vars) diff --git a/test/test_helper.rb b/test/test_helper.rb index c1b1ba6..94f7977 100644 --- a/test/test_helper.rb +++ b/test/test_helper.rb @@ -6,7 +6,7 @@ WebMock.disable_net_connect!(allow_localhost: true) Dir[File.expand_path("support/**/*.rb", __dir__)].each { require _1 } PwnedPasswords.checker = ->(password) { password == "breached-password-1" } # no network in tests # No DNS in tests: names resolve to a public address, IP addresses to themselves. -AirTrailClient.resolver = ->(host) { host.match?(/\A[\d.]+\z|:/) ? [ host.delete("[]") ] : [ "203.0.113.10" ] } +OutboundAddress.resolver = ->(host) { host.match?(/\A[\d.]+\z|:/) ? [ host.delete("[]") ] : [ "203.0.113.10" ] } module ActiveSupport class TestCase