indusagi-coding-agent 0.1.23 → 0.1.25

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 (236) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/README.md +2 -0
  3. package/dist/cli/args.d.ts +117 -1
  4. package/dist/cli/args.d.ts.map +1 -1
  5. package/dist/cli/args.js +221 -52
  6. package/dist/cli/args.js.map +1 -1
  7. package/dist/cli/config-selector.d.ts +58 -2
  8. package/dist/cli/config-selector.d.ts.map +1 -1
  9. package/dist/cli/config-selector.js +130 -12
  10. package/dist/cli/config-selector.js.map +1 -1
  11. package/dist/cli/file-processor.d.ts +70 -2
  12. package/dist/cli/file-processor.d.ts.map +1 -1
  13. package/dist/cli/file-processor.js +240 -15
  14. package/dist/cli/file-processor.js.map +1 -1
  15. package/dist/cli/list-models.d.ts +63 -3
  16. package/dist/cli/list-models.d.ts.map +1 -1
  17. package/dist/cli/list-models.js +202 -27
  18. package/dist/cli/list-models.js.map +1 -1
  19. package/dist/cli/login-handler.d.ts +82 -8
  20. package/dist/cli/login-handler.d.ts.map +1 -1
  21. package/dist/cli/login-handler.js +410 -77
  22. package/dist/cli/login-handler.js.map +1 -1
  23. package/dist/cli/session-picker.d.ts +74 -2
  24. package/dist/cli/session-picker.d.ts.map +1 -1
  25. package/dist/cli/session-picker.js +236 -12
  26. package/dist/cli/session-picker.js.map +1 -1
  27. package/dist/core/agent-session.d.ts +214 -9
  28. package/dist/core/agent-session.d.ts.map +1 -1
  29. package/dist/core/agent-session.js +214 -9
  30. package/dist/core/agent-session.js.map +1 -1
  31. package/dist/core/bash-executor.d.ts +302 -12
  32. package/dist/core/bash-executor.d.ts.map +1 -1
  33. package/dist/core/bash-executor.js +302 -12
  34. package/dist/core/bash-executor.js.map +1 -1
  35. package/dist/core/diagnostics.d.ts +191 -0
  36. package/dist/core/diagnostics.d.ts.map +1 -1
  37. package/dist/core/diagnostics.js +142 -0
  38. package/dist/core/diagnostics.js.map +1 -1
  39. package/dist/core/discover-packages.d.ts +6 -0
  40. package/dist/core/discover-packages.d.ts.map +1 -0
  41. package/dist/core/discover-packages.js +62 -0
  42. package/dist/core/discover-packages.js.map +1 -0
  43. package/dist/core/event-bus.d.ts +146 -0
  44. package/dist/core/event-bus.d.ts.map +1 -1
  45. package/dist/core/event-bus.js +93 -0
  46. package/dist/core/event-bus.js.map +1 -1
  47. package/dist/core/export-html/ansi-to-html.d.ts +4 -0
  48. package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
  49. package/dist/core/export-html/ansi-to-html.js +4 -0
  50. package/dist/core/export-html/ansi-to-html.js.map +1 -1
  51. package/dist/core/export-html/index.d.ts +128 -0
  52. package/dist/core/export-html/index.d.ts.map +1 -1
  53. package/dist/core/export-html/index.js +128 -0
  54. package/dist/core/export-html/index.js.map +1 -1
  55. package/dist/core/export-html/tool-renderer.d.ts +4 -0
  56. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  57. package/dist/core/export-html/tool-renderer.js +4 -0
  58. package/dist/core/export-html/tool-renderer.js.map +1 -1
  59. package/dist/core/keybindings.d.ts +142 -0
  60. package/dist/core/keybindings.d.ts.map +1 -1
  61. package/dist/core/keybindings.js +142 -0
  62. package/dist/core/keybindings.js.map +1 -1
  63. package/dist/core/model-registry.d.ts +98 -1
  64. package/dist/core/model-registry.d.ts.map +1 -1
  65. package/dist/core/model-registry.js +98 -1
  66. package/dist/core/model-registry.js.map +1 -1
  67. package/dist/core/model-resolver.d.ts +99 -1
  68. package/dist/core/model-resolver.d.ts.map +1 -1
  69. package/dist/core/model-resolver.js +99 -1
  70. package/dist/core/model-resolver.js.map +1 -1
  71. package/dist/core/prompt-templates.js.map +1 -1
  72. package/dist/core/sdk.d.ts.map +1 -1
  73. package/dist/core/sdk.js +2 -0
  74. package/dist/core/sdk.js.map +1 -1
  75. package/dist/core/session-manager.d.ts +127 -0
  76. package/dist/core/session-manager.d.ts.map +1 -1
  77. package/dist/core/session-manager.js +125 -0
  78. package/dist/core/session-manager.js.map +1 -1
  79. package/dist/core/skills.js.map +1 -1
  80. package/dist/core/subagents.js.map +1 -1
  81. package/dist/core/tools/bash.d.ts +391 -11
  82. package/dist/core/tools/bash.d.ts.map +1 -1
  83. package/dist/core/tools/bash.js +269 -2
  84. package/dist/core/tools/bash.js.map +1 -1
  85. package/dist/core/tools/bg-process.d.ts +49 -0
  86. package/dist/core/tools/bg-process.d.ts.map +1 -0
  87. package/dist/core/tools/bg-process.js +69 -0
  88. package/dist/core/tools/bg-process.js.map +1 -0
  89. package/dist/core/tools/edit.d.ts +284 -6
  90. package/dist/core/tools/edit.d.ts.map +1 -1
  91. package/dist/core/tools/edit.js +238 -0
  92. package/dist/core/tools/edit.js.map +1 -1
  93. package/dist/core/tools/find.d.ts +169 -5
  94. package/dist/core/tools/find.d.ts.map +1 -1
  95. package/dist/core/tools/find.js +136 -0
  96. package/dist/core/tools/find.js.map +1 -1
  97. package/dist/core/tools/grep.d.ts +285 -5
  98. package/dist/core/tools/grep.d.ts.map +1 -1
  99. package/dist/core/tools/grep.js +247 -0
  100. package/dist/core/tools/grep.js.map +1 -1
  101. package/dist/core/tools/index.d.ts +45 -0
  102. package/dist/core/tools/index.d.ts.map +1 -1
  103. package/dist/core/tools/index.js +15 -0
  104. package/dist/core/tools/index.js.map +1 -1
  105. package/dist/core/tools/ls.d.ts +6 -0
  106. package/dist/core/tools/ls.d.ts.map +1 -1
  107. package/dist/core/tools/ls.js +6 -0
  108. package/dist/core/tools/ls.js.map +1 -1
  109. package/dist/core/tools/read.d.ts +308 -7
  110. package/dist/core/tools/read.d.ts.map +1 -1
  111. package/dist/core/tools/read.js +231 -0
  112. package/dist/core/tools/read.js.map +1 -1
  113. package/dist/core/tools/registry.d.ts +17 -0
  114. package/dist/core/tools/registry.d.ts.map +1 -0
  115. package/dist/core/tools/registry.js +108 -0
  116. package/dist/core/tools/registry.js.map +1 -0
  117. package/dist/core/tools/webfetch.d.ts +118 -3
  118. package/dist/core/tools/webfetch.d.ts.map +1 -1
  119. package/dist/core/tools/webfetch.js +118 -3
  120. package/dist/core/tools/webfetch.js.map +1 -1
  121. package/dist/core/tools/websearch.d.ts +130 -3
  122. package/dist/core/tools/websearch.d.ts.map +1 -1
  123. package/dist/core/tools/websearch.js +130 -3
  124. package/dist/core/tools/websearch.js.map +1 -1
  125. package/dist/core/tools/write.d.ts +251 -5
  126. package/dist/core/tools/write.d.ts.map +1 -1
  127. package/dist/core/tools/write.js +210 -0
  128. package/dist/core/tools/write.js.map +1 -1
  129. package/dist/main.d.ts.map +1 -1
  130. package/dist/main.js +12 -1
  131. package/dist/main.js.map +1 -1
  132. package/dist/modes/interactive/components/assistant-message.d.ts +164 -1
  133. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  134. package/dist/modes/interactive/components/assistant-message.js +164 -1
  135. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  136. package/dist/modes/interactive/components/bash-execution.d.ts +297 -1
  137. package/dist/modes/interactive/components/bash-execution.d.ts.map +1 -1
  138. package/dist/modes/interactive/components/bash-execution.js +297 -1
  139. package/dist/modes/interactive/components/bash-execution.js.map +1 -1
  140. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  141. package/dist/modes/interactive/components/tool-execution.js +251 -1
  142. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  143. package/dist/modes/interactive/components/user-message.d.ts +186 -1
  144. package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
  145. package/dist/modes/interactive/components/user-message.js +186 -1
  146. package/dist/modes/interactive/components/user-message.js.map +1 -1
  147. package/dist/modes/interactive/interactive-mode.d.ts +1567 -13
  148. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  149. package/dist/modes/interactive/interactive-mode.js +1567 -13
  150. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  151. package/dist/modes/interactive/theme/theme.d.ts +422 -0
  152. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  153. package/dist/modes/interactive/theme/theme.js +422 -0
  154. package/dist/modes/interactive/theme/theme.js.map +1 -1
  155. package/dist/modes/print-mode.d.ts +538 -5
  156. package/dist/modes/print-mode.d.ts.map +1 -1
  157. package/dist/modes/print-mode.js +538 -5
  158. package/dist/modes/print-mode.js.map +1 -1
  159. package/dist/modes/rpc/rpc-client.d.ts +921 -8
  160. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  161. package/dist/modes/rpc/rpc-client.js +921 -8
  162. package/dist/modes/rpc/rpc-client.js.map +1 -1
  163. package/dist/modes/rpc/rpc-mode.d.ts +802 -9
  164. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  165. package/dist/modes/rpc/rpc-mode.js +802 -9
  166. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  167. package/dist/modes/rpc/rpc-types.d.ts +356 -3
  168. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  169. package/dist/modes/rpc/rpc-types.js +356 -3
  170. package/dist/modes/rpc/rpc-types.js.map +1 -1
  171. package/dist/modes/shared.d.ts +386 -0
  172. package/dist/modes/shared.d.ts.map +1 -0
  173. package/dist/modes/shared.js +543 -0
  174. package/dist/modes/shared.js.map +1 -0
  175. package/dist/utils/array.d.ts +389 -0
  176. package/dist/utils/array.d.ts.map +1 -0
  177. package/dist/utils/array.js +585 -0
  178. package/dist/utils/array.js.map +1 -0
  179. package/dist/utils/color-formatter.d.ts +318 -0
  180. package/dist/utils/color-formatter.d.ts.map +1 -0
  181. package/dist/utils/color-formatter.js +442 -0
  182. package/dist/utils/color-formatter.js.map +1 -0
  183. package/dist/utils/data-transformer.d.ts +326 -0
  184. package/dist/utils/data-transformer.d.ts.map +1 -0
  185. package/dist/utils/data-transformer.js +512 -0
  186. package/dist/utils/data-transformer.js.map +1 -0
  187. package/dist/utils/date-formatter.d.ts +281 -0
  188. package/dist/utils/date-formatter.d.ts.map +1 -0
  189. package/dist/utils/date-formatter.js +503 -0
  190. package/dist/utils/date-formatter.js.map +1 -0
  191. package/dist/utils/error-handler.d.ts +541 -0
  192. package/dist/utils/error-handler.d.ts.map +1 -0
  193. package/dist/utils/error-handler.js +726 -0
  194. package/dist/utils/error-handler.js.map +1 -0
  195. package/dist/utils/file-operations.d.ts +297 -0
  196. package/dist/utils/file-operations.d.ts.map +1 -0
  197. package/dist/utils/file-operations.js +505 -0
  198. package/dist/utils/file-operations.js.map +1 -0
  199. package/dist/utils/frontmatter.d.ts +268 -6
  200. package/dist/utils/frontmatter.d.ts.map +1 -1
  201. package/dist/utils/frontmatter.js +500 -21
  202. package/dist/utils/frontmatter.js.map +1 -1
  203. package/dist/utils/json-formatter.d.ts +259 -0
  204. package/dist/utils/json-formatter.d.ts.map +1 -0
  205. package/dist/utils/json-formatter.js +517 -0
  206. package/dist/utils/json-formatter.js.map +1 -0
  207. package/dist/utils/logger.d.ts +176 -0
  208. package/dist/utils/logger.d.ts.map +1 -0
  209. package/dist/utils/logger.js +346 -0
  210. package/dist/utils/logger.js.map +1 -0
  211. package/dist/utils/markdown-formatter.d.ts +211 -0
  212. package/dist/utils/markdown-formatter.d.ts.map +1 -0
  213. package/dist/utils/markdown-formatter.js +482 -0
  214. package/dist/utils/markdown-formatter.js.map +1 -0
  215. package/dist/utils/path-validator.d.ts +603 -0
  216. package/dist/utils/path-validator.d.ts.map +1 -0
  217. package/dist/utils/path-validator.js +870 -0
  218. package/dist/utils/path-validator.js.map +1 -0
  219. package/dist/utils/string-formatter.d.ts +609 -0
  220. package/dist/utils/string-formatter.d.ts.map +1 -0
  221. package/dist/utils/string-formatter.js +806 -0
  222. package/dist/utils/string-formatter.js.map +1 -0
  223. package/dist/utils/type-guards.d.ts +629 -0
  224. package/dist/utils/type-guards.d.ts.map +1 -0
  225. package/dist/utils/type-guards.js +662 -0
  226. package/dist/utils/type-guards.js.map +1 -0
  227. package/docs/COMPLETE-GUIDE.md +300 -0
  228. package/docs/COMPREHENSIVE-CLI-SUMMARY.md +900 -0
  229. package/docs/MODES-ARCHITECTURE.md +565 -0
  230. package/docs/PRINT-MODE-GUIDE.md +456 -0
  231. package/docs/RPC-GUIDE.md +705 -0
  232. package/docs/UTILS-IMPLEMENTATION-SUMMARY.md +647 -0
  233. package/docs/UTILS-MODULE-OVERVIEW.md +1480 -0
  234. package/docs/UTILS-QA-CHECKLIST.md +1061 -0
  235. package/docs/UTILS-USAGE-GUIDE.md +1419 -0
  236. package/package.json +7 -3
