standard_singpass 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 35e2fb1210199ace98e5db77de85e6a3650ee9297bffd8f8a0f2d16f743cba8e
4
- data.tar.gz: 594ff25cfe621eb103dc397889b91a21cb49316b23ba6b2e849d42f5046a5a33
3
+ metadata.gz: 39d9ad3d92728ff9057d396b688bebede81e5d08266f30bba35e3437b05044ab
4
+ data.tar.gz: 07467656b4460657c14dbbfb8db2a91ca0e6554953f522985c194237e8a610de
5
5
  SHA512:
6
- metadata.gz: '008b3123acb642f298caf073931dfd5778645dea026cdd3baf99045d4cb46caa74834d77cee80861042dee89d8a454d58717f39c20dc3bd2746c319716157726'
7
- data.tar.gz: d93185d6bb749e2413d8181f35b6383863fa95afe78642c4d6548b92bcf7f441fc8d9a0ba0a440e6f7c954883ffc4736b2684025e68b6cf4dceaae37c65882ac
6
+ metadata.gz: 8c756307402b1686d9ecabc9da82aabeef9305f2f66b7c7f341e8a72aebc4d622054d3ba7f935738e69ccca92940430efe6d2b2689dff1b89b93d0aab58e5d5e
7
+ data.tar.gz: 8d59436e01dc41fef288c31c8c6fe5ac7c3b4add2e4f530b9877751da02776a4872e92588394fe1e6ee5e51af880fd8ccbd9e7be8f15d7b475ffdbeec6ae352c
data/CHANGELOG.md CHANGED
@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.8.0] - 2026-11-23
11
+
12
+ ### Added
13
+ - **`config.error_reporter`** on `StandardSingpass::Myinfo::Configuration`: an
14
+ optional callable `(error, context)` receiving the errors the gem handles
15
+ without raising (a malformed private JWKS, an unconvertible JWK, a key
16
+ `public_jwks` cannot load, mock mode on a production-like deploy). nil (the
17
+ default) keeps the current `Rails.error.report(error, handled: true,
18
+ context:)`, so nothing changes unless a host sets it. All four sites now go
19
+ through one helper, `Configuration#report_error`, with their context keys
20
+ unchanged. A reporter that raises is logged and ignored.
21
+
22
+ ### Changed
23
+ - `public_jwks` key-load failures are now reported (through `error_reporter`)
24
+ even when Rails is not loaded, if a reporter is set; logging still needs
25
+ Rails.
26
+
27
+ ### Documentation
28
+ - README: an "Error reporting" section, and a recommended app-side
29
+ standard_health `env_spec` snippet for the `MYINFO_*` variables. The gem
30
+ reads none of them itself (only `APP_ENVIRONMENT`), so it contributes no env
31
+ declarations to standard_health.
32
+
10
33
  ## [0.7.0] - 2026-10-25
11
34
 
12
35
  ### Changed
data/README.md CHANGED
@@ -63,6 +63,10 @@ StandardSingpass::Myinfo.configure do |c|
63
63
  # the mock-mode guard. Defaults to APP_ENVIRONMENT (failing closed), then
64
64
  # Rails.env.production? — see "Mock mode" below.
65
65
  # c.production_env_detector = -> { ... }
66
+
67
+ # Optional: where the gem sends the errors it handles without raising (see
68
+ # "Error reporting" below). Defaults to Rails.error.report.
69
+ # c.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
66
70
  end
67
71
  ```
68
72
 
@@ -70,6 +74,72 @@ end
70
74
 
71
75
  `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.
72
76
 
