omniauth_syncer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6a819b9cbe1e4eac56eeb9504aaa0b61efd924995f9a98036a346de8a4032fe7
+  data.tar.gz: df5d6f52e868a53c096de1f0dae3e57f777b41ccf6fdd25a7e9967802feccafa
+SHA512:
+  metadata.gz: 885231fb38457b3b9284f80081c60b87ccfb9a1672164df8e5efd657a7165087b4bfef266efdf4a1206fa9ed83e0406a5cc2d1099e0a952588eddc85e01333f2
+  data.tar.gz: f7aecc03a67a0f66aa77d854708e57a34955feabc32f7225dfe8496c046c31e67e13b9ff36bcc806d4453a04ec5adab2d66add266403325cf9464df725825d03

data/.rspec_status

@@ -0,0 +1,8 @@
+example_id                                           | status | run_time        |
+---------------------------------------------------- | ------ | --------------- |
+./spec/omniauth_syncer/sync_service_spec.rb[1:1:1:1] | passed | 0.00427 seconds |
+./spec/omniauth_syncer/sync_service_spec.rb[1:1:2:1] | passed | 0.00022 seconds |
+./spec/omniauth_syncer/sync_service_spec.rb[1:1:3:1] | passed | 0.00079 seconds |
+./spec/omniauth_syncer/sync_service_spec.rb[1:1:3:2] | passed | 0.00019 seconds |
+./spec/omniauth_syncer/sync_service_spec.rb[1:1:4:1] | passed | 0.00072 seconds |
+./spec/omniauth_syncer/sync_service_spec.rb[1:1:5:1] | passed | 0.00029 seconds |

data/.rubocop.yml

@@ -0,0 +1,48 @@
+require:
+  - rubocop-performance
+  - rubocop-rails # Even if this is a non-Rails gem, many conventions apply
+
+AllCops:
+  # Exclude common files that aren't source code
+  Exclude:
+    - 'bin/*'
+    - 'vendor/**/*'
+    - 'spec/fixtures/**/*'
+    - 'Gemfile'
+    - 'Rakefile'
+    - '**/*.gemspec'
+  # Target the Ruby version you are developing against (e.g., 3.2 is modern)
+  TargetRubyVersion: 3.2
+  NewCops: enable
+
+# === Layout Cops (Formatting) ===
+Layout/LineLength:
+  # Relax line length for documentation/complex setup in specs
+  Max: 120
+  IgnoredPatterns: ['\.gemspec']
+
+# === Style Cops (Idiomatic Ruby) ===
+Style/Documentation:
+  # Gems often skip documenting simple classes/modules
+  Enabled: false
+Style/ClassAndModuleChildren:
+  # Use the standard, compact (nested) style: 
+  # e.g., 'module A; class B; end; end' instead of 'class A::B'
+  EnforcedStyle: nested
+Style/FrozenStringLiteralComment:
+  # Enable the magic comment for performance in modern Ruby
+  Enabled: true
+Style/ClassMethods:
+  # Use self.method_name for class methods
+  EnforcedStyle: self_name
+
+# === Performance Cops ===
+# Performance cops are helpful for writing efficient code
+Performance/FlatMap:
+  Enabled: true
+
+# === Naming Cops ===
+Naming/FileName:
+  # Allow the standard gem entry point file to have a hyphen
+  Exclude:
+    - 'exe/omniauth-syncer'

data/Gemfile

@@ -0,0 +1,13 @@
+source "https://rubygems.org"
+gemspec
+# Add development and testing tools
+group :development, :test do
+  # ... (other tools like rspec, pry)
+  
+  # Core RuboCop gem
+  gem 'rubocop', '~> 1.0' 
+  
+  # Extensions for common Ruby idioms and performance checks
+  gem 'rubocop-performance'
+  gem 'rubocop-rails' # Good to include even for a general gem
+end

data/Gemfile.lock

