janus 0.6.0 → 0.7.0

data/README.rdoc

@@ -1,180 +1,103 @@
 = Janus
 
-Janus is an authentication engine for Ruby on Rails 3 and is an alternative
-to the Warden + Devise combo, without the Rack middleware. The whole project
-is inspired by the Warden and Devise API (in order to somehow compatible)
-but is quite different since everything happens within ActionDispatch and not
-at the Rack level.
-
-This Rails instead of Rack difference, allows to actually have the main logic
-within plain Rails controllers. For instance the database authentication is
-called from SessionsController, and it's not just another strategy operating
-at the Rack level within Warden (which requires to check that it's being
-called from the correct URL). There ain't no factory to add strategy modules
-to your models too. You must manually include the necessary ones.
-
-Another difference is that you must actually create the necessary controllers,
-models, mailers and views within your project (extending the default ones).
-You will eventually need to have those controllers anyway, and having those
-from the beginning allows to skip some configuration. The burdensome of
-manually creating all those classes should eventually be leveraged by using
-some rails generators.
-
-Janus also provides a finer control over setting and unsetting a user than
-Warden provides. Janus uses +login+ and +logout+ to actually sign the user
-in and out, just like Warden, but actually uses +set_user+ and +unset_user+
-to manually set the session, without dispatching the +after_login+ and
-+after_logout+ hooks, of course.
-
-Emails are also sent from the controllers, not from the models, because I
-believe this is actually the job of controllers, not models.
+Janus is an authentication engine for Ruby on Rails 3+ to painlessly handle
+users in your apps. It comes with everything needed, from the migrations to the
+controllers, plus some different strategies to keep user signed in.
+
+Janus also tries to be somewhat compatible with Devise's API and conventions,
+because there was no reason to change it completely. Thought there are some
+differences, like controllers and views being required in your apps, and emails
+being sent from the controllers and never from the models.
 
 == Features
 
