omniauth-vitsme 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a95f27003ba5e85db4705861d35ebbb62a8d4701a7494d01faec43144d4f4749
-  data.tar.gz: ab6049d8756893307f0076cc75c2f14f83042de57f292f1031ab052dfbec922e
+  metadata.gz: aa0610f9d0d2e8dd9f3712a4f5b071a5fd680d2218e8b6155e3383d95c191da1
+  data.tar.gz: cdf33cdcb3b192bd2ba1e05dd9836d4078fe9da5caa221b370746ebba2fd146a
 SHA512:
-  metadata.gz: 0dcb9ba6a03dac71969ed404f4e41d47cc47d21b2ca710ea55b36720afdbe11e8750347141f8cc6abdfaebfb65c95154be52655181626b7ae8740aa944580d82
-  data.tar.gz: e0980bf755901669c8c3eb2ea70dc4ab79532a6ee4adad032f940ffaa7ed19a8035f479197002bab62bbb41c47e912be2bd6085a77e9bdf1bf5386f4450a1594
+  metadata.gz: f317e9bafb4ad03afcb8bbbe582e322c4d2da73f5adb9d30a11c44b04aa2b1913f0ff9350c1450bc5a7e48583339084e45c6248baecca57d27c1fed01379af87
+  data.tar.gz: 1706fb04b709cc4577f76095c2416b58a767c24e2feab20341a2a78fe7c0a0cc41205e10448ea7aecd0ddfd18645f07337ea703b54057275f993088b366a3ce8

data/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md — omniauth-vitsme
+
+You are helping someone sign people in with vits.me, or ask vits.me about them, from a Ruby/Rails
+app. These rules are not style preferences: breaking one leaks a private identifier or credits one
+person's verified details to another.
+
+## Choosing what to ask for
+
+- Scopes, claims, types, value formats and gates are all in [data/claims.json](data/claims.json).
+  Read it instead of guessing; an unknown scope raises at boot.
+- Ask for the least that answers the question: `age__over_18` rather than `birthdate`, a gate
+  rather than `nationality` when "is this person Israeli?" is all you need.
+- vits.me has no email, phone, picture or username claim. Ask the person for anything else.
+
+## Rules
+
+1. **The uid is private.** `auth.uid` (`sub`), `extra.lookup_uids` and `extra.fluid_uids` are
+   per-site secrets. Store them server-side as the lookup key, and never render, log, put in a URL,
+   federate, or derive a handle or email from them.
+2. **Don't log the auth hash.** `request.env["omniauth.auth"]` holds the uid and every shared detail.
+3. **Follow-up questions about a signed-in person need `expected_uid`.** A provider that verifies a
+   name, an age or a nationality of someone already signed in to the app must set
+   `expected_uid: ->(env) { ...the signed-in person's stored uid... }`. Without it, whoever signs in
+   at vits.me gets their details credited to the signed-in account. Don't set it on the sign-in
+   provider: there is nobody to expect yet.
+4. **Missing is not false.** Any disclosure claim may be absent: not shared, not held, or hidden.
+   Branch on `true` / `false` / absent, and never default a missing boolean to `false`.
+5. **A gate emits nothing.** `nationality_gate:` admits only verified nationals. Success is the
+   answer, and a refusal is `:nationality_gate_refused`. It can't be combined with the `fluid` scope.
+6. **`fluid_` means unverified.** Without the `fluid` scope you never see one. With it, give such
+   people a limited, tentative account and merge it when `extra.fluid_uids` shows up on a verified
+   sign-in.
+7. **Read everything in the callback.** Tokens live 5 seconds and there is no refresh token. Nothing
+   can be fetched later.
+8. **Find returning people by `extra.lookup_uids`** (plus `fluid_uids` with FLUID), current first, and
+   move a record found under an older uid to `auth.uid`.
+9. **User-facing copy says "verified"**, not "vits.me-verified". There is no need to name vits.me to
+   end users.
+10. **Handle every failure type** in [README.md#failure-types](README.md#failure-types):
+    `not_signed_in`, `identity_mismatch`, `unverified_identity`, `nationality_gate_refused`,
+    `access_denied`.
+
+## Doing the work
+
+- Rails: `bin/rails g omniauth_vitsme:install` (see `--help`) writes the initializer, controller,
+  locales, button and migration correctly. Prefer it to hand-writing.
+- Tests: `require "omniauth/vitsme/test"`, then `OmniAuth::Vitsme::Test.mock_auth(...)` /
+  `.mock_failure(...)`. Mocks have the real shape; unknown claims raise.
+- A worked app: [examples/rails/app.rb](examples/rails/app.rb).
+- The skill [.claude/skills/vitsme-integrate/SKILL.md](.claude/skills/vitsme-integrate/SKILL.md) walks
+  through adding vits.me to an app end to end.
+
+## Working on this gem
+
+- `bundle exec rspec && bundle exec rubocop` must pass. The suite boots the example Rails app.
+- `data/claims.json` mirrors the vits.me server (`config/initializers/doorkeeper*.rb` in the
+  mattyr mono-repo). Change them together, and keep `spec/omniauth/vitsme/catalog_spec.rb`'s scope
+  list in step.
+- `AuthShape` builds the auth hash for both the strategy and the test helper. Change the shape there
+  only.
+- Pre-1.0: breaking changes are fine. Record them in CHANGELOG.md.

data/CHANGELOG.md

@@ -5,6 +5,57 @@ 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).
 
