hierarchical-approval 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,73 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [0.7.0] - 2026-09-04
+
+### Fixed — two condition-evaluation bypasses
+
+Both of these let a `ConditionRule` fire when it should not have, and because
+conditions decide which levels an instance gets, a spurious match on a
+`skipLevels` rule **removes approval levels from a live document**. Anyone using
+`skipLevels` — or `addLevels` to *escalate* above a threshold — should upgrade.
+
+- **Numeric operators no longer coerce non-numbers to zero.** `>`, `<`, `>=` and
+  `<=` compared with `Number(actual)`, and `Number()` maps `null`, `''`, `'   '`,
+  `[]` and `false` all to `0`. So a fast-track rule like
+  `{ when: { field: 'amount', operator: '<', value: 5000 }, skipLevels: [2, 3] }`
+  matched a purchase order whose `amount` was `null` or blank, silently skipping
+  two approval levels on exactly the documents whose value was unknown. `false`
+  and `[]` did the same, and `true` compared as `1`.
+
+  A numeric comparison against a non-number is now treated as *undecidable* rather
+  than false-y: it reports **no match**, which is the outcome `undefined` has
+  always produced. Accepted operands are finite numbers, bigints, `Date`
+  (compared as epoch milliseconds), and numeric strings such as `'100'` or
+  `' 1e3 '` — ERP payloads routinely arrive as JSON strings, so string comparison
+  is retained. Rejected: `null`, `undefined`, booleans, arrays, objects, blank
+  strings, `NaN` and `Infinity`.
+
+  **Behaviour change.** A rule that was matching on blank or boolean data stops
+  matching. That is the fix, but it does change which levels such an instance
+  gets, so re-check any template whose conditions run against optional fields.
+  `==` and `!=` are untouched — they were already strict.
+
+- **Dot-path field lookup now reads own properties only.** `getField` tested
+  `key in obj`, which walks the prototype chain, so a condition on `isFastTrack`
+  was satisfied by an inherited `Object.prototype.isFastTrack` that no document
+  ever declared — turning any prototype pollution elsewhere in the dependency
+  tree into an approval-level bypass. Resolution now uses
+  `Object.prototype.hasOwnProperty`, so a segment that is not an own property
+  resolves to `undefined` exactly as an absent field does. This also closes
+  `__proto__`, `constructor` and `prototype` as readable paths.
+
+  **Behaviour change.** Context data whose fields live on a prototype (a class
+  instance with getters, rather than a plain object) no longer resolves. Plain
+  objects, arrays, array indices and `Object.create(null)` objects are
+  unaffected, and context data does not survive JSONB round-tripping as a class
+  instance in any case.
+
+### Added
+
+- **`toComparableNumber(value)` is exported from the package root.** The same
+  strict coercion the built-in numeric operators use, returning `number` or
+  `null`, so a custom operator registered with `registerConditionOperator()` can
+  inherit the identical semantics instead of re-introducing `Number()`. The
+  README's `between` recipe now uses it — the previous version of that snippet
+  demonstrated the zero-coercion bug.
+
+### Tests
+
+- Restored the **17 `ConditionEvaluator` unit tests that commit `8d648d8`
+  deleted**, having replaced the suite body with a `// ... existing tests ...`
+  placeholder and a single test. Coverage of the evaluator had silently dropped
+  to 74% of statements and 56% of functions.
+- Added 36 tests across the two fixes (per-type non-comparable operand matrix for
+  each numeric operator, the `skipLevels` bypass scenario, prototype-pollution
+  guards, `toComparableNumber` directly) plus an executable copy of the README's
+  custom-operator recipes, so a documented snippet cannot rot or stop compiling.
+  All 24 of the pre-existing-bug assertions were confirmed to fail against the
+  unfixed source.
+
 ## [0.6.0] - 2026-08-21
 
 ### Fixed — event delivery, template reads, and the CI lint gate

package/README.md

