thoughtbot/clearance

This system is a Ruby gem that provides authentication and authorization capabilities for Rails applications. It manages user sessions, sign-in, sign-up, and password reset flows through configurable Rack middleware and controller modules. The system supports customizable password hashing strategies, routing constraints based on authentication state, and includes generators for scaffolding tests and views.

21 changes.

The project refactored its core authentication logic into modular components and Rack middleware, moving away from traditional Rails controller patterns. It simultaneously modernized the user interface with HTML5 forms, configurable routes, and customizable views, while significantly expanding test coverage and CI configuration to support newer Ruby and Rails versions.

14 changes.

This period focused on enhancing authentication flexibility by introducing routing constraints for signed-in and signed-out states, alongside a configurable sign-in guard stack. The project also expanded its testing capabilities by adding comprehensive RSpec integration test generators, feature specs, and a dedicated dummy Rails application for isolated testing.

9 changes.

This period focused on significantly expanding test coverage for the Clearance gem, including acceptance tests for installation, unit tests for password strategies, and request specs for authentication behavior. It also involved updating database migration templates to enforce unique constraints and support configurable primary keys.

The application now sends password reset emails to users. A new ClearanceMailer class has been introduced to handle the delivery of these messages, utilizing the configured mailer sender and localized subject lines.

app/mailers · high confidence

Users can now run \rails generate clearance:specs\ to automatically create RSpec integration tests for their application. The generator intelligently detects the installed RSpec version and configures the generated specs to use \rails\_helper\ for RSpec 3+ or \spec\_helper\ for older versions, ensuring compatibility with the user's testing setup.

lib/generators/clearance/specs · high confidence

A new bin/setup script has been added to streamline the local development environment setup. This script automates the installation of required gems (including Bundler and Appraisal) and configures the test database by dropping and recreating it, ensuring a consistent state for running tests against multiple Rails versions.

bin · high confidence

The password hashing implementation has been refactored into distinct strategy modules. A new Argon2 strategy is added, utilizing the \argon2\ gem for authentication and password storage. The existing BCrypt strategy is now a dedicated module that supports configurable hashing costs via \BCrypt::Engine.cost\, while automatically using the minimum cost in test environments to improve speed. This change allows users to choose their preferred hashing algorithm and tune security parameters.

_lib/clearance/password\strategies · high confidence

A new \clearance:views\ generator has been added, allowing users to copy the default Clearance views and locale files directly into their project for customization. This generator creates copies of the base views (such as sessions, passwords, and users) and associated locale files, giving developers full control over the authentication UI and text.

lib/generators/clearance/views · high confidence

The application now provides \Clearance::Constraints::SignedIn\ and \Clearance::Constraints::SignedOut\ classes that can be used in \config/routes.rb\ to restrict route visibility based on authentication status. Routes constrained with \SignedIn\ will return a 404 for unauthenticated users, and support an optional block to enforce additional user requirements (e.g., admin status). Routes constrained with \SignedOut\ will return a 404 for authenticated users, explicitly handling cases where the session data is missing to prevent errors.

lib/clearance/constraints · high confidence

The project now includes ERB template linting via a new \.erb\_lint.yml\ configuration and a corresponding \erb\_lint\ Rake task, which is integrated into the default CI workflow. The testing matrix has been expanded to include Rails 7.2, 8.0, and 8.1, and the repository structure has been updated with new configuration files for code ownership (\.github/CODEOWNERS\), contribution guidelines (\CONTRIBUTING.md\), and security reporting (\SECURITY.md\).

(repo-wide) · high confidence

The authentication and authorization logic in Clearance has been refactored into distinct modules: \Clearance::Authentication\ (handling \sign\_in\, \sign\_out\, \current\_user\, and CSRF rotation), \Clearance::Authorization\ (handling \require\_login\, \deny\_access\, and redirect logic), and \Clearance::Controller\ (which includes both). This change introduces a configurable sign-in guard stack via \Configuration\#sign\_in\_guards\, allowing developers to intercept or modify the sign-in process. Additionally, the \Clearance::BackDoor\ middleware is now explicitly configurable via \allowed\_backdoor\_environments\ to restrict its use to specific environments like test or development, and the \RackSession\ middleware now supports signed cookies via the \signed\_cookie\ configuration option.

