If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/binarylogic/authlogic shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3mo ago
• 16 active contributors
• Distributed ownership (top contributor 33% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 3mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live binarylogic/authlogic repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/binarylogic/authlogic.

What it runs against: a local clone of binarylogic/authlogic — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in binarylogic/authlogic | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 120 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of binarylogic/authlogic. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/binarylogic/authlogic.git
#   cd authlogic
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of binarylogic/authlogic and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "binarylogic/authlogic(\\.git)?\\b" \\
  && ok "origin remote is binarylogic/authlogic" \\
  || miss "origin remote is not binarylogic/authlogic (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/authlogic.rb" \\
  && ok "lib/authlogic.rb" \\
  || miss "missing critical file: lib/authlogic.rb"
test -f "lib/authlogic/session/base.rb" \\
  && ok "lib/authlogic/session/base.rb" \\
  || miss "missing critical file: lib/authlogic/session/base.rb"
test -f "lib/authlogic/acts_as_authentic/base.rb" \\
  && ok "lib/authlogic/acts_as_authentic/base.rb" \\
  || miss "missing critical file: lib/authlogic/acts_as_authentic/base.rb"
test -f "lib/authlogic/controller_adapters/abstract_adapter.rb" \\
  && ok "lib/authlogic/controller_adapters/abstract_adapter.rb" \\
  || miss "missing critical file: lib/authlogic/controller_adapters/abstract_adapter.rb"
test -f "lib/authlogic/crypto_providers.rb" \\
  && ok "lib/authlogic/crypto_providers.rb" \\
  || miss "missing critical file: lib/authlogic/crypto_providers.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 120 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~90d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/binarylogic/authlogic"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Authlogic is a Ruby on Rails authentication library that provides session-based user authentication with a pluggable architecture for password hashing (bcrypt, scrypt, SHA256, etc.), perishable tokens, single-access tokens, and remember-me functionality. It wraps ActiveRecord models to add authentication capabilities without requiring Devise or similar monolithic solutions. Modular design: lib/authlogic/acts_as_authentic/ contains model mixins (password, email, login, perishable_token), lib/authlogic/crypto_providers/ abstracts hashing algorithms, lib/authlogic/controller_adapters/ supports Rails/Rack/Sinatra, and lib/authlogic/session/ (inferred from README) implements the core session model. Model and session classes are separate concerns.

Rails developers building custom authentication flows who need fine-grained control over session management, password encryption strategies, and token generation without the overhead of a full authentication framework. Common use cases include APIs, multi-tenant systems, and apps requiring specific security policies.

Production-ready and actively maintained. The repo shows 286K lines of Ruby code with comprehensive test coverage (evidenced by CI workflows in .github/workflows/test.yml), documented upgrading paths (UPGRADING.md), and support for modern Rails versions (7.2, 8.0, 8.1 in gemfiles/). Latest minor version is 6.6.1 with ongoing development.

Low risk for core functionality, but single-maintainer burden (binarylogic owns the repo). The crypto providers architecture mitigates dependency risk by wrapping external libs (bcrypt, scrypt) as optional integrations rather than hard requirements. No obvious abandoned status, but monitor for Rails 8+ edge cases as the framework evolves rapidly.

Active Rails version support updates; test.yml workflow suggests CI validation against Rails 7.2–8.1. No specific PR data visible, but CHANGELOG.md and version tags (v6.6.1, v6.5.0) indicate regular maintenance cycles. Focus appears to be compatibility and security updates rather than new features.

git clone https://github.com/binarylogic/authlogic.git
cd authlogic
bundle install
bundle exec rake test

Daily commands:

bundle exec rake test                    # Run full test suite
bundle exec rubocop                     # Lint with RuboCop
bundle exec rake                        # Default Rakefile task (likely tests)

• lib/authlogic.rb — Main entry point that requires and orchestrates all authlogic modules; essential for understanding how the gem is structured
• lib/authlogic/session/base.rb — Core session management logic; defines how user sessions are created, validated, and maintained throughout authentication lifecycle
• lib/authlogic/acts_as_authentic/base.rb — Model-level authentication setup that integrates with ActiveRecord; every User model must understand this to work correctly
• lib/authlogic/controller_adapters/abstract_adapter.rb — Framework-agnostic adapter interface for cookies and sessions; critical for supporting Rails, Sinatra, and Rack
• lib/authlogic/crypto_providers.rb — Central password encryption strategy dispatcher; determines which hashing algorithm is used and affects all password operations
• lib/authlogic/config.rb — Global configuration system that allows customization of session behavior, token generation, and crypto providers
• authlogic.gemspec — Gem manifest defining dependencies, Ruby version support, and build metadata for proper installation

Add a new authentication field to User model

1. Create database migration adding the new column to users table (e.g., phone_number) (db/migrate/[timestamp]_add_phone_to_users.rb)
2. Create a new acts_as_authentic module in lib/authlogic/acts_as_authentic/ (e.g., phone.rb) that validates and configures the field (lib/authlogic/acts_as_authentic/phone.rb)
3. Require the new module in the acts_as_authentic/base.rb and add it to the list of included modules (lib/authlogic/acts_as_authentic/base.rb)
4. Update User model to include the new field in acts_as_authentic configuration if custom behavior needed (app/models/user.rb)
5. Write tests in test/acts_as_authentic_test/ mirroring existing field tests (email_test.rb, login_test.rb) (test/acts_as_authentic_test/phone_test.rb)

Add support for a new crypto provider (hashing algorithm)

1. Create new crypto provider class in lib/authlogic/crypto_providers/ (e.g., argon2.rb) implementing encrypt and matches? methods (lib/authlogic/crypto_providers/argon2.rb)
2. Register the provider in lib/authlogic/crypto_providers.rb in the provider list and require statement (lib/authlogic/crypto_providers.rb)
3. Configure it globally in lib/authlogic/config.rb or per-session in lib/authlogic/session/base.rb (lib/authlogic/config.rb)
4. Add comprehensive tests in test/crypto_provider_test/ following the pattern of existing tests (test/crypto_provider_test/argon2_test.rb)

Customize session behavior (timeout, cookie settings, token format)

1. Review available configuration options in lib/authlogic/config.rb (e.g., session_key_prefix, persistence_token_length) (lib/authlogic/config.rb)
2. In config/initializers/authlogic.rb (create if needed), set Authlogic::Config options to override defaults (config/initializers/authlogic.rb)
3. For session-specific behavior, create a custom session class inheriting from Authlogic::Session::Base and override config methods (app/models/user_session.rb)
4. Test custom settings by writing integration tests using lib/authlogic/test_case.rb helpers (test/integration/custom_session_test.rb)

Add a new token type (e.g., single_access_token alternative)

1. Create migration adding new token column to users table with appropriate indexes (db/migrate/[timestamp]_add_api_token_to_users.rb)
2. Create new module in lib/authlogic/acts_as_authentic/ following pattern of single_access_token.rb (lib/authlogic/acts_as_authentic/api_token.rb)
3. Include module in acts_as_authentic/base.rb and expose token generation methods (lib/authlogic/acts_as_authentic/base.rb)
4. Add session-level support in lib/authlogic/session/base.rb to authenticate via the new token type (lib/authlogic/session/base.rb)
5. Write tests mirroring single_access_test.rb pattern (test/acts_as_authentic_test/api_token_test.rb)

• ActiveRecord — Provides ORM for User model and persistent token storage with database flexibility (MySQL, PostgreSQL, SQLite)
• bcrypt (default crypto) — Industry standard for password hashing with adaptive work factor against brute-force attacks; pluggable to support legacy SHA1/MD5 migration
• HTTP Cookies — Stateless session management without server-side session storage; supports both secure HttpOnly cookies and remember-me tokens
• Framework adapters (Rails/Sinatra/Rack) — Abstraction layer enabling single authentication library to work across multiple Ruby web frameworks with minimal boilerplate

• Plugin-based crypto providers instead of single algorithm

  • Why: Legacy Rails apps may use SHA1/MD5; supporting migration path without breaking existing installs
  • Consequence: Adds complexity (multiple provider classes) but allows gradual migration to bcrypt; default is bcrypt

• Both persistence_token and perishable_token stored in database

  • Why: Persistence token for automatic login via cookie; perishable token for password resets without storing plaintext secrets
  • Consequence: Two additional columns per User and extra database lookups, but enables secure token-based workflows without email links containing secrets

• Stateless cookie-based sessions (no session table)

  • Why: Simpler deployment, horizontal scaling, reduced database load
  • Consequence: Cannot revoke sessions server-side; relies on expiration and

No explicit env vars required for basic usage, but bcrypt/scrypt gems must be added to Gemfile manually (not forced dependencies—Authlogic detects them). Rails adapter expects request and response objects from Rails context; will fail silently in non-Rails environments. Perishable token expiry defaults to 10 minutes—verify this matches your use case for password reset links. Case sensitivity queries in lib/authlogic/acts_as_authentic/queries/ are database-specific (MySQL case-insensitive by default); logins may behave unexpectedly across DB backends. Remember-me cookie relies on secure cookie signing in Rails; if Rails.application.secrets changes, all remember-me sessions invalidate. No Rails 4 support (minimum 5.2 per gemfiles/).

• Perishable Token — Authlogic's unique feature for time-limited one-time use tokens (password resets, email verification); understanding expiry and regeneration is critical for security.
• Session Persistence Token — Authlogic generates an opaque token per session to prevent CSRF and session fixation attacks; differs from API tokens and perishable tokens.
• Crypto Provider Strategy Pattern — Authlogic abstracts password hashing behind pluggable providers (bcrypt, scrypt, SHA256); understanding how to swap or add providers is essential for security upgrades.
• ActiveRecord Mixin Composition — acts_as_authentic uses module mixins (password.rb, email.rb, login.rb) to compose User model behavior; core pattern for understanding how Authlogic decorates models.
• Adapter Pattern for Framework Abstraction — controller_adapters/ abstracts Rails/Rack/Sinatra differences; essential for understanding how Authlogic remains framework-agnostic.
• Remember-Me Cookie Persistence — Authlogic's remember_me flag persists authentication across browser restarts via encrypted cookies; requires Rails.application.secrets stability.
• Case-Sensitive Query Handling — Authlogic's queries/ dir handles DB-specific case sensitivity for logins (MySQL vs PostgreSQL); critical for cross-DB portability.

• plataformatec/devise — Primary competitor; monolithic Rails auth engine with built-in views. Choose Authlogic for minimal deps + custom flows.
• rails/rails — Core dependency; Authlogic integrates deeply with ActionController, ActiveRecord, and cookies/sessions
• bcrypt-ruby/bcrypt-ruby — Default password hashing provider for Authlogic; crypto_providers/bcrypt.rb wraps this
• thoughtbot/clearance — Lightweight Rails auth alternative; simpler than Devise but less configurable than Authlogic
• binarylogic/settingslogic — Companion gem by same author for Rails app configuration; often used alongside Authlogic

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for CookieCredentials parsing and serialization

The lib/authlogic/cookie_credentials.rb file exists but there's no dedicated test file visible in the structure. Cookie handling is security-critical in authentication libraries, and comprehensive tests would ensure edge cases (malformed cookies, encoding issues, expiration) are properly handled. This would be high-value for security and maintainability.

• [ ] Create spec/authlogic/cookie_credentials_spec.rb or equivalent
• [ ] Add tests for valid/invalid cookie parsing scenarios
• [ ] Add tests for credential serialization and deserialization
• [ ] Add tests for cookie expiration and timestamp validation
• [ ] Add security-focused tests for potential injection/encoding vulnerabilities

Add integration tests for all supported crypto providers with bcrypt fallback

The lib/authlogic/crypto_providers/ directory contains multiple providers (bcrypt, scrypt, sha1/v2, sha256/v2, sha512/v2, md5/v2) but the gem structure suggests migration/compatibility scenarios are important. Add integration tests that verify password verification works correctly when switching between crypto providers (e.g., legacy MD5 hashes upgraded to bcrypt). This addresses a real pain point for upgrading applications.

• [ ] Create spec/authlogic/crypto_providers/migration_spec.rb
• [ ] Add tests verifying sha1/md5 legacy hashes can be verified
• [ ] Add tests for bcrypt/scrypt as modern replacements
• [ ] Add tests for mixed-provider scenarios in same application
• [ ] Document migration path in doc/upgrading_crypto_providers.md

Add comprehensive tests for acts_as_authentic session maintenance across multiple session types

The lib/authlogic/acts_as_authentic/session_maintenance.rb file handles user sessions but the test coverage for edge cases in multi-session scenarios (remember-me tokens, single-access tokens, perishable tokens) appears incomplete. Add tests covering lifecycle: user logout, token expiration, concurrent session invalidation, and token regeneration after password change.

• [ ] Create spec/authlogic/acts_as_authentic/session_maintenance_spec.rb with comprehensive coverage
• [ ] Add tests for single_access_token invalidation on password change (lib/authlogic/acts_as_authentic/single_access_token.rb)
• [ ] Add tests for perishable_token cleanup and expiration (lib/authlogic/acts_as_authentic/perishable_token.rb)
• [ ] Add tests for persistence_token regeneration scenarios (lib/authlogic/acts_as_authentic/persistence_token.rb)
• [ ] Add tests for concurrent session handling across remember-me and regular sessions

• Add integration tests for Rails 8.1 ActionController::API mode (mentioned in README section 2.b.3 but no test coverage visible in file list); create test/authlogic/rails_api_integration_test.rb
• Document the acts_as_authentic DSL options (password_salt_columns, login_field, etc.) with examples in a new doc/configuration.md, since the file list shows doc/use_normal_rails_validation.md but no configuration reference
• Add a crypto_providers/argon2.rb provider following the bcrypt.rb pattern, since Argon2 is now OWASP-recommended but not present in lib/authlogic/crypto_providers/

Authlogic is a mature authentication library with reasonable security foundations. However, several areas warrant attention: (1) Support for legacy cryptographic algorithms creates misconfiguration risk, (2) Session and token generation mechanisms require

• High · Deprecated Cryptographic Algorithms — lib/authlogic/crypto_providers/ (md5.rb, sha1.rb, sha256.rb, sha512.rb). The codebase includes implementations of weak cryptographic providers (MD5, SHA1, SHA256, SHA512) that are considered deprecated or insecure for password hashing. While bcrypt and scrypt are available as alternatives, the presence of legacy algorithms suggests potential for misconfiguration where applications might fall back to weaker hashing methods. Fix: Deprecate MD5, SHA1, and SHA256 for password hashing. Enforce bcrypt or scrypt as the minimum acceptable algorithm. Consider adding warnings during initialization if weak algorithms are selected. Update documentation to clearly mark these as legacy-only.
• Medium · Potential Session Fixation Vulnerabilities — lib/authlogic/session/base.rb, lib/authlogic/acts_as_authentic/persistence_token.rb. The session management code in lib/authlogic/session/ handles persistence tokens and session state. Without careful examination of token generation and validation logic, there's potential for session fixation attacks if tokens are not properly regenerated or validated on authentication state changes. Fix: Ensure persistence tokens are cryptographically secure (use SecureRandom). Regenerate tokens on privilege escalation. Implement strict token validation and expiration. Add comprehensive tests for session fixation scenarios.
• Medium · Random Token Generation Security — lib/authlogic/random.rb. The custom random token generation in lib/authlogic/random.rb may not provide cryptographically secure randomness if not properly implemented. This affects persistence tokens, perishable tokens, and single access tokens used throughout the authentication system. Fix: Verify that random token generation uses SecureRandom or equivalent cryptographic PRNG. Conduct code review of the random.rb implementation. Add tests to verify entropy of generated tokens.
• Medium · Cookie Security Configuration — lib/authlogic/cookie_credentials.rb, lib/authlogic/controller_adapters/. The cookie credentials handling in lib/authlogic/cookie_credentials.rb may not enforce secure cookie flags (HttpOnly, Secure, SameSite) by default. Authentication cookies without proper flags are vulnerable to XSS and CSRF attacks. Fix: Ensure HttpOnly flag is always set on authentication cookies. Set Secure flag for HTTPS connections. Implement SameSite=Strict or SameSite=Lax by default. Provide clear documentation on cookie security configuration.
• Medium · Case Sensitivity in Authentication Queries — lib/authlogic/acts_as_authentic/queries/case_sensitivity.rb, lib/authlogic/acts_as_authentic/queries/find_with_case.rb. The case sensitivity handling in lib/authlogic/acts_as_authentic/queries/case_sensitivity.rb could lead to authentication bypasses if not properly implemented. Inconsistent case handling between login/email storage and lookup could allow attackers to bypass account restrictions. Fix: Implement case-insensitive comparisons consistently across all authentication lookups. Use database-level collation settings (case-insensitive) for login/email columns. Add tests covering various case permutations in authentication attempts.
• Low · Missing Security Headers Documentation — README.md, documentation files. While not a direct vulnerability in the gem, there's limited documentation on implementing additional security headers (CSP, X-Frame-Options, etc.) when using Authlogic in Rails applications. Fix: Add security best practices guide covering CSRF protection, CSP configuration, secure cookie settings, and other Rails security features that complement Authlogic.
• Low · Test Case Security Helpers — lib/authlogic/test_case/mock_*.rb files. The test case mock implementations (lib/authlogic/test_case/) may not properly simulate security-related behaviors, potentially leading to false negatives in security testing. Fix: Ensure mock implementations properly simulate secure cookie behavior, HTTPS enforcement, and CSRF token validation. Document testing limitations and recommend integration tests for security-critical paths.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.