standard_singpass 0.3.0 → 0.4.0

data/lib/standard_singpass/myinfo/ecdh_jwe.rb

@@ -2,7 +2,9 @@
 
 module StandardSingpass
   module Myinfo
-    # Native ECDH-ES+A256KW JWE implementation for decryption.
+    # Native ECDH-ES+A256KW JWE implementation for decryption. (The matching
+    # encryption side, needed only to build test fixtures, lives in
+    # `StandardSingpass::Testing::EcdhJwe`.)
     #
     # The `jwt` gem does not support ECDH-ES key agreement algorithms; this
     # service implements the subset needed for MyInfo (FAPI 2.0):
@@ -19,12 +21,15 @@ module StandardSingpass
       class DecryptionFailed < StandardError; end
       class InvalidAlgorithm < StandardError; end
 
-      SUPPORTED_ALGS = T.let(%w[ECDH-ES+A128KW ECDH-ES+A256KW].freeze, T::Array[String])
+      # Only ECDH-ES+A256KW: it is the one alg we publish on our encryption
+      # JWKs (see Myinfo.public_jwks) and the one FAPI 2.0 / Singpass uses.
+      # ECDH-ES+A128KW was accepted until 0.4.0; nothing legitimate sends it
+      # to us, so accepting it was pure attack surface.
+      SUPPORTED_ALGS = T.let(%w[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])
 
@@ -36,7 +41,11 @@ module StandardSingpass
         "A256GCM" => 32
       }.freeze, T::Hash[String, Integer])
 
-      # Encrypts a payload and returns a compact-serialized JWE string.
+      # Deprecated (0.4.0): encryption is only ever needed to build fixtures
+      # in tests — Singpass encrypts, we decrypt. It lives in
+      # `StandardSingpass::Testing::EcdhJwe` now (`require
+      # "standard_singpass/testing"`); this forwarder will be removed in a
+      # future minor release.
       sig do
         params(
           payload: String,
@@ -49,45 +58,12 @@ module StandardSingpass
         ).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(".")
+        StandardSingpass.deprecator.warn(
+          "StandardSingpass::Myinfo::EcdhJwe.encrypt is deprecated and will be removed; " \
+          "require \"standard_singpass/testing\" and use StandardSingpass::Testing::EcdhJwe.encrypt instead."
+        )
+        require "standard_singpass/testing"
+        StandardSingpass::Testing::EcdhJwe.encrypt(payload, public_key:, alg:, enc:, kid:, apu:, apv:)
       end
 
       # Decrypts a compact-serialized JWE string.
@@ -171,38 +147,6 @@ module StandardSingpass
           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)
@@ -231,18 +175,6 @@ module StandardSingpass
           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
@@ -270,18 +202,6 @@ module StandardSingpass
           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
@@ -297,28 +217,6 @@ module StandardSingpass
           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

data/lib/standard_singpass/myinfo/error.rb

@@ -1,8 +1,11 @@
 # typed: strict
 
+require "standard_singpass/error"
+
 module StandardSingpass
   module Myinfo
-    # Base class for every error the gem raises.
+    # Base class for every MyInfo error the gem raises. Descends from the
+    # gem-wide `StandardSingpass::Error`.
     #
     # Every error carries the two facts a host needs to decide what to tell
     # the user, so neither has to be recovered by reading the message:
@@ -26,7 +29,7 @@ module StandardSingpass
     # The alternative — matching "unreachable" or an HTTP code in `message` —
     # is a trap: the message is not a stable interface. `FailureClassifier`
     # consumes these so hosts never have to.
-    class Error < StandardError
+    class Error < StandardSingpass::Error
       extend T::Sig
 
       sig { returns(T.nilable(Integer)) }

data/lib/standard_singpass/myinfo/security.rb

@@ -5,15 +5,20 @@ module StandardSingpass
     class Security
       extend T::Sig
 
