feat(spec,lint)!: refuse an RLS or sharing-rule comparison between two fields of different comparison classes when it is authored; regenerate api-surface and export-origins (#20347)

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QcAS3qiYYZNezaxZxaUdMV

Author: claude

.changeset/20347-cross-field-comparison-class-authoring.md

@@ -0,0 +1,25 @@
+---
+"@objectstack/spec": minor
+"@objectstack/lint": minor
+---
+
+A row-level-security predicate or a sharing-rule condition that compares two fields of different comparison classes — a text field with a number field, a field with a single image or file field, a field with a formula field — is refused when it is authored, at `os validate` / `os build` / `os lint` and, for a permission set, at the metadata save door (#20347). The classification it is judged by is exported once, from `@objectstack/spec/data`.
+
+**BREAKING** — an accept-set narrowing in `@objectstack/lint`, shipped as `minor` under the repo's launch-window convention for accept-set narrowings. `@objectstack/spec` gains exports only.
+
+Clause-②: yes (narrowing)
+
+`record.status != record.amount` (text vs number) and `record.status != record.photo` (text vs a single image) lower to a legal `{ status: { $ne: { $field: … } } }` filter and hold no list, so no authoring rule refused them. Measured before this change, through the real `os validate` and the real plugin-security and ObjectQL on driver-sql: `os validate` reported both valid; the read a `using` scopes answered `INVALID_FILTER` / 400 and a by-id update or delete it scopes `PERMISSION_DENIED` / 403, because driver-sql compiles a column-to-column comparison only between two columns of one comparison class; and a single-record insert judged by the `check` — or by a `using` standing in as the check — was admitted and stored, because the in-process write check compares the two raw values. A formula field (`record.status != record.is_open`) answered the same three ways. The same-class control (`record.status != record.note`) read, updated, deleted and inserted normally. For a sharing rule, the condition lowers and is seeded, and every criteria query it runs meets the same driver-sql refusal.
+
+What changes:
+
+- `@objectstack/spec/data` (`filter-cross-field-comparison-class.ts`): the cross-field comparison classification. `CROSS_FIELD_COMPARISON_CLASSES` names the six classes (`numeric`, `text`, `boolean`, `date`, `datetime`, `time`); `CROSS_FIELD_NO_CLASS_REASONS` the three families with none (`list-or-object`, `file`, `formula`); `CROSS_FIELD_COMPARISON_TYPE_CLASSES` classifies every `FieldType` member exactly once, by reference to the existing value-class sets; `crossFieldColumnVerdict` answers one declared column (a multi-capable type flagged `multiple: true` holds a list); and `crossFieldComparisonVerdict` answers two (`comparable`, `cross-class`, `no-class`, or `unjudged` for a type outside `FieldType`). It is lifted case for case from driver-sql's cross-field boundary, and a pairwise parity test in driver-sql holds the two equal over every declared field type.
+- `@objectstack/lint`: `validateRlsPredicateEnforceability` reports `rls-predicate-unenforceable`, and `validateSharingRuleEnforceability` reports `sharing-rule-unlowerable-condition`, for every lowered field-to-field comparison (`==`, `!=`, `>`, `>=`, `<`, `<=`, either side, under `!` too) whose two declared columns are not `comparable`. It judges `using` and `check` on every operation, and sharing-rule conditions. The finding names each comparison, each column's declared type and class, and the clause's run-time consequence; the hint lists every class with the declared types it holds, read from the spec. A comparison either side of which holds a list or an object stays the existing list-holding finding, and a clause either arm refuses is not also handed to the engine's filter judge, so one defect earns one finding.
+
+Not changed: driver-sql and the in-process write check keep their own behaviour here; moving both onto the exported classification is the engine-lane half. A comparison between two columns of one class (`record.amount > record.budget`, `record.stage == record.account`), a file or formula field compared with a literal or tested against `null`, and any column the stack does not declare or declares with a type outside `FieldType`, are not reported.
+
+No shipped predicate moves: of the 163 `using` / `check` / `condition` string literals in this repository's packages and examples, the 105 that lower hold two field-to-field comparisons, both same-class (`spent > budget`, a hook condition; `a > b`, a gate fixture), and neither is an RLS predicate or a sharing-rule condition.
+
+To keep such a rule, compare a field only with a field of the same class, or with a literal or a `current_user` value; test a file field with `!= null`; or store the value the rule keys on in a field of the right type. If the two columns really hold comparable values, one of them is declared with the wrong type, and the declaration is what to fix.
+
+<!-- adr-0087: not-required (no-migration-prescription) nothing is renamed, retired or respelled: no metadata key, export or operator changes shape and no stored metadata is rewritten, so `objectstack migrate meta` has nothing to do; the author's remedy is to change which two columns a predicate compares, which is a change to the policy they meant, not to a spelling. -->

packages/cli/test/rls-policy-authoring-admission.test.ts

@@ -63,6 +63,7 @@ const deal = {
     account: { type: 'lookup', label: 'Account', reference: 'account' },
     tags: { type: 'json', label: 'Tags' },
     watchers: { type: 'lookup', label: 'Watchers', reference: 'account', multiple: true },
+    photo: { type: 'image', label: 'Photo' },
   },
 };
 const account = { name: 'account', label: 'Account', fields: { region: { type: 'text', label: 'Region' } } };
@@ -293,3 +294,60 @@ describe('a field compared with a json / multiple field is refused at both doors
     });
   }
 });
