belt 0.3.44 → 0.4.1

data/lib/belt/authentication/controller.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Belt
+  module Authentication
+    # Cognito identity for controllers. Mixed into BeltController::Base, so every
+    # controller already has it:
+    #
+    #   class ProfilesController < ApplicationController
+    #     before_action :authenticate_user!
+    #
+    #     def show
+    #       @profile = current_user
+    #     end
+    #   end
+    #
+    # `current_user` returns a record of the app's user model (see
+    # CognitoAuthenticatable), provisioned just-in-time on first sight. Nothing in a
+    # controller needs to decode a token, read a claim, or parse a Cognito group.
+    #
+    # Every ivar here is listed in ImplicitResponse::FRAMEWORK_IVARS, so an identity
+    # resolved mid-action never leaks into a JSON response body.
+    module Controller
+      # The raw `Authorization` header, however the client cased it.
+      def authorization_header
+        Claims.authorization_header(event)
+      end
+
+      # The raw Bearer credential — whatever it is. An app whose API accepts its own
+      # token format alongside Cognito reads it here and decides for itself.
+      def bearer_token
+        Claims.bearer_token(event)
+      end
+
+      # The Cognito claims on this request, or nil if there aren't any. Memoized
+      # including the nil, so a request decodes at most once.
+      def cognito_claims
+        return @cognito_claims if defined?(@cognito_claims)
+
+        @cognito_claims = Claims.from_event(event, issuer: belt_authentication_config.issuer)
+      end
+
+      def cognito_sub
+        cognito_claims && cognito_claims['sub']
+      end
+
+      def cognito_email
+        cognito_claims && cognito_claims['email']
+      end
+
+      # Cognito groups on the current token. Prefer #cognito_admin? or a role on
+      # #current_user over reading this directly.
+      def cognito_groups
+        return @cognito_groups if defined?(@cognito_groups)
+
+        @cognito_groups = Claims.groups(cognito_claims)
+      end
+
+      # Does this token grant platform staff access? The *grant* mechanism —
+      # `current_user.admin?` mirrors it, which is what the rest of the app should ask,
+      # so that a user's staff status is answerable without a token in hand.
+      def cognito_admin?
+        cognito_groups.intersect?(belt_authentication_config.admin_groups)
+      end
+
+      # The user record behind the token on this request, or nil when the request
+      # carries no Cognito identity (anonymous, or an app-specific credential such as
+      # an API key).
+      #
+      # Provisioned on first sight and refreshed only on drift — see
+      # CognitoAuthenticatable.sync_from_claims!. Memoized including the nil.
+      def current_user
+        return @current_user if defined?(@current_user)
+
+        @current_user = resolve_cognito_user
+      end
+
+      def user_signed_in?
+        !current_user.nil?
+      end
+
+      # Suppress Cognito resolution for a request authenticated some other way — an
+      # app's own API key, a machine token. Default false: always attempt.
+      #
+      # Usually unnecessary, since a credential that isn't a Cognito ID token yields no
+      # claims and therefore no user. It matters when a request could carry both, and
+      # the app's answer is "this caller is not a human".
+      def skip_cognito_identity?
+        false
+      end
+
+      # before_action guard. Raises, because Belt discards before_action return values
+      # (see BeltController::Base#run_before_actions) — returning a response hash would
+      # let the action run anyway. Belt maps the error to 401.
+      def authenticate_user!
+        raise NotAuthenticated, 'Authentication required' unless user_signed_in?
+      end
+
+      private
+
+      def resolve_cognito_user
+        return nil if skip_cognito_identity?
+
+        claims = cognito_claims
+        return nil if claims.nil?
+
+        model = belt_authentication_config.user_class
+        return nil unless model.respond_to?(:sync_from_claims!)
+
+        model.sync_from_claims!(
+          sub: claims['sub'],
+          email: claims['email'],
+          name: claims['name'],
+          admin: cognito_admin?,
+          email_verified: claims['email_verified']
+        )
+      end
+
+      def belt_authentication_config
+        Belt.configuration.authentication
+      end
+    end
+  end
+end

