@guren/server 2.14.0 → 2.16.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 (297) hide show
  1. package/dist/{DocsViewerServiceProvider-qFCaeiUv.js → DocsViewerServiceProvider-D2cuVgtN.js} +7 -12
  2. package/dist/{Hash-CzrwKeDp.js → Hash-D2DFd8xX.js} +12 -57
  3. package/dist/{HttpException-BkS3euNG.js → HttpException-BlQ2yEmT.js} +2 -79
  4. package/dist/{Job-BVT813DO.js → Job-DxQK8h3P.js} +24 -179
  5. package/dist/{McpServiceProvider-BawsYjgN.js → McpServiceProvider-nNcbCIQX.js} +11 -20
  6. package/dist/{Random-DbIJ22KQ.js → Random-S0OvCuR8.js} +9 -106
  7. package/dist/agent/AgentApprovalRequested.d.ts +31 -0
  8. package/dist/agent/approval.d.ts +184 -0
  9. package/dist/agent/audit-emitter.d.ts +36 -0
  10. package/dist/agent/audit.d.ts +67 -0
  11. package/dist/agent/derive.d.ts +32 -66
  12. package/dist/agent/dispatch.d.ts +53 -63
  13. package/dist/agent/events.d.ts +11 -19
  14. package/dist/agent/meta-tools.d.ts +34 -0
  15. package/dist/agent/public.d.ts +14 -0
  16. package/dist/agent/public.js +2 -0
  17. package/dist/agent/redact.d.ts +16 -38
  18. package/dist/agent/scopes.d.ts +23 -69
  19. package/dist/auth/AuthManager.d.ts +19 -40
  20. package/dist/auth/AuthenticatableModel.d.ts +2 -2
  21. package/dist/auth/SessionGuard.d.ts +0 -1
  22. package/dist/auth/TokenGuard.d.ts +6 -26
  23. package/dist/auth/api-token.d.ts +16 -148
  24. package/dist/auth/context.d.ts +5 -10
  25. package/dist/auth/email-verification.d.ts +29 -127
  26. package/dist/auth/index.js +1 -1
  27. package/dist/auth/oauth/index.d.ts +35 -57
  28. package/dist/auth/password/DefaultHasher.d.ts +9 -5
  29. package/dist/auth/password/PasswordHasher.d.ts +7 -0
  30. package/dist/auth/password/hash-format.d.ts +11 -0
  31. package/dist/auth/password-reset.d.ts +16 -42
  32. package/dist/auth/providers/ModelUserProvider.d.ts +3 -4
  33. package/dist/auth/providers/UserProvider.d.ts +4 -4
  34. package/dist/auth/signed-token.d.ts +18 -0
  35. package/dist/auth/types.d.ts +9 -32
  36. package/dist/auth/utils.d.ts +6 -27
  37. package/dist/{auth-BSUc14CD.js → auth-CbdPH4Cd.js} +252 -496
  38. package/dist/authorization/Gate.d.ts +9 -145
  39. package/dist/authorization/Policy.d.ts +6 -53
  40. package/dist/authorization/index.js +1 -1
  41. package/dist/authorization/middleware.d.ts +16 -62
  42. package/dist/authorization/types.d.ts +8 -64
  43. package/dist/{authorization-CdfbCj8J.js → authorization-CdEWZZw3.js} +44 -309
  44. package/dist/broadcasting/BroadcastManager.d.ts +29 -149
  45. package/dist/broadcasting/channels/Channel.d.ts +1 -19
  46. package/dist/broadcasting/channels/PresenceChannel.d.ts +1 -55
  47. package/dist/broadcasting/channels/PrivateChannel.d.ts +1 -23
  48. package/dist/broadcasting/drivers/MemoryDriver.d.ts +18 -70
  49. package/dist/broadcasting/drivers/RedisDriver.d.ts +3 -80
  50. package/dist/broadcasting/drivers/index.d.ts +1 -1
  51. package/dist/broadcasting/index.d.ts +1 -1
  52. package/dist/broadcasting/index.js +1 -1
  53. package/dist/broadcasting/types.d.ts +7 -88
  54. package/dist/{broadcasting-BxU-LIfF.js → broadcasting-B5RzB0A2.js} +87 -414
  55. package/dist/cache/CacheManager.d.ts +8 -62
  56. package/dist/cache/TaggedCache.d.ts +2 -35
  57. package/dist/cache/index.js +1 -1
  58. package/dist/cache/stores/FileStore.d.ts +2 -36
  59. package/dist/cache/stores/MemoryStore.d.ts +2 -26
  60. package/dist/cache/stores/RedisStore.d.ts +1 -29
  61. package/dist/cache/types.d.ts +21 -128
  62. package/dist/{cache-BYnZf2FR.js → cache-BOOIr324.js} +19 -198
  63. package/dist/client-C4TEr_Dd.js +9 -0
  64. package/dist/console/Command.d.ts +17 -126
  65. package/dist/console/ConsoleKernel.d.ts +2 -74
  66. package/dist/console/Input.d.ts +5 -113
  67. package/dist/console/Output.d.ts +3 -99
  68. package/dist/console/types.d.ts +3 -33
  69. package/dist/container/Container.d.ts +12 -103
  70. package/dist/container/ServiceProvider.d.ts +17 -61
  71. package/dist/container/bindings.d.ts +10 -12
  72. package/dist/container/defineModule.d.ts +16 -54
  73. package/dist/container/definePlugin.d.ts +12 -45
  74. package/dist/container/types.d.ts +2 -34
  75. package/dist/context-CXk_umpT.js +21 -0
  76. package/dist/database/Factory.d.ts +4 -57
  77. package/dist/database/Seeder.d.ts +8 -46
  78. package/dist/database/SeederRunner.d.ts +3 -33
  79. package/dist/database/types.d.ts +3 -24
  80. package/dist/discovery/AutoDiscovery.d.ts +10 -82
  81. package/dist/dispatch-BAwzftws.js +238 -0
  82. package/dist/docs-viewer/DocsViewerServiceProvider.d.ts +2 -5
  83. package/dist/docs-viewer/endpoint.d.ts +5 -11
  84. package/dist/encryption/Encrypter.d.ts +5 -71
  85. package/dist/encryption/Hash.d.ts +7 -57
  86. package/dist/encryption/Random.d.ts +6 -99
  87. package/dist/encryption/index.js +3 -3
  88. package/dist/encryption/types.d.ts +10 -72
  89. package/dist/{encryption-DJtkkhiw.js → encryption-uwP3Di4D.js} +13 -79
  90. package/dist/{endpoint-D6GIqOpe.js → endpoint-BXipU2Jj.js} +6 -12
  91. package/dist/endpoint-Dsw3Acvq.js +26 -0
  92. package/dist/errors/ExceptionHandler.d.ts +3 -90
  93. package/dist/errors/HttpException.d.ts +2 -79
  94. package/dist/errors/debug-page.d.ts +3 -17
  95. package/dist/errors/error-page.d.ts +1 -0
  96. package/dist/errors/exceptions/AuthenticationException.d.ts +2 -24
  97. package/dist/errors/exceptions/AuthorizationException.d.ts +1 -24
  98. package/dist/errors/exceptions/MethodNotAllowedException.d.ts +1 -23
  99. package/dist/errors/exceptions/NotFoundHttpException.d.ts +1 -27
  100. package/dist/errors/exceptions/ValidationException.d.ts +2 -43
  101. package/dist/errors/types.d.ts +1 -25
  102. package/dist/{errors-BgeOl_DC.js → errors-JpkcCjjn.js} +3 -41
  103. package/dist/events/Event.d.ts +1 -28
  104. package/dist/events/EventManager.d.ts +5 -107
  105. package/dist/events/Listener.d.ts +7 -55
  106. package/dist/events/builtin.d.ts +0 -24
  107. package/dist/events/index.js +1 -1
  108. package/dist/events/types.d.ts +4 -22
  109. package/dist/{events-aIH_bWRx.js → events-DOmAHDeP.js} +11 -191
  110. package/dist/facades/index.d.ts +2 -14
  111. package/dist/health/HealthCheck.d.ts +0 -24
  112. package/dist/health/HealthManager.d.ts +0 -36
  113. package/dist/health/checks/CacheCheck.d.ts +2 -17
  114. package/dist/health/checks/CustomCheck.d.ts +0 -9
  115. package/dist/health/checks/DatabaseCheck.d.ts +2 -17
  116. package/dist/health/checks/MemoryCheck.d.ts +3 -12
  117. package/dist/health/checks/RedisCheck.d.ts +1 -13
  118. package/dist/health/checks/StorageCheck.d.ts +2 -17
  119. package/dist/health/index.js +1 -1
  120. package/dist/health/types.d.ts +4 -24
  121. package/dist/{health-VWdWXRwh.js → health-DQSvUplL.js} +1 -76
  122. package/dist/hot-disposables-B5BXqaIH.js +167 -0
  123. package/dist/hot-reload/hot-disposables.d.ts +22 -74
  124. package/dist/hot-reload/testing.d.ts +4 -9
  125. package/dist/http/Application.d.ts +62 -208
  126. package/dist/http/FormRequest.d.ts +4 -55
  127. package/dist/http/dev-assets.d.ts +16 -18
  128. package/dist/http/dev-banner.d.ts +2 -5
  129. package/dist/http/inertia-assets.d.ts +3 -6
  130. package/dist/http/middleware/capabilities.d.ts +27 -50
  131. package/dist/http/middleware/cors.d.ts +4 -29
  132. package/dist/http/middleware/csp.d.ts +2 -25
  133. package/dist/http/middleware/csrf.d.ts +20 -95
  134. package/dist/http/middleware/detect-locale.d.ts +7 -27
  135. package/dist/http/middleware/force-https.d.ts +6 -24
  136. package/dist/http/middleware/host-authorization.d.ts +2 -12
  137. package/dist/http/middleware/loopback-guard.d.ts +15 -33
  138. package/dist/http/middleware/rate-limit.d.ts +29 -126
  139. package/dist/http/middleware/redirect-safety.d.ts +2 -20
  140. package/dist/http/middleware/request-id.d.ts +1 -14
  141. package/dist/http/middleware/request-logging.d.ts +2 -13
  142. package/dist/http/middleware/response-headers.d.ts +5 -13
  143. package/dist/http/middleware/security-headers.d.ts +2 -16
  144. package/dist/http/middleware/session.d.ts +15 -34
  145. package/dist/http/middleware/validation-errors-cookie.d.ts +7 -18
  146. package/dist/http/middleware/validation.d.ts +8 -63
  147. package/dist/http/public-assets.d.ts +14 -0
  148. package/dist/http/request.d.ts +49 -48
  149. package/dist/http/resources/CursorPaginator.d.ts +5 -64
  150. package/dist/http/resources/Paginator.d.ts +7 -84
  151. package/dist/http/resources/Resource.d.ts +9 -65
  152. package/dist/http/resources/ResourceCollection.d.ts +5 -39
  153. package/dist/http/resources/types.d.ts +10 -30
  154. package/dist/http/static-documents.d.ts +21 -0
  155. package/dist/http/validation/Validator.d.ts +25 -85
  156. package/dist/http/validation/rules.d.ts +48 -147
  157. package/dist/http/validation/types.d.ts +16 -61
  158. package/dist/http/vite-assets.d.ts +5 -28
  159. package/dist/http/vite-dev-server.d.ts +6 -9
  160. package/dist/http/vite-manifest.d.ts +19 -33
  161. package/dist/i18n/I18nManager.d.ts +12 -78
  162. package/dist/i18n/Translator.d.ts +3 -54
  163. package/dist/i18n/index.js +1 -1
  164. package/dist/i18n/loaders/JsonLoader.d.ts +4 -31
  165. package/dist/i18n/loaders/MemoryLoader.d.ts +1 -21
  166. package/dist/i18n/pluralization.d.ts +4 -13
  167. package/dist/i18n/types.d.ts +17 -69
  168. package/dist/{i18n-mcWi7LCd.js → i18n-Cg1aajRP.js} +31 -225
  169. package/dist/index.d.ts +13 -4
  170. package/dist/index.js +1036 -3080
  171. package/dist/internal/agent-preflight.d.ts +9 -21
  172. package/dist/internal/request.d.ts +10 -17
  173. package/dist/internal/request.js +2 -2
  174. package/dist/internal/route-path.d.ts +9 -21
  175. package/dist/internal/route-path.js +9 -21
  176. package/dist/internal/zod-compat.d.ts +55 -122
  177. package/dist/internal/zod-compat.js +39 -70
  178. package/dist/internal/zod-json-schema.d.ts +18 -54
  179. package/dist/internal/zod-json-schema.js +46 -123
  180. package/dist/jsx-runtime.d.ts +3 -8
  181. package/dist/lambda/index.d.ts +17 -79
  182. package/dist/lambda/index.js +11 -59
  183. package/dist/logging/LogManager.d.ts +1 -51
  184. package/dist/logging/Logger.d.ts +8 -47
  185. package/dist/logging/channels/ConsoleChannel.d.ts +1 -3
  186. package/dist/logging/channels/DailyFileChannel.d.ts +1 -5
  187. package/dist/logging/channels/FileChannel.d.ts +1 -3
  188. package/dist/logging/daily-file-path.d.ts +15 -0
  189. package/dist/logging/index.d.ts +1 -0
  190. package/dist/logging/index.js +2 -2
  191. package/dist/logging/types.d.ts +13 -45
  192. package/dist/{logging-CPaRMuPP.js → logging-zOY1XCtq.js} +83 -129
  193. package/dist/{loopback-guard-D0Kc7-xc.js → loopback-guard-DT9gHF0F.js} +41 -92
  194. package/dist/mail/Mail.d.ts +10 -106
  195. package/dist/mail/MailManager.d.ts +2 -60
  196. package/dist/mail/index.js +1 -1
  197. package/dist/mail/transports/LogTransport.d.ts +1 -4
  198. package/dist/mail/transports/MemoryTransport.d.ts +1 -63
  199. package/dist/mail/transports/ResendTransport.d.ts +1 -23
  200. package/dist/mail/transports/SmtpTransport.d.ts +1 -31
  201. package/dist/mail/types.d.ts +28 -150
  202. package/dist/{mail-DfEfSQEr.js → mail-76DWy9lj.js} +31 -289
  203. package/dist/mcp/McpServiceProvider.d.ts +4 -10
  204. package/dist/mcp/create-mcp-server.d.ts +25 -57
  205. package/dist/mcp/endpoint.d.ts +12 -36
  206. package/dist/mcp/index.js +1 -1
  207. package/dist/mvc/Controller.d.ts +46 -253
  208. package/dist/mvc/Router.d.ts +50 -129
  209. package/dist/mvc/inertia/InertiaEngine.d.ts +18 -48
  210. package/dist/mvc/inertia/shared.d.ts +6 -19
  211. package/dist/mvc/mount-route.d.ts +2 -6
  212. package/dist/mvc/view.d.ts +1 -2
  213. package/dist/notifications/Notification.d.ts +8 -75
  214. package/dist/notifications/NotificationManager.d.ts +15 -88
  215. package/dist/notifications/channels/DatabaseChannel.d.ts +1 -41
  216. package/dist/notifications/channels/MailChannel.d.ts +2 -31
  217. package/dist/notifications/channels/MemoryChannel.d.ts +2 -62
  218. package/dist/notifications/channels/SlackChannel.d.ts +3 -48
  219. package/dist/notifications/index.js +1 -1
  220. package/dist/notifications/notifiable-type.d.ts +3 -6
  221. package/dist/notifications/registry.d.ts +8 -27
  222. package/dist/notifications/types.d.ts +16 -53
  223. package/dist/{notifications-BGqmUNZ8.js → notifications-okWFs9ly.js} +37 -335
  224. package/dist/providers/AuthServiceProvider.d.ts +1 -3
  225. package/dist/providers/AuthorizationServiceProvider.d.ts +2 -3
  226. package/dist/providers/BroadcastServiceProvider.d.ts +1 -3
  227. package/dist/providers/CacheServiceProvider.d.ts +1 -3
  228. package/dist/providers/EncryptionServiceProvider.d.ts +1 -3
  229. package/dist/providers/ErrorServiceProvider.d.ts +1 -4
  230. package/dist/providers/EventServiceProvider.d.ts +1 -3
  231. package/dist/providers/HealthServiceProvider.d.ts +1 -3
  232. package/dist/providers/I18nServiceProvider.d.ts +6 -10
  233. package/dist/providers/InertiaServiceProvider.d.ts +1 -4
  234. package/dist/providers/LogServiceProvider.d.ts +1 -3
  235. package/dist/providers/MailServiceProvider.d.ts +1 -3
  236. package/dist/providers/NotificationServiceProvider.d.ts +1 -3
  237. package/dist/providers/OAuthServiceProvider.d.ts +1 -3
  238. package/dist/providers/QueueServiceProvider.d.ts +1 -3
  239. package/dist/providers/SchedulingServiceProvider.d.ts +1 -3
  240. package/dist/providers/StorageServiceProvider.d.ts +1 -3
  241. package/dist/queue/FailedJobReporter.d.ts +1 -24
  242. package/dist/queue/Job.d.ts +12 -99
  243. package/dist/queue/QueueManager.d.ts +6 -57
  244. package/dist/queue/Worker.d.ts +4 -65
  245. package/dist/queue/drivers/MemoryDriver.d.ts +3 -44
  246. package/dist/queue/drivers/RedisDriver.d.ts +7 -65
  247. package/dist/queue/drivers/SqsDriver.d.ts +6 -57
  248. package/dist/queue/drivers/SyncDriver.d.ts +10 -13
  249. package/dist/queue/index.js +2 -2
  250. package/dist/queue/types.d.ts +10 -92
  251. package/dist/{queue-CXrRK85G.js → queue-CcXCjuJI.js} +32 -260
  252. package/dist/redis/RedisApiTokenStore.d.ts +4 -56
  253. package/dist/redis/RedisEmailVerificationStore.d.ts +4 -37
  254. package/dist/redis/RedisOAuthStateStore.d.ts +2 -10
  255. package/dist/redis/RedisPasswordResetStore.d.ts +4 -37
  256. package/dist/redis/RedisRateLimitStore.d.ts +16 -49
  257. package/dist/redis/RedisSessionStore.d.ts +3 -44
  258. package/dist/redis/client.d.ts +2 -32
  259. package/dist/redis/index.js +47 -232
  260. package/dist/redis/redis-values.d.ts +6 -12
  261. package/dist/redis/scan-keys.d.ts +1 -4
  262. package/dist/request-CLOYytGP.js +68 -0
  263. package/dist/runtime/index.d.ts +2 -0
  264. package/dist/runtime/index.js +108 -74
  265. package/dist/scheduling/CronParser.d.ts +0 -29
  266. package/dist/scheduling/Schedule.d.ts +1 -153
  267. package/dist/scheduling/ScheduledTask.d.ts +0 -31
  268. package/dist/scheduling/Scheduler.d.ts +0 -70
  269. package/dist/scheduling/index.js +1 -1
  270. package/dist/scheduling/types.d.ts +4 -65
  271. package/dist/{scheduling-CPiEdtQd.js → scheduling-C6tcOtUl.js} +2 -287
  272. package/dist/storage/StorageManager.d.ts +0 -48
  273. package/dist/storage/drivers/LocalDriver.d.ts +1 -25
  274. package/dist/storage/drivers/MemoryDriver.d.ts +5 -35
  275. package/dist/storage/drivers/S3Driver.d.ts +6 -36
  276. package/dist/storage/drivers/s3-acl.d.ts +5 -10
  277. package/dist/storage/index.js +1 -1
  278. package/dist/storage/types.d.ts +27 -265
  279. package/dist/{storage-TLD9t0Q2.js → storage-BB59f07j.js} +17 -157
  280. package/dist/support/contained-path.d.ts +10 -20
  281. package/dist/support/error-polyfill.d.ts +4 -6
  282. package/dist/support/expiry.d.ts +17 -33
  283. package/dist/support/expiry.js +17 -33
  284. package/dist/support/import-map.d.ts +3 -7
  285. package/dist/support/inertia-defaults.d.ts +5 -10
  286. package/dist/support/redirect-target.d.ts +4 -6
  287. package/dist/support/stack-frames.d.ts +11 -50
  288. package/dist/support/trim-slashes.d.ts +4 -7
  289. package/dist/support/warn-once.d.ts +2 -6
  290. package/dist/{trim-slashes-ZJ_VsY5s.js → trim-slashes-BLY9hKAa.js} +4 -7
  291. package/dist/{vite-manifest-BGfWbPYp.js → vite-manifest-CTQp-SOo.js} +34 -58
  292. package/package.json +6 -2
  293. package/dist/client-Dd7vLcqp.js +0 -27
  294. package/dist/context-DoD0c7J_.js +0 -26
  295. package/dist/endpoint-D-20PiHY.js +0 -46
  296. package/dist/hot-disposables-WsTX2ySN.js +0 -281
  297. package/dist/request-CRVuIiQr.js +0 -78
