ruby-paseto 0.1.0

data/lib/paseto/validator.rb

@@ -0,0 +1,154 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  class Validator
+    extend T::Sig
+    extend T::Helpers
+
+    abstract!
+
+    sig { returns(T::Hash[String, T.untyped]) }
+    attr_reader :payload
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    attr_reader :options
+
+    sig { params(payload: T::Hash[String, T.untyped], options: T::Hash[Symbol, T.untyped]).void }
+    def initialize(payload, options)
+      @payload = payload
+      @options = options
+    end
+
+    sig { abstract.void }
+    def verify; end
+
+    class Audience < Validator
+      sig { override.void }
+      def verify
+        return unless (aud = options[:verify_aud])
+
+        given = payload['aud']
+        raise InvalidAudience, "Invalid audience. Expected #{aud}, got #{given || '<none>'}" if ([*aud] & [*given]).empty?
+      end
+    end
+
+    class Expiration < Validator
+      sig { override.void }
+      def verify
+        return unless options[:verify_exp]
+
+        given = payload['exp']
+        begin
+          exp = Time.iso8601(given)
+        rescue ArgumentError
+          raise ExpiredToken, "Expiry not valid iso8601, got #{given || '<none>'}"
+        end
+
+        raise ExpiredToken, 'Expiry has passed' if Time.now > exp
+      end
+    end
+
+    class IssuedAt < Validator
+      sig { override.void }
+      def verify
+        return unless options[:verify_iat]
+
+        given = payload['iat']
+        begin
+          iat = Time.iso8601(given)
+        rescue ArgumentError
+          raise ImmatureToken, "IssuedAt not valid iso8601, got #{given || '<none>'}"
+        end
+
+        raise ImmatureToken, 'Token is from the future' if Time.now < iat
+      end
+    end
+
+    class Issuer < Validator
+      sig { override.void }
+      def verify
+        return unless (permitted = options[:verify_iss])
+
+        given = payload['iss']
+        permitted = Array(permitted).map { |i| i.is_a?(Symbol) ? i.to_s : i }
+
+        case given
+        when *permitted
+          nil
+        else
+          raise InvalidIssuer, "Invalid issuer. Expected #{permitted}, got #{given || '<none>'}"
+        end
+      end
+    end
+
+    class WPK < Validator
+      PERMITTED = T.let(%w[seal local-wrap secret-wrap].freeze, T::Array[String])
+
+      sig { override.void }
+      def verify
+        return unless (wpk = payload['wpk'])
+
+        wpk.split('.', 3) => [_, String => type, _]
+        raise InvalidWPK unless PERMITTED.include?(type)
+      end
+    end
+
+    class KeyID < Validator
+      PERMITTED = T.let(%w[lid sid pid].freeze, T::Array[String])
+
+      sig { override.void }
+      def verify
+        return unless (kid = payload['kid'])
+
+        case kid.split('.')
+        in [_, String => type, _] if PERMITTED.include?(type)
+          nil
+        else
+          raise InvalidKID
+        end
+      end
+    end
+
+    class NotBefore < Validator
+      sig { override.void }
+      def verify
+        return unless options[:verify_nbf]
+
+        given = payload['nbf']
+        begin
+          nbf = Time.iso8601(given)
+        rescue ArgumentError
+          raise InactiveToken, "NotBefore not valid iso8601, got #{given || '<none>'}"
+        end
+
+        raise InactiveToken, 'Not yet active' if nbf > Time.now
+      end
+    end
+
+    class Subject < Validator
+      sig { override.void }
+      def verify
+        return unless (sub = options[:verify_sub])
+
+        given = payload['sub']
+
+        raise InvalidSubject, "Invalid subject. Expected #{sub}, got #{given || '<none>'}" unless sub == given
+      end
+    end
+
+    class TokenIdentifier < Validator
+      sig { override.void }
+      def verify
+        return unless (jti = options[:verify_jti])
+
+        given = payload['jti']
+        if jti.respond_to?(:call)
+          raise InvalidTokenIdentifier, 'Invalid jti' unless jti.call(given)
+        elsif given.to_s.empty?
+          raise InvalidTokenIdentifier, 'Missing jti'
+        end
+      end
+    end
+  end
+end

