@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.
- package/dist/{DocsViewerServiceProvider-qFCaeiUv.js → DocsViewerServiceProvider-D2cuVgtN.js} +7 -12
- package/dist/{Hash-CzrwKeDp.js → Hash-D2DFd8xX.js} +12 -57
- package/dist/{HttpException-BkS3euNG.js → HttpException-BlQ2yEmT.js} +2 -79
- package/dist/{Job-BVT813DO.js → Job-DxQK8h3P.js} +24 -179
- package/dist/{McpServiceProvider-BawsYjgN.js → McpServiceProvider-nNcbCIQX.js} +11 -20
- package/dist/{Random-DbIJ22KQ.js → Random-S0OvCuR8.js} +9 -106
- package/dist/agent/AgentApprovalRequested.d.ts +31 -0
- package/dist/agent/approval.d.ts +184 -0
- package/dist/agent/audit-emitter.d.ts +36 -0
- package/dist/agent/audit.d.ts +67 -0
- package/dist/agent/derive.d.ts +32 -66
- package/dist/agent/dispatch.d.ts +53 -63
- package/dist/agent/events.d.ts +11 -19
- package/dist/agent/meta-tools.d.ts +34 -0
- package/dist/agent/public.d.ts +14 -0
- package/dist/agent/public.js +2 -0
- package/dist/agent/redact.d.ts +16 -38
- package/dist/agent/scopes.d.ts +23 -69
- package/dist/auth/AuthManager.d.ts +19 -40
- package/dist/auth/AuthenticatableModel.d.ts +2 -2
- package/dist/auth/SessionGuard.d.ts +0 -1
- package/dist/auth/TokenGuard.d.ts +6 -26
- package/dist/auth/api-token.d.ts +16 -148
- package/dist/auth/context.d.ts +5 -10
- package/dist/auth/email-verification.d.ts +29 -127
- package/dist/auth/index.js +1 -1
- package/dist/auth/oauth/index.d.ts +35 -57
- package/dist/auth/password/DefaultHasher.d.ts +9 -5
- package/dist/auth/password/PasswordHasher.d.ts +7 -0
- package/dist/auth/password/hash-format.d.ts +11 -0
- package/dist/auth/password-reset.d.ts +16 -42
- package/dist/auth/providers/ModelUserProvider.d.ts +3 -4
- package/dist/auth/providers/UserProvider.d.ts +4 -4
- package/dist/auth/signed-token.d.ts +18 -0
- package/dist/auth/types.d.ts +9 -32
- package/dist/auth/utils.d.ts +6 -27
- package/dist/{auth-BSUc14CD.js → auth-CbdPH4Cd.js} +252 -496
- package/dist/authorization/Gate.d.ts +9 -145
- package/dist/authorization/Policy.d.ts +6 -53
- package/dist/authorization/index.js +1 -1
- package/dist/authorization/middleware.d.ts +16 -62
- package/dist/authorization/types.d.ts +8 -64
- package/dist/{authorization-CdfbCj8J.js → authorization-CdEWZZw3.js} +44 -309
- package/dist/broadcasting/BroadcastManager.d.ts +29 -149
- package/dist/broadcasting/channels/Channel.d.ts +1 -19
- package/dist/broadcasting/channels/PresenceChannel.d.ts +1 -55
- package/dist/broadcasting/channels/PrivateChannel.d.ts +1 -23
- package/dist/broadcasting/drivers/MemoryDriver.d.ts +18 -70
- package/dist/broadcasting/drivers/RedisDriver.d.ts +3 -80
- package/dist/broadcasting/drivers/index.d.ts +1 -1
- package/dist/broadcasting/index.d.ts +1 -1
- package/dist/broadcasting/index.js +1 -1
- package/dist/broadcasting/types.d.ts +7 -88
- package/dist/{broadcasting-BxU-LIfF.js → broadcasting-B5RzB0A2.js} +87 -414
- package/dist/cache/CacheManager.d.ts +8 -62
- package/dist/cache/TaggedCache.d.ts +2 -35
- package/dist/cache/index.js +1 -1
- package/dist/cache/stores/FileStore.d.ts +2 -36
- package/dist/cache/stores/MemoryStore.d.ts +2 -26
- package/dist/cache/stores/RedisStore.d.ts +1 -29
- package/dist/cache/types.d.ts +21 -128
- package/dist/{cache-BYnZf2FR.js → cache-BOOIr324.js} +19 -198
- package/dist/client-C4TEr_Dd.js +9 -0
- package/dist/console/Command.d.ts +17 -126
- package/dist/console/ConsoleKernel.d.ts +2 -74
- package/dist/console/Input.d.ts +5 -113
- package/dist/console/Output.d.ts +3 -99
- package/dist/console/types.d.ts +3 -33
- package/dist/container/Container.d.ts +12 -103
- package/dist/container/ServiceProvider.d.ts +17 -61
- package/dist/container/bindings.d.ts +10 -12
- package/dist/container/defineModule.d.ts +16 -54
- package/dist/container/definePlugin.d.ts +12 -45
- package/dist/container/types.d.ts +2 -34
- package/dist/context-CXk_umpT.js +21 -0
- package/dist/database/Factory.d.ts +4 -57
- package/dist/database/Seeder.d.ts +8 -46
- package/dist/database/SeederRunner.d.ts +3 -33
- package/dist/database/types.d.ts +3 -24
- package/dist/discovery/AutoDiscovery.d.ts +10 -82
- package/dist/dispatch-BAwzftws.js +238 -0
- package/dist/docs-viewer/DocsViewerServiceProvider.d.ts +2 -5
- package/dist/docs-viewer/endpoint.d.ts +5 -11
- package/dist/encryption/Encrypter.d.ts +5 -71
- package/dist/encryption/Hash.d.ts +7 -57
- package/dist/encryption/Random.d.ts +6 -99
- package/dist/encryption/index.js +3 -3
- package/dist/encryption/types.d.ts +10 -72
- package/dist/{encryption-DJtkkhiw.js → encryption-uwP3Di4D.js} +13 -79
- package/dist/{endpoint-D6GIqOpe.js → endpoint-BXipU2Jj.js} +6 -12
- package/dist/endpoint-Dsw3Acvq.js +26 -0
- package/dist/errors/ExceptionHandler.d.ts +3 -90
- package/dist/errors/HttpException.d.ts +2 -79
- package/dist/errors/debug-page.d.ts +3 -17
- package/dist/errors/error-page.d.ts +1 -0
- package/dist/errors/exceptions/AuthenticationException.d.ts +2 -24
- package/dist/errors/exceptions/AuthorizationException.d.ts +1 -24
- package/dist/errors/exceptions/MethodNotAllowedException.d.ts +1 -23
- package/dist/errors/exceptions/NotFoundHttpException.d.ts +1 -27
- package/dist/errors/exceptions/ValidationException.d.ts +2 -43
- package/dist/errors/types.d.ts +1 -25
- package/dist/{errors-BgeOl_DC.js → errors-JpkcCjjn.js} +3 -41
- package/dist/events/Event.d.ts +1 -28
- package/dist/events/EventManager.d.ts +5 -107
- package/dist/events/Listener.d.ts +7 -55
- package/dist/events/builtin.d.ts +0 -24
- package/dist/events/index.js +1 -1
- package/dist/events/types.d.ts +4 -22
- package/dist/{events-aIH_bWRx.js → events-DOmAHDeP.js} +11 -191
- package/dist/facades/index.d.ts +2 -14
- package/dist/health/HealthCheck.d.ts +0 -24
- package/dist/health/HealthManager.d.ts +0 -36
- package/dist/health/checks/CacheCheck.d.ts +2 -17
- package/dist/health/checks/CustomCheck.d.ts +0 -9
- package/dist/health/checks/DatabaseCheck.d.ts +2 -17
- package/dist/health/checks/MemoryCheck.d.ts +3 -12
- package/dist/health/checks/RedisCheck.d.ts +1 -13
- package/dist/health/checks/StorageCheck.d.ts +2 -17
- package/dist/health/index.js +1 -1
- package/dist/health/types.d.ts +4 -24
- package/dist/{health-VWdWXRwh.js → health-DQSvUplL.js} +1 -76
- package/dist/hot-disposables-B5BXqaIH.js +167 -0
- package/dist/hot-reload/hot-disposables.d.ts +22 -74
- package/dist/hot-reload/testing.d.ts +4 -9
- package/dist/http/Application.d.ts +62 -208
- package/dist/http/FormRequest.d.ts +4 -55
- package/dist/http/dev-assets.d.ts +16 -18
- package/dist/http/dev-banner.d.ts +2 -5
- package/dist/http/inertia-assets.d.ts +3 -6
- package/dist/http/middleware/capabilities.d.ts +27 -50
- package/dist/http/middleware/cors.d.ts +4 -29
- package/dist/http/middleware/csp.d.ts +2 -25
- package/dist/http/middleware/csrf.d.ts +20 -95
- package/dist/http/middleware/detect-locale.d.ts +7 -27
- package/dist/http/middleware/force-https.d.ts +6 -24
- package/dist/http/middleware/host-authorization.d.ts +2 -12
- package/dist/http/middleware/loopback-guard.d.ts +15 -33
- package/dist/http/middleware/rate-limit.d.ts +29 -126
- package/dist/http/middleware/redirect-safety.d.ts +2 -20
- package/dist/http/middleware/request-id.d.ts +1 -14
- package/dist/http/middleware/request-logging.d.ts +2 -13
- package/dist/http/middleware/response-headers.d.ts +5 -13
- package/dist/http/middleware/security-headers.d.ts +2 -16
- package/dist/http/middleware/session.d.ts +15 -34
- package/dist/http/middleware/validation-errors-cookie.d.ts +7 -18
- package/dist/http/middleware/validation.d.ts +8 -63
- package/dist/http/public-assets.d.ts +14 -0
- package/dist/http/request.d.ts +49 -48
- package/dist/http/resources/CursorPaginator.d.ts +5 -64
- package/dist/http/resources/Paginator.d.ts +7 -84
- package/dist/http/resources/Resource.d.ts +9 -65
- package/dist/http/resources/ResourceCollection.d.ts +5 -39
- package/dist/http/resources/types.d.ts +10 -30
- package/dist/http/static-documents.d.ts +21 -0
- package/dist/http/validation/Validator.d.ts +25 -85
- package/dist/http/validation/rules.d.ts +48 -147
- package/dist/http/validation/types.d.ts +16 -61
- package/dist/http/vite-assets.d.ts +5 -28
- package/dist/http/vite-dev-server.d.ts +6 -9
- package/dist/http/vite-manifest.d.ts +19 -33
- package/dist/i18n/I18nManager.d.ts +12 -78
- package/dist/i18n/Translator.d.ts +3 -54
- package/dist/i18n/index.js +1 -1
- package/dist/i18n/loaders/JsonLoader.d.ts +4 -31
- package/dist/i18n/loaders/MemoryLoader.d.ts +1 -21
- package/dist/i18n/pluralization.d.ts +4 -13
- package/dist/i18n/types.d.ts +17 -69
- package/dist/{i18n-mcWi7LCd.js → i18n-Cg1aajRP.js} +31 -225
- package/dist/index.d.ts +13 -4
- package/dist/index.js +1036 -3080
- package/dist/internal/agent-preflight.d.ts +9 -21
- package/dist/internal/request.d.ts +10 -17
- package/dist/internal/request.js +2 -2
- package/dist/internal/route-path.d.ts +9 -21
- package/dist/internal/route-path.js +9 -21
- package/dist/internal/zod-compat.d.ts +55 -122
- package/dist/internal/zod-compat.js +39 -70
- package/dist/internal/zod-json-schema.d.ts +18 -54
- package/dist/internal/zod-json-schema.js +46 -123
- package/dist/jsx-runtime.d.ts +3 -8
- package/dist/lambda/index.d.ts +17 -79
- package/dist/lambda/index.js +11 -59
- package/dist/logging/LogManager.d.ts +1 -51
- package/dist/logging/Logger.d.ts +8 -47
- package/dist/logging/channels/ConsoleChannel.d.ts +1 -3
- package/dist/logging/channels/DailyFileChannel.d.ts +1 -5
- package/dist/logging/channels/FileChannel.d.ts +1 -3
- package/dist/logging/daily-file-path.d.ts +15 -0
- package/dist/logging/index.d.ts +1 -0
- package/dist/logging/index.js +2 -2
- package/dist/logging/types.d.ts +13 -45
- package/dist/{logging-CPaRMuPP.js → logging-zOY1XCtq.js} +83 -129
- package/dist/{loopback-guard-D0Kc7-xc.js → loopback-guard-DT9gHF0F.js} +41 -92
- package/dist/mail/Mail.d.ts +10 -106
- package/dist/mail/MailManager.d.ts +2 -60
- package/dist/mail/index.js +1 -1
- package/dist/mail/transports/LogTransport.d.ts +1 -4
- package/dist/mail/transports/MemoryTransport.d.ts +1 -63
- package/dist/mail/transports/ResendTransport.d.ts +1 -23
- package/dist/mail/transports/SmtpTransport.d.ts +1 -31
- package/dist/mail/types.d.ts +28 -150
- package/dist/{mail-DfEfSQEr.js → mail-76DWy9lj.js} +31 -289
- package/dist/mcp/McpServiceProvider.d.ts +4 -10
- package/dist/mcp/create-mcp-server.d.ts +25 -57
- package/dist/mcp/endpoint.d.ts +12 -36
- package/dist/mcp/index.js +1 -1
- package/dist/mvc/Controller.d.ts +46 -253
- package/dist/mvc/Router.d.ts +50 -129
- package/dist/mvc/inertia/InertiaEngine.d.ts +18 -48
- package/dist/mvc/inertia/shared.d.ts +6 -19
- package/dist/mvc/mount-route.d.ts +2 -6
- package/dist/mvc/view.d.ts +1 -2
- package/dist/notifications/Notification.d.ts +8 -75
- package/dist/notifications/NotificationManager.d.ts +15 -88
- package/dist/notifications/channels/DatabaseChannel.d.ts +1 -41
- package/dist/notifications/channels/MailChannel.d.ts +2 -31
- package/dist/notifications/channels/MemoryChannel.d.ts +2 -62
- package/dist/notifications/channels/SlackChannel.d.ts +3 -48
- package/dist/notifications/index.js +1 -1
- package/dist/notifications/notifiable-type.d.ts +3 -6
- package/dist/notifications/registry.d.ts +8 -27
- package/dist/notifications/types.d.ts +16 -53
- package/dist/{notifications-BGqmUNZ8.js → notifications-okWFs9ly.js} +37 -335
- package/dist/providers/AuthServiceProvider.d.ts +1 -3
- package/dist/providers/AuthorizationServiceProvider.d.ts +2 -3
- package/dist/providers/BroadcastServiceProvider.d.ts +1 -3
- package/dist/providers/CacheServiceProvider.d.ts +1 -3
- package/dist/providers/EncryptionServiceProvider.d.ts +1 -3
- package/dist/providers/ErrorServiceProvider.d.ts +1 -4
- package/dist/providers/EventServiceProvider.d.ts +1 -3
- package/dist/providers/HealthServiceProvider.d.ts +1 -3
- package/dist/providers/I18nServiceProvider.d.ts +6 -10
- package/dist/providers/InertiaServiceProvider.d.ts +1 -4
- package/dist/providers/LogServiceProvider.d.ts +1 -3
- package/dist/providers/MailServiceProvider.d.ts +1 -3
- package/dist/providers/NotificationServiceProvider.d.ts +1 -3
- package/dist/providers/OAuthServiceProvider.d.ts +1 -3
- package/dist/providers/QueueServiceProvider.d.ts +1 -3
- package/dist/providers/SchedulingServiceProvider.d.ts +1 -3
- package/dist/providers/StorageServiceProvider.d.ts +1 -3
- package/dist/queue/FailedJobReporter.d.ts +1 -24
- package/dist/queue/Job.d.ts +12 -99
- package/dist/queue/QueueManager.d.ts +6 -57
- package/dist/queue/Worker.d.ts +4 -65
- package/dist/queue/drivers/MemoryDriver.d.ts +3 -44
- package/dist/queue/drivers/RedisDriver.d.ts +7 -65
- package/dist/queue/drivers/SqsDriver.d.ts +6 -57
- package/dist/queue/drivers/SyncDriver.d.ts +10 -13
- package/dist/queue/index.js +2 -2
- package/dist/queue/types.d.ts +10 -92
- package/dist/{queue-CXrRK85G.js → queue-CcXCjuJI.js} +32 -260
- package/dist/redis/RedisApiTokenStore.d.ts +4 -56
- package/dist/redis/RedisEmailVerificationStore.d.ts +4 -37
- package/dist/redis/RedisOAuthStateStore.d.ts +2 -10
- package/dist/redis/RedisPasswordResetStore.d.ts +4 -37
- package/dist/redis/RedisRateLimitStore.d.ts +16 -49
- package/dist/redis/RedisSessionStore.d.ts +3 -44
- package/dist/redis/client.d.ts +2 -32
- package/dist/redis/index.js +47 -232
- package/dist/redis/redis-values.d.ts +6 -12
- package/dist/redis/scan-keys.d.ts +1 -4
- package/dist/request-CLOYytGP.js +68 -0
- package/dist/runtime/index.d.ts +2 -0
- package/dist/runtime/index.js +108 -74
- package/dist/scheduling/CronParser.d.ts +0 -29
- package/dist/scheduling/Schedule.d.ts +1 -153
- package/dist/scheduling/ScheduledTask.d.ts +0 -31
- package/dist/scheduling/Scheduler.d.ts +0 -70
- package/dist/scheduling/index.js +1 -1
- package/dist/scheduling/types.d.ts +4 -65
- package/dist/{scheduling-CPiEdtQd.js → scheduling-C6tcOtUl.js} +2 -287
- package/dist/storage/StorageManager.d.ts +0 -48
- package/dist/storage/drivers/LocalDriver.d.ts +1 -25
- package/dist/storage/drivers/MemoryDriver.d.ts +5 -35
- package/dist/storage/drivers/S3Driver.d.ts +6 -36
- package/dist/storage/drivers/s3-acl.d.ts +5 -10
- package/dist/storage/index.js +1 -1
- package/dist/storage/types.d.ts +27 -265
- package/dist/{storage-TLD9t0Q2.js → storage-BB59f07j.js} +17 -157
- package/dist/support/contained-path.d.ts +10 -20
- package/dist/support/error-polyfill.d.ts +4 -6
- package/dist/support/expiry.d.ts +17 -33
- package/dist/support/expiry.js +17 -33
- package/dist/support/import-map.d.ts +3 -7
- package/dist/support/inertia-defaults.d.ts +5 -10
- package/dist/support/redirect-target.d.ts +4 -6
- package/dist/support/stack-frames.d.ts +11 -50
- package/dist/support/trim-slashes.d.ts +4 -7
- package/dist/support/warn-once.d.ts +2 -6
- package/dist/{trim-slashes-ZJ_VsY5s.js → trim-slashes-BLY9hKAa.js} +4 -7
- package/dist/{vite-manifest-BGfWbPYp.js → vite-manifest-CTQp-SOo.js} +34 -58
- package/package.json +6 -2
- package/dist/client-Dd7vLcqp.js +0 -27
- package/dist/context-DoD0c7J_.js +0 -26
- package/dist/endpoint-D-20PiHY.js +0 -46
- package/dist/hot-disposables-WsTX2ySN.js +0 -281
- 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-
|
|
3
|
-
import { n as createMcpAccessGuard, r as isMcpEndpointEnabled, t as MCP_ENDPOINT_PATH } from "./endpoint-
|
|
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
|
-
*
|
|
15
|
-
*
|
|
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`.
|
|
234
|
-
*
|
|
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
|
|
405
|
-
*
|
|
406
|
-
*
|
|
407
|
-
*
|
|
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
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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 {};
|