omniauth-vitsme 0.1.0 → 0.2.1

data/data/claims.json

@@ -0,0 +1,175 @@
+{
+  "catalog_version": 2,
+  "about": "Every scope, claim, gate and refusal reason a vits.me relying party can use. Source of truth for omniauth-vitsme (OmniAuth::Vitsme::Catalog) and for agents and developers choosing scopes. Mirrors the vits.me server: config/initializers/doorkeeper.rb (scopes), config/initializers/doorkeeper_openid_connect.rb (claims), config/initializers/authorizations_controller_extension.rb (value domains, gates, refusals).",
+  "conventions": {
+    "delivery": "Every claim except sub comes from the UserInfo endpoint, never the ID token. omniauth-vitsme fetches UserInfo on every sign-in.",
+    "absent_means_undisclosed": "A disclosure claim may be missing even when its scope was granted: the person chose to share nothing, holds no such detail, or hid it. Missing is never false.",
+    "person_chooses_the_value": "For disclosure claims the person picks the value on vits.me's consent screen, from options at different levels of detail (e.g. a given name, initials, or a full name). Ask for the least you need.",
+    "sub_is_private": "sub, solid, defunct_solids and fluid are private per-site identifiers. Store them; never render, log, put in a URL, federate or derive a public handle or email from them."
+  },
+  "identity_scopes": {
+    "openid": {
+      "required": true,
+      "claims": ["sub", "solid", "defunct_solids"],
+      "description": "Sign in. Always requested."
+    },
+    "fluid": {
+      "required": false,
+      "claims": ["fluid"],
+      "description": "Also sign in people whose verification is still pending (sub = fluid_...). Cannot be combined with a nationality gate.",
+      "doc": "https://github.com/yuvaltobias/omniauth-vitsme#unverified-fluid-identities"
+    }
+  },
+  "claims": {
+    "sub": {
+      "scope": "openid",
+      "type": "string",
+      "format": "solid_<base32> for a verified person; fluid_<base32> for a pending signup (only with the fluid scope)",
+      "description": "Pairwise subject: the same person has a different sub at every site. The OmniAuth uid."
+    },
+    "solid": {
+      "scope": "openid",
+      "type": "string",
+      "format": "solid_<base32>",
+      "description": "Equal to sub for a verified person; absent for a pending signup."
+    },
+    "defunct_solids": {
+      "scope": "openid",
+      "type": "string_array",
+      "format": "[solid_<base32>, ...]",
+      "description": "Earlier SOLIDs this site was given for the same person (kept one year). If your record holds one of these, move it to the current sub."
+    },
+    "fluid": {
+      "scope": "fluid",
+      "type": "string_array",
+      "format": "[fluid_<base32>, ...]",
+      "description": "Pending-signup identifiers this site may have been given for the same person in the past week. Merge any tentative account keyed by one into this person."
+    },
+    "name": {
+      "scope": "name",
+      "type": "string",
+      "examples": ["Jane", "J. D.", "Jane D.", "Jane Doe"],
+      "description": "One name, at the level of detail the person chose. Not split into given and family names. May be in Hebrew script."
+    },
+    "name__full": {
+      "scope": "name__full",
+      "type": "string",
+      "examples": ["Jane Doe", "Jane M. Doe"],
+      "description": "A full name, chosen from the person's full-name forms."
+    },
+    "nationality": {
+      "scope": "nationality",
+      "type": "string",
+      "format": "ISO 3166-1 alpha-2, upper case",
+      "examples": ["IL"],
+      "description": "A nationality the person holds and chose to share."
+    },
+    "nationality__in_eu": {
+      "scope": "nationality__in_eu",
+      "type": "boolean",
+      "description": "Whether the shared nationality is an EU member state."
+    },
+    "nationality__in_eea": {
+      "scope": "nationality__in_eea",
+      "type": "boolean",
+      "description": "Whether the shared nationality is in the European Economic Area."
+    },
+    "nationality__in_esm": {
+      "scope": "nationality__in_esm",
+      "type": "boolean",
+      "description": "Whether the shared nationality is in the European Single Market."
+    },
+    "nationality__gdpr_compliant": {
+      "scope": "nationality__gdpr_compliant",
+      "type": "boolean",
+      "description": "Whether the shared nationality is an EEA member state or the United Kingdom."
+    },
+    "il_government_id_number": {
+      "scope": "il_government_id_number",
+      "type": "string",
+      "description": "Israeli government ID number (teudat zehut). Highly sensitive: request only with a legal need."
+    },
+    "age": {
+      "scope": "age",
+      "type": "string",
+      "values": ["under_13", "over_13", "over_18", "over_21", "gen_lost", "gen_greatest", "gen_silent", "gen_boomers", "gen_x", "gen_y", "gen_z", "gen_alpha", "under_18", "18_to_24", "25_to_34", "35_to_44", "45_to_54", "55_to_64", "over_65", "<years as digits>"],
+      "description": "The person's age at the level they chose: a threshold, a generation, a range, or exact years."
+    },
+    "age__years": {
+      "scope": "age__years",
+      "type": "integer",
+      "description": "Exact age in whole years."
+    },
+    "age__range": {
+      "scope": "age__range",
+      "type": "string",
+      "values": ["under_18", "18_to_24", "25_to_34", "35_to_44", "45_to_54", "55_to_64", "over_65"],
+      "description": "An age range."
+    },
+    "age__over_13": {
+      "scope": "age__over_13",
+      "type": "boolean",
+      "description": "Whether the person is 13 or older."
+    },
+    "age__over_18": {
+      "scope": "age__over_18",
+      "type": "boolean",
+      "description": "Whether the person is 18 or older."
+    },
+    "age__over_21": {
+      "scope": "age__over_21",
+      "type": "boolean",
+      "description": "Whether the person is 21 or older."
+    },
+    "birthdate": {
+      "scope": "birthdate",
+      "type": "string",
+      "format": "YYYY-MM-DD",
+      "description": "Full date of birth."
+    },
+    "birthday": {
+      "scope": "birthday",
+      "type": "string",
+      "format": "M-D (month-day, no year) or YYYY-MM-DD, as the person chose",
+      "description": "Birthday. The person may share it with or without the year."
+    },
+    "birthyear": {
+      "scope": "birthyear",
+      "type": "string",
+      "format": "YYYY",
+      "description": "Year of birth."
+    }
+  },
+  "gates": {
+    "openid_nationality": {
+      "scope_pattern": "^openid_nationality__[a-z]{2}$",
+      "scope_format": "openid_nationality__<iso 3166-1 alpha-2, lower case>",
+      "claims": [],
+      "description": "Only verified people holding one of the requested nationalities can finish signing in. Several codes are any-of. Emits no claim: a successful sign-in is the answer. vits.me asks the person's consent for the verdict. Refused people return with error=access_denied and vitsme_error=nationality_gate (or nationality_gate_unverified).",
+      "incompatible_with": ["fluid"]
+    }
+  },
+  "refusals": {
+    "nationality_gate": {
+      "error": "access_denied",
+      "omniauth_failure": "nationality_gate_refused",
+      "description": "The person holds none of the nationalities the gate requires (or has hidden them)."
+    },
+    "nationality_gate_unverified": {
+      "error": "access_denied",
+      "omniauth_failure": "nationality_gate_refused",
+      "description": "A pending (unverified) signup tried to pass a nationality gate."
+    },
+    "subject_mismatch": {
+      "error": "access_denied",
+      "omniauth_failure": "identity_mismatch",
+      "description": "The site said whom it expected (claims sub value) and a different person is signed in at vits.me."
+    }
+  },
+  "lifetimes_seconds": {
+    "authorization_code": 5,
+    "access_token": 5,
+    "id_token": 5,
+    "refresh_token": null
+  }
+}

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'rails/version'
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'omniauth/vitsme'
+
+module OmniAuth
+  module Vitsme
+    module Generators
+      # bin/rails g omniauth_vitsme:install [--model=User] [--verify=age__over_18 name] [--gate=IL] [--fluid]
+      #
+      # Sign-in with vits.me wired the way the README describes: an initializer, a callbacks controller
+      # that finds a returning person by every uid vits.me lists for them, failure messages (en/he), a
+      # sign-in button partial, routes, and a migration adding a private, unique `vitsme_uid` column.
+      # --verify adds a second provider that asks about the person already signed in, with expected_uid.
+      class InstallGenerator < Rails::Generators::Base
+        include Rails::Generators::Migration
+
+        namespace 'omniauth_vitsme:install'
+        source_root File.expand_path('templates', __dir__)
+
+        class_option :model, type: :string, default: 'User', desc: 'The model a vits.me uid signs in as'
+        class_option :scope, type: :array, default: [], desc: 'Disclosure scopes to ask for at sign-in'
+        class_option :verify, type: :array, default: [],
+                              desc: 'Scopes for a :vitsme_verify provider about the signed-in person'
+        class_option :gate, type: :array, default: [], desc: 'Nationalities (ISO alpha-2) required to sign in'
+        class_option :fluid, type: :boolean, default: false, desc: 'Also sign in people pending verification'
+
+        def self.next_migration_number(_dirname)
+          Time.now.utc.strftime('%Y%m%d%H%M%S')
+        end
+
+        def check_options
+          scopes = sign_in_scopes + verify_scopes
+          unknown = scopes.reject { |s| Catalog.known_scope?(s) }
+          raise Thor::Error, "Unknown vits.me scope(s): #{unknown.join(', ')}" unless unknown.empty?
+          return unless options[:fluid] && !options[:gate].empty?
+
+          raise Thor::Error, '--fluid and --gate cannot be combined: a gate admits verified people only.'
+        end
+
+        def create_initializer
+          template 'omniauth_vitsme.rb.tt', 'config/initializers/omniauth_vitsme.rb'
+        end
+
+        def create_controller
+          template 'vitsme_callbacks_controller.rb.tt', 'app/controllers/vitsme_callbacks_controller.rb'
+        end
+
+        def create_views_and_locales
+          template '_sign_in.html.erb.tt', 'app/views/vitsme/_sign_in.html.erb'
+          copy_file 'vitsme.en.yml', 'config/locales/vitsme.en.yml'
+          copy_file 'vitsme.he.yml', 'config/locales/vitsme.he.yml'
+        end
+
+        def add_uid_migration
+          migration_template 'add_vitsme_uid.rb.tt', "db/migrate/add_vitsme_uid_to_#{table_name}.rb"
+        end
+
+        def add_routes
+          route "get '/auth/vitsme_verify/callback', to: 'vitsme_callbacks#verify'" if verify?
+          route "get '/auth/failure', to: 'vitsme_callbacks#failure'"
+          route "get '/auth/vitsme/callback', to: 'vitsme_callbacks#sign_in'"
+        end
+
+        def next_steps
+          say <<~TEXT
+
+            vits.me sign-in is wired. Next:
+              1. Ask the vits.me team for client credentials; set VITSME_CLIENT_ID / VITSME_CLIENT_SECRET.
+                 Register #{callback_urls.join(' and ')} as redirect URIs.
+              2. Add gem "omniauth-rails_csrf_protection" (OmniAuth 2 signs in by POST only).
+              3. bin/rails db:migrate, then render "vitsme/sign_in" where people sign in.
+              4. Read the uid rules in the omniauth-vitsme README: store it, never show or log it.
+          TEXT
+        end
+
+        private
+
+        def model
+          options[:model].camelize
+        end
+
+        def session_key
+          "#{options[:model].underscore.tr('/', '_')}_id"
+        end
+
+        def table_name
+          options[:model].underscore.tr('/', '_').pluralize
+        end
+
+        def sign_in_scopes
+          (['openid'] + options[:scope] + (options[:fluid] ? ['fluid'] : [])).uniq
+        end
+
+        def verify_scopes
+          options[:verify].empty? ? [] : (['openid'] + options[:verify]).uniq
+        end
+
+        def verify?
+          !options[:verify].empty?
+        end
+
+        def gate
+          options[:gate].map(&:upcase)
+        end
+
+        def symbols(list)
+          "%i[#{list.join(' ')}]"
+        end
+
+        def callback_urls
+          paths = ['/auth/vitsme/callback']
+          paths << '/auth/vitsme_verify/callback' if verify?
+          paths.map { |p| "https://<your host>#{p}" }
+        end
+
+        def migration_version
+          "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+        end
+      end
+    end
+  end
+end

