@velajs/cloudflare 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.6.0 (2026-07-01)
+
+### Added
+
+- **Multi-disk `StorageModule` over R2** (`StorageService.put/get/delete/exists/url`, per-disk templated roots, bucket-by-name via `EnvService`, `R2StorageDriver`) + a signature-gated `StorageController` presign-proxy.
+- **`KVCacheStore`** implementing vela's `AsyncCacheStore` — pair with `TieredCacheStore` for a memory→KV cache.
+- WebSocket transport for vela's WebSocket gateways (Durable Object backed).
+
+### Fixed
+
+- **Multiple same-type bindings** (e.g. two `KVModule.forRoot` with different bindings) now all initialize — `collectBindingRefs` enumerates every binding ref across module buckets instead of resolving each token once.
+
 ## 0.2.0 (2026-04-28)
 
 ### Breaking changes

package/README.md

@@ -34,7 +34,7 @@ class HyperdriveService { readonly binding: Hyperdrive; }
 
 ```ts
 import { Controller, Get, Module, Injectable, Param } from '@velajs/vela';
-import { CloudflareFactory, KVModule, KVService, D1Module, D1Service } from '@velajs/cloudflare';
+import { createCloudflareApp, KVModule, KVService, D1Module, D1Service } from '@velajs/cloudflare';
 
 @Injectable()
 class UserService {
@@ -73,7 +73,7 @@ class UserController {
 })
 class AppModule {}
 
-export default await CloudflareFactory.create(AppModule);
+export default await createCloudflareApp(AppModule);
 ```
 
 The `binding` string matches the binding name in your `wrangler.toml`:
@@ -327,14 +327,14 @@ class EmailWorker {
 }
 ```
 
-## CloudflareFactory
+## createCloudflareApp
 
-Use `CloudflareFactory.create()` instead of `VelaFactory.create()` for Cloudflare apps. It sets up a one-time middleware that captures `c.env` on the first request and initializes all binding modules.
+Use `createCloudflareApp()` instead of `VelaFactory.create()` for Cloudflare apps. It sets up a one-time middleware that captures `c.env` on the first request and initializes all binding modules.
 
 ```ts
-import { CloudflareFactory } from '@velajs/cloudflare';
+import { createCloudflareApp } from '@velajs/cloudflare';
 
-const app = await CloudflareFactory.create(AppModule);
+const app = await createCloudflareApp(AppModule);
 export default app;
 ```
 
@@ -343,7 +343,7 @@ export default app;
 To use scheduled triggers and queue consumers, export the handlers explicitly:
 
 ```ts
