mholling-active_url 0.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Matthew Hollingworth
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,454 @@
+h1. ActiveUrl
+
+Like many Rails websites, my first production "Rails site":http://things.toswap.com.au needed user sign-ups. I wanted to have this work in a way that allowed a user to register only after confirming their email address.
+
+The way to do this is with _secret URLs_.These are URLs that contain an encrypted string and are effectively impossible to guess. By sending a secret URL to an email address, if the URL is subsequently accessed, that's pretty much a guarantee that the email was received, since there's no other way that URL could have been obtained. (Check out the ??Rails Recipes?? book, which has a good chapter explaining secret URLs.)
+
+h2. Introducing the ActiveUrl Gem
+
+As a first attempt at contributing to the Rails community, I've extracted my site's secret URL functionality into a gem. Since it's used in a similar fashion to <code:ruy>ActiveRecord</code>, I've called it <code>ActiveUrl</code>.
+
+How is my implementation distinctive? Basically, it's database-free. You don't need any new database tables or fields to use it, since all the relevant information is persisted in the URL itself. All you need to do to hide a page behind a secret URL is to nest its route beneath an ActiveUrl object that the library provides. Neat!
+
+h2. Installation & Usage
+
+First, install the gem:
+
+<pre>
+gem sources -a http://gems.github.com
+sudo gem install mholling-active_url
+</pre>
+
+In your Rails app, make sure to specify the gem dependency in environment.rb:
+
+<pre>
+config.gem "mholling-active_url", :lib => "active_url", :source => "http://gems.github.com"
+</pre>
+
+Specify a secret passphrase for the library to perform its encryption. You can set this by adding an initializer (say active_url.rb) in your config/initializers directory. This will just set the secret passphrase for your app (you might not want to check this into your source control):
+
+<pre>
+ActiveUrl.config.secret = "my-app-encryption-secret"
+</pre>
+
+To generate secret URLs in your Rails application, simply inherit a model from <code>ActiveUrl::Base</code>, in the same way you would normally inherit from <code>ActiveRecord::Base</code>. These objects won't be stored in your database; instead they will be persisted as an encrypted ID and placed in an URL given only to that user (typically by email).
+
+<pre>
+class Secret < ActiveUrl::Base
+  ...
+end
+</pre>
+
+The following class methods are available for your model:
+
+* <code>attribute(*attribute_names)</code> [sets attributes on your model];
+* <code>belongs_to(model_name)</code> [sets a "foreign key" attribute and an association method];
+* <code>attr_accessible(*attribute_names)</code> [allows mass-assignment of attributes]
+* validations: most of the ActiveRecord validations are available on the attributes you set;
+* <code>after_save(callback_name)</code> [sets a callback to be run after the object is persisted];
+* <code>find(id)</code> [finds an object from the specified ID, which will be extracted from an URL].
+
+Save your object by using the <code>ActiveUrl::Base#save</code> method--this will run any validations and generate the encrypted ID if the validations pass. (You will usually use this method in your model's controller.)
+
+In your controllers which deal with ActiveUrl models, you'll want to deal with the case of an invalid URL; usually just to render a 404. This is easily done using <code>rescue_from</code> in your application controller:
+
+<pre>
+rescue_from ActiveUrl::RecordNotFound do
+  render :file => "#{Rails.root}/public/404.html", :status => 404
+end
+</pre>
+
+h2. Example: Confirming an Email Address
+
+The typical use case for this example is the verification of an email address provided by a someone signing up to your website. You want to check that the address is valid by sending an email to that address; the user must follow a secret URL in the email to confirm they received the email.
+
+h3. Registration Model
+
+We don't want to create a User model until the email is confirmed, so instead we'll use a <code>ActiveUrl::Base</code> model. This is what will be created when a user registers:
+
+<pre>
+class Registration < ActiveUrl::Base  
+  attribute :email, :accessible => true
+  validates_format_of :email, :with => /^[\w\.=-]+@[\w\.-]+\.[a-zA-Z]{2,4}$/ix
+  validate :email_not_taken
+  
+  after_save :send_registration_email
+  
+  protected
+  
+  def email_not_taken
+    if User.find_by_email(email)
+      errors.add(:email, "is already in use")
+    end
+  end
+  
+  def send_registration_email
+    Mailer.deliver_registration(self)
+  end
+end
+</pre>
+
+Going through this step-by-step:
+
+# First, we set our email attribute using <code>attribute :email</code>, which generates setter and getter methods for the attribute.
+# Next, validate the email address so it at least looks right (<code>validates_format_of :email</code>).
+# We also want to check that a user has not already signed up with that email address, so we add a custom validation (<code>email_not_taken</code>) which adds an error if a User with that email address is found.
+# Finally, we set an <code>after_save</code> callback to actually send the registration email when the model is saved. In the mailer method, we pass in the object so that we know what email address to send to and what secret URL to use.
+
+h3. Routes
+
+Next, let's set up our routes to allow user creation only via an email confirmation. In routes.rb the relevant routes would be:
+
+<pre>
+map.resources :registrations, :only => [ :new, :create ] do |registration|
+  registration.resources :users, :only => [ :new, :create ]
+end
+</pre>
+
+h3. Registrations Controller
+
+To allow a user to register, create a registrations controller with just two REST actions, <code>new</code> and <code>create</code>. The controller is entirely generic, as it should be:
+
+<pre>
+class RegistrationsController < ApplicationController
+  def new
+    @registration = Registration.new
+  end
+
+  def create
+    @registration = Registration.new(params[:registration])
+    if @registration.save
+      flash[:notice] = "Please check your email to complete the registration."
+      redirect_to root_path # or wherever...
+    else
+      flash.now[:error] = "There were problems with that email address."
+      render :action => "new"
+    end
+  end
+end
+</pre>
+
+When the <code>create</code> action succeeds, the registration object is saved and the registration email sent automatically by its <code>after_save</code> callback.
+
+h3. Registration View
+
+In the new.html.erb view, the registration form would look something like:
+
+<pre>
+<% form_for @registration do |form| %>
+  <div>
+    <%= form.label :email %>
+    <%= form.text_field :email %>
+  </div>
+  <div>
+    <%= form.submit "Register" %>
+  </div>
+<% end %>
+</pre>
+
+h3. Mailer
+
+Finally, we set the mailer to deliver a registration email to the supplied email address:
+
+<pre>
+class Mailer < ActionMailer::Base
+  def registration(registration)
+    subject    "Registration successful"
+    recipients registration.email
+    from       "admin@website.com"
+    
+    body       :registration => registration
+  end
+end
+</pre>
+
+The registration object is passed through to the email template, where we use it to get the email address and also to generate the new user URL. Since the URL is secret, if it is subsequently accessed then we know that whoever is accessing it was able to read that email. Thus we have confirmed the email address as a real one, which is what we wanted.
+
+The email template might look something like:
+
+<pre>
+Hi <%= @registration.email %>,
+
+Thanks for registering! Please follow this link to complete your
+registration process:
+
+<%= new_registration_user_url(@registration, :host => "website.com") %>
+
+Thanks!
+website.com
+</pre>
+
+The secret URL generated in the email would look something like:
+
+<pre>
+http://website.com/registrations/yAfxbJIeUFKX9YiY6Pqv0UAwufcacnYabEYS7TxTgZY/users/new
+</pre>
+
+h3. User Model
+
+In our <code>User</code> model, we want to make sure the email address cannot be mass-assigned, so be sure to use <code>attr_protected</code> (or even better, <code>attr_accessible</code>) to prevent this:
+
+<pre>
+class User < ActiveRecord::Base
+  ...
+  attr_protected :email
+  ...
+end
+</pre>
+
+h3. Users Controller
+
+Now let's turn our attention to the users controller. We access the <code>new</code> and <code>create</code> actions only via the nested routes, so that we can load our <code>Registration</code> object from the controller parameters. We'll use the <code>ActiveUrl::Base.find</code> method to retrieve the registration object, and then set the user's email address from it:
+
+<pre>
+class UsersController < ApplicationController
+  def new
+    @registration = Registration.find(params[:registration_id])
+    @user = User.new
+    @user.email = @registration.email
+  end
+
+  def create
+    @registration = Registration.find(params[:registration_id])
+    @user = User.new(params[:user])
+    @user.email = @registration.email
+    if @user.save
+      flash[:notice] = "Thanks for registering!"
+      redirect_to @user # or wherever...
+    else
+      flash.now[:error] = "There were problems with your information."
+      render :action => "new"
+    end
+  end
+end
+</pre>
+
+h3. New User View
+
+The exact contents of the user creation form will depend on our User model, among other things. Notably however,it will *not* include a field for the email address, since we've already obtained the email address from the registration object and we don't want the user to be able to subsequently change it. (It's probably advisable to include the email address in the form's text though, for the sake of clarity.)
+
+The new user form might look something like this:
+
+<pre>
+<% form_for [ @registration, @user ] do |form| %>
+  <div>
+    Please enter new user details for <% @user.email %>.
+  </div>
+  <div>
+    <%= form.label :name %>
+    <%= form.text_field :name %>
+  </div>
+  <!-- ... other user fields here ... -->
+  <div>
+    <%= form.submit "OK" %>
+  </div>
+<% end %>
+</pre>
+
+h2. Example: Resetting a Lost Password
+
+Let's take a look at another application of the library - implementing a "reset password" function. Basically, we want to allow an user to change his/her password without logging in. We'll achieve this by sending the secret URL to the user when they submit a "forgot your password?" form.
+
+Again, the basic idea is to hide the password-editing page behind the secret URL. The password-editing page will not be protected by the usual authentication requirements; instead, the knowledge of the secret URL is what authenticates the user. 
+
+h3. Model
+
+Let's first take a look at an ActiveUrl model for the secret URL. We want to create an instance from an email address, which is what the user will still know once the password is forgotten. We could declare an email attribute as in the previous article, but the only thing our model really needs is a reference to a user, which we can derive from the email.
+
+For this purpose, we'll use the <code>belongs_to</code> feature of ActiveUrl. This is a quick-and-dirty mirror of the corresponding ActiveRecord feature. (Its only purpose though is to relate a secret URL to an existing database record, so it's only got the bare minimum of functionality.) Let's use it:
+
+<pre>
+class Secret < ActiveUrl::Base
+  belongs_to :user
+  validates_presence_of :user
+  
+  attr_reader :email
+  attr_accessible :email
+  
+  def email=(email)
+    @email = email
+    self.user = User.find_by_email(email)
+  end
+
+  after_save :send_email
+  
+  protected
+  
+  def send_email
+    Mailer.deliver_secret(self)
+  end
+end
+</pre>
+
+h4. Attributes
+
+We've set the email as a _virtual attribute_, just as we might for a normal ActiveRecord object. In addition to setting an instance variable, the email setter method also sets the user. The <code>Secret#user=</code> method is generated by the <code>belongs_to</code> association. (<code>user_id=</code>, <code>user</code> and <code>user_id</code> methods are also generated.)
+
+We can see what attributes are stored in the model, and what can be written by mass-assignment:
+
+<pre>
+Secret.attribute_names
+# => #<Set: {:user_id}>
+
+Secret.accessible_attributes
+# => #<Set: {:email}>
+</pre>
+
+In other words, the only attribute stored in the model is the user id, but that id can only be set by setting the email.
+
+<pre>
+User.first
+# => #<User id: 1, email: "name@example.com", ... >
+
+secret = Secret.new(:user_id => 1)
+secret.user_id
+# => nil
+
+secret = Secret.new(:email => "name@example.com")
+secret.user_id
+# => 1
+</pre>
+
+h4. Validations
+
+A validation, <code>validates_presence_of :user</code>, ensures that an existing user is found for the given email address. The object won't save (and the email won't get sent) if there's no user with that email address.
+
+(n.b. If you want to use the Rails error markup in your form, you might want to set an error on <code>email</code> instead.)
+
+h4. Callbacks
+
+Finally, note the <code>after_save</code> callback. It's a method which sends the secret URL to the user in an email, and it will get called when the controller successfully saves the object.
+
+h3. Routes
+
+Our routes are pretty simple. We only want to be able to create secrets, so we'll just have <code>new</code> and <code>create</code> routes. Nested under a secret, we want some routes for changing the user's password. This could be arranged in a few different ways, but let's put the password-changing actions in their own controller:
+
+<pre>
+map.resources :secrets, :only => [ :new, :create ] do |secret|
+  secret.resources :passwords, :only => [ :new, :create ]
+end
+</pre>
+
+h3. Controller
+
+As always, we strive for generic controllers, and we pretty much get one here:
+
+<pre>
+class SecretsController < ApplicationController
+  def new
+    @secret = Secret.new
+  end
+  
+  def create
+    @secret = Secret.new(params[:secret])
+    if @secret.save
+      flash[:notice] = "Please check your email for a link to change your password."
+      redirect_to root_path # or wherever...
+    else
+      flash.now[:error] = "Unrecognised email address" # if you want to disclose this...
+      render :action => "new"
+    end
+  end
+end
+</pre>
+
+Of course, there's also a <code>PasswordController</code>, which will contain the actions for changing the user's password. (The user to edit will be obtained from the secret, which in turn will be found from <code>params[:secret_id]</code>.) Its implementation will depend on the <code>User</code> model. Since these actions are hidden behind the secret URL, we'd want to skip the normal user authentication filters for the actions.
+
+h3. View
+
+How does the user actually request a password reset? By submitting his/her email address in a form. Link to this form on the login page:
+
+<pre>
+<%= link_to "I forgot my password", new_secret_path %>
+</pre>
+
+The form itself just asks for an email address:
+
+<pre>
+<% form_for @secret do |form| %>
+  <p>
+    OK, so you forgot your password.
+    No problems! Just enter your email address.
+    We'll send you a link to change your password.
+  </p>
+  <div>
+    <%= form.label :email %>
+    <%= form.text_field :email %>
+  </div>
+  <div>
+    <%= form.submit "OK" %>
+  </div>
+<% end %>
+</pre>
+
+h3. Mailer
+
+In our mailer we want to send an email containing the secret URL for the password edit action. The ActiveUrl object obtained from the URL contains all we need to know, so we just pass it through to the email template. We send the email to the secret's associated user:
+
+<pre>
+class Mailer < ActionMailer::Base
+  def secret(secret)
+    subject    "Change password requested"
+    recipients secret.user.email
+    from       "admin@website.com"
+    
+    body       :secret => secret
+  end
+end
+</pre>
+
+The email template might look something like:
+
+<pre>
+Hi <%= @secret.user.first_name %>,
+
+To change your password, please visit the following link:
+
+<%= new_secret_password_url(@secret, :host => "website.com") %>
+
+(If you did not request a password change, just ignore this email.)
+
+Thanks!
+website.com
+</pre>
+
+h3. Expiring the URL
+
+There's a potential problem with the above implementation though. As it stands, the secret URL is static - the password reset URL for any given user will always be the same. This may or may not be a problem, depending on your security requirements.
+
+It would be nice to have the URL expire once the password has been changed - in effect, to have a single-use URL. This is easily done. We add an attribute to the model containing the current password hash (or the cleartext password, if you store your user passwords in the clear - you shouldn't):
+
+<pre>
+attribute :password_hash
+
+def email=(email)
+  @email = email
+  self.user = User.find_by_email(email)
+  self.password_hash = user.password_hash if user
+end
+</pre>
+
+Then, simply validate the password hash to ensure it's the same as the user's: 
+
+<pre>
+validate :password_hash_is_current, :if => :user
+
+def password_hash_is_current
+  errors.add(:password_hash) unless user.password_hash == password_hash
+end
+</pre>
+
+Since <code>ActiveUrl::Base.find</code> only finds valid objects, once the password has been changed, the secret URL won't validate and an <code>ActiveUrl::RecordNotFound</code> error will be raised. The controller will then drop through to a 404. Easy!
+
+h2. Benefits of ActiveUrl
+
+In other email confirmation schemes, whenever a registration process is initiated, a new user object is created, even before the email address is confirmed. This causes a couple of problems:
+
+* The user model will need some form of state (to distinguish between confirmed and unconfirmed users).
+* If a registration is initiated but not completed, the unconfirmed record will remain in the database, and will need to be manually removed at a later date.
+
+The ActiveUrl gem overcomes both these problems by persisting all the relevant data to the URL itself, in encrypted form. No database table is needed.
+
+One potential problem with this approach? The URL may become quite long if you store much data in the model. Keep the number of attributes and the length of their names to a minimum to avoid this. Typically, a single attribute or a <code>belongs_to</code> reference is all that's needed, and produces URLs of modest length.
+
+Copyright (c) 2009 Matthew Hollingworth. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "active_url"
+    gem.summary = %Q{A Rails library for generating secret URLs.}
+    gem.description = <<-EOF
+      ActiveUrl enables the storing of a model in an encrypted URL. It facilitates implementation
+      of secret URLs for user (e.g. feed URLs) that can be accessed without logging in, and URLs
+      for confirming the email address of a new user.
+    EOF
+    gem.email = "mdholling@gmail.com"
+    gem.homepage = "http://github.com/mholling/active_url"
+    gem.authors = ["Matthew Hollingworth"]
+    gem.add_dependency 'activerecord'
+    gem.has_rdoc = false
+    
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "active_url #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 1
+:major: 0
+:minor: 1

data/lib/active_url/base.rb

@@ -0,0 +1,107 @@
+module ActiveUrl
+  class RecordNotFound < ActiveUrlError
+  end
+  
+  class Base
+    class_inheritable_reader :attribute_names
+    class_inheritable_reader :accessible_attributes
+    
+    def self.attribute(*attribute_names)
+      options = attribute_names.extract_options!
+      attribute_names.map(&:to_sym).each { |attribute_name| add_attribute(attribute_name, options) }
+      # attribute_names.map(&:to_sym).each do |attribute_name|
+      #   attr_accessor attribute_name
+      #   self.attribute_names << attribute_name
+      #   self.accessible_attributes << attribute_name if options[:accessible]
+      # end
+    end
+    
+    def self.attr_accessible(*attribute_names)
+      self.accessible_attributes += attribute_names.map(&:to_sym)
+    end
+    
+    attr_reader :id
+
+    def initialize(attributes = nil)
+      attributes ||= {}
+      self.attributes = attributes
+    end
+    
+    def attributes=(attributes)
+      attributes.symbolize_keys.select do |key, value|
+        self.class.accessible_attributes.include? key
+      end.map do |key, value|
+        [ "#{key}=", value ]
+      end.each do |setter, value|
+        send setter, value if respond_to? setter
+      end
+    end
+    
+    def attributes
+      attribute_names.inject({}) do |hash, name|
+        hash.merge(name => send(name))
+      end
+    end
+    
+    def create
+      serialized = [ self.class.to_s, attributes ].to_yaml
+      @id = Crypto.encrypt(serialized)
+    end
+
+    def save
+      !create.blank?
+    end
+    
+    def save!
+      save
+    end
+    
+    def self.find(id)
+      raise RecordNotFound unless id.is_a?(String) && !id.blank?
+      serialized = begin
+        Crypto.decrypt(id)
+      rescue OpenSSL::CipherError
+        raise RecordNotFound
+      end
+      type, attributes = YAML.load(serialized)
+      raise RecordNotFound unless type == self.to_s && attributes.is_a?(Hash)
+      active_url = new
+      attributes.each { |key, value| active_url.send "#{key}=", value }
+      active_url.create
+      active_url
+    rescue RecordNotFound
+      raise RecordNotFound.new("Couldn't find #{self.name} with id=#{id}")
+    end
+    
+    def to_param
+      @id.to_s
+    end
+
+    def new_record?
+      @id.nil?
+    end
+    
+    def ==(other)
+      attributes == other.attributes && self.class == other.class
+    end
+
+    private
+    
+    class_inheritable_writer :attribute_names
+    class_inheritable_writer :accessible_attributes
+    self.attribute_names = Set.new
+    self.accessible_attributes = Set.new
+    
+    def self.add_attribute(attribute_name, options)
+      attr_accessor attribute_name
+      self.attribute_names << attribute_name
+      self.accessible_attributes << attribute_name if options[:accessible]
+    end
+  end
+  
+  Base.class_eval do
+    extend BelongsTo
+    include Validations
+    include Callbacks
+  end
+end

data/lib/active_url/belongs_to.rb

@@ -0,0 +1,32 @@
+module ActiveUrl
+  module BelongsTo
+    def belongs_to(object_name)
+      begin
+        object_name.to_s.classify.constantize
+      
+        attribute_name = "#{object_name}_id"
+        attribute attribute_name
+    
+        define_method object_name do
+          begin
+            object_name.to_s.classify.constantize.find(send(attribute_name))
+          rescue ActiveRecord::RecordNotFound
+            nil
+          end
+        end
+    
+        define_method "#{object_name}=" do |object|
+          if object.nil?
+            self.send "#{object_name}_id=", nil
+          elsif object.is_a?(object_name.to_s.classify.constantize)
+            self.send "#{object_name}_id=", object.id
+          else
+            raise TypeError.new("object is not of type #{object_name.to_s.classify}")
+          end
+        end
+      rescue NameError
+        raise ArgumentError.new("#{object_name.to_s.classify} is not an ActiveRecord class.")
+      end
+    end
+  end
+end

data/lib/active_url/callbacks.rb

@@ -0,0 +1,17 @@
+module ActiveUrl
+  module Callbacks
+    def create_with_callbacks
+      result = create_without_callbacks
+      run_callbacks(:after_save) unless result.blank?
+      result
+    end
+    
+    def self.included(base)
+      base.class_eval do
+        include ActiveSupport::Callbacks # Already included by ActiveRecord.
+        alias_method_chain :create, :callbacks
+        define_callbacks :after_save
+      end
+    end
+  end
+end

data/lib/active_url/configuration.rb

@@ -0,0 +1,12 @@
+require 'singleton'
+
+module ActiveUrl
+  def self.config
+    Configuration.instance
+  end
+  
+  class Configuration
+    include Singleton
+    attr_accessor :secret
+  end
+end

data/lib/active_url/crypto.rb

@@ -0,0 +1,32 @@
+require 'openssl'
+require 'digest/sha2'
+require 'base64'
+
+module ActiveUrl
+  module Crypto
+    PADDING = { 2 => "==", 3 => "=" }
+ 
+    def self.encrypt(clear)
+      crypto = start(:encrypt)
+      cipher = crypto.update(clear)
+      cipher << crypto.final
+      Base64.encode64(cipher).gsub(/[\s=]+/, "").gsub("+", "-").gsub("/", "_")
+    end
+ 
+    def self.decrypt(b64)
+      cipher = Base64.decode64("#{b64.gsub("-", "+").gsub("_", "/")}#{PADDING[b64.length % 4]}")
+      crypto = start(:decrypt)
+      clear = crypto.update(cipher)
+      clear << crypto.final
+    end
+ 
+    private
+ 
+    def self.start(mode)
+      raise ::ArgumentError.new("Set a secret key using ActiveUrl.config.secret = 'your-secret'") if ActiveUrl.config.secret.blank?
+      crypto = OpenSSL::Cipher::Cipher.new('aes-256-ecb').send(mode)
+      crypto.key = Digest::SHA256.hexdigest(ActiveUrl.config.secret)
+      return crypto
+    end
+  end
+end

data/lib/active_url/errors.rb

@@ -0,0 +1,4 @@
+module ActiveUrl
+  class ActiveUrlError < StandardError
+  end
+end

data/lib/active_url/validations.rb

@@ -0,0 +1,57 @@
+module ActiveUrl
+  class RecordInvalid < ActiveUrlError
+    attr_reader :record
+    def initialize(record)
+      @record = record
+      super("Validation failed: #{@record.errors.full_messages.join(", ")}")
+    end
+  end
+
+  module Validations
+    module ClassMethods
+      def self_and_descendants_from_active_record
+        [self]
+      end
+      alias_method :self_and_descendents_from_active_record, :self_and_descendants_from_active_record
+      
+      def human_name()
+      end
+      
+      def human_attribute_name(name, options = {})
+        name.to_s.humanize
+      end
+      
+      def find_with_validation(id)
+        active_url = find_without_validation(id)
+        raise ActiveUrl::RecordNotFound unless active_url.valid?
+        active_url
+      end
+      
+      private
+      
+      def add_attribute_with_validation(attribute_name, options)
+        add_attribute_without_validation(attribute_name, options)
+        alias_method "#{attribute_name}_before_type_cast", attribute_name
+      end
+        
+    end
+    
+    def save_with_active_url_exception!
+      save_without_active_url_exception!
+    rescue ActiveRecord::RecordInvalid => e
+      raise ActiveUrl::RecordInvalid.new(e.record)
+    end
+
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        include ActiveRecord::Validations
+        alias_method_chain :save!, :active_url_exception
+        class << self
+          alias_method_chain :find, :validation
+          alias_method_chain :add_attribute, :validation
+        end
+      end
+    end
+  end
+end

data/lib/active_url.rb

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'active_record'
+ActiveRecord::Base # hack to get ActiveRecord::Validations to load..?
+
+require 'active_url/errors'
+require 'active_url/configuration'
+require 'active_url/crypto'
+require 'active_url/belongs_to'
+require 'active_url/validations'
+require 'active_url/callbacks'
+require 'active_url/base'
+
+# module ActiveUrl
+#   autoload :Base,          'active_url/base'
+#   autoload :Configuration, 'active_url/configuration'
+#   autoload :Crypto,        'active_url/crypto'
+#   autoload :BelongsTo,     'active_url/belongs_to'
+#   autoload :Validations,   'active_url/validations'
+#   autoload :Callbacks,     'active_url/callbacks'
+# end

data/spec/active_url_spec.rb

@@ -0,0 +1,358 @@
+require 'spec_helper'
+
+describe ActiveUrl do
+  before(:all) do
+    ActiveUrl.config.secret = 'secret'
+  end
+  
+  context "instance" do
+    before(:each) do
+      @url = ActiveUrl::Base.new
+    end
+    
+    it "should have nil id" do
+      @url.id.should be_nil
+    end
+  
+    it "should be a new_record" do
+      @url.should be_new_record
+    end
+    
+    it "should be saveable" do
+      @url.save.should be_true
+    end
+  
+    context "after saving" do
+      before(:each) do
+        @url.save
+      end
+    
+      it "should have an id" do
+        @url.id.should_not be_blank
+      end
+      
+      it "should not be a new record" do
+        @url.should_not be_new_record
+      end
+    end
+  end
+  
+  context "derived" do
+    before(:all) do  
+      class DerivedClass < ActiveUrl::Base
+        attribute :foo, :bar
+        attribute :baz, :accessible => true
+        attr_accessible :bar
+          
+        attr_accessor :x, :y
+        attr_accessible :y
+      end
+    end
+    
+    context "instance" do
+      it "should not mass-assign attributes by default" do
+        @url = DerivedClass.new(:foo => "foo")
+        @url.foo.should be_nil
+      end
+    
+      it "should mass-assign attributes declared as attr_accessible" do
+        @url = DerivedClass.new(:bar => "bar")
+        @url.bar.should == "bar"
+      end
+    
+      it "should mass-assigned attributes with :accessible specified on declaration" do
+        @url = DerivedClass.new(:baz => "baz")
+        @url.baz.should == "baz"
+      end
+
+      it "should not mass-assign virtual attributes by default" do
+        @url = DerivedClass.new(:x => "x")
+        @url.x.should be_nil
+      end
+    
+      it "should mass-assign its accessible virtual attributes" do
+        @url = DerivedClass.new(:y => "y")
+        @url.y.should == "y"
+      end
+      
+      it "should know its mass-assignable attribute names" do
+        @url = DerivedClass.new
+        [ :bar, :baz, :y ].each { |name| @url.accessible_attributes.should     include(name) }
+        [ :foo, :x       ].each { |name| @url.accessible_attributes.should_not include(name) }
+      end
+      
+      it "should know its attribute names" do
+        @url = DerivedClass.new
+        [ :foo, :bar, :baz ].each { |name| @url.attribute_names.should     include(name) }
+        [ :x, :y           ].each { |name| @url.attribute_names.should_not include(name) }
+      end
+      
+      context "equality" do
+        before(:all) do
+          class OtherClass < DerivedClass
+          end
+        end
+        
+        it "should be based on class and attributes only" do
+          @url  = DerivedClass.new(:bar => "bar", :baz => "baz")
+          @url2 = DerivedClass.new(:bar => "bar", :baz => "baz")
+          @url3 = DerivedClass.new(:bar => "BAR", :baz => "baz")
+          @url4 =   OtherClass.new(:bar => "bar", :baz => "baz")
+          @url.should == @url2
+          @url.should_not == @url3
+          @url.should_not == @url4
+        end
+      end
+    end
+    
+    context "class" do
+      it "should know its mass-assignable attribute names" do
+        [ :bar, :baz, :y ].each { |name| DerivedClass.accessible_attributes.should     include(name) }
+        [ :foo, :x       ].each { |name| DerivedClass.accessible_attributes.should_not include(name) }
+      end
+      
+      it "should know its attribute names" do
+        [ :foo, :bar, :baz ].each { |name| DerivedClass.attribute_names.should     include(name) }
+        [ :x, :y           ].each { |name| DerivedClass.attribute_names.should_not include(name) }
+      end
+    end
+  end
+  
+  context "instance with validations" do
+    before(:all) do
+      class Registration < ActiveUrl::Base  
+        attribute :name, :email, :password, :age, :accessible => true
+        validates_presence_of :name
+        validates_format_of :email, :with => /^[\w\.=-]+@[\w\.-]+\.[a-zA-Z]{2,4}$/ix
+        validates_length_of :password, :minimum => 8
+        validates_numericality_of :age
+        after_save :send_registration_email
+      
+        def send_registration_email
+          @sent = true
+        end
+      end
+    end
+    
+    context "when invalid" do
+      before(:each) do
+        @registration = Registration.new(:email => "user @ example . com", :password => "short", :age => "ten")
+      end
+      
+      it "should not validate" do
+        @registration.should_not be_valid
+      end
+  
+      it "should not save" do
+        @registration.save.should_not be_true
+        @registration.id.should be_nil
+      end
+
+      it "should raise ActiveUrl::InvalidRecord when saved with bang" do
+        lambda { @registration.save! }.should raise_error(ActiveUrl::RecordInvalid)
+      end
+      
+      context "and saved" do
+        before(:each) do
+          @registration.save
+        end
+
+        it "should have errors" do
+          @registration.errors.should_not be_empty
+        end
+        
+        it "should validate presence of an attribute" do
+          @registration.errors[:name].should_not be_blank
+        end
+        
+        it "should validate format of an attribute" do
+          @registration.errors[:email].should_not be_blank
+        end
+        
+        it "should validate length of an attribute" do
+          @registration.errors[:password].should_not be_nil
+        end
+        
+        it "should validate numericality of an attribute" do
+          @registration.errors[:age].should_not be_nil
+        end
+        
+        it "should not execute any after_save callbacks" do
+          @registration.instance_variables.should_not include("@sent")
+        end
+      end
+    end
+    
+    context "when valid" do
+      before(:each) do
+        @registration = Registration.new(:name => "John Doe", :email => "user@example.com", :password => "password", :age => "10")
+      end
+      
+      it "should validate" do
+        @registration.should be_valid
+      end
+      
+      context "and saved" do
+        before(:each) do
+          @registration.save
+        end
+        
+        it "should have an id" do
+          @registration.id.should_not be_blank
+        end
+        
+        it "should have a param equal to its id" do
+          @registration.id.should == @registration.to_param
+        end
+        
+        it "should execute any after_save callbacks" do
+          @registration.instance_variables.should include("@sent")
+        end
+        
+        context "and re-found by its class" do
+          before(:each) do
+            @found = Registration.find(@registration.id)
+          end
+          
+          it "should exist" do
+            @found.should_not be_nil
+          end
+          
+          it "should have the same id" do
+            @found.id.should == @registration.id
+          end
+          
+          it "should have the same attributes" do
+            @found.attributes.should == @registration.attributes
+          end
+          
+          it "should be valid" do
+            @found.should be_valid
+          end
+        end
+        
+        context "and subsequently made invalid" do
+          before(:each) do
+            @registration.password = "short"
+            @registration.stub!(:valid?).and_return(true)
+            @registration.save
+          end
+                              
+          it "should not be found by its class" do
+            @registration.id.should_not be_blank
+            lambda { Registration.find(@registration.id) }.should raise_error(ActiveUrl::RecordNotFound)
+          end
+        end
+      end
+    end
+    
+    it "should raise ActiveUrl::RecordNotFound if id does not exist" do
+      lambda { Registration.find("blah") }.should raise_error(ActiveUrl::RecordNotFound)
+    end
+  end
+  
+  context "instance with belongs_to association" do
+    before(:all) do    
+      # a simple pretend-ActiveRecord model for testing belongs_to without setting up a db:
+      class ::User < ActiveRecord::Base
+        def self.columns() @columns ||= []; end
+        def self.column(name, sql_type = nil, default = nil, null = true)
+          columns << ActiveRecord::ConnectionAdapters::Column.new(name.to_s, default, sql_type.to_s, null)
+        end
+      end
+    
+      class Secret < ActiveUrl::Base
+        belongs_to :user
+      end
+    end
+    
+    before(:each) do
+      @url = Secret.new
+      @user = User.new
+      @user.stub!(:id).and_return(1)
+    end
+    
+    it "should raise ArgumentError if the association name is not an ActiveRecord class" do
+      lambda { Secret.belongs_to :foo }.should raise_error(ArgumentError)
+    end
+    
+    it "should respond to association_id, association_id=, association & association=" do
+      @url.attribute_names.should include(:user_id)
+      @url.should respond_to(:user)
+      @url.should respond_to(:user=)
+    end
+    
+    it "should have nil association if association or association_id not set" do
+      @url.user.should be_nil
+    end
+    
+    it "should not allow mass assignment of association_id" do
+      @url = Secret.new(:user_id => @user.id)
+      @url.user_id.should be_nil
+      @url.user.should be_nil
+    end
+    
+    it "should not allow mass assignment of association" do
+      @url = Secret.new(:user => @user)
+      @url.user_id.should be_nil
+      @url.user.should be_nil
+    end
+    
+    it "should be able to have its association set to nil" do
+      @url.user_id = @user.id
+      @url.user = nil
+      @url.user_id.should be_nil
+    end
+    
+    it "should raise ArgumentError if association is set to wrong type" do
+      lambda { @url.user = Object.new }.should raise_error(TypeError)
+    end
+      
+    it "should find its association_id if association is set" do
+      @url.user = @user
+      @url.user_id.should == @user.id
+    end
+    
+    it "should find its association if association_id is set" do
+      User.should_receive(:find).with(@user.id).and_return(@user)
+      @url.user_id = @user.id
+      @url.user.should == @user
+    end
+    
+    it "should return nil association if association_id is unknown" do
+      User.should_receive(:find).and_raise(ActiveRecord::RecordNotFound)
+      @url.user_id = 10
+      @url.user.should be_nil
+    end
+    
+    it "should know its association when found by id" do
+      User.should_receive(:find).with(@user.id).and_return(@user)
+      @url.user_id = @user.id
+      @url.save
+      @found = Secret.find(@url.id)
+      @found.user.should == @user
+    end
+
+  end
+end
+
+describe ActiveUrl::Crypto do
+  it "should raise ArgumentError if no secret is set" do
+    ActiveUrl.config.secret = nil
+    lambda { ActiveUrl::Crypto.encrypt("clear") }.should raise_error(ArgumentError)
+    ActiveUrl.config.secret = 'secret'
+  end
+  
+  it "should decode what it encodes" do
+    ActiveUrl::Crypto.decrypt(ActiveUrl::Crypto.encrypt("clear")).should == "clear"
+  end
+  
+  it "should always yield URL-safe output characters" do
+    url_safe = /^[\w\-]*$/
+    (1..20).each do |n|
+      clear = (0...8).inject("") { |string, n| string << rand(255).chr } # random string
+      cipher = ActiveUrl::Crypto.encrypt(clear)
+      cipher.should =~ url_safe
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'spec'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'active_url'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: mholling-active_url
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Matthew Hollingworth
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-21 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: ActiveUrl enables the storing of a model in an encrypted URL. It facilitates implementation of secret URLs for user (e.g. feed URLs) that can be accessed without logging in, and URLs for confirming the email address of a new user.
+email: mdholling@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.textile
+files: 
+- LICENSE
+- README.textile
+- Rakefile
+- VERSION.yml
+- lib/active_url.rb
+- lib/active_url/base.rb
+- lib/active_url/belongs_to.rb
+- lib/active_url/callbacks.rb
+- lib/active_url/configuration.rb
+- lib/active_url/crypto.rb
+- lib/active_url/errors.rb
+- lib/active_url/validations.rb
+- spec/active_url_spec.rb
+- spec/spec_helper.rb
+has_rdoc: false
+homepage: http://github.com/mholling/active_url
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A Rails library for generating secret URLs.
+test_files: 
+- spec/active_url_spec.rb
+- spec/spec_helper.rb