authnz_eleven 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 55b6fa11e7529b08d79c80eb75523f4d65a6f17365987e172a9dea6cb2fe90cd
+  data.tar.gz: fbc4882807a7027a124522082d76c74c932ff6b49581cdebf1d716476193129a
+SHA512:
+  metadata.gz: be92aa5fe4fca9845d5bd0e154aade76ee5a1af6686d6b366ea7831705487efe580808e1db293c1bb39d55787a1349ec5381fa7f31611efc0c876fa1c6a83e5a
+  data.tar.gz: 1f79e1ea9d500ed56be7303ea1f619d874fb7c21c8a856fb1ca761a7c5135ed59c285311dce22e4865c9709a577f071d1c54212b80f7dae11f84737bfc62dd30

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+Initial public release. See the [README](README.md) for features and installation.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Patrick Ziller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,384 @@
+# Authnz Eleven
+
+Authnz Eleven is an authentication **generator** for Rails. It ***is*** intended to be an [all-singing, all-dancing answer to most authentication concerns](https://github.com/rails/rails/pull/52328). Use it to build your own bespoke auth system or model one after an auth system used on a site you know. Most common authentication flows and features can be expressed with it. 
+
+You can think of this gem as a little bit
+like a compiler. It will always try to emit the simplest code possible with the fewest
+parts possible. Anything you don't use, you don't pay any complexity or overhead tax for.
+Because it is generated into your project, customization is
+infinite. If you want three-factor authentication, add it.
+
+The generated architecture is opinionated and has been designed to be easy for humans to understand, easy to extend,
+and hard to get wrong. It aims for strong account protection without making
+ordinary account management needlessly hostile. In addition to standard account
+protection, builds also resist account-squatting, pre-account hijacking, and other kinds of attacks.
+The defaults deliberately balance security, recovery, and convenience.
+
+Quick highlights:
+
+- **Sign in with email, phone, or username.** Phone and email can be verified or optional.
+
+- **Use passwords, passkeys, magic links, social login, SMS sign-in**, or any combination thereof.
+
+- **Optionally, stay coy about the existence of user accounts**. Make flows respond the same whether or not the account exists and resist timing attacks.
+
+- **Complete settings views**. You can leave it as-is or customize.
+
+## Why
+
+You may have heard that you shouldn't roll your own crypto, but you can roll your own auth. This is true, and truer now than ever before. You don't need a library or team of PhDs to design an auth system. But are you prepared to let your agent one-shot it? 
+
+The basic case is easy enough, but depending on what you ask for, it can become quite tricky, and may take several iterations to get right. There are often a large number of edge cases to consider, and the consequences of flubbing one can be very serious. There is no one "spec" to hand off, because every app's authentication requirements are different. Conversely, agents can also be overzealous, adding needless complexity to prevent "bugs" that would in fact be harmless or moot.
+
+Now you could call this under-specification, but that's just the thing: it's a case where the main bottleneck is *decisions* that must made about app behavior. So I went ahead and made them all for you. You can take this as a carefully considered, opinionated, and human-oriented starting point, so you can focus on only what actually needs changing.
+
+## Requirements
+
+Ruby >= 3.4.2
+
+Rails >= 8.0.0
+
+SQLite, PostgreSQL, or MySQL >= 8.0.13
+
+## Install
+
+```ruby
+# Add this to your Gemfile
+gem "authnz_eleven", group: :development
+```
+
+```bash
+# then
+bundle install
+bin/rails generate authnz_eleven --email --password
+bin/rails db:migrate # and whatever other instructions that are described in the post-install message
+```
+
+You must select at least one **identifier** (`--email`, `--phone`, or `--username`)
+and one **sign-in method** (`--password`, `--magic-link`, `--sms-code`, `--omniauth`, or
+`--passkey`).
+
+## Wizard
+
+There are quite a few flags, and some combinations don't work together, so if you'd rather have your hand held there is a wizard:
+
+```ruby
+# Add this to your Gemfile
+gem "huh", github: "marcoroth/huh-ruby", group: :development
+```
+
+```bash
+# then
+bundle install
+bin/rails generate authnz_eleven:wizard
+```
+
+## Sample builds
+
+Each build lists only the flags that give it its shape. Add more to taste: `--trackable --rememberable --pwned --deadboltable --captchable`, and so on. Please note these are rough approximations.
+
+### Hacker News / Reddit (old)
+
+```bash
+bin/rails generate authnz_eleven --username --password --email=optional --no-contactable --recoverable --no-verifiable
+```
+
+### Reddit (modern)
+
+```bash
+bin/rails generate authnz_eleven --username --password --email=optional --phone=optional --recoverable --omniauth
+```
+
+### WhatsApp / Signal
+
+```bash
+bin/rails generate authnz_eleven --phone --sms-code --registration=open-and-invites
+```
+
+### Slack
+
+```bash
+bin/rails generate authnz_eleven --email --magic-link --omniauth --teams --registration=open-and-invites
+```
+
+### GitHub
+
+```bash
+bin/rails generate authnz_eleven --username --email --password --recoverable --passkey --second-factor=totp,webauthn --sudoable
+```
+
+### Online store with guest checkout
+
+```bash
+bin/rails generate authnz_eleven --email --password --recoverable --guestable --rememberable
+```
+
+### Internal tool
+
+```bash
+bin/rails generate authnz_eleven --email --omniauth --registration=invite-only --admin-dashboard --impersonatable
+```
+
+### Shopify
+
+```bash
+bin/rails generate authnz_eleven --email --magic-link --guestable
+bin/rails generate authnz_eleven --user-class=Merchant --namespaced --email --password --second-factor --teams
+```
+
+## Choices
+
+All sessions are backed by a `Session` model. `ActiveSupport::CurrentAttributes` is used to reference the current user/session. Views are ERB.
+
+## Generated code
+
+Every build generates the identity model (`User` by default) and its `Authenticatable` concern,
+`Session`, `Current`, the `Authentication` controller concern, sign in/sign
+out controllers, a `/settings` area with a dashboard, signed-in device list, and delete account. Also a
+starter test suite. A navigation partial is included and will be injected into the layout if it has not been modified yet.
+
+## Registration and identifiers
+
+At least one identifier is needed to create an account, either an email, phone, or username. Having only a single optional email or phone will not work. However, having *both* an optional email *and* optional phone *will* (`--email=optional --phone=optional`), the user will just need to pick which one they want to supply, and this rule will prevent them from changing their email/phone later to remove both.
+
+| Flag | Adds |
+| --- | --- |
+| `--registration[=open\|open-and-invites\|invite-only\|closed]` | Account creation policy: `open` (default) means registration is public. `open-and-invites` allows users to invite others via email or phone, or invite them to teams if using `--teams` too. `invite-only` prevents public registration without an invite. See [Invitations](#invitations). `closed` means accounts must be created some other way in the backend. |
+| `--email[=required[,permanent]\|optional]` | Login with email address. If `required` (default), you may also set `permanent` to prevent users changing it. `optional` with `permanent` is not supported. Email addresses are validated with [valid_email2](https://github.com/micke/valid_email2) and by default also refuse disposable domains. |
+| `--phone[=required[,permanent]\|optional]` | Login with phone number. If `required` (default), you may also set `permanent` to prevent users changing it. `optional` with `permanent` is not supported. Stored in E.164 and validated with [phonelib](https://github.com/daddyz/phonelib). By default all countries are allowed, but you can restrict this in the initializer. |
+| `--username` | A required, unique, unchangeable username. Uniqueness is compared case-insensitively, but the original casing is stored for display. Comes with a customizable blacklist for names like `admin` or `404`, etc. |
+| `--contactable` | **On by default.** Requires that every account hold at least one channel identifier (an email address or phone number) so that you may contact them. |
+| `--verifiable` | **On by default.** Verify ownership of emails and phones by sending a verification email or texting a six-digit code. No-op if you only have usernames. |
+| `--coy` | Never reveal whether an account exists for a given email or phone number in any of the flows. For example, when doing the reset password flow, respond the same way whether an account with that email exists or not. Usernames are considered public and flows concerning them will always respond candidly regardless. Being coy is generally worse for user experience, and although we'll attempt to stymie timing attacks by deferring most timeable work to an `AuthnzElevenDeferredJob`, dedicated analysis can still reveal whether an account exists due to lookup miss vs hit timings. Cannot be used with `--no-verifiable`. |
+| `--encrypted-pii` | Encrypt the email and phone at rest with Active Record Encryption. Covers invitations and `pending_*` fields as well. Encryption is deterministic so `find_by`/`where`/`exists?` and unique indexes will still work, but `LIKE %search%` will not. |
+| `--guestable` | Anonymous guest users. See [Guests](#guests). |
+
+If `--verifiable` is on, sign-up will be staged in a `PendingRegistration` model until the email or phone is verified. If both are required, they both must be verified. Only upon satisfaction of verification and credential requirements will the account be created and added to the `users` table. Doing it like this prevents account-squatting, pre-account hijacking, and keeps the code from having to check if users are verified. One side effect though is that registrations that are abandoned will hang around. You can run the included rake task or schedule the cleanup job by uncommenting the entry in `config/recurring.yml`.
+
+```bash
+bin/rails authnz_eleven:delete_expired_pending_registrations
+```
+
+At this time there is no option to let users in a `--verifiable` build create an account with a grace period before requiring they verify their phone/email, but you can of course hack that in yourself.
+
+## Sign-in methods
+
+Only the sign-in methods for the flags included will exist in the generated build. If you do not specify `--password`, then passwords will not be an available method for signing in.
+
+| Flag | Adds |
+| --- | --- |
+| `--password[=required\|optional\|deferred]` | Password sign-in (`has_secure_password`). `required` (default) puts a mandatory password field on the sign-up form. `optional` lets you leave it blank. `deferred` puts password input after email/phone verification.|
+| `--magic-link` | Sign in by emailed link. Requires `--email`. |
+| `--sms-code` | Sign in by texted six-digit code. Requires `--phone`. |
+| `--passkey` | Passkeys as a passwordless first-factor using the `webauthn` gem. |
+| `--omniauth` | Social / SSO login via `omniauth` gem. You will need to set up a provider in the included initializer. |
+
+## Passwords
+
+**Disclaimer**: I do not recommend using passwords if you can avoid it. They are phishable, easy to forget, often make up the majority of IT support calls, and engender a need for more mechanisms in order to keep accounts safe. The few advantages are that they are conceptually simple and familiar to users and easy to share. Many websites will require passwords and then bolt on passkeys as an alternative sign-in method. I say that this is requiring user accounts to have a phishing vector. Better to not include passwords at all. All that being said, if you must use passwords, I suggest including another sign-in method as well, and `--pwned` and `--deadboltable` at the very least. It is up to your wisdom which of the others to include, based on your cohort of users.
+
+Any one of the following will imply the `--password` flag.
+
+| Flag | Adds |
+| --- | --- |
+| `--recoverable` | Password reset by emailed link. |
+| `--pwned` | `not_pwned` validation against Have I Been Pwned using `pwned` gem. |
+| `--strong-passwords` | Reject weak passwords by their `zxcvbn` strength score, adjustable in initializer. |
+| `--deadboltable` | Too many failed sign-ins deadbolts the password door shut for a duration. A deadbolted account may still use other sign in methods, like passkeys or magic links, because they are not guessable, and if an attacker has access to your email they can just reset your password anyway. Use `authenticate_with_password` instead of `authenticate`. |
+| `--password-rotatable` | Require changing passwords every 90 days (by default). The user will be held at the change-password page until they set a new one. **Note**: NIST SP 800-63B advises *against* forced rotation because it encourages formulaic passwords.  |
+| `--password-historical` | Reject a password matching any of the last 5 (default).
+
+## Sessions
+
+Control how long sessions may exist and under what conditions they be created.
+
+| Flag | Adds |
+| --- | --- |
+| `--rememberable` | A "remember me" checkbox on password sign-in. Checked, the cookie gets a lifetime that survives the browser closing. Unchecked, it's a browser-session cookie. |
+| `--timeoutable` | Expire sessions after a period of inactivity. |
+| `--max-sessionable[=evict\|prompt]` | Cap concurrent sessions. `evict` (default) signs out the least-recently-active session. `prompt` holds the new sign-in at the session list until the user signs one out. |
+
+## API tokens
+
+`--api-tokens` adds personal access tokens and a management page at `/settings/api_tokens`. Users can create and revoke tokens. Secrets are shown once and stored only as digests. Tokens expire after 90 days.
+
+### Using tokens in your API
+
+The generator includes an `ApiTokenAuthentication` concern that provides bearer authentication. Include it in your own API controller:
+
+```ruby
+class Api::ApplicationController < ActionController::API
+  include ApiTokenAuthentication
+end
+
+class Api::ProfileController < Api::ApplicationController
+  def show
+    render json: { id: current_api_user.id }
+  end
+end
+```
+
+Clients send `Authorization: Bearer <token>`. Your actions have access to `current_api_user` and `current_api_token`. Invalid, expired, or revoked tokens receive a JSON `401`.
+
+Token authentication does not create browser sessions. Signing out or changing a password leaves tokens active. Revocation and expiry end access. Banning or deleting the account removes its tokens. With `--security-notifications`, creation and revocation send an email.
+
+For namespaced identities, use `Realtors::ApiTokenAuthentication` and `Realtor::ApiToken`.
+
+## Activity
+
+| Flag | Adds |
+| --- | --- |
+| `--last-seenable` | A `last_seen_at` column on users, touched at sign-in and refreshed periodically. |
+| `--trackable` | An `Event` audit trail of authentication activity, browsable at `/settings/authentications/events`. Records the sign-in method used. |
+
+## Hardening
+
+There are many hardening measures included in every build, like rate limits and disallowing reuse of tokens. These flags are about behavior observable to the user.
+
+| Flag | Adds |
+| --- | --- |
+| `--second-factor[=totp\|webauth\|sms]` | Add two-factor authentication. You can adjust which sign-in methods require a 2nd factor in the initializer. `totp` ("time-based one-time password", the default) uses an authenticator app, `webauthn` is hardware security keys (like passkeys but for 2nd factor), and `sms` is a one-time code texted to the user's phone. You may use multiple, like so: `--second-factor=totp,webauthn,sms`. Enrolling in a 2FA method will create encrypted recovery codes and show them to the user only once, and they can be regenerated if lost. `sms` needs `--phone`, and will not work with `--sms-code` since the sign-in method and the 2FA method would be exactly the same. |
+| `--sudoable` | Re-require user authentication before dangerous actions. See [Sudo](#sudo). A partial template and controller class methods are included to simplify setup. Will challenge the user with an auth method based on what methods the user has available. |
+| `--captchable` | A captcha (Cloudflare Turnstile is the only provider included for now) partial template is included and used inline on the unauthenticated forms: sign-in, sign-up, password reset, magic link, texted-code sign-in. Reuse on any form you want. |
+| `--security-notifications` | Email users when credentials, second factors, connected accounts, contact information, sessions, or the account itself change. Requires `--email`. |
+
+## Administration
+
+| Flag | Adds |
+| --- | --- |
+| `--adminable` | Users can be site admins. Cannot be created from ActiveRecord, must be created directly in the DB. For example, `echo "UPDATE users SET admin = true …;" \| bin/rails dbconsole` |
+| `--admin-dashboard` | An `/admin` area (dashboard, users, sessions). Responds with a `404` unless the user is an admin. If `--second-factor` is included, admins are held at 2FA enrollment until they enroll one. Implies `--adminable`. |
+| `--bannable` | Admins can ban users temporarily or permanently. Immediately kicks the user out and locks login. |
+| `--impersonatable` | Admins can impersonate other users, with the true user being accessible through `Current.true_user`. Impersonation automatically expires after 1 hour (default). Useful for support or bug investigation. Implies `--adminable`. |
+| `--easy-dev-login` | **Development only.** Bypass the sign-in form and sign in as anyone in development. Use any email/phone/username. If using `--password` then the password is ignored. If not, there will be a dedicated endpoint at `POST /easy_dev_login`. Set `REQUIRE_DEV_PASSWORD` and `REQUIRE_DEV_MFA` ENV variables to use real flows. |
+
+## Teams
+
+| Flag | Adds |
+| --- | --- |
+| `--teams[=scope\|middleware\|session]` | Add `Team`, `Membership`, and team creation/selection. `scope` (default) namespaces team pages under a `/:team_id` route scope (or `/<identity>/:team_id` for a namespaced identity), allowing separate tabs to be open with different teams on the same session, and for links to be easily shareable. `middleware` does the same thing but using middleware, as seen in 37signals apps: it peels a leading `/:team_id` onto `SCRIPT_NAME`, so every route in the app carries it without being written inside a scope (not available with `--namespaced`). `session` stores the team on the session instead, so the team identifier is not in the url, but you're limited to one active team per session. A namespaced identity gets its own teams (`Merchant::Team`, `Merchant::Membership`). |
+
+## Identity classes
+
+You can customize the identity class used in generation.
+
+| Flag | Adds |
+| --- | --- |
+| `--user-class=NAME` | Rename the generated identity (default `User`). The table, sessions, routes, controllers and config constant all derive from it. |
+| `--namespaced` | Give the identity its own URL prefix and namespace. **This is required when generating a second identity** so it doesn't collide with the first. |
+| `--primary-key-type=TYPE` | Primary key type for the generated migrations (e.g. `uuid`). |
+
+Most apps will only ever need one user identity class and can utilize roles or admin flags to differentiate user types. However, if you need totally separate authentication methods or namespaces, you may run the generator again with `--namespaced` and a different `--user-class` to get a second, fully independent auth stack: its own model, table, sessions, controllers, routes, and flags.
+
+```bash
+bin/rails generate authnz_eleven --email --password --guestable
+bin/rails generate authnz_eleven --email --phone --passkey --timeoutable --user-class=Realtor --namespaced
+```
+
+That gives you a `Realtor` model that signs in at `/realtor/sign_in`, `Realtors::SessionsController`,
+`realtor_sign_in_path`, a `Realtor::Session` and a `Realtors::BaseController`.
+It's purely additive. No file from the first run is touched.
+
+A namespaced identity is its own portal, the way a Rails engine is. `Realtors::BaseController`
+inherits `ActionController::Base`, not your `ApplicationController`, and renders
+a `realtors` layout. Nothing you change in one identity's auth code reaches the other.
+
+## Invitations
+
+When using an invitable registration mode, you can send invitations to both emails and phone numbers if the invitee doesn't already have an account. The `User` is not created until the invitee accepts the invitation. 
+If teams are enabled as well, the you can also invite existing users to a team using email or phone.
+
+## Guests
+
+`--guestable` adds anonymous users. A guest is a **real `User` row** (`guest: true`) with a **real session**, so they get a real `Current.user` and your existing code should work unchanged. Guests are not considered `authenticated?` though.
+
+Opt a controller in with `allow_guest_access`:
+
+```ruby
+class CartsController < ApplicationController
+  allow_guest_access
+
+  def show
+    @cart = Current.user.cart   # both authenticated users and guest users can have carts
+  end
+end
+```
+
+When a guest signs in or signs up, `absorb_guest` in `User::Guestable` is called from the `Authentication` concern and transfers the guest state onto the authenticated account, then destroys the guest row:
+
+```ruby
+def absorb_guest(guest)
+  transaction do
+    guest.cart&.update!(user: self)
+    guest.destroy
+  end
+end
+```
+
+Guests sessions will pile up, so run the included rake task or schedule the cleanup job by uncommenting the entry in `config/recurring.yml`.
+
+```bash
+bin/rails authnz_eleven:delete_expired_guests
+```
+
+A guest's age is measured from creation, not last activity, and guests are exempt from `--timeoutable`. Their cookie persists for that lifetime, so returning visitors reuse their guest account even after closing the browser.
+
+## Sudo
+
+`--sudoable` generates two macros, for two different use cases:
+
+```ruby
+require_sudo only: :destroy                 # require the sudo challenge answer as a param in a single request
+require_sudo_within 10.minutes              # guard a collection of routes
+```
+
+`require_sudo` is for a single dangerous action. Include the password (or webauthn credential, or
+code) in a field on the form you submit. `require_sudo_within` guards a
+whole section and keeps it unlocked for the window. 
+
+A successful sudo confirmation stamps the session's `sudo_at` column. `require_sudo_within` checks that that timestamp is within the window, otherwise the user is redirected to a separate confirmation page, then back to the originally requested protected page.
+
+Use `require_sudo_within` on pages that can safely be requested again. It redirects back to the original URL; it does not replay a submitted form or preserve an OAuth callback's provider authentication data.
+
+Out of the box, sudo guards actions that create persistent access to the account, or that can't be undone:
+
+- changing the email address
+- changing the phone number
+- adding a passkey or security key
+- creating an API token
+- deleting the account
+
+Sudo only works with a password, passkey, or a TOTP/webauthn 2nd factor. Accounts that only use magic links, SMS OTPs, or logins from an Omniauth provider cannot perform a sudo and will not be asked for one.
+
+## Configuration
+
+`config/initializers/authentication.rb` holds every config, aliased to a top-level constant, `UserAuth` (default), so you can reference `UserAuth.session.idle_timeout`. I suggest you read that file to understand the different options. A namespaced identity gets its own config constant, for example `RealtorAuth`.
+
+The flags you generated the build with are posted in a comment at the top of the file.
+
+## Upgrading or transmuting
+
+Because authentication is generated into your app, there is no automated way to change to a new version or different set of flags in the future after you have added your own code in there, like you may be able to do in some runtime auth gems. However, you can generate a new separate build with the flags you want, and point an agent at it to fix your app to use the auth system of the new one. Don't forget to do data migrations and update your UI as well. Overall this seems to be effective because the chance of the agent messing up or building something awkward is greatly diminished by the fact that it has a reference implementation, a "spec", to look at.
+
+## Notes
+
+- `/settings` uses the top-level `Settings` constant. If your app already
+  defines one (the [`config`](https://github.com/rubyconfig/config) gem does),
+  [rename it before generating](https://github.com/rubyconfig/config#configuration).
+  
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests and style.
+
+## Acknowledgments
+
+This gem was heavily inspired by [`authentication-zero`](https://github.com/lazaronixon/authentication-zero), [`devise`](https://github.com/heartcombo/devise), and [`rodauth`](https://github.com/jeremyevans/rodauth). Thank you.
+
+## Author
+
+Patrick Ziller
+
+## License
+
+MIT, see [LICENSE.txt](LICENSE.txt).

data/lib/authnz_eleven/identity.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module AuthnzEleven
+  # Derives every name the generator needs from a single class name, using Rails'
+  # inflector so the generated code agrees with what Rails itself computes at
+  # runtime (route keys, table names, foreign keys).
+  #
+  # The default identity (class "User", not namespaced) is the plain case: User,
+  # /sign_in, Session, Authentication. Only a renamed (`--user-class`) and/or
+  # namespaced identity diverges, and every accessor below says how.
+  class Identity
+    DEFAULT_CLASS_NAME = "User"
+
+    attr_reader :class_name
+
+    def initialize(class_name: nil, namespaced: false)
+      name = class_name.to_s.strip
+      @class_name = (name.empty? ? DEFAULT_CLASS_NAME : name).camelize
+      @namespaced = namespaced
+    end
+
+    def namespaced? = @namespaced
+
+    # The canonical, unchanged build: plain "User", no namespace.
+    def default? = @class_name == DEFAULT_CLASS_NAME && !namespaced?
+
+    # Core inflections: "user"/"users" for the default, e.g. "realtor"/"realtors".
+    def singular = @class_name.underscore
+    def plural = singular.pluralize
+    def table = plural
+    def foreign_key = "#{singular}_id"
+
+    # Route + controller slugs. They track the class name (for the default that is
+    # the familiar user/users); the URL *path*, however, is only prefixed once
+    # namespaced (see #path_prefix), so the default keeps top-level /sign_in.
+    #
+    # route_scope       -> route "as:" stem, e.g. user_sign_in_path
+    # controller_module -> module: :users / Users::SessionsController
+    def route_scope = singular
+    def controller_module = plural
+
+    # Camelized forms for class/module declarations in templates.
+    # module_name     -> "Users"    (Users::SessionsController)
+    # settings_module -> "Settings" (Settings::PasswordsController)
+    def module_name = controller_module.camelize
+    def settings_module = nested_module("Settings")
+
+    # An area (settings, admin, teams) sits at the top level for the default
+    # identity and inside the identity's own namespace once namespaced: its files,
+    # its module, and its route helpers.
+    def nested_path(name) = namespaced? ? "#{controller_module}/#{name}" : name
+    def nested_module(name) = namespaced? ? "#{module_name}::#{name}" : name
+    def nested_helper(name) = namespaced? ? "#{route_scope}_#{name}" : name
+
+    # URL path scope: bare for the default identity (so /sign_in stays /sign_in),
+    # the identity's own name once namespaced.
+    def path_prefix = namespaced? ? singular : nil
+
+    # Where the self-service area's controllers, views and tests are *filed*:
+    # a plain top-level "settings" directory for the default identity. A namespaced
+    # identity's settings controllers, by contrast, live *inside* the same outer
+    # route scope as its other controllers (see namespaced_route_block), which sets
+    # `module: identity.controller_module` once for everything nested in it — so
+    # the directory must nest under controller_module here too, or the settings
+    # controllers get filed (and named) under a namespace the routes never
+    # actually point at.
+    def settings_path_prefix = nested_path("settings")
+
+    # The settings area's own base controller, mirroring AdminController: every
+    # Settings:: controller inherits it, so an exemption that belongs to the
+    # whole area is declared once.
+    def settings_controller = "#{settings_module}Controller"
+    def settings_controller_file = "#{settings_path_prefix}_controller"
+
+    # The *route-helper* stem for that same area — not simply the directory with
+    # slashes swapped. settings_path_prefix is plural (controller_module) so the
+    # controllers file/name correctly under Admins::Settings::…, but the settings
+    # routes nest inside the outer scope's `as: route_scope` (singular), so their
+    # helpers are admin_settings_… — not admins_settings_…. Use this for
+    # `#{…}_*_path/url`; use settings_path_prefix for file paths, and
+    # settings_module for the module name.
+    def settings_helper_prefix = nested_helper("settings")
+
+    # A generic name (Session, Current, Team, ...) belongs to the default identity.
+    # A namespaced identity nests its own copy inside its model class, where Rails
+    # infers associations (Realtor's has_many :sessions finds Realtor::Session),
+    # prefixes the table (realtor_sessions) and demodulizes foreign keys
+    # (session_id), so no association needs a class_name.
+    def namespaced_class(name) = namespaced? ? "#{@class_name}::#{name}" : name
+    def table_for(klass) = klass.underscore.tr("/", "_").pluralize
+
+    # Two identities can be signed in at once (separate cookies), never
+    # clobbering each other.
+    def session_class = namespaced_class("Session")
+    def session_file = session_class.underscore
+    def sessions_table = table_for(session_class)
+    def cookie_name = namespaced? ? "#{singular}_session_token" : "session_token"
+
+    # Each identity owns an independent set of authentication tunables, reachable
+    # two ways (the initializer sets up both, pointing at the same object):
+    #
+    #   config_storage  -> Rails.configuration.x.user_auth  (the Rails-native slot,
+    #                      source of truth; still works for anything expecting it)
+    #   config_constant -> UserAuth                         (a short top-level alias
+    #                      the generated code actually reads — UserAuth.session.…)
+    #
+    # config_reference is the constant: it's what every read site resolves to, so a
+    # single seam flips them all. A namespaced identity gets its own pair (RealtorAuth /
+    # Rails.configuration.x.realtor_auth) so two identities never share tunables.
+    def config_namespace = "#{singular}_auth"
+    def config_storage   = "Rails.configuration.x.#{config_namespace}"
+    def config_constant  = "#{@class_name}Auth"
+    def config_reference = config_constant
+    def initializer_file = default? ? "authentication" : "#{singular}_authentication"
+
+    # A namespaced identity's task gets its own namespace so it cannot sweep another identity's
+    # sessions.
+    def task_namespace = namespaced? ? singular : nil
+    def rake_task(name) = ["authnz_eleven", task_namespace, name].compact.join(":")
+
+    # The controller-level concerns. "Authentication" for the default identity
+    # (included in ApplicationController); Realtors::Authentication once namespaced,
+    # in the same namespace as the identity's controllers and included by its
+    # base controller.
+    def authentication_concern = nested_module("Authentication")
+    def authentication_concern_file = authentication_concern.underscore
+    def authorization_concern = nested_module("Authorization")
+    def authorization_concern_file = authorization_concern.underscore
+
+    # The base controller a namespaced identity's controllers inherit from
+    # (e.g. Realtors::BaseController). Unused for the default identity, which wires
+    # the concern straight into ApplicationController.
+    def base_controller = "#{controller_module.camelize}::BaseController"
+    def base_controller_file = "#{controller_module}/base_controller"
+
+    # What this identity's own controllers (sessions, registrations, account
+    # area, ...) inherit from: ApplicationController for the default identity;
+    # the identity's own BaseController once namespaced, so its authentication
+    # concern is never injected into the shared ApplicationController.
+    def controller_superclass = namespaced? ? base_controller : "ApplicationController"
+
+    # Mailers. Shared "UserMailer"/"InvitationMailer" for the default identity; a
+    # namespaced identity gets its own so two identities' mailers (and mailer views,
+    # which Rails locates by the mailer's underscored name) never collide.
+    def mailer_class = namespaced? ? "#{@class_name}Mailer" : "UserMailer"
+    def mailer_file = mailer_class.underscore
+
+    def current_class = namespaced_class("Current")
+    def current_file = current_class.underscore
+
+    def event_class = namespaced_class("Event")
+    def event_file = event_class.underscore
+    def events_table = table_for(event_class)
+
+    def api_token_class = namespaced_class("ApiToken")
+    def api_token_file = api_token_class.underscore
+    def api_tokens_table = table_for(api_token_class)
+
+    def recovery_code_class = namespaced_class("RecoveryCode")
+    def recovery_code_file = recovery_code_class.underscore
+    def recovery_codes_table = table_for(recovery_code_class)
+
+    # Named for the credential, not for one of its roles: this table holds passkeys
+    # as well as second-factor security keys.
+    def webauthn_credential_class = namespaced_class("WebauthnCredential")
+    def webauthn_credential_file = webauthn_credential_class.underscore
+    def webauthn_credentials_table = table_for(webauthn_credential_class)
+
+    def password_history_class = namespaced_class("PasswordHistory")
+    def password_history_file = password_history_class.underscore
+    def password_histories_table = table_for(password_history_class)
+
+    def invitation_class = namespaced_class("Invitation")
+    def invitation_file = invitation_class.underscore
+    def invitations_table = table_for(invitation_class)
+
+    def omniauth_identity_class = namespaced_class("OmniauthIdentity")
+    def omniauth_identity_file = omniauth_identity_class.underscore
+    def omniauth_identities_table = table_for(omniauth_identity_class)
+
+    def pending_registration_class = namespaced_class("PendingRegistration")
+    def pending_registration_file = pending_registration_class.underscore
+    def pending_registrations_table = table_for(pending_registration_class)
+
+    def team_class = namespaced_class("Team")
+    def team_file = team_class.underscore
+    def teams_table = table_for(team_class)
+
+    def membership_class = namespaced_class("Membership")
+    def membership_file = membership_class.underscore
+    def memberships_table = table_for(membership_class)
+
+    # The two things an account and a sign-up-in-progress must agree about: what
+    # identifies them, and what makes a password acceptable. Both are included by
+    # the model and by PendingRegistration, so a form that validates while staged
+    # still validates when it becomes a row.
+    def principals_concern = namespaced_class("Principals")
+    def principals_concern_file = principals_concern.underscore
+    def password_policy_concern = namespaced_class("PasswordPolicy")
+    def password_policy_concern_file = password_policy_concern.underscore
+
+    def nav_partial = namespaced? ? "#{controller_module}/authnz_eleven_nav" : "shared/authnz_eleven_nav"
+
+    def sudo_partial
+      namespaced? ? "#{controller_module}/authnz_eleven_sudo_challenge" : "shared/authnz_eleven_sudo_challenge"
+    end
+  end
+end