belt 0.2.10 → 0.2.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a550043d0d16c901e656de4a9d89a0f473d77778121e2b27fb8791f3edf74d4
-  data.tar.gz: f9404b6e69d725650ee612af06b96917886d2856fca14955bb99cb9555811dcd
+  metadata.gz: 43ae84461595be08ca6caada3afd148ccfa0db94bfc2e2bd864a9b466d41f087
+  data.tar.gz: 1f33826b8c7a7b068458db8ca38aa9910079e16f04c3c5c727550f084ed85075
 SHA512:
-  metadata.gz: e719bed32a829bf952c22885d63a1415ea292c3b1770a7f7bdb398ef874a5182a1b8208654e2672d6d7fcccbb4b2e9f24a82186708ed3982d9ca7ec94d9bedbf
-  data.tar.gz: 32fa436e2a97b5d3597af8d2afcfb8657c5de91f12a01b551d8368be97a80fdfd544e5b6b711a930ff741c1e8228d393088893700f13c719b454b59e01c3d6a0
+  metadata.gz: 81532edca53a084bdd6aabf5e7027fd1653ec0fc4c592b0bdb60374283c7c59512a2217405d3a19f32a975bcbcbbebdf9f9a97d952a25b1567e05af8e2cb879d
+  data.tar.gz: d5ff609d6526f8cc59964df6da091a43150eca9d1c6f625dee27b070db0c56bd90ef58ef11c42f57e27259f169c477a4c1c548f9ca0f4c4f916c8bea540763bb

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.11
+
+### Security hardening
+
+- **CORS origin validation**: format validation (scheme required, no paths/queries/fragments), length limit (253 chars) to prevent ReDoS, restrict wildcard matching to valid subdomain chars `[a-z0-9-]`.
+- **Security headers** on all responses: `X-Content-Type-Options: nosniff`, `Vary: Origin`; HTML responses also get `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`.
+- **Path traversal protection** in `ActionRouter`: strict regex for controller names, reject `..` sequences / absolute paths / backslashes, `realpath` validation in `resolve_from_paths`.
+- **Request body size limit** (10 MB): returns 413 for oversized bodies; proper 400 for invalid JSON.
+
+### Safe `belt destroy environment`
+
+Previously `belt destroy environment <name>` immediately deleted the infrastructure directory with no checks — leaving orphaned AWS resources.
+
+Now the command:
+1. Checks if Terraform state exists (local `.terraform` dir or remote state)
+2. If state found, prompts user to run `terraform destroy` first
+3. Requires explicit confirmation before deleting files
+4. Supports `--force` (skip prompts) and `--skip-terraform` flags
+
+### Environment generator state bucket fix
+
+The environment generator was writing `belt-terraform-state` as the backend bucket name, missing the account-ID suffix. Now resolves via sibling `backend.tf`, STS `get-caller-identity`, or placeholder (for later `belt setup state` patch).
+
+### Contributing & plugins
+
+- README: **Plugins** and **Contributing** sections — how to contribute to belt, how plugins register via `GeneratorRegistry`, layout used by `belt-messaging` / `belt-pay`, generator checklist for humans and agents.
+- **`belt plugin new <name>`** — scaffold a new plugin gem (gemspec, `Belt::<Name>` module, generator stub, RSpec, README, AGENTS.md), similar to `rails plugin new`.
+- **`AGENTS.md`** at the belt gem root — agent-oriented map of core layout, CLI, and the plugin/GeneratorRegistry contract (complements README).
+- Plugin scaffold includes **`AGENTS.md`** so new plugins match the agent guidance pattern already used by `belt new` apps.
+
 ## 0.2.10
 
 ### Quiet `belt new` (with optional verbose)

data/README.md

@@ -575,6 +575,175 @@ These are set via Terraform variables in each environment's `terraform.tfvars`.
 
 The backup phase reads table names from Terraform outputs. On a brand-new environment that has never been deployed, there are no outputs yet — Belt will warn and skip the backup phase gracefully. After the first successful deploy, backups run normally on subsequent deploys.
 
