source_monitor 0.2.0 → 0.3.0

data/.claude/skills/authentication-flow/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: authentication-flow
+description: Implements authentication using Rails 8 built-in generator. Use when setting up user authentication, login/logout, session management, password reset flows, or securing controllers.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Rails 8 Authentication
+
+## Overview
+
+Rails 8 includes a built-in authentication generator that creates a complete, secure authentication system without external gems.
+
+## Quick Start
+
+```bash
+# Generate authentication
+bin/rails generate authentication
+
+# Run migrations
+bin/rails db:migrate
+```
+
+This creates:
+- `User` model with `has_secure_password`
+- `Session` model for secure sessions
+- `Current` model for request-local storage
+- Authentication concern for controllers
+- Session and Password controllers
+- Login/logout views
+
+## Generated Structure
+
+```
+app/
+├── models/
+│   ├── user.rb              # User with has_secure_password
+│   ├── session.rb           # Session tracking
+│   └── current.rb           # Current.user accessor
+├── controllers/
+│   ├── sessions_controller.rb      # Login/logout
+│   ├── passwords_controller.rb     # Password reset
+│   └── concerns/
+│       └── authentication.rb       # Auth helpers
+└── views/
+    ├── sessions/
+    │   └── new.html.erb     # Login form
+    └── passwords/
+        ├── new.html.erb     # Forgot password
+        └── edit.html.erb    # Reset password
+```
+
+## Core Components
+
+### User Model
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_secure_password
+  has_many :sessions, dependent: :destroy
+
+  normalizes :email_address, with: -> { _1.strip.downcase }
+
+  validates :email_address, presence: true, uniqueness: true,
+            format: { with: URI::MailTo::EMAIL_REGEXP }
+end
+```
+
+### Session Model
+
+```ruby
+# app/models/session.rb
+class Session < ApplicationRecord
+  belongs_to :user
+
+  before_create { self.token = SecureRandom.urlsafe_base64(32) }
+
+  def self.find_by_token(token)
+    find_by(token: token) if token.present?
+  end
+end
+```
+
+### Current Model
+
+```ruby
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :session
+  delegate :user, to: :session, allow_nil: true
+end
+```
+
+### Authentication Concern
+
+```ruby
+# app/controllers/concerns/authentication.rb
+module Authentication
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :require_authentication
+    helper_method :authenticated?
+  end
+
+  class_methods do
+    def allow_unauthenticated_access(**options)
+      skip_before_action :require_authentication, **options
+    end
+  end
+
+  private
+
+  def authenticated?
+    Current.session.present?
+  end
+
+  def require_authentication
+    resume_session || request_authentication
+  end
+
+  def resume_session
+    if session_token = cookies.signed[:session_token]
+      if session = Session.find_by_token(session_token)
+        Current.session = session
+      end
+    end
+  end
+
+  def request_authentication
+    redirect_to new_session_path
+  end
+
+  def start_new_session_for(user)
+    session = user.sessions.create!
+    cookies.signed.permanent[:session_token] = { value: session.token, httponly: true }
+    Current.session = session
+  end
+
+  def terminate_session
+    Current.session&.destroy
+    cookies.delete(:session_token)
+  end
+end
+```
+
+## Usage Patterns
+
+### Protecting Controllers
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Authentication
+  # All actions require authentication by default
+end
+
+class HomeController < ApplicationController
+  allow_unauthenticated_access only: [:index, :about]
+end
+```
+
+### Accessing Current User
+
+```ruby
+# In controllers and views
+Current.user
+Current.user.email_address
+```
+
+### Login Flow
+
+```ruby
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
+  allow_unauthenticated_access only: [:new, :create]
+
+  def new
+  end
+
+  def create
+    if user = User.authenticate_by(email_address: params[:email_address],
+                                    password: params[:password])
+      start_new_session_for(user)
+      redirect_to root_path, notice: "Signed in successfully"
+    else
+      flash.now[:alert] = "Invalid email or password"
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    terminate_session
+    redirect_to root_path, notice: "Signed out"
+  end
+end
+```
+
+## Testing Authentication
+
+### Test Helper
+
+```ruby
+# test/test_helper.rb
+class ActionDispatch::IntegrationTest
+  def sign_in(user)
+    session = user.sessions.create!
+    cookies[:session_token] = session.token
+  end
+
+  def sign_out
+    cookies.delete(:session_token)
+  end
+end
+```
+
+### Session Controller Tests
+
+```ruby
+# test/controllers/sessions_controller_test.rb
+require "test_helper"
+
+class SessionsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:one)
+  end
+
+  test "GET new renders login form" do
+    get new_session_path
+    assert_response :success
+  end
+
+  test "POST create with valid credentials signs in user" do
+    post session_path, params: {
+      email_address: @user.email_address,
+      password: "password123"
+    }
+
+    assert_redirected_to root_path
+    assert cookies[:session_token].present?
+  end
+
+  test "POST create with invalid credentials shows error" do
+    post session_path, params: {
+      email_address: @user.email_address,
+      password: "wrong"
+    }
+
+    assert_response :unprocessable_entity
+  end
+
+  test "DELETE destroy signs out user" do
+    sign_in @user
+
+    delete session_path
+
+    assert_redirected_to root_path
+    assert_nil cookies[:session_token]
+  end
+end
+```
+
+### Protected Route Tests
+
+```ruby
+# test/controllers/posts_controller_test.rb
+require "test_helper"
+
+class PostsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:one)
+  end
+
+  test "redirects to login when not authenticated" do
+    get posts_path
+    assert_redirected_to new_session_path
+  end
+
+  test "shows posts when authenticated" do
+    sign_in @user
+
+    get posts_path
+    assert_response :success
+  end
+end
+```
+
+## References
+
+- See [sessions.md](reference/sessions.md) for session management details
+- See [current.md](reference/current.md) for Current attributes patterns
+- See [passwordless.md](reference/passwordless.md) for magic link authentication
+
+## Common Customizations
+
+### Remember Me
+
+```ruby
+def start_new_session_for(user, remember: false)
+  session = user.sessions.create!
+  cookie_options = { value: session.token, httponly: true }
+  cookie_options[:expires] = 2.weeks.from_now if remember
+  cookies.signed.permanent[:session_token] = cookie_options
+  Current.session = session
+end
+```
+
+### Multiple Sessions Tracking
+
+```ruby
+def active_sessions
+  sessions.where("created_at > ?", 30.days.ago)
+end
+
+def terminate_all_sessions_except(current_session)
+  sessions.where.not(id: current_session.id).destroy_all
+end
+```
+
+### Rate Limiting
+
+```ruby
+# app/controllers/sessions_controller.rb
+rate_limit to: 10, within: 3.minutes, only: :create,
+           with: -> { redirect_to new_session_path, alert: "Too many attempts" }
+```
+
+## Checklist
+
+- [ ] Authentication generator run
+- [ ] Test helper with `sign_in`/`sign_out` methods
+- [ ] Session controller tests written
+- [ ] Protected route tests written
+- [ ] Rate limiting on login
+- [ ] `allow_unauthenticated_access` on public pages
+- [ ] All tests GREEN

