standard_singpass 0.3.1 → 0.4.0

data/lib/standard_singpass/myinfo/configuration.rb

@@ -10,10 +10,13 @@
 #   c.client_id          - App ID from Singpass Developer Portal
 #   c.redirect_url       - OAuth callback URL (e.g. https://example.com/singpass/callback)
 #   c.private_jwks_json  - Full JWKS JSON string with private signing + encryption keys
-#                          (keys are identified by "use": "sig" and "use": "enc")
+#                          (keys are identified by "use": "sig" and "use": "enc").
+#                          Parsed lazily, so it can be assigned in any order.
 #
 # Optional attributes:
-#   c.scope                  - Space-separated scopes (defaults to DEFAULT_SCOPE)
+#   c.scope                  - Space-separated scopes. Defaults to the minimal
+#                              DEFAULT_SCOPE ("openid uinfin name"); every
+#                              real host should set its own approved list.
 #   c.minimum_acr            - Minimum Authentication Context Class Reference URN
 #                              (e.g. urn:singpass:authentication:loa:3) checked
 #                              client-side against the id_token `acr` claim.
@@ -33,79 +36,25 @@
 module StandardSingpass
   module Myinfo
     class Configuration
-      # Default MyInfo scope — keep aligned with the Singpass developer-portal
-      # approval list. Entries on separate lines so diffs against the portal's
-      # ordered dump are reviewable line-by-line. Joined into a single
-      # space-delimited string before sending to PAR.
-      DEFAULT_SCOPE = %w[
-        openid
-        aliasname
-        cpfbalances.oa
-        cpfcontributions
-        cpfemployers
-        cpfhousingwithdrawal
-        dob
-        email
-        employment
-        employmentsector
-        hanyupinyinaliasname
-        hanyupinyinname
-        hdbownership.address
-        hdbownership.balanceloanrepayment
-        hdbownership.hdbtype
-        hdbownership.loangranted
-        hdbownership.monthlyloaninstalment
-        hdbownership.noofowners
-        hdbownership.outstandinginstalment
-        hdbownership.outstandingloanbalance
-        hdbtype
-        housingtype
-        marital
-        marriedname
-        mobileno
-        name
-        nationality
-        noa
-        noa-basic
-        noahistory
-        noahistory-basic
-        occupation
-        ownerprivate
-        passexpirydate
-        passstatus
-        passtype
-        race
-        regadd
-        residentialstatus
-        sex
-        uinfin
-        vehicles.effectiveownership
-      ].join(" ").freeze
-
-      # The categories and their lender-underwriting purpose (PDPA §18,
-      # Purpose Limitation):
+      # Default MyInfo scope: the minimal identity set (`openid` plus the
+      # NRIC/FIN and name). Deliberately tiny.
       #
-      #   Identity        — uinfin, name, alias names, dob, sex, race,
-      #                     nationality, residentialstatus → KYC, contracts
-      #   Pass (FIN-only) — passtype, passstatus, passexpirydate,
-      #                     employmentsector → tenure-vs-pass-expiry, eligibility
-      #   Address         — regadd, hdbtype, housingtype → KYC + income proxy
-      #   Contact         — mobileno, email → OTP, mailers
-      #   Family          — marital → soft underwriting signal
-      #   Income          — noa, noa-basic, noahistory, noahistory-basic,
-      #                     cpfcontributions → MAS TDSR input
-      #   Employment      — employment, occupation, cpfemployers
-      #                     → continuity + employer stability
-      #   Assets          — cpfbalances.oa (only OA — MA/SA/RA are ring-fenced
-      #                     and not lender-relevant), ownerprivate
-      #   Liabilities     — cpfhousingwithdrawal, hdbownership.* (8 sub-fields)
-      #                     → TDSR housing component
-      #   Vehicle         — vehicles.effectiveownership (asset/liability hint;
-      #                     full vehicle details deliberately not requested)
+      # Which person attributes to request is a business decision (PDPA §18,
+      # Purpose Limitation) that must match the host's Singpass
+      # developer-portal approval list, so it belongs to the host, not this
+      # gem. Until 0.4.0 this constant was one consuming app's 42-entry
+      # underwriting scope — including `noa`, `noa-basic` and
+      # `noahistory-basic`, which Singpass review later flagged as redundant
+      # collection — and any host that relied on the default silently
+      # requested all of it.
       #
