standard_singpass 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea90960df9e3752b2ec01cb271cac1c31fc8c53cfb5a757a64810d3eccecbb79
-  data.tar.gz: 3eba17716f557250f1013b303216b2450ea691080ed7bc924b8fa1749b832305
+  metadata.gz: 1ecc46cf176551f25806d49f04c64ba204801c137b46c7c5970fd6a0f97d650a
+  data.tar.gz: f5d5c709779c0082d75c4909d549ccf451daa5406900ac7e05f83e23d2e69994
 SHA512:
-  metadata.gz: e3f7ca50aaf67da5e1b82f33455662da9743a9f4cffedd533a878c409394681b7f1e1d16c197362cccce9031744509c71e6674195b1012ee7f7867595fa4cd48
-  data.tar.gz: bba22e4c5ede26f234acfea6289ee469fa646612bf198eabcaacc397e3270ce276fd5d3ea18adf9c87b549a0d88ab3b905baa15b7692de1666eaebae0ba58d8d
+  metadata.gz: a30193c9f2d2a7633f3833e1eb186df1dd09b7fa922de35ab0c7dd2d1b7acb5f8c867e91e14e86fb82cce0f814f047ee1d402911334100d1fde4ac1b353b1f05
+  data.tar.gz: 886ac97c7a2ea5125cc079ef141dcb6c303d0ac02e0c48343a6e20aff20ed889d66af105305f315e5aab5f69ed1aaaa7a781467482326162511a0690780fd812

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-30
+
+### Added
+
+- **`StandardSingpass::Myinfo::FailureClassifier.upstream_unavailable?(error)`** — one answer to the question every host asks in its rescue: is Singpass unavailable, or is our request wrong? It decides what the user is told, and the two answers are not interchangeable — an unavailable upstream clears itself within minutes ("try again shortly"), while "contact support and quote this reference" is a dead end for a transient blip. True for 502/503/504, HTTP 429, and transport failures on any leg; false for authentication, decryption, signature, and configuration errors. `FailureClassifier::UPSTREAM_UNAVAILABLE_STATUSES` is the documented status list, and `Client::RETRYABLE_USERINFO_STATUSES` is now an alias of it rather than a second copy — the statuses worth one more automatic attempt are exactly the statuses that mean "their side, transient".
+- **`StandardSingpass::Myinfo::Error#transport?`** — true when the request never reached Singpass at all (DNS, connection refused, TLS, read timeout). Set on the PAR, token, and userinfo transport-failure paths. Previously the only way to recover this was to match `"unreachable"` in the message, which is the same trap `ApiError#status` was added in 0.2.0 to close: the message is not a stable interface.
+- **`StandardSingpass::Myinfo::Noa.history(parsed)`** / **`.basic_history(parsed)`** — normalise Notice-of-Assessment data into a single list regardless of which NOA scope the Singpass app was approved for. The width is a property of the app registration, not the request: `noa` yields the latest year only, `noahistory` the last two, and `PersonDataParser` mirrors that as `:noa` (one record) or `:noa_history` (an array). The records share a shape, so every consumer ended up writing the same "array, or wrap the single record" branch. Prefers the 2-year history when both are present (it is a superset), returns `nil` when neither scope yielded data, and reads both Symbol and String keys so a hash round-tripped through JSON or a database column works unchanged.
+- **`config.production_env_detector`** — an optional callable deciding whether the current deploy is real production, for the mock-mode guard below. Takes no arguments, returns a boolean; `nil` (the default) falls back to `Rails.env.production?`. Mirrors `StandardId`'s option of the same name. Staging and preview deploys routinely run `RAILS_ENV=production`, so hosts that distinguish a physical deploy environment from `RAILS_ENV` can supply `-> { AppEnv.production? }`.
+
+### Changed
+
+- **`Security::ValidationError` and `Security::DecryptionError` now descend from `StandardSingpass::Myinfo::Error`** (previously bare `StandardError`), and JWKS-fetch failures carry the JWKS response's status — or `transport?` when the endpoint was unreachable. Verifying a signature requires fetching Singpass's JWKS, so a JWKS host that is down previously surfaced as a statusless `SignatureError` (or `AuthenticationError` on the ID-token leg), indistinguishable from a genuinely bad signature and classified as our own bug. The client now propagates both attributes across those re-raises.
+- **`status` moved from `ApiError` up to the base `Error` class, and is now set on every leg of the flow.** 0.2.0 put it on `ApiError`, which covers the token and userinfo legs — but PAR raises `PARError`, so a 502 from the PAR endpoint carried no status and any classification keyed on `ApiError` reported a Singpass-side outage as our own bug. `status` and `transport?` now both live on `Error`, are populated on the PAR and authentication paths as well, and `FailureClassifier` keys on the base class. `ApiError#status` is unchanged for existing callers; `Error#initialize` takes both keywords optionally, so `raise SomeError, "msg"` still works.
+
+- **`config.mock_mode` is now guarded at boot (`StandardSingpass::Myinfo::MockModeGuard`).** Mock mode serves fixture persona data instead of running the real FAPI 2.0 flow — right for development, CI, and staging rehearsals, catastrophic in production, where real users would submit fabricated identity data that is indistinguishable from verified MyInfo data downstream. A mis-set environment variable is all it takes, and nothing about the running app looks wrong afterwards, so it is checked at boot rather than per request. Three outcomes: a **production deploy raises `ConfigurationError` and refuses to boot**; a **production-*like* deploy** (`RAILS_ENV=production` but not production per `production_env_detector`) logs and reports via `Rails.error`, then boots; anything else is silent. Wired from the engine's `after_initialize` with no opt-out — a guard you can forget to invoke is a guard that isn't there.
+
+  **Upgrade note:** a host that sets `mock_mode` on a deploy running `RAILS_ENV=production` will now either fail to boot or emit a reported error. If that deploy is a staging or preview box, set `config.production_env_detector` so the gem can tell the difference. Hosts that leave `mock_mode` at its default (`false`) are unaffected.
+
+  Reporting goes through `Rails.error` rather than any specific error tracker, so whatever the host has subscribed (Sentry included) picks it up.
+
+### Notes
+
+- All three additions are promotions of knowledge that had accumulated in a consumer app. Each is MyInfo protocol or scope-grant knowledge that any Singpass client needs — which statuses Singpass uses for upstream-agency outages, how the two NOA scope widths differ in shape, and that the gem's own mock mode must never reach real users — rather than host policy. Host policy (what copy to show a user, where to read an environment variable from) stays in the host: the gem still never reads `ENV` itself, and `production_env_detector` is the seam for the one environment opinion it does hold.
+
 ## [0.2.0] - 2026-07-22
 
 ### Added

