belt 0.3.44 → 0.4.1

data/lib/belt/cli/environment_command.rb

@@ -95,11 +95,11 @@ module Belt
         if @parent_environment
           puts "\nThis is a nested environment under '#{@parent_environment}'."
           puts "It will use the parent's wildcard certificate and hosted zone."
-          if @domain
-            puts "Domain will be: api.#{@env_name}.#{@parent_environment}.#{@domain}"
-          else
-            puts "Domain will be: #{@env_name}.#{@parent_environment}.<your-domain>"
-          end
+          # Nested envs use an `api-<env>` prefix (not `api.<env>`) so the API
+          # host stays a single level under the parent's *.<parent>.<domain>
+          # wildcard cert. See lib/templates/module/dns.tf.erb (api_domain).
+          puts "Frontend will be: https://#{@env_name}.#{@parent_environment}.#{@domain}"
+          puts "API will be: https://api-#{@env_name}.#{@parent_environment}.#{@domain}"
           puts "\nDeploy with:"
           puts "  belt deploy #{@env_name}"
           puts "\nNo DNS delegation needed — the parent environment handles DNS."

data/lib/belt/cli/explain_command.rb

@@ -17,6 +17,12 @@ module Belt
         'model' => 'models',
         'activeitem' => 'models',
         'dynamodb' => 'models',
+        'auth' => 'authentication',
+        'cognito' => 'authentication',
+        'users' => 'authentication',
+        'user' => 'authentication',
+        'current_user' => 'authentication',
+        'login' => 'authentication',
         'deploy' => 'deployment',
         'deploying' => 'deployment',
         'terraform' => 'deployment',

data/lib/belt/cli/frontend_deploy_command.rb

@@ -75,6 +75,12 @@ module Belt
 
       private
 
+      # Load infrastructure/<env>/belt.rb and apply its aws_profile + env vars
+      # to the current process. Without this, `terraform output` can't reach the
+      # S3 state backend (403), fetch_tf_output returns nil, and the deploy aborts
+      # with a misleading "Could not determine S3 bucket" error. The full
+      # `belt deploy` path applies this before invoking the frontend deploy;
+      # standalone `belt deploy frontend` must do it too.
       def load_and_apply_env_config!
         env_config = EnvironmentConfig.load(@env, infra_dir: @infra_dir)
         env_config.apply!

data/lib/belt/cli/frontend_env_command.rb

@@ -2,8 +2,10 @@
 
 require_relative 'app_detection'
 require_relative 'env_resolver'
+require_relative 'environment_config'
 require_relative 'frontend_env_map'
 require_relative 'frontend_registry'
+require_relative 'terraform_command'
 
 module Belt
   module CLI
@@ -111,18 +113,19 @@ module Belt
       def initialize(env, frontend: nil)
         @env = env
         @app_name = detect_app_name
-        @env_dir = "infrastructure/#{@env}"
+        @infra_dir = TerraformCommand.find_infrastructure_dir || 'infrastructure'
+        @env_dir = File.join(@infra_dir, @env)
         @frontend = frontend || FrontendRegistry.new.resolve!
       end
 
       def run
+        load_and_apply_env_config!
+
         unless Dir.exist?(@frontend.path)
           abort "Error: No #{@frontend.path}/ directory found. Run `belt generate frontend react` first."
         end
 
-        unless Dir.exist?(@env_dir)
-          abort "Error: infrastructure/#{@env} not found. Run `belt generate environment #{@env}` first."
-        end
+        abort "Error: #{@env_dir} not found. Run `belt generate environment #{@env}` first." unless Dir.exist?(@env_dir)
 
         map = FrontendEnvMap.new(@env, env_dir: @env_dir, frontend_path: @frontend.path)
 
@@ -142,6 +145,12 @@ module Belt
           puts "✅ Updated #{result[:path]} (#{updated.join(', ')})"
         end
       end
+
+      private
+
+      def load_and_apply_env_config!
+        EnvironmentConfig.load(@env, infra_dir: @infra_dir).apply!
+      end
     end
   end
 end

data/lib/belt/cli/logs_command.rb

@@ -2,6 +2,8 @@
 
 require 'json'
 require 'open3'
+require_relative 'environment_config'
+require_relative 'terraform_command'
 
 module Belt
   module CLI
@@ -76,6 +78,8 @@ module Belt
         @env ||= detect_environment
         abort 'Error: Cannot determine environment. Pass -e ENV or set BELT_ENV.' unless @env
 