+## Plugins
+
+Belt is designed to stay lean. Optional capabilities ship as **separate gems** that plug into the CLI and runtime the same way Rails engines and generators do.
+
+### Official / example plugins
+
+| Gem | Purpose | Status |
+|-----|---------|--------|
+| [`belt-messaging`](https://github.com/stowzilla/belt-messaging) | Two-way SMS via AWS End User Messaging (Pinpoint) | Early (not production-hardened) |
+| [`belt-pay`](https://github.com/stowzilla/belt-pay) | Stripe payments & subscriptions | Early (not production-hardened) |
+
+Install a plugin in a Belt app:
+
+```ruby
+# Gemfile
+gem "belt-messaging"
+# gem "belt-pay"
+```
+
+```bash
+bundle install
+belt generate messaging   # or: belt g pay
+belt generate --help      # lists built-ins + gem generators
+```
+
+### How plugins register
+
+No central registry file, no initializer hook. Belt discovers generators by scanning loaded gems:
+
+1. Gem is in the app `Gemfile` and bundled
+2. Gem ships a file at `lib/belt/generators/<name>_generator.rb`
+3. Class lives in `Belt::Generators`, named `<Name>Generator`
+4. Implements `.run(args)` (required), `.destroy(args)` and `.description` (optional)
+
+That is the whole contract. After `bundle install`, `belt generate <name>` and `belt destroy <name>` just work.
+
+See `Belt::CLI::GeneratorRegistry` and the CHANGELOG entry for **0.1.13 Generator Extension API**.
+
+### Plugin layout (canonical)
+
+```
+belt-messaging/
+├── belt-messaging.gemspec
+├── lib/
+│   ├── belt-messaging.rb              # require entrypoint
+│   └── belt/
+│       ├── messaging.rb               # Belt::Messaging API
+│       ├── messaging/
+│       │   ├── configuration.rb
+│       │   ├── version.rb
+│       │   ├── controllers/           # default controllers (optional)
+│       │   └── templates/             # ERB templates for the generator
+│       │       ├── terraform/
+│       │       ├── lambda/
+│       │       ├── config/
+│       │       └── controllers/
+│       └── generators/
+│           └── messaging_generator.rb # ← auto-discovered
+└── spec/
+```
+
+**Runtime code stays in the gem.** Generators copy only what the host app must own (Terraform modules, Lambda entrypoints, optional controller overrides). Prefer gem defaults + `belt g <plugin> --controllers` over dumping everything into the app (same idea as `rails g devise:views`).
+
+### Creating a new plugin
+
+Scaffold a ready-to-fill gem (Rails-style `plugin new`):
+
+```bash
+belt plugin new notifications
+# → ./belt-notifications/
+
+belt plugin new pay --path ~/Code --summary "Stripe payments for Belt"
+# → ~/Code/belt-pay/
+```
+
+Then:
+
+```bash
+cd belt-notifications
+bundle install
+# implement lib/belt/notifications/* and the generator
+```
+
+Point a Belt app at it while developing:
+
+```ruby
+# In the app Gemfile
+gem "belt-notifications", path: "../belt-notifications"
+```
+
+```bash
+bundle install
+belt generate notifications
+```
+
+When packaging Lambdas, `belt deploy` vendors path gems into `vendor/cache` so conveyor-belt can package them.
+
+### Generator checklist (for humans and agents)
+
+A solid plugin generator typically:
+
+1. **Terraform module** → `infrastructure/modules/<name>/` (`main.tf`, `variables.tf`, `outputs.tf`)
+2. **Lambda config** → `config/lambda/<name>.yml` (timeout, memory, env, triggers)
+3. **Lambda entrypoint** → `lambda/<name>.rb` using `Belt::LambdaHandler`
+4. **Routes / schema** → inject into `config/routes.tf.rb` or `infrastructure/schema.tf.rb` when needed
+5. **Optional overrides** → `--controllers` flag for app-local subclasses
+6. **Destroy path** → `belt destroy <name>` removes what generate created
+7. **Help text** → `.description` + `--help` explaining what was installed and next steps
+
+Copy from `belt-messaging` or `belt-pay` rather than inventing a new structure.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/stowzilla/belt).
+
+### Development setup
+
+```bash
+git clone https://github.com/stowzilla/belt.git
+cd belt
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+### Guidelines
+
+1. **Branch from `master`** — open a PR against `master`
+2. **Keep changes focused** — one concern per PR when practical
+3. **Follow existing patterns** — look at neighboring files and `lib/belt/cli/` before inventing new ones
+4. **Tests + lint** — run `bundle exec rspec` and `bundle exec rubocop` before opening (or updating) a PR. CI requires both (plus `bundler-audit`); failing checks block merge on `master`
+5. **Changelog** — note user-facing changes in `CHANGELOG.md` under the next version / Unreleased
+6. **No secrets** — never commit AWS keys, tokens, or real account IDs
+
+### Project layout (for contributors)
+
+| Path | What lives there |
+|------|------------------|
+| `lib/belt.rb` | Public require entry |
+| `lib/belt/` | Framework core (controller, router, handler, observability) |
+| `lib/belt/cli/` | CLI commands (`new`, `generate`, `deploy`, `plugin`, …) |
+| `lib/belt_controller/` | `BeltController::Base` |
+| `lib/templates/` | ERB templates for `belt new`, generators, plugin scaffold |
+| `exe/belt` | CLI executable |
+| `spec/` | RSpec suite |
+| `AGENTS.md` | Agent-oriented map of this gem (layout, CLI, plugin contract) |
+
+AI / coding agents: start with **[AGENTS.md](AGENTS.md)**. Belt apps and plugins scaffolded by the CLI get their own `AGENTS.md` as well (`belt new`, `belt plugin new`).
+
+### Local gem development against an app
+
+```ruby
+# In a Belt app's Gemfile
+gem "belt", path: "../belt"
+```
+
+`belt deploy` detects `path:` gems and materializes them into `vendor/cache` for Lambda packaging so you can iterate without publishing a gem for every try.
+
+### Contributing a plugin
+
+Plugins are separate repositories (not vendored into this repo). To add a new first-class capability:
+
+1. `belt plugin new <name>` (or copy `belt-messaging` / `belt-pay`)
+2. Implement the runtime API + generator contract above
+3. Document install steps in the plugin README (`gem …` → `belt generate …`)
+4. Open a PR on the plugin repo; optionally link it from this README's plugin table
+
+Questions about plugin design or core changes: open a GitHub issue or discuss in the project Discord.
+
 ## License
 
 MIT

data/lib/belt/action_router.rb

@@ -102,15 +102,35 @@ module Belt
     end
 
     def dispatch_to_controller(route_info, event, body)
-      controller_class = resolve_controller(route_info[:controller])
+      controller_name = route_info[:controller]
+
+      # Prevent path traversal — controller names must be simple identifiers or single-level nested
+      unless valid_controller_name?(controller_name)
+        Belt::Observability::Logger.instance&.warn('Invalid controller name', controller: controller_name)
+        return error_response('Not found', 404, event)
+      end
+
+      controller_class = resolve_controller(controller_name)
       controller = controller_class.new(event: event, body: body)
 
-      controller_name = controller_class.name.split('::').last.gsub('Controller', '')
-      Belt::Observability::Logger.instance&.info("Processing by #{controller_name}##{route_info[:action]}")
+      class_label = controller_class.name.split('::').last.gsub('Controller', '')
+      Belt::Observability::Logger.instance&.info("Processing by #{class_label}##{route_info[:action]}")
 
       controller.dispatch(route_info[:action].to_sym)
     end
 
+    # Validate controller names to prevent path traversal.
+    # Allows: "posts", "admin/posts" (single nesting level, no dots or special chars)
+    def valid_controller_name?(name)
+      return false if name.nil? || name.empty?
+      return false if name.include?('..')
+      return false if name.start_with?('/') || name.end_with?('/')
+      return false if name.include?('\\')
+
+      # Allow only lowercase letters, digits, underscores, and a single forward slash for nesting
+      name.match?(%r{\A[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)?\z})
+    end
+
     def resolve_controller(controller_name)
       # Try namespace module first (app's own controllers)
       begin
@@ -137,10 +157,18 @@ module Belt
     def resolve_from_paths(controller_name)
       if controller_name.include?('/')
       end
-      file_name = "#{controller_name}_controller.rb"
+      file_name = "#{controller_name.gsub('/', '_')}_controller.rb"
 
       Belt.all_controller_paths.each do |path|
         full_path = File.join(path, file_name)
+
+        # Ensure resolved path stays within the allowed controller directory
+        begin
+          resolved = File.realpath(full_path)
+        rescue Errno::ENOENT, Errno::EACCES
+          next
+        end
+        next unless resolved.start_with?(File.realpath(path))
         next unless File.exist?(full_path)
 
         require full_path

data/lib/belt/cli/destroy_command.rb

@@ -44,10 +44,11 @@ module Belt
         when 'environment'
           name = args.shift
           if name.nil? || name.empty?
-            puts 'Usage: belt destroy environment <name>'
+            puts 'Usage: belt destroy environment <name> [--force] [--skip-terraform]'
             exit 1
           end
-          new(generator, name, []).destroy
+          flags = parse_environment_flags(args)
+          new(generator, name, [], **flags).destroy
         when 'frontend'
           new(generator, nil, []).destroy
         when 'views'
@@ -67,6 +68,19 @@ module Belt
         end
       end
 
+      def self.parse_environment_flags(args)
+        flags = { force: false, skip_terraform: false }
+        args.each do |arg|
+          case arg
+          when '--force', '-f'
+            flags[:force] = true
+          when '--skip-terraform'
+            flags[:skip_terraform] = true
+          end
+        end
+        flags
+      end
+
       def self.parse_field(arg)
         name, type = arg.split(':', 2)
         { name: name, type: type || 'string' }
@@ -84,26 +98,37 @@ module Belt
             resource      Alias for scaffold
             model         Remove an ActiveItem model
             controller    Remove a controller
-            environment   Remove a deployment environment directory
+            environment   Remove a deployment environment and tear down infrastructure
             frontend      Remove the frontend/ directory
             views         Remove React pages for a resource
 
+          Environment options:
+            --force, -f          Skip all prompts (CI mode)
+            --skip-terraform     Delete local files without running terraform destroy
+
           Examples:
             belt d scaffold post title:string body:text status:string
             belt d model user
             belt d controller comments
             belt d environment staging
+            belt d environment dev --skip-terraform
+            belt d environment dev --force
             belt d frontend
             belt d views post
 
           ⚠ This is destructive. Files will be permanently deleted.
+
+          For environments: if terraform state is detected, you'll be prompted to run
+          `terraform destroy` first to tear down cloud resources before removing files.
         HELP
       end
 
-      def initialize(generator, name, fields)
+      def initialize(generator, name, fields, force: false, skip_terraform: false)
         @generator = generator
         @name = name&.downcase&.gsub(/[^a-z0-9_]/, '_')
         @fields = fields
+        @force = force
+        @skip_terraform = skip_terraform
         @app_name = detect_namespace
         @singular_name = @name ? Belt::Inflector.singularize(@name) : nil
         @resource_name = @singular_name ? Belt::Inflector.pluralize(@singular_name) : nil
@@ -149,15 +174,99 @@ module Belt
 
       def destroy_environment
         dir = "infrastructure/#{@name}"
-        if Dir.exist?(dir)
-          FileUtils.rm_rf(dir)
-          @removed << dir
-          puts "  remove  #{dir}/"
-          puts "\n✓ Environment '#{@name}' destroyed!"
-        else
+
+        unless Dir.exist?(dir)
           puts "✗ Environment '#{@name}' not found at #{dir}/"
           exit 1
         end
+
+        # Check if terraform state exists (infra may still be live)
+        if !@skip_terraform && terraform_state_exists?(dir)
+          puts "⚠  Environment '#{@name}' appears to have active infrastructure."
+          puts "   Terraform state was found — resources may still be running.\n\n"
+
+          if @force
+            puts '   --force passed, skipping terraform destroy.'
+          else
+            puts '   Options:'
+            puts '     1) Run `terraform destroy` to tear down infrastructure first (recommended)'
+            puts '     2) Skip terraform and just delete the local files (--skip-terraform)'
+            puts "     3) Cancel\n\n"
+
+            print "   Run terraform destroy for '#{@name}'? [y/N/skip] "
+            response = $stdin.gets&.strip&.downcase
+
+            case response
+            when 'y', 'yes'
+              run_terraform_destroy(dir)
+            when 'skip', 's'
+              puts '   Skipping terraform destroy.'
+            else
+              puts 'Cancelled.'
+              exit 0
+            end
+          end
+        end
+
+        # Final confirmation before deleting files
+        unless @force
+          print "\nPermanently delete #{dir}/? [y/N] "
+          response = $stdin.gets&.strip&.downcase
+          unless response&.start_with?('y')
+            puts 'Cancelled.'
+            exit 0
+          end
+        end
+
+        FileUtils.rm_rf(dir)
+        @removed << dir
+        puts "  remove  #{dir}/"
+        puts "\n✓ Environment '#{@name}' destroyed!"
+      end
+
+      def terraform_state_exists?(dir)
+        # Check for local .terraform directory (initialized state)
+        return true if Dir.exist?(File.join(dir, '.terraform'))
+
+        # Check if backend.tf exists (remote state configured)
+        backend_file = File.join(dir, 'backend.tf')
+        return false unless File.exist?(backend_file)
+
+        # Try to query remote state — if terraform is initialized and state exists,
+        # the environment likely has live resources
+        Dir.chdir(dir) do
+          # Quick check: does `terraform show` return anything?
+          output = `terraform show -no-color 2>&1`
+          Process.last_status.success? && !output.strip.empty? && !output.include?('No state')
+        end
+      rescue StandardError
+        # If we can't determine state, assume it might exist and warn
+        true
+      end
+
+      def run_terraform_destroy(dir)
+        puts "\n━━━ terraform destroy (#{@name}) ━━━"
+
+        Dir.chdir(dir) do
+          # Initialize if needed
+          unless Dir.exist?('.terraform')
+            puts '  Initializing terraform...'
+            unless system('terraform', 'init', '-input=false')
+              puts "\n✗ terraform init failed. You may need to destroy manually:"
+              puts "  cd #{dir} && terraform init && terraform destroy"
+              exit 1
+            end
+          end
+
+          # Run destroy with auto-approve (user already confirmed)
+          unless system('terraform', 'destroy', '-auto-approve')
+            puts "\n✗ terraform destroy failed."
+            puts '  Infrastructure may still be running. Fix and retry, or use --skip-terraform.'
+            exit 1
+          end
+        end
+
+        puts '  ✓ Infrastructure destroyed.'
       end
 
       def destroy_frontend

data/lib/belt/cli/environment_command.rb

@@ -32,6 +32,7 @@ module Belt
         @domain = domain
         @quiet = quiet
         @announce = announce
+        @state_bucket = resolve_state_bucket
       end
 
       def generate
@@ -80,6 +81,37 @@ module Belt
         content = ERB.new(File.read(template_path), trim_mode: '-').result(binding)
         File.write(dest_path, content)
       end
+
+      # Resolve the state bucket name to use in backend.tf.
+      # Priority: existing sibling backend.tf → AWS account ID → bare placeholder.
+      def resolve_state_bucket
+        bucket_from_sibling || bucket_from_aws || 'belt-terraform-state'
+      end
+
+      def bucket_from_sibling
+        Dir.glob('infrastructure/*/backend.tf').each do |f|
+          match = File.read(f).match(/bucket\s*=\s*"([^"]+)"/)
+          next unless match
+          # Skip the bare placeholder — it means state wasn't set up yet
+          return match[1] unless match[1] == 'belt-terraform-state'
+        end
+        nil
+      end
+
+      def bucket_from_aws
+        require 'open3'
+        output, status = Open3.capture2e('aws', 'sts', 'get-caller-identity')
+        return nil unless status.success?
+
+        data = begin
+          JSON.parse(output)
+        rescue StandardError
+          nil
+        end
+        return nil unless data&.dig('Account')
+
+        "belt-terraform-state-#{data['Account']}"
+      end
     end
   end
 end