data/lib/generators/omniauth_vitsme/install/templates/_sign_in.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# OmniAuth 2 starts sign-in by POST only (add omniauth-rails_csrf_protection). %>
+<%%= button_to t('vitsme.sign_in'), '/auth/vitsme', method: :post, data: { turbo: false } %>
+<% if verify? -%>
+<%%= button_to t('vitsme.verify'), '/auth/vitsme_verify', method: :post, data: { turbo: false } if session[:<%= session_key %>] %>
+<% end -%>

data/lib/generators/omniauth_vitsme/install/templates/add_vitsme_uid.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The private, per-site identifier vits.me returns (the OmniAuth uid). Unique, never shown.
+class AddVitsmeUidTo<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :<%= table_name %>, :vitsme_uid, :string
+    add_index :<%= table_name %>, :vitsme_uid, unique: true
+  end
+end

data/lib/generators/omniauth_vitsme/install/templates/omniauth_vitsme.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Sign in with vits.me (omniauth-vitsme). The uid it returns is a private, per-site identifier: store
+# it to find the person again, never show it, log it, put it in a URL or build a handle from it.
+vitsme = {
+  client_id: ENV.fetch('VITSME_CLIENT_ID', nil),
+  client_secret: ENV.fetch('VITSME_CLIENT_SECRET', nil),
+  environment: Rails.env.production? ? :production : :development
+}
+
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :vitsme, vitsme.merge(
+    scope: <%= symbols(sign_in_scopes) %><% unless gate.empty? %>,
+    # Only verified nationals of these countries finish signing in; vits.me asks for their consent.
+    nationality_gate: %w[<%= gate.join(' ') %>]<% end %>
+  )
+<% if verify? -%>
+
+  # Asks vits.me about the person already signed in here, and refuses an answer about anyone else.
+  provider :vitsme, vitsme.merge(
+    name: :vitsme_verify,
+    scope: <%= symbols(verify_scopes) %>,
+    expected_uid: ->(env) { <%= model %>.find_by(id: env['rack.session']['<%= session_key %>'])&.vitsme_uid }
+  )
+<% end -%>
+end

