@velajs/vela 1.14.0 → 1.16.0

package/dist/config/register-as.js

@@ -0,0 +1,39 @@
+// Config-namespace registration. Design ported from stratal's `registerAs`
+// (MIT, © Temitayo Fadojutimi) and reworked for vela's multi-runtime DI: env
+// enters through the `CONFIG_ENV` token instead of a Cloudflare-specific one.
+import { CONFIG_ENV } from "./config.tokens.js";
+/**
+ * Create a namespaced configuration factory (NestJS `registerAs` parity).
+ *
+ * The `KEY` is minted with `Symbol.for` so it keeps a stable identity across
+ * module re-evaluation (HMR / repeated imports) — a fresh `InjectionToken`
+ * would mint a new identity each eval and break dedup. It is typed as
+ * `InjectionToken<TConfig>` purely for injection-site DX.
+ *
+ * @example
+ * ```ts
+ * export const dbConfig = registerAs('database', (env: Env) => ({
+ *   url: env.DATABASE_URL,
+ *   pool: 10,
+ * }));
+ * // ConfigModule.forRoot({ load: [dbConfig] });
+ * // cfg.get('database.url');                              // via ConfigService
+ * // constructor(@Inject(dbConfig.KEY) db: InferConfigType<typeof dbConfig>) {}
+ * ```
+ */ export function registerAs(namespace, factory) {
+    const KEY = Symbol.for(`vela:config:${namespace}`);
+    return {
+        KEY,
+        namespace,
+        factory,
+        asProvider () {
+            return {
+                provide: KEY,
+                useFactory: factory,
+                inject: [
+                    CONFIG_ENV
+                ]
+            };
+        }
+    };
+}

package/dist/container/container.d.ts

@@ -1,5 +1,5 @@
 import { Scope } from '../constants';
-import type { ContainerOptions, Diagnostics, LazyResolutionHook, ModuleScope, ProviderOptions, Token, Type } from './types';
+import type { ContainerOptions, Diagnostics, LazyResolutionHook, ModuleDescription, ModuleScope, ProviderOptions, Token, Type } from './types';
 /**
  * Per-module provider buckets. Each module instance owns its providers under
  * its `moduleId`; the same logical token can have distinct registrations in
@@ -95,6 +95,13 @@ export declare class Container {
      * binding module — so framework adapters can initialize all of them.
      */
     getUseValues(): unknown[];