data/lib/belt/authentication/model_macro.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'activeitem'
+
+module Belt
+  module Authentication
+    # The declaration, Devise-style. Extended onto ActiveItem::Base so it reads as part
+    # of the model DSL rather than as a mixin the app has to know the path to:
+    #
+    #   class User < ApplicationRecord
+    #     cognito_authenticatable
+    #   end
+    module ModelMacro
+      # @param roles [Array<String>] allowed values for `role`. Defaults to
+      #   member/admin; extend it if the platform has more than staff and everyone else.
+      # @param default_role [String] role given to a newly provisioned user.
+      # @param email_index [String, false] GSI name for email lookups, or false if the
+      #   app doesn't need to resolve people by email.
+      def cognito_authenticatable(roles: nil, default_role: nil, email_index: nil)
+        include Belt::Authentication::CognitoAuthenticatable
+
+        self.cognito_roles = roles.map(&:to_s) if roles
+        self.cognito_default_role = default_role.to_s if default_role
+        self.cognito_email_index = email_index unless email_index.nil?
+
+        validate_cognito_default_role!
+        self
+      end
+
+      # Whether this model has declared cognito_authenticatable.
+      def cognito_authenticatable?
+        include?(Belt::Authentication::CognitoAuthenticatable)
+      end
+
+      private
+
+      def validate_cognito_default_role!
+        return if cognito_roles.include?(cognito_default_role)
+
+        raise ArgumentError,
+              "default_role #{cognito_default_role.inspect} is not in roles #{cognito_roles.inspect}"
+      end
+    end
+  end
+end
+
+ActiveItem::Base.extend(Belt::Authentication::ModelMacro)

data/lib/belt/authentication.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'configuration'
+require_relative 'authentication/configuration'
+require_relative 'authentication/claims'
+require_relative 'authentication/cognito_authenticatable'
+require_relative 'authentication/model_macro'
+require_relative 'authentication/controller'
+module Belt
+  # Cognito-backed identity for Belt apps.
+  #
+  # Cognito owns authentication (passwords, MFA, groups). Belt owns the *record* of the
+  # human it authenticated, so the app can answer its own questions about them without
+  # re-reading JWT claims everywhere.
+  #
+  # Declare it on a model, Devise-style:
+  #
+  #   class User < ApplicationRecord
+  #     cognito_authenticatable
+  #   end
+  #
+  # That single line supplies the identity attributes (email, name, role,
+  # email_verified, last_seen_on), the EmailIndex GSI, and the class methods that
+  # provision a row from a token — see Authentication::CognitoAuthenticatable.
+  #
+  # Controllers get `current_user`, `authenticate_user!`, `user_signed_in?` and
+  # `cognito_admin?` for free (Authentication::Controller is mixed into
+  # BeltController::Base), so a request never has to decode a JWT by hand.
+  #
+  # Rows are provisioned just-in-time on the first authenticated request. There is no
+  # signup endpoint to keep in step with Cognito's hosted UI.
+  module Authentication
+    # Raised when a request carries no usable Cognito identity and one is required.
+    # A subclass of Belt::AuthenticationError so BeltController's existing
+    # rescue_from mapping (401) applies without any app-level wiring.
+    class NotAuthenticated < Belt::AuthenticationError; end
+  end
+end

data/lib/belt/cli/auth_command.rb

@@ -4,12 +4,14 @@ require 'fileutils'
 require 'erb'
 require_relative 'app_detection'
 require_relative 'frontend_registry'
+require_relative 'tables_command'
 
 module Belt
   module CLI
     class AuthCommand
       TEMPLATE_DIR = File.expand_path('../../templates/generate/auth', __dir__)
       MODULE_DIR = 'infrastructure/modules/app'
+      MODELS_DIR = 'lambda/models'
 
       include AppDetection
 