+## [0.2.1] - 2026-11-02
+
+### Fixed
+
+- The docs claimed OmniAuth's test mode skips the identity checks. It doesn't: test mode skips the
+  trip to vits.me, but `expected_uid` and `require_verified` still judge the mocked answer. The
+  README, the test helper and the skill now say so, and four specs pin the behaviour. The examples
+  mock someone else to get `:identity_mismatch` and keep `mock_failure` for refusals only vits.me
+  makes.
+
+## [0.2.0] - 2026-11-02
+
+A rewrite that brings the gem up to the vits.me platform. **Breaking:** the auth hash changed shape,
+and Ruby ≥ 3.3 is required.
+
+### Added
+
+- `expected_uid:` for follow-up questions about a person already signed in. vits.me is told whom to
+  expect (OIDC `claims` sub value) and pre-selects that person. The callback refuses anyone else
+  (`:identity_mismatch`) and fails early when nobody is signed in (`:not_signed_in`). Earlier SOLIDs
+  listed in `defunct_solids` still match.
+- `require_verified:` refuses pending (`fluid_`) identities (`:unverified_identity`). It is on by
+  default with `expected_uid`.
+- `nationality_gate: %w[IL]` adds `openid_nationality__xx` gate scopes. A gate refusal is
+  `:nationality_gate_refused`, read from vits.me's machine-readable `vitsme_error`. Combining a gate
+  with `fluid` raises at boot.
+- `environment:` (`:production` / `:staging` / `:development`) and `OmniAuth::Vitsme.issuer`. The host
+  is derived from the issuer.
+- `data/claims.json`: a machine-readable catalog of every scope, claim, type, gate and refusal.
+  `scope:` is validated against it at boot.
+- `extra.claims`: the shared claims, typed (booleans, integers). `extra.identity` (`:solid` / `:fluid`),
+  `extra.lookup_uids` (current + defunct) and `extra.fluid_uids`. `info.verified`.
+- PKCE (S256) and `prompt: :login` by default. `redirect_uri` defaults to the provider's callback.
+- `OmniAuth::Vitsme::Test` (`mock_auth`, `mock_failure`), which builds mocks with the real shape.
+- `bin/rails g omniauth_vitsme:install`: initializer, callbacks controller, en/he messages, sign-in
+  button, routes and a `vitsme_uid` migration.
+- `examples/rails/app.rb`, booted by the test suite. AGENTS.md, llms.txt and a Claude Code skill
+  (`.claude/skills/vitsme-integrate`).
+
+### Changed
+
+- `info` holds only what vits.me sends: `name`, `nationality`, `verified`. `credentials` holds
+  `id_token` and `scope` (vits.me issues no refresh token and its access token lapses in 5 s).
+
+### Removed
+
+- `info.first_name`, `last_name`, `email`, `birthday`, `age_over_*`: vits.me never sent the first
+  three. `birthday` conflated `birthdate` with a month-day value. The `age_over_*` flags passed
+  `"false"` through as a truthy string. Use `extra.claims`.
+- Ruby 3.0–3.2 support.
+
 ## [0.1.0] - 2026-02-11
 
 ### Added

