telegramauth

README

telegram-auth

telegram-auth is a tiny Go library for validating Telegram Login Widget callback data.

It verifies:

• callback signature (hash)
• required fields (id, auth_date, hash)
• id format and range (> 0)
• auth_date freshness (TTL and clock skew)

Install

go get github.com/ffanatik/telegram-auth

Quick example

package main

import (
	"fmt"
	"net/http"
	"os"

	telegramauth "github.com/ffanatik/telegram-auth"
)

func callback(w http.ResponseWriter, r *http.Request) {
	auth, err := telegramauth.VerifyURLValues(r.URL.Query(), os.Getenv("TELEGRAM_BOT_TOKEN"))
	if err != nil {
		http.Error(w, "Unauthorized", http.StatusUnauthorized)
		return
	}

	fmt.Fprintf(w, "Hello, %s (%d)", auth.FirstName, auth.UserID)
}

API

• Verify(map[string]string, botToken string)
• VerifyURLValues(url.Values, botToken string)
• VerifyWithConfig(map[string]string, botToken string, config VerifyConfig)

Default values:

• DefaultAuthTTL = 5 * time.Minute
• DefaultClockSkew = 30 * time.Second

All exported validation errors are sentinel errors and can be checked with errors.Is.

Documentation

Overview

Package telegramauth validates Telegram Login Widget callback data.

Index

• Constants
• Variables
• type AuthData
  • func Verify(query map[string]string, botToken string) (AuthData, error)
  • func VerifyURLValues(values url.Values, botToken string) (AuthData, error)
  • func VerifyWithConfig(query map[string]string, botToken string, config VerifyConfig) (AuthData, error)
• type VerifyConfig

Constants

const (
	// DefaultAuthTTL is the default maximum age for auth_date.
	DefaultAuthTTL = 5 * time.Minute
	// DefaultClockSkew is the default allowed future skew for auth_date.
	DefaultClockSkew = 30 * time.Second
)

Variables

var (
	// ErrBotTokenRequired indicates that botToken is empty.
	ErrBotTokenRequired = errors.New("bot token is required")
	// ErrTelegramIDRequired indicates that id is missing.
	ErrTelegramIDRequired = errors.New("telegram id is required")
	// ErrTelegramIDInvalid indicates that id is malformed or not positive.
	ErrTelegramIDInvalid = errors.New("telegram id is invalid")
	// ErrTelegramHashRequired indicates that hash is missing.
	ErrTelegramHashRequired = errors.New("telegram hash is required")
	// ErrTelegramHashInvalid indicates that hash is malformed or does not match.
	ErrTelegramHashInvalid = errors.New("telegram hash is invalid")
	// ErrTelegramAuthDateRequired indicates that auth_date is missing.
	ErrTelegramAuthDateRequired = errors.New("telegram auth_date is required")
	// ErrTelegramAuthDateInvalid indicates that auth_date is malformed.
	ErrTelegramAuthDateInvalid = errors.New("telegram auth_date is invalid")
	// ErrTelegramAuthDateExpired indicates that auth_date is older than allowed TTL.
	ErrTelegramAuthDateExpired = errors.New("telegram auth_date is expired")
	// ErrTelegramAuthDateFuture indicates that auth_date is too far in the future.
	ErrTelegramAuthDateFuture = errors.New("telegram auth_date is from future")
)

Types

type AuthData

type AuthData struct {
	// UserID is Telegram user ID.
	UserID int64
	// Username is Telegram username.
	Username string
	// FirstName is Telegram first_name.
	FirstName string
	// LastName is Telegram last_name.
	LastName string
	// PhotoURL is Telegram photo_url.
	PhotoURL string
	// AuthDateUnix is Telegram auth_date unix timestamp.
	AuthDateUnix int64
}

AuthData contains validated Telegram user fields from callback data.

func Verify

func Verify(query map[string]string, botToken string) (AuthData, error)

Verify validates Telegram callback data from a plain key/value map.

func VerifyURLValues

func VerifyURLValues(values url.Values, botToken string) (AuthData, error)

VerifyURLValues validates Telegram callback data from url.Values.

func VerifyWithConfig

func VerifyWithConfig(query map[string]string, botToken string, config VerifyConfig) (AuthData, error)

VerifyWithConfig validates Telegram callback data with custom options.

type VerifyConfig

type VerifyConfig struct {
	// AuthTTL sets maximum allowed age for auth_date.
	// Zero value uses DefaultAuthTTL.
	AuthTTL time.Duration
	// ClockSkew sets allowed future skew for auth_date.
	// Zero value uses DefaultClockSkew.
	ClockSkew time.Duration
	// Now overrides current time source.
	// Nil uses time.Now.
	Now func() time.Time
}

VerifyConfig configures VerifyWithConfig behavior.