plutonium 0.41.1 → 0.42.0

data/docs/guides/user-invites.md

@@ -359,7 +359,7 @@ In your admin portal:
 ```ruby
 # Invites are scoped to the current entity
 # Admins see all pending invites for their organization
-Invites::UserInvite.pending.where(entity: current_entity)
+Invites::UserInvite.pending.where(entity: current_scoped_entity)
 ```
 
 ## Security Considerations

data/docs/reference/generators/index.md

@@ -410,6 +410,7 @@ Generate a complete multi-tenant SaaS setup with user, entity, and membership.
 rails generate pu:saas:setup --user Customer --entity Organization
 rails generate pu:saas:setup --user Customer --entity Organization --roles=member,admin,owner
 rails generate pu:saas:setup --user Customer --entity Organization --no-allow-signup
+rails generate pu:saas:setup --user Customer --entity Organization --api_client ApiClient
 ```
 
 #### Options
@@ -425,12 +426,15 @@ rails generate pu:saas:setup --user Customer --entity Organization --no-allow-si
 | `--user-attributes` | Additional user model attributes |
 | `--entity-attributes` | Additional entity model attributes |
 | `--membership-attributes` | Additional membership model attributes |
+| `--api_client NAME` | Generate an API client model for M2M auth |
+| `--api_client_roles` | Roles for API client (default: read_only,write,admin) |
 
 Creates:
 - User account model with Rodauth authentication
 - Entity model with unique name
 - Membership join model with role enum
 - Has-many-through associations with `dependent: :destroy`
+- (Optional) API client with HTTP Basic Auth, scoped to entity
 
 ### pu:saas:user
 
@@ -460,6 +464,45 @@ rails generate pu:saas:membership --user Customer --entity Organization
 rails generate pu:saas:membership --user Customer --entity Organization --roles=member,admin,owner
 ```
 
+### pu:saas:api_client
+
+Generate an API client account for machine-to-machine authentication.
+
+```bash
+rails generate pu:saas:api_client ApiClient
+rails generate pu:saas:api_client ApiClient --entity=Organization
+rails generate pu:saas:api_client ApiClient --entity=Organization --roles=read_only,write,admin
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--entity NAME` | Entity model to scope API clients to |
+| `--roles` | Available roles (default: read_only,write,admin) |
+| `--extra_attributes` | Additional model attributes |
+| `--dest` | Destination package |
+
+Creates:
+- Rodauth account with HTTP Basic Auth (login + auto-generated password)
+- Create and Disable interactions
+- Rake task for CLI creation (`rake api_clients:create`)
+- (If entity) Membership model with roles
+
+#### Usage
+
+```bash
+# Create via rake task
+rake api_clients:create LOGIN=my-service
+
+# With entity scoping
+rake api_clients:create LOGIN=my-service ORGANIZATION=acme ROLE=write
+```
+
+::: tip Credentials
+Credentials are displayed once on creation and cannot be retrieved later. The password is auto-generated using `SecureRandom.base64(32)`.
+:::
+
 ## Core Generators
 
 ### pu:core:install

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.41.0)
+    plutonium (0.41.1)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.41.0)
+    plutonium (0.41.1)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.41.0)
+    plutonium (0.41.1)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 9.0)

data/lib/generators/pu/invites/templates/app/interactions/invite_user_interaction.rb.tt

@@ -3,6 +3,8 @@
 class <%= entity_model %>::InviteUserInteraction < Plutonium::Resource::Interaction
   include Plutonium::Invites::Concerns::InviteUser
 
+  presents label: "Invite <%= user_model.underscore.humanize.titleize %>", icon: Phlex::TablerIcons::Mail
+
   attribute :role
   input :role, as: :select, choices: Invites::UserInvite.roles.keys
 <% if membership_model != "EntityUser" || user_model != "User" -%>

data/lib/generators/pu/invites/templates/app/interactions/user_invite_user_interaction.rb.tt

