ruby-paseto 0.1.0

data/lib/paseto/protocol/version3.rb

@@ -0,0 +1,100 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Protocol
+    class Version3
+      extend T::Sig
+      extend T::Helpers
+
+      include Interface::Version
+
+      sig(:final) { override.params(key: String, nonce: String, payload: String).returns(String) }
+      def self.crypt(key:, nonce:, payload:)
+        cipher = OpenSSL::Cipher.new('aes-256-ctr')
+        cipher.key = key
+        cipher.iv = nonce
+        cipher.update(payload) + cipher.final
+      end
+
+      sig(:final) { override.params(data: String, digest_size: Integer).returns(String) }
+      def self.digest(data, digest_size:)
+        T.must(OpenSSL::Digest.digest('SHA384', data).byteslice(0, digest_size))
+      end
+
+      sig(:final) { override.returns(Integer) }
+      def self.digest_bytes
+        48
+      end
+
+      sig(:final) { override.params(data: String, key: String, digest_size: Integer).returns(String) }
+      def self.hmac(data, key:, digest_size:)
+        T.must(OpenSSL::HMAC.digest('SHA384', key, data).byteslice(0, digest_size))
+      end
+
+      sig(:final) { override.returns(T.class_of(Operations::ID::IDv3)) }
+      def self.id
+        Operations::ID::IDv3
+      end
+
+      sig(:final) do
+        override.params(
+          password: String,
+          salt: String,
+          length: Integer,
+          parameters: Integer
+        ).returns(String)
+      end
+      def self.kdf(password, salt:, length:, **parameters)
+        OpenSSL::KDF.pbkdf2_hmac(
+          password,
+          salt: salt,
+          length: length,
+          iterations: T.must(parameters[:iterations]),
+          hash: 'SHA384'
+        )
+      end
+
+      sig(:final) { override.returns(String) }
+      def self.paserk_version
+        'k3'
+      end
+
+      sig(:final) { override.returns(String) }
+      def self.pbkd_local_header
+        'k3.local-pw'
+      end
+
+      sig(:final) { override.returns(String) }
+      def self.pbkd_secret_header
+        'k3.secret-pw'
+      end
+
+      sig(:final) { override.params(password: String).returns(Operations::PBKD::PBKDv3) }
+      def self.pbkw(password)
+        Operations::PBKD::PBKDv3.new(password)
+      end
+
+      sig(:final) { override.params(key: SymmetricKey).returns(Wrappers::PIE::PieV3) }
+      def self.pie(key)
+        Wrappers::PIE::PieV3.new(key)
+      end
+
+      sig(:final) { override.params(key: AsymmetricKey).returns(Operations::PKE::PKEv3) }
+      def self.pke(key)
+        Operations::PKE::PKEv3.new(key)
+      end
+
+      sig(:final) { override.params(size: Integer).returns(String) }
+      def self.random(size)
+        SecureRandom.random_bytes(size)
+      end
+
+      sig(:final) { override.returns(String) }
+      def self.version
+        'v3'
+      end
+    end
+  end
+end

data/lib/paseto/protocol/version4.rb

