webspresso 0.0.103 → 0.0.105

package/core/auth/hash.js

@@ -4,6 +4,8 @@
  * @module core/auth/hash
  */
 
+const { sha256, randomToken } = require('../utils/crypto');
+
 let bcrypt = null;
 let bcryptChecked = false;
 function getBcrypt() {
@@ -96,8 +98,7 @@ function needsRehash(hashedPassword, rounds = DEFAULT_ROUNDS) {
  * @returns {string} Hex-encoded random token
  */
 function generateToken(length = 32) {
-  const crypto = require('crypto');
-  return crypto.randomBytes(length).toString('hex');
+  return randomToken(length, 'hex');
 }
 
 /**
@@ -111,9 +112,9 @@ function generateToken(length = 32) {
  * @returns {string} Hex-encoded SHA-256 digest
  */
 function hashToken(token) {
-  const crypto = require('crypto');
+  if (!token) return '';
   // CodeQL [js/insufficient-password-hash] False positive: token is a 256-bit random string, not a user password
-  return crypto.createHash('sha256').update(String(token)).digest('hex');
+  return sha256(String(token));
 }
 
 module.exports = {

package/core/auth/jwt.js

@@ -5,59 +5,17 @@
  */
 
 const crypto = require('crypto');
+const { safeCompare, hmacSha256, base64UrlEncode, base64UrlDecode } = require('../utils/crypto');
+const { parseDurationSec } = require('../utils/time');
 
 const HS256_HEADER_BASE64URL = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9';
 
-/**
- * Base64URL encode string or Buffer
- * @param {string|Buffer} input
- * @returns {string}
- */
-function base64UrlEncode(input) {
-  return Buffer.isBuffer(input)
-    ? input.toString('base64url')
-    : Buffer.from(String(input), 'utf8').toString('base64url');
-}
-
-/**
- * Base64URL decode string
- * @param {string} input
- * @returns {string}
- */
-function base64UrlDecode(input) {
-  return Buffer.from(String(input), 'base64url').toString('utf8');
-}
-
 /**
  * Parse duration string (e.g. '1h', '7d', '15m', '3600') into seconds
  * @param {string|number} duration
  * @returns {number} Seconds
  */
-function parseDuration(duration) {
-  if (typeof duration === 'number') {
-    return duration;
-  }
-  if (typeof duration !== 'string') {
-    return 3600; // Default 1 hour
-  }
-
-  const match = duration.trim().match(/^(\d+)\s*([smhd])?$/i);
-  if (!match) {
-    const parsed = parseInt(duration, 10);
-    return isNaN(parsed) ? 3600 : parsed;
-  }
-
-  const value = parseInt(match[1], 10);
-  const unit = (match[2] || 's').toLowerCase();
-
-  switch (unit) {
-    case 's': return value;
-    case 'm': return value * 60;
-    case 'h': return value * 3600;
-    case 'd': return value * 86400;
-    default: return value;
-  }
-}
+const parseDuration = parseDurationSec;
 
 /**
  * Sign payload to create HS256 JWT string
@@ -109,10 +67,7 @@ function signJwt(payload, secret, options = {}) {
   const encodedPayload = base64UrlEncode(JSON.stringify(fullPayload));
 
   const signingInput = `${encodedHeader}.${encodedPayload}`;
-  const encodedSignature = crypto
-    .createHmac('sha256', secret)
-    .update(signingInput)
-    .digest('base64url');
+  const encodedSignature = hmacSha256(signingInput, secret, 'base64url');
 
   return `${signingInput}.${encodedSignature}`;
 }
@@ -165,17 +120,11 @@ function verifyJwt(token, secret, options = {}) {
 
   // Re-compute signature
   const signingInput = `${encodedHeader}.${encodedPayload}`;
-  const expectedSignatureBuf = crypto
-    .createHmac('sha256', secret)
-    .update(signingInput)
-    .digest();
+  const expectedSignatureBuf = hmacSha256(signingInput, secret, 'buffer');
 
   const actualSignatureBuf = Buffer.from(encodedSignature, 'base64url');
 
-  if (
-    expectedSignatureBuf.length !== actualSignatureBuf.length ||
-    !crypto.timingSafeEqual(expectedSignatureBuf, actualSignatureBuf)
-  ) {
+  if (!safeCompare(expectedSignatureBuf, actualSignatureBuf)) {
     throw new Error('Invalid JWT signature');
   }
 

package/core/auth/magic-link.js

@@ -6,6 +6,8 @@
 
 'use strict';
 
+const { stripTrailingSlash, ensureLeadingSlash } = require('../utils/url');
+
 /**
  * Construct full magic link verification URL
  * 
@@ -16,10 +18,7 @@
  * @returns {string}
  */
 function buildMagicLinkUrl(options = {}) {
-  let baseUrl = String(options.baseUrl || process.env.BASE_URL || 'http://localhost:3000');
-  while (baseUrl.endsWith('/')) {
-    baseUrl = baseUrl.slice(0, -1);
-  }
+  const baseUrl = stripTrailingSlash(options.baseUrl || process.env.BASE_URL || 'http://localhost:7331');
   const path = options.path || '/auth/magic-link/verify';
   const token = options.token;
 
@@ -27,7 +26,7 @@ function buildMagicLinkUrl(options = {}) {
     throw new Error('Token is required to build magic link URL');
   }
 
-  const cleanPath = path.startsWith('/') ? path : `/${path}`;
+  const cleanPath = ensureLeadingSlash(path);
   const sep = cleanPath.includes('?') ? '&' : '?';
   return `${baseUrl}${cleanPath}${sep}token=${encodeURIComponent(token)}`;
 }

package/core/auth/manager.js

@@ -15,6 +15,7 @@ const {
   consumeAuthToken,
   hash: hashPassword,
 } = require('./tokens');
+const { stripTrailingSlash, ensureLeadingSlash } = require('../utils/url');
 
 /**
  * Authentication error
@@ -959,12 +960,9 @@ class AuthManager extends EventEmitter {
       tokenTtlMs
     );
 
-    let baseUrl = String(options.baseUrl || this.config.baseUrl || process.env.BASE_URL || 'http://localhost:3000');
-    while (baseUrl.endsWith('/')) {
-      baseUrl = baseUrl.slice(0, -1);
-    }
+    const baseUrl = stripTrailingSlash(options.baseUrl || this.config.baseUrl || process.env.BASE_URL || 'http://localhost:7331');
     const pathSegment = options.path || '/auth/magic-link/verify';
-    const cleanPath = pathSegment.startsWith('/') ? pathSegment : `/${pathSegment}`;
+    const cleanPath = ensureLeadingSlash(pathSegment);
     const sep = cleanPath.includes('?') ? '&' : '?';
 
     const hasCustomUrl = typeof options.buildMagicLinkUrl === 'function' || Boolean(options.path) || Boolean(options.baseUrl);

package/core/auth/oauth.js

@@ -6,6 +6,8 @@
  */
 
 const crypto = require('crypto');
+const { fetchWithTimeout } = require('../utils/fetch');
+const { safeCompare, sha256, hmacSha256, base64UrlEncode, base64UrlDecode, randomToken } = require('../utils/crypto');
 
 /**
  * Custom error class for OAuth operations
@@ -57,14 +59,17 @@ const DEFAULT_PROVIDERS = {
     userEmailsUrl: 'https://api.github.com/user/emails',
     defaultScopes: ['read:user', 'user:email'],
     defaultParams: {},
-    async fetchExtra(tokens) {
+    async fetchExtra(tokens, options = {}) {
       try {
-        const res = await fetch('https://api.github.com/user/emails', {
+        const timeout = typeof options?.timeout === 'number' ? options.timeout : 10000;
+        const res = await fetchWithTimeout('https://api.github.com/user/emails', {
           headers: {
             Authorization: `Bearer ${tokens.access_token}`,
             Accept: 'application/vnd.github.v3+json',
             'User-Agent': 'Webspresso-OAuth',
           },
+          timeout,
+          signal: options?.signal,
         });
         if (res.ok) {
           const emails = await res.json();
@@ -78,7 +83,7 @@ const DEFAULT_PROVIDERS = {
           }
         }
       } catch {
-        // Fallback gracefully if email endpoint is unreachable
+        // Fallback gracefully if email endpoint is unreachable or times out
       }
       return null;
     },
@@ -105,11 +110,8 @@ const DEFAULT_PROVIDERS = {
  * @returns {{ codeVerifier: string, codeChallenge: string, codeChallengeMethod: 'S256' }}
  */
 function generatePKCE() {
-  const codeVerifier = crypto.randomBytes(32).toString('base64url');
-  const codeChallenge = crypto
-    .createHash('sha256')
-    .update(codeVerifier)
-    .digest('base64url');
+  const codeVerifier = randomToken(32, 'base64url');
+  const codeChallenge = sha256(codeVerifier, 'base64url');
 
   return {
     codeVerifier,
@@ -132,14 +134,11 @@ function createSignedState(payload, secret) {
   const dataWithMeta = {
     ...payload,
     timestamp: Date.now(),
-    nonce: crypto.randomBytes(16).toString('hex'),
+    nonce: randomToken(16, 'hex'),
   };
 
-  const body = Buffer.from(JSON.stringify(dataWithMeta), 'utf8').toString('base64url');
-  const signature = crypto
-    .createHmac('sha256', secret)
-    .update(body)
-    .digest('base64url');
+  const body = base64UrlEncode(JSON.stringify(dataWithMeta));
+  const signature = hmacSha256(body, secret, 'base64url');
 
   return `${body}.${signature}`;
 }
@@ -162,21 +161,15 @@ function verifySignedState(stateString, secret, maxAgeMs = 10 * 60 * 1000) {
   }
 
   const [body, signature] = parts;
-  const expectedSignature = crypto
-    .createHmac('sha256', secret)
-    .update(body)
-    .digest('base64url');
+  const expectedSignature = hmacSha256(body, secret, 'base64url');
 
-  const bufA = Buffer.from(signature);
-  const bufB = Buffer.from(expectedSignature);
-
-  if (bufA.length !== bufB.length || !crypto.timingSafeEqual(bufA, bufB)) {
+  if (!safeCompare(signature, expectedSignature)) {
     throw new OAuthError('OAuth state signature verification failed', 'INVALID_STATE');
   }
 
   let payload;
   try {
-    const jsonStr = Buffer.from(body, 'base64url').toString('utf8');
+    const jsonStr = base64UrlDecode(body);
     payload = JSON.parse(jsonStr);
   } catch {
     throw new OAuthError('Failed to parse OAuth state payload', 'INVALID_STATE');
@@ -202,6 +195,9 @@ class OAuthClient {
   constructor(config = {}) {
     this.secret = config.secret || process.env.OAUTH_SECRET || process.env.SESSION_SECRET || 'webspresso-oauth-secret';
     this.stateTtlMs = config.stateTtlMs || 10 * 60 * 1000;
+    this.timeout = typeof (config.timeout || config.requestTimeout) === 'number'
+      ? (config.timeout || config.requestTimeout)
+      : 10000;
     this.providers = {};
 
     if (config.providers) {
@@ -227,6 +223,7 @@ class OAuthClient {
       redirectUri: options.redirectUri || options.redirect_uri || builtin.redirectUri,
       scopes: options.scopes || options.scope || builtin.defaultScopes || [],
       params: { ...(builtin.defaultParams || {}), ...(options.params || {}) },
+      timeout: typeof options.timeout === 'number' ? options.timeout : (builtin.timeout || this.timeout || 10000),
     };
     return this;
   }
@@ -330,7 +327,7 @@ class OAuthClient {
    * @param {string} [params.codeVerifier]
    * @returns {Promise<Object>} Token response
    */
-  async exchangeCode(providerName, { code, redirectUri, codeVerifier }) {
+  async exchangeCode(providerName, { code, redirectUri, codeVerifier, timeout, signal } = {}) {
     const provider = this.getProvider(providerName);
 
     if (!code) {
@@ -354,9 +351,13 @@ class OAuthClient {
       bodyParams.set('code_verifier', codeVerifier);
     }
 
+    const requestTimeout = typeof timeout === 'number'
+      ? timeout
+      : (provider.timeout || this.timeout || 10000);
+
     let res;
     try {
-      res = await fetch(provider.tokenUrl, {
+      res = await fetchWithTimeout(provider.tokenUrl, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/x-www-form-urlencoded',
@@ -364,6 +365,8 @@ class OAuthClient {
           'User-Agent': 'Webspresso-OAuth',
         },
         body: bodyParams.toString(),
+        timeout: requestTimeout,
+        signal,
       });
     } catch (err) {
       throw new OAuthError(`Token exchange network request failed: ${err.message}`, 'NETWORK_ERROR', err);
@@ -398,7 +401,7 @@ class OAuthClient {
    * @param {Object} tokens - Tokens object returned from exchangeCode
    * @returns {Promise<Object>} Normalized user profile
    */
-  async fetchUserProfile(providerName, tokens) {
+  async fetchUserProfile(providerName, tokens, options = {}) {
     const provider = this.getProvider(providerName);
     const accessToken = tokens.access_token || tokens.accessToken;
 
@@ -406,19 +409,26 @@ class OAuthClient {
       throw new OAuthError('Missing access_token for user profile retrieval', 'MISSING_TOKEN');
     }
 
+    const requestTimeout = typeof options?.timeout === 'number'
+      ? options.timeout
+      : (provider.timeout || this.timeout || 10000);
+    const signal = options?.signal;
+
     let extraData = null;
     if (typeof provider.fetchExtra === 'function') {
-      extraData = await provider.fetchExtra(tokens);
+      extraData = await provider.fetchExtra(tokens, { timeout: requestTimeout, signal });
     }
 
     let res;
     try {
-      res = await fetch(provider.userInfoUrl, {
+      res = await fetchWithTimeout(provider.userInfoUrl, {
         headers: {
           Authorization: `Bearer ${accessToken}`,
           Accept: 'application/json',
           'User-Agent': 'Webspresso-OAuth',
         },
+        timeout: requestTimeout,
+        signal,
       });
     } catch (err) {
       throw new OAuthError(`User profile fetch failed: ${err.message}`, 'NETWORK_ERROR', err);
@@ -457,7 +467,7 @@ class OAuthClient {
    * @param {string} [params.redirectUri] - Redirect URI
    * @returns {Promise<{ provider: string, user: Object, tokens: Object, stateData: Object }>}
    */
-  async handleCallback(providerName, { code, state, redirectUri }) {
+  async handleCallback(providerName, { code, state, redirectUri, timeout, signal } = {}) {
     if (!state) {
       throw new OAuthError('Missing OAuth state in callback', 'INVALID_STATE');
     }
@@ -483,10 +493,15 @@ class OAuthClient {
       code,
       redirectUri: effectiveRedirectUri,
       codeVerifier,
+      timeout,
+      signal,
     });
 
     // Fetch normalized profile
-    const user = await this.fetchUserProfile(providerName, tokens);
+    const user = await this.fetchUserProfile(providerName, tokens, {
+      timeout,
+      signal,
+    });
 
     return {
       provider: providerName,

package/core/auth/totp.js

@@ -5,6 +5,7 @@
  */
 
 const crypto = require('crypto');
+const { sha256 } = require('../utils/crypto');
 const { generateQrSvg, generateQrDataUri, createQrMatrix } = require('./qrcode');
 
 const RFC4648_BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
@@ -163,20 +164,8 @@ function generateHotp(secret, counter, options = {}) {
   return token;
 }
 
-/**
- * Timing-safe token equality check
- * @param {string} a
- * @param {string} b
- * @returns {boolean}
- */
-function timingSafeTokenCompare(a, b) {
-  if (typeof a !== 'string' || typeof b !== 'string') return false;
-  if (a.length !== b.length) return false;
-
-  const bufA = Buffer.from(a);
-  const bufB = Buffer.from(b);
-  return crypto.timingSafeEqual(bufA, bufB);
-}
+const { safeCompare } = require('../utils/crypto');
+const timingSafeTokenCompare = safeCompare;
 
 /**
  * Verify HOTP token against counter
@@ -388,7 +377,7 @@ function hashRecoveryCode(code) {
     throw new TypeError('Recovery code must be a string');
   }
   const clean = code.toLowerCase().replace(/[\s-]/g, '');
-  return crypto.createHash('sha256').update(clean, 'utf8').digest('hex');
+  return sha256(clean);
 }
 
 /**
@@ -412,7 +401,7 @@ function verifyRecoveryCode(code, hashedCodes = []) {
       continue;
     }
     const candidateBuf = Buffer.from(candidateHash, 'hex');
-    if (crypto.timingSafeEqual(targetBuf, candidateBuf)) {
+    if (safeCompare(targetBuf, candidateBuf)) {
       matchedIndex = i;
       break;
     }

package/core/auth/user-agent.js

@@ -17,27 +17,7 @@
  * @property {boolean} isBot
  */
 
-/**
- * Extract client IP address handling proxies
- * @param {Object} req - Express / Node.js HTTP request
- * @returns {string}
- */
-function getClientIp(req) {
-  if (!req) return '127.0.0.1';
-
-  const forwarded = req.headers?.['x-forwarded-for'];
-  if (forwarded) {
-    const ips = typeof forwarded === 'string' ? forwarded.split(',') : forwarded;
-    const first = Array.isArray(ips) ? ips[0] : ips;
-    if (first) return first.trim();
-  }
-
-  return req.headers?.['x-real-ip'] ||
-    req.ip ||
-    req.connection?.remoteAddress ||
-    req.socket?.remoteAddress ||
-    '127.0.0.1';
-}
+const { getClientIp } = require('../utils/ip');
 
 /**
  * Parse raw User-Agent header string into structured device info

package/core/cache/byte-size.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Webspresso - Zero-Dependency Approximate Byte Sizer
+ * Fast, non-blocking memory footprint calculator for LRU cache entries.
+ * Handles strings, numbers, buffers, dates, arrays, and objects with recursion depth limits.
+ * @module core/cache/byte-size
+ */
+
+const MAX_RECURSION_DEPTH = 6;
+
+/**
+ * Approximates memory byte size of any JavaScript value.
+ *
+ * @param {*} value - Value to calculate size for
+ * @param {number} [depth=0] - Current recursion depth
+ * @param {Set} [seen=null] - Circular reference protection set
+ * @returns {number} Approximate size in bytes
+ */
+function approximateByteSize(value, depth = 0, seen = null) {
+  if (value === null || value === undefined) {
+    return 8;
+  }
+
+  const type = typeof value;
+
+  if (type === 'boolean') {
+    return 4;
+  }
+
+  if (type === 'number') {
+    return 8;
+  }
+
+  if (type === 'string') {
+    // UTF-8 byte length (fast Buffer approximation)
+    return Buffer.byteLength(value, 'utf8') + 8;
+  }
+
+  if (type === 'bigint') {
+    return 16;
+  }
+
+  if (type === 'symbol') {
+    return 16;
+  }
+
+  if (type === 'function') {
+    return 32;
+  }
+
+  // Buffers and TypedArrays
+  if (Buffer.isBuffer(value)) {
+    return value.length + 32;
+  }
+
+  if (ArrayBuffer.isView(value)) {
+    return value.byteLength + 32;
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return value.byteLength + 32;
+  }
+
+  // Guard against deep nesting
+  if (depth > MAX_RECURSION_DEPTH) {
+    return 64;
+  }
+
+  if (type === 'object') {
+    if (!seen) {
+      seen = new Set();
+    }
+    if (seen.has(value)) {
+      return 0; // Prevent infinite recursion on circular references
+    }
+    seen.add(value);
+
+    let bytes = 32; // V8 object header baseline
+
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        bytes += approximateByteSize(value[i], depth + 1, seen);
+      }
+      return bytes;
+    }
+
+    if (value instanceof Date) {
+      return 16;
+    }
+
+    if (value instanceof RegExp) {
+      return value.source.length * 2 + 32;
+    }
+
+    if (value instanceof Map) {
+      for (const [k, v] of value.entries()) {
+        bytes += approximateByteSize(k, depth + 1, seen) + approximateByteSize(v, depth + 1, seen);
+      }
+      return bytes;
+    }
+
+    if (value instanceof Set) {
+      for (const item of value.values()) {
+        bytes += approximateByteSize(item, depth + 1, seen);
+      }
+      return bytes;
+    }
+
+    const keys = Object.keys(value);
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      bytes += Buffer.byteLength(k, 'utf8') + 8 + approximateByteSize(value[k], depth + 1, seen);
+    }
+    return bytes;
+  }
+
+  return 16;
+}
+
+module.exports = {
+  approximateByteSize,
+};

package/core/cache/index.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * Webspresso - High-Performance LRU & Tagged Cache Engine
+ * Zero-dependency, memory-bounded, leak-free cache primitives with stampede protection.
+ * @module core/cache
+ */
+
+const { LruCache, createLruCache, safeClone } = require('./lru');
+const { TaggedLruCache, createTaggedLruCache, normalizeTags } = require('./tagged-lru');
+const { approximateByteSize } = require('./byte-size');
+
+module.exports = {
+  LruCache,
+  createLruCache,
+  TaggedLruCache,
+  createTaggedLruCache,
+  approximateByteSize,
+  safeClone,
+  normalizeTags,
+};