lib/clearance · high confidence

The application now conditionally registers authentication routes based on configuration settings. Users can disable all authentication routes entirely via a new \routes\_enabled\ setting. Additionally, sign-up and password-reset functionality are now optional; the sign-up route is only added if \allow\_sign\_up\ is enabled, and the password-edit/update routes are only added if \allow\_password\_reset\ is enabled.

config · high confidence

The Clearance routes generator has been updated to explicitly copy the default route definitions (including sign-in, sign-up, and password management paths) into the application's config/routes.rb file. Additionally, the generator now automatically sets config.routes to false in the Clearance initializer, ensuring that the application relies solely on the copied routes rather than the gem's internal routing logic.

lib/generators/clearance/routes · high confidence

Users can now implement custom logic to control the sign-in process through a new \SignInGuard\ system. This change adds \lib/clearance/sign\_in\_guard.rb\ and \lib/clearance/session\_status.rb\, providing a base class for creating custom guards (e.g., to require email confirmation) and status classes to represent success or failure. The guard stack allows developers to intercept sign-in attempts, fail the process with custom messages, or short-circuit the chain, offering fine-grained control over authentication behavior beyond the default flow.

clearance · high confidence

The password reset flow now uses dedicated views (new, edit, create) that display user-facing messages via locale translations instead of dynamic form helpers. The 'new' view uses an HTML5 email input field for the user's email address, and the 'edit' view allows users to set a new password. All text is externalized to locales, and the markup is wrapped in a 'clearance' div for styling.

app/views/passwords · high confidence

The user sign-up interface has been updated to use HTML5-compliant email input fields for better browser validation and user experience. Additionally, the password confirmation field has been removed from the form, simplifying the sign-up process. The markup now includes a specific wrapper for the clearance gem and utilizes translation helpers for consistent text management.

app/views/users · high confidence

The authentication controllers (Sessions, Passwords, Users) now inherit from a new \Clearance::BaseController\, allowing the parent controller class to be configured via \parent\_controller\. This change standardizes behavior across controllers, such as redirecting signed-in users to a configurable URL and skipping the \require\_login\ filter for public actions. Additionally, the controllers now use \before\_action\ instead of the deprecated \before\_filter\, handle HTTP status codes more explicitly (e.g., \:unprocessable\_content\ for validation errors), and deliver password reset emails inline using \deliver\_now\.

app/controllers · high confidence

The authentication mechanism has been moved from the Rails controller layer to a Rack middleware component (Clearance::RackSession). This change alters how the application handles session management and user authentication, shifting the core logic out of the typical Rails controller flow and into the middleware stack.

lib · high confidence

The sign-in view has been restructured to render a shared partial (\_form.html.erb), which standardizes the login interface and facilitates the addition of other authentication methods. This partial now conditionally displays 'Sign up' and 'Forgot password' links based on the application's configuration settings (allow\_sign\_up? and allow\_password\_reset?), ensuring that these options only appear when explicitly enabled. The main view wraps this form in a semantic container with the 'clearance' ID, improving markup structure and maintainability.

app/views/sessions · high confidence

The Clearance install generator now intelligently manages existing User models and database tables. If a User model already exists, the generator injects the \Clearance::User\ module directly into the class body rather than overwriting the file. Similarly, if the users table already exists, it generates a migration that adds only the missing Clearance columns (email, encrypted\_password, confirmation\_token, remember\_token) and indexes, rather than creating a new table. This prevents conflicts and data loss for applications that already have a User model in place.

lib/generators/clearance/install · high confidence

The change password email views (HTML and text versions) now use the user's confirmation\_token instead of the previous token field to generate the password reset link. This aligns with the backend split of token fields into confirmation\_token, remember\_token, and remember\_token\_expires\_at, ensuring the email directs users to the correct endpoint for changing their password.

_app/views/clearance\mailer · high confidence

