glogin 0.16.5 → 0.17.0

data/README.md

@@ -1,14 +1,14 @@
 # OAuth Login via GitHub Made Simple
 
-[![DevOps By Rultor.com](http://www.rultor.com/b/yegor256/glogin)](http://www.rultor.com/p/yegor256/glogin)
+[![DevOps By Rultor.com](https://www.rultor.com/b/yegor256/glogin)](https://www.rultor.com/p/yegor256/glogin)
 [![We recommend RubyMine](https://www.elegantobjects.org/rubymine.svg)](https://www.jetbrains.com/ruby/)
 
 [![rake](https://github.com/yegor256/glogin/actions/workflows/rake.yml/badge.svg)](https://github.com/yegor256/glogin/actions/workflows/rake.yml)
-[![PDD status](http://www.0pdd.com/svg?name=yegor256/glogin)](http://www.0pdd.com/p?name=yegor256/glogin)
-[![Gem Version](https://badge.fury.io/rb/glogin.svg)](http://badge.fury.io/rb/glogin)
+[![PDD status](https://www.0pdd.com/svg?name=yegor256/glogin)](https://www.0pdd.com/p?name=yegor256/glogin)
+[![Gem Version](https://badge.fury.io/rb/glogin.svg)](https://badge.fury.io/rb/glogin)
 [![Maintainability](https://api.codeclimate.com/v1/badges/155f86b639d155259219/maintainability)](https://codeclimate.com/github/yegor256/glogin/maintainability)
 [![Test Coverage](https://img.shields.io/codecov/c/github/yegor256/glogin.svg)](https://codecov.io/github/yegor256/glogin?branch=master)
-[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/yegor256/glogin/master/frames)
+[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/yegor256/glogin/master/frames)
 [![Hits-of-Code](https://hitsofcode.com/github/yegor256/glogin)](https://hitsofcode.com/view/github/yegor256/glogin)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/glogin/blob/master/LICENSE.txt)
 
@@ -27,7 +27,7 @@ First, somewhere in the global space, before the app starts:
 require 'glogin'
 configure do
   set :glogin, GLogin::Auth.new(
-    # Make sure their values are coming from a secure
+    # Make sure these values are coming from a secure
     # place and are not visible in the source code:
     client_id, client_secret,
     # This is what you will register in GitHub as an
@@ -59,11 +59,11 @@ before '/*' do
 end
 ```
 
-If the `glogin` cookie is coming in and contains a valid data,
+If the `glogin` cookie is coming in and contains valid data,
 a local variable `@user` will be set to something like this:
 
 ```ruby
-{ login: 'yegor256', avatar: 'http://...' }
+{ 'id' => '526301', 'login' => 'yegor256', 'avatar' => 'http://...' }
 ```
 
 If the `secret` is an empty string, the encryption will be disabled.
@@ -103,10 +103,10 @@ it is:
 settings.glogin.login_uri
 ```
 
-For unit testing you can just provide an empty string as a `secret` for
+For unit testing, you can just provide an empty string as a `secret` for
 `GLogin::Cookie::Open` and `GLogin::Cookie::Closed`
 and the encryption will be disabled:
-whatever will be coming from the cookie will be trusted. For testing
+whatever comes from the cookie will be trusted. For testing
 it will be convenient to provide a user name in a query string, like:
 
 ```text
@@ -134,7 +134,7 @@ Also, you can use `GLogin::Codec` just to encrypt/decrypt a piece of text:
 
 ```ruby
 require 'glogin/codec'
-codec = GLogin:Codec.new('the secret')
+codec = GLogin::Codec.new('the secret')
 encrypted = codec.encrypt('Hello, world!')
 decrypted = codec.decrypt(encrypted)
 ```
@@ -143,7 +143,7 @@ decrypted = codec.decrypt(encrypted)
 
 Read
 [these guidelines](https://www.yegor256.com/2014/04/15/github-guidelines.html).
-Make sure you build is green before you contribute
+Make sure your build is green before you contribute
 your pull request. You will need to have
 [Ruby](https://www.ruby-lang.org/en/) 2.3+ and
 [Bundler](https://bundler.io/) installed. Then:

data/REUSE.toml

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+version = 1
+[[annotations]]
+path = [
+    ".DS_Store",
+    ".gitattributes",
+    ".gitignore",
+    ".pdd",
+    "**.json",
+    "**.md",
+    "**.png",
+    "**.svg",
+    "**.txt",
+    "**/.DS_Store",
+    "**/.gitignore",
+    "**/.pdd",
+    "**/*.csv",
+    "**/*.jpg",
+    "**/*.json",
+    "**/*.md",
+    "**/*.pdf",
+    "**/*.png",
+    "**/*.svg",
+    "**/*.txt",
+    "**/*.vm",
+    "**/CNAME",
+    "**/Gemfile.lock",
+    "Gemfile.lock",
+    "README.md",
+    "renovate.json",
+]
+precedence = "override"
+SPDX-FileCopyrightText = "Copyright (c) 2025 Yegor Bugayenko"
+SPDX-License-Identifier = "MIT"

data/Rakefile

@@ -1,29 +1,11 @@
 # frozen_string_literal: true
 
 #
-# Copyright (c) 2017-2025 Yegor Bugayenko
-#
-# 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.
+# SPDX-FileCopyrightText: Copyright (c) 2017-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 require 'rubygems'
 require 'rake'
-require 'rdoc'
 require 'rake/clean'
 
 def name
@@ -34,7 +16,7 @@ def version
   Gem::Specification.load(Dir['*.gemspec'].first).version
 end
 
-task default: %i[clean test rubocop copyright]
+task default: %i[clean test rubocop yard]
 
 require 'rake/testtask'
 desc 'Run all unit tests'
@@ -46,26 +28,14 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = false
 end
 
-require 'rdoc/task'
-desc 'Build RDoc documentation'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "#{name} #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+require 'yard'
+desc 'Build Yard documentation'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
 end
 
 require 'rubocop/rake_task'
 desc 'Run RuboCop on all directories'
 RuboCop::RakeTask.new(:rubocop) do |task|
   task.fail_on_error = true
-  task.requires << 'rubocop-rspec'
-end
-
-task :copyright do
-  sh "grep -q -r '2017-#{Date.today.strftime('%Y')}' \
-    --include '*.rb' \
-    --include '*.txt' \
-    --include 'Rakefile' \
-    ."
 end

data/glogin.gemspec

@@ -1,24 +1,7 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2017-2025 Yegor Bugayenko
-#
-# 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.
+# SPDX-FileCopyrightText: Copyright (c) 2017-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 require 'English'
 
@@ -42,6 +25,7 @@ Gem::Specification.new do |s|
   s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = ['README.md', 'LICENSE.txt']
   s.add_dependency 'base58', '>= 0.2'
+  s.add_dependency 'base64', '>= 0.2'
   s.add_dependency 'openssl', '>= 2.0'
   s.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/glogin/auth.rb

@@ -1,40 +1,51 @@
 # frozen_string_literal: true
 
-#
-# Copyright (c) 2017-2025 Yegor Bugayenko
-#
-# 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.
+# SPDX-FileCopyrightText: Copyright (c) 2017-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
+require 'cgi'
+require 'json'
 require 'net/http'
 require 'uri'
-require 'json'
-require 'cgi'
 
 # GLogin main module.
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
 # License:: MIT
 module GLogin
+  # GitHub authentication mechanism.
+  #
+  # This class handles the OAuth flow with GitHub, including generating
+  # authorization URLs and exchanging authorization codes for access tokens
+  # to retrieve user information.
   #
-  # GitHub auth mechanism
+  # @example Creating an Auth instance
+  #   auth = GLogin::Auth.new(
+  #     'your-github-client-id',
+  #     'your-github-client-secret',
+  #     'https://yourapp.com/callback'
+  #   )
   #
+  # @example Getting the GitHub login URL
+  #   login_url = auth.login_uri
+  #   # => "https://github.com/login/oauth/authorize?client_id=...&redirect_uri=..."
+  #
+  # @example Retrieving user information after callback
+  #   user_info = auth.user(params[:code])
+  #   # => {"id"=>"123456", "login"=>"username", "avatar_url"=>"https://..."}
   class Auth
+    # Creates a new GitHub authentication handler.
+    #
+    # @param id [String] GitHub OAuth application client ID
+    # @param secret [String] GitHub OAuth application client secret
+    # @param redirect [String] The callback URL where GitHub will redirect after authentication
+    # @raise [RuntimeError] if any parameter is nil or redirect is empty
+    # @example
+    #   auth = GLogin::Auth.new(
+    #     ENV['GITHUB_CLIENT_ID'],
+    #     ENV['GITHUB_CLIENT_SECRET'],
+    #     'https://myapp.com/auth/callback'
+    #   )
     def initialize(id, secret, redirect)
       raise "GitHub client ID can't be nil" if id.nil?
       @id = id
@@ -45,14 +56,39 @@ module GLogin
       @redirect = redirect
     end
 
+    # Generates the GitHub OAuth authorization URL.
+    #
+    # Users should be redirected to this URL to begin the authentication process.
+    # GitHub will ask them to authorize your application, then redirect them back
+    # to your specified redirect URL with an authorization code.
+    #
+    # @return [String] The GitHub OAuth authorization URL
+    # @example Redirect users to GitHub for authentication
+    #   auth = GLogin::Auth.new(id, secret, redirect_url)
+    #   redirect auth.login_uri
     def login_uri
       "https://github.com/login/oauth/authorize?client_id=#{CGI.escape(@id)}&redirect_uri=#{CGI.escape(@redirect)}"
     end
 
-    # Returns a hash with information about Github user,
+    # Returns a hash with information about GitHub user
     # who just logged in with the authentication code.
     #
-    # API: https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user
+    # This method exchanges the temporary authorization code (received from GitHub
+    # callback) for an access token, then uses that token to fetch the user's
+    # profile information.
+    #
+    # @param code [String] The authorization code received from GitHub callback
+    # @return [Hash] User information including 'id', 'login', and 'avatar_url'
+    # @raise [RuntimeError] if the code is nil, empty, or if the API request fails
+    # @example Handling the GitHub callback
+    #   get '/auth/callback' do
+    #     code = params[:code]
+    #     user = auth.user(code)
+    #     # user => {"id"=>"123456", "login"=>"octocat", "avatar_url"=>"https://..."}
+    #     session[:user_id] = user['id']
+    #   end
+    # @note When secret is empty (test mode), returns a mock user object
+    # @see https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user
     def user(code)
       if @secret.empty?
         return {

data/lib/glogin/codec.rb

@@ -1,51 +1,90 @@
 # frozen_string_literal: true
 
-#
-# Copyright (c) 2017-2025 Yegor Bugayenko
-#
-# 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 NONINFINGEMENT. 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.
+# SPDX-FileCopyrightText: Copyright (c) 2017-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
-require 'securerandom'
-require 'openssl'
-require 'digest/sha1'
 require 'base58'
 require 'base64'
+require 'digest/sha1'
+require 'openssl'
+require 'securerandom'
 
 # Codec.
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2017-2025 Yegor Bugayenko
 # License:: MIT
 module GLogin
-  # The codec
+  # The codec for encrypting and decrypting text.
+  #
+  # This class provides symmetric encryption using AES-256-CBC. It can encode
+  # text using either Base64 or Base58 encoding. A random salt is added to
+  # each encryption to ensure that the same plaintext produces different
+  # ciphertexts each time.
+  #
+  # @example Basic encryption and decryption
+  #   codec = GLogin::Codec.new('my-secret-key')
+  #   encrypted = codec.encrypt('sensitive data')
+  #   decrypted = codec.decrypt(encrypted)
+  #   # => "sensitive data"
+  #
+  # @example Using Base64 encoding
+  #   codec = GLogin::Codec.new('secret', base64: true)
+  #   encrypted = codec.encrypt('hello world')
+  #   # => "U29tZUJhc2U2NEVuY29kZWRTdHJpbmc="
+  #
+  # @example Test mode without encryption
+  #   codec = GLogin::Codec.new('')  # Empty secret
+  #   encrypted = codec.encrypt('plaintext')
+  #   # => "plaintext" (no encryption in test mode)
   class Codec
-    # When can't decode.
+    # Raised when decryption fails.
+    #
+    # This can happen when:
+    # - The encrypted text is corrupted
+    # - The wrong secret key is used
+    # - The text is not properly encoded (Base64/Base58)
     class DecodingError < StandardError; end
 
-    # Ctor.
-    # +secret+: The secret to do the encoding
-    # +base64+: If TRUE, Base-64 will be used, otherwise Base-58
+    # Creates a new codec instance.
+    #
+    # @param secret [String] The secret key for encryption. If empty, no encryption is performed (test mode)
+    # @param base64 [Boolean] Whether to use Base64 encoding (true) or Base58 encoding (false)
+    # @raise [RuntimeError] if secret is nil
+    # @example Create codec with Base58 encoding (default)
+    #   codec = GLogin::Codec.new('my-secret-key')
+    #
+    # @example Create codec with Base64 encoding
+    #   codec = GLogin::Codec.new('my-secret-key', base64: true)
+    #
+    # @example Create codec in test mode (no encryption)
+    #   codec = GLogin::Codec.new('')
     def initialize(secret = '', base64: false)
       raise 'Secret can\'t be nil' if secret.nil?
       @secret = secret
       @base64 = base64
     end
 
+    # Decrypts an encrypted text string.
+    #
+    # @param text [String] The encrypted text to decrypt
+    # @return [String] The decrypted plaintext
+    # @raise [RuntimeError] if text is nil
+    # @raise [DecodingError] if decryption fails due to:
+    #   - Invalid Base64/Base58 encoding
+    #   - Wrong secret key
+    #   - Corrupted ciphertext
+    #   - Missing or invalid salt
+    # @example Decrypt a Base58-encoded string
+    #   codec = GLogin::Codec.new('secret')
+    #   plaintext = codec.decrypt('3Hs9k2LgU...')
+    #   # => "hello world"
+    #
+    # @example Handle decryption errors
+    #   begin
+    #     plaintext = codec.decrypt(corrupted_text)
+    #   rescue GLogin::Codec::DecodingError => e
+    #     puts "Decryption failed: #{e.message}"
+    #   end
     def decrypt(text)
       raise 'Text can\'t be nil' if text.nil?
       if @secret.empty?
@@ -73,6 +112,30 @@ module GLogin
       raise DecodingError, e.message
     end
 
+    # Encrypts a plaintext string.
+    #
+    # The method adds a random salt to the text before encryption to ensure
+    # that encrypting the same text multiple times produces different results.
+    # The encrypted output is encoded using either Base64 or Base58.
+    #
+    # @param text [String] The plaintext to encrypt
+    # @return [String] The encrypted and encoded text
+    # @raise [RuntimeError] if text is nil
+    # @example Encrypt with Base58 encoding
+    #   codec = GLogin::Codec.new('secret')
+    #   encrypted = codec.encrypt('sensitive data')
+    #   # => "3Hs9k2LgU..." (Base58 encoded)
+    #
+    # @example Encrypt with Base64 encoding
+    #   codec = GLogin::Codec.new('secret', base64: true)
+    #   encrypted = codec.encrypt('sensitive data')
+    #   # => "U29tZUJhc2U2NC..." (Base64 encoded)
+    #
+    # @example Multiple encryptions produce different results
+    #   codec = GLogin::Codec.new('secret')
+    #   enc1 = codec.encrypt('hello')
+    #   enc2 = codec.encrypt('hello')
+    #   enc1 != enc2  # => true (due to random salt)
     def encrypt(text)
       raise 'Text can\'t be nil' if text.nil?
       if @secret.empty?