@wooksjs/event-wf 0.7.8 → 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.8",
+  "version": "0.7.10",
   "description": "@wooksjs/event-wf",
   "keywords": [
     "app",
@@ -22,13 +22,8 @@
     "url": "git+https://github.com/wooksjs/wooksjs.git",
     "directory": "packages/event-wf"
   },
-  "bin": {
-    "wooksjs-event-wf-skill": "scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts"
+    "dist"
   ],
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -42,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.8",
-    "@wooksjs/event-http": "^0.7.8",
-    "wooks": "^0.7.8",
-    "@wooksjs/http-body": "^0.7.8"
+    "@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.8",
-    "@wooksjs/event-http": "^0.7.8",
-    "wooks": "^0.7.8",
-    "@wooksjs/http-body": "^0.7.8"
+    "@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": {
@@ -68,7 +63,6 @@
     }
   },
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs",
-    "setup-skills": "node scripts/setup-skills.js"
+    "build": "rolldown -c ../../rolldown.config.mjs"
   }
 }

package/scripts/setup-skills.js

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-'use strict'
-
-const fs = require('fs')
-const path = require('path')
-const os = require('os')
-
-const SKILL_NAME = 'wooksjs-event-wf'
-const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
-
-if (!fs.existsSync(SKILL_SRC)) {
-  console.error(`No skills found at ${SKILL_SRC}`)
-  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
-  process.exit(1)
-}
-
-const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
-}
-
-const args = process.argv.slice(2)
-const isGlobal = args.includes('--global') || args.includes('-g')
-const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
-const installedDirs = []
-
-for (const [agentName, cfg] of Object.entries(AGENTS)) {
-  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
-  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
-
-  // In postinstall mode: silently skip agents that aren't set up globally
-  if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
-  }
-
-  const dest = path.join(targetBase, SKILL_NAME)
-  try {
-    fs.mkdirSync(dest, { recursive: true })
-    fs.cpSync(SKILL_SRC, dest, { recursive: true })
-    console.log(`✅  ${agentName}: installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
-  }
-}
-
-// Add locally-installed skill dirs to .gitignore
-if (!isGlobal && installedDirs.length > 0) {
-  const gitignorePath = path.join(process.cwd(), '.gitignore')
-  let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
-  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
-  if (linesToAdd.length > 0) {
-    const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
-    fs.appendFileSync(gitignorePath, block)
-    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
-  }
-}
-
-if (installed === 0 && isPostinstall) {
-  // Silence is fine — no agents present, nothing to do
-} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
-} else if (installed === 0) {
-  console.log('Nothing installed. Run without --global to install project-locally.')
-} else {
-  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

package/skills/wooksjs-event-wf/SKILL.md

@@ -1,42 +0,0 @@
----
-name: wooksjs-event-wf
-description: Wooks Workflow framework — composable, step-based workflow engine for Node.js. Load when building workflow/process automation with wooks; defining workflow steps and flows; using workflow composables (useWfState, useRouteParams, useLogger); working with @wooksjs/event-core context (key, cached, defineWook, defineEventKind); creating conditional and looping flows; resuming paused workflows; handling user input requirements; using string-based step handlers; attaching workflow spies; working with StepRetriableError; creating custom event context composables for workflows; sharing parent event context (eventContext) for HTTP integration; accessing HTTP composables from workflow steps.
----
-
-# @wooksjs/event-wf
-
-A composable workflow framework for Node.js built on async context (AsyncLocalStorage) and `@prostojs/wf`. Define steps and flows as composable units — steps execute sequentially with conditional branching, loops, pause/resume, and user input handling. Context is scoped per workflow execution.
-
-## How to use this skill
-
-Read the domain file that matches the task. Do not load all files — only what you need.
-
-| Domain                         | File                           | Load when...                                                                                                                                                                                 |
-| ------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Event context (core machinery) | [event-core.md](event-core.md) | Understanding `EventContext`, `key()`/`cached()`/`defineWook()`/`defineEventKind()`/`slot()`, creating custom composables, lazy evaluation and caching, building your own `use*()` functions |
-| Workflow app setup             | [core.md](core.md)             | Creating a workflow app, `createWfApp`, starting/resuming workflows, error handling, spies, testing, logging, sharing parent event context (`eventContext`), HTTP integration                |
-| Steps & flows                  | [workflows.md](workflows.md)   | Defining steps (`app.step`), defining flows (`app.flow`), workflow schemas, conditions, loops, user input, parametric steps, `useWfState`, `StepRetriableError`, string-based handlers       |
-
-## Quick reference
-
-```ts
-import { createWfApp } from '@wooksjs/event-wf'
-
-const app = createWfApp<{ result: number }>()
-
-app.step('add', {
-  input: 'number',
-  handler: 'ctx.result += input',
-})
-
-app.flow('calculate', [
-  { id: 'add', input: 5 },
-  { id: 'add', input: 2 },
-  { condition: 'result < 10', steps: [{ id: 'add', input: 3 }] },
-])
-
-const output = await app.start('calculate', { result: 0 })
-console.log(output.state.context) // { result: 10 }
-```
-
-Key exports: `createWfApp()`, `useWfState()`, `useRouteParams()`, `useLogger()`, `StepRetriableError`.