@wooksjs/event-wf 0.7.9 → 0.7.11

package/dist/index.cjs

@@ -120,7 +120,6 @@ const useWfFinished = (0, __wooksjs_event_core.defineWook)((ctx) => ({
 
 //#endregion
 //#region packages/event-wf/src/outlets/trigger.ts
-const DEFAULT_CONSUME_TOKEN = { email: true };
 /**
 * Handle an HTTP request that starts or resumes a workflow.
 *
@@ -168,38 +167,32 @@ async function handleWfOutletRequest(config, deps) {
 	const wfid = body?.[wfidName] ?? queryParams.get(wfidName) ?? void 0;
 	const input = body?.input;
 	const resolveStrategy = (id) => typeof config.state === "function" ? config.state(id) : config.state;
-	const shouldConsume = (outletName) => {
-		if (typeof tok.consume === "boolean") return tok.consume;
-		return (tok.consume ?? DEFAULT_CONSUME_TOKEN)[outletName] ?? false;
-	};
 	let output;
 	if (token) {
 		const strategy = resolveStrategy(wfid ?? "");
 		ctx.set(stateStrategyKey, strategy);
-		const state = await strategy.retrieve(token);
-		if (!state) return {
-			error: "Invalid or expired workflow state",
-			status: 400
-		};
+		const state = await strategy.consume(token);
+		if (!state) {
+			response.setStatus(410);
+			return { error: "Invalid or expired workflow state" };
+		}
 		if (state.schemaId !== (wfid ?? "")) {
 			const realStrategy = resolveStrategy(state.schemaId);
 			ctx.set(stateStrategyKey, realStrategy);
 		}
-		const outletName = state.meta?.outlet;
-		if (outletName && shouldConsume(outletName)) await strategy.consume(token);
 		output = await deps.resume(state, {
 			input,
 			eventContext: ctx
 		});
 	} else if (wfid) {
-		if (config.allow?.length && !config.allow.includes(wfid)) return {
-			error: `Workflow '${wfid}' is not allowed`,
-			status: 403
-		};
-		if (config.block?.includes(wfid)) return {
-			error: `Workflow '${wfid}' is blocked`,
-			status: 403
-		};
+		if (config.allow?.length && !config.allow.includes(wfid)) {
+			response.setStatus(403);
+			return { error: `Workflow '${wfid}' is not allowed` };
+		}
+		if (config.block?.includes(wfid)) {
+			response.setStatus(403);
+			return { error: `Workflow '${wfid}' is blocked` };
+		}
 		const strategy = resolveStrategy(wfid);
 		ctx.set(stateStrategyKey, strategy);
 		const initialContext = config.initialContext ? config.initialContext(body, wfid) : {};
@@ -207,10 +200,10 @@ async function handleWfOutletRequest(config, deps) {
 			input,
 			eventContext: ctx
 		});
-	} else return {
-		error: "Missing wfs (state token) or wfid (workflow ID)",
-		status: 400
-	};
+	} else {
+		response.setStatus(400);
+		return { error: "Missing wfs (state token) or wfid (workflow ID)" };
+	}
 	if (output.finished) {
 		if (config.onFinished) return config.onFinished({
 			context: output.state.context,
@@ -219,32 +212,37 @@ async function handleWfOutletRequest(config, deps) {
 		const finished = ctx.get(wfFinishedKey);
 		if (finished?.cookies) for (const [name, cookie] of Object.entries(finished.cookies)) response.setCookie(name, cookie.value, cookie.options);
 		if (finished?.type === "redirect") {
+			response.setStatus(finished.status ?? 302);
 			response.setHeader("location", finished.value);
-			return { status: finished.status ?? 302 };
+			return "";
+		}
+		if (finished) {
+			if (finished.status) response.setStatus(finished.status);
+			return finished.value;
 		}
-		if (finished) return finished.value;
 		return { finished: true };
 	}
 	if (output.inputRequired) {
 		const outletReq = output.inputRequired;
 		const outletHandler = registry.get(outletReq.outlet);
-		if (!outletHandler) return {
-			error: `Unknown outlet: '${outletReq.outlet}'`,
-			status: 500
-		};
+		if (!outletHandler) {
+			response.setStatus(500);
+			return { error: `Unknown outlet: '${outletReq.outlet}'` };
+		}
 		const strategy = ctx.get(stateStrategyKey);
 		const stateWithMeta = {
 			...output.state,
 			meta: { outlet: outletReq.outlet }
 		};
 		const newToken = await strategy.persist(stateWithMeta, output.expires ? { ttl: output.expires - Date.now() } : void 0);
-		if (tokenWrite === "cookie") response.setCookie(tokenName, newToken, {
+		const outOfBand = outletHandler.tokenDelivery === "out-of-band";
+		if (tokenWrite === "cookie" && !outOfBand) response.setCookie(tokenName, newToken, {
 			httpOnly: true,
 			sameSite: "Strict",
 			path: "/"
 		});
 		const result = await outletHandler.deliver(outletReq, newToken);
-		if (tokenWrite === "body" && result?.response && typeof result.response === "object") return {
+		if (tokenWrite === "body" && !outOfBand && result?.response && typeof result.response === "object") return {
 			...result.response,
 			[tokenName]: newToken
 		};
@@ -274,6 +272,7 @@ async function handleWfOutletRequest(config, deps) {
 function createHttpOutlet(opts) {
 	return {
 		name: "http",
+		tokenDelivery: "caller",
 		async deliver(request, _token) {
 			const body = opts?.transform ? opts.transform(request.payload, request.context) : typeof request.payload === "object" && request.payload !== null ? {
 				...request.payload,
@@ -302,6 +301,7 @@ function createHttpOutlet(opts) {
 function createEmailOutlet(send) {
 	return {
 		name: "email",
+		tokenDelivery: "out-of-band",
 		async deliver(request, token) {
 			await send({
 				target: request.target ?? "",
@@ -339,7 +339,7 @@ function createOutletHandler(wfApp) {
 }
 
 //#endregion
-//#region node_modules/.pnpm/@prostojs+wf@0.1.1/node_modules/@prostojs/wf/dist/outlets/index.mjs
+//#region node_modules/.pnpm/@prostojs+wf@0.2.0/node_modules/@prostojs/wf/dist/outlets/index.mjs
 /**
 * Generic outlet request. Use for custom outlets.
 *
@@ -391,6 +391,29 @@ function outletEmail(target, template, context) {
 *
 * Token format: `base64url(iv[12] + authTag[16] + ciphertext)`
 *
+* ## Security warning — replay
+*
+* This strategy is STATELESS. It cannot enforce single-use semantics:
+* `consume()` is a no-op alias for `retrieve()` because there is no
+* server-side record to delete. Anyone who obtains a copy of the token
+* (browser history, server logs, shoulder-surfing, intermediate proxy,
+* shared device) can replay it until the TTL expires.
+*
+* Use `EncapsulatedStateStrategy` ONLY when BOTH of the following hold:
+*
+* 1. Every workflow step is idempotent — re-executing a step with the same
+*    input produces no harmful side effects (pure data collection,
+*    validation-only steps).
+* 2. The flow is not security-sensitive — no credential changes, financial
+*    operations, account provisioning, permission grants, or any other
+*    privileged action.
+*
+* For auth flows (login, password reset, invite accept), financial
+* operations, or anything with meaningful side effects, use
+* `HandleStateStrategy` with a durable `WfStateStore`. `HandleStateStrategy`
+* supports true single-use tokens via atomic `getAndDelete` at the store
+* layer.
+*
 * @example
 * const strategy = new EncapsulatedStateStrategy({
 *     secret: crypto.randomBytes(32),
@@ -433,7 +456,14 @@ var EncapsulatedStateStrategy = class {
 	async retrieve(token) {
 		return this.decrypt(token);
 	}
-	/** Same as retrieve (stateless — cannot truly invalidate a token). */
+	/**
+	* Stateless — CANNOT invalidate the token. Returns identical result to
+	* `retrieve()`. See the class-level security warning.
+	*
+	* This method exists only to satisfy the `WfStateStrategy` contract.
+	* Callers that need true single-use semantics must use
+	* `HandleStateStrategy`.
+	*/
 	async consume(token) {
 		return this.decrypt(token);
 	}

package/dist/index.d.ts

@@ -92,26 +92,36 @@ interface WfOutletTokenConfig {
     write?: 'body' | 'cookie';
     /** Parameter name for state token (default: `'wfs'`) */
     name?: string;
-    /**
-     * Token consumption mode per outlet. When `true`, the trigger calls
-     * `strategy.consume()` (single-use token) instead of `strategy.retrieve()`
-     * on resume. Defaults to `{ email: true }` — email magic links are consumed
-     * on first use, HTTP tokens are reusable.
-     *
-     * Can be a boolean (applies to all outlets) or a per-outlet-name map.
-     */
-    consume?: boolean | Record<string, boolean>;
 }
 interface WfOutletTriggerConfig {
     /** Whitelist of allowed workflow IDs. If empty, all are allowed. */
     allow?: string[];
     /** Blacklist of workflow IDs. Checked after allow. */
     block?: string[];
-    /** State persistence strategy */
+    /**
+     * State persistence strategy. Either a single strategy shared by all
+     * workflows, or a function that returns a strategy per workflow ID.
+     *
+     * **Constraint when using the function form.** The trigger resolves the
+     * strategy at resume time using the `wfid` from the request. If the resume
+     * request does not include `wfid` (e.g. cookie-only transport, token-only
+     * body), the trigger calls `config.state('')` — meaning:
+     *
+     * - EITHER all strategies returned by the function must share the same
+     *   underlying storage (same Redis instance, same `WfStateStore`, same
+     *   encryption key), so `consume`/`retrieve` operations work regardless of
+     *   which strategy instance is picked;
+     * - OR every resume request must carry `wfid` so the correct strategy is
+     *   always resolved.
+     *
+     * Violating this contract silently breaks single-use token invalidation:
+     * the `consume` call runs against the wrong strategy's storage, and the
+     * token remains live in the real strategy.
+     */
     state: WfStateStrategy | ((wfid: string) => WfStateStrategy);
     /** Registered outlets */
     outlets: WfOutlet[];
-    /** Token configuration (reading, writing, naming, consumption) */
+    /** Token configuration (reading, writing, naming) */
     token?: WfOutletTokenConfig;
     /** Parameter name for workflow ID (default: `'wfid'`) */
     wfidName?: string;

package/dist/index.mjs

@@ -97,7 +97,6 @@ const useWfFinished = defineWook((ctx) => ({
 
 //#endregion
 //#region packages/event-wf/src/outlets/trigger.ts
-const DEFAULT_CONSUME_TOKEN = { email: true };
 /**
 * Handle an HTTP request that starts or resumes a workflow.
 *
@@ -145,38 +144,32 @@ async function handleWfOutletRequest(config, deps) {
 	const wfid = body?.[wfidName] ?? queryParams.get(wfidName) ?? void 0;
 	const input = body?.input;
 	const resolveStrategy = (id) => typeof config.state === "function" ? config.state(id) : config.state;
-	const shouldConsume = (outletName) => {
-		if (typeof tok.consume === "boolean") return tok.consume;
-		return (tok.consume ?? DEFAULT_CONSUME_TOKEN)[outletName] ?? false;
-	};
 	let output;
 	if (token) {
 		const strategy = resolveStrategy(wfid ?? "");
 		ctx.set(stateStrategyKey, strategy);
-		const state = await strategy.retrieve(token);
-		if (!state) return {
-			error: "Invalid or expired workflow state",
-			status: 400
-		};
+		const state = await strategy.consume(token);
+		if (!state) {
+			response.setStatus(410);
+			return { error: "Invalid or expired workflow state" };
+		}
 		if (state.schemaId !== (wfid ?? "")) {
 			const realStrategy = resolveStrategy(state.schemaId);
 			ctx.set(stateStrategyKey, realStrategy);
 		}
-		const outletName = state.meta?.outlet;
-		if (outletName && shouldConsume(outletName)) await strategy.consume(token);
 		output = await deps.resume(state, {
 			input,
 			eventContext: ctx
 		});
 	} else if (wfid) {
-		if (config.allow?.length && !config.allow.includes(wfid)) return {
-			error: `Workflow '${wfid}' is not allowed`,
-			status: 403
-		};
-		if (config.block?.includes(wfid)) return {
-			error: `Workflow '${wfid}' is blocked`,
-			status: 403
-		};
+		if (config.allow?.length && !config.allow.includes(wfid)) {
+			response.setStatus(403);
+			return { error: `Workflow '${wfid}' is not allowed` };
+		}
+		if (config.block?.includes(wfid)) {
+			response.setStatus(403);
+			return { error: `Workflow '${wfid}' is blocked` };
+		}
 		const strategy = resolveStrategy(wfid);
 		ctx.set(stateStrategyKey, strategy);
 		const initialContext = config.initialContext ? config.initialContext(body, wfid) : {};
@@ -184,10 +177,10 @@ async function handleWfOutletRequest(config, deps) {
 			input,
 			eventContext: ctx
 		});
-	} else return {
-		error: "Missing wfs (state token) or wfid (workflow ID)",
-		status: 400
-	};
+	} else {
+		response.setStatus(400);
+		return { error: "Missing wfs (state token) or wfid (workflow ID)" };
+	}
 	if (output.finished) {
 		if (config.onFinished) return config.onFinished({
 			context: output.state.context,
@@ -196,32 +189,37 @@ async function handleWfOutletRequest(config, deps) {
 		const finished = ctx.get(wfFinishedKey);
 		if (finished?.cookies) for (const [name, cookie] of Object.entries(finished.cookies)) response.setCookie(name, cookie.value, cookie.options);
 		if (finished?.type === "redirect") {
+			response.setStatus(finished.status ?? 302);
 			response.setHeader("location", finished.value);
-			return { status: finished.status ?? 302 };
+			return "";
+		}
+		if (finished) {
+			if (finished.status) response.setStatus(finished.status);
+			return finished.value;
 		}
-		if (finished) return finished.value;
 		return { finished: true };
 	}
 	if (output.inputRequired) {
 		const outletReq = output.inputRequired;
 		const outletHandler = registry.get(outletReq.outlet);
-		if (!outletHandler) return {
-			error: `Unknown outlet: '${outletReq.outlet}'`,
-			status: 500
-		};
+		if (!outletHandler) {
+			response.setStatus(500);
+			return { error: `Unknown outlet: '${outletReq.outlet}'` };
+		}
 		const strategy = ctx.get(stateStrategyKey);
 		const stateWithMeta = {
 			...output.state,
 			meta: { outlet: outletReq.outlet }
 		};
 		const newToken = await strategy.persist(stateWithMeta, output.expires ? { ttl: output.expires - Date.now() } : void 0);
-		if (tokenWrite === "cookie") response.setCookie(tokenName, newToken, {
+		const outOfBand = outletHandler.tokenDelivery === "out-of-band";
+		if (tokenWrite === "cookie" && !outOfBand) response.setCookie(tokenName, newToken, {
 			httpOnly: true,
 			sameSite: "Strict",
 			path: "/"
 		});
 		const result = await outletHandler.deliver(outletReq, newToken);
-		if (tokenWrite === "body" && result?.response && typeof result.response === "object") return {
+		if (tokenWrite === "body" && !outOfBand && result?.response && typeof result.response === "object") return {
 			...result.response,
 			[tokenName]: newToken
 		};
@@ -251,6 +249,7 @@ async function handleWfOutletRequest(config, deps) {
 function createHttpOutlet(opts) {
 	return {
 		name: "http",
+		tokenDelivery: "caller",
 		async deliver(request, _token) {
 			const body = opts?.transform ? opts.transform(request.payload, request.context) : typeof request.payload === "object" && request.payload !== null ? {
 				...request.payload,
@@ -279,6 +278,7 @@ function createHttpOutlet(opts) {
 function createEmailOutlet(send) {
 	return {
 		name: "email",
+		tokenDelivery: "out-of-band",
 		async deliver(request, token) {
 			await send({
 				target: request.target ?? "",
@@ -316,7 +316,7 @@ function createOutletHandler(wfApp) {
 }
 
 //#endregion
-//#region node_modules/.pnpm/@prostojs+wf@0.1.1/node_modules/@prostojs/wf/dist/outlets/index.mjs
+//#region node_modules/.pnpm/@prostojs+wf@0.2.0/node_modules/@prostojs/wf/dist/outlets/index.mjs
 /**
 * Generic outlet request. Use for custom outlets.
 *
@@ -368,6 +368,29 @@ function outletEmail(target, template, context) {
 *
 * Token format: `base64url(iv[12] + authTag[16] + ciphertext)`
 *
+* ## Security warning — replay
+*
+* This strategy is STATELESS. It cannot enforce single-use semantics:
+* `consume()` is a no-op alias for `retrieve()` because there is no
+* server-side record to delete. Anyone who obtains a copy of the token
+* (browser history, server logs, shoulder-surfing, intermediate proxy,
+* shared device) can replay it until the TTL expires.
+*
+* Use `EncapsulatedStateStrategy` ONLY when BOTH of the following hold:
+*
+* 1. Every workflow step is idempotent — re-executing a step with the same
+*    input produces no harmful side effects (pure data collection,
+*    validation-only steps).
+* 2. The flow is not security-sensitive — no credential changes, financial
+*    operations, account provisioning, permission grants, or any other
+*    privileged action.
+*
+* For auth flows (login, password reset, invite accept), financial
+* operations, or anything with meaningful side effects, use
+* `HandleStateStrategy` with a durable `WfStateStore`. `HandleStateStrategy`
+* supports true single-use tokens via atomic `getAndDelete` at the store
+* layer.
+*
 * @example
 * const strategy = new EncapsulatedStateStrategy({
 *     secret: crypto.randomBytes(32),
@@ -410,7 +433,14 @@ var EncapsulatedStateStrategy = class {
 	async retrieve(token) {
 		return this.decrypt(token);
 	}
-	/** Same as retrieve (stateless — cannot truly invalidate a token). */
+	/**
+	* Stateless — CANNOT invalidate the token. Returns identical result to
+	* `retrieve()`. See the class-level security warning.
+	*
+	* This method exists only to satisfy the `WfStateStrategy` contract.
+	* Callers that need true single-use semantics must use
+	* `HandleStateStrategy`.
+	*/
 	async consume(token) {
 		return this.decrypt(token);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-wf",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "description": "@wooksjs/event-wf",
   "keywords": [
     "app",
@@ -37,22 +37,22 @@
     }
   },
   "dependencies": {
-    "@prostojs/wf": "^0.1.1"
+    "@prostojs/wf": "^0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@wooksjs/event-core": "^0.7.9",
-    "@wooksjs/event-http": "^0.7.9",
-    "@wooksjs/http-body": "^0.7.9",
-    "wooks": "^0.7.9"
+    "@wooksjs/event-core": "^0.7.11",
+    "@wooksjs/event-http": "^0.7.11",
+    "@wooksjs/http-body": "^0.7.11",
+    "wooks": "^0.7.11"
   },
   "peerDependencies": {
     "@prostojs/logger": "^0.4.3",
-    "@wooksjs/event-core": "^0.7.9",
-    "@wooksjs/event-http": "^0.7.9",
-    "@wooksjs/http-body": "^0.7.9",
-    "wooks": "^0.7.9"
+    "@wooksjs/event-core": "^0.7.11",
+    "@wooksjs/event-http": "^0.7.11",
+    "@wooksjs/http-body": "^0.7.11",
+    "wooks": "^0.7.11"
   },
   "peerDependenciesMeta": {
     "@wooksjs/event-http": {