go-dev-auth: Thư viện xác thực Go không phụ thuộc, mô phỏng theo better-auth

go-dev-auth là một thư viện xác thực toàn diện, không phụ thuộc framework cho Go, được mô phỏng theo better-auth. Thư viện hỗ trợ email/mật khẩu, đăng nhập mạng xã hội, phiên làm việc, liên kết tài khoản, xác thực hai yếu tố, passkey, magic link, tổ chức, SSO, công cụ quản trị, API key và JWT — tất cả với không phụ thuộc bên ngoài (chỉ dùng thư viện chuẩn).

CI badge

Tổng quan

Thư viện hiện đang ở giai đoạn tiền 1.0, đã được sử dụng trong sản xuất thực tế và đang hướng tới v1.0. Nó đang chạy trong một dự án tự động hóa thực tế trên PostgreSQL, sử dụng đầy đủ bộ tính năng. Các bản phát hành tuân theo SemVer: trong giai đoạn tiền 1.0, API công khai vẫn có thể thay đổi giữa các phiên bản nhỏ (nên ghim phiên bản chính xác); v1.0 sẽ đóng băng API, và từ đó các thay đổi phá vỡ tương thích yêu cầu phiên bản chính mới.

Các cổng còn lại để đạt v1.0 bao gồm: ví dụ có thể chạy được, dặm thực tế trên nhánh MySQL mới được tự động hóa, và đánh giá bảo mật của bên thứ ba.

Go Reference

Tính năng cốt lõi

• Xác thực email & mật khẩu với băm scrypt, tương thích định dạng băm của better-auth
• Đăng nhập mạng xã hội qua OAuth 2.0 / OIDC với PKCE — hỗ trợ sẵn Google, GitHub, Discord, Facebook, Microsoft, Apple, GitLab, LinkedIn, Spotify, Twitch, X, cộng với oauth2.Spec khai báo cho bất kỳ nhà cung cấp tùy chỉnh nào
• Phiên làm việc dựa trên cơ sở dữ liệu với hết hạn trượt, cookie ký, bộ đệm cookie tùy chọn, các endpoint liệt kê/thu hồi
• Xác minh email, đặt lại mật khẩu, đổi email/mật khẩu, xóa người dùng
• Liên kết & hủy liên kết tài khoản (nhà cung cấp tin cậy, làm mới token, thông tin tài khoản)
• Kiểm tra nguồn gốc CSRF, nguồn gốc tin cậy với tên miền phụ ký tự đại diện, giới hạn tốc độ dựa trên IP
• Bộ điều hợp lưu trữ với database/sql tích hợp (Postgres, MySQL, SQLite) và bộ điều hợp trong bộ nhớ, cộng với tạo SQL schema/di chuyển
• Hook yêu cầu, hook cơ sở dữ liệu, trường người dùng/phiên tùy chỉnh

Plugin

Thư viện cung cấp hệ thống plugin mô phỏng theo better-auth:

• twofactor — TOTP, OTP email và mã dự phòng
• passkey — WebAuthn passkey, bao gồm phân tích CBOR/COSE (không phụ thuộc bên ngoài)
• magiclink — liên kết email không cần mật khẩu
• organization — tổ chức, thành viên, vai trò, lời mời, nhóm
• sso — nhà cung cấp danh tính OIDC tự mang, khớp theo tên miền email
• admin — quản lý người dùng, cấm, vai trò, mạo danh
• apikey — API key được băm với phạm vi xác thực như phiên
• jwt — JWT ký EdDSA + endpoint JWKS
• bearer — xác thực header Authorization cho client không phải trình duyệt

Bắt đầu nhanh

package main

import (
    "context"
    "net/http"
    "os"
    "time"

    godevauth "github.com/go-dev-auth/go-dev-auth"
    "github.com/go-dev-auth/go-dev-auth/storage/memory"
)

func main() {
    auth, err := godevauth.New(godevauth.Config{
        BaseURL:  "http://localhost:8080",       // bắt buộc
        Secret:   os.Getenv("AUTH_SECRET"),      // bắt buộc, 32+ ký tự ngẫu nhiên
        Database: memory.New(),                  // bắt buộc
        EmailAndPassword: godevauth.EmailPasswordConfig{Enabled: true},
        Advanced: godevauth.AdvancedConfig{
            TrustProxyHeaders: true,
            TrustedProxies:    []string{"10.0.0.0/8"},
        },
    })
    if err != nil {
        panic(err)
    }

    defer auth.StartCleanup(context.Background(), time.Hour)()

    mux := http.NewServeMux()
    mux.Handle("/api/auth/", auth.Handler())
    http.ListenAndServe(":8080", mux)
}

Handler là một http.Handler thuần, nên có thể gắn lên chi, echo, gorilla, hoặc gin (qua gin.WrapH) theo cùng cách.

Yêu cầu triển khai: thông báo cho thư viện về proxy

