cryden

README

CrydenSync 🔐

Embeddable authentication engine for Go — offline-first, framework-agnostic.

🎯 The Problem

Authentication is not business logic, yet every project rewrites it. Developers face three painful choices:

1. Rewrite auth logic for every project — risky, inconsistent, time-consuming
2. Use hosted auth services — vendor lock-in, users aren't yours, requires internet
3. Use framework-specific tools — tied to Express, Django, Next.js — not reusable

💡 The Solution

CrydenSync is an embeddable authentication engine that gives you a standard, reusable auth system you control:

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/crydensync/cryden"
)

func main() {
    // Create context
    ctx := context.Background()
    
    // 1. Create engine (in-memory storage - perfect for testing)
    engine := cryden.New()
    fmt.Println("✅ Engine created")
    
    // 2. Sign up a new user
    email := "alice@example.com"
    password := "SecurePass123"
    
    user, err := cryden.SignUp(ctx, engine, email, password)
    if err != nil {
        log.Fatalf("❌ SignUp failed: %v", err)
    }
    fmt.Printf("✅ User created: %s (%s)\n", user.ID, user.Email)
    
    // 3. Login
    tokens, rateLimit, err := cryden.Login(ctx, engine, email, password)
    if err != nil {
        log.Fatalf("❌ Login failed: %v", err)
    }
    fmt.Printf("✅ Login successful!\n")
    fmt.Printf("   Access Token: %s...\n", tokens.AccessToken[:50])
    fmt.Printf("   Refresh Token: %s...\n", tokens.RefreshToken[:50])
    fmt.Printf("   Rate Limit Remaining: %d\n", rateLimit.Remaining)
    
    // 4. Verify token
    userID, err := cryden.VerifyToken(engine, tokens.AccessToken)
    if err != nil {
        log.Fatalf("❌ Token verification failed: %v", err)
    }
    fmt.Printf("✅ Token verified for user: %s\n", userID)
    
    // 5. Logout
    err = cryden.Logout(ctx, engine, tokens.RefreshToken)
    if err != nil {
        log.Fatalf("❌ Logout failed: %v", err)
    }
    fmt.Println("✅ Logout successful")
    
    // 6. Try to use logged out token (should fail)
    _, err = cryden.RefreshToken(ctx, engine, tokens.RefreshToken)
    if err != nil {
        fmt.Printf("✅ Expected error after logout: %v\n", err)
    }
    
    fmt.Println("\n🎉 All tests passed!")
}  
  

View full example →

✨ Features

✅ v1.0.0 (Current)

· Email/password authentication — Secure, bcrypt hashed · JWT access tokens — Short-lived, stateless · Opaque refresh tokens — Stored in DB for revocation · Rate limiting — Per IP with headers (X-RateLimit-*) · Audit logging — Track every auth event · Session management — Logout single device or all devices · Multiple storage backends — Memory, SQLite, PostgreSQL, MongoDB · Complete test suite — 90%+ coverage · Offline-first — Works without internet, SQLite by default

🚧 Coming Soon

Feature Status Target gRPC API 🚧 Planned v1.1.0 CLI tool (csax) 🚧 Planned v1.1.0 Language SDKs (JS, Python, PHP) 🚧 Planned v1.2.0 MFA/2FA (TOTP) 📅 Future v1.3.0 Magic Links 📅 Future v1.3.0 WebAuthn/Passkeys 📅 Future v2.0.0

📦 Installation

go get github.com/crydensync/cryden@v1.0.0

📖 Documentation

Section Description 📚 Getting Started 60-second working auth 🎯 Philosophy Why Cryden exists 🏗️ Architecture How it works 📐 Design Decisions Why we built it this way 🔧 Guide Installation, config, middleware, testing 🔌 Adapters Interface implementations 📘 API Reference Complete API docs 💡 Examples Copy-paste working code

🧪 Testing

CrydenSync is designed for maximum testability:

func TestLogin(t *testing.T) {
    engine := cryden.New()  // In-memory storage
    
    // Optional: Use mock hasher for faster tests
    engine.WithHasher(&core.MockHasher{})
    
    // Optional: Disable rate limiting
    engine.WithRateLimiter(&core.NoopRateLimiter{})
    
    ctx := context.Background()
    cryden.SignUp(ctx, engine, "test@example.com", "pass")
    tokens, _, err := cryden.Login(ctx, engine, "test@example.com", "pass")
    
    assert.NoError(t, err)
    assert.NotEmpty(t, tokens.AccessToken)
}

📖 Testing Guide →