-      # Both inherit the gem's base Error so they carry `status` and
-      # `transport?`. That matters for ValidationError in particular: fetching
-      # the JWKS is a network call to a Singpass host, so "the JWKS endpoint
-      # is down" and "this signature is genuinely bad" both surface here and
-      # must stay distinguishable — the first is an outage, the second is a
-      # key/cert problem. FailureClassifier reads those attributes; without
-      # them a JWKS-host outage would be reported as our own bug.
-      class DecryptionError < Error; end
-      class ValidationError < Error; end
+      # Deprecated aliases (0.4.0). Security used to raise its own
+      # DecryptionError / ValidationError, which the client then translated
+      # into the public Myinfo errors. It now raises the public errors
+      # directly: JWE failures raise `Myinfo::DecryptionError`, JWS / JWKS
+      # failures raise `Myinfo::SignatureError` (carrying the JWKS response's
+      # `status`, or `transport?` when the JWKS host was unreachable, so an
+      # outage stays distinguishable from a genuinely bad signature).
+      #
+      # The old names still resolve — to the same classes, so an existing
+      # `rescue Security::ValidationError` keeps catching — and will be
+      # removed in a future minor release.
+      DecryptionError = Myinfo::DecryptionError
+      ValidationError = Myinfo::SignatureError
+      deprecate_constant :DecryptionError, :ValidationError
 
       JWKS_CACHE_TTL = T.let(1.hour, ActiveSupport::Duration)
 
@@ -94,21 +99,25 @@ module StandardSingpass
       sig { params(jwe_string: String, private_keys: T::Array[T::Hash[Symbol, T.untyped]]).returns(String) }
       def self.decrypt_jwe(jwe_string, private_keys:)
         header_kid = extract_jwe_kid(jwe_string)
-        raise DecryptionError, "JWE header missing kid field" unless header_kid
+        raise Myinfo::DecryptionError, "JWE header missing kid field" unless header_kid
 
         matching_key = private_keys.find { |k| k[:kid] == header_kid }
-        raise DecryptionError, "No matching decryption key found" unless matching_key
+        raise Myinfo::DecryptionError, "No matching decryption key found" unless matching_key
 
         alg = extract_jwe_alg(jwe_string)
         unless EcdhJwe::SUPPORTED_ALGS.include?(alg)
-          raise DecryptionError, "Unsupported JWE alg #{alg.inspect}; FAPI 2.0 requires #{EcdhJwe::SUPPORTED_ALGS.join('/')}"
+          raise Myinfo::DecryptionError, "Unsupported JWE alg #{alg.inspect}; FAPI 2.0 requires #{EcdhJwe::SUPPORTED_ALGS.join('/')}"
         end
 
         EcdhJwe.decrypt(jwe_string, private_key: resolve_key(matching_key[:key]))
       rescue EcdhJwe::DecryptionFailed => e
-        raise DecryptionError, "JWE decryption failed: #{e.message}"
+        raise Myinfo::DecryptionError, "JWE decryption failed: #{e.message}"
+      rescue EcdhJwe::InvalidAlgorithm => e
+        # e.g. an unsupported `enc` — previously escaped as a bare
+        # StandardError subclass, bypassing every `rescue Myinfo::Error`.
+        raise Myinfo::DecryptionError, "Unsupported JWE: #{e.message}"
       rescue ArgumentError => e
-        raise DecryptionError, "Malformed JWE: #{e.message}"
+        raise Myinfo::DecryptionError, "Malformed JWE: #{e.message}"
       end
 
       # Validates a JWS string against keys from a JWKS endpoint.
@@ -124,10 +133,10 @@ module StandardSingpass
           begin
             decode_with_jwks(jws_string, jwks_data)
           rescue JWT::DecodeError => e
-            raise ValidationError, "JWS validation failed: #{e.message}"
+            raise Myinfo::SignatureError, "JWS validation failed: #{e.message}"
           end
         rescue JWT::DecodeError => e
-          raise ValidationError, "JWS validation failed: #{e.message}"
+          raise Myinfo::SignatureError, "JWS validation failed: #{e.message}"
         end
       end
 
@@ -164,7 +173,7 @@ module StandardSingpass
         case key
         when OpenSSL::PKey::PKey then key
         when String then OpenSSL::PKey.read(key)