+        apply_env_config!
+
         @app_name = detect_app_name
         abort 'Error: Cannot determine app name.' unless @app_name
 
@@ -88,6 +92,13 @@ module Belt
 
       private
 
+      def apply_env_config!
+        infra_dir = TerraformCommand.find_infrastructure_dir || find_infra_dir
+        env_config = EnvironmentConfig.load(@env, infra_dir: infra_dir)
+        env_config.apply!
+        puts "  🔑 Using AWS profile: #{env_config.aws_profile}" if env_config.aws_profile?
+      end
+
       def parse_args(args)
         i = 0
         while i < args.length

data/lib/belt/cli/server_command.rb

@@ -3,6 +3,7 @@
 require 'base64'
 require 'json'
 require_relative 'app_detection'
+require_relative 'environment_config'
 require_relative 'frontend_env_map'
 require_relative 'frontend_registry'
 require_relative 'terraform_command'
@@ -125,6 +126,9 @@ module Belt
         env_name = @deploy_env || ENV.fetch('BELT_ENV', nil) || TerraformCommand.list_environments.first
         return {} unless env_name
 
+        infra_dir = TerraformCommand.find_infrastructure_dir
+        EnvironmentConfig.load(env_name, infra_dir: infra_dir).apply!
+
         FrontendEnvMap.new(env_name, frontend_path: @frontend.path).process_env
       rescue StandardError
         # Fall back to legacy api_url detection if map resolution fails
@@ -274,6 +278,7 @@ module Belt
           next unless Dir.exist?(env_dir)
           next unless File.exist?(File.join(env_dir, '.terraform'))
 
+          EnvironmentConfig.load(env, infra_dir: infra_dir).apply!
           url = read_api_url_from_outputs(env_dir)
           if url
             @deploy_env = env

data/lib/belt/cli/tables_command.rb

@@ -84,6 +84,9 @@ module Belt
         # Extract indexes() declaration
         indexes = extract_indexes(content)
 
+        # cognito_authenticatable installs a GSI without an indexes() call
+        indexes += extract_cognito_indexes(content)
+
         # Extract belongs_to associations and generate convention indexes
         indexes += extract_belongs_to_indexes(content)
 
@@ -115,15 +118,33 @@ module Belt
         indexes
       end
 
+      # `cognito_authenticatable` installs an EmailIndex GSI without the model ever
+      # calling indexes() — see Belt::Authentication::CognitoAuthenticatable. The
+      # generator has to know that, or the table would be created without the GSI and
+      # the first email lookup would fail in production instead of here.
+      def extract_cognito_indexes(content)
+        declaration = uncommented(content).match(/^\s*cognito_authenticatable\b(.*)$/)
+        return [] unless declaration
+
+        options = declaration[1].to_s
+        return [] if options.match?(/email_index:\s*false/)
+
+        name = options.match(/email_index:\s*['"]([^'"]+)['"]/)
+        [{ name: name ? name[1] : 'EmailIndex', partition_key: 'email', sort_key: nil }]
+      end
+
       # Extract belongs_to declarations and generate convention-based GSI indexes.
       # belongs_to :conversation → ConversationIndex with partition_key: 'conversationId'
+      #
+      # `index: false` opts out — the model is saying the reverse lookup is covered some
+      # other way (its own indexes() entry, usually, under a different key name).
+      # Generating one anyway produces a GSI on an attribute that doesn't exist.
       def extract_belongs_to_indexes(content)
         indexes = []
 
-        # Skip commented-out belongs_to lines
-        content.lines.reject { |line| line.strip.start_with?('#') }.join
-               .scan(/belongs_to\s+:(\w+)/) do |match|
-          association_name = match[0]
+        uncommented(content).scan(/belongs_to\s+:(\w+)([^\n]*)/) do |association_name, options|
+          next if options.match?(/index:\s*false/)
+
           index_name = "#{Belt::Inflector.classify(association_name)}Index"
           partition_key = "#{association_name}Id"
 
@@ -133,6 +154,10 @@ module Belt
         indexes
       end
 
+      def uncommented(content)
+        content.lines.reject { |line| line.strip.start_with?('#') }.join
+      end
+
       def generate_dynamodb_tf(models)
         dest = File.join(MODULE_DIR, 'dynamodb.tf')
         existing_content = File.exist?(dest) ? File.read(dest) : nil

