omniauth-vitsme 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d349b546c14e9d6f7ec72ccd03a9aac7e8db44d711523c12d904a210cb65c1c
-  data.tar.gz: 839203e14305b75c1bdec348436be83745a9c582cf9dc37360d2421a6dbce54d
+  metadata.gz: 6b035cc18e25e105be04f7bb8f4a97ab65ae642cf4496efed8029311f73bcd8d
+  data.tar.gz: 44f4d03aecd52c51abf90fead1e1326508791192563149ebe854101f4409fcf6
 SHA512:
-  metadata.gz: 645645d4761352f621b88994d6d95d53a9d9ef882b5e878b68f137153cd95ed13a514507dbcc070ce4c352381aeb9fe19da415716678c5781030cb7793d99659
-  data.tar.gz: 90749983f5c6ba32121b08bebcf34d36fbeaf387d7fb5bd7268a3312fc589b9345300238f9b1e60f43a62211953de22c180a0b3fff998c06936918dfb1b81704
+  metadata.gz: 8ae6b954c46918c6e03104a3d81f153add7d6c44a1d3a227a9fd534f03566b37c330a70d2a76a63111830113b29e3a98ff0556dfb99a7aa01c7becee82980df6
+  data.tar.gz: 8ea8e3002b36594fb4c998be15515887b8801c26bcde6a57d17dda4c4fc7add6d0c06d1dcf04248b9dc919e2ec200088e0a10fbd821474c772df6fc048f1f8a4

data/AGENTS.md

@@ -30,8 +30,8 @@ person's verified details to another.
 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.
+7. **Read everything in the callback.** Tokens live 5 seconds and there is no refresh token. The one
+   exception is KNOT claims, below.
 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
@@ -42,6 +42,15 @@ person's verified details to another.
 11. **Ask only for scopes the site registered.** Its page at vits.me/developer sets which it may ask
     for, and vits.me refuses a request for any other. `il_government_id_number` is enabled by vits.me
     on request, per site.
