{"id":51923688,"url":"https://github.com/mrf1ow/go-core","last_synced_at":"2026-07-27T22:00:27.804Z","repository":{"id":356763066,"uuid":"1200761096","full_name":"MrF1ow/go-core","owner":"MrF1ow","description":"Multi-tenant authentication \u0026 authorization Go module - JWT, OAuth2, WebAuthn/passkeys, magic links, OIDC provider,   RBAC, 2FA, and an HTMX admin GUI. Import as a library, not a standalone service.","archived":false,"fork":false,"pushed_at":"2026-06-08T20:14:34.000Z","size":1185,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-25T17:20:48.355Z","etag":null,"topics":["authentication","authorization","gin","go-module","golang","htmx","jwt","magic-link","multi-tenant","oath2","oidc","passkeys","postgresql","rbac","redis","two-factor-authentication","webauthn"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MrF1ow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-03T19:49:59.000Z","updated_at":"2026-06-08T20:15:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MrF1ow/go-core","commit_stats":null,"previous_names":["mrf1ow/go-core"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MrF1ow/go-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrF1ow%2Fgo-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrF1ow%2Fgo-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrF1ow%2Fgo-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrF1ow%2Fgo-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MrF1ow","download_url":"https://codeload.github.com/MrF1ow/go-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrF1ow%2Fgo-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35966479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-27T02:00:06.776Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authorization","gin","go-module","golang","htmx","jwt","magic-link","multi-tenant","oath2","oidc","passkeys","postgresql","rbac","redis","two-factor-authentication","webauthn"],"created_at":"2026-07-27T22:00:22.825Z","updated_at":"2026-07-27T22:00:27.790Z","avatar_url":"https://github.com/MrF1ow.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-core\n\nA multi-tenant authentication and authorization module for Go. Built on Gin, PostgreSQL (pgx/SQLC), and Redis, it handles JWT auth, OAuth2 social login, WebAuthn/passkeys, magic links, two-factor authentication, RBAC, an OIDC provider, webhooks, brute-force protection, GeoIP rules, session groups for cross-app SSO, and an embedded HTMX admin GUI. Drop it into your backend and skip building auth from scratch.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\n\t\"github.com/gin-gonic/gin\"\n\n\tcore \"github.com/MrF1ow/go-core\"\n\t\"github.com/MrF1ow/go-core/app\"\n)\n\nfunc main() {\n\tcfg := core.DefaultConfig()\n\tcfg.Database.Host = \"localhost\"\n\tcfg.Database.Port = 5432\n\tcfg.Database.DBName = \"myapp\"\n\tcfg.Database.User = \"postgres\"\n\tcfg.Database.Password = \"secret\"\n\tcfg.JWT.Secret = \"your-secret-at-least-32-characters-long\"\n\n\tcoreApp, err := app.New(cfg)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer coreApp.Close()\n\n\tr := gin.Default()\n\tcoreApp.RegisterRoutes(r)\n\tr.Run(\":8080\")\n}\n```\n\nThat's it. You get registration, login, token refresh, password reset, email verification, 2FA, social login, and more out of the box.\n\n### Public API\n\n| Function | Description |\n|----------|-------------|\n| `app.New(cfg)` | Validates config, connects to Postgres, initializes all services |\n| `app.NewWithDB(cfg, pool)` | Same as `New` but reuses an existing `*pgxpool.Pool` |\n| `app.RegisterRoutes(r)` | Mounts all routes onto a Gin engine |\n| `app.AuthMiddleware()` | Returns a `gin.HandlerFunc` for protecting your own routes |\n| `app.Close()` | Shuts down background services and connection pool |\n\n## Required Config\n\nThese must be set or `app.New()` returns an error:\n\n| Field | Description |\n|-------|-------------|\n| `Database.Host` | PostgreSQL host |\n| `Database.Port` | PostgreSQL port (default: 5432) |\n| `Database.DBName` | Database name |\n| `Database.User` | Database user |\n| `Database.Password` | Database password (not validated, but you need it) |\n| `JWT.Secret` | Signing key for all access and refresh tokens. Minimum 32 characters. |\n\n## Optional Config\n\nEverything below is off or defaulted until you configure it. `DefaultConfig()` gives you sensible CORS defaults and reasonable token lifetimes.\n\n| Field | What it does | When unset |\n|-------|-------------|------------|\n| `Redis` | Redis connection for token blacklisting and sessions | Nil pointer = in-memory cache. Fine for dev, use Redis in production. |\n| `Email` | SMTP config for sending emails | Nil = email sending disabled. Magic links, 2FA email codes, and verification emails won't work. |\n| `CORS` | Cross-origin settings | Sensible defaults via `DefaultConfig()`. Override if needed. |\n| `OIDC` | OpenID Connect provider config | Disabled. |\n| `WebAuthn` | Passkey and biometric authentication | Disabled. |\n| `SMS` | 2FA via Twilio | Disabled. |\n| `Admin` | Admin GUI settings, API key, and [branding](web/README.md) | Disabled. |\n| `Social` | OAuth2 social login (Google, Facebook, GitHub) | Disabled. |\n| `GeoIP` | IP-based access rules, requires a MaxMind database file | Disabled. |\n| `Session` | Session groups, trusted devices, cross-app SSO settings | Defaults to single-app mode. |\n| `MultiTenant` | Enables multi-app mode with `X-App-ID` header | False. Single-app mode. |\n| `PublicURL` | Base URL for API links in emails and redirects | Empty. |\n| `FrontendURL` | Frontend app URL for redirect targets | Empty. |\n| `AppName` | Application name used in emails and admin GUI | Empty. |\n| `Port` | Server port for the reference `cmd/api` implementation | Empty. |\n| `GinMode` | Gin framework mode (`debug`, `release`, `test`) | Empty (Gin default). |\n\n## Features\n\n- JWT authentication (access + refresh tokens)\n- Registration, login, password reset, email verification\n- Magic link authentication\n- OAuth2 social login (Google, Facebook, GitHub)\n- WebAuthn / passkeys\n- Two-factor auth (TOTP, SMS, email, passkey)\n- Role-based access control (RBAC)\n- Multi-tenant with per-app configuration\n- HTMX admin GUI (embedded, no extra files needed)\n- OpenID Connect provider (auth code + PKCE)\n- Webhooks\n- Brute-force protection and account lockout\n- GeoIP-based access rules\n- Session groups (cross-app SSO)\n- Activity logging\n\n## Running the Example\n\nCheck out `examples/basic/main.go` for a working setup. You'll need PostgreSQL running with migrations applied.\n\n```bash\n# Start dependencies\nmake docker-dev\nmake migrate-up\n\n# Run the example\ngo run ./examples/basic\n```\n\n`make docker-dev` spins up PostgreSQL and Redis in Docker. `make migrate-up` applies the database schema.\n\n## Development\n\n```bash\nmake dev          # Hot reload dev server\nmake test         # Run all tests\nmake fmt          # Format code\nmake lint         # golangci-lint\nmake security     # gosec + govulncheck scans\nmake ci           # Run full CI pipeline (fmt, lint, test, security, build)\nmake build-prod   # Production binary\nmake setup-admin  # Create admin account for Admin GUI\nmake swag-init    # Regenerate Swagger docs after API changes\n```\n\n## Claude Code Skills\n\nThis project includes Claude Code skills for AI-assisted development. They live in `.claude/skills/go-core/` and cover:\n\n- **Project map** — architecture overview and key directories\n- **Route map** — all API endpoints and middleware\n- **Auth flows** — registration, login, token lifecycle, 2FA, OAuth2\n- **Data model** — database schema and SQLC query patterns\n- **Admin GUI** — HTMX admin interface structure\n- **Email system** — email templates and sending logic\n- **Security** — brute-force protection, GeoIP, CSRF, rate limiting\n- **New endpoint** — guide for adding new API endpoints\n- **Integration** — how to consume the module in your app\n- **Commits** — commit message conventions and scopes\n\nInvoke the hub skill with `/go-core` in Claude Code to get routed to the right reference.\n\n## Credits\n\nOriginally forked from [gjovanovicst/golang-auth-api](https://github.com/gjovanovicst/golang-auth-api). Significantly reworked into a consumable Go module — migrated from GORM to pgx/SQLC, embedded all assets, added a public API, and cleaned up the architecture.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrf1ow%2Fgo-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrf1ow%2Fgo-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrf1ow%2Fgo-core/lists"}