standard_singpass 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbda49a3c31fd6844db0d58c66c0bf1c8654882d37105c58dd1537a2e2cb13c5
-  data.tar.gz: 5b4ebd78e72bab8b36a2d8d5c298cc8f99e277c018b23a5b42ff7dfb4030292e
+  metadata.gz: b337f846e33125912e93e3819ad6ab9858dea86f6f2976f821650cd41eda5f2d
+  data.tar.gz: d655d89457c6a8120223dec9c266945ef03601dc79d82268e9ea5149fe7de75b
 SHA512:
-  metadata.gz: 47d70dda7f2948b55b59afac864885452e776aefe9e8806a16e62f31b9ca02bc6a8772e5eff7849b25ca3a8805487d45ea3c63a77412a713ba3c7b11f6e7f3e1
-  data.tar.gz: cd7b80ae5bea3214b3d1bb146801c673fe2934b8b245865ef7bd61dee8952a0d2f5dd670f24c08e925fb083fb6e8debe1901ad2ce9fcee57b8fe9174cff503af
+  metadata.gz: 0ccefce8b78a9ad7ef3213738a6266b544241c18e99ce645aa0de0bb1f6067f5bda79f793ee048757c4763cd1f990779649bc86c3d506849c5e3d7cfc19a0290
+  data.tar.gz: 6fb74b23e6fdf75e2191d7eecc76a45969aac95f6d5dd8383572b563299c15b1013dd2199c2816189248713452f0043c861c74cf9e14d33504357226a3b1f1e7

data/CHANGELOG.md

@@ -7,6 +7,49 @@ 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

data/README.md

@@ -33,10 +33,11 @@ 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 42 scopes — `openid` plus 41
-  # MyInfo attributes 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`.
@@ -64,6 +65,10 @@ 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
@@ -200,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
@@ -210,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:
@@ -234,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,7 +13,7 @@
 #
 # 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_MOCK_MODE         When set, suppresses missing-key warnings and
@@ -31,7 +31,19 @@ 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.
@@ -68,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

data/lib/standard_singpass/myinfo/client.rb

@@ -72,20 +72,23 @@ module StandardSingpass
         # (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|
-            req.headers["DPoP"] = Security.build_dpop_proof(
-              http_method: "POST",
-              url: T.must(@par_url),
-              key_pair: dpop_key_pair
-            )
-            req.headers["Content-Type"] = "application/x-www-form-urlencoded"
-            req.body = URI.encode_www_form(body)
+        instrument(:par) do |payload|
+          with_network_wrapper do
+            response = http_connection.post(@par_url) do |req|
+              req.headers["DPoP"] = Security.build_dpop_proof(
+                http_method: "POST",
+                url: T.must(@par_url),
+                key_pair: dpop_key_pair
+              )
+              req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+              req.body = URI.encode_www_form(body)
+            end
+            payload[:status] = response.status
+            handle_par_response(response)
           end
-          handle_par_response(response)
+        rescue Faraday::Error => e
+          raise PARError.new("PAR endpoint unreachable: #{e.class}", transport: true)
         end
-      rescue Faraday::Error => e
-        raise PARError.new("PAR endpoint unreachable: #{e.class}", transport: true)
       end
 
       sig { params(request_uri: String).returns(String) }
@@ -151,20 +154,23 @@ module StandardSingpass
           )
         }
 
-        with_network_wrapper do
-          response = http_connection.post(@token_url) do |req|
-            req.headers["DPoP"] = Security.build_dpop_proof(
-              http_method: "POST",
-              url: T.must(@token_url),
-              key_pair: dpop_key_pair
-            )
-            req.headers["Content-Type"] = "application/x-www-form-urlencoded"
-            req.body = URI.encode_www_form(body)
+        instrument(:token) do |payload|
+          with_network_wrapper do
+            response = http_connection.post(@token_url) do |req|
+              req.headers["DPoP"] = Security.build_dpop_proof(
+                http_method: "POST",
+                url: T.must(@token_url),
+                key_pair: dpop_key_pair
+              )
+              req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+              req.body = URI.encode_www_form(body)
+            end
+            payload[:status] = response.status
+            handle_token_response(response)
           end
-          handle_token_response(response)
+        rescue Faraday::Error => e
+          raise ApiError.new("MyInfo token endpoint unreachable: #{e.class}", transport: true)
         end
-      rescue Faraday::Error => e
-        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]) }
@@ -173,24 +179,27 @@ module StandardSingpass
         # 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