data/README.md

@@ -43,9 +43,52 @@ StandardSingpass::Myinfo.configure do |c|
   # Optional: path to a JSON file of test personas (for mock callback flows).
   # Defaults to the gem's bundled fixtures/myinfo-personas.json.
   # c.personas_path = Rails.root.join("e2e/fixtures/myinfo-personas.json")
+
+  # Optional: serve fixture persona data instead of running the real FAPI 2.0
+  # flow. Refused outright on a production deploy — see "Mock mode" below.
+  c.mock_mode = ENV["MYINFO_MOCK_MODE"].present?
+
+  # Optional: how the gem decides whether this deploy is real production, for
+  # the mock-mode guard. Defaults to Rails.env.production?.
+  # c.production_env_detector = -> { AppEnv.production? }
 end
 ```
 
+## Mock mode
+
+`config.mock_mode` makes the host serve fixture persona data
+(`StandardSingpass::Myinfo::TestPersonas`) instead of running the real
+Singpass flow — right for development, CI, and staging rehearsals, and
+catastrophic in production, where real users would submit fabricated identity
+data indistinguishable from verified MyInfo data downstream.
+
+**The gem enforces that.** An `after_initialize` hook runs
+`StandardSingpass::Myinfo::MockModeGuard.check!` on every boot. There is no
+opt-out — a guard you can forget to wire is a guard that isn't there.
+
+| Deploy | Mock mode on | Behaviour |
+|---|---|---|
+| Production | yes | **Raises `ConfigurationError` — the app refuses to boot.** |
+| `RAILS_ENV=production` but not production | yes | Logs an error and reports via `Rails.error`; boots. |
+| Anything else | yes | Silent. |
+| Any | no | Silent. |
+
+By default "production" means `Rails.env.production?`. Staging and preview
+deploys routinely run `RAILS_ENV=production` while being entirely legitimate
+places to enable mock mode, so hosts that distinguish a physical deploy
+environment from `RAILS_ENV` should say so:
+
+```ruby
+# Mock mode stays legal on a physically-staging box, still refused on real prod.
+c.production_env_detector = -> { AppEnv.production? }
+```
+
+`production_env_detector` takes no arguments and returns a boolean; when `nil`
+(the default) the gem falls back to `Rails.env.production?`, so existing
+consumers are unaffected. The production-like tier reports through
+`Rails.error` rather than a specific error tracker, so whatever the host has
+subscribed (Sentry included) picks it up.
+
 ## Initiating the flow
 
 ```ruby
