omniauth-vitsme 0.1.0 → 0.2.1

data/lib/omniauth/vitsme/auth_shape.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OmniAuth
+  module Vitsme
+    # Turns a vits.me UserInfo response into the `info` and `extra` of the auth hash. One builder for
+    # the strategy and for OmniAuth::Vitsme::Test, so a mocked sign-in has exactly the real shape.
+    module AuthShape
+      SOLID_PREFIX = 'solid_'
+      FLUID_PREFIX = 'fluid_'
+
+      module_function
+
+      # :solid for a verified person, :fluid for a pending signup (only with the `fluid` scope).
+      def identity_kind(uid)
+        uid.to_s.start_with?(FLUID_PREFIX) ? :fluid : :solid
+      end
+
+      def info(uid, raw_info)
+        claims = claims(raw_info)
+        {
+          name: claims['name'] || claims['name__full'],
+          nationality: claims['nationality'],
+          verified: identity_kind(uid) == :solid
+        }.compact
+      end
+
+      def extra(uid, raw_info)
+        {
+          identity: identity_kind(uid),
+          # Look a returning person up by every one of these, current first: a record keyed by a defunct
+          # SOLID belongs to this person and should move to `uid`.
+          lookup_uids: [uid.to_s, *Array(raw_info['defunct_solids'])].uniq,
+          # 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
+        }
+      end
+
+      # The disclosure claims vits.me returned, typed by the catalog. Identity claims (sub, solid,
+      # defunct_solids, fluid) are in `uid`, `lookup_uids` and `fluid_uids` instead; anything the
+      # catalog does not know stays in raw_info only.
+      def claims(raw_info)
+        Catalog.claims.each_with_object({}) do |(name, spec), out|
+          next if Catalog::DATA['identity_scopes'].key?(spec['scope'])
+
+          value = Catalog.coerce(name, raw_info[name])
+          out[name] = value unless value.nil?
+        end
+      end
+    end
+  end
+end

data/lib/omniauth/vitsme/catalog.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module OmniAuth
+  module Vitsme
+    # The scopes, claims, gates and refusal reasons vits.me offers, read from data/claims.json — the
+    # same file agents and developers read to choose scopes. The strategy validates `scope:` against it
+    # at boot and types every claim value by it.
+    module Catalog
+      PATH = File.expand_path('../../../data/claims.json', __dir__)
+      DATA = JSON.parse(File.read(PATH)).freeze
+      GATE_PATTERN = Regexp.new(DATA.dig('gates', 'openid_nationality', 'scope_pattern'))
+
+      module_function
+
+      def claims
+        DATA['claims']
+      end
+
+      def claim(name)
+        claims[name.to_s]
+      end
+
+      # Every requestable scope that is not a gate.
+      def scopes
+        @scopes ||= (DATA['identity_scopes'].keys + claims.values.map { |c| c['scope'] }).uniq.freeze
+      end
+
+      def gate_scope?(scope)
+        GATE_PATTERN.match?(scope.to_s)
+      end
+
+      def known_scope?(scope)
+        scopes.include?(scope.to_s) || gate_scope?(scope)
+      end
+
+      # The OmniAuth failure type for a `vitsme_error` refusal reason, or nil for an unknown one.
+      def failure_for(reason)
+        DATA.dig('refusals', reason.to_s, 'omniauth_failure')&.to_sym
+      end
+
+      # A claim value as the catalog types it. Tolerates the string forms older vits.me servers sent
+      # ("true", "37"); anything it cannot read as its type is dropped (nil), never guessed.
+      def coerce(name, value)
+        return nil if value.nil? || value == ''
+
+        case claim(name)&.fetch('type')
+        when 'boolean' then boolean(value)
+        when 'integer' then integer(value)
+        when 'string_array' then Array(value).map(&:to_s)
+        else value.to_s
+        end
+      end
+
+      def boolean(value)
+        case value
+        when true, 'true' then true
+        when false, 'false' then false
+        end
+      end
+
+      def integer(value)
+        return value if value.is_a?(Integer)
+
+        Integer(value.to_s, 10, exception: false)
+      end
+    end
+  end
+end

