claude-agent-framework 1.0.0

package/framework/skills/core/authentication.md

@@ -0,0 +1,306 @@
+# Skill: Authentication
+
+## Purpose
+Implement user authentication using Rails 8's built-in authentication generator.
+
+## Rails 8 Authentication Generator
+
+### Generate Authentication
+```bash
+rails generate authentication
+```
+
+### Generated Files
+```
+app/models/user.rb
+app/models/session.rb
+app/models/current.rb
+app/controllers/sessions_controller.rb
+app/controllers/passwords_controller.rb
+app/views/sessions/new.html.erb
+app/views/passwords/new.html.erb
+app/views/passwords/edit.html.erb
+db/migrate/TIMESTAMP_create_users.rb
+db/migrate/TIMESTAMP_create_sessions.rb
+```
+
+## User Model
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_secure_password
+  has_many :sessions, dependent: :destroy
+
+  normalizes :email_address, with: ->(e) { e.strip.downcase }
+
+  validates :email_address, presence: true, uniqueness: true,
+            format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :password, length: { minimum: 8 }, allow_nil: true
+end
+```
+
+## Session Model
+
+```ruby
+# app/models/session.rb
+class Session < ApplicationRecord
+  belongs_to :user
+
+  before_create do
+    self.token = SecureRandom.urlsafe_base64(32)
+  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 :signed_in?
+  end
+
+  class_methods do
+    def allow_unauthenticated_access(**options)
+      skip_before_action :require_authentication, **options
+    end
+  end
+
+  private
+
+  def signed_in?
+    Current.session.present?
+  end
+
+  def require_authentication
+    resume_session || request_authentication
+  end
+
+  def resume_session
+    Current.session = find_session_by_cookie
+  end
+
+  def find_session_by_cookie
+    Session.find_by(token: cookies.signed[:session_token])
+  end
+
+  def request_authentication
+    session[:return_to_after_authenticating] = request.url
+    redirect_to new_session_path, alert: "Please sign in to continue."
+  end
+
+  def after_authentication_url
+    session.delete(:return_to_after_authenticating) || root_url
+  end
+
+  def start_new_session_for(user)
+    user.sessions.create!.tap do |session|
+      Current.session = session
+      cookies.signed.permanent[:session_token] = {
+        value: session.token,
+        httponly: true,
+        same_site: :lax
+      }
+    end
+  end
+
+  def terminate_session
+    Current.session.destroy
+    cookies.delete(:session_token)
+  end
+end
+```
+
+## Sessions Controller
+
+```ruby
+# app/controllers/sessions_controller.rb
+class SessionsController < ApplicationController
+  allow_unauthenticated_access only: %i[new create]
+  rate_limit to: 10, within: 3.minutes, only: :create, with: -> {
+    redirect_to new_session_url, alert: "Too many attempts. Try again later."
+  }
+
+  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 after_authentication_url, notice: "Signed in successfully."
+    else
+      redirect_to new_session_path, alert: "Invalid email or password."
+    end
+  end
+
+  def destroy
+    terminate_session
+    redirect_to new_session_path, notice: "Signed out successfully."
+  end
+end
+```
+
+## Registration
+
+### Add Registration Controller
+```ruby
+# app/controllers/registrations_controller.rb
+class RegistrationsController < ApplicationController
+  allow_unauthenticated_access
+
+  def new
+    @user = User.new
+  end
+
+  def create
+    @user = User.new(user_params)
+
+    if @user.save
+      start_new_session_for @user
+      redirect_to root_path, notice: "Welcome! Your account has been created."
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:email_address, :password, :password_confirmation)
+  end
+end
+```
+
+### Registration View
+```erb
+<%# app/views/registrations/new.html.erb %>
+<div class="max-w-md mx-auto mt-10">
+  <h1 class="text-2xl font-bold mb-6">Create Account</h1>
+
+  <%= form_with model: @user, url: registration_path, class: "space-y-4" do |f| %>
+    <% if @user.errors.any? %>
+      <div class="bg-red-50 border border-red-200 rounded p-4">
+        <ul class="list-disc list-inside text-red-700 text-sm">
+          <% @user.errors.full_messages.each do |error| %>
+            <li><%= error %></li>
+          <% end %>
+        </ul>
+      </div>
+    <% end %>
+
+    <div>
+      <%= f.label :email_address, class: "block text-sm font-medium text-gray-700" %>
+      <%= f.email_field :email_address, required: true, autofocus: true,
+          class: "mt-1 w-full rounded-lg border-gray-300" %>
+    </div>
+
+    <div>
+      <%= f.label :password, class: "block text-sm font-medium text-gray-700" %>
+      <%= f.password_field :password, required: true,
+          class: "mt-1 w-full rounded-lg border-gray-300" %>
+    </div>
+
+    <div>
+      <%= f.label :password_confirmation, class: "block text-sm font-medium text-gray-700" %>
+      <%= f.password_field :password_confirmation, required: true,
+          class: "mt-1 w-full rounded-lg border-gray-300" %>
+    </div>
+
+    <%= f.submit "Create Account",
+        class: "w-full bg-blue-600 hover:bg-blue-700 text-white py-2 rounded-lg" %>
+  <% end %>
+
+  <p class="mt-4 text-center text-sm text-gray-600">
+    Already have an account?
+    <%= link_to "Sign in", new_session_path, class: "text-blue-600 hover:underline" %>
+  </p>
+</div>
+```
+
+### Routes
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  resource :session, only: [:new, :create, :destroy]
+  resource :registration, only: [:new, :create]
+  resource :password, only: [:new, :create, :edit, :update]
+
+  # ...
+end
+```
+
+## Login View
+
+```erb
+<%# app/views/sessions/new.html.erb %>
+<div class="max-w-md mx-auto mt-10">
+  <h1 class="text-2xl font-bold mb-6">Sign In</h1>
+
+  <%= form_with url: session_path, class: "space-y-4" do |f| %>
+    <div>
+      <%= f.label :email_address, class: "block text-sm font-medium text-gray-700" %>
+      <%= f.email_field :email_address, required: true, autofocus: true,
+          class: "mt-1 w-full rounded-lg border-gray-300" %>
+    </div>
+
+    <div>
+      <%= f.label :password, class: "block text-sm font-medium text-gray-700" %>
+      <%= f.password_field :password, required: true,
+          class: "mt-1 w-full rounded-lg border-gray-300" %>
+    </div>
+
+    <%= f.submit "Sign In",
+        class: "w-full bg-blue-600 hover:bg-blue-700 text-white py-2 rounded-lg" %>
+  <% end %>
+
+  <div class="mt-4 text-center text-sm text-gray-600">
+    <%= link_to "Forgot password?", new_password_path, class: "text-blue-600 hover:underline" %>
+    <span class="mx-2">|</span>
+    <%= link_to "Create account", new_registration_path, class: "text-blue-600 hover:underline" %>
+  </div>
+</div>
+```
+
+## Application Controller
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include Authentication
+end
+```
+
+## Current User Helper
+
+```erb
+<%# In views %>
+<% if signed_in? %>
+  <span>Welcome, <%= Current.user.email_address %></span>
+  <%= button_to "Sign Out", session_path, method: :delete %>
+<% else %>
+  <%= link_to "Sign In", new_session_path %>
+<% end %>
+```
+
+## Security Best Practices
+
+1. **Rate limiting** - Prevent brute force attacks
+2. **Secure cookies** - HttpOnly, SameSite, Secure in production
+3. **Password requirements** - Minimum 8 characters
+4. **Session management** - Token-based, revocable
+5. **Email normalization** - Consistent email handling

package/framework/skills/core/authorization.md

@@ -0,0 +1,388 @@
+# Skill: Authorization
+
+## Purpose
+Implement role-based access control using Pundit for fine-grained authorization.
+
+## Setup
+
+### Install Pundit
+```ruby
+# Gemfile
+gem "pundit"
+```
+
+```bash
+bundle install
+rails generate pundit:install
+```
+
+### Include in Application Controller
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include Pundit::Authorization
+
+  rescue_from Pundit::NotAuthorizedError, with: :user_not_authorized
+
+  private
+
+  def user_not_authorized
+    flash[:alert] = "You are not authorized to perform this action."
+    redirect_back(fallback_location: root_path)
+  end
+end
+```
+
+## User Roles
+
+### Add Role to User
+```ruby
+# Migration
+class AddRoleToUsers < ActiveRecord::Migration[8.0]
+  def change
+    add_column :users, :role, :string, default: "user", null: false
+    add_index :users, :role
+  end
+end
+```
+
+### User Model with Roles
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  ROLES = %w[user admin moderator].freeze
+
+  validates :role, inclusion: { in: ROLES }
+
+  def admin?
+    role == "admin"
+  end
+
+  def moderator?
+    role == "moderator"
+  end
+
+  def at_least_moderator?
+    admin? || moderator?
+  end
+end
+```
+
+## Policies
+
+### Application Policy (Base)
+```ruby
+# app/policies/application_policy.rb
+class ApplicationPolicy
+  attr_reader :user, :record
+
+  def initialize(user, record)
+    @user = user
+    @record = record
+  end
+
+  def index?
+    true
+  end
+
+  def show?
+    true
+  end
+
+  def create?
+    user.present?
+  end
+
+  def new?
+    create?
+  end
+
+  def update?
+    owner_or_admin?
+  end
+
+  def edit?
+    update?
+  end
+
+  def destroy?
+    owner_or_admin?
+  end
+
+  private
+
+  def owner?
+    record.respond_to?(:user) && record.user == user
+  end
+
+  def owner_or_admin?
+    owner? || user&.admin?
+  end
+
+  def admin?
+    user&.admin?
+  end
+
+  class Scope
+    def initialize(user, scope)
+      @user = user
+      @scope = scope
+    end
+
+    def resolve
+      scope.all
+    end
+
+    private
+
+    attr_reader :user, :scope
+  end
+end
+```
+
+### Resource Policy
+```ruby
+# app/policies/article_policy.rb
+class ArticlePolicy < ApplicationPolicy
+  def index?
+    true
+  end
+
+  def show?
+    record.published? || owner_or_admin?
+  end
+
+  def create?
+    user.present?
+  end
+
+  def update?
+    owner_or_admin?
+  end
+
+  def destroy?
+    owner_or_admin?
+  end
+
+  def publish?
+    owner_or_admin?
+  end
+
+  class Scope < ApplicationPolicy::Scope
+    def resolve
+      if user&.admin?
+        scope.all
+      elsif user
+        scope.where(published: true).or(scope.where(user: user))
+      else
+        scope.where(published: true)
+      end
+    end
+  end
+end
+```
+
+### Admin-Only Policy
+```ruby
+# app/policies/admin/user_policy.rb
+module Admin
+  class UserPolicy < ApplicationPolicy
+    def index?
+      admin?
+    end
+
+    def show?
+      admin?
+    end
+
+    def update?
+      admin? && record != user # Can't edit self
+    end
+
+    def destroy?
+      admin? && record != user # Can't delete self
+    end
+  end
+end
+```
+
+## Controller Usage
+
+### Basic Authorization
+```ruby
+class ArticlesController < ApplicationController
+  def show
+    @article = Article.find(params[:id])
+    authorize @article
+  end
+
+  def create
+    @article = current_user.articles.build(article_params)
+    authorize @article
+
+    if @article.save
+      redirect_to @article
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    @article = Article.find(params[:id])
+    authorize @article
+
+    if @article.update(article_params)
+      redirect_to @article
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+### Policy Scopes
+```ruby
+class ArticlesController < ApplicationController
+  def index
+    @articles = policy_scope(Article).recent
+  end
+end
+```
+
+### Authorize in Before Action
+```ruby
+class ArticlesController < ApplicationController
+  before_action :set_article, only: [:show, :edit, :update, :destroy]
+
+  def edit
+    # authorize called in set_article
+  end
+
+  private
+
+  def set_article
+    @article = Article.find(params[:id])
+    authorize @article
+  end
+end
+```
+
+## View Helpers
+
+### Conditional Display
+```erb
+<% if policy(@article).edit? %>
+  <%= link_to "Edit", edit_article_path(@article) %>
+<% end %>
+
+<% if policy(@article).destroy? %>
+  <%= button_to "Delete", @article, method: :delete %>
+<% end %>
+```
+
+### New Record Check
+```erb
+<% if policy(Article).create? %>
+  <%= link_to "New Article", new_article_path %>
+<% end %>
+```
+
+### Admin-Only Section
+```erb
+<% if policy([:admin, User]).index? %>
+  <%= link_to "Manage Users", admin_users_path %>
+<% end %>
+```
+
+## Headless Policies
+
+For actions not tied to a model:
+
+```ruby
+# app/policies/dashboard_policy.rb
+class DashboardPolicy < ApplicationPolicy
+  def initialize(user, _record = nil)
+    @user = user
+  end
+
+  def show?
+    user.present?
+  end
+
+  def admin?
+    user&.admin?
+  end
+end
+```
+
+```ruby
+# Controller
+class DashboardController < ApplicationController
+  def show
+    authorize :dashboard, :show?
+  end
+
+  def admin
+    authorize :dashboard, :admin?
+  end
+end
+```
+
+## Testing Policies
+
+```ruby
+# spec/policies/article_policy_spec.rb
+require "rails_helper"
+
+RSpec.describe ArticlePolicy do
+  subject { described_class }
+
+  let(:user) { create(:user) }
+  let(:admin) { create(:user, role: "admin") }
+  let(:article) { create(:article, user: user) }
+  let(:other_article) { create(:article) }
+
+  permissions :update?, :destroy? do
+    it "allows owner" do
+      expect(subject).to permit(user, article)
+    end
+
+    it "denies non-owner" do
+      expect(subject).not_to permit(user, other_article)
+    end
+
+    it "allows admin" do
+      expect(subject).to permit(admin, other_article)
+    end
+  end
+
+  describe "Scope" do
+    let!(:published) { create(:article, published: true) }
+    let!(:draft) { create(:article, published: false) }
+    let!(:own_draft) { create(:article, published: false, user: user) }
+
+    it "shows only published to guests" do
+      scope = ArticlePolicy::Scope.new(nil, Article).resolve
+      expect(scope).to contain_exactly(published)
+    end
+
+    it "shows published + own drafts to users" do
+      scope = ArticlePolicy::Scope.new(user, Article).resolve
+      expect(scope).to contain_exactly(published, own_draft)
+    end
+
+    it "shows all to admin" do
+      scope = ArticlePolicy::Scope.new(admin, Article).resolve
+      expect(scope).to contain_exactly(published, draft, own_draft)
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Authorize early** - Call authorize at the start of actions
+2. **Use scopes** - Filter collections with policy_scope
+3. **Test policies** - Write specs for all permission scenarios
+4. **Keep policies focused** - One policy per resource
+5. **Use permitted_attributes** - Let policy control params