standard_singpass 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ecc46cf176551f25806d49f04c64ba204801c137b46c7c5970fd6a0f97d650a
-  data.tar.gz: f5d5c709779c0082d75c4909d549ccf451daa5406900ac7e05f83e23d2e69994
+  metadata.gz: dbda49a3c31fd6844db0d58c66c0bf1c8654882d37105c58dd1537a2e2cb13c5
+  data.tar.gz: 5b4ebd78e72bab8b36a2d8d5c298cc8f99e277c018b23a5b42ff7dfb4030292e
 SHA512:
-  metadata.gz: a30193c9f2d2a7633f3833e1eb186df1dd09b7fa922de35ab0c7dd2d1b7acb5f8c867e91e14e86fb82cce0f814f047ee1d402911334100d1fde4ac1b353b1f05
-  data.tar.gz: 886ac97c7a2ea5125cc079ef141dcb6c303d0ac02e0c48343a6e20aff20ed889d66af105305f315e5aab5f69ed1aaaa7a781467482326162511a0690780fd812
+  metadata.gz: 47d70dda7f2948b55b59afac864885452e776aefe9e8806a16e62f31b9ca02bc6a8772e5eff7849b25ca3a8805487d45ea3c63a77412a713ba3c7b11f6e7f3e1
+  data.tar.gz: cd7b80ae5bea3214b3d1bb146801c673fe2934b8b245865ef7bd61dee8952a0d2f5dd670f24c08e925fb083fb6e8debe1901ad2ce9fcee57b8fe9174cff503af

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-24
+
+### Fixed
+
+- **`minimum_acr` is no longer sent to Singpass as `acr_values` on the Pushed Authorization Request.** Singpass rejects that parameter for MyInfo — `PAR failed (HTTP 400) invalid_request — "The acr_values parameter can only be used for specific use cases."` — so any host that set `minimum_acr` (as the README and the install generator recommended, via `MYINFO_MIN_ACR`) failed every MyInfo login at the first step. This took down production onboarding for a consuming app for roughly four days before it was traced. `minimum_acr` is now purely a client-side check: the id_token `acr` claim is still validated against it (`AuthenticationError` when below the floor or missing; `ConfigurationError` for an unrecognised URN), and the PAR body never carries `acr_values`.
+
+  **Behaviour change / upgrade note:** hosts with `minimum_acr` set go from "every PAR fails with HTTP 400" to "PAR succeeds and the returned id_token `acr` is checked locally". Hosts that left it unset see no change. If you had pinned `minimum_acr = nil` as a workaround, you can keep it — MyInfo's assurance level is governed by Singpass server-side and the floor is optional. If you wired it from `MYINFO_MIN_ACR`, consider removing that env wiring (see Documentation below).
+
+### Documentation
+
+- **Install generator no longer wires `c.minimum_acr = ENV["MYINFO_MIN_ACR"]`** or documents `MYINFO_MIN_ACR`. The option is left commented out with a warning that it is a client-side check only and that a wrong value fails every login closed.
+- **README:** Installation now mentions `bin/rails g standard_singpass:install`; the `MYINFO_MIN_ACR` wiring is removed from the configuration example; a new "Assurance level (`minimum_acr`)" section explains what the option does and does not do; and the default-scope comment now gives the real size of `DEFAULT_SCOPE` (42 scopes — `openid` plus 41 attributes — not "a 36-attribute set").
+- **Consumer list in `CLAUDE.md` narrowed to the one app that actually consumes this gem.** It said "the rarebit-one workspace's web apps", which reads as all five and would send a rollout at four apps with no Singpass integration. The single consumer is `fundbright-web`, in the sibling `~/Workspace/fundbright/` workspace. The list is now bulleted so the new advisory `check-gem-family-drift.sh` can diff it against the canonical matrix in the workspace's `rollout-gem/SKILL.md` — prose that a human reads as one thing and a script as another is how this drifted in the first place.
+
 ## [0.3.0] - 2026-07-30
 
 ### Added

data/README.md