@@ -59,6 +61,8 @@ module Belt
           What this generates:
             infrastructure/modules/app/cognito.tf          User pool + client resources
             infrastructure/modules/app/cognito_outputs.tf  Pool ID, ARN, and client ID outputs
+            lambda/models/user.rb                          User model (cognito_authenticatable)
+            infrastructure/modules/app/dynamodb.tf         users table + EmailIndex (regenerated)
 
           With --signup (when frontend/ exists):
             frontend/src/lib/auth.js                       Auth module (signIn, signUp, etc.)
@@ -95,6 +99,8 @@ module Belt
             2. Add auth: :cognito to your routes namespace
             3. Run `belt deploy` to create the user pool
             4. Create your account (admin-only): aws cognito-idp admin-create-user ...
+
+          Then `current_user` works in every controller — see `belt explain authentication`.
         HELP
       end
 
@@ -125,6 +131,7 @@ module Belt
         write_cognito_variables_tf if @ses_email
         patch_main_tf
         patch_env_outputs
+        write_user_model
         generate_frontend_auth if frontend?
 
         puts "\n✓ Auth generated!"
@@ -219,6 +226,26 @@ module Belt
 
       private
 
+      # Scaffold the app's user model. `cognito_authenticatable` is the whole point:
+      # the identity plumbing lives in the gem, so this file exists only to hold the
+      # app's own domain. Never overwritten — someone's associations are in there.
+      def write_user_model
+        return unless Dir.exist?(MODELS_DIR)
+
+        dest = File.join(MODELS_DIR, 'user.rb')
+        if File.exist?(dest)
+          puts "  skip    #{dest} (already exists)"
+          return
+        end
+
+        @user_class = 'User'
+        write_template('user_model.rb.erb', dest)
+        puts "  create  #{dest}"
+
+        # Regenerate dynamodb.tf so the users table (and its EmailIndex) exists.
+        TablesCommand.sync_all_environments
+      end
+
       def build_pool_metadata
         if @pool_names.length == 1 && @pool_names.first == 'main'
           [{ name: 'main', suffix: '', label: '' }]

data/lib/belt/cli/deploy_command.rb

@@ -14,6 +14,7 @@ require_relative 'zip_artifact_builder'
 require_relative 'nested_environment'
 require_relative 'cognito_sharer'
 require_relative 'dynamo_copier'
+require_relative 'dns_command'
 require_relative 'apex_dns_sync'
 
 module Belt
@@ -177,6 +178,11 @@ module Belt
         # Sync apex DNS records to root zone (if this is a prod/apex environment)
         run_apex_dns_sync
 
+        # Sync ACM validation CNAMEs for apex domains (e.g., prod)
+        # This handles the case where prod uses the apex domain (example.com)
+        # and needs validation CNAMEs in the root zone, not the env's zone.
+        sync_acm_validation_if_apex
+
         puts "\n✅ Deployed #{@env} successfully!"
         print_outputs(env_dir)
 
@@ -299,6 +305,27 @@ module Belt
         end
       end
 
+      # ─── ACM Validation Sync ────────────────────────────────────────
+
+      # For apex environments (prod), ACM validation CNAMEs need to be in the
+      # root zone (managed by infrastructure/dns), not the environment's zone.
+      # This is because the registrar points to the root zone, which is
+      # authoritative for the apex domain.
+      def sync_acm_validation_if_apex
+        # Only sync if DNS infrastructure exists
+        return unless Dir.exist?(File.join(@infra_dir, '..', 'infrastructure', 'dns')) ||
+                      Dir.exist?('infrastructure/dns')
+
+        # Check if this is an apex environment
+        return unless apex_environment?
+
+        DnsCommand.sync_acm_validation_if_needed(@env)
+      end
+
+      def apex_environment?
+        %w[prod production].include?(@env)
+      end
+
       # ─── Backup Phase ───────────────────────────────────────────────
 
       def run_backups