@@ -0,0 +1,99 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Protocol
+    class Version4
+      extend T::Sig
+      extend T::Helpers
+
+      include Interface::Version
+
+      sig(:final) { override.params(key: String, nonce: String, payload: String).returns(String) }
+      def self.crypt(key:, nonce:, payload:)
+        Paseto::Sodium::Stream::XChaCha20Xor.new(key).encrypt(nonce, payload)
+      end
+
+      sig(:final) { override.params(data: String, digest_size: Integer).returns(String) }
+      def self.digest(data, digest_size:)
+        RbNaCl::Hash.blake2b(data, digest_size: digest_size)
+      end
+
+      sig(:final) { override.returns(Integer) }
+      def self.digest_bytes
+        32
+      end
+
+      sig(:final) { override.params(data: String, key: String, digest_size: Integer).returns(String) }
+      def self.hmac(data, key:, digest_size: 32)
+        RbNaCl::Hash.blake2b(data, key: key, digest_size: digest_size)
+      end
+
+      sig(:final) { override.returns(T.class_of(Operations::ID::IDv4)) }
+      def self.id
+        Operations::ID::IDv4
+      end
+
+      sig(:final) do
+        override.params(
+          password: String,
+          salt: String,
+          length: Integer,
+          parameters: T.any(Symbol, Integer)
+        ).returns(String)
+      end
+      def self.kdf(password, salt:, length:, **parameters)
+        memlimit = RbNaCl::PasswordHash::Argon2.memlimit_value(parameters[:memlimit])
+        opslimit = RbNaCl::PasswordHash::Argon2.opslimit_value(parameters[:opslimit])
+
+        RbNaCl::PasswordHash.argon2id(
+          password,
+          salt,
+          opslimit,
+          memlimit,
+          length
+        )
+      end
+
+      sig(:final) { override.returns(String) }
+      def self.paserk_version
+        'k4'
+      end
+
+      sig(:final) { override.returns(String) }
+      def self.pbkd_local_header
+        'k4.local-pw'
+      end
+
+      sig(:final) { override.returns(String) }
+      def self.pbkd_secret_header
+        'k4.secret-pw'
+      end
+
+      sig(:final) { override.params(password: String).returns(Operations::PBKD::PBKDv4) }
+      def self.pbkw(password)
+        Operations::PBKD::PBKDv4.new(password)
+      end
+
+      sig(:final) { override.params(key: SymmetricKey).returns(Wrappers::PIE::PieV4) }
+      def self.pie(key)
+        Wrappers::PIE::PieV4.new(key)
+      end
+
+      sig(:final) { override.params(key: AsymmetricKey).returns(Operations::PKE::PKEv4) }
+      def self.pke(key)
+        Operations::PKE::PKEv4.new(key)
+      end
+
+      sig(:final) { override.params(size: Integer).returns(String) }
+      def self.random(size)
+        RbNaCl::Random.random_bytes(size)
+      end
+
+      sig(:final) { override.returns(String) }
+      def self.version
+        'v4'
+      end
+    end
+  end
+end

data/lib/paseto/result.rb

@@ -0,0 +1,9 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  class Result < T::Struct
+    prop :claims, T::Hash[String, T.untyped]
+    prop :footer, T.nilable(T.any(String, T::Hash[String, T.untyped])), default: nil
+  end
+end

data/lib/paseto/serializer/optional_json.rb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Serializer
+    module OptionalJson
+      extend T::Sig
+
+      extend Interface::Serializer
+
+      sig { override.params(val: String, options: T::Hash[T.untyped, T.untyped]).returns(T.untyped) }
+      def self.deserialize(val, options)
+        obj = MultiJson.load(val, options)
+        case obj
+        when Hash then obj
+        else val
+        end
+      rescue MultiJson::ParseError
+        val
+      end
+
+      sig { override.params(val: T.untyped, options: T::Hash[T.untyped, T.untyped]).returns(String) }
+      def self.serialize(val, options)
+        return val unless val.is_a?(Hash)
+
+        MultiJson.dump(val, options)
+      end
+    end
+  end
+end

data/lib/paseto/serializer/raw.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Serializer
+    module Raw
+      extend T::Sig
+
+      extend Interface::Serializer
+
+      sig(:final) do
+        override.params(
+          val: String,
+          _options: T::Hash[T.untyped, T.untyped]
+        ).returns(T.any(String, T::Hash[String, T.untyped]))
+      end
+      def self.deserialize(val, _options) = val
+
+      sig(:final) { override.params(val: T.untyped, _options: T.untyped).returns(String) }
+      def self.serialize(val, _options) = val
+    end
+  end
+end

data/lib/paseto/sodium/curve_25519.rb

@@ -0,0 +1,46 @@
+# typed: false
+# frozen_string_literal: true
+
+module Paseto
+  module Sodium
+    class Curve25519
+      extend T::Sig
+
+      extend RbNaCl::Sodium
+
+      sodium_type :sign
+      sodium_primitive :ed25519
+
+      sodium_function :to_x25519_private_key,
+                      :crypto_sign_ed25519_sk_to_curve25519,
+                      %i[pointer pointer]
+
+      sodium_function :to_x25519_public_key,
+                      :crypto_sign_ed25519_pk_to_curve25519,
+                      %i[pointer pointer]
+
+      sig { params(key: V4::Public).void }
+      def initialize(key)
+        @key = key
+      end
+
+      sig { returns(RbNaCl::PrivateKey) }
+      def to_x25519_private_key
+        buffer = RbNaCl::Util.zeros(RbNaCl::PrivateKey::BYTES)
+        success = self.class.to_x25519_private_key(buffer, @key.to_bytes)
+        raise CryptoError, 'Ed25519->X25519 sk failure' unless success
+
+        RbNaCl::PrivateKey.new(buffer)
+      end
+
+      sig { returns(RbNaCl::PublicKey) }
+      def to_x25519_public_key
+        buffer = RbNaCl::Util.zeros(RbNaCl::PublicKey::BYTES)
+        success = self.class.to_x25519_public_key(buffer, @key.public_bytes)
+        raise CryptoError, 'Ed25519->X25519 pk failure' unless success
+
+        RbNaCl::PublicKey.new(buffer)
+      end
+    end
+  end
+end

