@javagt/express-easy-auth 1.0.0 → 1.0.2

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "workbench.colorTheme": "Tomorrow Night Blue"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@javagt/express-easy-auth",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "",
   "type": "module",
   "main": "src/index.js",

package/readme.md

@@ -106,6 +106,20 @@ The library provides a flexible logging system and explicit control over error e
 - **Custom Logger**: Plug in your own logger (e.g., Winston, Pino) by passing it to `setupAuth`.
 - [View Example: Custom Logger](examples/05-custom-logger.js)
 
+### 🌐 SPA Fallback (Modern Alternative to Wildcard Routes)
+When building Single Page Applications (SPAs), avoid using catch-all wildcard routes (e.g., `app.get('*', ...)`) as they can cause routing conflicts and `PathError` in newer versions of Express. 
+
+Instead, use a middleware-based fallback that only triggers for HTML requests:
+```javascript
+app.use((req, res, next) => {
+  if (req.method === 'GET' && req.accepts('html') && !req.path.startsWith('/api')) {
+    res.sendFile(path.join(__dirname, 'public/index.html'));
+  } else {
+    next();
+  }
+});
+```
+
 ---
 
 ## 📜 API Reference
@@ -128,6 +142,8 @@ All identity endpoints are nested under the router (recommended path: `/api/v1/a
 | | POST | `/passkeys/authenticate/verify` | — | Verify passkey login |
 | | GET | `/passkeys` | ✓ | List registered passkeys |
 | | DELETE | `/passkeys/:id` | ✓ | Delete a passkey |
+| **Account** | POST | `/password/change` | ✓ (Fresh) | Change current password |
+| | POST | `/email/change` | ✓ (Fresh) | Update email address |
 | **Password Reset** | POST | `/password-reset/request` | — | Generate reset token |
 | | POST | `/password-reset/reset` | — | Complete reset |
 | **API Keys** | GET | `/api-keys` | ✓ | List user API keys |

package/src/client.js

@@ -5,6 +5,16 @@
  * TOTP 2FA, and session management.
  */
 
+export class AuthError extends Error {
+  constructor(message, status, code, data = {}) {
+    super(message || 'Authentication request failed');
+    this.name = 'AuthError';
+    this.status = status;
+    this.code = code;
+    this.data = data;
+  }
+}
+
 export class AuthClient {
   /**
    * @param {Object} options
@@ -51,11 +61,7 @@ export class AuthClient {
 
     const data = await res.json().catch(() => ({}));
     if (!res.ok) {
-      throw Object.assign(new Error(data.error || 'Request failed'), {
-        code: data.code,
-        status: res.status,
-        data,
-      });
+      throw new AuthError(data.error || 'Request failed', res.status, data.code, data);
     }
     return data;
   }
@@ -102,10 +108,17 @@ export class AuthClient {
     return this.request('/logout', { method: 'POST' });
   }
 
-  async changePassword(newPassword, token) {
-    return this.request('/change-password', {
+  async changePassword(newPassword) {
+    return this.request('/password/change', {
+      method: 'POST',
+      body: { newPassword }
+    });
+  }
+
+  async changeEmail(newEmail) {
+    return this.request('/email/change', {
       method: 'POST',
-      body: { newPassword, token }
+      body: { newEmail }
     });
   }
 

package/src/index.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 
 import { DefaultLogger } from './utils/logger.js';
-import { AuthClient } from './client.js';
+import { AuthClient, AuthError } from './client.js';
 
 /**
  * Initializes the authentication databases and configuration.
@@ -57,5 +57,6 @@ export {
   requireApiKey,
   authErrorLogger,
   DefaultLogger,
-  AuthClient
+  AuthClient,
+  AuthError
 };

package/src/middleware/auth.js

@@ -1,4 +1,4 @@
-import { randomUUID, randomBytes } from 'crypto';
+import { randomUUID, randomBytes } from 'node:crypto';
 import { authDb } from '../db/init.js';
 import bcrypt from 'bcrypt';
 

package/src/routes/auth.js

@@ -1,6 +1,6 @@
 import { Router } from 'express';
 import bcrypt from 'bcrypt';
-import { randomUUID, randomBytes } from 'crypto';
+import { randomUUID, randomBytes } from 'node:crypto';
 import { verifySync, generateSecret } from 'otplib';
 import QRCode from 'qrcode';
 import { 
@@ -36,17 +36,17 @@ router.post('/register', async (req, res) => {
   if (!username || !email || !password) {
     return getAuthResponse(req, res, {
       status: 400,
-      data: { error: 'username, email, and password are required' }
+      data: { error: 'username, email, and password are required', code: 'MISSING_CREDENTIALS' }
     });
   }
   const settings = getAppSettings();
   if (settings.auth_registration_enabled !== 'true') {
-    return res.status(403).json({ error: 'Registration is currently disabled' });
+    return res.status(403).json({ error: 'Registration is currently disabled', code: 'REGISTRATION_DISABLED' });
   }
 
   const minLen = parseInt(settings.password_min_length || '8', 10);
   if (password.length < minLen) {
-    return res.status(400).json({ error: `Password must be at least ${minLen} characters` });
+    return res.status(400).json({ error: `Password must be at least ${minLen} characters`, code: 'PASSWORD_TOO_SHORT' });
   }
 
   const db = authDb;
@@ -54,7 +54,7 @@ router.post('/register', async (req, res) => {
   if (existing) {
     return getAuthResponse(req, res, {
       status: 409,
-      data: { error: 'Username or email already taken' }
+      data: { error: 'Username or email already taken', code: 'USER_EXISTS' }
     });
   }
 
@@ -87,7 +87,7 @@ router.post('/login', async (req, res) => {
   if (!username || !password) {
     return getAuthResponse(req, res, {
       status: 400,
-      data: { error: 'username and password are required' }
+      data: { error: 'username and password are required', code: 'MISSING_CREDENTIALS' }
     });
   }
 
@@ -99,7 +99,7 @@ router.post('/login', async (req, res) => {
     await bcrypt.hash('dummy', SALT_ROUNDS);
     return getAuthResponse(req, res, {
       status: 401,
-      data: { error: 'Invalid credentials' }
+      data: { error: 'Invalid credentials', code: 'INVALID_CREDENTIALS' }
     });
   }
 
@@ -108,7 +108,7 @@ router.post('/login', async (req, res) => {
     const minsLeft = Math.ceil((user.locked_until - now) / 60000);
     return getAuthResponse(req, res, {
       status: 403,
-      data: { error: `Account locked. Please try again in ${minsLeft} minutes.` }
+      data: { error: `Account locked. Please try again in ${minsLeft} minutes.`, code: 'ACCOUNT_LOCKED' }
     });
   }
 
@@ -128,7 +128,10 @@ router.post('/login', async (req, res) => {
 
     return getAuthResponse(req, res, {
       status: 401,
-      data: { error: failed >= maxAttempts ? `Account locked for ${lockoutMins} minutes` : 'Invalid credentials' }
+      data: { 
+        error: failed >= maxAttempts ? `Account locked for ${lockoutMins} minutes` : 'Invalid credentials',
+        code: failed >= maxAttempts ? 'ACCOUNT_LOCKED' : 'INVALID_CREDENTIALS'
+      }
     });
   }
 
@@ -153,7 +156,7 @@ router.post('/login', async (req, res) => {
     if (!valid2FA?.valid) {
       return getAuthResponse(req, res, {
         status: 401,
-        data: { error: 'Invalid 2FA code' }
+        data: { error: 'Invalid 2FA code', code: 'INVALID_2FA_CODE' }
       });
     }
   }
@@ -174,13 +177,13 @@ router.post('/login/recovery', async (req, res) => {
   if (!username) username = req.session.pendingUsername;
 
   if (!username || !code) {
-    return getAuthResponse(req, res, { status: 400, data: { error: 'Username and recovery code are required' } });
+    return getAuthResponse(req, res, { status: 400, data: { error: 'Username and recovery code are required', code: 'MISSING_CREDENTIALS' } });
   }
 
   const db = authDb;
   const user = db.prepare('SELECT * FROM users WHERE username=? OR email=?').get(username || null, username || null);
   if (!user) {
-    return getAuthResponse(req, res, { status: 401, data: { error: 'Invalid recovery attempt' } });
+    return getAuthResponse(req, res, { status: 401, data: { error: 'Invalid recovery attempt', code: 'INVALID_CREDENTIALS' } });
   }
 
   const codes = db.prepare('SELECT * FROM recovery_codes WHERE user_id=? AND used=0').all(user.id);
@@ -193,7 +196,7 @@ router.post('/login/recovery', async (req, res) => {
   }
 
   if (!matchedCodeId) {
-    return getAuthResponse(req, res, { status: 401, data: { error: 'Invalid recovery code' } });
+    return getAuthResponse(req, res, { status: 401, data: { error: 'Invalid recovery code', code: 'INVALID_RECOVERY_CODE' } });
   }
 
   db.prepare('UPDATE recovery_codes SET used=1 WHERE id=?').run(matchedCodeId);
@@ -268,15 +271,15 @@ router.post(['/fresh-auth', '/reauth'], requireAuth, async (req, res) => {
 
   if (password) {
     const valid = await bcrypt.compare(password, user.password_hash);
-    if (!valid) return res.status(401).json({ error: 'Invalid password' });
+    if (!valid) return res.status(401).json({ error: 'Invalid password', code: 'INVALID_PASSWORD' });
 
     if (user.totp_enabled) {
       if (!submittedToken) return res.json({ requires2FA: true });
       const ok = verifySync({ token: submittedToken, secret: user.totp_secret, type: 'totp' });
-      if (!ok?.valid) return res.status(401).json({ error: 'Invalid TOTP code' });
+      if (!ok?.valid) return res.status(401).json({ error: 'Invalid TOTP code', code: 'INVALID_2FA_CODE' });
     }
   } else {
-    return res.status(400).json({ error: 'password required for reauth' });
+    return res.status(400).json({ error: 'password required for reauth', code: 'MISSING_PASSWORD' });
   }
 
   req.session.lastAuthedAt = Date.now();
@@ -290,7 +293,9 @@ router.post('/2fa/setup', requireAuth, async (req, res) => {
   const secret = generateSecret();
   req.session.pendingTotpSecret = secret;
 
-  const otpauthUrl = `otpauth://totp/${encodeURIComponent('AuthServer')}:${encodeURIComponent(user.email)}?secret=${secret}&issuer=AuthServer`;
+  const { rpName } = getRpConfig(req);
+  const issuer = encodeURIComponent(rpName);
+  const otpauthUrl = `otpauth://totp/${issuer}:${encodeURIComponent(user.email)}?secret=${secret}&issuer=${issuer}`;
   const qrCode = await QRCode.toDataURL(otpauthUrl);
 
   res.json({ secret, qrCode, otpauthUrl });
@@ -300,14 +305,14 @@ router.post('/2fa/verify-setup', requireAuth, (req, res) => {
   const { code, token } = req.body;
   const submittedToken = token || code;
   const secret = req.session.pendingTotpSecret;
-  if (!secret) return res.status(400).json({ error: 'No pending TOTP setup' });
+  if (!secret) return res.status(400).json({ error: 'No pending TOTP setup', code: 'NO_PENDING_2FA' });
 
   const valid = verifySync({ token: submittedToken, secret, type: 'totp' });
-  if (!valid?.valid) return res.status(401).json({ error: 'Invalid code' });
+  if (!valid?.valid) return res.status(401).json({ error: 'Invalid code', code: 'INVALID_2FA_CODE' });
 
   authDb.prepare('UPDATE users SET totp_secret=?, totp_enabled=1 WHERE id=?').run(secret, req.session.userId);
 
-  generateRecoveryCodes(10).then(({ codes, hashes }) => {
+  generateRecoveryCodes(10).then(({ plain: codes, hashes }) => {
     const now = Date.now();
     const stmt = authDb.prepare('INSERT INTO recovery_codes (id, user_id, code_hash, created_at) VALUES (?, ?, ?, ?)');
     for (const hash of hashes) {
@@ -355,11 +360,11 @@ router.post('/passkeys/register/verify', requireAuth, async (req, res) => {
   const challengeRow = authDb.prepare('SELECT * FROM webauthn_challenges WHERE user_id = ? AND type = \'registration\' AND expires_at > ? ORDER BY created_at DESC LIMIT 1')
     .get(req.userId, Date.now());
 
-  if (!challengeRow) return res.status(400).json({ error: 'No valid challenge found' });
+  if (!challengeRow) return res.status(400).json({ error: 'No valid challenge found', code: 'WEBAUTHN_CHALLENGE_NOT_FOUND' });
 
   try {
     const verification = await verifyRegistrationResponse({ response, expectedChallenge: challengeRow.challenge, expectedOrigin: origin, expectedRPID: rpID });
-    if (!verification.verified || !verification.registrationInfo) return res.status(400).json({ error: 'Passkey registration failed' });
+    if (!verification.verified || !verification.registrationInfo) return res.status(400).json({ error: 'Passkey registration failed', code: 'PASSKEY_REGISTRATION_FAILED' });
 
     const { credential, credentialDeviceType, credentialBackedUp } = verification.registrationInfo;
     const now = Date.now();
@@ -405,14 +410,14 @@ router.post('/passkeys/authenticate/verify', async (req, res) => {
   const { rpID, origin } = getRpConfig(req);
   const { response } = req.body;
   const challenge = req.session.passkeyChallenge;
-  if (!challenge) return res.status(400).json({ error: 'No active passkey challenge' });
+  if (!challenge) return res.status(400).json({ error: 'No active passkey challenge', code: 'WEBAUTHN_CHALLENGE_NOT_FOUND' });
 
   const challengeRow = authDb.prepare('SELECT * FROM webauthn_challenges WHERE challenge = ? AND type = \'authentication\' AND expires_at > ? ORDER BY created_at DESC LIMIT 1')
     .get(challenge, Date.now());
-  if (!challengeRow) return res.status(400).json({ error: 'Challenge expired or not found' });
+  if (!challengeRow) return res.status(400).json({ error: 'Challenge expired or not found', code: 'WEBAUTHN_CHALLENGE_EXPIRED' });
 
   const passkey = authDb.prepare('SELECT * FROM passkeys WHERE credential_id = ?').get(response.id);
-  if (!passkey) return res.status(400).json({ error: 'Passkey not registered' });
+  if (!passkey) return res.status(400).json({ error: 'Passkey not registered', code: 'PASSKEY_NOT_FOUND' });
 
   try {
     const verification = await verifyAuthenticationResponse({
@@ -421,7 +426,7 @@ router.post('/passkeys/authenticate/verify', async (req, res) => {
       transports: passkey.transports ? JSON.parse(passkey.transports) : [] }
     });
 
-    if (!verification.verified) return res.status(401).json({ error: 'Passkey verification failed' });
+    if (!verification.verified) return res.status(401).json({ error: 'Passkey verification failed', code: 'PASSKEY_VERIFICATION_FAILED' });
 
     authDb.prepare('UPDATE passkeys SET counter = ?, last_used = ? WHERE id = ?').run(verification.authenticationInfo.newCounter, Date.now(), passkey.id);
     authDb.prepare('DELETE FROM webauthn_challenges WHERE id = ?').run(challengeRow.id);
@@ -449,6 +454,33 @@ router.delete('/passkeys/:id', requireAuth, (req, res) => {
   res.json({ success: true });
 });
 
+// ─── ACCOUNT MANAGEMENT ──────────────────────────────────────────────────────
+
+router.post('/password/change', requireFreshAuth, async (req, res) => {
+  const { newPassword } = req.body;
+  if (!newPassword) return res.status(400).json({ error: 'newPassword is required' });
+
+  const settings = getAppSettings();
+  const minLen = parseInt(settings.password_min_length || '8', 10);
+  if (newPassword.length < minLen) {
+    return res.status(400).json({ error: `Password must be at least ${minLen} characters` });
+  }
+
+  const hash = await bcrypt.hash(newPassword, SALT_ROUNDS);
+  authDb.prepare('UPDATE users SET password_hash=?, updated_at=? WHERE id=?').run(hash, Date.now(), req.userId);
+
+  res.json({ success: true, message: 'Password changed successfully' });
+});
+
+router.post('/email/change', requireFreshAuth, async (req, res) => {
+  const { newEmail } = req.body;
+  if (!newEmail) return res.status(400).json({ error: 'newEmail is required' });
+
+  authDb.prepare('UPDATE users SET email=?, updated_at=? WHERE id=?').run(newEmail, Date.now(), req.userId);
+
+  res.json({ success: true, message: 'Email updated successfully', email: newEmail });
+});
+
 // ─── SESSIONS ────────────────────────────────────────────────────────────────
 
 router.get('/sessions', requireAuth, (req, res) => {

package/src/utils/authHelpers.js

@@ -1,5 +1,5 @@
 import bcrypt from 'bcrypt';
-import { randomBytes } from 'crypto';
+import { randomBytes } from 'node:crypto';
 
 /**
  * Generate a set of secure, readable recovery codes.

package/src/utils/logger.js

@@ -1,4 +1,4 @@
-import { randomUUID } from 'crypto';
+import { randomUUID } from 'node:crypto';
 import { authDb } from '../db/init.js';
 
 /**