data/lib/belt/configuration.rb

@@ -5,6 +5,7 @@ module Belt
   #
   #   Belt.configure do |config|
   #     config.default_format = :json  # or :html
+  #     config.authentication.user_class = 'Account'
   #   end
   #
   # Note: infrastructure/<env>/belt.rb uses a separate sandboxed DSL for CLI
@@ -18,6 +19,12 @@ module Belt
 
     attr_reader :default_format
 
+    # Cognito identity settings — see Belt::Authentication::Configuration.
+    # Resolved lazily so config can be set before the app's models are loaded.
+    def authentication
+      @authentication ||= Belt::Authentication::Configuration.new
+    end
+
     def default_format=(value)
       format = value.to_sym
       unless VALID_FORMATS.include?(format)
@@ -27,4 +34,23 @@ module Belt
       @default_format = format
     end
   end
+
+  # Runtime configuration accessors live here, not in belt.rb, so that a single
+  # subsystem can be required on its own (`require 'belt/authentication'`) and still
+  # reach Belt.configuration. Test harnesses that shadow BeltController do exactly that.
+  class << self
+    # Runtime configuration (lambda/config/environment.rb). Separate from the
+    # CLI sandboxed DSL in infrastructure/<env>/belt.rb.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
 end

data/lib/belt/docs/authentication.md