+12. **KNOT claims come from partners, and partners come and go.** Don't hard-code a partner or the
+    shape of its claims from memory: read the scope's description and documentation link from
+    `OmniAuth::Vitsme::Knot.scopes` (or the site's page at vits.me/developer). Claims arrive in
+    `extra.knot_claims`, already verified; missing is unknown, and a partner that can't be asked shows
+    in `extra.knot_errors` without failing the sign-in. While the person's consent stands, refresh with
+    `OmniAuth::Vitsme::Knot.fresh_claims`, and handle `ConsentRequired` by letting go of what you had.
+13. **Verify every change event** with `OmniAuth::Vitsme::Events.verify!` before acting on it, answer
+    `202`, and treat it as idempotent. It never carries values: refetch on `:claims_changed`, forget on
+    `:consent_withdrawn`, whose `reason` is `withdrawn` (the person) or `retired` (the partner left).
 
 ## Doing the work
 

data/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-11-10
+
+### Added
+
+- KNOT claims, from partner services. The gem knows no partner: any `knot:<knot>:<name>` scope passes
+  the boot-time scope check, and vits.me refuses one your site wasn't granted. When UserInfo carries
+  KNOT sources, the strategy fetches each partner's answer during the callback, verifies its signature
+  against the source's `jwks_uri`, issuer, audience (your client_id) and `knot_txn`, and puts the claims
+  in `extra.knot_claims` as sent. A partner that can't be asked shows in `extra.knot_errors` and doesn't
+  fail the sign-in.
+- `OmniAuth::Vitsme::Knot.scopes` reads the active KNOT scopes as vits.me describes them now (what each
+  answer holds, and a documentation link).
+- `OmniAuth::Vitsme::Knot.fresh_claims` asks for KNOT claims again without the person, while their
+  standing consent holds, raising `ConsentRequired` once it doesn't.
+- `OmniAuth::Vitsme::Events.verify!` verifies the change events vits.me pushes to a site's change
+  notifications URL: `:claims_changed`, and `:consent_withdrawn` with a `reason` of `withdrawn` or
+  `retired` (the partner or scope left).
+- `OmniAuth::Vitsme::Test.mock_auth(knot_claims:)`.
+- `data/claims.json` has a generic `knots` section and the introduction's 30-second lifetime
+  (catalog 3). It lists no partner.
+
+### Changed
+
+- `extra.raw_info` no longer carries `_claim_names`, `_claim_sources` or `knot_txn`: they are spent
+  during the callback.
+
 ## [0.3.0] - 2026-11-05
 
 ### Added

data/README.md

@@ -26,7 +26,7 @@ rules built in.
 
 ```ruby
 # Gemfile
-gem "omniauth-vitsme", "~> 0.3"
+gem "omniauth-vitsme", "~> 0.4"
 gem "omniauth-rails_csrf_protection" # OmniAuth 2 starts sign-in by POST only
 ```
 
@@ -158,6 +158,69 @@ is still pending can sign in too:
   `extra.fluid_uids`. Merge the tentative account into the verified one, and drop tentative accounts
   nobody claimed after a week.
 
+## Partner services (KNOT claims)
+
+Some facts come from partner services rather than vits.me. Partners come and go, so this gem knows none
+of them: it handles whatever KNOT scopes your site chose to work with. The active ones, each with what its
+answer holds and a documentation link, are listed by vits.me; choose them under Partners on your site's
+form at vits.me/developer, and its page there shows the ones it holds:
+
+```ruby
+OmniAuth::Vitsme::Knot.scopes   # [{ "scope" => "knot:<knot>:<name>", "knot" => "…", "claim" => "…",
+                                #    "title" => {…}, "description" => {…}, "documentation_url" => "…" }]
+```
+
+Ask for one like any other scope:
+
+```ruby
+provider :vitsme, client_id: ENV["VITSME_APP_ID"], client_secret: ENV["VITSME_APP_SECRET"],
+                  scope: %i[openid knot:<knot>:<name>]
+```
+
+The person agrees on vits.me's consent screen. During the callback the strategy fetches the partner's
+answer, verifies its signature, and hands you the claims as the partner sent them:
+
+```ruby
+auth.extra.knot_claims  # { "<claim>" => <the partner's answer> }; its shape is in the partner's documentation
+auth.extra.knot_errors  # { "<knot>" => "HTTP 503" } when a partner could not be asked
+```
+
+A claim missing from `knot_claims` is unknown, never false. A partner that cannot be reached never
+fails the sign-in.
+
+**Fresh claims, without the person.** While they keep the consent (a year from their last agreement),
+ask again:
+
+```ruby
+result = OmniAuth::Vitsme::Knot.fresh_claims(uid: person.vitsme_uid, scopes: %w[knot:<knot>:<name>],
+                                             client_id: ENV["VITSME_APP_ID"], client_secret: ENV["VITSME_APP_SECRET"])
+result.claims  # as above
+# raises OmniAuth::Vitsme::Knot::ConsentRequired once they no longer share it
+```
+
+**Change events.** Set a change notifications URL on your site's page, and vits.me POSTs to it when a
+partner says something changed for someone, when they stop sharing, or when a partner or scope leaves.
+Verify each one:
+
+```ruby
+class VitsmeEventsController < ActionController::API
+  def create
+    event = OmniAuth::Vitsme::Events.verify!(request.raw_post, client_id: ENV["VITSME_APP_ID"],
+                                             environment: Rails.env)
+    person = Person.find_by(vitsme_uid: event.uid)
+    case event.type
+    when :claims_changed then RefreshPartnerClaimsJob.perform_later(person.id, event.scopes) if person
+    when :consent_withdrawn then person&.forget_partner_claims!(event.scopes)  # event.reason: "withdrawn" or "retired"
+    end
+    head :accepted
+  rescue OmniAuth::Vitsme::Events::Invalid
+    head :bad_request
+  end
+end
+```
+
+Events never carry values, may arrive twice, and are retried until you answer `202`.
+
 ## Finding a returning person
 
 Look a person up by `extra.lookup_uids`, current uid first, plus `extra.fluid_uids` if you use FLUID.
@@ -200,7 +263,9 @@ OmniAuth sends failures to `OmniAuth.config.on_failure` (in Rails, `/auth/failur
     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
+    knot_claims: { "<claim>" => … },                              # from partner services, verified
+    knot_errors: {},                                             # partners that could not be asked
+    raw_info: { "sub" => "solid_…", … }                          # the UserInfo response, without KNOT sources
   }
 }
 ```

data/data/claims.json

@@ -1,5 +1,5 @@
 {
-  "catalog_version": 2,
+  "catalog_version": 3,
   "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.",
@@ -149,6 +149,14 @@
       "incompatible_with": ["fluid"]
     }
   },
+  "knots": {
+    "scope_pattern": "^knot:[^:\\s]+:\\S+$",
+    "scope_format": "knot:<knot>:<name>",
+    "description": "Claims from a partner service (a KNOT) that verifies what vits.me does not, served to your site directly. Partners come and go, so none is listed here: GET <issuer>/knot/scopes lists the active KNOT scopes, each with what its answer holds and a documentation URL (OmniAuth::Vitsme::Knot.scopes), and your site's page at vits.me/developer shows the ones staff granted it. The person agrees on vits.me's consent screen; left on, the agreement stands for a year and can be withdrawn at any time. When a partner leaves, its consents end and you get consent_withdrawn with reason retired.",
+    "auth_hash": "extra.knot_claims (by claim name, fetched and verified during the callback) and extra.knot_errors (by source). Missing is unknown, never false.",
+    "fresh_claims": "While the consent stands: OmniAuth::Vitsme::Knot.fresh_claims(uid:, scopes:, client_id:, client_secret:). Raises ConsentRequired once it no longer does.",
+    "events": "Set a change notifications URL on your registration; verify each POST with OmniAuth::Vitsme::Events.verify! (types claims_changed, consent_withdrawn with reason withdrawn or retired) and answer 202."
+  },
   "refusals": {
     "nationality_gate": {
       "error": "access_denied",
@@ -175,6 +183,7 @@
     "authorization_code": 5,
     "access_token": 5,
     "id_token": 5,
+    "knot_introduction": 30,
     "refresh_token": null
   }
 }

data/lib/omniauth/strategies/vitsme.rb

@@ -17,6 +17,9 @@ module OmniAuth
     #            expected_uid: ->(env) { ... },           # "details about a signed-in person" only
     #            require_verified: true                   # refuse pending (fluid_) identities
     #
+    # A KNOT scope (knot:<knot>:<name>) asks a partner service; its claims arrive verified in
+    # extra.knot_claims (OmniAuth::Vitsme::Knot).
+    #
     # See README.md for the auth hash, the failure types and the rules (the uid is private).
     class Vitsme < OpenIDConnect
       option :name, 'vitsme'
@@ -80,7 +83,17 @@ module OmniAuth
       end
 
       def extra
-        OmniAuth::Vitsme::AuthShape.extra(uid, raw_info)
+        OmniAuth::Vitsme::AuthShape.extra(uid, raw_info, knot: knot)
+      end
+
+      # The KNOT sources in UserInfo, fetched and verified now: their introductions live 30 seconds.
+      def knot
+        return @knot if defined?(@knot)
+
+        @knot = (if raw_info['_claim_sources']
+                   OmniAuth::Vitsme::Knot.resolve(raw_info,
+                                                  client_id: client_options.identifier)
+                 end)
       end
 
       # vits.me issues no refresh token and its access token lapses five seconds after issue: everything

data/lib/omniauth/vitsme/auth_shape.rb

@@ -7,6 +7,8 @@ module OmniAuth
     module AuthShape
       SOLID_PREFIX = 'solid_'
       FLUID_PREFIX = 'fluid_'
+      # Spent as soon as the strategy fetched them, and none of your app's business afterwards.
+      KNOT_SOURCE_KEYS = %w[_claim_names _claim_sources knot_txn].freeze
 
       module_function
 
@@ -24,7 +26,9 @@ module OmniAuth
         }.compact
       end
 
