@guren/server 2.15.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 (296) hide show
  1. package/dist/{DocsViewerServiceProvider-qFCaeiUv.js → DocsViewerServiceProvider-D2cuVgtN.js} +7 -12
  2. package/dist/{Hash-C8aejmi8.js → Hash-D2DFd8xX.js} +7 -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 +11 -39
  8. package/dist/agent/approval.d.ts +76 -187
  9. package/dist/agent/audit-emitter.d.ts +16 -44
  10. package/dist/agent/audit.d.ts +20 -56
  11. package/dist/agent/derive.d.ts +32 -66
  12. package/dist/agent/dispatch.d.ts +38 -90
  13. package/dist/agent/events.d.ts +11 -19
  14. package/dist/agent/meta-tools.d.ts +18 -46
  15. package/dist/agent/public.d.ts +6 -25
  16. package/dist/agent/public.js +1 -1
  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 +5 -14
  29. package/dist/auth/password/PasswordHasher.d.ts +5 -13
  30. package/dist/auth/password/hash-format.d.ts +5 -13
  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-DkYoAPVn.js → auth-CbdPH4Cd.js} +169 -502
  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-BwodCA4q.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 +5 -26
  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-erOS9epZ.js → dispatch-BAwzftws.js} +32 -79
  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-D99Vmls3.js → encryption-uwP3Di4D.js} +9 -78
  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 +13 -31
  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 +11 -7
  148. package/dist/http/request.d.ts +32 -118
  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 +10 -20
  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 +2 -1
  170. package/dist/index.js +714 -3011
  171. package/dist/internal/agent-preflight.d.ts +9 -21
  172. package/dist/internal/request.d.ts +6 -19
  173. package/dist/internal/request.js +1 -1
  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 -3
  187. package/dist/logging/channels/FileChannel.d.ts +1 -3
  188. package/dist/logging/daily-file-path.d.ts +7 -16
  189. package/dist/logging/index.js +1 -1
  190. package/dist/logging/types.d.ts +13 -45
  191. package/dist/{logging-B-kngi3q.js → logging-zOY1XCtq.js} +52 -141
  192. package/dist/{loopback-guard-D0Kc7-xc.js → loopback-guard-DT9gHF0F.js} +41 -92
  193. package/dist/mail/Mail.d.ts +10 -106
  194. package/dist/mail/MailManager.d.ts +2 -60
  195. package/dist/mail/index.js +1 -1
  196. package/dist/mail/transports/LogTransport.d.ts +1 -4
  197. package/dist/mail/transports/MemoryTransport.d.ts +1 -63
  198. package/dist/mail/transports/ResendTransport.d.ts +1 -23
  199. package/dist/mail/transports/SmtpTransport.d.ts +1 -31
  200. package/dist/mail/types.d.ts +28 -150
  201. package/dist/{mail-DfEfSQEr.js → mail-76DWy9lj.js} +31 -289
  202. package/dist/mcp/McpServiceProvider.d.ts +4 -10
  203. package/dist/mcp/create-mcp-server.d.ts +25 -57
  204. package/dist/mcp/endpoint.d.ts +12 -36
  205. package/dist/mcp/index.js +1 -1
  206. package/dist/mvc/Controller.d.ts +46 -227
  207. package/dist/mvc/Router.d.ts +50 -129
  208. package/dist/mvc/inertia/InertiaEngine.d.ts +18 -48
  209. package/dist/mvc/inertia/shared.d.ts +6 -19
  210. package/dist/mvc/mount-route.d.ts +2 -6
  211. package/dist/mvc/view.d.ts +1 -2
  212. package/dist/notifications/Notification.d.ts +8 -75
  213. package/dist/notifications/NotificationManager.d.ts +15 -88
  214. package/dist/notifications/channels/DatabaseChannel.d.ts +1 -41
  215. package/dist/notifications/channels/MailChannel.d.ts +2 -31
  216. package/dist/notifications/channels/MemoryChannel.d.ts +2 -62
  217. package/dist/notifications/channels/SlackChannel.d.ts +3 -48
  218. package/dist/notifications/index.js +1 -1
  219. package/dist/notifications/notifiable-type.d.ts +3 -6
  220. package/dist/notifications/registry.d.ts +8 -27
  221. package/dist/notifications/types.d.ts +16 -53
  222. package/dist/{notifications-BGqmUNZ8.js → notifications-okWFs9ly.js} +37 -335
  223. package/dist/providers/AuthServiceProvider.d.ts +1 -3
  224. package/dist/providers/AuthorizationServiceProvider.d.ts +2 -3
  225. package/dist/providers/BroadcastServiceProvider.d.ts +1 -3
  226. package/dist/providers/CacheServiceProvider.d.ts +1 -3
  227. package/dist/providers/EncryptionServiceProvider.d.ts +1 -3
  228. package/dist/providers/ErrorServiceProvider.d.ts +1 -4
  229. package/dist/providers/EventServiceProvider.d.ts +1 -3
  230. package/dist/providers/HealthServiceProvider.d.ts +1 -3
  231. package/dist/providers/I18nServiceProvider.d.ts +6 -10
  232. package/dist/providers/InertiaServiceProvider.d.ts +1 -4
  233. package/dist/providers/LogServiceProvider.d.ts +1 -3
  234. package/dist/providers/MailServiceProvider.d.ts +1 -3
  235. package/dist/providers/NotificationServiceProvider.d.ts +1 -3
  236. package/dist/providers/OAuthServiceProvider.d.ts +1 -3
  237. package/dist/providers/QueueServiceProvider.d.ts +1 -3
  238. package/dist/providers/SchedulingServiceProvider.d.ts +1 -3
  239. package/dist/providers/StorageServiceProvider.d.ts +1 -3
  240. package/dist/queue/FailedJobReporter.d.ts +1 -24
  241. package/dist/queue/Job.d.ts +12 -99
  242. package/dist/queue/QueueManager.d.ts +6 -57
  243. package/dist/queue/Worker.d.ts +4 -65
  244. package/dist/queue/drivers/MemoryDriver.d.ts +3 -44
  245. package/dist/queue/drivers/RedisDriver.d.ts +7 -65
  246. package/dist/queue/drivers/SqsDriver.d.ts +6 -57
  247. package/dist/queue/drivers/SyncDriver.d.ts +10 -13
  248. package/dist/queue/index.js +2 -2
  249. package/dist/queue/types.d.ts +10 -92
  250. package/dist/{queue-CXrRK85G.js → queue-CcXCjuJI.js} +32 -260
  251. package/dist/redis/RedisApiTokenStore.d.ts +4 -56
  252. package/dist/redis/RedisEmailVerificationStore.d.ts +4 -37
  253. package/dist/redis/RedisOAuthStateStore.d.ts +2 -10
  254. package/dist/redis/RedisPasswordResetStore.d.ts +4 -37
  255. package/dist/redis/RedisRateLimitStore.d.ts +16 -49
  256. package/dist/redis/RedisSessionStore.d.ts +3 -44
  257. package/dist/redis/client.d.ts +2 -32
  258. package/dist/redis/index.js +47 -232
  259. package/dist/redis/redis-values.d.ts +6 -12
  260. package/dist/redis/scan-keys.d.ts +1 -4
  261. package/dist/request-CLOYytGP.js +68 -0
  262. package/dist/runtime/index.d.ts +2 -0
  263. package/dist/runtime/index.js +50 -92
  264. package/dist/scheduling/CronParser.d.ts +0 -29
  265. package/dist/scheduling/Schedule.d.ts +1 -153
  266. package/dist/scheduling/ScheduledTask.d.ts +0 -31
  267. package/dist/scheduling/Scheduler.d.ts +0 -70
  268. package/dist/scheduling/index.js +1 -1
  269. package/dist/scheduling/types.d.ts +4 -65
  270. package/dist/{scheduling-CPiEdtQd.js → scheduling-C6tcOtUl.js} +2 -287
  271. package/dist/storage/StorageManager.d.ts +0 -48
  272. package/dist/storage/drivers/LocalDriver.d.ts +1 -25
  273. package/dist/storage/drivers/MemoryDriver.d.ts +5 -35
  274. package/dist/storage/drivers/S3Driver.d.ts +6 -36
  275. package/dist/storage/drivers/s3-acl.d.ts +5 -10
  276. package/dist/storage/index.js +1 -1
  277. package/dist/storage/types.d.ts +27 -265
  278. package/dist/{storage-TLD9t0Q2.js → storage-BB59f07j.js} +17 -157
  279. package/dist/support/contained-path.d.ts +10 -20
  280. package/dist/support/error-polyfill.d.ts +4 -6
  281. package/dist/support/expiry.d.ts +17 -33
  282. package/dist/support/expiry.js +17 -33
  283. package/dist/support/import-map.d.ts +3 -7
  284. package/dist/support/inertia-defaults.d.ts +5 -10
  285. package/dist/support/redirect-target.d.ts +4 -6
  286. package/dist/support/stack-frames.d.ts +11 -50
  287. package/dist/support/trim-slashes.d.ts +4 -7
  288. package/dist/support/warn-once.d.ts +2 -6
  289. package/dist/{trim-slashes-ZJ_VsY5s.js → trim-slashes-BLY9hKAa.js} +4 -7
  290. package/dist/{vite-manifest-w_RSOvQW.js → vite-manifest-CTQp-SOo.js} +34 -58
  291. package/package.json +2 -2
  292. package/dist/client-Dd7vLcqp.js +0 -27
  293. package/dist/context-DoD0c7J_.js +0 -26
  294. package/dist/endpoint-D-20PiHY.js +0 -46
  295. package/dist/hot-disposables-WsTX2ySN.js +0 -281
  296. package/dist/request-CVQwpu2J.js +0 -129
