Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,30 @@
import { describe, expect, it } from "vitest";
import { readRepoFile } from "~/utils/testing/repoPaths";
import { WORKFLOW_API_ERROR_FALLBACKS, workflowApiText } from "./workflowApiErrors.server";
function readEnTranslations() {
return JSON.parse(readRepoFile("apps/web/public/locales/en/translations.json")) as Record<string, unknown>;
}
function getTranslationValue(source: Record<string, unknown>, key: string): unknown {
return key.split(".").reduce<unknown>((current, segment) => {
if (!current || typeof current !== "object") return undefined;
return (current as Record<string, unknown>)[segment];
}, source);
}
describe("workflowApiErrors", () => {
it("keeps API fallback text aligned with the English locale", () => {
const en = readEnTranslations();
for (const [key, fallback] of Object.entries(WORKFLOW_API_ERROR_FALLBACKS)) {
expect(getTranslationValue(en, key), key).toBe(fallback);
}
});
it("resolves workflow API text from the fallback map", () => {
const t = (key: string, options?: { defaultValue?: string }) => `${key}:${options?.defaultValue ?? ""}`;
expect(workflowApiText(t, "workflows.errors.invalidJsonBody")).toBe("workflows.errors.invalidJsonBody:Invalid JSON body.");
});
});
@@ -0,0 +1,49 @@
import type { TFunction } from "i18next";
import type { WorkflowApiAccessValidation } from "~/utils/services/apiService";
const REDACTED = "[REDACTED]";
export const WORKFLOW_API_ERROR_FALLBACKS = {
"workflows.errors.executionIdRequired": "Execution ID is required",
"workflows.errors.executionNotFound": "Execution not found",
"workflows.errors.idempotencyKeyConflict": "Idempotency-Key was already used for a different workflow trigger request.",
"workflows.errors.idempotencyKeyInProgress": "Idempotency-Key is already being processed.",
"workflows.errors.idempotencyKeyRequired": "Idempotency-Key header is required.",
"workflows.errors.invalidAction": "Invalid action",
"workflows.errors.invalidJsonBody": "Invalid JSON body.",
"workflows.errors.methodNotAllowed": "Method not allowed.",
"workflows.errors.tenantIdRequired": "Account context is required.",
"workflows.errors.workflowNotFound": "Workflow not found",
} as const;
export function workflowApiText(t: TFunction, key: keyof typeof WORKFLOW_API_ERROR_FALLBACKS) {
const defaultValue = WORKFLOW_API_ERROR_FALLBACKS[key];
return t(key, { defaultValue });
}
export function requireWorkflowTenant(apiAccessValidation: WorkflowApiAccessValidation, t: TFunction): NonNullable<WorkflowApiAccessValidation["tenant"]> {
if (!apiAccessValidation.tenant?.id) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.tenantIdRequired")), { status: 400 });
}
return apiAccessValidation.tenant;
}
export function getWorkflowErrorAccess(apiAccessValidation: WorkflowApiAccessValidation | undefined, error: any): WorkflowApiAccessValidation | undefined {
return apiAccessValidation ?? (error.apiKeyLog ? { tenant: null, apiKeyLog: error.apiKeyLog } : undefined);
}
export function redactWorkflowApiErrorMessage(request: Request, message: unknown) {
let redacted = message instanceof Error ? message.message : String(message ?? "");
for (const value of getSensitiveRequestValues(request)) {
redacted = redacted.split(value).join(REDACTED);
}
return redacted;
}
function getSensitiveRequestValues(request: Request) {
const authorization = request.headers.get("Authorization")?.trim() ?? "";
const bearerToken = authorization.replace(/^Bearer\s+/i, "").trim();
return [authorization, bearerToken, request.headers.get("X-Api-Key")?.trim() ?? "", process.env.API_ACCESS_TOKEN ?? ""]
.filter((value) => value.length >= 8)
.sort((left, right) => right.length - left.length);
}
@@ -0,0 +1,971 @@
import type { ActionFunctionArgs, LoaderFunctionArgs } from "react-router";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { createInternalWebApiProxyHeaders } from "~/utils/api/internalWebApiProxy.server";
export { describe, expect, it, vi };
const globalMockStoreKey = "__apiWorkflowAuthTestMocks__";
const globalMockStore = globalThis as typeof globalThis & {
__apiWorkflowAuthTestMocks__?: {
validateApiKey: ReturnType<typeof vi.fn>;
setApiKeyLogStatus: ReturnType<typeof vi.fn>;
execute: ReturnType<typeof vi.fn>;
executeExisting: ReturnType<typeof vi.fn>;
queueApiExecution: ReturnType<typeof vi.fn>;
queueContinuationExecution: ReturnType<typeof vi.fn>;
continueExecution: ReturnType<typeof vi.fn>;
getExecution: ReturnType<typeof vi.fn>;
eventStream: ReturnType<typeof vi.fn>;
emitterOn: ReturnType<typeof vi.fn>;
emitterOff: ReturnType<typeof vi.fn>;
idempotencyKey: {
findUnique: ReturnType<typeof vi.fn>;
create: ReturnType<typeof vi.fn>;
update: ReturnType<typeof vi.fn>;
deleteMany: ReturnType<typeof vi.fn>;
};
};
};
globalMockStore.__apiWorkflowAuthTestMocks__ ??= {
validateApiKey: vi.fn(),
setApiKeyLogStatus: vi.fn(),
execute: vi.fn(),
executeExisting: vi.fn(),
queueApiExecution: vi.fn(),
queueContinuationExecution: vi.fn(),
continueExecution: vi.fn(),
getExecution: vi.fn(),
eventStream: vi.fn(),
emitterOn: vi.fn(),
emitterOff: vi.fn(),
idempotencyKey: {
findUnique: vi.fn(),
create: vi.fn(),
update: vi.fn(),
deleteMany: vi.fn(),
},
};
const mocks = globalMockStore[globalMockStoreKey];
vi.mock("@toolctrl/db/api-keys.server", () => ({
setLegacyApiKeyLogStatus: mocks.setApiKeyLogStatus,
}));
vi.mock("~/modules/workflowEngine/services/WorkflowsExecutionsService", () => ({
default: {
execute: mocks.execute,
executeExisting: mocks.executeExisting,
queueApiExecution: mocks.queueApiExecution,
queueContinuationExecution: mocks.queueContinuationExecution,
continueExecution: mocks.continueExecution,
},
}));
vi.mock("~/modules/workflowEngine/services/WorkflowsService", () => ({
default: {
getExecution: mocks.getExecution,
},
}));
vi.mock("~/utils/services/apiService", () => ({
validateApiKey: mocks.validateApiKey,
getWorkflowApiKeyFromRequest: async (request: Request, params: Record<string, string>) => {
const apiAccessValidation = (await mocks.validateApiKey(request, params)) as {
tenant: unknown;
userId?: string;
tenantApiKey?: { apiKeyLog?: unknown; usage?: unknown };
};
return {
tenant: apiAccessValidation.tenant,
userId: apiAccessValidation.userId,
apiKeyLog: apiAccessValidation.tenantApiKey?.apiKeyLog,
usage: apiAccessValidation.tenantApiKey?.usage,
};
},
setWorkflowApiKeyLogStatus: async (
apiAccessValidation: { apiKeyLog?: { id: string; tenantId?: string }; tenant?: { id: string } | null } | undefined,
data: Record<string, unknown>
) => {
if (!apiAccessValidation?.apiKeyLog) {
return;
}
const tenantId = apiAccessValidation.apiKeyLog.tenantId ?? apiAccessValidation.tenant?.id;
await mocks.setApiKeyLogStatus({ id: apiAccessValidation.apiKeyLog.id, tenantId }, data);
},
}));
vi.mock("~/utils/stream/emitter.server", () => ({
emitter: {
on: mocks.emitterOn,
off: mocks.emitterOff,
},
}));
vi.mock("~/utils/stream/event-stream", () => ({
eventStream: mocks.eventStream,
}));
vi.mock("~/utils/db.server", () => ({
db: {
idempotencyKey: mocks.idempotencyKey,
},
}));
vi.mock("~/locale/i18next.server", () => ({
getTranslations: vi.fn(async () => ({
t: (key: string, options?: { defaultValue?: string }) => `[${key}] ${options?.defaultValue ?? key}`,
})),
}));
const tenant = { id: "tenant_1", name: "Acme", slug: "acme", deactivatedReason: null };
const tenantApiKey = { apiKeyLog: { id: "api_key_log_1", tenantId: tenant.id }, apiKey: { id: "api_key_1", tenantId: tenant.id }, usage: undefined };
const workflowExecution = { id: "execution_1", workflowId: "workflow_1", tenantId: tenant.id, status: "running" };
const translated = {
executionNotFound: "[workflows.errors.executionNotFound] Execution not found",
idempotencyKeyConflict: "[workflows.errors.idempotencyKeyConflict] Idempotency-Key was already used for a different workflow trigger request.",
idempotencyKeyRequired: "[workflows.errors.idempotencyKeyRequired] Idempotency-Key header is required.",
invalidJsonBody: "[workflows.errors.invalidJsonBody] Invalid JSON body.",
methodNotAllowed: "[workflows.errors.methodNotAllowed] Method not allowed.",
tenantIdRequired: "[workflows.errors.tenantIdRequired] Account context is required.",
};
function resetIdempotencyStore() {
type StoredIdempotencyRow = {
scope: string;
key: string;
requestHash: string;
responseStatus: number;
responseBody: unknown;
responseHeaders: Record<string, string> | null;
createdAt: Date;
expiresAt: Date | null;
};
const rows = new Map<string, StoredIdempotencyRow>();
const rowKey = (scope: string, key: string) => `${scope}:${key}`;
mocks.idempotencyKey.findUnique.mockImplementation(async ({ where }) => {
const { scope, key } = where.idempotency_key_scope_key;
return rows.get(rowKey(scope, key)) ?? null;
});
mocks.idempotencyKey.create.mockImplementation(async ({ data }) => {
const key = rowKey(data.scope, data.key);
if (rows.has(key)) {
throw Object.assign(new Error("Unique constraint failed"), { code: "P2002" });
}
const row = { ...data, createdAt: new Date(), expiresAt: data.expiresAt ?? null };
rows.set(key, row);
return row;
});
mocks.idempotencyKey.update.mockImplementation(async ({ where, data }) => {
const { scope, key } = where.idempotency_key_scope_key;
const existing = rows.get(rowKey(scope, key));
if (!existing) {
throw new Error("Idempotency row not found");
}
const row = { ...existing, ...data };
rows.set(rowKey(scope, key), row);
return row;
});
mocks.idempotencyKey.deleteMany.mockImplementation(async ({ where } = {}) => {
for (const [key, row] of rows.entries()) {
if (where?.scope && row.scope !== where.scope) continue;
if (where?.key && row.key !== where.key) continue;
if (where?.expiresAt?.lte && (!row.expiresAt || row.expiresAt > where.expiresAt.lte)) continue;
rows.delete(key);
}
return { count: 0 };
});
}
function makeRequest(method: string, body?: unknown, headers: HeadersInit = {}) {
const canHaveBody = method !== "GET" && method !== "HEAD" && body !== undefined;
const request = new Request("https://example.com/internal/api/workflows", {
method,
body: canHaveBody ? JSON.stringify(body) : undefined,
headers: {
...(canHaveBody ? { "Content-Type": "application/json" } : {}),
...headers,
},
});
return withInternalProxyHeaders(request);
}
function withInternalProxyHeaders(request: Request) {
for (const [name, value] of Object.entries(createInternalWebApiProxyHeaders(request, "test-api-access-token"))) {
request.headers.set(name, value);
}
return request;
}
async function callRunAction(method = "POST", body: unknown = { name: "Ada" }, headers: HeadersInit = {}) {
const { action } = await import("./workflows.run.$id");
return action({
request: makeRequest(method, body, headers),
params: { id: "workflow_1" },
context: {},
} as unknown as ActionFunctionArgs) as Promise<Response>;
}
async function callTriggerAction(
method = "POST",
body: unknown = { event: "row.created" },
idempotencyKey: string | null = "workflow-trigger:evt_1:workflow_1:tenant_1"
) {
const { action } = await import("./workflows.trigger.$id");
const canHaveBody = method !== "GET" && method !== "HEAD" && body !== undefined;
const request = new Request("https://example.com/internal/api/workflows/trigger/workflow_1?tenantId=tenant_1", {
method,
body: canHaveBody ? JSON.stringify(body) : undefined,
headers: {
...(canHaveBody ? { "Content-Type": "application/json" } : {}),
...(idempotencyKey === null ? {} : { "Idempotency-Key": idempotencyKey }),
},
});
return action({
request: withInternalProxyHeaders(request),
params: { id: "workflow_1" },
context: {},
} as unknown as ActionFunctionArgs) as Promise<Response>;
}
async function callExecutionStartAction(
method = "POST",
body: unknown = { workflowId: "workflow_1", type: "manual", input: { approved: true }, userId: "user_1" },
idempotencyKey: string | null = "workflow-execution:evt_1:execution_1:tenant_1"
) {
const { action } = await import("./workflows.executions.$id.start");
const canHaveBody = method !== "GET" && method !== "HEAD" && body !== undefined;
const request = new Request("https://example.com/internal/api/workflows/executions/execution_1/start?tenantId=tenant_1", {
method,
body: canHaveBody ? JSON.stringify(body) : undefined,
headers: {
...(canHaveBody ? { "Content-Type": "application/json" } : {}),
...(idempotencyKey === null ? {} : { "Idempotency-Key": idempotencyKey }),
},
});
return action({
request: withInternalProxyHeaders(request),
params: { id: "execution_1" },
context: {},
} as unknown as ActionFunctionArgs) as Promise<Response>;
}
async function callExecutionContinuationStartAction(
method = "POST",
body: unknown = { workflowId: "workflow_1", type: "api", input: { approved: true }, userId: "user_1" },
idempotencyKey: string | null = "workflow-continuation:evt_1:execution_1:tenant_1"
) {
const { action } = await import("./workflows.executions.$id.continue.start");
const canHaveBody = method !== "GET" && method !== "HEAD" && body !== undefined;
const request = new Request("https://example.com/internal/api/workflows/executions/execution_1/continue/start?tenantId=tenant_1", {
method,
body: canHaveBody ? JSON.stringify(body) : undefined,
headers: {
...(canHaveBody ? { "Content-Type": "application/json" } : {}),
...(idempotencyKey === null ? {} : { "Idempotency-Key": idempotencyKey }),
},
});
return action({
request: withInternalProxyHeaders(request),
params: { id: "execution_1" },
context: {},
} as unknown as ActionFunctionArgs) as Promise<Response>;
}
async function callContinueAction(method = "POST", body: unknown = { approved: true }, headers: HeadersInit = {}) {
const { action } = await import("./workflows.executions.$id.continue");
return action({
request: makeRequest(method, body, headers),
params: { id: "execution_1" },
context: {},
} as unknown as ActionFunctionArgs) as Promise<Response>;
}
async function callExecutionLoader(method = "GET", id = "execution_1", headers: HeadersInit = {}) {
const { loader } = await import("./workflows.executions.$id");
return loader({ request: makeRequest(method, undefined, headers), params: { id }, context: {} } as unknown as LoaderFunctionArgs) as Promise<Response>;
}
async function callStreamLoader(executionId = "execution_1", method = "GET", headers: HeadersInit = {}) {
const { loader } = await import("./workflows.stream.$executionId");
return loader({
request: makeRequest(method, undefined, headers),
params: { executionId },
context: {},
} as unknown as LoaderFunctionArgs) as Promise<Response>;
}
type InternalBridgeRouteCase = {
name: string;
params: Record<string, string>;
makeRequest: (headers?: HeadersInit) => Request;
call: (request: Request, params: Record<string, string>) => Promise<Response>;
};
function postBridgeRequest(url: string, body: unknown = {}): Request {
return new Request(url, {
method: "POST",
body: JSON.stringify(body),
headers: { "Content-Type": "application/json", "Idempotency-Key": "internal-bridge-boundary" },
});
}
function getBridgeRequest(url: string): Request {
return new Request(url, { method: "GET" });
}
function withHeaders(request: Request, headers: HeadersInit): Request {
const nextHeaders = new Headers(request.headers);
for (const [name, value] of new Headers(headers).entries()) {
nextHeaders.set(name, value);
}
return new Request(request, { headers: nextHeaders });
}
function forgedInternalProxyHeaders(): HeadersInit {
return {
"x-toolctrl-internal-web-api-proxy": "1",
"x-toolctrl-internal-web-api-proxy-signature": "forged",
};
}
function expectNoWorkflowBridgeSideEffects() {
expect(mocks.validateApiKey).not.toHaveBeenCalled();
expect(mocks.execute).not.toHaveBeenCalled();
expect(mocks.executeExisting).not.toHaveBeenCalled();
expect(mocks.queueApiExecution).not.toHaveBeenCalled();
expect(mocks.queueContinuationExecution).not.toHaveBeenCalled();
expect(mocks.continueExecution).not.toHaveBeenCalled();
expect(mocks.getExecution).not.toHaveBeenCalled();
expect(mocks.eventStream).not.toHaveBeenCalled();
expect(mocks.emitterOn).not.toHaveBeenCalled();
}
const internalBridgeRouteCases: InternalBridgeRouteCase[] = [
{
name: "workflow API run",
params: { id: "workflow_1" },
makeRequest: () => postBridgeRequest("https://example.com/internal/api/workflows/run/workflow_1", { name: "Ada" }),
call: async (request, params) => {
const { action } = await import("./workflows.run.$id");
return action({ request, params, context: {} } as unknown as ActionFunctionArgs) as Promise<Response>;
},
},
{
name: "workflow API continuation queue",
params: { id: "execution_1" },
makeRequest: () => postBridgeRequest("https://example.com/internal/api/workflows/executions/execution_1/continue", { approved: true }),
call: async (request, params) => {
const { action } = await import("./workflows.executions.$id.continue");
return action({ request, params, context: {} } as unknown as ActionFunctionArgs) as Promise<Response>;
},
},
{
name: "workflow execution read",
params: { id: "execution_1" },
makeRequest: () => getBridgeRequest("https://example.com/internal/api/workflows/executions/execution_1"),
call: async (request, params) => {
const { loader } = await import("./workflows.executions.$id");
return loader({ request, params, context: {} } as unknown as LoaderFunctionArgs) as Promise<Response>;
},
},
{
name: "workflow execution stream",
params: { executionId: "execution_1" },
makeRequest: () => getBridgeRequest("https://example.com/internal/api/workflows/stream/execution_1"),
call: async (request, params) => {
const { loader } = await import("./workflows.stream.$executionId");
return loader({ request, params, context: {} } as unknown as LoaderFunctionArgs) as Promise<Response>;
},
},
{
name: "workflow trigger callback",
params: { id: "workflow_1" },
makeRequest: () => postBridgeRequest("https://example.com/internal/api/workflows/trigger/workflow_1?tenantId=tenant_1", { event: "row.created" }),
call: async (request, params) => {
const { action } = await import("./workflows.trigger.$id");
return action({ request, params, context: {} } as unknown as ActionFunctionArgs) as Promise<Response>;
},
},
{
name: "workflow execution start",
params: { id: "execution_1" },
makeRequest: () =>
postBridgeRequest("https://example.com/internal/api/workflows/executions/execution_1/start?tenantId=tenant_1", {
workflowId: "workflow_1",
type: "manual",
input: { approved: true },
}),
call: async (request, params) => {
const { action } = await import("./workflows.executions.$id.start");
return action({ request, params, context: {} } as unknown as ActionFunctionArgs) as Promise<Response>;
},
},
{
name: "workflow continuation start",
params: { id: "execution_1" },
makeRequest: () =>
postBridgeRequest("https://example.com/internal/api/workflows/executions/execution_1/continue/start?tenantId=tenant_1", {
workflowId: "workflow_1",
type: "api",
input: { approved: true },
}),
call: async (request, params) => {
const { action } = await import("./workflows.executions.$id.continue.start");
return action({ request, params, context: {} } as unknown as ActionFunctionArgs) as Promise<Response>;
},
},
];
function expectSuccessLog(status: number) {
expect(mocks.setApiKeyLogStatus).toHaveBeenCalledWith(
{ id: tenantApiKey.apiKeyLog.id, tenantId: tenant.id },
expect.objectContaining({ status, startTime: expect.any(Number) })
);
}
function expectErrorLog(message: string, status: number) {
expect(mocks.setApiKeyLogStatus).toHaveBeenCalledWith(
{ id: tenantApiKey.apiKeyLog.id, tenantId: tenant.id },
expect.objectContaining({ error: message, status, startTime: expect.any(Number) })
);
}
describe("workflow API auth boundaries", () => {
beforeEach(() => {
vi.clearAllMocks();
vi.resetModules();
process.env.API_ACCESS_TOKEN = "test-api-access-token";
mocks.validateApiKey.mockResolvedValue({ tenant, userId: "user_1", tenantApiKey });
mocks.execute.mockResolvedValue(workflowExecution);
mocks.executeExisting.mockResolvedValue(workflowExecution);
mocks.queueApiExecution.mockResolvedValue({ ...workflowExecution, status: "running", type: "api" });
mocks.queueContinuationExecution.mockResolvedValue({ ...workflowExecution, status: "waiting", type: "api" });
mocks.continueExecution.mockResolvedValue(workflowExecution);
mocks.getExecution.mockResolvedValue(workflowExecution);
mocks.eventStream.mockImplementation((_signal: AbortSignal, init: (send: (args: { data: string }) => void) => () => void) => {
init(vi.fn());
return new Response("stream", { status: 200, headers: { "Content-Type": "text/event-stream" } });
});
mocks.setApiKeyLogStatus.mockResolvedValue(undefined);
resetIdempotencyStore();
});
it("queues workflow API runs with the authenticated tenant/user session and logs tenant API-key acceptance", async () => {
const response = await callRunAction("POST", { name: "Ada" });
expect(response.status).toBe(202);
await expect(response.json()).resolves.toEqual({ execution: { ...workflowExecution, status: "running", type: "api" } });
expect(mocks.validateApiKey).toHaveBeenCalledWith(expect.any(Request), { id: "workflow_1" });
expect(mocks.queueApiExecution).toHaveBeenCalledWith("workflow_1", {
input: { name: "Ada" },
session: { tenantId: tenant.id, userId: "user_1" },
});
expect(mocks.execute).not.toHaveBeenCalled();
expectSuccessLog(202);
});
it("logs workflow run queueing errors for tenant API keys", async () => {
mocks.queueApiExecution.mockRejectedValueOnce(Object.assign(new Error("Workflow not found"), { status: 404 }));
const response = await callRunAction();
expect(response.status).toBe(404);
await expect(response.json()).resolves.toEqual({ error: "Workflow not found" });
expectErrorLog("Workflow not found", 404);
});
it("does not run workflows for unsupported methods and logs the failure", async () => {
const response = await callRunAction("GET");
expect(response.status).toBe(405);
await expect(response.json()).resolves.toEqual({ error: translated.methodNotAllowed });
expect(mocks.queueApiExecution).not.toHaveBeenCalled();
expectErrorLog(translated.methodNotAllowed, 405);
});
it("rejects workflow run service tokens without tenant context", async () => {
mocks.validateApiKey.mockResolvedValueOnce({ tenant: null });
const response = await callRunAction();
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.tenantIdRequired });
expect(mocks.queueApiExecution).not.toHaveBeenCalled();
});
it("rejects invalid workflow run JSON before executing", async () => {
const { action } = await import("./workflows.run.$id");
const response = (await action({
request: withInternalProxyHeaders(
new Request("https://example.com/internal/api/workflows", { method: "POST", body: "{", headers: { "Content-Type": "application/json" } })
),
params: { id: "workflow_1" },
context: {},
} as unknown as ActionFunctionArgs)) as Response;
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.invalidJsonBody });
expect(mocks.queueApiExecution).not.toHaveBeenCalled();
expectErrorLog(translated.invalidJsonBody, 400);
});
it("redacts request auth tokens from workflow run error responses and API-key logs", async () => {
const secret = "workflow-route-secret-token";
mocks.validateApiKey.mockRejectedValueOnce(Object.assign(new Error(`Validation failed for ${secret}`), { status: 401, apiKeyLog: tenantApiKey.apiKeyLog }));
const response = await callRunAction("POST", { name: "Ada" }, { "X-Api-Key": secret });
expect(response.status).toBe(401);
await expect(response.json()).resolves.toEqual({ error: "Validation failed for [REDACTED]" });
expectErrorLog("Validation failed for [REDACTED]", 401);
expect(JSON.stringify(mocks.setApiKeyLogStatus.mock.calls)).not.toContain(secret);
});
it("rejects direct workflow web API calls without the internal API proxy header", async () => {
const { action } = await import("./workflows.run.$id");
await expect(
action({
request: new Request("https://example.com/internal/api/workflows", { method: "POST", body: "{}" }),
params: { id: "workflow_1" },
context: {},
} as unknown as ActionFunctionArgs)
).rejects.toMatchObject({ status: 404 });
expect(mocks.validateApiKey).not.toHaveBeenCalled();
});
it("rejects direct workflow web API calls with a forged internal proxy header", async () => {
const { action } = await import("./workflows.run.$id");
await expect(
action({
request: new Request("https://example.com/internal/api/workflows", {
method: "POST",
body: "{}",
headers: {
"x-toolctrl-internal-web-api-proxy": "1",
"x-toolctrl-internal-web-api-proxy-signature": "forged",
},
}),
params: { id: "workflow_1" },
context: {},
} as unknown as ActionFunctionArgs)
).rejects.toMatchObject({ status: 404 });
expect(mocks.validateApiKey).not.toHaveBeenCalled();
});
it.each(internalBridgeRouteCases)("rejects direct $name bridge calls before any privileged side effect", async (route) => {
await expect(route.call(route.makeRequest(), route.params)).rejects.toMatchObject({ status: 404 });
expectNoWorkflowBridgeSideEffects();
});
it.each(internalBridgeRouteCases)("rejects forged $name bridge signatures before any privileged side effect", async (route) => {
await expect(route.call(withHeaders(route.makeRequest(), forgedInternalProxyHeaders()), route.params)).rejects.toMatchObject({ status: 404 });
expectNoWorkflowBridgeSideEffects();
});
it("runs workflow trigger callbacks with tenant scope and trigger execution semantics", async () => {
const response = await callTriggerAction("POST", { event: "row.created", userId: "user_1" });
expect(response.status).toBe(200);
await expect(response.json()).resolves.toEqual({ execution: workflowExecution });
expect(mocks.validateApiKey).not.toHaveBeenCalled();
expect(mocks.execute).toHaveBeenCalledWith("workflow_1", {
type: "trigger",
input: { event: "row.created", userId: "user_1" },
session: { tenantId: tenant.id, userId: "user_1" },
});
});
it("runs workflow trigger callbacks with header tenant scope and query trigger block scope", async () => {
const { action } = await import("./workflows.trigger.$id");
const request = new Request("https://example.com/internal/api/workflows/trigger/workflow_1?triggerBlockId=block_1", {
method: "POST",
body: JSON.stringify({ event: "row.created", userId: "user_2" }),
headers: {
"Content-Type": "application/json",
"Idempotency-Key": "idem-trigger-header-tenant",
"X-Tenant-Id": "tenant_from_header",
},
});
const response = (await action({
request: withInternalProxyHeaders(request),
params: { id: "workflow_1" },
context: {},
} as unknown as ActionFunctionArgs)) as Response;
expect(response.status).toBe(200);
expect(mocks.execute).toHaveBeenCalledWith("workflow_1", {
type: "trigger",
input: { event: "row.created", userId: "user_2" },
session: { tenantId: "tenant_from_header", userId: "user_2" },
fromBlockId: "block_1",
});
});
it("rejects workflow trigger callbacks for unsupported methods before executing", async () => {
const response = await callTriggerAction("GET");
expect(response.status).toBe(405);
await expect(response.json()).resolves.toEqual({ error: translated.methodNotAllowed });
expect(mocks.execute).not.toHaveBeenCalled();
});
it("rejects invalid workflow trigger JSON before idempotent execution", async () => {
const { action } = await import("./workflows.trigger.$id");
const request = new Request("https://example.com/internal/api/workflows/trigger/workflow_1?tenantId=tenant_1", {
method: "POST",
body: "{",
headers: {
"Content-Type": "application/json",
"Idempotency-Key": "idem-trigger-invalid-json",
},
});
const response = (await action({
request: withInternalProxyHeaders(request),
params: { id: "workflow_1" },
context: {},
} as unknown as ActionFunctionArgs)) as Response;
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.invalidJsonBody });
expect(mocks.execute).not.toHaveBeenCalled();
});
it("replays workflow trigger callbacks with the same idempotency key", async () => {
const first = await callTriggerAction("POST", { event: "row.created", userId: "user_1" }, "idem-trigger-1");
const second = await callTriggerAction("POST", { event: "row.created", userId: "user_1" }, "idem-trigger-1");
expect(first.status).toBe(200);
expect(second.status).toBe(200);
await expect(first.json()).resolves.toEqual({ execution: workflowExecution });
await expect(second.json()).resolves.toEqual({ execution: workflowExecution });
expect(mocks.execute).toHaveBeenCalledTimes(1);
});
it("rejects workflow trigger callbacks that reuse an idempotency key for different input", async () => {
const first = await callTriggerAction("POST", { event: "row.created" }, "idem-trigger-conflict");
const second = await callTriggerAction("POST", { event: "row.updated" }, "idem-trigger-conflict");
expect(first.status).toBe(200);
expect(second.status).toBe(409);
await expect(second.json()).resolves.toEqual({ error: translated.idempotencyKeyConflict });
expect(mocks.execute).toHaveBeenCalledTimes(1);
});
it("rejects workflow trigger callbacks without an idempotency key", async () => {
const response = await callTriggerAction("POST", { event: "row.created" }, null);
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.idempotencyKeyRequired });
expect(mocks.execute).not.toHaveBeenCalled();
});
it("rejects workflow trigger callbacks without tenant scope", async () => {
const { action } = await import("./workflows.trigger.$id");
const request = new Request("https://example.com/internal/api/workflows/trigger/workflow_1", {
method: "POST",
body: "{}",
headers: { "Content-Type": "application/json" },
});
const response = (await action({
request: withInternalProxyHeaders(request),
params: { id: "workflow_1" },
context: {},
} as unknown as ActionFunctionArgs)) as Response;
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.tenantIdRequired });
expect(mocks.execute).not.toHaveBeenCalled();
});
it("starts queued workflow executions with tenant scope and idempotency", async () => {
const response = await callExecutionStartAction(
"POST",
{ workflowId: "workflow_1", type: "manual", input: { approved: true }, userId: "user_1" },
"idem-execution-start"
);
expect(response.status).toBe(200);
await expect(response.json()).resolves.toEqual({ execution: workflowExecution });
expect(mocks.validateApiKey).not.toHaveBeenCalled();
expect(mocks.executeExisting).toHaveBeenCalledWith("execution_1", {
workflowId: "workflow_1",
type: "manual",
input: { approved: true },
session: { tenantId: tenant.id, userId: "user_1" },
});
});
it("treats queued workflow execution errors as successful delivery envelopes", async () => {
const failedExecution = {
...workflowExecution,
status: "error",
error: "Manual trigger validation failed: data is required",
};
mocks.executeExisting.mockResolvedValueOnce(failedExecution);
const first = await callExecutionStartAction(
"POST",
{ workflowId: "workflow_1", type: "manual", input: { approved: false } },
"idem-execution-start-error"
);
const second = await callExecutionStartAction(
"POST",
{ workflowId: "workflow_1", type: "manual", input: { approved: false } },
"idem-execution-start-error"
);
expect(first.status).toBe(200);
expect(second.status).toBe(200);
await expect(first.json()).resolves.toEqual({ execution: failedExecution });
await expect(second.json()).resolves.toEqual({ execution: failedExecution });
expect(mocks.executeExisting).toHaveBeenCalledTimes(1);
});
it("replays queued workflow execution starts with the same idempotency key", async () => {
const first = await callExecutionStartAction(
"POST",
{ workflowId: "workflow_1", type: "manual", input: { approved: true } },
"idem-execution-start-replay"
);
const second = await callExecutionStartAction(
"POST",
{ workflowId: "workflow_1", type: "manual", input: { approved: true } },
"idem-execution-start-replay"
);
expect(first.status).toBe(200);
expect(second.status).toBe(200);
expect(mocks.executeExisting).toHaveBeenCalledTimes(1);
});
it("rejects queued workflow execution starts that reuse an idempotency key for different input", async () => {
const first = await callExecutionStartAction(
"POST",
{ workflowId: "workflow_1", type: "manual", input: { approved: true } },
"idem-execution-start-conflict"
);
const second = await callExecutionStartAction(
"POST",
{ workflowId: "workflow_1", type: "manual", input: { approved: false } },
"idem-execution-start-conflict"
);
expect(first.status).toBe(200);
expect(second.status).toBe(409);
await expect(second.json()).resolves.toEqual({ error: translated.idempotencyKeyConflict });
expect(mocks.executeExisting).toHaveBeenCalledTimes(1);
});
it("rejects queued workflow execution starts without an idempotency key", async () => {
const response = await callExecutionStartAction("POST", { workflowId: "workflow_1", type: "manual" }, null);
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.idempotencyKeyRequired });
expect(mocks.executeExisting).not.toHaveBeenCalled();
});
it("queues workflow continuations with the authenticated tenant/user session and logs tenant API-key acceptance", async () => {
const response = await callContinueAction("POST", { approved: true });
expect(response.status).toBe(202);
await expect(response.json()).resolves.toEqual({ execution: { ...workflowExecution, status: "waiting", type: "api" }, queued: true });
expect(mocks.validateApiKey).toHaveBeenCalledWith(expect.any(Request), { id: "execution_1" });
expect(mocks.queueContinuationExecution).toHaveBeenCalledWith("execution_1", {
type: "api",
input: { approved: true },
session: { tenantId: tenant.id, userId: "user_1" },
});
expect(mocks.continueExecution).not.toHaveBeenCalled();
expectSuccessLog(202);
});
it("rejects workflow continuation service tokens without tenant context", async () => {
mocks.validateApiKey.mockResolvedValueOnce({ tenant: null });
const response = await callContinueAction();
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.tenantIdRequired });
expect(mocks.queueContinuationExecution).not.toHaveBeenCalled();
});
it("rejects invalid workflow continuation JSON before continuing", async () => {
const { action } = await import("./workflows.executions.$id.continue");
const response = (await action({
request: withInternalProxyHeaders(
new Request("https://example.com/internal/api/workflows", { method: "POST", body: "{", headers: { "Content-Type": "application/json" } })
),
params: { id: "execution_1" },
context: {},
} as unknown as ActionFunctionArgs)) as Response;
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.invalidJsonBody });
expect(mocks.queueContinuationExecution).not.toHaveBeenCalled();
expectErrorLog(translated.invalidJsonBody, 400);
});
it("does not continue executions for unsupported methods and logs the failure", async () => {
const response = await callContinueAction("GET");
expect(response.status).toBe(405);
await expect(response.json()).resolves.toEqual({ error: translated.methodNotAllowed });
expect(mocks.queueContinuationExecution).not.toHaveBeenCalled();
expectErrorLog(translated.methodNotAllowed, 405);
});
it("starts queued workflow continuations through the signed internal bridge", async () => {
const response = await callExecutionContinuationStartAction(
"POST",
{ workflowId: "workflow_1", type: "api", input: { approved: true }, userId: "user_1" },
"idem-continuation-start"
);
expect(response.status).toBe(200);
await expect(response.json()).resolves.toEqual({ execution: workflowExecution });
expect(mocks.continueExecution).toHaveBeenCalledWith("execution_1", {
type: "api",
input: { approved: true },
session: { tenantId: "tenant_1", userId: "user_1" },
});
});
it("rejects queued workflow continuation starts that reuse an idempotency key for different input", async () => {
const first = await callExecutionContinuationStartAction(
"POST",
{ workflowId: "workflow_1", type: "api", input: { approved: true } },
"idem-continuation-conflict"
);
const second = await callExecutionContinuationStartAction(
"POST",
{ workflowId: "workflow_1", type: "api", input: { approved: false } },
"idem-continuation-conflict"
);
expect(first.status).toBe(200);
expect(second.status).toBe(409);
await expect(second.json()).resolves.toEqual({ error: translated.idempotencyKeyConflict });
expect(mocks.continueExecution).toHaveBeenCalledTimes(1);
});
it("reads workflow executions with GET for only the authenticated tenant", async () => {
const response = await callExecutionLoader("GET");
expect(response.status).toBe(200);
await expect(response.json()).resolves.toEqual({ execution: workflowExecution });
expect(mocks.validateApiKey).toHaveBeenCalledWith(expect.any(Request), { id: "execution_1" });
expect(mocks.getExecution).toHaveBeenCalledWith("execution_1", { tenantId: tenant.id });
expectSuccessLog(200);
});
it("rejects workflow execution reads without tenant context", async () => {
mocks.validateApiKey.mockResolvedValueOnce({ tenant: null });
const response = await callExecutionLoader();
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.tenantIdRequired });
expect(mocks.getExecution).not.toHaveBeenCalled();
});
it("returns not found and logs when execution ownership cannot be proven", async () => {
mocks.getExecution.mockResolvedValueOnce(null);
const response = await callExecutionLoader("GET", "missing_execution");
expect(response.status).toBe(404);
await expect(response.json()).resolves.toEqual({ error: translated.executionNotFound });
expect(mocks.getExecution).toHaveBeenCalledWith("missing_execution", { tenantId: tenant.id });
expectErrorLog(translated.executionNotFound, 404);
});
it("rejects non-read methods on the execution loader", async () => {
const response = await callExecutionLoader("POST");
expect(response.status).toBe(405);
await expect(response.json()).resolves.toEqual({ error: translated.methodNotAllowed });
expect(mocks.getExecution).not.toHaveBeenCalled();
expectErrorLog(translated.methodNotAllowed, 405);
});
it("validates stream auth and execution ownership before subscribing to execution updates", async () => {
const response = await callStreamLoader();
expect(response.status).toBe(200);
expect(mocks.validateApiKey).toHaveBeenCalledWith(expect.any(Request), { executionId: "execution_1" });
expect(mocks.getExecution).toHaveBeenCalledWith("execution_1", { tenantId: tenant.id });
expect(mocks.eventStream).toHaveBeenCalled();
expect(mocks.emitterOn).toHaveBeenCalledWith("workflowExecutionUpdate:execution_1", expect.any(Function));
expectSuccessLog(200);
});
it("rejects workflow streams without tenant context", async () => {
mocks.validateApiKey.mockResolvedValueOnce({ tenant: null });
const response = await callStreamLoader();
expect(response.status).toBe(400);
await expect(response.json()).resolves.toEqual({ error: translated.tenantIdRequired });
expect(mocks.getExecution).not.toHaveBeenCalled();
expect(mocks.eventStream).not.toHaveBeenCalled();
});
it("does not subscribe unauthenticated streams to execution updates", async () => {
mocks.validateApiKey.mockRejectedValueOnce(Object.assign(new Error("Invalid API Key"), { status: 401, apiKeyLog: tenantApiKey.apiKeyLog }));
const response = await callStreamLoader();
expect(response.status).toBe(401);
await expect(response.json()).resolves.toEqual({ error: "Invalid API Key" });
expect(mocks.getExecution).not.toHaveBeenCalled();
expect(mocks.eventStream).not.toHaveBeenCalled();
expect(mocks.emitterOn).not.toHaveBeenCalled();
expectErrorLog("Invalid API Key", 401);
});
it("rejects unsupported workflow stream methods before subscribing", async () => {
const response = await callStreamLoader("execution_1", "POST");
expect(response.status).toBe(405);
await expect(response.json()).resolves.toEqual({ error: translated.methodNotAllowed });
expect(mocks.getExecution).not.toHaveBeenCalled();
expect(mocks.eventStream).not.toHaveBeenCalled();
expect(mocks.emitterOn).not.toHaveBeenCalled();
expectErrorLog(translated.methodNotAllowed, 405);
});
it("does not subscribe streams when execution ownership cannot be proven", async () => {
mocks.getExecution.mockResolvedValueOnce(null);
const response = await callStreamLoader("other_tenant_execution");
expect(response.status).toBe(404);
await expect(response.json()).resolves.toEqual({ error: translated.executionNotFound });
expect(mocks.getExecution).toHaveBeenCalledWith("other_tenant_execution", { tenantId: tenant.id });
expect(mocks.eventStream).not.toHaveBeenCalled();
expect(mocks.emitterOn).not.toHaveBeenCalled();
expectErrorLog(translated.executionNotFound, 404);
});
it("removes stream execution update listeners when the authorized stream aborts", async () => {
let cleanup: (() => void) | undefined;
mocks.eventStream.mockImplementationOnce((_signal: AbortSignal, init: (send: (args: { data: string }) => void) => () => void) => {
cleanup = init(vi.fn());
return new Response("stream", { status: 200, headers: { "Content-Type": "text/event-stream" } });
});
const response = await callStreamLoader();
cleanup?.();
expect(response.status).toBe(200);
expect(mocks.emitterOn).toHaveBeenCalledWith("workflowExecutionUpdate:execution_1", expect.any(Function));
expect(mocks.emitterOff).toHaveBeenCalledWith("workflowExecutionUpdate:execution_1", expect.any(Function));
});
});
@@ -0,0 +1,100 @@
import { CatalogError, foundationErrors, type IdempotencyClient, type JsonValue, withIdempotency } from "@toolctrl/foundation";
import { ActionFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import WorkflowsExecutionsService from "~/modules/workflowEngine/services/WorkflowsExecutionsService";
import { requireInternalWebApiProxyRequest } from "~/utils/api/internalWebApiProxy.server";
import { db } from "~/utils/db.server";
import { redactWorkflowApiErrorMessage, workflowApiText } from "./workflowApiErrors.server";
function getTenantId(request: Request, t: TFunction): string {
const url = new URL(request.url);
const tenantId = url.searchParams.get("tenantId") || request.headers.get("X-Tenant-Id") || "";
if (!tenantId) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.tenantIdRequired")), { status: 400 });
}
return tenantId;
}
function getIdempotencyKey(request: Request, t: TFunction): string {
const key = request.headers.get("Idempotency-Key")?.trim();
if (!key || key.length > 255 || /[\u0000-\u001f\u007f]/u.test(key)) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.idempotencyKeyRequired")), { status: 400 });
}
return key;
}
function toJsonValue(value: unknown): JsonValue {
return JSON.parse(JSON.stringify(value ?? null)) as JsonValue;
}
export const action = async ({ request, params }: ActionFunctionArgs) => {
requireInternalWebApiProxyRequest(request);
const { t } = await getTranslations(request);
try {
if (request.method !== "POST") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.methodNotAllowed")), { status: 405 });
}
let body: { [key: string]: any } = {};
try {
body = await request.json();
} catch {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.invalidJsonBody")), { status: 400 });
}
const tenantId = getTenantId(request, t);
const workflowId = typeof body.workflowId === "string" ? body.workflowId : "";
if (!workflowId) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.workflowNotFound")), { status: 400 });
}
if (body.type !== "manual" && body.type !== "api") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.invalidAction")), { status: 400 });
}
const idempotencyKey = getIdempotencyKey(request, t);
const input = body.input && typeof body.input === "object" && !Array.isArray(body.input) ? body.input : null;
const userId = typeof body.userId === "string" && body.userId.length > 0 ? body.userId : null;
const idempotency = await withIdempotency(
{
scope: `workflow-continuation:tenant:${tenantId}`,
key: idempotencyKey,
fingerprint: {
method: request.method,
workflowId,
executionId: params.id!,
tenantId,
body: toJsonValue(body),
},
expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
},
db as unknown as IdempotencyClient,
async () => {
const execution = await WorkflowsExecutionsService.continueExecution(params.id!, {
type: body.type,
input,
session: {
tenantId,
userId,
},
});
return {
status: 200,
headers: { "content-type": "application/json" },
body: { execution: toJsonValue(execution) },
};
}
);
return Response.json(idempotency.body ?? {}, { status: idempotency.status, headers: idempotency.headers });
} catch (e: any) {
if (e instanceof CatalogError && e.code === foundationErrors.idempotencyConflict.code) {
return Response.json(
{ error: workflowApiText(t, "workflows.errors.idempotencyKeyConflict") },
{ status: 409 }
);
}
if (e instanceof CatalogError && e.code === foundationErrors.idempotencyInProgress.code) {
return Response.json(
{ error: workflowApiText(t, "workflows.errors.idempotencyKeyInProgress") },
{ status: 409 }
);
}
return Response.json({ error: redactWorkflowApiErrorMessage(request, e) }, { status: e.status ?? 500 });
}
};
@@ -0,0 +1,42 @@
import { ActionFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import WorkflowsExecutionsService from "~/modules/workflowEngine/services/WorkflowsExecutionsService";
import { requireInternalWebApiProxyRequest } from "~/utils/api/internalWebApiProxy.server";
import { getWorkflowApiKeyFromRequest, setWorkflowApiKeyLogStatus, type WorkflowApiAccessValidation } from "~/utils/services/apiService";
import { getWorkflowErrorAccess, redactWorkflowApiErrorMessage, requireWorkflowTenant, workflowApiText } from "./workflowApiErrors.server";
export const action = async ({ request, params }: ActionFunctionArgs) => {
requireInternalWebApiProxyRequest(request);
const { t } = await getTranslations(request);
const startTime = performance.now();
let apiAccessValidation: WorkflowApiAccessValidation | undefined = undefined;
try {
apiAccessValidation = await getWorkflowApiKeyFromRequest(request, params);
if (request.method !== "POST") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.methodNotAllowed")), { status: 405 });
}
const tenant = requireWorkflowTenant(apiAccessValidation, t);
const { userId } = apiAccessValidation;
let body: { [key: string]: any } = {};
try {
body = await request.json();
} catch {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.invalidJsonBody")), { status: 400 });
}
const execution = await WorkflowsExecutionsService.queueContinuationExecution(params.id!, {
type: "api",
input: body,
session: {
tenantId: tenant.id,
userId: userId ?? null,
},
});
await setWorkflowApiKeyLogStatus(apiAccessValidation, { status: 202, startTime });
return Response.json({ execution, queued: true }, { status: 202 });
} catch (e: any) {
const status = e.status ?? 500;
const error = redactWorkflowApiErrorMessage(request, e);
await setWorkflowApiKeyLogStatus(getWorkflowErrorAccess(apiAccessValidation, e), { error, status, startTime });
return Response.json({ error }, { status });
}
};
@@ -0,0 +1,101 @@
import { CatalogError, foundationErrors, type IdempotencyClient, type JsonValue, withIdempotency } from "@toolctrl/foundation";
import { ActionFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import WorkflowsExecutionsService from "~/modules/workflowEngine/services/WorkflowsExecutionsService";
import { requireInternalWebApiProxyRequest } from "~/utils/api/internalWebApiProxy.server";
import { db } from "~/utils/db.server";
import { redactWorkflowApiErrorMessage, workflowApiText } from "./workflowApiErrors.server";
function getTenantId(request: Request, t: TFunction): string {
const url = new URL(request.url);
const tenantId = url.searchParams.get("tenantId") || request.headers.get("X-Tenant-Id") || "";
if (!tenantId) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.tenantIdRequired")), { status: 400 });
}
return tenantId;
}
function getIdempotencyKey(request: Request, t: TFunction): string {
const key = request.headers.get("Idempotency-Key")?.trim();
if (!key || key.length > 255 || /[\u0000-\u001f\u007f]/u.test(key)) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.idempotencyKeyRequired")), { status: 400 });
}
return key;
}
function toJsonValue(value: unknown): JsonValue {
return JSON.parse(JSON.stringify(value ?? null)) as JsonValue;
}
export const action = async ({ request, params }: ActionFunctionArgs) => {
requireInternalWebApiProxyRequest(request);
const { t } = await getTranslations(request);
try {
if (request.method !== "POST") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.methodNotAllowed")), { status: 405 });
}
let body: { [key: string]: any } = {};
try {
body = await request.json();
} catch {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.invalidJsonBody")), { status: 400 });
}
const tenantId = getTenantId(request, t);
const workflowId = typeof body.workflowId === "string" ? body.workflowId : "";
if (!workflowId) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.workflowNotFound")), { status: 400 });
}
if (body.type !== "manual" && body.type !== "api") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.invalidAction")), { status: 400 });
}
const idempotencyKey = getIdempotencyKey(request, t);
const input = body.input && typeof body.input === "object" && !Array.isArray(body.input) ? body.input : null;
const userId = typeof body.userId === "string" && body.userId.length > 0 ? body.userId : null;
const idempotency = await withIdempotency(
{
scope: `workflow-execution:tenant:${tenantId}`,
key: idempotencyKey,
fingerprint: {
method: request.method,
workflowId,
executionId: params.id!,
tenantId,
body: toJsonValue(body),
},
expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
},
db as unknown as IdempotencyClient,
async () => {
const execution = await WorkflowsExecutionsService.executeExisting(params.id!, {
workflowId,
type: body.type,
input,
session: {
tenantId,
userId,
},
});
return {
status: 200,
headers: { "content-type": "application/json" },
body: { execution: toJsonValue(execution) },
};
}
);
return Response.json(idempotency.body ?? {}, { status: idempotency.status, headers: idempotency.headers });
} catch (e: any) {
if (e instanceof CatalogError && e.code === foundationErrors.idempotencyConflict.code) {
return Response.json(
{ error: workflowApiText(t, "workflows.errors.idempotencyKeyConflict") },
{ status: 409 }
);
}
if (e instanceof CatalogError && e.code === foundationErrors.idempotencyInProgress.code) {
return Response.json(
{ error: workflowApiText(t, "workflows.errors.idempotencyKeyInProgress") },
{ status: 409 }
);
}
return Response.json({ error: redactWorkflowApiErrorMessage(request, e) }, { status: e.status ?? 500 });
}
};
@@ -0,0 +1,33 @@
import { LoaderFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import WorkflowsService from "~/modules/workflowEngine/services/WorkflowsService";
import { requireInternalWebApiProxyRequest } from "~/utils/api/internalWebApiProxy.server";
import { getWorkflowApiKeyFromRequest, setWorkflowApiKeyLogStatus, type WorkflowApiAccessValidation } from "~/utils/services/apiService";
import { getWorkflowErrorAccess, redactWorkflowApiErrorMessage, requireWorkflowTenant, workflowApiText } from "./workflowApiErrors.server";
export const loader = async ({ request, params }: LoaderFunctionArgs) => {
requireInternalWebApiProxyRequest(request);
const { t } = await getTranslations(request);
const startTime = performance.now();
let apiAccessValidation: WorkflowApiAccessValidation | undefined = undefined;
try {
apiAccessValidation = await getWorkflowApiKeyFromRequest(request, params);
if (request.method !== "GET") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.methodNotAllowed")), { status: 405 });
}
const tenant = requireWorkflowTenant(apiAccessValidation, t);
const execution = await WorkflowsService.getExecution(params.id!, {
tenantId: tenant.id,
});
if (!execution) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.executionNotFound")), { status: 404 });
}
await setWorkflowApiKeyLogStatus(apiAccessValidation, { status: 200, startTime });
return Response.json({ execution }, { status: 200 });
} catch (e: any) {
const status = e.status ?? 400;
const error = redactWorkflowApiErrorMessage(request, e);
await setWorkflowApiKeyLogStatus(getWorkflowErrorAccess(apiAccessValidation, e), { error, status, startTime });
return Response.json({ error }, { status });
}
};
@@ -0,0 +1,41 @@
import { ActionFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import WorkflowsExecutionsService from "~/modules/workflowEngine/services/WorkflowsExecutionsService";
import { requireInternalWebApiProxyRequest } from "~/utils/api/internalWebApiProxy.server";
import { getWorkflowApiKeyFromRequest, setWorkflowApiKeyLogStatus, type WorkflowApiAccessValidation } from "~/utils/services/apiService";
import { getWorkflowErrorAccess, redactWorkflowApiErrorMessage, requireWorkflowTenant, workflowApiText } from "./workflowApiErrors.server";
export const action = async ({ request, params }: ActionFunctionArgs) => {
requireInternalWebApiProxyRequest(request);
const { t } = await getTranslations(request);
const startTime = performance.now();
let apiAccessValidation: WorkflowApiAccessValidation | undefined = undefined;
try {
apiAccessValidation = await getWorkflowApiKeyFromRequest(request, params);
if (request.method !== "POST") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.methodNotAllowed")), { status: 405 });
}
const tenant = requireWorkflowTenant(apiAccessValidation, t);
const { userId } = apiAccessValidation;
let body: { [key: string]: any } = {};
try {
body = await request.json();
} catch {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.invalidJsonBody")), { status: 400 });
}
const execution = await WorkflowsExecutionsService.queueApiExecution(params.id!, {
input: body,
session: {
tenantId: tenant.id,
userId: userId ?? null,
},
});
await setWorkflowApiKeyLogStatus(apiAccessValidation, { status: 202, startTime });
return Response.json({ execution }, { status: 202 });
} catch (e: any) {
const status = e.status ?? 500;
const error = redactWorkflowApiErrorMessage(request, e);
await setWorkflowApiKeyLogStatus(getWorkflowErrorAccess(apiAccessValidation, e), { error, status, startTime });
return Response.json({ error }, { status });
}
};
@@ -0,0 +1,53 @@
import { LoaderFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import WorkflowsService from "~/modules/workflowEngine/services/WorkflowsService";
import { emitter } from "~/utils/stream/emitter.server";
import { eventStream } from "~/utils/stream/event-stream";
import { requireInternalWebApiProxyRequest } from "~/utils/api/internalWebApiProxy.server";
import { getWorkflowApiKeyFromRequest, setWorkflowApiKeyLogStatus, WorkflowApiAccessValidation } from "~/utils/services/apiService";
import { redactWorkflowApiErrorMessage, requireWorkflowTenant, workflowApiText } from "./workflowApiErrors.server";
export const loader = async ({ request, params }: LoaderFunctionArgs) => {
requireInternalWebApiProxyRequest(request);
const { t } = await getTranslations(request);
const startTime = performance.now();
let apiAccessValidation: WorkflowApiAccessValidation | undefined = undefined;
try {
if (!params.executionId) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.executionIdRequired")), { status: 400 });
}
apiAccessValidation = await getWorkflowApiKeyFromRequest(request, params);
if (request.method !== "GET") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.methodNotAllowed")), { status: 405 });
}
const tenant = requireWorkflowTenant(apiAccessValidation, t);
const execution = await WorkflowsService.getExecution(params.executionId, {
tenantId: tenant.id,
});
if (!execution) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.executionNotFound")), { status: 404 });
}
await setWorkflowApiKeyLogStatus(apiAccessValidation, { status: 200, startTime });
const eventName = `workflowExecutionUpdate:${params.executionId}`;
return eventStream(request.signal, (send) => {
// listener handler
const listener = (data: string) => {
// data should be serialized
send({ data });
};
// event listener itself
emitter.on(eventName, listener);
// cleanup
return () => {
emitter.off(eventName, listener);
};
});
} catch (e: any) {
const status = e.status ?? 400;
const error = redactWorkflowApiErrorMessage(request, e);
await setWorkflowApiKeyLogStatus(apiAccessValidation ?? { apiKeyLog: e.apiKeyLog, tenant: null }, { error, status, startTime });
return Response.json({ error }, { status });
}
};
@@ -0,0 +1,99 @@
import { CatalogError, foundationErrors, type IdempotencyClient, type JsonValue, withIdempotency } from "@toolctrl/foundation";
import { ActionFunctionArgs } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import WorkflowsExecutionsService from "~/modules/workflowEngine/services/WorkflowsExecutionsService";
import { requireInternalWebApiProxyRequest } from "~/utils/api/internalWebApiProxy.server";
import { db } from "~/utils/db.server";
import { redactWorkflowApiErrorMessage, workflowApiText } from "./workflowApiErrors.server";
function getTenantId(request: Request, t: TFunction): string {
const url = new URL(request.url);
const tenantId = url.searchParams.get("tenantId") || request.headers.get("X-Tenant-Id") || "";
if (!tenantId) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.tenantIdRequired")), { status: 400 });
}
return tenantId;
}
function getTriggerBlockId(request: Request, body: Record<string, unknown>): string | null {
const url = new URL(request.url);
const fromQuery = url.searchParams.get("triggerBlockId")?.trim();
if (fromQuery) {
return fromQuery;
}
return typeof body.triggerBlockId === "string" && body.triggerBlockId.length > 0 ? body.triggerBlockId : null;
}
function getUserId(body: Record<string, unknown>): string | null {
return typeof body.userId === "string" && body.userId.length > 0 ? body.userId : null;
}
function getIdempotencyKey(request: Request, t: TFunction): string {
const key = request.headers.get("Idempotency-Key")?.trim();
if (!key || key.length > 255 || /[\u0000-\u001f\u007f]/u.test(key)) {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.idempotencyKeyRequired")), { status: 400 });
}
return key;
}
function toJsonValue(value: unknown): JsonValue {
return JSON.parse(JSON.stringify(value ?? null)) as JsonValue;
}
export const action = async ({ request, params }: ActionFunctionArgs) => {
requireInternalWebApiProxyRequest(request);
const { t } = await getTranslations(request);
try {
if (request.method !== "POST") {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.methodNotAllowed")), { status: 405 });
}
let body: { [key: string]: any } = {};
try {
body = await request.json();
} catch {
throw Object.assign(new Error(workflowApiText(t, "workflows.errors.invalidJsonBody")), { status: 400 });
}
const tenantId = getTenantId(request, t);
const triggerBlockId = getTriggerBlockId(request, body);
const idempotencyKey = getIdempotencyKey(request, t);
const idempotency = await withIdempotency({
scope: `workflow-trigger:tenant:${tenantId}`,
key: idempotencyKey,
fingerprint: {
method: request.method,
workflowId: params.id!,
tenantId,
triggerBlockId,
body: toJsonValue(body),
},
expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
}, db as unknown as IdempotencyClient, async () => {
const execution = await WorkflowsExecutionsService.execute(params.id!, {
type: "trigger",
input: body,
session: {
tenantId,
userId: getUserId(body),
},
...(triggerBlockId ? { fromBlockId: triggerBlockId } : {}),
});
if (execution.error) {
throw Object.assign(new Error(execution.error), { status: 400 });
}
return {
status: 200,
headers: { "content-type": "application/json" },
body: { execution: toJsonValue(execution) },
};
});
return Response.json(idempotency.body ?? {}, { status: idempotency.status, headers: idempotency.headers });
} catch (e: any) {
if (e instanceof CatalogError && e.code === foundationErrors.idempotencyConflict.code) {
return Response.json({ error: workflowApiText(t, "workflows.errors.idempotencyKeyConflict") }, { status: 409 });
}
if (e instanceof CatalogError && e.code === foundationErrors.idempotencyInProgress.code) {
return Response.json({ error: workflowApiText(t, "workflows.errors.idempotencyKeyInProgress") }, { status: 409 });
}
return Response.json({ error: redactWorkflowApiErrorMessage(request, e) }, { status: e.status ?? 500 });
}
};
@@ -0,0 +1,290 @@
import type { ActionFunctionArgs } from "react-router";
import { beforeEach, describe, expect, it, vi } from "vitest";
const globalMockStoreKey = "__importsDryRunRouteTestMocks__";
const globalMockStore = globalThis as typeof globalThis & {
__importsDryRunRouteTestMocks__?: {
requireAuth: ReturnType<typeof vi.fn>;
createImportJob: ReturnType<typeof vi.fn>;
markImportJobRunning: ReturnType<typeof vi.fn>;
markImportJobSucceeded: ReturnType<typeof vi.fn>;
markImportJobFailed: ReturnType<typeof vi.fn>;
createImportDryRunPreview: ReturnType<typeof vi.fn>;
verifyUserHasPermission: ReturnType<typeof vi.fn>;
};
};
globalMockStore.__importsDryRunRouteTestMocks__ ??= {
requireAuth: vi.fn(),
createImportJob: vi.fn(),
markImportJobRunning: vi.fn(),
markImportJobSucceeded: vi.fn(),
markImportJobFailed: vi.fn(),
createImportDryRunPreview: vi.fn(),
verifyUserHasPermission: vi.fn(),
};
const mocks = globalMockStore[globalMockStoreKey];
const translations: Record<string, string> = {
"models.row.import.errors.dryRunFailed": "Import dry-run failed.",
"models.row.import.errors.dryRunFailedBeforeCompletion": "The import dry-run failed before completion.",
"models.row.import.errors.sourceStorageAccessDenied": "Import source storage access denied.",
"models.row.import.errors.sourceRequired": "Source is required.",
"models.row.import.errors.mappingsRequired": "Mappings must include at least one field mapping.",
"models.row.import.errors.methodNotAllowed": "Method not allowed.",
"models.row.import.errors.unsupportedFormat": "Unsupported import format.",
"models.row.import.errors.unsupportedType": "Unsupported import type: {{importType}}",
};
vi.mock("~/utils/loaders.middleware", () => ({
requireAuth: mocks.requireAuth,
}));
vi.mock("~/locale/i18next.server", () => ({
getTranslations: vi.fn(async () => ({
locale: "en",
translations: {},
t: (key: string, options?: Record<string, unknown>) => (translations[key] ?? key).replace("{{importType}}", String(options?.importType ?? "")),
})),
}));
vi.mock("~/utils/helpers/.server/PermissionsService", () => ({
verifyUserHasPermission: mocks.verifyUserHasPermission,
}));
vi.mock("~/utils/session.server", () => ({
validateCSRFToken: vi.fn(),
}));
vi.mock("@toolctrl/db/import-jobs.server", () => ({
createImportJob: mocks.createImportJob,
markImportJobRunning: mocks.markImportJobRunning,
markImportJobSucceeded: mocks.markImportJobSucceeded,
markImportJobFailed: mocks.markImportJobFailed,
}));
vi.mock("@toolctrl/imports", () => ({
createImportDryRunPreview: mocks.createImportDryRunPreview,
createRedactedParserDiagnostic: (code: string, message: string, options: Record<string, unknown> = {}) => ({
severity: "error",
...options,
code,
message: message.replace(
/(?:api[_-]?key|authorization|bearer|password|secret|token|rawBody)\s*[:=]\s*[^\s,;]+/gi,
(match) => `${match.split(/[:=]/, 1)[0]}: [REDACTED]`
),
}),
isSupportedImportFormat: (value: string) => ["csv", "json", "xlsx"].includes(value),
redactDiagnosticMessage: (message: string) =>
message.replace(
/(?:api[_-]?key|authorization|bearer|password|secret|token|rawBody)\s*[:=]\s*[^\s,;]+/gi,
(match) => `${match.split(/[:=]/, 1)[0]}: [REDACTED]`
),
}));
const validBody = {
format: "csv",
importType: "members",
source: {
tenantId: "tenant_1",
sourceKey: "tenants/tenant_1/uploads/import.csv",
fileName: "import.csv",
contentType: "text/csv",
requestId: "request_1",
},
fields: [{ targetField: "email", required: true, label: "Email" }],
mappings: [{ sourceColumn: "Email", targetField: "email", required: true, label: "Email" }],
rows: [{ rowNumber: 1, values: { Email: "ada@example.com" } }],
};
const preview = {
rows: [{ ok: true, rowNumber: 1, normalized: { email: "ada@example.com" }, warnings: undefined }],
mappedRows: [{ rowNumber: 1, normalized: { email: "ada@example.com" }, sourceColumns: ["Email"] }],
summary: { format: "csv", totalRows: 1, acceptedRows: 1, rejectedRows: 0, diagnostics: [] },
};
function makeRequest(method: string, body?: unknown) {
return new Request("https://example.com/internal/imports/dry-run", {
method,
body: body === undefined || method === "GET" || method === "HEAD" ? undefined : JSON.stringify(body),
headers: body === undefined ? undefined : { "Content-Type": "application/json", Authorization: "Bearer secret-token" },
});
}
async function callAction(method = "POST", body: unknown = validBody) {
const { action } = await import("./dry-run");
return action({ request: makeRequest(method, body), params: {}, context: {} } as unknown as ActionFunctionArgs) as Promise<Response>;
}
describe("/internal/imports/dry-run action", () => {
beforeEach(() => {
vi.clearAllMocks();
vi.resetModules();
mocks.requireAuth.mockResolvedValue({ userId: "user_1" });
mocks.createImportJob.mockResolvedValue({ id: "job_1" });
mocks.markImportJobRunning.mockResolvedValue(undefined);
mocks.markImportJobSucceeded.mockResolvedValue(undefined);
mocks.markImportJobFailed.mockResolvedValue(undefined);
mocks.createImportDryRunPreview.mockReturnValue(preview);
mocks.verifyUserHasPermission.mockResolvedValue(true);
});
it("authenticates, builds a dry-run preview, persists scalar counters, and returns the redacted response shape", async () => {
const response = await callAction();
expect(response.status).toBe(200);
await expect(response.json()).resolves.toEqual({
jobId: "job_1",
status: "COMPLETED",
summary: preview.summary,
rows: preview.rows,
diagnostics: [],
});
expect(mocks.requireAuth).toHaveBeenCalledWith({ request: expect.any(Request), params: {} });
expect(mocks.verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "app.settings.members.create", "tenant_1");
expect(mocks.createImportJob).toHaveBeenCalledWith(
expect.objectContaining({
tenantId: "tenant_1",
requestedByUserId: "user_1",
importType: "members",
format: "csv",
requestId: "request_1",
sourceBucket: "import-dry-run",
sourceKey: "tenants/tenant_1/uploads/import.csv",
attemptsMade: 0,
})
);
expect(mocks.markImportJobRunning).toHaveBeenCalledWith({ id: "job_1", tenantId: "tenant_1", attemptsMade: 1 });
expect(mocks.createImportDryRunPreview).toHaveBeenCalledWith(
expect.objectContaining({
format: "csv",
fields: validBody.fields,
mappings: validBody.mappings,
rows: validBody.rows,
})
);
expect(mocks.markImportJobSucceeded).toHaveBeenCalledWith({
id: "job_1",
tenantId: "tenant_1",
rowCount: 1,
acceptedRows: 1,
rejectedRows: 0,
attemptsMade: 1,
});
expect(mocks.markImportJobFailed).not.toHaveBeenCalled();
});
it("returns localized validation messages for missing source and mappings", async () => {
const missingSource = await callAction("POST", { ...validBody, source: undefined });
await expect(missingSource.json()).resolves.toMatchObject({ error: "Source is required." });
const missingMappings = await callAction("POST", { ...validBody, mappings: [] });
await expect(missingMappings.json()).resolves.toMatchObject({ error: "Mappings must include at least one field mapping." });
});
it("rejects non-POST requests before auth or persistence", async () => {
const response = await callAction("GET", undefined);
expect(response.status).toBe(405);
await expect(response.json()).resolves.toEqual({ error: "Method not allowed." });
expect(mocks.requireAuth).not.toHaveBeenCalled();
expect(mocks.createImportJob).not.toHaveBeenCalled();
});
it("rejects unsupported formats and redacts secret-bearing invalid payload details", async () => {
const response = await callAction("POST", { ...validBody, format: "xml", apiKey: "secret-token" });
expect(response.status).toBe(400);
const payload = await response.json();
expect(payload.error).toBe("Unsupported import format.");
expect(payload.diagnostics[0]).toMatchObject({ code: "invalid_dry_run_request", message: "Unsupported import format." });
expect(JSON.stringify(payload)).not.toContain("secret-token");
expect(mocks.createImportJob).not.toHaveBeenCalled();
});
it("rejects missing mappings or rows without checking permissions or creating a job", async () => {
const response = await callAction("POST", { ...validBody, mappings: [], rows: [] });
expect(response.status).toBe(400);
await expect(response.json()).resolves.toMatchObject({
error: "Mappings must include at least one field mapping.",
diagnostics: [expect.objectContaining({ code: "invalid_dry_run_request" })],
});
expect(mocks.verifyUserHasPermission).not.toHaveBeenCalled();
expect(mocks.createImportJob).not.toHaveBeenCalled();
});
it("propagates permission denials before persistence, preview generation, or authorization leakage", async () => {
const denial = new Response(null, { status: 302, headers: { Location: "/unauthorized/app.settings.members.create/tenant_2" } });
mocks.verifyUserHasPermission.mockRejectedValueOnce(denial);
await expect(callAction("POST", { ...validBody, importType: "members", source: { ...validBody.source, tenantId: "tenant_2" } })).rejects.toBe(denial);
expect(mocks.verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "app.settings.members.create", "tenant_2");
expect(mocks.createImportJob).not.toHaveBeenCalled();
expect(mocks.markImportJobRunning).not.toHaveBeenCalled();
expect(mocks.createImportDryRunPreview).not.toHaveBeenCalled();
expect(mocks.markImportJobSucceeded).not.toHaveBeenCalled();
expect(mocks.markImportJobFailed).not.toHaveBeenCalled();
expect(JSON.stringify(denial.headers)).not.toContain("secret-token");
});
it("rejects dry-run source keys outside the requested tenant prefix", async () => {
const response = await callAction("POST", {
...validBody,
source: { ...validBody.source, sourceKey: "tenants/tenant_2/uploads/import.csv" },
});
expect(response.status).toBe(403);
await expect(response.json()).resolves.toEqual({
error: "Import source storage access denied.",
reason: "tenant_mismatch",
});
expect(mocks.verifyUserHasPermission).toHaveBeenCalledWith(expect.any(Request), "app.settings.members.create", "tenant_1");
expect(mocks.createImportJob).not.toHaveBeenCalled();
expect(mocks.createImportDryRunPreview).not.toHaveBeenCalled();
});
it("rejects unsupported import types before permissions or persistence", async () => {
const response = await callAction("POST", { ...validBody, importType: "widgets" });
expect(response.status).toBe(400);
await expect(response.json()).resolves.toMatchObject({ error: "Unsupported import type: widgets" });
expect(mocks.verifyUserHasPermission).not.toHaveBeenCalled();
expect(mocks.createImportJob).not.toHaveBeenCalled();
});
it("redacts helper failures, marks the import job failed, and does not leak raw body or tokens", async () => {
mocks.createImportDryRunPreview.mockImplementationOnce(() => {
throw new Error('Parser failed authorization: Bearer secret-token rawBody={"email":"ada@example.com"}');
});
const response = await callAction("POST", validBody);
expect(response.status).toBe(500);
const payload = await response.json();
expect(payload.error).toBe("Import dry-run failed.");
expect(JSON.stringify(payload)).not.toContain("secret-token");
expect(JSON.stringify(payload)).not.toContain("ada@example.com");
expect(mocks.markImportJobFailed).toHaveBeenCalledWith(
expect.objectContaining({
id: "job_1",
attemptsMade: 1,
errorName: "Error",
errorMessage: expect.not.stringContaining("secret-token"),
})
);
});
it("returns a redacted server error when DB helpers fail", async () => {
mocks.markImportJobRunning.mockRejectedValueOnce(new Error("database token=secret-token is unavailable"));
const response = await callAction();
expect(response.status).toBe(500);
const payload = await response.json();
expect(payload).toMatchObject({ error: "Import dry-run failed.", diagnostics: [expect.objectContaining({ code: "dry_run_failed" })] });
expect(JSON.stringify(payload)).not.toContain("secret-token");
expect(mocks.markImportJobSucceeded).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,355 @@
import type { ActionFunctionArgs } from "react-router";
import {
createImportDryRunPreview,
createRedactedParserDiagnostic,
isSupportedImportFormat,
redactDiagnosticMessage,
type ColumnMapping,
type ImportDryRunFieldDefinition,
type ImportDryRunPreviewInput,
type ImportPreviewInputRow,
type NormalizedImportRow,
type NormalizedRowValue,
type ParserDiagnostic,
} from "@toolctrl/imports";
import { createImportJob, markImportJobFailed, markImportJobRunning, markImportJobSucceeded } from "@toolctrl/db/import-jobs.server";
import { authorizeStorageObjectAccess } from "@toolctrl/storage";
import { requireAuth } from "~/utils/loaders.middleware";
import { verifyUserHasPermission } from "~/utils/helpers/.server/PermissionsService";
import type { DefaultPermission } from "~/application/dtos/shared/DefaultPermissions";
import { validateCSRFToken } from "~/utils/session.server";
import { getTranslations } from "~/locale/i18next.server";
import type { TFunction } from "i18next";
const MAX_PREVIEW_ROWS = 500;
const MAX_MAPPINGS = 200;
const MAX_FIELDS = 200;
const DRY_RUN_SOURCE_BUCKET = "import-dry-run";
type DryRunBody = {
format?: unknown;
importType?: unknown;
source?: unknown;
mappings?: unknown;
rows?: unknown;
fields?: unknown;
};
type DryRunSource = {
tenantId: string;
sourceKey: string;
fileName?: string | null;
contentType?: string | null;
requestId?: string | null;
};
function json(payload: unknown, status = 200) {
return Response.json(payload, { status });
}
function invalidInput(message: string, diagnostics?: readonly ParserDiagnostic[]) {
return json({ error: message, ...(diagnostics && diagnostics.length > 0 ? { diagnostics } : {}) }, 400);
}
function methodNotAllowed(t: TFunction) {
return json({ error: t("models.row.import.errors.methodNotAllowed") }, 405);
}
function storageAccessDenied(t: TFunction, reason: string) {
const status = reason === "invalid_tenant" || reason === "invalid_key" ? 400 : 403;
return json({ error: t("models.row.import.errors.sourceStorageAccessDenied"), reason }, status);
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function isNormalizedRowValue(value: unknown): value is NormalizedRowValue {
if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
return true;
}
return Array.isArray(value) && value.every((item) => item === null || typeof item === "string" || typeof item === "number" || typeof item === "boolean");
}
function parseString(value: unknown, fieldName: string, t: TFunction): string {
if (typeof value !== "string" || value.trim().length === 0) {
throw new Error(t("models.row.import.errors.requiredField", { field: fieldName }));
}
return value.trim();
}
function parseOptionalString(value: unknown): string | null {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}
function parseSource(value: unknown, t: TFunction): DryRunSource {
if (!isRecord(value)) {
throw new Error(t("models.row.import.errors.sourceRequired"));
}
return {
tenantId: parseString(value.tenantId, "source.tenantId", t),
sourceKey: parseString(value.sourceKey, "source.sourceKey", t),
fileName: parseOptionalString(value.fileName),
contentType: parseOptionalString(value.contentType),
requestId: parseOptionalString(value.requestId),
};
}
function parseMappings(value: unknown, t: TFunction): ColumnMapping[] {
if (!Array.isArray(value) || value.length === 0) {
throw new Error(t("models.row.import.errors.mappingsRequired"));
}
if (value.length > MAX_MAPPINGS) {
throw new Error(t("models.row.import.errors.maxMappings", { max: MAX_MAPPINGS }));
}
return value.map((item, index) => {
if (!isRecord(item)) {
throw new Error(t("models.row.import.errors.mappingMustBeObject", { index }));
}
return {
sourceColumn: parseString(item.sourceColumn, `mappings[${index}].sourceColumn`, t),
targetField: parseString(item.targetField, `mappings[${index}].targetField`, t),
required: item.required === true,
label: parseOptionalString(item.label) ?? undefined,
};
});
}
function parseFields(value: unknown, t: TFunction): ImportDryRunFieldDefinition[] {
if (value === undefined) {
return [];
}
if (!Array.isArray(value)) {
throw new Error(t("models.row.import.errors.fieldsMustBeArray"));
}
if (value.length > MAX_FIELDS) {
throw new Error(t("models.row.import.errors.maxFields", { max: MAX_FIELDS }));
}
return value.map((item, index) => {
if (!isRecord(item)) {
throw new Error(t("models.row.import.errors.fieldMustBeObject", { index }));
}
return {
targetField: parseString(item.targetField, `fields[${index}].targetField`, t),
required: item.required === true,
label: parseOptionalString(item.label) ?? undefined,
};
});
}
function parseRows(value: unknown, t: TFunction): ImportPreviewInputRow[] {
if (!Array.isArray(value) || value.length === 0) {
throw new Error(t("models.row.import.errors.rowsRequired"));
}
if (value.length > MAX_PREVIEW_ROWS) {
throw new Error(t("models.row.import.errors.maxRows", { max: MAX_PREVIEW_ROWS }));
}
return value.map((item, index) => {
if (!isRecord(item) || !isRecord(item.values)) {
throw new Error(t("models.row.import.errors.rowValuesMustBeObject", { index }));
}
const values: NormalizedImportRow = {};
for (const [key, rowValue] of Object.entries(item.values)) {
if (!isNormalizedRowValue(rowValue)) {
throw new Error(t("models.row.import.errors.rowValueMustBeScalar", { index, field: key }));
}
values[key] = rowValue;
}
const rowNumber = typeof item.rowNumber === "number" && Number.isInteger(item.rowNumber) && item.rowNumber > 0 ? item.rowNumber : undefined;
return { rowNumber, values };
});
}
function validationDiagnostic(message: string): ParserDiagnostic[] {
return [createRedactedParserDiagnostic("invalid_dry_run_request", message)];
}
function buildPreviewInput(body: DryRunBody, t: TFunction): ImportDryRunPreviewInput & { source: DryRunSource; importType: string } {
const format = parseString(body.format, "format", t);
if (!isSupportedImportFormat(format)) {
throw new Error(t("models.row.import.errors.unsupportedFormat"));
}
return {
format,
importType: parseString(body.importType, "importType", t),
source: parseSource(body.source, t),
mappings: parseMappings(body.mappings, t),
fields: parseFields(body.fields, t),
rows: parseRows(body.rows, t),
};
}
function getImportPermission(importType: string, t: TFunction): DefaultPermission {
switch (importType) {
case "members":
return "app.settings.members.create";
default:
throw new Error(t("models.row.import.errors.unsupportedType", { importType }));
}
}
function getCreatedJobId(createdJob: unknown, t: TFunction): string {
if (isRecord(createdJob) && typeof createdJob.id === "string" && createdJob.id.length > 0) {
return createdJob.id;
}
throw new Error(t("models.row.import.errors.importJobCreateFailed"));
}
function toErrorMessage(error: unknown, t: TFunction): string {
return error instanceof Error ? error.message : t("models.row.import.errors.dryRunFailed");
}
function sanitizeDiagnosticMessage(message: string): string {
return redactDiagnosticMessage(message)
.replace(/authorization:\s*\[REDACTED\]\s+[^\s,;]+/gi, "authorization: [REDACTED]")
.replace(/Bearer\s+[^\s,;]+/gi, "Bearer [REDACTED]")
.replace(/rawBody\s*=\s*(?:\{[^}]*\}|\[[^\]]*\]|[^\s,;]+)/gi, "rawBody=[REDACTED]");
}
async function markFailureIfPossible(
jobId: string | undefined,
tenantId: string,
attemptsMade: number,
error: unknown,
t: TFunction,
counters?: { rowCount?: number; acceptedRows?: number; rejectedRows?: number }
) {
if (!jobId) {
return;
}
await markImportJobFailed({
id: jobId,
tenantId,
attemptsMade,
rowCount: counters?.rowCount,
acceptedRows: counters?.acceptedRows,
rejectedRows: counters?.rejectedRows,
errorName: error instanceof Error ? error.name : "Error",
errorMessage: sanitizeDiagnosticMessage(toErrorMessage(error, t)),
});
}
export const action = async ({ request, params }: ActionFunctionArgs) => {
const { t } = await getTranslations(request);
if (request.method !== "POST") {
return methodNotAllowed(t);
}
let userInfo: Awaited<ReturnType<typeof requireAuth>>;
try {
userInfo = await requireAuth({ request, params });
} catch (error) {
throw error;
}
let body: DryRunBody;
try {
await validateCSRFToken(request);
const parsed = await request.json();
if (!isRecord(parsed)) {
return invalidInput(t("models.row.import.errors.jsonBodyMustBeObject"));
}
body = parsed;
} catch {
return invalidInput(t("models.row.import.errors.invalidJsonBody"));
}
let previewInput: ImportDryRunPreviewInput & { source: DryRunSource; importType: string };
try {
previewInput = buildPreviewInput(body, t);
} catch (error) {
const message = sanitizeDiagnosticMessage(toErrorMessage(error, t));
return invalidInput(message, validationDiagnostic(message));
}
let permission: DefaultPermission;
try {
permission = getImportPermission(previewInput.importType, t);
} catch (error) {
const message = sanitizeDiagnosticMessage(toErrorMessage(error, t));
return invalidInput(message, validationDiagnostic(message));
}
await verifyUserHasPermission(request, permission, previewInput.source.tenantId);
const accessDecision = authorizeStorageObjectAccess({
tenantId: previewInput.source.tenantId,
key: previewInput.source.sourceKey,
operation: "download",
});
if (!accessDecision.allowed) {
return storageAccessDenied(t, accessDecision.reason);
}
const requestId = previewInput.source.requestId ?? crypto.randomUUID();
let jobId: string | undefined;
const attemptsMade = 1;
try {
const createdJob = await createImportJob({
tenantId: previewInput.source.tenantId,
requestedByUserId: userInfo.userId ?? null,
importType: previewInput.importType,
format: previewInput.format,
requestId,
sourceBucket: DRY_RUN_SOURCE_BUCKET,
sourceKey: accessDecision.key,
fileName: previewInput.source.fileName,
contentType: previewInput.source.contentType,
attemptsMade: 0,
});
jobId = getCreatedJobId(createdJob, t);
await markImportJobRunning({ id: jobId, tenantId: previewInput.source.tenantId, attemptsMade });
const preview = createImportDryRunPreview(previewInput);
await markImportJobSucceeded({
id: jobId,
tenantId: previewInput.source.tenantId,
rowCount: preview.summary.totalRows,
acceptedRows: preview.summary.acceptedRows,
rejectedRows: preview.summary.rejectedRows,
attemptsMade,
});
return json({
jobId,
status: "COMPLETED",
summary: preview.summary,
rows: preview.rows,
diagnostics: preview.summary.diagnostics,
});
} catch (error) {
try {
await markFailureIfPossible(jobId, previewInput.source.tenantId, attemptsMade, error, t);
} catch {
// Preserve the original dry-run failure while avoiding diagnostic leakage from persistence failures.
}
return json(
{
error: t("models.row.import.errors.dryRunFailed"),
diagnostics: [createRedactedParserDiagnostic("dry_run_failed", t("models.row.import.errors.dryRunFailedBeforeCompletion"))],
},
500
);
}
};