organizations 0.4.3 → 0.5.0

data/config/routes.rb

@@ -1,40 +1,58 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/BlockLength -- a routes file is one declarative block by nature
 Organizations::Engine.routes.draw do
-  # Organization switching
-  # POST /organizations/switch/:id
-  post "organizations/switch/:id", to: "switch#create", as: :switch_organization
+  # Route groups are drawn per config.engine_routes (devise_for-style
+  # only:/except:) so hosts declare what they want instead of shadowing
+  # engine routes with order-load-bearing redirects before the mount.
+  # Routes re-draw on every reload_routes!, so config is always respected.
+  groups = Organizations.configuration.engine_route_groups
 
-  # Organization management
-  # All operations are scoped to current_organization (from session)
-  resources :organizations, only: [:index, :show, :new, :create, :edit, :update, :destroy]
+  if groups.include?(:switching)
+    # Organization switching
+    # POST /organizations/switch/:id
+    post "organizations/switch/:id", to: "switch#create", as: :switch_organization
+  end
 
-  # Membership management (scoped to current_organization)
-  # These are flat routes - the organization is determined by session, not URL
-  resources :memberships, only: [:index, :update, :destroy] do
-    member do
-      post :transfer_ownership
-    end
-    collection do
-      delete :leave
+  if groups.include?(:organizations)
+    # Organization management
+    # All operations are scoped to current_organization (from session)
+    resources :organizations, only: [:index, :show, :new, :create, :edit, :update, :destroy]
+  end
+
+  if groups.include?(:memberships)
+    # Membership management (scoped to current_organization)
+    # These are flat routes - the organization is determined by session, not URL
+    resources :memberships, only: [:index, :update, :destroy] do
+      member do
+        post :transfer_ownership
+      end
+      collection do
+        delete :leave
+      end
     end
   end
 
-  # Invitation management (scoped to current_organization)
-  # These are flat routes - the organization is determined by session, not URL
-  # NOTE: Must come BEFORE token-based routes so /invitations/new doesn't match /:token
-  resources :invitations, only: [:index, :new, :create, :destroy], as: :organization_invitations do
-    member do
-      post :resend
+  if groups.include?(:invitations)
+    # Invitation management (scoped to current_organization)
+    # These are flat routes - the organization is determined by session, not URL
+    # NOTE: Must come BEFORE token-based routes so /invitations/new doesn't match /:token
+    resources :invitations, only: [:index, :new, :create, :destroy], as: :organization_invitations do
+      member do
+        post :resend
+      end
     end
   end
 
-  # Invitation acceptance (public routes with token)
-  # These use PublicInvitationsController which inherits from a minimal base controller
-  # to avoid host app filters that might enforce authentication.
-  # GET  /invitations/:token        → View invitation details
-  # POST /invitations/:token/accept → Accept the invitation
-  # NOTE: These must come AFTER resourceful routes to avoid matching "new" as a token
-  get "invitations/:token", to: "public_invitations#show", as: :invitation
-  post "invitations/:token/accept", to: "public_invitations#accept", as: :accept_invitation
+  if groups.include?(:public_invitations)
+    # Invitation acceptance (public routes with token)
+    # These use PublicInvitationsController which inherits from a minimal base controller
+    # to avoid host app filters that might enforce authentication.
+    # GET  /invitations/:token        → View invitation details
+    # POST /invitations/:token/accept → Accept the invitation
+    # NOTE: These must come AFTER resourceful routes to avoid matching "new" as a token
+    get "invitations/:token", to: "public_invitations#show", as: :invitation
+    post "invitations/:token/accept", to: "public_invitations#accept", as: :accept_invitation
+  end
 end
+# rubocop:enable Metrics/BlockLength

data/gemfiles/rails_7.2.gemfile

@@ -7,9 +7,9 @@ gem "rails", "~> 7.2.3"
 
 group :development do
   gem "irb"
-  gem "rubocop", "~> 1.0"
-  gem "rubocop-minitest", "~> 0.35"
-  gem "rubocop-performance", "~> 1.0"
+  gem "rubocop", "~> 1.88"
+  gem "rubocop-minitest", "~> 0.39"
+  gem "rubocop-performance", "~> 1.26"
 end
 
 group :development, :test do

data/gemfiles/rails_8.1.gemfile

@@ -7,9 +7,9 @@ gem "rails", "~> 8.1.2"
 
 group :development do
   gem "irb"