@@ -1,49 +1,19 @@
1
1
  /**
2
2
  * The scope grammar an API token's `abilities` use to reach agent tools
3
- * (RFC 0016 §5.1).
4
- *
5
- * Four forms, and deliberately no more — a grammar an agent-facing consent
6
- * screen has to render is only useful if a human can read a scope and say
7
- * which tools it grants:
8
- *
9
- * - `tool:<name>` one tool, by exact name
10
- * - `tools:read` every tool whose resolved `readOnlyHint` is true
11
- * - `tools:*` every tool
12
- * - `tools:<prefix>.*` every tool named `<prefix>.…`
13
- *
14
- * **Only `tool:` / `tools:` entries are considered.** Every other ability an
15
- * `ApiToken` carries — including the store's default `['*']` — is ignored, so
16
- * it matches nothing. This is the fail-closed half of a deliberate split:
17
- *
18
- * - A token issued before agent tools existed, for an app's own API, holds
19
- * `['*']`. Reading that as "all agent tools" would silently hand every
20
- * already-issued token the whole agent surface the moment an app declares
21
- * its first `.agent()` route. Access to the agent surface is granted by an
22
- * explicit tool scope or not at all (default deny, RFC §5.1); `tools:*` is
23
- * the explicit way to say "everything".
24
- * - A malformed entry is likewise ignored here rather than throwing: this
25
- * module judges an already-issued token, and a token that cannot be parsed
26
- * must grant less, never more. Rejecting a bad scope belongs to the
27
- * *issuer* (`token:issue`, a later PR), which runs {@link parseToolScope}
28
- * over what it was asked for and refuses a `null`.
29
- *
30
- * Matching is case-sensitive and entries are not trimmed. A stored ability
31
- * with stray whitespace is an issuance bug; normalizing it here would make
32
- * the judge more permissive than the issuer, which is the wrong direction.
3
+ * (RFC 0016 §5.1). Four forms, so a human can read a scope on a consent screen:
4
+ * `tool:<name>`, `tools:read` (every tool whose resolved `readOnlyHint` is
5
+ * true), `tools:*`, `tools:<prefix>.*`. **Only `tool:` / `tools:` entries are
6
+ * considered**, so the store's default `['*']` grants no tool (default deny). A
7
+ * malformed entry is ignored, not thrown: this module judges an issued token and
8
+ * must grant less, never more; rejecting belongs to the issuer, which refuses a
9
+ * `null` from {@link parseToolScope}. Case-sensitive and untrimmed, for the same reason.
33
10
  */
