standard_singpass 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ecc46cf176551f25806d49f04c64ba204801c137b46c7c5970fd6a0f97d650a
-  data.tar.gz: f5d5c709779c0082d75c4909d549ccf451daa5406900ac7e05f83e23d2e69994
+  metadata.gz: b337f846e33125912e93e3819ad6ab9858dea86f6f2976f821650cd41eda5f2d
+  data.tar.gz: d655d89457c6a8120223dec9c266945ef03601dc79d82268e9ea5149fe7de75b
 SHA512:
-  metadata.gz: a30193c9f2d2a7633f3833e1eb186df1dd09b7fa922de35ab0c7dd2d1b7acb5f8c867e91e14e86fb82cce0f814f047ee1d402911334100d1fde4ac1b353b1f05
-  data.tar.gz: 886ac97c7a2ea5125cc079ef141dcb6c303d0ac02e0c48343a6e20aff20ed889d66af105305f315e5aab5f69ed1aaaa7a781467482326162511a0690780fd812
+  metadata.gz: 0ccefce8b78a9ad7ef3213738a6266b544241c18e99ce645aa0de0bb1f6067f5bda79f793ee048757c4763cd1f990779649bc86c3d506849c5e3d7cfc19a0290
+  data.tar.gz: 6fb74b23e6fdf75e2191d7eecc76a45969aac95f6d5dd8383572b563299c15b1013dd2199c2816189248713452f0043c861c74cf9e14d33504357226a3b1f1e7