@@ -12,6 +12,15 @@ Add to your Gemfile:
 gem "standard_singpass"
 ```
 
+Then generate the initializer:
+
+```bash
+bin/rails g standard_singpass:install
+```
+
+This writes `config/initializers/standard_singpass.rb`, mapping the `MYINFO_*`
+environment variables onto the gem's configuration (see below).
+
 ## Configuration
 
 ```ruby
@@ -24,17 +33,18 @@ StandardSingpass::Myinfo.configure do |c|
   c.client_id        = ENV["MYINFO_CLIENT_ID"]
   c.redirect_url     = ENV["MYINFO_REDIRECT_URL"]
 
-  # Optional: override default scope (defaults to a 36-attribute set covering
-  # identity, contact, income, employment, housing, assets, vehicles).
+  # Optional: override default scope (defaults to 42 scopes — `openid` plus 41
+  # MyInfo attributes covering identity, contact, income, employment, housing,
+  # assets, vehicles).
   # c.scope = "openid name email ..."
 
   # Required: full private JWKS JSON containing both sig (ES256) and enc
   # (ECDH-ES+A256KW) keys with the private scalar `d`.
   c.private_jwks_json = ENV["MYINFO_PRIVATE_JWKS"]
 
-  # Optional: enforce minimum Authentication Context Class Reference. Set to
-  # e.g. "urn:singpass:authentication:loa:3" to require high-assurance.
-  c.minimum_acr = ENV["MYINFO_MIN_ACR"]
+  # Optional: client-side floor on the id_token `acr` claim. Never sent to
+  # Singpass — see "Assurance level (`minimum_acr`)" below before setting it.
+  # c.minimum_acr = "urn:singpass:authentication:loa:2"
 
   # Optional: wrap outbound HTTP calls with a circuit breaker / retry layer.
   # Defaults to identity (no wrapper).