@@ -84,6 +127,27 @@ acr    = result[:id_token_acr]
 # host-side persistence / projection layer.
 ```
 
+### Notice-of-Assessment scopes
+
+Singpass approves NOA access at one of two widths, and the width is a property
+of the *app registration*, not of the request: `noa` yields the latest year
+only, `noahistory` the last two. `PersonDataParser` mirrors that faithfully,
+emitting `:noa` (one record) or `:noa_history` (an array) — so consumers that
+just want "the NOA records" would each write the same branch.
+`StandardSingpass::Myinfo::Noa` is that branch:
+
+```ruby
+# An array of NOA records regardless of which scope was granted, or nil when
+# neither yielded data. Prefers the 2-year history when both are present.
+StandardSingpass::Myinfo::Noa.history(parsed)
+
+# Same, for the narrower `noa-basic` / `noahistory-basic` scope pair.
+StandardSingpass::Myinfo::Noa.basic_history(parsed)
+```
+
+Keys are read as both Symbols and Strings, so a hash round-tripped through
+JSON or a database column works unchanged.
+
 ## Generating and serving JWKS
 
 The host application is responsible for serving the public JWKS at
@@ -109,7 +173,29 @@ All errors descend from `StandardSingpass::Myinfo::Error`:
 - `RateLimitError` — Singpass returned HTTP 429
 - `ConfigurationError` — gem is misconfigured (e.g. invalid ACR URN)
 
-`DecryptionError` and `SignatureError` indicate a key/cert misconfiguration, not an upstream outage — exclude them from circuit-breaker tracking if you use one.
+`DecryptionError` and `SignatureError` usually indicate a key/cert misconfiguration rather than an upstream outage. **Usually, not always:** verifying a signature requires fetching Singpass's JWKS, so a JWKS host that is down surfaces as a `SignatureError` (or an `AuthenticationError` on the ID-token leg) too. Those carry the JWKS response's `status` / `transport?`, so ask `FailureClassifier` rather than deciding by class — including when choosing what to feed a circuit breaker.
+
+Every error carries two facts, on the base class rather than on any one subclass — a 502 is a 502 whichever leg of the flow returned it:
+
+- `status` — the HTTP status of the offending response (`nil` for transport failures and for errors a host raises itself)
+- `transport?` — true when the request never reached Singpass at all (DNS, connection refused, TLS, read timeout)
+
+### Classifying a failure
+
+What the host tells the user turns on one question: is Singpass unavailable, or is our request wrong? An unavailable upstream clears itself within minutes, so "try again shortly" is the honest instruction; "contact support and quote this reference" is a dead end. Get the answer from the gem rather than re-deriving it:
+
+```ruby
+if StandardSingpass::Myinfo::FailureClassifier.upstream_unavailable?(error)
+  # 502/503/504, HTTP 429, or a transport failure on any leg.
+  # Tell the user to retry shortly.
+else
+  # Our request, our keys, or our config. Surface it to support.
+end
+```
+
+This covers every leg — PAR, token exchange, userinfo, and the JWKS fetches that back signature verification. 502 is Singpass's documented signal that a MyInfo upstream agency (CPF Board, IRAS, MOM, …) is unavailable — returned both for genuine blips and throughout their [published maintenance windows](https://docs.developer.singpass.gov.sg/docs/products/singpass-myinfo/scheduled-downtimes); 503/504 are the generic equivalents. The list is `FailureClassifier::UPSTREAM_UNAVAILABLE_STATUSES`, and the client's automatic userinfo retry uses that same constant.
+
+**Never classify by matching the message text** — it is not a stable interface. That is exactly what `transport?` and `status` exist to replace.
 
 ## License
 

data/lib/generators/standard_singpass/install/templates/initializer.rb.erb

@@ -19,7 +19,9 @@
 #   MYINFO_MIN_ACR           Required Authentication Context Class Reference
 #                            URN, e.g. urn:singpass:authentication:loa:3
 #   MYINFO_MOCK_MODE         When set, suppresses missing-key warnings and
-#                            unlocks any mock-callback routes the host registers
+#                            unlocks any mock-callback routes the host
+#                            registers. The gem REFUSES TO BOOT if this is set
+#                            on a production deploy — see MockModeGuard.
 
 StandardSingpass::Myinfo.configure do |c|
   # Endpoint set. :production → live Singpass FAPI; :staging → sandbox.
@@ -41,6 +43,14 @@ StandardSingpass::Myinfo.configure do |c|
   c.minimum_acr = ENV["MYINFO_MIN_ACR"]
   c.mock_mode   = ENV["MYINFO_MOCK_MODE"].present?
 
+  # How the gem decides whether this deploy is real production, for the
+  # mock-mode boot guard. Defaults to Rails.env.production?. Staging and
+  # preview deploys routinely run RAILS_ENV=production while being legitimate
+  # places to run mock mode — if that describes you, point this at your own
+  # environment discriminator so mock mode stays legal there and still
+  # refuses to boot on real production.
+  # c.production_env_detector = -> { AppEnv.production? }
+
   # Path to a JSON file of test personas the host can drive mock callbacks
   # against. Defaults to the gem's bundled fixture set. Override here if you
   # maintain your own persona file.

data/lib/standard_singpass/engine.rb

@@ -12,6 +12,12 @@ if defined?(::Rails::Engine)
       rake_tasks do
         load File.expand_path("../tasks/standard_singpass.rake", __dir__)
       end
+
+      # Runs after the host's own initializers, so `config.mock_mode` has
+      # been set by the time it is read. Inert unless mock mode is on.
+      config.after_initialize do
+        StandardSingpass::Myinfo::MockModeGuard.check!
+      end
     end
   end
 end

data/lib/standard_singpass/myinfo/client.rb

@@ -85,7 +85,7 @@ module StandardSingpass
           handle_par_response(response)
         end
       rescue Faraday::Error => e
-        raise PARError, "PAR endpoint unreachable: #{e.class}"
+        raise PARError.new("PAR endpoint unreachable: #{e.class}", transport: true)
       end
 
       sig { params(request_uri: String).returns(String) }
@@ -121,11 +121,11 @@ module StandardSingpass
           data = JSON.parse(response.body)
           { request_uri: data.fetch("request_uri"), expires_in: data.fetch("expires_in") }
         when 401, 403
-          raise PARError, "PAR rejected (HTTP #{response.status}): #{body_excerpt(response)}"
+          raise PARError.new("PAR rejected (HTTP #{response.status}): #{body_excerpt(response)}", status: response.status)
         when 429
           raise RateLimitError, "PAR endpoint rate limit exceeded"
         else
-          raise PARError, "PAR failed (HTTP #{response.status}): #{body_excerpt(response)}"
+          raise PARError.new("PAR failed (HTTP #{response.status}): #{body_excerpt(response)}", status: response.status)
         end
       rescue KeyError
         raise PARError, "PAR response missing required fields"
@@ -164,7 +164,7 @@ module StandardSingpass
           handle_token_response(response)
         end
       rescue Faraday::Error => e
-        raise ApiError, "MyInfo token endpoint unreachable: #{e.class}"
+        raise ApiError.new("MyInfo token endpoint unreachable: #{e.class}", transport: true)
       end
 
       sig { params(access_token: String, dpop_key_pair: OpenSSL::PKey::EC).returns(T::Hash[String, T.untyped]) }
@@ -190,7 +190,7 @@ module StandardSingpass
           end
         end
       rescue Faraday::Error => e
-        raise ApiError, "MyInfo userinfo endpoint unreachable: #{e.class}"
+        raise ApiError.new("MyInfo userinfo endpoint unreachable: #{e.class}", transport: true)
       end
 
       sig { params(id_token: T.nilable(String), nonce: T.nilable(String)).returns(T::Hash[String, T.untyped]) }
@@ -222,8 +222,15 @@ module StandardSingpass
         Security.validate_jws(decrypted, jwks_url: T.must(@jwks_url))
       rescue Security::DecryptionError
         raise AuthenticationError, "ID token decryption failed"
-      rescue Security::ValidationError
-        raise AuthenticationError, "ID token signature verification failed"
+      rescue Security::ValidationError => e
+        # Carry status/transport across the re-raise: a JWKS endpoint that is
+        # down produces the same exception here as a genuinely bad signature,
+        # and only these attributes tell them apart.
+        raise AuthenticationError.new(
+          "ID token signature verification failed",
+          status: e.status,
+          transport: e.transport?
+        )
       rescue JWT::DecodeError
         raise AuthenticationError, "Failed to decode ID token"
       end
@@ -336,7 +343,7 @@ module StandardSingpass
           data = JSON.parse(response.body)
           { access_token: data.fetch("access_token"), id_token: data["id_token"] }
         when 401, 403
-          raise AuthenticationError, "Token exchange rejected (HTTP #{response.status}): #{body_excerpt(response)}"
+          raise AuthenticationError.new("Token exchange rejected (HTTP #{response.status}): #{body_excerpt(response)}", status: response.status)
         when 429
           raise RateLimitError, "Token endpoint rate limit exceeded"
         else
@@ -357,7 +364,7 @@ module StandardSingpass
         when 200
           decrypt_and_validate_person(response.body, jwks_url:)
         when 401, 403
-          raise AuthenticationError, "Person data request forbidden (HTTP #{response.status}): #{body_excerpt(response)}"
+          raise AuthenticationError.new("Person data request forbidden (HTTP #{response.status}): #{body_excerpt(response)}", status: response.status)
         when 429
           raise RateLimitError, "Person endpoint rate limit exceeded"
         else
@@ -372,7 +379,12 @@ module StandardSingpass
       # having a moment" — transient and worth one more try. 502 is Singpass's
       # documented upstream-dependency signal (`upstream_dependency_error`),
       # which they also return throughout CPF/IRAS/MOM maintenance windows.
-      RETRYABLE_USERINFO_STATUSES = T.let([502, 503, 504].freeze, T::Array[Integer])
+      #
+      # Aliased from FailureClassifier rather than restated: the statuses
+      # worth one more automatic attempt are exactly the statuses the host is
+      # told to present as "their side, try again shortly", and two copies of
+      # that list would eventually disagree.
+      RETRYABLE_USERINFO_STATUSES = FailureClassifier::UPSTREAM_UNAVAILABLE_STATUSES
 
       # Total attempts, not retries — 3 means the original plus two more.
       USERINFO_MAX_ATTEMPTS = 3
@@ -457,7 +469,8 @@ module StandardSingpass
       rescue Security::DecryptionError => e
         raise DecryptionError, e.message
       rescue Security::ValidationError => e
-        raise SignatureError, e.message
+        # As above — a JWKS-host outage must not be reported as a bad signature.
+        raise SignatureError.new(e.message, status: e.status, transport: e.transport?)
       end
 
       sig { void }

data/lib/standard_singpass/myinfo/configuration.rb

@@ -17,6 +17,10 @@
 #   c.minimum_acr            - Required Authentication Context Class Reference URN
 #   c.network_wrapper        - Lambda wrapping outbound Faraday calls (e.g. circuit breaker)
 #   c.mock_mode              - When true, suppresses missing-key warnings
+#                              (and is refused outright on a production deploy
+#                              — see MockModeGuard)
+#   c.production_env_detector - Callable returning whether this deploy is real
+#                              production; defaults to Rails.env.production?
 #   c.personas_path          - Pathname to JSON file of test personas
 #   c.authorize_url, c.par_url, c.token_url, c.userinfo_url,
 #   c.jwks_url, c.userinfo_jwks_url, c.issuer
@@ -125,12 +129,24 @@ module StandardSingpass
                     :signing_key, :signing_kid, :encryption_keys,
                     :minimum_acr, :network_wrapper, :mock_mode, :personas_path
 
+      # Optional callable deciding whether the current deploy is real
+      # production, for the purpose of MockModeGuard. Takes no args, returns a
+      # boolean. When nil (the default) the gem falls back to
+      # Rails.env.production?, so existing consumers are unchanged.
+      #
+      # Hosts that distinguish a physical deploy environment from RAILS_ENV
+      # — staging and preview boxes routinely run RAILS_ENV=production — can
+      # supply `-> { AppEnv.production? }` so mock mode stays legal on those
+      # while still refusing to boot on real production.
+      attr_accessor :production_env_detector
+
       def initialize
         self.environment = :staging
         @scope = DEFAULT_SCOPE
         @encryption_keys = []
         @network_wrapper = ->(&block) { block.call }
         @mock_mode = false
+        @production_env_detector = nil
       end
 
       def environment=(env)

data/lib/standard_singpass/myinfo/error.rb

@@ -2,7 +2,57 @@
 
 module StandardSingpass
   module Myinfo
-    class Error < StandardError; end
+    # Base class for every error the gem raises.
+    #
+    # 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:
+    #
+    # `status` — the HTTP status of the Singpass response that produced the
+    # error. Nil when there was no response (a transport failure) and for
+    # errors a host raises itself.
+    #
+    # `transport?` — true when we never got an answer from Singpass at all
+    # (DNS, connection refused, TLS, read timeout — a `Faraday::Error` under
+    # the hood), as opposed to Singpass answering with something we can't
+    # use. Only the former is unambiguously *their* side being unreachable.
+    #
+    # Both live on the base class rather than on `ApiError` alone because
+    # every leg of the flow raises its own class — `PARError` for PAR,
+    # `ApiError` for token and userinfo — and a host asking "is Singpass
+    # available?" needs the same answer from all of them. Scoping `status` to
+    # `ApiError` would silently misclassify a 502 from the PAR endpoint as
+    # "our request was wrong".
+    #
+    # 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
+      extend T::Sig
+
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :status
+
+      # Both keywords are optional so the bare `raise SomeError, "msg"` form
+      # used across the client (and by hosts) keeps working unchanged.
+      sig do
+        params(
+          message: T.nilable(String),
+          status: T.nilable(Integer),
+          transport: T::Boolean
+        ).void
+      end
+      def initialize(message = nil, status: nil, transport: false)
+        super(message)
+        @status = status
+        @transport = transport
+      end
+
+      sig { returns(T::Boolean) }
+      def transport?
+        @transport
+      end
+    end
+
     class AuthenticationError < Error; end
     class PARError < Error; end
     class DecryptionError < Error; end
@@ -10,34 +60,14 @@ module StandardSingpass
     class RateLimitError < Error; end
     class ConfigurationError < Error; end
 
-    # Raised for a Myinfo response we can't use, and for transport failures
-    # reaching Myinfo at all.
-    #
-    # `status` carries the HTTP status when the error came from an actual
-    # response (nil for transport failures, and for errors a host application
-    # raises itself). Hosts need it to tell "Myinfo or one of its upstream
-    # agencies is unavailable" — 502/503/504, retry in a few minutes — apart
-    # from "we sent something wrong", which is a bug and warrants support
-    # contact. Parsing the status back out of `message` is the alternative, and
-    # it is a trap: the message is not a stable interface.
+    # Raised for a Myinfo token- or userinfo-endpoint response we can't use,
+    # and for transport failures reaching those endpoints at all. `status` and
+    # `transport?` come from Error.
     #
     # 502 specifically is Singpass's documented signal that a Myinfo upstream
     # (CPF Board, IRAS, MOM, …) is down, including during their published
     # maintenance windows:
     # https://docs.developer.singpass.gov.sg/docs/products/singpass-myinfo/scheduled-downtimes
-    class ApiError < Error
-      extend T::Sig
-
-      sig { returns(T.nilable(Integer)) }
-      attr_reader :status
-
-      # `status:` is keyword-only and optional so the bare `raise ApiError,
-      # "msg"` form used across the client (and by hosts) keeps working.
-      sig { params(message: T.nilable(String), status: T.nilable(Integer)).void }
-      def initialize(message = nil, status: nil)
-        super(message)
-        @status = status
-      end
-    end
+    class ApiError < Error; end
   end
 end