data/lib/paseto/verifiers/footer.rb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Verifiers
+    class Footer < T::Enum
+      extend T::Sig
+
+      enums do
+        ForbiddenWPKValue = new
+        ForbiddenKIDValue = new
+      end
+
+      sig { params(footer: T::Hash[String, T.untyped], options: T::Hash[Symbol, T.untyped]).void }
+      def self.verify(footer, options)
+        values.each { |v| v.verifier.new(footer, options).verify }
+      end
+
+      sig { returns(T.class_of(Validator)) }
+      def verifier
+        case self
+        when ForbiddenWPKValue then Paseto::Validator::WPK
+        when ForbiddenKIDValue then Paseto::Validator::KeyID
+        else
+          T.absurd(self)
+        end
+      end
+    end
+  end
+end

data/lib/paseto/verifiers/payload.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Verifiers
+    class Payload < T::Enum
+      extend T::Sig
+
+      enums do
+        Audience = new
+        IssuedAt = new
+        Issuer = new
+        Expiration = new
+        NotBefore = new
+        Subject = new
+        TokenIdentifier = new
+      end
+
+      sig { params(body: T::Hash[String, T.untyped], options: T::Hash[Symbol, T.untyped]).void }
+      def self.verify(body, options)
+        values.each { |v| v.verifier.new(body, options).verify }
+      end
+
+      sig { returns(T.class_of(Validator)) }
+      def verifier # rubocop:disable Metrics/CyclomaticComplexity
+        case self
+        when Audience then Paseto::Validator::Audience
+        when IssuedAt then Paseto::Validator::IssuedAt
+        when Issuer then Paseto::Validator::Issuer
+        when Expiration then Paseto::Validator::Expiration
+        when NotBefore then Paseto::Validator::NotBefore
+        when Subject then Paseto::Validator::Subject
+        when TokenIdentifier then Paseto::Validator::TokenIdentifier
+        else
+          # :nocov:
+          T.absurd(self)
+          # :nocov:
+        end
+      end
+    end
+  end
+end

data/lib/paseto/verify.rb

@@ -0,0 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  class Verify
+    extend T::Sig
+
+    sig { returns(Result) }
+    attr_reader :result
+
+    sig do
+      params(
+        result: Result,
+        options: T::Hash[Symbol, T.untyped]
+      ).returns(Result)
+    end
+    def self.verify(result, options = {})
+      new(result, Paseto.config.decode.to_h.merge(options))
+        .then(&:verify_footer)
+        .then(&:verify_claims)
+        .then(&:result)
+    end
+
+    sig do
+      params(
+        result: Result,
+        options: T::Hash[Symbol, T.untyped]
+      ).void
+    end
+    def initialize(result, options)
+      @result = result
+      @options = options
+    end
+
+    sig { returns(T.self_type) }
+    def verify_claims
+      Verifiers::Payload.verify(@result.claims, @options)
+      self
+    end
+
+    sig { returns(T.self_type) }
+    def verify_footer
+      footer = @result.footer
+      Verifiers::Footer.verify(footer, @options) if footer.is_a?(Hash)
+      self
+    end
+  end
+end

data/lib/paseto/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  VERSION = '0.1.0'
+end

data/lib/paseto/versions.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  class Versions < T::Enum
+    extend T::Sig
+
+    enums do
+      V3Version = new(Protocol::Version3)
+      V4Version = new(Protocol::Version4)
+      V3Str = new('v3')
+      V4Str = new('v4')
+      K3Str = new('k3')
+      K4Str = new('k4')
+    end
+
+    sig { returns(Interface::Version) }
+    def instance
+      case self
+      when V3Version, V3Str, K3Str then Protocol::Version3.new
+      when V4Version, V4Str, K4Str then Protocol::Version4.new
+      end
+    end
+  end
+end

data/lib/paseto/wrappers/pie/pie_v3.rb