-      def extra(uid, raw_info)
+      # `knot` is the Knot::Result for this sign-in's KNOT sources, if it had any.
+      def extra(uid, raw_info, knot: nil)
+        knot ||= Knot::Result.empty
         {
           identity: identity_kind(uid),
           # Look a returning person up by every one of these, current first: a record keyed by a defunct
@@ -33,7 +37,11 @@ module OmniAuth
           # Tentative accounts (keyed by a pending signup's FLUID) to merge into this person.
           fluid_uids: Array(raw_info['fluid']),
           claims: claims(raw_info),
-          raw_info: raw_info
+          # Claims from KNOTs, by claim name, already fetched and verified ({ "<claim>" => <answer> }),
+          # and why a KNOT could not be asked, by source. A claim missing here is unknown, never false.
+          knot_claims: knot.claims,
+          knot_errors: knot.errors,
+          raw_info: raw_info.except(*KNOT_SOURCE_KEYS)
         }
       end
 

data/lib/omniauth/vitsme/catalog.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'omniauth/vitsme/knot'
 
 module OmniAuth
   module Vitsme
@@ -31,8 +32,10 @@ module OmniAuth
         GATE_PATTERN.match?(scope.to_s)
       end
 
+      # KNOT scopes (knot:<knot>:<name>) are registered data on vits.me, not catalog entries: any well-formed
+      # one is accepted here, and vits.me refuses one your site was not granted.
       def known_scope?(scope)
