mirror of
https://github.com/rickbarrette/simple-aircraft-manager-rails.git
synced 2026-11-17 15:50:36 -05:00
REST API v1: tokens, read endpoints, squawks, webhooks
- Personal tokens (Profile → API tokens) act as their owner; integration tokens (Admin → Integrations) reach chosen aircraft and scopes, and their writes name the person they're for (SAM-On-Behalf-Of). Tokens are stored hashed, shown once, revocable, with last use recorded. - GET aircraft, components, due list, inspections, ADs, logbook entries and squawks; POST/PATCH squawks with external_ref links to the other system. - Idempotency-Key for safe retries, paging, JSON errors, rate limits. - Record history keeps the token with each change (in the hashed payload). - Webhooks (squawk created/updated/resolved, entry signed), HMAC-signed, retried, never sent to the server itself; deliveries listed for admins. - The outbound address check is shared by AirTrail and webhooks; reporting a squawk is announced the same way from the form and the API. - docs/guide/api.md: the API reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
ec0f43019f
commit
bffdea937c
45 files changed
+1577
-51
No files matched your search
@@ -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
|
||||
@@ -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
|
||||
@@ -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: <email>" (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=<id> to continue, ?updated_since=<ISO time>.
|
||||
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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user