data/lib/omniauth/vitsme/issuers.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OmniAuth
+  module Vitsme
+    ISSUERS = {
+      production: 'https://vits.me',
+      staging: 'https://staging.vits.me',
+      development: 'https://vitsme.localhost'
+    }.freeze
+
+    # The vits.me issuer for an environment: :production, :staging or :development (a Rails.env works
+    # too — "test" maps to development).
+    def self.issuer(environment = :production)
+      key = environment.to_s == 'test' ? :development : environment.to_s.to_sym
+      ISSUERS.fetch(key) { raise ArgumentError, "omniauth-vitsme: unknown environment #{environment.inspect}" }
+    end
+  end
+end

data/lib/omniauth/vitsme/test.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'omniauth'
+require 'omniauth/vitsme'
+
+module OmniAuth
+  module Vitsme
+    # Test helpers for apps that sign people in with vits.me. Not loaded by default:
+    #
+    #   require 'omniauth/vitsme/test'
+    #   OmniAuth.config.test_mode = true
+    #   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)
+    #
+    # 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
+    # but still runs the strategy's identity checks (expected_uid, require_verified) on the mock: mock
+    # someone other than the signed-in person to see :identity_mismatch. mock_failure is for refusals
+    # only vits.me makes (:nationality_gate_refused, :access_denied).
+    module Test
+      module_function
+
+      # A plausible private uid. Real ones are opaque; never derive anything from them.
+      def uid(identity = :solid)
+        "#{identity == :fluid ? AuthShape::FLUID_PREFIX : AuthShape::SOLID_PREFIX}#{SecureRandom.alphanumeric(52).downcase}"
+      end
+
+      # The UserInfo response vits.me would send: identity claims plus the disclosure claims given.
+      def raw_info(uid:, claims: {}, defunct_uids: [], fluid_uids: [])
+        claims = claims.transform_keys(&:to_s)
+        unknown = claims.keys.reject { |name| Catalog.claim(name) }
+        raise ArgumentError, "omniauth-vitsme: unknown claim(s) #{unknown.join(', ')}" unless unknown.empty?
+
+        info = { 'sub' => uid }
+        info['solid'] = uid if AuthShape.identity_kind(uid) == :solid
+        info['defunct_solids'] = defunct_uids unless defunct_uids.empty?
+        info['fluid'] = fluid_uids unless fluid_uids.empty?
+        info.merge(claims)
+      end
+
+      def auth_hash(provider = :vitsme, identity: :solid, uid: nil, claims: {}, defunct_uids: [], fluid_uids: [])
+        uid ||= self.uid(identity)
+        raw = raw_info(uid: uid, claims: claims, defunct_uids: defunct_uids, fluid_uids: fluid_uids)
+        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)
+        )
+      end
+
+      # Makes the next callback for `provider` succeed with this person.
+      def mock_auth(provider = :vitsme, **)
+        OmniAuth.config.mock_auth[provider.to_sym] = auth_hash(provider, **)
+      end
+
+      # Makes the next callback for `provider` fail with `type` (e.g. :identity_mismatch, :not_signed_in,
+      # :unverified_identity, :nationality_gate_refused, :access_denied).
+      def mock_failure(provider = :vitsme, type = :access_denied)
+        OmniAuth.config.mock_auth[provider.to_sym] = type.to_sym
+      end
+    end
+  end
+end

data/lib/omniauth/vitsme/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAuth
   module Vitsme
-    VERSION = '0.1.0'
+    VERSION = '0.2.1'
   end
 end

data/lib/omniauth/vitsme.rb

@@ -1,4 +1,7 @@
 # frozen_string_literal: true
 
 require 'omniauth/vitsme/version'