-        scopes.include?(scope.to_s) || gate_scope?(scope)
+        scopes.include?(scope.to_s) || gate_scope?(scope) || Knot.scope?(scope)
       end
 
       # The OmniAuth failure type for a `vitsme_error` refusal reason, or nil for an unknown one.

data/lib/omniauth/vitsme/events.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'omniauth/vitsme/jws'
+require 'omniauth/vitsme/issuers'
+
+module OmniAuth
+  module Vitsme
+    # The change events vits.me POSTs to your site's change notifications URL (Security Event Tokens,
+    # RFC 8417, pushed per RFC 8935 with Content-Type application/secevent+jwt), while someone keeps a
+    # standing consent with your site:
+    #
+    #   :claims_changed     what a KNOT would tell you about them changed: ask again (Knot.fresh_claims)
+    #   :consent_withdrawn  they stopped sharing (reason "withdrawn"), or the partner or scope left
+    #                       (reason "retired"): let go of what you were given
+    #
+    # An event never carries values. Answer 202; anything else is retried. Events are idempotent and may
+    # arrive twice.
+    #
+    #   event = OmniAuth::Vitsme::Events.verify!(request.raw_post, client_id: ENV['VITSME_APP_ID'])
+    #   person = Person.find_by(vitsme_uid: event.uid)  # the uid is private, as everywhere
+    module Events
+      TYPES = {
+        'https://vits.me/secevent/knot/claims-changed' => :claims_changed,
+        'https://vits.me/secevent/knot/consent-withdrawn' => :consent_withdrawn
+      }.freeze
+      CONTENT_TYPE = 'application/secevent+jwt'
+      MAX_AGE = 300
+
+      class Invalid < StandardError; end
+
+      Event = Struct.new(:type, :uid, :scopes, :reason, :id, :issued_at, keyword_init: true)
+
+      module_function
+
+      def verify!(token, client_id:, environment: :production, issuer: nil, now: Time.now)
+        issuer ||= Vitsme.issuer(environment)
+        claims = JWS.verify!(token, jwks_uri: "#{issuer}/oauth/discovery/keys", iss: issuer, aud: client_id,
+                                    typ: 'secevent+jwt', expiring: false, now: now)
+        raise Invalid, 'stale or future event' unless (claims['iat'].to_i - now.to_i).abs <= MAX_AGE
+
+        event(claims, issuer)
+      rescue JWS::Invalid, Keys::Unavailable => e
+        raise Invalid, e.message
+      end
+
+      def event(claims, issuer)
+        sub_id = claims['sub_id']
+        unless sub_id.is_a?(Hash) && sub_id['format'] == 'iss_sub' && sub_id['iss'] == issuer
+          raise Invalid,
+                'unsupported subject'
+        end
+
+        type_uri, body = Hash(claims['events']).find { |uri, _| TYPES.key?(uri) }
+        raise Invalid, 'unsupported event' unless type_uri
+
+        body = Hash(body)
+        Event.new(type: TYPES[type_uri], uid: sub_id['sub'], scopes: body['scope'].to_s.split, reason: body['reason'],
+                  id: claims['jti'], issued_at: Time.at(claims['iat'].to_i))
+      end
+    end
+  end
+end

