standard_singpass 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8da1f0678a358ee51cf45c1f7b47f537e465f4d9c2ed738de7cdb2326fd92b49
+  data.tar.gz: cd6df85e85fe8d5a0636558b943f1cfadc5a5704eed15c7c52c367c2bf7ba974
+SHA512:
+  metadata.gz: 849a2c6e1de1e63c8092f2088ef5e8de12292d3b3e130c6a47831fa244def9dfe7cc854a82eff49d4863757423d4feb788f6d943345aa953c6007a85f91df549
+  data.tar.gz: 36da035a4471275f50a3a2e2c974f440ff337c45a34b43a4181da80187a283c40937bcc0724f20a52d8f9a22780d6af277aba3494739bdaa49ebe586a193caee

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-24
+
+### Added
+
+- `StandardSingpass::Myinfo::Client` — FAPI 2.0 OAuth client with PKCE, DPoP (RFC 9449), and `private_key_jwt` client assertion. Performs PAR, token exchange, ID-token validation (iss/aud/exp/iat/sub/acr/nonce), and userinfo fetch.
+- `StandardSingpass::Myinfo::Security` — PKCE/DPoP primitives, JWE decryption dispatch, JWS validation with JWKS caching and one-shot key-rotation retry.
+- `StandardSingpass::Myinfo::EcdhJwe` — native ECDH-ES+A128KW / +A256KW JWE implementation covering A128GCM, A256GCM, A128CBC-HS256, A256CBC-HS512. Exists because the `jwt` gem does not support ECDH-ES key agreement.
+- `StandardSingpass::Myinfo::PersonDataParser` — extracts 40+ structured fields (identity, contact, address, pass info, income, employment, assets, housing, vehicles) from FAPI 2.0 v5 userinfo responses, unwrapping the `person_info` envelope.
+- `StandardSingpass::Myinfo::JwksGenerator` — generates and validates the private JWKS document used for signing + ECDH-ES decryption keys. Includes a `standard_singpass:myinfo:generate_jwks` rake task.
+- `StandardSingpass::Myinfo::TestPersonas` — loader for the bundled persona fixture set used by mock-callback flows and RSpec helpers; host can override via `config.personas_path`.
+- `StandardSingpass::Myinfo::Configuration` — block-style config (`StandardSingpass::Myinfo.configure { |c| ... }`). Host passes `client_id`, `redirect_url`, `private_jwks_json`, optional `minimum_acr`, optional `network_wrapper` (e.g. circuit breaker), and `environment` (`:production` / `:staging` — picks Singpass endpoint URLs).
+- `rails generate standard_singpass:install` scaffolds `config/initializers/standard_singpass.rb` with the full configuration surface commented out. Idempotent; `--force` overwrites.
+- Full-flow integration spec at `spec/standard_singpass/myinfo/full_flow_spec.rb` walking PAR → token exchange → userinfo → JWE decrypt → JWS validate → parse end to end. Covers happy path, nonce mismatch, and the `minimum_acr` enforcement branch (LOA-3 floor + LOA-2 token → `AuthenticationError`).
+- `spec/standard_singpass/myinfo/configuration_spec.rb` covering the global `configure` / `public_jwks` paths and the private-JWKS parser (happy path, malformed JSON, public-only-key rejection).
+- Sorbet wired end to end: `bin/tapioca` shim, generated RBIs for runtime deps under `sorbet/rbi/gems/`, hand-edited shims for `OpenSSL::PKey::EC::Point#to_octet_string` and `Faraday.get`, `.github/workflows/typecheck.yml` running `bundle exec srb tc` on every PR, and `bundle exec srb tc` appended to the weekly-maintenance test commands so dependency-update PRs also catch type-sig breakage.
+- `AGENTS.md` — quick-reference doc for AI agents and human contributors. Public surface, error taxonomy, key workflows.
+- Bundled persona fixture at `fixtures/myinfo-personas.json`.
+- Productivity workflows: `.github/workflows/{claude.yml,claude-code-review.yml,weekly-maintenance.yml}` + `.github/dependabot.yml` (matches peer `standard_*` gem setup).
+
+### Notes
+
+- No Rails routes, models, or migrations — gem is library-only by design. The host owns persistence (e.g. a MyInfo record model), orchestration (callback handlers), forms, and UI.
+- `lib/standard_singpass/engine.rb` defers its `Rails::Engine` definition behind `if defined?(::Rails::Engine)` so the gem loads cleanly under `tapioca gems` and other no-Rails contexts. The host `Gemfile` should also list `gem "rails"` ahead of `gemspec` so `Bundler.require` loads Rails first.
+- Coverage sits at 95.26% line / 84.29% branch with a 90% line / 75% branch floor enforced via SimpleCov.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Jaryl Sim
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,116 @@
+# StandardSingpass
+
+Singpass MyInfo (FAPI 2.0) client for Rails applications. Packages the OAuth flow, DPoP/PKCE primitives, native ECDH-ES JWE decryption, JWS validation, and person-data parser needed to integrate with Singpass MyInfo.
+
+The gem is intentionally **library-only** — it does not own routes, models, migrations, or UI. The host application owns persistence, orchestration, forms, and presentation.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "standard_singpass"
+```
+
+## Configuration
+
+```ruby
+# config/initializers/standard_singpass.rb
+StandardSingpass::Myinfo.configure do |c|
+  # Endpoint set. Drives production vs. staging Singpass URLs.
+  c.environment = Rails.env.production? ? :production : :staging
+
+  # Client credentials.
+  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 ..."
+
+  # 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: wrap outbound HTTP calls with a circuit breaker / retry layer.
+  # Defaults to identity (no wrapper).
+  # c.network_wrapper = ->(&block) { StandardCircuit.run(:myinfo, &block) }
+
+  # Optional: path to a JSON file of test personas (for mock callback flows).
+  # Defaults to the gem's bundled fixtures/myinfo-personas.json.
+  # c.personas_path = Rails.root.join("e2e/fixtures/myinfo-personas.json")
+end
+```
+
+## Initiating the flow
+
+```ruby
+pkce       = StandardSingpass::Myinfo::Security.generate_pkce_pair
+dpop_key   = StandardSingpass::Myinfo::Security.generate_ephemeral_key_pair
+state      = SecureRandom.hex(16)
+nonce      = SecureRandom.hex(16)
+
+client = StandardSingpass::Myinfo::Client.new
+par    = client.push_authorization_request(
+  code_challenge: pkce[:code_challenge],
+  state:          state,
+  nonce:          nonce,
+  dpop_key_pair:  dpop_key
+)
+
+# Persist pkce[:code_verifier], state, nonce, and dpop_key in the user session.
+redirect_to client.build_authorize_redirect(request_uri: par[:request_uri])
+```
+
+## Handling the callback
+
+```ruby
+result = client.get_person_data(
+  auth_code:     params[:code],
+  code_verifier: session[:myinfo_code_verifier],
+  dpop_key_pair: session[:myinfo_dpop_key],
+  nonce:         session[:myinfo_nonce]
+)
+
+parsed = StandardSingpass::Myinfo::PersonDataParser.call(result[:person_data])
+acr    = result[:id_token_acr]
+
+# `parsed` is a 40+ key hash: nric, name, email, mobile_number,
+# registered_address, cpf_balances, noa, hdb_ownership, etc. Pass it to your
+# host-side persistence / projection layer.
+```
+
+## Generating and serving JWKS
+
+The host application is responsible for serving the public JWKS at
+`/.well-known/jwks.json` (or another endpoint Singpass is configured to fetch).
+
+```ruby
+# Generate a fresh private JWKS (run locally, never in CI):
+bin/rails standard_singpass:myinfo:generate_jwks > private-jwks.json
+
+# Serve the public JWKS from a controller:
+render json: StandardSingpass::Myinfo.public_jwks
+```
+
+## Error classes
+
+All errors descend from `StandardSingpass::Myinfo::Error`:
+
+- `AuthenticationError` — ID token or token exchange rejected
+- `ApiError` — endpoint reachable but returned a non-2xx response
+- `PARError` — pushed authorization request failed
+- `DecryptionError` — JWE decryption failed
+- `SignatureError` — JWS verification failed
+- `RateLimitError` — Singpass returned HTTP 429
+- `ConfigurationError` — gem is misconfigured (e.g. invalid ACR URN)
+
+`DecryptionError` and `SignatureError` indicate a key/cert misconfiguration, not an upstream outage — exclude them from circuit-breaker tracking if you use one.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/fixtures/myinfo-personas.json

@@ -0,0 +1,250 @@
+{
+  "default": {
+    "name": { "value": "TAN AH KOW" },
+    "uinfin": { "value": "S9812345A" },
+    "aliasname": { "value": "JOHN TAN" },
+    "dob": { "value": "1998-03-15" },
+    "sex": { "code": "M", "desc": "MALE" },
+    "race": { "code": "CN", "desc": "CHINESE" },
+    "nationality": { "code": "SG", "desc": "SINGAPORE CITIZEN" },
+    "residentialstatus": { "code": "C", "desc": "CITIZEN" },
+    "marital": { "code": "2", "desc": "MARRIED" },
+    "edulevel": { "code": "7", "desc": "BACHELOR'S OR EQUIVALENT" },
+    "email": { "value": "ahkow@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "91234567" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "123" },
+      "street": { "value": "BEDOK NORTH AVE 1" },
+      "floor": { "value": "05" },
+      "unit": { "value": "123" },
+      "postal": { "value": "460123" },
+      "country": { "code": "SG" }
+    },
+    "hdbtype": { "code": "112", "desc": "4-ROOM FLAT" },
+    "housingtype": { "code": "HDB", "desc": "HDB" },
+    "employment": { "value": "EMPLOYED" },
+    "occupation": { "code": "5223", "desc": "SALES SUPERVISOR" },
+    "ownerprivate": { "value": "N" },
+    "cpfbalances": {
+      "oa": { "value": "12500.00" }
+    },
+    "cpfcontributions": {
+      "history": [
+        { "employer": { "value": "ACME PTE LTD" }, "month": { "value": "2026-04" }, "amount": { "value": "1850.00" }, "date": { "value": "2026-04-15" } },
+        { "employer": { "value": "ACME PTE LTD" }, "month": { "value": "2026-03" }, "amount": { "value": "1850.00" }, "date": { "value": "2026-03-15" } }
+      ]
+    },
+    "cpfemployers": {
+      "history": [
+        { "employer": { "value": "ACME PTE LTD" }, "month": { "value": "2026-04" } }
+      ]
+    },
+    "noa-basic": {
+      "yearofassessment": { "value": "2025" },
+      "amount": { "value": "75000.00" }
+    },
+    "noahistory-basic": {
+      "noas": [
+        { "yearofassessment": { "value": "2024" }, "amount": { "value": "70000.00" } },
+        { "yearofassessment": { "value": "2023" }, "amount": { "value": "65000.00" } }
+      ]
+    },
+    "hdbownership": [
+      {
+        "noofowners": { "value": "2" },
+        "address": {
+          "block": { "value": "123" },
+          "street": { "value": "BEDOK NORTH AVE 1" },
+          "floor": { "value": "05" },
+          "unit": { "value": "123" },
+          "postal": { "value": "460123" },
+          "country": { "code": "SG" }
+        },
+        "hdbtype": { "code": "112" },
+        "loangranted": { "value": "300000" },
+        "balanceloanrepayment": { "value": "15" },
+        "outstandingloanbalance": { "value": "240000" },
+        "monthlyloaninstalment": { "value": "1800" },
+        "outstandinginstalment": { "value": "1800" }
+      }
+    ],
+    "vehicles": [
+      { "effectiveownership": { "value": "2024-06-15T00:00:00" } }
+    ]
+  },
+
+  "self_employed": {
+    "name": { "value": "LIM MEI LING" },
+    "uinfin": { "value": "S8567890B" },
+    "dob": { "value": "1985-11-22" },
+    "sex": { "code": "F", "desc": "FEMALE" },
+    "race": { "code": "CN", "desc": "CHINESE" },
+    "nationality": { "code": "SG", "desc": "SINGAPORE CITIZEN" },
+    "residentialstatus": { "code": "C", "desc": "CITIZEN" },
+    "marital": { "code": "1", "desc": "SINGLE" },
+    "edulevel": { "code": "5", "desc": "DIPLOMA OR EQUIVALENT" },
+    "email": { "value": "meiling@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "98765432" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "456" },
+      "street": { "value": "TAMPINES ST 21" },
+      "floor": { "value": "12" },
+      "unit": { "value": "456" },
+      "postal": { "value": "520456" },
+      "country": { "code": "SG" }
+    },
+    "employment": { "value": "SELF-EMPLOYED" }
+  },
+
+  "tamil_name": {
+    "name": { "value": "RAJ KUMAR S/O THIAGARAJAN" },
+    "uinfin": { "value": "S7234567C" },
+    "dob": { "value": "1972-06-08" },
+    "sex": { "code": "M", "desc": "MALE" },
+    "race": { "code": "IN", "desc": "INDIAN" },
+    "nationality": { "code": "SG", "desc": "SINGAPORE CITIZEN" },
+    "residentialstatus": { "code": "C", "desc": "CITIZEN" },
+    "marital": { "code": "2", "desc": "MARRIED" },
+    "edulevel": { "code": "8", "desc": "MASTER'S OR EQUIVALENT" },
+    "email": { "value": "rajkumar@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "92223344" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "789" },
+      "street": { "value": "SERANGOON GARDEN WAY" },
+      "floor": { "value": "03" },
+      "unit": { "value": "07" },
+      "postal": { "value": "555789" },
+      "country": { "code": "SG" }
+    },
+    "employment": { "value": "EMPLOYED" }
+  },
+
+  "permanent_resident": {
+    "name": { "value": "KIM SOO YOUNG" },
+    "uinfin": { "value": "G6543210D" },
+    "dob": { "value": "1990-09-03" },
+    "sex": { "code": "F", "desc": "FEMALE" },
+    "race": { "code": "OT", "desc": "OTHERS" },
+    "nationality": { "code": "KR", "desc": "KOREAN" },
+    "residentialstatus": { "code": "P", "desc": "PERMANENT RESIDENT" },
+    "marital": { "code": "1", "desc": "SINGLE" },
+    "edulevel": { "code": "8", "desc": "MASTER'S OR EQUIVALENT" },
+    "email": { "value": "sooyoung.kim@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "94445566" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "21" },
+      "street": { "value": "SCOTTS ROAD" },
+      "floor": { "value": "18" },
+      "unit": { "value": "1801" },
+      "postal": { "value": "228221" },
+      "country": { "code": "SG" }
+    },
+    "employment": { "value": "EMPLOYED" }
+  },
+
+  "sparse_data": {
+    "name": { "value": "TAN BOON HUAT" },
+    "uinfin": { "value": "S5078901E" },
+    "dob": { "value": "1950-12-19" },
+    "sex": { "code": "M", "desc": "MALE" },
+    "race": { "code": "CN", "desc": "CHINESE" },
+    "nationality": { "code": "SG", "desc": "SINGAPORE CITIZEN" },
+    "residentialstatus": { "code": "C", "desc": "CITIZEN" },
+    "marital": { "code": "3", "desc": "WIDOWED" },
+    "edulevel": { "code": "1", "desc": "PRIMARY OR LOWER SECONDARY" },
+    "email": { "value": "tan.boon.huat@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "98889999" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "20" },
+      "street": { "value": "TOA PAYOH LOR 4" },
+      "postal": { "value": "310020" },
+      "country": { "code": "SG" }
+    },
+    "employment": {}
+  },
+
+  "fin_holder": {
+    "name": { "value": "RAJESH KUMAR" },
+    "uinfin": { "value": "G7890123H" },
+    "dob": { "value": "1988-08-12" },
+    "sex": { "code": "M", "desc": "MALE" },
+    "race": { "code": "IN", "desc": "INDIAN" },
+    "nationality": { "code": "IN", "desc": "INDIAN" },
+    "residentialstatus": { "code": "F", "desc": "FOREIGNER" },
+    "passtype": { "code": "EP", "desc": "EMPLOYMENT PASS" },
+    "passstatus": { "code": "LIVE", "desc": "LIVE" },
+    "passexpirydate": { "value": "2027-08-31" },
+    "employmentsector": { "code": "FINANCIAL_SERVICES", "desc": "FINANCIAL SERVICES" },
+    "employment": { "value": "GLOBAL FINANCE PTE LTD" },
+    "occupation": { "code": "2411", "desc": "ACCOUNTANT" },
+    "marital": { "code": "1", "desc": "SINGLE" },
+    "email": { "value": "rajesh.kumar@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "96667788" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "55" },
+      "street": { "value": "BENCOOLEN STREET" },
+      "floor": { "value": "08" },
+      "unit": { "value": "12" },
+      "postal": { "value": "189627" },
+      "country": { "code": "SG" }
+    }
+  },
+
+  "error_paths": {
+    "name": { "value": "ONG WEI MING" },
+    "uinfin": { "value": "S8345678F" },
+    "dob": { "value": "1983-04-27" },
+    "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": "weiming.ong@example.com" },
+    "mobileno": {
+      "prefix": { "value": "+" },
+      "areacode": { "value": "65" },
+      "nbr": { "value": "93334455" }
+    },
+    "regadd": {
+      "type": "SG",
+      "block": { "value": "88" },
+      "street": { "value": "QUEENSWAY" },
+      "floor": { "value": "10" },
+      "unit": { "value": "1010" },
+      "postal": { "value": "149053" },
+      "country": { "code": "SG" }
+    },
+    "employment": { "value": "EMPLOYED" }
+  }
+}

data/lib/generators/standard_singpass/install/install_generator.rb

@@ -0,0 +1,45 @@
+# typed: ignore
+
+# Sorbet skips this file — Rails::Generators::Base / Thor's dynamic API is
+# not modelled in tapioca's generated RBIs and adding shims for it has
+# diminishing returns for a one-class generator.
+
+require "rails/generators"
+
+module StandardSingpass
+  module Generators
+    # Installs StandardSingpass in a host Rails application.
+    #
+    # Writes the initializer at `config/initializers/standard_singpass.rb`
+    # with the full configuration surface commented out so consumers know
+    # what's available without being forced to wire everything up front.
+    #
+    # Idempotent: re-running the generator skips an existing initializer
+    # unless `--force` is passed.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Installs StandardSingpass. By default this:
+          * writes config/initializers/standard_singpass.rb
+
+        The generator is idempotent — an existing initializer is left alone
+        unless --force is passed.
+      DESC
+
+      class_option :force, type: :boolean, default: false,
+        desc: "Overwrite config/initializers/standard_singpass.rb if it already exists"
+
+      def copy_initializer
+        initializer_path = "config/initializers/standard_singpass.rb"
+
+        if File.exist?(File.join(destination_root, initializer_path)) && !options[:force]
+          say_status("identical", "#{initializer_path} (already exists; pass --force to overwrite)", :blue)
+          return
+        end
+
+        template "initializer.rb.erb", initializer_path, force: options[:force]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# StandardSingpass MyInfo configuration.
+#
+# All Singpass FAPI 2.0 flow logic lives in the gem; this file is the
+# host-side adapter that maps environment variables onto the gem's
+# configuration object.
+#
+# Required environment variables:
+#
+#   MYINFO_CLIENT_ID         App ID from the Singpass Developer Portal
+#   MYINFO_REDIRECT_URL      OAuth callback URL (e.g. https://example.com/singpass/callback)
+#   MYINFO_PRIVATE_JWKS      Full JWKS JSON with private signing + encryption keys
+#                            (keys identified by "use": "sig" and "use": "enc")
+#
+# Optional environment variables:
+#
+#   MYINFO_SCOPE             Space-separated scopes (defaults to DEFAULT_SCOPE)
+#   MYINFO_USERINFO_URL      Userinfo endpoint override (rarely needed)
+#   MYINFO_USERINFO_JWKS_URL Userinfo JWKS endpoint override (rarely needed)
+#   MYINFO_MIN_ACR           Required Authentication Context Class Reference
+#                            URN, e.g. urn:singpass:authentication:loa:3
+#   MYINFO_MOCK_MODE         When set, suppresses missing-key warnings and
+#                            unlocks any mock-callback routes the host registers
+
+StandardSingpass::Myinfo.configure do |c|
+  # Endpoint set. :production → live Singpass FAPI; :staging → sandbox.
+  # If RAILS_ENV is "production" on multiple deployment environments
+  # (e.g. staging vs. production share the same RAILS_ENV), key this off
+  # your own environment discriminator rather than Rails.env.
+  c.environment = Rails.env.production? ? :production : :staging
+
+  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)
+
+  # 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?
+
+  # Path to a JSON file of test personas the host can drive mock callbacks
+  # against. Defaults to the gem's bundled fixture set. Override here if you
+  # maintain your own persona file.
+  # c.personas_path = Rails.root.join("e2e/fixtures/myinfo-personas.json")
+
+  # Wrap outbound Faraday calls in a resilience layer (circuit breaker, retry,
+  # tracing). Default is the identity wrapper.
+  # 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.
+  c.private_jwks_json = ENV["MYINFO_PRIVATE_JWKS"]
+end

data/lib/standard_singpass/engine.rb

@@ -0,0 +1,17 @@
+# Defines the Rails engine when Rails is loaded. In tooling contexts that
+# load the gem without Rails (e.g. `tapioca gems`, which calls
+# `Bundler.require` before any explicit `require "rails"`), this file is
+# still required by `lib/standard_singpass.rb` but the engine class is
+# simply not defined — which is fine, because rake-task autoloading is
+# only meaningful inside a Rails host anyway.
+if defined?(::Rails::Engine)
+  module StandardSingpass
+    class Engine < ::Rails::Engine
+      isolate_namespace StandardSingpass
+
+      rake_tasks do
+        load File.expand_path("../tasks/standard_singpass.rake", __dir__)
+      end
+    end
+  end
+end