+    /**
+     * Serializable description of every loaded module instance (load order),
+     * plus the `__root__` bucket (bootstrap primitives) when non-empty —
+     * the `vela module graph` seam. Reads registration state only: safe pre-
+     * and post-bootstrap, never constructs, never claims lazy modules.
+     */
+    getModuleDescriptions(): ModuleDescription[];
     /**
      * Compute request-scope bubbling for every registration (call once at
      * bootstrap, after all providers are registered). A provider whose declared

package/dist/container/container.js

@@ -1,7 +1,7 @@
 import { Scope } from "../constants.js";
 import { disposeInstance, isDisposable } from "./disposable.js";
 import { getConstructorDependencies, getInjectMetadata, getScope, isInjectable } from "./decorators.js";
-import { ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
+import { describeToken, ForwardRef, InjectionToken, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
 const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips type-only imports at ' + 'runtime and `design:paramtypes` emits `Object`/`undefined` for their ' + 'positions. Use a runtime `import { X }` for DI tokens.';
 /**
  * Sentinel comparing a token to the bare `Object` class — `design:paramtypes`
@@ -415,6 +415,44 @@ const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips typ
         return out;
     }
     /**
+   * Serializable description of every loaded module instance (load order),
+   * plus the `__root__` bucket (bootstrap primitives) when non-empty —
+   * the `vela module graph` seam. Reads registration state only: safe pre-
+   * and post-bootstrap, never constructs, never claims lazy modules.
+   */ getModuleDescriptions() {
+        const out = [];
+        for (const scope of this.scopes.values()){
+            out.push({
+                moduleId: scope.moduleId,
+                imports: [
+                    ...scope.importedModules
+                ],
+                isGlobal: scope.isGlobal,
+                lazy: scope.lazy === true,
+                providers: [
+                    ...this.providers.get(scope.moduleId)?.keys() ?? []
+                ].map(describeToken),
+                exports: [
+                    ...scope.exportedTokens
+                ].map(describeToken)
+            });
+        }
+        const rootBucket = this.providers.get(ROOT_MODULE_ID);
+        if (rootBucket && rootBucket.size > 0) {
+            out.push({
+                moduleId: ROOT_MODULE_ID,
+                imports: [],
+                isGlobal: false,
+                lazy: false,
+                providers: [
+                    ...rootBucket.keys()
+                ].map(describeToken),
+                exports: []
+            });
+        }
+        return out;
+    }
+    /**
    * Compute request-scope bubbling for every registration (call once at
    * bootstrap, after all providers are registered). A provider whose declared
    * scope is not REQUEST but which (transitively) depends on a request-scoped

package/dist/container/index.d.ts

@@ -1,6 +1,6 @@
 export { Container } from './container';
 export { Injectable, Inject, Optional, isInjectable, getScope } from './decorators';
-export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, } from './types';
+export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, describeToken, } from './types';
 export { ModuleRef } from './module-ref';
 export { mixin } from './mixin';
-export type { Type, Token, InferToken, InferTokens, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ContainerOptions, Diagnostics, } from './types';
+export type { Type, Token, InferToken, InferTokens, InjectableOptions, InjectMetadata, ProviderOptions, ProviderRegistration, InjectionTokenOptions, ModuleScope, ModuleDescription, ContainerOptions, Diagnostics, } from './types';

package/dist/container/index.js

@@ -1,5 +1,5 @@
 export { Container } from "./container.js";
 export { Injectable, Inject, Optional, isInjectable, getScope } from "./decorators.js";
-export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID } from "./types.js";
+export { InjectionToken, ForwardRef, forwardRef, ModuleVisibilityError, MultipleProvidersFoundError, ROOT_MODULE_ID, describeToken } from "./types.js";
 export { ModuleRef } from "./module-ref.js";
 export { mixin } from "./mixin.js";

package/dist/container/types.d.ts

@@ -117,6 +117,29 @@ export type Diagnostics = 'silent' | 'log' | 'throw';
 export interface ContainerOptions {
     diagnostics?: Diagnostics;
 }
+/**
+ * Human-readable token label — class name, `InjectionToken(desc)`, symbol
+ * string, or String() fallback. Public so introspection tooling (module
+ * graphs, entrypoint listings) renders tokens the same way vela's own errors
+ * do.
+ */
+export declare function describeToken(token: Token): string;
+/**
+ * One module instance in the loaded graph, serializable (strings only) —
+ * what `Container.getModuleDescriptions()` returns for introspection tooling
+ * (`vela module graph`). Reads registration state only; never constructs.
+ */
+export interface ModuleDescription {
+    moduleId: string;
+    /** moduleIds this instance imports. */
+    imports: string[];
+    isGlobal: boolean;
+    lazy: boolean;
+    /** Token labels registered in this instance's bucket (registration order). */
+    providers: string[];
+    /** Token labels this instance exports. */
+    exports: string[];
+}
 export declare class ModuleVisibilityError extends Error {
     readonly moduleId: string;
     readonly token: Token;

package/dist/container/types.js

@@ -18,7 +18,12 @@ export class ForwardRef {
 export function forwardRef(factory) {
     return new ForwardRef(factory);
 }
-function describeToken(token) {
+/**
+ * Human-readable token label — class name, `InjectionToken(desc)`, symbol
+ * string, or String() fallback. Public so introspection tooling (module
+ * graphs, entrypoint listings) renders tokens the same way vela's own errors
+ * do.
+ */ export function describeToken(token) {
     if (token instanceof InjectionToken) return token.toString();
     if (typeof token === 'function') return token.name;
     if (typeof token === 'symbol') return token.toString();

package/dist/{storage → crypto}/signed-url.js

@@ -1,6 +1,11 @@
 // Signed-URL utilities using HMAC-SHA256 via the Web Crypto API (edge-safe;
 // no node:crypto). Verification uses crypto.subtle.verify for timing-safety.
 // Pattern: https://developers.cloudflare.com/workers/examples/signing-requests/
+//
+// This is the canonical home for the util. `@velajs/vela/storage` re-exports it
+// (see src/storage/index.ts) so the storage subpath API is unchanged, while
+// core (the URL generator + signed-URL guard) imports it here directly — core
+// never reaches into a published subpath.
 async function importKey(secret) {
     return crypto.subtle.importKey('raw', new TextEncoder().encode(secret), {
         name: 'HMAC',

package/dist/factory/bootstrap.js

@@ -4,6 +4,8 @@ import { ModuleRef } from "../container/module-ref.js";
 import { DiscoveryService } from "../discovery/discovery.service.js";
 import { REQUEST_CONTEXT } from "../http/request-context.js";
 import { RouteManager } from "../http/route.manager.js";
+import { UrlGeneratorService } from "../http/url/url-generator.service.js";
+import { SignedUrlGuard } from "../http/url/signed-url.guard.js";
 import { ModuleLoader } from "../module/module-loader.js";
 import { bindAppProviders } from "../pipeline/app-providers.js";
 import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
@@ -70,6 +72,14 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
         useValue: routeManager
     });
     container.markGlobalToken(RouteManager);
+    // Named-route URL generation + signed-URL verification are app-level
+    // singletons: injectable from any module, and (for the guard) instantiable by
+    // the pipeline when a route opts in via `@SignedUrl()`. Both read their secret
+    // lazily and never force controllers/lazy modules to materialize.
+    container.register(UrlGeneratorService);
+    container.markGlobalToken(UrlGeneratorService);
+    container.register(SignedUrlGuard);
+    container.markGlobalToken(SignedUrlGuard);
     const loader = new ModuleLoader(container, routeManager);
     // loader.load() also arms the deferred-init seam (LazyModuleManager) — kept
     // inside the loader so hand-rolled bootstrap paths that never call this

package/dist/http/decorators.d.ts

@@ -31,15 +31,24 @@ export declare function Controller(pathOrOptions?: string | ControllerOptions):
  */
 export declare function Version(version: number | number[]): MethodDecorator;
 export declare function getRouteVersion(target: Constructor, propertyKey: string | symbol): number | number[] | undefined;
-export declare const Get: (path?: string) => MethodDecorator;
-export declare const Post: (path?: string) => MethodDecorator;
-export declare const Put: (path?: string) => MethodDecorator;
-export declare const Patch: (path?: string) => MethodDecorator;
-export declare const Delete: (path?: string) => MethodDecorator;
-export declare const Options: (path?: string) => MethodDecorator;
-export declare const Head: (path?: string) => MethodDecorator;
-export declare const All: (path?: string) => MethodDecorator;
-export declare const Sse: (path?: string) => MethodDecorator;
+/** Per-route options for the HTTP method decorators (`@Get`, `@Post`, …). */
+export interface RouteOptions {
+    /**
+     * A stable, human-readable name for this route. Enables URL generation
+     * (`UrlGeneratorService.urlFor(name, …)`), surfaces on `app.describeRoutes()`,
+     * and — when set — becomes the OpenAPI `operationId`.
+     */
+    name?: string;
+}
+export declare const Get: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Post: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Put: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Patch: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Delete: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Options: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Head: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const All: (path?: string, options?: RouteOptions) => MethodDecorator;
+export declare const Sse: (path?: string, options?: RouteOptions) => MethodDecorator;
 export declare const Param: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;
 export declare const Query: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;
 export declare const Body: (nameOrPipe?: string | PipeType, ...pipes: PipeType[]) => ParameterDecorator;

package/dist/http/decorators.js

@@ -57,7 +57,7 @@ export function getRouteVersion(target, propertyKey) {
     return MetadataRegistry.getRouteVersion(target, propertyKey);
 }
 function createMethodDecorator(method) {
-    return (path = '')=>{
+    return (path = '', options)=>{
         return (target, propertyKey, _descriptor)=>{
             const ctor = target.constructor;
             const normalizedPath = normalizePath(path);
@@ -68,6 +68,9 @@ function createMethodDecorator(method) {
                 handlerName: propertyKey,
                 ...version !== undefined ? {
                     version
+                } : {},
+                ...options?.name !== undefined ? {
+                    name: options.name
                 } : {}
             });
         };

package/dist/http/index.d.ts

@@ -3,6 +3,10 @@ export type { RouteManagerOptions } from './route.manager';
 export { MiddlewareBuilder } from '../module/middleware';
 export type { MiddlewareConsumer, MiddlewareConfigProxy, RouteInfo, NestModule, MiddlewareRouteDefinition } from '../module/middleware';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators, isController, } from './decorators';
+export type { RouteOptions } from './decorators';
 export { createLazyParamDecorator } from './lazy-param.decorator';
+export { UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET, } from './url/index';
+export type { UrlForOptions, SignedUrlGenerateOptions } from './url/index';
+export type { VelaRouteMap, RouteName, RouteParams } from './route-map';
 export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext, } from './ambient';
 export type { RouteMetadata, ControllerMetadata, ControllerOptions, ParamMetadata, ControllerRegistration, } from './types';

package/dist/http/index.js

@@ -2,4 +2,6 @@ export { RouteManager } from "./route.manager.js";
 export { MiddlewareBuilder } from "../module/middleware.js";
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators, isController } from "./decorators.js";
 export { createLazyParamDecorator } from "./lazy-param.decorator.js";
+// Named-route URL generation + signed URLs
+export { UrlGeneratorService, SignedUrlGuard, SignedUrl, URL_SIGNING_SECRET } from "./url/index.js";
 export { enableAmbientContainer, getCurrentContainer, getCurrentRequestContext } from "./ambient.js";

package/dist/http/route-map.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Augmentable map of route name → its path params. Users opt in to type-safe
+ * URL generation by augmenting this interface — no build step, no codegen:
+ *
+ * ```ts
+ * declare module '@velajs/vela' {
+ *   interface VelaRouteMap {
+ *     'users.index': Record<string, never>;
+ *     'users.show': { id: string };
+ *   }
+ * }
+ * ```
+ *
+ * Until augmented it stays empty, so `RouteName` falls back to `string` and
+ * `RouteParams<N>` to a loose `Record<string, string> | undefined` — untyped
+ * callers keep working unchanged.
+ */
+export interface VelaRouteMap {
+}
+/**
+ * Every valid route name. Falls back to `string` when `VelaRouteMap` has not
+ * been augmented, so `urlFor`/`signedUrl` accept any name in an untyped app.
+ */
+export type RouteName = keyof VelaRouteMap extends never ? string : Extract<keyof VelaRouteMap, string>;
+/**
+ * The params object required to build a named route's URL. When `VelaRouteMap`
+ * is augmented, resolves to the declared params shape for `N`; otherwise a
+ * loose `Record<string, string> | undefined`.
+ */
+export type RouteParams<N extends RouteName> = N extends keyof VelaRouteMap ? VelaRouteMap[N] : Record<string, string> | undefined;

package/dist/http/route-map.js

@@ -0,0 +1,27 @@
+// Zero-codegen, type-safe route names — mirrors the augmentation pattern from
+// stratal `packages/core/src/router/route-map.ts` (MIT © Temitayo Fadojutimi).
+// Adapted for vela: `VelaRouteMap` maps a route name directly to its params
+// object (stratal wraps params in `{ params: … }`; vela keeps it flat to match
+// the `urlFor(name, params)` call shape).
+/**
+ * Augmentable map of route name → its path params. Users opt in to type-safe
+ * URL generation by augmenting this interface — no build step, no codegen:
+ *
+ * ```ts
+ * declare module '@velajs/vela' {
+ *   interface VelaRouteMap {
+ *     'users.index': Record<string, never>;
+ *     'users.show': { id: string };
+ *   }
+ * }
+ * ```
+ *
+ * Until augmented it stays empty, so `RouteName` falls back to `string` and
+ * `RouteParams<N>` to a loose `Record<string, string> | undefined` — untyped
+ * callers keep working unchanged.
+ */ // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentable interface, intentionally empty until a consumer declares routes
+/**
+ * The params object required to build a named route's URL. When `VelaRouteMap`
+ * is augmented, resolves to the declared params shape for `N`; otherwise a
+ * loose `Record<string, string> | undefined`.
+ */ export { };

package/dist/http/route.manager.d.ts

@@ -5,6 +5,25 @@ import type { MiddlewareRouteDefinition } from '../module/middleware';
 import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from '../pipeline/types';
 import type { FilterType, GuardType, InterceptorType, MiddlewareType, PipeType } from '../registry/types';
 import type { ControllerRegistration } from './types';
+/**
+ * One explicit controller route as the framework registered it — recorded by
+ * `build()` with the SAME composed path handed to Hono (global prefix +
+ * version segment + controller prefix + route path), so introspection tooling
+ * (`vela route list`) never re-derives composition. Contributed routes
+ * (`RouteContributor`, e.g. `@velajs/crud`) mount directly on the Hono app
+ * and are not described here — diff `app.getHonoApp().routes` for those.
+ */
+export interface RouteDescription {
+    /** As declared on the handler — `@Head()` reports HEAD (Hono serves it under GET). */
+    method: string;
+    /** Fully composed path exactly as registered. */
+    path: string;
+    controller: string;
+    handler: string;
+    version?: number;
+    /** Route name (`@Get(path, { name })`) — the URL-generation / `operationId` key. */
+    name?: string;
+}
 export interface RouteManagerOptions {
     getClientIp?: (c: Context) => string | null;
     middleware?: MiddlewareHandler[];
@@ -27,6 +46,7 @@ export declare class RouteManager {
     private globalFilters;
     private globalPrefix;
     private consumerMiddlewareDefinitions;
+    private routeDescriptions;
     private readonly handlerExecutor;
     private readonly ambientContainer;
     constructor(container: Container, options?: RouteManagerOptions);
@@ -59,6 +79,10 @@ export declare class RouteManager {
     private wrapMiddlewareWithFilters;
     private mapMiddlewareError;
     registerController(controller: Type): this;
+    /** The explicit controller routes recorded by the last `build()`. */
+    getRouteDescriptions(): RouteDescription[];
+    /** The global prefix in effect (set at bootstrap; '' when none). */
+    getGlobalPrefix(): string;
     build(): Promise<Hono>;
     private registerRoute;
     private buildVersionedPaths;

package/dist/http/route.manager.js

@@ -92,6 +92,7 @@ export class RouteManager {
     globalFilters = [];
     globalPrefix = '';
     consumerMiddlewareDefinitions = [];
+    routeDescriptions = [];
     handlerExecutor;
     ambientContainer;
     constructor(container, options = {}){
@@ -273,8 +274,17 @@ export class RouteManager {
         });
         return this;
     }
+    /** The explicit controller routes recorded by the last `build()`. */ getRouteDescriptions() {
+        return [
+            ...this.routeDescriptions
+        ];
+    }
+    /** The global prefix in effect (set at bootstrap; '' when none). */ getGlobalPrefix() {
+        return this.globalPrefix;
+    }
     async build() {
         const app = new Hono();
+        this.routeDescriptions = [];
         // Outermost: dispose the per-request child container once the request is
         // fully done. Fast-paths out when the child has no request-scoped
         // disposables (the common case → zero overhead / no behavior change).
@@ -353,11 +363,18 @@ export class RouteManager {
                 for (const route of routes){
                     const effectiveVersion = route.version ?? metadata.version;
                     const versionedPaths = this.buildVersionedPaths(this.globalPrefix, metadata.prefix, route.path, effectiveVersion);
+                    // Parallel to versionedPaths: buildVersionedPaths maps versions to
+                    // paths 1:1 in order, so index i of both arrays belongs together.
+                    const versionsForPaths = effectiveVersion === undefined ? [
+                        undefined
+                    ] : Array.isArray(effectiveVersion) ? effectiveVersion : [
+                        effectiveVersion
+                    ];
                     // Scoped (controller/handler) middleware only — global middleware is
                     // applied once by this manager's own global pass, never re-read here.
                     const middlewareItems = ComponentManager.getScopedComponents('middleware', controller, route.handlerName);
                     const handler = this.handlerExecutor.create(route, controller, allParamMetadata);
-                    for (const fullPath of versionedPaths){
+                    for (const [pathIndex, fullPath] of versionedPaths.entries()){
                         for (const middlewareItem of middlewareItems){
                             app.use(fullPath, this.wrapMiddlewareWithFilters((c, next)=>{
                                 const requestContainer = this.getRequestContainer(c);
@@ -366,6 +383,16 @@ export class RouteManager {
                             }));
                         }
                         this.registerRoute(app, route.method, fullPath, handler);
+                        this.routeDescriptions.push({
+                            method: String(route.method),
+                            path: fullPath || '/',
+                            controller: controller.name,
+                            handler: String(route.handlerName),
+                            version: versionsForPaths[pathIndex],
+                            ...route.name !== undefined ? {
+                                name: route.name
+                            } : {}
+                        });
                     }
                 }
             }

package/dist/http/types.d.ts

@@ -6,6 +6,8 @@ export interface RouteMetadata {
     path: string;
     handlerName: string | symbol;
     version?: number | number[];
+    /** Route name for URL generation / OpenAPI operationId (`@Get(path, { name })`). */
+    name?: string;
 }
 export interface ControllerOptions {
     path?: string;

package/dist/http/url/index.d.ts

@@ -0,0 +1,4 @@
+export { UrlGeneratorService } from './url-generator.service';
+export type { UrlForOptions, SignedUrlGenerateOptions } from './url-generator.service';
+export { SignedUrlGuard, SignedUrl } from './signed-url.guard';
+export { URL_SIGNING_SECRET } from './signing-secret';

package/dist/http/url/index.js

@@ -0,0 +1,3 @@
+export { UrlGeneratorService } from "./url-generator.service.js";
+export { SignedUrlGuard, SignedUrl } from "./signed-url.guard.js";
+export { URL_SIGNING_SECRET } from "./signing-secret.js";

package/dist/http/url/signed-url.guard.d.ts

@@ -0,0 +1,27 @@
+import { applyDecorators } from '../decorators';
+import type { CanActivate, ExecutionContext } from '../../pipeline/types';
+/**
+ * Verifies the HMAC signature (and `expires`) of the incoming request URL,
+ * using the same secret source as {@link UrlGeneratorService.signedUrl}: the
+ * {@link URL_SIGNING_SECRET} token, else `CONFIG_ENV`. Throws
+ * `ForbiddenException` (403) when the signature is missing, tampered, or
+ * expired. Registered app-wide by `bootstrap`; apply it per-route with
+ * {@link SignedUrl}.
+ */
+export declare class SignedUrlGuard implements CanActivate {
+    private readonly secretToken?;
+    private readonly env;
+    constructor(secretToken?: string | undefined, env?: Record<string, unknown>);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+/**
+ * Guards a route with {@link SignedUrlGuard} — the request must carry a valid,
+ * unexpired HMAC signature (produced by `UrlGeneratorService.signedUrl`).
+ *
+ * ```ts
+ * @Get('download', { name: 'file.download' })
+ * @SignedUrl()
+ * download() { ... }
+ * ```
+ */
+export declare function SignedUrl(): ReturnType<typeof applyDecorators>;

package/dist/http/url/signed-url.guard.js

@@ -0,0 +1,62 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Injectable, Inject, Optional } from "../../container/decorators.js";
+import { CONFIG_ENV } from "../../config/config.tokens.js";
+import { verifySignedUrl } from "../../crypto/signed-url.js";
+import { ForbiddenException } from "../../errors/http-exception.js";
+import { applyDecorators } from "../decorators.js";
+import { UseGuards } from "../../pipeline/decorators.js";
+import { URL_SIGNING_SECRET, resolveSigningSecret } from "./signing-secret.js";
+export class SignedUrlGuard {
+    secretToken;
+    env;
+    constructor(secretToken, env = {}){
+        this.secretToken = secretToken;
+        this.env = env;
+    }
+    async canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        const secret = resolveSigningSecret(undefined, this.secretToken, this.env);
+        const valid = await verifySignedUrl(request.url, secret);
+        if (!valid) {
+            throw new ForbiddenException('Invalid or expired signed URL');
+        }
+        return true;
+    }
+}
+SignedUrlGuard = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Optional()),
+    _ts_param(0, Inject(URL_SIGNING_SECRET)),
+    _ts_param(1, Optional()),
+    _ts_param(1, Inject(CONFIG_ENV)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        String,
+        typeof Record === "undefined" ? Object : Record
+    ])
+], SignedUrlGuard);
+/**
+ * Guards a route with {@link SignedUrlGuard} — the request must carry a valid,
+ * unexpired HMAC signature (produced by `UrlGeneratorService.signedUrl`).
+ *
+ * ```ts
+ * @Get('download', { name: 'file.download' })
+ * @SignedUrl()
+ * download() { ... }
+ * ```
+ */ export function SignedUrl() {
+    return applyDecorators(UseGuards(SignedUrlGuard));
+}

package/dist/http/url/signing-secret.d.ts

@@ -0,0 +1,20 @@
+import { InjectionToken } from '../../container/types';
+/**
+ * Optional DI token holding the HMAC secret used to sign / verify URLs. Provide
+ * it globally (e.g. from a platform adapter or a `@Global` module) so both
+ * {@link UrlGeneratorService} and the signed-URL guard can read it:
+ *
+ * ```ts
+ * { provide: URL_SIGNING_SECRET, useValue: env.URL_SIGNING_SECRET }
+ * ```
+ */
+export declare const URL_SIGNING_SECRET: InjectionToken<string>;
+/** Key read from `CONFIG_ENV` when no explicit secret / token is available. */
+export declare const URL_SIGNING_SECRET_ENV_KEY = "URL_SIGNING_SECRET";
+/**
+ * Resolve the signing secret from, in order: an explicit argument, the
+ * {@link URL_SIGNING_SECRET} token, then `CONFIG_ENV[URL_SIGNING_SECRET]`.
+ * Throws a descriptive error when none is available — signing must never fall
+ * back to an empty/implicit key.
+ */
+export declare function resolveSigningSecret(explicit: string | undefined, token: string | undefined, env: Record<string, unknown> | undefined): string;

package/dist/http/url/signing-secret.js

@@ -0,0 +1,24 @@
+import { InjectionToken } from "../../container/types.js";
+/**
+ * Optional DI token holding the HMAC secret used to sign / verify URLs. Provide
+ * it globally (e.g. from a platform adapter or a `@Global` module) so both
+ * {@link UrlGeneratorService} and the signed-URL guard can read it:
+ *
+ * ```ts
+ * { provide: URL_SIGNING_SECRET, useValue: env.URL_SIGNING_SECRET }
+ * ```
+ */ export const URL_SIGNING_SECRET = new InjectionToken('URL_SIGNING_SECRET');
+/** Key read from `CONFIG_ENV` when no explicit secret / token is available. */ export const URL_SIGNING_SECRET_ENV_KEY = 'URL_SIGNING_SECRET';
+/**
+ * Resolve the signing secret from, in order: an explicit argument, the
+ * {@link URL_SIGNING_SECRET} token, then `CONFIG_ENV[URL_SIGNING_SECRET]`.
+ * Throws a descriptive error when none is available — signing must never fall
+ * back to an empty/implicit key.
+ */ export function resolveSigningSecret(explicit, token, env) {
+    const fromEnv = env?.[URL_SIGNING_SECRET_ENV_KEY];
+    const secret = explicit ?? token ?? (typeof fromEnv === 'string' ? fromEnv : undefined);
+    if (!secret) {
+        throw new Error('No URL signing secret is available. Pass one explicitly, register a ' + '`URL_SIGNING_SECRET` provider, or set `URL_SIGNING_SECRET` in `CONFIG_ENV`.');
+    }
+    return secret;
+}