standard_singpass 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8da1f0678a358ee51cf45c1f7b47f537e465f4d9c2ed738de7cdb2326fd92b49
-  data.tar.gz: cd6df85e85fe8d5a0636558b943f1cfadc5a5704eed15c7c52c367c2bf7ba974
+  metadata.gz: ea90960df9e3752b2ec01cb271cac1c31fc8c53cfb5a757a64810d3eccecbb79
+  data.tar.gz: 3eba17716f557250f1013b303216b2450ea691080ed7bc924b8fa1749b832305
 SHA512:
-  metadata.gz: 849a2c6e1de1e63c8092f2088ef5e8de12292d3b3e130c6a47831fa244def9dfe7cc854a82eff49d4863757423d4feb788f6d943345aa953c6007a85f91df549
-  data.tar.gz: 36da035a4471275f50a3a2e2c974f440ff337c45a34b43a4181da80187a283c40937bcc0724f20a52d8f9a22780d6af277aba3494739bdaa49ebe586a193caee
+  metadata.gz: e3f7ca50aaf67da5e1b82f33455662da9743a9f4cffedd533a878c409394681b7f1e1d16c197362cccce9031744509c71e6674195b1012ee7f7867595fa4cd48
+  data.tar.gz: bba22e4c5ede26f234acfea6289ee469fa646612bf198eabcaacc397e3270ce276fd5d3ea18adf9c87b549a0d88ab3b905baa15b7692de1666eaebae0ba58d8d

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-22
+
+### Added
+
+- `StandardSingpass::Myinfo::ApiError#status` — the HTTP status of the Myinfo response that produced the error (`nil` for transport failures and for errors a host raises itself). Hosts need this to separate "Myinfo or one of its upstream agencies is unavailable" (502/503/504 — tell the user to retry shortly) from "we sent something wrong" (4xx — a bug worth surfacing to support). Previously the only way to recover the status was to parse it back out of the message, which is not a stable interface. Set on both the userinfo and token-exchange failure paths.
+- Bounded retry with jittered exponential backoff on the **userinfo** fetch for transient upstream statuses (502/503/504), 3 attempts total. Singpass returns `502 upstream_dependency_error` whenever a Myinfo upstream (CPF Board, IRAS, MOM, …) is unavailable — including throughout their [published maintenance windows](https://docs.developer.singpass.gov.sg/docs/products/singpass-myinfo/scheduled-downtimes) — and a single transient one previously failed the whole flow. Because the authorization code is already spent by that point, the user's only recovery was a **full Singpass re-login**, so a momentary blip cost a complete re-authentication.
+
+### Notes
+
+- The retry is scoped deliberately:
+  - **Userinfo only.** The token exchange is never retried — it consumes a single-use authorization code, and replaying it earns an `invalid_grant`. Userinfo is an idempotent GET against an access token already in hand.
+  - **Status-based failures only, never timeouts.** A 5xx returns in well under a second; a timed-out attempt has already spent the request budget, and retrying it risks turning a slow page into a gateway error.
+  - **Inside `network_wrapper`, not outside.** A host's wrapper is typically a circuit breaker; keeping retries inside means one user attempt counts as one failure against the breaker rather than three, so a single unlucky user can't trip a shared circuit alone.
+- The DPoP proof is rebuilt on every attempt — RFC 9449 proofs carry a one-shot `jti`, so a replayed header would be rejected.
+
 ## [0.1.0] - 2026-05-24
 
 ### Added

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,6 @@
-Copyright (c) 2026 Jaryl Sim
+The MIT License (MIT)
+
+Copyright (c) 2026 Rarebit One
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/standard_singpass/myinfo/client.rb

@@ -169,17 +169,25 @@ module StandardSingpass
 
       sig { params(access_token: String, dpop_key_pair: OpenSSL::PKey::EC).returns(T::Hash[String, T.untyped]) }
       def fetch_userinfo(access_token:, dpop_key_pair:)
+        # Retries sit INSIDE the network wrapper deliberately. A host's wrapper
+        # is typically a circuit breaker; keeping retries inside means one user
+        # attempt counts as one failure against the breaker instead of three,
+        # so a single unlucky borrower can't trip a shared circuit on their own.
         with_network_wrapper do
-          response = http_connection.get(@userinfo_url) do |req|
-            req.headers["Authorization"] = "DPoP #{access_token}"
-            req.headers["DPoP"] = Security.build_dpop_proof(
-              http_method: "GET",
-              url: T.must(@userinfo_url),
-              key_pair: dpop_key_pair,
-              access_token:
-            )
+          with_userinfo_retries do
+            # The DPoP proof carries a per-request jti/iat, so it is rebuilt on
+            # every attempt — replaying one would be rejected as a duplicate.
+            response = http_connection.get(@userinfo_url) do |req|
+              req.headers["Authorization"] = "DPoP #{access_token}"
+              req.headers["DPoP"] = Security.build_dpop_proof(
+                http_method: "GET",
+                url: T.must(@userinfo_url),
+                key_pair: dpop_key_pair,
+                access_token:
+              )
+            end
+            handle_person_response(response, jwks_url: @userinfo_jwks_url)
           end
-          handle_person_response(response, jwks_url: @userinfo_jwks_url)
         end
       rescue Faraday::Error => e
         raise ApiError, "MyInfo userinfo endpoint unreachable: #{e.class}"
@@ -332,7 +340,10 @@ module StandardSingpass
         when 429
           raise RateLimitError, "Token endpoint rate limit exceeded"
         else
-          raise ApiError, "Token exchange failed (HTTP #{response.status}): #{body_excerpt(response)}"
+          raise ApiError.new(
+            "Token exchange failed (HTTP #{response.status}): #{body_excerpt(response)}",
+            status: response.status
+          )
         end
       rescue KeyError
         raise AuthenticationError, "Token response missing access_token"
@@ -350,10 +361,60 @@ module StandardSingpass
         when 429
           raise RateLimitError, "Person endpoint rate limit exceeded"
         else
-          raise ApiError, "Person data fetch failed (HTTP #{response.status}): #{body_excerpt(response)}"
+          raise ApiError.new(
+            "Person data fetch failed (HTTP #{response.status}): #{body_excerpt(response)}",
+            status: response.status
+          )
+        end
+      end
+
+      # Myinfo statuses that mean "Myinfo, or one of its upstream agencies, is
+      # 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])
+
+      # Total attempts, not retries — 3 means the original plus two more.
+      USERINFO_MAX_ATTEMPTS = 3
+
+      # Base for the exponential backoff, in seconds (0.3s, then 0.6s, each
+      # with jitter). Deliberately small: this runs inside a browser redirect
+      # from Singpass, so the whole retry budget has to stay well under the
+      # user's patience and the host's request timeout.
+      USERINFO_RETRY_BASE_DELAY = 0.3
+
+      # Retry a userinfo fetch that failed with a transient upstream status.
+      #
+      # Safe to retry because the userinfo call is an idempotent GET against an
+      # access token we already hold — unlike the token exchange, which burns a
+      # single-use authorization code and must never be replayed.
+      #
+      # Only status-based failures are retried, never timeouts: a 5xx comes back
+      # in well under a second, whereas a timed-out attempt has already spent
+      # the request budget and retrying it risks turning a slow page into a
+      # gateway error. A transport failure therefore propagates on the first hit.
+      sig { params(block: T.proc.returns(T::Hash[String, T.untyped])).returns(T::Hash[String, T.untyped]) }
+      def with_userinfo_retries(&block)
+        attempt = 0
+        begin
+          attempt += 1
+          block.call
+        rescue ApiError => e
+          raise unless RETRYABLE_USERINFO_STATUSES.include?(e.status)
+          raise if attempt >= USERINFO_MAX_ATTEMPTS
+
+          sleep(userinfo_retry_delay(attempt))
+          retry
         end
       end
 
+      # Exponential backoff with full jitter, so concurrent borrowers hitting
+      # the same upstream blip don't retry in lockstep.
+      sig { params(attempt: Integer).returns(Float) }
+      def userinfo_retry_delay(attempt)
+        Float(rand * USERINFO_RETRY_BASE_DELAY * (2**(attempt - 1)))
+      end
+
       # Standardized FAPI/OAuth error fields that are safe to surface in error
       # messages — non-PII, useful for debugging, and explicitly named by the
       # OAuth 2.0 / FAPI 2.0 / Singpass specs. Any other field in the response

data/lib/standard_singpass/myinfo/error.rb

@@ -4,11 +4,40 @@ module StandardSingpass
   module Myinfo
     class Error < StandardError; end
     class AuthenticationError < Error; end
-    class ApiError < Error; end
     class PARError < Error; end
     class DecryptionError < Error; end
     class SignatureError < Error; end
     class RateLimitError < Error; end
     class ConfigurationError < Error; end
+
+    # 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.
+    #
+    # 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
   end
 end

data/lib/standard_singpass/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_singpass
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -132,7 +132,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- LICENSE
 - README.md
 - Rakefile
 - fixtures/myinfo-personas.json