webspresso 0.0.103 → 0.0.105

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/.agents/AGENTS.md +6 -0
  2. package/.agents/ARCHITECTURE.md +23 -0
  3. package/.agents/CACHE.md +147 -0
  4. package/.agents/CLI.md +1 -1
  5. package/.agents/EARLY_HINTS.md +120 -0
  6. package/.agents/HEALTH.md +118 -0
  7. package/.agents/LIMITS.md +109 -0
  8. package/.agents/ORM.md +155 -1
  9. package/.agents/PLUGINS.md +28 -0
  10. package/.agents/RESILIENCE.md +235 -0
  11. package/AGENTS.md +6 -0
  12. package/README.md +2 -2
  13. package/bin/commands/add-docker.js +6 -6
  14. package/bin/commands/dev.js +4 -3
  15. package/bin/commands/new.js +5 -5
  16. package/bin/commands/openapi.js +1 -1
  17. package/bin/commands/start.js +1 -1
  18. package/bin/utils/orm-map-html.js +2 -8
  19. package/bin/utils/project.js +2 -2
  20. package/core/auth/hash.js +5 -4
  21. package/core/auth/jwt.js +6 -57
  22. package/core/auth/magic-link.js +4 -5
  23. package/core/auth/manager.js +3 -5
  24. package/core/auth/oauth.js +45 -30
  25. package/core/auth/totp.js +5 -16
  26. package/core/auth/user-agent.js +1 -21
  27. package/core/cache/byte-size.js +123 -0
  28. package/core/cache/index.js +21 -0
  29. package/core/cache/lru.js +477 -0
  30. package/core/cache/tagged-lru.js +346 -0
  31. package/core/commands/registry.js +6 -20
  32. package/core/content/renderer.js +1 -13
  33. package/core/early-hints/index.js +267 -0
  34. package/core/errors/domain.js +48 -0
  35. package/core/errors/http.js +31 -0
  36. package/core/errors/index.js +10 -0
  37. package/core/errors/middleware.js +2 -8
  38. package/core/errors/normalize.js +88 -2
  39. package/core/events/discovery.js +6 -24
  40. package/core/events/dispatcher.js +2 -7
  41. package/core/forms/form-builder.js +1 -9
  42. package/core/health/index.js +41 -0
  43. package/core/health/middleware.js +213 -0
  44. package/core/health/normalize.js +140 -0
  45. package/core/health/probes.js +203 -0
  46. package/core/limits/index.js +34 -0
  47. package/core/limits/middleware.js +317 -0
  48. package/core/limits/normalize.js +222 -0
  49. package/core/orm/batch.js +70 -0
  50. package/core/orm/cache/fingerprint.js +2 -2
  51. package/core/orm/cache/memory-provider.js +27 -110
  52. package/core/orm/index.js +76 -8
  53. package/core/orm/json-fields.js +22 -8
  54. package/core/orm/model.js +10 -0
  55. package/core/orm/query-builder.js +63 -9
  56. package/core/orm/query-filters.js +393 -0
  57. package/core/orm/repository.js +318 -19
  58. package/core/orm/schema-helpers.js +8 -10
  59. package/core/orm/scopes.js +321 -1
  60. package/core/orm/transaction.js +10 -2
  61. package/core/orm/utils.js +4 -86
  62. package/core/queue/adapters/database.js +4 -8
  63. package/core/queue/manager.js +55 -41
  64. package/core/resilience/circuit-breaker.js +391 -0
  65. package/core/resilience/errors.js +63 -0
  66. package/core/resilience/index.js +53 -0
  67. package/core/resilience/registry.js +97 -0
  68. package/core/resilience/retry.js +203 -0
  69. package/core/schema-cache.js +9 -2
  70. package/core/shutdown/http-adapter.js +4 -1
  71. package/core/shutdown/shutdown-manager.js +132 -31
  72. package/core/utils/array.js +12 -0
  73. package/core/utils/base64url.js +8 -0
  74. package/core/utils/crypto.js +191 -0
  75. package/core/utils/ensure-leading-slash.js +6 -0
  76. package/core/utils/escape-html.js +7 -0
  77. package/core/utils/escape-regexp.js +7 -0
  78. package/core/utils/fetch.js +121 -0
  79. package/core/utils/fs.js +144 -0
  80. package/core/utils/get-client-ip.js +6 -0
  81. package/core/utils/hmac.js +6 -0
  82. package/core/utils/html.js +72 -0
  83. package/core/utils/ip.js +86 -0
  84. package/core/utils/json.js +98 -0
  85. package/core/utils/object.js +106 -0
  86. package/core/utils/random.js +9 -0
  87. package/core/utils/regex.js +77 -0
  88. package/core/utils/safe-compare.js +3 -0
  89. package/core/utils/sha256.js +6 -0
  90. package/core/utils/string.js +87 -0
  91. package/core/utils/strip-trailing-slash.js +6 -0
  92. package/core/utils/time.js +96 -0
  93. package/core/utils/timeout.js +348 -0
  94. package/core/utils/url.js +106 -0
  95. package/core/utils/walk.js +7 -0
  96. package/index.d.ts +627 -2
  97. package/index.js +158 -0
  98. package/package.json +1 -2
  99. package/plugins/admin-panel/auth.js +15 -7
  100. package/plugins/admin-panel/client/parts/01-state-api-breadcrumb.js +82 -10
  101. package/plugins/admin-panel/client/parts/05-rich-text-file-helpers.js +4 -2
  102. package/plugins/admin-panel/client/parts/08-record-list.js +3 -2
  103. package/plugins/admin-panel/client/parts/10-export-registry.js +6 -0
  104. package/plugins/admin-panel/core/api-extensions.js +3 -80
  105. package/plugins/admin-panel/index.js +1 -1
  106. package/plugins/admin-panel/lib/login-rate-limiter.js +15 -13
  107. package/plugins/admin-panel/modules/menu.js +1 -1
  108. package/plugins/api-key/crypto.js +3 -26
  109. package/plugins/api-key/scopes.js +5 -7
  110. package/plugins/audit-log/api-handlers.js +8 -7
  111. package/plugins/audit-log/middleware.js +11 -2
  112. package/plugins/audit-log/parse.js +3 -3
  113. package/plugins/basic-auth/index.js +2 -26
  114. package/plugins/cors.js +2 -2
  115. package/plugins/csrf/index.js +7 -23
  116. package/plugins/dashboard/app.js +2 -2
  117. package/plugins/dashboard/index.js +5 -5
  118. package/plugins/data-exchange/record-selection.js +2 -5
  119. package/plugins/email/api-handlers.js +5 -18
  120. package/plugins/email/auth-bridge.js +3 -2
  121. package/plugins/file-manager/admin-component.js +3 -1
  122. package/plugins/file-manager/core.js +34 -4
  123. package/plugins/health-check.js +2 -1
  124. package/plugins/index.js +2 -0
  125. package/plugins/lazy.js +5 -6
  126. package/plugins/mcp/auth.js +1 -13
  127. package/plugins/mcp/discovery.js +18 -17
  128. package/plugins/mcp/index.js +23 -1
  129. package/plugins/mcp/transports/sse.js +10 -1
  130. package/plugins/orm-cache-admin/admin-component.js +3 -2
  131. package/plugins/polar/src/api.js +11 -3
  132. package/plugins/polar/src/webhooks.js +7 -13
  133. package/plugins/rate-limit/index.js +3 -1
  134. package/plugins/recaptcha/helpers.js +1 -7
  135. package/plugins/recaptcha/verify.js +37 -23
  136. package/plugins/redirect/index.js +57 -7
  137. package/plugins/rest-resources/index.js +1 -207
  138. package/plugins/rls/index.js +170 -0
  139. package/plugins/schema-explorer/admin-component.js +4 -2
  140. package/plugins/schema-explorer.js +40 -29
  141. package/plugins/seo-checker/index.js +5 -2
  142. package/plugins/site-analytics/tracking.js +21 -18
  143. package/plugins/sitemap.js +21 -17
  144. package/plugins/swagger.js +13 -17
  145. package/plugins/upload/index.js +4 -3
  146. package/plugins/upload/orphan-pruner.js +4 -3
  147. package/plugins/webhooks/crypto.js +6 -28
  148. package/plugins/webhooks/dispatcher.js +14 -9
  149. package/plugins/webhooks/index.js +6 -0
  150. package/plugins/webhooks/matcher.js +28 -17
  151. package/plugins/webhooks/sender.js +40 -13
  152. package/src/app-context.js +41 -5
  153. package/src/dev/banner.js +6 -2
  154. package/src/dev-reload/index.js +47 -6
  155. package/src/file-router.js +1 -3
  156. package/src/helpers.js +180 -33
  157. package/src/modules/module-discovery.js +1 -9
  158. package/src/pages/page-loader.js +53 -1
  159. package/src/plugin-manager.js +90 -17
  160. package/src/server.js +137 -26
  161. package/src/services/discovery.js +19 -40
  162. package/src/services/executor.js +86 -25
  163. package/src/services/memoize.js +3 -25
  164. package/src/services/registry.js +6 -0
  165. package/src/template/precompile.js +8 -19