@@ -0,0 +1,186 @@
+# Authentication
+
+Cognito owns authentication — passwords, MFA, hosted signup, groups. Belt owns the
+**record** of the human Cognito authenticated, so your app can answer its own questions
+about that person without re-reading JWT claims in every controller.
+
+Declare it on a model and you're done:
+
+```ruby
+class User < ApplicationRecord
+  cognito_authenticatable
+end
+```
+
+That one line supplies:
+
+| | |
+|---|---|
+| Primary key | the Cognito `sub` — resolving the caller is one `GetItem` |
+| Attributes | `email`, `name`, `role`, `email_verified`, `last_seen_on` |
+| GSI | `EmailIndex`, for finding a person by address |
+| Class methods | `.sync_from_claims!`, `.for_sub`, `.for_email` |
+| Instance methods | `#admin?`, `#email_verified?` |
+
+Controllers get `current_user`, `authenticate_user!`, `user_signed_in?`, and
+`cognito_admin?` with no `include` and no configuration.
+
+## The table
+
+```hcl
+resource "aws_dynamodb_table" "users" {
+  name         = "${var.app_name}-${var.environment}-users"
+  billing_mode = "PAY_PER_REQUEST"
+  hash_key     = "id" # the Cognito sub
+
+  attribute {
+    name = "id"
+    type = "S"
+  }
+
+  attribute {
+    name = "email"
+    type = "S"
+  }
+
+  global_secondary_index {
+    name            = "EmailIndex"
+    hash_key        = "email"
+    projection_type = "ALL"
+  }
+}
+```
+
+Identity attributes are stored snake_case (`email_verified`, not `emailVerified`) so
+they read the same in the console, in `dynamodb.tf`, and in a GSI key definition.
+
+Grant the table to every Lambda, not per route. Authenticated requests read it *before*
+the action runs, so per-route `tables:` means listing it on every route and 500ing on
+whichever one you missed.
+
+## In a controller
+
+```ruby
+class ProfilesController < ApplicationController
+  before_action :authenticate_user!
+
+  def show
+    @profile = current_user
+  end
+end
+```
+
+`authenticate_user!` raises `Belt::Authentication::NotAuthenticated`, which Belt already
+maps to **401**. It has to raise: `before_action` cannot halt the chain by returning a
+response — return values are discarded and the action runs anyway.
+
+| Method | |
+|---|---|
+| `current_user` | the user record, or nil. Memoized per request |
+| `user_signed_in?` | is there a Cognito identity on this request? |
+| `authenticate_user!` | `before_action` guard → 401 |
+| `cognito_admin?` | does the token carry a staff Cognito group? |
+| `cognito_claims` | raw claims, if you really need them |
+| `bearer_token` | the raw `Authorization: Bearer` credential |
+
+If your app has a *second* credential scheme — an API key for machine callers, say —
+override `skip_cognito_identity?` to declare that such a request is not a human:
+
+```ruby
+def skip_cognito_identity?
+  agent_request?   # `Authorization: Bearer fp_...`
+end
+```
+
+Usually unnecessary: a credential that isn't a Cognito ID token yields no claims and
+therefore no `current_user`. It matters when a request could be read as both.
+
+## Just-in-time provisioning
+
+There is no signup endpoint to keep in step with Cognito's hosted UI. The first
+authenticated request from a user writes the row; later requests only write when
+something actually drifted — a name changed in Cognito, a staff group was granted or
+revoked, or it's the first sighting today. Steady state is one `GetItem` and no write.
+
+`last_seen_on` is a **date**, not a timestamp, precisely so an active session doesn't
+generate a write per request.
+
+To hang your own behaviour off that moment, override the hook:
+
+```ruby
+class User < ApplicationRecord
+  cognito_authenticatable
+
+  # Runs whenever an identity is resolved from a token.
+  def after_cognito_sync
+    claim_pending_invitations!
+  end
+end
+```
+
+## Platform staff
+
+`role` is platform-wide: `member` or `admin`. It mirrors a Cognito group on **every**
+request, so removing someone from the group locks them out on their very next call.
+
+```ruby
+current_user.admin?   # FeatureParity staff — can see across tenants
+cognito_admin?        # the grant: does this token carry the group?
+```
+
+Per-tenant roles (owner of a project, member of an org) are your domain, not this
+concern's. Model them yourself.
+
+Grant staff by hand — Terraform should create the group but not manage its members, so
+that a `terraform apply` can't hand out platform-wide read access:
+
+```bash
+aws cognito-idp admin-add-user-to-group \
+  --user-pool-id <pool> --username <you> --group-name admins
+```
+
+## Configuration
+
+Every setting has a working default. An app whose model is `User` and whose staff group
+is `admins` configures nothing.
+
+```ruby
+# lambda/config/environment.rb
+Belt.configure do |config|
+  config.authentication.user_class   = 'Account'  # default: 'User'
+  config.authentication.admin_groups = %w[staff]  # default: ['admins'], or ADMIN_COGNITO_GROUPS
+  config.authentication.issuer       = '...'      # default: derived from COGNITO_USER_POOL_ID
+end
+```
+
+Macro options:
+
+```ruby
+cognito_authenticatable roles: %w[member admin support],
+                        default_role: 'member',
+                        email_index: 'PeopleEmailIndex' # or false to skip it
+```
+
+## Two token shapes
+
+A route can be authenticated either way, and both are handled:
+
+1. **API Gateway Cognito authorizer** — claims arrive pre-verified under
+   `requestContext.authorizer.claims`, with every value flattened to a string
+   (`"true"`, `"[admins, members]"`).
+2. **A raw `Authorization: Bearer <id token>` header** — the Lambda decodes it.
+
+Case 2 is signature-unverified by design: where an authorizer is attached, the gateway
+already checked the signature and an unsigned token never reaches your code. What can
+still be checked cheaply is checked — structure, expiry, issuer, and `token_use` (an
+access token is rejected; it carries no email or name).
+
+Anything that isn't a Cognito ID token — including your own API key scheme sharing the
+same header — reads as "no Cognito identity" rather than an error, so
+`current_user` is simply nil.
+
+## See also
+
+- `belt explain models` — ActiveItem
+- `belt explain controllers` — `before_action`, response helpers
+- `belt generate auth` — create the Cognito user pool

data/lib/belt/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Belt
+  class AuthenticationError < StandardError; end
+  class RecordNotFound < StandardError; end
+  class ActionNotFound < StandardError; end
+  class TemplateNotFound < StandardError; end
+end

data/lib/belt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.3.44'
+  VERSION = '0.4.1'
 end

data/lib/belt.rb

@@ -3,6 +3,7 @@
 require 'activeitem'
 require_relative 'belt/version'
 require_relative 'belt/root'
+require_relative 'belt/errors'
 require_relative 'belt/configuration'
 require_relative 'belt/http_status'
 require_relative 'belt/parameters'
@@ -11,30 +12,11 @@ require_relative 'belt/lambda_handler'
 require_relative 'belt/action_router'
 
 module Belt
-  class AuthenticationError < StandardError; end
-  class RecordNotFound < StandardError; end
-  class ActionNotFound < StandardError; end
-  class TemplateNotFound < StandardError; end
-
   @controller_paths = []
 
   class << self
     attr_reader :controller_paths
 