@@ -0,0 +1,72 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Wrappers
+    class PIE
+      class PieV3
+        extend T::Sig
+
+        include Interface::PIE
+
+        DOMAIN_SEPARATOR_AUTH = "\x81"
+        DOMAIN_SEPARATOR_ENCRYPT = "\x80"
+
+        sig { override.params(data: String).returns({ t: String, n: String, c: String }) }
+        def self.decode_and_split(data)
+          b = Util.decode64(data)
+          {
+            t: T.must(b.byteslice(0, 48)),
+            n: T.must(b.byteslice(48, 32)),
+            c: T.must(b.byteslice(80..))
+          }
+        end
+
+        sig { override.returns(Protocol::Version3) }
+        def self.protocol
+          Protocol::Version3.new
+        end
+
+        sig { override.returns(String) }
+        def local_header
+          'k3.local-wrap.pie.'
+        end
+
+        sig { override.returns(String) }
+        def secret_header
+          'k3.secret-wrap.pie.'
+        end
+
+        sig { params(wrapping_key: SymmetricKey).void }
+        def initialize(wrapping_key)
+          @wrapping_key = wrapping_key
+        end
+
+        sig { override.params(nonce: String).returns(String) }
+        def authentication_key(nonce:)
+          protocol.hmac("#{DOMAIN_SEPARATOR_AUTH}#{nonce}", key: @wrapping_key.to_bytes, digest_size: 32)
+        end
+
+        sig { override.params(payload: String, auth_key: String).returns(String) }
+        def authentication_tag(payload:, auth_key:)
+          protocol.hmac(payload, key: auth_key)
+        end
+
+        sig { override.returns(String) }
+        def random_nonce
+          protocol.random(32)
+        end
+
+        sig { override.params(nonce: String, payload: String).returns(String) }
+        def crypt(nonce:, payload:)
+          x = OpenSSL::HMAC.digest('SHA384', @wrapping_key.to_bytes, "#{DOMAIN_SEPARATOR_ENCRYPT}#{nonce}")
+          ek = T.must(x[0, 32])
+          n2 = T.must(x[32..])
+
+          protocol.crypt(key: ek, nonce: n2, payload: payload)
+        end
+      end
+    end
+  end
+end

data/lib/paseto/wrappers/pie/pie_v4.rb

@@ -0,0 +1,72 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Wrappers
+    class PIE
+      class PieV4
+        extend T::Sig
+
+        include Interface::PIE
+
+        DOMAIN_SEPARATOR_AUTH = "\x81"
+        DOMAIN_SEPARATOR_ENCRYPT = "\x80"
+
+        sig { override.params(data: String).returns({ t: String, n: String, c: String }) }
+        def self.decode_and_split(data)
+          b = Util.decode64(data)
+          {
+            t: T.must(b.byteslice(0, 32)),
+            n: T.must(b.byteslice(32, 32)),
+            c: T.must(b.byteslice(64..))
+          }
+        end
+
+        sig { override.returns(Protocol::Version4) }
+        def self.protocol
+          Protocol::Version4.new
+        end
+
+        sig { override.returns(String) }
+        def local_header
+          'k4.local-wrap.pie.'
+        end
+
+        sig { override.returns(String) }
+        def secret_header
+          'k4.secret-wrap.pie.'
+        end
+
+        sig { params(wrapping_key: SymmetricKey).void }
+        def initialize(wrapping_key)
+          @wrapping_key = wrapping_key
+        end
+
+        sig { override.params(nonce: String).returns(String) }
+        def authentication_key(nonce:)
+          protocol.hmac("#{DOMAIN_SEPARATOR_AUTH}#{nonce}", key: @wrapping_key.to_bytes, digest_size: 32)
+        end
+
+        sig { override.params(payload: String, auth_key: String).returns(String) }
+        def authentication_tag(payload:, auth_key:)
+          protocol.hmac(payload, key: auth_key, digest_size: 32)
+        end
+
+        sig { override.returns(String) }
+        def random_nonce
+          protocol.random(32)
+        end
+
+        sig { override.params(nonce: String, payload: String).returns(String) }
+        def crypt(nonce:, payload:)
+          x = protocol.hmac("#{DOMAIN_SEPARATOR_ENCRYPT}#{nonce}", key: @wrapping_key.to_bytes, digest_size: 56)
+          ek = T.must(x[0, 32])
+          n2 = T.must(x[32..])
+
+          protocol.crypt(key: ek, nonce: n2, payload: payload)
+        end
+      end
+    end
+  end
+end