-const app = await CloudflareFactory.create(AppModule);
+const app = await createCloudflareApp(AppModule);
 
 export default {
   fetch: app.fetch,
@@ -371,7 +371,7 @@ const rawHD = hdService.binding;       // Hyperdrive
 
 Cloudflare Workers only provide bindings (`env.DB`, `env.MY_KV`, etc.) at request time via the `env` parameter. They are stable across requests within an isolate.
 
-`CloudflareFactory` handles this by:
+`createCloudflareApp` handles this by:
 
 1. Each `XModule.forRoot()` creates a `BindingRef` (mutable holder) and registers it in the DI container
 2. Services are constructed at boot time with the `BindingRef` — no binding access yet

package/dist/cloudflare-application.d.ts

@@ -1,5 +1,6 @@
 import type { Hono } from 'hono';
 import { type VelaApplication } from '@velajs/vela';
+import { type WsGatewayRoute } from './websocket/websocket-routing';
 import type { CloudflareEnv } from './types';
 /**
  * Options accepted by {@link CloudflareApplication.mountOpenApi}.
@@ -42,6 +43,7 @@ export declare class CloudflareApplication {
     private app;
     private scheduledHandlers;
     private queueConsumers;
+    private wsGatewayRoutes;
     constructor(app: VelaApplication);
     get fetch(): Hono['fetch'];
     getHonoApp(): Hono;
@@ -81,6 +83,8 @@ export declare class CloudflareApplication {
     mountOpenApi(options: MountOpenApiOptions): this;
     /** @internal — scans instances for @Scheduled, @Cron, and @QueueConsumer metadata */
     scanInstances(instances: unknown[]): void;
+    /** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */
+    getWsGatewayRoutes(): WsGatewayRoute[];
     /**
      * Handle Cloudflare scheduled (cron) events.
      * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()` handlers.

package/dist/cloudflare-application.js

@@ -1,6 +1,7 @@
 import { CRON_METADATA, getMetadata } from "@velajs/vela";
 import { getScheduledMetadata } from "./decorators/scheduled.js";
 import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
+import { collectWsGatewayRoutes } from "./websocket/websocket-routing.js";
 function invoke(instance, methodName, args) {
     const method = instance[methodName];
     if (typeof method !== 'function') {
@@ -40,6 +41,7 @@ function invoke(instance, methodName, args) {
     app;
     scheduledHandlers = [];
     queueConsumers = [];
+    wsGatewayRoutes = [];
     constructor(app){
         this.app = app;
     }
@@ -112,8 +114,12 @@ function invoke(instance, methodName, args) {
                     queueName: meta.queueName
                 });
             }
+            this.wsGatewayRoutes.push(...collectWsGatewayRoutes(instance));
         }
     }
+    /** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */ getWsGatewayRoutes() {
+        return this.wsGatewayRoutes;
+    }
     /**
    * Handle Cloudflare scheduled (cron) events.
    * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()` handlers.

package/dist/cloudflare-factory.js

@@ -2,19 +2,18 @@ import { VelaFactory } from "@velajs/vela";
 import { BindingRef } from "./binding-ref.js";
 import { CloudflareApplication } from "./cloudflare-application.js";
 import { EnvRef } from "./env-ref.js";
+import { registerWebSocketRoutes } from "./websocket/websocket-routing.js";
 // Walks every provider registered in the container and pulls out the
 // BindingRef instances. Replaces the old module-level `bindingsRegistry`
 // global so two CloudflareApplication instances in one process don't
 // share state.
 function collectBindingRefs(container) {
+    // Enumerate per-instance useValue providers across ALL module buckets. Two
+    // same-type binding modules (e.g. KVModule.forRoot for CACHE and SESSIONS)
+    // share one token but live in distinct buckets — resolving the token would
+    // return only the first, leaving the others uninitialized.
     const refs = [];
-    for (const token of container.getTokens()){
-        let value;
-        try {
-            value = container.resolve(token);
-        } catch  {
-            continue;
-        }
+    for (const value of container.getUseValues()){
         if (value instanceof BindingRef) refs.push(value);
     }
     return refs;
@@ -76,5 +75,8 @@ function collectBindingRefs(container) {
     refs = collectBindingRefs(velaApp.getContainer());
     const cfApp = new CloudflareApplication(velaApp);
     cfApp.scanInstances(velaApp.getInstances());
+    // Register WebSocket upgrade routes for any @WebSocketGateway({ path, binding }).
+    // Each forwards the upgrade to the room's Durable Object (which owns the socket).
+    registerWebSocketRoutes(cfApp.getHonoApp(), cfApp.getWsGatewayRoutes());
     return cfApp;
 }

package/dist/index.d.ts

@@ -11,7 +11,10 @@ export { AIModule } from './modules/ai.module';
 export { VectorizeModule } from './modules/vectorize.module';
 export { HyperdriveModule } from './modules/hyperdrive.module';
 export { EnvModule } from './modules/env.module';
+export { StorageModule, StorageService, StorageManagerService, StorageController, R2StorageDriver, STORAGE_OPTIONS, } from './storage/index';
+export type { StorageModuleOptions, DiskConfig, PresignedUrlConfig } from './storage/index';
 export { KVService } from './services/kv.service';
+export { KVCacheStore } from './services/kv-cache.store';
 export { D1Service } from './services/d1.service';
 export { R2Service } from './services/r2.service';
 export { QueueService } from './services/queue.service';
@@ -23,6 +26,10 @@ export { EnvService } from './services/env.service';
 export { Env } from './decorators/env';
 export { Scheduled } from './decorators/scheduled';
 export { QueueConsumer } from './decorators/queue-consumer';
+export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom, } from './websocket/index';
+export type { WsGatewayRoute } from './websocket/index';
+export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException, } from '@velajs/vela/websocket';
+export type { WsClient, WsServer, WsResponse, WsMessage, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from '@velajs/vela/websocket';
 export type { CloudflareEnv, ScheduledRegistration, QueueRegistration } from './types';
 export type { ScheduledMetadata } from './decorators/scheduled';
 export type { QueueConsumerMetadata } from './decorators/queue-consumer';

package/dist/index.js

@@ -11,8 +11,11 @@ export { AIModule } from "./modules/ai.module.js";
 export { VectorizeModule } from "./modules/vectorize.module.js";
 export { HyperdriveModule } from "./modules/hyperdrive.module.js";
 export { EnvModule } from "./modules/env.module.js";
+// Storage (multi-disk over R2 + presign proxy)
+export { StorageModule, StorageService, StorageManagerService, StorageController, R2StorageDriver, STORAGE_OPTIONS } from "./storage/index.js";
 // Services
 export { KVService } from "./services/kv.service.js";
+export { KVCacheStore } from "./services/kv-cache.store.js";
 export { D1Service } from "./services/d1.service.js";
 export { R2Service } from "./services/r2.service.js";
 export { QueueService } from "./services/queue.service.js";
@@ -25,3 +28,7 @@ export { EnvService } from "./services/env.service.js";
 export { Env } from "./decorators/env.js";
 export { Scheduled } from "./decorators/scheduled.js";
 export { QueueConsumer } from "./decorators/queue-consumer.js";
+// WebSocket (Durable Object transport for the Vela WebSocketModule)
+export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom } from "./websocket/index.js";
+// Re-export the core gateway API so a Cloudflare app can import it from one place.
+export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException } from "@velajs/vela/websocket";

package/dist/modules/create-binding-module.js

@@ -1,7 +1,8 @@
+import { defineConfigurableModule } from "@velajs/vela";
 import { BindingRef } from "../binding-ref.js";
 // Single factory for every Cloudflare binding module (KV, D1, R2, ...).
-// Each binding module is just a bag of (token, service); this generates
-// the canonical forRoot() shape for them.
+// Each binding module is just a bag of (token, service); this generates the
+// canonical forRoot() shape via vela's `defineConfigurableModule` engine.
 //
 // Identity model (post vela audit #2):
 //   - One real module class is declared per binding TYPE (KV, D1, R2, ...).
@@ -22,24 +23,20 @@ export function createBindingModule(opts) {
         [className]: class {
         }
     }[className];
-    return {
-        forRoot ({ binding }) {
-            const ref = new BindingRef(binding);
-            return {
-                module: moduleClass,
-                key: binding,
-                providers: [
-                    {
-                        provide: opts.bindingRefToken,
-                        useValue: ref
-                    },
-                    opts.serviceClass
-                ],
-                exports: [
-                    opts.serviceClass,
-                    opts.bindingRefToken
-                ]
-            };
-        }
-    };
+    return defineConfigurableModule({
+        module: moduleClass,
+        methodName: 'forRoot',
+        keyFrom: ({ binding })=>binding,
+        providers: ({ binding })=>[
+                {
+                    provide: opts.bindingRefToken,
+                    useValue: new BindingRef(binding)
+                },
+                opts.serviceClass
+            ],
+        exports: [
+            opts.serviceClass,
+            opts.bindingRefToken
+        ]
+    });
 }

package/dist/services/kv-cache.store.d.ts

@@ -0,0 +1,19 @@
+import { type AsyncCacheStore } from '@velajs/vela';
+import { KVService } from './kv.service';
+/**
+ * Cloudflare KV-backed {@link CacheStore}. Values are JSON-encoded. Intended as
+ * the slow tier under a `TieredCacheStore` (memory L1 → KV L2), but usable
+ * standalone as `CacheModule.forRootAsync({ inject: [KVService], useFactory: (kv) => ({ store: new KVCacheStore(kv) }) })`.
+ *
+ * Note: Cloudflare KV requires `expirationTtl >= 60s`, so sub-minute TTLs are
+ * clamped up. Keep short TTLs on the memory tier; use KV for longer-lived entries.
+ */
+export declare class KVCacheStore implements AsyncCacheStore {
+    private readonly kv;
+    constructor(kv: KVService);
+    private get ns();
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/services/kv-cache.store.js

@@ -0,0 +1,58 @@
+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 { Inject, Injectable } from "@velajs/vela";
+import { KVService } from "./kv.service.js";
+export class KVCacheStore {
+    kv;
+    constructor(kv){
+        this.kv = kv;
+    }
+    get ns() {
+        return this.kv.namespace;
+    }
+    async get(key) {
+        const value = await this.ns.get(key, 'json');
+        return value === null ? undefined : value;
+    }
+    async set(key, value, ttl) {
+        // KV enforces a 60s minimum expirationTtl; clamp up. Omit for no-TTL.
+        const options = ttl !== undefined ? {
+            expirationTtl: Math.max(60, Math.floor(ttl))
+        } : undefined;
+        await this.ns.put(key, JSON.stringify(value), options);
+    }
+    async del(key) {
+        await this.ns.delete(key);
+    }
+    async clear() {
+        // KV has no native clear — page through and delete. Best-effort.
+        let cursor;
+        do {
+            const list = await this.ns.list(cursor ? {
+                cursor
+            } : undefined);
+            await Promise.all(list.keys.map((entry)=>this.ns.delete(entry.name)));
+            cursor = list.list_complete ? undefined : list.cursor;
+        }while (cursor)
+    }
+}
+KVCacheStore = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(KVService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof KVService === "undefined" ? Object : KVService
+    ])
+], KVCacheStore);