-  gem "rubocop", "~> 1.0"
-  gem "rubocop-minitest", "~> 0.35"
-  gem "rubocop-performance", "~> 1.0"
+  gem "rubocop", "~> 1.88"
+  gem "rubocop-minitest", "~> 0.39"
+  gem "rubocop-performance", "~> 1.26"
 end
 
 group :development, :test do

data/lib/generators/organizations/install/install_generator.rb

@@ -30,6 +30,9 @@ module Organizations
         say "  2. Review and customize 'config/initializers/organizations.rb'."
         say "  3. Add 'has_organizations' to your User model."
         say "  4. Mount the engine in your routes: mount Organizations::Engine => '/'"
+        say "  5. Run 'rails g organizations:views' to copy the reference views"
+        say "     (the engine renders HOST views — without them you'll hit"
+        say "     missing-template errors on the org/membership/invitation pages)."
       end
 
       private

data/lib/generators/organizations/install/templates/create_organizations_tables.rb.erb

@@ -2,6 +2,9 @@
 
 class CreateOrganizationsTables < ActiveRecord::Migration<%= migration_version %>
   def change
+    # ⚠️ If your user model is NOT `User` (config.user_class), adjust every
+    # `to_table: :users` below (and `foreign_key: true` on user references)
+    # to your user table before migrating.
     primary_key_type, foreign_key_type = primary_and_foreign_key_types
     adapter = connection.adapter_name.downcase
 
@@ -22,20 +25,42 @@ class CreateOrganizationsTables < ActiveRecord::Migration<%= migration_version %
       t.string :role, null: false, default: "member"
       t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
 
+      # Verified-joining provenance: how this member joined and which email
+      # address they proved control of (if any).
+      t.string :joined_via
+      t.string :verified_email
+      t.string :verified_email_normalized
+      t.datetime :verified_at
+
       t.timestamps
     end
 
-    add_index :organizations_memberships, [:user_id, :organization_id], unique: true
+    add_index :organizations_memberships, [ :user_id, :organization_id ], unique: true
     add_index :organizations_memberships, :role
 
+    # One proven email address => one membership per organization.
+    # NULLs never collide, so unverified memberships are unconstrained —
+    # a plain unique index gives identical semantics on every adapter.
+    add_index :organizations_memberships, [ :organization_id, :verified_email_normalized ],
+              unique: true, name: "index_org_memberships_verified_email_unique"
+
     # Enforce "at most one owner membership per organization" at DB level where possible.
     # Both PostgreSQL and SQLite support partial indexes with identical syntax.
+    # ⚠️ Partial-index SQL stays on ONE line on purpose: the SQLite schema
+    # dumper only recovers the WHERE clause from single-line index SQL — a
+    # multi-line statement dumps as a FULL unique index, and databases
+    # provisioned from schema.rb (db:schema:load, test DBs) silently lose
+    # the partial-index invariant.
+    # `reversible` + up-only: raw execute in `def change` would raise
+    # IrreversibleMigration on rollback; the indexes/columns die with their
+    # tables when the reversed create_table drops them, so down is a no-op.
     if adapter.include?("postgresql") || adapter.include?("sqlite")
-      execute <<-SQL
-        CREATE UNIQUE INDEX index_organizations_memberships_single_owner
-        ON organizations_memberships (organization_id)
-        WHERE role = 'owner'
-      SQL
+      reversible do |dir|
+        dir.up do
+          execute "CREATE UNIQUE INDEX index_organizations_memberships_single_owner " \
+                  "ON organizations_memberships (organization_id) WHERE role = 'owner'"
+        end
+      end
     end
 
     # Invitations table
@@ -48,6 +73,10 @@ class CreateOrganizationsTables < ActiveRecord::Migration<%= migration_version %
       t.string :role, null: false, default: "member"
       t.datetime :accepted_at
       t.datetime :expires_at
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+      # Copied onto the membership created when this invitation is accepted
+      # (cohort tags etc. — the gem never interprets the contents)
+      t.send(json_column_type, :membership_metadata, null: json_column_null, default: json_column_default)
 
       t.timestamps
     end
@@ -57,30 +86,146 @@ class CreateOrganizationsTables < ActiveRecord::Migration<%= migration_version %
 
     # Unique partial index: only one pending (non-accepted) invitation per email per org
     # Both PostgreSQL and SQLite (3.8.0+) support partial indexes with identical syntax.