data/lib/omniauth/vitsme/http.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module OmniAuth
+  module Vitsme
+    # The few HTTPS calls the gem makes outside the OpenID Connect flow: KNOT claims, fresh introductions
+    # and published keys. Short timeouts; any transport failure is HTTP::Unavailable.
+    module HTTP
+      TIMEOUT = 5
+
+      class Unavailable < StandardError; end
+
+      Response = Struct.new(:status, :body) do
+        def ok? = status.between?(200, 299)
+        def json = JSON.parse(body)
+      end
+
+      module_function
+
+      def get(url, headers = {})
+        request(Net::HTTP::Get.new(URI(url), headers))
+      end
+
+      def post_form(url, form, basic: nil, headers: {})
+        req = Net::HTTP::Post.new(URI(url), headers)
+        req.set_form_data(form)
+        req.basic_auth(*basic) if basic
+        request(req)
+      end
+
+      def request(req)
+        uri = req.uri
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                                       open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+          http.request(req)
+        end
+        Response.new(response.code.to_i, response.body.to_s)
+      rescue SocketError, SystemCallError, IOError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+        raise Unavailable, e.class.name
+      end
+    end
+  end
+end

data/lib/omniauth/vitsme/jws.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'json/jwt'
+require 'omniauth/vitsme/keys'
+
+module OmniAuth
+  module Vitsme
+    # Verifies a signed JWT from vits.me or a KNOT: RS256 against the keys at `jwks_uri`, then the claims
+    # the caller names. Raises JWS::Invalid with a short reason.
+    module JWS
+      LEEWAY = 30
+
+      class Invalid < StandardError; end
+
+      module_function
+
+      # The verified claims, as a Hash with string keys.
+      def verify!(token, jwks_uri:, iss:, aud:, typ: nil, expiring: true, now: Time.now)
+        claims = signed_claims(token, jwks_uri: jwks_uri, typ: typ)
+        raise Invalid, 'unexpected issuer' unless claims['iss'] == iss
+        raise Invalid, 'not addressed to you' unless Array(claims['aud']).include?(aud)
+        raise Invalid, 'expired' if expiring && claims['exp'].to_i + LEEWAY < now.to_i
+
+        claims
+      end
+
+      # The payload once the signature checks out. `alg: none` and every algorithm but RS256 are refused.
+      def signed_claims(token, jwks_uri:, typ:)
+        header = JSON::JWT.decode(token.to_s, :skip_verification).header
+        raise Invalid, 'unexpected type' if typ && header['typ'] != typ
+
+        keys = Keys.for(jwks_uri, kid: header['kid'])
+        JSON::JWT.decode(token.to_s, keys, [:RS256]).to_h.transform_keys(&:to_s)
+      rescue JSON::JWT::Exception => e
+        raise Invalid, e.class.name.split('::').last
+      end
+    end
+  end
+end