package/dist/storage/index.d.ts

@@ -0,0 +1,7 @@
+export { StorageModule } from './storage.module';
+export { StorageService } from './storage.service';
+export { StorageManagerService } from './storage-manager.service';
+export { StorageController } from './storage.controller';
+export { R2StorageDriver } from './r2-storage.driver';
+export { STORAGE_OPTIONS } from './storage.tokens';
+export type { StorageModuleOptions, DiskConfig, PresignedUrlConfig } from './storage.types';

package/dist/storage/index.js

@@ -0,0 +1,6 @@
+export { StorageModule } from "./storage.module.js";
+export { StorageService } from "./storage.service.js";
+export { StorageManagerService } from "./storage-manager.service.js";
+export { StorageController } from "./storage.controller.js";
+export { R2StorageDriver } from "./r2-storage.driver.js";
+export { STORAGE_OPTIONS } from "./storage.tokens.js";

package/dist/storage/r2-storage.driver.d.ts

@@ -0,0 +1,19 @@
+import { type DownloadResult, type PresignedUrlResult, type PresignMethod, type StorageBody, type StorageDriver, type UploadOptions, type UploadResult } from '@velajs/vela/storage';
+/** Base path of the StorageController presign-proxy route. */
+export declare const STORAGE_ROUTE_BASE = "/storage";
+export interface R2StorageDriverConfig {
+    disk: string;
+    bucket: R2Bucket;
+    /** HMAC secret for presigned URLs (typically env.APP_SECRET). */
+    secret?: string;
+}
+/** {@link StorageDriver} over a Cloudflare R2 bucket. */
+export declare class R2StorageDriver implements StorageDriver {
+    private readonly config;
+    constructor(config: R2StorageDriverConfig);
+    upload(body: StorageBody, path: string, options: UploadOptions): Promise<UploadResult>;
+    download(path: string): Promise<DownloadResult>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getPresignedUrl(path: string, method: PresignMethod, expiresIn: number): Promise<PresignedUrlResult>;
+}