+    # (One line on purpose — see the single_owner index note above.)
     if adapter.include?("postgresql") || adapter.include?("sqlite")
-      execute <<-SQL
-        CREATE UNIQUE INDEX index_organizations_invitations_pending_unique
-        ON organizations_invitations (organization_id, LOWER(email))
-        WHERE accepted_at IS NULL
-      SQL
+      reversible do |dir|
+        dir.up do
+          execute "CREATE UNIQUE INDEX index_organizations_invitations_pending_unique " \
+                  "ON organizations_invitations (organization_id, LOWER(email)) WHERE accepted_at IS NULL"
+        end
+      end
     elsif adapter.include?("mysql")
       # MySQL doesn't support partial indexes, so we use a generated column that is
       # only non-NULL for pending invitations and enforce uniqueness on that value.
-      execute <<-SQL
-        ALTER TABLE organizations_invitations
-        ADD COLUMN pending_email VARCHAR(255)
-        GENERATED ALWAYS AS (
-          CASE
-            WHEN accepted_at IS NULL THEN LOWER(email)
-            ELSE NULL
-          END
-        ) STORED
-      SQL
-
-      add_index :organizations_invitations, [:organization_id, :pending_email], unique: true, name: "index_organizations_invitations_pending_unique"
+      reversible do |dir|
+        dir.up do
+          execute <<-SQL
+            ALTER TABLE organizations_invitations
+            ADD COLUMN pending_email VARCHAR(255)
+            GENERATED ALWAYS AS (
+              CASE
+                WHEN accepted_at IS NULL THEN LOWER(email)
+                ELSE NULL
+              END
+            ) STORED
+          SQL
+        end
+      end
+
+      add_index :organizations_invitations, [ :organization_id, :pending_email ], unique: true, name: "index_organizations_invitations_pending_unique"
     else
       # For other adapters, fall back to app-level validation.
-      add_index :organizations_invitations, [:organization_id, :email], name: "index_organizations_invitations_on_org_and_email"
+      add_index :organizations_invitations, [ :organization_id, :email ], name: "index_organizations_invitations_on_org_and_email"
+    end
+
+    # === Verified joining ===
+
+    # Email domains owned by an organization (exact-match joining)
+    create_table :organizations_domains, id: primary_key_type do |t|
+      t.references :organization, null: false, type: foreign_key_type, foreign_key: { to_table: :organizations_organizations }
+      t.string :domain, null: false
+      t.send(json_column_type, :membership_metadata, null: json_column_null, default: json_column_default)
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :organizations_domains, [ :organization_id, :domain ], unique: true
+    add_index :organizations_domains, :domain
+
+    # Shareable join codes ("PINs") — globally unique, rotatable, cappable
+    create_table :organizations_join_codes, id: primary_key_type do |t|
+      t.references :organization, null: false, type: foreign_key_type, foreign_key: { to_table: :organizations_organizations }
+      t.string :code, null: false
+      t.string :label
+      t.boolean :requires_verified_domain_email, null: false, default: false
+      t.boolean :auto_approve, null: false, default: true
+      t.datetime :expires_at
+      t.integer :max_uses
+      t.integer :uses_count, null: false, default: 0
+      t.datetime :revoked_at
+      t.references :created_by, null: true, type: foreign_key_type, foreign_key: { to_table: :users }
+      t.send(json_column_type, :membership_metadata, null: json_column_null, default: json_column_default)
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :organizations_join_codes, :code, unique: true
+
+    # Pre-approved roster emails (allowlist joining)
+    create_table :organizations_allowlist_entries, id: primary_key_type do |t|
+      t.references :organization, null: false, type: foreign_key_type, foreign_key: { to_table: :organizations_organizations }
+      t.string :email, null: false
+      t.string :email_normalized, null: false
+      t.string :source
+      t.send(json_column_type, :membership_metadata, null: json_column_null, default: json_column_default)
+      t.datetime :claimed_at
+      t.references :claimed_by, null: true, type: foreign_key_type, foreign_key: { to_table: :users }
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :organizations_allowlist_entries, [ :organization_id, :email_normalized ], unique: true
+
+    # Join requests (request-to-join workflow + email-verification challenges)
+    create_table :organizations_join_requests, id: primary_key_type do |t|
+      t.references :organization, null: false, type: foreign_key_type, foreign_key: { to_table: :organizations_organizations }
+      t.references :user, null: false, type: foreign_key_type, foreign_key: true
+      t.string :status, null: false, default: "pending"
+      t.string :joined_via
+      t.references :join_code, null: true, type: foreign_key_type, foreign_key: { to_table: :organizations_join_codes }
+      t.string :message
+      t.string :verification_email
+      t.string :verification_email_normalized
+      t.string :verification_code_digest
+      t.datetime :verification_sent_at
+      t.datetime :verification_expires_at
+      t.integer :verification_attempts, null: false, default: 0
+      t.integer :verification_sends_count, null: false, default: 0
+      t.datetime :verified_at
+      t.references :decided_by, null: true, type: foreign_key_type, foreign_key: { to_table: :users }
+      t.datetime :decided_at
+      t.datetime :expires_at
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :organizations_join_requests, :status
+
+    # One OPEN request per (organization, user). Decided requests keep their
+    # history without blocking a fresh request.
+    # (One line on purpose — see the single_owner index note above.)
+    if adapter.include?("postgresql") || adapter.include?("sqlite")
+      reversible do |dir|
+        dir.up do
+          execute "CREATE UNIQUE INDEX index_org_join_requests_pending_unique " \
+                  "ON organizations_join_requests (organization_id, user_id) WHERE status = 'pending'"
+        end
+      end
+    elsif adapter.include?("mysql")
+      # MySQL doesn't support partial indexes: use a generated column that is
+      # only non-NULL for pending requests (NULLs never collide in unique indexes).
+      reversible do |dir|
+        dir.up do
+          execute <<-SQL
+            ALTER TABLE organizations_join_requests
+            ADD COLUMN pending_user_key VARCHAR(255)
+            GENERATED ALWAYS AS (
+              CASE
+                WHEN status = 'pending' THEN CONCAT(organization_id, '-', user_id)
+                ELSE NULL
+              END
+            ) STORED
+          SQL
+        end
+      end
+
+      add_index :organizations_join_requests, :pending_user_key, unique: true, name: "index_org_join_requests_pending_unique"
+    else
+      add_index :organizations_join_requests, [ :organization_id, :user_id ], name: "index_org_join_requests_on_org_and_user"
     end
   end
 
