standard_singpass 0.6.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 +4 -4
- data/CHANGELOG.md +34 -0
- data/README.md +74 -3
- data/lib/standard_singpass/myinfo/client.rb +12 -3
- data/lib/standard_singpass/myinfo/configuration.rb +39 -3
- data/lib/standard_singpass/myinfo/mock_mode_guard.rb +5 -7
- data/lib/standard_singpass/myinfo.rb +2 -3
- data/lib/standard_singpass/version.rb +1 -1
- metadata +3 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 39d9ad3d92728ff9057d396b688bebede81e5d08266f30bba35e3437b05044ab
|
|
4
|
+
data.tar.gz: 07467656b4460657c14dbbfb8db2a91ca0e6554953f522985c194237e8a610de
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 8c756307402b1686d9ecabc9da82aabeef9305f2f66b7c7f341e8a72aebc4d622054d3ba7f935738e69ccca92940430efe6d2b2689dff1b89b93d0aab58e5d5e
|
|
7
|
+
data.tar.gz: 8d59436e01dc41fef288c31c8c6fe5ac7c3b4add2e4f530b9877751da02776a4872e92588394fe1e6ee5e51af880fd8ccbd9e7be8f15d7b475ffdbeec6ae352c
|
data/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,40 @@ 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
|
+
|
|
33
|
+
## [0.7.0] - 2026-10-25
|
|
34
|
+
|
|
35
|
+
### Changed
|
|
36
|
+
|
|
37
|
+
- **`get_person_data` now requires a `nonce` by default.** Passing `nonce: nil` (or omitting it) raises
|
|
38
|
+
`StandardSingpass::Myinfo::ConfigurationError` with a clear message. The nonce binds the id_token to
|
|
39
|
+
the session and prevents replay attacks; PKCE + DPoP substantially raise the bar but do not fully close
|
|
40
|
+
the replay window without it. The only consumer, `fundbright-web`, already passes the nonce from the
|
|
41
|
+
session on every call, so it is unaffected. To opt out for flows where no nonce was included in the PAR
|
|
42
|
+
request, pass `skip_nonce_validation: true` — this is intentionally verbose so it stands out in review.
|
|
43
|
+
|
|
10
44
|
## [0.6.0] - 2026-10-22
|
|
11
45
|
|
|
12
46
|
### 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
|
|
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 `
|
|
131
|
-
|
|
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
|
|
|
@@ -101,10 +101,19 @@ module StandardSingpass
|
|
|
101
101
|
"#{@authorize_url}?#{URI.encode_www_form(params)}"
|
|
102
102
|
end
|
|
103
103
|
|
|
104
|
-
sig { params(auth_code: String, code_verifier: String, dpop_key_pair: OpenSSL::PKey::EC, nonce: T.nilable(String)).returns(T::Hash[Symbol, T.untyped]) }
|
|
105
|
-
def get_person_data(auth_code:, code_verifier:, dpop_key_pair:, nonce: nil)
|
|
104
|
+
sig { params(auth_code: String, code_verifier: String, dpop_key_pair: OpenSSL::PKey::EC, nonce: T.nilable(String), skip_nonce_validation: T::Boolean).returns(T::Hash[Symbol, T.untyped]) }
|
|
105
|
+
def get_person_data(auth_code:, code_verifier:, dpop_key_pair:, nonce: nil, skip_nonce_validation: false)
|
|
106
|
+
unless skip_nonce_validation
|
|
107
|
+
if nonce.blank?
|
|
108
|
+
raise ConfigurationError,
|
|
109
|
+
"nonce is required for id_token replay protection. " \
|
|
110
|
+
"Pass the nonce you sent in the PAR request. " \
|
|
111
|
+
"Only pass skip_nonce_validation: true for flows where no nonce was sent in the PAR request."
|
|
112
|
+
end
|
|
113
|
+
end
|
|
114
|
+
|
|
106
115
|
token_data = exchange_token(auth_code:, code_verifier:, dpop_key_pair:)
|
|
107
|
-
id_token_payload = validate_id_token(token_data[:id_token], nonce:)
|
|
116
|
+
id_token_payload = validate_id_token(token_data[:id_token], nonce: skip_nonce_validation ? nil : nonce)
|
|
108
117
|
|
|
109
118
|
person_data = fetch_userinfo(access_token: token_data[:access_token], dpop_key_pair:)
|
|
110
119
|
|
|
@@ -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
|
|
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
|
-
|
|
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 `
|
|
97
|
-
#
|
|
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
|
-
|
|
108
|
-
|
|
109
|
-
::Rails.error.report(
|
|
108
|
+
StandardSingpass::Myinfo.configuration.report_error(
|
|
110
109
|
ConfigurationError.new(message),
|
|
111
|
-
|
|
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
|
-
|
|
82
|
-
|
|
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
|
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.
|
|
4
|
+
version: 0.8.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
|
-
-
|
|
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.
|
|
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: []
|