-The main feature is of course having a framework for authenticating users
-painleslly. Yet a very usefull feature is the cross domain authentication
---which allows a user to single sign in and out across top level domains.
+- full auth system with strategies and hooks;
+- scoped auth for parallel authentications (like +users+, +admin_users+, etc.);
+- abstract controllers ready to use;
+- generators to have everything generated automatically;
+- use only what you need at anytime.
+
+As for the strategies and hooks:
+
+- {DatabaseAuthenticatable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/DatabaseAuthenticatable]
+  to auth users with passwords (plus registration and password reset);
+- {RemoteAuthenticatable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/RemoteAuthenticatable]
+  to keep users signed in across top level domains;
+- {Confirmable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/RemoteAuthenticatable]
+  to have users confirm their emails upon registration;
+- {Rememberable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/Rememberable]
+  to keep users authentified;
+- {Trackable}[http://rdoc.info/github/ysbaddaden/janus/Janus/Models/Trackable]
+
+== Getting Started
+
+First add the janus gem to your Gemfile, then run `bundle` to install it:
+
+  gem 'janus'
+  gem 'bcrypt-ruby'
+  # gem 'scrypt'
+
+You'll also need either the `bcrypt-ruby` or scrypt` gems, depending on which
+library you want to use to encrypt the passwords. Janus uses bcrypt by default,
+to be compatible with Devise, but you may prefer scrypt, which is stronger.
+
+Run the <tt>janus:install</tt> generator to setup janus in your app:
+
+  $ rails generate janus:install
 
-How is the cross domain authentication strategy usefull? Let's imagine you
-host of blogging website where users may host their blogs on other domains.
-Since you don't rely on subdomains, it will be a pain to keep the user
-authentified, because you can't rely on '.' domain cookie trick.
+Then create your first authenticatable resource, let's say +User+:
 
-This is where RemoteAuthentication comes in, and allows you to painlessly
-keep your users connected across the main website and their blogs. This
-without actually tracking connections since this strategy takes advantage
-of the +set_user+ and +unset_user+ methods, because they're not really
-signing in, they just stay authentified across domains.
+  $ rails generate janus:resource user
 
-So, Janus provides the following API:
+You may notice that Janus also generates all the controllers and views. This is
+because you will eventually need those to customize some behavior and having
+them around from the beginning is great.
 
-- full authentication system with strategies and hooks
-- scoped authentications with parallel authentication (like `users`, `admin_users`, etc.)
-- database authentication with password encryption (bcrypt) and validation
-- remote authentication for cross domain single sign in / sign out
-- abstract controllers for session management, registration, email confirmation and password reset
-- route generation for the above controllers
+You may run the routes rake task, to see what routes were added by Janus.
 
-And for the strategies and hooks:
+=== Helpers & Filters
+
+  - authenticate_user!
+  - user_signed_in?
+  - current_user
+
+=== Strategies
+
+You may customize the strategies for the <tt>janus:resource</tt> generator, like an
+AdminUser that may only be created and managed from the console:
+
+  $ rails generate janus:resource AdminUser session password remember
+
+Here is the list of all the current strategies:
+
+- +session+      — get users signed in and out (email/password combinaison)
+- +remember+     — keep users signed in across sessions
+- +registration+ — get users registered
+- +confirmation+ — emails may be confirmed after registration
+- +password+     — reset password (using an email exchanged token)
+- +track+        — track current and previous user's sign in date and IP
+- +remote+       — keeps users signed in different top level domains
 
-- DatabaseAuthenticatable
-- RemoteAuthenticatable
-- Confirmable
-- Rememberable
-- Trackable (note that login through Janus::Manager#set_user won't track the user).
 
 == TODO
 
-- Simple configuration to use scrypt instead of bcrypt for password encryption.
+- Differenciate mailers per resource, by looking for User::Mailer or AdminUser::Mailer classes.
 - Reconfirmable when email changes.
-- TokenAuthenticatable.
-- Remember me on remote authenticated domains.
-- Differenciate mailers per resource, by looking for Users::Mailer class.
-- Generators: `janus:install` and `janus <scope>`.
-- Integrate OmniAuth, or shall we let the user do it himself?
-- Providing an OAuth 2.0 server whould be cool.
-
-== Install
-
-There is no automated way to install Janus yet, because generators are missing.
-Also remember that Janus is only compatible with Rails 3+.
-
-First add the gem to your Gemfile:
-
-  $ gem 'janus'
-
-Configure your user models by including all or a selection of the Janus::Models
-modules:
-
-  class User < ActiveRecord::Base
-    include Janus::Models::Base
-    include Janus::Models::DatabaseAuthenticatable
-    include Janus::Models::RemoteAuthenticatable
-    include Janus::Models::Confirmable
-    include Janus::Models::Rememberable
-    include Janus::Models::Trackable
-  end
-
-  class Admin < ActiveRecord::Base
-    include Janus::Models::Base
-    include Janus::Models::DatabaseAuthenticatable
-  end
-
-Configure your routes:
-
-  Name::Application.routes.map do
-    janus :users,  :session => true, :registration => true, :password => true, :confirmation => true
-    janus :admins, :session => true
-    root :to => "home#index"
-  end
-
-Create the required controllers:
-
-  class Users::SessionsController < Janus::SessionsController
-    respond_to :html
-  end
-
-  class Users::RegistrationsController < Janus::RegistrationsController
-    respond_to :html
-  end
-
-  class Users::PasswordsController < Janus::PasswordsController
-    respond_to :html
-  end
-
-  class Users::ConfirmationsController < Janus::ConfirmationsController
-    respond_to :html
-  end
-
-  class Admins::SessionsController < Janus::SessionsController
-    respond_to :html
-  end
-
-Copy the views from test/rails_app to your application:
-
-  mkdir name/app/views/users/
-  cp -r janus/test/rails_app/app/views/users/sessions name/app/views/users/
-  cp -r janus/test/rails_app/app/views/users/registrations name/app/views/users/
-  cp -r janus/test/rails_app/app/views/users/confirmations name/app/views/users/
-  cp -r janus/test/rails_app/app/views/users/registrations name/app/views/users/
-  
-  mkdir name/app/views/admins/
-  cp -r janus/test/rails_app/app/views/users/sessions name/app/views/users/
-
-Have a look to the test app in <tt>test/rails_app</tt> for additional help:
-
-  app/controllers/application_controller.rb
-  app/controller/users/confirmations_controller.rb
-  app/controller/users/passwords_controller.rb
-  app/controller/users/registrations_controller.rb
-  app/controller/users/sessions_controller.rb
-  app/mailers/janus_mailer.rb
-  app/models/remote_token.rb
-  app/models/user.rb
-  app/views/janus_mailer/confirmation_instructions.html.erb
-  app/views/janus_mailer/confirmation_instructions.text.erb
-  app/views/janus_mailer/reset_password_instructions.html.erb
-  app/views/janus_mailer/reset_password_instructions.text.erb
-  app/views/users/confirmations/new.html.erb
-  app/views/users/passwords/new.html.erb
-  app/views/users/passwords/edit.html.erb
-  app/views/users/registrations/new.html.erb
-  app/views/users/registrations/edit.html.erb
-  app/views/users/sessions/new.html.erb
-  config/initializers/janus.rb
-  config/locales/janus.en.yml
-  config/routes.rb
-  db/migrate/*.rb
+- Simple configuration to use scrypt instead of bcrypt for password encryption.
+- TokenAuthenticatable strategy.
+- Rememberable across top level domains.
+- Omniauthable (or shall we let the user do it himself?)
+- Providing an OAuth 1.0 service whould be cool.
 
 == License
 
 Janus is distributed under the MIT-License.
 
-== Authors
+== Credits
 
 Most of the API and some code like password encryption is copied from
 Devise: http://github.com/plataformatec/devise.git and Warden:
 http://github.com/hassox/warden
 
-- Julien Portalier <ysbaddaden@gmail.com>
+- Julien Portalier <julien@portalier.com>
 

data/lib/generators/janus/install_generator.rb

@@ -0,0 +1,19 @@
+require 'securerandom'
+
+module Janus
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('../../templates', __FILE__)
+
+      desc "Configures Janus into your app"
+
+      def copy_initializer
+        template 'janus.rb', 'config/initializers/janus.rb'
+      end
+
+      def copy_locale
+        template 'janus.en.yml', 'config/locales/janus.en.yml'
+      end
+    end
+  end
+end

data/lib/generators/janus/resource_generator.rb

@@ -0,0 +1,64 @@
+module Janus
+  module Generators
+    class ResourceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('../../templates', __FILE__)
+
+      argument :strategies, :type => :array, :banner => "strategy strategy",
+        :default => %w{session registration confirmation password remember}
+
+      desc "Generates an authenticatable resource (with migration," <<
+           "routes, strategies and views)"
+
+      def create_resource
+        attributes  = [singular_name]
+        attributes += %w{email:string encrypted_password:string}
+        attributes += %w{remember_token:string:uniq remember_created_at:datetime} if strategies.include?('remember')
+        attributes += %w{confirmation_token:string:uniq confirmation_sent_at:datetime confirmed_at:datetime} if strategies.include?('confirmation')
+        attributes += %w{reset_password_token:string:uniq reset_password_sent_at:datetime} if strategies.include?('password')
+        attributes += %w{session_token:string:uniq} if strategies.include?('remote')
+        attributes += %w{sign_in_count:integer last_sign_in_at:datetime last_sign_in_ip:string current_sign_in_at:datetime current_sign_in_ip:string} if strategies.include?('track')
+        generate('model', attributes.join(' '))
+
+        modules = [
+          "  include Janus::Models::Base",
+          "  include Janus::Models::DatabaseAuthenticatable",
+        ]
+        modules << "  include Janus::Models::Rememberable" if strategies.include?('remember')
+        modules << "  include Janus::Models::Confirmable" if strategies.include?('confirmation')
+        modules << "  include Janus::Models::Trackable" if strategies.include?('track')
+        modules << "  include Janus::Models::RemoteAuthenticatable" if strategies.include?('remote')
+        inject_into_class "app/models/#{singular_name}.rb", class_name, modules.join("\n") + "\n"
+      end
+
+      def create_controllers_and_views
+        if strategies.include?('session')
+          template 'sessions_controller.erb', "app/controllers/#{plural_name}/sessions_controller.rb"
+          template 'sessions/new.html.erb',   "app/views/#{plural_name}/sessions/new.html.erb"
+        end
+        if strategies.include?('registration')
+          template 'registrations_controller.erb', "app/controllers/#{plural_name}/registrations_controller.rb"
+          template 'registrations/new.html.erb',   "app/views/#{plural_name}/registrations/new.html.erb"
+          template 'registrations/edit.html.erb',  "app/views/#{plural_name}/registrations/edit.html.erb"
+        end
+        if strategies.include?('confirmation')
+          template 'confirmations_controller.erb', "app/controllers/#{plural_name}/confirmations_controller.rb"
+          template 'confirmations/new.html.erb',   "app/views/#{plural_name}/confirmations/new.html.erb"
+        end
+        if strategies.include?('password')
+          template 'passwords_controller.erb', "app/controllers/#{plural_name}/passwords_controller.rb"
+          template 'passwords/new.html.erb',   "app/views/#{plural_name}/passwords/new.html.erb"
+          template 'passwords/edit.html.erb',  "app/views/#{plural_name}/passwords/edit.html.erb"
+        end
+      end
+
+      def add_janus_route
+        route "janus :#{plural_name}, " + controllers.map { |ctrl| ":#{ctrl} => true" }.join(', ')
+      end
+
+      private
+        def controllers
+          strategies & %w{session registration confirmation password}
+        end
+    end
+  end
+end

data/lib/generators/templates/confirmations/new.html.erb

@@ -0,0 +1,16 @@
+<h1><%%= t 'janus.confirmations.new.resend_confirmation_instructions' %></h1>
+
+<%%= form_for @<%= singular_name %>, :url => <%= singular_name %>_confirmation_path, :method => :post do |f| %>
+  <%%= janus_error_messages %>
+
+  <%% <%= class_name %>.authentication_keys.each do |key| %>
+    <div class="field">
+      <%%= f.label key %>
+      <%%= f.text_field key %>
+    </div>
+  <%% end %>
+
+  <div class="actions">
+    <%%= f.submit t('janus.confirmations.new.send_instructions_btn') %>
+  </div>
+<%% end %>

data/lib/generators/templates/confirmations_controller.erb

@@ -0,0 +1,3 @@
+class <%= class_name.pluralize %>::ConfirmationsController < Janus::ConfirmationsController
+  respond_to :html
+end

data/lib/generators/templates/janus.en.yml

@@ -0,0 +1,62 @@
+en:
+#  activerecord:
+#    attributes:
+#      user:
+#        email: "Email"
+#        password: "Password"
+#        password_confirmation: "Confirm password"
+#        current_password: "Current password"
+#  errors:
+#    messages:
+#      not_found: "not found"
+
+  flash:
+    janus:
+      passwords:
+        create:
+          email_sent: "Instructions to reset your password were sent to your email account."
+          user_not_found: "Error: no such user."
+        update:
+          password_updated: "Your password was successfully resetted."
+          invalid_token: "Error: invalid token."
+
+  janus:
+    mailer:
+      hello: "Hello,"
+      reset_password_instructions:
+        subject: "Instructions to change your password"
+        infos: "Somebody requested to change your password. To do so just click the following link:"
+        change_password_link: "Change my password"
+        please_ignore_your_password_wont_change: "If you didn't make this request, please delete this email immediately. Your password won't change until you click the link and change your password."
+
+      confirmation_instructions:
+        subject: "Confirm your account"
+        confirm: "You may confirm your registration by clicking the following link:"
+        confirm_my_account: "Confirm my account"
+
+    sessions:
+      new:
+        sign_in: "Sign in"
+        sign_in_btn: "Sign in"
+
+    registrations:
+      new:
+        sign_up: "Sign up"
+        sign_up_btn: "Sign up"
+      edit:
+        my_account: "My account"
+        save_changes_btn: "Save changes"
+
+    confirmations:
+      new:
+        resend_confirmation_instructions: "Resend confirmation instructions"
+        send_instructions_btn: "Send instructions"
+
+    passwords:
+      new:
+        forgot_password: "Forgot your password?"
+        send_instructions_btn: "Send instructions"
+      edit:
+        change_password: "Change your password"
+        change_password_btn: "Change my password"
+

data/lib/generators/templates/janus.rb

@@ -0,0 +1,25 @@
+Janus.config do |config|
+  config.contact_email = "contact@some-example-domain.com"
+
+  # DatabaseAuthenticatable
+  config.authentication_keys = [ :email ]
+
+  # you may use bcrypt:
+  config.encryptor = :bcrypt
+  config.stretches = 10
+  config.pepper = <%= SecureRandom.hex(64).inspect %>
+
+  # or you prefer scrypt:
+  # config.encryptor = :scrypt
+  # config.scrypt_options = { :max_time => 0.25 }
+
+  # Confirmable
+  # config.confirmation_key = :confirm_token
+
+  # Rememberable
+  # config.remember_for = 1.year
+  # config.extend_remember_period = false
+
+  # RemoteAuthenticatable
+  # config.remote_authentication_key = :auth_token
+end