data/README.md

@@ -1,182 +1,280 @@
 # OmniAuth vits.me
 
-OmniAuth strategy for [vits.me](https://vits.me) (itsme), global digital identity verification platform.
-
-Wraps [omniauth_openid_connect](https://github.com/omniauth/omniauth_openid_connect) with vits.me-specific defaults so you only need to supply `client_id` and `client_secret`.
-
-## Installation
-
-Add to your Gemfile:
+Sign people in with [vits.me](https://vits.me), ask about details they have verified there (a name, an
+age, a nationality), and admit only verified nationals of chosen countries. An OmniAuth strategy on top
+of [omniauth_openid_connect](https://github.com/omniauth/omniauth_openid_connect), with the vits.me
+rules built in.
+
+> **Agents:** read [AGENTS.md](AGENTS.md) first. Every scope and claim is in
+> [data/claims.json](data/claims.json).
+
+- [Quick start](#quick-start)
+- [Environments](#environments)
+- [Claims](#claims)
+- [Verifying a signed-in person](#verifying-a-signed-in-person)
+- [Gated communities](#gated-communities)
+- [Unverified (FLUID) identities](#unverified-fluid-identities)
+- [Finding a returning person](#finding-a-returning-person)
+- [Failure types](#failure-types)
+- [The auth hash](#the-auth-hash)
+- [Operational notes](#operational-notes)
+- [Privacy rules](#privacy-rules)
+- [Testing](#testing)
+- [Options](#options)
+
+## Quick start
 
 ```ruby
-gem "omniauth-vitsme", "~> 0.1"
+# Gemfile
+gem "omniauth-vitsme", "~> 0.2"
+gem "omniauth-rails_csrf_protection" # OmniAuth 2 starts sign-in by POST only
 ```
 
-Then run:
+The generator writes everything below: an initializer, a callbacks controller, failure messages
+(en/he), a sign-in button, routes, and a migration adding a unique `vitsme_uid` column.
 
 ```
-bundle install
+bin/rails g omniauth_vitsme:install [--model=User] [--scope=name] [--verify=age__over_18] [--gate=IL] [--fluid]
 ```
 
-## Usage
-
-### Rails (Rack middleware)
+Or by hand:
 
 ```ruby
 Rails.application.config.middleware.use OmniAuth::Builder do
   provider :vitsme,
     client_id: ENV["VITSME_CLIENT_ID"],
-    client_secret: ENV["VITSME_CLIENT_SECRET"]
+    client_secret: ENV["VITSME_CLIENT_SECRET"],
+    environment: Rails.env.production? ? :production : :development
 end
 ```
 
-### With additional scopes
+```erb
+<%= button_to "Sign in", "/auth/vitsme", method: :post, data: { turbo: false } %>
+```
+
+Client credentials come from the vits.me team: there is no self-service registration yet. Register
+`https://<your host>/auth/vitsme/callback` (and one callback per extra provider) as redirect URIs.
+
+## Environments
+
+| `environment:` | Issuer |
+|---|---|
+| `:production` (default) | `https://vits.me` |
+| `:staging` | `https://staging.vits.me` |
+| `:development` / `"test"` | `https://vitsme.localhost` (local, mkcert certificate) |
+
+`OmniAuth::Vitsme.issuer(Rails.env)` gives the same mapping. An explicit `issuer:` wins.
+
+## Claims
+
+Ask for a claim by its scope: `scope: %i[openid age__over_18 nationality]`. `openid` is always added.
+An unknown scope raises `ArgumentError` when the app boots. The full list, with types and value
+formats, is [data/claims.json](data/claims.json).
+
+| Scope = claim | Type in `extra.claims` | Example |
+|---|---|---|
+| `name` | String: one name at the detail the person chose | `"Jane"`, `"J. D."`, `"Jane Doe"` |
+| `name__full` | String | `"Jane Doe"` |
+| `nationality` | String, ISO 3166-1 alpha-2 | `"IL"` |
+| `nationality__in_eu`, `__in_eea`, `__in_esm`, `__gdpr_compliant` | Boolean | `true` |
+| `il_government_id_number` | String | (sensitive: ask only with a legal need) |
+| `age` | String: a threshold, generation, range or years | `"over_18"`, `"gen_x"`, `"25_to_34"`, `"37"` |
+| `age__years` | Integer | `37` |
+| `age__range` | String | `"25_to_34"` |
+| `age__over_13`, `__over_18`, `__over_21` | Boolean | `true` |
+| `birthdate` | String `YYYY-MM-DD` | `"1990-01-15"` |
+| `birthday` | String `M-D` or `YYYY-MM-DD`, as the person chose | `"1-15"` |
+| `birthyear` | String `YYYY` | `"1990"` |
+
+**The person chooses.** On vits.me's consent screen the person picks what to share for each scope,
+at the level of detail they prefer, or nothing at all.
+
+**Missing is not false.** A claim may be absent even when its scope was granted: the person shared
+nothing, holds no such detail, or hid it. `extra.claims["age__over_18"]` is `true`, `false`, or not
+there. Treat "not there" as "unknown", never as "no":
 
 ```ruby
-Rails.application.config.middleware.use OmniAuth::Builder do
-  provider :vitsme,
-    client_id: ENV["VITSME_CLIENT_ID"],
-    client_secret: ENV["VITSME_CLIENT_SECRET"],
-    scope: [:openid, :name, :age__over_18, :nationality]
+case auth.extra.claims["age__over_18"]
+when true  then admit
+when false then refuse
+else            ask_them_to_share_it
 end
 ```
 
-### Devise integration
+There is no email, phone, picture or username. If you need a public handle, ask the person for one.
+
+## Verifying a signed-in person
+
+vits.me signs in **whoever is at its keyboard** and answers about them. A provider that asks about the
+person *already signed in to your app* must make sure the answer is about them, or one person's
+verified details get credited to another. `expected_uid` does that:
 
 ```ruby
-Devise.setup do |config|
-  config.omniauth :vitsme,
-    client_id: ENV["VITSME_CLIENT_ID"],
-    client_secret: ENV["VITSME_CLIENT_SECRET"],
-    scope: [:openid, :name]
-end
+provider :vitsme,
+  name: :vitsme_verify,
+  client_id: ENV["VITSME_CLIENT_ID"], client_secret: ENV["VITSME_CLIENT_SECRET"],
+  scope: %i[openid age__over_18],
+  expected_uid: ->(env) { User.find_by(id: env["rack.session"]["user_id"])&.vitsme_uid }
 ```
 
-## Available Scopes
-
-| Scope | Description |
-|---|---|
-| `openid` | Required. Returns the subject identifier (`sub`). |
-| `name` | Given name and family name |
-| `name__full` | Full name as a single string |
-| `nationality` | ISO country code |
-| `nationality__in_eu` | Whether the user is an EU national |
-| `birthday` / `birthdate` | Date of birth |
-| `birthyear` | Year of birth |
-| `age__over_13` | Age verification (13+) |
-| `age__over_18` | Age verification (18+) |
-| `age__over_21` | Age verification (21+) |
+- Nobody signed in: the request fails `:not_signed_in` without leaving your app.
+- vits.me is told whom you expect (the standard OpenID Connect `claims` sub request). It opens the
+  pincode page on that person's account and refuses anyone else (`:identity_mismatch`).
+- The callback checks again, in the middleware, before your controller runs: the answer must be about
+  `expected_uid` or a uid vits.me lists in `defunct_solids`. Otherwise it fails `:identity_mismatch`.
+- With `expected_uid` set, a pending (`fluid_`) identity fails `:unverified_identity`
+  (`require_verified: false` turns that off).
 
-## Auth Hash
+Use `expected_uid` only for these follow-up questions. At sign-in there is nobody to expect yet.
 
-The auth hash returned in the callback looks like:
+## Gated communities
 
 ```ruby
-{
-  provider: "vitsme",
-  uid: "pairwise-subject-identifier",
-  info: {
-    name: "Jane Doe",
-    first_name: "Jane",
-    last_name: "Doe",
-    email: "jane@example.com",
-    birthday: "1990-01-15",
-    nationality: "IL",
-    age_over_13: true,
-    age_over_18: true,
-    age_over_21: true
-  },
-  credentials: {
-    id_token: "eyJ...",
-    token: "access_token_value",
-    refresh_token: "refresh_token_value",
-    expires_in: 3600,
-    scope: "openid name"
-  },
-  extra: {
-    raw_info: {
-      sub: "pairwise-subject-identifier",
-      name: "Jane Doe",
-      # ... all raw claims from the userinfo endpoint
-    }
-  }
-}
+provider :vitsme, client_id: ..., client_secret: ..., nationality_gate: %w[IL]
 ```
 
-Only requested scopes will appear in `info`. Nil values are omitted via `.compact`.
+Only verified people holding one of the listed nationalities finish signing in. Several codes mean
+any of them. vits.me asks the person to consent to this check. **The gate sends no claim back**: a
+successful sign-in is the answer. Add the `nationality` scope if you also want the value. A person
+who doesn't pass returns as `:nationality_gate_refused`, and no account is created.
 
-Note: vits.me uses **pairwise subject identifiers** -- the same person will have a different `uid` for each registered client application.
+A gate admits verified people only, so it can't be combined with the `fluid` scope (that raises at
+boot). Make your gated sign-in button look different from an ordinary one, so people know before they
+start. To build a community that way, follow madon's lead: gate the sign-in, then ask the new member
+to pick a public handle. Never derive the handle from the uid.
 
-## Configuration
+## Unverified (FLUID) identities
 
-This gem is a wrapper for [omniauth_openid_connect](https://github.com/omniauth/omniauth_openid_connect). All configuration options available for `omniauth_openid_connect` can be used with `omniauth-vitsme`. The most common options are listed below.
+By default only verified people can sign in. With `scope: %i[openid fluid]`, people whose verification
+is still pending can sign in too:
 
-| Option | Default | Description |
-|---|---|---|
-| `client_id` | *required* | Your vits.me client ID |
-| `client_secret` | *required* | Your vits.me client secret |
-| `scope` | `[:openid]` | OIDC scopes to request |
-| `discovery` | `true` | Fetch endpoints from `.well-known/openid-configuration` |
-| `issuer` | `https://vits.me` | OIDC issuer URL |
-| `response_type` | `code` | OAuth response type (Authorization Code Flow) |
+- `uid` starts with `fluid_`, `extra.identity` is `:fluid`, and `info.verified` is `false`.
+- A pending identity lasts one week. Give it a limited, tentative account.
+- When the person is verified, a later sign-in returns their `solid_` uid with the pending uids in
+  `extra.fluid_uids`. Merge the tentative account into the verified one, and drop tentative accounts
+  nobody claimed after a week.
 
-## Environments
+## Finding a returning person
 
-For development or staging environments, Vits.me may provide a separate set of endpoints. You can configure these by overriding the `client_options`.
+Look a person up by `extra.lookup_uids`, current uid first, plus `extra.fluid_uids` if you use FLUID.
+A record found under an older uid belongs to this person: move it to `auth.uid`.
 
 ```ruby
-Rails.application.config.middleware.use OmniAuth::Builder do
-  provider :vitsme,
-    name: 'vitsme_staging', # Give it a unique name
-    client_id: ENV["VITSME_STAGING_CLIENT_ID"],
-    client_secret: ENV["VITSME_STAGING_CLIENT_SECRET"],
-    client_options: {
-      site: 'https://staging.vits.me',
-      authorize_url: 'https://staging.vits.me/oauth/authorize',
-      token_url: 'https://staging.vits.me/oauth/token',
-      userinfo_endpoint: 'https://staging.vits.me/userinfo'
-    }
-end
+uids = auth.extra.lookup_uids + auth.extra.fluid_uids
+user = User.where(vitsme_uid: uids).min_by { |u| uids.index(u.vitsme_uid) }
+user&.update!(vitsme_uid: auth.uid) unless user&.vitsme_uid == auth.uid
+user ||= User.create!(vitsme_uid: auth.uid)
 ```
-**Note:** The URLs in the example above are placeholders. Please refer to the official Vits.me documentation for the correct staging URLs.
 
-## Authentication Failures
+(vits.me lists superseded uids in `defunct_solids` for a year after a re-key.)
 
-If the user denies the authentication request or if there's a misconfiguration, OmniAuth will redirect to the `/auth/failure` path in your application. The `omniauth.error` and `omniauth.error.type` variables will be set in the Rack environment.
+## Failure types
 
-You can catch these failures by creating a `FailureEndpoint` in your application, for example, by routing `/auth/failure` to a specific controller action.
+OmniAuth sends failures to `OmniAuth.config.on_failure` (in Rails, `/auth/failure?message=<type>`).
 
-In a Rails application, you can handle this in your `OmniAuth::FailureEndpoint`:
+| Type | Meaning |
+|---|---|
+| `:not_signed_in` | `expected_uid` returned nothing: nobody is signed in to your app. |
+| `:identity_mismatch` | The answer was about someone other than `expected_uid`, whether caught by vits.me or by the callback. |
+| `:unverified_identity` | A pending (`fluid_`) identity, refused by `require_verified`. |
+| `:nationality_gate_refused` | The person doesn't hold a nationality the gate requires (or is unverified). |
+| `:access_denied` | Any other refusal, e.g. the person cancelled. |
+| others | From omniauth_openid_connect: `:csrf_detected`, `:invalid_grant`, `:timeout`, … |
+
+## The auth hash
 
 ```ruby
-# config/initializers/omniauth.rb
-OmniAuth.config.on_failure = Proc.new { |env|
-  OmniAuth::FailureEndpoint.new(env).redirect_to_failure
+{
+  provider: "vitsme",
+  uid: "solid_…",                      # private: store, never show or log
+  info: { name: "Jane D.", nationality: "IL", verified: true },  # only what was shared
+  credentials: { id_token: "…", scope: "openid name" },          # no refresh token
+  extra: {
+    identity: :solid,                  # or :fluid
+    lookup_uids: ["solid_…", "solid_<earlier>"],
+    fluid_uids: [],
+    claims: { "name" => "Jane D.", "age__over_18" => true },     # typed, shared claims only
+    raw_info: { "sub" => "solid_…", … }                          # the UserInfo response, verbatim
+  }
 }
 ```
 
+`info.name` is the shared `name` (or `name__full`). OmniAuth always includes the key, which may be nil.
+
+## Operational notes
+
+- **Read everything in the callback.** Authorization codes, access tokens and ID tokens live for
+  **5 seconds** and there is no refresh token. The strategy redeems the code and fetches UserInfo at
+  once. Keep your server's clock in sync (NTP): a few seconds of skew fails ID-token validation.
+- **Every sign-in asks for the pincode.** A regular person's vits.me session lasts one site sign-in,
+  so there is no single sign-on between sites and `prompt=none` cannot succeed. `prompt: :login` is the
+  default. A "verify" round-trip asks for the pincode too.
+- **No logout endpoint.** Sign people out of your app; there's nothing to end at vits.me.
+- **PKCE (S256) is on** by default, alongside the client secret.
+- **Claims arrive from UserInfo, not the ID token.** The strategy handles this.
+
+## Privacy rules
+
+- The uid (`sub`), `lookup_uids` and `fluid_uids` are **private, per-site identifiers**. Treat them
+  like session tokens: store them server-side as the lookup key, and **never** render them, log them,
+  put them in a URL, federate them, or derive a username, handle or email from them.
+- Don't log `request.env["omniauth.auth"]`: it holds the uid and everything the person shared.
+- Ask for the least you need. `age__over_18` answers "is this an adult?". `birthdate` answers far more.
+- In copy your users read, call people "verified". There is no need to name vits.me.
+
+## Testing
+
 ```ruby
-# app/controllers/omniauth_callbacks_controller.rb
-class OmniauthCallbacksController < Devise::OmniauthCallbacksController
-  def failure
-    # Your custom failure logic here.
-    # For example, redirect to the root path with an error message.
-    redirect_to root_path, alert: "Authentication failed: #{params[:message]}"
-  end
-end
+require "omniauth/vitsme/test"
+
+OmniAuth.config.test_mode = true
+OmniAuth::Vitsme::Test.mock_auth(claims: { age__over_18: true })                 # :vitsme
+OmniAuth::Vitsme::Test.mock_auth(:vitsme_verify, uid: user.vitsme_uid, claims: { name: "Jane D." })
+OmniAuth::Vitsme::Test.mock_auth(identity: :fluid)                               # pending signup
+OmniAuth::Vitsme::Test.mock_auth(:vitsme_verify, uid: someone_else_uid)                   # → :identity_mismatch
+OmniAuth::Vitsme::Test.mock_failure(:vitsme, :nationality_gate_refused)
 ```
 
-The `params[:message]` will contain a description of the error (e.g., `invalid_credentials`).
+Mocks are built by the same code as real sign-ins, so they have the real shape and types, and
+unknown claims raise. Test mode skips the round trip to vits.me, but the strategy's identity checks
+still run on the mock. A verify provider's `expected_uid` and `require_verified` judge the mocked
+answer exactly as they would a real one: mock the signed-in person's uid to pass, or someone else's
+to see `:identity_mismatch`. A mocked earlier uid (`defunct_uids:`) matches as it does in
+production. `mock_failure` simulates refusals that only vits.me can make, such as
+`:nationality_gate_refused` or `:access_denied`.
+
+[examples/rails/app.rb](examples/rails/app.rb) is a one-file Rails app using sign-in, a gate and
+verification. The test suite boots it against a stubbed vits.me.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `client_id`, `client_secret` | required | From the vits.me team |
+| `environment` | `:production` | `:production`, `:staging`, `:development` |
+| `issuer` | from `environment` | |
+| `scope` | `[:openid]` | Validated against [data/claims.json](data/claims.json) |
+| `nationality_gate` | `[]` | ISO alpha-2 codes, e.g. `%w[IL]` |
+| `expected_uid` | `nil` | `->(env) { uid }` for follow-up questions about a signed-in person |
+| `require_verified` | on when `expected_uid` is set | Refuse `fluid_` identities |
+| `send_expected_uid` | `true` | Tell vits.me whom you expect |
+| `prompt` | `:login` | |
+| `pkce` | `true` | S256 |
+| `name` | `"vitsme"` | Set a different name for each additional provider |
+
+Everything else is passed to omniauth_openid_connect.
 
 ## Development
 
 ```
 bundle install
-bundle exec rspec
+bundle exec rspec     # strategy, catalog, generator, and the example Rails app
 bundle exec rubocop
-bundle exec rake        # runs both
 ```
 
+The catalog mirrors the vits.me server. When vits.me adds a scope, it lands in `data/claims.json` in
+the same change (vits.me's `docs/adding-vitsme-scope.md`).
+
 ## License
 
 MIT License. See [LICENSE.txt](LICENSE.txt).