@@ -0,0 +1,100 @@
+PATH
+  remote: .
+  specs:
+    omniauth_syncer (0.1.0)
+      activesupport (>= 6.0)
+      omniauth (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.1.7.10)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.3.5)
+    diff-lcs (1.6.2)
+    hashie (5.0.0)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    json (2.7.6)
+    logger (1.7.0)
+    method_source (1.1.0)
+    minitest (5.25.4)
+    omniauth (2.1.4)
+      hashie (>= 3.4.6)
+      logger
+      rack (>= 2.2.3)
+      rack-protection
+    parallel (1.24.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.8.1)
+    rack (3.2.3)
+    rack-protection (3.0.6)
+      rack
+    rainbow (3.1.1)
+    rake (13.3.0)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.50.2)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    rubocop-performance (1.17.1)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rails (2.19.1)
+      activesupport (>= 4.2.0)
+      rack (>= 1.1)
+      rubocop (>= 1.33.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.6.0)
+    zeitwerk (2.6.18)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  omniauth_syncer!
+  pry
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.0)
+  rubocop-performance
+  rubocop-rails
+
+BUNDLED WITH
+   2.4.22

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Daniele Frisanco
+
+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,127 @@
+omniauth\_syncer 🚀
+===================
+
+A plug-and-play Ruby gem designed for applications using **OmniAuth** (often with SSO providers) to reliably and safely synchronize user profile data into a local $\\text{ActiveRecord}$ model.
+
+This gem prevents data drift by ensuring the local user record is always up-to-date with the latest information fetched from the SSO provider during a successful login.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+Ruby
+
+```ruby
+gem 'omniauth_syncer'
+```
+
+Then execute:
+
+Bash
+
+```bash
+bundle install   
+```
+
+Configuration
+-------------
+
+The gem requires a basic setup to know which local model to use and how to map fields from the OmniAuth hash.
+
+Create an initializer file at config/initializers/omniauth\_syncer.rb:
+
+Ruby
+
+```ruby
+# config/initializers/omniauth_syncer.rb
+OmniauthSyncer.configure do |config|
+  # 1. Local User Model
+  # The name of the local ActiveRecord class to sync data to (e.g., 'User')
+  config.user_model = 'User'
+  # 2. Unique Identifier Field
+  # The column in your local User model used for lookup (must be unique).
+  config.uid_field = :sso_uid
+  # 3. Path to UID in Auth Hash
+  # The string path in the OmniAuth Auth Hash that holds the unique identifier.
+  # Example: 'uid' is used for the top-level hash['uid'].
+  config.uid_field_in_auth = 'uid'
+  # 4. Attribute Mappings
+  # Map local attributes (keys) to the path in the OmniAuth Auth Hash (values).
+  # Use dot notation for nested fields (e.g., 'info.email').
+  config.mappings = {
+    email: 'info.email',
+    full_name: 'info.name',
+    # Example for nested data like roles provided by the SSO server:
+    roles: 'extra.raw_info.roles'
+  }
+end   
+```
+
+Usage
+-----
+
+The gem provides the core synchronization logic via a helper module, which should be included in your application's **OmniAuth Callback Controller**.
+
+### Step 1: Include the Helper
+
+In your OmniAuth Callback Controller (e.g., app/controllers/users/omniauth\_callbacks\_controller.rb):
+
+Ruby
+
+```ruby
+class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  # Include the helper module
+  include OmniauthSyncer::ControllerHelpers
+  # ...
+end   
+```
+
+### Step 2: Sync the User
+
+Call the **sync\_sso\_user** method inside your provider action (e.g., sso\_provider). This method will handle the following automatically:
+
+1.  Retrieving the current $\\text{OmniAuth Auth Hash}$.
+    
+2.  Calling the $\\text{SyncService}$ to $\\text{find or create}$ the local user record based on the configured $\\text{uid}$.
+    
+3.  Updating all configured attributes.
+    
+4.  Safely **preserving** existing local data if a field is missing or nil in the incoming SSO data.
+    
+
+Ruby
+
+```ruby
+# app/controllers/users/omniauth_callbacks_controller.rb
+class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  include OmniauthSyncer::ControllerHelpers
+  def sso_provider
+    begin
+      # 1. Sync the user and get the local user object
+      @user = sync_sso_user
+      # 2. Sign in the user (e.g., using Devise or a custom method)
+      if @user.persisted?
+        sign_in_and_redirect @user, event: :authentication
+      else
+        # This occurs if the user record fails local validations (e.g., missing mandatory field)
+        redirect_to root_path, alert: "Could not sync user profile due to data issues."
+      end
+    rescue => e
+      # Log any synchronization or validation errors
+      logger.error "SSO Sync Failure: #{e.message}"
+      redirect_to root_path, alert: "Authentication failed due to internal error."
+    end
+  end
+end   
+```
+
+Contributing
+------------
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/danielefrisanco/omniauth_syncer.
+
+License
+-------
+
+The gem is available as open source under the terms of the **MIT License**.