-        else raise DecryptionError, "Unsupported key type: #{key.class}"
+        else raise Myinfo::DecryptionError, "Unsupported key type: #{key.class}"
         end
       end
       private_class_method :resolve_key
@@ -178,7 +187,7 @@ module StandardSingpass
         Rails.cache.fetch(cache_key, expires_in: JWKS_CACHE_TTL) do
           response = Faraday.get(url) { |req| req.options.timeout = 5; req.options.open_timeout = 3 }
           unless response.success?
-            raise ValidationError.new("Failed to fetch JWKS: HTTP #{response.status}", status: response.status)
+            raise Myinfo::SignatureError.new("Failed to fetch JWKS: HTTP #{response.status}", status: response.status)
           end
 
           JSON.parse(response.body)
@@ -186,10 +195,10 @@ module StandardSingpass
       rescue Faraday::Error => e
         # Never reached the JWKS host — the same "their side" case a transport
         # failure on any other leg represents.
-        raise ValidationError.new("Failed to fetch JWKS: #{e.message}", transport: true)
+        raise Myinfo::SignatureError.new("Failed to fetch JWKS: #{e.message}", transport: true)
       rescue JSON::ParserError => e
         # Reached it and got something unusable. Not an availability problem.
-        raise ValidationError, "Failed to fetch JWKS: #{e.message}"
+        raise Myinfo::SignatureError, "Failed to fetch JWKS: #{e.message}"
       end
       private_class_method :fetch_jwks
 

data/lib/standard_singpass/myinfo/test_personas.rb

@@ -31,9 +31,14 @@ module StandardSingpass
         @data ||= JSON.parse(fixture_path.read).freeze
       end
 
-      # Test-only — call from a spec `before(:suite)` if you want to pick up
-      # mid-run edits to the fixture file.
+      # Deprecated (0.4.0) — unused by any consumer, and will be removed in a
+      # future minor release. Personas are read once per process; restart the
+      # process (or point `personas_path` at a different file) to pick up
+      # edits.
       def self.reload!
+        StandardSingpass.deprecator.warn(
+          "StandardSingpass::Myinfo::TestPersonas.reload! is deprecated and will be removed."
+        )
         @data = nil
         data
       end

data/lib/standard_singpass/myinfo.rb

@@ -9,6 +9,7 @@ require "digest"
 require "securerandom"
 require "aes_key_wrap"
 
+require "standard_singpass/error"
 require "standard_singpass/myinfo/error"
 require "standard_singpass/myinfo/failure_classifier"
 require "standard_singpass/myinfo/configuration"
@@ -32,6 +33,7 @@ module StandardSingpass
       def configuration
         @configuration ||= Configuration.new
       end
+      alias_method :config, :configuration
 
       def reset_configuration!
         @configuration = Configuration.new
@@ -57,8 +59,7 @@ module StandardSingpass
             exported[:alg] = "ES256"
             keys << exported
           rescue OpenSSL::PKey::PKeyError => e
-            Rails.logger.error("StandardSingpass::Myinfo: failed to load signing key: #{e.message}")
-            Rails.error.report(e, handled: true, context: { component: "StandardSingpass::Myinfo", reason: "build_public_jwks_signing", kid: c.signing_kid })
+            log_and_report(e, "failed to load signing key: #{e.message}", reason: "build_public_jwks_signing", kid: c.signing_kid)
           end
         end
 
@@ -70,12 +71,17 @@ module StandardSingpass
           exported[:alg] = "ECDH-ES+A256KW"
           keys << exported
         rescue OpenSSL::PKey::PKeyError => e
-          Rails.logger.error("StandardSingpass::Myinfo: failed to load encryption key #{enc_key_config[:kid]}: #{e.message}")
-          Rails.error.report(e, handled: true, context: { component: "StandardSingpass::Myinfo", reason: "build_public_jwks_encryption", kid: enc_key_config[:kid] })
+          log_and_report(e, "failed to load encryption key #{enc_key_config[:kid]}: #{e.message}", reason: "build_public_jwks_encryption", kid: enc_key_config[:kid])
         end
 
         { keys: }
       end