data/lib/standard_singpass/myinfo/failure_classifier.rb

@@ -0,0 +1,64 @@
+# typed: strict
+
+module StandardSingpass
+  module Myinfo
+    # Decides whether a Myinfo failure is *Singpass's* side being unavailable
+    # or *our* request being wrong.
+    #
+    # The distinction exists because it changes what the host tells the user.
+    # An unavailable upstream clears itself within minutes, so the honest
+    # instruction is "try again shortly"; telling someone "something on our
+    # side stopped the verification — contact support and quote this
+    # reference" is both wrong and a dead end. Conversely, presenting a
+    # genuine integration bug as a transient blip sends the user round a loop
+    # that will never succeed.
+    #
+    # This lives in the gem rather than in each host because the rule is
+    # entirely Myinfo protocol knowledge: which statuses Singpass uses for
+    # upstream-agency outages, and which of the gem's own exception classes
+    # represent an unreachable endpoint. Hosts typically need the same answer
+    # at more than one call site (a callback's result branch and a
+    # controller's rescue), so it is a module function rather than a private
+    # method on either.
+    module FailureClassifier
+      extend T::Sig
+
+      # 502 is Singpass's documented signal that a Myinfo upstream agency
+      # (CPF Board, IRAS, MOM, …) is unavailable — returned both for genuine
+      # blips and throughout their published maintenance windows. 503/504 are
+      # the generic unavailable/gateway-timeout equivalents.
+      # https://docs.developer.singpass.gov.sg/docs/products/singpass-myinfo/scheduled-downtimes
+      #
+      # `Client::RETRYABLE_USERINFO_STATUSES` is an alias of this list: the
+      # statuses worth one more automatic attempt are exactly the statuses
+      # that mean "their side, transient".
+      UPSTREAM_UNAVAILABLE_STATUSES = T.let([502, 503, 504].freeze, T::Array[Integer])
+
+      # True when the failure is Singpass (or one of its upstream agencies)
+      # being unavailable, i.e. the user should be told to retry shortly.
+      # False for anything that looks like our own request being wrong —
+      # authentication, decryption, signature, and configuration failures, and
+      # any non-Myinfo exception.
+      #
+      # Deliberately keyed on the base `Error` rather than `ApiError`: every
+      # leg of the flow raises its own class (`PARError` for PAR, `ApiError`
+      # for token and userinfo), and a 502 is a 502 whichever leg returned it.
+      # Narrowing to `ApiError` would report a PAR-leg outage as our own bug.
+      sig { params(error: ::StandardError).returns(T::Boolean) }
+      def self.upstream_unavailable?(error)
+        # Rate limiting counts: temporary, clears on its own, and the advice
+        # the host gives the user is identical.
+        return true if error.is_a?(RateLimitError)
+        return false unless error.is_a?(Error)
+
+        # A transport failure never reached Singpass at all, which is still
+        # their endpoint being unreachable from here.
+        return true if error.transport?
+
+        # `status` is nil for an error a host raised itself; that falls
+        # through to false rather than being guessed at.
+        UPSTREAM_UNAVAILABLE_STATUSES.include?(error.status)
+      end
+    end
+  end
+end