data/lib/generators/omniauth_vitsme/install/templates/vitsme.en.yml

@@ -0,0 +1,13 @@
+en:
+  vitsme:
+    sign_in: "Sign in"
+    verify: "Verify my details"
+    signed_in: "You are signed in."
+    verified: "Your details are verified."
+    failures:
+      default: "Signing in did not work. Please try again."
+      access_denied: "Signing in was cancelled."
+      not_signed_in: "Sign in first, then verify your details."
+      identity_mismatch: "That answer was about a different account than the one signed in here."
+      unverified_identity: "This needs a verified account. Finish verifying, then try again."
+      nationality_gate_refused: "Only verified nationals of the required countries can join."

data/lib/generators/omniauth_vitsme/install/templates/vitsme.he.yml

@@ -0,0 +1,13 @@
+he:
+  vitsme:
+    sign_in: "התחברות"
+    verify: "אימות הפרטים שלי"
+    signed_in: "התחברת בהצלחה."
+    verified: "הפרטים שלך אומתו."
+    failures:
+      default: "ההתחברות לא הצליחה. אפשר לנסות שוב."
+      access_denied: "ההתחברות בוטלה."
+      not_signed_in: "יש להתחבר קודם, ואז לאמת את הפרטים."
+      identity_mismatch: "התשובה התייחסה לחשבון אחר מזה שמחובר כאן."
+      unverified_identity: "נדרש חשבון מאומת. אפשר להשלים את האימות ולנסות שוב."
+      nationality_gate_refused: "רק אזרחים מאומתים של המדינות הנדרשות יכולים להצטרף."

