omniauth-xivauth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: af91e773acc4e5e73805012b91c57b5a7b259057f5b0de951b8555fa99d84f14
+  data.tar.gz: 98272562e841dacd01947a0b2ac83b08ad9277ac2dbbaf0b406591a06af1a2e8
+SHA512:
+  metadata.gz: 717a1c7e81900360033c4f81cbe1b28a21b3a6ac03119e2c46a210fe2045e72dfe51666558c5c2035c95cea5606be141b983391b91ac21973aee9a994c1d39ae
+  data.tar.gz: 6b817bf5c26627cc3b4ca0a3e5db318f3bca6d40b464f405d88adb747631aee2519760979e14232485986ff82a4abbbb2b11f1c43882c0007b89832449497df6

data/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      ruby:
+        patterns:
+          - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      gha:
+        patterns:
+          - "*"

data/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  # smoke test: don't release a build that broke, somehow.
+  test:
+    permissions:
+      contents: read
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.3
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake
+
+  release:
+    needs: test
+    if: github.repository == 'xivauth/omniauth-xivauth'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    permissions:
+      contents: write
+      id-token: write
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: 3.3
+      - name: Release gem to RubyGems
+        uses: rubygems/release-gem@v1
+      - name: Push gem to GitHub Packages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p "$HOME/.gem"
+          printf -- '---\n:github: Bearer %s\n' "$GITHUB_TOKEN" > "$HOME/.gem/credentials"
+          chmod 0600 "$HOME/.gem/credentials"
+          gem push --key github \
+            --host "https://rubygems.pkg.github.com/${{ github.repository_owner }}" \
+            pkg/*.gem

data/.github/workflows/ruby.yml

@@ -0,0 +1,107 @@
+name: Ruby
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: "Canonical Test Suite"
+    permissions:
+      contents: read
+      checks: write
+      code-quality: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.3
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec --format progress --format RspecJunitFormatter --out tmp/testresults/rspec.xml
+        env:
+          REPORT_TEST_RESULTS: true
+          SOFT_FAIL_TESTS: true
+
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./tmp/testresults/rspec.xml
+          report_type: test_results
+
+      - name: Upload coverage to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./tmp/testresults/coverage/coverage.xml
+          report_type: coverage
+
+      - name: Upload coverage to GitHub
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/upload-code-coverage@v1
+        with:
+          file: ./tmp/testresults/coverage/coverage.xml
+          language: Ruby
+          label: canonical
+
+  compat_test:
+    name: "Compatibility test: ${{ matrix.ruby }} on ${{ matrix.os }}"
+    permissions:
+      contents: read
+      checks: write
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        ruby: [3.3, 3.4, 4.0]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Set JRUBY_OPTS environment variable
+        run: echo "JRUBY_OPTS=--debug" >> "$GITHUB_ENV"
+        if: ${{ startsWith(matrix.ruby, 'jruby') }}
+      - name: Run tests
+        run: bundle exec rake
+
+  lint:
+    permissions:
+      contents: read
+      pull-requests: write
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Install Ruby and gems
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+
+      - name: Generate binstubs
+        run: bundle binstubs rubocop
+
+      - name: Run rubocop with reviewdog
+        uses: reviewdog/action-rubocop@v2.22.0
+        with:
+          reporter: github-pr-review
+          only_changed: true
+          skip_install: true
+          use_bundler: true

data/.gitignore

@@ -0,0 +1,101 @@
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# Just all of IDEA
+.idea/
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### Ruby template
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+

data/.rubocop.yml

@@ -0,0 +1,20 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
+  SuggestExtensions: false
+  Exclude:
+    - 'coverage/**/*'
+    - 'vendor/**/*'
+
+Metrics:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never
+
+Naming/FileName:
+  Exclude:
+    - 'lib/omniauth-xivauth.rb'

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [v0.1.0](https://github.com/xivauth/xivauth-omniauth/releases/tag/v0.1.0) 
+
+- Initial gem release.

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.5'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.0'
+  gem 'simplecov'
+  gem 'simplecov-cobertura'
+  gem 'webmock'
+end

data/LICENSE.md

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2026, The XIVAuth Project
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,106 @@
+# XIVAuth OmniAuth Strategy
+
+Plug [XIVAuth](https://xivauth.net) into your Omniauth protected application
+simply and efficiently. This strategy supports both user-based and 
+character-based flows.
+
+Please be sure to refer to the [XIVAuth documentation](https://xivauth.net/developer/docs)
+for information on how it provides OAuth2 services and how to use scopes.
+
+## Installation
+
+Add the following line to your application's Gemfile:
+
+```ruby
+gem 'omniauth-xivauth'
+```
+
+## Usage
+
+This gem is standard for OmniAuth strategies. An example provider:
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :xivauth, ENV['XIVAUTH_CLIENT_ID'], ENV['XIVAUTH_CLIENT_SECRET'],
+           scope: 'user user:email character:all'
+end
+```
+
+By default, this strategy will request the `user` scope. Additional scopes may
+be requested through the `scope` option. Generally speaking, applications will
+likely want one of `character`, `user`, or `user character:all`.
+
+**Consumers must also take care to expect data in odd formats.** Users may 
+approve/reject certain scopes, or share many/one/no characters depending on 
+their preferences. Applications should be prepared to handle these cases 
+gracefully.
+
+### Auth Hash Information
+
+The format of the auth hash will differ based on the scope(s) requested, namely
+whether `user` or `character` is chosen. In nearly all cases, the following 
+structure will be returned. Note that user information will not be returned 
+unless the `user` scope is requested and granted.
+
+```ruby
+{
+  provider: "xivauth",
+  uid: "53f5faa3-3a9a-4d1e-91e5-80626b1a7da1",  # user id
+  info: {  # information about the user
+    name: "StandardUserTest",
+    email: "someuser@invalid.test",  # nil unless `user:email` was granted and the address is verified
+    image: "https://cdn.xivauth.test/dummydata/standard-user-avatar.png"
+  },
+  extra: {
+    raw_info: { 
+      # Alias of `extra.user` hash. 
+    },
+    user: {
+      # API response from XIVAuth's /api/v1/user endpoint. 
+    },
+    characters: nil # populated only if a character scope was granted
+  }
+}
+```
+
+However, if an application is using just the `character` scope, the auth hash will instead present the chosen
+character's identity as the authoritative object. This allows for applications that only care about character 
+information to treat inbound characters as their own first-class identities.
+
+```ruby
+{
+  provider: "xivauth",
+  uid: "7bBfWdAGQYQ3mtHzalpgQOyFdTk",  # character persistent key
+  info: {
+    name: "Mikoto Jinba",
+    image: "https://cdn.xivauth.test/dummydata/mikoto-portrait.png",
+    location: "Behemoth",  # Home world of the character
+    urls: {
+      lodestone: "https://na.finalfantasyxiv.com/lodestone/character/32080755/"
+    },
+    lodestone_id: "32080755"
+  },
+  extra: {
+    raw_info: { 
+      # Alias of `extra.characters` array's first (and only) element.
+    },
+    user: nil,  # will always be null; this is a character-only auth hash
+    characters: [
+      { "persistent_key" => "7bBfWdAGQYQ3mtHzalpgQOyFdTk", "name" => "Mikoto Jinba" }
+    ]
+  }
+}
+```
+
+## Contributing
+
+Contributions are welcome! Feel free to submit Issues and PRs to improve this gem if you spot something that can be made
+better. Note, however, that this gem is ultimately a transparent wrapper around the XIVAuth API. Upstream changes should
+likely be filed against that project instead.
+
+Please make sure tests pass (`bundle exec rspec`) and that Rubocop is happy (`bundle exec rubocop`) before submitting a
+PR.
+
+## License
+
+Licensed under the [MIT license](./LICENSE.md). 

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+desc 'Run specs'
+task default: :spec

data/lib/omniauth/strategies/xivauth.rb

@@ -0,0 +1,118 @@
+require 'omniauth-oauth2'
+
+module OmniAuth
+  module Strategies
+    class Xivauth < OmniAuth::Strategies::OAuth2
+      DEFAULT_SCOPE = 'user'.freeze
+      LODESTONE_CHARACTER_URL = 'https://na.finalfantasyxiv.com/lodestone/character/%s/'.freeze
+
+      option :name, 'xivauth'
+
+      option :client_options, {
+        site: 'https://xivauth.net/api/v1',
+        authorize_url: '/oauth/authorize',
+        token_url: '/oauth/token'
+      }
+
+      option :authorize_options, [ :scope ]
+
+      info do
+        if user_data
+          {
+            name: user_data['display_name'],
+            email: user_data['email_verified'] ? user_data['email'] : nil,
+            image: user_data['avatar_url']
+          }
+        elsif character_only_login? && primary_character
+          {
+            name: primary_character['name'],
+            image: primary_character['portrait_url'],
+            location: primary_character['home_world'],
+            urls: {
+              lodestone: format(LODESTONE_CHARACTER_URL, primary_character['lodestone_id'])
+            },
+
+            # Not officially part of OmniAuth spec, but important enough to justify its own field.
+            lodestone_id: primary_character['lodestone_id']
+          }
+        else
+          {}
+        end
+      end
+
+      uid do
+        if user_data
+          user_data['id']
+        elsif character_only_login? && primary_character
+          primary_character['persistent_key']
+        end
+      end
+
+      extra do
+        {
+          raw_info: user_data || primary_character,
+          user: user_data,
+          characters: character_data
+        }
+      end
+
+      # NOTE: assumes the token response echoes back the granted scope as a
+      # space-delimited `scope` param, readable via `access_token.params`.
+      def granted_scopes
+        return @granted_scopes if defined?(@granted_scopes)
+
+        scope = access_token.params && access_token.params['scope']
+        @granted_scopes = scope.to_s.split
+      end
+
+      def character_only_login?
+        # character and character:all are blocked by xivauth's server side, but we should still test for it.
+        granted_scopes.include?('character') && !user_scope_granted? &&
+          !(granted_scopes.include?('character:all') || granted_scopes.include?('character:manage'))
+      end
+
+      def user_scope_granted?
+        granted_scopes.include?('user') || granted_scopes.include?('user:manage')
+      end
+
+      def character_scope_granted?
+        granted_scopes.include?('character') || granted_scopes.include?('character:all') ||
+          granted_scopes.include?('character:manage')
+      end
+
+      # Only fetched when the `user` scope was granted. The `user:email`
+      # scope only adds fields to this same payload, it doesn't change
+      # whether the request is made.
+      def user_data
+        return @user_data if defined?(@user_data)
+
+        @user_data = user_scope_granted? ? access_token.get('user').parsed : nil
+      end
+
+      # Fetched whenever the `character` scope was granted.
+      def character_data
+        return @character_data if defined?(@character_data)
+
+        @character_data = access_token.get('characters').parsed if character_scope_granted?
+      end
+
+      # The single character returned when `character` scope is granted
+      # without `user` scope (the character-only sign-in flow).
+      def primary_character
+        return nil if user_scope_granted? || !character_scope_granted?
+
+        character_data&.first
+      end
+
+      def authorize_params
+        super.tap do |params|
+          options[:authorize_options].each do |option|
+            params[option] = request.params[option.to_s] if request.params[option.to_s]
+          end
+
+          params[:scope] ||= DEFAULT_SCOPE
+        end
+      end
+    end
+  end
+end

data/lib/omniauth/xivauth/version.rb

@@ -0,0 +1,5 @@
+module Omniauth
+  module Xivauth
+    VERSION = '0.1.0'.freeze
+  end
+end

data/lib/omniauth/xivauth.rb

@@ -0,0 +1,2 @@
+require 'omniauth/xivauth/version'
+require 'omniauth/strategies/xivauth'

data/lib/omniauth-xivauth.rb

@@ -0,0 +1 @@
+require 'omniauth/xivauth'

data/omniauth-xivauth.gemspec

@@ -0,0 +1,29 @@
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'omniauth/xivauth/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'omniauth-xivauth'
+  spec.version       = Omniauth::Xivauth::VERSION
+  spec.authors       = ['Kaz Wolfe', 'XIVAuth Development Team']
+  spec.email         = %w[hi@wolf.dev support@xivauth.net]
+
+  spec.summary       = 'XIVAuth strategy for OmniAuth'
+  spec.description   = 'An OmniAuth strategy to authenticate users against XIVAuth, a third-party authentication ' \
+                       'service for Final Fantasy XIV.'
+  spec.homepage      = 'https://github.com/xivauth/omniauth-xivauth'
+  spec.license       = 'MIT'
+  spec.metadata      = {
+    'source_code_uri' => 'https://github.com/xivauth/omniauth-xivauth.git',
+    'changelog_uri' => 'https://github.com/xivauth/omniauth-xivauth/blob/main/CHANGELOG.md',
+    'github_repo' => 'ssh://github.com/xivauth/omniauth-xivauth',
+    'rubygems_mfa_required' => 'true',
+  }
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec)/}) }
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'omniauth', '~> 2.0'
+  spec.add_dependency 'omniauth-oauth2', '~> 1.8'
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-xivauth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaz Wolfe
+- XIVAuth Development Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: An OmniAuth strategy to authenticate users against XIVAuth, a third-party
+  authentication service for Final Fantasy XIV.
+email:
+- hi@wolf.dev
+- support@xivauth.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/dependabot.yml"
+- ".github/workflows/release.yml"
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/omniauth-xivauth.rb
+- lib/omniauth/strategies/xivauth.rb
+- lib/omniauth/xivauth.rb
+- lib/omniauth/xivauth/version.rb
+- omniauth-xivauth.gemspec
+homepage: https://github.com/xivauth/omniauth-xivauth
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/xivauth/omniauth-xivauth.git
+  changelog_uri: https://github.com/xivauth/omniauth-xivauth/blob/main/CHANGELOG.md
+  github_repo: ssh://github.com/xivauth/omniauth-xivauth
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: XIVAuth strategy for OmniAuth
+test_files: []