-      # `cpfbalances.oa`, `hdbownership.*`, and `vehicles.effectiveownership`
-      # use FAPI 2.0 sub-attribute scope notation — sharper data minimisation
-      # than parent-keyword grants.
+      # A minimal default rather than a boot-time "scope is required" error:
+      # `openid uinfin name` is a subset of every MyInfo approval, so a host
+      # that forgets to set `scope` gets a working flow that collects the
+      # least data possible, instead of either over-collecting (the old
+      # default) or failing to boot in development and test. Hosts set
+      # `c.scope` explicitly; the install generator does.
+      DEFAULT_SCOPE = "openid uinfin name"
 
       PRODUCTION_ENDPOINTS = {
         authorize_url:     "https://id.singpass.gov.sg/fapi/auth",
@@ -130,7 +79,6 @@ module StandardSingpass
       attr_accessor :authorize_url, :par_url, :token_url, :userinfo_url,
                     :jwks_url, :userinfo_jwks_url, :issuer,
                     :client_id, :redirect_url, :scope,
-                    :signing_key, :signing_kid, :encryption_keys,
                     :minimum_acr, :network_wrapper, :mock_mode, :personas_path
 
       # Optional callable deciding whether the current deploy is real
@@ -148,6 +96,10 @@ module StandardSingpass
         self.environment = :staging
         @scope = DEFAULT_SCOPE
         @encryption_keys = []
+        @signing_key = nil
+        @signing_kid = nil
+        @private_jwks_json = nil
+        @private_jwks_pending = false
         @network_wrapper = ->(&block) { block.call }
         @mock_mode = false
         @production_env_detector = nil
@@ -167,18 +119,77 @@ module StandardSingpass
 
       attr_reader :environment
 
-      # Accepts the raw JWKS JSON string and populates signing_key, signing_kid,
-      # and encryption_keys. Logs and reports issues via Rails.logger / Rails.error
-      # rather than raising — a malformed JWKS silently degrades the Singpass
-      # widget at runtime, but the host should boot regardless.
+      # Stores the raw private JWKS JSON string. Parsing into signing_key,
+      # signing_kid, and encryption_keys is deferred until one of those is
+      # first read (or `resolve_private_jwks!` is called — the engine does so
+      # from `after_initialize`, alongside MockModeGuard, so problems surface
+      # at boot). Until 0.4.0 this setter parsed eagerly, so its warnings
+      # depended on `mock_mode` having been assigned *before* it ("set
+      # last"); deferring makes the configure block order-independent.
+      #
+      # Issues are logged and reported via Rails.logger / Rails.error rather
+      # than raised — a malformed JWKS silently degrades the Singpass widget
+      # at runtime, but the host should boot regardless.
       def private_jwks_json=(jwks_json)
+        @private_jwks_json = jwks_json
+        @private_jwks_pending = true
+      end
+
+      attr_reader :private_jwks_json
+
+      def signing_key
+        resolve_private_jwks!
+        @signing_key
+      end
+
+      def signing_kid
+        resolve_private_jwks!
+        @signing_kid
+      end
+
+      def encryption_keys
+        resolve_private_jwks!
+        @encryption_keys
+      end
+
+      # Direct assignment still works (and wins over an earlier
+      # `private_jwks_json=`): any pending JWKS is resolved first so it can't
+      # later overwrite the explicit value.
+      def signing_key=(value)
+        resolve_private_jwks!
+        @signing_key = value
+      end
+
+      def signing_kid=(value)
+        resolve_private_jwks!
+        @signing_kid = value
+      end
+
+      def encryption_keys=(value)
+        resolve_private_jwks!
+        @encryption_keys = value
+      end
+
+      # Parses the pending private JWKS, if any. Idempotent: a no-op until
+      # `private_jwks_json=` is assigned again. Returns self.
+      def resolve_private_jwks!
+        return self unless @private_jwks_pending
+
+        @private_jwks_pending = false
+        parse_private_jwks(@private_jwks_json)
+        self
+      end
+
+      private
+
+      def parse_private_jwks(jwks_json)
         @encryption_keys = []
         @signing_key = nil
         @signing_kid = nil
 
         if jwks_json.nil? || jwks_json.to_s.strip.empty?
-          return if mock_mode || (defined?(Rails) && Rails.env.test?)
-          Rails.logger.warn("StandardSingpass::Myinfo: private_jwks_json is not set — Singpass flow will fail at first request")
+          return if quiet?
+          log(:warn, "private_jwks_json is not set — Singpass flow will fail at first request")
           return
         end
 
@@ -187,7 +198,7 @@ module StandardSingpass
         keys = jwks["keys"] || []
 
         sig_jwks = keys.select { |k| k.is_a?(Hash) && k["use"] == "sig" }
-        Rails.logger.warn("StandardSingpass::Myinfo: multiple sig keys in private_jwks_json — using first") if sig_jwks.size > 1
+        log(:warn, "multiple sig keys in private_jwks_json — using first") if sig_jwks.size > 1
         sig_jwk = sig_jwks.first
         if sig_jwk
           @signing_kid = sig_jwk["kid"]
@@ -196,8 +207,8 @@ module StandardSingpass
           # confusing in console triage (which is the scenario this method is
           # trying to help with).
           @signing_kid = nil unless @signing_key
-        elsif !mock_mode && !(defined?(Rails) && Rails.env.test?)
-          Rails.logger.error("StandardSingpass::Myinfo: private_jwks_json contains no key with \"use\":\"sig\"")
+        elsif !quiet?
+          log(:error, "private_jwks_json contains no key with \"use\":\"sig\"")
         end
 
         enc_jwks = keys.select { |k| k.is_a?(Hash) && k["use"] == "enc" }
@@ -210,11 +221,11 @@ module StandardSingpass
         # forgot to include enc keys) vs all-rejected (every enc key was
         # public-only or otherwise unloadable). The latter is the trap the
         # rest of this method is built to catch.
-        if @encryption_keys.empty? && !mock_mode && !(defined?(Rails) && Rails.env.test?)
+        if @encryption_keys.empty? && !quiet?
           if enc_jwks.empty?
-            Rails.logger.error("StandardSingpass::Myinfo: private_jwks_json contains no key with \"use\":\"enc\"")
+            log(:error, "private_jwks_json contains no key with \"use\":\"enc\"")
           else
-            Rails.logger.error("StandardSingpass::Myinfo: private_jwks_json has \"use\":\"enc\" keys but none are usable (all public-only or invalid)")
+            log(:error, "private_jwks_json has \"use\":\"enc\" keys but none are usable (all public-only or invalid)")
           end
         end
       rescue JSON::ParserError, TypeError => e
@@ -224,12 +235,31 @@ module StandardSingpass
         # Reported because a malformed private JWKS silently degrades the
         # Singpass widget — the request that finally fails will report, but by
         # then customers have hit the broken page.
-        Rails.logger.error("StandardSingpass::Myinfo: failed to parse private_jwks_json: #{e.class}: #{e.message}")
-        Rails.error.report(e, handled: true, context: { component: "StandardSingpass::Myinfo::Configuration", reason: "parse_private_jwks" }) if defined?(Rails.error)
+        log(:error, "failed to parse private_jwks_json: #{e.class}: #{e.message}")
+        report(e, reason: "parse_private_jwks")
         @encryption_keys = []
       end
 
-      private
+      # Missing-key warnings are noise in mock mode and in the test env.
+      # Read at parse time — i.e. after the whole configure block has run —
+      # so the order of assignments inside the block no longer matters.
+      def quiet?
+        mock_mode || (defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.test?)
+      end
+
+      # Rails.logger / Rails.error are optional: the gem can be loaded (and a
+      # Configuration built) outside a booted Rails app — tooling, plain Ruby
+      # scripts, or before the logger is assigned.
+      def log(level, message)
+        return unless defined?(::Rails) && ::Rails.respond_to?(:logger)
+        ::Rails.logger&.public_send(level, "StandardSingpass::Myinfo: #{message}")
+      end
+
+      def report(error, reason:, **context)
+        return unless defined?(::Rails) && ::Rails.respond_to?(:error)
+        ::Rails.error.report(error, handled: true, context: { component: "StandardSingpass::Myinfo::Configuration", reason:, **context })
+      end
+
 
       # Converts a JWK to a *private* PEM. Refuses public-only JWKs — the
       # private scalar (`d` for EC) must be present, otherwise signing /
@@ -239,13 +269,13 @@ module StandardSingpass
       def jwk_to_private_pem(jwk_hash, role:)
         kid = jwk_hash["kid"]
         if jwk_hash["d"].blank?
-          Rails.logger.error("StandardSingpass::Myinfo: #{role} JWK #{kid.inspect} is public-only (missing \"d\") — re-export with include_private: true")
+          log(:error, "#{role} JWK #{kid.inspect} is public-only (missing \"d\") — re-export with include_private: true")
           return nil
         end
         JWT::JWK.new(jwk_hash).keypair.to_pem
       rescue => e
-        Rails.logger.error("StandardSingpass::Myinfo: failed to convert #{role} JWK #{kid.inspect}: #{e.class} — #{e.message}")
-        Rails.error.report(e, handled: true, context: { component: "StandardSingpass::Myinfo::Configuration", reason: "jwk_to_private_pem", role:, kid: }) if defined?(Rails.error)
+        log(:error, "failed to convert #{role} JWK #{kid.inspect}: #{e.class} — #{e.message}")
+        report(e, reason: "jwk_to_private_pem", role:, kid:)
         nil
       end
     end

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