Authrix v2.1.0

Authrix Release Notes — API Simplification & Critical Bug Fixes

This release delivers major stability improvements, critical bug fixes, and the first phase of our Email Services API and Core Auth API simplification.
It focuses on unifying duplicate code paths, fixing security-sensitive issues, and improving developer experience, while preserving backward compatibility via shims and one‑time warnings.

---

Highlights

🔒 Critical Security & Stability Fixes

• Password Pepper Stability (Dev/Test) — Pepper now deterministically derived from JWT_SECRET if env pepper missing, preventing post‑restart sign‑in failures during development. Production still requires explicit AUTHRIX_PASSWORD_PEPPER.
• Hashed Passwords for SSO Users — Random passwords generated for SSO accounts are now securely hashed before DB storage; user records also track authMethod and authProvider.
• PostgreSQL Schema Updates — full_name and profile_picture columns (plus optional auth_method and auth_provider) added to match Mongo adapter and persist extra profile fields.
• Cookie Unit Normalization — Fixed maxAge seconds/milliseconds mismatch in Set-Cookie headers for predictable expiry across frameworks.
• Middleware Signature Validation — Structural JWT checks now enforce signature verification if secret configured.

📧 Email Services API Unification

• Single EmailServiceRegistry replaces multiple registries; setDefault() ensures consistent default resolution.
• New explicit initialization:

  initEmailServices({
    defaultEmailService: 'resend',
    providers: { resend: {...}, sendgrid: {...} }
  })

• Normalized types (SendEmailOptions, EmailMetadata, EmailServiceCapabilities) and environment validation across providers.
• Side‑effect–free imports (no auto‑init) for cleaner application bootstraps.

⚙️ Core Auth API Consolidation

• New grouped namespace:
  • auth.actions (signup, signin, logout)
  • auth.session (getUser, isAuthenticated)
  • auth.handlers (factory route handlers)
• Legacy flat exports remain with one‑time deprecation warnings; full migration doc provided.

---

Developer Experience Improvements

• Reduced inline comment noise; concise TSDoc added for public APIs to improve IDE hover help.
• Deterministic default email service selection (resend > sendgrid > gmail > smtp > console) when only environment configuration provided.
• Centralized registry and cookie helpers reduce configuration complexity.

---

Migration Notes

• Email: Prefer initEmailServices() or pass email config via initAuth(). Legacy initializeEmailServices calls still work but warn.
• Auth Actions: Update imports to auth.actions.* and auth.session.* where possible. Old Next/App/Pages-specific exports map directly.
• PostgreSQL: Apply provided ALTER TABLE snippet to add missing columns for profile and auth method/provider fields.
• Env Vars: Set AUTHRIX_PASSWORD_PEPPER (required in prod) and JWT_SECRET. In dev, missing pepper falls back to deterministic derivation.

---

Status

• Critical fixes complete for pepper stability, SSO hashing, Postgres fields, cookie expiry, and JWT signature enforcement.
• Email and core API unification Phase 1 complete; shims ensure non-breaking transition.
• Upcoming: Enhanced provider diagnostics, logging unification, rolling session refresh option, and migration doc for API simplification.

---

Recommended Action:
Upgrade promptly to benefit from security and stability fixes. Apply the Postgres migration if applicable, update environment variables, and begin transitioning to the unified auth and initEmailServices APIs.