34
11
  /**
35
12
  * The MCP tool-name grammar (SEP-986), which a `tool:` scope names and a
36
- * `tools:<prefix>.*` scope has to stay inside — a scope that could not
37
- * possibly name a legal tool is not a scope.
38
- *
39
- * `packages/cli/src/agent-route-check.ts` holds the same pattern for the
40
- * check that fails a build over an illegal tool name. Collapsing the two onto
41
- * this export is a later change, not this one: the CLI reaches `@guren/server`
42
- * through `dist/`, so the collapse needs a built server and belongs with the
43
- * PR that does the build-order work.
44
- *
45
- * Note what the charset gives for free: `*` is not in it, so `tool:posts.*`
46
- * fails the test and needs no special case to be rejected.
13
+ * `tools:<prefix>.*` scope must stay inside. `packages/cli/src/agent-route-check.ts`
14
+ * holds the same pattern; collapsing the two needs a built server, so it waits
15
+ * for the PR doing that build-order work. `*` is not in the charset, so
16
+ * `tool:posts.*` is rejected with no special case.
47
17
  */
48
18
  export declare const AGENT_TOOL_NAME_PATTERN: RegExp;
49
19
  /** One well-formed scope entry, discriminated by what it grants. */
@@ -68,10 +38,8 @@ export type ParsedToolScope =
68
38
  };
69
39
  /**
70
40
  * The shape a tool has to present to be judged: its name, and whether it
71
- * resolved to read-only. Deliberately not `DerivedAgentTool` — the token
72
- * guard, the consent screen and a test fixture all supply this, and none of
73
- * them should have to build a whole derived tool to ask a question about two
74
- * fields. `DerivedAgentTool` is structurally compatible via
41
+ * resolved to read-only. Deliberately not `DerivedAgentTool`, which is
42
+ * structurally compatible via
75
43
  * `{ name: tool.toolName, readOnly: tool.annotations.readOnlyHint }`.
76
44
  */