data/lib/paseto/wrappers/pie.rb

@@ -0,0 +1,71 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Wrappers
+    class PIE
+      extend T::Sig
+
+      include Interface::Wrapper
+
+      sig { params(wrapping_key: SymmetricKey).void }
+      def initialize(wrapping_key)
+        @wrapping_key = wrapping_key
+        @coder = T.let(wrapping_key.pie, Interface::PIE)
+      end
+
+      sig { override.params(key: Interface::Key, nonce: T.nilable(String)).returns(String) }
+      def encode(key, nonce: nil)
+        raise LucidityError unless key.version == @wrapping_key.version
+
+        nonce ||= @coder.random_nonce
+        header = pie_header(key)
+
+        c = @coder.crypt(nonce: nonce, payload: key.to_bytes)
+
+        ak = @coder.authentication_key(nonce: nonce)
+        t = @coder.authentication_tag(payload: "#{header}#{nonce}#{c}", auth_key: ak)
+
+        [header, Util.encode64("#{t}#{nonce}#{c}")].join
+      end
+
+      sig { override.params(paserk: [String, String, String, String]).returns(Interface::Key) }
+      def decode(paserk)
+        paserk => [version, type, protocol, data]
+        raise UnknownProtocol, 'payload does not use PIE' unless protocol == 'pie'
+        raise ParseError, 'not a valid PIE PASERK' if data.empty?
+        raise LucidityError unless version == @wrapping_key.paserk_version
+
+        header = "#{version}.#{type}.pie."
+
+        # :nocov:
+        @coder.decode_and_split(data) => {t:, n:, c:}
+        # :nocov:
+
+        ak = @coder.authentication_key(nonce: n)
+        t2 = @coder.authentication_tag(payload: "#{header}#{n}#{c}", auth_key: ak)
+
+        raise InvalidAuthenticator unless Util.constant_compare(t, t2)
+
+        ptk = @coder.crypt(nonce: n, payload: c)
+
+        PaserkTypes.deserialize("#{version}.#{type}").generate(ptk)
+      end
+
+      private
+
+      sig { params(key: Interface::Key).returns(String) }
+      def pie_header(key)
+        case key
+        when SymmetricKey then @coder.local_header
+        when AsymmetricKey then @coder.secret_header
+        else
+          # :nocov:
+          raise ArgumentError, 'not a valid type of key'
+          # :nocov:
+        end
+      end
+    end
+  end
+end

data/lib/paseto.rb

