foobara-aws 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4de7e0012dfa7d11c92054cd25827b8b7f2e0864bf779027fe8c35a754c423e
+  data.tar.gz: b5009b5e2c62ba0db20ba010ad3580afec5c0524733fd8a8aa09f9a0afa8e475
+SHA512:
+  metadata.gz: cb24ae7b484641d23c71c27ff59743ff1a2ac60eb0eea8c672da9c7177d05083cecfc535b47e722c09f995ca70fd9c8b32ea74ca1c5b6e2f2b0767ee9d58eedd
+  data.tar.gz: 87c12595977a88553fc092c6aa050dd22dcb25d433e5593d5b0594958b0e16cd42e47ae6553fcec8957089a8aeab68e620b251974a8e2da4bd38a65115793a29

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-08-04
+
+- Initial release. Renamed from foobara-cdk before publishing: half of it is runtime code that loads inside a
+  Lambda, where "cdk" in the namespace would be a lie and CDK on the load path would be cold-start cost for nothing.
+- `Foobara::AWS::Handler` — API Gateway v2 to Rack, with identity taken from the authorizer's verified claims.
+  Owns `Foobara::AWS.current_caller`, which is the answer to "who is calling?" for a command that is public and
+  viewer-aware — something Foobara's `requires_authentication` cannot express.
+- `Foobara::AWS::Authorizer` — an optional-auth REQUEST authorizer. Verifies a token when one is present, lets
+  anonymous callers through on the commands the manifest says are public, and refuses everything else.
+- `Foobara::AWS::Packager` — one artifact per unit: sources, a generated handler, and a standalone gem bundle
+  built in a Lambda-like container. Units whose gemfiles resolve identically share one bundle build; gems declared
+  by `path:` are copied in and their load paths rewritten, since bundler writes those relative to the bundle and
+  they would not survive being copied into an artifact.
+- `Service` gained `tracing:` and `log_retention:`. `tracing: :active` is the cold-start measure worth having:
+  X-Ray splits a cold invocation into an Initialization subsegment and the handler's own work.
+- Per-command units are closed over `depends_on`, transitively and cycle-safely.
+- `Foobara::AWS.plan(manifest)` — reads a Foobara manifest into a deployment plan: one unit per domain
+  (or organization, or command), its route, and which of its commands are callable without authentication.
+  Plain data; needs neither aws-cdk-lib nor Foobara itself.
+- `Plan#to_h` / `Plan.load` — the plan survives JSON, so it can be produced at build time where the app is and
+  consumed at synth time where the infrastructure is.
+- `Foobara::AWS::CDK::Service` — synthesises the plan into one Lambda per unit behind an HTTP API, with greedy routes
+  and an optional REQUEST authorizer. Raises if a unit's artifact is missing rather than deploying a route to
+  nothing.
+- `Foobara::AWS::Lambda` — `aws_lambda memory:/vcpu:/timeout:` on a command, carried through the manifest.
+  The one deployment fact a manifest cannot otherwise supply. `vcpu:` resolves to memory, since Lambda allocates
+  CPU in proportion to it.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Omar Qureshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# foobara-aws
+
+Deploy [Foobara](https://github.com/foobara) commands to AWS Lambda, with the
+topology read out of the manifest instead of restated in infrastructure code.
+
+`connect(Posts)` already says what a deployment unit is. The manifest already
+says which commands it holds, where they are served, and which need
+authentication. This reads that and builds the AWS resources.
+
+```ruby
+plan = Foobara::AWS.plan(JSON.parse(File.read("build/plan.json")))
+
+service = Foobara::AWS::CDK::Service.new(self, "Api", plan: plan, code_root: "build")
+
+posts_table.grant_read_write_data(service.function("posts"))
+```
+
+## Two halves, on purpose
+
+```ruby
+Foobara::AWS.plan(manifest)   # what to deploy. Plain data. No CDK, no Foobara.
+Foobara::AWS::CDK::Service.new     # the AWS resources. No application.
+```
+
+They are separable because they usually run in different places. The plan is
+produced where the app is — a running connector serves `/manifest` — and
+consumed where the infrastructure is, which is often a CDK app that should not
+have to load an application in order to deploy it.
+
+A plan survives a JSON round trip, so it travels as a build artifact:
+
+```ruby
+# in the build, against a running connector
+File.write("build/plan.json", JSON.pretty_generate(Foobara::AWS.plan(manifest).to_h))
+
+# in the CDK app — no Foobara, no ORM, no application gems
+Foobara::AWS::CDK::Service.new(self, "Api",
+  plan: Foobara::AWS::Plan.load(JSON.parse(File.read("build/plan.json"))),
+  code_root: "build")
+```
+
+That also gets you a property worth having: synthesis depends on what was
+actually built, so `cdk synth` cannot create a route to a Lambda whose code is
+missing. `Service` raises if a unit's artifact directory is not there.
+
+## What the plan reads
+
+| plan | manifest field |
+| --- | --- |
+| unit identity and grouping | `domain` or `organization` |
+| the route | `mount` + `scoped_full_path` |
+| which commands are public | `requires_authentication` — **derived, never handed in** |
+| how to size the function | `aws_lambda` (see below) |
+
+The public list is the one to notice. It is not a list you maintain: a command
+moves in or out of it by how it is connected, and nowhere else.
+
+## Granularity
+
+```ruby
+Foobara::AWS.plan(manifest)                            # one Lambda per domain
+Foobara::AWS.plan(manifest, granularity: :organization) # one per organization
+Foobara::AWS.plan(manifest, granularity: :command)      # one per command
+```
+
+Foobara gives two natural grouping levels where most frameworks give one, so
+both are offered, plus the fine-grained case. Per-domain and per-organization
+units get a greedy route (`/run/Posts/{proxy+}`); per-command units get an exact
+one.
+
+A greedy route is only safe with a REQUEST authorizer, which sees the path and
+can decide per command. A JWT authorizer attaches per route, so a unit mixing
+public and authenticated commands would have to be split into one route each.
+
+## Sizing: `aws_lambda`
+
+The one thing a manifest cannot otherwise supply. Foobara describes what a
+command *is*, not how it should be run — but something has to carry it, and the
+person who knows a command fans out across a whole comment tree is the person
+writing that command:
+
+```ruby
+class DestroyPost < Foobara::Command
+  extend Foobara::AWS::Lambda
+  aws_lambda vcpu: 1, timeout: 60
+  ...
+end
+```
+
+No change to Foobara is required: a command's manifest is `super.merge(...)`, so
+this adds a key and the connector serves it.
+
+**`vcpu:` resolves to memory.** Lambda has no CPU setting — CPU is allocated in
+proportion to memory, and 1,769 MB is where a function gets one full vCPU. So
+asking for compute is more honest than picking a memory number, but it is not a
+second dial. Give both and the larger memory wins.
+
+Where a unit holds several commands, the largest value any of them asked for
+wins: a unit runs all of its commands in one function, so it must be sized for
+the hungriest. Undersizing is a runtime failure; oversizing is a rounding error
+on the bill.
+
+## The authorizer
+
+Pass a built authorizer, or a hash and let `Service` build it:
+
+```ruby
+Foobara::AWS::CDK::Service.new(self, "Api", plan: plan, code_root: "build",
+  authorizer: { code: "build/authorizer", environment: { "ISSUER" => issuer } })
+```
+
+Building it here is deliberate, because it is the only way to guarantee this:
+
+**No identity source, and caching off.** Naming an identity source makes it
+*required* — when the header is absent, API Gateway answers 401 itself and never
+invokes the authorizer. Every anonymous caller is refused before any "is this
+command public?" logic can run, which defeats the only reason to choose a
+REQUEST authorizer over a JWT one. It is an easy mistake to make and a hard one
+to see: the symptom is that public commands 401 for signed-out callers, with no
+log line anywhere, because the function was never called.
+
+The plan's public list and mount are passed to the function as
+`FOOBARA_ANONYMOUS` and `FOOBARA_MOUNT`, so the authorizer decides per command
+from `rawPath` without being configured separately.
+
+`Service` does not implement the authorizer itself — verification is
+identity-provider-specific, and `code:` is your own artifact.
+
+## Packaging
+
+```ruby
+Foobara::AWS::Packager.new(plan: plan, root: ".", authorizer: {}).build
+```
+
+One artifact per unit: the application's sources, a generated `handler.rb`, and
+a standalone gem bundle holding only that unit's dependencies (`units/<name>.gemfile`).
+Units whose gemfiles resolve identically share one bundle build.
+
+The generated handler is fully generic — everything unit-specific comes from the
+plan, and everything app-specific from the boot file, where the application sets
+`Foobara::AWS.caller_builder`. Pass `handler_template:` for your own.
+
+Two things it handles that are easy to get wrong:
+
+- **Standalone, not `bundle exec`.** Bundler's runtime is a large fraction of a
+  Ruby cold start and buys a deployed artifact nothing.
+- **Gems declared by `path:`.** Bundler does not copy those into a standalone
+  bundle; it writes their location into the load path, relative to the bundle
+  directory. Copy the bundle into an artifact and that path resolves elsewhere,
+  so the unit boots on the build machine and dies in Lambda. They are copied in
+  and the load path rewritten. (Use `mounts:` so the build container can see
+  them in the first place.)
+
+## What it does not do
+
+- **Create tables, buckets or queues.** Those are the application's, not the
+  connector's. For DynamoDB from Dynamoid models, see
+  [dynamoid-cdk-schema](https://github.com/omarqureshi/dynamoid-cdk-schema),
+  which follows the same describe/build split.
+
+## Development
+
+```sh
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+```
+
+The specs use a manifest fragment carrying only the fields planning reads — no
+type declarations, no possible errors — which is a check in itself that nothing
+else is needed.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/foobara/aws/authorizer.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+# An API Gateway v2 REQUEST authorizer that supports OPTIONAL authentication.
+#
+# RUNTIME, not synth. Require this file and nothing else from the gem — it loads
+# no planning code and no CDK. It runs on EVERY request, including anonymous
+# ones, so its cold start is the one that matters most.
+#
+#   require "foobara/aws/authorizer"
+#
+#   HANDLER = Foobara::AWS::Authorizer.from_env(issuer: ENV.fetch("ISSUER"),
+#                                               audience: ENV.fetch("AUDIENCE"))
+#   def handle(event:, context:) = HANDLER.call(event, context)
+#
+# The public list and the mount come from the environment — FOOBARA_ANONYMOUS
+# and FOOBARA_MOUNT, which Foobara::AWS::CDK::Service sets from the plan. So the
+# set of commands reachable without authentication is derived from
+# `requires_authentication` and never maintained by hand.
+#
+# WHY IT EXISTS. An API Gateway JWT authorizer is all-or-nothing: it rejects a
+# request with no token, and a route without one receives no verified claims at
+# all. There is no "verify if present". That breaks any command which is public
+# but viewer-aware — one that marks your own posts editable, say. Such a command
+# must be readable signed out AND must know who is calling when someone is
+# signed in.
+#
+# This sees rawPath, so it decides per COMMAND rather than per route. Routes stay
+# greedy, which keeps the route count off API Gateway's per-API quota, and the
+# public list is configuration rather than topology.
+#
+# IDENTITY SOURCE. The stack must NOT declare one — Service guarantees this, and
+# it is the reason Service builds the authorizer rather than accepting one.
+# Naming an identity source makes it required: when the header is absent API
+# Gateway answers 401 itself and never invokes this function, so every anonymous
+# caller is refused before the logic below can allow them.
+#
+# It does NOT decide what a caller may do. It answers "is this token real, and is
+# this command reachable without one" — authorization is the command's own,
+# through Foobara's allowed_rule.
+#
+# Verification covers signature (RS256 against the issuer's JWKS), exp, iss and
+# aud. JWKS is fetched once per execution environment — cold-start scope, never
+# request scope.
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "error"
+require_relative "version"
+
+module Foobara
+  module AWS
+    class Unverified < StandardError; end
+
+    class Authorizer
+      # Reads the plan-derived settings Service puts in the environment, so a
+      # deployed authorizer needs no configuration of its own beyond who issued
+      # the tokens.
+      def self.from_env(issuer:, audience:, jwks_url: nil)
+        new(
+          issuer:, audience:, jwks_url:,
+          anonymous: ENV.fetch("FOOBARA_ANONYMOUS", "").split(","),
+          mount: ENV.fetch("FOOBARA_MOUNT", "/run")
+        )
+      end
+
+      def initialize(issuer:, audience:, anonymous: [], mount: "/run", jwks_url: nil)
+        @issuer = issuer.to_s.chomp("/")
+        @audience = Array(audience)
+        # Foobara's own full command names — "Posts::ListPosts" — so the list the
+        # packager derives from the manifest travels here untranslated.
+        @anonymous = Array(anonymous).map(&:to_s)
+        @mount = mount
+        @jwks_url = jwks_url || "#{@issuer}/.well-known/jwks.json"
+      end
+
+      # SIMPLE response format:
+      #   { "isAuthorized" => bool, "context" => { ...claims } }
+      # Anything in `context` reaches the command Lambda at
+      # requestContext.authorizer.lambda, which is where the handler reads the
+      # viewer from.
+      def call(event, _lambda_context = nil)
+        token = bearer(event)
+        command = command_name(event)
+
+        if token.nil?
+          # No token at all. Allowed only where the command is declared public —
+          # and it reaches the command with no claims, so a public viewer-aware
+          # command correctly sees an anonymous caller.
+          return allow({}) if anonymous?(command)
+
+          return deny
+        end
+
+        begin
+          allow(claims_from(token))
+        rescue Unverified
+          # A present-but-invalid token: expired, wrong audience, bad signature.
+          #
+          # On a public command this is treated as anonymous rather than refused —
+          # someone whose session expired should still see the public feed, and
+          # they gain nothing by it. On a gated command it is a refusal.
+          anonymous?(command) ? allow({}) : deny
+        end
+      end
+
+      private
+
+      def allow(context) = { "isAuthorized" => true, "context" => stringify(context) }
+      def deny = { "isAuthorized" => false }
+
+      # API Gateway forwards only strings in the authorizer context.
+      def stringify(claims)
+        claims.to_h { |k, v| [k.to_s, v.is_a?(Array) ? v.join(",") : v.to_s] }
+      end
+
+      def anonymous?(command) = command && @anonymous.include?(command)
+
+      # "/run/Posts/ListPosts" -> "Posts::ListPosts", which is exactly the key the
+      # Foobara manifest files that command under. Deciding here rather than in
+      # routing is what lets routes stay greedy.
+      def command_name(event)
+        path = event["rawPath"] || event.dig("requestContext", "http", "path") || ""
+        parts = path.delete_prefix("#{@mount}/").split("/")
+        parts.length == 2 ? parts.join("::") : nil
+      end
+
+      def bearer(event)
+        headers = event["headers"] || {}
+        raw = headers["authorization"] ||
+              headers.find { |k, _| k.to_s.downcase == "authorization" }&.last
+        return nil if raw.nil? || raw.empty?
+
+        raw.to_s.sub(/\Abearer\s+/i, "").strip.then { |t| t.empty? ? nil : t }
+      end
+
+      def claims_from(token)
+        require_jwt!
+
+        payload, = JWT.decode(
+          token, nil, true,
+          algorithms: ["RS256"],
+          jwks: jwks,
+          iss: @issuer, verify_iss: true,
+          aud: @audience, verify_aud: !@audience.empty?,
+          verify_expiration: true
+        )
+        payload
+      rescue Unverified
+        raise # an unreachable JWKS is already the right failure
+      rescue StandardError => e
+        # Broad on purpose: the jwt gem raises several unrelated classes for
+        # signature, key-lookup and claim failures, and every one of them means the
+        # same thing here — this token is not trustworthy.
+        raise Unverified, "#{e.class}: #{e.message}"
+      end
+
+      # `jwt` is deliberately not a dependency of this gem: only the authorizer
+      # needs it, only the authorizer's own deployment unit installs it, and a
+      # bare LoadError — which is not even a StandardError, so it escapes the
+      # rescue above — would say none of that.
+      def require_jwt!
+        require "jwt"
+      rescue LoadError
+        raise Error,
+              "Foobara::AWS::Authorizer needs the `jwt` gem, which foobara-aws does not depend on — " \
+              "only the authorizer uses it. Add `gem \"jwt\"` to the authorizer unit's gemfile."
+      end
+
+      # Cold-start scope: fetched once per execution environment and reused across
+      # invocations. Nothing request-specific may be cached here.
+      def jwks
+        @jwks ||= begin
+          JSON.parse(Net::HTTP.get(URI(@jwks_url)), symbolize_names: true)
+        rescue StandardError => e
+          # An unreachable JWKS must not quietly become "everyone is anonymous".
+          raise Unverified, "could not fetch JWKS from #{@jwks_url}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/foobara/aws/cdk/service.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+# Service takes a Plan and every caller has to build one, so requiring
+# "foobara/aws/cdk/service" alone must be enough.
+require_relative "../plan"
+
+module Foobara
+  module AWS
+    # Everything here is SYNTH time. Nothing under Foobara::AWS::CDK is
+    # ever loaded inside a Lambda — that is why the handler and the
+    # authorizer live outside it.
+    module CDK
+      # Synthesises a {Plan} into Lambda functions behind one HTTP API.
+      #
+      # AWS CDK is the caller's dependency (the Ruby CDK, from its preview feed),
+      # so it is referenced lazily — {Foobara::AWS.plan} works without it, which is
+      # what lets a build step produce a plan on a machine that has no CDK at all.
+      #
+      #   service = Foobara::AWS::CDK::Service.new(self, "Api", plan: plan, code_root: "build")
+      #   table.grant_read_write_data(service.function("posts"))
+      #
+      # It does NOT build artifacts. `code_root` must already contain one directory
+      # per unit, each with a `handler.rb` — so synthesis cannot create a route to a
+      # Lambda whose code was never built.
+      class Service
+        DEFAULT_SIZING = { memory_size: 1024, timeout_seconds: 10 }.freeze
+
+        attr_reader :api, :functions, :plan
+
+        # rubocop:disable Metrics/ParameterLists
+        def initialize(scope, id, plan:, code_root:, sizing: {}, defaults: DEFAULT_SIZING,
+                       environment: {}, runtime: nil, architecture: nil, authorizer: nil,
+                       api_props: {}, tracing: nil, log_retention: nil)
+          # Checked first: everything below needs it, and a bare LoadError from
+          # `constructs` would say nothing about which dependency is missing.
+          cdk
+
+          @scope = construct(scope, id)
+          @plan = plan
+          @code_root = code_root
+          @sizing = sizing.transform_keys(&:to_s)
+          @defaults = DEFAULT_SIZING.merge(defaults)
+          @environment = environment
+          @runtime = runtime
+          @architecture = architecture
+          @tracing = tracing
+          @log_retention = log_retention
+          @functions = {}
+
+          @api = cdk::APIGatewayv2::HttpAPI.new(@scope, "Api", api_props)
+          @authorizer = build_authorizer(authorizer)
+          plan.units.each { |unit| add_unit(unit) }
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # Look a unit's function up by name, for grants:
+        #   table.grant_read_write_data(service.function("posts"))
+        def function(name) = @functions.fetch(name.to_s)
+
+        def url = @api.url
+
+        private
+
+        def add_unit(unit)
+          fn = build_function(unit)
+          @functions[unit.name] = fn
+
+          props = {
+            path: unit.route,
+            methods: [cdk::APIGatewayv2::HttpMethod::ANY],
+            integration: cdk::APIGatewayv2Integrations::HttpLambdaIntegration.new(
+              "#{logical(unit.name)}Integration", fn
+            )
+          }
+          props[:authorizer] = @authorizer if @authorizer
+          @api.add_routes(props)
+        end
+
+        def build_function(unit)
+          # Precedence: an explicit sizing: override, then whatever the unit's
+          # commands declared via aws_lambda, then the defaults. The override
+          # exists for the case the declaration cannot know about — an
+          # environment where everything should be small, say.
+          sizing = @defaults.merge(unit.sizing).merge(@sizing.fetch(unit.name, {}))
+          asset = File.join(@code_root, unit.name)
+          unless Dir.exist?(asset)
+            raise Error, "no artifact for unit #{unit.name.inspect} at #{asset} — build it before synthesising"
+          end
+
+          cdk::Lambda::Function.new(@scope, logical(unit.name), {
+            runtime: @runtime || cdk::Lambda::Runtime.RUBY_4_0,
+            # x86_64 by default: building arm64 artifacts on an x86_64 host
+            # runs under qemu, which is dramatically slower.
+            architecture: @architecture || cdk::Lambda::Architecture.X86_64,
+            handler: "handler.handle",
+            code: cdk::Lambda::Code.from_asset(asset),
+            memory_size: sizing.fetch(:memory_size),
+            timeout: cdk::Duration.seconds(sizing.fetch(:timeout_seconds)),
+            environment: @environment.merge("FOOBARA_UNIT" => unit.name)
+          }.merge(observability))
+        end
+
+        # Accepts an already-built authorizer, or a hash describing one to build.
+        #
+        # Building it here rather than leaving it to the caller is deliberate: it
+        # is the only way to guarantee the two settings below, and getting either
+        # wrong silently breaks optional authentication rather than failing.
+        def build_authorizer(config)
+          return nil if config.nil?
+          return config unless config.is_a?(Hash)
+
+          fn = authorizer_function(config)
+
+          cdk::APIGatewayv2Authorizers::HttpLambdaAuthorizer.new(
+            config.fetch(:id, "FoobaraAuth"), fn,
+            {
+              response_types: [cdk::APIGatewayv2Authorizers::HttpLambdaResponseType::SIMPLE],
+              # NO identity source, and this is not an oversight.
+              #
+              # Naming one makes it REQUIRED: when the header is absent, API
+              # Gateway answers 401 itself and never invokes the authorizer. Every
+              # anonymous caller is then refused before any "is this command
+              # public?" logic can run — which defeats the only reason to choose a
+              # REQUEST authorizer over a JWT one.
+              #
+              # With no identity source the authorizer runs on every request, which
+              # is what optional means. Caching must then be off: there is no key
+              # to cache under.
+              identity_source: [],
+              results_cache_ttl: cdk::Duration.seconds(0)
+            }
+          )
+        end
+
+        def authorizer_function(config)
+          asset = config.fetch(:code)
+          # The public list is passed in, not configured: it comes from the plan,
+          # which read it from the manifest.
+          env = { "FOOBARA_ANONYMOUS" => plan.anonymous.join(","),
+                  "FOOBARA_MOUNT" => plan.mount }.merge(config.fetch(:environment, {}))
+
+          cdk::Lambda::Function.new(@scope, config.fetch(:id, "FoobaraAuth"), {
+            runtime: @runtime || cdk::Lambda::Runtime.RUBY_4_0,
+            architecture: @architecture || cdk::Lambda::Architecture.X86_64,
+            handler: config.fetch(:handler, "handler.handle"),
+            code: cdk::Lambda::Code.from_asset(asset),
+            memory_size: config.fetch(:memory_size, 512),
+            timeout: cdk::Duration.seconds(config.fetch(:timeout_seconds, 10)),
+            environment: env
+          }.merge(observability))
+        end
+
+        # Tracing and log retention, applied identically to every function
+        # including the authorizer — a trace that stops at the authorizer would
+        # hide the one invocation that happens on every single request.
+        #
+        # `tracing: :active` is the cold-start measure worth having: X-Ray breaks
+        # a cold invocation into an Initialization subsegment and the handler's
+        # own work, so you can see what the boot actually costs rather than
+        # inferring it. CloudWatch's REPORT line already carries Init Duration
+        # per invocation; X-Ray adds the shape of it, and the view across
+        # services once a command calls another.
+        #
+        # NOTE it is Lambda-side only. An API Gateway HTTP API (v2) does not
+        # support X-Ray — only REST APIs do — so the trace begins at the
+        # function, not at the edge.
+        def observability
+          props = {}
+          props[:tracing] = tracing_mode(@tracing) if @tracing
+          props[:log_retention] = @log_retention if @log_retention
+          props
+        end
+
+        def tracing_mode(value)
+          case value
+          when :active then cdk::Lambda::Tracing::ACTIVE
+          when :pass_through then cdk::Lambda::Tracing::PASS_THROUGH
+          when :disabled then cdk::Lambda::Tracing::DISABLED
+          else value # an already-resolved CDK enum
+          end
+        end
+
+        # A child construct, so the functions' logical ids cannot collide with
+        # anything at stack level — a "comments" function and a "Comments" table
+        # both want the id "Comments" otherwise, and synthesis fails.
+        def construct(scope, id)
+          require "constructs"
+          Constructs::Construct.new(scope, id)
+        end
+
+        # CloudFormation logical ids must be alphanumeric.
+        def logical(name) = name.to_s.split(/[.\-_]/).map(&:capitalize).join
+
+        def cdk
+          return AWSCDK if defined?(AWSCDK)
+
+          raise Error, "aws-cdk-lib must be loaded to synthesise — add it to your CDK app and `require \"aws-cdk-lib\"`"
+        end
+      end
+    end
+  end
+end

data/lib/foobara/aws/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Foobara
+  module AWS
+    # Shared by every entry point — planning, packaging, synthesis, runtime — so
+    # each can be required on its own without dragging the others in.
+    class Error < StandardError; end
+  end
+end