data/lib/standard_singpass/myinfo/mock_mode_guard.rb

@@ -0,0 +1,112 @@
+# typed: strict
+
+module StandardSingpass
+  module Myinfo
+    # Boot-time guard against running with `config.mock_mode` enabled where it
+    # must never be.
+    #
+    # Mock mode short-circuits the FAPI 2.0 dance and serves data from static
+    # fixture personas (`TestPersonas`). That is exactly right for
+    # development, CI, and staging rehearsals, and catastrophic in production:
+    # real users would submit fabricated identity and income data, and it
+    # would be indistinguishable downstream from verified Myinfo data. A
+    # mis-set environment variable on one deploy is all it takes, and nothing
+    # about the running app looks wrong afterwards — which is why this is a
+    # boot-time check rather than a runtime warning.
+    #
+    # Three outcomes, deliberately:
+    #
+    #   production deploy       → raise. The app refuses to boot.
+    #   production-*like* deploy → log + report, boot anyway.
+    #   anything else           → silent.
+    #
+    # The middle tier exists because staging and preview deploys routinely run
+    # `RAILS_ENV=production` while being entirely legitimate places to enable
+    # mock mode. Failing those closed would make the guard unusable, and
+    # staying silent would hide a genuinely mis-set variable, so they get a
+    # loud-but-non-fatal signal instead.
+    #
+    # "Production deploy" is decided by `config.production_env_detector` when
+    # set, falling back to `Rails.env.production?`. The gem cannot know about
+    # a host's own environment discriminator (`APP_ENVIRONMENT` and friends),
+    # and deliberately does not read ENV itself — the callable is the seam.
+    # This mirrors `StandardId`'s `production_env_detector`.
+    #
+    # Wired automatically from the engine's `after_initialize`, so a host gets
+    # the guard by configuring `mock_mode` at all. There is no opt-out: a
+    # guard you can forget to invoke is a guard that isn't there.
+    module MockModeGuard
+      extend T::Sig
+
+      sig { void }
+      def self.check!
+        return unless StandardSingpass::Myinfo.configuration.mock_mode
+
+        if production_deploy?
+          raise ConfigurationError, production_message
+        elsif rails_production?
+          report_production_like
+        end
+      end
+
+      # Whether this deploy is real production for the purpose of the guard.
+      # Defers to config.production_env_detector when set (hosts that
+      # distinguish a physical deploy environment from RAILS_ENV), else falls
+      # back to Rails.env.production?.
+      sig { returns(T::Boolean) }
+      def self.production_deploy?
+        detector = StandardSingpass::Myinfo.configuration.production_env_detector
+        return !!detector.call if detector
+
+        rails_production?
+      end
+
+      sig { returns(T::Boolean) }
+      def self.rails_production?
+        defined?(::Rails) && ::Rails.env.production?
+      end
+      private_class_method :rails_production?
+
+      sig { returns(String) }
+      def self.production_message
+        "StandardSingpass::Myinfo mock_mode is enabled on a production " \
+          "deploy. Mock mode bypasses the real Singpass flow and serves " \
+          "fixture persona data, so real users would submit fabricated " \
+          "identity data that is indistinguishable from verified Myinfo " \
+          "data downstream. The application refuses to boot. Unset the " \
+          "mock-mode environment variable on this deploy and redeploy. If " \
+          "this deploy is not actually production, set " \
+          "config.production_env_detector so the gem can tell."
+      end
+      private_class_method :production_message
+
+      # A production-*like* deploy (RAILS_ENV=production but not production
+      # per the detector) — staging, preview, a review app. Mock mode can be
+      # intentional here, so this boots; it is reported rather than raised.
+      #
+      # Reported through `Rails.error` rather than a specific error tracker so
+      # whatever the host has subscribed (Sentry included) picks it up.
+      sig { void }
+      def self.report_production_like
+        message = "StandardSingpass::Myinfo mock_mode is enabled on a " \
+          "deploy running RAILS_ENV=production. Users will go through the " \
+          "mock Singpass flow and submit fixture data. Unset the mock-mode " \
+          "environment variable unless this is intentional."
+
+        ::Rails.logger&.error("StandardSingpass::Myinfo: #{message}")
+
+        return unless defined?(::Rails.error)
+
+        ::Rails.error.report(
+          ConfigurationError.new(message),
+          handled: true,
+          context: {
+            component: "StandardSingpass::Myinfo::MockModeGuard",
+            reason: "mock_mode_on_production_like_deploy"
+          }
+        )
+      end
+      private_class_method :report_production_like
+    end
+  end
+end

