Skip to content
GlyndorPublic

About

Authentication library for Go: Argon2id passwords, EdDSA JWTs with refresh rotation, API keys, TOTP, field encryption and OIDC/OAuth2 social login. Runs in your process; no database or framework required.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

495 Commits

Folders and files

Repository files navigation

authcore

Authentication library for Go: Argon2id password hashing, EdDSA access and refresh tokens with rotation, opaque API keys, TOTP, single-use reset and activation tokens, column encryption with a blind index, OIDC and OAuth2 social login, and email and username validation. It runs in your process and needs no database or framework.

CI Go Reference

flowchart LR
    App["Your app"] -->|init once| Core["authcore"]
    Core -->|loads or generates| Keys[("Ed25519 key + HMAC secret<br/>in KeysDir")]
    Core -->|Provider| M["password, jwt, apikey, oauth,<br/>email, username, totp,<br/>credential, field"]
    M -->|hash, sign, verify| App
Loading

authcore ships no HTTP server of its own; you wire the modules into your own stack.

Modules

Each module is an independent package that takes the Provider and is usable on its own.

Module Does
🔑 password Hash + verify. Argon2id, policy-enforced, self-describing PHC format.
🎫 jwt Access + refresh tokens. EdDSA / Ed25519, generic claims, refresh rotation, optional revocation through a denylist you implement.
📧 email Validate + normalize. RFC 5321/5322, optional cached DNS MX check.
👤 username Validate + normalize. Reserved-name blocklist, character rules.
🗝️ apikey Opaque API keys. Generate, keyed-hash for storage, constant-time verify.
🔐 totp TOTP / RFC 6238 second factor. Enroll, verify, recovery codes; replay protection through a step recorder you implement.
✉️ credential Tokens for password reset and account activation. Bound to a purpose and a subject, TTL enforced; your store makes them single-use.
🛡️ field Column encryption. AES-256-GCM plus an HMAC blind index, so a value stays searchable by equality without being readable.
🌐 oauth Social login: Google, Apple, Microsoft, Vercel (OIDC) and GitHub, Discord (OAuth2). Auth Code + PKCE, ID-token validation or userinfo.

Install

go get github.com/Glyndor/authcore

Requires Go 1.26.10+. On first run authcore writes an Ed25519 signing key and an HMAC refresh secret to KeysDir (default .authcore/); in production, point it at a mounted volume or provision the keys once with authcore-keygen. See Key management and Containers.

Quick start

// One-time setup at startup. Keys are created on first run.
auth, _ := authcore.New(authcore.DefaultConfig())

pwd, _    := password.New(auth)                          // Argon2id, OWASP defaults
tokens, _ := jwt.New[UserClaims](auth, jwt.DefaultConfig())

// Register: store only the hash, never the plaintext.
hash, err := pwd.Hash("Str0ng-P@ssword!")                // errors.Is(err, password.ErrWeakPassword) on a policy failure

// Log in: verify, then mint an access + refresh pair.
if ok, _ := pwd.Verify("Str0ng-P@ssword!", hash); ok {
    pair, _ := tokens.CreateTokens(userID, UserClaims{Role: "admin"})
    // pair.AccessToken      → Authorization: Bearer …
    // pair.RefreshTokenHash → store server-side (never the raw token)
    // pair.SessionID        → UUID v7, use as your session PK
}

Tip

Full, runnable versions live in examples/: cd examples/modules/jwt && go run .. Wiring into a real HTTP stack: Fiber, Gin.

Sign-in providers

Provider Protocol Build it with
Google OIDC oauth.Google()
Apple OIDC oauth.Apple() with oauth.AppleClientSecret
Microsoft (Azure AD) OIDC oauth.Microsoft(tenantID), or a multi-tenant Provider
GitHub OAuth2 oauth.GitHub()
Discord OAuth2 oauth.Discord()
Vercel OIDC oauth.Vercel()
Any other OIDC provider (Okta, Auth0, GitLab, Keycloak, …) OIDC oauth.Discover(ctx, issuer, nil)

Plain OAuth2 providers without OIDC take a hand-built Provider; see OIDC login.

Docs

Group Links
Start here Secure login recipe, Configuration, FAQ
Operations Key management, Containers, Testing & modules, Migrating from bcrypt
Reference Errors, Email & username validation, Versioning, pkg.go.dev

License

MIT. Report vulnerabilities privately via the Security tab, never in a public issue.

About

Authentication library for Go: Argon2id passwords, EdDSA JWTs with refresh rotation, API keys, TOTP, field encryption and OIDC/OAuth2 social login. Runs in your process; no database or framework required.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Used by

Contributors

Languages