organizations 0.4.2 → 0.5.0

data/config/locales/es.yml

@@ -0,0 +1,126 @@
+# Organizations gem — Spanish locale.
+#
+# Ships with the gem so Spanish-market hosts get correct end-user copy out of
+# the box (the first two production hosts of this gem are Spanish products).
+# Keep key parity with en.yml — en.yml is the catalog SSOT; this file must
+# always answer the same keys. Tone: neutral "tú", consistent with typical
+# Spanish SaaS copy.
+es:
+  organizations:
+    roles:
+      owner: "Propietario"
+      admin: "Administrador"
+      member: "Miembro"
+      viewer: "Observador"
+
+    invitation_status:
+      pending: "Pendiente"
+      accepted: "Aceptada"
+      expired: "Caducada"
+
+    # En minúsculas a propósito: se interpolan a mitad de frase en
+    # errors.join_request_already_decided.
+    join_request_status:
+      pending: "pendiente"
+      approved: "aprobada"
+      rejected: "rechazada"
+      withdrawn: "retirada"
+      expired: "caducada"
+
+    errors:
+      join_code_invalid: "Este código no es válido"
+      join_code_exhausted: "Este código ya ha alcanzado su límite de usos"
+
+      join_request_expired: "Esta solicitud ha caducado"
+      join_request_already_decided: "Esta solicitud ya está %{status}"
+      join_request_already_member: "Ya eres miembro de esta organización"
+      join_request_create_failed: "No se ha podido crear la solicitud"
+      join_request_membership_gone: "La solicitud se aprobó pero la membresía ya no existe"
+
+      membership_vetoed: "Ahora mismo no puedes unirte a esta organización"
+
+      verification_email_invalid: "Esta dirección de email no es válida"
+      verification_email_not_eligible: "Ese email no pertenece a esta organización"
+      verification_email_already_claimed: "Ese email ya está asociado a un miembro de esta organización"
+      verification_code_invalid: "El código no es correcto"
+      verification_code_missing: "No hay ningún código de verificación activo para esta solicitud"
+      verification_code_expired: "El código ha caducado — pide uno nuevo"
+      verification_attempts_exceeded: "Demasiados intentos — pide un código nuevo"
+      verification_sends_exceeded: "Se han pedido demasiados códigos para esta solicitud"
+      verification_resend_throttled: "Espera un momento antes de pedir otro código"
+      account_email_trust_disabled: "La verificación por email de cuenta está desactivada (config.trust_confirmed_account_email)"
+      account_email_unconfirmed: "El email de la cuenta no está confirmado"
+      not_accepting_requests: "Esta organización no acepta solicitudes ahora mismo"
+
+      invitation_expired: "Esta invitación ha caducado"
+      invitation_already_accepted: "Esta invitación ya ha sido aceptada"
+      invitation_cannot_resend_accepted: "No se puede reenviar una invitación ya aceptada"
+      invitation_email_mismatch: "Esta invitación se envió a otra dirección de email"
+      invitation_accept_as_owner: "No se puede aceptar una invitación como propietario. Invita como administrador y transfiere la propiedad después."
+      invitation_already_member: "Esa persona ya es miembro de esta organización"
+      invite_as_owner: "No se puede invitar como propietario. Invita como administrador y transfiere la propiedad después."
+      invite_not_a_member: "Solo los miembros de la organización pueden enviar invitaciones"
+      invite_not_authorized: "No tienes permiso para invitar miembros"
+
+      cannot_remove_owner: "No se puede eliminar al propietario de la organización. Transfiere la propiedad primero."
+      cannot_add_as_owner: "No se puede añadir un miembro como propietario. Usa la transferencia de propiedad."
+      cannot_promote_to_owner: "No se puede ascender a propietario. Usa la transferencia de propiedad."
+      cannot_demote_owner_directly: "No se puede degradar al propietario directamente. Usa la transferencia de propiedad."
+      cannot_demote_owner: "No se puede degradar al propietario. Transfiere la propiedad primero."
+      promote_not_higher: "No se puede ascender a %{new_role}: no es un rol superior a %{role}"
+      demote_not_lower: "No se puede degradar a %{new_role}: no es un rol inferior a %{role}"
+      transfer_no_owner: "No se puede transferir la propiedad porque la organización no tiene propietario"
+      transfer_to_non_member: "No se puede transferir la propiedad a alguien que no es miembro"
+      transfer_to_non_admin: "No se puede transferir la propiedad a alguien que no es administrador. Asciéndele primero."
+
+      cannot_leave_as_last_owner: "No puedes salir de la organización siendo su único propietario. Transfiere la propiedad primero."
+      cannot_leave_last_organization: "No puedes salir de tu única organización"
+      organization_limit_reached: "Has alcanzado el máximo de organizaciones (%{max})"
+      no_current_organization_to_leave: "No hay ninguna organización activa de la que salir"
+      cannot_delete_user_owns_organizations: "No se puede eliminar un usuario que aún es propietario de organizaciones. Transfiere la propiedad o elimina esas organizaciones primero."
+
+      unauthorized_role: "Necesitas acceso de %{role} para hacer esto"
+      unauthorized_permission: "No tienes permiso para %{permission}"
+      unauthorized: "No estás autorizado para hacer esto"
+      not_a_member: "No eres miembro de esta organización"
+      organization_required: "Se requiere una organización"
+      cannot_change_own_role: "No puedes cambiar tu propio rol"
+      invalid_role: "Rol no válido: %{role}"
+
+    notices:
+      welcome: "¡Ya formas parte de %{organization}!"
+      already_member: "Ya eres miembro de %{organization}."
+      select_or_create_organization: "Selecciona o crea una organización."
+
+    attributes:
+      membership_taken: "ya es miembro de esta organización"
+      owner_taken: "ya existe un propietario para esta organización"
+      pending_request_taken: "ya tiene una solicitud pendiente para esta organización"
+      invitation_taken: "ya ha sido invitado a esta organización"
+      allowlist_taken: "ya está en la lista de esta organización"
+      domain_invalid: "no es un nombre de dominio válido"
+
+    mailers:
+      from_team: "El equipo"
+      invitation:
+        subject: "%{inviter} te ha invitado a unirte a %{organization}"
+        header: "¡Te han invitado!"
+        title: "¡Te han invitado a unirte a %{organization}!"
+        greeting: "Hola,"
+        invited_by: "%{inviter} te ha invitado a unirte a %{organization}."
+        invited_by_html: "<strong>%{inviter}</strong> te ha invitado a unirte a <strong>%{organization}</strong>."
+        invited_generic: "Te han invitado a unirte a %{organization}."
+        invited_generic_html: "Te han invitado a unirte a <strong>%{organization}</strong>."
+        joining_as: "Te unirás como: %{role}"
+        joining_as_label: "Te unirás como:"
+        accept_cta: "Acepta tu invitación aquí:"
+        accept_button: "Aceptar invitación"
+        copy_link: "O copia y pega este enlace en tu navegador:"
+        expires_on: "Esta invitación caducará el %{date}."
+        ignore: "Si no esperabas esta invitación, puedes ignorar este email."
+      verification:
+        subject: "%{code} es tu código de verificación de %{organization}"
+        lead: "Usa este código para verificar tu email y unirte a %{organization}:"
+        lead_html: "Usa este código para verificar tu email y unirte a <strong>%{organization}</strong>:"
+        expires: "El código caduca en %{minutes} minutos."
+        ignore: "Si no has pedido este código, puedes ignorar este email — nadie puede unirse a %{organization} con tu dirección sin él."

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
   # ============================================================================