+require 'omniauth/vitsme/issuers'
+require 'omniauth/vitsme/catalog'
+require 'omniauth/vitsme/auth_shape'
 require 'omniauth/strategies/vitsme'

data/llms.txt

@@ -0,0 +1,9 @@
+# omniauth-vitsme
+
+> OmniAuth strategy (Ruby/Rails) for vits.me: sign people in, ask about details they verified (name, age, nationality), and admit only verified nationals of chosen countries. The uid is a private per-site identifier; claims may be absent; follow-up questions about a signed-in person need `expected_uid`.
+
+- [AGENTS.md](https://github.com/yuvaltobias/omniauth-vitsme/blob/main/AGENTS.md): rules for agents, read first
+- [data/claims.json](https://github.com/yuvaltobias/omniauth-vitsme/blob/main/data/claims.json): every scope, claim, type, gate and refusal, machine-readable
+- [README.md](https://github.com/yuvaltobias/omniauth-vitsme/blob/main/README.md): quick start, claims, verifying a signed-in person, gates, FLUID, failure types, auth hash, privacy rules, testing
+- [examples/rails/app.rb](https://github.com/yuvaltobias/omniauth-vitsme/blob/main/examples/rails/app.rb): a one-file Rails app using sign-in, a gate and verification
+- [Skill: vitsme-integrate](https://github.com/yuvaltobias/omniauth-vitsme/blob/main/.claude/skills/vitsme-integrate/SKILL.md): add vits.me to a Rails app end to end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-vitsme
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Yuval Tobias
@@ -23,26 +23,36 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
-description: OmniAuth OpenID Connect strategy for vits.me, digital identity platform.
+description: Sign people in with vits.me, verify details about them, and gate sign-up
+  by nationality — an OpenID Connect strategy with identity matching, typed claims
+  and a machine-readable claim catalog.
 email:
 - yuval@mattyr.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/settings.local.json"
-- ".rspec"
-- ".rspec_status"
-- ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
+- data/claims.json
+- lib/generators/omniauth_vitsme/install/install_generator.rb
+- lib/generators/omniauth_vitsme/install/templates/_sign_in.html.erb.tt
+- lib/generators/omniauth_vitsme/install/templates/add_vitsme_uid.rb.tt
+- lib/generators/omniauth_vitsme/install/templates/omniauth_vitsme.rb.tt
+- lib/generators/omniauth_vitsme/install/templates/vitsme.en.yml
+- lib/generators/omniauth_vitsme/install/templates/vitsme.he.yml
+- lib/generators/omniauth_vitsme/install/templates/vitsme_callbacks_controller.rb.tt
 - lib/omniauth-vitsme.rb
 - lib/omniauth/strategies/vitsme.rb
 - lib/omniauth/vitsme.rb
+- lib/omniauth/vitsme/auth_shape.rb
+- lib/omniauth/vitsme/catalog.rb
+- lib/omniauth/vitsme/issuers.rb
+- lib/omniauth/vitsme/test.rb
 - lib/omniauth/vitsme/version.rb
-- omniauth-vitsme.gemspec
+- llms.txt
 homepage: https://github.com/yuvaltobias/omniauth-vitsme
 licenses:
 - MIT
@@ -50,6 +60,7 @@ metadata:
   homepage_uri: https://github.com/yuvaltobias/omniauth-vitsme
   source_code_uri: https://github.com/yuvaltobias/omniauth-vitsme
   changelog_uri: https://github.com/yuvaltobias/omniauth-vitsme/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/yuvaltobias/omniauth-vitsme#readme
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -58,14 +69,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.0
+rubygems_version: 4.0.20
 specification_version: 4
 summary: OmniAuth strategy for vits.me identity verification
 test_files: []

data/.claude/settings.local.json

@@ -1,27 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebSearch",
-      "WebFetch(domain:vits.me)",
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:rubygems.org)",
-      "WebFetch(domain:msuliq.medium.com)",
-      "Bash(gem contents:*)",
-      "Bash(gem list:*)",
-      "WebFetch(domain:raw.githubusercontent.com)",
-      "Bash(curl:*)",
-      "Bash(python3:*)",
-      "Bash(ruby --version:*)",
-      "Bash(git init:*)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(bundle install:*)",
-      "Bash(bundle exec rspec:*)",
-      "Bash(bundle show:*)",
-      "Bash(bundle exec rubocop:*)",
-      "Bash(bundle update:*)",
-      "Bash(gem build:*)",
-      "Bash(bundle exec rake:*)"
-    ]
-  }
-}

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rspec_status

@@ -1,29 +0,0 @@
-example_id                                        | status | run_time        |
-------------------------------------------------- | ------ | --------------- |
-./spec/omniauth/strategies/vitsme_spec.rb[1:1:1]  | passed | 0.00013 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:1:2]  | passed | 0.00034 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:1:3]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:1:4]  | passed | 0.00013 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:1:5]  | passed | 0.00026 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:1:6]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:1:7]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:2:1]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:2:2]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:2:3]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:2:4]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:2:5]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:2:6]  | passed | 0.00013 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:2:7]  | passed | 0.00014 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:3:1]  | passed | 0.00015 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:3:2]  | passed | 0.00056 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:1]  | passed | 0.00024 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:2]  | passed | 0.00031 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:3]  | passed | 0.0003 seconds  |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:4]  | passed | 0.00031 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:5]  | passed | 0.00033 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:6]  | passed | 0.00031 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:7]  | passed | 0.00033 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:8]  | passed | 0.00042 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:9]  | passed | 0.00098 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:4:10] | passed | 0.00022 seconds |
-./spec/omniauth/strategies/vitsme_spec.rb[1:5:1]  | passed | 0.00266 seconds |