data/app/controllers/users/omniauth_callbacks_controller.rb

@@ -0,0 +1,13 @@
+# The final controller setup in the user's application
+class Users::OmniauthCallbacksController < ApplicationController
+  include OmniauthSyncer::ControllerHelpers # Includes the sync_sso_user method
+
+  def sso_provider
+    # Use the helper to sync the user and retrieve the record
+    @user = sync_sso_user
+
+    sign_in_and_redirect @user, event: :authentication
+  rescue StandardError
+    redirect_to root_path, alert: 'Authentication failed.'
+  end
+end

data/config/initializers/omniauth_syncer.rb

@@ -0,0 +1,16 @@
+OmniauthSyncer.configure do |config|
+  # The ActiveRecord model class name
+  config.user_model = 'User'
+
+  # The column used for the unique identifier
+  config.uid_field = :sso_id
+
+  # Mapping: local_attribute => path_in_auth_hash
+  # 'info.email' looks into auth_hash.info['email']
+  config.mappings = {
+    email: 'info.email',
+    full_name: 'info.name',
+    # Example for nested/extra data: auth_hash.extra['raw_info']['roles']
+    roles: 'extra.raw_info.roles'
+  }
+end

data/lib/omniauth_syncer/configuration.rb

@@ -0,0 +1,23 @@
+module OmniauthSyncer
+  class Configuration
+    # Define settings with default values or required accessors
+    attr_accessor :user_model, :uid_field, :uid_field_in_auth, :mappings
+
+    def initialize
+      # Sensible defaults
+      @user_model = 'User'
+      @uid_field = :uid
+      @uid_field_in_auth = 'uid' # Default path in AuthHash
+      @mappings = {}
+    end
+  end
+
+  # Class method to expose the configuration object and the configuration block
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/omniauth_syncer/controller_helpers.rb

@@ -0,0 +1,17 @@
+module OmniauthSyncer
+  module ControllerHelpers
+    # Call this method inside the OmniAuth callback action
+    def sync_sso_user
+      # Retrieve the auth hash from the Rack environment
+      auth_hash = request.env['omniauth.auth']
+
+      # Execute the core sync logic
+      OmniauthSyncer::SyncService.call(auth_hash)
+    rescue ActiveRecord::RecordInvalid => e
+      # Provide a clear, common way to handle sync validation errors
+      logger.error "OmniauthSyncer Validation Error: #{e.message}"
+      # Optionally, you might raise a custom error here
+      raise e
+    end
+  end
+end

data/lib/omniauth_syncer/engine.rb