@@ -1,6 +1,6 @@
1
1
  import { t as __exportAll } from "./rolldown-runtime-B4FMCO8f.js";
2
- import { r as ServiceProvider } from "./loopback-guard-D0Kc7-xc.js";
3
- import { n as createMcpAccessGuard, r as isMcpEndpointEnabled, t as MCP_ENDPOINT_PATH } from "./endpoint-D-20PiHY.js";
2
+ import { r as ServiceProvider } from "./loopback-guard-DT9gHF0F.js";
3
+ import { n as createMcpAccessGuard, r as isMcpEndpointEnabled, t as MCP_ENDPOINT_PATH } from "./endpoint-Dsw3Acvq.js";
4
4
  import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
5
5
  import { z } from "zod";
6
6
  //#region src/mcp/create-mcp-server.ts
@@ -10,10 +10,9 @@ function isAgentRoute(route) {
10
10
  return typeof method === "string" && typeof path === "string" && typeof agent === "object" && agent !== null;
11
11
  }
12
12
  /**
13
- * One tool as an agent editing the app should see it. Annotations are
14
- * reported **as declared**, with no defaults filled in: the derivation layer
15
- * owns the GET/QUERY → readOnlyHint rule, and restating it here would be a
16
- * second copy of it that can disagree.
13
+ * One tool as an agent editing the app should see it. Annotations are reported
14
+ * **as declared**, no defaults filled in: the derivation layer owns the
15
+ * GET/QUERY → readOnlyHint rule, and a second copy here could disagree.
17
16
  */
