@guren/server 2.1.1 → 2.3.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-D7RGJPGM.js → DocsViewerServiceProvider-RUYDFBMW.js} +2 -2
- package/dist/McpServiceProvider-FRJ5O7LT.js +8 -0
- package/dist/auth/AuthManager.d.ts +30 -0
- package/dist/auth/AuthenticatableModel.d.ts +25 -0
- package/dist/auth/RequestAuthContext.d.ts +24 -0
- package/dist/auth/SessionGuard.d.ts +31 -0
- package/dist/auth/api-token.d.ts +299 -0
- package/dist/auth/email-verification.d.ts +203 -0
- package/dist/auth/index.d.ts +18 -110
- package/dist/auth/index.js +4 -1
- package/dist/auth/oauth/index.d.ts +239 -0
- package/dist/auth/password/DefaultHasher.d.ts +13 -0
- package/dist/auth/password/NodeHasher.d.ts +22 -0
- package/dist/auth/password/PasswordHasher.d.ts +5 -0
- package/dist/auth/password/ScryptHasher.d.ts +26 -0
- package/dist/auth/password-reset.d.ts +91 -0
- package/dist/auth/providers/ModelUserProvider.d.ts +36 -0
- package/dist/auth/providers/UserProvider.d.ts +9 -0
- package/dist/auth/types.d.ts +102 -0
- package/dist/auth/utils.d.ts +39 -0
- package/dist/{Gate-CynjZCtS.d.ts → authorization/Gate.d.ts} +30 -111
- package/dist/authorization/Policy.d.ts +77 -0
- package/dist/authorization/index.d.ts +5 -129
- package/dist/authorization/index.js +3 -1
- package/dist/authorization/middleware.d.ts +49 -0
- package/dist/authorization/types.d.ts +108 -0
- package/dist/broadcasting/BroadcastManager.d.ts +205 -0
- package/dist/broadcasting/channels/Channel.d.ts +28 -0
- package/dist/broadcasting/channels/PresenceChannel.d.ts +72 -0
- package/dist/broadcasting/channels/PrivateChannel.d.ts +32 -0
- package/dist/broadcasting/channels/index.d.ts +3 -0
- package/dist/broadcasting/drivers/MemoryDriver.d.ts +93 -0
- package/dist/broadcasting/drivers/RedisDriver.d.ts +112 -0
- package/dist/broadcasting/drivers/index.d.ts +2 -0
- package/dist/broadcasting/index.d.ts +6 -233
- package/dist/broadcasting/index.js +1 -1
- package/dist/broadcasting/typed.d.ts +23 -0
- package/dist/broadcasting/types.d.ts +155 -0
- package/dist/cache/CacheManager.d.ts +87 -0
- package/dist/cache/TaggedCache.d.ts +62 -0
- package/dist/cache/index.d.ts +6 -233
- package/dist/cache/index.js +1 -1
- package/dist/cache/stores/FileStore.d.ts +64 -0
- package/dist/cache/stores/MemoryStore.d.ts +52 -0
- package/dist/cache/stores/RedisStore.d.ts +53 -0
- package/dist/{CacheManager-BmDzUKrF.d.ts → cache/types.d.ts} +26 -99
- package/dist/chunk-3KV5X2FL.js +31 -0
- package/dist/{chunk-TVY72CLV.js → chunk-4VE3LYOM.js} +3 -2
- package/dist/{chunk-DSDX3ASM.js → chunk-5WL2FTC4.js} +67 -85
- package/dist/{chunk-5SZTEZ22.js → chunk-6IGN233M.js} +15 -8
- package/dist/{chunk-FZD2AKJI.js → chunk-7OB2YXRE.js} +56 -28
- package/dist/{chunk-WIXGT4TN.js → chunk-A5JJ7XTH.js} +8 -2
- package/dist/{chunk-CWI4AJ47.js → chunk-HPET6XY5.js} +13 -9
- package/dist/{chunk-A3ISJVEV.js → chunk-HR2KZ3WL.js} +23 -5
- package/dist/{chunk-BZMZEFRG.js → chunk-LHR6OHI7.js} +11 -0
- package/dist/{chunk-JBG4AR24.js → chunk-Q2P6YLRR.js} +8 -2
- package/dist/{chunk-J6ETA476.js → chunk-TVV5YNEC.js} +101 -9
- package/dist/console/Command.d.ts +179 -0
- package/dist/{ConsoleKernel-CJg975mp.d.ts → console/ConsoleKernel.d.ts} +4 -6
- package/dist/console/Input.d.ts +140 -0
- package/dist/console/Output.d.ts +161 -0
- package/dist/console/index.d.ts +5 -0
- package/dist/console/types.d.ts +106 -0
- package/dist/container/Container.d.ts +148 -0
- package/dist/container/ServiceProvider.d.ts +103 -0
- package/dist/container/bindings.d.ts +55 -0
- package/dist/container/defineModule.d.ts +88 -0
- package/dist/container/definePlugin.d.ts +62 -0
- package/dist/container/index.d.ts +8 -0
- package/dist/container/types.d.ts +73 -0
- package/dist/database/Factory.d.ts +82 -0
- package/dist/database/Seeder.d.ts +35 -0
- package/dist/database/SeederRunner.d.ts +41 -0
- package/dist/database/index.d.ts +4 -0
- package/dist/database/types.d.ts +49 -0
- package/dist/discovery/AutoDiscovery.d.ts +113 -0
- package/dist/discovery/index.d.ts +2 -0
- package/dist/docs-viewer/DocsViewerServiceProvider.d.ts +12 -0
- package/dist/docs-viewer/endpoint.d.ts +29 -0
- package/dist/encryption/Encrypter.d.ts +96 -0
- package/dist/encryption/Hash.d.ts +69 -0
- package/dist/encryption/MessageSigner.d.ts +21 -0
- package/dist/encryption/Random.d.ts +119 -0
- package/dist/encryption/app-key.d.ts +12 -0
- package/dist/encryption/index.d.ts +10 -222
- package/dist/encryption/signed-url.d.ts +9 -0
- package/dist/encryption/types.d.ts +103 -0
- package/dist/errors/ExceptionHandler.d.ts +118 -0
- package/dist/errors/HttpException.d.ts +106 -0
- package/dist/errors/debug-page.d.ts +22 -0
- package/dist/errors/error-page.d.ts +1 -0
- package/dist/errors/exceptions/AuthenticationException.d.ts +32 -0
- package/dist/errors/exceptions/AuthorizationException.d.ts +32 -0
- package/dist/errors/exceptions/MethodNotAllowedException.d.ts +31 -0
- package/dist/errors/exceptions/NotFoundHttpException.d.ts +36 -0
- package/dist/errors/exceptions/ValidationException.d.ts +60 -0
- package/dist/errors/exceptions/index.d.ts +5 -0
- package/dist/errors/index.d.ts +5 -0
- package/dist/errors/types.d.ts +43 -0
- package/dist/events/Event.d.ts +33 -0
- package/dist/{EventManager-CmIoLt7r.d.ts → events/EventManager.d.ts} +4 -86
- package/dist/events/Listener.d.ts +79 -0
- package/dist/events/builtin.d.ts +73 -0
- package/dist/events/index.d.ts +6 -155
- package/dist/events/types.d.ts +48 -0
- package/dist/facades/index.d.ts +31 -0
- package/dist/health/HealthCheck.d.ts +34 -0
- package/dist/health/HealthManager.d.ts +53 -0
- package/dist/health/checks/CacheCheck.d.ts +35 -0
- package/dist/health/checks/CustomCheck.d.ts +23 -0
- package/dist/health/checks/DatabaseCheck.d.ts +33 -0
- package/dist/health/checks/MemoryCheck.d.ts +32 -0
- package/dist/health/checks/RedisCheck.d.ts +27 -0
- package/dist/health/checks/StorageCheck.d.ts +35 -0
- package/dist/health/checks/index.d.ts +12 -0
- package/dist/health/index.d.ts +5 -185
- package/dist/health/types.d.ts +52 -0
- package/dist/hot-reload/hot-disposables.d.ts +96 -0
- package/dist/hot-reload/testing.d.ts +14 -0
- package/dist/http/Application.d.ts +199 -0
- package/dist/http/FormRequest.d.ts +73 -0
- package/dist/http/dev-assets.d.ts +62 -0
- package/dist/http/dev-banner.d.ts +7 -0
- package/dist/http/inertia-assets.d.ts +31 -0
- package/dist/http/middleware/auth.d.ts +13 -0
- package/dist/http/middleware/capabilities.d.ts +22 -0
- package/dist/http/middleware/cors.d.ts +40 -0
- package/dist/http/middleware/csp.d.ts +59 -0
- package/dist/http/middleware/csrf.d.ts +121 -0
- package/dist/http/middleware/detect-locale.d.ts +65 -0
- package/dist/http/middleware/force-https.d.ts +34 -0
- package/dist/http/middleware/host-authorization.d.ts +24 -0
- package/dist/http/middleware/index.d.ts +19 -0
- package/dist/http/middleware/loopback-guard.d.ts +51 -0
- package/dist/{rate-limit-D9J2b4S1.d.ts → http/middleware/rate-limit.d.ts} +22 -50
- package/dist/http/middleware/redirect-safety.d.ts +29 -0
- package/dist/http/middleware/request-id.d.ts +19 -0
- package/dist/http/middleware/request-logging.d.ts +16 -0
- package/dist/http/middleware/response-headers.d.ts +18 -0
- package/dist/http/middleware/security-headers.d.ts +49 -0
- package/dist/http/middleware/session.d.ts +93 -0
- package/dist/http/middleware/validation.d.ts +94 -0
- package/dist/http/public-assets.d.ts +15 -0
- package/dist/http/request.d.ts +24 -0
- package/dist/http/resources/CursorPaginator.d.ts +106 -0
- package/dist/http/resources/Paginator.d.ts +130 -0
- package/dist/http/resources/Resource.d.ts +67 -0
- package/dist/http/resources/ResourceCollection.d.ts +60 -0
- package/dist/http/resources/index.d.ts +6 -0
- package/dist/http/resources/types.d.ts +91 -0
- package/dist/http/validation/Validator.d.ts +128 -0
- package/dist/http/validation/index.d.ts +3 -0
- package/dist/http/validation/rules.d.ts +196 -0
- package/dist/http/validation/types.d.ts +96 -0
- package/dist/http/vite-dev-server.d.ts +27 -0
- package/dist/i18n/I18nManager.d.ts +114 -0
- package/dist/i18n/Translator.d.ts +80 -0
- package/dist/i18n/index.d.ts +6 -101
- package/dist/i18n/index.js +5 -3
- package/dist/i18n/loaders/JsonLoader.d.ts +47 -0
- package/dist/i18n/loaders/MemoryLoader.d.ts +37 -0
- package/dist/i18n/pluralization.d.ts +19 -0
- package/dist/i18n/types.d.ts +106 -0
- package/dist/index.d.ts +69 -2605
- package/dist/index.js +405 -180
- package/dist/lambda/index.d.ts +17 -37
- package/dist/logging/LogManager.d.ts +83 -0
- package/dist/logging/Logger.d.ts +76 -0
- package/dist/logging/channels/ConsoleChannel.d.ts +11 -0
- package/dist/logging/channels/DailyFileChannel.d.ts +20 -0
- package/dist/logging/channels/FileChannel.d.ts +15 -0
- package/dist/logging/index.d.ts +8 -50
- package/dist/logging/types.d.ts +96 -0
- package/dist/mail/Mail.d.ts +138 -0
- package/dist/mail/MailManager.d.ts +79 -0
- package/dist/mail/address.d.ts +8 -0
- package/dist/mail/index.d.ts +7 -316
- package/dist/mail/transports/LogTransport.d.ts +19 -0
- package/dist/mail/transports/MemoryTransport.d.ts +84 -0
- package/dist/mail/transports/ResendTransport.d.ts +32 -0
- package/dist/mail/transports/SmtpTransport.d.ts +40 -0
- package/dist/{MailManager-DpMvYiP9.d.ts → mail/types.d.ts} +11 -92
- package/dist/mcp/McpServiceProvider.d.ts +17 -0
- package/dist/mcp/create-mcp-server.d.ts +152 -0
- package/dist/mcp/endpoint.d.ts +47 -0
- package/dist/mcp/index.d.ts +3 -185
- package/dist/mcp/index.js +3 -3
- package/dist/mvc/Controller.d.ts +326 -0
- package/dist/mvc/Router.d.ts +239 -0
- package/dist/mvc/ViewEngine.d.ts +11 -0
- package/dist/mvc/inertia/InertiaEngine.d.ts +114 -0
- package/dist/mvc/inertia/shared.d.ts +90 -0
- package/dist/mvc/mount-route.d.ts +10 -0
- package/dist/notifications/Notification.d.ts +99 -0
- package/dist/notifications/NotificationManager.d.ts +150 -0
- package/dist/notifications/channels/DatabaseChannel.d.ts +55 -0
- package/dist/notifications/channels/MailChannel.d.ts +45 -0
- package/dist/notifications/channels/MemoryChannel.d.ts +85 -0
- package/dist/notifications/channels/SlackChannel.d.ts +73 -0
- package/dist/notifications/channels/index.d.ts +4 -0
- package/dist/notifications/index.d.ts +6 -322
- package/dist/notifications/notifiable-type.d.ts +10 -0
- package/dist/notifications/registry.d.ts +39 -0
- package/dist/notifications/types.d.ts +162 -0
- package/dist/providers/AuthServiceProvider.d.ts +7 -0
- package/dist/providers/AuthorizationServiceProvider.d.ts +9 -0
- package/dist/providers/BroadcastServiceProvider.d.ts +7 -0
- package/dist/providers/CacheServiceProvider.d.ts +7 -0
- package/dist/providers/EncryptionServiceProvider.d.ts +7 -0
- package/dist/providers/ErrorServiceProvider.d.ts +9 -0
- package/dist/providers/EventServiceProvider.d.ts +7 -0
- package/dist/providers/HealthServiceProvider.d.ts +7 -0
- package/dist/providers/I18nServiceProvider.d.ts +27 -0
- package/dist/providers/InertiaServiceProvider.d.ts +20 -0
- package/dist/providers/LogServiceProvider.d.ts +7 -0
- package/dist/providers/MailServiceProvider.d.ts +7 -0
- package/dist/providers/NotificationServiceProvider.d.ts +8 -0
- package/dist/providers/OAuthServiceProvider.d.ts +7 -0
- package/dist/providers/QueueServiceProvider.d.ts +7 -0
- package/dist/providers/SchedulingServiceProvider.d.ts +7 -0
- package/dist/providers/StorageServiceProvider.d.ts +7 -0
- package/dist/providers/index.d.ts +17 -0
- package/dist/queue/FailedJobReporter.d.ts +40 -0
- package/dist/queue/Job.d.ts +140 -0
- package/dist/queue/QueueManager.d.ts +79 -0
- package/dist/queue/Worker.d.ts +99 -0
- package/dist/queue/drivers/MemoryDriver.d.ts +60 -0
- package/dist/queue/drivers/RedisDriver.d.ts +96 -0
- package/dist/queue/drivers/SqsDriver.d.ts +108 -0
- package/dist/queue/drivers/SyncDriver.d.ts +28 -0
- package/dist/queue/index.d.ts +9 -453
- package/dist/queue/types.d.ts +171 -0
- package/dist/redis/RedisApiTokenStore.d.ts +78 -0
- package/dist/redis/RedisEmailVerificationStore.d.ts +54 -0
- package/dist/redis/RedisOAuthStateStore.d.ts +26 -0
- package/dist/redis/RedisPasswordResetStore.d.ts +57 -0
- package/dist/redis/RedisRateLimitStore.d.ts +77 -0
- package/dist/redis/RedisSessionStore.d.ts +61 -0
- package/dist/redis/client.d.ts +41 -0
- package/dist/redis/index.d.ts +14 -356
- package/dist/redis/index.js +45 -9
- package/dist/redis/redis-values.d.ts +17 -0
- package/dist/redis/scan-keys.d.ts +6 -0
- package/dist/runtime/index.d.ts +8 -95
- package/dist/runtime/index.js +101 -68
- package/dist/scheduling/CronParser.d.ts +37 -0
- package/dist/scheduling/Schedule.d.ts +229 -0
- package/dist/scheduling/ScheduledTask.d.ts +47 -0
- package/dist/scheduling/Scheduler.d.ts +99 -0
- package/dist/scheduling/index.d.ts +5 -41
- package/dist/scheduling/types.d.ts +97 -0
- package/dist/storage/StorageManager.d.ts +65 -0
- package/dist/storage/drivers/LocalDriver.d.ts +55 -0
- package/dist/storage/drivers/MemoryDriver.d.ts +66 -0
- package/dist/storage/drivers/S3Driver.d.ts +72 -0
- package/dist/storage/index.d.ts +5 -197
- package/dist/{StorageManager-oZTHqaza.d.ts → storage/types.d.ts} +10 -77
- package/dist/support/contained-path.d.ts +26 -0
- package/dist/support/error-polyfill.d.ts +9 -0
- package/dist/support/expiry.d.ts +47 -0
- package/dist/support/expiry.js +12 -0
- package/dist/support/import-map.d.ts +13 -0
- package/dist/support/redirect-target.d.ts +11 -0
- package/dist/support/stack-frames.d.ts +56 -0
- package/dist/support/trim-slashes.d.ts +11 -0
- package/dist/vite/index.d.ts +2 -35
- package/dist/vite/index.js +0 -3
- package/dist/vite/plugin.d.ts +34 -0
- package/package.json +7 -3
- package/dist/AuthManager-DBP4KYsx.d.ts +0 -79
- package/dist/BroadcastManager-D8KoJxiV.d.ts +0 -492
- package/dist/HealthManager-DUyMIzsZ.d.ts +0 -141
- package/dist/I18nManager-BiSoczfV.d.ts +0 -275
- package/dist/LogManager-7mxnkaPM.d.ts +0 -256
- package/dist/McpServiceProvider-7BB5FPF3.js +0 -8
- package/dist/Scheduler-pZiT8i57.d.ts +0 -471
- package/dist/api-token-D24VPr_E.d.ts +0 -663
- package/dist/app-key-CsBfRC_Q.d.ts +0 -214
- package/dist/email-verification-Dx426KLn.d.ts +0 -336
- package/dist/index-9_Jzj5jo.d.ts +0 -7
- package/dist/validation-yAL53e1S.d.ts +0 -2610
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
import { Hono } from 'hono';
|
|
2
|
+
import type { MiddlewareHandler, ExecutionContext } from 'hono';
|
|
3
|
+
import { Router } from '../mvc/Router.js';
|
|
4
|
+
import { Container, type GurenModule } from '../container/index.js';
|
|
5
|
+
import { type ServiceProviderConstructor } from '../container/ServiceProvider.js';
|
|
6
|
+
import { AuthManager } from '../auth/AuthManager.js';
|
|
7
|
+
import type { CreateSessionMiddlewareOptions } from './middleware/session.js';
|
|
8
|
+
import type { DetectLocaleOptions } from './middleware/detect-locale.js';
|
|
9
|
+
import type { TranslationLoader } from '../i18n/index.js';
|
|
10
|
+
import { type SecurityHeadersOptions } from './middleware/security-headers.js';
|
|
11
|
+
import { type HostAuthorizationOptions } from './middleware/host-authorization.js';
|
|
12
|
+
import { type DevBannerOptions } from './dev-banner.js';
|
|
13
|
+
import { type StartViteDevServerOptions } from './vite-dev-server.js';
|
|
14
|
+
export type BootCallback = (app: Hono) => void | Promise<void>;
|
|
15
|
+
/**
|
|
16
|
+
* Service provider class constructor type.
|
|
17
|
+
*/
|
|
18
|
+
export type { ServiceProviderConstructor } from '../container/ServiceProvider.js';
|
|
19
|
+
export type RouteRegistration = (router: Router) => void | Promise<void>;
|
|
20
|
+
export type ApplicationFeatures = Record<string, unknown>;
|
|
21
|
+
export interface ApplicationOptions {
|
|
22
|
+
readonly boot?: BootCallback;
|
|
23
|
+
readonly providers?: Array<ServiceProviderConstructor>;
|
|
24
|
+
readonly auth?: AuthPluginOptions;
|
|
25
|
+
/**
|
|
26
|
+
* Configure internationalization: translation loading, locale detection,
|
|
27
|
+
* and Inertia `_i18n` shared props. When set, {@link I18nServiceProvider}
|
|
28
|
+
* is registered automatically.
|
|
29
|
+
*/
|
|
30
|
+
readonly i18n?: I18nPluginOptions;
|
|
31
|
+
readonly discover?: boolean;
|
|
32
|
+
readonly routes?: RouteRegistration;
|
|
33
|
+
/**
|
|
34
|
+
* Application modules (RFC 0002) — each module's providers are appended
|
|
35
|
+
* to `providers` below, and its route registrar runs after `routes`
|
|
36
|
+
* (wrapped in `router.group(prefix, ...)` when the module declares one).
|
|
37
|
+
*/
|
|
38
|
+
readonly modules?: GurenModule[];
|
|
39
|
+
readonly features?: ApplicationFeatures;
|
|
40
|
+
/**
|
|
41
|
+
* Configure or disable the default security headers middleware.
|
|
42
|
+
* Set to `false` to disable entirely, or pass `SecurityHeadersOptions` to customize.
|
|
43
|
+
* Enabled by default with safe Rails-matching defaults.
|
|
44
|
+
*/
|
|
45
|
+
readonly securityHeaders?: SecurityHeadersOptions | false;
|
|
46
|
+
/**
|
|
47
|
+
* Configure host authorization middleware for DNS rebinding protection.
|
|
48
|
+
* Pass `HostAuthorizationOptions` to enable, or `false` / omit to disable.
|
|
49
|
+
* The `create-app` template includes a default localhost configuration.
|
|
50
|
+
*/
|
|
51
|
+
readonly hostAuthorization?: HostAuthorizationOptions | false;
|
|
52
|
+
}
|
|
53
|
+
export interface I18nPluginOptions {
|
|
54
|
+
/**
|
|
55
|
+
* Locales the app supports. Locale detection only ever resolves to one of
|
|
56
|
+
* these, and all of them are preloaded during `boot()`.
|
|
57
|
+
*/
|
|
58
|
+
readonly supported: readonly string[];
|
|
59
|
+
/**
|
|
60
|
+
* Fallback (and default) locale. Defaults to the first supported locale.
|
|
61
|
+
*/
|
|
62
|
+
readonly fallback?: string;
|
|
63
|
+
/**
|
|
64
|
+
* Directory containing `<path>/<locale>/*.json` translation files, loaded
|
|
65
|
+
* with {@link JsonLoader}. Defaults to `'lang'`. Ignored when `loader` is
|
|
66
|
+
* set.
|
|
67
|
+
*
|
|
68
|
+
* Framework tooling (typed keys from `guren codegen`, `guren check
|
|
69
|
+
* --i18n`, the Vite watch) assumes the default `lang/` location — a
|
|
70
|
+
* custom path or loader opts out of those.
|
|
71
|
+
*/
|
|
72
|
+
readonly path?: string;
|
|
73
|
+
/**
|
|
74
|
+
* Custom translation loader (e.g. `MemoryLoader` for bundled messages on
|
|
75
|
+
* serverless targets without a filesystem). Takes precedence over `path`.
|
|
76
|
+
*/
|
|
77
|
+
readonly loader?: TranslationLoader;
|
|
78
|
+
/**
|
|
79
|
+
* Locale detection middleware options. `detectLocaleMiddleware` is mounted
|
|
80
|
+
* automatically with the `supported` locales and `fallback` above; pass
|
|
81
|
+
* `false` to mount (or skip) it yourself.
|
|
82
|
+
*/
|
|
83
|
+
readonly detect?: Omit<DetectLocaleOptions, 'supported' | 'fallback' | 'i18n'> | false;
|
|
84
|
+
/**
|
|
85
|
+
* Share the request locale and its messages with Inertia pages as the
|
|
86
|
+
* `_i18n` prop. Defaults to `true`.
|
|
87
|
+
*/
|
|
88
|
+
readonly share?: boolean;
|
|
89
|
+
}
|
|
90
|
+
export interface AuthPluginOptions {
|
|
91
|
+
autoSession?: boolean;
|
|
92
|
+
sessionOptions?: CreateSessionMiddlewareOptions;
|
|
93
|
+
/**
|
|
94
|
+
* Automatically register CSRF middleware when session is enabled.
|
|
95
|
+
* Defaults to `true`. Set to `false` to disable (e.g., for pure API servers).
|
|
96
|
+
*/
|
|
97
|
+
autoCsrf?: boolean;
|
|
98
|
+
/**
|
|
99
|
+
* Options passed to the CSRF middleware when `autoCsrf` is enabled.
|
|
100
|
+
*/
|
|
101
|
+
csrfOptions?: import('./middleware/csrf.js').CsrfOptions;
|
|
102
|
+
}
|
|
103
|
+
export interface ApplicationListenOptions {
|
|
104
|
+
port?: number;
|
|
105
|
+
hostname?: string;
|
|
106
|
+
assetsUrl?: string;
|
|
107
|
+
vite?: StartViteDevServerOptions | false;
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Application wires an app-local router into a running Hono instance.
|
|
111
|
+
*
|
|
112
|
+
* It embeds a DI Container as the backbone of the framework, binding core
|
|
113
|
+
* services and managing providers through the container's ProviderManager.
|
|
114
|
+
*/
|
|
115
|
+
export declare class Application {
|
|
116
|
+
private readonly options;
|
|
117
|
+
readonly hono: Hono;
|
|
118
|
+
readonly container: Container;
|
|
119
|
+
readonly router: Router;
|
|
120
|
+
private readonly providerManager;
|
|
121
|
+
private readonly authManager;
|
|
122
|
+
private viteDevServer?;
|
|
123
|
+
private bunServer?;
|
|
124
|
+
private viteTeardownRegistered;
|
|
125
|
+
private bunTeardownRegistered;
|
|
126
|
+
private autoSessionAttached;
|
|
127
|
+
private routesRegistered;
|
|
128
|
+
private bootPromise?;
|
|
129
|
+
constructor(options?: ApplicationOptions);
|
|
130
|
+
get auth(): AuthManager;
|
|
131
|
+
get authOptions(): AuthPluginOptions | undefined;
|
|
132
|
+
get i18nOptions(): I18nPluginOptions | undefined;
|
|
133
|
+
markAutoSessionAttached(): void;
|
|
134
|
+
hasAutoSessionAttached(): boolean;
|
|
135
|
+
/**
|
|
136
|
+
* Mounts the application router onto the Hono instance.
|
|
137
|
+
*/
|
|
138
|
+
mountRoutes(): Promise<void>;
|
|
139
|
+
/**
|
|
140
|
+
* Allows registering global middlewares directly on the underlying Hono app.
|
|
141
|
+
*/
|
|
142
|
+
use(path: string, ...middleware: MiddlewareHandler[]): void;
|
|
143
|
+
/**
|
|
144
|
+
* Executes provider registration, boot callback, mounts routes, and boots providers.
|
|
145
|
+
*
|
|
146
|
+
* Booting twice is a no-op: the first call's promise is reused, so providers
|
|
147
|
+
* and routes are never mounted a second time — including when two callers
|
|
148
|
+
* boot concurrently, before the first has finished. A boot that throws is not
|
|
149
|
+
* remembered, so a later call attempts boot again (it resumes on a partially
|
|
150
|
+
* mounted app rather than starting clean). The security defaults are mounted
|
|
151
|
+
* by the constructor and so are outside this entirely.
|
|
152
|
+
*/
|
|
153
|
+
boot(): Promise<void>;
|
|
154
|
+
private bootOnce;
|
|
155
|
+
/**
|
|
156
|
+
* Registers default security middleware (headers + host authorization).
|
|
157
|
+
*
|
|
158
|
+
* Called once, from the constructor — see the note there for why it does
|
|
159
|
+
* not belong in boot().
|
|
160
|
+
*/
|
|
161
|
+
private mountSecurityDefaults;
|
|
162
|
+
private mountHostAuthorization;
|
|
163
|
+
/**
|
|
164
|
+
* Mounts an opt-in, dev-only framework endpoint: the MCP endpoint
|
|
165
|
+
* (/_guren/mcp) and the docs viewer (/_guren/docs) both work this way.
|
|
166
|
+
*
|
|
167
|
+
* Only the dynamic import is allowed to fail silently — these
|
|
168
|
+
* providers reach optional dependencies (the MCP SDK, @guren/cli) that
|
|
169
|
+
* an app need not have installed, and `missing` names that case. A
|
|
170
|
+
* failure inside the provider's own boot is a real problem and is
|
|
171
|
+
* rethrown, rather than leaving the developer with a silent 404.
|
|
172
|
+
*/
|
|
173
|
+
private mountDevEndpoint;
|
|
174
|
+
/**
|
|
175
|
+
* Fetch handler to integrate with Bun.serve or any standard Fetch runtime.
|
|
176
|
+
*/
|
|
177
|
+
fetch(request: Request, env?: unknown, executionCtx?: ExecutionContext): Promise<Response>;
|
|
178
|
+
/**
|
|
179
|
+
* Convenience helper to start a Bun server when available.
|
|
180
|
+
*/
|
|
181
|
+
listen(options?: ApplicationListenOptions): Promise<void>;
|
|
182
|
+
/**
|
|
183
|
+
* Register a service provider.
|
|
184
|
+
*/
|
|
185
|
+
register(provider: ServiceProviderConstructor): this;
|
|
186
|
+
/**
|
|
187
|
+
* Register multiple service providers.
|
|
188
|
+
*/
|
|
189
|
+
registerMany(providers: Array<ServiceProviderConstructor>): this;
|
|
190
|
+
/**
|
|
191
|
+
* Logs the rich development server banner to the console.
|
|
192
|
+
*/
|
|
193
|
+
logDevServerBanner(options: DevBannerOptions): void;
|
|
194
|
+
private closeViteDevServer;
|
|
195
|
+
private registerViteTeardown;
|
|
196
|
+
private registerBunTeardown;
|
|
197
|
+
}
|
|
198
|
+
export declare function createApp(options?: ApplicationOptions): Application;
|
|
199
|
+
export type { Context } from 'hono';
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import type { Context } from 'hono';
|
|
2
|
+
import type { ValidationRule } from './validation/types.js';
|
|
3
|
+
/**
|
|
4
|
+
* Base class for form request validation.
|
|
5
|
+
*
|
|
6
|
+
* FormRequest encapsulates both validation rules and authorization logic
|
|
7
|
+
* for a single request type. Extend this class and define `rules()` and
|
|
8
|
+
* optionally `authorize()` to create type-safe request validation.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```typescript
|
|
12
|
+
* interface StorePostData {
|
|
13
|
+
* title: string
|
|
14
|
+
* content: string
|
|
15
|
+
* status: 'draft' | 'published'
|
|
16
|
+
* }
|
|
17
|
+
*
|
|
18
|
+
* class StorePostRequest extends FormRequest<StorePostData> {
|
|
19
|
+
* rules() {
|
|
20
|
+
* return {
|
|
21
|
+
* title: [required(), stringRule(), min(3), max(255)],
|
|
22
|
+
* content: [required(), stringRule()],
|
|
23
|
+
* status: [required(), inValues(['draft', 'published'])],
|
|
24
|
+
* }
|
|
25
|
+
* }
|
|
26
|
+
*
|
|
27
|
+
* authorize() {
|
|
28
|
+
* return this.user() !== null
|
|
29
|
+
* }
|
|
30
|
+
* }
|
|
31
|
+
*
|
|
32
|
+
* // In controller:
|
|
33
|
+
* const data = await this.validate(StorePostRequest)
|
|
34
|
+
* // data is typed as StorePostData
|
|
35
|
+
* ```
|
|
36
|
+
*/
|
|
37
|
+
/**
|
|
38
|
+
* @deprecated Legacy compatibility layer — prefer schema-first validation
|
|
39
|
+
* via `this.validateBody()` / `validateQuery()` / `validateParams()`.
|
|
40
|
+
*/
|
|
41
|
+
export declare abstract class FormRequest<T = Record<string, unknown>> {
|
|
42
|
+
protected ctx: Context;
|
|
43
|
+
/**
|
|
44
|
+
* Define validation rules for this request.
|
|
45
|
+
* Return an object mapping field names to arrays of validation rules.
|
|
46
|
+
*/
|
|
47
|
+
abstract rules(): Record<string, ValidationRule[]>;
|
|
48
|
+
/**
|
|
49
|
+
* Determine if the user is authorized to make this request.
|
|
50
|
+
* Override to implement authorization logic. Defaults to true.
|
|
51
|
+
*/
|
|
52
|
+
authorize(): boolean | Promise<boolean>;
|
|
53
|
+
/**
|
|
54
|
+
* Custom error messages for validation rules.
|
|
55
|
+
* Override to provide custom messages.
|
|
56
|
+
*/
|
|
57
|
+
messages(): Record<string, string>;
|
|
58
|
+
/**
|
|
59
|
+
* Custom attribute names for validation errors.
|
|
60
|
+
* Override to provide human-readable field names.
|
|
61
|
+
*/
|
|
62
|
+
attributes(): Record<string, string>;
|
|
63
|
+
/**
|
|
64
|
+
* Get the authenticated user from the request context.
|
|
65
|
+
*/
|
|
66
|
+
protected user(): unknown;
|
|
67
|
+
/**
|
|
68
|
+
* Handle the form request: authorize, parse body, validate, return typed data.
|
|
69
|
+
* @internal Called by Controller.validate()
|
|
70
|
+
*/
|
|
71
|
+
handle(ctx: Context): Promise<T>;
|
|
72
|
+
private parseBody;
|
|
73
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import type { Application } from './Application.js';
|
|
2
|
+
import { type RootPublicAssetsConfig } from './public-assets.js';
|
|
3
|
+
/**
|
|
4
|
+
* Derive the mount point for the vendored Inertia client from its public
|
|
5
|
+
* path: the containing directory (always slash-terminated), the Hono route
|
|
6
|
+
* pattern for it, and the file's path relative to that base.
|
|
7
|
+
*/
|
|
8
|
+
export declare function resolveInertiaClientRoute(inertiaClientPath: string): {
|
|
9
|
+
base: string;
|
|
10
|
+
pattern: string;
|
|
11
|
+
requestPath: string;
|
|
12
|
+
};
|
|
13
|
+
export interface DevAssetsOptions {
|
|
14
|
+
/** Absolute path to the resources directory (e.g. `/app/resources`). */
|
|
15
|
+
resourcesDir?: string;
|
|
16
|
+
/** Base import meta used to resolve relative paths. */
|
|
17
|
+
importMeta?: ImportMeta;
|
|
18
|
+
/** Relative path from `importMeta` to the resources directory. Defaults to `../resources`. */
|
|
19
|
+
resourcesPath?: string;
|
|
20
|
+
/** Path prefix to mount transpiled JS assets. Defaults to `/resources/js`. */
|
|
21
|
+
prefix?: string;
|
|
22
|
+
/** Route pattern used to serve raw CSS assets. Defaults to `/resources/css/*`. */
|
|
23
|
+
cssRoute?: string;
|
|
24
|
+
/** Absolute path to the CSS directory. Defaults to `<resourcesDir>/../css`. */
|
|
25
|
+
cssDir?: string;
|
|
26
|
+
/** Enables serving the bundled inertia client. Defaults to true. */
|
|
27
|
+
inertiaClient?: boolean;
|
|
28
|
+
/** Path to the inertia client source. Defaults to the version bundled with Guren. */
|
|
29
|
+
inertiaClientSource?: string;
|
|
30
|
+
/** Public URL for the inertia client. Defaults to `/vendor/inertia-client.tsx`. */
|
|
31
|
+
inertiaClientPath?: string;
|
|
32
|
+
/** Override the remote JSX runtime URL. */
|
|
33
|
+
jsxRuntimeUrl?: string;
|
|
34
|
+
/** Absolute path to a directory with static assets (e.g. `/app/public`). */
|
|
35
|
+
publicDir?: string;
|
|
36
|
+
/** Relative path from `importMeta` to the static assets directory. Defaults to `../public`. */
|
|
37
|
+
publicPath?: string | false;
|
|
38
|
+
/** Route pattern used when serving static assets. Defaults to `/public/*`. */
|
|
39
|
+
publicRoute?: string;
|
|
40
|
+
/** Whether to register a no-op favicon route. Defaults to true when static assets are served. */
|
|
41
|
+
favicon?: boolean;
|
|
42
|
+
/** Serve selected files from the public directory without the `/public` prefix. */
|
|
43
|
+
rootPublicAssets?: RootPublicAssetsConfig;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Absolute path to `@guren/inertia-client`'s build output, the directory
|
|
47
|
+
* production serves the vendored client and its chunks from.
|
|
48
|
+
*
|
|
49
|
+
* Unlike {@link resolveGurenInertiaClient}, this must not follow a tsconfig
|
|
50
|
+
* `paths` mapping to the package's TypeScript sources — production serves
|
|
51
|
+
* files, it cannot transpile them. So it anchors on `./package.json`, a
|
|
52
|
+
* subpath such a mapping misses (there is no `src/package.json`) and real
|
|
53
|
+
* package resolution answers with the package root.
|
|
54
|
+
*/
|
|
55
|
+
export declare function resolveInertiaClientDir(): string;
|
|
56
|
+
/**
|
|
57
|
+
* Registers development asset serving middleware.
|
|
58
|
+
* @param app
|
|
59
|
+
* @param options
|
|
60
|
+
*/
|
|
61
|
+
export declare function registerDevAssets(app: Application, options: DevAssetsOptions): void;
|
|
62
|
+
export declare function createStaticRewrite(route: string): (path: string) => string;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { Application } from './Application.js';
|
|
2
|
+
import { type DevAssetsOptions } from './dev-assets.js';
|
|
3
|
+
export interface InertiaAssetsOptions extends DevAssetsOptions {
|
|
4
|
+
/** Default stylesheet entry embedded into Inertia responses. */
|
|
5
|
+
stylesEntry?: string;
|
|
6
|
+
/** Default script entry embedded into Inertia responses (production). */
|
|
7
|
+
scriptEntry?: string;
|
|
8
|
+
/** Path to the SSR bundle entry consumed by the Inertia engine. */
|
|
9
|
+
ssrEntry?: string;
|
|
10
|
+
/** Path to the SSR manifest file generated by the build. */
|
|
11
|
+
ssrManifest?: string;
|
|
12
|
+
}
|
|
13
|
+
export interface AutoConfigureInertiaOptions extends InertiaAssetsOptions {
|
|
14
|
+
/** Dev server URL used when NODE_ENV !== 'production'. */
|
|
15
|
+
devServerUrl?: string;
|
|
16
|
+
/** Output directory for Vite SSR bundles (relative to project root). */
|
|
17
|
+
ssrOutDir?: string;
|
|
18
|
+
/** Enables SSR auto-wiring (defaults to true). */
|
|
19
|
+
enableSsr?: boolean;
|
|
20
|
+
}
|
|
21
|
+
export declare function configureInertiaAssets(app: Application, options: InertiaAssetsOptions): void;
|
|
22
|
+
/**
|
|
23
|
+
* Serves the built Inertia client and the chunks it imports out of the
|
|
24
|
+
* resolved package directory.
|
|
25
|
+
*
|
|
26
|
+
* Split out of {@link configureInertiaAssets} so it can be pointed at a
|
|
27
|
+
* directory: the caller derives `inertiaClientDir` from `import.meta.resolve`,
|
|
28
|
+
* which no test can redirect at a fixture.
|
|
29
|
+
*/
|
|
30
|
+
export declare function registerBuiltInertiaClient(app: Application, inertiaClientDir: string, inertiaClientPath: string): void;
|
|
31
|
+
export declare function autoConfigureInertiaAssets(app: Application, options: AutoConfigureInertiaOptions): void;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { Context, MiddlewareHandler } from 'hono';
|
|
2
|
+
import type { AuthContext } from '../../auth/types.js';
|
|
3
|
+
export type { AuthContext } from '../../auth/types.js';
|
|
4
|
+
export interface RequireAuthOptions {
|
|
5
|
+
redirectTo?: string;
|
|
6
|
+
status?: number;
|
|
7
|
+
responseFactory?: () => Response;
|
|
8
|
+
}
|
|
9
|
+
declare const AUTH_CONTEXT_KEY = "guren:auth";
|
|
10
|
+
export declare function attachAuthContext(contextFactory: (ctx: Context) => AuthContext): MiddlewareHandler;
|
|
11
|
+
export declare function requireAuthenticated(options?: RequireAuthOptions): MiddlewareHandler;
|
|
12
|
+
export declare function requireGuest(options?: RequireAuthOptions): MiddlewareHandler;
|
|
13
|
+
export { AUTH_CONTEXT_KEY };
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { MiddlewareHandler } from 'hono';
|
|
2
|
+
/**
|
|
3
|
+
* Internal security-capability marker (RFC 0007).
|
|
4
|
+
*
|
|
5
|
+
* Built-in middleware factories stamp the handlers they return so tooling
|
|
6
|
+
* that holds the real function objects (the router registry, `guren audit`
|
|
7
|
+
* via route loading) can recognize what a handler enforces without name
|
|
8
|
+
* heuristics. `Symbol.for()` keeps the key identical across duplicated
|
|
9
|
+
* `@guren/server` copies in one process.
|
|
10
|
+
*
|
|
11
|
+
* Deliberately not part of the public API: nothing here is exported from
|
|
12
|
+
* the package root, and the shape may change in any release. A public
|
|
13
|
+
* `defineMiddleware` integration is future work in RFC 0007.
|
|
14
|
+
*/
|
|
15
|
+
export declare const CAPABILITIES: unique symbol;
|
|
16
|
+
export interface MiddlewareCapabilities {
|
|
17
|
+
authentication?: {
|
|
18
|
+
mode: 'required' | 'guest-only';
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
export declare function stampCapabilities(handler: MiddlewareHandler, capabilities: MiddlewareCapabilities): MiddlewareHandler;
|
|
22
|
+
export declare function capabilitiesOf(handler: unknown): MiddlewareCapabilities | undefined;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { MiddlewareHandler } from 'hono';
|
|
2
|
+
export interface CorsOptions {
|
|
3
|
+
/**
|
|
4
|
+
* Allowed origins. Default: none (same-origin policy applies).
|
|
5
|
+
* - A string: exact origin match (use '*' to allow all origins)
|
|
6
|
+
* - An array of strings: multiple allowed origins
|
|
7
|
+
* - A function: dynamic origin evaluation
|
|
8
|
+
*/
|
|
9
|
+
origin?: string | string[] | ((origin: string, ctx: unknown) => string | undefined | null);
|
|
10
|
+
/** Allowed HTTP methods. Default: ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH'] */
|
|
11
|
+
allowMethods?: string[];
|
|
12
|
+
/** Allowed request headers. */
|
|
13
|
+
allowHeaders?: string[];
|
|
14
|
+
/** Headers exposed to the browser. */
|
|
15
|
+
exposeHeaders?: string[];
|
|
16
|
+
/** Preflight cache max-age in seconds. */
|
|
17
|
+
maxAge?: number;
|
|
18
|
+
/** Allow credentials (cookies, authorization headers). Default: false */
|
|
19
|
+
credentials?: boolean;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* CORS middleware powered by Hono's built-in CORS support.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* import { createCorsMiddleware } from '@guren/core'
|
|
27
|
+
*
|
|
28
|
+
* // Allow specific origins
|
|
29
|
+
* app.use('/api/*', createCorsMiddleware({
|
|
30
|
+
* origin: ['https://example.com', 'https://app.example.com'],
|
|
31
|
+
* credentials: true,
|
|
32
|
+
* }))
|
|
33
|
+
*
|
|
34
|
+
* // Dynamic origin
|
|
35
|
+
* app.use('/api/*', createCorsMiddleware({
|
|
36
|
+
* origin: (origin) => origin.endsWith('.example.com') ? origin : null,
|
|
37
|
+
* }))
|
|
38
|
+
* ```
|
|
39
|
+
*/
|
|
40
|
+
export declare function createCorsMiddleware(options?: CorsOptions): MiddlewareHandler;
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import type { Context, MiddlewareHandler } from 'hono';
|
|
2
|
+
export interface CspDirectives {
|
|
3
|
+
defaultSrc?: string[];
|
|
4
|
+
scriptSrc?: string[];
|
|
5
|
+
styleSrc?: string[];
|
|
6
|
+
imgSrc?: string[];
|
|
7
|
+
fontSrc?: string[];
|
|
8
|
+
connectSrc?: string[];
|
|
9
|
+
mediaSrc?: string[];
|
|
10
|
+
objectSrc?: string[];
|
|
11
|
+
frameSrc?: string[];
|
|
12
|
+
childSrc?: string[];
|
|
13
|
+
workerSrc?: string[];
|
|
14
|
+
frameAncestors?: string[];
|
|
15
|
+
formAction?: string[];
|
|
16
|
+
baseUri?: string[];
|
|
17
|
+
manifestSrc?: string[];
|
|
18
|
+
upgradeInsecureRequests?: boolean;
|
|
19
|
+
blockAllMixedContent?: boolean;
|
|
20
|
+
/** Escape hatch for directives not listed above. */
|
|
21
|
+
[directive: string]: string[] | boolean | undefined;
|
|
22
|
+
}
|
|
23
|
+
export interface CspOptions {
|
|
24
|
+
/** CSP directives configuration. */
|
|
25
|
+
directives?: CspDirectives;
|
|
26
|
+
/** Use Content-Security-Policy-Report-Only instead. Default: false */
|
|
27
|
+
reportOnly?: boolean;
|
|
28
|
+
/** URI for CSP violation reports. */
|
|
29
|
+
reportUri?: string;
|
|
30
|
+
/** Generate a per-request nonce and auto-append to script-src and style-src. Default: false */
|
|
31
|
+
useNonce?: boolean;
|
|
32
|
+
}
|
|
33
|
+
export declare const CSP_NONCE_KEY = "csp-nonce";
|
|
34
|
+
/**
|
|
35
|
+
* Retrieve the CSP nonce for the current request.
|
|
36
|
+
* Only available when `useNonce: true` is set.
|
|
37
|
+
*/
|
|
38
|
+
export declare function getCspNonce(ctx: Context): string;
|
|
39
|
+
/**
|
|
40
|
+
* Middleware that sets Content-Security-Policy headers.
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* ```ts
|
|
44
|
+
* import { createCspMiddleware, getCspNonce } from '@guren/core'
|
|
45
|
+
*
|
|
46
|
+
* app.use('*', createCspMiddleware({
|
|
47
|
+
* directives: {
|
|
48
|
+
* defaultSrc: ["'self'"],
|
|
49
|
+
* scriptSrc: ["'self'", 'https://cdn.example.com'],
|
|
50
|
+
* styleSrc: ["'self'", "'unsafe-inline'"],
|
|
51
|
+
* imgSrc: ["'self'", 'data:', 'https:'],
|
|
52
|
+
* objectSrc: ["'none'"],
|
|
53
|
+
* },
|
|
54
|
+
* useNonce: true,
|
|
55
|
+
* reportUri: '/csp-report',
|
|
56
|
+
* }))
|
|
57
|
+
* ```
|
|
58
|
+
*/
|
|
59
|
+
export declare function createCspMiddleware(options?: CspOptions): MiddlewareHandler;
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
import type { Context, MiddlewareHandler } from 'hono';
|
|
2
|
+
export declare const CSRF_TOKEN_KEY = "_csrf_token";
|
|
3
|
+
export declare const CSRF_HEADER_NAME = "X-CSRF-TOKEN";
|
|
4
|
+
export declare const XSRF_HEADER_NAME = "X-XSRF-TOKEN";
|
|
5
|
+
export declare const XSRF_COOKIE_NAME = "XSRF-TOKEN";
|
|
6
|
+
export declare const CSRF_FORM_FIELD = "_token";
|
|
7
|
+
export interface CsrfOptions {
|
|
8
|
+
/**
|
|
9
|
+
* Routes to exclude from CSRF protection.
|
|
10
|
+
* Supports exact paths ('/api/webhook') or patterns ('/api/*').
|
|
11
|
+
*/
|
|
12
|
+
exclude?: string[];
|
|
13
|
+
/**
|
|
14
|
+
* Custom error handler when CSRF validation fails.
|
|
15
|
+
* Defaults to returning a 403 JSON response.
|
|
16
|
+
*/
|
|
17
|
+
onError?: (ctx: Context) => Response | Promise<Response>;
|
|
18
|
+
/**
|
|
19
|
+
* HTTP methods that require CSRF token validation.
|
|
20
|
+
* Defaults to ['POST', 'PUT', 'PATCH', 'DELETE'].
|
|
21
|
+
*/
|
|
22
|
+
methods?: string[];
|
|
23
|
+
/**
|
|
24
|
+
* Set the CSRF token as an `XSRF-TOKEN` cookie on every response.
|
|
25
|
+
* This enables Axios/Inertia.js to automatically read the cookie
|
|
26
|
+
* and send it back as the `X-XSRF-TOKEN` header.
|
|
27
|
+
* Defaults to true.
|
|
28
|
+
*/
|
|
29
|
+
cookie?: boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Cookie options when `cookie` is enabled.
|
|
32
|
+
*/
|
|
33
|
+
cookieOptions?: {
|
|
34
|
+
path?: string;
|
|
35
|
+
secure?: boolean;
|
|
36
|
+
sameSite?: 'Strict' | 'Lax' | 'None';
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Get the request's CSRF token.
|
|
41
|
+
*
|
|
42
|
+
* Signed token bound to the session when a stable one exists, otherwise a
|
|
43
|
+
* stateless signed double-submit token for guests. Nothing is stored
|
|
44
|
+
* server-side, so anonymous page views cost no session writes. A cookie
|
|
45
|
+
* token that is still valid for this request's mode is reused; otherwise a
|
|
46
|
+
* fresh token is minted and set on the response by the middleware.
|
|
47
|
+
*
|
|
48
|
+
* The answer tracks the session as it stands *at the moment of the call*,
|
|
49
|
+
* because a handler can change it: log a user in and the correct token stops
|
|
50
|
+
* being the guest one it would have got a line earlier. A token cached from
|
|
51
|
+
* before that point would be rendered into the response body while the
|
|
52
|
+
* response cookie carried a session-bound one, and `verifyCsrfToken` would
|
|
53
|
+
* then reject the form on submit. So the per-request cache is keyed by the
|
|
54
|
+
* mode it was issued for, and re-issues when the mode moves — which also
|
|
55
|
+
* makes re-reads free, since the common case is that nothing changed.
|
|
56
|
+
*/
|
|
57
|
+
export declare function getCsrfToken(ctx: Context): string;
|
|
58
|
+
/**
|
|
59
|
+
* Generate an HTML hidden input field containing the CSRF token.
|
|
60
|
+
*/
|
|
61
|
+
export declare function csrfField(ctx: Context): string;
|
|
62
|
+
/**
|
|
63
|
+
* Verify a request token.
|
|
64
|
+
*
|
|
65
|
+
* The token must first carry a valid app-key signature (proving this server
|
|
66
|
+
* minted it). The mode is then fixed by the request — whether it carries a
|
|
67
|
+
* bindable session — and the token has to be in that mode:
|
|
68
|
+
* - **Session-bound** (request has a session; token must carry a matching
|
|
69
|
+
* `sid`): immune to cookie injection — a sibling-subdomain attacker can
|
|
70
|
+
* plant a cookie but cannot know the victim's session id. A stateless
|
|
71
|
+
* token is rejected here, which is the point: anyone can mint one.
|
|
72
|
+
* - **Stateless** (request has no session, so no `sid`): the token must match the `XSRF-TOKEN`
|
|
73
|
+
* cookie (double-submit). Guests hold no authenticated state to protect.
|
|
74
|
+
*
|
|
75
|
+
* Legacy fallback: tokens stored in sessions by earlier releases keep
|
|
76
|
+
* verifying against the session until those sessions expire. Remove this
|
|
77
|
+
* branch once all pre-upgrade sessions have aged out (a major release).
|
|
78
|
+
*/
|
|
79
|
+
export declare function verifyCsrfToken(ctx: Context, token: string | undefined): boolean;
|
|
80
|
+
/**
|
|
81
|
+
* Creates a CSRF protection middleware.
|
|
82
|
+
*
|
|
83
|
+
* This middleware:
|
|
84
|
+
* - Issues a signed token in the `XSRF-TOKEN` cookie on safe requests.
|
|
85
|
+
* With a logged-in session the token is bound to the session id; for
|
|
86
|
+
* guests it is a stateless double-submit token. Nothing is stored
|
|
87
|
+
* server-side, so anonymous traffic costs no session writes and session
|
|
88
|
+
* middleware is optional.
|
|
89
|
+
* - Validates the token for state-changing HTTP methods (POST, PUT, PATCH,
|
|
90
|
+
* DELETE): always requires a valid app-key signature, then the bound
|
|
91
|
+
* session id or (guest) the cookie match.
|
|
92
|
+
* - Supports token submission via form field (_token) or header (X-CSRF-TOKEN)
|
|
93
|
+
* - Keeps verifying tokens stored in sessions by earlier releases until
|
|
94
|
+
* those sessions expire
|
|
95
|
+
* - Exempts the dev-only MCP endpoint while it is mounted, since agent
|
|
96
|
+
* clients cannot fetch a token first (it guards local-only access instead)
|
|
97
|
+
*
|
|
98
|
+
* `cookie: false` disables the `XSRF-TOKEN` cookie for apps that deliver the
|
|
99
|
+
* token themselves (meta tag / form field). Session-bound tokens still
|
|
100
|
+
* verify without the cookie; guest (stateless) tokens require the cookie, so
|
|
101
|
+
* disable it only for session-authenticated flows.
|
|
102
|
+
*
|
|
103
|
+
* **Mount it directly inside the session middleware.** The response cookie is
|
|
104
|
+
* settled once the handler returns, reading the session id as it stands then.
|
|
105
|
+
* Middleware layered *between* the two that mutates the session after its own
|
|
106
|
+
* `await next()` — regenerating or invalidating it — moves the id after this
|
|
107
|
+
* has already committed to a token, and the next mutation is rejected. The
|
|
108
|
+
* automatic registration in `AuthServiceProvider` mounts them adjacently;
|
|
109
|
+
* hand-composed chains have to keep that property.
|
|
110
|
+
*
|
|
111
|
+
* @example
|
|
112
|
+
* ```ts
|
|
113
|
+
* import { createCsrfMiddleware } from '@guren/server'
|
|
114
|
+
*
|
|
115
|
+
* app.use(createSessionMiddleware())
|
|
116
|
+
* app.use(createCsrfMiddleware({
|
|
117
|
+
* exclude: ['/api/webhooks/*']
|
|
118
|
+
* }))
|
|
119
|
+
* ```
|
|
120
|
+
*/
|
|
121
|
+
export declare function createCsrfMiddleware(options?: CsrfOptions): MiddlewareHandler;
|