standard_singpass 0.1.0

data/lib/standard_singpass/myinfo/ecdh_jwe.rb

@@ -0,0 +1,350 @@
+# typed: strict
+
+module StandardSingpass
+  module Myinfo
+    # Native ECDH-ES+A256KW JWE implementation for decryption.
+    #
+    # The `jwt` gem does not support ECDH-ES key agreement algorithms; this
+    # service implements the subset needed for MyInfo (FAPI 2.0):
+    #   alg: ECDH-ES+A256KW
+    #   enc: A128CBC-HS256, A256CBC-HS512, A128GCM, A256GCM
+    #
+    # References:
+    #   - RFC 7516 (JWE)
+    #   - RFC 7518 Section 4.6 (ECDH-ES key agreement)
+    #   - NIST SP 800-56A Concat KDF
+    class EcdhJwe
+      extend T::Sig
+
+      class DecryptionFailed < StandardError; end
+      class InvalidAlgorithm < StandardError; end
+
+      SUPPORTED_ALGS = T.let(%w[ECDH-ES+A128KW ECDH-ES+A256KW].freeze, T::Array[String])
+      SUPPORTED_ENCS = T.let(%w[A128CBC-HS256 A256CBC-HS512 A128GCM A256GCM].freeze, T::Array[String])
+
+      # Key wrap key sizes (in bytes) for each alg
+      KEK_SIZES = T.let({
+        "ECDH-ES+A128KW" => 16,
+        "ECDH-ES+A256KW" => 32
+      }.freeze, T::Hash[String, Integer])
+
+      # CEK sizes (in bytes) for each enc
+      CEK_SIZES = T.let({
+        "A128CBC-HS256" => 32,
+        "A256CBC-HS512" => 64,
+        "A128GCM" => 16,
+        "A256GCM" => 32
+      }.freeze, T::Hash[String, Integer])
+
+      # Encrypts a payload and returns a compact-serialized JWE string.
+      sig do
+        params(
+          payload: String,
+          public_key: OpenSSL::PKey::EC,
+          alg: String,
+          enc: String,
+          kid: T.nilable(String),
+          apu: T.nilable(String),
+          apv: T.nilable(String)
+        ).returns(String)
+      end
+      def self.encrypt(payload, public_key:, alg:, enc:, kid: nil, apu: nil, apv: nil)
+        validate_algorithms!(alg, enc)
+
+        # Generate ephemeral key pair on same curve
+        group = public_key.group
+        ephemeral_key = OpenSSL::PKey::EC.generate(group.curve_name)
+
+        # ECDH key agreement
+        shared_secret = derive_shared_secret(ephemeral_key, public_key)
+
+        # Derive KEK via Concat KDF
+        kek_size = KEK_SIZES.fetch(alg)
+        kek = concat_kdf(shared_secret, alg, kek_size, apu:, apv:)
+
+        # Generate random CEK
+        cek_size = CEK_SIZES.fetch(enc)
+        cek = SecureRandom.random_bytes(cek_size)
+
+        # Wrap CEK with KEK
+        encrypted_key = AESKeyWrap.wrap(cek, kek)
+
+        # Build header
+        epk_jwk = ec_public_key_to_jwk(ephemeral_key)
+        header = { "alg" => alg, "enc" => enc, "epk" => epk_jwk }
+        header["kid"] = kid if kid
+        header["apu"] = Base64.urlsafe_encode64(apu, padding: false) if apu
+        header["apv"] = Base64.urlsafe_encode64(apv, padding: false) if apv
+
+        # Encrypt content
+        header_b64 = Base64.urlsafe_encode64(header.to_json, padding: false)
+        iv, ciphertext, auth_tag = encrypt_content(cek, enc, payload, header_b64)
+
+        # Assemble compact serialization
+        [
+          header_b64,
+          Base64.urlsafe_encode64(encrypted_key, padding: false),
+          Base64.urlsafe_encode64(T.must(iv), padding: false),
+          Base64.urlsafe_encode64(T.must(ciphertext), padding: false),
+          Base64.urlsafe_encode64(T.must(auth_tag), padding: false)
+        ].join(".")
+      end
+
+      # Decrypts a compact-serialized JWE string.
+      sig { params(jwe_string: String, private_key: OpenSSL::PKey::EC).returns(String) }
+      def self.decrypt(jwe_string, private_key:)
+        parts = jwe_string.split(".")
+        raise DecryptionFailed, "Invalid JWE format" unless parts.length == 5
+
+        header_b64, encrypted_key_b64, iv_b64, ciphertext_b64, tag_b64 = parts
+
+        header = JSON.parse(Base64.urlsafe_decode64(T.must(header_b64)))
+        alg = header["alg"]
+        enc = header["enc"]
+
+        validate_algorithms!(alg, enc)
+
+        epk = header["epk"]
+        raise DecryptionFailed, "Missing ephemeral public key (epk)" unless epk
+
+        # Decode apu/apv from header if present
+        apu = header["apu"] ? Base64.urlsafe_decode64(header["apu"]) : nil
+        apv = header["apv"] ? Base64.urlsafe_decode64(header["apv"]) : nil
+
+        # Reconstruct ephemeral public key
+        ephemeral_public_key = jwk_to_ec_public_key(epk)
+
+        # ECDH key agreement
+        shared_secret = derive_shared_secret(private_key, ephemeral_public_key)
+
+        # Derive KEK via Concat KDF
+        kek_size = KEK_SIZES.fetch(alg)
+        kek = concat_kdf(shared_secret, alg, kek_size, apu:, apv:)
+
+        # Unwrap CEK
+        encrypted_key = Base64.urlsafe_decode64(T.must(encrypted_key_b64))
+        cek = AESKeyWrap.unwrap(encrypted_key, kek)
+        raise DecryptionFailed, "Key unwrap failed" unless cek
+
+        # Decrypt content
+        iv = Base64.urlsafe_decode64(T.must(iv_b64))
+        ciphertext = Base64.urlsafe_decode64(T.must(ciphertext_b64))
+        auth_tag = Base64.urlsafe_decode64(T.must(tag_b64))
+
+        decrypt_content(cek, enc, ciphertext, iv, auth_tag, T.must(header_b64))
+      rescue JSON::ParserError, ArgumentError => e
+        raise DecryptionFailed, "Malformed JWE: #{e.message}"
+      rescue OpenSSL::OpenSSLError => e
+        raise DecryptionFailed, "Decryption failed: #{e.message}"
+      end
+
+      class << self
+        extend T::Sig
+
+        private
+
+        sig { params(alg: T.untyped, enc: T.untyped).void }
+        def validate_algorithms!(alg, enc)
+          raise InvalidAlgorithm, "Unsupported alg: #{alg}" unless SUPPORTED_ALGS.include?(alg)
+          raise InvalidAlgorithm, "Unsupported enc: #{enc}" unless SUPPORTED_ENCS.include?(enc)
+        end
+
+        # Performs ECDH key agreement and returns the raw shared secret.
+        sig { params(local_key: OpenSSL::PKey::EC, remote_public_key: OpenSSL::PKey::EC).returns(String) }
+        def derive_shared_secret(local_key, remote_public_key)
+          local_key.dh_compute_key(remote_public_key.public_key)
+        end
+
+        # NIST Concat KDF (single-pass, SHA-256) per RFC 7518 Section 4.6.2
+        sig { params(shared_secret: String, algorithm: String, key_length: Integer, apu: T.nilable(String), apv: T.nilable(String)).returns(String) }
+        def concat_kdf(shared_secret, algorithm, key_length, apu: nil, apv: nil)
+          algorithm_id = [algorithm.bytesize].pack("N") + algorithm
+          party_u_info = apu ? [apu.bytesize].pack("N") + apu : [0].pack("N")
+          party_v_info = apv ? [apv.bytesize].pack("N") + apv : [0].pack("N")
+          supp_pub_info = [key_length * 8].pack("N")
+
+          other_info = algorithm_id + party_u_info + party_v_info + supp_pub_info
+
+          # Single round (SHA-256 output is 32 bytes, enough for up to 256-bit keys)
+          round_input = [1].pack("N") + shared_secret + other_info
+          digest = OpenSSL::Digest::SHA256.digest(round_input)
+          digest[0, key_length]
+        end
+
+        # Converts an OpenSSL EC key to a JWK hash (public components only).
+        sig { params(ec_key: OpenSSL::PKey::EC).returns(T::Hash[String, String]) }
+        def ec_public_key_to_jwk(ec_key)
+          # Get the public key point
+          point = ec_key.public_key
+          group = ec_key.group
+
+          # Determine curve name for JWK
+          crv = case group.curve_name
+          when "prime256v1" then "P-256"
+          when "secp384r1" then "P-384"
+          when "secp521r1" then "P-521"
+          else raise InvalidAlgorithm, "Unsupported curve: #{group.curve_name}"
+          end
+
+          # Get uncompressed point bytes (0x04 || x || y)
+          bn = point.to_bn(:uncompressed)
+          uncompressed = bn.to_s(2)
+
+          # Skip the 0x04 prefix byte
+          coord_length = (uncompressed.bytesize - 1) / 2
+          x = uncompressed[1, coord_length]
+          y = uncompressed[1 + coord_length, coord_length]
+
+          {
+            "kty" => "EC",
+            "crv" => crv,
+            "x" => Base64.urlsafe_encode64(x, padding: false),
+            "y" => Base64.urlsafe_encode64(y, padding: false)
+          }
+        end
+
+        # Reconstructs an EC public key from a JWK hash.
+        sig { params(jwk: T::Hash[String, T.untyped]).returns(OpenSSL::PKey::EC) }
+        def jwk_to_ec_public_key(jwk)
+          crv = jwk["crv"]
+          curve_name = case crv
+          when "P-256" then "prime256v1"
+          when "P-384" then "secp384r1"
+          when "P-521" then "secp521r1"
+          else raise InvalidAlgorithm, "Unsupported curve: #{crv}"
+          end
+
+          x = Base64.urlsafe_decode64(jwk["x"])
+          y = Base64.urlsafe_decode64(jwk["y"])
+
+          group = OpenSSL::PKey::EC::Group.new(curve_name)
+          # Build uncompressed point: 0x04 || x || y
+          point_hex = "04" + x.unpack1("H*") + y.unpack1("H*")
+          point = OpenSSL::PKey::EC::Point.new(group, OpenSSL::BN.new(point_hex, 16))
+
+          # Build a public-only EC key
+          inner = [OpenSSL::ASN1::ObjectId.new("id-ecPublicKey"),
+                    OpenSSL::ASN1::ObjectId.new(curve_name)]
+          outer = [OpenSSL::ASN1::Sequence.new(inner),
+                    OpenSSL::ASN1::BitString.new(point.to_octet_string(:uncompressed))]
+          asn1 = OpenSSL::ASN1::Sequence.new(outer)
+          OpenSSL::PKey::EC.new(asn1.to_der)
+        end
+
+        sig { params(cek: String, enc: String, plaintext: String, aad: String).returns(T::Array[String]) }
+        def encrypt_content(cek, enc, plaintext, aad)
+          case enc
+          when "A128GCM", "A256GCM"
+            encrypt_gcm(cek, plaintext, aad, enc)
+          when "A128CBC-HS256", "A256CBC-HS512"
+            encrypt_cbc(cek, plaintext, aad, enc)
+          else
+            raise InvalidAlgorithm, "Unsupported enc: #{enc}"
+          end
+        end
+
+        sig { params(cek: String, enc: String, ciphertext: String, iv: String, auth_tag: String, aad: String).returns(String) }
+        def decrypt_content(cek, enc, ciphertext, iv, auth_tag, aad)
+          case enc
+          when "A128GCM", "A256GCM"
+            decrypt_gcm(cek, ciphertext, iv, auth_tag, aad, enc)
+          when "A128CBC-HS256", "A256CBC-HS512"
+            decrypt_cbc(cek, ciphertext, iv, auth_tag, aad, enc)
+          else
+            raise InvalidAlgorithm, "Unsupported enc: #{enc}"
+          end
+        end
+
+        sig { params(enc: String).returns(String) }
+        def gcm_cipher_name(enc)
+          enc == "A128GCM" ? "aes-128-gcm" : "aes-256-gcm"
+        end
+
+        sig { params(enc: String).returns(String) }
+        def cbc_cipher_name(enc)
+          enc == "A128CBC-HS256" ? "aes-128-cbc" : "aes-256-cbc"
+        end
+
+        sig { params(enc: String).returns(String) }
+        def cbc_hmac_digest(enc)
+          enc == "A128CBC-HS256" ? "SHA256" : "SHA512"
+        end
+
+        sig { params(cek: String, plaintext: String, aad: String, enc: String).returns(T::Array[String]) }
+        def encrypt_gcm(cek, plaintext, aad, enc)
+          cipher = OpenSSL::Cipher.new(gcm_cipher_name(enc))
+          cipher.encrypt
+          cipher.key = cek
+          iv = cipher.random_iv
+          cipher.auth_data = aad
+          ciphertext = cipher.update(plaintext) + cipher.final
+          auth_tag = cipher.auth_tag
+          [iv, ciphertext, auth_tag]
+        end
+
+        sig { params(cek: String, ciphertext: String, iv: String, auth_tag: String, aad: String, enc: String).returns(String) }
+        def decrypt_gcm(cek, ciphertext, iv, auth_tag, aad, enc)
+          raise DecryptionFailed, "Invalid authentication tag" if auth_tag.bytesize < 16
+
+          cipher = OpenSSL::Cipher.new(gcm_cipher_name(enc))
+          cipher.decrypt
+          cipher.key = cek
+          cipher.iv = iv
+          cipher.auth_tag = auth_tag
+          cipher.auth_data = aad
+          cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError
+          raise DecryptionFailed, "Content decryption failed"
+        end
+
+        sig { params(cek: String, plaintext: String, aad: String, enc: String).returns(T::Array[String]) }
+        def encrypt_cbc(cek, plaintext, aad, enc)
+          mac_key_len = cek.bytesize / 2
+          mac_key = cek[0, mac_key_len]
+          enc_key = cek[mac_key_len, mac_key_len]
+
+          cipher = OpenSSL::Cipher.new(cbc_cipher_name(enc))
+          cipher.encrypt
+          cipher.key = T.must(enc_key)
+          iv = cipher.random_iv
+          ciphertext = cipher.update(plaintext) + cipher.final
+
+          # Compute authentication tag (HMAC over AAD || IV || ciphertext || AL)
+          al = [aad.bytesize * 8].pack("Q>")
+          hmac_input = aad + iv + ciphertext + al
+          hmac = OpenSSL::HMAC.digest(cbc_hmac_digest(enc), T.must(mac_key), hmac_input)
+          tag_len = mac_key_len  # half of HMAC output
+          auth_tag = hmac[0, tag_len]
+
+          [iv, ciphertext, auth_tag]
+        end
+
+        sig { params(cek: String, ciphertext: String, iv: String, auth_tag: String, aad: String, enc: String).returns(String) }
+        def decrypt_cbc(cek, ciphertext, iv, auth_tag, aad, enc)
+          mac_key_len = cek.bytesize / 2
+          mac_key = cek[0, mac_key_len]
+          enc_key = cek[mac_key_len, mac_key_len]
+
+          # Verify authentication tag
+          al = [aad.bytesize * 8].pack("Q>")
+          hmac_input = aad + iv + ciphertext + al
+          hmac = OpenSSL::HMAC.digest(cbc_hmac_digest(enc), T.must(mac_key), hmac_input)
+          tag_len = mac_key_len
+          expected_tag = hmac[0, tag_len]
+
+          unless OpenSSL.fixed_length_secure_compare(auth_tag, expected_tag)
+            raise DecryptionFailed, "Authentication tag verification failed"
+          end
+
+          cipher = OpenSSL::Cipher.new(cbc_cipher_name(enc))
+          cipher.decrypt
+          cipher.key = T.must(enc_key)
+          cipher.iv = iv
+          cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError
+          raise DecryptionFailed, "Content decryption failed"
+        end
+      end
+    end
+  end
+end

