@velajs/cloudflare 1.10.0 → 2.0.0

package/dist/index.js

@@ -1,39 +1,1023 @@
-// Factory & Application
-export { cloudflareAdapter, createCloudflareApp } from "./cloudflare-factory.js";
-export { CloudflareApplication } from "./cloudflare-application.js";
-// Modules
-export { KVModule } from "./modules/kv.module.js";
-export { D1Module } from "./modules/d1.module.js";
-export { R2Module } from "./modules/r2.module.js";
-export { QueueModule } from "./modules/queue.module.js";
-export { DurableObjectModule } from "./modules/durable-object.module.js";
-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";
-export { DurableObjectService } from "./services/durable-object.service.js";
-export { AIService } from "./services/ai.service.js";
-export { VectorizeService } from "./services/vectorize.service.js";
-export { HyperdriveService } from "./services/hyperdrive.service.js";
-export { EnvService } from "./services/env.service.js";
-// Feature-flag drivers (implement @velajs/feature-flags' FeatureFlagDriver contract)
-export { FlagshipFlagDriver, flagshipFlagDriver } from "./services/flagship-flag.driver.js";
-export { KvFlagDriver, kvFlagDriver } from "./services/kv-flag.driver.js";
-// Decorators
-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";
-// Live queries (Durable Object transport for @velajs/vela/live)
-export { DoCursorLog, durableObjectCursorLog, durableObjectLive, liveInvalidateToRoom } 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";
+import { C as roomToDurableId, _ as resolveCloudflareRoot, a as durableObjectLive, c as liveInvalidateToRoom, d as WsServerHolder, f as DoPitrUnavailableError, g as __decorate, h as readDoPitrBookmark, i as durableObjectCursorLog, m as isDoPitrUnavailable, n as isValidExpiry, p as armDoPitr, r as DoCursorLog, t as isCanonicalBoundedText, v as assertCloudflareEnvironment, x as durableObjectRoomName, y as registerCloudflareEnvironment } from "./nonce-validation-LE0vFk-7.js";
+import { getConnInfo } from "hono/cloudflare-workers";
+import { CRON_METADATA, ConfigurableModuleBuilder, Controller, Get, Inject, Injectable, InjectionToken, Module, PipelineRunner, Req, VelaFactory, buildEntrypointExecutionContext, createParamDecorator, defineMetadata, defineProvider, getMetadata, getTrustedRequestIdentity, registerEntrypointKind, runInEntrypointScope, shouldFilterCatch } from "@velajs/vela";
+import { ComponentManager } from "@velajs/vela/internal";
+import { ConnectedSocket, DEFAULT_WS_MAX_FRAME_BYTES, MessageBody, SubscribeMessage, WS_GATEWAY_METADATA, WS_SERVER, WebSocketGateway, WebSocketServer, WsDispatcher, WsException, assertBroadcastCommandFits, authenticateWebSocketUpgrade, resolveGatewayRoomId, resolveGatewayRoomParam, resolveMaxFrameBytes } from "@velajs/vela/websocket";
+import { STORAGE_SIGNED_URL_PURPOSE, joinStoragePath, signUrl, verifySignedUrl } from "@velajs/vela/storage";
+//#region src/websocket/websocket-routing.ts
+const MAX_IDENTITY_FIELD_BYTES = 2048;
+const encoder = new TextEncoder();
+function isIdentityField(value) {
+	return typeof value === "string" && value.length > 0 && !value.includes("\r") && !value.includes("\n") && encoder.encode(value).byteLength <= MAX_IDENTITY_FIELD_BYTES;
+}
+/** `null` means an identity was present but violated the transport contract. */
+function accessIdentity(c) {
+	const value = getTrustedRequestIdentity(c.req.raw);
+	if (!value) return void 0;
+	const { principal, tenantId, expiresAtMs } = value;
+	if (!isIdentityField(principal.issuer) || !isIdentityField(principal.subject) || !isIdentityField(tenantId) || typeof expiresAtMs !== "number" || !Number.isSafeInteger(expiresAtMs) || expiresAtMs <= 0) return null;
+	return {
+		principal,
+		tenantId,
+		expiresAtMs
+	};
+}
+/** `null` means two independently verified identities disagree. */
+function combineIdentities(requestIdentity, upgradeIdentity) {
+	if (!requestIdentity && !upgradeIdentity) return void 0;
+	if (!requestIdentity) return upgradeIdentity;
+	if (!upgradeIdentity) return requestIdentity;
+	if (requestIdentity.principal.issuer !== upgradeIdentity.principal.issuer || requestIdentity.principal.subject !== upgradeIdentity.principal.subject || requestIdentity.principal.principalType !== upgradeIdentity.principal.principalType || requestIdentity.tenantId !== upgradeIdentity.tenantId) return null;
+	return {
+		principal: { ...upgradeIdentity.principal },
+		tenantId: upgradeIdentity.tenantId,
+		expiresAtMs: Math.min(requestIdentity.expiresAtMs, upgradeIdentity.expiresAtMs)
+	};
+}
+/** Read `@WebSocketGateway({ path, binding })` off a resolved instance (CF-hosted gateways only). */
+function collectWsGatewayRoutes(instance) {
+	const options = getMetadata(WS_GATEWAY_METADATA, instance.constructor);
+	if (!options?.path || !options?.binding) return [];
+	resolveGatewayRoomParam(options);
+	resolveMaxFrameBytes(options);
+	return [{
+		path: options.path,
+		binding: options.binding,
+		options: { ...options }
+	}];
+}
+/**
+* Registers the upgrade routes on the Worker's Hono app. Each route validates
+* the `Upgrade` header, resolves the room's Durable Object, and forwards the raw
+* request — injecting spoof-safe `x-vela-*` headers the DO reads. The DO returns
+* the `101` with the client socket.
+*/
+function registerWebSocketRoutes(hono, routes) {
+	for (const route of routes) hono.get(route.path, async (c) => {
+		if (c.req.header("upgrade")?.toLowerCase() !== "websocket") return c.text("Expected WebSocket upgrade", 426);
+		const headers = new Headers(c.req.raw.headers);
+		headers.delete("x-vela-room");
+		headers.delete("x-vela-path");
+		headers.delete("x-vela-user");
+		headers.delete("x-vela-expires-at");
+		headers.delete("x-vela-expires-at-ms");
+		headers.delete("x-vela-issuer");
+		headers.delete("x-vela-subject");
+		headers.delete("x-vela-principal-type");
+		headers.delete("x-vela-tenant");
+		const sanitizedRequest = new Request(c.req.raw, { headers });
+		let roomId;
+		try {
+			roomId = resolveGatewayRoomId(route.options, (name) => c.req.param(name));
+		} catch {
+			return c.text("Invalid WebSocket room", 400);
+		}
+		const upgrade = await authenticateWebSocketUpgrade(route.options, sanitizedRequest, roomId);
+		if (upgrade === false) return c.text("WebSocket upgrade forbidden", 403);
+		const requestIdentity = accessIdentity(c);
+		if (requestIdentity === null) return c.text("Invalid WebSocket identity", 403);
+		const identity = combineIdentities(requestIdentity, upgrade.identity);
+		if (identity === null) return c.text("Conflicting WebSocket identities", 403);
+		if (identity && identity.expiresAtMs <= Date.now()) return c.text("WebSocket identity expired", 403);
+		const forwardHeaders = new Headers(upgrade.request.headers);
+		forwardHeaders.set("x-vela-room", roomId);
+		forwardHeaders.set("x-vela-path", route.path);
+		if (identity) {
+			forwardHeaders.set("x-vela-user", identity.principal.subject);
+			forwardHeaders.set("x-vela-issuer", identity.principal.issuer);
+			forwardHeaders.set("x-vela-subject", identity.principal.subject);
+			forwardHeaders.set("x-vela-principal-type", identity.principal.principalType);
+			forwardHeaders.set("x-vela-tenant", identity.tenantId);
+			forwardHeaders.set("x-vela-expires-at-ms", String(identity.expiresAtMs));
+		}
+		return forwardToRoom(c.env, route.binding, route.path, roomId, new Request(upgrade.request, { headers: forwardHeaders }));
+	});
+}
+/**
+* Gateway metadata contains a runtime binding name, so the native type is
+* erased. Validate only the operations consumed here and their observable
+* results; never assert that an arbitrary value implements a native namespace.
+*/
+async function forwardToRoom(env, binding, path, room, request) {
+	if (typeof env !== "object" || env === null) throw new Error("Worker environment is missing");
+	const namespace = Reflect.get(env, binding);
+	if (typeof namespace !== "object" || namespace === null) return new Response(`Durable Object binding '${binding}' is not configured`, { status: 500 });
+	const idFromName = Reflect.get(namespace, "idFromName");
+	const get = Reflect.get(namespace, "get");
+	if (typeof idFromName !== "function" || typeof get !== "function") throw new Error("Invalid Durable Object namespace");
+	const id = Reflect.apply(idFromName, namespace, [durableObjectRoomName(path, room)]);
+	const stub = Reflect.apply(get, namespace, [id]);
+	if (typeof stub !== "object" || stub === null) throw new Error("Invalid Durable Object stub");
+	const fetch = Reflect.get(stub, "fetch");
+	if (typeof fetch !== "function") throw new Error("Durable Object stub has no fetch operation");
+	const response = await Reflect.apply(fetch, stub, [request]);
+	if (!(response instanceof Response)) throw new Error("Durable Object returned an invalid response");
+	return response;
+}
+//#endregion
+//#region src/cloudflare-application.ts
+registerEntrypointKind({
+	kind: "cf:vela-cron",
+	metaKey: CRON_METADATA,
+	level: "method"
+});
+function invoke(instance, methodName, args) {
+	const method = Reflect.get(instance, methodName);
+	if (typeof method !== "function") throw new Error(`Method '${methodName}' is not a function on ${instance.constructor.name}`);
+	return Reflect.apply(method, instance, args);
+}
+function entrypointString(meta, property) {
+	if (typeof meta !== "object" || meta === null) throw new Error("Invalid entrypoint metadata.");
+	const value = Reflect.get(meta, property);
+	if (typeof value !== "string") throw new Error(`Invalid entrypoint metadata: ${property} must be a string.`);
+	return value;
+}
+/**
+* Wraps VelaApplication with Cloudflare-specific handlers:
+* - `fetch` — HTTP request handler (from Hono)
+* - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
+*                 AND vela's own `@Cron()` jobs)
+* - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
+* - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on
+*                    the underlying Hono app
+*
+* @example
+* ```ts
+* const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+* export default {
+*   fetch: app.fetch,
+*   scheduled: app.scheduled.bind(app),
+*   queue: app.queue.bind(app),
+* };
+* ```
+*
+* @example
+* ```ts
+* // Serve OpenAPI docs alongside your routes
+* const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+* const document = createOpenApiDocument(AppModule);
+* app.mountOpenApi({ document, ui: 'scalar' });
+* // GET /openapi.json -> JSON document
+* // GET /scalar       -> Scalar UI (loads from CDN)
+* ```
+*/
+var CloudflareApplication = class {
+	app;
+	env;
+	wsGatewayRoutes = [];
+	constructor(app, env) {
+		this.app = app;
+		this.env = env;
+		this.get = app.get.bind(app);
+	}
+	fetch = async (request, env, ctx) => {
+		assertCloudflareEnvironment(this.env, env);
+		return this.app.fetch(request, env, ctx);
+	};
+	getHonoApp() {
+		return this.app.getHonoApp();
+	}
+	/**
+	* Resolve a provider from the application's DI container (delegates to
+	* `VelaApplication.get`). Handy for grabbing a service — e.g. an auth service —
+	* to use inside `createCloudflareApp({ middleware: env => [...] })` request middleware,
+	* which runs outside the DI request pipeline.
+	*
+	* @example
+	* ```ts
+	* const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+	* const auth = app.get(BetterAuthService);
+	* ```
+	*/
+	get;
+	get entrypoints() {
+		return this.app.entrypoints;
+	}
+	/**
+	* Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the
+	* underlying Hono app. Delegates verbatim to `VelaApplication.mountOpenApi`,
+	* so the JSON endpoint defaults to `/openapi.json` and the Scalar UI (when
+	* opted in) defaults to `/scalar`. Edge-safe — the UI HTML loads Scalar from
+	* a CDN at runtime, nothing is bundled server-side.
+	*
+	* @example
+	* ```ts
+	* import { createOpenApiDocument } from '@velajs/vela';
+	*
+	* const app = await createCloudflareApp(AppModule, { env, envToken: ENV });
+	* const document = createOpenApiDocument(AppModule, {
+	*   info: { title: 'My API', version: '1.0.0' },
+	* });
+	* app.mountOpenApi({ document, ui: 'scalar' });
+	* // GET /openapi.json -> { openapi: '3.1.0', ... }
+	* // GET /scalar       -> Scalar UI HTML
+	* ```
+	*/
+	mountOpenApi(options) {
+		this.app.mountOpenApi(options);
+		return this;
+	}
+	/**
+	* @internal — scans instances for `@WebSocketGateway({ path, binding })`
+	* upgrade routes. Queue/scheduled handlers are NOT scanned anymore: they
+	* come from `app.entrypoints` (`cf:queue` / `cf:scheduled` / `cf:vela-cron`
+	* kinds) at dispatch time.
+	*/
+	scanInstances(instances) {
+		for (const instance of instances) {
+			if (!instance || typeof instance !== "object") continue;
+			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 read from `app.entrypoints`; each handler runs inside a fresh
+	* request-scoped child (request-scoped providers rebuild per tick).
+	*/
+	async scheduled(event, env, ctx) {
+		assertCloudflareEnvironment(this.env, env);
+		const handlers = [...this.app.entrypoints.ofKind("cf:scheduled").map((ep) => ({
+			ep,
+			cron: entrypointString(ep.meta, "cron")
+		})), ...this.app.entrypoints.ofKind("cf:vela-cron").map((ep) => ({
+			ep,
+			cron: entrypointString(ep.meta, "expression")
+		}))].filter((h) => h.cron === event.cron);
+		await Promise.all(handlers.map(({ ep }) => this.dispatchEntrypoint(ep, [
+			event,
+			env,
+			ctx
+		])));
+	}
+	/**
+	* Run one entrypoint handler inside a fresh request scope, through the
+	* shared guard → interceptor pipeline (components declared with
+	* `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
+	* method). HTTP-global components deliberately do NOT apply — an HTTP auth
+	* guard has no business rejecting a queue batch. Unclaimed errors rethrow
+	* so the platform's retry semantics stay intact.
+	*/
+	async dispatchEntrypoint(ep, args) {
+		const targetClass = ep.token;
+		if (typeof targetClass !== "function") throw new Error("Entrypoint token must be a class.");
+		const methodName = String(ep.methodName);
+		const context = buildEntrypointExecutionContext(ep.kind, targetClass, methodName, args[0]);
+		await runInEntrypointScope(this.app.getContainer(), async (scope) => {
+			const instance = scope.resolve(ep.token);
+			if (typeof instance !== "object" || instance === null) throw new Error("Entrypoint must resolve to an object.");
+			const guards = ComponentManager.resolveGuards(ComponentManager.getScopedComponents("guard", targetClass, methodName), scope);
+			const interceptors = ComponentManager.resolveInterceptors(ComponentManager.getScopedComponents("interceptor", targetClass, methodName), scope);
+			const filters = ComponentManager.resolveFilters([...ComponentManager.getScopedComponents("filter", targetClass, methodName)].reverse(), scope);
+			try {
+				await PipelineRunner.run({
+					context,
+					guards,
+					interceptors,
+					resolveArgs: async () => args,
+					invoke: async (resolved) => invoke(instance, methodName, resolved)
+				});
+			} catch (error) {
+				for (const filter of filters) if (shouldFilterCatch(filter, error)) {
+					await filter.catch(error, context);
+					return;
+				}
+				throw error;
+			}
+		});
+	}
+	/**
+	* Handle Cloudflare Queue consumer events.
+	* Matches the batch queue name to `@QueueConsumer()` handlers read from
+	* `app.entrypoints`; each batch is processed inside a fresh request-scoped
+	* child (request-scoped providers rebuild per batch — no boot-time captives).
+	*/
+	async queue(batch, env, ctx) {
+		assertCloudflareEnvironment(this.env, env);
+		const handlers = this.app.entrypoints.ofKind("cf:queue").filter((ep) => entrypointString(ep.meta, "queueName") === batch.queue);
+		await Promise.all(handlers.map((ep) => this.dispatchEntrypoint(ep, [
+			batch,
+			env,
+			ctx
+		])));
+	}
+	async close(signal) {
+		return this.app.close(signal);
+	}
+};
+//#endregion
+//#region src/cloudflare-factory.ts
+/** Bind an application to one environment before provider factories and lifecycle hooks. */
+function cloudflareAdapter(options) {
+	return {
+		name: "cloudflare",
+		requestMiddleware: [async (context, next) => {
+			assertCloudflareEnvironment(options.env, context.env);
+			await next();
+		}],
+		invocationTransport: ({ app }) => (request) => Promise.resolve(app.fetch(request, options.env)),
+		getClientIp: (c) => getConnInfo(c).remote.address ?? null,
+		configureContainer: (container) => {
+			registerCloudflareEnvironment(container, {
+				token: options.envToken,
+				env: options.env
+			});
+		}
+	};
+}
+/** Build an application for one native Workers environment. Call inside a platform event. */
+async function createCloudflareApp(rootModule, options) {
+	const velaApp = await VelaFactory.create(resolveCloudflareRoot(rootModule, options.env), {
+		globalPrefix: options.globalPrefix,
+		security: options.security,
+		middleware: options.middleware?.(options.env),
+		adapters: [cloudflareAdapter(options)]
+	});
+	const app = new CloudflareApplication(velaApp, options.env);
+	app.scanInstances(velaApp.getInstances());
+	registerWebSocketRoutes(app.getHonoApp(), app.getWsGatewayRoutes());
+	return app;
+}
+/**
+* Worker entrypoint with one bootstrap per environment identity. Weak keys let
+* obsolete environments and secrets be collected. Concurrent cold events share
+* construction; failed construction is evicted so the next event can retry.
+*/
+function createCloudflareWorker(rootModule, options) {
+	const applications = /* @__PURE__ */ new WeakMap();
+	const application = (env) => {
+		const existing = applications.get(env);
+		if (existing) return existing;
+		const pending = createCloudflareApp(rootModule, {
+			...options,
+			env
+		});
+		applications.set(env, pending);
+		pending.catch(() => {
+			if (applications.get(env) === pending) applications.delete(env);
+		});
+		return pending;
+	};
+	return {
+		async fetch(request, env, ctx) {
+			return (await application(env)).fetch(request, env, ctx);
+		},
+		async scheduled(event, env, ctx) {
+			return (await application(env)).scheduled(event, env, ctx);
+		},
+		async queue(batch, env, ctx) {
+			return (await application(env)).queue(batch, env, ctx);
+		}
+	};
+}
+//#endregion
+//#region src/storage/storage.tokens.ts
+const STORAGE_OPTIONS = new InjectionToken("STORAGE_OPTIONS");
+//#endregion
+//#region src/storage/storage-key-claim.ts
+/** R2-compatible object-key claim bound. Keeps decode work predictably small. */
+const MAX_STORAGE_KEY_BYTES = 1024;
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
+const ROOT_TOKEN_PATTERNS = {
+	date: "\\d{4}-\\d{2}-\\d{2}",
+	year: "\\d{4}",
+	month: "(?:0[1-9]|1[0-2])",
+	day: "(?:0[1-9]|[12]\\d|3[01])",
+	uuid: "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}"
+};
+/** Encode an object key as an opaque, canonical base64url query claim. */
+function encodeStorageKeyClaim(key) {
+	const bytes = new TextEncoder().encode(key);
+	if (bytes.byteLength === 0 || bytes.byteLength > 1024) throw new Error(`Storage key must be 1–${MAX_STORAGE_KEY_BYTES} UTF-8 bytes`);
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Decode exactly one canonical base64url layer. Malformed/non-UTF-8 claims return undefined. */
+function decodeStorageKeyClaim(claim) {
+	try {
+		if (claim.length === 0 || claim.length > Math.ceil(4096 / 3) || !BASE64URL_RE.test(claim) || claim.length % 4 === 1) return;
+		const base64 = claim.replace(/-/g, "+").replace(/_/g, "/");
+		const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+		const binary = atob(padded);
+		const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		if (bytes.byteLength === 0 || bytes.byteLength > 1024) return void 0;
+		const decoded = new TextDecoder("utf-8", {
+			fatal: true,
+			ignoreBOM: false
+		}).decode(bytes);
+		return encodeStorageKeyClaim(decoded) === claim ? decoded : void 0;
+	} catch {
+		return;
+	}
+}
+function isDotSegment(segment) {
+	let decoded = segment;
+	for (let i = 0; i < 2; i++) {
+		if (decoded === "" || decoded === "." || decoded === "..") return true;
+		try {
+			const next = decodeURIComponent(decoded);
+			if (next === decoded) break;
+			decoded = next;
+		} catch {
+			break;
+		}
+	}
+	return decoded === "" || decoded === "." || decoded === "..";
+}
+function rootSegmentPattern(segment) {
+	let pattern = "";
+	let cursor = 0;
+	for (const match of segment.matchAll(/\{(date|year|month|day|uuid)\}/g)) {
+		pattern += segment.slice(cursor, match.index).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		pattern += ROOT_TOKEN_PATTERNS[match[1]];
+		cursor = match.index + match[0].length;
+	}
+	pattern += segment.slice(cursor).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return pattern;
+}
+/** Assert a canonical key is beneath a static or templated configured root. */
+function isStorageKeyWithinRoot(key, root) {
+	const segments = (root ?? "").split(/[/\\]+/).filter((segment) => !isDotSegment(segment));
+	if (segments.length === 0) return key.length > 0;
+	const rootPattern = segments.map(rootSegmentPattern).join("/");
+	return new RegExp(`^(?:${rootPattern})(?:/|$)`).test(key);
+}
+//#endregion
+//#region src/storage/r2-storage.driver.ts
+/** Base path of the StorageController presign-proxy route. */
+const STORAGE_ROUTE_BASE = "/storage";
+/** {@link StorageDriver} over a Cloudflare R2 bucket. */
+var R2StorageDriver = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	async upload(body, path, options) {
+		await this.config.bucket.put(path, body, {
+			httpMetadata: options.mimeType ? { contentType: options.mimeType } : void 0,
+			customMetadata: options.metadata
+		});
+		return {
+			path,
+			disk: this.config.disk,
+			size: options.size,
+			mimeType: options.mimeType ?? "application/octet-stream",
+			uploadedAt: /* @__PURE__ */ 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).");
+		if (!Number.isSafeInteger(expiresIn) || expiresIn <= 0) throw new Error(`Invalid presigned URL expiry: ${expiresIn}s (must be a positive safe integer).`);
+		const claim = encodeStorageKeyClaim(path);
+		const routePath = `${STORAGE_ROUTE_BASE}/${encodeURIComponent(this.config.disk)}`;
+		const query = new URLSearchParams({
+			key: claim,
+			method
+		});
+		return {
+			url: await signUrl(`${routePath}?${query}`, this.config.secret, {
+				expiresIn,
+				method,
+				purpose: STORAGE_SIGNED_URL_PURPOSE
+			}),
+			method,
+			expiresIn,
+			expiresAt: new Date(Date.now() + expiresIn * 1e3)
+		};
+	}
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region src/storage/storage-manager.service.ts
+let StorageManagerService = class StorageManagerService {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	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) {
+		return new R2StorageDriver({
+			disk,
+			bucket: this.getDiskConfig(disk).bucket,
+			secret: this.options.secret
+		});
+	}
+};
+StorageManagerService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(STORAGE_OPTIONS)),
+	__decorateMetadata("design:paramtypes", [Object])
+], StorageManagerService);
+//#endregion
+//#region src/storage/storage.controller.ts
+let StorageController = class StorageController {
+	manager;
+	options;
+	constructor(manager, options) {
+		this.manager = manager;
+		this.options = options;
+	}
+	async download(c) {
+		const secret = this.options.secret;
+		if (!secret) return new Response("Storage signing is not configured", { status: 500 });
+		if (!await verifySignedUrl(c.req.url, secret, {
+			method: c.req.method,
+			purpose: STORAGE_SIGNED_URL_PURPOSE
+		})) return new Response("Invalid or expired URL", { status: 403 });
+		const url = new URL(c.req.url);
+		if (url.searchParams.get("method") !== "GET") return new Response("URL is not scoped for reads", { status: 403 });
+		const disk = c.req.param("disk");
+		if (!disk || !this.manager.hasDisk(disk)) return new Response("Unknown disk", { status: 404 });
+		const claim = url.searchParams.get("key");
+		const decoded = claim ? decodeStorageKeyClaim(claim) : void 0;
+		if (!decoded) return new Response("Malformed storage key claim", { status: 400 });
+		const fullPath = joinStoragePath(void 0, decoded);
+		if (fullPath !== decoded) return new Response("Invalid storage key", { status: 403 });
+		if (!isStorageKeyWithinRoot(fullPath, this.manager.getDiskConfig(disk).root)) return new Response("Storage key is outside the configured root", { status: 403 });
+		try {
+			const result = await this.manager.getDriver(disk).download(fullPath);
+			const filename = fullPath.split("/").at(-1) || "download";
+			return new Response(result.toStream(), { headers: {
+				"content-type": result.contentType || "application/octet-stream",
+				"content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`,
+				"x-content-type-options": "nosniff"
+			} });
+		} catch {
+			return new Response("Not found", { status: 404 });
+		}
+	}
+};
+__decorate([
+	Get("/:disk"),
+	__decorateParam(0, Req()),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], StorageController.prototype, "download", null);
+StorageController = __decorate([
+	Controller("storage"),
+	__decorateParam(0, Inject(StorageManagerService)),
+	__decorateParam(1, Inject(STORAGE_OPTIONS)),
+	__decorateMetadata("design:paramtypes", [typeof StorageManagerService === "undefined" ? Object : StorageManagerService, Object])
+], StorageController);
+//#endregion
+//#region src/storage/storage.service.ts
+const DEFAULT_PRESIGN = {
+	defaultExpiry: 3600,
+	maxExpiry: 86400
+};
+let StorageService = class StorageService {
+	options;
+	manager;
+	constructor(options, manager) {
+		this.options = options;
+		this.manager = manager;
+	}
+	put(relativePath, body, options = {}, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).upload(body, this.fullPath(relativePath, name), options);
+	}
+	get(relativePath, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).download(this.fullPath(relativePath, name));
+	}
+	delete(relativePath, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).delete(this.fullPath(relativePath, name));
+	}
+	exists(relativePath, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).exists(this.fullPath(relativePath, name));
+	}
+	url(relativePath, method = "GET", expiresIn, disk) {
+		const name = this.resolveDisk(disk);
+		return this.manager.getDriver(name).getPresignedUrl(this.fullPath(relativePath, name), method, this.validateExpiry(expiresIn));
+	}
+	resolveDisk(disk) {
+		const name = disk ?? this.options.defaultDisk;
+		if (!this.manager.hasDisk(name)) throw new Error(`Storage disk "${name}" is not configured.`);
+		return name;
+	}
+	fullPath(relativePath, disk) {
+		return joinStoragePath(this.manager.getDiskConfig(disk).root, relativePath);
+	}
+	validateExpiry(expiresIn) {
+		const cfg = this.options.presignedUrl ?? DEFAULT_PRESIGN;
+		const value = expiresIn ?? cfg.defaultExpiry;
+		if (!Number.isSafeInteger(value) || value < 1 || value > cfg.maxExpiry) throw new Error(`Presigned URL expiry ${value}s is out of range (1–${cfg.maxExpiry}s).`);
+		return value;
+	}
+};
+StorageService = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(STORAGE_OPTIONS)),
+	__decorateParam(1, Inject(StorageManagerService)),
+	__decorateMetadata("design:paramtypes", [Object, typeof StorageManagerService === "undefined" ? Object : StorageManagerService])
+], StorageService);
+//#endregion
+//#region src/storage/storage.module.ts
+const { ConfigurableModuleClass } = new ConfigurableModuleBuilder({
+	moduleName: "Storage",
+	optionsInjectionToken: STORAGE_OPTIONS
+}).build();
+let StorageModule = class StorageModule extends ConfigurableModuleClass {};
+StorageModule = __decorate([Module({
+	providers: [StorageManagerService, StorageService],
+	controllers: [StorageController],
+	exports: [
+		StorageService,
+		StorageManagerService,
+		STORAGE_OPTIONS
+	]
+})], StorageModule);
+//#endregion
+//#region src/services/kv-cache.store.ts
+/**
+* Cloudflare KV-backed {@link CacheStore}. Values are JSON-encoded. Intended as
+* the slow tier under a `TieredCacheStore` (memory L1 → KV L2), but usable
+* standalone from a typed environment factory: `new KVCacheStore(env.CACHE)`.
+* Reads return unknown JSON; validate values at the consuming boundary.
+*
+* 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.
+*/
+var KVCacheStore = class {
+	ns;
+	constructor(ns) {
+		this.ns = ns;
+	}
+	async get(key) {
+		const value = await this.ns.get(key, "json");
+		return value === null ? void 0 : value;
+	}
+	async set(key, value, ttl) {
+		const options = ttl !== void 0 ? { expirationTtl: Math.max(60, Math.floor(ttl)) } : void 0;
+		await this.ns.put(key, JSON.stringify(value), options);
+	}
+	async del(key) {
+		await this.ns.delete(key);
+	}
+	async clear() {
+		let cursor;
+		do {
+			const list = await this.ns.list(cursor ? { cursor } : void 0);
+			await Promise.all(list.keys.map((entry) => this.ns.delete(entry.name)));
+			cursor = list.list_complete ? void 0 : list.cursor;
+		} while (cursor);
+	}
+};
+//#endregion
+//#region src/services/flagship-flag.driver.ts
+/**
+* {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+*
+* A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+* corresponding value method, forwarding the caller's `fallback` (the binding's
+* `defaultValue`) and evaluation context. The binding resolves the fallback on
+* evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+* dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+* the never-throw guarantee.
+*
+* Build the driver inside a provider factory with the native environment:
+*
+* ```ts
+* FeatureFlagsModule.forRootAsync({
+*   inject: [ENV],
+*   useFactory: (env: WorkerEnv) => ({ drivers: [flagshipFlagDriver(env.FLAGS)] }),
+* });
+* ```
+*
+* Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+* Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+* bare driver.
+*/
+var FlagshipFlagDriver = class {
+	name;
+	resolve;
+	constructor(binding, options = {}) {
+		this.resolve = typeof binding === "function" ? binding : () => binding;
+		this.name = options.name ?? "flagship";
+	}
+	getBoolean(key, fallback, ctx) {
+		return this.resolve().getBooleanValue(key, fallback, ctx);
+	}
+	getString(key, fallback, ctx) {
+		return this.resolve().getStringValue(key, fallback, ctx);
+	}
+	getNumber(key, fallback, ctx) {
+		return this.resolve().getNumberValue(key, fallback, ctx);
+	}
+	getObject(key, fallback, ctx) {
+		return this.resolve().getObjectValue(key, fallback, ctx);
+	}
+};
+/** Convenience factory for {@link FlagshipFlagDriver}. */
+function flagshipFlagDriver(binding, options) {
+	return new FlagshipFlagDriver(binding, options);
+}
+//#endregion
+//#region src/services/kv-flag.driver.ts
+/**
+* Cloudflare KV-backed {@link FeatureFlagDriver}. Flags are stored as JSON
+* values under an optional key prefix and read with `get(key, 'json')`. Reads
+* are type-checked against the requested type: a missing key or a value of the
+* wrong JSON type returns the caller's `fallback`. KV has no targeting, so the
+* evaluation context is ignored.
+*
+* The driver stays honest — it does **not** swallow errors. A KV failure (or a
+* `SyntaxError` from a malformed stored value) propagates; the never-throw
+* guarantee lives in `@velajs/feature-flags`'s service layer.
+*
+* Placed like {@link KVCacheStore}: construct it in a wiring factory over a
+* resolved {@link KVNamespace}.
+*
+* ```ts
+* FeatureFlagsModule.forRootAsync({
+*   inject: [ENV],
+*   useFactory: (env: WorkerEnv) => ({ drivers: [new KvFlagDriver(env.CACHE, { prefix: 'flag:' })] }),
+* });
+* ```
+*/
+var KvFlagDriver = class {
+	ns;
+	name;
+	prefix;
+	constructor(ns, options = {}) {
+		this.ns = ns;
+		this.name = options.name ?? "kv";
+		this.prefix = options.prefix ?? "";
+	}
+	getBoolean(key, fallback, _ctx) {
+		return this.read(key, fallback, (v) => typeof v === "boolean");
+	}
+	getString(key, fallback, _ctx) {
+		return this.read(key, fallback, (v) => typeof v === "string");
+	}
+	getNumber(key, fallback, _ctx) {
+		return this.read(key, fallback, (v) => typeof v === "number");
+	}
+	getObject(key, fallback, _ctx) {
+		return this.read(key, fallback, (v) => typeof v === "object" && v !== null);
+	}
+	/**
+	* Reads and JSON-parses the (prefixed) key, returning the parsed value only
+	* when `matches` accepts its type; otherwise the caller's fallback. A missing
+	* key reads as `null` → fallback. Read/parse errors are left to propagate.
+	*/
+	async read(key, fallback, matches) {
+		const value = await this.ns.get(this.prefix + key, "json");
+		if (value === null || value === void 0) return fallback;
+		return matches(value) ? value : fallback;
+	}
+};
+/** Convenience factory for {@link KvFlagDriver}. */
+function kvFlagDriver(kv, options) {
+	return new KvFlagDriver(kv, options);
+}
+//#endregion
+//#region src/decorators/env.ts
+/**
+* Parameter decorator to inject Cloudflare environment bindings.
+*
+* Without arguments, returns the entire `env` object.
+* With a binding name, returns that specific binding.
+*
+* @example
+* ```ts
+* @Get()
+* handle(@Env() env: WorkerEnv) { ... }
+*
+* @Get()
+* handle(@Env('MY_KV') kv: KVNamespace) { ... }
+* ```
+*/
+const Env = createParamDecorator((bindingName, ctx) => {
+	const env = ctx.getContext().env;
+	if (typeof env !== "object" || env === null) return void 0;
+	return bindingName ? Reflect.get(env, bindingName) : env;
+});
+//#endregion
+//#region src/decorators/scheduled.ts
+const SCHEDULED_METADATA_KEY = "cloudflare:scheduled";
+registerEntrypointKind({
+	kind: "cf:scheduled",
+	metaKey: SCHEDULED_METADATA_KEY,
+	level: "method"
+});
+/**
+* Marks a method as a scheduled (cron) handler.
+*
+* @example
+* ```ts
+* @Injectable()
+* class WorkerService {
+*   @Scheduled('0 * * * *')
+*   async hourlyCron() {
+*     console.log('Running hourly');
+*   }
+* }
+* ```
+*/
+function Scheduled(cron) {
+	return (target, propertyKey, _descriptor) => {
+		const existing = getMetadata(SCHEDULED_METADATA_KEY, target.constructor) ?? [];
+		existing.push({
+			cron,
+			methodName: String(propertyKey)
+		});
+		defineMetadata(SCHEDULED_METADATA_KEY, existing, target.constructor);
+	};
+}
+//#endregion
+//#region src/decorators/queue-consumer.ts
+const QUEUE_CONSUMER_METADATA_KEY = "cloudflare:queue-consumer";
+registerEntrypointKind({
+	kind: "cf:queue",
+	metaKey: QUEUE_CONSUMER_METADATA_KEY,
+	level: "method"
+});
+/**
+* Marks a method as a queue consumer handler.
+*
+* @example
+* ```ts
+* @Injectable()
+* class WorkerService {
+*   @QueueConsumer('email-queue')
+*   async processEmails(batch: MessageBatch) {
+*     for (const msg of batch.messages) {
+*       console.log('Processing:', msg.body);
+*       msg.ack();
+*     }
+*   }
+* }
+* ```
+*/
+function QueueConsumer(queueName) {
+	return (target, propertyKey, _descriptor) => {
+		const existing = getMetadata(QUEUE_CONSUMER_METADATA_KEY, target.constructor) ?? [];
+		existing.push({
+			queueName,
+			methodName: String(propertyKey)
+		});
+		defineMetadata(QUEUE_CONSUMER_METADATA_KEY, existing, target.constructor);
+	};
+}
+//#endregion
+//#region src/websocket/cloudflare-websocket.module.ts
+/**
+* Cloudflare counterpart to the core `WebSocketModule.forRoot()`. Import this in
+* your `AppModule` instead: it provides the gateway dispatcher plus a late-bound
+* `WS_SERVER` (`WsServerHolder`) that the WebSocket Durable Object wires to a
+* ctx-backed server per instance. `useClass` ensures a fresh holder per DI
+* container so colocated DO instances never share a server.
+*/
+var CloudflareWebSocketModule = class CloudflareWebSocketModule {
+	static forRoot() {
+		const providers = [defineProvider(WS_SERVER, { useClass: WsServerHolder }), WsDispatcher];
+		return {
+			module: CloudflareWebSocketModule,
+			providers,
+			exports: [WS_SERVER, WsDispatcher]
+		};
+	}
+};
+//#endregion
+//#region src/websocket/broadcast.ts
+/**
+* Push to a room from a Worker HTTP handler / cron / queue consumer (server-
+* initiated emit). Resolves the room's Durable Object and calls its `broadcast`
+* RPC method — the same canonical room→DO mapping the upgrade route uses, so it
+* always reaches the DO holding those sockets.
+*
+* @example
+* ```ts
+* // In a controller — ns from the typed Worker environment
+* await broadcastToRoom(ns, '/orgs/:orgId/ws', `org:${id}`, 'order.created', order);
+* ```
+*/
+async function broadcastToRoom(ns, gatewayPath, room, event, data, options) {
+	const cmd = {
+		rooms: [room],
+		exceptIds: options?.exceptIds,
+		frame: JSON.stringify({
+			event,
+			data
+		})
+	};
+	const maxFrameBytes = resolveMaxFrameBytes({ maxFrameBytes: options?.maxFrameBytes ?? DEFAULT_WS_MAX_FRAME_BYTES });
+	assertBroadcastCommandFits(cmd, maxFrameBytes);
+	await ns.get(roomToDurableId(ns, gatewayPath, room)).broadcast(cmd);
+}
+//#endregion
+//#region src/rate-limit/cloudflare-rate-limit.store.ts
+/**
+* Adapt a Cloudflare Workers Rate Limiting binding to Vela's throttler store.
+*
+* The platform binding makes the allow/deny decision. It does not expose exact
+* counters or reset timestamps, so this adapter intentionally omits `remaining`.
+*/
+function cloudflareRateLimitStore(binding, options) {
+	if (!binding || typeof binding !== "function" && typeof binding.limit !== "function") throw new TypeError("A Cloudflare Rate Limiting binding is required");
+	if (!Number.isSafeInteger(options.limit) || options.limit <= 0 || options.limit >= Number.MAX_SAFE_INTEGER) throw new RangeError("Rate limit must be a positive safe integer");
+	if (options.periodSeconds !== 10 && options.periodSeconds !== 60) throw new RangeError("Cloudflare rate-limit periods must be 10 or 60 seconds");
+	const maxKeyBytes = options.maxKeyBytes ?? 1024;
+	if (!Number.isSafeInteger(maxKeyBytes) || maxKeyBytes <= 0 || maxKeyBytes > 4096) throw new RangeError("maxKeyBytes must be between 1 and 4096");
+	const ttlMs = options.periodSeconds * 1e3;
+	const encoder = new TextEncoder();
+	const resolveBinding = typeof binding === "function" ? binding : () => binding;
+	return {
+		async increment(key, requestedTtlMs) {
+			if (requestedTtlMs !== ttlMs) throw new Error(`Cloudflare binding period mismatch: expected ${ttlMs}ms, received ${requestedTtlMs}ms`);
+			if (typeof key !== "string" || key.length === 0 || /[\u0000-\u001f\u007f]/.test(key) || encoder.encode(key).byteLength > maxKeyBytes) throw new Error("Refusing an invalid or oversized rate-limit key");
+			const currentBinding = resolveBinding();
+			if (!currentBinding || typeof currentBinding.limit !== "function") throw new Error("Cloudflare Rate Limiting binding is unavailable");
+			const decision = await currentBinding.limit({ key });
+			if (!decision || typeof decision.success !== "boolean") throw new Error("Cloudflare rate-limit binding returned an invalid decision");
+			return {
+				count: decision.success ? 0 : options.limit + 1,
+				ttlMs,
+				allowed: decision.success,
+				enforcedLimit: options.limit
+			};
+		},
+		reset() {
+			throw new Error("Cloudflare Rate Limiting bindings do not support counter reset");
+		}
+	};
+}
+//#endregion
+//#region src/nonce/durable-object-nonce.store.ts
+const APP_NAMESPACE_PREFIX = "vela:nonce:v1:";
+const MAX_APP_NAMESPACE_BYTES = 128;
+/**
+* Strict, cross-isolate {@link NonceStore} backed by one SQLite Durable Object
+* per explicit application namespace.
+*
+* Invalid input, an unavailable/malformed binding, RPC failure, or a malformed
+* RPC result all deny the claim (`false`). Only the literal boolean `true` from
+* the Durable Object is accepted.
+*/
+function durableObjectNonceStore(options) {
+	if (!options || typeof options !== "object") throw new TypeError("Durable Object nonce-store options are required");
+	if (!isCanonicalBoundedText(options.appNamespace, MAX_APP_NAMESPACE_BYTES)) throw new TypeError(`appNamespace must be canonical, non-empty, and at most ${MAX_APP_NAMESPACE_BYTES} UTF-8 bytes`);
+	if (typeof options.binding !== "function") throw new TypeError("A lazy Durable Object namespace binding resolver is required");
+	const objectName = `${APP_NAMESPACE_PREFIX}${options.appNamespace}`;
+	return { async claim(nonce, expEpochSeconds) {
+		const now = Math.floor(Date.now() / 1e3);
+		if (!isCanonicalBoundedText(nonce, 512) || !isValidExpiry(expEpochSeconds, now)) return false;
+		try {
+			const namespace = await options.binding();
+			const id = namespace.idFromName(objectName);
+			return await namespace.get(id).claim(nonce, expEpochSeconds) === true;
+		} catch {
+			return false;
+		}
+	} };
+}
+//#endregion
+export { CloudflareApplication, CloudflareWebSocketModule, ConnectedSocket, DoCursorLog, DoPitrUnavailableError, Env, FlagshipFlagDriver, KVCacheStore, KvFlagDriver, MessageBody, QueueConsumer, R2StorageDriver, STORAGE_OPTIONS, Scheduled, StorageController, StorageManagerService, StorageModule, StorageService, SubscribeMessage, WebSocketGateway, WebSocketServer, WsException, armDoPitr, broadcastToRoom, cloudflareAdapter, cloudflareRateLimitStore, createCloudflareApp, createCloudflareWorker, durableObjectCursorLog, durableObjectLive, durableObjectNonceStore, durableObjectRoomName, flagshipFlagDriver, isDoPitrUnavailable, kvFlagDriver, liveInvalidateToRoom, readDoPitrBookmark };
+
+//# sourceMappingURL=index.js.map