data/lib/standard_singpass/myinfo/noa.rb

@@ -0,0 +1,76 @@
+# typed: strict
+
+module StandardSingpass
+  module Myinfo
+    # Normalises Notice-of-Assessment data from `PersonDataParser` into a
+    # single list, regardless of which NOA scope the Singpass app was approved
+    # for.
+    #
+    # Singpass approves NOA access at one of two widths, and the width is a
+    # property of the *app registration*, not of the request:
+    #
+    #   noa            → Notice of Assessment, latest year only
+    #   noahistory     → Notice of Assessment, last 2 years
+    #
+    # `PersonDataParser` mirrors that faithfully, emitting `:noa` (one record)
+    # or `:noa_history` (an array, one entry per assessment year). The two
+    # records have an identical shape — `year_of_assessment`, `amount`,
+    # `employment`, `trade`, `rent`, `interest`, `tax_category` — so every
+    # consumer that renders NOA data ends up writing the same "array or wrap
+    # the single record" branch. That branch is scope-grant knowledge, not
+    # host policy, so it belongs here.
+    #
+    # The `-basic` scopes (`noa-basic` / `noahistory-basic`) are the same
+    # split at a narrower field set (`year_of_assessment` and `amount` only),
+    # handled by `.basic_history`.
+    #
+    # The wider grant is preferred when both keys are present: a 2-year
+    # history is a superset of the latest year, so returning it loses nothing.
+    #
+    # Keys are looked up as both Symbol and String because parser output is
+    # symbol-keyed when fresh but string-keyed once it has round-tripped
+    # through JSON or a database column — which is where most hosts read it
+    # back from.
+    module Noa
+      extend T::Sig
+
+      # Detailed NOA records, newest first as Singpass returns them. Returns
+      # nil when neither detailed scope yielded data (e.g. a self-reported
+      # application with no Myinfo record at all).
+      sig { params(parsed: T.untyped).returns(T.nilable(T::Array[T.untyped])) }
+      def self.history(parsed)
+        normalize(parsed, history_key: :noa_history, single_key: :noa)
+      end
+
+      # Same, for the `-basic` scope pair.
+      sig { params(parsed: T.untyped).returns(T.nilable(T::Array[T.untyped])) }
+      def self.basic_history(parsed)
+        normalize(parsed, history_key: :noa_history_basic, single_key: :noa_basic)
+      end
+
+      sig do
+        params(
+          parsed: T.untyped,
+          history_key: Symbol,
+          single_key: Symbol
+        ).returns(T.nilable(T::Array[T.untyped]))
+      end
+      def self.normalize(parsed, history_key:, single_key:)
+        history = fetch(parsed, history_key)
+        return history if history.is_a?(Array) && !history.empty?
+
+        single = fetch(parsed, single_key)
+        single.is_a?(Hash) && !single.empty? ? [single] : nil
+      end
+      private_class_method :normalize
+
+      sig { params(parsed: T.untyped, key: Symbol).returns(T.untyped) }
+      def self.fetch(parsed, key)
+        return nil unless parsed.is_a?(Hash)
+
+        parsed[key].nil? ? parsed[key.to_s] : parsed[key]
+      end
+      private_class_method :fetch
+    end
+  end
+end