+
+/**
+ * [#20347] A field compared with a field of ANOTHER comparison class — text vs
+ * number, text vs a single image, text vs a formula field — is refused when it
+ * is AUTHORED, at both doors, on every clause. None of these holds a list, so
+ * the #19886 arm above lets them through; measured before this arm, the real
+ * `os validate` reported `record.status != record.amount` and
+ * `record.status != record.photo` valid, while through the real plugin-security
+ * on driver-sql the read their `using` scopes answered `INVALID_FILTER` / 400
+ * and the insert their `check` judges was admitted and stored. The rule judges
+ * by the spec's classification (`crossFieldComparisonVerdict`); the full
+ * operator × clause × class × order table is pinned beside the rule in
+ * `@objectstack/lint`.
+ */
+describe('a field compared with a field of another comparison class is refused at both doors, on every clause (#20347)', () => {
+  const ROWS: ReadonlyArray<{ label: string; clause: 'using' | 'check'; operation: string; predicate: string }> = [
+    { label: 'using on select, text != number', clause: 'using', operation: 'select', predicate: 'record.region != record.amount' },
+    { label: 'using on all, text != a single image', clause: 'using', operation: 'all', predicate: 'record.region != record.photo' },
+    { label: 'using on select, text != a formula field', clause: 'using', operation: 'select', predicate: 'record.region != record.is_open' },
+    { label: 'using on update, number > date', clause: 'using', operation: 'update', predicate: 'record.amount > record.close_date' },
+    { label: 'check on insert, text != number', clause: 'check', operation: 'insert', predicate: 'record.region != record.amount' },
+    { label: 'check on insert, the image first', clause: 'check', operation: 'insert', predicate: 'record.photo != record.region' },
+  ];
+  const CONTROLS: ReadonlyArray<{ label: string; clause: 'using' | 'check'; operation: string; predicate: string }> = [
+    { label: 'using on select, text != text', clause: 'using', operation: 'select', predicate: 'record.region != record.owner' },
+    { label: 'check on insert, a single lookup == text (both text)', clause: 'check', operation: 'insert', predicate: 'record.account == record.owner' },
+    { label: 'using on all, an image null test', clause: 'using', operation: 'all', predicate: 'record.photo != null' },
+  ];
+  const setFor = (row: { clause: string; operation: string; predicate: string }) =>
+    permissionSet('', { operation: row.operation, [row.clause]: row.predicate });
+
+  for (const row of ROWS) {
+    it(`REFUSED at both doors with one sentence — ${row.label}: \`${row.predicate}\``, async () => {
+      const cli = cliDoor('', setFor(row));
+      const saved = await runtimeDoor('', setFor(row));
+
+      expect(cli.map((f) => ({ severity: f.severity, rule: f.rule, path: f.path }))).toEqual([
+        { severity: 'error', rule: UNENFORCEABLE, path: `permissions[0].rowLevelSecurity[0].${row.clause}` },
+      ]);
+      expect(cli[0].message).toContain('lowers, but compares two fields that share no comparison class');
+
+      expect(saved.accepted).toBe(false);
+      expect({ code: saved.code, status: saved.status }).toEqual({ code: 'INVALID_METADATA', status: 422 });
+      expect(saved.issues.map((i) => ({ rule: i.rule, path: i.path }))).toEqual([
+        { rule: UNENFORCEABLE, path: `permissions.sales.rowLevelSecurity[0].${row.clause}` },
+      ]);
+      expect(saved.issues[0].message).toBe(cli[0].message);
+    });
+  }
+
+  for (const row of CONTROLS) {
+    it(`ACCEPTED at both doors — ${row.label}: \`${row.predicate}\``, async () => {
+      expect(cliDoor('', setFor(row))).toEqual([]);
+      expect(await runtimeDoor('', setFor(row))).toEqual({ accepted: true, issues: [] });
+    });
+  }
+});