data/lib/omniauth/vitsme/keys.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'json/jwt'
+require 'omniauth/vitsme/http'
+
+module OmniAuth
+  module Vitsme
+    # Published signing keys (a JWKS URL's JSON::JWK::Set), cached per URL for TTL seconds and fetched again
+    # once when a token names a key the cache does not hold (rotation).
+    module Keys
+      TTL = 600
+
+      class Unavailable < StandardError; end
+
+      @cache = {}
+      @mutex = Mutex.new
+
+      class << self
+        def for(jwks_uri, kid:)
+          set = cached(jwks_uri)
+          return set if kid.nil? || set.any? { |jwk| jwk[:kid] == kid }
+
+          fetch(jwks_uri)
+        end
+
+        def clear!
+          @mutex.synchronize { @cache.clear }
+        end
+
+        private
+
+        def cached(jwks_uri)
+          entry = @mutex.synchronize { @cache[jwks_uri] }
+          return entry[:set] if entry && entry[:at] > Time.now - TTL
+
+          fetch(jwks_uri)
+        end
+
+        def fetch(jwks_uri)
+          response = HTTP.get(jwks_uri, 'Accept' => 'application/json')
+          raise Unavailable, "keys: HTTP #{response.status}" unless response.ok?
+
+          set = JSON::JWK::Set.new(response.json)
+          @mutex.synchronize { @cache[jwks_uri] = { set: set, at: Time.now } }
+          set
+        rescue JSON::ParserError, HTTP::Unavailable => e
+          raise Unavailable, "keys: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/omniauth/vitsme/knot.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'omniauth/vitsme/http'
+require 'omniauth/vitsme/jws'
+require 'omniauth/vitsme/issuers'
+
+module OmniAuth
+  module Vitsme
+    # Claims from KNOTs: partner services that verify what vits.me does not (organization memberships, for
+    # one) and serve it to sites directly, with vits.me brokering identity and consent.
+    #
+    # vits.me's UserInfo names each KNOT source with an `endpoint`, an `access_token` (an introduction,
+    # encrypted to the KNOT and opaque to you), and the KNOT's `iss` and `jwks_uri`. The KNOT answers with a
+    # JWS, `aud` your client_id and `sub` the response's `knot_txn`. Introductions live 30 seconds and work
+    # once, so the strategy fetches them while it builds the auth hash.
+    module Knot
+      # Partners come and go, so the gem knows none of them: any well-formed KNOT scope is accepted, and
+      # vits.me refuses one your site was not granted.
+      SCOPE_PATTERN = /\Aknot:[^:\s]+:\S+\z/
+
+      class ConsentRequired < StandardError; end
+      class InvalidClient < StandardError; end
+      class Unavailable < StandardError; end
+
+      # `claims` by claim name ({ "<claim>" => <answer> }); `errors` by source, for KNOTs that could not
+      # be asked or whose answer did not verify. A claim missing from `claims` is unknown, never false.
+      Result = Struct.new(:claims, :errors) do
+        def self.empty = new({}, {})
+      end
+
+      module_function
+
+      def scope?(scope) = SCOPE_PATTERN.match?(scope.to_s)
+
+      # The active KNOT scopes, as vits.me describes them now (GET <issuer>/knot/scopes): each one's
+      # `scope`, `knot`, `claim`, `title`, `description` and `documentation_url`. For developers and their
+      # tools; signing in never depends on it. Raises Unavailable.
+      def scopes(environment: :production, issuer: nil)
+        response = HTTP.get("#{issuer || Vitsme.issuer(environment)}/knot/scopes", 'Accept' => 'application/json')
+        raise Unavailable, "vits.me: HTTP #{response.status}" unless response.ok?
+
+        response.json.fetch('knot_scopes')
+      rescue HTTP::Unavailable, JSON::ParserError, KeyError => e
+        raise Unavailable, e.message
+      end
+
+      # Fetches and verifies every KNOT source in a UserInfo (or POST /knot/introductions) response.
+      def resolve(response, client_id:)
+        names = response['_claim_names'] || {}
+        sources = response['_claim_sources'] || {}
+        txn = response['knot_txn']
+        sources.each_with_object(Result.empty) do |(source, spec), result|
+          answer = answer(spec, client_id: client_id, txn: txn)
+          names.each { |claim, from| result.claims[claim] = answer[claim] if from == source && answer.key?(claim) }
+        rescue JWS::Invalid, Keys::Unavailable, HTTP::Unavailable, Unavailable => e
+          result.errors[source] = e.message
+        end
+      end
+
+      # Fresh KNOT claims about someone, without them present, while they keep a standing consent with your
+      # site: vits.me introduces your site to each KNOT again. `uid` is the person's uid at your site.
+      # Raises ConsentRequired when nothing asked for is still agreed, InvalidClient for wrong credentials,
+      # and Unavailable when vits.me cannot be reached.
+      def fresh_claims(uid:, scopes:, client_id:, client_secret:, environment: :production, issuer: nil)
+        issuer ||= Vitsme.issuer(environment)
+        response = HTTP.post_form("#{issuer}/knot/introductions", { sub: uid, scope: Array(scopes).join(' ') },
+                                  basic: [client_id, client_secret], headers: { 'Accept' => 'application/json' })
+        case response.status
+        when 200 then resolve(response.json, client_id: client_id)
+        when 403 then raise ConsentRequired, 'the person does not let your site be told this'
+        when 401 then raise InvalidClient, 'vits.me did not accept the client credentials'
+        else raise Unavailable, "vits.me: HTTP #{response.status}"
+        end
+      rescue HTTP::Unavailable, JSON::ParserError => e
+        raise Unavailable, e.message
+      end
+
+      def answer(spec, client_id:, txn:)
+        response = HTTP.get(spec.fetch('endpoint'), 'Authorization' => "Bearer #{spec.fetch('access_token')}",
+                                                    'Accept' => 'application/jwt')
+        raise Unavailable, "HTTP #{response.status}" unless response.ok?
+
+        claims = JWS.verify!(response.body, jwks_uri: spec.fetch('jwks_uri'), iss: spec.fetch('iss'), aud: client_id)
+        raise JWS::Invalid, 'answer for another transaction' unless txn && claims['sub'] == txn
+
+        claims
+      rescue KeyError
+        raise Unavailable, 'incomplete source'
+      end
+    end
+  end
+end

