@octaviaflow/flow-rules 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -53,6 +53,7 @@ __export(exports_src, {
   ForEachConfig: () => ForEachConfig,
   JoinType: () => JoinType,
   LogicalOperator: () => LogicalOperator,
+  MAX_STEP_CONFIG_BYTES: () => MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig: () => ManualTriggerConfig,
   NodeStatus: () => NodeStatus,
   QueryMode: () => QueryMode,
@@ -66,6 +67,7 @@ __export(exports_src, {
   buildPathOptions: () => buildPathOptions,
   collectArrayPaths: () => collectArrayPaths,
   collectArrayPathsFromSample: () => collectArrayPathsFromSample,
+  configErrors: () => configErrors,
   emailDefinition: () => emailDefinition,
   flattenNestedWorkflow: () => flattenNestedWorkflow,
   generateConnectionsFromSteps: () => generateConnectionsFromSteps,
@@ -91,6 +93,8 @@ __export(exports_src, {
   validateEdge: () => validateEdge,
   validateFlowData: () => validateFlowData,
   validateNode: () => validateNode,
+  validateStepConfig: () => validateStepConfig,
+  validateStepConfigs: () => validateStepConfigs,
   validateWorkflow: () => validateWorkflow
 });
 module.exports = __toCommonJS(exports_src);
@@ -4093,3 +4097,158 @@ function validateFlowData(flow) {
   const f = flow;
   return typeof f.id === "string" && typeof f.name === "string" && f.workflow !== undefined && typeof f.workflow === "object" && f.workflow !== null && Array.isArray(f.workflow.steps);
 }
+// src/rules/configSafety.ts
+var MAX_STEP_CONFIG_BYTES = 256 * 1024;
+var FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+var MAX_DEPTH = 12;
+function typeMatches(field, value) {
+  if (value === null || value === undefined || value === "")
+    return true;
+  switch (field.type) {
+    case "number" /* Number */:
+      return typeof value === "number" || typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value));
+    case "boolean" /* Boolean */:
+      return typeof value === "boolean" || value === "true" || value === "false";
+    case "array" /* Array */:
+    case "multi_select" /* MultiSelect */:
+      return Array.isArray(value);
+    case "object" /* Object */:
+    case "mapping" /* Mapping */:
+      return typeof value === "object" && !Array.isArray(value);
+    case "string" /* String */:
+    case "code" /* Code */:
+    case "expression" /* Expression */:
+    case "select" /* Select */:
+    case "connection" /* Connection */:
+    case "secret" /* Secret */:
+    case "url" /* URL */:
+    case "email" /* Email */:
+    case "phone" /* Phone */:
+    case "color" /* Color */:
+    case "rich_text" /* RichText */:
+    case "markdown" /* Markdown */:
+    case "date" /* Date */:
+    case "datetime" /* DateTime */:
+      return typeof value !== "object";
+    default:
+      return true;
+  }
+}
+function walk(value, stepId, path, depth, issues) {
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_DEEP",
+      stepId,
+      field: path || undefined,
+      message: `Configuration nests deeper than ${MAX_DEPTH} levels.`
+    });
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, stepId, path, depth + 1, issues);
+    return;
+  }
+  if (value === null || typeof value !== "object")
+    return;
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      issues.push({
+        severity: "error",
+        code: "FORBIDDEN_KEY",
+        stepId,
+        field: path ? `${path}.${key}` : key,
+        message: `\`${key}\` is not allowed in a step's configuration.`
+      });
+      continue;
+    }
+    walk(value[key], stepId, path ? `${path}.${key}` : key, depth + 1, issues);
+  }
+}
+function validateStepConfig(step) {
+  const issues = [];
+  const stepId = typeof step.id === "string" ? step.id : "(unknown step)";
+  const config = step.config;
+  if (config === null || config === undefined)
+    return issues;
+  if (typeof config !== "object" || Array.isArray(config)) {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be an object."
+    });
+    return issues;
+  }
+  let serialised;
+  try {
+    serialised = JSON.stringify(config);
+  } catch {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be plain JSON."
+    });
+    return issues;
+  }
+  if (serialised.length > MAX_STEP_CONFIG_BYTES) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_LARGE",
+      stepId,
+      message: `Configuration is ${Math.round(serialised.length / 1024)} KB; the limit is ${MAX_STEP_CONFIG_BYTES / 1024} KB.`
+    });
+  }
+  walk(config, stepId, "", 0, issues);
+  const definition = typeof step.actionDefinitionId === "string" ? getActionById(step.actionDefinitionId) : undefined;
+  if (!definition)
+    return issues;
+  const declared = new Map(definition.inputSchema.fields.map((f) => [f.key, f]));
+  const entries = Object.entries(config);
+  for (const [key, value] of entries) {
+    const field = declared.get(key);
+    if (!field) {
+      issues.push({
+        severity: "warning",
+        code: "UNDECLARED_FIELD",
+        stepId,
+        field: key,
+        message: `\`${key}\` is not declared by ${definition.id}.`
+      });
+      continue;
+    }
+    if (!typeMatches(field, value)) {
+      issues.push({
+        severity: "error",
+        code: "FIELD_WRONG_TYPE",
+        stepId,
+        field: key,
+        message: `\`${key}\` must be ${field.type}.`
+      });
+      continue;
+    }
+    if (field.options && field.options.length > 0 && value !== null && value !== undefined && value !== "") {
+      const allowed = new Set(field.options.map((o) => o.value));
+      const values = Array.isArray(value) ? value : [value];
+      const bad = values.filter((v) => (typeof v === "string" || typeof v === "number") && !allowed.has(v));
+      if (bad.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "FIELD_BAD_OPTION",
+          stepId,
+          field: key,
+          message: `\`${key}\` must be one of: ${[...allowed].join(", ")}.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function validateStepConfigs(steps) {
+  return steps.flatMap((s) => validateStepConfig(s));
+}
+function configErrors(steps) {
+  return validateStepConfigs(steps).filter((i) => i.severity === "error");
+}

package/dist/index.d.ts

@@ -43,3 +43,4 @@ export { type ManualTriggerConfigType } from "./catalog/triggers/manual-trigger/
 export * from "./catalog/workflow";
 export { type FlowConnection, type FlowData, type FlowStep, generateConnectionsFromSteps, transformConnectionToEdge, transformFlowToWorkflow, transformStepToNode, validateFlowData, } from "./rules/flowShape";
 export { flattenNestedWorkflow } from "./rules/flattenNestedWorkflow";
+export { configErrors, MAX_STEP_CONFIG_BYTES, validateStepConfig, validateStepConfigs, type ConfigIssue, type ConfigIssueCode, } from "./rules/configSafety";

package/dist/index.js

@@ -3996,6 +3996,161 @@ function validateFlowData(flow) {
   const f = flow;
   return typeof f.id === "string" && typeof f.name === "string" && f.workflow !== undefined && typeof f.workflow === "object" && f.workflow !== null && Array.isArray(f.workflow.steps);
 }
+// src/rules/configSafety.ts
+var MAX_STEP_CONFIG_BYTES = 256 * 1024;
+var FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+var MAX_DEPTH = 12;
+function typeMatches(field, value) {
+  if (value === null || value === undefined || value === "")
+    return true;
+  switch (field.type) {
+    case "number" /* Number */:
+      return typeof value === "number" || typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value));
+    case "boolean" /* Boolean */:
+      return typeof value === "boolean" || value === "true" || value === "false";
+    case "array" /* Array */:
+    case "multi_select" /* MultiSelect */:
+      return Array.isArray(value);
+    case "object" /* Object */:
+    case "mapping" /* Mapping */:
+      return typeof value === "object" && !Array.isArray(value);
+    case "string" /* String */:
+    case "code" /* Code */:
+    case "expression" /* Expression */:
+    case "select" /* Select */:
+    case "connection" /* Connection */:
+    case "secret" /* Secret */:
+    case "url" /* URL */:
+    case "email" /* Email */:
+    case "phone" /* Phone */:
+    case "color" /* Color */:
+    case "rich_text" /* RichText */:
+    case "markdown" /* Markdown */:
+    case "date" /* Date */:
+    case "datetime" /* DateTime */:
+      return typeof value !== "object";
+    default:
+      return true;
+  }
+}
+function walk(value, stepId, path, depth, issues) {
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_DEEP",
+      stepId,
+      field: path || undefined,
+      message: `Configuration nests deeper than ${MAX_DEPTH} levels.`
+    });
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, stepId, path, depth + 1, issues);
+    return;
+  }
+  if (value === null || typeof value !== "object")
+    return;
+  for (const key of Object.keys(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      issues.push({
+        severity: "error",
+        code: "FORBIDDEN_KEY",
+        stepId,
+        field: path ? `${path}.${key}` : key,
+        message: `\`${key}\` is not allowed in a step's configuration.`
+      });
+      continue;
+    }
+    walk(value[key], stepId, path ? `${path}.${key}` : key, depth + 1, issues);
+  }
+}
+function validateStepConfig(step) {
+  const issues = [];
+  const stepId = typeof step.id === "string" ? step.id : "(unknown step)";
+  const config = step.config;
+  if (config === null || config === undefined)
+    return issues;
+  if (typeof config !== "object" || Array.isArray(config)) {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be an object."
+    });
+    return issues;
+  }
+  let serialised;
+  try {
+    serialised = JSON.stringify(config);
+  } catch {
+    issues.push({
+      severity: "error",
+      code: "FIELD_WRONG_TYPE",
+      stepId,
+      message: "A step's configuration must be plain JSON."
+    });
+    return issues;
+  }
+  if (serialised.length > MAX_STEP_CONFIG_BYTES) {
+    issues.push({
+      severity: "error",
+      code: "CONFIG_TOO_LARGE",
+      stepId,
+      message: `Configuration is ${Math.round(serialised.length / 1024)} KB; the limit is ${MAX_STEP_CONFIG_BYTES / 1024} KB.`
+    });
+  }
+  walk(config, stepId, "", 0, issues);
+  const definition = typeof step.actionDefinitionId === "string" ? getActionById(step.actionDefinitionId) : undefined;
+  if (!definition)
+    return issues;
+  const declared = new Map(definition.inputSchema.fields.map((f) => [f.key, f]));
+  const entries = Object.entries(config);
+  for (const [key, value] of entries) {
+    const field = declared.get(key);
+    if (!field) {
+      issues.push({
+        severity: "warning",
+        code: "UNDECLARED_FIELD",
+        stepId,
+        field: key,
+        message: `\`${key}\` is not declared by ${definition.id}.`
+      });
+      continue;
+    }
+    if (!typeMatches(field, value)) {
+      issues.push({
+        severity: "error",
+        code: "FIELD_WRONG_TYPE",
+        stepId,
+        field: key,
+        message: `\`${key}\` must be ${field.type}.`
+      });
+      continue;
+    }
+    if (field.options && field.options.length > 0 && value !== null && value !== undefined && value !== "") {
+      const allowed = new Set(field.options.map((o) => o.value));
+      const values = Array.isArray(value) ? value : [value];
+      const bad = values.filter((v) => (typeof v === "string" || typeof v === "number") && !allowed.has(v));
+      if (bad.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "FIELD_BAD_OPTION",
+          stepId,
+          field: key,
+          message: `\`${key}\` must be one of: ${[...allowed].join(", ")}.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function validateStepConfigs(steps) {
+  return steps.flatMap((s) => validateStepConfig(s));
+}
+function configErrors(steps) {
+  return validateStepConfigs(steps).filter((i) => i.severity === "error");
+}
 export {
   ActionCategory,
   ActionStatus,
@@ -4011,6 +4166,7 @@ export {
   ForEachConfig,
   JoinType,
   LogicalOperator,
+  MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig,
   NodeStatus,
   QueryMode,
@@ -4024,6 +4180,7 @@ export {
   buildPathOptions,
   collectArrayPaths,
   collectArrayPathsFromSample,
+  configErrors,
   emailDefinition,
   flattenNestedWorkflow,
   generateConnectionsFromSteps,
@@ -4049,5 +4206,7 @@ export {
   validateEdge,
   validateFlowData,
   validateNode,
+  validateStepConfig,
+  validateStepConfigs,
   validateWorkflow
 };

package/dist/rules/configSafety.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What a step's config may contain, enforced where a caller cannot skip it.
+ *
+ * The editor's rules run in a browser, so they are advice, not a fence. A
+ * request posted straight at the API — or modified on its way — reaches
+ * `PUT /flows/:id/workflow`, which validated STRUCTURE (ids, connections,
+ * cycles) and typed config as `z.record(z.string(), z.unknown())`. Any key,
+ * any value, stored verbatim.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: treat `inputSchema.fields` as an
+ * allow-list. Measured against the real estate, 71 of 131 distinct config
+ * keys in use are not declared there — `slack_message.text`,
+ * `query.visualConfig`, `transform.operation`, `flowId` on nearly every
+ * action. `inputSchema` describes the fields the config PANEL renders, and
+ * every action with a custom panel stores more than that. Rejecting undeclared
+ * keys would refuse most flows on the platform. So an unknown key is a
+ * WARNING, never an error.
+ *
+ * What it does enforce is the part a legitimate client never violates:
+ *
+ *   1. a declared field's declared TYPE;
+ *   2. keys that can poison an object prototype;
+ *   3. a size and depth bound, because a config is a form's worth of settings
+ *      and an unbounded one is a document every reader of that flow pays for
+ *      (the DEV-366 problem, in a different field).
+ *
+ * Every one of those was dry-run against all 295 steps of the 77 flows on
+ * beta before it was allowed to block anything: 0 oversized (largest 28 KB
+ * against a 256 KB cap), 0 deeper than 6 (limit 12), 0 forbidden keys, 0 type
+ * mismatches. A rule that refuses data the platform already holds is not a
+ * fence, it is an outage.
+ *
+ * An enumerated field's options are checked but only WARN, for the same
+ * reason — see the note at that check.
+ */
+/** Largest config a single step may carry, serialised. */
+export declare const MAX_STEP_CONFIG_BYTES: number;
+export type ConfigIssueCode = "FORBIDDEN_KEY" | "CONFIG_TOO_LARGE" | "CONFIG_TOO_DEEP" | "FIELD_WRONG_TYPE" | "FIELD_BAD_OPTION" | "UNDECLARED_FIELD";
+export interface ConfigIssue {
+    severity: "error" | "warning";
+    code: ConfigIssueCode;
+    stepId: string;
+    /** The config key, when the issue is about one. */
+    field?: string;
+    message: string;
+}
+export interface StepLike {
+    id?: unknown;
+    actionDefinitionId?: unknown;
+    config?: unknown;
+}
+/**
+ * Check one step's config.
+ *
+ * Errors block a save. Warnings never do — see the file header on why an
+ * undeclared key cannot be an error.
+ */
+export declare function validateStepConfig(step: StepLike): ConfigIssue[];
+/** Every step of a workflow. `steps` may be nested; flatten before calling. */
+export declare function validateStepConfigs(steps: readonly StepLike[]): ConfigIssue[];
+/** Just the blocking ones — what a save path refuses on. */
+export declare function configErrors(steps: readonly StepLike[]): ConfigIssue[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octaviaflow/flow-rules",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The flow action catalog and the rules engine behind Flow Doctor \u2014 one definition of what a step accepts and what makes a flow valid, shared by the editor and the server",
   "type": "module",
   "main": "./dist/index.cjs",