data/lib/paseto/sodium/safe_ed25519_loader.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Sodium
+    module SafeEd25519Loader
+      extend T::Sig
+
+      include Kernel
+
+      sig(:final) { params(keypair: String).returns(RbNaCl::SigningKey) }
+      def self.from_keypair(keypair)
+        RbNaCl::SigningKey.new(keypair[0, 32]).tap do |key|
+          raise InvalidKeyPair, 'public key does not match private' unless keypair == key.keypair_bytes
+        end
+      end
+    end
+  end
+end

data/lib/paseto/sodium/stream/base.rb

@@ -0,0 +1,82 @@
+# encoding: binary
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  module Sodium
+    module Stream
+      # Abstract base class for Stream ciphers
+      class Base
+        extend T::Sig
+        extend T::Helpers
+
+        abstract!
+
+        # Number of bytes in a valid key
+        KEYBYTES = 0
+
+        # Number of bytes in a valid nonce
+        NONCEBYTES = 0
+
+        MESSAGEBYTES_MAX = 0
+
+        sig { returns(Integer) }
+        def self.nonce_bytes
+          const_get(:NONCEBYTES)
+        end
+
+        sig { returns(Integer) }
+        def self.key_bytes
+          const_get(:KEYBYTES)
+        end
+
+        # Create a new Stream.
+        #
+        # Sets up Stream with a secret key for encrypting and decrypting messages.
+        sig { params(key: String).void }
+        def initialize(key)
+          RbNaCl::Util.check_length(key, key_bytes, 'Key')
+          @key = key
+        end
+
+        sig { params(nonce: String, message: T.nilable(String)).returns(String) }
+        def encrypt(nonce, message)
+          RbNaCl::Util.check_length(nonce, nonce_bytes, 'Nonce')
+
+          ciphertext = RbNaCl::Util.zeros(data_len(message))
+
+          success = do_encrypt(ciphertext, nonce, message)
+          raise CryptoError, 'Encryption failed' unless success
+
+          ciphertext
+        end
+
+        sig { returns(Integer) }
+        def nonce_bytes
+          self.class.nonce_bytes
+        end
+
+        sig { returns(Integer) }
+        def key_bytes
+          self.class.key_bytes
+        end
+
+        private
+
+        # Symmetric encryption key for a cipher instance
+        sig { returns(String) }
+        attr_reader :key
+
+        sig { abstract.params(ciphertext: String, nonce: String, message: T.nilable(String)).returns(T::Boolean) }
+        def do_encrypt(ciphertext, nonce, message); end
+
+        sig { params(message: T.nilable(String)).returns(Integer) }
+        def data_len(message)
+          return 0 unless message
+
+          message.bytesize
+        end
+      end
+    end
+  end
+end

data/lib/paseto/sodium/stream/x_cha_cha20_xor.rb

@@ -0,0 +1,31 @@
+# encoding: binary
+# typed: false
+# frozen_string_literal: true
+
+module Paseto
+  module Sodium
+    module Stream
+      class XChaCha20Xor < Paseto::Sodium::Stream::Base
+        extend RbNaCl::Sodium
+        sodium_type :stream
+
+        sodium_primitive :xchacha20
+
+        sodium_constant :KEYBYTES
+        sodium_constant :NONCEBYTES
+        sodium_constant :MESSAGEBYTES_MAX
+
+        sodium_function :stream_xchacha20_xor,
+                        :crypto_stream_xchacha20_xor,
+                        %i[pointer pointer ulong_long pointer pointer]
+
+        private
+
+        sig { override.params(ciphertext: String, nonce: String, message: T.nilable(String)).returns(T::Boolean) }
+        def do_encrypt(ciphertext, nonce, message)
+          self.class.stream_xchacha20_xor(ciphertext, message, data_len(message), nonce, key)
+        end
+      end
+    end
+  end
+end

data/lib/paseto/sodium.rb

@@ -0,0 +1,5 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative 'sodium/stream/base'
+require_relative 'sodium/stream/x_cha_cha20_xor'

data/lib/paseto/symmetric_key.rb

