@dotsetlabs/tollgate 0.2.2 → 0.3.0

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 (194) hide show
  1. package/README.md +138 -0
  2. package/dist/analyzers/filesystem.d.ts +5 -0
  3. package/dist/analyzers/filesystem.d.ts.map +1 -1
  4. package/dist/analyzers/filesystem.js +61 -7
  5. package/dist/analyzers/filesystem.js.map +1 -1
  6. package/dist/analyzers/loader.d.ts +5 -0
  7. package/dist/analyzers/loader.d.ts.map +1 -1
  8. package/dist/analyzers/loader.js +112 -6
  9. package/dist/analyzers/loader.js.map +1 -1
  10. package/dist/analyzers/prompt-injection.d.ts +1 -0
  11. package/dist/analyzers/prompt-injection.d.ts.map +1 -1
  12. package/dist/analyzers/prompt-injection.js +48 -2
  13. package/dist/analyzers/prompt-injection.js.map +1 -1
  14. package/dist/analyzers/shell.d.ts +8 -0
  15. package/dist/analyzers/shell.d.ts.map +1 -1
  16. package/dist/analyzers/shell.js +109 -8
  17. package/dist/analyzers/shell.js.map +1 -1
  18. package/dist/analyzers/sql.d.ts.map +1 -1
  19. package/dist/analyzers/sql.js +8 -7
  20. package/dist/analyzers/sql.js.map +1 -1
  21. package/dist/approval/interactive.d.ts +1 -1
  22. package/dist/approval/interactive.d.ts.map +1 -1
  23. package/dist/approval/interactive.js +13 -1
  24. package/dist/approval/interactive.js.map +1 -1
  25. package/dist/approval/rate-limiter.d.ts +115 -0
  26. package/dist/approval/rate-limiter.d.ts.map +1 -0
  27. package/dist/approval/rate-limiter.js +200 -0
  28. package/dist/approval/rate-limiter.js.map +1 -0
  29. package/dist/approval/url-validator.d.ts +51 -0
  30. package/dist/approval/url-validator.d.ts.map +1 -0
  31. package/dist/approval/url-validator.js +184 -0
  32. package/dist/approval/url-validator.js.map +1 -0
  33. package/dist/approval/webhook.d.ts +48 -0
  34. package/dist/approval/webhook.d.ts.map +1 -1
  35. package/dist/approval/webhook.js +89 -0
  36. package/dist/approval/webhook.js.map +1 -1
  37. package/dist/audit/integrity.d.ts +107 -0
  38. package/dist/audit/integrity.d.ts.map +1 -0
  39. package/dist/audit/integrity.js +191 -0
  40. package/dist/audit/integrity.js.map +1 -0
  41. package/dist/audit/logger.d.ts.map +1 -1
  42. package/dist/audit/logger.js +6 -5
  43. package/dist/audit/logger.js.map +1 -1
  44. package/dist/audit/redaction.js +6 -4
  45. package/dist/audit/redaction.js.map +1 -1
  46. package/dist/cli/commands/guard.d.ts +97 -0
  47. package/dist/cli/commands/guard.d.ts.map +1 -0
  48. package/dist/cli/commands/guard.js +456 -0
  49. package/dist/cli/commands/guard.js.map +1 -0
  50. package/dist/cli/commands/serve.js +1 -1
  51. package/dist/cli/commands/serve.js.map +1 -1
  52. package/dist/cli/index.js +3 -0
  53. package/dist/cli/index.js.map +1 -1
  54. package/dist/cli/input-validation.d.ts +83 -0
  55. package/dist/cli/input-validation.d.ts.map +1 -0
  56. package/dist/cli/input-validation.js +237 -0
  57. package/dist/cli/input-validation.js.map +1 -0
  58. package/dist/cli/ui.js +2 -2
  59. package/dist/cli/ui.js.map +1 -1
  60. package/dist/guard/alternatives/index.d.ts +68 -0
  61. package/dist/guard/alternatives/index.d.ts.map +1 -0
  62. package/dist/guard/alternatives/index.js +224 -0
  63. package/dist/guard/alternatives/index.js.map +1 -0
  64. package/dist/guard/alternatives/registry.d.ts +16 -0
  65. package/dist/guard/alternatives/registry.d.ts.map +1 -0
  66. package/dist/guard/alternatives/registry.js +518 -0
  67. package/dist/guard/alternatives/registry.js.map +1 -0
  68. package/dist/guard/alternatives/types.d.ts +86 -0
  69. package/dist/guard/alternatives/types.d.ts.map +1 -0
  70. package/dist/guard/alternatives/types.js +5 -0
  71. package/dist/guard/alternatives/types.js.map +1 -0
  72. package/dist/guard/approval/enhanced-terminal.d.ts +110 -0
  73. package/dist/guard/approval/enhanced-terminal.d.ts.map +1 -0
  74. package/dist/guard/approval/enhanced-terminal.js +387 -0
  75. package/dist/guard/approval/enhanced-terminal.js.map +1 -0
  76. package/dist/guard/config.d.ts +80 -0
  77. package/dist/guard/config.d.ts.map +1 -0
  78. package/dist/guard/config.js +260 -0
  79. package/dist/guard/config.js.map +1 -0
  80. package/dist/guard/context/directory.d.ts +35 -0
  81. package/dist/guard/context/directory.d.ts.map +1 -0
  82. package/dist/guard/context/directory.js +243 -0
  83. package/dist/guard/context/directory.js.map +1 -0
  84. package/dist/guard/context/environment.d.ts +31 -0
  85. package/dist/guard/context/environment.d.ts.map +1 -0
  86. package/dist/guard/context/environment.js +204 -0
  87. package/dist/guard/context/environment.js.map +1 -0
  88. package/dist/guard/context/git.d.ts +52 -0
  89. package/dist/guard/context/git.d.ts.map +1 -0
  90. package/dist/guard/context/git.js +278 -0
  91. package/dist/guard/context/git.js.map +1 -0
  92. package/dist/guard/context/index.d.ts +64 -0
  93. package/dist/guard/context/index.d.ts.map +1 -0
  94. package/dist/guard/context/index.js +227 -0
  95. package/dist/guard/context/index.js.map +1 -0
  96. package/dist/guard/context/project.d.ts +47 -0
  97. package/dist/guard/context/project.d.ts.map +1 -0
  98. package/dist/guard/context/project.js +281 -0
  99. package/dist/guard/context/project.js.map +1 -0
  100. package/dist/guard/context/types.d.ts +152 -0
  101. package/dist/guard/context/types.d.ts.map +1 -0
  102. package/dist/guard/context/types.js +7 -0
  103. package/dist/guard/context/types.js.map +1 -0
  104. package/dist/guard/engine.d.ts +107 -0
  105. package/dist/guard/engine.d.ts.map +1 -0
  106. package/dist/guard/engine.js +430 -0
  107. package/dist/guard/engine.js.map +1 -0
  108. package/dist/guard/enhanced-engine.d.ts +151 -0
  109. package/dist/guard/enhanced-engine.d.ts.map +1 -0
  110. package/dist/guard/enhanced-engine.js +622 -0
  111. package/dist/guard/enhanced-engine.js.map +1 -0
  112. package/dist/guard/hooks/index.d.ts +50 -0
  113. package/dist/guard/hooks/index.d.ts.map +1 -0
  114. package/dist/guard/hooks/index.js +325 -0
  115. package/dist/guard/hooks/index.js.map +1 -0
  116. package/dist/guard/index.d.ts +29 -0
  117. package/dist/guard/index.d.ts.map +1 -0
  118. package/dist/guard/index.js +31 -0
  119. package/dist/guard/index.js.map +1 -0
  120. package/dist/guard/learning/index.d.ts +136 -0
  121. package/dist/guard/learning/index.d.ts.map +1 -0
  122. package/dist/guard/learning/index.js +314 -0
  123. package/dist/guard/learning/index.js.map +1 -0
  124. package/dist/guard/learning/pattern-extractor.d.ts +50 -0
  125. package/dist/guard/learning/pattern-extractor.d.ts.map +1 -0
  126. package/dist/guard/learning/pattern-extractor.js +372 -0
  127. package/dist/guard/learning/pattern-extractor.js.map +1 -0
  128. package/dist/guard/learning/rule-suggester.d.ts +67 -0
  129. package/dist/guard/learning/rule-suggester.d.ts.map +1 -0
  130. package/dist/guard/learning/rule-suggester.js +345 -0
  131. package/dist/guard/learning/rule-suggester.js.map +1 -0
  132. package/dist/guard/learning/types.d.ts +211 -0
  133. package/dist/guard/learning/types.d.ts.map +1 -0
  134. package/dist/guard/learning/types.js +18 -0
  135. package/dist/guard/learning/types.js.map +1 -0
  136. package/dist/guard/preview/effects.d.ts +15 -0
  137. package/dist/guard/preview/effects.d.ts.map +1 -0
  138. package/dist/guard/preview/effects.js +413 -0
  139. package/dist/guard/preview/effects.js.map +1 -0
  140. package/dist/guard/preview/index.d.ts +49 -0
  141. package/dist/guard/preview/index.d.ts.map +1 -0
  142. package/dist/guard/preview/index.js +196 -0
  143. package/dist/guard/preview/index.js.map +1 -0
  144. package/dist/guard/preview/parser.d.ts +34 -0
  145. package/dist/guard/preview/parser.d.ts.map +1 -0
  146. package/dist/guard/preview/parser.js +292 -0
  147. package/dist/guard/preview/parser.js.map +1 -0
  148. package/dist/guard/preview/types.d.ts +140 -0
  149. package/dist/guard/preview/types.d.ts.map +1 -0
  150. package/dist/guard/preview/types.js +5 -0
  151. package/dist/guard/preview/types.js.map +1 -0
  152. package/dist/guard/reversibility/index.d.ts +88 -0
  153. package/dist/guard/reversibility/index.d.ts.map +1 -0
  154. package/dist/guard/reversibility/index.js +310 -0
  155. package/dist/guard/reversibility/index.js.map +1 -0
  156. package/dist/guard/types.d.ts +192 -0
  157. package/dist/guard/types.d.ts.map +1 -0
  158. package/dist/guard/types.js +8 -0
  159. package/dist/guard/types.js.map +1 -0
  160. package/dist/index.d.ts +10 -0
  161. package/dist/index.d.ts.map +1 -1
  162. package/dist/index.js +24 -0
  163. package/dist/index.js.map +1 -1
  164. package/dist/orchestrator/manager.d.ts.map +1 -1
  165. package/dist/orchestrator/manager.js +6 -1
  166. package/dist/orchestrator/manager.js.map +1 -1
  167. package/dist/policy/engine.d.ts.map +1 -1
  168. package/dist/policy/engine.js +11 -3
  169. package/dist/policy/engine.js.map +1 -1
  170. package/dist/policy/parser.d.ts.map +1 -1
  171. package/dist/policy/parser.js +3 -0
  172. package/dist/policy/parser.js.map +1 -1
  173. package/dist/proxy/server.d.ts.map +1 -1
  174. package/dist/proxy/server.js +8 -6
  175. package/dist/proxy/server.js.map +1 -1
  176. package/dist/session/manager.d.ts +2 -2
  177. package/dist/session/manager.d.ts.map +1 -1
  178. package/dist/session/manager.js +106 -88
  179. package/dist/session/manager.js.map +1 -1
  180. package/dist/session/signing.d.ts +88 -0
  181. package/dist/session/signing.d.ts.map +1 -0
  182. package/dist/session/signing.js +166 -0
  183. package/dist/session/signing.js.map +1 -0
  184. package/dist/session/types.d.ts +2 -0
  185. package/dist/session/types.d.ts.map +1 -1
  186. package/dist/session/types.js.map +1 -1
  187. package/dist/utils/security-logger.d.ts +146 -0
  188. package/dist/utils/security-logger.d.ts.map +1 -0
  189. package/dist/utils/security-logger.js +222 -0
  190. package/dist/utils/security-logger.js.map +1 -0
  191. package/dist/wizard.d.ts.map +1 -1
  192. package/dist/wizard.js +7 -1
  193. package/dist/wizard.js.map +1 -1
  194. package/package.json +3 -2