@@ -0,0 +1,191 @@
1
+ /**
2
+ * Webspresso Zero-Dependency Crypto & Security Utilities
3
+ *
4
+ * Lightweight, timing-attack resistant cryptographic helpers.
5
+ *
6
+ * @module core/utils/crypto
7
+ */
8
+
9
+ 'use strict';
10
+
11
+ const crypto = require('crypto');
12
+
13
+ /**
14
+ * Constant-time equality comparison to prevent timing attacks.
15
+ *
16
+ * Compares two strings or Buffers in constant time using `crypto.timingSafeEqual`.
17
+ * Handles length mismatches by executing a dummy comparison against identical buffer
18
+ * to protect against timing leakage while safely returning `false`.
19
+ *
20
+ * @param {string|Buffer} a - First value to compare
21
+ * @param {string|Buffer} b - Second value to compare
22
+ * @returns {boolean} True if values are identical, false otherwise
23
+ */
24
+ function safeCompare(a, b) {
25
+ if (a === null || a === undefined || b === null || b === undefined) {
26
+ return false;
27
+ }
28
+
29
+ const isABuf = Buffer.isBuffer(a);
30
+ const isBBuf = Buffer.isBuffer(b);
31
+
32
+ if (isABuf && isBBuf) {
33
+ if (a.length !== b.length) {
34
+ if (a.length > 0) {
35
+ try {
36
+ crypto.timingSafeEqual(a, a);
37
+ } catch (_) {}
38
+ }
39
+ return false;
40
+ }
41
+ try {
42
+ return crypto.timingSafeEqual(a, b);
43
+ } catch (_) {
44
+ return false;
45
+ }
46
+ }
47
+
48
+ if (typeof a !== 'string' || typeof b !== 'string') {
49
+ return false;
50
+ }
51
+
52
+ const bufA = Buffer.from(a, 'utf8');
53
+ const bufB = Buffer.from(b, 'utf8');
54
+
55
+ if (bufA.length !== bufB.length) {
56
+ try {
57
+ // Dummy comparison to prevent timing leaks on length mismatches
58
+ crypto.timingSafeEqual(bufA, bufA);
59
+ } catch (_) {}
60
+ return false;
61
+ }
62
+
63
+ try {
64
+ return crypto.timingSafeEqual(bufA, bufB);
65
+ } catch (_) {
66
+ return false;
67
+ }
68
+ }
69
+
70
+ /**
71
+ * Compute SHA-256 hash of a string, Buffer, or value.
72
+ *
73
+ * Zero-dependency wrapper around native `crypto.createHash('sha256')`.
74
+ * Safely coerces non-Buffer/non-string values to strings (or empty string for null/undefined).
75
+ *
76
+ * @param {string|Buffer|any} data - Data to hash
77
+ * @param {import('crypto').BinaryToTextEncoding|'buffer'} [encoding='hex'] - Output encoding ('hex', 'base64', 'base64url', or 'buffer')
78
+ * @returns {string|Buffer} Digest in specified encoding, or Buffer if encoding is 'buffer'
79
+ */
80
+ function sha256(data, encoding = 'hex') {
81
+ if (data === null || data === undefined) {
82
+ data = '';
83
+ }
84
+ const input = Buffer.isBuffer(data) || typeof data === 'string' ? data : String(data);
85
+ const hash = crypto.createHash('sha256').update(input);
86
+ return encoding === 'buffer' ? hash.digest() : hash.digest(encoding || 'hex');
87
+ }
88
+
89
+ /**
90
+ * Compute HMAC-SHA256 signature of data using a secret key.
91
+ *
92
+ * Zero-dependency wrapper around native `crypto.createHmac('sha256', secret)`.
93
+ *
94
+ * @param {string|Buffer|any} data - Data to sign
95
+ * @param {string|Buffer} secret - Secret key
96
+ * @param {import('crypto').BinaryToTextEncoding|'buffer'} [encoding='hex'] - Output encoding ('hex', 'base64', 'base64url', or 'buffer')
97
+ * @returns {string|Buffer} Signature in specified encoding, or Buffer if encoding is 'buffer'
98
+ */
99
+ function hmacSha256(data, secret, encoding = 'hex') {
100
+ if (secret === null || secret === undefined) {
101
+ throw new TypeError('A secret key is required for HMAC computation');
102
+ }
103
+ if (data === null || data === undefined) {
104
+ data = '';
105
+ }
106
+ const input = Buffer.isBuffer(data) || typeof data === 'string' ? data : String(data);
107
+ const hmac = crypto.createHmac('sha256', secret).update(input);
108
+ return encoding === 'buffer' ? hmac.digest() : hmac.digest(encoding || 'hex');
109
+ }
110
+
111
+ /**
112
+ * Generate a cryptographically secure random token string or buffer.
113
+ *
114
+ * @param {number} [byteLength=32] - Number of random bytes
115
+ * @param {import('crypto').BinaryToTextEncoding|'buffer'} [encoding='hex'] - Output encoding ('hex', 'base64', 'base64url', or 'buffer')
116
+ * @returns {string|Buffer}
117
+ */
118
+ function randomToken(byteLength = 32, encoding = 'hex') {
119
+ const bytes = crypto.randomBytes(byteLength);
120
+ return encoding === 'buffer' ? bytes : bytes.toString(encoding || 'hex');
121
+ }
122
+
123
+ /**
124
+ * Generate a cryptographically secure random string with an optional prefix.
125
+ * E.g. randomId('whsec', 24) -> 'whsec_a1b2c3...'
126
+ *
127
+ * @param {string} [prefix=''] - Identifier prefix
128
+ * @param {number} [byteLength=16] - Random byte length
129
+ * @param {import('crypto').BinaryToTextEncoding} [encoding='hex'] - Output encoding
130
+ * @returns {string}
131
+ */
132
+ function randomId(prefix = '', byteLength = 16, encoding = 'hex') {
133
+ const token = randomToken(byteLength, encoding);
134
+ if (!prefix) return token;
135
+ const p = prefix.endsWith('_') ? prefix : `${prefix}_`;
136
+ return `${p}${token}`;
137
+ }
138
+
139
+ /**
140
+ * Generate a timestamped unique ID with optional prefix.
141
+ * E.g. randomTimestampedId('dlv', 8) -> 'dlv_1729221234567_abcdef1234567890'
142
+ *
143
+ * @param {string} [prefix=''] - Identifier prefix
144
+ * @param {number} [byteLength=8] - Random byte length
145
+ * @param {import('crypto').BinaryToTextEncoding} [encoding='hex'] - Output encoding
146
+ * @returns {string}
147
+ */
148
+ function randomTimestampedId(prefix = '', byteLength = 8, encoding = 'hex') {
149
+ const token = randomToken(byteLength, encoding);
150
+ const p = prefix ? (prefix.endsWith('_') ? prefix : `${prefix}_`) : '';
151
+ return `${p}${Date.now()}_${token}`;
152
+ }
153
+
154
+ /**
155
+ * Encode string or Buffer to Base64URL string (RFC 4648 §5).
156
+ *
157
+ * @param {string|Buffer|any} input
158
+ * @returns {string}
159
+ */
160
+ function base64UrlEncode(input) {
161
+ if (input === null || input === undefined) return '';
162
+ return Buffer.isBuffer(input)
163
+ ? input.toString('base64url')
164
+ : Buffer.from(String(input), 'utf8').toString('base64url');
165
+ }
166
+
167
+ /**
168
+ * Decode Base64URL string to UTF-8 string.
169
+ *
170
+ * @param {string} input
171
+ * @returns {string}
172
+ */
173
+ function base64UrlDecode(input) {
174
+ if (!input) return '';
175
+ return Buffer.from(String(input), 'base64url').toString('utf8');
176
+ }
177
+
178
+ module.exports = {
179
+ safeCompare,
180
+ timingSafeEqual: safeCompare,
181
+ sha256,
182
+ hashSha256: sha256,
183
+ hmacSha256,
184
+ createHmacSha256: hmacSha256,
185
+ randomToken,
186
+ randomId,
187
+ randomTimestampedId,
188
+ base64UrlEncode,
189
+ base64UrlDecode,
190
+ };
191
+
@@ -0,0 +1,6 @@
1
+ 'use strict';
2
+
3
+ const { ensureLeadingSlash } = require('./url');
4
+
5
+ module.exports = ensureLeadingSlash;
6
+ module.exports.ensureLeadingSlash = ensureLeadingSlash;
@@ -0,0 +1,7 @@
1
+ 'use strict';
2
+
3
+ const { escapeHtml, unescapeHtml } = require('./html');
4
+
5
+ module.exports = escapeHtml;
6
+ module.exports.escapeHtml = escapeHtml;
7
+ module.exports.unescapeHtml = unescapeHtml;
@@ -0,0 +1,7 @@
1
+ 'use strict';
2
+
3
+ const { escapeRegExp } = require('./regex');
4
+
5
+ module.exports = escapeRegExp;
6
+ module.exports.escapeRegExp = escapeRegExp;
7
+ module.exports.escapeRegex = escapeRegExp;
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Webspresso Zero-Dependency Fetch Utility
3
+ *
4
+ * Lightweight, production-grade wrapper around native `fetch` with built-in:
5
+ * - Configurable timeout with automatic AbortController
6
+ * - Seamless signal composition (external AbortSignal + timeout AbortSignal)
7
+ * - Timer unreferencing (`timer.unref()`) to prevent hanging Node.js event loop
8
+ * - Semantic error wrapping (ETIMEDOUT / TimeoutError)
9
+ * - JSON convenience helper (`fetchWithTimeout.json`)
10
+ *
11
+ * @module core/utils/fetch
12
+ */
13
+
14
+ const { parseDurationMs } = require('./time');
15
+
16
+ /**
17
+ * Executes a fetch request with timeout and abort controller support.
18
+ *
19
+ * @param {string | URL | Request} url - Target URL or Request instance
20
+ * @param {RequestInit & { timeout?: number | string }} [options] - Standard RequestInit plus optional timeout (ms or '5s')
21
+ * @returns {Promise<Response>}
22
+ */
23
+ async function fetchWithTimeout(url, options = {}) {
24
+ const { timeout = 10000, signal, ...fetchOptions } = options;
25
+
26
+ if (signal && signal.aborted) {
27
+ const reason = (signal.reason !== undefined && signal.reason !== null)
28
+ ? signal.reason
29
+ : new Error('This operation was aborted');
30
+ throw reason;
31
+ }
32
+
33
+ if (typeof AbortController === 'undefined') {
34
+ return fetch(url, { ...fetchOptions, signal });
35
+ }
36
+
37
+ const controller = new AbortController();
38
+ let timer = null;
39
+ let callerSignalListener = null;
40
+
41
+ const timeoutMs = timeout !== undefined ? parseDurationMs(timeout, 10000) : 10000;
42
+ if (typeof timeoutMs === 'number' && timeoutMs > 0) {
43
+ timer = setTimeout(() => {
44
+ const err = new Error(`Request timed out after ${timeoutMs}ms`);
45
+ err.name = 'TimeoutError';
46
+ err.code = 'ETIMEDOUT';
47
+ controller.abort(err);
48
+ }, timeoutMs);
49
+ if (timer && typeof timer.unref === 'function') {
50
+ timer.unref();
51
+ }
52
+ }
53
+
54
+ if (signal) {
55
+ callerSignalListener = () => {
56
+ controller.abort(signal.reason);
57
+ };
58
+ signal.addEventListener('abort', callerSignalListener, { once: true });
59
+ }
60
+
61
+ try {
62
+ return await fetch(url, {
63
+ ...fetchOptions,
64
+ signal: controller.signal,
65
+ });
66
+ } catch (err) {
67
+ if (controller.signal.aborted && controller.signal.reason) {
68
+ const reason = controller.signal.reason;
69
+ if (reason instanceof Error && (reason.name === 'TimeoutError' || reason.code === 'ETIMEDOUT')) {
70
+ throw reason;
71
+ }
72
+ }
73
+ if (err && err.name === 'AbortError' && controller.signal.aborted && controller.signal.reason) {
74
+ throw controller.signal.reason;
75
+ }
76
+ throw err;
77
+ } finally {
78
+ if (timer) {
79
+ clearTimeout(timer);
80
+ }
81
+ if (signal && callerSignalListener) {
82
+ signal.removeEventListener('abort', callerSignalListener);
83
+ }
84
+ }
85
+ }
86
+
87
+ /**
88
+ * Fetch with timeout and automatically parse JSON response.
89
+ *
90
+ * @param {string | URL | Request} url
91
+ * @param {RequestInit & { timeout?: number }} [options]
92
+ * @returns {Promise<{ res: Response, data: any }>}
93
+ */
94
+ fetchWithTimeout.json = async function fetchJson(url, options = {}) {
95
+ const res = await fetchWithTimeout(url, {
96
+ ...options,
97
+ headers: {
98
+ Accept: 'application/json',
99
+ ...(options.headers || {}),
100
+ },
101
+ });
102
+ let data = null;
103
+ const contentType = (res.headers && typeof res.headers.get === 'function')
104
+ ? (res.headers.get('content-type') || '')
105
+ : '';
106
+ if (contentType.includes('application/json')) {
107
+ data = await res.json();
108
+ } else {
109
+ const text = await res.text();
110
+ try {
111
+ data = JSON.parse(text);
112
+ } catch {
113
+ data = { raw: text };
114
+ }
115
+ }
116
+ return { res, data };
117
+ };
118
+
119
+ module.exports = {
120
+ fetchWithTimeout,
121
+ };
@@ -0,0 +1,144 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Webspresso - Native Filesystem & Directory Walking Utilities
5
+ * Zero-dependency recursive and flat directory scanner with configurable filters.
6
+ * @module core/utils/fs
7
+ */
8
+
9
+ const fs = require('fs');
10
+ const path = require('path');
11
+
12
+ /**
13
+ * Standard test file extensions and type declarations to ignore by default
14
+ */
15
+ const DEFAULT_TEST_SUFFIXES = [
16
+ '.test.js',
17
+ '.test.cjs',
18
+ '.test.mjs',
19
+ '.test.ts',
20
+ '.spec.js',
21
+ '.spec.cjs',
22
+ '.spec.mjs',
23
+ '.spec.ts',
24
+ '.d.ts',
25
+ ];
26
+
27
+ /**
28
+ * Recursively (or flatly) scans a directory for files matching specified criteria.
29
+ *
30
+ * @param {string} dir - Directory path to scan
31
+ * @param {Object} [options]
32
+ * @param {string[]|Set<string>|null} [options.extensions] - Allowed extensions (e.g. ['.js', '.cjs']). Null allows any extension.
33
+ * @param {boolean} [options.recursive=true] - Whether to scan subdirectories recursively
34
+ * @param {boolean} [options.ignoreTests=true] - Whether to ignore test files (.test.js, .spec.js, .d.ts)
35
+ * @param {string[]} [options.ignorePrefixes=['.', '_']] - Prefixes of files/directories to ignore
36
+ * @param {string[]} [options.ignoreNames=['node_modules']] - Exact file or directory names to ignore
37
+ * @param {Function} [options.filter] - Custom filter function (fullPath, dirent) => boolean
38
+ * @param {string} [options.baseDir] - Base directory for computing relative paths (defaults to dir)
39
+ * @param {boolean} [options.detailed=false] - If true, returns array of objects with { absolutePath, relativePath, name, ext }
40
+ * @returns {string[]|Array<{ absolutePath: string, relativePath: string, name: string, ext: string }>}
41
+ */
42
+ function walkDirectory(dir, options = {}) {
43
+ const {
44
+ extensions = null,
45
+ recursive = true,
46
+ ignoreTests = true,
47
+ ignorePrefixes = ['.', '_'],
48
+ ignoreNames = ['node_modules'],
49
+ filter = null,
50
+ baseDir = dir,
51
+ detailed = false,
52
+ } = options;
53
+
54
+ if (!dir || typeof dir !== 'string') return [];
55
+
56
+ const resolvedDir = path.resolve(dir);
57
+ if (!fs.existsSync(resolvedDir)) return [];
58
+
59
+ const extSet = extensions
60
+ ? new Set(Array.from(extensions).map(e => (e.startsWith('.') ? e.toLowerCase() : `.${e.toLowerCase()}`)))
61
+ : null;
62
+
63
+ const results = [];
64
+ const resolvedBase = path.resolve(baseDir);
65
+
66
+ function walk(currentDir) {
67
+ let entries;
68
+ try {
69
+ entries = fs.readdirSync(currentDir, { withFileTypes: true });
70
+ } catch (_) {
71
+ return;
72
+ }
73
+
74
+ for (const entry of entries) {
75
+ const name = entry.name;
76
+
77
+ // Ignore specified exact names (e.g. 'node_modules')
78
+ if (ignoreNames && ignoreNames.includes(name)) {
79
+ continue;
80
+ }
81
+
82
+ // Ignore specified prefixes (e.g. '.' or '_')
83
+ if (ignorePrefixes && ignorePrefixes.some(prefix => name.startsWith(prefix))) {
84
+ continue;
85
+ }
86
+
87
+ const fullPath = path.join(currentDir, name);
88
+
89
+ if (entry.isDirectory()) {
90
+ if (recursive) {
91
+ walk(fullPath);
92
+ }
93
+ } else if (entry.isFile()) {
94
+ const ext = path.extname(name).toLowerCase();
95
+
96
+ // Check extensions if specified
97
+ if (extSet && !extSet.has(ext)) {
98
+ continue;
99
+ }
100
+
101
+ // Check test file suffixes
102
+ if (ignoreTests && DEFAULT_TEST_SUFFIXES.some(suffix => name.toLowerCase().endsWith(suffix))) {
103
+ continue;
104
+ }
105
+
106
+ // Custom filter function
107
+ if (typeof filter === 'function' && !filter(fullPath, entry)) {
108
+ continue;
109
+ }
110
+
111
+ if (detailed) {
112
+ const relPath = path.relative(resolvedBase, fullPath).split(path.sep).join('/');
113
+ results.push({
114
+ absolutePath: fullPath,
115
+ relativePath: relPath,
116
+ name,
117
+ ext,
118
+ });
119
+ } else {
120
+ results.push(fullPath);
121
+ }
122
+ }
123
+ }
124
+ }
125
+
126
+ walk(resolvedDir);
127
+ return results;
128
+ }
129
+
130
+ /**
131
+ * Convenient wrapper for walkDirectory with detailed: true
132
+ * @param {string} dir
133
+ * @param {Object} [options]
134
+ * @returns {Array<{ absolutePath: string, relativePath: string, name: string, ext: string }>}
135
+ */
136
+ function walkDirectoryDetailed(dir, options = {}) {
137
+ return walkDirectory(dir, { ...options, detailed: true });
138
+ }
139
+
140
+ module.exports = {
141
+ walkDirectory,
142
+ walkDirectoryDetailed,
143
+ DEFAULT_TEST_SUFFIXES,
144
+ };
@@ -0,0 +1,6 @@
1
+ 'use strict';
2
+
3
+ const { getClientIp } = require('./ip');
4
+
5
+ module.exports = getClientIp;
6
+ module.exports.getClientIp = getClientIp;
@@ -0,0 +1,6 @@
1
+ 'use strict';
2
+
3
+ const { hmacSha256 } = require('./crypto');
4
+
5
+ module.exports = hmacSha256;
6
+ module.exports.hmacSha256 = hmacSha256;
@@ -0,0 +1,72 @@
1
+ /**
2
+ * Webspresso Zero-Dependency HTML Utilities
3
+ *
4
+ * High-performance, XSS-safe HTML entity escaping and unescaping.
5
+ *
6
+ * @module core/utils/html
7
+ */
8
+
9
+ 'use strict';
10
+
11
+ const HTML_ESCAPE_TEST_RE = /[&<>"']/;
12
+ const HTML_ESCAPE_RE = /[&<>"']/g;
13
+
14
+ const HTML_ESCAPES = {
15
+ '&': '&amp;',
16
+ '<': '&lt;',
17
+ '>': '&gt;',
18
+ '"': '&quot;',
19
+ "'": '&#39;',
20
+ };
21
+
22
+ const HTML_UNESCAPE_RE = /&(?:amp|lt|gt|quot|#39|#039|#x27);/g;
23
+
24
+ const HTML_UNESCAPES = {
25
+ '&amp;': '&',
26
+ '&lt;': '<',
27
+ '&gt;': '>',
28
+ '&quot;': '"',
29
+ '&#39;': "'",
30
+ '&#039;': "'",
31
+ '&#x27;': "'",
32
+ };
33
+
34
+ /**
35
+ * Escapes characters with special meaning in HTML to prevent XSS injection attacks.
36
+ * Fast-paths strings without special characters to avoid unnecessary allocations.
37
+ *
38
+ * @param {unknown} value - Value to escape (converted to string; null/undefined becomes '')
39
+ * @returns {string} HTML-escaped string
40
+ */
41
+ function escapeHtml(value) {
42
+ if (value === null || value === undefined) {
43
+ return '';
44
+ }
45
+
46
+ const str = typeof value === 'string' ? value : String(value);
47
+ if (!HTML_ESCAPE_TEST_RE.test(str)) {
48
+ return str;
49
+ }
50
+
51
+ return str.replace(HTML_ESCAPE_RE, (char) => HTML_ESCAPES[char]);
52
+ }
53
+
54
+ /**
55
+ * Unescapes common HTML entities back to their literal character representations.
56
+ *
57
+ * @param {unknown} value - HTML string to unescape
58
+ * @returns {string} Unescaped string
59
+ */
60
+ function unescapeHtml(value) {
61
+ if (value === null || value === undefined) {
62
+ return '';
63
+ }
64
+
65
+ const str = typeof value === 'string' ? value : String(value);
66
+ return str.replace(HTML_UNESCAPE_RE, (match) => HTML_UNESCAPES[match] || match);
67
+ }
68
+
69
+ module.exports = {
70
+ escapeHtml,
71
+ unescapeHtml,
72
+ };
@@ -0,0 +1,86 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Universal Client IP Extraction Utility
5
+ * Safely extracts client IP address with proxy support, header normalizations,
6
+ * and customizable fallbacks.
7
+ *
8
+ * Precedence:
9
+ * 1. x-forwarded-for header (first IP if comma-separated or array)
10
+ * 2. x-real-ip header
11
+ * 3. req.ip (Express trust proxy / custom assignment)
12
+ * 4. req.connection.remoteAddress
13
+ * 5. req.socket.remoteAddress
14
+ * 6. req.info.remoteAddress (Fastify/Hapi compatibility)
15
+ * 7. fallback (defaults to '127.0.0.1' if not explicitly provided)
16
+ *
17
+ * @param {Object} [req] - Express / Node.js HTTP request object
18
+ * @param {any} [fallback='127.0.0.1'] - Fallback value if no IP could be extracted
19
+ * @returns {any}
20
+ */
21
+ function getClientIp(req, fallback) {
22
+ const defaultFallback = arguments.length > 1 ? fallback : '127.0.0.1';
23
+ if (!req || typeof req !== 'object') {
24
+ return defaultFallback;
25
+ }
26
+
27
+ const headers = req.headers;
28
+
29
+ // 1. x-forwarded-for (can be string or array in Node HTTP/proxies)
30
+ let forwarded = headers ? (headers['x-forwarded-for'] || headers['X-Forwarded-For']) : undefined;
31
+ if (!forwarded && typeof req.get === 'function') {
32
+ forwarded = req.get('x-forwarded-for');
33
+ }
34
+
35
+ if (forwarded) {
36
+ const ips = typeof forwarded === 'string' ? forwarded.split(',') : forwarded;
37
+ const first = Array.isArray(ips) ? ips[0] : ips;
38
+ if (first && typeof first === 'string') {
39
+ const trimmed = first.trim();
40
+ if (trimmed) return trimmed;
41
+ }
42
+ }
43
+
44
+ // 2. x-real-ip
45
+ let realIp = headers ? (headers['x-real-ip'] || headers['X-Real-IP']) : undefined;
46
+ if (!realIp && typeof req.get === 'function') {
47
+ realIp = req.get('x-real-ip');
48
+ }
49
+ if (realIp && typeof realIp === 'string') {
50
+ const trimmed = realIp.trim();
51
+ if (trimmed) return trimmed;
52
+ }
53
+
54
+ // 3. req.ip
55
+ if (req.ip && typeof req.ip === 'string') {
56
+ const trimmed = req.ip.trim();
57
+ if (trimmed) return trimmed;
58
+ }
59
+
60
+ // 4. req.connection.remoteAddress
61
+ const connAddr = req.connection && req.connection.remoteAddress;
62
+ if (connAddr && typeof connAddr === 'string') {
63
+ const trimmed = connAddr.trim();
64
+ if (trimmed) return trimmed;
65
+ }
66
+
67
+ // 5. req.socket.remoteAddress
68
+ const sockAddr = req.socket && req.socket.remoteAddress;
69
+ if (sockAddr && typeof sockAddr === 'string') {
70
+ const trimmed = sockAddr.trim();
71
+ if (trimmed) return trimmed;
72
+ }
73
+
74
+ // 6. req.info.remoteAddress (Fastify/Hapi compatibility)
75
+ const infoAddr = req.info && req.info.remoteAddress;
76
+ if (infoAddr && typeof infoAddr === 'string') {
77
+ const trimmed = infoAddr.trim();
78
+ if (trimmed) return trimmed;
79
+ }
80
+
81
+ return defaultFallback;
82
+ }
83
+
84
+ module.exports = {
85
+ getClientIp,
86
+ };