data/lib/generators/omniauth_vitsme/install/templates/vitsme_callbacks_controller.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Where vits.me sends people back. Never log request.env['omniauth.auth']: it holds the private uid and
+# whatever the person chose to share.
+class VitsmeCallbacksController < ApplicationController
+  def sign_in
+    auth = request.env['omniauth.auth']
+    person = returning_person(auth) || <%= model %>.create!(vitsme_uid: auth.uid)
+    reset_session
+    session[:<%= session_key %>] = person.id
+    redirect_to root_path, notice: t('vitsme.signed_in')
+  end
+<% if verify? -%>
+
+  # The strategy has already checked that this answer is about the person signed in here
+  # (expected_uid). A claim the person chose not to share is absent — never treat that as false.
+  def verify
+    claims = request.env['omniauth.auth'].extra.claims
+    # Keep what you asked for, e.g.: current_<%= options[:model].underscore %>.update!(adult: claims['age__over_18'])
+    redirect_to root_path, notice: t('vitsme.verified')
+  end
+<% end -%>
+
+  # OmniAuth sends every refusal here with ?message=<failure type>.
+  def failure
+    redirect_to root_path, alert: t("vitsme.failures.#{params[:message]}", default: t('vitsme.failures.default'))
+  end
+
+  private
+
+  # A returning person may be on file under an earlier uid (vits.me's defunct_solids) or, if you ask
+  # for the fluid scope, under a pending-signup uid. Move them to the current one.
+  def returning_person(auth)
+    uids = auth.extra.lookup_uids + auth.extra.fluid_uids
+    person = <%= model %>.where(vitsme_uid: uids).min_by { |p| uids.index(p.vitsme_uid) }
+    person.update!(vitsme_uid: auth.uid) if person && person.vitsme_uid != auth.uid
+    person
+  end
+end

