keypairs 0.1.0.alpha.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf4de0021d86f8b939eb09102bf3523ff50c43b65306090823f4d7ea896f85c6
-  data.tar.gz: 69e0d3738b6e8d3c2d3d1e7b397b08361d83b98f075526ffd9174ab844201109
+  metadata.gz: 7d16e91f622673ad1e6b0675d86fefecfcf2dea5f49d04e4e412eb6d13b1690e
+  data.tar.gz: fce2c5965a3487437f6f265244bcc9eff7f04435104826fd9d48df51a8a7425e
 SHA512:
-  metadata.gz: 0e2acb9c0ec8069c3de1885bb810d6d759fa5e6594ce309feffb3abd5e357338106740949185734731f2fd9368b06472cbc2cd2dedc2a283711c78a17587c6af
-  data.tar.gz: 359aeb886e535c34f4c8071b4043e1186c92e91947b05c6215cd45efd3a54314abb85be17d8e56b5e186581b8a166f9b8f5f2e22ab4cc1af8a9590d796c9c546
+  metadata.gz: 608c44fa803ecd3af3bcd2e6bc16feaddefa073032c8b569d56756c23814e8bd035b2453e561de333786abc8b3c32a99d1b824e0a48d050afa8853103b255e7e
+  data.tar.gz: 586339052532023f863e8fa0fe1ab3ddce3636271be7375a21af04c3f01d348c8bdead9e6e03cd9a7d5cec0aecad40e3fa4078e1907ecd122846a90940e7109f

data/README.md

@@ -4,15 +4,28 @@ Applications often need to have a public/private keypair so sign messages. This
 Note: This gem is intended to work within Rails applications. It can probably be adjusted easily to also work for non-rails / sinatra project but that's out of scope for now. 
 
 ## Installation
-Add this line to your application's Gemfile:
+1. **Add gem**
 
-```ruby
-gem 'keypairs'
-```
+   Add this line to your application's Gemfile:
+   
+   ```ruby
+   gem 'keypairs'
+   ```
+   
+   The of course run `bundle install`. 
+
+2. **Copy migration**
+
+   The default migration file can be copied to your app with:
+   ```bash
+   bundle exec rails keypairs:install:migrations
+   ```
+   
+   Then of course run `bundle exec rails db:migrate`
 
-The of course run `bundle install` and run the migrations `bundle exec rake db:migrate`. The migrations from the gem run automatically.
+3. **Setup encryption key**
 
