belt 0.3.44 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7977614906b8f7154ca9e00597f1eb5744bc00ac6814985cfda98a16687d5992
-  data.tar.gz: d60ca2ff84dec2ce5d8b6ee97be3f9ef189fc455881e30b4877a37ae3dafef36
+  metadata.gz: 5a04110a957fa2d24cbca0245df1aa6aa421547ac140467cb5e6a15e9d0e1fb1
+  data.tar.gz: 17ffdd470fe0dd613ac82cd0554c12146fb527ee1a6ccd179f3de4b3e3024eab
 SHA512:
-  metadata.gz: b8cf0deed02541a8775b7f4000ba8f5336d09572d6752520bd5191407fd40b97412d5d8c2ee19790b6e8445231be9ffedbd09688c0233b642a96d2ba4494a38c
-  data.tar.gz: 025eb3373be5e8c345b29525fd6f81c2e21581b2b044d66dab03482b838e7e491556e6669b099cd128c0b5e5965b29a1ea741761c741b8dee5c489c7f587c34d
+  metadata.gz: 540c4da110ef61d412c09af5ce4db33bd534ec460d636ac2988e9784cb0fc58ac54e6cd9eeb201b48f863832d7d936ae5677bbcb78d37e702f04915e234ee230
+  data.tar.gz: ecc50065fcff0b93904c89cbc8c0e3c1a0c45e8f54c7c12af80d9546d894ed12b0a9f8103f8ca5eae3623c1cbd0e38d703137acf86e242ca9fe05946734ac28f

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.4.0
+
+### New Features
+
+- **`cognito_authenticatable` — Cognito identity in one line.** Everything an app used
+  to hand-write to turn a JWT into a user record now lives in the gem, Devise-style:
+
+  ```ruby
+  class User < ApplicationRecord
+    cognito_authenticatable
+  end
+  ```
+
+  That supplies the Cognito `sub` as primary key, the identity attributes
+  (`email`, `name`, `role`, `email_verified`, `last_seen_on`), an `EmailIndex` GSI,
+  `.sync_from_claims!` / `.for_sub` / `.for_email`, and `#admin?`. The app's model is
+  left holding only the app's own domain.
+
+  Controllers get `current_user`, `user_signed_in?`, `authenticate_user!`, and
+  `cognito_admin?` with no `include` and no configuration — `BeltController::Base`
+  mixes them in. Both token shapes are handled (a pre-verified API Gateway authorizer
+  claim set, or a raw `Authorization: Bearer` ID token the Lambda decodes and checks
+  for expiry, issuer, and `token_use`).
+
+  Rows are provisioned just-in-time on the first authenticated request and refreshed
+  only on drift, so an unchanged user costs one `GetItem` and no write. Hook your own
+  behaviour off that moment with `#after_cognito_sync`.
+
+  Options: `roles:`, `default_role:`, `email_index:`. Configure with
+  `Belt.configure { |c| c.authentication.user_class = 'Account' }`. Full docs:
+  `belt explain authentication`.
+
+- **`belt generate auth` scaffolds the user model.** It writes `lambda/models/user.rb`
+  (never overwriting an existing one) and regenerates `dynamodb.tf` so the `users`
+  table and its `EmailIndex` exist. `belt setup tables` now recognizes the macro, so a
+  model that declares `cognito_authenticatable` gets its GSI without an explicit
+  `indexes()` call.
+
+### Bug Fix
+
+- **`belt setup tables` respected `belongs_to ..., index: false`.** It didn't. ActiveItem
+  skips registering an association index when told to, but the table generator created
+  the convention GSI anyway — on a `fooId` attribute the model never writes, so the
+  index silently indexed nothing while costing storage. It now skips those declarations.
+  Regenerating `dynamodb.tf` in a project that uses `index: false` will therefore drop
+  the dead GSIs; that's a real (if harmless) Terraform diff, so look before you apply.
+
+### Internal
+
+- `Belt::AuthenticationError` and friends moved to `lib/belt/errors.rb` so they can be
+  required without pulling in the whole gem. No API change.
+
+### Upgrading
+
+- Upgrade is additive — nothing breaks by bumping to 0.4.0. To adopt
+  `cognito_authenticatable` in an existing app (and for the one `index: false` diff to
+  watch even if you don't), see [UPGRADING.md](UPGRADING.md).
+
 ## 0.3.43
 
 ### Bug Fix

data/README.md

@@ -256,6 +256,46 @@ end
 - **Scope in nested context**: Group routes with shared path prefix, controller, tables, or auth
 - **Singular `resource`**: For nested resources without an `:id` (billing, profile, etc.)
 
+## Authentication
+
+Cognito owns authentication. Belt owns the record of the human it authenticated:
+
+```ruby
+class User < ApplicationRecord
+  cognito_authenticatable
+end
+```
+
+One line supplies the Cognito `sub` as primary key, the identity attributes
+(`email`, `name`, `role`, `email_verified`, `last_seen_on`), an `EmailIndex` GSI,
+just-in-time provisioning from a token, and `#admin?` for platform staff. Your model is
+left holding only your own domain.
+
+Controllers get it for free — no `include`, no configuration:
+
+```ruby
+class ProfilesController < ApplicationController
+  before_action :authenticate_user!
+
+  def show
+    @profile = current_user
+  end
+end
+```
+
+| | |
+|---|---|
+| `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? |
+
+`belt generate auth` creates the user pool *and* scaffolds the model and its table.
+Full details — configuration, the `after_cognito_sync` hook, platform staff, and how
+both token shapes are handled — in `belt explain authentication`.
+
+Upgrading an existing app to Cognito auth? See [UPGRADING.md](UPGRADING.md).
+
 ## BeltController Features
 
 ### Callbacks

data/lib/belt/authentication/claims.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'base64'
+
+module Belt
+  module Authentication
+    # Reads Cognito claims off a Lambda event.
+    #
+    # Two shapes have to be handled, because a route can be authenticated either way:
+    #
+    #   1. API Gateway Cognito authorizer — claims arrive pre-verified under
+    #      requestContext.authorizer.claims, with every value flattened to a String.
+    #   2. A raw `Authorization: Bearer <id token>` header — the Lambda decodes it.
+    #
+    # Case 2 is signature-unverified by design: when a Cognito authorizer is attached,
+    # the gateway has already checked the signature and an unsigned token never reaches
+    # us. What we can still check cheaply is checked (structure, expiry, issuer, token
+    # use), which is what stops an expired or foreign token from being waved through on
+    # routes that read the header directly.
+    module Claims
+      # Cognito sends `cognito:groups` as a JSON array in the raw token, but API
+      # Gateway flattens it to a string — "[admins, members]" or "admins,members".
+      GROUPS_CLAIM = 'cognito:groups'
+
+      TRUTHY = [true, 'true', 1, '1'].freeze
+
+      class << self
+        # Claims for this request, or nil if there is no usable Cognito identity.
+        def from_event(event, issuer: nil)
+          authorizer = event.dig('requestContext', 'authorizer', 'claims')
+          return authorizer if authorizer
+
+          token = bearer_token(event)
+          return nil unless token
+
+          decode(token, issuer: issuer)
+        end
+
+        # The raw Bearer credential, whatever it is. Callers that only want Cognito
+        # tokens rely on #decode rejecting anything that isn't one — an app's own API
+        # key scheme can share the header without special-casing here.
+        def bearer_token(event)
+          header = authorization_header(event)
+          return nil unless header&.start_with?('Bearer ')
+
+          token = header.sub('Bearer ', '').strip
+          token.empty? ? nil : token
+        end
+
+        def authorization_header(event)
+          headers = event['headers'] || {}
+          headers['Authorization'] || headers['authorization']
+        end
+
+        # Decode a Cognito ID token's payload, rejecting it unless it is one.
+        # Returns nil rather than raising: a bad token means "no identity", and every
+        # caller here is deciding whether an identity exists.
+        def decode(token, issuer: nil)
+          payload = payload_segment(token)
+          return nil unless payload
+
+          claims = JSON.parse(payload)
+          return nil unless claims.is_a?(Hash)
+          return nil if expired?(claims)
+          return nil unless issuer_matches?(claims, issuer)
+          return nil unless id_token?(claims)
+
+          claims
+        rescue ArgumentError, JSON::ParserError
+          nil
+        end
+
+        def groups(claims)
+          parse_groups(claims && claims[GROUPS_CLAIM])
+        end
+
+        def parse_groups(raw)
+          return [] if raw.nil?
+          return raw.map(&:to_s) if raw.is_a?(Array)
+
+          # Strip only the wrapping brackets Cognito uses for the space/comma-separated
+          # group list (e.g. "[admins, editors]"), not brackets anywhere in the string.
+          raw.to_s.sub(/\A\[/, '').sub(/\]\z/, '').split(',').map(&:strip).reject(&:empty?)
+        end
+
+        # Booleans arrive as JSON booleans from a decoded token and as strings from
+        # API Gateway authorizer claims.
+        def truthy?(value)
+          TRUTHY.include?(value)
+        end
+
+        private
+
+        def payload_segment(token)
+          parts = token.to_s.split('.')
+          return nil unless parts.length == 3
+
+          segment = parts[1]
+          segment += '=' * (4 - (segment.length % 4)) if (segment.length % 4) != 0
+          Base64.urlsafe_decode64(segment)
+        end
+
+        def expired?(claims)
+          exp = claims['exp']
+          !exp.nil? && Time.now.to_i > exp.to_i
+        end
+
+        def issuer_matches?(claims, issuer)
+          return true if issuer.nil?
+
+          claims['iss'] == issuer
+        end
+
+        # Belt authenticates with ID tokens; an access token carries no email/name and
+        # must not stand in for one.
+        def id_token?(claims)
+          use = claims['token_use']
+          use.nil? || use == 'id'
+        end
+      end
+    end
+  end
+end

data/lib/belt/authentication/cognito_authenticatable/class_methods.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Belt
+  module Authentication
+    module CognitoAuthenticatable
+      # Class-side of cognito_authenticatable: the schema knobs the macro sets, and the
+      # lookups that turn a token into a record.
+      module ClassMethods
+        attr_writer :cognito_roles, :cognito_default_role, :cognito_email_index
+
+        # Allowed values for `role`. Set by the macro's `roles:` option.
+        def cognito_roles
+          @cognito_roles || ROLES
+        end
+
+        # Role given to a newly provisioned user.
+        def cognito_default_role
+          @cognito_default_role || DEFAULT_ROLE
+        end
+
+        # GSI used for email lookups, or false if the app doesn't need them.
+        def cognito_email_index
+          return @cognito_email_index if defined?(@cognito_email_index)
+
+          DEFAULT_EMAIL_INDEX
+        end
+
+        def cognito_email_index_definition
+          index = cognito_email_index
+          return {} unless index
+
+          { index.to_s => { partition_key: ATTRIBUTE_MAP['email'] } }
+        end
+
+        # Look up by Cognito sub. Returns nil rather than raising — callers are asking
+        # whether the user exists yet, not asserting that they do.
+        def for_sub(sub)
+          id = sub.to_s
+          return nil if id.empty?
+
+          find(id)
+        rescue ActiveItem::RecordNotFound
+          nil
+        end
+
+        def for_email(email)
+          normalized = normalize_cognito_email(email)
+          return nil if normalized.empty?
+
+          index = cognito_email_index
+          index ? find_by(email: normalized, index: index.to_s) : find_by(email: normalized)
+        end
+
+        # Provision-or-refresh the row for the identity on this request.
+        #
+        # Called once per authenticated request, so it is deliberately write-averse: an
+        # unchanged user costs one GetItem and no write. Only real drift (name changed
+        # in Cognito, staff group granted or revoked, first sighting today) writes.
+        #
+        # @param sub [String] Cognito `sub` — becomes the primary key.
+        # @param admin [Boolean] Whether the token carries a staff Cognito group.
+        #   Cognito stays the source of truth, `role` only mirrors it, and passing
+        #   false demotes — so removal from the group takes effect on the next request.
+        # @return [self, nil] nil when there is no usable sub.
+        def sync_from_claims!(sub:, email: nil, name: nil, admin: false, email_verified: false)
+          id = sub.to_s
+          return nil if id.empty?
+
+          existing = for_sub(id)
+          attrs = cognito_claim_attributes(
+            email: email, name: name, admin: admin, email_verified: email_verified
+          )
+
+          user = existing ? refresh_from_cognito(existing, attrs) : provision_from_cognito(id, attrs)
+          user&.after_cognito_sync
+          user
+        end
+
+        def normalize_cognito_email(email)
+          email.to_s.strip.downcase
+        end
+
+        private
+
+        def cognito_claim_attributes(email:, name:, admin:, email_verified:)
+          normalized_email = normalize_cognito_email(email)
+
+          {
+            email: normalized_email.empty? ? nil : normalized_email,
+            name: cognito_display_name(name, normalized_email),
+            role: admin ? ADMIN_ROLE : cognito_default_role,
+            email_verified: Claims.truthy?(email_verified),
+            last_seen_on: Time.now.utc.strftime('%Y-%m-%d')
+          }.compact
+        end
+
+        # The `name` claim is optional — Cognito's hosted signup UI doesn't collect it
+        # unless configured — so fall back to the email local part. Better than a blank
+        # row in an admin screen.
+        def cognito_display_name(name, normalized_email)
+          given = name.to_s.strip
+          return given unless given.empty?
+          return nil if normalized_email.empty?
+
+          normalized_email.split('@').first
+        end
+
+        def provision_from_cognito(id, attrs)
+          create!(attrs.merge(id: id))
+        rescue ActiveItem::RecordInvalid
+          # Two concurrent first requests from the same new user: DynamoDB's
+          # attribute_not_exists condition rejects the loser, surfacing as an
+          # "already exists" validation error. The row we wanted now exists.
+          for_sub(id)
+        end
+
+        # Write only what actually changed. `last_seen_on` is a date precisely so an
+        # active session doesn't generate a write per request.
+        def refresh_from_cognito(user, attrs)
+          drift = attrs.reject { |attr, value| user.public_send(attr) == value }
+          return user if drift.empty?
+
+          user.update!(drift)
+          user
+        end
+      end
+    end
+  end
+end

data/lib/belt/authentication/cognito_authenticatable.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Belt
+  module Authentication
+    # Everything a Belt app needs to know about a Cognito-authenticated human,
+    # without writing any of it.
+    #
+    #   class User < ApplicationRecord
+    #     cognito_authenticatable
+    #   end
+    #
+    # What that gets you:
+    #
+    #   * Primary key **is** the Cognito `sub`. Resolving the caller is one GetItem,
+    #     and the sub becomes a usable foreign key everywhere else in the schema.
+    #   * Attributes: email, name, role, email_verified, last_seen_on.
+    #   * An `EmailIndex` GSI, so invitations (addressed to an email before the invitee
+    #     has an account) can find their person.
+    #   * `.sync_from_claims!` — just-in-time provisioning from a token, write-averse
+    #     enough to sit on the authenticated request path.
+    #   * `#admin?` — platform staff, mirrored from a Cognito group on every request.
+    #
+    # Options:
+    #
+    #   cognito_authenticatable roles: %w[member admin support],  # default member/admin
+    #                           default_role: 'member',
+    #                           email_index: 'PeopleEmailIndex'   # or false to skip
+    #
+    # The app's own domain stays the app's: memberships, orgs, plans, per-tenant roles.
+    # This concern only owns identity.
+    module CognitoAuthenticatable
+      extend ActiveSupport::Concern
+
+      # Platform-wide role. `admin` means staff — someone who can see across tenants.
+      # Not to be confused with a per-tenant role, which the app models itself.
+      ROLES = %w[member admin].freeze
+      ADMIN_ROLE = 'admin'
+      DEFAULT_ROLE = 'member'
+      DEFAULT_EMAIL_INDEX = 'EmailIndex'
+
+      # DynamoDB attribute names for the identity attributes. Snake_case, not
+      # ActiveItem's default camelCase, so they read the same in the console, in
+      # `dynamodb.tf`, and in a GSI key definition.
+      ATTRIBUTE_MAP = {
+        'id' => 'id',
+        'email' => 'email',
+        'name' => 'name',
+        'role' => 'role',
+        'email_verified' => 'email_verified',
+        'last_seen_on' => 'last_seen_on'
+      }.freeze
+
+      # Merges the identity schema into whatever the model declares itself, in either
+      # order. Prepended to the model's singleton rather than assigned in `included do`
+      # because ActiveItem's `indexes` / `dynamo_attribute_map` writers replace instead
+      # of merge — an app declaring its own index after the macro would otherwise drop
+      # EmailIndex on the floor, silently, until a lookup failed in production.
+      #
+      # App declarations win on conflict.
+      module SchemaDefaults
+        def indexes(definitions = nil)
+          return super if definitions
+
+          cognito_email_index_definition.merge(super())
+        end
+
+        def dynamo_attribute_map(mappings = nil)
+          return super if mappings
+
+          ATTRIBUTE_MAP.merge(super())
+        end
+      end
+
+      included do
+        attr_accessor :email,          # Cognito `email` claim, normalized to lowercase.
+                      :name,           # Cognito `name` claim, or the email local part.
+                      :role,           # Platform role — see ROLES.
+                      :email_verified, # Cognito `email_verified`.
+                      :last_seen_on    # ISO date, not a timestamp — see .sync_from_claims!
+
+        # Email is deliberately NOT validated. It comes from a verified token rather
+        # than a form, and this model is written on the authentication path: a
+        # validation failure here would 500 every request instead of rejecting input.
+        validates :role, presence: true, inclusion: { in: ->(record) { record.class.cognito_roles } }
+
+        singleton_class.prepend(SchemaDefaults)
+      end
+
+      # Platform staff. Mirrored from the Cognito group on every request, so a
+      # revocation takes effect on the caller's next call.
+      def admin?
+        role.to_s == ADMIN_ROLE
+      end
+
+      def email_verified?
+        Claims.truthy?(email_verified)
+      end
+
+      # Hook for whatever the app wants to happen each time an identity is resolved
+      # from a token — binding pending invitations, seeding a default workspace, an
+      # audit trail. No-op by default; override in the model.
+      def after_cognito_sync; end
+    end
+  end
+end
+
+require_relative 'cognito_authenticatable/class_methods'

data/lib/belt/authentication/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Belt
+  module Authentication
+    # Authentication settings, reachable from the runtime config:
+    #
+    #   Belt.configure do |config|
+    #     config.authentication.user_class  = 'Account'   # default: 'User'
+    #     config.authentication.admin_groups = %w[staff]  # default: ['admins']
+    #   end
+    #
+    # Every setting has a working default, so an app that names its model `User` and
+    # its Cognito group `admins` configures nothing.
+    class Configuration
+      # Cognito groups whose members are platform staff. NOT a per-tenant role — that
+      # belongs to the app's own domain (a membership, an org role, whatever).
+      DEFAULT_ADMIN_GROUPS = %w[admins].freeze
+
+      DEFAULT_USER_CLASS = 'User'
+
+      def initialize
+        @user_class = nil
+        @admin_groups = nil
+        @issuer = nil
+      end
+
+      attr_writer :admin_groups, :issuer
+
+      # Accepts a class or a name. Stored as a name and resolved on demand so the
+      # setting can be declared before the model file is loaded.
+      def user_class=(value)
+        @user_class = value.is_a?(Class) ? value.name : value&.to_s
+      end
+
+      def user_class_name
+        @user_class || DEFAULT_USER_CLASS
+      end
+
+      # The model backing #current_user, or nil if the app hasn't defined one.
+      # Nil is a legitimate answer: an app can use Belt's Cognito plumbing without
+      # persisting a user row at all.
+      def user_class
+        Object.const_get(user_class_name)
+      rescue NameError
+        nil
+      end
+
+      def admin_groups
+        return Array(@admin_groups).map(&:to_s) if @admin_groups
+
+        configured = ENV.fetch('ADMIN_COGNITO_GROUPS', '').to_s.split(',').map(&:strip).reject(&:empty?)
+        configured.empty? ? DEFAULT_ADMIN_GROUPS : configured
+      end
+
+      # Expected `iss` claim. Derived from the Cognito env vars Belt's Terraform module
+      # already exports, so apps don't restate it. Nil disables the issuer check —
+      # which is the right behaviour locally and in tests, where there is no pool.
+      def issuer
+        return @issuer if @issuer
+
+        pool_id = ENV.fetch('COGNITO_USER_POOL_ID', nil)
+        return nil if pool_id.to_s.empty?
+
+        region = ENV['COGNITO_REGION'] || ENV['AWS_REGION'] || 'us-east-1'
+        "https://cognito-idp.#{region}.amazonaws.com/#{pool_id}"
+      end
+    end
+  end
+end

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/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/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.0'
 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.0
 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