@@ -0,0 +1,99 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+require 'base64'
+require 'multi_json'
+require 'openssl'
+begin
+  require 'rbnacl'
+rescue LoadError
+  raise if defined?(RbNaCl)
+end
+require 'securerandom'
+require 'sorbet-runtime'
+T::Configuration.enable_final_checks_on_hooks
+require 'time'
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+unless defined?(RbNaCl)
+  loader.ignore(
+    "#{__dir__}/paseto/v4/",
+    "#{__dir__}/paseto/sodium/",
+    "#{__dir__}/paseto/sodium.rb"
+  )
+end
+loader.inflector.inflect(
+  'asn1' => 'ASN1',
+  'ec_private_key' => 'ECPrivateKey',
+  'ecdsa_sig_value' => 'ECDSASigValue',
+  'ecdsa_signature' => 'ECDSASignature',
+  'ecdsa_full_r' => 'ECDSAFullR',
+  'pie' => 'PIE',
+  'pbkw' => 'PBKW',
+  'pbkd' => 'PBKD',
+  'id' => 'ID',
+  'pke' => 'PKE'
+)
+loader.setup
+
+module Paseto
+  extend T::Sig
+  extend Configuration
+
+  class Error < StandardError; end
+
+  class AlgorithmError < Error; end
+  # An algorithm assertion was violated, such as attempting to wrap a
+  # v4 key with a v3 key, or providing an EC key other than secp384 to v3.
+  class LucidityError < AlgorithmError; end
+
+  # A cryptographic primitive has failed for any reason,
+  # such as attempting to initialize a stream cipher with
+  # an invalid nonce.
+  class CryptoError < Error; end
+  # An authenticator was forged or otherwise corrupt
+  class InvalidAuthenticator < CryptoError; end
+  # A signature was forged or otherwise corrupt
+  class InvalidSignature < CryptoError; end
+  # Key is not valid for algorithm
+  class InvalidKeyPair < CryptoError; end
+
+  # Superclass for claim validation errors
+  class ValidationError < Error; end
+  # Token is expired
+  class ExpiredToken < ValidationError; end
+  # Token has a nbf before the current time
+  class InactiveToken < ValidationError; end
+  # Disallowed issuer
+  class InvalidIssuer < ValidationError; end
+  # Incorrect audience
+  class InvalidAudience < ValidationError; end
+  # Token issued in the future
+  class ImmatureToken < ValidationError; end
+  # Unacceptable sub
+  class InvalidSubject < ValidationError; end
+  # Missing or unacceptable jti
+  class InvalidTokenIdentifier < ValidationError; end
+  # Footer contains unknown or forbidden payload types
+  class InvalidWPK < ValidationError; end
+  # Footer contains unknown or invalid KID payloads
+  class InvalidKID < ValidationError; end
+
+  class PaserkError < Error; end
+  class UnknownProtocol < PaserkError; end
+  class UnknownOperation < PaserkError; end
+
+  # Deserialized data did not include mandatory fields.
+  class ParseError < Error; end
+  # Tried to work with a V4 token without RbNaCl loaded
+  class UnsupportedToken < ParseError; end
+
+  sig { returns(T::Boolean) }
+  def self.rbnacl?
+    !!defined?(RbNaCl)
+  end
+end
+
+loader.eager_load

data/paseto.gemspec

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'lib/paseto/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'ruby-paseto'
+  spec.version = Paseto::VERSION
+  spec.platform = Gem::Platform::RUBY
+  spec.authors = ['Joe Truba']
+  spec.email = ['joe@bannable.net']
+
+  spec.summary = 'A ruby implementation of PASETO and PASERK tokens'
+  spec.description = <<-DESCRIPTION
+    Platform Agnostic SEcurity TOkens are a specification for secure stateless tokens.
+    This is an implementation of PASETO tokens, and the PASERK key management extensions,
+    in ruby, with runtime static type checking provided by Sorbet.
+  DESCRIPTION
+  spec.homepage = 'https://github.com/bannable/paseto'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/bannable/paseto/issues',
+    'changelog_uri' => 'https://github.com/bannable/paseto/blob/main/CHANGELOG.md',
+    'documentation_uri' => 'https://github.com/bannable/paseto',
+    'homepage_uri' => 'https://github.com/bannable/paseto',
+    'source_code_uri' => 'https://github.com/bannable/paseto',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(/^(?:bin|spec|coverage|tmp|devcontainers|gemfiles)/) || # Irrelevant directories
+        f.match(/^\.+/) || # Anything starting with .
+        f.match(/^(Gemfile|Gemfile\.lock|Rakefile|Appraisals)$/) # Irrelevant files
+    end
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'multi_json', '~> 1.15.0'
+  spec.add_runtime_dependency 'openssl', '~> 3.0.0'
+  spec.add_runtime_dependency 'sorbet-runtime'
+  spec.add_runtime_dependency 'zeitwerk'
+
+  spec.add_development_dependency 'appraisal'
+  spec.add_development_dependency 'bundler', '~> 2'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop', '~> 1.38.0'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.15.0'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.14.2'
+  spec.add_development_dependency 'rubocop-sorbet', '~> 0.6.11'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'sorbet'
+  spec.add_development_dependency 'timecop'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/sorbet/config

@@ -0,0 +1,3 @@
+--dir
+.
+--ignore=vendor/