@@ -88,7 +233,7 @@ class CreateOrganizationsTables < ActiveRecord::Migration<%= migration_version %
 
   def primary_and_foreign_key_types
     config = Rails.configuration.generators
-    setting = config.options[config.orm][:primary_key_type]
+    setting = config.options[config.orm][ :primary_key_type ]
     primary_key_type = setting || :primary_key
     foreign_key_type = setting || :bigint
     [primary_key_type, foreign_key_type]

data/lib/generators/organizations/install/templates/initializer.rb

@@ -55,6 +55,59 @@ Organizations.configure do |config|
   # Default: :member
   # config.default_invitation_role = :member
 
+  # ============================================================================
+  # VERIFIED JOINING (join requests, domains, join codes, allowlists)
+  # ============================================================================
+  #
+  # Users can join organizations by proving they belong:
+  #   - request-to-join:  user.request_to_join!(org) → org.approve_join_request!(...)
+  #   - email domain:     org.add_domain!("corp.com") + emailed 6-digit code
+  #   - join code (PIN):  org.generate_join_code!(...) + JoinCode.redeem(code, user:)
+  #   - allowlist/roster: org.import_allowlist!(emails) + emailed 6-digit code
+  #
+  # The gem ships models and APIs only (bring your own UI + rate limiting on
+  # your join endpoints). See the README's "Verified joining" section.
+
+  # Mailer that sends verification codes. Custom mailers must implement
+  # code_email(join_request, code).
+  # Default: "Organizations::VerificationMailer"
+  # config.verification_mailer = "Organizations::VerificationMailer"
+
+  # How long an emailed code stays valid (codes always expire).
+  # Default: 15.minutes
+  # config.verification_code_ttl = 15.minutes
+
+  # Wrong-attempt cap per challenge, and send throttles per join request.
+  # Defaults: 5 attempts, 60.seconds between sends, 5 sends max
+  # config.verification_max_attempts = 5
+  # config.verification_resend_interval = 60.seconds
+  # config.verification_max_sends = 5
+
+  # Email normalizer used for the "one proven email = one membership per org"
+  # invariant. Default collapses case, whitespace, and +tags (plus-addressing).
+  # config.verification_email_normalizer = ->(email) { ... }
+
+  # Allow org.join_with_account_email!(user) to trust a CONFIRMED account
+  # email (e.g. Devise :confirmable) as inbox proof — no emailed code needed
+  # when the account email's domain is enrolled.
+  # Default: true
+  # config.trust_confirmed_account_email = true
+
+  # How long join requests stay open before reading as expired (nil = never).
+  # Default: 30.days
+  # config.join_request_expiry = 30.days
+
+  # Custom join-code generator (default: 8 chars, ambiguity-free alphabet).
+  # config.join_code_generator = -> { SecureRandom.alphanumeric(10).upcase }
+
+  # Lifecycle callbacks:
+  # config.on_join_request_created  { |ctx| ... }  # ctx: organization, user, join_request
+  # config.on_join_request_approved { |ctx| ... }  # + membership, decided_by (nil = auto)
+  # config.on_join_request_rejected { |ctx| ... }  # + decided_by
+  #
+  # NOTE: like all after-callbacks these are error-isolated — enforce hard
+  # caps (member limits etc.) BEFORE calling approve/redeem, in your own code.
+
   # ============================================================================
   # ROLES & PERMISSIONS
   # ============================================================================

