🖼️AuthCore - Universal Authentication Engine — Screenshot 1 of 1
Click to Expand 🔍
Auth Module – The Universal Authentication Engine
The Auth Module (auth-engine) is a deeply decoupled, plug-and-play authentication engine. It works for simple single-role apps or complex multi-role, multi-tenant platforms, and is designed to integrate with other auth systems (OAuth, SAML, custom IdPs) through a single, consistent API.
Adapters are provided for Mock (in-memory) and SQLite (Drizzle). You can add Postgres, MongoDB, Redis, etc., without changing core logic.
Getting started
1. Backend (auth-engine)
cd auth-engine
npm install
cp .env.example .env # Edit with your JWT_SECRET and CORS_ORIGIN
npm run db:push # Create/update SQLite tables (tenant_id, password_reset_tokens)
npm run dev
Server runs at http://localhost:3000. Env options: PORT, CORS_ORIGIN, JWT_SECRET, ACCESS_EXPIRY, REFRESH_EXPIRY_MS.
2. Frontend (demo)
cd frontend
npm install
cp .env.example .env # Set VITE_API_URL=http://localhost:3000
npm run dev
Open http://localhost:5173. Use Forgot password? on login; in development the reset token is printed in the auth-engine console so you can paste it into the Reset Password form.
Request reset
Client: POST /auth/forgot-password with { identifier } (or email).
Server: If user exists, creates a short-lived reset token, then emits PASSWORD_RESET_REQUESTED with { userId, identifier, rawToken, expiresAt }. Your app should send an email with a link containing the token (e.g. https://yourapp.com/reset?token=...).
Reset password
Client: POST /auth/reset-password with { token, newPassword }.
Server: Validates token (single-use), updates password, emits PASSWORD_RESET_COMPLETED.
In development, the demo server logs the reset token to the console so you can test without email.
Integrating with other auth systems (universal / adaptive)
To keep one consistent auth surface (JWT + session) while supporting external IdPs (OAuth, SAML, etc.):
Implement an external auth resolver that, given a provider and token (and optional profile), validates the token with the external system and returns your internal user id (and optionally creates/links the user).
Pass it into Auth.init as externalAuthResolver.
Clients call POST /auth/external with { provider, token, profile? } and receive the same accessToken, refreshToken, sessionId as with local login.
Same as login (only if externalAuthResolver is set)
Client should store accessToken, refreshToken, and sessionId (e.g. in memory or localStorage). Use sessionId for refresh and logout. On 401, call /auth/refresh with refreshToken and sessionId, then retry the request with the new access token.
Options
trustJwtClaims (default false): If true, claims are read from the JWT payload instead of resolving on every request (faster, but role changes apply only after re-login or refresh).