@@ -0,0 +1,430 @@
1
+ /**
2
+ * Guard Engine - Core orchestrator for AI Shell Guardian
3
+ *
4
+ * The GuardEngine evaluates shell commands through multiple stages:
5
+ * 1. Fast path - Skip analysis for known-safe commands
6
+ * 2. Allowlist - Exact match bypass
7
+ * 3. Denylist - Pattern-based blocking
8
+ * 4. Analysis - Risk classification via ShellAnalyzer
9
+ * 5. Custom rules - Pattern-based policy overrides
10
+ * 6. Session grants - Check for existing approvals
11
+ * 7. Risk policy - Map risk level to action
12
+ * 8. Approval - Prompt user if needed
13
+ *
14
+ * @example
15
+ * ```typescript
16
+ * const engine = new GuardEngine({ config: loadGuardConfig() });
17
+ * const result = await engine.evaluate({ command: 'rm -rf node_modules' });
18
+ *
19
+ * if (result.allowed) {
20
+ * // Execute the command
21
+ * } else {
22
+ * console.log(`Blocked: ${result.reason}`);
23
+ * }
24
+ * ```
25
+ */
26
+ import { v4 as uuidv4 } from 'uuid';
27
+ import { ShellAnalyzer } from '../analyzers/shell.js';
28
+ import { SessionManager, InMemorySessionStore } from '../session/manager.js';
29
+ import { SqliteSessionStore } from '../session/sqlite-store.js';
30
+ import { TerminalApprovalHandler } from '../approval/terminal.js';
31
+ import { AuditLogger } from '../audit/logger.js';
32
+ import { DEFAULT_GUARD_CONFIG, compileRules, compileDenylist, } from './config.js';
33
+ import { DEFAULT_APPROVAL_TIMEOUT_MS } from '../constants.js';
34
+ import { getDataDir } from '../utils/config.js';
35
+ import { join } from 'node:path';
36
+ /**
37
+ * GuardEngine orchestrates command validation and approval.
38
+ */
39
+ export class GuardEngine {
40
+ config;
41
+ analyzer;
42
+ sessionManager;
43
+ approvalHandler;
44
+ auditLogger;
45
+ // Pre-compiled patterns for performance
46
+ compiledRules;
47
+ compiledDenylist;
48
+ // Fast path prefix set for O(1) lookup
49
+ fastPathPrefixes;
50
+ constructor(options) {
51
+ this.config = options.config;
52
+ // Initialize analyzer
53
+ this.analyzer = new ShellAnalyzer();
54
+ // Initialize session manager
55
+ const sessionPath = options.sessionPath ?? join(getDataDir(), 'guard-sessions.db');
56
+ const sessionStore = options.persistSessions
57
+ ? new SqliteSessionStore(sessionPath)
58
+ : new InMemorySessionStore();
59
+ this.sessionManager = new SessionManager(sessionStore);
60
+ // Initialize approval handler
61
+ const timeoutMs = options.timeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
62
+ this.approvalHandler = new TerminalApprovalHandler(timeoutMs);
63
+ // Initialize audit logger (if enabled)
64
+ this.auditLogger = this.config.audit.enabled
65
+ ? new AuditLogger({
66
+ dbPath: options.auditPath,
67
+ enableRedaction: this.config.audit.redactSecrets,
68
+ })
69
+ : null;
70
+ // Pre-compile patterns
71
+ this.compiledRules = compileRules(this.config.rules);
72
+ this.compiledDenylist = compileDenylist(this.config.denylist);
73
+ // Build fast path prefix set
74
+ this.fastPathPrefixes = new Set(this.config.fastPath.enabled ? this.config.fastPath.safePrefixes : []);
75
+ }
76
+ /**
77
+ * Evaluate a command and determine if it should be allowed to execute.
78
+ *
79
+ * @param context - The command context to evaluate
80
+ * @returns Result indicating whether command is allowed and why
81
+ */
82
+ async evaluate(context) {
83
+ const startTime = Date.now();
84
+ const { command } = context;
85
+ // Normalize command for consistent matching
86
+ const normalizedCommand = command.trim();
87
+ // Stage 1: Fast path for known-safe commands
88
+ if (this.matchesFastPath(normalizedCommand)) {
89
+ return this.createResult({
90
+ allowed: true,
91
+ reason: 'Fast path: known safe command',
92
+ riskLevel: 'safe',
93
+ analysis: { risk: 'safe', reason: 'Fast path bypass' },
94
+ decisionSource: 'allowlist',
95
+ evaluationTimeMs: Date.now() - startTime,
96
+ });
97
+ }
98
+ // Stage 2: Check allowlist (exact matches)
99
+ if (this.isAllowlisted(normalizedCommand)) {
100
+ return this.createResult({
101
+ allowed: true,
102
+ reason: 'Allowlisted command',
103
+ riskLevel: 'safe',
104
+ analysis: { risk: 'safe', reason: 'Allowlist match' },
105
+ decisionSource: 'allowlist',
106
+ evaluationTimeMs: Date.now() - startTime,
107
+ });
108
+ }
109
+ // Stage 3: Check denylist (pattern matches)
110
+ const denyMatch = this.matchesDenylist(normalizedCommand);
111
+ if (denyMatch) {
112
+ const result = this.createResult({
113
+ allowed: false,
114
+ reason: denyMatch.reason ?? 'Blocked by denylist',
115
+ riskLevel: 'dangerous',
116
+ analysis: {
117
+ risk: 'dangerous',
118
+ reason: denyMatch.reason ?? 'Denylist match',
119
+ metadata: { pattern: denyMatch.originalPattern },
120
+ },
121
+ decisionSource: 'denylist',
122
+ evaluationTimeMs: Date.now() - startTime,
123
+ });
124
+ await this.logDecision(context, result, 'denied');
125
+ return result;
126
+ }
127
+ // Stage 4: Analyze command with ShellAnalyzer
128
+ const analysis = this.analyzer.analyze(normalizedCommand);
129
+ // Stage 5: Check custom rules
130
+ const ruleMatch = this.matchCustomRule(normalizedCommand);
131
+ if (ruleMatch) {
132
+ if (ruleMatch.action === 'allow') {
133
+ return this.createResult({
134
+ allowed: true,
135
+ reason: ruleMatch.reason,
136
+ riskLevel: analysis.risk,
137
+ analysis,
138
+ decisionSource: 'rule',
139
+ evaluationTimeMs: Date.now() - startTime,
140
+ });
141
+ }
142
+ if (ruleMatch.action === 'deny') {
143
+ const result = this.createResult({
144
+ allowed: false,
145
+ reason: ruleMatch.reason,
146
+ riskLevel: analysis.risk,
147
+ analysis,
148
+ decisionSource: 'rule',
149
+ evaluationTimeMs: Date.now() - startTime,
150
+ });
151
+ await this.logDecision(context, result, 'denied');
152
+ return result;
153
+ }
154
+ // 'prompt' falls through to normal flow
155
+ }
156
+ // Stage 6: Apply risk-based policy
157
+ const action = this.config.risks[analysis.risk] ?? 'prompt';
158
+ if (action === 'allow') {
159
+ return this.createResult({
160
+ allowed: true,
161
+ reason: analysis.reason,
162
+ riskLevel: analysis.risk,
163
+ analysis,
164
+ decisionSource: 'risk',
165
+ evaluationTimeMs: Date.now() - startTime,
166
+ });
167
+ }
168
+ if (action === 'deny') {
169
+ const result = this.createResult({
170
+ allowed: false,
171
+ reason: analysis.reason,
172
+ riskLevel: analysis.risk,
173
+ analysis,
174
+ decisionSource: 'risk',
175
+ evaluationTimeMs: Date.now() - startTime,
176
+ });
177
+ await this.logDecision(context, result, 'denied');
178
+ return result;
179
+ }
180
+ // Stage 7: Check for existing session grant
181
+ const commandCategory = this.extractCommandCategory(normalizedCommand);
182
+ const grantCheck = await this.sessionManager.checkGrant({
183
+ server: 'guard',
184
+ tool: commandCategory,
185
+ args: { command: normalizedCommand },
186
+ timestamp: new Date(),
187
+ });
188
+ if (grantCheck.granted && grantCheck.grant) {
189
+ const result = this.createResult({
190
+ allowed: true,
191
+ reason: `Session grant: ${this.sessionManager.formatGrant(grantCheck.grant)}`,
192
+ riskLevel: analysis.risk,
193
+ analysis,
194
+ sessionGrantId: grantCheck.grant.id,
195
+ decisionSource: 'session',
196
+ evaluationTimeMs: Date.now() - startTime,
197
+ });
198
+ if (this.config.audit.logAllCommands) {
199
+ await this.logDecision(context, result, 'allowed');
200
+ }
201
+ return result;
202
+ }
203
+ // Stage 8: Dry-run mode - don't prompt
204
+ if (context.dryRun) {
205
+ return this.createResult({
206
+ allowed: false,
207
+ reason: 'Would prompt for approval (dry-run mode)',
208
+ riskLevel: analysis.risk,
209
+ analysis,
210
+ decisionSource: 'risk',
211
+ evaluationTimeMs: Date.now() - startTime,
212
+ });
213
+ }
214
+ // Stage 9: Prompt for approval
215
+ const approval = await this.promptApproval(context, analysis, commandCategory);
216
+ if (approval.result === 'approved') {
217
+ let sessionGrantId;
218
+ // Create session grant if requested
219
+ if (approval.sessionGrant) {
220
+ const grant = await this.sessionManager.createGrant({
221
+ context: {
222
+ server: 'guard',
223
+ tool: commandCategory,
224
+ args: { command: normalizedCommand },
225
+ timestamp: new Date(),
226
+ },
227
+ scope: approval.sessionGrant.scope,
228
+ duration: approval.sessionGrant.duration,
229
+ grantedBy: 'terminal',
230
+ });
231
+ sessionGrantId = grant.id;
232
+ }
233
+ const result = this.createResult({
234
+ allowed: true,
235
+ reason: 'User approved',
236
+ riskLevel: analysis.risk,
237
+ analysis,
238
+ sessionGrantId,
239
+ decisionSource: 'user',
240
+ evaluationTimeMs: Date.now() - startTime,
241
+ });
242
+ await this.logDecision(context, result, 'allowed', 'approved');
243
+ return result;
244
+ }
245
+ // User denied or timed out
246
+ const result = this.createResult({
247
+ allowed: false,
248
+ reason: approval.result === 'timeout' ? 'Approval timed out' : 'User denied',
249
+ riskLevel: analysis.risk,
250
+ analysis,
251
+ decisionSource: 'user',
252
+ evaluationTimeMs: Date.now() - startTime,
253
+ });
254
+ await this.logDecision(context, result, 'denied', approval.result);
255
+ return result;
256
+ }
257
+ /**
258
+ * Analyze a command without prompting (for preview/display).
259
+ */
260
+ analyze(command) {
261
+ return this.analyzer.analyze(command.trim());
262
+ }
263
+ /**
264
+ * Check if command matches fast path prefixes.
265
+ */
266
+ matchesFastPath(command) {
267
+ if (!this.config.fastPath.enabled) {
268
+ return false;
269
+ }
270
+ // Check exact prefix matches
271
+ for (const prefix of this.fastPathPrefixes) {
272
+ if (command === prefix || command.startsWith(prefix + ' ')) {
273
+ return true;
274
+ }
275
+ }
276
+ return false;
277
+ }
278
+ /**
279
+ * Check if command is in the allowlist.
280
+ */
281
+ isAllowlisted(command) {
282
+ return this.config.allowlist.includes(command);
283
+ }
284
+ /**
285
+ * Check if command matches any denylist pattern.
286
+ */
287
+ matchesDenylist(command) {
288
+ for (const deny of this.compiledDenylist) {
289
+ if (deny.pattern.test(command)) {
290
+ return deny;
291
+ }
292
+ }
293
+ return null;
294
+ }
295
+ /**
296
+ * Check if command matches any custom rule.
297
+ */
298
+ matchCustomRule(command) {
299
+ for (const rule of this.compiledRules) {
300
+ if (rule.pattern.test(command)) {
301
+ return rule;
302
+ }
303
+ }
304
+ return null;
305
+ }
306
+ /**
307
+ * Extract the primary command for session scoping.
308
+ */
309
+ extractCommandCategory(command) {
310
+ // Get first word (the actual command)
311
+ const firstWord = command.split(/\s+/)[0] ?? 'unknown';
312
+ // Handle common patterns
313
+ if (firstWord === 'sudo' || firstWord === 'doas') {
314
+ // Get the command after sudo/doas
315
+ const parts = command.split(/\s+/);
316
+ return parts[1] ?? firstWord;
317
+ }
318
+ return firstWord;
319
+ }
320
+ /**
321
+ * Prompt user for approval.
322
+ */
323
+ async promptApproval(context, analysis, commandCategory) {
324
+ const request = {
325
+ id: uuidv4(),
326
+ context: {
327
+ server: 'guard',
328
+ tool: commandCategory,
329
+ args: { command: context.command },
330
+ timestamp: new Date(),
331
+ },
332
+ decision: {
333
+ action: 'prompt',
334
+ reason: analysis.reason,
335
+ matchedRule: 'guard-policy',
336
+ analysis: {
337
+ analyzer: 'shell',
338
+ risk: analysis.risk,
339
+ triggers: analysis.triggers,
340
+ },
341
+ },
342
+ timestamp: new Date(),
343
+ sessionConfig: {
344
+ allowRemember: this.config.session.allowRemember,
345
+ defaultScope: this.config.session.defaultScope,
346
+ allowedDurations: this.config.session.allowedDurations,
347
+ },
348
+ };
349
+ return this.approvalHandler.prompt(request);
350
+ }
351
+ /**
352
+ * Create a GuardResult with consistent structure.
353
+ */
354
+ createResult(partial) {
355
+ return {
356
+ allowed: partial.allowed,
357
+ reason: partial.reason,
358
+ riskLevel: partial.riskLevel,
359
+ analysis: partial.analysis,
360
+ sessionGrantId: partial.sessionGrantId,
361
+ decisionSource: partial.decisionSource,
362
+ evaluationTimeMs: partial.evaluationTimeMs,
363
+ };
364
+ }
365
+ /**
366
+ * Log a guard decision to the audit log.
367
+ */
368
+ async logDecision(context, result, decision, userResponse) {
369
+ if (!this.auditLogger) {
370
+ return;
371
+ }
372
+ // Log as a tool call attempt (reusing existing audit infrastructure)
373
+ const auditId = this.auditLogger.logAttempt({
374
+ server: 'guard',
375
+ tool: this.extractCommandCategory(context.command),
376
+ args: { command: context.command, cwd: context.cwd, shell: context.shell },
377
+ timestamp: new Date(),
378
+ }, {
379
+ action: result.allowed ? 'allow' : 'deny',
380
+ reason: result.reason,
381
+ matchedRule: result.decisionSource,
382
+ analysis: result.analysis ? {
383
+ analyzer: 'shell',
384
+ risk: result.analysis.risk,
385
+ triggers: result.analysis.triggers,
386
+ } : undefined,
387
+ }, result.sessionGrantId);
388
+ // Log the result
389
+ this.auditLogger.logResult(auditId, userResponse ?? (result.allowed ? 'approved' : 'denied'), result.allowed ? 'success' : 'error', result.allowed ? undefined : result.reason, result.evaluationTimeMs);
390
+ }
391
+ /**
392
+ * Get session manager for external access (e.g., CLI commands).
393
+ */
394
+ getSessionManager() {
395
+ return this.sessionManager;
396
+ }
397
+ /**
398
+ * Get audit logger for external access (e.g., CLI commands).
399
+ */
400
+ getAuditLogger() {
401
+ return this.auditLogger;
402
+ }
403
+ /**
404
+ * Get current configuration.
405
+ */
406
+ getConfig() {
407
+ return this.config;
408
+ }
409
+ /**
410
+ * Clean up resources.
411
+ */
412
+ close() {
413
+ this.sessionManager.close();
414
+ this.approvalHandler.close();
415
+ this.auditLogger?.close();
416
+ }
417
+ }
418
+ /**
419
+ * Create a GuardEngine with default configuration.
420
+ */
421
+ export function createGuardEngine(options) {
422
+ return new GuardEngine({
423
+ config: options?.config ?? DEFAULT_GUARD_CONFIG,
424
+ auditPath: options?.auditPath,
425
+ sessionPath: options?.sessionPath,
426
+ persistSessions: options?.persistSessions,
427
+ timeoutMs: options?.timeoutMs,
428
+ });
429
+ }
430
+ //# sourceMappingURL=engine.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/guard/engine.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Enhanced Guard Engine - Full-featured AI Shell Guardian
3
+ *
4
+ * Extends the base GuardEngine with:
5
+ * - Context-aware risk assessment (project, git, directory, environment)
6
+ * - Safer alternatives suggestions
7
+ * - Command preview with effect analysis
8
+ * - Reversibility scoring
9
+ * - Pattern learning for policy suggestions
10
+ * - Enhanced approval UI
11
+ */
12
+ import type { AnalysisResult } from '../analyzers/types.js';
13
+ import { SessionManager } from '../session/manager.js';
14
+ import { AuditLogger } from '../audit/logger.js';
15
+ import type { GuardConfig, GuardContext, GuardResult, GuardEngineOptions } from './types.js';
16
+ import type { EnhancedGuardContext } from './context/types.js';
17
+ import type { AlternativeResult } from './alternatives/types.js';
18
+ import type { CommandPreview } from './preview/types.js';
19
+ import type { ReversibilityAssessment } from './reversibility/index.js';
20
+ import { LearningEngine } from './learning/index.js';
21
+ /**
22
+ * Extended options for the enhanced guard engine.
23
+ */
24
+ export interface EnhancedGuardEngineOptions extends GuardEngineOptions {
25
+ /** Whether to enable context enhancement */
26
+ enableContext?: boolean;
27
+ /** Whether to enable alternatives suggestions */
28
+ enableAlternatives?: boolean;
29
+ /** Whether to enable command preview */
30
+ enablePreview?: boolean;
31
+ /** Whether to enable reversibility analysis */
32
+ enableReversibility?: boolean;
33
+ /** Whether to enable pattern learning */
34
+ enableLearning?: boolean;
35
+ /** Whether to use enhanced approval UI */
36
+ enhancedUI?: boolean;
37
+ /** Path for learning data storage */
38
+ learningPath?: string;
39
+ }
40
+ /**
41
+ * Extended result with enhanced information.
42
+ */
43
+ export interface EnhancedGuardResult extends GuardResult {
44
+ /** Enhanced context information */
45
+ enhancedContext?: EnhancedGuardContext;
46
+ /** Safer alternatives if available */
47
+ alternatives?: AlternativeResult;
48
+ /** Command preview if generated */
49
+ preview?: CommandPreview;
50
+ /** Reversibility assessment if evaluated */
51
+ reversibility?: ReversibilityAssessment;
52
+ /** Risk modifier from context (-1 to 1) */
53
+ riskModifier?: number;
54
+ /** If user chose an alternative */
55
+ chosenAlternative?: string;
56
+ }
57
+ /**
58
+ * EnhancedGuardEngine adds sophisticated context-aware features
59
+ * to the base Shell Guardian functionality.
60
+ */
61
+ export declare class EnhancedGuardEngine {
62
+ private readonly config;
63
+ private readonly analyzer;
64
+ private readonly sessionManager;
65
+ private readonly auditLogger;
66
+ private readonly compiledRules;
67
+ private readonly compiledDenylist;
68
+ private readonly fastPathPrefixes;
69
+ private readonly contextProvider;
70
+ private readonly alternativesFinder;
71
+ private readonly previewGenerator;
72
+ private readonly reversibilityAnalyzer;
73
+ private readonly learningEngine;
74
+ private readonly approvalHandler;
75
+ private readonly useEnhancedUI;
76
+ constructor(options: EnhancedGuardEngineOptions);
77
+ /**
78
+ * Evaluate a command with full enhanced analysis.
79
+ */
80
+ evaluate(context: GuardContext): Promise<EnhancedGuardResult>;
81
+ /**
82
+ * Build enhanced context from base context.
83
+ */
84
+ private buildEnhancedContext;
85
+ /**
86
+ * Apply risk modifier based on context.
87
+ */
88
+ private applyRiskModifier;
89
+ /**
90
+ * Generate command preview if enabled.
91
+ */
92
+ private generatePreview;
93
+ /**
94
+ * Find alternatives if enabled.
95
+ */
96
+ private findAlternatives;
97
+ /**
98
+ * Assess reversibility if enabled.
99
+ */
100
+ private assessReversibility;
101
+ /**
102
+ * Prompt for enhanced approval.
103
+ */
104
+ private promptEnhancedApproval;
105
+ private matchesFastPath;
106
+ private isAllowlisted;
107
+ private matchesDenylist;
108
+ private matchCustomRule;
109
+ private extractCommandCategory;
110
+ private createEnhancedResult;
111
+ private logDecision;
112
+ /**
113
+ * Analyze a command without prompting.
114
+ */
115
+ analyze(command: string): AnalysisResult;
116
+ /**
117
+ * Preview a command (dry-run).
118
+ */
119
+ preview(command: string): Promise<{
120
+ analysis: AnalysisResult;
121
+ preview?: CommandPreview;
122
+ alternatives?: AlternativeResult;
123
+ reversibility?: ReversibilityAssessment;
124
+ context?: EnhancedGuardContext;
125
+ }>;
126
+ /**
127
+ * Get learning engine for external access.
128
+ */
129
+ getLearningEngine(): LearningEngine | null;
130
+ /**
131
+ * Get session manager.
132
+ */
133
+ getSessionManager(): SessionManager;
134
+ /**
135
+ * Get audit logger.
136
+ */
137
+ getAuditLogger(): AuditLogger | null;
138
+ /**
139
+ * Get configuration.
140
+ */
141
+ getConfig(): GuardConfig;
142
+ /**
143
+ * Clean up resources.
144
+ */
145
+ close(): void;
146
+ }
147
+ /**
148
+ * Create an enhanced guard engine with all features.
149
+ */
150
+ export declare function createEnhancedGuardEngine(options?: Partial<EnhancedGuardEngineOptions>): EnhancedGuardEngine;
151
+ //# sourceMappingURL=enhanced-engine.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"enhanced-engine.d.ts","sourceRoot":"","sources":["../../src/guard/enhanced-engine.ts"],"names":[],"mappings":"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"}