[world-local] Implement Hook "token" uniqueness validation (#295)

TooTallNate · web-flow · commit 2b880f90cb66 · 2025-11-10T15:16:05.000-08:00
Signed-off-by: Nathan Rajlich &lt;n@n8.io&gt;
diff --git a/.changeset/busy-ears-switch.md b/.changeset/busy-ears-switch.md
@@ -0,0 +1,5 @@
+---
+"@workflow/world-local": patch
+---
+
+Enforce uniqueness on hook "token" values
diff --git a/packages/world-local/src/storage.test.ts b/packages/world-local/src/storage.test.ts
@@ -927,6 +927,106 @@ describe('Storage', () => {
           .catch(() => false);
         expect(fileExists).toBe(true);
       });
+
+      it('should throw error when creating a hook with a duplicate token', async () => {
+        // Create first hook with a token
+        const hookData = {
+          hookId: 'hook_1',
+          token: 'duplicate-test-token',
+        };
+
+        await storage.hooks.create(testRunId, hookData);
+
+        // Try to create another hook with the same token
+        const duplicateHookData = {
+          hookId: 'hook_2',
+          token: 'duplicate-test-token',
+        };
+
+        await expect(
+          storage.hooks.create(testRunId, duplicateHookData)
+        ).rejects.toThrow(
+          'Hook with token duplicate-test-token already exists for this project'
+        );
+      });
+
+      it('should allow multiple hooks with different tokens for the same run', async () => {
+        const hook1 = await storage.hooks.create(testRunId, {
+          hookId: 'hook_1',
+          token: 'token-1',
+        });
+
+        const hook2 = await storage.hooks.create(testRunId, {
+          hookId: 'hook_2',
+          token: 'token-2',
+        });
+
+        expect(hook1.token).toBe('token-1');
+        expect(hook2.token).toBe('token-2');
+      });
+
+      it('should allow the same token only after disposing the previous hook', async () => {
+        const token = 'reusable-token';
+
+        // Create first hook
+        const hook1 = await storage.hooks.create(testRunId, {
+          hookId: 'hook_1',
+          token,
+        });
+
+        expect(hook1.token).toBe(token);
+
+        // Try to create another hook with the same token - should fail
+        await expect(
+          storage.hooks.create(testRunId, {
+            hookId: 'hook_2',
+            token,
+          })
+        ).rejects.toThrow(
+          `Hook with token ${token} already exists for this project`
+        );
+
+        // Dispose the first hook
+        await storage.hooks.dispose('hook_1');
+
+        // Now we should be able to create a new hook with the same token
+        const hook2 = await storage.hooks.create(testRunId, {
+          hookId: 'hook_2',
+          token,
+        });
+
+        expect(hook2.token).toBe(token);
+        expect(hook2.hookId).toBe('hook_2');
+      });
+
+      it('should enforce token uniqueness across different runs within the same project', async () => {
+        // Create a second run
+        const run2 = await storage.runs.create({
+          deploymentId: 'deployment-456',
+          workflowName: 'another-workflow',
+          input: [],
+        });
+
+        const token = 'shared-token-across-runs';
+
+        // Create hook in first run
+        const hook1 = await storage.hooks.create(testRunId, {
+          hookId: 'hook_1',
+          token,
+        });
+
+        expect(hook1.token).toBe(token);
+
+        // Try to create hook with same token in second run - should fail
+        await expect(
+          storage.hooks.create(run2.runId, {
+            hookId: 'hook_2',
+            token,
+          })
+        ).rejects.toThrow(
+          `Hook with token ${token} already exists for this project`
+        );
+      });
     });
 
     describe('get', () => {
diff --git a/packages/world-local/src/storage.ts b/packages/world-local/src/storage.ts
@@ -1,10 +1,14 @@
 import path from 'node:path';
 import { WorkflowRunNotFoundError } from '@workflow/errors';
 import {
+  type CreateHookRequest,
   type Event,
   EventSchema,
+  type GetHookParams,
   type Hook,
   HookSchema,
+  type ListHooksParams,
+  type PaginatedResponse,
   type Step,
   StepSchema,
   type Storage,
@@ -94,6 +98,123 @@ const getObjectCreatedAt =
     return ulidToDate(ulid);
   };
 
+/**
+ * Creates a hooks storage implementation using the filesystem.
+ * Implements the Storage['hooks'] interface with hook CRUD operations.
+ */
+function createHooksStorage(basedir: string): Storage['hooks'] {
+  // Helper function to find a hook by token (shared between create and getByToken)
+  async function findHookByToken(token: string): Promise<Hook | null> {
+    const hooksDir = path.join(basedir, 'hooks');
+    const files = await listJSONFiles(hooksDir);
+
+    for (const file of files) {
+      const hookPath = path.join(hooksDir, `${file}.json`);
+      const hook = await readJSON(hookPath, HookSchema);
+      if (hook && hook.token === token) {
+        return hook;
+      }
+    }
+
+    return null;
+  }
+
+  async function create(runId: string, data: CreateHookRequest): Promise<Hook> {
+    // Check if a hook with the same token already exists
+    // Token uniqueness is enforced globally per embedded environment
+    const existingHook = await findHookByToken(data.token);
+    if (existingHook) {
+      throw new Error(
+        `Hook with token ${data.token} already exists for this project`
+      );
+    }
+
+    const now = new Date();
+
+    const result = {
+      runId,
+      hookId: data.hookId,
+      token: data.token,
+      metadata: data.metadata,
+      ownerId: 'embedded-owner',
+      projectId: 'embedded-project',
+      environment: 'embedded',
+      createdAt: now,
+    } as Hook;
+
+    const hookPath = path.join(basedir, 'hooks', `${data.hookId}.json`);
+    await writeJSON(hookPath, result);
+    return result;
+  }
+
+  async function get(hookId: string, params?: GetHookParams): Promise<Hook> {
+    const hookPath = path.join(basedir, 'hooks', `${hookId}.json`);
+    const hook = await readJSON(hookPath, HookSchema);
+    if (!hook) {
+      throw new Error(`Hook ${hookId} not found`);
+    }
+    const resolveData = params?.resolveData || DEFAULT_RESOLVE_DATA_OPTION;
+    return filterHookData(hook, resolveData);
+  }
+
+  async function getByToken(token: string): Promise<Hook> {
+    const hook = await findHookByToken(token);
+    if (!hook) {
+      throw new Error(`Hook with token ${token} not found`);
+    }
+    return hook;
+  }
+
+  async function list(
+    params: ListHooksParams
+  ): Promise<PaginatedResponse<Hook>> {
+    const hooksDir = path.join(basedir, 'hooks');
+    const resolveData = params.resolveData || DEFAULT_RESOLVE_DATA_OPTION;
+
+    const result = await paginatedFileSystemQuery({
+      directory: hooksDir,
+      schema: HookSchema,
+      sortOrder: params.pagination?.sortOrder,
+      limit: params.pagination?.limit,
+      cursor: params.pagination?.cursor,
+      filePrefix: undefined, // Hooks don't have ULIDs, so we can't optimize by filename
+      filter: (hook) => {
+        // Filter by runId if provided
+        if (params.runId && hook.runId !== params.runId) {
+          return false;
+        }
+        return true;
+      },
+      getCreatedAt: () => {
+        // Hook files don't have ULID timestamps in filename
+        // We need to read the file to get createdAt, but that's inefficient
+        // So we return the hook's createdAt directly (item.createdAt will be used for sorting)
+        // Return a dummy date to pass the null check, actual sorting uses item.createdAt
+        return new Date(0);
+      },
+      getId: (hook) => hook.hookId,
+    });
+
+    // Transform the data after pagination
+    return {
+      ...result,
+      data: result.data.map((hook) => filterHookData(hook, resolveData)),
+    };
+  }
+
+  async function dispose(hookId: string): Promise<Hook> {
+    const hookPath = path.join(basedir, 'hooks', `${hookId}.json`);
+    const hook = await readJSON(hookPath, HookSchema);
+    if (!hook) {
+      throw new Error(`Hook ${hookId} not found`);
+    }
+    await deleteJSON(hookPath);
+    return hook;
+  }
+
+  return { create, get, getByToken, list, dispose };
+}
+
 export function createStorage(basedir: string): Storage {
   return {
     runs: {
@@ -415,97 +536,6 @@ export function createStorage(basedir: string): Storage {
     },
 
     // Hooks
-    hooks: {
-      async create(runId, data) {
-        const now = new Date();
-
-        const result = {
-          runId,
-          hookId: data.hookId,
-          token: data.token,
-          metadata: data.metadata,
-          ownerId: 'embedded-owner',
-          projectId: 'embedded-project',
-          environment: 'embedded',
-          createdAt: now,
-        } as Hook;
-
-        const hookPath = path.join(basedir, 'hooks', `${data.hookId}.json`);
-        await writeJSON(hookPath, result);
-        return result;
-      },
-
-      async get(hookId, params) {
-        const hookPath = path.join(basedir, 'hooks', `${hookId}.json`);
-        // Try webhook schema first (which includes response), fall back to HookSchema
-        const hook = await readJSON(hookPath, HookSchema);
-        if (!hook) {
-          throw new Error(`Hook ${hookId} not found`);
-        }
-        const resolveData = params?.resolveData || DEFAULT_RESOLVE_DATA_OPTION;
-        return filterHookData(hook, resolveData);
-      },
-
-      async getByToken(token) {
-        // Need to search through all hooks to find one with matching token
-        const hooksDir = path.join(basedir, 'hooks');
-        const files = await listJSONFiles(hooksDir);
-
-        for (const file of files) {
-          const hookPath = path.join(hooksDir, `${file}.json`);
-          const hook = await readJSON(hookPath, HookSchema);
-          if (hook && hook.token === token) {
-            return hook;
-          }
-        }
-
-        throw new Error(`Hook with token ${token} not found`);
-      },
-
-      async list(params) {
-        const hooksDir = path.join(basedir, 'hooks');
-        const resolveData = params.resolveData || DEFAULT_RESOLVE_DATA_OPTION;
-
-        const result = await paginatedFileSystemQuery({
-          directory: hooksDir,
-          schema: HookSchema,
-          sortOrder: params.pagination?.sortOrder,
-          limit: params.pagination?.limit,
-          cursor: params.pagination?.cursor,
-          filePrefix: undefined, // Hooks don't have ULIDs, so we can't optimize by filename
-          filter: (hook) => {
-            // Filter by runId if provided
-            if (params.runId && hook.runId !== params.runId) {
-              return false;
-            }
-            return true;
-          },
-          getCreatedAt: () => {
-            // Hook files don't have ULID timestamps in filename
-            // We need to read the file to get createdAt, but that's inefficient
-            // So we return the hook's createdAt directly (item.createdAt will be used for sorting)
-            // Return a dummy date to pass the null check, actual sorting uses item.createdAt
-            return new Date(0);
-          },
-          getId: (hook) => hook.hookId,
-        });
-
-        // Transform the data after pagination
-        return {
-          ...result,
-          data: result.data.map((hook) => filterHookData(hook, resolveData)),
-        };
-      },
-
-      async dispose(hookId) {
-        const hookPath = path.join(basedir, 'hooks', `${hookId}.json`);
-        const hook = await readJSON(hookPath, HookSchema);
-        if (!hook) {
-          throw new Error(`Hook ${hookId} not found`);
-        }
-        await deleteJSON(hookPath);
-        return hook;
-      },
-    },
+    hooks: createHooksStorage(basedir),
   };
 }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@workflow/world-local": patch
 +---
++
 +Enforce uniqueness on hook "token" values