+
+      def log_and_report(error, message, reason:, kid:)
+        return unless defined?(::Rails)
+        ::Rails.logger&.error("StandardSingpass::Myinfo: #{message}") if ::Rails.respond_to?(:logger)
+        ::Rails.error.report(error, handled: true, context: { component: "StandardSingpass::Myinfo", reason:, kid: }) if ::Rails.respond_to?(:error)
+      end
     end
   end
 end

data/lib/standard_singpass/testing.rb

@@ -0,0 +1,174 @@
+# typed: strict
+
+require "standard_singpass"
+
+module StandardSingpass
+  # Test-only helpers. Not loaded by `require "standard_singpass"`; require
+  # this file from a spec helper:
+  #
+  #   require "standard_singpass/testing"
+  #
+  # Nothing here is needed at runtime — Singpass encrypts, the gem decrypts.
+  module Testing
+    # ECDH-ES JWE *encryption*, the mirror of
+    # `StandardSingpass::Myinfo::EcdhJwe.decrypt`. Use it to build the
+    # encrypted id_token / userinfo payloads Singpass would return, so specs
+    # can exercise the real decrypt + verify path end to end.
+    #
+    # Accepts exactly the algorithms the decryptor does
+    # (`Myinfo::EcdhJwe::SUPPORTED_ALGS` / `SUPPORTED_ENCS`), and shares its
+    # key-agreement and KDF code, so a fixture that encrypts here decrypts
+    # there by construction.
+    class EcdhJwe
+      extend T::Sig
+
+      Impl = StandardSingpass::Myinfo::EcdhJwe
+      InvalidAlgorithm = StandardSingpass::Myinfo::EcdhJwe::InvalidAlgorithm
+
+      # 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)
+        shared(: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 = shared(:derive_shared_secret, ephemeral_key, public_key)
+
+        # Derive KEK via Concat KDF
+        kek_size = Impl::KEK_SIZES.fetch(alg)
+        kek = shared(:concat_kdf, shared_secret, alg, kek_size, apu:, apv:)
+
+        # Generate random CEK
+        cek_size = Impl::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
+
+      class << self
+        extend T::Sig
+
+        private
+
+        # The decryptor's key-agreement / KDF / validation helpers are private
+        # class methods; reuse them rather than keeping a second copy.
+        sig { params(name: Symbol, args: T.untyped, kwargs: T.untyped).returns(T.untyped) }
+        def shared(name, *args, **kwargs)
+          T.unsafe(Impl).send(name, *args, **kwargs)
+        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
+
+        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, plaintext: String, aad: String, enc: String).returns(T::Array[String]) }
+        def encrypt_gcm(cek, plaintext, aad, enc)
+          cipher = OpenSSL::Cipher.new(shared(: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, 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(shared(: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(shared(: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
+      end
+    end
+  end
+end

data/lib/standard_singpass/version.rb

@@ -1,3 +1,3 @@
 module StandardSingpass
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/standard_singpass.rb

@@ -3,4 +3,29 @@ require "standard_singpass/engine"
 require "standard_singpass/myinfo"
 
 module StandardSingpass
+  class << self
+    # Top-level entry points matching the sibling `standard_*` gems'
+    # `Gem.configure` / `Gem.config` convention. Singpass MyInfo is the only
+    # product the gem integrates today, so both delegate to
+    # `StandardSingpass::Myinfo` — `configure` goes through
+    # `Myinfo.configure` so the derived public-JWKS cache is still reset.
+    #
+    #   StandardSingpass.configure { |c| c.client_id = "..." }
+    #   StandardSingpass.config.client_id
+    def configure(&block)
+      Myinfo.configure(&block)
+      config
+    end
+
+    def config
+      Myinfo.configuration
+    end
+
+    # Deprecation warnings for the gem's own deprecated APIs. Registered
+    # with the host's `Rails.application.deprecators` by the engine, so the
+    # host's deprecation behaviour (log / raise / silence) applies.
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("0.5", "StandardSingpass")
+    end
+  end
 end