packages/lint/src/validate-rls-predicate-enforceability.cross-class-field.test.ts

@@ -154,7 +154,8 @@ describe('validateRlsPredicateEnforceability — a field compared with a field o
     const using = validateRlsPredicateEnforceability(stackWith({ operation: 'select', using: 'record.status != record.amount' }))[0];
     expect(using.message).toContain(
       'every read this policy scopes is refused on the SQL drivers (`INVALID_FILTER` / 400: driver-sql refuses the ' +
-        "comparison by the two columns' declared types).",
+        "comparison by the two columns' declared types), and every by-id update or delete it scopes fails closed " +
+        '(`PERMISSION_DENIED` / 403).',
     );
     expect(using.message).toContain('the same `using` is also the write check whenever no applicable policy');
 

packages/lint/src/validate-rls-predicate-enforceability.ts

@@ -232,12 +232,17 @@
  * `record.status != record.photo` (text vs a single image) lower to legal
  * `{ status: { $ne: { $field: … } } }` shapes and hold no list, so the arm above
  * lets them through. Measured before this arm, through the real plugin-security
- * and ObjectQL on driver-sql: `os validate` reported them valid, the read their
- * `using` scopes answered `INVALID_FILTER` / 400 (driver-sql compiles a
- * column-to-column comparison only between two columns of ONE comparison
- * class, and refuses the file family and formula fields outright), and an
- * insert their `check` judges was ADMITTED and stored — the in-process write
- * check has no class rule, so the permissive answer sat on the write side of
+ * and ObjectQL on driver-sql, for those two and for `record.status !=
+ * record.is_open` (a formula field): `os validate` reported them valid; the
+ * read their `using` scopes answered `INVALID_FILTER` / 400 (driver-sql
+ * compiles a column-to-column comparison only between two columns of ONE
+ * comparison class, and refuses the file family and formula fields outright)
+ * and a by-id update or delete it scopes `PERMISSION_DENIED` / 403; and an
+ * insert their `check` judges — or their `using`, standing in as the check —
+ * was ADMITTED and stored. The in-process write check has no class rule and
+ * compares the two raw values, so the write answer is whatever that comparison
+ * happens to give (`record.amount > record.status` was refused 403, because
+ * `5 > 'open'` is false in JS): the permissive answer sits on the write side of
  * an access policy. One policy, three answers.
  *
  * This arm refuses the comparison where it is written, by the same rule the
@@ -1231,9 +1236,10 @@ function crossClassConsequence(clause: 'using' | 'check'): string {
     'comparison happens to hold — an answer the read path refuses to give';
   return clause === 'using'
     ? 'every read this policy scopes is refused on the SQL drivers (`INVALID_FILTER` / 400: driver-sql refuses ' +
-        'the comparison by the two columns\' declared types). On an `insert`, `update` or `all` policy the same ' +
-        '`using` is also the write check whenever no applicable policy for that operation declares a `check` ' +
-        `(ADR-0058 D4), and there ${write}.`
+        'the comparison by the two columns\' declared types), and every by-id update or delete it scopes fails ' +
+        'closed (`PERMISSION_DENIED` / 403). On an `insert`, `update` or `all` policy the same `using` is also ' +
+        'the write check whenever no applicable policy for that operation declares a `check` (ADR-0058 D4), and ' +
+        `there ${write}.`
     : `${write[0].toUpperCase()}${write.slice(1)}. The policy reads as a write rule and is enforced by an ` +
         'accident of the two values.';
 }

packages/spec/api-surface/data.json

@@ -74,6 +74,9 @@
     "CREDENTIAL_KEY_SPELLINGS (const)",
     "CREDENTIAL_URL_QUERY_PARAMS (const)",
     "CREDENTIAL_URL_QUERY_PARAM_NAMES (const)",
+    "CROSS_FIELD_COMPARISON_CLASSES (const)",
+    "CROSS_FIELD_COMPARISON_TYPE_CLASSES (const)",
+    "CROSS_FIELD_NO_CLASS_REASONS (const)",
     "CalendarDateValue (type)",
     "CalendarDateValueSchema (const)",
     "ClockTimeValue (type)",
@@ -95,6 +98,12 @@
     "ContextTokenPlaceholder (type)",
     "ContextTokenPlaceholderSchema (const)",
     "ContextTokenSchema (const)",
+    "CrossFieldColumnVerdict (type)",
+    "CrossFieldComparisonClass (type)",
+    "CrossFieldComparisonFieldMeta (interface)",
+    "CrossFieldComparisonTypeClass (interface)",
+    "CrossFieldComparisonVerdict (type)",
+    "CrossFieldNoClassReason (type)",
     "CrossFieldValidation (type)",
     "CrossFieldValidationParsed (type)",
     "CrossFieldValidationSchema (const)",
@@ -738,6 +747,8 @@
     "credentialFreeMongoOptions (function)",
     "credentialFreeUrl (function)",
     "credentialQueryParamOf (function)",
+    "crossFieldColumnVerdict (function)",
+    "crossFieldComparisonVerdict (function)",
     "defaultAggregateFor (function)",
     "defaultValueTokenIssue (function)",
     "defineCube (function)",

packages/spec/export-origins/data.json

@@ -71,6 +71,9 @@
     "CREDENTIAL_KEY_SPELLINGS": "src/data/driver/common.zod.ts#CREDENTIAL_KEY_SPELLINGS (const)",
     "CREDENTIAL_URL_QUERY_PARAMS": "src/data/driver/common.zod.ts#CREDENTIAL_URL_QUERY_PARAMS (const)",
     "CREDENTIAL_URL_QUERY_PARAM_NAMES": "src/data/driver/common.zod.ts#CREDENTIAL_URL_QUERY_PARAM_NAMES (const)",
+    "CROSS_FIELD_COMPARISON_CLASSES": "src/data/filter-cross-field-comparison-class.ts#CROSS_FIELD_COMPARISON_CLASSES (const)",
+    "CROSS_FIELD_COMPARISON_TYPE_CLASSES": "src/data/filter-cross-field-comparison-class.ts#CROSS_FIELD_COMPARISON_TYPE_CLASSES (const)",
+    "CROSS_FIELD_NO_CLASS_REASONS": "src/data/filter-cross-field-comparison-class.ts#CROSS_FIELD_NO_CLASS_REASONS (const)",
     "CalendarDateValue": "src/data/field-value.zod.ts#CalendarDateValue (type)",
     "CalendarDateValueSchema": "src/data/field-value.zod.ts#CalendarDateValueSchema (const)",
     "ClockTimeValue": "src/data/field-value.zod.ts#ClockTimeValue (type)",
@@ -92,6 +95,12 @@
     "ContextTokenPlaceholder": "src/data/context-tokens.zod.ts#ContextTokenPlaceholder (type)",
     "ContextTokenPlaceholderSchema": "src/data/context-tokens.zod.ts#ContextTokenPlaceholderSchema (const)",
     "ContextTokenSchema": "src/data/context-tokens.zod.ts#ContextTokenSchema (const)",
+    "CrossFieldColumnVerdict": "src/data/filter-cross-field-comparison-class.ts#CrossFieldColumnVerdict (type)",
+    "CrossFieldComparisonClass": "src/data/filter-cross-field-comparison-class.ts#CrossFieldComparisonClass (type)",
+    "CrossFieldComparisonFieldMeta": "src/data/filter-cross-field-comparison-class.ts#CrossFieldComparisonFieldMeta (interface)",
+    "CrossFieldComparisonTypeClass": "src/data/filter-cross-field-comparison-class.ts#CrossFieldComparisonTypeClass (interface)",
+    "CrossFieldComparisonVerdict": "src/data/filter-cross-field-comparison-class.ts#CrossFieldComparisonVerdict (type)",
+    "CrossFieldNoClassReason": "src/data/filter-cross-field-comparison-class.ts#CrossFieldNoClassReason (type)",
     "CrossFieldValidation": "src/data/validation.zod.ts#CrossFieldValidation (type)",
     "CrossFieldValidationParsed": "src/data/validation.zod.ts#CrossFieldValidationParsed (type)",
     "CrossFieldValidationSchema": "src/data/validation.zod.ts#CrossFieldValidationSchema (const)",
@@ -725,6 +734,8 @@
     "credentialFreeMongoOptions": "src/data/driver/common.zod.ts#credentialFreeMongoOptions (function)",
     "credentialFreeUrl": "src/data/driver/common.zod.ts#credentialFreeUrl (function)",
     "credentialQueryParamOf": "src/data/driver/common.zod.ts#credentialQueryParamOf (function)",
+    "crossFieldColumnVerdict": "src/data/filter-cross-field-comparison-class.ts#crossFieldColumnVerdict (function)",
+    "crossFieldComparisonVerdict": "src/data/filter-cross-field-comparison-class.ts#crossFieldComparisonVerdict (function)",
     "defaultAggregateFor": "src/data/aggregation-policy.ts#defaultAggregateFor (function)",
     "defaultValueTokenIssue": "src/data/default-value-shape.ts#defaultValueTokenIssue (function)",
     "defineCube": "src/data/analytics.zod.ts#defineCube (function)",