-          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:
-              )
+        instrument(:userinfo) do |payload|
+          with_network_wrapper do
+            with_userinfo_retries(payload) 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
+              payload[:status] = response.status
+              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.new("MyInfo userinfo endpoint unreachable: #{e.class}", transport: true)
         end
-      rescue Faraday::Error => e
-        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]) }
@@ -220,9 +229,9 @@ module StandardSingpass
 
         decrypted = Security.decrypt_jwe(id_token, private_keys: @encryption_keys)
         Security.validate_jws(decrypted, jwks_url: T.must(@jwks_url))
-      rescue Security::DecryptionError
+      rescue DecryptionError
         raise AuthenticationError, "ID token decryption failed"
-      rescue Security::ValidationError => e
+      rescue SignatureError => 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.
@@ -406,17 +415,26 @@ module StandardSingpass
       # 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)
+      #
+      # Each retry emits a `standard_singpass.retry` notification; the
+      # enclosing `standard_singpass.userinfo` payload records `attempts`.
+      sig { params(payload: T::Hash[Symbol, T.untyped], block: T.proc.returns(T::Hash[String, T.untyped])).returns(T::Hash[String, T.untyped]) }
+      def with_userinfo_retries(payload, &block)
         attempt = 0
         begin
           attempt += 1
+          payload[:attempts] = attempt
           block.call
         rescue ApiError => e
           raise unless RETRYABLE_USERINFO_STATUSES.include?(e.status)
           raise if attempt >= USERINFO_MAX_ATTEMPTS
 
-          sleep(userinfo_retry_delay(attempt))
+          delay = userinfo_retry_delay(attempt)
+          ActiveSupport::Notifications.instrument(
+            "standard_singpass.retry",
+            leg: :userinfo, attempt:, status: e.status, error: e.class.name, delay:
+          )
+          sleep(delay)
           retry
         end
       end
@@ -463,15 +481,13 @@ module StandardSingpass
         "(non-JSON body, #{body.bytesize} bytes)"
       end
 
+      # Security raises the public DecryptionError / SignatureError directly
+      # (SignatureError carrying the JWKS response's status / transport?), so
+      # there is nothing to translate on the userinfo leg.
       sig { params(jwe_body: String, jwks_url: T.nilable(String)).returns(T::Hash[String, T.untyped]) }
       def decrypt_and_validate_person(jwe_body, jwks_url:)
         decrypted = Security.decrypt_jwe(jwe_body, private_keys: @encryption_keys)
         Security.validate_jws(decrypted, jwks_url: T.must(jwks_url))
-      rescue Security::DecryptionError => e
-        raise DecryptionError, e.message
-      rescue Security::ValidationError => e
-        # 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 }
@@ -488,6 +504,48 @@ module StandardSingpass
         end
       end
 
+      # Emits `standard_singpass.<event>` via ActiveSupport::Notifications
+      # around one leg of the flow. The payload is deliberately PII-free:
+      #
+      #   :duration  — wall time in milliseconds (Float)
+      #   :status    — HTTP status of the (last) Singpass response, or nil
+      #   :error     — class name of the error raised, or nil on success
+      #   :transport — true when Singpass was never reached
+      #   :attempts  — (userinfo only) attempts made, including retries
+      #
+      # Never tokens, codes, bodies, URLs, or error messages. The error is
+      # captured inside the instrument block and re-raised outside it so
+      # ActiveSupport does not add its own `:exception` entry (which would
+      # carry the message) to the payload.
+      sig do
+        params(
+          event: Symbol,
+          block: T.proc.params(payload: T::Hash[Symbol, T.untyped]).returns(T.untyped)
+        ).returns(T.untyped)
+      end
+      def instrument(event, &block)
+        payload = T.let({ status: nil, error: nil, transport: false }, T::Hash[Symbol, T.untyped])
+        error = T.let(nil, T.nilable(Exception))
+        result = ActiveSupport::Notifications.instrument("standard_singpass.#{event}", payload) do
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          begin
+            block.call(payload)
+          rescue => e
+            error = e
+            payload[:error] = e.class.name
+            if e.is_a?(Error)
+              payload[:status] ||= e.status
+              payload[:transport] = e.transport?
+            end
+            nil
+          ensure
+            payload[:duration] = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+          end
+        end
+        raise error if error
+        result
+      end
+
       # Wraps the given block in the configured network_wrapper. Default is
       # the identity wrapper (no resilience). Hosts typically set this to a
       # circuit-breaker lambda. Scoped narrowly to the Faraday network call