-    # Runtime configuration (lambda/config/environment.rb). Separate from the
-    # CLI sandboxed DSL in infrastructure/<env>/belt.rb.
-    def configuration
-      @configuration ||= Configuration.new
-    end
-
-    def configure
-      yield configuration
-    end
-
-    def reset_configuration!
-      @configuration = Configuration.new
-    end
-
     # Auto-discover lambda/controllers dirs in all loaded gems
     def gem_controller_paths
       @gem_controller_paths ||= discover_gem_paths('lambda/controllers')
@@ -72,5 +54,6 @@ module Belt
   end
 end
 
+require_relative 'belt/authentication'
 require_relative 'belt_controller/base'
 require_relative 'belt/controllers/welcome_controller'

data/lib/belt_controller/base.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'cgi'
 require_relative '../belt/parameters'
+require_relative '../belt/authentication'
 require_relative '../belt/helpers/response'
 require_relative '../belt/helpers/error_logging'
 require_relative '../belt/helpers/cors_origin'
@@ -14,6 +15,9 @@ module BeltController
     include Belt::Helpers::Response
     include Belt::Rendering
     include ImplicitResponse
+    # Cognito identity: current_user, authenticate_user!, cognito_admin?.
+    # Inert unless the app declares `cognito_authenticatable` on a model.
+    include Belt::Authentication::Controller
 
     attr_reader :event, :body
 

data/lib/belt_controller/implicit_response.rb

@@ -8,6 +8,7 @@ module BeltController
     FRAMEWORK_IVARS = %i[
       @event @raw_body @params @current_action @current_user_id @user_groups
       @logger @__assigns_before @__response_status
+      @current_user @cognito_claims @cognito_groups
     ].freeze
 
     private

data/lib/templates/generate/auth/user_model.rb.erb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# <%= @user_class %> — a human who signs into this app. One row per Cognito user.
+#
+# Cognito owns authentication (passwords, MFA, the `admins` group). `cognito_authenticatable`
+# supplies everything derived from a token — the `sub` as primary key, email/name/role,
+# just-in-time provisioning, an EmailIndex GSI. Run `belt explain authentication` for the
+# full list.
+#
+# Add your own domain below: associations, per-tenant roles, whatever this app needs to
+# know about a person that Cognito doesn't.
+class <%= @user_class %> < ApplicationRecord
+  cognito_authenticatable
+
+  # has_many :memberships, foreign_key: 'cognito_sub', index: 'CognitoIndex'
+
+  # Runs whenever an identity is resolved from a token — first sight and every request
+  # after. Override to bind pending invitations, seed a workspace, and so on.
+  # def after_cognito_sync
+  # end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.3.44
+  version: 0.4.1
 platform: ruby
 authors:
 - Stowzilla
@@ -102,6 +102,13 @@ files:
 - lib/belt/action_router.rb
 - lib/belt/assets/belt-default.jpg
 - lib/belt/assets/welcome.css
+- lib/belt/authentication.rb
+- lib/belt/authentication/claims.rb
+- lib/belt/authentication/cognito_authenticatable.rb
+- lib/belt/authentication/cognito_authenticatable/class_methods.rb
+- lib/belt/authentication/configuration.rb
+- lib/belt/authentication/controller.rb
+- lib/belt/authentication/model_macro.rb
 - lib/belt/cli.rb
 - lib/belt/cli/apex_dns_sync.rb
 - lib/belt/cli/app_detection.rb
@@ -149,6 +156,7 @@ files:
 - lib/belt/cli/zip_artifact_builder.rb
 - lib/belt/configuration.rb
 - lib/belt/controllers/welcome_controller.rb
+- lib/belt/docs/authentication.md
 - lib/belt/docs/backups.md
 - lib/belt/docs/console.md
 - lib/belt/docs/controllers.md
@@ -161,6 +169,7 @@ files:
 - lib/belt/docs/plugins.md
 - lib/belt/docs/routing.md
 - lib/belt/docs/structure.md
+- lib/belt/errors.rb
 - lib/belt/helpers/cors_origin.rb
 - lib/belt/helpers/error_logging.rb
 - lib/belt/helpers/response.rb
@@ -207,6 +216,7 @@ files:
 - lib/templates/generate/auth/frontend/apiClient.js
 - lib/templates/generate/auth/frontend/auth.css
 - lib/templates/generate/auth/frontend/auth.js
+- lib/templates/generate/auth/user_model.rb.erb
 - lib/templates/generate/controller.rb.erb
 - lib/templates/generate/model.rb.erb
 - lib/templates/module/dns.tf.erb