77
+ ## Error reporting
78
+
79
+ Some failures are handled rather than raised, so the host still boots and the
80
+ operator still hears about them:
81
+
82
+ | Source | `context[:component]` | `context[:reason]` (and other keys) |
83
+ |---|---|---|
84
+ | Malformed `private_jwks_json` | `StandardSingpass::Myinfo::Configuration` | `parse_private_jwks` |
85
+ | A JWK that cannot be converted to a private key | `StandardSingpass::Myinfo::Configuration` | `jwk_to_private_pem` (`role`, `kid`) |
86
+ | A configured key `public_jwks` cannot load | `StandardSingpass::Myinfo` | `build_public_jwks_signing` / `build_public_jwks_encryption` (`kid`) |
87
+ | Mock mode on a production-like deploy | `StandardSingpass::Myinfo::MockModeGuard` | `mock_mode_on_production_like_deploy` |
88
+
89
+ Each goes to `config.error_reporter`, a callable taking `(error, context)`. When
90
+ it is nil (the default) the gem calls `Rails.error.report(error, handled: true,
91
+ context: context)`, which reaches Sentry only when a `Rails.error` subscriber is
92
+ registered (sentry-rails registers one). A host that never forwards
93
+ `Rails.error` can point it straight at its tracker:
94
+
95
+ ```ruby
96
+ c.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
97
+ ```
98
+
99
+ It replaces the `Rails.error` call; call `Rails.error.report` from it too if you
100
+ want both. A reporter that raises is logged and ignored, so it can never turn a
101
+ handled error into a raised one or fail boot. Errors the gem raises
102
+ (`StandardSingpass::Myinfo::Error` and its subclasses) are not reported; the
103
+ caller owns them.
104
+
105
+ ## Environment variables and StandardHealth
106
+
107
+ The gem reads no environment variable of its own apart from the estate-wide
108
+ `APP_ENVIRONMENT` (see [Mock mode](#mock-mode)). Credentials and toggles reach it
109
+ through `StandardSingpass::Myinfo.configure`, and the install generator maps the
110
+ conventional `MYINFO_*` names there. So the gem contributes nothing to
111
+ standard_health's env audit: the app owns those names and should declare them.
112
+ With [standard_health](https://github.com/rarebit-one/standard_health), add
113
+ them to the app's `env_spec`, adjusting the `in:` lists to your deploy
114
+ environments:
115
+
116
+ ```ruby
117
+ # config/initializers/standard_health.rb, inside StandardHealth.configure
118
+ c.env_spec = StandardHealth::EnvSpec.define do
119
+ # ...your other declarations...
120
+ group "Singpass / MyInfo" do
121
+ required :MYINFO_CLIENT_ID, in: %w[staging production],
122
+ description: "Singpass developer-portal client id",
123
+ consumed_by: "config/initializers/standard_singpass.rb"
124
+ required :MYINFO_REDIRECT_URL, in: %w[staging production],
125
+ description: "Callback URL registered with Singpass",
126
+ consumed_by: "config/initializers/standard_singpass.rb"
127
+ required :MYINFO_PRIVATE_JWKS, in: %w[production],
128
+ description: "Private JWKS with the ES256 signing and ECDH-ES+A256KW encryption keys",
129
+ consumed_by: "config/initializers/standard_singpass.rb"
130
+ # Mock mode on production already fails boot (MockModeGuard); this row
131
+ # makes a mis-set variable visible in the audit as well.
132
+ forbidden :MYINFO_MOCK_MODE, in: %w[production],
133
+ description: "Serves fixture personas instead of the real Singpass flow",
134
+ consumed_by: "config/initializers/standard_singpass.rb"
135
+ end
136
+ end
137
+ ```
138
+
139
+ `MYINFO_SCOPE`, `MYINFO_USERINFO_URL` and `MYINFO_USERINFO_JWKS_URL` are
140
+ optional overrides in the generated initializer; declare them only if your app
141
+ relies on them.
142
+
73
143
  ## Assurance level (`minimum_acr`)
74
144
 
75
145
  `config.minimum_acr` is an optional, **client-side** check. When set to a
@@ -112,7 +182,7 @@ opt-out — a guard you can forget to wire is a guard that isn't there.
112
182
  | Deploy | Mock mode on | Behaviour |
113
183
  |---|---|---|
114
184
  | Production | yes | **Raises `ConfigurationError` — the app refuses to boot.** |
115
- | `RAILS_ENV=production` but not production | yes | Logs an error and reports via `Rails.error`; boots. |
185
+ | `RAILS_ENV=production` but not production | yes | Logs an error and reports via `config.error_reporter` (default `Rails.error`); boots. |
116
186
  | Anything else | yes | Silent. |
117
187
  | Any | no | Silent. |
118
188
 
@@ -127,8 +197,9 @@ with no extra wiring.
127
197
 
128
198
  `config.production_env_detector` (a callable taking no arguments, returning a
129
199
  boolean) overrides that, for a host with a different discriminator. The
130
- production-like tier reports through `Rails.error` rather than a specific error
131
- tracker, so whatever the host has subscribed (Sentry included) picks it up.
200
+ production-like tier reports through [`config.error_reporter`](#error-reporting),
201
+ which defaults to `Rails.error` rather than a specific error tracker, so
202
+ whatever the host has subscribed (Sentry included) picks it up.
132
203
 
133
204
  ## Initiating the flow
134
205
 
@@ -29,6 +29,9 @@
29
29
  # c.production_env_detector - Callable returning whether this deploy is real
30
30
  # production; defaults to Rails.env.production?
31
31
  # c.personas_path - Pathname to JSON file of test personas
32
+ # c.error_reporter - Callable `(error, context)` receiving the errors
33
+ # the gem handles without raising; defaults to
34
+ # Rails.error.report
32
35
  # c.authorize_url, c.par_url, c.token_url, c.userinfo_url,
33
36
  # c.jwks_url, c.userinfo_jwks_url, c.issuer
34
37
  # - Override individual endpoints (rarely needed)
@@ -92,6 +95,24 @@ module StandardSingpass
92
95
  # while still refusing to boot on real production.
93
96
  attr_accessor :production_env_detector
94
97
 
98
+ # Where the gem sends the errors it handles without raising: a malformed
99
+ # private JWKS, an unloadable JWK, a key `public_jwks` cannot load, and
100
+ # mock mode on a production-like deploy (MockModeGuard). A callable
101
+ # taking `(error, context)`, where context is a Hash such as
102
+ # `{ component: "StandardSingpass::Myinfo::Configuration", reason: "parse_private_jwks" }`.
103
+ #
104
+ # nil (the default) means `Rails.error.report(error, handled: true,
105
+ # context: context)`, which reaches Sentry only when a `Rails.error`
106
+ # subscriber is registered (sentry-rails registers one). A host that
107
+ # never forwards Rails.error can point this straight at its tracker:
108
+ #
109
+ # c.error_reporter = ->(error, context) { Sentry.capture_exception(error, extra: context) }
110
+ #
111
+ # It replaces the Rails.error call; call `Rails.error.report` from it too
112
+ # if you want both. A reporter that raises is logged and ignored, so it
113
+ # can never turn a handled error into a raised one (or fail boot).
114
+ attr_accessor :error_reporter
115
+
95
116
  def initialize
96
117
  self.environment = :staging
97
118
  @scope = DEFAULT_SCOPE
@@ -103,6 +124,7 @@ module StandardSingpass
103
124
  @network_wrapper = ->(&block) { block.call }
104
125
  @mock_mode = false
105
126
  @production_env_detector = nil
127
+ @error_reporter = nil
106
128
  end
107
129
 
108
130
  def environment=(env)
@@ -180,6 +202,21 @@ module StandardSingpass
180
202
  self
181
203
  end
182
204
 
205
+ # @api private: the one place the gem reports an error it handles.
206
+ # Calls `error_reporter` when set, otherwise `Rails.error.report(error,
207
+ # handled: true, context:)` when Rails.error exists. Returns nil.
208
+ def report_error(error, context)
209
+ if error_reporter
210
+ error_reporter.call(error, context)
211
+ elsif defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
212
+ ::Rails.error.report(error, handled: true, context:)
213
+ end
214
+ nil
215
+ rescue => e
216
+ log(:error, "error reporting failed: #{e.class}: #{e.message}")
217
+ nil
218
+ end
219
+
183
220
  private
184
221
 
185
222
  def parse_private_jwks(jwks_json)
@@ -247,7 +284,7 @@ module StandardSingpass
247
284
  mock_mode || (defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.test?)
248
285
  end
249
286
 
250
- # Rails.logger / Rails.error are optional: the gem can be loaded (and a
287
+ # Rails.logger is optional: the gem can be loaded (and a
251
288
  # Configuration built) outside a booted Rails app — tooling, plain Ruby
252
289
  # scripts, or before the logger is assigned.
253
290
  def log(level, message)
@@ -256,8 +293,7 @@ module StandardSingpass
256
293
  end
257
294
 
258
295
  def report(error, reason:, **context)
259
- return unless defined?(::Rails) && ::Rails.respond_to?(:error)
260
- ::Rails.error.report(error, handled: true, context: { component: "StandardSingpass::Myinfo::Configuration", reason:, **context })
296
+ report_error(error, { component: "StandardSingpass::Myinfo::Configuration", reason:, **context })
261
297
  end
262
298
 
263
299
 
@@ -93,8 +93,9 @@ module StandardSingpass
93
93
  # per the detector) — staging, preview, a review app. Mock mode can be
94
94
  # intentional here, so this boots; it is reported rather than raised.
95
95
  #
96
- # Reported through `Rails.error` rather than a specific error tracker so
97
- # whatever the host has subscribed (Sentry included) picks it up.
96
+ # Reported through `config.error_reporter`, which defaults to
97
+ # `Rails.error` rather than a specific error tracker so whatever the host
98
+ # has subscribed (Sentry included) picks it up.
98
99
  sig { void }
99
100
  def self.report_production_like
100
101
  message = "StandardSingpass::Myinfo mock_mode is enabled on a " \
@@ -104,12 +105,9 @@ module StandardSingpass
104
105
 
105
106
  ::Rails.logger&.error("StandardSingpass::Myinfo: #{message}")
106
107
 
107
- return unless defined?(::Rails.error)
108
-
109
- ::Rails.error.report(
108
+ StandardSingpass::Myinfo.configuration.report_error(
110
109
  ConfigurationError.new(message),
111
- handled: true,
112
- context: {
110
+ {
113
111
  component: "StandardSingpass::Myinfo::MockModeGuard",
114
112
  reason: "mock_mode_on_production_like_deploy"
115
113
  }
@@ -78,9 +78,8 @@ module StandardSingpass
78
78
  end
79
79
 
80
80
  def log_and_report(error, message, reason:, kid:)
81
- return unless defined?(::Rails)
82
- ::Rails.logger&.error("StandardSingpass::Myinfo: #{message}") if ::Rails.respond_to?(:logger)
83
- ::Rails.error.report(error, handled: true, context: { component: "StandardSingpass::Myinfo", reason:, kid: }) if ::Rails.respond_to?(:error)
81
+ ::Rails.logger&.error("StandardSingpass::Myinfo: #{message}") if defined?(::Rails) && ::Rails.respond_to?(:logger)
82
+ configuration.report_error(error, { component: "StandardSingpass::Myinfo", reason:, kid: })
84
83
  end
85
84
  end
86
85
  end
@@ -1,3 +1,3 @@
1
1
  module StandardSingpass
2
- VERSION = "0.7.0"
2
+ VERSION = "0.8.0"
3
3
  end
metadata CHANGED
@@ -1,10 +1,10 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: standard_singpass
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.7.0
4
+ version: 0.8.0
5
5
  platform: ruby
6
6
  authors:
7
- - Jaryl Sim
7
+ - Rarebit One
8
8
  bindir: bin
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
@@ -196,7 +196,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
196
196
  - !ruby/object:Gem::Version
197
197
  version: '0'
198
198
  requirements: []
199
- rubygems_version: 4.0.10
199
+ rubygems_version: 4.0.20
200
200
  specification_version: 4
201
201
  summary: Singpass MyInfo (and future Singpass Sign-In) client for Rails apps.
202
202
  test_files: []