@@ -305,6 +305,33 @@ conditions: [
 
 **Built-in operators:** `>`, `<`, `>=`, `<=`, `==`, `!=`, `in`, `not_in`
 
+#### How values are compared
+
+`==` and `!=` compare **strictly** — `'100'` does not equal `100`.
+
+The numeric operators (`>`, `<`, `>=`, `<=`) match only when **both** sides are
+unambiguously numeric: finite numbers, bigints, `Date` (compared as epoch
+milliseconds), and numeric strings such as `'100'` or `' 1e3 '` — because ERP
+payloads routinely arrive as JSON strings. Anything else — `null`, `undefined`,
+`true`/`false`, arrays, objects, blank strings, `NaN`, `Infinity` — is treated as
+*not comparable*, and the condition reports **no match**.
+
+This matters for safety. A rule that skips levels on small amounts must not fire
+on a document whose amount was never populated:
+
+```ts
+{ when: { field: 'amount', operator: '<', value: 5000 }, skipLevels: [2, 3] }
+
+// amount: 4999  -> matches, levels 2 and 3 are skipped
+// amount: null  -> NO match, every level is kept
+// amount: ''    -> NO match, every level is kept
+```
+
+Field paths resolve **own properties only**, so an inherited or polluted
+`Object.prototype` member can never satisfy a condition. A path segment that is
+not an own property — including `__proto__`, `constructor`, and `prototype` —
+resolves to `undefined`, exactly as a genuinely absent field does.
+
 **Register custom operators** at engine level:
 
 ```ts
@@ -312,11 +339,23 @@ engine.registerConditionOperator(
   'contains',
   (actual, expected) => typeof actual === 'string' && actual.includes(String(expected)),
 );
+```
 
-engine.registerConditionOperator(
-  'between',
-  (actual, [min, max]: number[]) => Number(actual) >= min && Number(actual) <= max,
-);
+Custom numeric operators should reuse the same strictness via the exported
+`toComparableNumber` helper, which returns `null` for anything that is not
+unambiguously a number:
+
+```ts
+import { toComparableNumber } from 'hierarchical-approval';
+
+engine.registerConditionOperator('between', (actual, expected) => {
+  const value = toComparableNumber(actual);
+  if (value === null || !Array.isArray(expected) || expected.length !== 2) return false;
+  const min = toComparableNumber(expected[0]);
+  const max = toComparableNumber(expected[1]);
+  if (min === null || max === null) return false;
+  return value >= min && value <= max;
+});
 ```
 
 ---

package/dist/{ApprovalEngine-CIQFYhsX.d.cts → ApprovalEngine-BET-UqQo.d.cts}

@@ -130,6 +130,26 @@ type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
 }) => Promise<string[]> | string[];
 
 type ConditionOperatorFn = (actual: unknown, expected: unknown) => boolean;
+/**
+ * Coerce a value to a number *only* when it unambiguously represents one.
+ *
+ * Plain `Number()` maps `null`, `''`, `'   '`, `[]` and `false` all to `0`, which
+ * in an approval engine is an approval-bypass hazard: a rule such as
+ * `{ amount: '<' 5000 } -> skipLevels: [2, 3]` would fire on a document whose
+ * `amount` is missing or blank, silently skipping two approval levels. Numeric
+ * comparison against a value that is not a number is not "false-y", it is
+ * *undecidable*, so this returns `null` and the comparison reports no match —
+ * the same outcome `undefined` has always produced.
+ *
+ * Accepted: finite numbers, bigints, `Date` (compared as epoch ms), and numeric
+ * strings such as `'100'` or `' 1e3 '` (ERP payloads routinely arrive as JSON
+ * strings). Rejected: `null`, `undefined`, booleans, arrays, objects, blank
+ * strings, and the non-finite `NaN` / `Infinity`.
+ *
+ * @param value - The raw value taken from the condition or the context data.
+ * @returns The numeric value, or `null` when the value is not comparable.
+ */
+declare function toComparableNumber(value: unknown): number | null;
 
 interface ValidationResult {
     valid: boolean;
@@ -415,4 +435,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, weekendCalendar as w };