data/lib/standard_singpass/myinfo/security.rb

@@ -5,8 +5,15 @@ module StandardSingpass
     class Security
       extend T::Sig
 
-      class DecryptionError < StandardError; end
-      class ValidationError < StandardError; end
+      # 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
 
       JWKS_CACHE_TTL = T.let(1.hour, ActiveSupport::Duration)
 
@@ -170,11 +177,18 @@ 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 }
-          raise ValidationError, "Failed to fetch JWKS: HTTP #{response.status}" unless response.success?
+          unless response.success?
+            raise ValidationError.new("Failed to fetch JWKS: HTTP #{response.status}", status: response.status)
+          end
 
           JSON.parse(response.body)
         end
-      rescue Faraday::Error, JSON::ParserError => e
+      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)
+      rescue JSON::ParserError => e
+        # Reached it and got something unusable. Not an availability problem.
         raise ValidationError, "Failed to fetch JWKS: #{e.message}"
       end
       private_class_method :fetch_jwks

data/lib/standard_singpass/myinfo.rb

@@ -10,13 +10,16 @@ require "securerandom"
 require "aes_key_wrap"
 
 require "standard_singpass/myinfo/error"
+require "standard_singpass/myinfo/failure_classifier"
 require "standard_singpass/myinfo/configuration"
 require "standard_singpass/myinfo/ecdh_jwe"
 require "standard_singpass/myinfo/security"
 require "standard_singpass/myinfo/client"
 require "standard_singpass/myinfo/person_data_parser"
+require "standard_singpass/myinfo/noa"
 require "standard_singpass/myinfo/jwks_generator"
 require "standard_singpass/myinfo/test_personas"
+require "standard_singpass/myinfo/mock_mode_guard"
 
 module StandardSingpass
   module Myinfo

data/lib/standard_singpass/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_singpass
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -145,7 +145,10 @@ files:
 - lib/standard_singpass/myinfo/configuration.rb
 - lib/standard_singpass/myinfo/ecdh_jwe.rb
 - lib/standard_singpass/myinfo/error.rb
+- lib/standard_singpass/myinfo/failure_classifier.rb
 - lib/standard_singpass/myinfo/jwks_generator.rb
+- lib/standard_singpass/myinfo/mock_mode_guard.rb
+- lib/standard_singpass/myinfo/noa.rb
 - lib/standard_singpass/myinfo/person_data_parser.rb
 - lib/standard_singpass/myinfo/security.rb
 - lib/standard_singpass/myinfo/test_personas.rb