@@ -0,0 +1 @@
1
+ {"version":3,"file":"markdown-formatter.js","sourceRoot":"","sources":["../../src/utils/markdown-formatter.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,603 @@
1
+ /**
2
+ * @fileoverview Path Validation and Normalization Utilities
3
+ *
4
+ * **SECURITY FOCUSED**: This module provides secure path handling to prevent
5
+ * common path traversal and directory escape vulnerabilities.
6
+ *
7
+ * Common Path Vulnerabilities Addressed:
8
+ * - Directory traversal (../../) attacks
9
+ * - Symlink following (TOCTOU - Time-of-Check-Time-of-Use)
10
+ * - Path normalization bypasses
11
+ * - Null byte injection (\0)
12
+ * - Mixed slash handling (Windows vs Unix)
13
+ * - Relative path escape patterns
14
+ *
15
+ * SECURITY PRINCIPLES:
16
+ * 1. Always validate and normalize paths before file operations
17
+ * 2. Prevent directory traversal with ".." and "." resolution
18
+ * 3. Resolve symlinks to detect jail breaks
19
+ * 4. Whitelist allowed directories when possible
20
+ * 5. Never trust user-supplied paths directly
21
+ *
22
+ * This module provides type-safe, well-tested functions for:
23
+ * - Path safety validation and sanitization
24
+ * - Secure path resolution and normalization
25
+ * - Path component extraction
26
+ * - Cross-platform path handling
27
+ * - Symlink and traversal detection
28
+ *
29
+ * @example
30
+ * // SAFE: Validate before use
31
+ * if (isPathSafe(userPath, baseDir)) {
32
+ * const fullPath = joinSafe(baseDir, userPath);
33
+ * // Safe to use fullPath
34
+ * }
35
+ *
36
+ * @example
37
+ * // UNSAFE: Direct concatenation - vulnerable to path traversal
38
+ * const fullPath = baseDir + '/' + userPath; // DON'T DO THIS
39
+ *
40
+ * @example
41
+ * // SAFE: Use validation helpers
42
+ * validatePath(userPath, { allowRelative: true, base: '/app/uploads' });
43
+ * const dir = getDirName(path);
44
+ * const name = getFileName(path);
45
+ */
46
+ /**
47
+ * Path validation options
48
+ */
49
+ export interface PathValidationOptions {
50
+ /** Base directory for relative path resolution */
51
+ base?: string;
52
+ /** Allow relative paths (default: false) */
53
+ allowRelative?: boolean;
54
+ /** Allow symlinks (default: false - security) */
55
+ allowSymlinks?: boolean;
56
+ /** Allow hidden files starting with . (default: false) */
57
+ allowHidden?: boolean;
58
+ /** Maximum allowed path length in characters (default: 4096) */
59
+ maxLength?: number;
60
+ }
61
+ /**
62
+ * Path validation result with detailed information
63
+ */
64
+ export interface PathValidationResult {
65
+ /** Whether the path is valid */
66
+ valid: boolean;
67
+ /** Error message if invalid */
68
+ error?: string;
69
+ /** Resolved absolute path */
70
+ resolved?: string;
71
+ /** Whether path contains symlinks */
72
+ hasSymlinks?: boolean;
73
+ /** Whether path is within allowed base */
74
+ isWithinBase?: boolean;
75
+ }
76
+ /**
77
+ * SECURITY: Checks if a path is safe for operations
78
+ *
79
+ * This is the primary security function - use before ANY file operation.
80
+ * Prevents:
81
+ * - Directory traversal (../../etc/passwd)
82
+ * - Absolute path bypass
83
+ * - Symlink attacks
84
+ * - Path normalization bypass
85
+ *
86
+ * @param pathStr - Path to validate
87
+ * @param baseDir - Optional base directory for restriction
88
+ * @returns true if path is safe, false otherwise
89
+ *
90
+ * @example
91
+ * // SAFE: Check user-supplied path
92
+ * const userInput = req.query.file;
93
+ * if (isPathSafe(userInput, '/app/uploads')) {
94
+ * const fullPath = path.join('/app/uploads', userInput);
95
+ * const data = fs.readFileSync(fullPath); // Safe
96
+ * }
97
+ *
98
+ * @example
99
+ * // UNSAFE: Allows directory traversal
100
+ * const fullPath = path.join('/app/uploads', userInput); // DON'T - no validation
101
+ * const data = fs.readFileSync(fullPath);
102
+ *
103
+ * @example
104
+ * // UNSAFE PATHS (returns false)
105
+ * isPathSafe('../../../etc/passwd') // true -> prevents escape
106
+ * isPathSafe('/etc/passwd', '/app') // false -> absolute outside base
107
+ * isPathSafe('../../file.txt') // false -> traversal attempt
108
+ * isPathSafe('./file.txt', '/app') // true -> safe relative
109
+ *
110
+ * @edge-cases
111
+ * - Empty path returns true (cwd)
112
+ * - Resolves .. but only within base directory
113
+ * - Strips null bytes (\0) - potential injection
114
+ * - Windows paths with backslashes normalized to forward slashes
115
+ *
116
+ * @security-notes
117
+ * - Use this function BEFORE every file operation with user input
118
+ * - Does NOT check file existence
119
+ * - For maximum security, use with baseDir parameter
120
+ * - Be aware of TOCTOU: file can change between check and use
121
+ */
122
+ export declare function isPathSafe(pathStr: string, baseDir?: string): boolean;
123
+ /**
124
+ * SECURITY: Comprehensive path validation with detailed results
125
+ *
126
+ * Use this for detailed validation and error reporting.
127
+ * Returns structured result with specific error information.
128
+ *
129
+ * @param pathStr - Path to validate
130
+ * @param options - Validation options
131
+ * @returns Detailed validation result
132
+ *
133
+ * @example
134
+ * // Validate with full options
135
+ * const result = validatePath(userPath, {
136
+ * base: '/app/uploads',
137
+ * allowRelative: true,
138
+ * allowSymlinks: false,
139
+ * maxLength: 255,
140
+ * });
141
+ *
142
+ * if (!result.valid) {
143
+ * console.error(result.error);
144
+ * // Reject the request
145
+ * }
146
+ *
147
+ * @example
148
+ * // Check for symlinks and traversal
149
+ * const result = validatePath('../../secret.txt', {
150
+ * base: '/app/data',
151
+ * allowSymlinks: false,
152
+ * });
153
+ * // result.valid === false
154
+ * // result.error mentions directory traversal
155
+ *
156
+ * @edge-cases
157
+ * - Symlink detection requires filesystem access
158
+ * - May be expensive for deeply nested paths
159
+ * - Resolved path is provided even if invalid (for debugging)
160
+ */
161
+ export declare function validatePath(pathStr: string, options?: PathValidationOptions): PathValidationResult;
162
+ /**
163
+ * SECURITY: Normalizes a path to prevent traversal bypass
164
+ *
165
+ * Removes redundant separators and resolves . and .. patterns.
166
+ * Critical for preventing normalized path bypass attacks.
167
+ *
168
+ * @param pathStr - Path to normalize
169
+ * @returns Normalized path
170
+ *
171
+ * @example
172
+ * normalizePath('./foo/../bar') // "bar"
173
+ * normalizePath('foo//bar') // "foo/bar"
174
+ * normalizePath('foo/./bar') // "foo/bar"
175
+ * normalizePath('\\foo\\bar') // "foo/bar" (Windows)
176
+ * normalizePath('') // "."
177
+ * normalizePath('/absolute/./path') // "/absolute/path"
178
+ * normalizePath('foo/../../bar') // "../bar"
179
+ *
180
+ * @edge-cases
181
+ * - Normalizes both forward and backslashes (Windows/Unix)
182
+ * - Preserves absolute path status
183
+ * - Collapses .. patterns (may escape if outside boundary)
184
+ * - Use isPathSafe() to prevent escape with .. patterns
185
+ *
186
+ * @security-notes
187
+ * - This ALONE doesn't prevent attacks
188
+ * - Use with isPathSafe() for full protection
189
+ * - Directory traversal requires checking against base dir
190
+ */
191
+ export declare function normalizePath(pathStr: string): string;
192
+ /**
193
+ * SECURITY: Safely joins path segments with base directory
194
+ *
195
+ * Validates each segment against directory traversal before joining.
196
+ * Preferred over path.join() for security-sensitive code.
197
+ *
198
+ * @param base - Base directory (absolute path)
199
+ * @param ...segments - Path segments to join
200
+ * @returns Safely joined path, or throws if unsafe
201
+ *
202
+ * @example
203
+ * // SAFE: Returns '/app/uploads/user-file.txt'
204
+ * joinSafe('/app/uploads', 'user-file.txt')
205
+ *
206
+ * @example
207
+ * // UNSAFE: Throws error
208
+ * try {
209
+ * joinSafe('/app/uploads', '../../etc/passwd')
210
+ * } catch (e) {
211
+ * console.log('Traversal attempt blocked')
212
+ * }
213
+ *
214
+ * @example
215
+ * // SAFE: Multiple segments
216
+ * joinSafe('/app', 'uploads', 'users', 'file.txt')
217
+ * // -> '/app/uploads/users/file.txt'
218
+ *
219
+ * @example
220
+ * // UNSAFE: Symlink in path (if allowSymlinks: false)
221
+ * joinSafe('/app', './link-to-escape')
222
+ * // throws if link escapes /app
223
+ *
224
+ * @throws Error if any segment is unsafe for the given base
225
+ *
226
+ * @security-notes
227
+ * - Base directory must be absolute
228
+ * - Each segment is validated independently
229
+ * - Throws on traversal attempts (fail-safe)
230
+ * - Suitable for file server implementations
231
+ */
232
+ export declare function joinSafe(base: string, ...segments: string[]): string;
233
+ /**
234
+ * SECURITY: Resolves a path safely relative to a base directory
235
+ *
236
+ * Like joinSafe but returns resolved path. Better for cases
237
+ * where the target path must be within base (sandboxing).
238
+ *
239
+ * @param pathStr - Path to resolve
240
+ * @param baseDir - Base directory for restriction
241
+ * @returns Resolved absolute path
242
+ *
243
+ * @example
244
+ * resolvePath('uploads/file.txt', '/app')
245
+ * // -> '/app/uploads/file.txt'
246
+ *
247
+ * @example
248
+ * // Throws: attempts escape
249
+ * resolvePath('../../etc/passwd', '/app')
250
+ *
251
+ * @throws Error if path attempts to escape base directory
252
+ *
253
+ * @security-notes
254
+ * - For sandboxing / jail implementations
255
+ * - Always validate user input
256
+ * - Return error, don't expose real paths
257
+ */
258
+ export declare function resolvePath(pathStr: string, baseDir: string): string;
259
+ /**
260
+ * Returns whether a path is absolute (not relative)
261
+ *
262
+ * Works consistently across Windows and Unix.
263
+ *
264
+ * @param pathStr - Path to check
265
+ * @returns true if absolute, false if relative
266
+ *
267
+ * @example
268
+ * isAbsolutePath('/home/user') // true
269
+ * isAbsolutePath('C:\\Users\\User') // true (Windows)
270
+ * isAbsolutePath('./relative') // false
271
+ * isAbsolutePath('relative/path') // false
272
+ * isAbsolutePath('') // false
273
+ *
274
+ * @edge-cases
275
+ * - Windows drive letters (C:\) are absolute
276
+ * - UNC paths (\\server\share) are absolute
277
+ * - Relative paths with ./ prefix are still relative
278
+ */
279
+ export declare function isAbsolutePath(pathStr: string): boolean;
280
+ /**
281
+ * Returns whether a path is relative (not absolute)
282
+ *
283
+ * Inverse of isAbsolutePath.
284
+ *
285
+ * @param pathStr - Path to check
286
+ * @returns true if relative, false if absolute
287
+ *
288
+ * @example
289
+ * isRelativePath('./file') // true
290
+ * isRelativePath('file.txt') // true
291
+ * isRelativePath('dir/file') // true
292
+ * isRelativePath('/absolute') // false
293
+ * isRelativePath('') // true
294
+ *
295
+ * @edge-cases
296
+ * - Relative paths may escape with .. patterns
297
+ * - Empty string is technically relative
298
+ */
299
+ export declare function isRelativePath(pathStr: string): boolean;
300
+ /**
301
+ * Extracts the file name from a path (including extension)
302
+ *
303
+ * Safe extraction of filename from path.
304
+ *
305
+ * @param pathStr - Full path
306
+ * @returns File name without directory
307
+ *
308
+ * @example
309
+ * getFileName('/home/user/file.txt') // "file.txt"
310
+ * getFileName('file.txt') // "file.txt"
311
+ * getFileName('/home/user/') // "" (directory path)
312
+ * getFileName('/home/user/doc.tar.gz') // "doc.tar.gz"
313
+ * getFileName('') // ""
314
+ * getFileName('.gitignore') // ".gitignore"
315
+ *
316
+ * @edge-cases
317
+ * - Returns empty string for directory paths
318
+ * - Preserves multiple extensions
319
+ */
320
+ export declare function getFileName(pathStr: string): string;
321
+ /**
322
+ * Extracts the directory path without the file name
323
+ *
324
+ * Returns the directory containing the file.
325
+ *
326
+ * @param pathStr - Full path
327
+ * @returns Directory path
328
+ *
329
+ * @example
330
+ * getDirName('/home/user/file.txt') // "/home/user"
331
+ * getDirName('file.txt') // "." (current directory)
332
+ * getDirName('/home/user/') // "/home/user"
333
+ * getDirName('') // "."
334
+ * getDirName('/') // "/" (root)
335
+ *
336
+ * @edge-cases
337
+ * - Returns "." for relative paths without directory
338
+ * - Trailing slashes are normalized
339
+ */
340
+ export declare function getDirName(pathStr: string): string;
341
+ /**
342
+ * Extracts the file extension (without the dot)
343
+ *
344
+ * Gets the extension of a file.
345
+ *
346
+ * @param pathStr - File path
347
+ * @returns Extension without dot, or empty string
348
+ *
349
+ * @example
350
+ * getFileExtension('/home/user/file.txt') // "txt"
351
+ * getFileExtension('archive.tar.gz') // "gz"
352
+ * getFileExtension('file') // ""
353
+ * getFileExtension('.gitignore') // ""
354
+ * getFileExtension('/path/.hidden') // ""
355
+ * getFileExtension('') // ""
356
+ *
357
+ * @edge-cases
358
+ * - Hidden files starting with . don't have extension
359
+ * - Returns only the last extension (use custom parser for .tar.gz)
360
+ * - Case preserved (not lowercased)
361
+ */
362
+ export declare function getFileExtension(pathStr: string): string;
363
+ /**
364
+ * Gets file name without extension
365
+ *
366
+ * Returns just the base file name.
367
+ *
368
+ * @param pathStr - File path
369
+ * @returns File name without extension
370
+ *
371
+ * @example
372
+ * getBaseName('/home/user/file.txt') // "file"
373
+ * getBaseName('document.pdf') // "document"
374
+ * getBaseName('archive.tar.gz') // "archive.tar" (only removes last ext)
375
+ * getBaseName('noextension') // "noextension"
376
+ * getBaseName('') // ""
377
+ *
378
+ * @edge-cases
379
+ * - Only removes the last extension
380
+ * - For .tar.gz, returns "archive.tar"
381
+ */
382
+ export declare function getBaseName(pathStr: string): string;
383
+ /**
384
+ * SECURITY: Compares two paths for equality
385
+ *
386
+ * Safe comparison that handles path variations (normalization, case sensitivity).
387
+ * Important for security checks.
388
+ *
389
+ * @param pathA - First path
390
+ * @param pathB - Second path
391
+ * @param caseSensitive - Case-sensitive comparison (default: true on Unix, false on Windows)
392
+ * @returns true if paths refer to the same location
393
+ *
394
+ * @example
395
+ * comparePaths('/home/user', '/home/user') // true
396
+ * comparePaths('/home/user/', '/home/user') // true (trailing slash removed)
397
+ * comparePaths('./file', 'file') // true (when run from same directory)
398
+ * comparePaths('/HOME/user', '/home/user', false) // true (case-insensitive)
399
+ * comparePaths('/home/user', '/other/path') // false
400
+ *
401
+ * @edge-cases
402
+ * - Normalizes paths before comparison
403
+ * - Case sensitivity depends on filesystem
404
+ * - Relative paths resolved to current directory
405
+ *
406
+ * @security-notes
407
+ * - Use for validating against whitelists
408
+ * - Prevents bypass via path normalization tricks
409
+ */
410
+ export declare function comparePaths(pathA: string, pathB: string, caseSensitive?: boolean): boolean;
411
+ /**
412
+ * Checks if a path is contained within a base directory
413
+ *
414
+ * Useful for sandboxing and access control.
415
+ *
416
+ * @param pathStr - Path to check
417
+ * @param baseDir - Base directory
418
+ * @returns true if pathStr is within baseDir
419
+ *
420
+ * @example
421
+ * isPathWithinBase('/home/user/file.txt', '/home/user') // true
422
+ * isPathWithinBase('/home/user/docs/file.txt', '/home/user') // true
423
+ * isPathWithinBase('/home/user', '/home/user/subdir') // false
424
+ * isPathWithinBase('/etc/passwd', '/home/user') // false
425
+ * isPathWithinBase('/home/user/../etc/passwd', '/home/user') // false
426
+ *
427
+ * @edge-cases
428
+ * - Resolves paths before comparison
429
+ * - Trailing slashes ignored
430
+ * - Case-insensitive on Windows
431
+ *
432
+ * @security-notes
433
+ * - Critical for file upload handlers
434
+ * - Prevents directory traversal in validation
435
+ * - Use with normalizePath() for defense in depth
436
+ */
437
+ export declare function isPathWithinBase(pathStr: string, baseDir: string): boolean;
438
+ /**
439
+ * Detects if a path contains directory traversal patterns
440
+ *
441
+ * Simple pattern-based detection for common attack vectors.
442
+ *
443
+ * @param pathStr - Path to check
444
+ * @returns true if path contains traversal patterns
445
+ *
446
+ * @example
447
+ * hasTraversalPattern('../../etc/passwd') // true
448
+ * hasTraversalPattern('file.txt') // false
449
+ * hasTraversalPattern('./file.txt') // false
450
+ * hasTraversalPattern('..\\..\\windows\\system32') // true (Windows)
451
+ * hasTraversalPattern('foo/..') // true
452
+ * hasTraversalPattern('') // false
453
+ *
454
+ * @edge-cases
455
+ * - Detects both / and \ separators
456
+ * - Catches .. patterns anywhere in path
457
+ * - May have false positives (validate with isPathSafe)
458
+ *
459
+ * @security-notes
460
+ * - Use as quick check before detailed validation
461
+ * - Not sufficient alone - use isPathSafe() for security
462
+ */
463
+ export declare function hasTraversalPattern(pathStr: string): boolean;
464
+ /**
465
+ * Detects if a path contains null bytes (injection attempt)
466
+ *
467
+ * Null bytes can truncate paths in C string libraries.
468
+ * Critical security check for some codebases.
469
+ *
470
+ * @param pathStr - Path to check
471
+ * @returns true if path contains null bytes
472
+ *
473
+ * @example
474
+ * hasNullBytes('file.txt') // false
475
+ * hasNullBytes('file.txt\0.jsp') // true
476
+ * hasNullBytes('') // false
477
+ *
478
+ * @edge-cases
479
+ * - Only relevant for C-based systems
480
+ * - Node.js handles this automatically in most cases
481
+ */
482
+ export declare function hasNullBytes(pathStr: string): boolean;
483
+ /**
484
+ * Sanitizes a path by removing dangerous characters
485
+ *
486
+ * Removes null bytes, excess whitespace, and potentially problematic characters.
487
+ * Use for defensive programming.
488
+ *
489
+ * @param pathStr - Path to sanitize
490
+ * @returns Sanitized path
491
+ *
492
+ * @example
493
+ * sanitizePath('file.txt') // "file.txt"
494
+ * sanitizePath('file.txt\0.jsp') // "file.txt.jsp"
495
+ * sanitizePath('file name.txt') // "file name.txt"
496
+ * sanitizePath('') // ""
497
+ *
498
+ * @edge-cases
499
+ * - Doesn't validate path, only removes dangerous chars
500
+ * - Use with isPathSafe() for full validation
501
+ */
502
+ export declare function sanitizePath(pathStr: string): string;
503
+ /**
504
+ * Gets the relative path between two paths
505
+ *
506
+ * Safe version of path.relative with error handling.
507
+ *
508
+ * @param from - Starting path
509
+ * @param to - Target path
510
+ * @returns Relative path from 'from' to 'to'
511
+ *
512
+ * @example
513
+ * getRelativePath('/home/user', '/home/user/file.txt')
514
+ * // "file.txt"
515
+ *
516
+ * getRelativePath('/home/user/docs', '/home/user/file.txt')
517
+ * // "../file.txt"
518
+ *
519
+ * getRelativePath('/home', '/var')
520
+ * // "../../var"
521
+ *
522
+ * @edge-cases
523
+ * - Empty paths treated as current directory
524
+ * - May produce .. patterns
525
+ */
526
+ export declare function getRelativePath(from: string, to: string): string;
527
+ /**
528
+ * Configuration for path list operations
529
+ */
530
+ export interface PathListOptions {
531
+ /** Base directory for validation */
532
+ base?: string;
533
+ /** Filter out unsafe paths (default: true) */
534
+ filterUnsafe?: boolean;
535
+ /** Normalize paths (default: true) */
536
+ normalize?: boolean;
537
+ }
538
+ /**
539
+ * SECURITY: Validates a list of paths
540
+ *
541
+ * Batch validation useful for multi-file operations.
542
+ *
543
+ * @param paths - Array of paths to validate
544
+ * @param options - Validation options
545
+ * @returns Array of valid paths
546
+ *
547
+ * @example
548
+ * validatePaths(userPaths, {
549
+ * base: '/app/uploads',
550
+ * filterUnsafe: true,
551
+ * })
552
+ *
553
+ * @edge-cases
554
+ * - Filters out duplicates if normalize: true
555
+ * - Returns empty array if no valid paths
556
+ */
557
+ export declare function validatePaths(paths: string[], options?: PathListOptions): string[];
558
+ /**
559
+ * Creates a pattern to detect path variations
560
+ *
561
+ * Useful for accepting different path formats.
562
+ *
563
+ * @param pathStr - Base path
564
+ * @returns Test function for path equivalence
565
+ *
566
+ * @example
567
+ * const isSameFile = createPathMatcher('/home/user/file.txt');
568
+ * isSameFile('/home/user/file.txt') // true
569
+ * isSameFile('/home/user//file.txt') // true
570
+ * isSameFile('/home/user/./file.txt') // true
571
+ * isSameFile('~/file.txt') // false (if ~ not expanded)
572
+ *
573
+ * @edge-cases
574
+ * - Doesn't expand ~ (home directory)
575
+ * - Case-sensitive on Unix, insensitive on Windows
576
+ */
577
+ export declare function createPathMatcher(pathStr: string): (other: string) => boolean;
578
+ /**
579
+ * Checks if a file path looks like a suspicious upload
580
+ *
581
+ * Detects common file upload attack patterns.
582
+ *
583
+ * @param pathStr - File path to check
584
+ * @returns Array of detected issues (empty if safe)
585
+ *
586
+ * @example
587
+ * detectUploadThreats('shell.php.txt') // ['suspicious_extension_combo']
588
+ * detectUploadThreats('../../../etc/passwd') // ['traversal_pattern']
589
+ * detectUploadThreats('file.txt') // []
590
+ * detectUploadThreats('.htaccess') // ['hidden_file']
591
+ *
592
+ * @edge-cases
593
+ * - Uses heuristics, not definitive
594
+ * - May have false positives
595
+ * - Combine with extension whitelisting
596
+ *
597
+ * @security-notes
598
+ * - Use as additional layer, not primary validation
599
+ * - Always validate against whitelist of extensions
600
+ * - Store uploads outside web root
601
+ */
602
+ export declare function detectUploadThreats(pathStr: string): string[];
603
+ //# sourceMappingURL=path-validator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"path-validator.d.ts","sourceRoot":"","sources":["../../src/utils/path-validator.ts"],"names":[],"mappings":"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"}