diff options
Diffstat (limited to 'doc.go')
| -rw-r--r-- | doc.go | 150 |
1 files changed, 150 insertions, 0 deletions
@@ -0,0 +1,150 @@ +// Package kate provides secure cookie-based authentication for HTTP applications. +// +// This package implements encrypted cookies with authenticated encryption. +// It supports generic types to allow storage of any serializable data in encrypted HTTP cookies. +// +// Key features: +// - Type-safe authentication data storage using Go generics +// - Authenticated encryption for secure cookie storage +// - HTTP middleware for required and optional authentication +// - Ready-to-use login handlers for password, oauth, and magic link authentication +// - Configurable cookie properties (domain, path, HTTPS-only, max age) +// - Pluggable serialization interface for custom data formats +// - Secure password hashing with industry-standard algorithms +// +// Example usage: +// +// type UserData struct { +// ID int +// Name string +// } +// +// // Implement SerDes interface for UserData +// type UserSerDes struct{} +// func (s UserSerDes) Serialize(w io.Writer, data UserData) error { /* ... */ } +// func (s UserSerDes) Deserialize(r io.Reader, data *UserData) error { /* ... */ } +// +// // Create authentication instance +// auth := kate.New("hex-encoded-32-byte-key", kate.AuthConfig[UserData]{ +// SerDes: UserSerDes{}, +// CookieName: "session", +// HTTPSOnly: true, +// MaxAge: 24 * time.Hour, +// }) +// +// // Use as middleware +// http.Handle("GET /protected", auth.Required(protectedHandler)) +// +// // Set authentication cookie +// user := UserData{ID: 123, Name: "John"} +// auth.Set(w, user) +// +// // Get authenticated data +// user, ok := auth.Get(r.Context()) +// +// Login handlers: +// +// type User struct { +// Username string +// Hash string +// ID int +// } +// +// // Implement PasswordUserDataStore interface +// type UserStore struct{} +// func (us UserStore) Fetch(username string) (User, bool, error) { +// user, exists := database.FindUser(username) +// return user, exists, nil +// } +// func (us UserStore) GetPassHash(user User) string { +// return user.Hash +// } +// +// // Password-based login +// passwordConfig := kate.PasswordLoginConfig[User]{ +// UserData: UserStore{}, +// Redirects: kate.Redirects{ +// Default: "/dashboard", +// AllowedPrefixes: []string{"/app/", "/admin/"}, +// FieldName: "redirect", +// }, +// } +// http.Handle("POST /login", auth.PasswordLoginHandler(passwordConfig)) +// +// // Implement MagicLinkMailer interface +// type UserMailer struct{} +// func (um UserMailer) Fetch(email string) (User, bool, error) { +// user, exists := database.FindUserByEmail(email) +// return user, exists, nil +// } +// func (um UserMailer) SendEmail(user User, token string) error { +// return emailService.SendMagicLink(user.Email, token) +// } +// +// // Magic link authentication +// magicConfig := kate.MagicLinkConfig[User]{ +// Mailer: UserMailer{}, +// Redirects: kate.Redirects{ Default: "/dashboard" }, +// TokenExpiry: 15 * time.Minute, +// TokenLocation: kate.TokenLocationQuery, +// } +// http.Handle("POST /magic-link", auth.MagicLinkLoginHandler(magicConfig)) +// http.Handle("GET /verify", auth.MagicLinkVerifyHandler(magicConfig)) +// +// // OAuth2 authentication (Google example) +// type UserDataStore struct{} +// func (ds UserDataStore) GetOrCreateUser(email string) (User, error) { +// user, exists := database.FindUserByEmail(email) +// if exists { +// return user, nil +// } +// return database.CreateUser(email) +// } +// func (ds UserDataStore) StoreState(state kate.OAuthState) (string, error) { +// id := generateUniqueID() +// return id, cache.Set(id, state, 10*time.Minute) +// } +// func (ds UserDataStore) GetAndClearState(id string) (*kate.OAuthState, error) { +// var state kate.OAuthState +// exists, err := cache.GetAndDelete(id, &state) +// if !exists { +// return nil, err +// } +// return &state, err +// } +// +// oauthConfig := kate.GoogleOAuthConfig[User]( +// "your-client-id", +// "your-client-secret", +// "https://yourapp.com/auth/callback", +// UserDataStore{}, +// ) +// // Customize redirects if needed +// oauthConfig.Redirects = kate.Redirects{ +// Default: "/dashboard", +// AllowedPrefixes: []string{"/app/", "/admin/"}, +// FieldName: "redirect", +// } +// http.Handle("GET /auth/login", auth.OAuthLoginHandler(oauthConfig)) +// http.Handle("GET /auth/callback", auth.OAuthCallbackHandler(oauthConfig)) +// +// Password hashing: +// +// // Hash a password with defaults +// hash, err := kate.HashPassword("user-password", nil) +// +// // Verify a password +// match, err := kate.ComparePassword("user-password", hash) +// if err != nil { +// // Handle malformed hash error +// } +// if match { +// // Password is correct +// } +// +// Cryptographic algorithms: +// +// This package uses the following cryptographic algorithms: +// - Token encryption: XSalsa20 stream cipher with Poly1305 MAC for authenticated encryption (compatible with libsodium secretbox) +// - Password hashing: Argon2id with secure default parameters and PHC format storage +package kate |