glogin 0.16.5 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7ee2b3588faa0297950d9a0c6d7b6df1671fd05220fdcda8118480a4a117d46
-  data.tar.gz: 9deff64ac0bea305d078259160bfeac8aaff6b7ab09a2a8695843122b10a10c9
+  metadata.gz: 70ae5615b657f9b0317275a3b7d5fe65eccdbbb1031d2f09d60b37715ebb232e
+  data.tar.gz: 8c3867ec9311912f049694be981dfa7141971539e652e0f24c02377d0d3ce8df
 SHA512:
-  metadata.gz: 9bd7e92b91df017728c8a35d7aada795206090e69aa0547ab0f7f59e54ba189da7797c827a111c8f64a1274744bfff4a8bbd4d0371f6fa93096ea61925ad9d3f
-  data.tar.gz: 0c8b5c829294f6ac683c660bd54fbe2a485bffbb76daf70096d4c3772c5c380161e3da9a011a403aa7f3a1348b3d9c3b17fa88149e114f8a276bbdfa8fb208e6
+  metadata.gz: 9c631be9cc3d9f1e8ded85802aec693a2ce22fd1a920d049b40c413714ab51a9c327daab6c1404e06242b7df5df47faee8845688e33b387c9d803436a7ef60bd
+  data.tar.gz: f43009a609ca1eecfffe0842cfe68f395bcae50549ecab083a05e4933fb1c0e9620498b999e3169ecec637dbe4e908d6afc6303cf515968b549c4103d52c8161

data/Gemfile

@@ -1,36 +1,20 @@
 # 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
 
 source 'https://rubygems.org'
 gemspec
 
-gem 'minitest', '5.25.2', require: false
-gem 'rake', '13.2.1', require: false
-gem 'rdoc', '6.11.0', require: false
-gem 'rspec-rails', '7.1.0', require: false
-gem 'rubocop', '1.71.0', require: false
-gem 'rubocop-minitest', '0.36.0', require: false
-gem 'rubocop-performance', '1.23.1', require: false
-gem 'rubocop-rspec', '3.4.0', require: false
-gem 'simplecov', '0.22.0', require: false
-gem 'webmock', '3.24.0', require: false
+gem 'minitest', '~>6.0', require: false
+gem 'minitest-reporters', '~>1.7', require: false
+gem 'rake', '~>13.2', require: false
+gem 'rdoc', '~>7.0', require: false
+gem 'rubocop', '~>1.71', require: false
+gem 'rubocop-minitest', '~>0.38', require: false
+gem 'rubocop-performance', '~>1.25', require: false
+gem 'rubocop-rake', '~>0.7', require: false
+gem 'simplecov', '~>0.22', require: false
+gem 'simplecov-cobertura', '~>3.0', require: false
+gem 'webmock', '~>3.24', require: false
+gem 'yard', '~>0.9', require: false

data/Gemfile.lock

@@ -0,0 +1,125 @@
+PATH
+  remote: .
+  specs:
+    glogin (0.0.0)
+      base58 (>= 0.2)
+      base64 (>= 0.2)
+      openssl (>= 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ansi (1.5.0)
+    ast (2.4.3)
+    base58 (0.2.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    builder (3.3.0)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    date (3.5.1)
+    docile (1.4.1)
+    erb (6.0.1)
+    hashdiff (1.2.1)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    minitest (6.0.0)
+      prism (~> 1.5)
+    minitest-reporters (1.7.1)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    openssl (4.0.0)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.7.0)
+    psych (5.3.1)
+      date
+      stringio
+    public_suffix (7.0.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    rdoc (7.0.1)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rubocop (1.82.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.48.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-minitest (0.38.2)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-cobertura (3.1.0)
+      rexml
+      simplecov (~> 0.19)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.2.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.38)
+
+PLATFORMS
+  arm64-darwin-22
+  arm64-darwin-23
+  arm64-darwin-24
+  x64-mingw-ucrt
+  x86_64-linux
+
+DEPENDENCIES
+  glogin!
+  minitest (~> 6.0)
+  minitest-reporters (~> 1.7)
+  rake (~> 13.2)
+  rdoc (~> 7.0)
+  rubocop (~> 1.71)
+  rubocop-minitest (~> 0.38)
+  rubocop-performance (~> 1.25)
+  rubocop-rake (~> 0.7)
+  simplecov (~> 0.22)
+  simplecov-cobertura (~> 3.0)
+  webmock (~> 3.24)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.5.16

data/LICENSES/MIT.txt

@@ -0,0 +1,21 @@
+(The MIT License)
+
+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.

data/README.md

@@ -1,18 +1,18 @@
 # 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)
 
-This simple gem will help you enable login/logout through
+This simple gem helps you enable login/logout through
 [GitHub OAuth][doc]
 for your web application. This is how it works with
 [Sinatra](http://www.sinatrarb.com/),
@@ -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,14 +59,14 @@ before '/*' do
 end
 ```
 
-If the `glogin` cookie is coming in and contains a valid data,
-a local variable `@user` will be set to something like this:
+If the `glogin` cookie is coming in and contains valid data,
+a local variable `@user` is 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.
+If the `secret` is an empty string, the encryption is disabled.
 
 Next, we need a URL for GitHub OAuth callback:
 
@@ -94,20 +94,20 @@ It is recommended to provide the third "context" parameter to
 `GLogin::Cookie::Closed` and `GLogin::Cookie::Open` constructors, in order
 to enforce stronger security. The context may include the `User-Agent`
 HTTP header of the user, their IP address, and so on. When anything
-changes on the user side, they will be forced to re-login.
+changes on the user side, they are forced to re-login.
 
-One more thing is the login URL you will need for your front page. Here
-it is:
+One more thing is the login URL you need for your front page.
+Here it is:
 
 ```ruby
 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
-it will be convenient to provide a user name in a query string, like:
+and the encryption is disabled: whatever comes from the cookie is trusted.
+For testing it is convenient to provide a user name in a query string,
+like:
 
 ```text
 http://localhost:9292/?glogin=tester
@@ -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,8 +143,8 @@ 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
-your pull request. You will need to have
+Make sure your build is green before you contribute
+your pull request. You 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,15 @@ 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']
+  t.options = ['--fail-on-warning']
 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'
 
@@ -36,12 +19,13 @@ Gem::Specification.new do |s|
   s.description = 'Enables login/logout functionality for a Ruby web app'
   s.authors = ['Yegor Bugayenko']
   s.email = 'yegor256@gmail.com'
-  s.homepage = 'http://github.com/yegor256/glogin'
-  s.files = `git ls-files`.split($RS)
+  s.homepage = 'https://github.com/yegor256/glogin'
+  s.files = `git ls-files | grep -v -E '^(test/|\\.|renovate)'`.split($RS)
   s.executables = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
   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,20 +56,45 @@ 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 {
-          'id' => 526_301,
-          'login' => 'yegor256',
-          'avatar_url' => 'https://github.com/yegor256.png'
+          'id' => 1_024_025,
+          'login' => 'torvalds',
+          'avatar_url' => 'https://github.com/torvalds.png'
         }
       end
       raise 'Code can\'t be nil' if code.nil?