@@ -3,13 +3,15 @@
 class <%= user_model %>::InviteUserInteraction < Plutonium::Resource::Interaction
   include Plutonium::Invites::Concerns::InviteUser
 
+  presents label: "Invite <%= user_model.underscore.humanize.titleize %>", icon: Phlex::TablerIcons::Mail
+
   attribute :role
   input :role, as: :select, choices: Invites::UserInvite.roles.keys
 
   private
 
   def entity
-    current_entity
+    current_scoped_entity
   end
 <% if membership_model != "EntityUser" -%>
 

data/lib/generators/pu/invites/templates/invitable/invite_user_interaction.rb.tt

@@ -3,12 +3,14 @@
 class <%= model_class %>::InviteUserInteraction < Plutonium::Resource::Interaction
   include Plutonium::Invites::Concerns::InviteUser
 
+  presents label: "Invite <%= user_model.underscore.humanize.titleize %>", icon: Phlex::TablerIcons::Mail
+
   input :email
 
   private
 
   def entity
-    current_entity
+    current_scoped_entity
   end
 
   def invitable

data/lib/generators/pu/lib/plutonium_generators/concerns/package_selector.rb

@@ -22,7 +22,7 @@ module PlutoniumGenerators
 
       def available_packages
         @available_packages ||= begin
-          packages = Dir["packages/*"].map { |dir| dir.gsub "packages/", "" }
+          packages = Dir[Rails.root.join("packages", "*")].map { |dir| File.basename(dir) }
           packages - reserved_packages
         end
       end

data/lib/generators/pu/rodauth/account_generator.rb

@@ -6,12 +6,14 @@ require "securerandom"
 require "#{__dir__}/concerns/configuration"
 require "#{__dir__}/concerns/account_selector"
 require "#{__dir__}/concerns/feature_selector"
+require "#{__dir__}/concerns/gem_helpers"
 
 module Pu
   module Rodauth
     class AccountGenerator < ::Rails::Generators::Base
       include Concerns::AccountSelector
       include Concerns::FeatureSelector
+      include Concerns::GemHelpers
 
       source_root "#{__dir__}/templates"
 
@@ -21,12 +23,20 @@ module Pu
       class_option :extra_attributes, type: :array, default: [],
         desc: "Additional attributes to add to the account model (e.g., role:integer)"
 
+      class_option :login_column, type: :string, default: "email",
+        desc: "Name of the login column (default: email)"
+
       def install_dependencies
+        gems = []
+        gems << "jwt" if jwt? || jwt_refresh?
+        gems << "rotp" if otp?
+        gems << "rqrcode" if otp?
+        gems << "webauthn" if webauthn? || webauthn_autofill?
+        gems = gems.reject { |g| gem_in_bundle?(g) }
+        return if gems.empty?
+
         Bundler.with_unbundled_env do
-          run "bundle add jwt" if jwt? || jwt_refresh?
-          run "bundle add rotp" if otp?
-          run "bundle add rqrcode" if otp?
-          run "bundle add webauthn" if webauthn? || webauthn_autofill?
+          gems.each { |gem| run "bundle add #{gem}" }
         end
       end
 
@@ -91,6 +101,7 @@ module Pu
         invoke "pu:rodauth:migration", [table], features: selected_migration_features,
           name: kitchen_sink? ? "rodauth_kitchen_sink" : nil,
           migration_name: options[:migration_name],
+          login_column: login_column,
           force: options[:force],
           skip: options[:skip]
 
@@ -113,7 +124,7 @@ module Pu
         return unless base?
 
         template "app/models/account.rb", "app/models/#{account_path}.rb"
-        scaffold_attrs = ["email:string", "status:integer"] + Array(options[:extra_attributes])
+        scaffold_attrs = ["#{login_column}:string", "status:integer"] + Array(options[:extra_attributes])
         invoke "pu:res:scaffold", [table, *scaffold_attrs], dest: "main_app",
           model: false,
           force: true,