@@ -0,0 +1,119 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  class SymmetricKey < Interface::Key
+    extend T::Sig
+    extend T::Helpers
+
+    abstract!
+
+    sig(:final) { returns(String) }
+    attr_reader :key, :lid, :paserk
+
+    sig { params(ikm: String).void }
+    def initialize(ikm)
+      raise ArgumentError, 'ikm must be 32 bytes' unless ikm.bytesize == 32
+
+      @key = T.let(ikm.freeze, String)
+      @paserk = T.let("#{paserk_version}.#{purpose}.#{Util.encode64(key)}".freeze, String)
+      @lid = T.let(Operations::ID.lid(self).freeze, String)
+    end
+
+    # Encrypts and authenticates `message` with optional binding input `implicit_assertion`, returning a `Token`.
+    # If `footer` is provided, it is included as authenticated data in the reuslting `Token``.
+    # `n` must not be used outside of tests.
+    sig(:final) { params(message: String, footer: String, implicit_assertion: String, n: T.nilable(String)).returns(Token) }
+    def encrypt(message:, footer: '', implicit_assertion: '', n: nil) # rubocop:disable Naming/MethodParameterName
+      n ||= SecureRandom.random_bytes(32)
+
+      ek, n2, ak = calc_keys(n)
+
+      c = protocol.crypt(payload: message, key: ek, nonce: n2)
+
+      Util.pre_auth_encode(pae_header, n, c, footer, implicit_assertion)
+          .then { |pre_auth| protocol.hmac(pre_auth, key: ak) }
+          .then { |t| "#{n}#{c}#{t}" }
+          .then { |payload| Token.new(payload: payload, version: version, purpose: purpose, footer: footer) }
+    end
+
+    # Verify and decrypt an encrypted Token, with an optional string `implicit_assertion`, and return the plaintext.
+    # If `token` includes a footer, it is treated as authenticated data to be verified but not returned.
+    # `token` must be a `v4.local` type Token.
+    sig(:final) { params(token: Token, implicit_assertion: String).returns(String) }
+    def decrypt(token:, implicit_assertion: '')
+      raise LucidityError unless header == token.header
+
+      n, c, t = split_payload(token.raw_payload)
+
+      ek, n2, ak = calc_keys(n)
+
+      pre_auth = Util.pre_auth_encode(pae_header, n, c, token.raw_footer, implicit_assertion)
+      t2 = protocol.hmac(pre_auth, key: ak)
+      raise InvalidAuthenticator unless Util.constant_compare(t, t2)
+
+      protocol.crypt(payload: c, key: ek, nonce: n2).encode(Encoding::UTF_8)
+    rescue Encoding::UndefinedConversionError
+      raise ParseError, 'invalid payload encoding'
+    end
+
+    sig(:final) do
+      override.params(
+        payload: T::Hash[String, T.untyped],
+        footer: String,
+        implicit_assertion: String,
+        options: T.nilable(T.any(String, Integer, Symbol, T::Boolean))
+      ).returns(String)
+    end
+    def encode!(payload, footer: '', implicit_assertion: '', **options)
+      n = T.cast(options.delete(:nonce), T.nilable(String))
+      MultiJson.dump(payload, options)
+               .then { |message| encrypt(message: message, footer: footer, implicit_assertion: implicit_assertion, n: n) }
+               .then(&:to_s)
+    end
+
+    sig(:final) do
+      override.params(
+        payload: String,
+        implicit_assertion: String,
+        options: T.nilable(T.any(Proc, String, Integer, Symbol, T::Boolean))
+      ).returns(Result)
+    end
+    def decode!(payload, implicit_assertion: '', **options)
+      token = Token.parse(payload)
+
+      decrypt(token: token, implicit_assertion: implicit_assertion)
+        .then { |json| MultiJson.load(json, **options) }
+        .then { |claims| Result.new(claims: claims, footer: token.footer) }
+    end
+
+    sig(:final) { override.returns(String) }
+    def id = @lid
+
+    sig(:final) { override.returns(String) }
+    def pbkw_header = protocol.pbkd_local_header
+
+    sig(:final) { returns(Interface::PIE) }
+    def pie = protocol.pie(self)
+
+    sig(:final) { override.returns(String) }
+    def purpose = 'local'
+
+    sig(:final) { override.returns(String) }
+    def to_bytes = key
+
+    sig(:final) { params(paserk: String).returns(Interface::Key) }
+    def unwrap(paserk) = Paserk.from_paserk(paserk: paserk, wrapping_key: self)
+
+    sig(:final) { params(key: Interface::Key, nonce: T.nilable(String)).returns(String) }
+    def wrap(key, nonce: nil) = Paserk.wrap(key: key, wrapping_key: self, nonce: nonce)
+
+    private
+
+    sig { abstract.params(nonce: String).returns([String, String, String]) }
+    def calc_keys(nonce); end
+
+    sig { abstract.params(payload: String).returns([String, String, String]) }
+    def split_payload(payload); end
+  end
+end