data/.rubocop.yml

@@ -1,39 +0,0 @@
-plugins:
-  - rubocop-rspec
-
-AllCops:
-  TargetRubyVersion: 3.0
-  NewCops: enable
-  SuggestExtensions: false
-
-Style/Documentation:
-  Enabled: false
-
-Style/OpenStructUse:
-  Exclude:
-    - "spec/**/*"
-
-Naming/FileName:
-  Exclude:
-    - "lib/omniauth-vitsme.rb"
-
-Naming/VariableNumber:
-  Enabled: false
-
-Metrics/BlockLength:
-  Exclude:
-    - "spec/**/*"
-    - "*.gemspec"
-
-Metrics/ModuleLength:
-  Exclude:
-    - "spec/**/*"
-
-RSpec/ExampleLength:
-  Max: 10
-
-RSpec/MultipleExpectations:
-  Max: 5
-
-RSpec/NestedGroups:
-  Max: 4

data/Rakefile

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-require 'rspec/core/rake_task'
-require 'rubocop/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-RuboCop::RakeTask.new(:rubocop)
-
-task default: %i[spec rubocop]

data/omniauth-vitsme.gemspec

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'lib/omniauth/vitsme/version'
-
-Gem::Specification.new do |spec|
-  spec.name = 'omniauth-vitsme'
-  spec.version = OmniAuth::Vitsme::VERSION
-  spec.authors = ['Yuval Tobias']
-  spec.email = ['yuval@mattyr.com']
-
-  spec.summary = 'OmniAuth strategy for vits.me identity verification'
-  spec.description = 'OmniAuth OpenID Connect strategy for vits.me, ' \
-                     'digital identity platform.'
-  spec.homepage = 'https://github.com/yuvaltobias/omniauth-vitsme'
-  spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.0.0'
-
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = spec.homepage
-  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
-  spec.metadata['rubygems_mfa_required'] = 'true'
-
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?('spec/', 'test/', '.git', '.github', 'Gemfile')
-    end
-  end
-  spec.require_paths = ['lib']
-
-  spec.add_dependency 'omniauth_openid_connect', '~> 0.8'
-end