🔧 Configuration

// With SQLite persistence
engine, err := cryden.WithSQLite("users.db")

// With custom JWT secret (required in production)
cryden.WithJWTSecret(engine, os.Getenv("JWT_SECRET"))

// With custom rate limiter
engine.WithRateLimiter(redis.NewRateLimiter())

// With custom audit logger
engine.WithAuditLogger(file.NewAuditLogger("auth.log"))

📊 Storage Backends

Backend Status Use Case Memory ✅ Stable Testing SQLite ✅ Stable Offline-first, development PostgreSQL ✅ Stable Production MongoDB ✅ Stable Document stores MySQL 🚧 Planned v1.1.0 Redis 🚧 Planned v1.1.0 (rate limiting)

📛 About the Name

CrydenSync is the full name of the project, but the Go package is simply cryden for brevity.

import "github.com/crydensync/cryden"  // Notice: crydensync/cryden

auth := cryden.New()  // Short and sweet!

🔒 Security Notes v1.0.0

✅ Implemented

• Password hashing with bcrypt
• JWT signing with HMAC-SHA256
• Rate limiting to prevent brute force
• Audit logging for all auth events

⚠️ Planned for v1.1.0

• Refresh token hashing in database
• Session token hashing
• Device fingerprinting
• Argon2id hasher option

Future Security Enhancements

• Email verification (v1.1)
• Password reset flow (v1.1)
• MFA/2FA (v1.2)
• Login notifications (v1.2)
• Breached password detection (v1.2)

🔐 Best Practices

1. Always use HTTPS in production
2. Set strong JWT secrets via environment variables
3. Monitor audit logs for suspicious activity
4. Add email verification before sensitive actions

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

· Code of Conduct · Development setup · Pull request process · Coding standards

📄 License

MIT © Crydensync

⭐ Support

If you find Cryden useful, please star the repo!

🗺️ Roadmap

Current: v1.0.0 (March 2026)

✅ Core authentication with email/password. ✅ JWT + refresh tokens. ✅ Rate limiting & audit logs. ✅ Multiple databases (SQLite, PostgreSQL, MongoDB)

Coming in v1.1.0 (Q2 2026)

🚀 CLI tool (csax) 📱 Device tracking (IP, user agent, last seen) 🔐 Argon2id hasher ⚡ Redis rate limiter le audit logger 🐬 MySQL support

Coming in v1.2.0 (Q3 2026)

🔌 gRPC API 🌐 Language SDKs (JS, Python, PHP) 🔔 Webhooks 🔄 Migration tools (Clerk, Auth0, Supabase)

Coming in v1.3.0 (Q4 2026)

🔐 Multi-Factor Authentication (TOTP) 📧 Magic links & passwordless 🔑 WebAuthn / Passkeys 🌍 Social login (OAuth2)

Future (2027+)

☁️ Optional cloud sync 📊 Enterprise features 🔌 More adapters 🚀 v2.0.0 (breaking changes if needed)

View full roadmap →

---

_{Built with ❤️ in Africa · Own your users, not vendor lock-in}

Documentation

Overview

Package cryden is the main entry point for the CrydennSync authentication engine.

Index

• Variables
• func ChangeEmail(ctx context.Context, engine *Engine, userID, newEmail string) error
• func ChangePassword(ctx context.Context, engine *Engine, userID, oldPassword, newPassword string) error
• func DeleteAccount(ctx context.Context, engine *Engine, userID string) error
• func Login(ctx context.Context, engine *Engine, email, password string) (*TokenPair, *LimitResult, error)
• func Logout(ctx context.Context, engine *Engine, refreshToken string) error
• func LogoutAll(ctx context.Context, engine *Engine, userID string) error
• func RevokeSession(ctx context.Context, engine *Engine, sessionID string) error
• func VerifyToken(engine *Engine, tokenString string) (string, error)
• type AuditEntry
• type AuditLogger
• type Claims
• type Engine
  • func New() *Engine
  • func WithAuditLogger(engine *Engine, logger AuditLogger) *Engine
  • func WithHasher(engine *Engine, hasher Hasher) *Engine
  • func WithJWTSecret(engine *Engine, secret string) *Engine
  • func WithRateLimiter(engine *Engine, limiter RateLimiter) *Engine
  • func WithSQLite(dbPath string) (*Engine, error)
• type Hasher
• type LimitResult
• type RateLimiter
• type Session
  • func ListSessions(ctx context.Context, engine *Engine, userID string) ([]Session, error)