data/lib/omniauth/strategies/vitsme.rb

@@ -1,68 +1,186 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'uri'
 require 'omniauth_openid_connect'
+require 'omniauth/vitsme/issuers'
+require 'omniauth/vitsme/catalog'
+require 'omniauth/vitsme/auth_shape'
 
 module OmniAuth
   module Strategies
+    # Sign in with vits.me, or ask vits.me about someone already signed in to your app.
+    #
+    #   provider :vitsme, client_id: ..., client_secret: ...,
+    #            scope: %i[openid age__over_18],          # checked against data/claims.json at boot
+    #            nationality_gate: %w[IL],                # optional: only verified IL nationals get through
+    #            expected_uid: ->(env) { ... },           # "details about a signed-in person" only
+    #            require_verified: true                   # refuse pending (fluid_) identities
+    #
+    # See README.md for the auth hash, the failure types and the rules (the uid is private).
     class Vitsme < OpenIDConnect
       option :name, 'vitsme'
 
+      option :environment, :production
+      option :issuer, nil
       option :discovery, true
-      option :issuer, 'https://vits.me'
       option :client_signing_alg, :RS256
       option :scope, [:openid]
       option :response_type, 'code'
       option :response_mode, 'query'
+      # Every vits.me sign-in asks for the pincode; a regular person's session there lasts one site sign-in.
+      option :prompt, :login
+      option :pkce, true
 
       option :client_options, {
         identifier: nil,
         secret: nil,
-        scheme: 'https',
-        host: 'vits.me',
-        port: 443,
+        redirect_uri: nil,
+        scheme: nil,
+        host: nil,
+        port: nil,
         authorization_endpoint: '/oauth/authorize',
         token_endpoint: '/oauth/token',
         userinfo_endpoint: '/oauth/userinfo',
-        jwks_uri: '/oauth/discovery/keys'
+        jwks_uri: '/oauth/discovery/keys',
+        end_session_endpoint: nil
       }
 
       option :client_id, nil
       option :client_secret, nil
 
+      # Nationalities a person must hold to finish signing in (gate scopes `openid_nationality__xx`).
+      option :nationality_gate, []
+
+      # `->(env) { solid_or_nil }` — the uid your app holds for the person signed in to it. Set it on a
+      # provider that asks vits.me about that person (verify a name, an age, a nationality): the
+      # answer must be theirs. vits.me is told whom to expect, and the callback refuses anyone else.
+      option :expected_uid, nil
+      # Refuse a pending (fluid_) identity. nil = on whenever expected_uid is set.
+      option :require_verified, nil
+      # Tell vits.me whom you expect (OIDC `claims` sub value) so it pre-selects that person and refuses
+      # others. The callback checks either way.
+      option :send_expected_uid, true
+
+      FAILURES = %i[identity_mismatch not_signed_in unverified_identity nationality_gate_refused].freeze
+
+      def initialize(app, *args, &)
+        super
+        normalize_options!
+      end
+
       def uid
-        raw_info['sub']
+        user_info.raw_attributes[:sub] || user_info.raw_attributes['sub'] || user_info.sub
       end
 
-      info do
-        {
-          name: raw_info['name'] || raw_info['name__full'],
-          first_name: raw_info['given_name'],
-          last_name: raw_info['family_name'],
-          email: raw_info['email'],
-          birthday: raw_info['birthdate'] || raw_info['birthday'],
-          nationality: raw_info['nationality'],
-          age_over_13: raw_info['age__over_13'],
-          age_over_18: raw_info['age__over_18'],
-          age_over_21: raw_info['age__over_21']
-        }.compact
+      # Methods, not the `info { }` DSL: OmniAuth merges a DSL block with every ancestor's, and the base
+      # OpenID Connect strategy's would add email, first_name, nickname… — fields vits.me never sends.
+      def info
+        OmniAuth::Vitsme::AuthShape.info(uid, raw_info)
       end
 