Giới hạn tốc độ và mọi IP phiên được ghi lại phụ thuộc vào việc phân giải địa chỉ client. Nếu có bất cứ thứ gì chấm dứt kết nối trước tiến trình này — AWS ALB, nginx, Cloudflare, Kubernetes ingress — bạn phải khai báo, vì cả hai mặc định đều sai theo hướng khác nhau:

Cấu hình	Điều gì xảy ra
Không đặt gì, nhưng chạy sau proxy	Mọi yêu cầu phân giải về địa chỉ proxy, tất cả client chia sẻ một bucket. Quy tắc nghiêm ngặt 3 lần đăng nhập/10 giây trở thành 3 lần/10 giây cho toàn bộ hệ thống. Đây là sự cố tự gây ra.
TrustProxyHeaders không có TrustedProxies	X-Forwarded-For do client cung cấp. Bất kỳ người gọi nào cũng tự chọn bucket và giới hạn ngừng giới hạn bất cứ thứ gì.
TrustProxyHeaders + TrustedProxies	Chính xác. Header chuyển tiếp chỉ được đọc từ peer được liệt kê.

Bộ điều hợp lưu trữ

Bộ điều hợp	Import	Ghi chú
Trong bộ nhớ	storage/memory	Kiểm thử, ví dụ, đơn tiến trình
SQL	storage/sqlstore	PostgreSQL, MySQL, SQLite qua database/sql
MongoDB	storage/mongostore	Driver mongo-go chính thức. Module Go riêng

Go Report Card

Tất cả bộ điều hợp được viết dựa trên cùng một bộ kiểm thử tuân thủ (storage/storagetest), ghim các ngữ nghĩa mà lõi xác thực phụ thuộc vào.

Mô hình bảo mật

Mật khẩu

Sử dụng scrypt (N=16384, r=16, p=1), định dạng hex salt:key của better-auth. Mỗi lần băm tốn ~50ms CPU và ~32MiB bộ nhớ tạm theo thiết kế; bộ băm giới hạn đồng thời và gộp bộ đệm để một loạt đăng nhập không thể làm cạn kiệt bộ nhớ.

Phiên làm việc

Token ngẫu nhiên 32 byte, cookie ký HMAC với phân tách tên miền và tiền tố __Secure- trên HTTPS. Token thô không bao giờ được đưa vào danh sách phiên.

OAuth

PKCE (S256), state ghim vào trình duyệt với cookie và nhà cung cấp phát hành, dùng một lần và hết hạn. Liên kết tài khoản tự động yêu cầu cả email đã xác minh do nhà cung cấp khẳng định và nhà cung cấp đó nằm trong danh sách tin cậy.

CSRF

Các yêu cầu thay đổi trạng thái được kiểm tra nguồn gốc dựa trên BaseURL + TrustedOrigins.

Bí mật lưu trữ

Bí mật TOTP, mã dự phòng và khóa riêng JWT được mã hóa AES-256-GCM với khóa dẫn xuất từ Secret của bạn. Mọi ciphertext được ràng buộc với vị trí lưu trữ — mô hình, id bản ghi và tên trường được xác thực cùng với giá trị.

Hiệu năng

Đo trên container arm64 4 nhân so với bộ điều hợp trong bộ nhớ:

Thao tác	Chi phí
Xác thực phiên (cookie -> người dùng)	~0.6 µs song song, 21 cấp phát
Yêu cầu HTTP đầy đủ qua router	~4 µs, 47 cấp phát
Tra cứu phiên, 10k hàng	~0.5 µs (có chỉ mục)
Băm / xác minh mật khẩu	~51 ms, 21 KB

Mọi thứ ngoại trừ băm mật khẩu đều tính bằng micro giây. Băm mật khẩu chiếm ưu thế CPU — khoảng 51ms mỗi lần đăng nhập nghĩa là khoảng sign-ins/sec ÷ 20 lõi CPU.

Đóng góp và giấy phép

Dự án sử dụng go.work cho phát triển cục bộ. Chạy make check để chạy fmt, vet, lint, tests và race. Xem CONTRIBUTING.md cho kỳ vọng về thay đổi, SECURITY.md cho mô hình bảo mật và quy trình báo cáo.

Thư viện được phát hành dưới giấy phép MIT.

License

Nhận định cho độc giả Việt Nam: Với các dự án Go tại Việt Nam — đặc biệt là các startup fintech và nền tảng SaaS cần xác thực mạnh mẽ nhưng muốn giảm phụ thuộc — go-dev-auth là lựa chọn đáng cân nhắc. Việc không phụ thuộc bên ngoài giúp giảm rủi ro chuỗi cung ứng, một mối quan tâm ngày càng tăng trong cộng đồng phát triển phần mềm. Tuy nhiên, do đang ở giai đoạn tiền 1.0, các nhóm nên ghim phiên bản chính xác trước khi triển khai production.