@wooksjs/event-wf 0.7.9 → 0.7.10

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,15 +167,11 @@ 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);
+		const state = await strategy.consume(token);
 		if (!state) return {
 			error: "Invalid or expired workflow state",
 			status: 400
@@ -185,8 +180,6 @@ async function handleWfOutletRequest(config, deps) {
 			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
@@ -238,13 +231,14 @@ async function handleWfOutletRequest(config, deps) {
 			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 +268,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 +297,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 +335,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 +387,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 +452,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,15 +144,11 @@ 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);
+		const state = await strategy.consume(token);
 		if (!state) return {
 			error: "Invalid or expired workflow state",
 			status: 400
@@ -162,8 +157,6 @@ async function handleWfOutletRequest(config, deps) {
 			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
@@ -215,13 +208,14 @@ async function handleWfOutletRequest(config, deps) {
 			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 +245,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 +274,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 +312,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 +364,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 +429,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.10",
   "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-http": "^0.7.10",
+    "@wooksjs/event-core": "^0.7.10",
+    "wooks": "^0.7.10",
+    "@wooksjs/http-body": "^0.7.10"
   },
   "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.10",
+    "@wooksjs/event-http": "^0.7.10",
+    "@wooksjs/http-body": "^0.7.10",
+    "wooks": "^0.7.10"
   },
   "peerDependenciesMeta": {
     "@wooksjs/event-http": {