LogoDocsHub
IAM

Essentials

Core concepts and features of the IAM service, from JWT tokens and anomaly detection to rate limiting, database schema, and service startup.

The IAM service is composed of several interconnected subsystems. Each one is designed to work independently as a library export, and together they form a complete authentication stack. This section documents every core concept in detail.

Token system

Tokens
How the IAM service generates, caches, verifies, rotates, and revokes JWT access tokens and MySQL-backed refresh tokens.
Access Tokens
How the IAM service generates, caches, verifies, and revokes access tokens, and how library users wire roles and route protection.
Refresh Tokens
How the IAM service generates, stores, verifies, consumes, rotates, and revokes refresh tokens with reuse detection.
Cookies
How the IAM service sets, reads, clears, and secures cookies including the session refresh token, the issued-at timestamp, and the bot-detector canary identifier.

Authentication flows

Signup
How the IAM service registers new users, the full validation pipeline from rate limiting through email domain verification to password breach checks.
Login
How the IAM service authenticates users with email and password, the rate limiting and validation pipeline, device trust, and token issuance.
Logout
How the IAM service terminates a session by consuming and revoking the refresh token, blacklisting the access token, and clearing cookies.
OAuth
How the IAM service handles OAuth social login, provider registration with schema or field-type maps, profile mapping, and user deduplication.

Security and verification

Anomaly Detection
Nine sequential behavioral checks that run on every refresh-token use, including canary cookie matching, IP range comparison, and device fingerprint consistency.
MFA
Adaptive email OTP triggered automatically by anomaly detection, custom MFA flows for protecting sensitive actions, and OTP code generation and verification.
Magic Links
Signed temporary JWT links for adaptive MFA, password reset, email update, and custom flows. All link tokens are cached and single-use by design.
Fingerprinting
How the IAM service builds a composite device fingerprint from IP geolocation and user-agent parsing, and how it persists and compares fingerprints for anomaly detection.
XSS Protection
The multi-pass HTML sanitization pipeline, Zod integration, automatic IP banning on XSS detection, and timing-attack prevention.
HMAC Authentication
How the IAM service verifies inter-service requests using HMAC-SHA256 signatures, replay protection via a nonce cache, and clock-skew tolerance.

Communication and delivery

Emails
Transactional emails through Resend, EJS templates for OTP and notification flows, custom templates, disposable-email detection, and MX validation.
Backend for Frontend
Protected endpoints for BFF proxies, including authorization checks, token metadata with rotation hints, and the full middleware security chain.

Infrastructure

Rate Limiting
Layered rate limiters with union pairing, strike-based blocking, consecutive failure caches, and per-endpoint limiter groups for every sensitive route.
Logging
Application and HTTP request logging with Pino, log file layout, redaction, request IDs, child loggers, and asset filtering.
Database
MySQL schema organization, connection pools, hashing utilities, and in-memory caches across four IAM tables, two pool types, and an LRU access token store.
Service Startup
How the IAM service boots, initializes pools and databases, mounts middleware and routes, and serves requests in both standalone and library modes.

Getting Started

Tokens

Logo