18
17
  function describeAgentRoute(route) {
19
18
  const { agent } = route;
@@ -230,10 +229,8 @@ function createMcpServer(options) {
230
229
  let failed = false;
231
230
  /**
232
231
  * Runs one generator and files its artifacts under `generated` or
233
- * `skipped`. A generator that returns an empty `outputPath` had
234
- * nothing to describe, which is a normal shape for a project rather
235
- * than a failure; a throw is the opposite, and is what `isError`
236
- * reports on.
232
+ * `skipped`. An empty `outputPath` is a normal project shape, not a
233
+ * failure; a throw is, and is what `isError` reports on.
237
234
  */
238
235
  const run = async (artifacts, generate) => {
239
236
  try {
@@ -401,16 +398,10 @@ function createMcpServer(options) {
401
398
  //#region src/mcp/McpServiceProvider.ts
402
399
  var McpServiceProvider_exports = /* @__PURE__ */ __exportAll({ McpServiceProvider: () => McpServiceProvider });
403
400
  /**
404
- * Registers the MCP (Model Context Protocol) endpoint at /_guren/mcp.
405
- *
406
- * Only active while `isMcpEndpointEnabled()` holds, so registering this
407
- * provider directly honours the same `GUREN_MCP=1` opt-in that `Application`
408
- * gates on — and the same condition that exempts the endpoint from CSRF.
409
- * It allows AI coding agents (Claude Code, Cursor, etc.) to introspect
410
- * the project structure, run integrity checks, and scaffold code.
411
- *
412
- * @guren/cli is loaded via dynamic import to avoid circular dependencies
413
- * (@guren/server -> @guren/cli -> @guren/core -> @guren/server).
401
+ * Registers the MCP endpoint at /_guren/mcp, so AI coding agents can introspect
402
+ * the project, run integrity checks, and scaffold code. Only active while
403
+ * `isMcpEndpointEnabled()` holds — the same `GUREN_MCP=1` opt-in that exempts
404
+ * the endpoint from CSRF. @guren/cli is imported dynamically to break a cycle.
414
405
  */
415
406
  var McpServiceProvider = class extends ServiceProvider {
416
407
  register() {}
@@ -1,8 +1,5 @@
1
1
  import { randomBytes, randomInt, randomUUID } from "crypto";
2
2
  //#region src/encryption/Random.ts
3
- /**
4
- * Character sets for random string generation.
5
- */
6
3
  const CHARSETS = {
7
4
  alphanumeric: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
8
5
  alphabetic: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
@@ -12,10 +9,9 @@ const CHARSETS = {
12
9
  "url-safe": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
13
10
  };
14
11
  /**
15
- * Map random bytes onto a character set without modulo bias: bytes that fall
16
- * into the truncated remainder of the 0-255 range are discarded and redrawn,
17
- * so every character stays equally likely (a plain `byte % chars.length`
18
- * skews toward the front of the set whenever 256 is not a multiple of it).
12
+ * Maps random bytes onto a character set without modulo bias: bytes above the
13
+ * largest multiple of `chars.length` under 256 are discarded and redrawn, so
14
+ * every character stays equally likely.
19
15
  */
20
16
  function unbiasedRandomChars(length, chars) {
21
17
  if (!Number.isInteger(length) || length < 0) throw new RangeError(`Random string length must be a non-negative integer, received ${length}.`);
@@ -31,90 +27,35 @@ function unbiasedRandomChars(length, chars) {
31
27
  }
32
28
  return result;
33
29
  }
34
- /**
35
- * Generate a cryptographically secure random string.
36
- *
37
- * @example
38
- * ```typescript
39
- * randomString(32) // 32-character alphanumeric string
40
- * randomString(16, { charset: 'hex' }) // 16-character hex string
41
- * randomString(24, { charset: 'url-safe' }) // URL-safe string
42
- * ```
43
- */
30
+ /** Cryptographically secure random string. */
44
31
  function randomString(length, options = {}) {
45
32
  const { charset = "alphanumeric" } = options;
46
33
  return unbiasedRandomChars(length, CHARSETS[charset]);
47
34
  }
48
- /**
49
- * Generate random bytes.
50
- *
51
- * @example
52
- * ```typescript
53
- * const bytes = random(32) // 32 random bytes
54
- * ```
55
- */
35
+ /** Cryptographically secure random bytes. */
56
36
  function random(length) {
57
37
  return randomBytes(length);
58
38
  }
59
- /**
60
- * Generate random bytes as hex string.
61
- */
62
39
  function randomHex(length) {
63
40
  return randomBytes(length).toString("hex");
64
41
  }
65
- /**
66
- * Generate random bytes as base64 string.
67
- */
68
42
  function randomBase64(length) {
69
43
  return randomBytes(length).toString("base64");
70
44
  }
71
- /**
72
- * Generate random bytes as URL-safe base64 string.
73
- */
74
45
  function randomBase64Url(length) {
75
46
  return randomBytes(length).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
76
47
  }
77
- /**
78
- * Generate a UUID v4.
79
- *
80
- * @example
81
- * ```typescript
82
- * const id = uuid() // e.g., '550e8400-e29b-41d4-a716-446655440000'
83
- * ```
84
- */
85
48
  function uuid() {
86
49
  return randomUUID();
87
50
  }
88
- /**
89
- * Generate a secure random integer.
90
- *
91
- * @example
92
- * ```typescript
93
- * randomInt(1, 100) // Random number between 1 and 100 (inclusive)
94
- * ```
95
- */
51
+ /** Secure random integer in `[min, max]` — `max` is inclusive. */
96
52
  function randomInt$1(min, max) {
97
53
  return randomInt(min, max + 1);
98
54
  }
99
- /**
100
- * Generate a random token suitable for URLs.
101
- *
102
- * @example
103
- * ```typescript
104
- * const token = urlSafeToken(32) // URL-safe 32-character token
105
- * ```
106
- */
55
+ /** URL-safe token of exactly `length` characters. */
107
56
  function urlSafeToken(length = 32) {
108
57
  return randomBase64Url(Math.ceil(length * .75)).slice(0, length);
109
58
  }
110
- /**
111
- * Generate a secure random password.
112
- *
113
- * @example
114
- * ```typescript
115
- * const password = generatePassword(16) // Random 16-character password
116
- * ```
117
- */
118
59
  function generatePassword(length = 16, options = {}) {
119
60
  const { uppercase = true, lowercase = true, numbers = true, symbols = true } = options;
120
61
  let chars = "";
@@ -125,36 +66,14 @@ function generatePassword(length = 16, options = {}) {
125
66
  if (chars.length === 0) chars = CHARSETS.alphanumeric;
126
67
  return unbiasedRandomChars(length, chars);
127
68
  }
128
- /**
129
- * Generate a random OTP (One-Time Password).
130
- *
131
- * @example
132
- * ```typescript
133
- * const otp = generateOtp(6) // e.g., '482901'
134
- * ```
135
- */
69
+ /** One-time password. */
136
70
  function generateOtp(length = 6) {
137
71
  return randomString(length, { charset: "numeric" });
138
72
  }
139
- /**
140
- * Generate a random slug-friendly string.
141
- *
142
- * @example
143
- * ```typescript
144
- * const slug = generateSlug() // e.g., 'a8b2c4d6e8'
145
- * ```
146
- */
147
73
  function generateSlug(length = 10) {
148
74
  return randomString(length, { charset: "hex" });
149
75
  }
150
- /**
151
- * Shuffle an array using Fisher-Yates algorithm with secure random.
152
- *
153
- * @example
154
- * ```typescript
155
- * const shuffled = shuffle([1, 2, 3, 4, 5])
156
- * ```
157
- */
76
+ /** Fisher-Yates, drawing from the secure source. */
158
77
  function shuffle(array) {
159
78
  const result = [...array];
160
79
  for (let i = result.length - 1; i > 0; i--) {
@@ -163,26 +82,10 @@ function shuffle(array) {
163
82
  }
164
83
  return result;
165
84
  }
166
- /**
167
- * Pick a random element from an array.
168
- *
169
- * @example
170
- * ```typescript
171
- * const item = pick(['a', 'b', 'c']) // Random element
172
- * ```
173
- */
174
85
  function pick(array) {
175
86
  if (array.length === 0) throw new Error("Cannot pick from empty array.");
176
87
  return array[randomInt$1(0, array.length - 1)];
177
88
  }
178
- /**
179
- * Pick multiple random elements from an array.
180
- *
181
- * @example
182
- * ```typescript
183
- * const items = sample(['a', 'b', 'c', 'd'], 2) // Two random elements
184
- * ```
185
- */
186
89
  function sample(array, count) {
187
90
  if (count > array.length) throw new Error("Sample count exceeds array length.");
188
91
  return shuffle(array).slice(0, count);
@@ -0,0 +1,31 @@
1
+ /**
2
+ * The notification an application sends its approvers when an agent tool call
3
+ * becomes a pending approval request (RFC 0016 §5.4 item 4).
4
+ *
5
+ * Takes a request, not a recipient: who the approvers are is never the
6
+ * framework's decision. Deliberately unimported by `approval.ts`, so a runtime
7
+ * that never notifies does not pull the notifications subsystem into its graph.
8
+ * Not queued (`shouldQueue` stays false): an approval is answered within minutes
9
+ * or expires, and a worker that is behind notifies after the window closed.
10
+ */
11
+ import { Notification } from '../notifications/Notification.js';
12
+ import type { Notifiable, NotificationMailMessage, SlackMessage } from '../notifications/types.js';
13
+ import type { AgentApprovalRequest } from './approval.js';
14
+ export declare class AgentApprovalRequested extends Notification {
15
+ readonly request: AgentApprovalRequest;
16
+ constructor(request: AgentApprovalRequest);
17
+ /**
18
+ * Mail and database by default — "tell someone now" and "there is a list of
19
+ * things waiting". An application overrides by subclassing.
20
+ */
21
+ via(_notifiable: Notifiable): string[];
22
+ toMail(_notifiable: Notifiable): NotificationMailMessage;
23
+ /**
24
+ * The record's own fields, minus the fingerprint: that is a hash of the *raw*
25
+ * arguments (see `approval.ts`), while a database notification is read by
26
+ * more people and kept longer. The arguments an approver judges are `input`,
27
+ * already masked.
28
+ */
29
+ toDatabase(_notifiable: Notifiable): Record<string, unknown>;
30
+ toSlack(_notifiable: Notifiable): SlackMessage;
31
+ }
@@ -0,0 +1,184 @@
1
+ /**
2
+ * The agent approval queue (RFC 0016 §5.4 item 4): a tool declaring
3
+ * `approval: 'required'` becomes a pending record, approvers are notified, and
4
+ * only a *human* decision turns it into permission for one later call.
5
+ * Declarations and pure derivation only, like `audit.ts`: no database, clock or
6
+ * notification. {@link AgentApprovalRequest.input} arrives already redacted;
7
+ * the *fingerprint* is computed from the **raw** arguments, or approving
8
+ * `users.setPassword {id: 5, password: '…'}` would authorize the same call
9
+ * with a different password.
10
+ */
11
+ import type { AgentPrincipal } from './events.js';
12
+ /**
13
+ * How long a pending request stays answerable by default: one hour. An approval
14
+ * is permission for one call *now*, not a standing grant.
15
+ */
16
+ export declare const DEFAULT_AGENT_APPROVAL_TTL_MS: number;
17
+ /**
18
+ * The configuration key an adapter reads the queue out of, as a value: `guren
19
+ * check` finds the `mcpPlugin({ … })` call by it and cannot import
20
+ * `@guren/plugin-mcp`, so a restated string would let a rename leave the check
21
+ * passing every app silently. Same rule, two readers, as
22
+ * {@link file://./meta-tools.ts}.
23
+ */
24
+ export declare const AGENT_APPROVAL_CONFIG_KEY = "approvals";
25
+ /**
26
+ * What a request is waiting for, or what happened to it. `'expired'` is a
27
+ * *stored* status only for a store that sweeps; {@link agentApprovalStatusAt}
28
+ * derives expiry from `expiresAt` against a clock, so a store that never
29
+ * sweeps and one that sweeps hourly answer the same way.
30
+ */
31
+ export type AgentApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
32
+ /** One pending, answered, or spent approval request. */
33
+ export interface AgentApprovalRequest {
34
+ /** Opaque identity, quoted back to the caller so it can poll. */
35
+ id: string;
36
+ /** The tool the call addressed, by its catalogue name. */
37
+ tool: string;
38
+ /**
39
+ * The call's arguments **already redacted** — see the module header. Shown
40
+ * to the approver and persisted; never what the match is computed from.
41
+ */
42
+ input: Record<string, unknown>;
43
+ /**
44
+ * {@link agentApprovalFingerprint} of the *raw* arguments — the hash, never
45
+ * the canonical string: a store holding a reversible copy of every argument
46
+ * an agent ever passed would be a second place secrets live.
47
+ */
48
+ fingerprint: string;
49
+ /** Who asked. `null` for a surface with no verified principal. */
50
+ principal: AgentPrincipal | null;
51
+ /**
52
+ * {@link agentApprovalPrincipalKey} of `principal`, denormalized so a store
53
+ * can index the match without knowing how the key is derived.
54
+ */
55
+ principalKey: string;
56
+ /** ISO 8601, UTC. */
57
+ requestedAt: string;
58
+ /** ISO 8601, UTC. Past this instant the record authorizes nothing. */
59
+ expiresAt: string;
60
+ status: AgentApprovalStatus;
61
+ /** ISO 8601, UTC — when a human answered. Absent while pending. */
62
+ resolvedAt?: string;
63
+ /**
64
+ * Who answered, in whatever vocabulary the application approves in. Never
65
+ * interpreted by the framework; it exists so the answer to "who let this
66
+ * through" is in the record rather than only in the approval UI's logs.
67
+ */
68
+ resolvedBy?: string;
69
+ /** ISO 8601, UTC — when the approval was spent. Set by `consume`. */
70
+ consumedAt?: string;
71
+ }
72
+ /** The three fields that identify *this* call for the store's lookup. */
73
+ export interface AgentApprovalMatch {
74
+ tool: string;
75
+ fingerprint: string;
76
+ principalKey: string;
77
+ }
78
+ /**
79
+ * Where pending approvals live. The application implements it; the framework
80
+ * ships no default, because a queue degrading to process memory on Workers or
81
+ * Lambda would answer "approved" for a record the next isolate never heard of
82
+ * (`gateToolCall` fails closed instead). No `list`/`approve`/`reject`: resolving
83
+ * a request is a human action, through the application's own interface.
84
+ */
85
+ export interface AgentApprovalStore {
86
+ /** Persist a new pending request. */
87
+ create(request: AgentApprovalRequest): Promise<void>;
88
+ /**
89
+ * The request with this id, or `null`. Backs `guren.approval_status`. Takes
90
+ * no principal: the caller-scoping rule is applied by the framework (see
91
+ * {@link agentApprovalVisibleTo}), because a store that forgot to filter
92
+ * would leak other principals' pending actions and nothing would fail.
93
+ */
94
+ find(id: string): Promise<AgentApprovalRequest | null>;
95
+ /**
96
+ * The **unconsumed** record matching this exact call, or `null`; the most
97
+ * recently requested when several match. Not "the approved one": the gate
98
+ * must see a *pending* or *rejected* match too, or an agent polling by
99
+ * re-calling the tool creates unbounded records and notifies approvers once
100
+ * per poll. Expiry is not filtered here either — see {@link agentApprovalUsableAt}.
101
+ */
102
+ findMatch(match: AgentApprovalMatch): Promise<AgentApprovalRequest | null>;
103
+ /**
104
+ * Spend the approval with this id, returning whether *this* call won it.
105
+ * Must be a compare-and-set: two concurrent calls find the same approved
106
+ * record, and an unconditional write hands it to both. The gate treats
107
+ * `false` as "no approval", not an error, and creates a new pending record.
108
+ */
109
+ consume(id: string): Promise<boolean>;
110
+ }
111
+ /**
112
+ * A stable key for "the same caller". Kind and id only: a token's *abilities*
113
+ * are not part of the identity, so an approval a human granted survives a
114
+ * rotation or re-scope, and the scope gate has already run by the time this key
115
+ * is used. The id's type is part of the key — collapsing `5` and `'5'` would
116
+ * let a service token named `"5"` spend a user 5 approval.
117
+ */
118
+ export declare function agentApprovalPrincipalKey(principal: AgentPrincipal | null): string;
119
+ /**
120
+ * The canonical text of one call's arguments — the *only* rule for "same
121
+ * call"; a second serialization is how approving `posts.destroy {id: 5}`
122
+ * silently comes to authorize `{id: 9}`. Normalizes object key order at every
123
+ * depth, nothing else: types, array order and absent-vs-null distinguish calls.
124
+ * A value JSON cannot carry throws; the gate turns that into a fail-closed refusal.
125
+ */
126
+ export declare function canonicalizeAgentApprovalInput(input: Record<string, unknown>): string;
127
+ /**
128
+ * The fingerprint an approval is bound to: SHA-256 of
129
+ * {@link canonicalizeAgentApprovalInput}, hex. Hashed rather than stored
130
+ * verbatim because these are the **raw** arguments while the record persists
131
+ * and is shown to a human. Async because `crypto.subtle` is — the one digest
132
+ * available unchanged on Bun, Node and Workers.
133
+ */
134
+ export declare function agentApprovalFingerprint(input: Record<string, unknown>): Promise<string>;
135
+ /** What {@link buildAgentApprovalRequest} needs beyond the clock. */
136
+ export interface AgentApprovalRequestInput {
137
+ tool: string;
138
+ /** Already redacted — see the module header. */
139
+ input: Record<string, unknown>;
140
+ /** From {@link agentApprovalFingerprint}, over the *raw* arguments. */
141
+ fingerprint: string;
142
+ principal: AgentPrincipal | null;
143
+ /** Defaults to {@link DEFAULT_AGENT_APPROVAL_TTL_MS}. */
144
+ ttlMs?: number;
145
+ }
146
+ /**
147
+ * Derive a new pending record. `now` is a parameter because the caller that
148
+ * creates a record also decides whether an existing one has expired, and two
149
+ * clock reads can disagree. The id comes from `crypto.randomUUID()` rather than
150
+ * a parameter: the caller reads it off the returned record, and threading one
151
+ * in would invite two call sites to generate ids differently.
152
+ */
153
+ export declare function buildAgentApprovalRequest(request: AgentApprovalRequestInput, now: Date): AgentApprovalRequest;
154
+ /**
155
+ * Whether a record has passed its expiry at `now`. An unparseable `expiresAt`
156
+ * counts as expired: treating a date the framework cannot read as "not expired
157
+ * yet" fails open into a permanent approval, and that is the one direction of
158
+ * error nothing outside can notice.
159
+ */
160
+ export declare function agentApprovalExpiredAt(request: AgentApprovalRequest, now: Date): boolean;
161
+ /**
162
+ * The record's status as of `now`, with expiry applied. Derived here rather
163
+ * than filtered by the store: a second copy of the rule is the one that fails
164
+ * open — a store that forgets to compare, or compares in local time, hands out
165
+ * an approval granted last month and nothing reports it. A resolved record
166
+ * keeps its resolution.
167
+ */
168
+ export declare function agentApprovalStatusAt(request: AgentApprovalRequest, now: Date): AgentApprovalStatus;
169
+ /**
170
+ * Whether this record authorizes a call at `now`: approved, unexpired, and not
171
+ * already spent. All three are checked in framework code rather than trusted to
172
+ * the store's query; `consumedAt` too, because the single-use guarantee must
173
+ * not rest on an application's SQL — `consume`'s compare-and-set is the atomic
174
+ * half of it, this is the cheap half.
175
+ */
176
+ export declare function agentApprovalUsableAt(request: AgentApprovalRequest, now: Date): boolean;
177
+ /**
178
+ * Whether `principal` may be told anything at all about `request` — the scope
179
+ * rule of `guren.approval_status` (RFC 0016 §5.4): a caller reads only the
180
+ * status of a request it created, or an agent could walk ids and enumerate
181
+ * other principals' pending actions. A `false` here must be answered *exactly*
182
+ * as an unknown id is: any difference in message, shape or timing reintroduces it.
183
+ */
184
+ export declare function agentApprovalVisibleTo(request: AgentApprovalRequest, principal: AgentPrincipal | null): boolean;
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The one place an agent audit event is announced: to the configured sink, and
3
+ * to the application's event listeners.
4
+ *
5
+ * Here rather than in a protocol adapter because it has two readers —
6
+ * `@guren/plugin-mcp` binds one into the container at boot, `guren tool:call`
7
+ * resolves that binding for the `'cli'` surface. A second copy is how one
8
+ * surface comes to swallow a sink failure the other warns about. Its own module
9
+ * so it can be exercised without standing up an endpoint.
10
+ */
11
+ import type { AgentToolDenied, AgentToolInvoked } from './events.js';
12
+ import type { EventManager } from '../events/index.js';
13
+ import { type AgentAuditRecord } from './audit.js';
14
+ /**
15
+ * The container service an application's audit emitter is published under
16
+ * (`ServiceBindings['agent.audit']`). A constant because `@guren/plugin-mcp`
17
+ * binds it and `@guren/cli` resolves it, and neither depends on the other; two
18
+ * drifted literals would break the wiring *silently* — the CLI recording
19
+ * nothing reads exactly like an application that configured no trail.
20
+ */
21
+ export declare const AGENT_AUDIT_BINDING = "agent.audit";
22
+ /** What an application hands each audit event to. */
23
+ export type AgentAuditSink = (record: AgentAuditRecord) => void | Promise<void>;
24
+ /**
25
+ * What every agent surface calls to record one invocation or one denial. Named
26
+ * because it is a container binding (`'agent.audit'`) as well as a return value.
27
+ */
28
+ export type AgentAuditEmitter = (event: AgentToolInvoked | AgentToolDenied) => void;
29
+ /**
30
+ * **The sink is called directly, not subscribed as a listener**:
31
+ * `EventManager.emit` awaits listeners in a bare `for` loop, so one unrelated
32
+ * application listener throwing would silence the trail. The events are still
33
+ * emitted for genuine listeners (RFC 0016 §5.2). Neither half may fail the call
34
+ * it records: both are caught, the sink's failure warned rather than swallowed.
35
+ */
36
+ export declare function createAuditEmitter(sink: AgentAuditSink | undefined, events: EventManager | undefined, now?: () => Date): AgentAuditEmitter;
@@ -0,0 +1,67 @@
1
+ /**
2
+ * The agent audit record (RFC 0016 §5.2): one invocation or one denial, in the
3
+ * one shape a sink writes as a line and `guren tool:log` reads back.
4
+ * Declarations and pure derivation only — {@link toAuditRecord} takes the
5
+ * instant as an argument — because this module is reachable from runtimes with
6
+ * no filesystem, and a self-timestamping builder cannot be pinned by a test.
7
+ * **Redaction is the emitter's contract:** `AgentToolInvoked.arguments` arrives
8
+ * already through `redactAgentArguments` and is carried verbatim; different
9
+ * masking belongs in the route's `.agent({ redact })`.
10
+ */
11
+ import type { AgentPrincipal, AgentSurface, AgentToolDenialReason, AgentToolDenied, AgentToolInvoked } from './events.js';
12
+ /**
13
+ * Where an application's audit trail is written by default, relative to the
14
+ * app root. `storage/logs/` is the convention `LogManager`'s own examples
15
+ * already use, so an audit trail lands beside the application log rather than
16
+ * inventing a second place to look.
17
+ */
18
+ export declare const DEFAULT_AGENT_AUDIT_PATH = "storage/logs/agent-audit.log";
19
+ /** What every audit record carries, whatever its outcome. */
20
+ interface AgentAuditRecordBase {
21
+ /** ISO 8601, in UTC — the instant the record was made. */
22
+ ts: string;
23
+ surface: AgentSurface;
24
+ tool: string;
25
+ principal: AgentPrincipal | null;
26
+ /** Already redacted by the emitter; see the module header. */
27
+ arguments: Record<string, unknown>;
28
+ }
29
+ /**
30
+ * A tool that ran. `status` and `durationMs` exist here and nowhere else:
31
+ * a denial refuses before any HTTP happens, so there is no status it could
32
+ * honestly report (RFC 0016 §5.2, as amended).
33
+ */
34
+ export interface AgentAuditInvokedRecord extends AgentAuditRecordBase {
35
+ outcome: 'invoked';
36
+ status: number;
37
+ durationMs: number;
38
+ }
39
+ /** A tool call the adapter refused before it reached the application. */
40
+ export interface AgentAuditDeniedRecord extends AgentAuditRecordBase {
41
+ outcome: 'denied';
42
+ reason: AgentToolDenialReason;
43
+ }
44
+ /**
45
+ * One line of the audit trail. A union rather than one interface with optional
46
+ * fields, so a record with a `reason` *and* a `status` cannot be written down:
47
+ * the two outcomes disagree about what happened, and a shape admitting both
48
+ * would let a sink emit that contradiction and a reader believe it.
49
+ */
50
+ export type AgentAuditRecord = AgentAuditInvokedRecord | AgentAuditDeniedRecord;
51
+ /**
52
+ * Derive the record for one audit event. `now` is a parameter because the sink
53
+ * writing the record also picks the dated file it lands in, and two clock reads
54
+ * can disagree across midnight. The two events are told apart structurally, not
55
+ * with `instanceof`: the event classes cross a boundary this repo resolves twice
56
+ * (`dist` for the CLI and plugins, `src` inside `packages/server`).
57
+ */
58
+ export declare function toAuditRecord(event: AgentToolInvoked | AgentToolDenied, now: Date): AgentAuditRecord;
59
+ /**
60
+ * Read one line of an audit file back, or `null` if it is not a record. The one
61
+ * parser on the read side; a second would fail silently, since a record it
62
+ * stops recognising reads as an empty trail. `null` rather than a throw: a file
63
+ * being appended to routinely ends in a partial or blank line. Extra keys are
64
+ * ignored because `DailyFileChannel`'s JSON format wraps the record in a log envelope.
65
+ */
66
+ export declare function parseAuditRecord(line: string): AgentAuditRecord | null;
67
+ export {};