package/dist/{ApprovalEngine-D3rHIli1.d.ts → ApprovalEngine-BGfrrFxl.d.ts}

@@ -130,6 +130,26 @@ type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
 }) => Promise<string[]> | string[];
 
 type ConditionOperatorFn = (actual: unknown, expected: unknown) => boolean;
+/**
+ * Coerce a value to a number *only* when it unambiguously represents one.
+ *
+ * Plain `Number()` maps `null`, `''`, `'   '`, `[]` and `false` all to `0`, which
+ * in an approval engine is an approval-bypass hazard: a rule such as
+ * `{ amount: '<' 5000 } -> skipLevels: [2, 3]` would fire on a document whose
+ * `amount` is missing or blank, silently skipping two approval levels. Numeric
+ * comparison against a value that is not a number is not "false-y", it is
+ * *undecidable*, so this returns `null` and the comparison reports no match —
+ * the same outcome `undefined` has always produced.
+ *
+ * Accepted: finite numbers, bigints, `Date` (compared as epoch ms), and numeric
+ * strings such as `'100'` or `' 1e3 '` (ERP payloads routinely arrive as JSON
+ * strings). Rejected: `null`, `undefined`, booleans, arrays, objects, blank
+ * strings, and the non-finite `NaN` / `Infinity`.
+ *
+ * @param value - The raw value taken from the condition or the context data.
+ * @returns The numeric value, or `null` when the value is not comparable.
+ */
+declare function toComparableNumber(value: unknown): number | null;
 
 interface ValidationResult {
     valid: boolean;
@@ -415,4 +435,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, weekendCalendar as w };

package/dist/index.cjs

@@ -439,11 +439,33 @@ var EscalationScheduler = class {
 };
 
 // src/engine/ConditionEvaluator.ts
+function toComparableNumber(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "bigint") return Number(value);
+  if (value instanceof Date) {
+    const time = value.getTime();
+    return Number.isFinite(time) ? time : null;
+  }
+  if (typeof value === "string") {
+    if (value.trim() === "") return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function numeric(compare) {
+  return (actual, expected) => {
+    const left = toComparableNumber(actual);
+    const right = toComparableNumber(expected);
+    if (left === null || right === null) return false;
+    return compare(left, right);
+  };
+}
 var operatorRegistry = /* @__PURE__ */ new Map([
-  [">", (a, e) => Number(a) > Number(e)],
-  ["<", (a, e) => Number(a) < Number(e)],
-  [">=", (a, e) => Number(a) >= Number(e)],
-  ["<=", (a, e) => Number(a) <= Number(e)],
+  [">", numeric((a, e) => a > e)],
+  ["<", numeric((a, e) => a < e)],
+  [">=", numeric((a, e) => a >= e)],
+  ["<=", numeric((a, e) => a <= e)],
   ["==", (a, e) => a === e],
   ["!=", (a, e) => a !== e],
   ["in", (a, e) => Array.isArray(e) && e.includes(a)],
@@ -460,7 +482,7 @@ function registerConditionOperator(name, fn) {
 }
 function getField(data, path) {
   return path.split(".").reduce((obj, key) => {
-    if (obj !== null && typeof obj === "object" && key in obj) {
+    if (obj !== null && typeof obj === "object" && Object.prototype.hasOwnProperty.call(obj, key)) {
       return obj[key];
     }
     return void 0;
@@ -2596,6 +2618,7 @@ exports.MemoryAdapter = MemoryAdapter;
 exports.defaultIdGenerator = defaultIdGenerator;
 exports.noopLogger = noopLogger;
 exports.systemClock = systemClock;
+exports.toComparableNumber = toComparableNumber;
 exports.weekendCalendar = weekendCalendar;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map