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:
rickyandClaude Opus 5.5 committed 2026-11-14 19:05:10 -05:00
1 parent ec0f43019f
commit bffdea937c
45 files changed
+1577 -51

No files matched your search

+103
View File
@@ -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
+198
View File
@@ -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
+3 -3
View File
@@ -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)
+1 -1
View File
@@ -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