zoreal-oauth2 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e5d3f39f216e8d1785e62de549d19ca9aec733ca7a3c22391ff8b2a234a2cfd
+  data.tar.gz: 061177e1bcce5d19f45c3e0e5f150b9634993e0d1f0ca482a1b2cf145c6904b5
+SHA512:
+  metadata.gz: a3192fbc0c628a62efb76bc8553641105675919d518bc1bd1e29a3b38baf97ebc8d67f002d6f9104fb7c64e5789c55b45b4d54e6fc91b6e1986349964938d85f
+  data.tar.gz: 4e7ca36900276481a1fccbb7e9eabf3bf089f65e745be5a79899314a40453fdd2fe4b5bc8400409b25865b34ea649e4245f4174509726912bf19637ce0a41079

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bynn Intelligence, Inc.
+
+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,152 @@
+# zoreal-oauth2
+
+Login with ZOREAL for Ruby backends: the relying-party half of the flow that
+[`@zoreal/oauth2-react`](https://github.com/Bynn-Intelligence/zoreal-oauth2-react)
+starts in the browser.
+
+The browser SDK runs the pairing (QR or app link), and hands your frontend an
+authorization `code` plus the `code_verifier` and `nonce` it generated. Your
+frontend posts all three to your backend, and this gem does the rest: the code
+exchange with your client authentication, ES256 verification of the ID token
+against the provider's JWKS, and the `/userinfo` read for personal claims.
+
+```
+zoreal-oauth2 (this gem)   your backend: exchange, verify, userinfo
+@zoreal/oauth2-react       your frontend: the button, the QR, the polling
+```
+
+## Install
+
+```ruby
+# Gemfile — until the gem is on rubygems.org, vendor it or use the git source:
+gem 'zoreal-oauth2', git: 'https://github.com/Bynn-Intelligence/zoreal-oauth2-ruby'
+```
+
+Ruby >= 3.1. One dependency: `jwt`.
+
+## Quick start
+
+Build one client at boot and share it; it is thread-safe.
+
+```ruby
+ZOREAL_OAUTH = Zoreal::OAuth2::Client.new(
+  client_id: ENV['ZOREAL_CLIENT_ID'],                                   # ast_...
+  client_secret: Rails.application.credentials.dig(:zoreal, :client_secret),
+  issuer: ENV.fetch('ZOREAL_ISSUER', 'https://id.zoreal.com'),
+  cache: Rails.cache                                                    # optional, for the JWKS
+)
+```
+
+The endpoint your frontend posts to:
+
+```ruby
+login = ZOREAL_OAUTH.authenticate(
+  code: params[:code],
+  code_verifier: params[:code_verifier],   # PKCE is mandatory; the SDK hands it over
+  nonce: params[:nonce]                    # binds the ID token to this login
+)
+
+login.sub          # "TC5X-JN7G-YTSE-6E63" — pairwise, stable for YOUR domain
+login.acr          # "zoreal.live" | "zoreal.device" | "zoreal.session"
+login.assurance    # uniqueness basis, verification month, chip liveness, trust tier
+login.email        # from /userinfo, when your client has the email scope
+login.email_verified?
+login.name         # from /userinfo, profile.name scope
+```
+
+Account matching, the shape that works:
+
+```ruby
+user = User.find_by(provider: 'zoreal', uid: login.sub)
+if user.nil?
+  user = User.find_by(email: login.email) if login.email_verified?  # claim, don't collide
+  user ||= User.new(email: login.email)
+  user.update!(provider: 'zoreal', uid: login.sub)
+end
+```
+
+## Client authentication: all four registered methods
+
+| `token_endpoint_auth_method` | Configuration | What travels |
+|---|---|---|
+| `none` | nothing | a public client: PKCE alone, Tier A scopes only |
+| `client_secret_basic` | `client_secret:` | the secret, as HTTP Basic |
+| `private_key_jwt` | `private_key:` (PEM or `OpenSSL::PKey`), `private_key_kid:` optional | a fresh RFC 7523 assertion per exchange: `iss`=`sub`=client id, `aud`=`{issuer}/token`, 60-second life, single-use `jti`. P-256 signs ES256, RSA signs RS256 |
+| `tls_client_auth` | `tls_client_cert:`, `tls_client_key:` | the TLS client certificate. Registrable today; the provider still answers 501 at `/token`, and that surfaces as the `ExchangeError` it is |
+
+`auth_method:` may be omitted: a `client_secret` implies `client_secret_basic`,
+a `private_key` implies `private_key_jwt`, neither means `none`.
+
+## What each call does
+
+| Call | What happens |
+|---|---|
+| `authenticate(code:, code_verifier:, nonce: nil)` | `exchange` + `verify_id_token`, returns a `Login` |
+| `exchange(code:, code_verifier:)` | `POST {issuer}/token` with the configured client authentication |
+| `verify_id_token(jwt, nonce: nil)` | ES256 against `{issuer}/jwks`, checks `iss`, `aud`, `exp`, and `nonce` when given |
+| `userinfo(access_token)` | `GET {issuer}/userinfo` with the Bearer token |
+| `Login#userinfo` | the above, once, memoized; `{}` when there is no access token |
+
+`Login` exposes every claim the scope catalogue can grant: `sub`, `acr`, `amr`,
+`assurance`, `age_over?(n)`, `nationality` from the ID token; `email`,
+`email_verified?`, `name`, `given_name`, `family_name`, `birthdate`,
+`document_type`, `document_number`, `issuing_country`, `document_expires_on`
+and `portrait` from `/userinfo` (`portrait` is registrable but not served by
+the provider yet, and returns nil until it is).
+
+Errors: `ConfigurationError`, `ExchangeError` (carries the provider's OAuth
+error code and reason, verbatim), `VerificationError`, `UserinfoError`. A
+returning user matched on `sub` can survive a rescued `UserinfoError`; a
+signup that needs the email cannot.
+
+## Things worth knowing before you integrate
+
+- **The ID token never carries personal data.** `sub`, timing, `acr`/`amr`,
+  the assurance block, and — if registered — `age_over_*` booleans and
+  `nationality`. Email, names, birthdate and document fields come only from
+  `/userinfo`, which is why `authenticate` alone is not enough for a signup.
+- **The access token lives 10 minutes.** Read `/userinfo` while handling the
+  login; do not store the token for later.
+- **`sub` is pairwise per verified domain.** It is the right account key and
+  it is derived from your registered sector: changing your asset's domain
+  rotates every `sub` you have stored. Plan domain changes as a migration.
+- **ES256 only.** The provider signs with nothing else, and this gem refuses
+  other algorithms rather than negotiating.
+- **Always pass the nonce through.** The SDK generates it and gives it to your
+  frontend in `onSuccess`; without it your backend cannot tell a substituted
+  ID token from the real one.
+- **Email is a deliberate choice.** It is a Tier B scope precisely because a
+  shared email defeats the unlinkability the pairwise `sub` provides. Request
+  it because you need it, not because the checkbox is familiar.
+- **Sandbox clients accept localhost origins; production clients do not.**
+  Registration lives in the ZOREAL dashboard on the asset's OAuth2 tab; Tier B
+  scopes (email, profile.\*) need a confidential client on a verified domain.
+
+## Development against a local provider
+
+Point `issuer:` at your provider instance (for the Bynn stack:
+`https://rails.bynn.io/id`). The issuer value must match the `iss` inside the
+tokens exactly — it is compared, not normalized.
+
+## The ZOREAL OAuth2 library family
+
+| Repository | Package | Role |
+|---|---|---|
+| zoreal-oauth2-react | @zoreal/oauth2-react (npm) | React frontend: the button, the QR, the polling |
+| zoreal-oauth2-js | @zoreal/oauth2-js (npm) | Framework-free browser core |
+| zoreal-oauth2-react-native | @zoreal/oauth2-react-native (npm) | React Native frontend |
+| zoreal-oauth2-node | @zoreal/oauth2-node (npm) | Node.js backend |
+| zoreal-oauth2-ruby | zoreal-oauth2 (RubyGems) | Ruby backend |
+| zoreal-oauth2-python | zoreal-oauth2 (PyPI) | Python backend |
+| zoreal-oauth2-php | zoreal/oauth2 (Packagist) | PHP backend |
+| zoreal-oauth2-go | github.com/Bynn-Intelligence/zoreal-oauth2-go | Go backend |
+| zoreal-oauth2-java | com.zoreal:oauth2 (Maven Central) | JVM backend |
+| zoreal-oauth2-dotnet | Zoreal.OAuth2 (NuGet) | .NET backend |
+
+The repository always carries the platform suffix; the package drops it where
+the registry already scopes the ecosystem. None of them are named after a
+framework, because none of them depend on one.
+
+## License
+
+MIT.

data/lib/zoreal/oauth2/client.rb

@@ -0,0 +1,294 @@
+require 'json'
+require 'net/http'
+require 'securerandom'
+require 'uri'
+require 'jwt'
+
+module Zoreal
+  module OAuth2
+    # The relying-party client. One instance per registered ZOREAL client;
+    # thread-safe, so build it once at boot and share it.
+    #
+    #   ZOREAL_CLIENT = Zoreal::OAuth2::Client.new(
+    #     client_id: ENV['ZOREAL_CLIENT_ID'],
+    #     client_secret: Rails.application.credentials.dig(:zoreal, :client_secret),
+    #     issuer: ENV.fetch('ZOREAL_ISSUER', 'https://id.zoreal.com'),
+    #     cache: Rails.cache
+    #   )
+    #
+    #   login = ZOREAL_CLIENT.authenticate(code: params[:code],
+    #                                      code_verifier: params[:code_verifier],
+    #                                      nonce: params[:nonce])
+    #   login.sub            # the pairwise subject: your stable user key
+    #   login.userinfo       # Tier B claims (email, name, ...), fetched once
+    class Client
+      DEFAULT_ISSUER = 'https://id.zoreal.com'.freeze
+      # The provider serves its JWKS with a 10-minute public cache; mirroring
+      # it here keeps a busy relying party off the endpoint without holding a
+      # rotated-out key longer than the provider itself would.
+      JWKS_TTL = 600
+      JWKS_CACHE_KEY = 'zoreal_oauth2_jwks'.freeze
+
+      AUTH_METHODS = %w[none client_secret_basic private_key_jwt tls_client_auth].freeze
+      # The provider rejects an assertion whose exp is more than 60 seconds
+      # out, so that is the lifetime, not a choice.
+      ASSERTION_LIFETIME = 60
+
+      attr_reader :client_id, :issuer, :auth_method
+
+      # Every registered token_endpoint_auth_method is supported:
+      #
+      #   none               a public client: no secret, no key, PKCE alone,
+      #                      and only ever Tier A scopes.
+      #   client_secret_basic  the secret travels as an HTTP Basic header.
+      #   private_key_jwt    the library signs a fresh RFC 7523 assertion per
+      #                      exchange from private_key (an OpenSSL::PKey or a
+      #                      PEM string; P-256 signs ES256, RSA signs RS256;
+      #                      private_key_kid sets the JWS kid header when your
+      #                      registered JWKS carries one).
+      #   tls_client_auth    tls_client_cert/tls_client_key are presented as
+      #                      the TLS client certificate. Registrable today;
+      #                      the provider itself still answers 501 at /token,
+      #                      and that surfaces as the ExchangeError it is.
+      #
+      # auth_method may be omitted: a client_secret implies
+      # client_secret_basic, a private_key implies private_key_jwt, neither
+      # means none.
+      #
+      # cache takes anything with read(key) and write(key, value, expires_in:)
+      # (ActiveSupport::Cache::Store is the intended shape). Without one, an
+      # in-process store is used; that is fine for one process and means each
+      # process of a multi-process server fetches the JWKS for itself.
+      def initialize(client_id:, client_secret: nil, issuer: DEFAULT_ISSUER,
+                     auth_method: nil, private_key: nil, private_key_kid: nil,
+                     tls_client_cert: nil, tls_client_key: nil,
+                     cache: nil, timeout: 10)
+        raise ConfigurationError, 'client_id is required' if nil_or_empty?(client_id)
+        raise ConfigurationError, 'issuer is required' if nil_or_empty?(issuer)
+
+        @client_id = client_id
+        @client_secret = client_secret
+        @private_key = import_private_key(private_key)
+        @private_key_kid = private_key_kid
+        @tls_client_cert = import_certificate(tls_client_cert)
+        @tls_client_key = import_private_key(tls_client_key)
+        @auth_method = resolve_auth_method(auth_method)
+        @issuer = issuer.chomp('/')
+        @cache = cache || MemoryCache.new
+        @timeout = timeout
+      end
+
+      # The whole login, in order: exchange the code (with the PKCE verifier
+      # the browser SDK handed over), verify the ID token against the JWKS,
+      # check the nonce when the caller has it. Returns a Login; personal data
+      # is NOT fetched here, because the ID token never carries it and not
+      # every caller wants it — Login#userinfo fetches on first use.
+      def authenticate(code:, code_verifier:, nonce: nil)
+        tokens = exchange(code: code, code_verifier: code_verifier)
+        claims = verify_id_token(tokens['id_token'], nonce: nonce)
+        Login.new(client: self, claims: claims,
+                  id_token: tokens['id_token'],
+                  access_token: tokens['access_token'],
+                  scope: tokens['scope'])
+      end
+
+      # POST /token. The verifier is mandatory: PKCE is required for every
+      # ZOREAL client, and the browser SDK that generated it hands it to your
+      # frontend precisely so your backend can present it here.
+      def exchange(code:, code_verifier:)
+        raise ArgumentError, 'code is required' if nil_or_empty?(code)
+        raise ArgumentError, 'code_verifier is required' if nil_or_empty?(code_verifier)
+
+        response = post_form("#{issuer}/token", {
+                               'grant_type' => 'authorization_code',
+                               'code' => code,
+                               'code_verifier' => code_verifier,
+                               'client_id' => client_id
+                             })
+        body = parse_json(response.body)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise ExchangeError.new(body['error'] || 'server_error',
+                                  body['error_description'] || "the provider answered #{response.code}",
+                                  status: response.code.to_i)
+        end
+        raise ExchangeError.new('server_error', 'no id_token in the token response') if nil_or_empty?(body['id_token'])
+
+        body
+      end
+
+      # ES256 against the provider's JWKS, plus iss, aud, exp and — when the
+      # caller passes the nonce the SDK generated — the nonce binding. Returns
+      # the claims. There is no RS256 fallback on purpose: ZOREAL signs
+      # nothing with RSA, and accepting a second algorithm is how algorithm
+      # confusion starts.
+      def verify_id_token(id_token, nonce: nil)
+        claims, = JWT.decode(
+          id_token, nil, true,
+          algorithms: ['ES256'],
+          iss: issuer, verify_iss: true,
+          aud: client_id, verify_aud: true,
+          jwks: ->(options) {
+            @cache.write(JWKS_CACHE_KEY, nil, expires_in: 0) if options[:kid_not_found]
+            jwks
+          }
+        )
+        if !nil_or_empty?(nonce) && claims['nonce'] != nonce
+          raise VerificationError, 'the ID token nonce is not the one this login started with'
+        end
+
+        claims
+      rescue JWT::DecodeError => e
+        raise VerificationError, e.message
+      end
+
+      # GET /userinfo with the Bearer access token from the exchange. This is
+      # the only place personal claims (email, profile.*) are served, and the
+      # access token lives ten minutes, so call it as part of handling the
+      # login rather than storing the token for later.
+      def userinfo(access_token)
+        raise ArgumentError, 'access_token is required' if nil_or_empty?(access_token)
+
+        uri = URI("#{issuer}/userinfo")
+        request = Net::HTTP::Get.new(uri)
+        request['Authorization'] = "Bearer #{access_token}"
+        response = http_for(uri).request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          body = parse_json(response.body)
+          raise UserinfoError,
+                body['error_description'] || "userinfo answered #{response.code}"
+        end
+        parse_json(response.body)
+      end
+
+      private
+
+      def jwks
+        cached = @cache.read(JWKS_CACHE_KEY)
+        return cached if cached
+
+        uri = URI("#{issuer}/jwks")
+        begin
+          response = http_for(uri).request(Net::HTTP::Get.new(uri))
+        rescue SystemCallError, SocketError, IOError, Timeout::Error, OpenSSL::SSL::SSLError => e
+          raise VerificationError, "could not fetch the provider JWKS: #{e.message}"
+        end
+        raise VerificationError, "could not fetch the provider JWKS (#{response.code})" unless response.is_a?(Net::HTTPSuccess)
+
+        keys = JSON.parse(response.body, symbolize_names: true)
+        @cache.write(JWKS_CACHE_KEY, keys, expires_in: JWKS_TTL)
+        keys
+      end
+
+      def post_form(url, form)
+        uri = URI(url)
+        request = Net::HTTP::Post.new(uri)
+        # The form always carries client_id, whatever the auth method: the
+        # provider matches the code against it.
+        case auth_method
+        when 'client_secret_basic'
+          # The secret travels as the Basic password, never as a form field.
+          request.basic_auth(client_id, @client_secret)
+        when 'private_key_jwt'
+          form = form.merge(
+            'client_assertion_type' => 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+            'client_assertion' => build_client_assertion
+          )
+        end
+        request.set_form_data(form)
+        http_for(uri).request(request)
+      end
+
+      # RFC 7523, in the shape the provider verifies: iss and sub are the
+      # client_id, aud is the token endpoint, exp is the capped 60 seconds,
+      # and jti is fresh because the provider enforces single use on it.
+      def build_client_assertion
+        now = Time.now.to_i
+        algorithm = @private_key.is_a?(OpenSSL::PKey::EC) ? 'ES256' : 'RS256'
+        headers = @private_key_kid ? { kid: @private_key_kid } : {}
+        JWT.encode(
+          {
+            iss: client_id, sub: client_id, aud: "#{issuer}/token",
+            exp: now + ASSERTION_LIFETIME, iat: now, jti: SecureRandom.uuid
+          },
+          @private_key, algorithm, headers
+        )
+      end
+
+      def http_for(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        if auth_method == 'tls_client_auth' && http.use_ssl?
+          http.cert = @tls_client_cert
+          http.key = @tls_client_key
+        end
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http
+      end
+
+      def resolve_auth_method(explicit)
+        method = explicit&.to_s
+        method ||= if !nil_or_empty?(@client_secret) then 'client_secret_basic'
+                   elsif @private_key then 'private_key_jwt'
+                   else 'none'
+                   end
+        raise ConfigurationError, "unknown auth_method #{method}" unless AUTH_METHODS.include?(method)
+        raise ConfigurationError, 'client_secret_basic needs a client_secret' if method == 'client_secret_basic' && nil_or_empty?(@client_secret)
+        raise ConfigurationError, 'private_key_jwt needs a private_key' if method == 'private_key_jwt' && @private_key.nil?
+        if method == 'tls_client_auth' && (@tls_client_cert.nil? || @tls_client_key.nil?)
+          raise ConfigurationError, 'tls_client_auth needs tls_client_cert and tls_client_key'
+        end
+
+        method
+      end
+
+      def import_private_key(key)
+        return nil if key.nil?
+        return key unless key.is_a?(String)
+
+        OpenSSL::PKey.read(key)
+      rescue OpenSSL::PKey::PKeyError => e
+        raise ConfigurationError, "the private key did not parse: #{e.message}"
+      end
+
+      def import_certificate(cert)
+        return nil if cert.nil?
+        return cert unless cert.is_a?(String)
+
+        OpenSSL::X509::Certificate.new(cert)
+      rescue OpenSSL::X509::CertificateError => e
+        raise ConfigurationError, "the certificate did not parse: #{e.message}"
+      end
+
+      def parse_json(body)
+        JSON.parse(body.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def nil_or_empty?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+
+      # The fallback JWKS cache: one process, TTL respected, no eviction
+      # beyond overwrite, because it only ever holds the one key set.
+      class MemoryCache
+        def initialize
+          @mutex = Mutex.new
+          @store = {}
+        end
+
+        def read(key)
+          @mutex.synchronize do
+            value, expires_at = @store[key]
+            expires_at && expires_at > Time.now ? value : nil
+          end
+        end
+
+        def write(key, value, expires_in:)
+          @mutex.synchronize { @store[key] = [value, Time.now + expires_in] }
+        end
+      end
+    end
+  end
+end

data/lib/zoreal/oauth2/errors.rb

@@ -0,0 +1,32 @@
+module Zoreal
+  module OAuth2
+    class Error < StandardError; end
+
+    # The client was built without something it cannot work without.
+    class ConfigurationError < Error; end
+
+    # The provider refused the code exchange. `oauth_error` is the RFC 6749
+    # error code and `description` the provider's own reason, verbatim: the
+    # provider's words are the only signal that says WHY (a consumed code, a
+    # PKCE mismatch, a lapsed sector), and rewriting them hides it.
+    class ExchangeError < Error
+      attr_reader :oauth_error, :description, :status
+
+      def initialize(oauth_error, description, status: nil)
+        @oauth_error = oauth_error
+        @description = description
+        @status = status
+        super([oauth_error, description].compact.join(': '))
+      end
+    end
+
+    # The ID token did not verify: bad signature, wrong issuer or audience,
+    # expired, or a nonce that was not the one this login started with.
+    class VerificationError < Error; end
+
+    # /userinfo answered with anything but the claims. Callers that can live
+    # without personal data (a returning user matched by sub) may rescue this
+    # and continue; callers that need the email should not.
+    class UserinfoError < Error; end
+  end
+end

data/lib/zoreal/oauth2/login.rb

@@ -0,0 +1,114 @@
+module Zoreal
+  module OAuth2
+    # One verified login. The ID token claims are already checked when this
+    # exists; userinfo is fetched on first use, because the ID token never
+    # carries personal data and not every login needs any.
+    class Login
+      # The verified ID token claims and the raw compact JWT they came from.
+      attr_reader :claims, :id_token
+      # From the token response. The access token lives ten minutes.
+      attr_reader :access_token, :scope
+
+      def initialize(client:, claims:, id_token:, access_token: nil, scope: nil)
+        @client = client
+        @claims = claims
+        @id_token = id_token
+        @access_token = access_token
+        @scope = scope
+      end
+
+      # The pairwise subject: stable for your verified domain, meaningless to
+      # anyone else. This is the value to key accounts on — and it is derived
+      # from YOUR registered sector, so changing your asset's domain rotates
+      # every sub you have stored.
+      def sub
+        claims['sub']
+      end
+
+      # How the login was authenticated: zoreal.live, zoreal.device or
+      # zoreal.session. Describes what happened, never what was requested.
+      def acr
+        claims['acr']
+      end
+
+      def amr
+        claims['amr']
+      end
+
+      # The assurance block: uniqueness basis, verification month, chip
+      # liveness, trust tier, key protection.
+      def assurance
+        claims['zoreal']
+      end
+
+      # zoreal.age scope: the registered thresholds arrive as booleans
+      # (age_over_18 and so on), never an age.
+      def age_over?(threshold)
+        claims["age_over_#{threshold.to_i}"]
+      end
+
+      # zoreal.nationality scope: ISO 3166-1 alpha-3, read from the chip.
+      def nationality
+        claims['nationality']
+      end
+
+      # The Tier B claims, from /userinfo, fetched once and memoized. Raises
+      # UserinfoError when the endpoint refuses — rescue it if your flow can
+      # continue without personal data, as a returning user matched on sub
+      # can. Returns an empty hash when the exchange carried no access token.
+      def userinfo
+        @userinfo ||= access_token ? @client.userinfo(access_token) : {}
+      end
+
+      def email
+        userinfo['email']
+      end
+
+      def email_verified?
+        userinfo['email_verified'] == true
+      end
+
+      def name
+        userinfo['name']
+      end
+
+      def given_name
+        userinfo['given_name']
+      end
+
+      def family_name
+        userinfo['family_name']
+      end
+
+      # ISO 8601, from the profile.birthdate scope.
+      def birthdate
+        userinfo['birthdate']
+      end
+
+      # The profile.document scope: the document as presented, not an
+      # assertion about the person beyond it.
+      def document_type
+        userinfo['document_type']
+      end
+
+      def document_number
+        userinfo['document_number']
+      end
+
+      def issuing_country
+        userinfo['issuing_country']
+      end
+
+      def document_expires_on
+        userinfo['document_expires_on']
+      end
+
+      # The profile.portrait scope (Tier C): the chip's DG2 image. The scope
+      # is registrable but the provider does not serve the claim yet, so this
+      # returns nil until it does.
+      def portrait
+        userinfo['portrait']
+      end
+    end
+  end
+end

data/lib/zoreal/oauth2/version.rb

@@ -0,0 +1,5 @@
+module Zoreal
+  module OAuth2
+    VERSION = '0.1.1'.freeze
+  end
+end

data/lib/zoreal/oauth2.rb

@@ -0,0 +1,9 @@
+require_relative 'oauth2/version'
+require_relative 'oauth2/errors'
+require_relative 'oauth2/client'
+require_relative 'oauth2/login'
+
+module Zoreal
+  module OAuth2
+  end
+end

data/lib/zoreal-oauth2.rb

@@ -0,0 +1 @@
+require_relative 'zoreal/oauth2'

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: zoreal-oauth2
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- ZOREAL
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: 'The relying-party half of Login with ZOREAL: exchanges the authorization
+  code your frontend received from @zoreal/oauth2-react, verifies the ID token against
+  the provider''s JWKS, and reads personal claims from /userinfo.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/zoreal-oauth2.rb
+- lib/zoreal/oauth2.rb
+- lib/zoreal/oauth2/client.rb
+- lib/zoreal/oauth2/errors.rb
+- lib/zoreal/oauth2/login.rb
+- lib/zoreal/oauth2/version.rb
+homepage: https://zoreal.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Bynn-Intelligence/zoreal-oauth2-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Login with ZOREAL for Ruby backends.
+test_files: []