data/lib/generators/organizations/upgrade/templates/add_verified_joining_to_organizations.rb.erb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# Upgrades organizations <= 0.4.x to 0.5.0 ("Verified Joining").
+# Additive only: no existing columns/rows are touched.
+class AddVerifiedJoiningToOrganizations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # ⚠️ If your user model is NOT `User` (config.user_class), adjust every
+    # `to_table: :users` below (and `foreign_key: true` on user references)
+    # to your user table before migrating.
+    _primary_key_type, foreign_key_type = primary_and_foreign_key_types
+    adapter = connection.adapter_name.downcase
+
+    # === Membership provenance ===
+
+    add_column :organizations_memberships, :joined_via, :string
+    add_column :organizations_memberships, :verified_email, :string
+    add_column :organizations_memberships, :verified_email_normalized, :string
+    add_column :organizations_memberships, :verified_at, :datetime
+
+    # One proven email address => one membership per organization.
+    # NULLs never collide in unique indexes on every supported adapter, so
+    # existing (unverified) memberships are unconstrained.
+    add_index :organizations_memberships, [ :organization_id, :verified_email_normalized ],
+              unique: true, name: "index_org_memberships_verified_email_unique"
+
+    # === Invitation metadata parity ===
+
+    add_column :organizations_invitations, :metadata, json_column_type,
+               null: json_column_null, default: json_column_default
+    add_column :organizations_invitations, :membership_metadata, json_column_type,
+               null: json_column_null, default: json_column_default
+
+    # === Email domains (exact-match joining) ===
+
+    create_table :organizations_domains, id: primary_key_type_setting do |t|
+      t.references :organization, null: false, type: foreign_key_type, foreign_key: { to_table: :organizations_organizations }
+      t.string :domain, null: false
+      t.send(json_column_type, :membership_metadata, null: json_column_null, default: json_column_default)
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :organizations_domains, [ :organization_id, :domain ], unique: true
+    add_index :organizations_domains, :domain
+
+    # === Join codes ("PINs") ===
+
+    create_table :organizations_join_codes, id: primary_key_type_setting do |t|
+      t.references :organization, null: false, type: foreign_key_type, foreign_key: { to_table: :organizations_organizations }
+      t.string :code, null: false
+      t.string :label
+      t.boolean :requires_verified_domain_email, null: false, default: false
+      t.boolean :auto_approve, null: false, default: true
+      t.datetime :expires_at
+      t.integer :max_uses
+      t.integer :uses_count, null: false, default: 0
+      t.datetime :revoked_at
+      t.references :created_by, null: true, type: foreign_key_type, foreign_key: { to_table: :users }
+      t.send(json_column_type, :membership_metadata, null: json_column_null, default: json_column_default)
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :organizations_join_codes, :code, unique: true
+
+    # === Allowlist / roster entries ===
+
+    create_table :organizations_allowlist_entries, id: primary_key_type_setting do |t|
+      t.references :organization, null: false, type: foreign_key_type, foreign_key: { to_table: :organizations_organizations }
+      t.string :email, null: false
+      t.string :email_normalized, null: false
+      t.string :source
+      t.send(json_column_type, :membership_metadata, null: json_column_null, default: json_column_default)
+      t.datetime :claimed_at
+      t.references :claimed_by, null: true, type: foreign_key_type, foreign_key: { to_table: :users }
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :organizations_allowlist_entries, [ :organization_id, :email_normalized ], unique: true
+
+    # === Join requests ===
+
+    create_table :organizations_join_requests, id: primary_key_type_setting do |t|
+      t.references :organization, null: false, type: foreign_key_type, foreign_key: { to_table: :organizations_organizations }
+      t.references :user, null: false, type: foreign_key_type, foreign_key: true
+      t.string :status, null: false, default: "pending"
+      t.string :joined_via
+      t.references :join_code, null: true, type: foreign_key_type, foreign_key: { to_table: :organizations_join_codes }
+      t.string :message
+      t.string :verification_email
+      t.string :verification_email_normalized
+      t.string :verification_code_digest
+      t.datetime :verification_sent_at
+      t.datetime :verification_expires_at
+      t.integer :verification_attempts, null: false, default: 0
+      t.integer :verification_sends_count, null: false, default: 0
+      t.datetime :verified_at
+      t.references :decided_by, null: true, type: foreign_key_type, foreign_key: { to_table: :users }
+      t.datetime :decided_at
+      t.datetime :expires_at
+      t.send(json_column_type, :metadata, null: json_column_null, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index :organizations_join_requests, :status
+
+    # One OPEN request per (organization, user); decided history never blocks
+    if adapter.include?("postgresql") || adapter.include?("sqlite")
+      reversible do |dir|
+        dir.up do
+          # ONE line on purpose: the SQLite schema dumper only recovers a
+          # partial index's WHERE clause from single-line index SQL — a
+          # multi-line statement dumps as a FULL unique index, and databases
+          # provisioned from schema.rb (db:schema:load, test DBs) silently
+          # lose the partial-index invariant.
+          execute "CREATE UNIQUE INDEX index_org_join_requests_pending_unique " \
+                  "ON organizations_join_requests (organization_id, user_id) WHERE status = 'pending'"
+        end
+        dir.down do
+          execute "DROP INDEX IF EXISTS index_org_join_requests_pending_unique"
+        end
+      end
+    elsif adapter.include?("mysql")
+      reversible do |dir|
+        dir.up do
+          execute <<-SQL
+            ALTER TABLE organizations_join_requests
+            ADD COLUMN pending_user_key VARCHAR(255)
+            GENERATED ALWAYS AS (
+              CASE
+                WHEN status = 'pending' THEN CONCAT(organization_id, '-', user_id)
+                ELSE NULL
+              END
+            ) STORED
+          SQL
+        end
+        dir.down do
+          execute "ALTER TABLE organizations_join_requests DROP COLUMN pending_user_key"
+        end
+      end
+      add_index :organizations_join_requests, :pending_user_key, unique: true, name: "index_org_join_requests_pending_unique"
+    else
+      add_index :organizations_join_requests, [ :organization_id, :user_id ], name: "index_org_join_requests_on_org_and_user"
+    end
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][ :primary_key_type ]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+
+  def primary_key_type_setting
+    primary_and_foreign_key_types.first
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?('postgresql')
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns.
+  def json_column_default
+    return nil if connection.adapter_name.downcase.include?('mysql')
+    {}
+  end
+
+  def json_column_null
+    connection.adapter_name.downcase.include?('mysql')
+  end
+end

data/lib/generators/organizations/upgrade/upgrade_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Organizations
+  module Generators
+    # Upgrades an existing organizations install (<= 0.4.x) to 0.5.0
+    # ("Verified Joining"): new tables for domains, join codes, allowlist
+    # entries and join requests, plus provenance columns on memberships and
+    # metadata columns on invitations.
+    #
+    # Fresh installs don't need this — `rails g organizations:install`
+    # already includes everything.
+    #
+    #   rails g organizations:upgrade
+    #   rails db:migrate
+    #
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add the verified-joining tables/columns (organizations 0.5.0) to an existing install"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "add_verified_joining_to_organizations.rb.erb",
+                           File.join(db_migrate_path, "add_verified_joining_to_organizations.rb"),
+                           migration_version: migration_version
+      end
+
+      def display_post_upgrade_message
+        say "\n✅ organizations verified-joining migration created.", :green
+        say "\nNext steps:"
+        say "  1. Run 'rails db:migrate'."
+        say "  2. See the README's \"Verified joining\" section for the new API"
+        say "     (domains, join codes, allowlists, join requests)."
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end