data/.claude/skills/authentication-flow/reference/current.md

@@ -0,0 +1,248 @@
+# Current Attributes Reference
+
+## Concept
+
+`Current` uses `ActiveSupport::CurrentAttributes` to provide request-local storage, making request-specific data available throughout the application without passing it explicitly.
+
+## Basic Setup
+
+```ruby
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  # Attributes stored per-request
+  attribute :session
+  attribute :user_agent
+  attribute :ip_address
+  attribute :request_id
+
+  # Delegate to session for convenience
+  delegate :user, to: :session, allow_nil: true
+
+  # Resets automatically between requests
+  resets { Time.zone = nil }
+end
+```
+
+## Setting Current Attributes
+
+### In ApplicationController
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  before_action :set_current_attributes
+
+  private
+
+  def set_current_attributes
+    Current.user_agent = request.user_agent
+    Current.ip_address = request.remote_ip
+    Current.request_id = request.request_id
+  end
+end
+```
+
+### In Authentication
+
+```ruby
+# app/controllers/concerns/authentication.rb
+def resume_session
+  if token = cookies.signed[:session_token]
+    if session = Session.find_by_token(token)
+      Current.session = session  # Sets Current.session
+    end
+  end
+end
+```
+
+## Accessing Current
+
+### In Controllers
+
+```ruby
+class PostsController < ApplicationController
+  def create
+    @post = Current.user.posts.build(post_params)
+    # ...
+  end
+
+  def index
+    @posts = Current.user.posts
+  end
+end
+```
+
+### In Views
+
+```erb
+<% if Current.user %>
+  Logged in as: <%= Current.user.email_address %>
+  <%= link_to "Sign out", session_path, method: :delete %>
+<% else %>
+  <%= link_to "Sign in", new_session_path %>
+<% end %>
+```
+
+### In Models (Use Sparingly)
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :user
+
+  before_create :set_author
+
+  private
+
+  def set_author
+    self.user ||= Current.user
+  end
+end
+```
+
+**Warning**: Using `Current` in models couples them to the request context. This makes testing harder and breaks in background jobs. Prefer passing the user explicitly.
+
+### In Mailers
+
+```ruby
+class NotificationMailer < ApplicationMailer
+  def alert(user, message)
+    @user = user
+    @message = message
+    @request_id = Current.request_id  # For logging correlation
+
+    mail(to: user.email)
+  end
+end
+```
+
+### In Jobs (Careful!)
+
+```ruby
+class AuditLogJob < ApplicationJob
+  def perform(action:, user_id:, ip_address:, request_id:)
+    # Don't rely on Current - it's reset between requests
+    # Pass values explicitly
+    AuditLog.create!(
+      action: action,
+      user_id: user_id,
+      ip_address: ip_address,
+      request_id: request_id
+    )
+  end
+end
+
+# Enqueue with current values
+AuditLogJob.perform_later(
+  action: "created_post",
+  user_id: Current.user.id,
+  ip_address: Current.ip_address,
+  request_id: Current.request_id
+)
+```
+
+## Common Attributes
+
+```ruby
+class Current < ActiveSupport::CurrentAttributes
+  # Authentication
+  attribute :session
+  delegate :user, to: :session, allow_nil: true
+
+  # Request metadata
+  attribute :request_id
+  attribute :user_agent
+  attribute :ip_address
+
+  # Timezone (per-user)
+  attribute :time_zone
+
+  # Feature flags
+  attribute :feature_flags
+
+  # Request tracking
+  attribute :request_start_time
+end
+```
+
+## Callbacks
+
+```ruby
+class Current < ActiveSupport::CurrentAttributes
+  attribute :session, :time_zone
+
+  # Called when session is set
+  after_reset do
+    Time.zone = nil
+  end
+
+  # Apply user's timezone when session is set
+  def session=(session)
+    super
+    self.time_zone = session&.user&.time_zone
+    Time.zone = time_zone if time_zone
+  end
+end
+```
+
+## Testing
+
+### Stub Current in Tests
+
+```ruby
+# test/support/current_helpers.rb
+module CurrentHelpers
+  def with_current_user(user)
+    session = user.sessions.create!
+    Current.session = session
+    yield
+  ensure
+    Current.reset
+  end
+end
+
+```
+
+### In Tests
+
+```ruby
+# test/models/post_test.rb
+require "test_helper"
+
+class PostTest < ActiveSupport::TestCase
+  test "sets author from Current.user" do
+    user = users(:one)
+    with_current_user(user) do
+      post = Post.create!(title: "Test")
+      assert_equal user, post.user
+    end
+  end
+end
+```
+
+### Controller Tests
+
+```ruby
+# test/controllers/posts_controller_test.rb
+require "test_helper"
+
+class PostsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:one)
+    sign_in_as @user  # Sets Current.session
+  end
+
+  test "uses current user" do
+    post posts_path, params: { post: { title: "Test" } }
+    assert_equal @user, Post.last.user
+  end
+end
+```
+
+## Best Practices
+
+1. **Controllers/Views**: Safe to use `Current.user` freely
+2. **Models**: Pass user explicitly when possible
+3. **Jobs**: Never rely on Current - pass values explicitly
+4. **Mailers**: Can use for metadata, but pass main data explicitly
+5. **Services**: Accept user as parameter, don't assume Current
+6. **Tests**: Reset Current between examples