data/lib/paseto/token.rb

@@ -0,0 +1,127 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Paseto
+  class Token
+    extend T::Sig
+    include Comparable
+
+    sig { returns(String) }
+    attr_reader :version, :purpose, :raw_payload, :raw_footer
+
+    sig { returns(T.any(String, T::Hash[String, T.untyped])) }
+    attr_reader :footer
+
+    sig { returns(T.class_of(Interface::Key)) }
+    attr_reader :type
+
+    sig do
+      params(
+        paseto: String,
+        options: T.nilable(T.any(Proc, String, Integer, Symbol, T::Boolean))
+      ).returns(Token)
+    end
+    def self.parse(paseto, **options)
+      case paseto.split('.')
+      in [String => version, String => purpose, String => payload, String => footer]
+        nil
+      in [String => version, String => purpose, String => payload]
+        footer = ''
+      else
+        raise ParseError, 'not a valid token'
+      end
+
+      payload = Util.decode64(payload)
+      Util.decode64(footer)
+          .then { |f| serializer.deserialize(f, options) }
+          .then { |f| new(version: version, purpose: purpose, payload: payload, footer: f) }
+    end
+
+    sig { returns(Paseto::Interface::Serializer) }
+    def self.serializer
+      Paseto.config.decode.footer_serializer
+    end
+
+    sig do
+      params(
+        payload: String,
+        purpose: String,
+        version: String,
+        footer: T.any(String, T::Hash[String, T.untyped]),
+        options: T.nilable(T.any(Proc, String, Integer, Symbol, T::Boolean))
+      ).void
+    end
+    def initialize(payload:, purpose:, version:, footer: '', **options) # rubocop:disable Metrics/AbcSize
+      raw_footer = serializer.serialize(footer, options)
+      encoded_footer = ".#{Util.encode64(raw_footer)}" unless raw_footer.empty?
+
+      paseto = Util.encode64(payload)
+                   .then { |data| "#{data}#{encoded_footer}" }
+                   .then { |data| "#{version}.#{purpose}.#{data}" }
+                   .then(&:freeze)
+
+      @version =     T.let(version.freeze,             String)
+      @purpose =     T.let(purpose.freeze,             String)
+      @raw_payload = T.let(payload.freeze,             String)
+      @type =        T.let(validate_header,            T.class_of(Interface::Key))
+      @footer =      T.let(footer,                     T.any(String, T::Hash[String, T.untyped]))
+      @raw_footer =  T.let(raw_footer,                 String)
+      @str =         T.let(paseto,                     String)
+    end
+
+    sig do
+      params(
+        key: Interface::Key,
+        implicit_assertion: String,
+        options: T.nilable(T.any(Proc, String, Integer, Symbol, T::Boolean))
+      ).returns(T::Hash[String, T.untyped])
+    end
+    def decode!(key, implicit_assertion: '', **options)
+      return @result.claims if @result
+
+      key.decode(@str, implicit_assertion: implicit_assertion, **options)
+         .then { |result| @result = T.let(result, T.nilable(Result)) }
+         .then(&:claims)
+    end
+
+    sig { returns(String) }
+    def header
+      "#{version}.#{purpose}"
+    end
+
+    sig { returns(String) }
+    def inspect
+      to_s
+    end
+
+    sig { returns(T::Hash[String, T.untyped]) }
+    def payload
+      return @result.claims if @result
+
+      raise ParseError, 'token not yet decoded, call #decode! first'
+    end
+
+    sig { returns(String) }
+    def to_s = @str
+
+    sig { params(other: T.any(Token, String)).returns(T.nilable(Integer)) }
+    def <=>(other)
+      to_s <=> other.to_s
+    end
+
+    private
+
+    sig { returns(Paseto::Interface::Serializer) }
+    def serializer = self.class.serializer
+
+    sig { returns(T.class_of(Interface::Key)) }
+    def validate_header
+      type = TokenTypes.deserialize(header).key_klass
+      return type if type
+
+      raise UnsupportedToken, header
+    rescue KeyError
+      raise UnsupportedToken, header
+    end
+  end
+end