data/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-24
+
+### Upgrading from 0.3.x
+
+1. **Set `c.scope` explicitly** if you relied on `DEFAULT_SCOPE` — it is now only `openid uinfin name`.
+2. `rescue Security::DecryptionError` / `Security::ValidationError` keeps working (they alias the public classes) but should move to `DecryptionError` / `SignatureError`.
+3. Specs calling `Myinfo::EcdhJwe.encrypt` should `require "standard_singpass/testing"` and call `StandardSingpass::Testing::EcdhJwe.encrypt`.
+4. The "set `private_jwks_json` last" ordering rule no longer applies.
+
+### Changed
+
+- **Breaking: `Configuration::DEFAULT_SCOPE` is now the minimal `"openid uinfin name"`.** It used to be one consuming app's 42-entry underwriting scope — including `noa`, `noa-basic` and `noahistory-basic`, which Singpass review flagged as redundant collection — so any host that never set `c.scope` silently requested all of it. Which attributes to collect is a host decision (PDPA Purpose Limitation) that must match the host's own developer-portal approval list, and the gem holds no domain policy. A minimal default was chosen over a "scope is required" boot error because `openid uinfin name` is a subset of every MyInfo approval: a host that forgets to set it gets a working flow that collects the least data possible, rather than over-collecting or failing to boot in development and test. The install generator now sets `c.scope` explicitly.
+
+  **Upgrade note:** if you relied on the old default, set `c.scope` to your approved list before upgrading — otherwise `PersonDataParser` fields outside `uinfin`/`name` come back `nil`. The 0.3.1 list is in [`configuration.rb` at v0.3.1](https://github.com/rarebit-one/standard_singpass/blob/v0.3.1/lib/standard_singpass/myinfo/configuration.rb) for reference (drop the NOA entries your approval does not cover). Hosts that already set `c.scope` are unaffected.
+- **Behaviour change: `ECDH-ES+A128KW` is no longer accepted.** `EcdhJwe::SUPPORTED_ALGS` is now `["ECDH-ES+A256KW"]` — the only alg the gem publishes on its encryption JWKs (`Myinfo.public_jwks`) and the one FAPI 2.0 Singpass uses. An A128KW JWE now raises `DecryptionError` ("Unsupported JWE alg") instead of decrypting. Nothing legitimate sends it to us, so accepting it was pure attack surface; hosts should see no difference.
+- **`Security` raises the public errors directly; `Security::DecryptionError` / `Security::ValidationError` are deprecated aliases.** JWE failures now raise `StandardSingpass::Myinfo::DecryptionError` and JWS / JWKS-fetch failures raise `StandardSingpass::Myinfo::SignatureError` (still carrying the JWKS response's `status`, or `transport?` when the JWKS host was unreachable). The old constants resolve to those same classes — `Security::ValidationError` *is* `SignatureError` — so an existing `rescue Security::ValidationError` keeps catching; referencing them emits Ruby's constant-deprecation warning (when `Warning[:deprecated]` is on) and they will be removed in a future minor. The client no longer needs to translate them on the userinfo leg; on the ID-token leg they are still wrapped in `AuthenticationError` exactly as before.
+- **New gem-wide root `StandardSingpass::Error`**, which `StandardSingpass::Myinfo::Error` now inherits from (previously `StandardError`). Existing `rescue StandardSingpass::Myinfo::Error` is unaffected.
+- **`private_jwks_json=` is parsed lazily.** The setter now only stores the JSON; it is parsed into `signing_key` / `signing_kid` / `encryption_keys` on first read of any of them, or by `Configuration#resolve_private_jwks!`, which the engine calls from `after_initialize` alongside `MockModeGuard` so missing / malformed-key warnings still surface at boot. Previously the setter parsed eagerly and read `mock_mode` / `Rails.env` at assignment time, so the configure block was order-dependent (hence the old "set `private_jwks_json` last" advice — no longer needed). Assigning `signing_key=` / `signing_kid=` / `encryption_keys=` directly still works and wins over an earlier `private_jwks_json=`. `Rails.logger` / `Rails.error` are now guarded (nil logger, or no Rails at all) in the parser and in `Myinfo.public_jwks`.
+- **`EcdhJwe.encrypt` moved to `StandardSingpass::Testing::EcdhJwe.encrypt`** (`require "standard_singpass/testing"`, not loaded by default). Encryption is only ever needed to build test fixtures — Singpass encrypts, the gem decrypts — so it no longer ships in the runtime load path. `StandardSingpass::Myinfo::EcdhJwe.encrypt` remains as a deprecated forwarder (same signature) that warns through the new `StandardSingpass.deprecator` — registered with `Rails.application.deprecators[:standard_singpass]` — and will be removed in a future minor.
+- **Dependency upper bounds:** `rails >= 8.0, < 9`, `faraday >= 2.0, < 3`, `jwt >= 2.7, < 4`. Each next major is a real API break for code the gem depends on (`JWT::JWK`, Faraday connection options, Rails engine hooks) and should be adopted deliberately rather than resolved into silently. The consuming app's current versions (Rails 8.1, Faraday 2.14, jwt 3.3) are all inside the ranges.
+- **Gem packaging:** `spec.files` no longer globs `app/`, `config/`, or `db/` (the gem has none), and the engine drops `isolate_namespace` — it has no routes, models, controllers, or views, so namespace isolation did nothing. Hosts never mounted it, so nothing changes for them.
+
+### Added
+
+- **`ActiveSupport::Notifications` instrumentation.** `standard_singpass.par`, `standard_singpass.token`, and `standard_singpass.userinfo` wrap each leg of the flow with a payload of `duration` (ms), `status`, `error` (class name only), `transport`, and — for userinfo — `attempts`; `standard_singpass.retry` fires on each automatic userinfo retry with `leg`, `attempt`, `status`, `error`, and `delay`. Payloads are PII-free by construction: no tokens, codes, bodies, URLs, or error messages (the error is captured and re-raised outside the instrument block, so ActiveSupport's message-bearing `:exception` keys are never added). See README → Instrumentation.
+- **`StandardSingpass.configure` / `StandardSingpass.config`** — top-level aliases for `StandardSingpass::Myinfo.configure` / `.configuration`, matching the sibling `standard_*` gems' `Gem.configure` / `Gem.config` convention. `StandardSingpass::Myinfo.config` is also available. The existing `Myinfo.configure` / `Myinfo.configuration` entry points are unchanged.
+- **Two more bundled test personas** in `fixtures/myinfo-personas.json`, upstreamed from the consuming app's own fixture set: `work_permit_holder` (FIN holder on a Work Permit / `RPass`) and `duplicate_check` (a stable NRIC for exercising duplicate-application paths). The existing personas are unchanged.
+
+### Deprecated
+
+- **`TestPersonas.reload!`** — unused by any consumer; now warns via `StandardSingpass.deprecator` and will be removed in a future minor.
+- **`Security::DecryptionError` / `Security::ValidationError`** — aliases of `DecryptionError` / `SignatureError`; see Changed.
+- **`StandardSingpass::Myinfo::EcdhJwe.encrypt`** — use `StandardSingpass::Testing::EcdhJwe.encrypt`; see Changed.
+
+### Fixed
+
+- **An unsupported JWE `enc` now raises `StandardSingpass::Myinfo::DecryptionError`.** `EcdhJwe::InvalidAlgorithm` (a bare `StandardError`) used to escape `Security.decrypt_jwe`, bypassing every `rescue StandardSingpass::Myinfo::Error` in a host.
+
+### Documentation
+
+- **README:** new "Instrumentation" and "Development and testing" sections (running the suite, mock-mode personas, the test-only JWE encryptor); the configuration example sets `c.scope` explicitly and notes the top-level `StandardSingpass.configure` alias and lazy JWKS parsing; the error section documents `StandardSingpass::Error` and the deprecated `Security` aliases.
+- **Install generator** sets `c.scope` to an explicit list and drops the "set `private_jwks_json` last" advice.
+
+## [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,19 @@ 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).
-  # c.scope = "openid name email ..."
+  # MyInfo scope: set it explicitly to the attributes approved for your app
+  # on the Singpass developer portal. The gem's default is only the minimal
+  # identity set ("openid uinfin name"); which attributes you collect is a
+  # host decision (PDPA Purpose Limitation), not the gem's.
+  c.scope = "openid uinfin name email mobileno regadd"
 
   # 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 +65,37 @@ StandardSingpass::Myinfo.configure do |c|
 end
 ```
 
+`StandardSingpass.configure` / `StandardSingpass.config` are equivalent top-level aliases, matching the other `standard_*` gems.
+
+`private_jwks_json` is parsed lazily — on first use, or at the end of boot (the engine resolves it from `after_initialize`, next to the mock-mode guard) — so assignments inside the block can come in any order.
+
+## 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
@@ -163,7 +205,7 @@ render json: StandardSingpass::Myinfo.public_jwks
 
 ## Error classes
 
-All errors descend from `StandardSingpass::Myinfo::Error`:
+All errors descend from `StandardSingpass::Myinfo::Error`, which in turn descends from the gem-wide `StandardSingpass::Error`:
 
 - `AuthenticationError` — ID token or token exchange rejected
 - `ApiError` — endpoint reachable but returned a non-2xx response
@@ -173,6 +215,8 @@ All errors descend from `StandardSingpass::Myinfo::Error`:
 - `RateLimitError` — Singpass returned HTTP 429
 - `ConfigurationError` — gem is misconfigured (e.g. invalid ACR URN)
 
+`Security` raises `DecryptionError` / `SignatureError` directly. The pre-0.4.0 `Security::DecryptionError` / `Security::ValidationError` constants are deprecated aliases of those two classes.
+
 `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:
@@ -197,6 +241,69 @@ This covers every leg — PAR, token exchange, userinfo, and the JWKS fetches th
 
 **Never classify by matching the message text** — it is not a stable interface. That is exactly what `transport?` and `status` exist to replace.
 
+## Instrumentation
+
+The client emits [`ActiveSupport::Notifications`](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) events, one per leg of the flow:
+
+| Event | When |
+| --- | --- |
+| `standard_singpass.par` | Pushed Authorization Request |
+| `standard_singpass.token` | Token exchange |
+| `standard_singpass.userinfo` | Userinfo fetch, decrypt, and verify (spans all retry attempts) |
+| `standard_singpass.retry` | Each automatic userinfo retry, just before the backoff sleep |
+
+`par` / `token` / `userinfo` payloads:
+
+- `duration` — wall time in milliseconds (Float)
+- `status` — HTTP status of the (last) Singpass response, or `nil` when none arrived
+- `error` — class name of the raised error, or `nil` on success (the error is re-raised as usual)
+- `transport` — `true` when Singpass was never reached
+- `attempts` — (`userinfo` only) attempts made, including retries
+
+`retry` payloads: `leg` (`:userinfo`), `attempt` (the attempt that failed), `status`, `error`, `delay` (seconds about to be slept).
+
+Payloads are deliberately PII-free: no tokens, authorization codes, response bodies, URLs, or error messages — only the class name. ActiveSupport's own `:exception` / `:exception_object` keys (which would carry the message) are not added.
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\Astandard_singpass\./) do |event|
+  StatsD.distribution("singpass.#{event.name.delete_prefix("standard_singpass.")}",
+                      event.payload[:duration] || 0,
+                      tags: { status: event.payload[:status], error: event.payload[:error] })
+end
+```
+
+## Development and testing
+
+```sh
+bundle install
+bundle exec rspec          # full suite (boots spec/dummy, WebMock blocks outbound HTTP)
+bin/rubocop                # style
+bundle exec srb tc         # Sorbet typecheck — keep it green
+```
+
+`lefthook install` wires the pre-push checks (rubocop, brakeman, rspec, signed-commit verification).
+
+### Testing a host app against the gem
+
+- **Mock mode + personas.** Set `c.mock_mode = true` (never on production — see [Mock mode](#mock-mode)) and drive your mock callback with `StandardSingpass::Myinfo::TestPersonas.fetch(key)`, then `PersonDataParser.call(persona)`. Bundled keys: `default`, `self_employed`, `tamil_name`, `permanent_resident`, `sparse_data`, `fin_holder`, `work_permit_holder`, `error_paths`, `duplicate_check`. Point `c.personas_path` at your own JSON file to maintain your own set.
+- **End-to-end crypto.** To exercise the real decrypt + verify path, build the encrypted payloads Singpass would send with the test-only encryptor:
+
+  ```ruby
+  # spec/rails_helper.rb
+  require "standard_singpass/testing"
+
+  jwe = StandardSingpass::Testing::EcdhJwe.encrypt(
+    signed_jws,
+    public_key: enc_key,          # OpenSSL::PKey::EC matching your "enc" JWK
+    alg: "ECDH-ES+A256KW",
+    enc: "A256GCM",
+    kid: "your-enc-kid"
+  )
+  ```
+
+  `standard_singpass/testing` is not loaded by `require "standard_singpass"`. The old `StandardSingpass::Myinfo::EcdhJwe.encrypt` still works but is deprecated.
+- **Specs that mutate configuration** should call `StandardSingpass::Myinfo.reset_configuration!` afterwards.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/fixtures/myinfo-personas.json

@@ -220,6 +220,38 @@
     }
   },
 
+  "work_permit_holder": {
+    "name": { "value": "MD RAHMAN HASAN" },
+    "uinfin": { "value": "G6543210T" },
+    "dob": { "value": "1992-03-15" },
+    "sex": { "code": "M", "desc": "MALE" },
+    "race": { "code": "OT", "desc": "OTHERS" },
+    "nationality": { "code": "BD", "desc": "BANGLADESHI" },
+    "residentialstatus": { "code": "F", "desc": "FOREIGNER" },
+    "passtype": { "code": "RPass", "desc": "Work Permit" },
+    "passstatus": { "code": "LIVE", "desc": "LIVE" },
+    "passexpirydate": { "value": "2027-02-28" },
+    "employmentsector": { "code": "CONSTRUCTION", "desc": "CONSTRUCTION" },
+    "employment": { "value": "BUILDRIGHT CONSTRUCTION PTE LTD" },
+    "occupation": { "code": "9312", "desc": "CONSTRUCTION LABOURER" },
+    "marital": { "code": "1", "desc": "SINGLE" },
+    "email": { "value": "rahman.hasan@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "98771234" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "12" },
+      "street": { "value": "TUAS SOUTH AVENUE 3" },
+      "floor": { "value": "01" },
+      "unit": { "value": "05" },
+      "postal": { "value": "637601" },
+      "country": { "code": "SG" }
+    }
+  },
+
   "error_paths": {
     "name": { "value": "ONG WEI MING" },
     "uinfin": { "value": "S8345678F" },
@@ -246,5 +278,32 @@
       "country": { "code": "SG" }
     },
     "employment": { "value": "EMPLOYED" }
+  },
+  "duplicate_check": {
+    "name": { "value": "DUPLICATE CHECK TESTER" },
+    "uinfin": { "value": "S7777777J" },
+    "dob": { "value": "1990-01-01" },
+    "sex": { "code": "M", "desc": "MALE" },
+    "race": { "code": "CN", "desc": "CHINESE" },
+    "nationality": { "code": "SG", "desc": "SINGAPORE CITIZEN" },
+    "residentialstatus": { "code": "C", "desc": "CITIZEN" },
+    "marital": { "code": "1", "desc": "SINGLE" },
+    "edulevel": { "code": "7", "desc": "BACHELOR'S OR EQUIVALENT" },
+    "email": { "value": "dup-check@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "97777777" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "1" },
+      "street": { "value": "DUPLICATE LANE" },
+      "floor": { "value": "01" },
+      "unit": { "value": "01" },
+      "postal": { "value": "100001" },
+      "country": { "code": "SG" }
+    },
+    "employment": { "value": "EMPLOYED" }
   }
 }

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

@@ -13,11 +13,9 @@
 #
 # Optional environment variables:
 #
-#   MYINFO_SCOPE             Space-separated scopes (defaults to DEFAULT_SCOPE)
+#   MYINFO_SCOPE             Space-separated scopes (overrides the list below)
 #   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
@@ -33,15 +31,36 @@ StandardSingpass::Myinfo.configure do |c|
   c.client_id    = ENV["MYINFO_CLIENT_ID"]
   c.redirect_url = ENV["MYINFO_REDIRECT_URL"]
 
-  c.scope = ENV.fetch("MYINFO_SCOPE", StandardSingpass::Myinfo::Configuration::DEFAULT_SCOPE)
+  # MyInfo scope — set this explicitly. It must match (or be a subset of) the
+  # attributes approved for your app on the Singpass developer portal, and
+  # which attributes you collect is your decision to justify under PDPA
+  # (Purpose Limitation). The gem's own default is only the minimal identity
+  # set ("openid uinfin name"). One scope per line keeps diffs against the
+  # portal's approval list reviewable.
+  app_scope = %w[
+    openid
+    uinfin
+    name
+  ].join(" ").freeze
+
+  c.scope = ENV.fetch("MYINFO_SCOPE", app_scope)
 
   # Endpoint overrides — only set if you're running against a non-standard
   # Singpass sandbox or mocked service.
   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
@@ -61,7 +80,7 @@ StandardSingpass::Myinfo.configure do |c|
   # c.network_wrapper = ->(&block) { StandardCircuit.run(:myinfo, &block) }
 
   # Required: full JWKS JSON containing both sig (ES256) and enc
-  # (ECDH-ES+A256KW) keys with the private scalar `d`. Set last so any
-  # missing-key warnings the gem logs include the rest of the context.
+  # (ECDH-ES+A256KW) keys with the private scalar `d`. Parsed lazily (at the
+  # end of boot, or on first use), so it can be assigned in any order.
   c.private_jwks_json = ENV["MYINFO_PRIVATE_JWKS"]
 end

data/lib/standard_singpass/engine.rb

@@ -6,17 +6,27 @@
 # only meaningful inside a Rails host anyway.
 if defined?(::Rails::Engine)
   module StandardSingpass
+    # Library-only engine: no routes, models, controllers, or views, so no
+    # `isolate_namespace` (dropped in 0.4.0 — it only matters for engines
+    # that ship app/ code or mountable routes). It exists for the rake tasks
+    # and the boot-time hooks below.
     class Engine < ::Rails::Engine
-      isolate_namespace StandardSingpass
+      initializer "standard_singpass.deprecator" do |app|
+        app.deprecators[:standard_singpass] = StandardSingpass.deprecator if app.respond_to?(:deprecators)
+      end
 
       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.
+      # Runs after the host's own initializers (and its `to_prepare`
+      # blocks), so the whole configure block has run by the time either is
+      # read. The guard is inert unless mock mode is on; resolving the
+      # private JWKS here surfaces missing/malformed-key warnings at boot
+      # rather than on the first Singpass request.
       config.after_initialize do
         StandardSingpass::Myinfo::MockModeGuard.check!
+        StandardSingpass::Myinfo.configuration.resolve_private_jwks!
       end
     end
   end

data/lib/standard_singpass/error.rb

@@ -0,0 +1,9 @@
+# typed: strict
+
+module StandardSingpass
+  # Root of every error the gem raises, across products. Hosts that want one
+  # `rescue` for "anything standard_singpass raised" rescue this;
+  # `StandardSingpass::Myinfo::Error` (which carries `status` / `transport?`)
+  # descends from it.
+  class Error < StandardError; end
+end