@@ -133,6 +144,10 @@ module Pu
       def only_json?
         ::Rails.application.config.api_only || !::Rails.application.config.session_store || options[:api_only]
       end
+
+      def login_column
+        options[:login_column] || "email"
+      end
     end
   end
 end

data/lib/generators/pu/rodauth/admin_generator.rb

@@ -119,7 +119,7 @@ module Pu
         ].map { |feature| [feature, true] }.to_h
       end
 
-      def display_name = name.humanize.downcase
+      def display_name = name.underscore.humanize.downcase
 
       def normalized_name = name.underscore
 

data/lib/generators/pu/rodauth/concerns/configuration.rb

@@ -184,6 +184,7 @@ module Pu
           },
           jwt: {},
           json: {},
+          http_basic_auth: {},
           case_insensitive_login: {default: true},
           internal_request: {default: true}
         }.freeze

data/lib/generators/pu/rodauth/concerns/gem_helpers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pu
+  module Rodauth
+    module Concerns
+      module GemHelpers
+        private
+
+        def gem_in_bundle?(name)
+          in_root do
+            return true if File.exist?("Gemfile") && File.read("Gemfile").match?(/gem ['"]#{name}['"]/)
+            return true if File.exist?("Gemfile.lock") && File.read("Gemfile.lock").include?("    #{name} ")
+          end
+          false
+        end
+      end
+    end
+  end
+end

data/lib/generators/pu/rodauth/install_generator.rb

@@ -2,20 +2,24 @@ require "rails/generators/base"
 require "rails/generators/active_record/migration"
 require "securerandom"
 
+require "#{__dir__}/concerns/gem_helpers"
+
 module Pu
   module Rodauth
     class InstallGenerator < ::Rails::Generators::Base
       include ::ActiveRecord::Generators::Migration
+      include Concerns::GemHelpers
 
       source_root "#{__dir__}/templates"
 
       desc "Install rodauth-rails"
 
       def add_rodauth
+        gems = %w[bcrypt sequel-activerecord_connection tilt rodauth-rails].reject { |g| gem_in_bundle?(g) }
+        return if gems.empty?
+
         Bundler.with_unbundled_env do
-          %w[bcrypt sequel-activerecord_connection tilt rodauth-rails].each do |gem|
-            run "bundle add #{gem}"
-          end
+          gems.each { |gem| run "bundle add #{gem}" }
         end
       end
 

data/lib/generators/pu/rodauth/migration/active_record/base.erb

@@ -2,15 +2,15 @@ create_table :<%= table_prefix.pluralize %><%= primary_key_type %> do |t|
   t.integer :status, null: false, default: 1
 <% case activerecord_adapter -%>
 <% when "postgresql" -%>
-  t.citext :email, null: false
+  t.citext :<%= login_column %>, null: false
 <% else -%>
-  t.string :email, null: false
+  t.string :<%= login_column %>, null: false
 <% end -%>
 <% case activerecord_adapter -%>
 <% when "postgresql", "sqlite3" -%>
-  t.index :email, unique: true, where: "status IN (1, 2)"
+  t.index :<%= login_column %>, unique: true, where: "status IN (1, 2)"
 <% else -%>
-  t.index :email, unique: true
+  t.index :<%= login_column %>, unique: true
 <% end -%>
 <% unless separate_passwords? -%>
   t.string :password_hash

data/lib/generators/pu/rodauth/migration_generator.rb

@@ -27,6 +27,9 @@ module Pu
       class_option :features, required: true, type: :array,
         desc: "Rodauth features to create tables for (otp, sms_codes, single_session, account_expiration etc.)"
 
+      class_option :login_column, type: :string, default: "email",
+        desc: "Name of the login column (default: email)"
+
       def validate_selected_features
         if selected_features.empty?
           say "No migration features specified!", :yellow
@@ -119,6 +122,10 @@ module Pu
         selected_features.include? :separate_passwords
       end
 
+      def login_column
+        options[:login_column] || "email"
+      end
+
       def migration_chunk(feature)
         "#{MIGRATION_DIR}/#{feature}.erb"
       end

data/lib/generators/pu/rodauth/templates/app/models/account.rb.tt

@@ -22,7 +22,7 @@ class <%= account_path.classify %> < ResourceRecord
 
   # add scopes above.
 
-  validates :email, presence: true
+  validates :<%= login_column %>, presence: true
   # add validations above.
 
   # add callbacks above.

data/lib/generators/pu/saas/USAGE

@@ -2,10 +2,11 @@ Description:
     SaaS generators for multi-tenant applications with user accounts, entities, and memberships.
 
 Generators:
-    pu:saas:setup       Complete SaaS setup (user + entity + membership)
+    pu:saas:setup       Complete SaaS setup (user + entity + membership + optional api_client)
     pu:saas:user        SaaS user account with Rodauth
     pu:saas:entity      Entity/organization model
     pu:saas:membership  Membership join table linking users to entities
+    pu:saas:api_client  API client account for machine-to-machine auth
 
 Example:
     rails g pu:saas:setup --user Customer --entity Organization
@@ -15,8 +16,16 @@ Example:
         - Organization entity model with unique name
         - OrganizationCustomer membership model with role enum
 
+    With API client:
+    rails g pu:saas:setup --user Customer --entity Organization --api_client ApiClient
+
+    This also creates:
+        - ApiClient account with HTTP Basic Auth
+        - OrganizationApiClient membership model with roles
+
 See individual generator help for more options:
     rails g pu:saas:setup --help
     rails g pu:saas:user --help
     rails g pu:saas:entity --help
     rails g pu:saas:membership --help
+    rails g pu:saas:api_client --help

data/lib/generators/pu/saas/api_client/USAGE

@@ -0,0 +1,32 @@
+Description:
+    Generate an API client account for machine-to-machine authentication.
+
+    API clients use HTTP Basic Auth with application name (login) and
+    auto-generated password. Credentials are displayed once on creation
+    and cannot be reset - only disabled or deleted.
+
+Example:
+    # Basic API client (platform-level)
+    rails generate pu:saas:api_client ApiClient
+
+    # API client scoped to an organization with roles
+    rails generate pu:saas:api_client ApiClient --entity=Organization
+
+    # Custom roles
+    rails generate pu:saas:api_client ApiClient --entity=Organization --roles=read_only,write,admin
+
+    # With extra attributes
+    rails generate pu:saas:api_client ApiClient --extra_attributes=description:string,rate_limit:integer
+
+This will create:
+    - Rodauth account with HTTP Basic Auth
+    - Create and Disable interactions
+    - Rake task for CLI creation
+    - If --entity: membership model with roles
+
+Usage:
+    # Create via rake task
+    rake api_clients:create LOGIN=my-service
+
+    # Or with entity
+    rake api_clients:create LOGIN=my-service ORGANIZATION=acme ROLE=write

data/lib/generators/pu/saas/api_client/templates/app/interactions/create_interaction.rb.tt

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class <%= name.classify %>::CreateInteraction < Plutonium::Resource::Interaction
+  include Plutonium::ApiClient::Concerns::CreateApiClient
+
+<% if entity? -%>
+  attribute :<%= normalized_entity_name %>_id, :integer
+  attribute :role, :string, default: "<%= default_role %>"
+
+  validates :<%= normalized_entity_name %>_id, presence: true
+  validates :role, presence: true, inclusion: {in: <%= membership_model_name.classify %>.roles.keys}
+
+  # Only show entity picker if not in a scoped context
+  input :<%= normalized_entity_name %>_id, if: -> { scoped_entity.nil? } do |f|
+    choices = <%= normalized_entity_name.classify %>.pluck(:name, :id)
+    f.select_tag choices: choices
+  end
+  input :role, as: :select, choices: <%= membership_model_name.classify %>.roles.keys
+
+  def initialize(**)
+    super
+    self.<%= normalized_entity_name %>_id ||= scoped_entity&.id
+  end
+
+<% end -%>
+  private
+
+  def rodauth_name
+    :<%= normalized_name %>
+  end
+
+  def api_client_class
+    <%= name.classify %>
+  end
+<% if entity? -%>
+
+  def entity_class
+    <%= normalized_entity_name.classify %>
+  end
+
+  def membership_class
+    <%= membership_model_name.classify %>
+  end
+
+  def scoped_entity_id
+    <%= normalized_entity_name %>_id
+  end
+
+  # Custom credentials page with proper resource URL
+  class CredentialsPage < Plutonium::ApiClient::Concerns::CreateApiClient::CredentialsPage
+    def success_title
+      "<%= display_name.titleize %> Created Successfully"
+    end
+
+    def done_url
+      helpers.resource_url_for(<%= name.classify %>, parent: @parent)
+    end
+  end
+
+  def credentials_page_class
+    CredentialsPage
+  end
+<% else -%>
+
+  # Custom credentials page with proper resource URL
+  class CredentialsPage < Plutonium::ApiClient::Concerns::CreateApiClient::CredentialsPage
+    def success_title
+      "<%= display_name.titleize %> Created Successfully"
+    end
+
+    def done_url
+      helpers.resource_url_for(<%= name.classify %>)
+    end
+  end
+
+  def credentials_page_class
+    CredentialsPage
+  end
+<% end -%>
+end

data/lib/generators/pu/saas/api_client/templates/app/interactions/disable_interaction.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class <%= name.classify %>::DisableInteraction < Plutonium::Resource::Interaction
+  include Plutonium::ApiClient::Concerns::DisableApiClient
+
+  private
+
+  def rodauth_name
+    :<%= normalized_name %>
+  end
+
+  def success_message(login)
+    "<%= display_name.titleize %> '#{login}' has been disabled"
+  end
+end

data/lib/generators/pu/saas/api_client/templates/lib/tasks/api_client.rake.tt

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+namespace :<%= normalized_name.pluralize %> do
+  desc "Create a new <%= display_name %>"
+  task create: :environment do
+    require "tty-prompt"
+
+    prompt = TTY::Prompt.new
+
+    login = ENV["LOGIN"] || prompt.ask("Application name:", required: true)
+<% if entity? -%>
+    <%= normalized_entity_name %>_name = ENV["<%= normalized_entity_name.upcase %>"] || prompt.ask("<%= normalized_entity_name.titleize %> name:", required: true)
+    role = ENV["ROLE"] || prompt.select("Role:", %w[<%= roles.join(" ") %>])
+
+    <%= normalized_entity_name %> = <%= normalized_entity_name.classify %>.find_by!(name: <%= normalized_entity_name %>_name)
+<% end -%>
+
+    password = SecureRandom.base64(32)
+
+    RodauthApp.rodauth(:<%= normalized_name %>).create_account(
+      login: login,
+      password: password
+    )
+<% if entity? -%>
+
+    <%= normalized_name %> = <%= name.classify %>.find_by!(login: login)
+
+    <%= membership_model_name.classify %>.create!(
+      <%= normalized_entity_name %>: <%= normalized_entity_name %>,
+      <%= normalized_name %>: <%= normalized_name %>,
+      role: role
+    )
+<% end -%>
+
+    puts
+    puts "=== <%= display_name.titleize %> Created ==="
+    puts
+    puts "Login:    #{login}"
+    puts "Password: #{password}"
+<% if entity? -%>
+    puts "<%= normalized_entity_name.titleize %>: #{<%= normalized_entity_name %>.name}"
+    puts "Role:     #{role}"
+<% end -%>
+    puts
+    puts "IMPORTANT: Save these credentials now. The password cannot be retrieved later."
+    puts
+  end
+end