Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Engine (authsome.Engine)                          │
│                                                                             │
│  SignUp / SignIn / SignOut / Refresh / GetMe / UpdateMe                     │
│  ForgotPassword / ResetPassword / ChangePassword / VerifyEmail              │
│  Impersonate / RBAC / Webhooks / Devices / Environments                     │
├──────────────────────────┬──────────────────────────────────────────────────┤
│        Plugin System     │        Strategy Registry                         │
│                          │                                                  │
│  plugin.Registry         │  strategy.Registry                               │
│  BeforeSignUp            │    password strategy (priority 10)               │
│  AfterSignUp             │    social strategy (priority 20)                 │
│  BeforeSignIn            │    passkey strategy (priority 30)                │
│  AfterSignIn             │    sso strategy (priority 40)                   │
│  BeforeSessionCreate     │    magiclink strategy (priority 50)              │
│  AfterUserDelete         │    phone strategy (priority 60)                  │
│  RouteProvider           │    (priority determines fallback order)          │
│  MigrationProvider       │                                                  │
├──────────────────────────┴──────────────────────────────────────────────────┤
│                          Hook Bus (hook.Bus)                                 │
│  40+ action types: ActionSignUp, ActionSignIn, ActionSignOut,               │
│  ActionRefresh, ActionUserUpdate, ActionSessionRevoke, ActionImpersonate,   │
│  ActionAdminBanUser, ActionRoleCreate, ActionEnvironmentCreate, ...         │
├─────────────────────────────────────────────────────────────────────────────┤
│                         Bridge Interfaces                                    │
│  Chronicle (audit) · Relay (webhooks) · Mailer · SMSSender · Herald        │
│  Warden (authz) · Keysmith (API keys) · Vault (secrets) · Dispatch (jobs)  │
│  Ledger (billing) · MetricsCollector                                        │
├──────────────────────────┬──────────────────────────────────────────────────┤
│       store.Store        │     Token Formats                                │
│  (composite interface)   │                                                  │
│  UserStore               │  tokenformat.Format interface                   │
│  SessionStore            │    Opaque (64-char hex, default)                 │
│  DeviceStore             │    JWT (OIDC claims, per-app)                    │
│  WebhookStore            │                                                  │
│  OrganizationStore       │                                                  │
│  EnvironmentStore        │                                                  │
│  RBACStore               │                                                  │
│  FormConfigStore         │                                                  │
├──────┬───────────────────┴──────────────────────────────────────────────────┤
│memory│  postgres  │  sqlite  │  mongo                                       │
└──────┴────────────┴──────────┴──────────────────────────────────────────────┘

import "github.com/xraph/authsome"

eng, err := authsome.New(
    authsome.WithStore(myStore),
    authsome.WithPlugin(passwordPlugin),
    authsome.WithWarden(wardenEngine),    // optional: Warden for RBAC
    authsome.WithChronicle(chronicle),    // optional: audit trail
    authsome.WithMailer(mailer),          // optional: transactional email
)

// Development: no external dependencies
store := memory.New()

// Production: PostgreSQL
store, err := postgres.New(ctx, "postgres://user:pass@host:5432/db")

// Alternative: SQLite for embedded applications
store, err := sqlite.New(ctx, "./auth.db")

// Alternative: MongoDB for document-oriented workloads
store, err := mongo.New(ctx, "mongodb://localhost:27017", "authdb")

// Base interface — all plugins must implement this.
type Plugin interface {
    Name() string
}

// Optional lifecycle interfaces a plugin may implement:
type OnInit interface {
    OnInit(ctx context.Context, e PluginEngine) error
}
type RouteProvider interface {
    RegisterRoutes(r forge.Router, e PluginEngine)
}
type MigrationProvider interface {
    Migrations(driver string) []migrate.Migration
}
type BeforeSignUp interface {
    OnBeforeSignUp(ctx context.Context, req *account.SignUpRequest) error
}
type AfterSignUp interface {
    OnAfterSignUp(ctx context.Context, u *user.User, sess *session.Session)
}
type BeforeSignIn interface {
    OnBeforeSignIn(ctx context.Context, req *account.SignInRequest) error
}
type AfterSignIn interface {
    OnAfterSignIn(ctx context.Context, u *user.User, sess *session.Session)
}
type AuthMethodContributor interface {
    AuthMethods() []AuthMethod
}

import "github.com/xraph/authsome/hook"

// Subscribe to sign-up events.
eng.Hooks().Subscribe(hook.ActionSignUp, func(ctx context.Context, event *hook.Event) {
    log.Printf("new signup: user=%s app=%s", event.ResourceID, event.Tenant)
})

import "github.com/xraph/authsome/strategy"

// Plugins register strategies through the plugin.AuthMethodContributor interface.
// You can also register strategies directly:
eng.RegisterStrategy(myStrategy, 5)

import (
    "github.com/xraph/authsome/bridge/chronicleadapter"
    "github.com/xraph/authsome/bridge/maileradapter"
    "github.com/xraph/authsome/bridge/smsadapter"
    "github.com/xraph/authsome/bridge/relayadapter"
)

// Chronicle: wrap a Chronicle engine
authsome.WithChronicle(chronicleadapter.New(chronicleEngine))

// Mailer: SMTP or Resend
authsome.WithMailer(maileradapter.NewSMTP(smtpConfig))
authsome.WithMailer(maileradapter.NewResend(resendAPIKey))

// SMS: Twilio
authsome.WithSMSSender(smsadapter.NewTwilio(twilioConfig))

// Relay: wrap a Relay engine
authsome.WithEventRelay(relayadapter.New(relayEngine))

import "github.com/xraph/authsome/extension"

// Register as a Forge extension (auto-wires store from DI container).
app.Register(extension.New(
    extension.WithPlugin(password.New()),
    extension.WithPlugin(social.New(socialCfg)),
))

import "github.com/xraph/authsome/middleware"

// Extract and validate Bearer token, inject user into context.
mux.Handle("/api/", middleware.RequireAuth(eng)(apiHandler))

// Require a specific permission (delegates to Warden if configured).
mux.Handle("/api/admin/", middleware.RequirePermission(eng, "admin", "users")(adminHandler))

// Apply per-endpoint rate limiting.
mux.Handle("/api/", middleware.RateLimit(eng)(apiHandler))

import "github.com/xraph/authsome/tokenformat"

// JWT format with RSA-256 signing key.
jwtFmt, err := tokenformat.NewJWT(tokenformat.JWTConfig{
    Algorithm:  "RS256",
    PrivateKey: rsaPrivateKey,
    PublicKey:  rsaPublicKey,
    Issuer:     "https://auth.myapp.com",
    Audience:   []string{"https://api.myapp.com"},
})

// Register JWT format for a specific app.
authsome.WithJWTFormat("myapp", jwtFmt)