package/dist/storage/r2-storage.driver.js

@@ -0,0 +1,61 @@
+import { signUrl } from "@velajs/vela/storage";
+/** Base path of the StorageController presign-proxy route. */ export const STORAGE_ROUTE_BASE = '/storage';
+/** {@link StorageDriver} over a Cloudflare R2 bucket. */ export class R2StorageDriver {
+    config;
+    constructor(config){
+        this.config = config;
+    }
+    async upload(body, path, options) {
+        await this.config.bucket.put(path, body, {
+            httpMetadata: options.mimeType ? {
+                contentType: options.mimeType
+            } : undefined,
+            customMetadata: options.metadata
+        });
+        return {
+            path,
+            disk: this.config.disk,
+            size: options.size,
+            mimeType: options.mimeType ?? 'application/octet-stream',
+            uploadedAt: new Date()
+        };
+    }
+    async download(path) {
+        const obj = await this.config.bucket.get(path);
+        if (!obj) throw new Error(`Storage object not found at "${path}".`);
+        return {
+            toStream: ()=>obj.body,
+            toArrayBuffer: ()=>obj.arrayBuffer(),
+            toText: ()=>obj.text(),
+            contentType: obj.httpMetadata?.contentType ?? 'application/octet-stream',
+            size: obj.size,
+            metadata: obj.customMetadata
+        };
+    }
+    async delete(path) {
+        await this.config.bucket.delete(path);
+    }
+    async exists(path) {
+        return await this.config.bucket.head(path) !== null;
+    }
+    async getPresignedUrl(path, method, expiresIn) {
+        if (!this.config.secret) {
+            throw new Error('A signing secret is required for presigned URLs (set APP_SECRET).');
+        }
+        // Defend the direct-driver path too: a non-finite/non-positive expiry would
+        // make signUrl omit `expires`, yielding a never-expiring URL.
+        if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+            throw new Error(`Invalid presigned URL expiry: ${expiresIn}s (must be a positive number).`);
+        }
+        const routePath = `${STORAGE_ROUTE_BASE}/${this.config.disk}/${path}`;
+        const url = await signUrl(`${routePath}?method=${method}`, this.config.secret, {
+            expiresIn
+        });
+        return {
+            url,
+            method,
+            expiresIn,
+            expiresAt: new Date(Date.now() + expiresIn * 1000)
+        };
+    }
+}