@@ -0,0 +1,25 @@
+require 'rails/engine'
+
+module OmniauthSyncer
+  class Engine < ::Rails::Engine
+    # Allows the host application to use OmniauthSyncer configurations
+    isolate_namespace OmniauthSyncer
+
+    # This initializer runs before all other application initializers.
+    # It ensures that our configuration block is loaded early.
+    initializer 'omniauth_syncer.configure_defaults' do
+      # Load your configuration settings here if needed,
+      # but typically, we rely on the host app's initializer.
+    end
+
+    # Optionally, you can include logic to automatically integrate
+    # the SyncService into the host app's controller.
+    initializer 'omniauth_syncer.controller_mixin' do
+      ActiveSupport.on_load(:action_controller_base) do
+        # This is where you would define a helper method
+        # that the user can call in their OmniAuth controller:
+        # include OmniauthSyncer::ControllerHelpers
+      end
+    end
+  end
+end

data/lib/omniauth_syncer/sync_service.rb

@@ -0,0 +1,57 @@
+module OmniauthSyncer
+  class SyncService
+    # Use the .call convention for single-purpose service objects
+    def self.call(auth_hash)
+      new(auth_hash).sync_user
+    end
+
+    def sync_user
+      # Step 1: Find or Create the User
+      user = find_or_initialize_user
+
+      # Step 2: Update Mapped Attributes
+      @config.mappings.each do |local_attr, auth_path|
+        # Use a helper to safely retrieve nested data (e.g., 'info.email')
+        auth_value = get_auth_value(auth_path)
+
+        # Only set if the value is present and the local attribute is writable
+        user.send("#{local_attr}=", auth_value) if auth_value.present?
+      end
+
+      # Step 3: Save and Return
+      user.save! # Use save! to ensure we raise an error on validation failure
+      user
+    end
+
+    private
+
+    def initialize(auth_hash)
+      @auth_hash = auth_hash
+      @config = OmniauthSyncer.configuration
+      # Dynamically get the User model class
+      @user_class = @config.user_model.constantize
+    end
+
+    def find_or_initialize_user
+      # Get the unique identifier value from the auth hash (e.g., the UID)
+      uid_value = get_auth_value(@config.uid_field_in_auth) # Assume config holds the path to UID
+
+      # Use the configured uid_field for the database lookup
+      @user_class.find_or_initialize_by(@config.uid_field => uid_value)
+    end
+
+    # Helper method to safely traverse the nested AuthHash
+    # (Simplified for demonstration; a real implementation would be more robust)
+    def get_auth_value(path)
+      parts = path.to_s.split('.')
+      current = @auth_hash.dup
+
+      parts.each do |part|
+        # Use dig for safety, converting to symbol or string keys
+        current = current.respond_to?(:dig) ? current.dig(part.to_sym) || current.dig(part.to_s) : current[part]
+        return nil unless current
+      end
+      current
+    end
+  end
+end

data/lib/omniauth_syncer/version.rb

@@ -0,0 +1,3 @@
+module OmniauthSyncer
+  VERSION = '0.1.0'
+end

data/lib/omniauth_syncer.rb

@@ -0,0 +1,9 @@
+require 'active_support/core_ext/string/inflections' # For constantize
+require 'omniauth_syncer/version'
+require 'omniauth_syncer/configuration'
+require 'omniauth_syncer/sync_service'
+
+module OmniauthSyncer
+  # No code here, just module definition.
+  # All logic is in SyncService and Configuration.
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: omniauth_syncer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniele Frisanco
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-10-23 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: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ensures local user records are created or updated with the latest data
+  from the SSO provider after a successful OmniAuth login.
+email:
+- daniele.frisanco@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec_status"
+- ".rubocop.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- app/controllers/users/omniauth_callbacks_controller.rb
+- config/initializers/omniauth_syncer.rb
+- lib/omniauth_syncer.rb
+- lib/omniauth_syncer/configuration.rb
+- lib/omniauth_syncer/controller_helpers.rb
+- lib/omniauth_syncer/engine.rb
+- lib/omniauth_syncer/sync_service.rb
+- lib/omniauth_syncer/version.rb
+homepage: https://github.com/danielefrisanco/omniauth_syncer
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key: 
+specification_version: 4
+summary: A Ruby gem for synchronizing user profile data from OmniAuth to local ActiveRecord
+  models.
+test_files: []