• type SessionStore
• type TokenPair
  • func RefreshToken(ctx context.Context, engine *Engine, refreshToken string) (*TokenPair, error)
• type User
  • func GetUser(ctx context.Context, engine *Engine, userID string) (*User, error)
  • func GetUserByEmail(ctx context.Context, engine *Engine, email string) (*User, error)
  • func SignUp(ctx context.Context, engine *Engine, email, password string) (*User, error)
• type UserStore

Variables

var (
	ErrUserExists         = core.ErrUserExists
	ErrUserNotFound       = core.ErrUserNotFound
	ErrInvalidCredentials = core.ErrInvalidCredentials
	ErrInvalidEmail       = core.ErrInvalidEmail
	ErrPasswordTooShort   = core.ErrPasswordTooShort
	ErrPasswordTooLong    = core.ErrPasswordTooLong
	ErrPasswordNoUpper    = core.ErrPasswordNoUpper
	ErrPasswordNoLower    = core.ErrPasswordNoLower
	ErrPasswordNoNumber   = core.ErrPasswordNoNumber
	ErrTooManyAttempts    = core.ErrTooManyAttempts
	ErrInvalidToken       = core.ErrInvalidToken
	ErrSessionNotFound    = core.ErrSessionNotFound
)

Functions

func ChangeEmail

func ChangeEmail(ctx context.Context, engine *Engine, userID, newEmail string) error

ChangeEmail updates user's email

func ChangePassword

func ChangePassword(ctx context.Context, engine *Engine, userID, oldPassword, newPassword string) error

ChangePassword updates user's password and logs out all devices

func DeleteAccount

func DeleteAccount(ctx context.Context, engine *Engine, userID string) error

DeleteAccount removes user and all sessions

func Login

func Login(ctx context.Context, engine *Engine, email, password string) (*TokenPair, *LimitResult, error)

Login authenticates a user and returns tokens

func Logout

func Logout(ctx context.Context, engine *Engine, refreshToken string) error

Logout revokes the current session

func LogoutAll

func LogoutAll(ctx context.Context, engine *Engine, userID string) error

LogoutAll revokes ALL sessions for a user

func RevokeSession

func RevokeSession(ctx context.Context, engine *Engine, sessionID string) error

RevokeSession manually revokes a specific session

func VerifyToken

func VerifyToken(engine *Engine, tokenString string) (string, error)

VerifyToken validates a JWT access token and returns the user ID

Types

type AuditEntry

type AuditEntry = core.AuditEntry

type AuditLogger

type AuditLogger = core.AuditLogger

type Claims

type Claims = core.Claims

type Engine

type Engine = core.Engine

Engine is the main authentication engine

func New

func New() *Engine

New creates an in-memory engine (perfect for testing)

func WithAuditLogger

func WithAuditLogger(engine *Engine, logger AuditLogger) *Engine

WithAuditLogger sets a custom audit logger

func WithHasher

func WithHasher(engine *Engine, hasher Hasher) *Engine

WithHasher sets a custom password hasher

func WithJWTSecret

func WithJWTSecret(engine *Engine, secret string) *Engine

WithJWTSecret sets a custom JWT secret

func WithRateLimiter

func WithRateLimiter(engine *Engine, limiter RateLimiter) *Engine

WithRateLimiter sets a custom rate limiter

func WithSQLite

func WithSQLite(dbPath string) (*Engine, error)

WithSQLite creates an engine with persistent SQLite storage

type Hasher

type Hasher = core.Hasher

type LimitResult

type LimitResult = core.LimitResult

type RateLimiter

type RateLimiter = core.RateLimiter

type Session

type Session = core.Session

func ListSessions

func ListSessions(ctx context.Context, engine *Engine, userID string) ([]Session, error)

ListSessions returns all active sessions for a user

type SessionStore

type SessionStore = core.SessionStore

type TokenPair

type TokenPair = core.TokenPair

func RefreshToken

func RefreshToken(ctx context.Context, engine *Engine, refreshToken string) (*TokenPair, error)

RefreshToken issues new tokens and rotates the refresh token

type User

type User = core.User

func GetUser

func GetUser(ctx context.Context, engine *Engine, userID string) (*User, error)

GetUser retrieves a user by ID

func GetUserByEmail

func GetUserByEmail(ctx context.Context, engine *Engine, email string) (*User, error)

GetUserByEmail retrieves a user by email

func SignUp

func SignUp(ctx context.Context, engine *Engine, email, password string) (*User, error)

SignUp creates a new user account

type UserStore

type UserStore = core.UserStore

Interfaces