data/lib/standard_singpass/myinfo/error.rb

@@ -0,0 +1,14 @@
+# typed: strict
+
+module StandardSingpass
+  module Myinfo
+    class Error < StandardError; end
+    class AuthenticationError < Error; end
+    class ApiError < Error; end
+    class PARError < Error; end
+    class DecryptionError < Error; end
+    class SignatureError < Error; end
+    class RateLimitError < Error; end
+    class ConfigurationError < Error; end
+  end
+end

data/lib/standard_singpass/myinfo/jwks_generator.rb

@@ -0,0 +1,116 @@
+# typed: strict
+
+module StandardSingpass
+  module Myinfo
+    # Generates and validates the private JWKS document that gets pasted into
+    # the host application's `MYINFO_PRIVATE_JWKS` env var (or equivalent).
+    # Public-facing entrypoint is the `standard_singpass:myinfo:generate_jwks`
+    # rake task; this module holds the logic so it's testable without going
+    # through Rake.
+    #
+    # The validator mirrors what `Configuration#private_jwks_json=` requires —
+    # particularly the "must have private scalar `d`" check that traps the
+    # public/private key mix-up.
+    module JwksGenerator
+      extend T::Sig
+
+      SIG_ALG = T.let("ES256", String)
+      ENC_ALG = T.let("ECDH-ES+A256KW", String)
+      EC_CURVE = T.let("P-256", String)
+      EC_OPENSSL_NAME = T.let("prime256v1", String)
+
+      sig { params(sig_kid: String, enc_kid: String).returns(T::Hash[Symbol, T.untyped]) }
+      def self.generate(sig_kid:, enc_kid:)
+        sig_jwk = build_jwk(OpenSSL::PKey::EC.generate(EC_OPENSSL_NAME), kid: sig_kid, use: "sig", alg: SIG_ALG)
+        enc_jwk = build_jwk(OpenSSL::PKey::EC.generate(EC_OPENSSL_NAME), kid: enc_kid, use: "enc", alg: ENC_ALG)
+
+        jwks = { keys: [sig_jwk, enc_jwk] }
+
+        # Defensive — the trap this module is built to prevent. If we ever
+        # emit a public-only JWK from a generation path, refuse early.
+        issues = validate(jwks)
+        raise "Internal: generated JWKS failed self-validation:\n#{issues.join("\n")}" if issues.any?
+
+        jwks
+      end
+
+      # Returns an array of issue strings; empty array means valid.
+      # Accepts either symbol- or string-keyed hashes (JSON.parse output is
+      # string-keyed; in-memory values from .generate are symbol-keyed).
+      sig { params(jwks: T.untyped).returns(T::Array[String]) }
+      def self.validate(jwks)
+        return ["root is not a JSON object (got #{jwks.class})"] unless jwks.is_a?(Hash)
+
+        keys = jwks["keys"] || jwks[:keys]
+        return ["missing 'keys' array"] unless keys.is_a?(Array)
+
+        issues = []
+
+        sig_keys = keys.select { |k| k.is_a?(Hash) && key_field(k, :use) == "sig" }
+        enc_keys = keys.select { |k| k.is_a?(Hash) && key_field(k, :use) == "enc" }
+
+        issues << "expected exactly one sig key (use=\"sig\"), got #{sig_keys.size}" unless sig_keys.size == 1
+        issues << "expected at least one enc key (use=\"enc\"), got 0" if enc_keys.empty?
+
+        # RFC 7517 §4.5: kid values within a JWKS should be distinct so a
+        # consumer can pick keys unambiguously. The runtime config loader
+        # selects by `use`, so a duplicate kid wouldn't blow up at boot —
+        # but Singpass may behave differently, and a duplicate is almost
+        # always an operator copy/paste mistake.
+        hashlike_keys = keys.grep(Hash)
+        kid_counts = hashlike_keys.group_by { |k| key_field(k, :kid) }.transform_values(&:size)
+        kid_counts.each do |kid, count|
+          next if count <= 1
+          issues << "duplicate kid #{kid.inspect} appears #{count} times — kids must be unique within a JWKS (RFC 7517 §4.5)"
+        end
+
+        keys.each_with_index do |k, i|
+          unless k.is_a?(Hash)
+            issues << "keys[#{i}] is not an object (got #{k.class})"
+            next
+          end
+          kid = key_field(k, :kid)
+          use = key_field(k, :use)
+          label = "keys[#{i}] kid=#{kid.inspect} use=#{use.inspect}"
+
+          d = key_field(k, :d)
+          kty = key_field(k, :kty)
+          crv = key_field(k, :crv)
+          alg = key_field(k, :alg)
+
+          # Public-only-key trap. Without `d` the JWK is public-only and
+          # cannot sign or decrypt — every Singpass call fails at runtime.
+          # `.blank?` matches the runtime config loader's check so the
+          # validator and the loader accept the same set of inputs.
+          issues << "#{label}: missing 'd' (public-only — re-export with include_private: true)" if d.blank?
+          issues << "#{label}: kty=#{kty.inspect} expected \"EC\"" unless kty == "EC"
+          issues << "#{label}: crv=#{crv.inspect} expected \"P-256\" (FAPI 2.0 requires EC P-256)" unless crv == EC_CURVE
+
+          case use
+          when "sig"
+            issues << "#{label}: alg=#{alg.inspect} expected \"#{SIG_ALG}\"" unless alg == SIG_ALG
+          when "enc"
+            issues << "#{label}: alg=#{alg.inspect} expected \"#{ENC_ALG}\"" unless alg == ENC_ALG
+          else
+            issues << "#{label}: use=#{use.inspect} expected \"sig\" or \"enc\""
+          end
+        end
+
+        issues
+      end
+
+      sig { params(key: OpenSSL::PKey::EC, kid: String, use: String, alg: String).returns(T::Hash[Symbol, T.untyped]) }
+      private_class_method def self.build_jwk(key, kid:, use:, alg:)
+        jwk = JWT::JWK.new(key, kid:).export(include_private: true)
+        jwk[:use] = use
+        jwk[:alg] = alg
+        jwk
+      end
+
+      sig { params(hash: T::Hash[T.untyped, T.untyped], field: Symbol).returns(T.untyped) }
+      private_class_method def self.key_field(hash, field)
+        hash[field] || hash[field.to_s]
+      end
+    end
+  end
+end