-      extra do
-        { raw_info: raw_info }
+      def extra
+        OmniAuth::Vitsme::AuthShape.extra(uid, raw_info)
+      end
+
+      # vits.me issues no refresh token and its access token lapses five seconds after issue: everything
+      # it can tell you is already in `info` and `extra`.
+      def credentials
+        { id_token: access_token.id_token, scope: access_token.scope }
       end
 
       def raw_info
-        @raw_info ||= user_info.raw_attributes
+        @raw_info ||= user_info.raw_attributes.to_h.transform_keys(&:to_s)
+      end
+
+      def request_phase
+        return fail!(:not_signed_in) if options.expected_uid && expected_uid.empty?
+
+        super
+      end
+
+      def authorize_uri
+        uri = super
+        return uri unless options.expected_uid && options.send_expected_uid && !expected_uid.empty?
+
+        with_query(uri, 'claims' => { id_token: { sub: { value: expected_uid } } }.to_json)
+      end
+
+      def callback_phase
+        if params['error'] && (failure = OmniAuth::Vitsme::Catalog.failure_for(params['vitsme_error']))
+          return fail!(failure, CallbackError.new(error: params['error'], reason: params['error_description']))
+        end
+
+        super
+      end
+
+      # The identity checks run here, after the auth hash is built and before your app sees it.
+      def call_app!(env = @env)
+        return super unless on_callback_path? && env['omniauth.auth']
+
+        auth = env['omniauth.auth']
+        return fail!(:unverified_identity) if require_verified? && auth.dig('extra', 'identity').to_s == 'fluid'
+        return super unless options.expected_uid
+        return fail!(:not_signed_in) if expected_uid.empty?
+        return fail!(:identity_mismatch) unless Array(auth.dig('extra', 'lookup_uids')).include?(expected_uid)
+
+        super
       end
 
       private
 
+      def require_verified?
+        options.require_verified.nil? ? !options.expected_uid.nil? : options.require_verified
+      end
+
+      def expected_uid
+        @expected_uid ||= options.expected_uid.call(env).to_s
+      end
+
+      def normalize_options!
+        options.issuer ||= OmniAuth::Vitsme.issuer(options.environment)
+        scopes = (Array(options.scope).map(&:to_s) | ['openid']) +
+                 Array(options.nationality_gate).map { |code| "openid_nationality__#{code.to_s.downcase}" }
+        validate_scopes!(scopes)
+        options.scope = scopes.uniq.map(&:to_sym)
+      end
+
+      def validate_scopes!(scopes)
+        unknown = scopes.reject { |s| OmniAuth::Vitsme::Catalog.known_scope?(s) }
+        unless unknown.empty?
+          raise ArgumentError, "omniauth-vitsme: unknown scope(s) #{unknown.join(', ')}. " \
+                               "Known: #{OmniAuth::Vitsme::Catalog.scopes.join(', ')}, openid_nationality__<cc>."
+        end
+        return unless scopes.include?('fluid') && scopes.any? { |s| OmniAuth::Vitsme::Catalog.gate_scope?(s) }
+
+        raise ArgumentError, 'omniauth-vitsme: a nationality gate admits verified people only; ' \
+                             'vits.me refuses it together with the fluid scope.'
+      end
+
       def client_options
         opts = options.client_options
+        issuer = URI(options.issuer)
+        opts.scheme ||= issuer.scheme
+        opts.host ||= issuer.host
+        opts.port ||= issuer.port
         opts.identifier ||= options.client_id if options.client_id
         opts.secret ||= options.client_secret if options.client_secret
         opts
       end
+
+      # The base strategy needs client_options.redirect_uri spelled out; default it to this provider's
+      # callback on the current host (without the callback's own code/state query).
+      def redirect_uri
+        return super if client_options.redirect_uri
+
+        full_host + callback_path
+      end
+
+      def with_query(uri, extra)
+        parsed = URI(uri)
+        parsed.query = URI.encode_www_form(URI.decode_www_form(parsed.query.to_s) + extra.to_a)
+        parsed.to_s
+      end
     end
   end
 end