foobara-aws 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4de7e0012dfa7d11c92054cd25827b8b7f2e0864bf779027fe8c35a754c423e
-  data.tar.gz: b5009b5e2c62ba0db20ba010ad3580afec5c0524733fd8a8aa09f9a0afa8e475
+  metadata.gz: 4d08fb1f5a14798c744facb5a4f0a3986b544482f486b3962b90d8248b20bfab
+  data.tar.gz: 568943fcb7e647eb2fd620b0430076a173065bc8760ce8c0d6ec7cc7f89a8017
 SHA512:
-  metadata.gz: cb24ae7b484641d23c71c27ff59743ff1a2ac60eb0eea8c672da9c7177d05083cecfc535b47e722c09f995ca70fd9c8b32ea74ca1c5b6e2f2b0767ee9d58eedd
-  data.tar.gz: 87c12595977a88553fc092c6aa050dd22dcb25d433e5593d5b0594958b0e16cd42e47ae6553fcec8957089a8aeab68e620b251974a8e2da4bd38a65115793a29
+  metadata.gz: aae339846f621a18ccb328143d5543aa6b3cc42ab8e0f8429cbb8c2f69c156bf7000286fa6e3fa488a838cec557244581de972229320f38c5ea6d9cd28123f00
+  data.tar.gz: d02982c0c6f67749b548f411f246f614778f59af62043bd529f4227006ed83b06c9302af32271e388b60a90866be94104947859cc4a066f442a7dc28960745b5

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-04
+
+- `Foobara::AWS::Check` — checks a DEPLOYED API against the plan it was deployed from. It asserts the few things
+  that are true of every Foobara deployment and that an application's own tests structurally cannot see, because
+  they live at the edge: a public command is reachable without credentials, a gated one is refused without them
+  and with an invalid token, and a refusal is JSON rather than an HTML page with a 200 on it.
+- Gated commands are only ever called WITHOUT credentials, so they are refused before executing and nothing is
+  written. Public commands are executed with empty inputs; `skip:` is there for when that is not wanted. A 422 is
+  treated as success — the question is whether the request reached the command, not whether it liked the inputs.
+
 ## [0.1.0] - 2026-08-04
 
 - Initial release. Renamed from foobara-cdk before publishing: half of it is runtime code that loads inside a

data/README.md

@@ -151,6 +151,36 @@ Two things it handles that are easy to get wrong:
   and the load path rewritten. (Use `mounts:` so the build container can see
   them in the first place.)
 
+## Checking a deployment
+
+```ruby
+result = Foobara::AWS::Check.new(url: "https://api.example.com", plan: plan).run
+puts result.report
+exit 1 unless result.ok?
+```
+
+Driven by the plan, so it knows which commands are public without being told. It
+asserts the few things true of every Foobara deployment that an application's own
+tests structurally cannot see, because they live at the edge:
+
+- a public command is reachable **without** credentials
+- a gated command is refused without them, and with an invalid token
+- a refusal is JSON, not an HTML page with a 200 on it
+
+Each has a specific failure behind it. A public command that 401s usually means
+the authorizer declared an identity source, so API Gateway answered before the
+authorizer ran — silent, because the function was never invoked and logged
+nothing. A refusal arriving as `200 text/html` usually means a SPA history
+fallback is rewriting the API's errors, which turns every client-side error check
+into a lie. Both are real, both shipped, and both passed a full green test suite.
+
+Every request carries `{}`, so a command with required inputs answers 422 — which
+counts as success, since the question is whether the request reached the command.
+Gated commands are therefore only ever called **without** credentials: they are
+refused before executing and nothing is written. Public commands are executed
+with empty inputs, which is safe for the usual case of a read; `skip:` is there
+for when it is not.
+
 ## What it does not do
 
 - **Create tables, buckets or queues.** Those are the application's, not the