-The private keys are encrypted with the [lockbox](https://github.com/ankane/lockbox) gem. In order for this to work, you need to set the master key as described in [the readme](https://github.com/ankane/lockbox#key-generation), but the easiest thing is to set the environment variable `LOCKBOX_MASTER_KEY` to a sufficient long string (you can generate one with `Lockbox.generate_key`).
+   The private keys are encrypted with the [lockbox](https://github.com/ankane/lockbox) gem. In order for this to work, you need to set the master key as described in [the readme](https://github.com/ankane/lockbox#key-generation), but the easiest thing is to set the environment variable `LOCKBOX_MASTER_KEY` to a sufficient long string (you can generate one with `Lockbox.generate_key`).
 
 ## Usage
 The central point of this gem is the `Keypair` model which is backed by the `keypairs` table. If you need to sign messages, you can get the current keypair with the `Keypair.current` method. This method performs the rotation of the keypairs if required.

data/db/migrate/20201116144600_add_validity_to_keypairs.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class AddValidityToKeypairs < ActiveRecord::Migration[6.0]
+  class Keypair < ActiveRecord::Base; end
+
+  def change # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    change_table :keypairs, bulk: true do |t|
+      t.datetime :not_before, precision: 6
+      t.datetime :not_after, precision: 6
+      t.datetime :expires_at, precision: 6
+    end
+
+    reversible do |dir|
+      dir.up do
+        Keypair.find_each do |keypair|
+          keypair.update!(
+            not_before: keypair.created_at,
+            not_after: keypair.created_at + 1.month,
+            expires_at: keypair.created_at + 2.months
+          )
+        end
+      end
+    end
+
+    change_column_null :keypairs, :not_before, false
+    change_column_null :keypairs, :not_after, false
+    change_column_null :keypairs, :expires_at, false
+  end
+end

data/{app/models → lib}/keypair.rb

@@ -6,8 +6,18 @@ require 'jwt'
 # This class contains functionality needed for signing messages
 # and publishing JWK[s].
 #
-# The last three created keypairs are considered valid, so creating a new Keypair
-# will invalidate the second to last created Keypair.
+# Keypairs are considered valid based on their {#not_before}, {#not_after} and {#expires_at} attributes.
+#
+# A keypair can be used for signing if:
+# - The current time is greater than or equal to {#not_before}
+# - The current time is less than or equal to {#not_after}
+#
+# A keypair can be used for validation if:
+# - The current time is less than {#expires_at}.
+#
+# By default, this means that when a key is created, it can be used for signing for 1 month and can still be used
+# for signature validation 1 month after it is not used for signing (i.e. for 2 months since it started being used
+# for signing).
 #
 # If you need to sign messages, use the {Keypair.current} keypair for this. This method
 # performs the rotation of the keypairs if required.
@@ -21,26 +31,36 @@ require 'jwt'
 #   decoded = Keypair.jwt_decode(id_token)
 #
 # @attr [String] jwk_kid The public external id of the key used to find the associated key on decoding.
+# @attr [Time] not_before The time before which no payloads may be signed using the keypair.
+# @attr [Time] not_after The time after which no payloads may be signed using the keypair.
+# @attr [Time] expires_at The time after which the keypair may not be used for signature validation.
 class Keypair < ActiveRecord::Base
   ALGORITHM = 'RS256'
   ROTATION_INTERVAL = 1.month
 
-  encrypts :_keypair
+  lockbox_encrypts :_keypair
 
   validates :_keypair, presence: true
   validates :jwk_kid, presence: true
+  validates :not_before, :expires_at, presence: true
+
+  validate :not_after_after_not_before
+  validate :expires_at_after_not_after
 
   after_initialize :set_keypair
+  after_initialize :set_validity
 
   # @!method valid
   #   @!scope class
-  #   The last 3 keypairs are considered valid and can be used to validate signatures and export public jwks.
-  #   It uses a subquery to make sure a +find_by+ actually searches only the valid 3 ones.
-  scope :valid, -> { where(id: unscoped.order(created_at: :desc).limit(3)) }
+  #   Non-expired keypairs are considered valid and can be used to validate signatures and export public jwks.
+  scope :valid, -> { where(arel_table[:expires_at].gt(Time.zone.now)) }
 
-  # @return [Keypair] the keypair used to sign messages and autorotates if it is older than 1 month.
+  # @return [Keypair] the keypair used to sign messages and autorotates if it has expired.
   def self.current
-    order(:created_at).where(arel_table[:created_at].gt(1.month.ago)).last || create!
+    order(not_before: :asc)
+      .where(arel_table[:not_before].lteq(Time.zone.now))
+      .where(arel_table[:not_after].gteq(Time.zone.now))
+      .last || create!
   end
 
   # The JWK Set of our valid keypairs.
@@ -66,11 +86,26 @@ class Keypair < ActiveRecord::Base
   #
   # @see https://www.imsglobal.org/spec/security/v1p0/#h_key-set-url
   def self.keyset
+    valid_keys = valid.order(not_before: :asc).to_a
+    # If we don't have any keys or if we don't have a future key (i.e. the last key is the current key)
+    while valid_keys.last.nil? || valid_keys.last.not_before <= Time.zone.now
+      # There is an automatic fallback to Time.zone.now if not_before is not set
+      valid_keys << create!(not_before: valid_keys.last&.not_after)
+    end
+
     {
-      keys: valid.order(created_at: :desc).map(&:public_jwk_export)
+      keys: valid_keys.map(&:public_jwk_export)
     }
   end
 
+  # @return [Hash] a cached version of the keyset
+  # @see #keyset
+  def self.cached_keyset
+    Rails.cache.fetch('keypairs/Keypair/keyset', expires_in: 12.hours) do
+      keyset
+    end
+  end
+
   # Encodes the payload with the current keypair.
   # It forewards the call to the instance method {Keypair#jwt_encode}.
   # @return [String] Encoded JWT token with security credentials.
@@ -173,4 +208,25 @@ class Keypair < ActiveRecord::Base
     self._keypair ||= OpenSSL::PKey::RSA.new(2048).to_pem
     self.jwk_kid = public_jwk.kid
   end
+
+  # Set the validity timestamps based on the rotation interval.
+  def set_validity
+    self.not_before ||= created_at || Time.zone.now
+    self.not_after ||= not_before + ROTATION_INTERVAL
+    self.expires_at ||= not_after + ROTATION_INTERVAL
+  end
+
+  def not_after_after_not_before
+    return if not_before.nil? || not_after.nil?
+    return if not_after > not_before
+
+    errors.add(:not_after, 'must be after not before')
+  end
+
+  def expires_at_after_not_after
+    return if not_after.nil? || expires_at.nil?
+    return if expires_at > not_after
+
+    errors.add(:expires_at, 'must be after not after')
+  end
 end

data/lib/keypairs/engine.rb

@@ -1,18 +1,8 @@
 # frozen_string_literal: true
 
 module Keypairs
-  # Rails engine for this gem.
-  # It ensures that the migrations are automatically ran in the applications.
+  # This engine is only needed to add the migration installation rake task.
   class Engine < ::Rails::Engine
-    initializer :append_migrations do |app|
-      unless app.root.to_s.match? "#{root}/"
-        config.paths['db/migrate'].expanded.each do |expanded_path|
-          app.config.paths['db/migrate'] << expanded_path
-        end
-        # Apartment will modify this, but it doesn't fully support engine migrations,
-        # so we'll reset it here
-        ActiveRecord::Migrator.migrations_paths = app.paths['db/migrate'].to_a
-      end
-    end
+    engine_name 'keypairs'
   end
 end

data/{app/controllers → lib}/keypairs/public_keys_controller.rb

@@ -18,7 +18,9 @@ module Keypairs
   #  }
   class PublicKeysController < ActionController::API
     def index
-      render json: Keypair.keyset
+      # Always cache for 1 week, our rotation interval is much more than a week
+      expires_in 1.week, public: true
+      render json: Keypair.cached_keyset
     end
   end
 end

data/lib/keypairs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Keypairs
-  VERSION = '0.1.0.alpha.2'
+  VERSION = '1.1.1'
 end

data/lib/keypairs.rb

@@ -1,4 +1,12 @@
 # frozen_string_literal: true
 
 require 'lockbox'
-require 'keypairs/engine'
+
+autoload :Keypair, 'keypair.rb'
+
+# The Keypairs module contains common functionality in support of the {Keypair} model.
+module Keypairs
+  autoload :PublicKeysController, 'keypairs/public_keys_controller'
+end
+
+require 'keypairs/engine' if defined?(Rails)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: keypairs
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.2
+  version: 1.1.1
 platform: ruby
 authors:
 - Stef Schenkelaars
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-26 00:00:00.000000000 Z
+date: 2022-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: brakeman
   requirement: !ruby/object:Gem::Requirement
@@ -206,6 +220,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Manage application level keypairs with automatic rotation and JWT support
 email:
 - stef.schenkelaars@gmail.com
@@ -215,11 +243,12 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- app/controllers/keypairs/public_keys_controller.rb
-- app/models/keypair.rb
 - db/migrate/20201024100500_create_keypairs.rb
+- db/migrate/20201116144600_add_validity_to_keypairs.rb
+- lib/keypair.rb
 - lib/keypairs.rb
 - lib/keypairs/engine.rb
+- lib/keypairs/public_keys_controller.rb
 - lib/keypairs/version.rb
 homepage: https://drieam.github.io/keypairs
 licenses:
@@ -235,14 +264,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
 summary: Manage application level keypairs with automatic rotation and JWT support