plutonium 0.50.0 → 0.52.0

data/docs/reference/auth/accounts.md

@@ -0,0 +1,229 @@
+# Accounts
+
+Rodauth account types. Pick one (or several — apps can have multiple side-by-side).
+
+## Basic account — `pu:rodauth:account`
+
+```bash
+rails generate pu:rodauth:account user [options]
+```
+
+### Options
+
+| Option | Description |
+|---|---|
+| `--defaults` | Enables login, logout, remember, password reset |
+| `--kitchen_sink` | Enables ALL features |
+| `--no-mails` | Skip mailer setup |
+| `--argon2` | Use Argon2 instead of bcrypt |
+| `--api_only` | JSON API only (no sessions) |
+
+### Feature flags
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--login`, `--logout`, `--remember` | ✓ | Basic auth |
+| `--create_account`, `--verify_account` | ✓ | Registration + email verification |
+| `--verify_account_grace_period` | ✓ | Grace period before verification is required |
+| `--reset_password`, `--reset_password_notify` | ✓ | Password reset via email + notification |
+| `--change_password`, `--change_password_notify` | ✓ | Password change + notification |
+| `--change_login`, `--verify_login_change` | ✓ | Email change with verification |
+| `--case_insensitive_login` | ✓ | Case-insensitive email matching |
+| `--internal_request` | ✓ | Internal request support |
+| `--otp` | | TOTP 2FA |
+| `--webauthn` | | WebAuthn / passkeys |
+| `--recovery_codes` | | 2FA backup codes |
+| `--lockout` | | Lock after failed attempts |
+| `--active_sessions` | | Track active sessions |
+| `--audit_logging` | | Log auth events |
+| `--close_account` | | Allow account deletion |
+| `--email_auth` | | Passwordless email login |
+| `--sms_codes` | | SMS 2FA |
+| `--jwt`, `--jwt_refresh` | | JWT for API auth |
+| `--password_expiration` | | Force periodic password changes |
+| `--disallow_password_reuse` | | Prevent reusing recent passwords |
+
+### Examples
+
+```bash
+# Basic account
+rails g pu:rodauth:account user
+
+# With 2FA
+rails g pu:rodauth:account user --otp --recovery_codes
+
+# API only
+rails g pu:rodauth:account api_user --api_only --jwt --jwt_refresh
+
+# Kitchen sink
+rails g pu:rodauth:account user --kitchen_sink
+```
+
+## Admin account — `pu:rodauth:admin`
+
+Pre-configured secure admin with multi-phase login, **required** TOTP, recovery codes, lockout, active session tracking, audit logging, role-based access, invite interaction, and **no public signup**.
+
+```bash
+rails g pu:rodauth:admin admin
+rails g pu:rodauth:admin admin --roles=super_admin,admin,viewer
+rails g pu:rodauth:admin admin --extra-attributes=name:string,department:string
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--roles` | `super_admin,admin` | Comma-separated roles (positional enum) |
+| `--extra_attributes` | | Additional model attributes (e.g. `name:string`) |
+
+**Role-ordering convention:** index 0 is the most privileged. Generated invite interaction defaults new invitees to `roles[1]` — the order in `--roles=` matters.
+
+```ruby
+enum :role, super_admin: 0, admin: 1
+```
+
+Rake task for direct admin creation (generated alongside the account — namespace is `rodauth`, task name is the account name):
+
+```bash
+EMAIL=admin@example.com rails rodauth:admin
+# (run without EMAIL to be prompted)
+```
+
+The task creates the account and triggers a verification email; the admin sets their own password via that flow. No password is passed on the command line.
+
+## SaaS setup — `pu:saas:setup` (meta-generator)
+
+Creates the User + Entity + Membership trio AND runs:
+
+- `pu:saas:portal` → a full `{Entity}Portal` scoped to the entity
+- `pu:profile:setup` → profile model + association (see [Profile](./profile))
+- `pu:saas:welcome` → onboarding / select-entity flow
+- `pu:invites:install` → the invites package (see [Tenancy › Invites](/reference/tenancy/invites))
+
+::: warning Don't re-run pieces manually
+After `pu:saas:setup` runs, don't separately run `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, or `pu:invites:install`. Pass `--force` to re-run the whole meta-generator.
+:::
+
+```bash
+rails g pu:saas:setup --user Customer --entity Organization
+rails g pu:saas:setup --user Customer --entity Organization --roles=admin,member
+rails g pu:saas:setup --user Customer --entity Organization --no-allow-signup
+rails g pu:saas:setup --user Customer --entity Organization \
+  --user-attributes=name:string --entity-attributes=slug:string
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--user=NAME` | (required) | User account model name |
+| `--entity=NAME` | (required) | Entity model name |
+| `--allow-signup` | `true` | Allow public registration |
+| `--roles` | `admin,member` | Additional roles. **`owner` always prepended as index 0** |
+| `--skip-entity` | | Skip entity model generation |
+| `--skip-membership` | | Skip membership model generation |
+| `--user-attributes`, `--entity-attributes`, `--membership-attributes` | | Extra model fields |
+| `--api_client=NAME` | | Also generate an API client |
+| `--api_client_roles` | `read_only,write,admin` | API client roles |
+
+Individual SaaS generators (rarely needed): `pu:saas:user`, `pu:saas:entity`, `pu:saas:membership`, `pu:saas:portal`, `pu:saas:welcome`.
+
+Generated user + membership models:
+
+```ruby
+class Customer < ApplicationRecord
+  include Rodauth::Rails.model(:customer)
+  has_many :organization_customers, dependent: :destroy
+  has_many :organizations, through: :organization_customers
+end
+
+class OrganizationCustomer < ApplicationRecord
+  belongs_to :organization
+  belongs_to :customer
+  enum :role, owner: 0, admin: 1, member: 2
+
+  validates :customer, uniqueness: {
+    scope: :organization_id,
+    message: "is already a member of this organization"
+  }
+end
+```
+
+## API client — `pu:saas:api_client`
+
+For machine-to-machine authentication. HTTP Basic Auth with auto-generated password.
+
+```bash
+rails g pu:saas:api_client ApiClient
+rails g pu:saas:api_client ApiClient --entity=Organization
+rails g pu:saas:api_client ApiClient --entity=Organization --roles=read_only,write,admin
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--entity=NAME` | | Entity to scope API clients to |
+| `--roles` | `read_only,write,admin` | Available roles |
+| `--extra_attributes` | | Additional model attributes |
+| `--dest` | `main_app` | Destination package |
+
+CLI creation:
+
+```bash
+rake api_clients:create LOGIN=my-service
+rake api_clients:create LOGIN=my-service ORGANIZATION=acme ROLE=write
+```
+
+::: warning Credentials shown once
+The auto-generated password (`SecureRandom.base64(32)`) is displayed once at creation and cannot be retrieved later.
+:::
+
+## Common customizations
+
+All inside the Rodauth `configure do ... end` block in `app/rodauth/<name>_rodauth_plugin.rb`.
+
+### Custom login redirect
+
+```ruby
+login_redirect do
+  rails_account.admin? ? "/admin" : "/dashboard"
+end
+```
+
+### Custom create-account validation + hook
+
+```ruby
+before_create_account do
+  throw_error_status(422, "name", "must be present") if param("name").empty?
+end
+
+after_create_account do
+  Profile.create!(account_id: account_id, name: param("name"))
+end
+```
+
+### Password requirements
+
+```ruby
+password_minimum_length 12
+
+password_meets_requirements? do |password|
+  super(password) && password.match?(/\d/) && password.match?(/[^a-zA-Z\d]/)
+end
+```
+
+### Multi-phase login (password on a separate page)
+
+```ruby
+use_multi_phase_login? true
+```
+
+### Prevent public signup (admin pattern)
+
+```ruby
+before_create_account_route do
+  request.halt unless internal_request?
+end
+```
+
+## Related
+
+- [Profile](./profile) — profile resource + SecuritySection component
+- [App › Portals › Controller concern (auth)](/reference/app/portals#controller-concern-auth) — wiring accounts into portal controllers
+- [Tenancy › Invites](/reference/tenancy/invites) — invitation system on top of Rodauth signup
+- [App › Generators › Authentication generators](/reference/app/generators#authentication-generators) — full generator catalog

data/docs/reference/auth/index.md

@@ -0,0 +1,88 @@
+# Auth Reference
+
+Plutonium uses [Rodauth](http://rodauth.jeremyevans.net/) via [rodauth-rails](https://github.com/janko/rodauth-rails). This area covers Rodauth installation, account types, and the user profile resource.
+
+## Sub-pages
+
+- [Accounts](./accounts) — Rodauth install, basic accounts, admin accounts, SaaS setup, account customization
+- [Profile](./profile) — profile resource generator, the SecuritySection component
+
+## 🚨 Critical
+
+- **Use the generators.** `pu:rodauth:install`, `pu:rodauth:account`, `pu:rodauth:admin`, `pu:saas:setup`, `pu:profile:install`, `pu:profile:conn`. Never hand-write Rodauth plugin files, account models, or profile resources.
+- **Role index 0 is the most privileged** (`owner`, `super_admin`). Invite interactions default new invitees to **index 1** — the order in `--roles=` matters.
+- **`pu:saas:setup --roles=...` always prepends `owner` as index 0.** Don't include `owner` in the option.
+- **`pu:saas:setup` is a meta-generator.** It also runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install`. Don't re-run those manually.
+- **Profile association is always `:profile`** regardless of the model class — `current_user.profile`, `build_profile`, `params.require(:profile)`.
+- **Profile needs `pu:profile:conn` to be visible** — without it, the singular `/profile` route and `profile_url` helper don't exist.
+- **Every user needs a profile row.** Add an `after_create` callback or `find_or_create_by` — otherwise `current_user.profile` is nil.
+
+## Install Rodauth
+
+```bash
+rails generate pu:rodauth:install
+```
+
+Installs gems (`rodauth-rails`, `bcrypt`, `sequel-activerecord_connection`), the Roda app at `app/rodauth/rodauth_app.rb`, base plugin and controller, initializer, layout, and a PostgreSQL extension migration if applicable.
+
+## Wire auth into controllers
+
+```ruby
+class ResourceController < PlutoniumController
+  include Plutonium::Resource::Controller
+  include Plutonium::Auth::Rodauth(:user)
+end
+```
+
+Multiple account types — include the matching `:name`:
+
+```ruby
+class AdminController < PlutoniumController
+  include Plutonium::Resource::Controller
+  include Plutonium::Auth::Rodauth(:admin)
+end
+```
+
+`Plutonium::Auth::Rodauth(:name)` exposes `current_user`, `logout_url`, `profile_url`, and `rodauth` in the controller (all available as helper methods in views too).
+
+For portal wiring (`AdminPortal::Concerns::Controller`), see [App › Portals](/reference/app/portals#controller-concern-auth).
+
+## Email configuration
+
+Standard ActionMailer in `config/environments/production.rb`:
+
+```ruby
+config.action_mailer.delivery_method = :smtp
+config.action_mailer.smtp_settings = {
+  address: "smtp.example.com",
+  port: 587,
+  user_name: ENV["SMTP_USER"],
+  password: ENV["SMTP_PASSWORD"]
+}
+```
+
+Override templates in `app/views/rodauth/<account>_mailer/`.
+
+## API authentication
+
+```bash
+rails generate pu:rodauth:account api_user --api_only --jwt --jwt_refresh
+```
+
+```
+POST /api_users/login
+{"login": "user@example.com", "password": "secret"}
+# → {"access_token": "...", "refresh_token": "..."}
+
+GET /api/posts
+Authorization: Bearer <access_token>
+```
+
+## Related
+
+- [Accounts](./accounts) — account types and feature flags
+- [Profile](./profile) — profile resource + SecuritySection
+- [Tenancy › Invites](/reference/tenancy/invites) — invitation system on top of Rodauth signup
+- [App › Portals › Controller concern (auth)](/reference/app/portals#controller-concern-auth) — portal-side wiring
+- [Guides › Authentication](/guides/authentication) — task-oriented walkthrough
+- [Guides › User profile](/guides/user-profile)

data/docs/reference/auth/profile.md

@@ -0,0 +1,185 @@
+# Profile
+
+Manages Rodauth account settings as a Plutonium resource — users view/edit personal fields and access Rodauth security features (change password, 2FA, etc.) on one page.
+
+## 🚨 Critical
+
+- **Profile association is always `:profile`** regardless of the model class — `current_user.profile`, `build_profile`, `params.require(:profile)` always work.
+- **Profile needs `pu:profile:conn`** — without it, no route, no `profile_url` helper, no user-menu link.
+- **Every user needs a profile row** — add an `after_create` callback (or `find_or_create_by`). Without it, `current_user.profile` is nil and the profile route errors.
+
+## Quick setup
+
+```bash
+rails g pu:profile:setup date_of_birth:date bio:text \
+  --dest=competition \
+  --portal=competition_portal
+```
+
+Meta-generator: runs `pu:profile:install` + `pu:profile:conn` in one shot.
+
+## Step-by-step
+
+```bash
+rails generate pu:profile:install bio:text avatar:attachment 'timezone:string?' \
+  --dest=customer
+
+rails db:migrate
+
+rails generate pu:profile:conn --dest=customer_portal
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--dest=DEST` | (prompts) | Target package or `main_app` |
+| `--user-model=NAME` | `User` | Rodauth user model |
+
+Custom resource name (first positional argument):
+
+```bash
+rails g pu:profile:install AccountSettings bio:text --dest=main_app
+```
+
+## What gets created
+
+By default the model is `{UserModel}Profile` — `UserProfile`, `StaffUserProfile`, etc. — derived from `--user-model`.
+
+```
+app/models/[package/]user_profile.rb
+db/migrate/xxx_create_user_profiles.rb
+app/controllers/[package/]user_profiles_controller.rb
+app/policies/[package/]user_profile_policy.rb
+app/definitions/[package/]user_profile_definition.rb
+```
+
+The generator modifies the user model:
+
+```ruby
+has_one :profile, class_name: "UserProfile", dependent: :destroy
+```
+
+::: warning Association name is fixed
+Even when the class is `StaffUserProfile`, the association is `:profile`. Don't rename it — `current_user.profile`, `build_profile`, `params.require(:profile)` all assume this.
+:::
+
+The generated definition injects a custom `ShowPage` that renders the `SecuritySection` component.
+
+## The `SecuritySection` component
+
+Dynamically lists Rodauth security links based on which features are enabled on the account.
+
+| Feature enabled | Link rendered |
+|---|---|
+| `change_password` | Change Password |
+| `change_login` | Change Email |
+| `otp` | Two-Factor Authentication |
+| `recovery_codes` | Recovery Codes |
+| `webauthn` | Security Keys |
+| `active_sessions` | Active Sessions |
+| `close_account` | Close Account |
+
+If a feature isn't enabled on the account, its link doesn't render — no configuration needed.
+
+To customize (e.g. add chrome, reorder), override `ShowPage#render_after_content`:
+
+```ruby
+class UserProfileDefinition < Plutonium::Resource::Definition
+  class ShowPage < ShowPage
+    private
+
+    def render_after_content
+      render Plutonium::Profile::SecuritySection.new
+    end
+  end
+end
+```
+
+See [UI › Pages](/reference/ui/pages) for page-class customization.
+
+## Required: every user gets a profile
+
+```ruby
+class User < ApplicationRecord
+  after_create :create_profile!
+
+  private
+  def create_profile! = create_profile
+end
+```
+
+Without this, `current_user.profile` returns nil and the profile route errors. For existing users at migration time, run a one-off backfill:
+
+```bash
+rails runner "User.find_each(&:create_profile)"
+```
+
+## Connecting to a portal
+
+`pu:profile:conn` registers the profile as a **singular** resource — `/profile` (no `:id`), and exposes the `profile_url` helper:
+
+```bash
+rails g pu:profile:conn --dest=customer_portal
+```
+
+This is what makes the profile visible. Without it, the model exists but has no route in any portal.
+
+## Linking to the profile
+
+```ruby
+link_to("Profile", profile_url) if respond_to?(:profile_url)
+```
+
+The `respond_to?` guard is defensive — only portals that ran `pu:profile:conn` have the helper.
+
+## Customizing the definition
+
+The generated definition is a normal Plutonium resource definition. Customize like any other:
+
+```ruby
+class UserProfileDefinition < Plutonium::Resource::Definition
+  field :bio, as: :markdown
+  input :avatar, as: :uppy
+  field :timezone, as: :select, choices: ActiveSupport::TimeZone.all.map(&:name)
+
+  metadata :created_at, :updated_at
+
+  class ShowPage < ShowPage
+    private
+
+    def render_after_content
+      render Plutonium::Profile::SecuritySection.new
+    end
+  end
+end
+```
+
+See [Resource › Definition](/reference/resource/definition) for the full definition surface.
+
+## Multiple account types
+
+If your app has both `User` and `StaffUser` accounts, run `pu:profile:install` once per:
+
+```bash
+rails g pu:profile:install --user-model=User --dest=main_app
+rails g pu:profile:install --user-model=StaffUser --dest=main_app
+```
+
+Each gets its own `*Profile` model with `:profile` association on the respective user. Connect each to the appropriate portal:
+
+```bash
+rails g pu:profile:conn UserProfile      --dest=customer_portal
+rails g pu:profile:conn StaffUserProfile --dest=admin_portal
+```
+
+## Gotchas
+
+- **`current_user.profile` is nil** — every user needs a profile row. Add `after_create :create_profile!` to the user model.
+- **`profile_url` is undefined** — the profile isn't connected to this portal. Run `pu:profile:conn --dest=<portal>`.
+- **Custom resource name** — pass it as the first positional argument to `pu:profile:install`. The association is still `:profile`.
+- **SecuritySection shows nothing** — none of the relevant Rodauth features are enabled on the account. Enable `change_password`, `otp`, etc. on the Rodauth plugin.
+
+## Related
+
+- [Accounts](./accounts) — Rodauth feature flags that gate SecuritySection links
+- [Resource › Definition](/reference/resource/definition) — customizing the profile definition
+- [App › Generators › Profile generators](/reference/app/generators#profile-generators)