tg-auth

Telegram authentication for Crystal applications. Provides OAuth-like login flow, bot token validation, and secure callback verification.

Documentation

Full API documentation is available at: documentation

Features

• bot token validation with Telegram API
• Username verification
• Telegram login URL generation
• Secure callback verification with HMAC-SHA256
• CSRF protection with state parameter
• Zero external dependencies (uses Crystal stdlib)
• Full test coverage

Installation

Add this to your application's shard.yml:

dependencies:
  tg-auth:
    gitlab: telegem-cr/tg-auth
    version: ~> 0.1.0

Then run:

shards install

Usage

1. Quick Start

require "tg-auth"

# Initialize with your bot credentials
auth = TgAuth.auth(
  token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
  username: "MyExampleBot",
  callback_url: "https://yourapp.com/auth/telegram/callback"
)

# Check if bot is valid
if auth.result && auth.result[:success]
  puts "Bot is valid!"
  
  # Generate login URL for user
  login_url = auth.start_auth
  puts "Send user to: #{login_url}"
else
  puts " Bot validation failed: #{auth.result[:message] if auth.result}"
end

2. Bot Validation Only

validator = TgAuth.validate(
  token: "123456:ABC-DEF1234ghIkl",
  username: "MyExampleBot"
)

if validator.result[:success]
  puts "✓ Token and username match"
else
  puts "✗ #{validator.result[:message]}"
end

3. Complete Authentication Flow

# In your web app (Lucky, Amber, Kemal, etc.)

# Step 1: Redirect user to Telegram login
get "/auth/telegram" do
  auth = TgAuth.auth(
    token: ENV["BOT_TOKEN"],
    username: ENV["BOT_USERNAME"],
    callback_url: "https://yourapp.com/auth/telegram/callback"
  )
  
  redirect auth.start_auth.not_nil!
end

Step 2: Handle callback

get "/auth/telegram/callback" do |env|
  auth = TgAuth.auth(
    token: ENV["BOT_TOKEN"],
    username: ENV["BOT_USERNAME"],
    callback_url: "https://yourapp.com/auth/telegram/callback"
  )
  
  result = auth.verify_callback(env.params)
  
  if result[:success]
    user_data = result[:user]
    # Create or login user
    session[:user_id] = user_data["id"]
    redirect "/dashboard"
  else
    # Show error
    "Authentication failed: #{result[:error]}"
  end
end

API Reference

TgAuth.auth(token, username, callback_url)

Creates a new authentication instance with validation.

• Parameters:
  • token (String) – Telegram bot token from @BotFather
  • username (String) – Bot username (without @)
  • callback_url (String) – Your OAuth callback URL
• Returns: Auth::Auth instance

TgAuth.validate(token, username)

Validates bot token and username without setting up OAuth.

• Parameters:
  • token (String) – Telegram bot token
  • username (String) – Expected bot username
• Returns: Auth::Validate instance with .result

Auth::Auth#start_auth

Generates Telegram login URL.

• Returns: String? – Login URL if validation passed, nil otherwise

Auth::Auth#verify_callback(params)

Verifies Telegram callback parameters.

• Parameters:
  • params (Hash(String, String)) – Callback parameters from Telegram
• Returns: NamedTuple(success: Bool, user: Hash(String, String)?, error: String?)

Development

Running Tests

shards install
crystal spec

Generating Documentation

crystal docs

Code Style

ameba

🤝 Contributing

1. Fork it (https://gitlab.com/telegem-cr/tg-auth/-/forks)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Merge Request

License

MIT License. See LICENSE for details.

Author

slick_phantom

---

Made with ❤️ for the Crystal community