The install generator templates have been updated to reflect current best practices and security standards. The generated README now instructs users to use \rails db:migrate\ instead of the deprecated \rake db:migrate\, and provides updated layout code using \button\_to\ for sign out actions. The generated \clearance.rb\ configuration now defaults \config.rotate\_csrf\_on\_sign\_in\ to true to enhance security by resetting CSRF tokens on sign-in, and updates the default \mailer\_sender\ from 'donotreply' to 'reply'. Additionally, the generated User model template now inherits from a configurable base class (\@inherit\_from\) rather than a hardcoded parent, allowing for greater flexibility in application structure.

lib/generators/clearance/install/templates · high confidence

The generated database migration templates for the Clearance authentication gem have been updated to enforce data integrity and support custom database configurations. The \create\_users\ migration now adds unique constraints on both the \confirmation\_token\ and \remember\_token\ columns, ensuring that these values remain distinct across user records. Additionally, the template now supports a configurable \primary\_key\_type\, allowing the generated \create\_table\ statement to use a specific primary key type (such as \bigint\) if configured, rather than relying on the default. The \add\_clearance\_to\_users\ migration template was also refined to correctly handle index removal in the down method and to clean up SQL output.

lib/generators/clearance/install/templates/db · high confidence

Added FactoryBot factory template for user generation; Added RSpec support template for clearance integration tests; Added RSpec test suite for configuration and routing; Added acceptance test for Clearance installation process; Added comprehensive test suite for User model; Added controller specs for authentication and authorization flows; Added dummy Rails application for testing; Added dummy app models for Rails-dependent specs; Added feature spec helper module for Clearance integration tests; Added feature specs for authentication flows; Added request specs for authentication and session behavior; Added test controller for dummy application; Added test coverage for Clearance authentication components; Added test coverage for Clearance testing helpers; Added test coverage for password strategy configuration and implementations; Added test fixtures for Rails application template generation; Added test fixtures for Rails application templates; Added test support helpers for redirects, generators, and authentication; Added tests for Clearance routing constraints; Added tests for ClearanceMailer change password functionality; Added tests for RSpec helper and view spec configurations; Added tests for the Clearance install generator; New testing helpers for controller and view specs.

Clearance has been updated to version 2.12.0, raising the minimum Ruby requirement to 3.3.11 and adding support for Rails 8.1.3. The gemspec now specifies dependencies on bcrypt (\>= 3.1.1), argon2 (\~\> 2.0), email\_validator (\~\> 2.0), and core Rails components (railties, activemodel, activerecord, actionmailer) all requiring version 5.0 or higher. Development and testing dependencies have also been updated, including capybara 3.40.0, rspec-rails, factory\_bot\_rails 6.5.1, and sqlite3 (\~\> 2.9).

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 72 → 67 (-4.7)
• Rubric changed (rubric-2026.09.8 → rubric-2026.09.16) — scores are not directly comparable.

• Code Health 100 → 100 (+0.0)
• Architecture 98 → 87 (-10.9)
• Maturity 56 → 56 (+0.0)
• Readiness 89 → 89 (+0.0)
• Security 78 → 82 (+4.5)
• Accessibility 66 (new)

• Documentation: no usage examples (README.md)

• Duplicate intent across types. Authentication.sign_in and Session.sign_in appear to perform the same core action (signing in a user). In a well-designed API, one should delegate to the other, or the distinction should be clear (e.g., one is high-level, one is low-level). Currently, they look like parallel implementations of the same logic.
• Duplicate method names across different helper modules with potentially different contexts. sign_in and sign_in_as exist in both ControllerHelpers and ViewHelpers. While the context (controller vs view) differs, the naming is identical, which can be confusing when importing both modules. It is unclear if they do the same thing or if one is a no-op.
• Redundant configuration entry points. Clearance.configure() is a standard Ruby DSL pattern for setting up configuration, while Clearance.configuration= is a setter that likely does the same thing or is an alias. Having both configure (block-based) and a setter configuration= creates confusion about the preferred API surface.

• Unchanged — 0 containers · 1 contexts · 0 edges

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

thoughtbot/clearance was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.