77
45
  export interface ScopedTool {
@@ -79,19 +47,11 @@ export interface ScopedTool {
79
47
  readOnly: boolean;
80
48
  }
81
49
  /**
82
- * Parse one `abilities` entry.
83
- *
84
- * @returns The scope it denotes, or `null` for an entry that is not a tool
85
- * scope at all (`'*'`, an app's own ability name) and for one that is
86
- * malformed (`tools:`, `tools:.*`, `tools:*.store`, a prefix outside the
87
- * tool-name grammar). Callers cannot tell those apart on purpose: both mean
88
- * "grants no tool", and a judge that distinguished them would be inventing
89
- * a third answer for a two-valued question.
90
- *
91
- * Note the two reserved `tools:` words are matched before the wildcard form,
92
- * so a tool family literally named `read.…` is still reachable as
93
- * `tools:read.*`, while a tool named exactly `read` is reachable only as
94
- * `tool:read` — the reserved word wins its own spelling.
50
+ * Parse one `abilities` entry. The two reserved `tools:` words are matched
51
+ * before the wildcard form, so a family named `read.…` is still reachable as
52
+ * `tools:read.*` while a tool named exactly `read` is only `tool:read`.
53
+ * @returns The scope, or `null` for both a non-tool entry and a malformed one
54
+ * (`tools:`, `tools:.*`, `tools:*.store`): both mean "grants no tool", on purpose.
95
55
  */
96
56
  export declare function parseToolScope(entry: string): ParsedToolScope | null;
97
57
  /**
@@ -100,16 +60,10 @@ export declare function parseToolScope(entry: string): ParsedToolScope | null;
100
60
  */
101
61
  export declare function scopesAllowTool(abilities: readonly string[], tool: ScopedTool): boolean;
102
62
  /**
103
- * The concrete tool names a token's abilities grant, for the surfaces that
104
- * have to show a human what a scope means: the OAuth consent screen, the
105
- * `token:issue` confirmation, and the issuance-time lint.
106
- *
107
- * Literally a filter over {@link scopesAllowTool}, and it must stay one. A
108
- * second matcher that walked entries and accumulated names is how a consent
109
- * screen comes to list a tool the dispatcher then denies — the two answers
110
- * have to be the same answer, not two implementations of one rule.
111
- *
112
- * @returns Names in the order the tools were given, so a caller controls the
113
- * display order by ordering its input.
63
+ * The concrete tool names a token's abilities grant, for the surfaces that show
64
+ * a human what a scope means: the OAuth consent screen, the `token:issue`
65
+ * confirmation, the issuance-time lint. Literally a filter over
66
+ * {@link scopesAllowTool}, and it must stay one: a second matcher is how a
67
+ * consent screen comes to list a tool the dispatcher then denies. Order of `tools`.
114
68
  */
115
69
  export declare function expandToolScopes(abilities: readonly string[], tools: readonly ScopedTool[]): string[];
@@ -5,7 +5,7 @@ import { type ApiTokenStore } from './api-token.js';
5
5
  import type { AttachContextOptions, AuthContext, AuthManagerContract, AuthManagerOptions, AuthCredentials, Guard, GuardContext, GuardFactory, ProviderFactory, UserProvider } from './types.js';
6
6
  /** How `useTokens()` configures the guard it registers. */
7
7
  export interface ApiTokenGuardOptions {
8
- /** Registered provider name used to load the full user record from a token's userId. */
8
+ /** Registered provider name that loads the full user record from a token's userId. */
9
9
  provider?: string;
10
10
  /** Guard registry name (defaults to 'token'). */
11
11
  guardName?: string;
@@ -31,63 +31,42 @@ export declare class AuthManager implements AuthManagerContract {
31
31
  * The guard name an unqualified `auth.guard()` / `auth.user()` call resolves
32
32
  * to for this request. Explicit names always win; otherwise a registered
33
33
  * token guard is selected when the request carries a Bearer Authorization
34
- * header, falling back to the default (session) guard. This is the
35
- * composite-guard rule from RFC 0016: session- and token-authenticated
36
- * requests flow through the same auth surface without configuration.
34
+ * header, falling back to the default (session) guard — the composite-guard
35
+ * rule from RFC 0016.
37
36
  */
38
37
  resolveGuardName(ctx: Context, name?: string): string;
39
38
  createAuthContext(ctx: Context, options?: AttachContextOptions): AuthContext;
40
39
  attempt(name: string, ctx: Context, credentials: AuthCredentials, remember?: boolean): Promise<boolean>;
41
40
  /**
42
- * Shorthand method to register a model-based authentication provider and session guard.
43
- * This simplifies the common case of authenticating users via a database model.
41
+ * Register a model-based authentication provider and session guard — the
42
+ * common case of authenticating users via a database model.
44
43
  *
45
- * @param model - The model class to use for user authentication
46
- * @param options - Options for the ModelUserProvider (partial, with defaults)
47
- * @param providerName - Name for the provider (defaults to 'users')
48
- * @param guardName - Name for the guard (defaults to 'web')
44
+ * @param providerName - Defaults to 'users'
45
+ * @param guardName - Defaults to 'web'
49
46
  */
50
47
  useModel(model: typeof Model<PlainObject>, options?: Partial<ModelUserProviderOptions>, providerName?: string, guardName?: string): void;
51
48
  /**
52
49
  * Register a bearer-token guard backed by an ApiTokenStore and enable
53
50
  * header-based guard selection: requests carrying `Authorization: Bearer`
54
- * resolve to this guard, everything else keeps the default (session)
55
- * guard. The default guard itself is unchanged — session apps keep
56
- * working exactly as before.
57
- *
58
- * @param store - Where issued tokens live (see createApiToken)
59
- * @param options.provider - Registered provider name used to load the full
60
- * user record from the token's userId. Without it, `auth.user()` resolves
61
- * to a minimal `{ id }` record (enough for Gate/policy evaluation).
62
- * @param options.guardName - Guard registry name (defaults to 'token')
51
+ * resolve to this guard, everything else keeps the default (session) guard.
52
+ * Without `options.provider`, `auth.user()` resolves to a minimal `{ id }`
53
+ * record (enough for Gate/policy evaluation).
63
54
  */
64
55
  useTokens(store: ApiTokenStore, options?: ApiTokenGuardOptions): void;
65
56
  /**
66
- * The options the last `useTokens()` call configured its guard with.
67
- *
68
- * Read by machinery that has to *replace* the store without changing
69
- * anything else about how tokens authenticate — `guren tool:dev` installs an
70
- * ephemeral store over the app's, and doing that with a bare `useTokens(store)`
57
+ * The options the last `useTokens()` call configured its guard with. Read by
58
+ * machinery that has to *replace* the store without changing anything else —
59
+ * `guren tool:dev` installs an ephemeral store, and a bare `useTokens(store)`
71
60
  * silently dropped the app's `provider`, so a token resolved to a bare
72
- * `{ id }` instead of the real user record and every policy reading a user
73
- * field behaved differently for no stated reason.
61
+ * `{ id }` and every policy reading a user field behaved differently.
74
62
  */
75
63
  getApiTokenOptions(): ApiTokenGuardOptions;
76
64
  /**
77
- * The token store {@link useTokens} was configured with, or `undefined`
78
- * when this app never called it.
79
- *
80
- * This is the one path by which out-of-request machinery — `guren
81
- * token:issue`, the App MCP adapter's principal lookup — reaches the same
82
- * store the guard verifies against. `useTokens` otherwise closes over
83
- * `store` inside the guard factory, where nothing outside a live request
84
- * can see it, so an issuance command could only write tokens into a store
85
- * of its own making, which no running app would ever read.
86
- *
87
- * Deliberately on this class rather than on `AuthManagerContract`: the
88
- * contract describes what a *request* needs from auth, and handing out the
89
- * raw store is not part of that. Callers reach it through the concrete
90
- * manager (`Application.auth`).
65
+ * The token store {@link useTokens} was configured with, or `undefined`. The
66
+ * one path by which out-of-request machinery (`guren token:issue`, the App MCP
67
+ * adapter's principal lookup) reaches the store the guard verifies against —
68
+ * otherwise `store` is closed over inside the guard factory. On this class
69
+ * rather than `AuthManagerContract`, which describes what a *request* needs.
91
70
  */
92
71
  getApiTokenStore(): ApiTokenStore | undefined;
93
72
  }
@@ -16,8 +16,8 @@ export declare abstract class AuthenticatableModel<TRecord extends PlainObject =
16
16
  * Credential columns can never be mass-assigned: the resolved password-hash
17
17
  * column (unless the model hashes in place into the password field itself)
18
18
  * and the remember-token column. Resolved at call time so a renamed column
19
- * stays covered. Use `forceCreate()`/`forceUpdate()` for trusted
20
- * server-side values such as `passwordHash: 'oauth:...'`.
19
+ * stays covered. Use `forceCreate()`/`forceUpdate()` for trusted server-side
20
+ * values such as `passwordHash: 'oauth:...'`.
21
21
  */
22
22
  protected static deniedFields(): string[];
23
23
  protected static resolvePasswordHasher(): PasswordHasher;
@@ -15,7 +15,6 @@ export declare class SessionGuard<User extends Authenticatable = Authenticatable
15
15
  private sessionKey;
16
16
  private rememberSessionKey;
17
17
  private loadRememberedUser;
18
- /** Strip auth-internal fields before a record is cached or exposed. */
19
18
  private sanitizeUser;
20
19
  private resolveUser;
21
20
  check(): Promise<boolean>;
@@ -6,38 +6,18 @@ export interface TokenGuardOptions<User = unknown> {
6
6
  store: ApiTokenStore;
7
7
  ctx: Context;
8
8
  /**
9
- * Resolves the token's userId to a full user record (sanitized through the
10
- * provider's `sanitize` when present). Without a provider the guard still
11
- * authenticates: `user()` resolves to a minimal `{ id }` record so
12
- * Gate/policy evaluation (which keys on `id`) works out of the box.
9
+ * Resolves the token's userId to a full user record. Without one the guard
10
+ * still authenticates: `user()` resolves to a minimal `{ id }` record.
13
11
  */
14
12
  provider?: UserProvider<User>;
15
13
  /** Update the token's lastUsedAt on successful verification. Default true. */
16
14
  updateLastUsed?: boolean;
17
15
  }
18
16
  /**
19
- * Bearer-token implementation of the Guard contract (RFC 0016 Phase 0).
20
- *
21
- * Reads `Authorization: Bearer <token>`, verifies it against the configured
22
- * ApiTokenStore, and exposes the result through the same Guard surface the
23
- * SessionGuard implements — so `requireAuthenticated()`, `Controller.auth`,
24
- * and Gate resolution treat session- and token-authenticated requests
25
- * identically. On successful verification the result is also written to
26
- * `ctx[API_TOKEN_KEY]`, keeping `getApiToken(ctx)` and `tokenCan*` working
27
- * exactly as they do behind `createBearerTokenMiddleware` — and when that
28
- * middleware already verified this request's token, the guard reuses its
29
- * result instead of paying a second store read and lastUsedAt write.
30
- *
31
- * Credential flows do not apply to bearer tokens: `attempt()`, `login()` and
32
- * `validate()` throw. `logout()` is not a no-op — it revokes the presented
33
- * token, the closest meaningful analogue to ending a session. On a request
34
- * that carries a session cookie *and* a Bearer header, only the token is
35
- * revoked; end the session explicitly via `auth.guard('web').logout()`.
36
- *
37
- * This guard answers authentication only. Token *abilities* are not
38
- * consulted here or by Gate/policies — enforce them where the operation is
39
- * dispatched (`tokenCan*`, `createBearerTokenMiddleware({ abilities })`, or
40
- * the RFC 0016 scope gate), per the RFC's scope-before-policy layering.
17
+ * Bearer-token Guard (RFC 0016 Phase 0). Credential flows (`attempt`,
18
+ * `login`, `validate`) throw; `logout()` revokes the presented token and
19
+ * leaves a co-present session alone. Answers authentication only — token
20
+ * abilities are enforced elsewhere (`tokenCan*`, the RFC 0016 scope gate).
41
21
  */
42
22
  export declare class TokenGuard<User = unknown> implements Guard<User> {
43
23
  private readonly ctx;
@@ -17,29 +17,11 @@ export interface ApiToken {
17
17
  * Implement this for database-backed storage.
18
18
  */
19
19
  export interface ApiTokenStore {
20
- /**
21
- * Store a new API token.
22
- */
23
20
  store(token: ApiToken): Promise<void>;
24
- /**
25
- * Find a token by its hashed value.
26
- */
27
21
  findByHashedToken(hashedToken: string): Promise<ApiToken | null>;
28
- /**
29
- * Find all tokens for a user.
30
- */
31
22
  findByUserId(userId: string | number): Promise<ApiToken[]>;
32
- /**
33
- * Delete a token by its ID.
34
- */
35
23
  delete(id: string): Promise<void>;
36
- /**
37
- * Delete all tokens for a user.
38
- */
39
24
  deleteForUser(userId: string | number): Promise<void>;
40
- /**
41
- * Update the last used timestamp.
42
- */
43
25
  updateLastUsed(id: string, timestamp: Date): Promise<void>;
44
26
  }
45
27
  /**
@@ -55,39 +37,24 @@ export declare class MemoryApiTokenStore implements ApiTokenStore {
55
37
  delete(id: string): Promise<void>;
56
38
  deleteForUser(userId: string | number): Promise<void>;
57
39
  updateLastUsed(id: string, timestamp: Date): Promise<void>;
58
- /**
59
- * Clear all tokens (useful for testing).
60
- */
61
40
  clear(): void;
62
- /**
63
- * Get the number of stored tokens.
64
- */
65
41
  get size(): number;
66
42
  }
67
43
  /**
68
44
  * Configuration for API token creation.
69
45
  */
70
46
  export interface CreateApiTokenOptions {
71
- /**
72
- * Human-readable name for the token.
73
- */
74
47
  name: string;
75
- /**
76
- * User ID the token belongs to.
77
- */
78
48
  userId: string | number;
79
- /**
80
- * Token abilities/scopes.
81
- * @default ['*'] (all abilities)
82
- */
49
+ /** @default ['*'] (all abilities) */
83
50
  abilities?: string[];
84
51
  /**
85
- * Token expiration time in milliseconds from now.
52
+ * Expiration in milliseconds from now.
86
53
  * @default null (never expires)
87
54
  */
88
55
  expiresIn?: number | null;
89
56
  /**
90
- * Token byte length (before encoding).
57
+ * Token byte length, before encoding.
91
58
  * @default 32
92
59
  */
93
60
  tokenLength?: number;
@@ -97,31 +64,14 @@ export interface CreateApiTokenOptions {
97
64
  */
98
65
  export interface CreateApiTokenResult {
99
66
  /**
100
- * The full token to give to the user.
101
- * Format: {id}|{plainToken}
67
+ * The full token to give to the user, formatted `{id}|{plainToken}`.
102
68
  * This is the ONLY time the plain token is available.
103
69
  */
104
70
  plainTextToken: string;
105
- /**
106
- * The token record (without the plain token).
107
- */
108
71
  token: ApiToken;
109
72
  }
110
73
  /**
111
74
  * Create a new API token.
112
- *
113
- * @example
114
- * ```ts
115
- * const { plainTextToken, token } = await createApiToken(store, {
116
- * name: 'My App Token',
117
- * userId: user.id,
118
- * abilities: ['read', 'write'],
119
- * expiresIn: 30 * 24 * 60 * 60 * 1000, // 30 days
120
- * })
121
- *
122
- * // Return plainTextToken to user - this is the only time it's available
123
- * return ctx.json({ token: plainTextToken })
124
- * ```
125
75
  */
126
76
  export declare function createApiToken(store: ApiTokenStore, options: CreateApiTokenOptions): Promise<CreateApiTokenResult>;
127
77
  /**
@@ -132,18 +82,17 @@ export declare function parseApiToken(plainTextToken: string): {
132
82
  token: string;
133
83
  } | null;
134
84
  /**
135
- * Extract the bearer token from an Authorization header value. The one
136
- * parsing rule shared by `createBearerTokenMiddleware`, `TokenGuard`, and
137
- * `hasBearerHeader` below — three readers of the same header must not
138
- * disagree about what a bearer request is.
85
+ * Extract the bearer token from an Authorization header. The one parsing rule
86
+ * shared by `createBearerTokenMiddleware`, `TokenGuard` and `hasBearerHeader`.
87
+ * `\S` keeps the match linear — `\s+(.+)` backtracks quadratically when a
88
+ * trailing newline makes `$` unreachable, on a pre-authentication header — and
89
+ * makes an all-whitespace token "not a bearer request", so CSRF is not skipped.
139
90
  */
140
91
  export declare function readBearerToken(header: string | undefined | null): string | null;
141
92
  /**
142
- * The one answer to "is this request bearer-authenticated?" — the parsing
143
- * rule above applied to the header it is read from. Shared by guard selection
144
- * (`AuthManager.resolveGuardName`) and the CSRF skip for cookie-less bearer
145
- * requests: both must classify a request identically, and a second copy of
146
- * the header name is how they would drift apart.
93
+ * The one answer to "is this request bearer-authenticated?", shared by
94
+ * `AuthManager.resolveGuardName` and the CSRF skip for cookie-less bearer
95
+ * requests, which must classify a request identically.
147
96
  */
148
97
  export declare function hasBearerHeader(ctx: Context): boolean;
149
98
  /**
@@ -157,17 +106,6 @@ export interface VerifiedApiToken {
157
106
  }
158
107
  /**
159
108
  * Verify an API token and return the associated user ID.
160
- *
161
- * @example
162
- * ```ts
163
- * const result = await verifyApiToken(plainTextToken, store)
164
- *
165
- * if (!result) {
166
- * return ctx.json({ error: 'Invalid token' }, 401)
167
- * }
168
- *
169
- * console.log(`User ${result.userId} authenticated with abilities:`, result.abilities)
170
- * ```
171
109
  */
172
110
  export declare function verifyApiToken(plainTextToken: string, store: ApiTokenStore, options?: {
173
111
  updateLastUsed?: boolean;
@@ -192,31 +130,14 @@ export declare function tokenCanAny(token: ApiToken | {
192
130
  }, abilities: string[]): boolean;
193
131
  /**
194
132
  * Revoke (delete) an API token.
195
- *
196
- * @example
197
- * ```ts
198
- * await revokeApiToken(tokenId, store)
199
- * ```
200
133
  */
201
134
  export declare function revokeApiToken(id: string, store: ApiTokenStore): Promise<void>;
202
135
  /**
203
136
  * Revoke all API tokens for a user.
204
- *
205
- * @example
206
- * ```ts
207
- * // Revoke all tokens when user changes password
208
- * await revokeAllApiTokens(user.id, store)
209
- * ```
210
137
  */
211
138
  export declare function revokeAllApiTokens(userId: string | number, store: ApiTokenStore): Promise<void>;
212
139
  /**
213
140
  * Get all API tokens for a user.
214
- *
215
- * @example
216
- * ```ts
217
- * const tokens = await getUserApiTokens(user.id, store)
218
- * // Returns tokens without the plain text (only metadata)
219
- * ```
220
141
  */
221
142
  export declare function getUserApiTokens(userId: string | number, store: ApiTokenStore): Promise<ApiToken[]>;
222
143
  /**
@@ -227,72 +148,27 @@ export declare const API_TOKEN_KEY = "guren:api-token";
227
148
  * Options for the bearer token middleware.
228
149
  */
229
150
  export interface BearerTokenMiddlewareOptions {
230
- /**
231
- * Token store implementation.
232
- */
233
151
  store: ApiTokenStore;
234
- /**
235
- * Function to load the user from the user ID.
236
- */
237
152
  loadUser?: (userId: string | number) => Promise<unknown>;
238
- /**
239
- * Required abilities for this route.
240
- * If not specified, any valid token is accepted.
241
- */
153
+ /** Required abilities. Any valid token is accepted when unset. */
242
154
  abilities?: string[];
243
- /**
244
- * Custom handler when authentication fails.
245
- */
246
155
  onUnauthorized?: (ctx: Context) => Response | Promise<Response>;
247
- /**
248
- * Custom handler when token lacks required abilities.
249
- */
250
156
  onForbidden?: (ctx: Context, required: string[]) => Response | Promise<Response>;
251
- /**
252
- * Header name to extract the token from.
253
- * @default 'Authorization'
254
- */
157
+ /** @default 'Authorization' */
255
158
  headerName?: string;
256
- /**
257
- * Whether to update the token's lastUsedAt timestamp.
258
- * @default true
259
- */
159
+ /** @default true */
260
160
  updateLastUsed?: boolean;
261
161
  }
262
162
  /**
263
163
  * Create middleware that authenticates requests using Bearer tokens.
264
- *
265
164
  * @example
266
165
  * ```ts
267
- * // Basic usage
268
- * app.use('/api/*', createBearerTokenMiddleware({ store }))
269
- *
270
- * // With ability requirement
271
- * router.delete('/api/posts/:id', [PostController, 'destroy'],
272
- * createBearerTokenMiddleware({
273
- * store,
274
- * abilities: ['posts:delete'],
275
- * })
276
- * )
277
- *
278
- * // With user loading
279
- * app.use('/api/*', createBearerTokenMiddleware({
280
- * store,
281
- * loadUser: async (userId) => User.find(userId),
282
- * }))
166
+ * app.use('/api/*', createBearerTokenMiddleware({ store, abilities: ['posts:delete'] }))
283
167
  * ```
284
168
  */
285
169
  export declare function createBearerTokenMiddleware(options: BearerTokenMiddlewareOptions): MiddlewareHandler;
286
170
  /**
287
171
  * Get the authenticated API token from the request context.
288
- *
289
- * @example
290
- * ```ts
291
- * router.get('/api/me', async (ctx) => {
292
- * const { token, userId, abilities } = getApiToken(ctx)!
293
- * return ctx.json({ userId, tokenName: token.name, abilities })
294
- * })
295
- * ```
296
172
  */
297
173
  export declare function getApiToken(ctx: Context): {
298
174
  token: ApiToken;
@@ -303,14 +179,6 @@ export declare function getApiToken(ctx: Context): {
303
179
  * Get the authenticated API token from the request context, or throw.
304
180
  *
305
181
  * @throws {AuthenticationException} When no token is present in the context.
306
- *
307
- * @example
308
- * ```ts
309
- * router.get('/api/me', async (ctx) => {
310
- * const { token, userId, abilities } = getApiTokenOrFail(ctx)
311
- * return ctx.json({ userId, tokenName: token.name, abilities })
312
- * })
313
- * ```
314
182
  */
315
183
  export declare function getApiTokenOrFail(ctx: Context): {
316
184
  token: ApiToken;
@@ -8,16 +8,11 @@ import type { AuthContext } from './types.js';
8
8
  */
9
9
  export declare const AUTH_CONTEXT_KEY = "guren:auth";
10
10
  /**
11
- * Read the framework auth context off a request context.
12
- *
13
- * The lookup and its cast, in one place — nothing more. `ctx.get` returns
14
- * arbitrary values for unknown keys (test doubles and exotic contexts
15
- * included), so the cast is a claim, not a check. A caller whose behavior
16
- * turns on the value really being an auth context probes the member it is
17
- * about to call; `Gate.resolveUser` does exactly that, because a stray value
18
- * there decides whether the legacy `ctx.get('user')` fallback runs. Probing
19
- * here instead would reject contexts that `requireAuthenticated` and
20
- * `requireGuest` can use — they only ever read `check()` / `guest()`.
11
+ * Read the framework auth context off a request context. `ctx.get` returns
12
+ * arbitrary values for unknown keys, so the cast is a claim, not a check. A
13
+ * caller whose behavior turns on a real auth context probes the member it is
14
+ * about to call, as `Gate.resolveUser` does before its legacy `ctx.get('user')`
15
+ * fallback; probing here would reject contexts `requireAuthenticated` can use.
21
16
  */
22
17
  export declare function getAuthContext(ctx: {
23
18
  get: (key: string) => unknown;