Documentation
¶
Overview ¶
Package auth provides the core data layer for Aegis authentication system. It defines the fundamental storage interfaces and models for users, accounts, sessions, and verification tokens that form the foundation of authentication.
The package follows a repository pattern with four primary storage interfaces:
- UserStore: Core user identity management
- AccountStore: Provider-specific account linking (OAuth, email/password, etc.)
- VerificationStore: Temporary tokens for email verification, password reset, etc.
- SessionStore: Active user session tracking with token management
A default SQL-based implementation using sqlc is provided, but consumers can supply custom implementations for any store to integrate with different backends.
Example usage:
auth := auth.New(auth.Config{
DB: db, // Uses default SQL stores for all operations
})
// Or with custom stores:
auth := auth.New(auth.Config{
DB: db,
UserStore: myCustomUserStore, // Custom implementation
// Other stores fall back to defaults
})
Package auth provides schema export functionality for different database dialects. The actual SQL schemas are embedded from internal files and can be accessed programmatically for documentation, CLI tools, or custom migration systems.
This allows users to access the core authentication schema definitions without needing to extract them from binary builds.
Index ¶
Constants ¶
const ( // DialectPostgres is for PostgreSQL databases (>=9.6 recommended) DialectPostgres = authtypes.DialectPostgres // DialectMySQL is for MySQL databases (>=5.7 or MariaDB >=10.2) DialectMySQL = authtypes.DialectMySQL // DialectSQLite is for SQLite databases DialectSQLite = authtypes.DialectSQLite )
Variables ¶
This section is empty.
Functions ¶
func PackageName ¶
func PackageName() string
PackageName returns the package identifier for the auth schema. This is used by the CLI schema export tool.
Types ¶
type Account ¶
Account represents a provider-specific authentication account linked to a User. One user may have multiple Accounts — one per provider (e.g., email/password, Google, GitHub). Each Account stores the provider name, provider-assigned user ID, credential or token data, and optional expiry information.
type AccountStore ¶
type AccountStore = authtypes.AccountStore
AccountStore defines the persistence interface for Account records: create, fetch by ID, by user ID, and by provider+providerAccountID, update, and delete. Implement this to manage provider-linked accounts in a custom store.
type Auth ¶
type Auth struct {
// contains filtered or unexported fields
}
Auth represents the core authentication system and provides access to all configured storage backends. It acts as a central registry for user, account, session, and verification data operations.
Auth is safe for concurrent use and should be initialized once at application startup and shared across the application.
func New ¶
New creates a new Auth instance with the provided configuration. For any store that is nil in the Config, a default SQL-based implementation is automatically created using the provided database connection.
Returns an error if DB is nil and any store is also nil, since default stores cannot be created without a database connection.
func (*Auth) AccountStore ¶
func (a *Auth) AccountStore() AccountStore
AccountStore returns the configured account store implementation. Use this to manage provider-specific account associations and credentials.
func (*Auth) SessionStore ¶
func (a *Auth) SessionStore() SessionStore
SessionStore returns the configured session store implementation. Use this to manage active user sessions, including token-based and refresh token authentication flows.
func (*Auth) UserStore ¶
UserStore returns the configured user store implementation. Use this to perform CRUD operations on user identities.
func (*Auth) VerificationStore ¶
func (a *Auth) VerificationStore() VerificationStore
VerificationStore returns the configured verification store implementation. Use this to manage temporary verification tokens for email confirmation, password resets, OTP codes, and other time-limited verification flows.
type Config ¶
type Config struct {
// DB is the SQL database connection used for default store implementations.
// Required if any store field is left nil.
DB *sql.DB
// Dialect selects which sqlc-generated code is used for the default stores.
// Defaults to DialectPostgres when not set.
Dialect Dialect
// UserStore handles user identity storage operations.
// If nil, uses default SQL implementation.
UserStore UserStore
// AccountStore manages provider-linked accounts (OAuth, credentials, etc.).
// If nil, uses default SQL implementation.
AccountStore AccountStore
// VerificationStore manages temporary verification tokens.
// If nil, uses default SQL implementation.
VerificationStore VerificationStore
// SessionStore handles active session persistence.
// If nil, uses default SQL implementation.
SessionStore SessionStore
}
Config holds the configuration for the auth system. Only the User model is generic.
If any store is nil, the default SQL-based implementation will be used automatically using the provided DB connection. This allows mixing custom and default stores as needed.
type Dependency ¶
type Dependency struct {
// Package is the Go import path of the dependency
Package string
// Version is the minimum required version of the dependency
Version int
}
Dependency represents a schema dependency on another package.
type Migration ¶
type Migration struct {
// Version is the numeric migration version (e.g., 1, 2, 3).
Version int
// Description is a human-readable summary of what this migration does
// (e.g., "initial", "add_user_roles", "alter_session_index").
Description string
// Up is the SQL to apply this migration (create tables, add columns, etc.).
Up string
// Down is the SQL to revert this migration (drop tables, remove columns, etc.).
Down string
}
Migration represents a versioned database schema change. Each migration has both an "up" script (to apply the change) and a "down" script (to revert it), enabling bidirectional schema evolution.
func GetMigrations ¶
GetMigrations returns all migrations for the specified database dialect in version order.
Migration versioning:
- Version 001+: All migrations from migrations/<dialect>/*.sql
Migration file naming convention:
<version>_<description>.<up|down>.sql
Examples:
001_initial.up.sql - Initial schema migration 001_initial.down.sql - Revert initial schema 002_add_user_roles.up.sql - Applies migration 002 002_add_user_roles.down.sql - Reverts migration 002 003_alter_sessions.up.sql - Applies migration 003
Each migration version must have both .up.sql and .down.sql files. Migrations are returned sorted by version number for sequential application.
Parameters:
- dialect: The database dialect (postgres, mysql, sqlite)
Returns:
- Slice of migrations sorted by version
- Error if the dialect is not supported or if migration files are malformed
type Schema ¶
type Schema struct {
// Dialect identifies the database type (postgres, mysql, sqlite)
Dialect Dialect
// SQL is the complete schema definition in SQL
SQL string
// Info contains metadata about the schema package
Info SchemaInfo
}
Schema represents the complete SQL schema for a specific database dialect.
func GetSchema ¶
GetSchema returns the complete SQL schema definition for the specified dialect.
This is useful for:
- Generating documentation
- Initializing new databases
- Comparing schemas across dialects
- Custom migration tooling
The returned Schema includes both the raw SQL and metadata about the schema package.
Example:
schema, err := auth.GetSchema(auth.DialectPostgres)
if err != nil {
log.Fatal(err)
}
fmt.Println(schema.SQL) // Prints the full PostgreSQL schema
type SchemaInfo ¶
type SchemaInfo struct {
// Package is the Go import path for this schema
Package string
// Version is the schema version number (currently unused, always 0)
Version int
// Description is a human-readable summary of the schema
Description string
// Dependencies lists other schema packages this schema depends on
Dependencies []Dependency
}
SchemaInfo contains metadata about a schema package. This can be used for dependency tracking and versioning in complex systems.
type Session ¶
Session represents an authenticated user session. It holds a session token, an optional refresh token, an expiry time, and optional metadata such as the client IP address and user-agent string.
type SessionStore ¶
type SessionStore = authtypes.SessionStore
SessionStore defines the persistence interface for Session records: create, fetch by ID, token, and refresh token, list by user ID, delete, and clean up expired sessions. Implement this to manage sessions in a custom store.
type User ¶
User is the core Aegis user identity model. It holds the user's unique ID, display Name, Email, Avatar URL, Disabled status, extensible Metadata, and CreatedAt/UpdatedAt timestamps. A user may have multiple linked Accounts, one per authentication provider.
type UserStore ¶
UserStore defines the persistence interface for User records: create, fetch by ID and email, update, soft-delete, paginated list, and count. Implement this interface to replace the built-in SQL store with a custom backend.
type Verification ¶
type Verification = authtypes.Verification
Verification is a time-limited token used for email verification, password reset, OTP delivery, and other flows that require confirming an identifier before proceeding. Tokens are scoped by Identifier, Type, and ExpiresAt.
type VerificationStore ¶
type VerificationStore = authtypes.VerificationStore
VerificationStore defines the persistence interface for Verification tokens: create, lookup by token, list by identifier, invalidate, delete, and clean up expired tokens. Used by email verification, password reset, and OTP flows.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package defaultstore implements the SQL-backed default store for the Aegis authentication module.
|
Package defaultstore implements the SQL-backed default store for the Aegis authentication module. |
|
internal
|
|
|
Package types defines the core domain models, interfaces, and types for the Aegis authentication module.
|
Package types defines the core domain models, interfaces, and types for the Aegis authentication module. |