Menu
Complete module inventory of the Auth API project with file paths, dependencies, and architecture overview. Load this first in any new session.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Complete HTTP route structure with auth layers, middleware chains, rate limiting, and handler mappings for all API and GUI endpoints.
Documentation of the HTMX admin GUI including template rendering, session management, CRUD patterns, and the GUIHandler structure.
Detailed documentation of the 4 authentication systems, token lifecycle, middleware pipeline, session management, and RBAC authorization.
All 17 GORM database models with fields, relationships, indexes, and the entity relationship diagram for the Auth API.
Complete documentation of the email subsystem including template resolution, variable pipeline, rendering engines, SMTP config, and default templates.
| name | project-map |
| description | Complete module inventory of the Auth API project with file paths, dependencies, and architecture overview. Load this first in any new session. |
| license | MIT |
A multi-tenant authentication and authorization REST API in Go 1.23+, using Gin, PostgreSQL (GORM), and Redis. It provides user registration, login, OAuth2 social login, TOTP/email/SMS/backup-email 2FA, WebAuthn/passkeys, magic links, RBAC, session management, OIDC provider, webhooks, brute-force protection, GeoIP IP rules, health/metrics, and a full admin interface (JSON API + HTMX GUI).
Pattern: Repository -> Service -> Handler (Clean Architecture)
Key design decisions:
RoleLookupFunc, AssignDefaultRoleFunc)AppID (UUID), with default app 00000000-0000-0000-0000-000000000001cmd/api/main.go -- Dependency injection, route setup, server startupTenant/app CRUD, OAuth provider configuration, email management, API key management, admin account authentication, 2FA for admin accounts, system settings (env -> DB -> default resolution), dashboard stats, HTMX GUI handler.
| File | Purpose |
|---|---|
gui_handler.go | HTMX admin GUI (4976 lines, largest file) |
handler.go | Admin JSON REST API (1146 lines) |
repository.go | Data access for tenants, apps, OAuth, users, API keys, logs (952 lines) |
account_service.go | Admin auth, sessions, 2FA, CSRF, password ops |
account_repository.go | AdminAccount GORM queries |
dashboard_service.go | Dashboard stats aggregation (PostgreSQL + Redis) |
settings_service.go | System settings with 3-tier resolution (env > DB > default) |
settings_repository.go | SystemSetting GORM queries with upsert |
apikey_util.go | API key generation (SHA-256 hash, prefix/suffix) |
apikey_util_test.go | Tests for API key utilities |
account_service_test.go | Tests for admin account service |
Registration, login (with self-healing role assignment), password reset, magic link auth, email change with verification, profile management.
| File | Purpose |
|---|---|
handler.go | User HTTP handlers |
service.go | User business logic |
repository.go | User GORM queries |
handler_test.go | Handler tests |
service_test.go | Service tests |
Google, Facebook, GitHub OAuth2 flows. Supports account linking and direct social login/registration.
| File | Purpose |
|---|---|
handler.go | OAuth2 HTTP handlers (login, callback, link) |
service.go | OAuth2 business logic |
repository.go | SocialAccount GORM queries |
oauth_state.go | OAuth state parameter encoding (appID, provider, action, HMAC) |
TOTP (authenticator apps), email-based 2FA codes, SMS 2FA (Twilio), backup email 2FA, recovery codes, trusted devices.
| File | Purpose |
|---|---|
handler.go | 2FA HTTP handlers (TOTP, email, SMS, backup email, trusted devices, phone management) |
service.go | 2FA business logic (TOTP + email + SMS + backup email codes, trusted device validation) |
trusted_device_repository.go | TrustedDevice GORM queries |
Full WebAuthn support for users and admin accounts.
| File | Purpose |
|---|---|
handler.go | Passkey HTTP handlers |
service.go | WebAuthn ceremony logic |
repository.go | WebAuthnCredential GORM queries |
config.go | Relying party configuration |
user_adapter.go | Adapts User/AdminAccount to WebAuthn user interface |
Redis-backed sessions with refresh token rotation, multi-device tracking.
| File | Purpose |
|---|---|
service.go | Session lifecycle (create, refresh, revoke, list) |
handler.go | Session API endpoints |
Roles per-application, permissions as resource:action, Redis-cached authorization.
| File | Purpose |
|---|---|
service.go | RBAC logic with Redis caching |
repository.go | Role/Permission/UserRole GORM queries |
handler.go | RBAC API endpoints |
Multi-layered email system: Service -> VariableResolver + Renderer + Sender.
| File | Purpose |
|---|---|
service.go | Orchestrator (send pipeline, template/SMTP resolution) |
resolver.go | Variable resolution pipeline (4 layers) |
renderer.go | Three template engines (go_template, placeholder, raw_html) |
sender.go | SMTP sending via gopkg.in/mail.v2 |
types.go | Constants, structs, variable registry |
defaults.go | 7 hardcoded default email templates |
repository.go | Email types, templates, server configs GORM queries |
email_integration_test.go | Integration tests |
Async channel-based logging with anomaly detection.
| File | Purpose |
|---|---|
service.go | Async log service (buffered channel, background worker) |
anomaly.go | Anomaly detection (new IP, new UA, unusual time) |
cleanup.go | Scheduled log retention/cleanup |
query_service.go | Filtered, paginated log querying |
handler.go | Log API endpoints |
repository.go | ActivityLog GORM queries |
| File | Purpose |
|---|---|
auth.go | JWT auth + token blacklist checking |
admin_auth.go | Admin API Key auth (static env + DB-backed) |
app_api_key.go | Per-app API Key auth |
gui_auth.go | Admin GUI cookie session auth |
csrf.go | CSRF protection for GUI |
app_id.go | X-App-ID header extraction |
app_route_guard.go | Cross-app URL parameter validation |
rate_limit.go | Redis + in-memory fallback rate limiting |
cors.go | CORS configuration |
security_headers.go | CSP, HSTS, X-Frame-Options |
auth_test.go | Auth middleware tests |
rate_limit_test.go | Rate limit tests |
security_headers_test.go | Security header tests |
| Package | File | Purpose |
|---|---|---|
internal/oidc/ | 7 files | Full OIDC provider: discovery, authorize, token, userinfo, introspect, revoke, end_session, JWKS, RS256 id_token signing |
internal/webhook/ | 3 files | Webhook endpoint registry, async delivery dispatcher, retry queue, HMAC-SHA256 signing |
internal/bruteforce/ | 2 files | Account lockout, progressive login delays, CAPTCHA trigger threshold |
internal/geoip/ | 3 files | MaxMind GeoLite2 service, IP rule repository, IP rule evaluator (CIDR/country per app) |
internal/health/ | 1 file | GET /health liveness, GET /metrics Prometheus, PrometheusMiddleware, MetricsSummary |
internal/sms/ | 3 files | SMS sender interface, Twilio implementation, config loader |
internal/database/ | db.go | PostgreSQL connection + GORM auto-migration |
internal/redis/ | redis.go | Redis connection + token blacklisting + session helpers |
internal/config/ | logging.go | Logging configuration |
internal/util/ | client_info.go, frontend_url.go | Client info extraction, frontend URL resolution |
| Package | Files | Purpose |
|---|---|---|
pkg/models/ | 17+ model files | GORM models: User, Tenant, Application, Role, Permission, UserRole, AdminAccount, SocialAccount, WebAuthnCredential, ActivityLog, ApiKey, ApiKeyUsage, EmailType, EmailTemplate, EmailServerConfig, OAuthProviderConfig, SystemSetting, SchemaMigration, OIDCClient, OIDCAuthCode, WebhookEndpoint, WebhookDelivery, IPRule, TrustedDevice |
pkg/dto/ | 7+ files | Request/response DTOs: auth, admin, session, RBAC, WebAuthn, email, activity_log, oidc, webhook, geoip |
pkg/errors/ | errors.go, errors_test.go | AppError type with 6 HTTP status code mappings |
pkg/jwt/ | jwt.go, jwt_test.go | JWT Claims (UserID, AppID, SessionID, TokenType, Roles), generate/parse |
| File | Purpose |
|---|---|
renderer.go | HTML template renderer (embedded templates, funcMap) |
context_keys.go | Shared context keys, SessionValidator/ApiKeyValidator interfaces, cookie helpers |
static/embed.go | Embedded static files (CSS/JS) |
main.go wires everything:
user.Service depends on: user.Repository, email.Service, rbac.Service (via callbacks), session.Service, webhook.Service, sms.Sender
social.Service depends on: user.Repository, social.Repository, rbac.Service (via callbacks), session.Service, webhook.Service
twofa.Service depends on: user.Repository, email.Service, sms.Sender, trusted_device.Repository
twofa.Handler depends on: rbac.Service (via callbacks), session.Service, trusted_device.Repository
webauthn.Service depends on: webauthn.Repository, user.Repository
webauthn.Handler depends on: rbac.Service (via callbacks), session.Service, webhook.Service
oidc.Service depends on: oidc.Repository, rbac.Service (GetUserRoleNames)
webhook.Service depends on: webhook.Repository
bruteforce.Service depends on: database.DB (Redis-less, PostgreSQL counters)
geoip.IPRuleEvaluator depends on: geoip.IPRuleRepository, geoip.Service
health.Handler depends on: database.DB, redis.Rdb, SMTP address
rbac.Service depends on: rbac.Repository
session.Service depends on: Redis
email.Service depends on: email.Repository, VariableResolver, Renderer, Sender
log.Service depends on: log.Repository, AnomalyDetector
admin.Handler depends on: admin.Repository, email.Service, trusted_device.Repository
admin.GUIHandler depends on: AccountService, DashboardService, admin.Repository, SettingsService, email.Service, rbac.Service, webauthn.Service, webhook.Service, oidc.Service, health.Handler, trusted_device.Repository
Load this skill at the start of any session to understand the project structure. For domain-specific deep dives, also load the relevant skill: route-map, data-model, auth-flows, email-system, or admin-gui.