@@ -54,6 +64,33 @@ StandardSingpass::Myinfo.configure do |c|
 end
 ```
 
+## Assurance level (`minimum_acr`)
+
+`config.minimum_acr` is an optional, **client-side** check. When set to a
+Singpass LOA URN (`urn:singpass:authentication:loa:2` or `...:loa:3`), the
+client rejects any id_token whose `acr` claim is below that level — or missing
+— with `StandardSingpass::Myinfo::AuthenticationError`. A value that is not a
+recognised LOA URN raises `ConfigurationError`. Unset or blank disables the
+check.
+
+It is **never sent to Singpass.** Singpass rejects `acr_values` on a MyInfo
+Pushed Authorization Request:
+
+```
+PAR failed (HTTP 400) invalid_request —
+"The acr_values parameter can only be used for specific use cases."
+```
+
+Versions up to 0.3.0 forwarded a configured `minimum_acr` as `acr_values`, so
+setting it broke every MyInfo login. From 0.3.1 the PAR request never carries
+`acr_values`. MyInfo's assurance level is governed by Singpass server-side, so
+most hosts should leave `minimum_acr` unset; if you do set it, set it in code
+rather than from a loosely-managed environment variable, because a wrong value
+fails every login closed.
+
+The `acr` Singpass actually returned is surfaced as `result[:id_token_acr]`
+from `get_person_data` for audit, whether or not a floor is configured.
+
 ## Mock mode
 
 `config.mock_mode` makes the host serve fixture persona data

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

@@ -16,8 +16,6 @@
 #   MYINFO_SCOPE             Space-separated scopes (defaults to DEFAULT_SCOPE)
 #   MYINFO_USERINFO_URL      Userinfo endpoint override (rarely needed)
 #   MYINFO_USERINFO_JWKS_URL Userinfo JWKS endpoint override (rarely needed)
-#   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. The gem REFUSES TO BOOT if this is set
@@ -40,8 +38,17 @@ StandardSingpass::Myinfo.configure do |c|
   c.userinfo_url      = ENV["MYINFO_USERINFO_URL"]      if ENV["MYINFO_USERINFO_URL"].present?
   c.userinfo_jwks_url = ENV["MYINFO_USERINFO_JWKS_URL"] if ENV["MYINFO_USERINFO_JWKS_URL"].present?
 
-  c.minimum_acr = ENV["MYINFO_MIN_ACR"]
-  c.mock_mode   = ENV["MYINFO_MOCK_MODE"].present?
+  c.mock_mode = ENV["MYINFO_MOCK_MODE"].present?
+
+  # Optional client-side floor on the id_token `acr` claim. The gem rejects an
+  # id_token whose assurance level is below it (AuthenticationError); it is
+  # NEVER sent to Singpass — `acr_values` on a MyInfo PAR is rejected with
+  # HTTP 400 invalid_request. MyInfo's assurance level is governed by Singpass
+  # server-side, so most hosts should leave this unset.
+  #
+  # WARNING: do not wire this to an environment variable without a test that
+  # exercises the real flow — a stray value fails every login closed.
+  # c.minimum_acr = "urn:singpass:authentication:loa:2"
 
   # How the gem decides whether this deploy is real production, for the
   # mock-mode boot guard. Defaults to Rails.env.production?. Staging and

data/lib/standard_singpass/myinfo/client.rb

@@ -60,17 +60,17 @@ module StandardSingpass
           )
         }
 
-        # Ask Singpass to enforce a minimum assurance level upstream. The same
-        # config attribute also drives downstream validation of the returned
-        # id_token (validate_id_token_acr) — defense in depth. When unset, we
-        # skip both the request parameter and the validator entirely; useful
-        # for sandbox personas that may return non-conformant acr values.
-        # Concrete URN per Singpass: `urn:singpass:authentication:loa:N` (N
-        # is 2 or 3; Singpass never issues below LOA 2). `.to_s.strip` mirrors
-        # the validator so whitespace-only values are treated as unset and any
-        # value sent over the wire is trimmed.
-        min_acr = @minimum_acr.to_s.strip
-        body[:acr_values] = min_acr unless min_acr.empty?
+        # `acr_values` is deliberately NEVER sent, even when `minimum_acr` is
+        # configured. Singpass rejects it on a MyInfo PAR:
+        #
+        #   PAR failed (HTTP 400) invalid_request —
+        #   "The acr_values parameter can only be used for specific use cases."
+        #
+        # Until 0.3.1 a non-empty `minimum_acr` was forwarded here, which broke
+        # every MyInfo onboarding for any host that set it. `minimum_acr` is
+        # now purely a client-side check of the returned id_token `acr` claim
+        # (see validate_id_token_acr); MyInfo's assurance level itself is
+        # governed by Singpass server-side.
 
         with_network_wrapper do
           response = http_connection.post(@par_url) do |req|
@@ -299,8 +299,9 @@ module StandardSingpass
       # Enforce a minimum Authentication Context Class Reference (`acr`) on the
       # id_token. The floor is configured via `minimum_acr` so staging and
       # production can diverge — staging may tolerate looser values returned by
-      # MyInfo sandbox personas. When the attr is unset or blank, both this
-      # validator and the upstream PAR `acr_values` parameter are skipped.
+      # MyInfo sandbox personas. When the attr is unset or blank, this
+      # validator is skipped. This is the ONLY effect of `minimum_acr` — it is
+      # never sent to Singpass as `acr_values` (see push_authorization_request).
       #
       # Singpass's `acr` URN format is `urn:singpass:authentication:loa:N`
       # where N is 2 or 3 (no LOA 1 path — Singpass's IdP is 2FA by design).

data/lib/standard_singpass/myinfo/configuration.rb

@@ -14,7 +14,11 @@
 #
 # Optional attributes:
 #   c.scope                  - Space-separated scopes (defaults to DEFAULT_SCOPE)
-#   c.minimum_acr            - Required Authentication Context Class Reference URN
+#   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.
+#                              Never sent to Singpass: `acr_values` on a MyInfo
+#                              PAR is rejected with HTTP 400 invalid_request.
 #   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

data/lib/standard_singpass/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_singpass
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Jaryl Sim