data/lib/foobara/aws/check.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "error"
+require_relative "plan"
+
+module Foobara
+  module AWS
+    # Checks a DEPLOYED API against the plan it was deployed from.
+    #
+    #   result = Foobara::AWS::Check.new(url: "https://api.example.com", plan: plan).run
+    #   puts result.report
+    #   exit 1 unless result.ok?
+    #
+    # Not a substitute for the application's own tests. It asserts the handful of
+    # things that are true of every Foobara deployment and that unit tests
+    # structurally cannot see, because they live at the edge:
+    #
+    #   * a public command is reachable WITHOUT credentials
+    #   * a command requiring authentication is refused without them
+    #   * a refusal is a refusal, not an HTML page with a 200 on it
+    #
+    # Each of those has a specific failure behind it. A public command that 401s
+    # usually means the authorizer declared an identity source, so API Gateway
+    # answered before the authorizer ran — silent, because the function was never
+    # invoked and logged nothing. A refusal arriving as `200 text/html` usually
+    # means a SPA history fallback is rewriting the API's errors, which turns
+    # every client error check into a lie.
+    #
+    # WHAT IT SENDS. Every request carries `{}` as its body, so a command that
+    # requires inputs answers 422. That is treated as SUCCESS: the point is
+    # whether the request reached the command at all, not whether it liked the
+    # inputs. It also means gated commands are only ever called WITHOUT
+    # credentials, so they are refused before executing and nothing is written.
+    #
+    # Public commands ARE executed, with empty inputs. That is safe for the usual
+    # case — a command reachable anonymously is nearly always a read — but it is
+    # the caller's judgement, and `skip:` exists for when it is not.
+    class Check
+      # Anything at all, as long as it is not a refusal and not HTML.
+      REFUSALS = [401, 403].freeze
+
+      Finding = Data.define(:command, :description, :expected, :actual, :ok) do
+        def to_s
+          "#{ok ? "ok  " : "FAIL"} #{command.ljust(28)} #{description} (expected #{expected}, got #{actual})"
+        end
+      end
+
+      Result = Data.define(:findings) do
+        def ok? = findings.all?(&:ok)
+        def failures = findings.reject(&:ok)
+
+        def report
+          summary = "#{findings.count(&:ok)}/#{findings.length} checks passed"
+          ([summary] + findings.map(&:to_s)).join("\n")
+        end
+      end
+
+      # +http+ is injectable so this can be tested without a network, and so a
+      # caller can supply its own client (a proxy, a custom CA, an SSM-fetched
+      # token). It receives (url, body_hash, headers) and returns
+      # [status, content_type, body_string].
+      def initialize(url:, plan:, skip: [], invalid_token: "not.a.token", http: nil)
+        @url = url.to_s.chomp("/")
+        @plan = plan
+        @skip = Array(skip).map(&:to_s)
+        @invalid_token = invalid_token
+        @http = http || method(:request)
+      end
+
+      def run
+        Result.new(findings: @plan.units.flat_map { |unit| check_unit(unit) })
+      end
+
+      private
+
+      def check_unit(unit)
+        unit.commands.reject { |c| @skip.include?(c) }.flat_map do |command|
+          if unit.public_commands.include?(command)
+            check_public(command)
+          else
+            check_gated(command)
+          end
+        end
+      end
+
+      # Reachable without credentials, and answering as an API rather than as a
+      # web page.
+      def check_public(command)
+        status, content_type, = call(command)
+
+        [
+          finding(command, "reachable anonymously", "not #{REFUSALS.join("/")}", status,
+                  !REFUSALS.include?(status)),
+          finding(command, "answers as an API", "json", content_type, json?(content_type))
+        ]
+      end
+
+      # Refused without credentials, and refused with a token that does not
+      # verify — the second catches an authorizer that accepts anything, which
+      # the first cannot distinguish from one that is never invoked.
+      def check_gated(command)
+        anonymous, anonymous_type, = call(command)
+        forged, forged_type, = call(command, token: @invalid_token)
+
+        [
+          finding(command, "refused anonymously", REFUSALS.join("/"), anonymous,
+                  REFUSALS.include?(anonymous)),
+          finding(command, "refusal is not a web page", "json", anonymous_type, json?(anonymous_type)),
+          finding(command, "refused with an invalid token", REFUSALS.join("/"), forged,
+                  REFUSALS.include?(forged)),
+          finding(command, "invalid-token refusal is not a web page", "json", forged_type,
+                  json?(forged_type))
+        ]
+      end
+
+      def finding(command, description, expected, actual, passed)
+        Finding.new(command: command, description: description, expected: expected,
+                    actual: actual.to_s, ok: passed)
+      end
+
+      # A 200 serving text/html is the CloudFront-rewrite failure, and it is worth
+      # naming rather than reporting as an unexpected status.
+      def json?(content_type) = content_type.to_s.include?("json")
+
+      def call(command, token: nil)
+        path = command.split("::").join("/")
+        headers = { "Content-Type" => "application/json" }
+        headers["Authorization"] = "Bearer #{token}" if token
+
+        @http.call("#{@url}#{@plan.mount}/#{path}", {}, headers)
+      rescue StandardError => e
+        # A connection failure is a check failure, not a crash: reporting it
+        # alongside the others is more useful than aborting the run, and it
+        # applies to an injected client as much as to the default one.
+        [0, "error: #{e.class}", e.message]
+      end
+
+      def request(url, body, headers)
+        uri = URI(url)
+        request = Net::HTTP::Post.new(uri)
+        headers.each { |k, v| request[k] = v }
+        request.body = JSON.dump(body)
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.request(request)
+        end
+
+        [response.code.to_i, response["content-type"], response.body]
+      end
+    end
+  end
+end

data/lib/foobara/aws/version.rb

@@ -2,6 +2,6 @@
 
 module Foobara
   module AWS
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/foobara/aws.rb

@@ -27,4 +27,5 @@ end
 
 require_relative "aws/lambda"
 require_relative "aws/plan"
+require_relative "aws/check"
 require_relative "aws/cdk/service"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foobara-aws
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Omar Qureshi
@@ -26,6 +26,7 @@ files:
 - lib/foobara/aws.rb
 - lib/foobara/aws/authorizer.rb
 - lib/foobara/aws/cdk/service.rb
+- lib/foobara/aws/check.rb
 - lib/foobara/aws/error.rb
 - lib/foobara/aws/handler.rb
 - lib/foobara/aws/lambda.rb