data/lib/omniauth/vitsme/test.rb

@@ -13,6 +13,7 @@ module OmniAuth
     #   OmniAuth::Vitsme::Test.mock_auth(claims: { age__over_18: true })              # provider :vitsme
     #   OmniAuth::Vitsme::Test.mock_auth(:verify, uid: person.vitsme_uid, claims: { name: 'Jane D.' })
     #   OmniAuth::Vitsme::Test.mock_failure(:vitsme, :nationality_gate_refused)
+    #   OmniAuth::Vitsme::Test.mock_auth(knot_claims: { '<claim>' => <what the partner answers> })
     #
     # The auth hash is built by the same code as the real strategy's (AuthShape), so `info`, `extra`
     # and the typed claims look exactly as they will in production. Test mode skips the trip to vits.me
@@ -40,15 +41,17 @@ module OmniAuth
         info.merge(claims)
       end
 
-      def auth_hash(provider = :vitsme, identity: :solid, uid: nil, claims: {}, defunct_uids: [], fluid_uids: [])
+      def auth_hash(provider = :vitsme, identity: :solid, uid: nil, claims: {}, defunct_uids: [], fluid_uids: [],
+                    knot_claims: {}, knot_errors: {})
         uid ||= self.uid(identity)
         raw = raw_info(uid: uid, claims: claims, defunct_uids: defunct_uids, fluid_uids: fluid_uids)
+        knot = Knot::Result.new(knot_claims.transform_keys(&:to_s), knot_errors.transform_keys(&:to_s))
         OmniAuth::AuthHash.new(
           provider: provider.to_s,
           uid: uid,
           info: AuthShape.info(uid, raw),
           credentials: { id_token: 'test.id.token', scope: 'openid' },
-          extra: AuthShape.extra(uid, raw)
+          extra: AuthShape.extra(uid, raw, knot: knot)
         )
       end
 

data/lib/omniauth/vitsme/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAuth
   module Vitsme
-    VERSION = '0.3.0'
+    VERSION = '0.4.0'
   end
 end

data/lib/omniauth/vitsme.rb

@@ -4,4 +4,6 @@ require 'omniauth/vitsme/version'
 require 'omniauth/vitsme/issuers'
 require 'omniauth/vitsme/catalog'
 require 'omniauth/vitsme/auth_shape'
+require 'omniauth/vitsme/knot'
+require 'omniauth/vitsme/events'
 require 'omniauth/strategies/vitsme'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-vitsme
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yuval Tobias
@@ -49,7 +49,12 @@ files:
 - lib/omniauth/vitsme.rb
 - lib/omniauth/vitsme/auth_shape.rb
 - lib/omniauth/vitsme/catalog.rb
+- lib/omniauth/vitsme/events.rb
+- lib/omniauth/vitsme/http.rb
 - lib/omniauth/vitsme/issuers.rb
+- lib/omniauth/vitsme/jws.rb
+- lib/omniauth/vitsme/keys.rb
+- lib/omniauth/vitsme/knot.rb
 - lib/omniauth/vitsme/test.rb
 - lib/omniauth/vitsme/version.rb
 - llms.txt