belt 0.3.44 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7977614906b8f7154ca9e00597f1eb5744bc00ac6814985cfda98a16687d5992
-  data.tar.gz: d60ca2ff84dec2ce5d8b6ee97be3f9ef189fc455881e30b4877a37ae3dafef36
+  metadata.gz: 846db7f1373b5bd98f3e795404b1f157825f5dd94541bd46aa76e3510ba89adf
+  data.tar.gz: 251135fea6ee2d3d55e7dcdf46b98460ddc3df50fa1e4113b561f721755c935d
 SHA512:
-  metadata.gz: b8cf0deed02541a8775b7f4000ba8f5336d09572d6752520bd5191407fd40b97412d5d8c2ee19790b6e8445231be9ffedbd09688c0233b642a96d2ba4494a38c
-  data.tar.gz: 025eb3373be5e8c345b29525fd6f81c2e21581b2b044d66dab03482b838e7e491556e6669b099cd128c0b5e5965b29a1ea741761c741b8dee5c489c7f587c34d
+  metadata.gz: 60b0ecf81e375ea1c219c84ccf7f90d568437cc81507c708ec56a40f903178e0611e5b6be03e1e71185ce66263d1ec0c12ddee8e1a4d2cfdc26f99dba4828c48
+  data.tar.gz: fb3fa14275a68c7e79892504d0fef2cbe86727225033a7d7bc3c1272b963413b5ed7259c3a5c2f1e202770d16b0234ff242571e4d2b7abed50a040090da250e1

data/CHANGELOG.md

@@ -1,5 +1,116 @@
 # Changelog
 
+## Unreleased
+
+### Bug Fix
+
+- **Apply environment AWS profile in `belt deploy frontend`, `belt frontend env`, `belt logs`, and `belt server`**:
+  Standalone frontend deployment (`belt deploy frontend <env>`), frontend env generation (`belt frontend env <env>`),
+  log viewing (`belt logs`), and the local dev server (`belt server`) now load `infrastructure/<env>/belt.rb`
+  and apply its configured `aws_profile` and environment variables. Previously, running `belt deploy frontend <env>`
+  directly would query Terraform outputs without the environment's AWS profile, causing a 403 against remote S3
+  state backends and aborting with `Error: Could not determine S3 bucket. Run belt apply <env> first.`
+
+## 0.4.1
+
+### Feature
+
+- **`belt dns doctor`**: New diagnostic command that checks DNS health across all
+  environments. Shows zone status, NS delegation, ACM certificate state, and
+  API Gateway custom domain configuration. Use `--env prod` to check a specific
+  environment only.
+
+  ```bash
+  belt dns doctor
+  belt dns doctor --env prod
+  ```
+
+- **`belt dns sync-validation`**: New command to sync ACM validation CNAMEs from
+  an environment's zone to the root zone. Needed for apex domains (e.g., prod →
+  `example.com`) where the root zone is authoritative for the apex domain.
+
+  ```bash
+  belt dns sync-validation prod
+  ```
+
+- **Auto-sync ACM validation for apex environments**: `belt deploy prod` now
+  automatically syncs ACM validation CNAMEs to the root zone when deploying
+  environments that use the apex domain. No manual intervention needed — the
+  "prod is special" logic is handled by Belt internally.
+
+  This fixes the issue where prod ACM certificates would timeout waiting for
+  validation because the validation CNAMEs were created in the prod zone, but
+  ACM validates against the authoritative zone (the root zone managed by
+  `infrastructure/dns`).
+
+### Bug Fix
+
+- **Fix misleading nested environment domain announcement**: `belt generate
+  environment <name> <parent>` printed `Domain will be:
+  api.<env>.<parent>.<domain>`, but the deployed infrastructure actually uses
+  the single-level `api-<env>.<parent>.<domain>` form (the `api-` prefix keeps
+  the host under the parent's `*.<parent>.<domain>` wildcard cert). The message
+  now matches the real deployed domain. Infrastructure was already correct —
+  only the CLI output was wrong.
+
+## 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