package/dist/storage/storage-manager.service.d.ts

@@ -0,0 +1,16 @@
+import { EnvService } from '../services/env.service';
+import { R2StorageDriver } from './r2-storage.driver';
+import type { DiskConfig, StorageModuleOptions } from './storage.types';
+/**
+ * Resolves R2 buckets by binding NAME (via {@link EnvService}) so multiple disks
+ * coexist without registering N R2Modules. Drivers are created per call — cheap,
+ * and avoids caching a per-request env value on this singleton.
+ */
+export declare class StorageManagerService {
+    private readonly options;
+    private readonly env;
+    constructor(options: StorageModuleOptions, env: EnvService);
+    hasDisk(disk: string): boolean;
+    getDiskConfig(disk: string): DiskConfig;
+    getDriver(disk: string): R2StorageDriver;
+}

package/dist/storage/storage-manager.service.js

@@ -0,0 +1,56 @@
+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 { Inject, Injectable } from "@velajs/vela";
+import { EnvService } from "../services/env.service.js";
+import { R2StorageDriver } from "./r2-storage.driver.js";
+import { STORAGE_OPTIONS } from "./storage.tokens.js";
+export class StorageManagerService {
+    options;
+    env;
+    constructor(options, env){
+        this.options = options;
+        this.env = env;
+    }
+    hasDisk(disk) {
+        return this.options.disks.some((d)=>d.disk === disk);
+    }
+    getDiskConfig(disk) {
+        const config = this.options.disks.find((d)=>d.disk === disk);
+        if (!config) throw new Error(`Storage disk "${disk}" is not configured.`);
+        return config;
+    }
+    getDriver(disk) {
+        const config = this.getDiskConfig(disk);
+        const bucket = this.env.get(config.binding);
+        if (!bucket) {
+            throw new Error(`R2 binding "${config.binding}" for disk "${disk}" was not found in env.`);
+        }
+        return new R2StorageDriver({
+            disk,
+            bucket,
+            secret: this.env.get('APP_SECRET')
+        });
+    }
+}
+StorageManagerService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(STORAGE_OPTIONS)),
+    _ts_param(1, Inject(EnvService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof StorageModuleOptions === "undefined" ? Object : StorageModuleOptions,
+        typeof EnvService === "undefined" ? Object : EnvService
+    ])
+], StorageManagerService);

