@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.
- package/dist/{DocsViewerServiceProvider-qFCaeiUv.js → DocsViewerServiceProvider-D2cuVgtN.js} +7 -12
- package/dist/{Hash-C8aejmi8.js → Hash-D2DFd8xX.js} +7 -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 +11 -39
- package/dist/agent/approval.d.ts +76 -187
- package/dist/agent/audit-emitter.d.ts +16 -44
- package/dist/agent/audit.d.ts +20 -56
- package/dist/agent/derive.d.ts +32 -66
- package/dist/agent/dispatch.d.ts +38 -90
- package/dist/agent/events.d.ts +11 -19
- package/dist/agent/meta-tools.d.ts +18 -46
- package/dist/agent/public.d.ts +6 -25
- package/dist/agent/public.js +1 -1
- 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 +5 -14
- package/dist/auth/password/PasswordHasher.d.ts +5 -13
- package/dist/auth/password/hash-format.d.ts +5 -13
- 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-DkYoAPVn.js → auth-CbdPH4Cd.js} +169 -502
- 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-BwodCA4q.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 +5 -26
- 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-erOS9epZ.js → dispatch-BAwzftws.js} +32 -79
- 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-D99Vmls3.js → encryption-uwP3Di4D.js} +9 -78
- 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 +13 -31
- 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 +11 -7
- package/dist/http/request.d.ts +32 -118
- 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 +10 -20
- 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 +2 -1
- package/dist/index.js +714 -3011
- package/dist/internal/agent-preflight.d.ts +9 -21
- package/dist/internal/request.d.ts +6 -19
- package/dist/internal/request.js +1 -1
- 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 -3
- package/dist/logging/channels/FileChannel.d.ts +1 -3
- package/dist/logging/daily-file-path.d.ts +7 -16
- package/dist/logging/index.js +1 -1
- package/dist/logging/types.d.ts +13 -45
- package/dist/{logging-B-kngi3q.js → logging-zOY1XCtq.js} +52 -141
- 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 -227
- 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 +50 -92
- 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-w_RSOvQW.js → vite-manifest-CTQp-SOo.js} +34 -58
- package/package.json +2 -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-CVQwpu2J.js +0 -129
package/dist/agent/approval.d.ts
CHANGED
|
@@ -1,62 +1,32 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The agent approval queue (RFC 0016 §5.4 item 4): a tool declaring
|
|
3
|
-
* `approval: 'required'`
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* argument, because this module is reachable from every runtime the framework
|
|
11
|
-
* targets and because a rule that timestamped itself could not be pinned by a
|
|
12
|
-
* test. *Where* records live is the application's decision, made once through
|
|
13
|
-
* {@link AgentApprovalStore}; this module only says what one looks like and
|
|
14
|
-
* what makes one usable.
|
|
15
|
-
*
|
|
16
|
-
* **Redaction is the emitter's contract, and nothing here may re-run it.**
|
|
17
|
-
* {@link AgentApprovalRequest.input} arrives having already been through
|
|
18
|
-
* `redactAgentArguments`, the same contract `events.ts` and `audit.ts` state:
|
|
19
|
-
* a record is shown to a human approver and is persisted, so it carries the
|
|
20
|
-
* masked copy. Masking again here would install a second, quieter redaction
|
|
21
|
-
* rule beside the real one, and nothing reading a record could tell which of
|
|
22
|
-
* them produced a mask it is looking at.
|
|
23
|
-
*
|
|
24
|
-
* That contract is exactly why the *fingerprint* is computed from the **raw**
|
|
25
|
-
* arguments instead (see {@link agentApprovalFingerprint}). Binding an
|
|
26
|
-
* approval to the redacted copy would make approving
|
|
27
|
-
* `users.setPassword {id: 5, password: '…'}` authorize the same call with a
|
|
28
|
-
* different password, since the two redact to the same object — the hole the
|
|
29
|
-
* argument-binding rule exists to close.
|
|
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.
|
|
30
10
|
*/
|
|
31
11
|
import type { AgentPrincipal } from './events.js';
|
|
32
12
|
/**
|
|
33
|
-
* How long a pending request stays answerable by default: one hour.
|
|
34
|
-
*
|
|
35
|
-
* An approval is permission for one call *now*, not a standing grant. The
|
|
36
|
-
* default is short for the reason the single-use rule exists — an approval
|
|
37
|
-
* granted last month must not let a call through today — and an application
|
|
38
|
-
* that wants longer says so.
|
|
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.
|
|
39
15
|
*/
|
|
40
16
|
export declare const DEFAULT_AGENT_APPROVAL_TTL_MS: number;
|
|
41
17
|
/**
|
|
42
|
-
* The configuration key an adapter reads the queue out of, as a value
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
* on it, and an app that never installs App MCP is still checked — so without
|
|
48
|
-
* this constant the check would restate the string and the two would drift:
|
|
49
|
-
* renaming the option would leave the check passing every app, silently. Same
|
|
50
|
-
* rule, two readers, as {@link file://./meta-tools.ts}.
|
|
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}.
|
|
51
23
|
*/
|
|
52
24
|
export declare const AGENT_APPROVAL_CONFIG_KEY = "approvals";
|
|
53
25
|
/**
|
|
54
|
-
* What a request is waiting for, or what happened to it.
|
|
55
|
-
*
|
|
56
|
-
* `
|
|
57
|
-
*
|
|
58
|
-
* expiry from `expiresAt` against a clock, so a store that never sweeps and one
|
|
59
|
-
* that sweeps hourly answer the same question the same way.
|
|
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.
|
|
60
30
|
*/
|
|
61
31
|
export type AgentApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
|
|
62
32
|
/** One pending, answered, or spent approval request. */
|
|
@@ -71,11 +41,9 @@ export interface AgentApprovalRequest {
|
|
|
71
41
|
*/
|
|
72
42
|
input: Record<string, unknown>;
|
|
73
43
|
/**
|
|
74
|
-
* {@link agentApprovalFingerprint} of the *raw* arguments
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
* place secrets live, and the redaction above exists precisely so the first
|
|
78
|
-
* one does not.
|
|
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.
|
|
79
47
|
*/
|
|
80
48
|
fingerprint: string;
|
|
81
49
|
/** Who asked. `null` for a surface with no verified principal. */
|
|
@@ -93,10 +61,9 @@ export interface AgentApprovalRequest {
|
|
|
93
61
|
/** ISO 8601, UTC — when a human answered. Absent while pending. */
|
|
94
62
|
resolvedAt?: string;
|
|
95
63
|
/**
|
|
96
|
-
* Who answered, in whatever vocabulary the application approves in
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
* record rather than only in the approval UI's own logs.
|
|
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.
|
|
100
67
|
*/
|
|
101
68
|
resolvedBy?: string;
|
|
102
69
|
/** ISO 8601, UTC — when the approval was spent. Set by `consume`. */
|
|
@@ -110,116 +77,59 @@ export interface AgentApprovalMatch {
|
|
|
110
77
|
}
|
|
111
78
|
/**
|
|
112
79
|
* Where pending approvals live. The application implements it; the framework
|
|
113
|
-
* ships no default,
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
* instead (`gateToolCall`'s fail-closed refusal names the configuration line).
|
|
118
|
-
*
|
|
119
|
-
* Four methods, each one the gate actually reaches for. Deliberately no
|
|
120
|
-
* `list`, `approve`, or `reject`: resolving a request is a human action taken
|
|
121
|
-
* through the application's own interface, over the application's own storage,
|
|
122
|
-
* and a framework interface for it would be a second way to write records that
|
|
123
|
-
* nothing here reads.
|
|
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.
|
|
124
84
|
*/
|
|
125
85
|
export interface AgentApprovalStore {
|
|
126
86
|
/** Persist a new pending request. */
|
|
127
87
|
create(request: AgentApprovalRequest): Promise<void>;
|
|
128
88
|
/**
|
|
129
|
-
* The request with this id, or `null`. Backs `guren.approval_status`.
|
|
130
|
-
*
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
* that forgot to filter would leak other principals' pending actions and
|
|
134
|
-
* nothing would fail.
|
|
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.
|
|
135
93
|
*/
|
|
136
94
|
find(id: string): Promise<AgentApprovalRequest | null>;
|
|
137
95
|
/**
|
|
138
|
-
* The **unconsumed** record matching this exact call, or `null
|
|
139
|
-
*
|
|
140
|
-
*
|
|
141
|
-
*
|
|
142
|
-
*
|
|
143
|
-
* unbounded number of records and notifies approvers once per poll. It needs
|
|
144
|
-
* to see a *rejected* one for the same reason. Expiry is not filtered here
|
|
145
|
-
* either — see {@link agentApprovalUsableAt}.
|
|
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}.
|
|
146
101
|
*/
|
|
147
102
|
findMatch(match: AgentApprovalMatch): Promise<AgentApprovalRequest | null>;
|
|
148
103
|
/**
|
|
149
104
|
* Spend the approval with this id, returning whether *this* call won it.
|
|
150
|
-
*
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
* approved record — an approval is permission for one call, and a `consume`
|
|
154
|
-
* implemented as an unconditional write hands it to both. The gate treats
|
|
155
|
-
* `false` as "no approval", not as an error, and falls through to creating a
|
|
156
|
-
* new pending record.
|
|
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.
|
|
157
108
|
*/
|
|
158
109
|
consume(id: string): Promise<boolean>;
|
|
159
110
|
}
|
|
160
111
|
/**
|
|
161
|
-
* A stable key for "the same caller".
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
*
|
|
166
|
-
* evaporate because an unrelated ability was added. The scope gate has already
|
|
167
|
-
* run by the time this key is used, so the call's own authority is checked
|
|
168
|
-
* regardless.
|
|
169
|
-
*
|
|
170
|
-
* The id's type is part of the key. `id: 5` and `id: '5'` are different
|
|
171
|
-
* principals to every store that distinguishes them, and collapsing the two
|
|
172
|
-
* here would let a service token named `"5"` spend a user 5 approval.
|
|
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.
|
|
173
117
|
*/
|
|
174
118
|
export declare function agentApprovalPrincipalKey(principal: AgentPrincipal | null): string;
|
|
175
119
|
/**
|
|
176
|
-
* The canonical text of one call's arguments — the *only* rule for
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
*
|
|
181
|
-
* serialization is how approving `posts.destroy {id: 5}` comes to authorize
|
|
182
|
-
* `{id: 9}` — the failure this whole binding exists to prevent — and it would
|
|
183
|
-
* do it silently, because both sides would still produce *a* string.
|
|
184
|
-
*
|
|
185
|
-
* What it normalizes: object key order, at every depth. `{a: 1, b: 2}` and
|
|
186
|
-
* `{b: 2, a: 1}` are the same call, nested or not.
|
|
187
|
-
*
|
|
188
|
-
* What it deliberately does **not** normalize, because each would make two
|
|
189
|
-
* genuinely different calls match:
|
|
190
|
-
*
|
|
191
|
-
* - **Types.** `{id: 5}` and `{id: '5'}` are different calls. A route that
|
|
192
|
-
* coerces them to the same value is coercing *after* the gate; the approver
|
|
193
|
-
* saw one of the two written down.
|
|
194
|
-
* - **Array order.** Order is meaning in a JSON array (`ids: [1, 2]` vs
|
|
195
|
-
* `[2, 1]` may be the same call to one route and not to another) and the
|
|
196
|
-
* framework cannot know which.
|
|
197
|
-
* - **Absent vs. explicitly null.** A dropped key and `null` are different
|
|
198
|
-
* inputs to a schema with a default.
|
|
199
|
-
* - Unicode form, number spelling beyond what JSON already fixes, or
|
|
200
|
-
* whitespace inside strings.
|
|
201
|
-
*
|
|
202
|
-
* Total over JSON, and deliberately *not* total over everything else: a value
|
|
203
|
-
* JSON cannot carry throws rather than serializing to a placeholder. A
|
|
204
|
-
* placeholder would make two distinct inputs canonicalize identically, which
|
|
205
|
-
* is the one failure mode worse than refusing — and refusing is safe here,
|
|
206
|
-
* because the gate turns a throw into a fail-closed refusal. Arguments reach
|
|
207
|
-
* this function parsed from JSON-RPC, so no such value can occur in practice;
|
|
208
|
-
* the rule is written down for the surface that one day passes one.
|
|
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.
|
|
209
125
|
*/
|
|
210
126
|
export declare function canonicalizeAgentApprovalInput(input: Record<string, unknown>): string;
|
|
211
127
|
/**
|
|
212
128
|
* The fingerprint an approval is bound to: SHA-256 of
|
|
213
|
-
* {@link canonicalizeAgentApprovalInput}, hex.
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
* own `input` field is redacted precisely to keep out of storage. The hash
|
|
218
|
-
* binds the approval without keeping the secret.
|
|
219
|
-
*
|
|
220
|
-
* Async because `crypto.subtle` is: it is the one digest available unchanged
|
|
221
|
-
* on every runtime the framework targets (Bun, Node, Workers), and the gate is
|
|
222
|
-
* async already.
|
|
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.
|
|
223
133
|
*/
|
|
224
134
|
export declare function agentApprovalFingerprint(input: Record<string, unknown>): Promise<string>;
|
|
225
135
|
/** What {@link buildAgentApprovalRequest} needs beyond the clock. */
|
|
@@ -234,62 +144,41 @@ export interface AgentApprovalRequestInput {
|
|
|
234
144
|
ttlMs?: number;
|
|
235
145
|
}
|
|
236
146
|
/**
|
|
237
|
-
* Derive a new pending record.
|
|
238
|
-
*
|
|
239
|
-
* `now` is a parameter for the reason `toAuditRecord`'s is: the caller that
|
|
147
|
+
* Derive a new pending record. `now` is a parameter because the caller that
|
|
240
148
|
* creates a record also decides whether an existing one has expired, and two
|
|
241
|
-
* clock reads can disagree
|
|
242
|
-
*
|
|
243
|
-
*
|
|
244
|
-
* The id comes from `crypto.randomUUID()` rather than a parameter, which is
|
|
245
|
-
* not the same compromise: an id needs no seam to be testable, since the
|
|
246
|
-
* caller reads it straight off the returned record, and threading one in from
|
|
247
|
-
* every call site would invite two of them to generate ids differently.
|
|
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.
|
|
248
152
|
*/
|
|
249
153
|
export declare function buildAgentApprovalRequest(request: AgentApprovalRequestInput, now: Date): AgentApprovalRequest;
|
|
250
154
|
/**
|
|
251
|
-
* Whether a record has passed its expiry at `now`.
|
|
252
|
-
*
|
|
253
|
-
*
|
|
254
|
-
*
|
|
255
|
-
* fails open into a permanent approval, and this is the one direction of error
|
|
256
|
-
* that cannot be noticed from the outside.
|
|
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.
|
|
257
159
|
*/
|
|
258
160
|
export declare function agentApprovalExpiredAt(request: AgentApprovalRequest, now: Date): boolean;
|
|
259
161
|
/**
|
|
260
|
-
* The record's status as of `now`, with expiry applied.
|
|
261
|
-
*
|
|
262
|
-
* Expiry is derived here rather than filtered by the store on purpose: a store
|
|
263
|
-
* that judged it would be a second copy of the rule, and the copy that fails
|
|
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
|
|
264
164
|
* open — a store that forgets to compare, or compares in local time, hands out
|
|
265
|
-
* an approval granted last month and nothing
|
|
266
|
-
*
|
|
267
|
-
* approval that was already spent is reported by `consumedAt`, not by this.
|
|
165
|
+
* an approval granted last month and nothing reports it. A resolved record
|
|
166
|
+
* keeps its resolution.
|
|
268
167
|
*/
|
|
269
168
|
export declare function agentApprovalStatusAt(request: AgentApprovalRequest, now: Date): AgentApprovalStatus;
|
|
270
169
|
/**
|
|
271
|
-
* Whether this record authorizes a call at `now`: approved, unexpired, and
|
|
272
|
-
*
|
|
273
|
-
*
|
|
274
|
-
*
|
|
275
|
-
*
|
|
276
|
-
* checked even though `findMatch` promises unconsumed records, because the
|
|
277
|
-
* single-use guarantee must not rest on an application's SQL: the *atomic*
|
|
278
|
-
* half of it is `consume`'s compare-and-set, and this is the cheap half.
|
|
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.
|
|
279
175
|
*/
|
|
280
176
|
export declare function agentApprovalUsableAt(request: AgentApprovalRequest, now: Date): boolean;
|
|
281
177
|
/**
|
|
282
|
-
* Whether `principal` may be told anything at all about `request
|
|
283
|
-
*
|
|
284
|
-
*
|
|
285
|
-
*
|
|
286
|
-
*
|
|
287
|
-
* learn what a colleague is waiting to have approved, which is both the
|
|
288
|
-
* content of the request and the fact that it exists.
|
|
289
|
-
*
|
|
290
|
-
* A record this returns `false` for must be answered *exactly* as an unknown
|
|
291
|
-
* id is. Any difference between the two answers — a distinct message, a
|
|
292
|
-
* different error shape, a slower path — is the enumeration the rule forbids,
|
|
293
|
-
* reintroduced.
|
|
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.
|
|
294
183
|
*/
|
|
295
184
|
export declare function agentApprovalVisibleTo(request: AgentApprovalRequest, principal: AgentPrincipal | null): boolean;
|
|
@@ -2,63 +2,35 @@
|
|
|
2
2
|
* The one place an agent audit event is announced: to the configured sink, and
|
|
3
3
|
* to the application's event listeners.
|
|
4
4
|
*
|
|
5
|
-
* Here rather than in a protocol adapter because it has two readers
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
* surface
|
|
9
|
-
*
|
|
10
|
-
* sink as an event listener after the other stopped — and the evidence of
|
|
11
|
-
* either would be a trail that is quietly missing a surface.
|
|
12
|
-
*
|
|
13
|
-
* Its own module so it can be exercised without an endpoint. The alternative
|
|
14
|
-
* is a closure inside the plugin's `boot`, reachable only by standing up a
|
|
15
|
-
* server and making a real tool call — which is worth doing once, and is the
|
|
16
|
-
* wrong price for the several cases that matter here (a sink that throws, a
|
|
17
|
-
* sink beside a listener that throws, a sink with no event manager at all).
|
|
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.
|
|
18
10
|
*/
|
|
19
11
|
import type { AgentToolDenied, AgentToolInvoked } from './events.js';
|
|
20
12
|
import type { EventManager } from '../events/index.js';
|
|
21
13
|
import { type AgentAuditRecord } from './audit.js';
|
|
22
14
|
/**
|
|
23
15
|
* The container service an application's audit emitter is published under
|
|
24
|
-
* (`ServiceBindings['agent.audit']`).
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
* `@guren/plugin-mcp` binds it, `@guren/cli` resolves it, and neither depends
|
|
29
|
-
* on the other. Two literals that drifted would break the wiring *silently* —
|
|
30
|
-
* the CLI would resolve nothing and record nothing, which reads exactly like
|
|
31
|
-
* an application that configured no trail. That is the one failure this
|
|
32
|
-
* feature exists to prevent, so it may not be spelled twice.
|
|
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.
|
|
33
20
|
*/
|
|
34
21
|
export declare const AGENT_AUDIT_BINDING = "agent.audit";
|
|
35
22
|
/** What an application hands each audit event to. */
|
|
36
23
|
export type AgentAuditSink = (record: AgentAuditRecord) => void | Promise<void>;
|
|
37
24
|
/**
|
|
38
|
-
* What every agent surface calls to record one invocation or one denial.
|
|
39
|
-
*
|
|
40
|
-
* Named because it is a container binding (`'agent.audit'`) as well as a return
|
|
41
|
-
* value: a caller resolving it has to be able to say what it expects to find.
|
|
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.
|
|
42
27
|
*/
|
|
43
28
|
export type AgentAuditEmitter = (event: AgentToolInvoked | AgentToolDenied) => void;
|
|
44
29
|
/**
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
* `for` loop, so the first one to throw ends the loop and every listener after
|
|
51
|
-
* it never runs. An unrelated application listener registered at a higher
|
|
52
|
-
* priority would then silence the audit trail, and the only evidence an
|
|
53
|
-
* operator would have of that is an empty file. A record of what agents did
|
|
54
|
-
* cannot be contingent on what else the application happens to listen for.
|
|
55
|
-
*
|
|
56
|
-
* The events are still emitted, unchanged, for every consumer that
|
|
57
|
-
* legitimately is a listener — RFC 0016 §5.2's "forward them wherever you
|
|
58
|
-
* already forward events" is untouched.
|
|
59
|
-
*
|
|
60
|
-
* Neither half may fail the tool call it is recording, so both are caught. The
|
|
61
|
-
* sink's failure is *warned* rather than swallowed: an audit sink dropping
|
|
62
|
-
* records in silence is precisely the failure this feature exists to prevent.
|
|
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.
|
|
63
35
|
*/
|
|
64
36
|
export declare function createAuditEmitter(sink: AgentAuditSink | undefined, events: EventManager | undefined, now?: () => Date): AgentAuditEmitter;
|
package/dist/agent/audit.d.ts
CHANGED
|
@@ -1,25 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The agent audit record (RFC 0016 §5.2): one invocation or one denial, in the
|
|
3
3
|
* one shape a sink writes as a line and `guren tool:log` reads back.
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* decision, made once by the application (`@guren/plugin-mcp`'s `audit`
|
|
11
|
-
* option); this module only says what one looks like.
|
|
12
|
-
*
|
|
13
|
-
* **Redaction is the emitter's contract, and nothing here may re-run it.**
|
|
14
|
-
* `AgentToolInvoked.arguments` arrives having already been through
|
|
15
|
-
* `redactAgentArguments`, exactly as `events.ts` states, and this module
|
|
16
|
-
* carries it across verbatim. Masking again here would install a second,
|
|
17
|
-
* quieter redaction rule beside the real one — the two would drift, and
|
|
18
|
-
* nothing reading a record could tell which of them produced a mask it is
|
|
19
|
-
* looking at. That is the reasoning `events.ts` used to refuse redacting on
|
|
20
|
-
* construction, and it holds one layer down without change. A sink that wants
|
|
21
|
-
* different masking changes the route's `.agent({ redact })`, which is the
|
|
22
|
-
* one place the rule lives.
|
|
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 })`.
|
|
23
10
|
*/
|
|
24
11
|
import type { AgentPrincipal, AgentSurface, AgentToolDenialReason, AgentToolDenied, AgentToolInvoked } from './events.js';
|
|
25
12
|
/**
|
|
@@ -55,49 +42,26 @@ export interface AgentAuditDeniedRecord extends AgentAuditRecordBase {
|
|
|
55
42
|
reason: AgentToolDenialReason;
|
|
56
43
|
}
|
|
57
44
|
/**
|
|
58
|
-
* One line of the audit trail.
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
* about what happened, and a shape that admits both would let a sink emit that
|
|
63
|
-
* contradiction and a reader believe it.
|
|
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.
|
|
64
49
|
*/
|
|
65
50
|
export type AgentAuditRecord = AgentAuditInvokedRecord | AgentAuditDeniedRecord;
|
|
66
51
|
/**
|
|
67
|
-
* Derive the record for one audit event.
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
* filed just after. One read, used for both.
|
|
73
|
-
*
|
|
74
|
-
* The two events are told apart structurally, not with `instanceof`. The event
|
|
75
|
-
* classes cross a package boundary that this repo resolves twice — `@guren/cli`
|
|
76
|
-
* and the plugins reach `@guren/server` through its `dist`, a test inside
|
|
77
|
-
* `packages/server` through `src` — so an `instanceof` here would answer
|
|
78
|
-
* `false` for a genuine event constructed on the other side of that seam, and
|
|
79
|
-
* would do it by mislabelling the record rather than by failing.
|
|
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`).
|
|
80
57
|
*/
|
|
81
58
|
export declare function toAuditRecord(event: AgentToolInvoked | AgentToolDenied, now: Date): AgentAuditRecord;
|
|
82
59
|
/**
|
|
83
|
-
* Read one line of an audit file back, or `null` if it is not a record.
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
* empty trail.
|
|
89
|
-
*
|
|
90
|
-
* Returning `null` rather than throwing is what makes the reader usable
|
|
91
|
-
* against a file that is being appended to right now. The last line of such a
|
|
92
|
-
* file is routinely a *partial* record — an append is not atomic — and a blank
|
|
93
|
-
* line is what a file ends with. Neither is corruption, and neither should
|
|
94
|
-
* take down a command whose whole job is to show what the earlier lines say.
|
|
95
|
-
*
|
|
96
|
-
* Extra keys are ignored, deliberately: the file sink writes through
|
|
97
|
-
* `DailyFileChannel`, whose JSON format wraps the record in a log envelope
|
|
98
|
-
* (`timestamp`, `level`, `message`). Tolerating that envelope is what lets the
|
|
99
|
-
* sink reuse the channel's rotation and retention instead of reimplementing
|
|
100
|
-
* both, and the record's own fields are unambiguous beside it.
|
|
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.
|
|
101
65
|
*/
|
|
102
66
|
export declare function parseAuditRecord(line: string): AgentAuditRecord | null;
|
|
103
67
|
export {};
|