authkit

README

goravel-authkit

Batteries-included, session-based authentication + user management for Goravel apps. Install it, register the provider, configure it — and it publishes the API routes, database migrations, the User model, and (optionally) the admin user-management endpoints for you.

Inspired by jeremykenedy/laravel-auth, adapted to Go/Goravel idioms (static typing, code-based migrations, generated SDK contracts). The React/PatternFly frontend counterpart lives in @freshost/auth-ui.

Status: v1 in development. v1 covers the core that real projects already ship: login/logout/session, change-password with other-session invalidation, login rate-limiting, admin user-management CRUD, an audit log, and TOTP two-factor. Later phases: self-registration, email verification, password reset by email, RBAC.

What v1 gives you

Endpoint	Description
POST /auth/login	Session login (rate-limited), bcrypt verification
POST /auth/logout	Destroys the session
GET /auth/me	Current authenticated user
PUT /auth/password	Change password (invalidates other sessions)
POST /auth/two-factor …	TOTP enroll / confirm / disable / recovery-codes (toggleable)
POST /auth/two-factor-challenge	Complete a 2FA login
GET/POST/PUT/DELETE /users	Admin user management (toggleable)
POST /users/{id}/password	Admin set-password

Plus: session-fixation protection, password_changed_at multi-session invalidation, TOTP two-factor (encrypted secret + single-use recovery codes), an audit_logs table + writer, and an auth:create-user artisan command for bootstrapping the first admin.

Documentation

• Installation — full wiring (provider, config, migrations, routes, first admin, SDK).
• Configuration — authkit.* keys, feature toggles, the role gate.
• API reference — endpoints, request/response shapes, error codes, operation ids.
• Security model — guarantees, operator responsibilities, v1 limitations, audit actions.
• Architecture — layering, the canonical model, Goravel integration, the SDK contract loop.

Adopting into an existing app? There is a bundled agent skill at .claude/skills/adopt-goravel-authkit/ — copy it into your project's .claude/skills/ and an AI agent can perform the swap (including the admin_users → users data migration) step by step.

Install

Register the provider — that is the whole integration. The provider registers the migrations, routes, and artisan commands itself.

go get github.com/freshost/goravel-authkit
./artisan package:install github.com/freshost/goravel-authkit
./artisan migrate
./artisan auth:create-user --email=admin@example.com --password=change-me

package:install makes four small, additive edits to your app:

1. registers authkit.ServiceProvider in bootstrap/providers.go;
2. writes config/authkit.go (the package's own settings file);
3. adds a session admin guard + users orm provider into your existing config/auth.go (your other guards are left untouched);
4. sets bcrypt cost 12 in your existing config/hashing.go.

You don't append migrations or register routes by hand — the provider does it at boot.

Existing auth already? The install is additive, but if your app already has an admin guard, a users table, or its own login code, follow the adoption skill (reconcile the guard, migrate admin_users → users) instead of the plain install.

For local development before the repo is public, add a replace directive (replace github.com/freshost/goravel-authkit => ../goravel-authkit) and register the provider manually (&authkit.ServiceProvider{} in bootstrap/providers.go).

Configuration

Everything is tuned through the config/authkit.go file that package:install writes (all keys optional — the package falls back to safe defaults). The you consume the package only by registering the provider — there is no Go wiring to do.

Key	Type	Default	Meaning
authkit.route_prefix	string	/api/v1	Prefix for all routes
authkit.guard	string	admin	Goravel session guard name
authkit.min_password_length	int	8	Minimum new-password length
authkit.rate_limit.attempts	int	5	Login attempts per window per IP
authkit.rate_limit.window	int	60	Rate-limit window (seconds)
authkit.features.user_management	bool	true	Register /users CRUD
authkit.features.audit_log	bool	true	Write audit entries
authkit.features.two_factor	bool	true	Register TOTP two-factor endpoints + login gate
authkit.two_factor.issuer	string	""	Authenticator issuer (empty = app name)
authkit.two_factor.recovery_codes	int	8	Recovery codes per confirmation
authkit.user_management_roles	[]string	[]	Roles allowed on /users (empty = any)

See docs/configuration.md for details.

Programmatic API (facade)

Besides the HTTP endpoints, the package exposes a facade so your own Go code (seeders, installers, custom commands, domain logic) can drive auth/users without HTTP:

import authfacades "github.com/freshost/goravel-authkit/facades"

user, err := authfacades.Authkit().CreateUser(ctx, "jane@example.com", "Jane", "secret123", "admin")
user, err := authfacades.Authkit().Authenticate(ctx, email, password)
err := authfacades.Authkit().ChangePassword(ctx, id, current, next)

// two-factor
secret, url, err := authfacades.Authkit().EnableTwoFactor(ctx, id)
codes, err := authfacades.Authkit().ConfirmTwoFactor(ctx, id, "123456")

See contracts/authkit.go for the full interface.

Security notes (read before deploying)

• Hashing is bcrypt cost 12. package:install writes config/hashing.go with bcrypt cost 12 (what existing $2a$12$ hashes verify against). Keep it that way — the package hashes via the Goravel Hash facade.
• Configure trusted proxies. The login rate-limiter and the audit log key on ctx.Request().Ip(), which honours X-Forwarded-For. Behind a proxy/CDN, set Goravel's http.trusted_proxies or the limit is bypassable (and audit IPs are spoofable) by sending a forged header.
• No RBAC in v1. The /users management endpoints sit behind the session guard only — every authenticated user can manage users. Once your app assigns roles, gate them with authkit.user_management_roles (e.g. []string{"admin"}), which adds a RequireRole check. True RBAC (roles/permissions tables) is a later phase.
• Sessions use httpOnly cookies with session-id regeneration on login (anti-fixation) and password_changed_at multi-session invalidation. Set session.same_site to lax or strict and session.secure=true in production.

License

MIT © Freshost

Documentation

Overview

Package authkit is the root of the goravel-authkit package: a batteries-included, session-based authentication + user-management module for Goravel apps.

Install is a single step:

./artisan package:install github.com/freshost/goravel-authkit

which registers this ServiceProvider and writes the config files (config/auth.go, config/authkit.go, config/hashing.go). The provider registers the migrations and the artisan commands itself; the app mounts the HTTP routes from its own routing callback with one line:

authkitroutes "github.com/freshost/goravel-authkit/routes"
// inside foundation.Setup().WithRouting(func(){ ... })
authkitroutes.Register(facades.Route(), authkitroutes.OptionsFromConfig())

Routes are registered app-side (not in the provider) because Goravel rebuilds the HTTP engine when global middleware is set — which happens AFTER providers boot — so any routes a provider registers in Boot are discarded. The routing callback runs after that rebuild, so routes registered there survive. The app must also enable session middleware globally (the package is cookie-based):

WithMiddleware(func(h configuration.Middleware){ h.Append(sessionmiddleware.StartSession()) })

See the README and docs/installation.md.

Index

• Constants
• Variables
• type Authkit
  • func NewAuthkit(app foundation.Application) *Authkit
  • func (a *Authkit) Authenticate(ctx context.Context, email, password string) (*models.User, error)
  • func (a *Authkit) ChangePassword(ctx context.Context, id uuid.UUID, currentPassword, newPassword string) error
  • func (a *Authkit) ConfirmTwoFactor(ctx context.Context, id uuid.UUID, code string) ([]string, error)
  • func (a *Authkit) CreateUser(ctx context.Context, email, name, password, role string) (*models.User, error)
  • func (a *Authkit) DeleteUser(ctx context.Context, id uuid.UUID) error
  • func (a *Authkit) DisableTwoFactor(ctx context.Context, id uuid.UUID) error
  • func (a *Authkit) EnableTwoFactor(ctx context.Context, id uuid.UUID) (secret, otpauthURL string, err error)
  • func (a *Authkit) GetUser(ctx context.Context, id uuid.UUID) (*models.User, error)
  • func (a *Authkit) ListUsers(ctx context.Context) ([]models.User, error)
  • func (a *Authkit) SetPassword(ctx context.Context, id uuid.UUID, newPassword string) (*models.User, error)
  • func (a *Authkit) VerifyTwoFactor(ctx context.Context, id uuid.UUID, code string) (bool, error)
• type ServiceProvider
  • func (r *ServiceProvider) Boot(app foundation.Application)
  • func (r *ServiceProvider) Register(app foundation.Application)
  • func (r *ServiceProvider) Relationship() binding.Relationship

Constants

const Binding = "authkit"

Binding is the service-container key under which the Authkit service is bound; the facades.Authkit() accessor resolves it.

const Name = "Authkit"

Name is the human-readable module name.

const PackageName = "github.com/freshost/goravel-authkit"

PackageName is the module path, used as the first argument to Publishes.

Variables

var App foundation.Application

App holds the application instance, used by the facade to resolve the service.

Types

type Authkit

type Authkit struct {
	// contains filtered or unexported fields
}

Authkit is the concrete implementation behind facades.Authkit(). It wraps the auth + user-management + two-factor services so app code can drive them programmatically.

func NewAuthkit

func NewAuthkit(app foundation.Application) *Authkit

NewAuthkit builds the service from the application (read lazily at resolve time, so config is available).

func (*Authkit) Authenticate

func (a *Authkit) Authenticate(ctx context.Context, email, password string) (*models.User, error)

func (*Authkit) ChangePassword

func (a *Authkit) ChangePassword(ctx context.Context, id uuid.UUID, currentPassword, newPassword string) error

func (*Authkit) ConfirmTwoFactor

func (a *Authkit) ConfirmTwoFactor(ctx context.Context, id uuid.UUID, code string) ([]string, error)

func (*Authkit) CreateUser

func (a *Authkit) CreateUser(ctx context.Context, email, name, password, role string) (*models.User, error)

func (*Authkit) DeleteUser

func (a *Authkit) DeleteUser(ctx context.Context, id uuid.UUID) error

func (*Authkit) DisableTwoFactor

func (a *Authkit) DisableTwoFactor(ctx context.Context, id uuid.UUID) error

func (*Authkit) EnableTwoFactor

func (a *Authkit) EnableTwoFactor(ctx context.Context, id uuid.UUID) (secret, otpauthURL string, err error)

func (*Authkit) GetUser

func (a *Authkit) GetUser(ctx context.Context, id uuid.UUID) (*models.User, error)

func (*Authkit) ListUsers

func (a *Authkit) ListUsers(ctx context.Context) ([]models.User, error)

func (*Authkit) SetPassword

func (a *Authkit) SetPassword(ctx context.Context, id uuid.UUID, newPassword string) (*models.User, error)

func (*Authkit) VerifyTwoFactor

func (a *Authkit) VerifyTwoFactor(ctx context.Context, id uuid.UUID, code string) (bool, error)

type ServiceProvider

type ServiceProvider struct{}

ServiceProvider registers the goravel-authkit migrations, commands, and publishable config. HTTP routes are mounted app-side via routes.Register (see the package doc) because provider-registered routes do not survive the engine rebuild that global middleware triggers.

func (*ServiceProvider) Boot

func (r *ServiceProvider) Boot(app foundation.Application)

Boot registers the package migrations, artisan commands, and the publishable config (for `vendor:publish`). HTTP routes are NOT registered here — the app calls routes.Register from its routing callback (see the package doc).

func (*ServiceProvider) Register

func (r *ServiceProvider) Register(app foundation.Application)

Register stores the application instance and binds the Authkit service so facades.Authkit() (and any app code) can resolve it.

func (*ServiceProvider) Relationship

func (r *ServiceProvider) Relationship() binding.Relationship

Relationship declares the framework services the package depends on so it boots after them. It registers no container bindings of its own.