package/dist/storage/storage.controller.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from 'hono';
+import { EnvService } from '../services/env.service';
+import { StorageManagerService } from './storage-manager.service';
+/**
+ * Presign-proxy: serves objects for HMAC-signed URLs produced by
+ * `StorageService.url()`. R2 has no native presign, so a signed URL points here;
+ * this route verifies the signature (+expiry) before streaming the object.
+ * The wildcard is the FULL object path (root already applied at sign time), so
+ * it is passed straight to the driver.
+ */
+export declare class StorageController {
+    private readonly manager;
+    private readonly env;
+    constructor(manager: StorageManagerService, env: EnvService);
+    download(c: Context): Promise<Response>;
+}

package/dist/storage/storage.controller.js

@@ -0,0 +1,88 @@
+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 { Controller, Get, Inject, Req } from "@velajs/vela";
+import { verifySignedUrl } from "@velajs/vela/storage";
+import { EnvService } from "../services/env.service.js";
+import { StorageManagerService } from "./storage-manager.service.js";
+export class StorageController {
+    manager;
+    env;
+    constructor(manager, env){
+        this.manager = manager;
+        this.env = env;
+    }
+    async download(c) {
+        const secret = this.env.get('APP_SECRET');
+        if (!secret) return new Response('Storage signing is not configured', {
+            status: 500
+        });
+        const disk = c.req.param('disk');
+        if (!disk || !this.manager.hasDisk(disk)) return new Response('Unknown disk', {
+            status: 404
+        });
+        if (!await verifySignedUrl(c.req.url, secret)) {
+            return new Response('Invalid or expired URL', {
+                status: 403
+            });
+        }
+        // Enforce the signed `method` scope: this proxy only serves reads, so a URL
+        // scoped to PUT/DELETE/HEAD must NOT be honored as a GET (it would over-grant
+        // read access relative to the token's intended scope). The param is part of
+        // the signed payload, so it is trustworthy once the signature verifies.
+        const url = new URL(c.req.url);
+        if ((url.searchParams.get('method') ?? 'GET') !== 'GET') {
+            return new Response('URL is not scoped for reads', {
+                status: 403
+            });
+        }
+        // The object key is everything after `/storage/:disk/` (Hono doesn't expose
+        // the `*` wildcard via param()). The key already includes the disk root.
+        const { pathname } = url;
+        const prefix = `/storage/${disk}/`;
+        const idx = pathname.indexOf(prefix);
+        const fullPath = idx >= 0 ? decodeURIComponent(pathname.slice(idx + prefix.length)) : '';
+        try {
+            const result = await this.manager.getDriver(disk).download(fullPath);
+            return new Response(result.toStream(), {
+                headers: {
+                    'content-type': result.contentType
+                }
+            });
+        } catch  {
+            return new Response('Not found', {
+                status: 404
+            });
+        }
+    }
+}
+_ts_decorate([
+    Get('/:disk/*'),
+    _ts_param(0, Req()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Context === "undefined" ? Object : Context
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], StorageController.prototype, "download", null);
+StorageController = _ts_decorate([
+    Controller('storage'),
+    _ts_param(0, Inject(StorageManagerService)),
+    _ts_param(1, Inject(EnvService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof StorageManagerService === "undefined" ? Object : StorageManagerService,
+        typeof EnvService === "undefined" ? Object : EnvService
+    ])
+], StorageController);

package/dist/storage/storage.module.d.ts

@@ -0,0 +1,7 @@
+import type { StorageModuleOptions } from './storage.types';
+declare const ConfigurableModuleClass: import("@velajs/vela").ConfigurableModuleClassType<StorageModuleOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class StorageModule extends ConfigurableModuleClass {
+}
+export {};