@guren/server 2.15.0 → 2.17.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-Zihx3Bjq.js} +35 -20
- package/dist/{Random-DbIJ22KQ.js → Random-S0OvCuR8.js} +9 -106
- package/dist/agent/AgentApprovalRequested.d.ts +11 -39
- package/dist/agent/approval-status.d.ts +56 -0
- 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 +17 -23
- package/dist/agent/gate.d.ts +118 -0
- package/dist/agent/meta-tools.d.ts +18 -46
- package/dist/agent/pipeline.d.ts +234 -0
- 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 +55 -69
- package/dist/auth/AgentPrincipalGuard.d.ts +49 -0
- package/dist/auth/AuthManager.d.ts +22 -43
- 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-Gg54ppQi.js} +279 -519
- 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 +77 -205
- 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 +28 -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/index.d.ts +1 -1
- 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 +11 -4
- package/dist/index.js +1186 -3040
- package/dist/internal/agent-preflight.d.ts +9 -21
- package/dist/internal/agent-principal.d.ts +32 -0
- 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 +42 -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-B_Iy5183.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
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The invocation pipeline (RFC 0017 §1): scope gate → interposition → approval
|
|
3
|
+
* gate → dispatch → redact → audit, in one protocol-neutral place. `app.fetch`
|
|
4
|
+
* alone only executes, so a surface dispatching without these would bypass
|
|
5
|
+
* scopes, approvals and the trail while looking exactly like a gated call.
|
|
6
|
+
* One function with option hooks, not a middleware chain (RFC 0017 Open
|
|
7
|
+
* Question 1): a chain would publish an ordering vocabulary, and the ordering
|
|
8
|
+
* is the part that must not be negotiable. Nothing here imports an MCP type;
|
|
9
|
+
* the result is a union each adapter maps onto its own shapes.
|
|
10
|
+
*/
|
|
11
|
+
import type { ExecutionContext } from 'hono';
|
|
12
|
+
import { type AgentApprovalRequest, type AgentApprovalStore } from './approval.js';
|
|
13
|
+
import type { AgentAuditEmitter } from './audit-emitter.js';
|
|
14
|
+
import type { DerivedAgentTool } from './derive.js';
|
|
15
|
+
import { type ToolCallOutcome } from './dispatch.js';
|
|
16
|
+
import { type AgentPrincipal, type AgentSurface, type AgentToolDenialReason } from './events.js';
|
|
17
|
+
import { type ApprovalGateContext } from './gate.js';
|
|
18
|
+
/**
|
|
19
|
+
* What the audit hooks need from a tool: its name, and the redaction rules its
|
|
20
|
+
* arguments are recorded under. Narrower than {@link DerivedAgentTool} because
|
|
21
|
+
* one audited call has no route behind it: a `guren.preflight` invocation is
|
|
22
|
+
* recorded under the meta-tool's name with the *checked* tool's `redact` list,
|
|
23
|
+
* the meta-tool's own being empty.
|
|
24
|
+
*/
|
|
25
|
+
export interface AuditedTool {
|
|
26
|
+
toolName: string;
|
|
27
|
+
redact?: readonly string[];
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* What the pipeline hands to `app.fetch`. Structural rather than
|
|
31
|
+
* `Application`, so the pipeline stays a leaf of the agent layer and a test
|
|
32
|
+
* can drive it with a bare `fetch`.
|
|
33
|
+
*/
|
|
34
|
+
export interface AgentDispatchTarget {
|
|
35
|
+
fetch(request: Request, env?: unknown, executionCtx?: ExecutionContext): Promise<Response>;
|
|
36
|
+
}
|
|
37
|
+
/** A refusal, in the one shape every surface renders. */
|
|
38
|
+
export interface AgentInvocationDenial {
|
|
39
|
+
reason: AgentToolDenialReason;
|
|
40
|
+
message: string;
|
|
41
|
+
/**
|
|
42
|
+
* A machine-readable body riding alongside the message. Only the approval
|
|
43
|
+
* refusals carry one — a caller told "this is pending" needs the id to poll
|
|
44
|
+
* with (see {@link GateVerdict}).
|
|
45
|
+
*/
|
|
46
|
+
body?: Record<string, unknown>;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* What one call through the pipeline came to. Three variants, because a
|
|
50
|
+
* dispatch that *threw* is not one that answered: it is audited as an
|
|
51
|
+
* invocation, but the caller has no response to map, only a message.
|
|
52
|
+
* Collapsing it into `executed` would make every adapter invent an outcome,
|
|
53
|
+
* and they would invent different ones.
|
|
54
|
+
*/
|
|
55
|
+
export type AgentInvocationResult =
|
|
56
|
+
/** The request reached (or was refused by) the application. */
|
|
57
|
+
{
|
|
58
|
+
status: 'executed';
|
|
59
|
+
outcome: ToolCallOutcome;
|
|
60
|
+
}
|
|
61
|
+
/** A gate or the interposition hook refused before any HTTP happened. */
|
|
62
|
+
| {
|
|
63
|
+
status: 'denied';
|
|
64
|
+
denial: AgentInvocationDenial;
|
|
65
|
+
}
|
|
66
|
+
/** The dispatch itself broke. Audited as a 500 invocation. */
|
|
67
|
+
| {
|
|
68
|
+
status: 'failed';
|
|
69
|
+
message: string;
|
|
70
|
+
};
|
|
71
|
+
/** The call the interposition hook is asked about. */
|
|
72
|
+
export interface InterposedAgentCall {
|
|
73
|
+
tool: DerivedAgentTool;
|
|
74
|
+
args: Record<string, unknown>;
|
|
75
|
+
/** True for a rehearsal (`guren.preflight`), which executes nothing. */
|
|
76
|
+
preflight: boolean;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* The one seam a surface may put its own check in, **after the scope gate and
|
|
80
|
+
* before the approval gate**: after scope so an unauthorized prober cannot
|
|
81
|
+
* drain a budget on ungranted calls, before approval because that gate writes
|
|
82
|
+
* a record and notifies humans, deduplicating only on *identical* arguments —
|
|
83
|
+
* a caller varying one field files unbounded requests. A denial dispatches nothing.
|
|
84
|
+
*/
|
|
85
|
+
export type AgentInterposition = (call: InterposedAgentCall) => AgentInvocationDenial | undefined | Promise<AgentInvocationDenial | undefined>;
|
|
86
|
+
/**
|
|
87
|
+
* Everything the pipeline needs that is settled once per caller, not per call.
|
|
88
|
+
*/
|
|
89
|
+
export interface AgentInvocationOptions {
|
|
90
|
+
/** The application the dispatched request re-enters. */
|
|
91
|
+
app: AgentDispatchTarget;
|
|
92
|
+
/**
|
|
93
|
+
* Who is calling. **Resolved by the caller**, never by the pipeline: how a
|
|
94
|
+
* principal is established is the surface's business (a verified bearer, an
|
|
95
|
+
* OAuth grant presented over a seam, a registered durable agent), and a
|
|
96
|
+
* pipeline that guessed would be a second authentication rule.
|
|
97
|
+
*/
|
|
98
|
+
principal: AgentPrincipal | null;
|
|
99
|
+
/** The scope grammar's input — the abilities the scope gate judges by. */
|
|
100
|
+
abilities: readonly string[];
|
|
101
|
+
/**
|
|
102
|
+
* Which surface this is, for the audit trail. Caller-supplied and never
|
|
103
|
+
* invented: the trail's whole value is that a record says where a call came
|
|
104
|
+
* from, and a default would make the commonest surface absorb every one that
|
|
105
|
+
* forgot to say.
|
|
106
|
+
*/
|
|
107
|
+
surface: AgentSurface;
|
|
108
|
+
/**
|
|
109
|
+
* Where invocations and denials are recorded. Undefined records nothing —
|
|
110
|
+
* the call still works, exactly as an application with no audit sink
|
|
111
|
+
* configured behaves today.
|
|
112
|
+
*/
|
|
113
|
+
audit?: AgentAuditEmitter;
|
|
114
|
+
/**
|
|
115
|
+
* The approval queue (RFC 0016 §5.4 item 4). Absent, a tool declaring
|
|
116
|
+
* `approval: 'required'` is refused **fail-closed**: nothing is dispatched
|
|
117
|
+
* and the denial is audited, so an unconfigured queue never looks like a
|
|
118
|
+
* working one. `redact` takes the tool as well as the arguments, one context
|
|
119
|
+
* serving every tool with each route's own masking rules.
|
|
120
|
+
*/
|
|
121
|
+
approvals?: Omit<ApprovalGateContext, 'redact'> & {
|
|
122
|
+
redact(tool: DerivedAgentTool, args: Record<string, unknown>): Record<string, unknown>;
|
|
123
|
+
};
|
|
124
|
+
/**
|
|
125
|
+
* How *this* surface configures an approval queue, named in the fail-closed
|
|
126
|
+
* refusal. See {@link import('./gate').ScopeGateOptions.configureHint}.
|
|
127
|
+
*/
|
|
128
|
+
approvalConfigureHint?: string;
|
|
129
|
+
/**
|
|
130
|
+
* What a scope refusal calls the thing whose scopes fell short —
|
|
131
|
+
* `"The token's scopes"` on a bearer surface. Defaults to the neutral
|
|
132
|
+
* {@link DEFAULT_SCOPE_SUBJECT}, because a durable agent's principal is
|
|
133
|
+
* minted from its registration and holds no token anyone could widen.
|
|
134
|
+
*/
|
|
135
|
+
scopeSubject?: string;
|
|
136
|
+
/** The one interposition seam. See {@link AgentInterposition}. */
|
|
137
|
+
interpose?: AgentInterposition;
|
|
138
|
+
/**
|
|
139
|
+
* Origin the synthesized request is built on, so host-authorization
|
|
140
|
+
* middleware sees the real Host the caller reached this surface on.
|
|
141
|
+
*/
|
|
142
|
+
origin?: string;
|
|
143
|
+
/**
|
|
144
|
+
* `Authorization` to forward verbatim, for a surface whose credential the
|
|
145
|
+
* application's own guards can verify. **Mutually exclusive with
|
|
146
|
+
* {@link handoff}, and enforced**: setting both puts two answers to "who is
|
|
147
|
+
* this" on one request, which guard-resolution order would then settle
|
|
148
|
+
* rather than anything the surface said, so the factory throws.
|
|
149
|
+
*/
|
|
150
|
+
authorization?: string;
|
|
151
|
+
/**
|
|
152
|
+
* `'seam'` installs {@link AgentInvocationOptions.principal} on the exact
|
|
153
|
+
* `Request` handed to `app.fetch`, so `requireAuthenticated()`,
|
|
154
|
+
* `Controller.auth` and `Gate` answer for it (RFC 0017 §2). Not a token:
|
|
155
|
+
* `createBearerTokenMiddleware` and `tokenCan*` judge one and there is none,
|
|
156
|
+
* so a route behind those refuses. Omitted, nothing is installed.
|
|
157
|
+
*/
|
|
158
|
+
handoff?: 'seam';
|
|
159
|
+
/** Forwarded to `app.fetch` — D1/R2 bindings on Workers (RFC 0016 §3.1). */
|
|
160
|
+
env?: unknown;
|
|
161
|
+
/** Forwarded to `app.fetch` — `waitUntil` on Workers. */
|
|
162
|
+
executionCtx?: ExecutionContext;
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Build {@link AgentInvocationOptions.approvals} for one caller.
|
|
166
|
+
*
|
|
167
|
+
* The TTL default, the redaction rules and the `notify` wrapping are invariants
|
|
168
|
+
* of an approval record rather than of a protocol. Per caller, because an
|
|
169
|
+
* approval binds to the principal that asked; `undefined` means no queue.
|
|
170
|
+
*/
|
|
171
|
+
export declare function createAgentApprovalContext(config: {
|
|
172
|
+
store: AgentApprovalStore;
|
|
173
|
+
notify: (request: AgentApprovalRequest) => void | Promise<void>;
|
|
174
|
+
ttlMs?: number;
|
|
175
|
+
} | undefined, principal: AgentPrincipal | null): NonNullable<AgentInvocationOptions['approvals']> | undefined;
|
|
176
|
+
/** What {@link createAgentAuditRecorder} needs, settled once per caller. */
|
|
177
|
+
export interface AgentAuditRecorderOptions {
|
|
178
|
+
audit?: AgentAuditEmitter;
|
|
179
|
+
principal: AgentPrincipal | null;
|
|
180
|
+
surface: AgentSurface;
|
|
181
|
+
}
|
|
182
|
+
/** The two records a surface writes. See {@link createAgentAuditRecorder}. */
|
|
183
|
+
export interface AgentAuditRecorder {
|
|
184
|
+
invoked(audited: AuditedTool, args: Record<string, unknown>, status: number, durationMs: number): void;
|
|
185
|
+
denied(audited: AuditedTool, args: Record<string, unknown>, reason: AgentToolDenialReason): void;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* How a call is written down: principal, surface, and argument masking.
|
|
189
|
+
*
|
|
190
|
+
* Exported because a durable agent's approval-status check reaches the store
|
|
191
|
+
* without dispatching a tool (RFC 0017 §5), and a second copy of this rule is
|
|
192
|
+
* how one surface records an argument the other masks.
|
|
193
|
+
*/
|
|
194
|
+
export declare function createAgentAuditRecorder(options: AgentAuditRecorderOptions): AgentAuditRecorder;
|
|
195
|
+
/** One call, as the pipeline is asked to run it. */
|
|
196
|
+
export interface AgentInvocation {
|
|
197
|
+
/** The tool the request is built from. */
|
|
198
|
+
tool: DerivedAgentTool;
|
|
199
|
+
/** The arguments the request is built from. */
|
|
200
|
+
args: Record<string, unknown>;
|
|
201
|
+
/**
|
|
202
|
+
* Ask the route for a verdict instead of an execution (RFC 0016 §5.4). The
|
|
203
|
+
* scope half still runs — checking a tool requires the same scope as calling
|
|
204
|
+
* it — but the **approval gate is skipped**: an approval-gated tool is the
|
|
205
|
+
* one a caller most needs to rehearse, and a rehearsal executes nothing.
|
|
206
|
+
*/
|
|
207
|
+
preflight?: boolean;
|
|
208
|
+
/**
|
|
209
|
+
* The identity the record is written under, when it is not the dispatched
|
|
210
|
+
* tool's own — see {@link AuditedTool}. `guren.preflight` is the one caller:
|
|
211
|
+
* the meta-tool's name, the checked tool's redaction rules.
|
|
212
|
+
*/
|
|
213
|
+
audited?: AuditedTool;
|
|
214
|
+
/**
|
|
215
|
+
* The arguments written down, when they are not {@link args}. Separate
|
|
216
|
+
* because the preflight path dispatches the *checked* tool's input while
|
|
217
|
+
* recording the *meta-tool's* own arguments, so the record shows what the
|
|
218
|
+
* agent actually asked. Collapsing the two silently changes what an audit
|
|
219
|
+
* trail says a caller passed.
|
|
220
|
+
*/
|
|
221
|
+
auditedArguments?: Record<string, unknown>;
|
|
222
|
+
}
|
|
223
|
+
/** What {@link createAgentInvocationPipeline} returns. */
|
|
224
|
+
export interface AgentInvocationPipeline {
|
|
225
|
+
invoke(call: AgentInvocation): Promise<AgentInvocationResult>;
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Build the pipeline for one caller. A factory because everything in
|
|
229
|
+
* {@link AgentInvocationOptions} is settled per caller and read per call — the
|
|
230
|
+
* principal an approval binds to, the abilities the gate judges by, the surface
|
|
231
|
+
* the trail records — and hoisting any of it would carry whichever caller
|
|
232
|
+
* arrived first.
|
|
233
|
+
*/
|
|
234
|
+
export declare function createAgentInvocationPipeline(options: AgentInvocationOptions): AgentInvocationPipeline;
|
package/dist/agent/public.d.ts
CHANGED
|
@@ -1,31 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The published entry of `@guren/server/agent` (mirrored as
|
|
3
3
|
* `@guren/core/agent`): the half of the agent surface an *out-of-process*
|
|
4
|
-
* dispatcher needs — a browser tab running WebMCP, a CLI, a test harness
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* container, `Router`), which is exactly what a client bundle must not pull
|
|
11
|
-
* in. This module is the one place that promises otherwise, so the promise is
|
|
12
|
-
* stated here rather than left to whoever next adds a re-export:
|
|
13
|
-
*
|
|
14
|
-
* - **Pure Web API.** `Request` / `Response` / `Headers` / `URLSearchParams`
|
|
15
|
-
* and nothing else. No `node:` import, no Bun global, no DOM access — the
|
|
16
|
-
* module must be importable under SSR as well as in a browser. Its two
|
|
17
|
-
* transitive imports (`../internal/route-path`, `../internal/agent-preflight`)
|
|
18
|
-
* are string and regex constants for that reason.
|
|
19
|
-
* - **Types only from `./derive`.** `dispatch.ts` imports `DerivedAgentTool`
|
|
20
|
-
* with `import type`, so the derivation — which reaches `Router` and the
|
|
21
|
-
* authorization middleware — never enters the graph. Re-exporting a *value*
|
|
22
|
-
* from `./derive` here would undo that silently: the bundle would grow the
|
|
23
|
-
* whole route layer and nothing would fail.
|
|
24
|
-
*
|
|
25
|
-
* A consumer holding a `.guren/agents.gen.ts` manifest therefore has
|
|
26
|
-
* everything needed to turn a flat tool call into the HTTP request the route
|
|
27
|
-
* validates, and the route's response back into an MCP tool result — the one
|
|
28
|
-
* dispatch contract (RFC 0016 §3), not a second one written per surface.
|
|
4
|
+
* dispatcher needs — a browser tab running WebMCP, a CLI, a test harness.
|
|
5
|
+
* Two rules keep it importable there. Pure Web API only (`Request`,
|
|
6
|
+
* `Response`, `Headers`, `URLSearchParams`): no `node:` import, no Bun global,
|
|
7
|
+
* no DOM, so it loads under SSR too. And types only from `./derive` —
|
|
8
|
+
* re-exporting a *value* would silently pull `Router` and the authorization
|
|
9
|
+
* middleware into a client bundle.
|
|
29
10
|
*/
|
|
30
11
|
export { advertisesStructuredOutput, buildToolRequest, describeBuildFailure, mapToolResponse, PREFLIGHT_ARGUMENT, } from './dispatch.js';
|
|
31
12
|
export type { BuildToolRequestOptions, BuiltToolRequest, ToolCallOutcome, ToolRequestBuildFailure, } from './dispatch.js';
|
package/dist/agent/public.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { a as mapToolResponse, i as describeBuildFailure, n as advertisesStructuredOutput, r as buildToolRequest, t as PREFLIGHT_ARGUMENT } from "../dispatch-
|
|
1
|
+
import { a as mapToolResponse, i as describeBuildFailure, n as advertisesStructuredOutput, r as buildToolRequest, t as PREFLIGHT_ARGUMENT } from "../dispatch-BAwzftws.js";
|
|
2
2
|
export { PREFLIGHT_ARGUMENT, advertisesStructuredOutput, buildToolRequest, describeBuildFailure, mapToolResponse };
|
package/dist/agent/redact.d.ts
CHANGED
|
@@ -1,22 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Argument masking for the agent audit trail (RFC 0016 §5.2).
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* *contains* a fragment, and that applies to the declared `redact` entries
|
|
11
|
-
* too, not just the built-ins. So `redact: ['id']` also masks `userId`, and
|
|
12
|
-
* the built-in `session` masks `sessionCount`. Over-redaction is the safe
|
|
13
|
-
* direction for a log: a masked field that did not need masking costs a
|
|
14
|
-
* debugging round trip, an unmasked credential costs a rotation.
|
|
15
|
-
*
|
|
16
|
-
* The walk is total for the same reason the derivation is: it runs while
|
|
17
|
-
* *recording* what happened, including a denial taken before the route's own
|
|
18
|
-
* validation, so it must not be the thing that throws. A cycle and a payload
|
|
19
|
-
* nested past {@link MAX_DEPTH} both terminate with a marker.
|
|
2
|
+
* Argument masking for the agent audit trail (RFC 0016 §5.2). Two sources,
|
|
3
|
+
* unioned: a fixed list of sensitive key *fragments* every application gets,
|
|
4
|
+
* and the route's own `.agent({ redact })`. A key matches when its lowercased
|
|
5
|
+
* name *contains* a fragment, declared entries included — `redact: ['id']` also
|
|
6
|
+
* masks `userId`. Over-redaction is the safe direction: a needless mask costs a
|
|
7
|
+
* debugging round trip, an unmasked credential costs a rotation. The walk is
|
|
8
|
+
* total because it runs while recording a denial taken before validation: a
|
|
9
|
+
* cycle and a payload nested past {@link MAX_DEPTH} both terminate with a marker.
|
|
20
10
|
*/
|
|
21
11
|
/**
|
|
22
12
|
* The replacement written in place of a masked value. A string, so a redacted
|
|
@@ -24,10 +14,9 @@
|
|
|
24
14
|
*/
|
|
25
15
|
export declare const AGENT_REDACTED = "[REDACTED]";
|
|
26
16
|
/**
|
|
27
|
-
* Written in place of a value that closes a cycle
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
* you", the other "there is nothing further here to show".
|
|
17
|
+
* Written in place of a value that closes a cycle. Distinct from
|
|
18
|
+
* {@link AGENT_REDACTED} on purpose: one says "we would not show you", the
|
|
19
|
+
* other "there is nothing further here to show".
|
|
31
20
|
*/
|
|
32
21
|
export declare const AGENT_CIRCULAR = "[Circular]";
|
|
33
22
|
/**
|
|
@@ -35,21 +24,10 @@ export declare const AGENT_CIRCULAR = "[Circular]";
|
|
|
35
24
|
*/
|
|
36
25
|
export declare const AGENT_TRUNCATED = "[Truncated]";
|
|
37
26
|
/**
|
|
38
|
-
* Mask the sensitive fields of an agent tool's arguments
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
* a `Map`, a `Set`, a class instance) is carried across as the *same
|
|
44
|
-
* reference*, because copying it would need a rule per type and would still
|
|
45
|
-
* get the exotic cases wrong; nothing below such a value is inspected, so a
|
|
46
|
-
* credential hidden inside a class instance is masked only if the key holding
|
|
47
|
-
* that instance matches. Tool arguments arrive as parsed JSON on every
|
|
48
|
-
* surface, where this case does not occur; a caller synthesizing arguments in
|
|
49
|
-
* process is the one that can hit it.
|
|
50
|
-
*
|
|
51
|
-
* @param args The invocation arguments. Walked as a record whatever its
|
|
52
|
-
* prototype, so the return is always a fresh plain object.
|
|
53
|
-
* @param redact Extra key fragments from the route's `.agent({ redact })`.
|
|
27
|
+
* Mask the sensitive fields of an agent tool's arguments; `redact` adds the
|
|
28
|
+
* route's `.agent({ redact })` fragments. Returns a fresh plain object (`args`
|
|
29
|
+
* is walked as a record whatever its prototype), deep only through plain objects
|
|
30
|
+
* and arrays: a `Date`, `Map` or class instance is carried by reference and
|
|
31
|
+
* never inspected, which only an in-process caller can hit (surfaces pass JSON).
|
|
54
32
|
*/
|
|
55
33
|
export declare function redactAgentArguments(args: Record<string, unknown>, redact?: readonly string[]): Record<string, unknown>;
|
package/dist/agent/scopes.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* -
|
|
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
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
* `
|
|
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
|
|
72
|
-
*
|
|
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,37 +47,55 @@ export interface ScopedTool {
|
|
|
79
47
|
readOnly: boolean;
|
|
80
48
|
}
|
|
81
49
|
/**
|
|
82
|
-
* Parse one `abilities` entry.
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
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;
|
|
57
|
+
/**
|
|
58
|
+
* The scope forms a **registration** may declare (RFC 0017 §3): the narrower
|
|
59
|
+
* half of the grammar above, because a registration grants an *unattended*
|
|
60
|
+
* principal and is outlived by the route graph, so a set grant would acquire
|
|
61
|
+
* consent to tools that did not yet exist. One rule, shared with `guren check`.
|
|
62
|
+
*/
|
|
63
|
+
export type RegistrationScopeVerdict =
|
|
64
|
+
/** The entry is a legal registration scope. */
|
|
65
|
+
{
|
|
66
|
+
allowed: true;
|
|
67
|
+
scope: Extract<ParsedToolScope, {
|
|
68
|
+
kind: 'tool';
|
|
69
|
+
} | {
|
|
70
|
+
kind: 'read';
|
|
71
|
+
}>;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The entry may not be registered. `message` states the reason and the fix,
|
|
75
|
+
* and is what both the plugin's throw and the check's finding say — so a
|
|
76
|
+
* developer reads the same sentence whichever surface catches it first.
|
|
77
|
+
*/
|
|
78
|
+
| {
|
|
79
|
+
allowed: false;
|
|
80
|
+
reason: 'wildcard' | 'prefix' | 'not-a-tool-scope';
|
|
81
|
+
message: string;
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* Judge one `scopes` entry of an agent registration.
|
|
85
|
+
*
|
|
86
|
+
* @param entry The scope as written in the config.
|
|
87
|
+
*/
|
|
88
|
+
export declare function classifyRegistrationScope(entry: string): RegistrationScopeVerdict;
|
|
97
89
|
/**
|
|
98
90
|
* Whether a token's abilities grant a tool. Any one entry suffices — scopes
|
|
99
91
|
* are additive, and there is no deny form.
|
|
100
92
|
*/
|
|
101
93
|
export declare function scopesAllowTool(abilities: readonly string[], tool: ScopedTool): boolean;
|
|
102
94
|
/**
|
|
103
|
-
* The concrete tool names a token's abilities grant, for the surfaces that
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
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.
|
|
95
|
+
* The concrete tool names a token's abilities grant, for the surfaces that show
|
|
96
|
+
* a human what a scope means: the OAuth consent screen, the `token:issue`
|
|
97
|
+
* confirmation, the issuance-time lint. Literally a filter over
|
|
98
|
+
* {@link scopesAllowTool}, and it must stay one: a second matcher is how a
|
|
99
|
+
* consent screen comes to list a tool the dispatcher then denies. Order of `tools`.
|
|
114
100
|
*/
|
|
115
101
|
export declare function expandToolScopes(abilities: readonly string[], tools: readonly ScopedTool[]): string[];
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import type { Session } from '../http/middleware/index.js';
|
|
2
|
+
import type { InstalledAgentPrincipal } from '../internal/agent-principal.js';
|
|
3
|
+
import type { AuthCredentials, Guard, UserProvider } from './types.js';
|
|
4
|
+
export interface AgentPrincipalGuardOptions<User = unknown> {
|
|
5
|
+
/** The principal the invocation pipeline installed on this request. */
|
|
6
|
+
installed: InstalledAgentPrincipal;
|
|
7
|
+
/**
|
|
8
|
+
* Resolves a `kind: 'user'` principal's id to a full user record, the same
|
|
9
|
+
* provider `useTokens({ provider })` names. Without one the guard still
|
|
10
|
+
* authenticates: `user()` resolves to a minimal `{ id }` record so
|
|
11
|
+
* Gate/policy evaluation (which keys on `id`) works out of the box — the
|
|
12
|
+
* shape `TokenGuard` returns for a token with no provider configured.
|
|
13
|
+
*/
|
|
14
|
+
provider?: UserProvider<User>;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* The guard answering for a principal the pipeline installed (RFC 0017 §2), for
|
|
18
|
+
* an **unqualified** lookup on a seam-marked request; explicit `guard('web')` /
|
|
19
|
+
* `guard('token')` is untouched, and `guardNames()` never lists this one. It
|
|
20
|
+
* satisfies `requireAuthenticated()`, `Controller.auth` and `Gate`, but not
|
|
21
|
+
* `createBearerTokenMiddleware` / `tokenCan*`, which judge an `ApiToken`.
|
|
22
|
+
*/
|
|
23
|
+
export declare class AgentPrincipalGuard<User = unknown> implements Guard<User> {
|
|
24
|
+
private readonly installed;
|
|
25
|
+
private readonly provider?;
|
|
26
|
+
private resolvedUser?;
|
|
27
|
+
constructor(options: AgentPrincipalGuardOptions<User>);
|
|
28
|
+
/**
|
|
29
|
+
* `user() !== null`, the predicate `TokenGuard` answers `check()` with: true
|
|
30
|
+
* in every case but one, a `kind: 'user'` principal a configured provider
|
|
31
|
+
* cannot resolve. Answering true there would admit a request whose
|
|
32
|
+
* `Controller.auth.userOrFail()` then throws.
|
|
33
|
+
*/
|
|
34
|
+
check(): Promise<boolean>;
|
|
35
|
+
guest(): Promise<boolean>;
|
|
36
|
+
/**
|
|
37
|
+
* `kind: 'service'` is always the minimal `{ id }`: a service principal names
|
|
38
|
+
* no user, so a lookup would resolve an id in a table it does not belong to.
|
|
39
|
+
* `kind: 'user'` goes through the provider when one is configured.
|
|
40
|
+
*/
|
|
41
|
+
user<T = User>(): Promise<T | null>;
|
|
42
|
+
id(): Promise<unknown>;
|
|
43
|
+
login(): Promise<void>;
|
|
44
|
+
attempt(_credentials: AuthCredentials, _remember?: boolean): Promise<boolean>;
|
|
45
|
+
validate(_credentials: AuthCredentials): Promise<User | null>;
|
|
46
|
+
/** Nothing to end: no session, and no stored credential to revoke. */
|
|
47
|
+
logout(): Promise<void>;
|
|
48
|
+
session<T extends Session = Session>(): T | undefined;
|
|
49
|
+
}
|